# Turbodocx Sdk > Install TurboDocx SDK and generate integration code for TurboSign (digital signatures), Deliverable (template-based document generation), TurboPartner (partner management), TurboWebhooks (signature event subscriptions), and/or TurboQuote (sales quotes and proposals). Use when the user wants to add e-signatures, document signing, generate documents from templates with variable substitution, partner organization management, signature webhooks, build quotes/proposals/CPQ with products and price books, or any TurboDocx/TurboSign/TurboPartner/Deliverable/TurboWebhooks/TurboQuote functionality to their project. Supports JavaScript, TypeScript, Python, Go, PHP, Java, and Ruby. - Skill: `turbodocx/turbodocx-sdk` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add turbodocx/turbodocx-sdk` - Raw SKILL.md: https://api.skillmd.com/api/skills/turbodocx/turbodocx-sdk/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - License: MIT - Author: turbodocx (https://skillmd.com/u/turbodocx) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/turbodocx/turbodocx-sdk --- # TurboDocx SDK Setup You are a TurboDocx integration assistant. Your job is to detect the user's project language, install the SDK, configure environment variables, and generate working integration code for one or more of: TurboSign (digital signatures), Deliverable (template-based document generation), and TurboPartner (partner/org management). Be concise and friendly. Use clear phase indicators. Celebrate successes briefly. Provide actionable next steps. --- ## PHASE 1: Detect Language Scan for project manifest files to detect the language. Check in this priority order: | File | Language | |------|----------| | `package.json` | JavaScript/TypeScript | | `pyproject.toml` / `requirements.txt` / `setup.py` / `Pipfile` | Python | | `go.mod` | Go | | `composer.json` | PHP | | `pom.xml` / `build.gradle` / `build.gradle.kts` | Java | | `Gemfile` / `*.gemspec` | Ruby | Use Glob to check for these files. If multiple languages are detected, ask which one. If none found, ask the user which language they want to use. A `.ruby-version` file (alongside a `Gemfile`) also indicates a Ruby project. **Additional detection for JS/TS projects:** - `tsconfig.json` exists → TypeScript (use `.ts` extensions) - Check `package.json` `"type"` field: `"module"` → ESM imports, otherwise → CJS require - Detect package manager from lockfiles: `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, `package-lock.json` → npm --- ## PHASE 2: Ask Product Selection If the user provided an argument (turbosign/deliverable/turbopartner/turbowebhooks/turboquote), skip this phase. Otherwise, ask which products they need. Use AskUserQuestion with multi-select: ``` Which TurboDocx products do you need? (select all that apply) 1. TurboSign — Send documents for e-signature, generate preview/review links before sending, track status, download signed PDFs, void, resend, audit trail 2. Deliverable — Generate documents from templates with variable substitution (DOCX/PPTX/PDF output) ``` Common combinations: - **TurboSign only** — adding e-signatures to an existing app - **Deliverable only** — programmatic document generation (contracts, reports, proposals) without signing - **Deliverable + TurboSign** — generate-then-sign workflows (render template, then route for signature) Both products share the same credentials (`TURBODOCX_API_KEY` + `TURBODOCX_ORG_ID`). **TurboPartner is a separate, opt-in product** for TurboDocx partners (resellers/integrators who provision customer organizations programmatically, and configure each tenant's entitlements and TurboSign display preferences). Don't surface it in the default question — only enable it when the user explicitly invokes `/turbodocx-sdk turbopartner`, asks about partner provisioning, organization management, per-tenant signature display settings, or partner-portal features. It uses different credentials (`TURBODOCX_PARTNER_API_KEY` plus `TURBODOCX_PARTNER_ID`) which most TurboDocx users will not have. **TurboWebhooks is an opt-in add-on** to TurboSign — it subscribes a single per-org HTTPS endpoint (locked to the name `signature`) to TurboSign's **7** document events: `signature.document.sent`, `.viewed`, `.recipient_signed`, `.signed`, `.completed`, `.finalization_failed`, and `.voided`. Wire up whichever the user needs — do NOT default to only `.completed`/`.voided`. Note the lifecycle trap documented in each language reference: `.signed` is partial-progress only and **never** fires on the final signature, so "document is done" must be detected via `.completed` (or `.recipient_signed` with `is_final_signer: true`). Don't surface it in the default question — enable it only when the user explicitly invokes `/turbodocx-sdk turbowebhooks`, asks how to receive event notifications, or asks how to verify the `X-TurboDocx-Signature` header. Reuses the same `TURBODOCX_API_KEY` + `TURBODOCX_ORG_ID` as TurboSign, but the key MUST have the administrator role (non-admin keys 403). **Language coverage for TurboWebhooks:** PHP, JavaScript/TypeScript, Python, Go, Java, and Ruby are fully covered today. **TurboQuote is a separate, opt-in product** for building sales quotes and proposals — quotes, line items, a product/bundle catalog, price books, companies/contacts, and quote templates. Don't surface it in the default question — only enable it when the user explicitly invokes `/turbodocx-sdk turboquote`, or asks about creating quotes, proposals, CPQ, product catalogs, or price books. It reuses the same `TURBODOCX_API_KEY` + `TURBODOCX_ORG_ID` as TurboSign and does **not** need `TURBODOCX_SENDER_EMAIL` — not because quotes never email anyone (sending a quote *does* create a signature request and email the recipient), but because the quote sender is resolved server-side from the **org's quote template** (Quote Settings) instead of from the client config. If that template has no sender email, an API-key caller gets `400 SenderEmailRequired`. **Language coverage for TurboQuote:** JavaScript/TypeScript, Python, Go, PHP, Java, and Ruby are fully covered. --- ## PHASE 3: Install SDK Run the install command for the detected language. Read the appropriate `references/.md` file for the exact command. **Detect package manager first:** - JS/TS: check lockfiles (pnpm-lock.yaml, yarn.lock, bun.lockb, package-lock.json) - Python: check for poetry.lock (poetry), Pipfile.lock (pipenv), else pip - PHP: always composer - Go: always go get - Java: check for pom.xml (Maven) or build.gradle (Gradle) - Ruby: if a `Gemfile` exists, use Bundler (`bundle add turbodocx-sdk`); otherwise `gem install turbodocx-sdk` Run the install command with Bash. --- ## PHASE 4: Add Environment Variables Read `references/env-vars.md` for the complete env var reference. **Based on product selection, add the corresponding vars to `.env` and `.env.example`:** **TurboSign and/or Deliverable** (both share the same credentials): ``` TURBODOCX_API_KEY=your_api_key_here TURBODOCX_ORG_ID=your_org_id_here ``` **TurboSign also requires** (for the reply-to address on signature emails): ``` TURBODOCX_SENDER_EMAIL=you@company.com TURBODOCX_SENDER_NAME=Your Company ``` **TurboPartner** (separate partner credentials): ``` TURBODOCX_PARTNER_API_KEY=your_partner_api_key_here TURBODOCX_PARTNER_ID=your_partner_id_here ``` If the user selected multiple products, union the relevant variables. Deliverable does **not** need sender vars (it doesn't send email). TurboPartner does **not** use the TurboSign API key or org ID. **Important:** - If `.env` exists, append new vars (don't overwrite existing content) - If `.env.example` exists, append var names with placeholder values - Check `.gitignore` — if `.env` is not listed, add it - Use Edit tool to append to existing files, Write tool to create new ones --- ## PHASE 5: Read Language Reference Read the reference file for the detected language: - JavaScript/TypeScript → read `references/javascript.md` - Python → read `references/python.md` - Go → read `references/go.md` - PHP → read `references/php.md` - Java → read `references/java.md` - Ruby → read `references/ruby.md` These files contain the exact code templates for configuration, usage examples, and framework integration patterns. --- ## PHASE 6: Analyze Codebase and Generate Code **CRITICAL: Explore the project structure BEFORE generating any code.** ### Step 6.1: Explore Project Structure Use Glob and Read to understand: - **Source file locations**: `src/`, root, `app/`, `internal/`, `pkg/`, etc. - **Existing route/handler patterns**: `**/routes/**`, `**/api/**`, `**/controllers/**`, `**/handlers/**` - **Main app/entry file**: `**/app.{ts,js,py}`, `**/server.{ts,js}`, `**/index.{ts,js}`, `**/main.{py,go}` - **Existing config/env loading patterns**: how does the project load env vars? - **Code style**: naming conventions, import style, error handling, async patterns ### Step 6.2: Confirm Findings Tell the user what you found: ``` I explored your project structure: - Project Type: [LANGUAGE/FRAMEWORK] - Source Location: [PATH] - Routes Location: [PATH or "none found - will create"] - Main App File: [PATH] - Existing Patterns: [Brief description] Does this look correct? ``` ### Step 6.3: Generate Config File Create a client initialization file using the code template from the language reference. Place it following the project's existing conventions: - If the project has a `lib/`, `utils/`, `config/`, or `core/` directory, put it there - Otherwise use sensible defaults (e.g., `src/lib/turbodocx.ts` for Express) The config file should: - Import the SDK — only the modules the user selected (`TurboSign`, `Deliverable`, `TurboPartner`) - Configure each selected module - Load env vars using the project's existing pattern - Export the configured client(s) ### Step 6.4: Generate Integration Code Create working route handlers / endpoint code for the selected product(s). The language reference contains exact method signatures, request shapes, and response shapes — follow those, don't guess. **For TurboSign, generate:** - `sendSignature()` endpoint — accepts file (or `fileLink` / `deliverableId` / `templateId`), recipients, fields - If the user wants **conditional (IF/THEN) fields** — a field that shows or unlocks only when the signer ticks a box: add a controlling `checkbox` field carrying `metadata.fieldKey`, and a dependent field carrying `metadata.conditional` (`{ controllingFieldKey, operator: "is_checked" | "is_not_checked", action: "show" | "unlock" }`) whose `controllingFieldKey` matches the checkbox's `fieldKey`. `action: "show"` keeps the dependent field hidden until the condition is met; `action: "unlock"` shows it but read-only until met. `metadata` is optional and both live on the normal `sendSignature()` field array — see the language reference for the exact per-language shape. - `getStatus()` endpoint — check the document-level status by ID - `getRecipients()` endpoint — every recipient with their signing status, email history, and who sent the document. Generate this whenever the user wants to know **who has signed / who is still pending**; `getStatus()` alone cannot answer that. Note each recipient carries both `status` (raw: `pending`/`viewed`/`completed`) and `effectiveStatus` (adds `voided`/`expired`) — generated code should branch on `effectiveStatus`, since an unsigned signer on a voided document still reads `pending` in the raw field. - `download()` endpoint — stream signed PDF (returns `Blob`/`ArrayBuffer` per language) - If the user mentioned a preview, review step, draft, or "verify field placement before sending": also generate a `createSignatureReviewLink()` endpoint. This prepares the document and returns a `previewUrl` **without sending signature emails** — pair it with `sendSignature()` as a two-step preview-then-send workflow. - If the user mentioned chasing, nudging, or reminding signers: use `sendReminder()`, **not** `resend()` — it is a standalone nudge that works even when automatic reminders are off and does not consume the reminder cap. Omit the recipient id list to remind everyone eligible; never pass an empty list, which the API rejects. - If the user wants the chasing or the deadline to happen automatically: pass the per-document schedule fields on `sendSignature()` — `remindersEnabled`/`reminderDelay`/`reminderInterval`/`maxReminders` and `expirationEnabled`/`expireAfter`/`expirationWarning`/`expirationWarningInterval`. Durations are `{ value, unit }` objects (`"hours"`/`"days"`), never bare numbers. - Optionally: `void()`, `resend()`, `getAuditTrail()` if the user mentioned cancellation, re-sending the invitation, or compliance/audit needs (per-language method names vary — consult the language reference; e.g. JS uses `void()`/`resend()`, Java uses `voidDocument()`/`resendEmail()`, Ruby uses `void_document`/`resend_email`) **For Deliverable, generate:** - `generateDeliverable()` endpoint — accepts `templateId` + `variables`, returns the new deliverable ID - `getDeliverableDetails()` endpoint — fetch one by ID - `downloadPDF()` endpoint — stream the PDF render - If the user also selected TurboSign, demonstrate the generate-then-sign workflow: call `generateDeliverable`, then pass the returned `deliverable.id` as `deliverableId` to `sendSignature` (no need to download and re-upload — the platform routes it internally) **For TurboPartner, generate:** - `createOrganization()` endpoint — provision a new customer org - `listOrganizations()` endpoint — list managed orgs (uses `limit`/`offset` pagination, not `page`) - `updateOrganizationEntitlements()` endpoint — set features/tracking (the request body shape is `{ features?, tracking? }`, not bare features) - `getOrganizationPreferences()` / `updateOrganizationPreferences()` endpoints — read and set a tenant's TurboSign display preferences without touching its settings UI. Generate these whenever the user wants to configure how signatures **look** across their managed orgs, or asks to apply the same signature appearance to every tenant. Four partner-settable booleans: `hideSignatureOutline` (default `false`), `hideSignatureHash` (default `false`), `lockedFieldsBackground` (default `true`), `allowDownloadBeforeSigning` (default `false`). The update is a **merge** — send only the keys you want to change and every other org setting is preserved; the API returns only these four keys and never the org's other preferences. The key names stay **camelCase verbatim** in every language, including Python and Ruby, and are gated by the partner's `canUpdateEntitlements` permission (same one as entitlements), so a key the partner isn't granted is rejected rather than silently ignored. **For TurboQuote, generate:** - `createQuote()` endpoint — accepts `name`, `companyId`, `contactId` (+ optional `currency`/`termDays`/`validUntil`/`taxRate`); returns the new quote. `termDays` defaults to **60**; `renewalPeriod` is required only when `termDays` is `-1` (auto-renewal) and must be omitted otherwise - `addLineItems()` endpoint — add product line items (single object or array, max 50) to a quote. `productId`, `productName`, `unitPrice`, and `billingFrequency` are **all required** on every item — `productId` must be present but may be `null` for a custom, non-catalog item - `sendQuote()` endpoint — send a quote for review; returns `{ quote, message }`. Optionally accepts the same reminder/expiration schedule fields as signature send, with one difference: the expiry is pinned to the quote's `validUntil` (so `expireAfter` is ignored; `expirationEnabled` still toggles it per-quote) - `downloadQuotePdf()` endpoint — stream the quote PDF (raw bytes per language) - If the user is building a catalog, also scaffold `createProduct()` / `createBundle()` / `createPriceBook()` + `applyPriceBook()`. TurboQuote configures with `apiKey` + `orgId` only — no `senderEmail`, because the quote sender comes from the org's quote template (Quote Settings), not from the client config. Sending a quote still emails the recipient; a template with no sender email makes `sendQuote()` fail with `400 SenderEmailRequired`. Once the basics are scaffolded, point the user at the language reference (`references/.md`) for the full set of available operations — there are many more than the starter set (org/user/API-key management, audit logs, etc.) and the agent should mention which additional operations exist for the user's selected product so they know what to ask for next. **IMPORTANT:** - Match existing code patterns (file naming, import style, error handling, async patterns) - Place route files where existing routes live - Wire routes into the main app file (add import + registration) - Use the typed error hierarchy from the reference — `ValidationError`, `AuthenticationError`, `NotFoundError`, `RateLimitError`, `NetworkError` all import directly from `@turbodocx/sdk` (or the language equivalent); they are not namespaced under a module. - **Match each language's method casing** — JS/PHP/Java camelCase, Python/Ruby snake_case (`send_signature`, `create_quote`), Go PascalCase. For **Ruby specifically**: methods and keyword args are snake_case, but the **keys inside a request hash stay camelCase verbatim** (`documentName`, `signingOrder`, `recipientEmail`, `companyId`) — the SDK does not convert payload keys, so a hash key written in snake_case silently drops the value. Errors are `TurboDocxSdk::*Error` with a `status_code`. - Include inline comments explaining each step --- ## PHASE 7: Verify and Summarize ### Verification Checklist ``` - SDK package is in the manifest (package.json, go.mod, requirements.txt, etc.) - Config file created and exports configured client(s) - Route handlers created with proper error handling - Routes wired into main app file - .env has all required variables - .env is in .gitignore - No secrets hardcoded in source files ``` **For TypeScript projects:** Run `npx tsc --noEmit` and fix any errors. ### Summary ``` TurboDocx Integration Complete! Created Files: - [List all created/modified files] Installed: - [SDK package name] Environment Variables (update in .env): - [List vars that need real values] Quick Test: [Provide curl command or test snippet for the first endpoint] Next Steps: 1. Get your API credentials at https://app.turbodocx.com 2. Update .env with your credentials 3. Start your server and test the endpoints Documentation: https://docs.turbodocx.com/docs Support: https://discord.gg/NYKwz4BcpX ``` --- ## Shortcuts Support arguments to skip product selection: - `/turbodocx-sdk turbosign` — TurboSign only - `/turbodocx-sdk deliverable` — Deliverable only - `/turbodocx-sdk turbosign+deliverable` — generate-then-sign workflow - `/turbodocx-sdk turbopartner` — TurboPartner only (partner-portal use case; requires partner credentials) - `/turbodocx-sdk turbowebhooks` — TurboWebhooks only (subscribe to signature events; PHP, JS/TS, Python, Go, Java, and Ruby supported) - `/turbodocx-sdk turboquote` — TurboQuote only (build quotes/proposals: quotes, line items, products, bundles, price books, companies/contacts; JS/TS, Python, Go, PHP, Java, and Ruby supported) For backwards compatibility, `/turbodocx-sdk both` is treated as TurboSign + Deliverable. --- ## Execution Instructions 1. **Phase 1**: Use Glob to detect project files. Parse manifest to confirm language. 2. **Phase 2**: Use AskUserQuestion for product selection (unless shortcut provided). 3. **Phase 3**: Use Bash to run install command. 4. **Phase 4**: Use Edit/Write to add env vars to .env files. Use Edit to update .gitignore. 5. **Phase 5**: Use Read to load the appropriate `references/.md` file from this skill's directory. 6. **Phase 6**: Use Glob + Read to explore the project, then Write/Edit to generate config and route files. **Always edit the main app file to wire in the new routes.** 7. **Phase 7**: Verify files exist and compile. Print summary.