@assinafy/sdk 1.4.0 → 2.0.0

package/README.md

@@ -2,11 +2,15 @@
 
 TypeScript SDK for the [Assinafy API](https://api.assinafy.com.br/v1/docs) — a Brazilian digital signature platform.
 
-Provides 100% endpoint coverage of the public API: documents, signers, assignments, templates, tags, workspaces, webhooks, field definitions, authentication, public/signer-side flows, and the high-level `uploadAndRequestSignatures` helper.
+Covers the server-side surface of the API: documents, signers, assignments, templates, tags, workspaces, webhooks, field definitions, authentication, public/signer-side flows, and the high-level `uploadAndRequestSignatures` helper.
+
+Deliberately not wrapped: the browser-redirect OAuth endpoints (`/auth/authenticate`, `/auth/link-social-login`, `/login-callback`), which a server-side SDK cannot meaningfully drive, and the account `theme`/`logo` branding routes.
 
 ## Requirements
 
-- Node.js 18+ for the built-in `FormData` / `Blob` APIs used by uploads
+- Node.js 22+ for the built-in `FormData` / `Blob` APIs used by uploads. Tested
+  on 22 (maintenance LTS) and 24 (active LTS); Node 20 reached end-of-life in
+  April 2026 and is no longer supported.
 - or Bun 1.0+
 
 ## Installation
@@ -66,11 +70,19 @@ new AssinafyClient({ token: 'jwt_xxx', accountId: 'acc_xxx' });
 | `apiKey`        | string   | —                                       | Preferred credential (sent as `X-Api-Key`).   |
 | `token`         | string   | —                                       | Legacy access token (sent as `Bearer`).       |
 | `accountId`     | string   | —                                       | Default workspace/account ID.                  |
-| `baseUrl`       | string   | `https://api.assinafy.com.br/v1`        | Override base URL.                             |
+| `baseUrl`       | string   | `https://api.assinafy.com.br/v1`        | Override base URL (e.g. the sandbox).          |
 | `webhookSecret` | string   | —                                       | Shared secret used by `WebhookVerifier`.       |
 | `timeout`       | number   | `30000`                                 | Request timeout in milliseconds.               |
+| `maxRetries`    | number   | `2`                                     | Auto-retries on HTTP 429, honoring `Retry-After`. `0` disables. |
 | `logger`        | `Logger` | no-op                                   | Optional `{debug,info,warn,error}` logger.     |
 
+### Rate limiting
+
+The API allows ~120 requests/minute and returns `X-Rate-Limit-*` headers. On an
+HTTP `429`, the client automatically retries up to `maxRetries` times, waiting
+for the server-provided `Retry-After` (or `X-Rate-Limit-Reset`) delay before
+each attempt. Only `429` is retried, so non-idempotent calls are safe.
+
 ### Factories
 
 ```ts
@@ -90,16 +102,16 @@ Every public endpoint documented in https://api.assinafy.com.br/v1/docs is cover
 
 | Resource              | Endpoints                                                                                                                                                                                                                                          |
 | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `client.documents`    | list, upload, details, activities, waitUntilReady, download, thumbnail, downloadPage, statuses, delete, verify, createFromTemplate, estimateCostFromTemplate, **getPublic**, **sendToken**, **listTags**, **replaceTags**, **addTags**, **detachTag**, isFullySigned, getSigningProgress |
+| `client.documents`    | list, **search**, upload, details, get, **rename**, activities, waitUntilReady, download, thumbnail, downloadPage, statuses, delete, verify, createFromTemplate, estimateCostFromTemplate, getPublic, sendToken, listTags, replaceTags, addTags, detachTag, isFullySigned, getSigningProgress |
 | `client.signers`      | create, get, list, update, delete, findByEmail                                                                                                                                                                                                     |
-| `client.assignments`  | create, estimateCost, resetExpiration, resendNotification, estimateResendCost, listWhatsAppNotifications, cancel                                                                                                                                   |
-| `client.templates`    | list, get, downloadPage                                                                                                                                                                                                                            |
+| `client.assignments`  | **list**, create, estimateCost, resetExpiration, resendNotification, estimateResendCost, listWhatsAppNotifications                                                                                                                                  |
+| `client.templates`    | **create**, list, get, **update**, **delete**, downloadPage                                                                                                                                                                                        |
 | `client.tags`         | list, create, update, delete                                                                                                                                                                                                                       |
 | `client.workspaces`   | create, list, get, update, delete                                                                                                                                                                                                                  |
-| `client.webhooks`     | register, get, inactivate, delete, listEventTypes, listDispatches, retryDispatch                                                                                                                                                                   |
+| `client.webhooks`     | register, get, inactivate, listEventTypes, listDispatches, retryDispatch                                                                                                                                                                           |
 | `client.fields`       | create, list, get, update, delete, validate, validateMultiple, listTypes                                                                                                                                                                           |
 | `client.auth`         | login, socialLogin, createApiKey, getApiKey, deleteApiKey, changePassword, requestPasswordReset, resetPassword                                                                                                                                     |
-| `client.signerDocuments` | getCurrent, list, download, signMultiple, declineMultiple, self, acceptTerms, verifyEmail, confirmData, uploadSignature, downloadSignature, getAssignment, sign, decline                                                                        |
+| `client.signerDocuments` | getCurrent, list, **search**, download, signMultiple, declineMultiple, self, acceptTerms, verifyEmail, confirmData, uploadSignature, downloadSignature, getAssignment, sign, decline                                                            |
 | `client.webhookVerifier` | verify, extractEvent, getEventType, getEventData                                                                                                                                                                                                |
 
 ## Resources
@@ -112,17 +124,40 @@ Most account-scoped methods accept an optional `accountId` that overrides the cl
 // Upload from a file path (recommended)
 const doc = await client.documents.upload(
   { filePath: './contract.pdf' },
-  { metadata: { type: 'service' } },
+  { name: 'Service agreement', metadata: { type: 'service' } },
 );
+// `name` is optional and defaults to the file's own name. The API derives the
+// display name from the uploaded filename and appends `.pdf` when absent, so
+// the document above is stored as 'Service agreement.pdf'. Accents are
+// transliterated by the API ('Contrato de Serviço' → 'Contrato de Servico.pdf').
+// → {
+//   resource: 'document', id: '1031…', account_id: '102d…', template_id: null,
+//   name: 'contract.pdf', status: 'uploaded',
+//   artifacts: { original: 'https://…/download/original' },
+//   signing_url: 'https://app…/sign/1031…',
+//   pages: [],                 // populated once status reaches `metadata_ready`
+//   tags: [], is_closed: false, created_at: '2026-…', updated_at: '2026-…'
+// }
 
 // …or from a Buffer already in memory
 await client.documents.upload({ buffer, fileName: 'contract.pdf' });
 
+// List → { data: IDocumentListItem[], meta?: { current_page, per_page, total, last_page } }
 const { data, meta } = await client.documents.list({ page: 1, per_page: 20, sort: '-created_at' });
+
+// Search is the lightweight alternative to list: same item shape, but the API
+// skips the expanded `assignment`/`pages`. Prefer it for name lookups.
+const hits = await client.documents.search({ search: 'agreement', status: 'pending_signature', 'per-page': 20 });
+
 await client.documents.details(doc.id);
 await client.documents.activities(doc.id);
 await client.documents.waitUntilReady(doc.id, { maxWaitMs: 30_000 });
 
+// Rename. The API rejects this with 400 while the document is still in
+// `metadata_processing`, so await waitUntilReady() first on a fresh upload.
+// (Passing `name` to upload() avoids both the round-trip and the race.)
+await client.documents.rename(doc.id, 'Signed service agreement.pdf');
+
 await client.documents.download(doc.id, 'certificated');   // 'original' | 'certificated' | 'certificate-page' | 'bundle'
 await client.documents.thumbnail(doc.id);
 await client.documents.downloadPage(doc.id, pageId);
@@ -159,6 +194,9 @@ await client.signers.create({
   whatsapp_phone_number: '+5548999990000',
   cpf: '123.456.789-00', // optional Brazilian tax ID — non-digits are stripped automatically
 });
+// → { id: '19e6…', full_name: 'John Doe', email: 'john@example.com',
+//     whatsapp_phone_number: '+5548999990000', has_accepted_terms: false }
+// (note: `cpf` is accepted on input but never echoed back by the API)
 
 // `email` is optional — a WhatsApp-only signer is valid (at least one is required)
 await client.signers.create({
@@ -186,6 +224,10 @@ When an `email` is supplied, `signers.create()` is idempotent by email, matching
 ### Assignments
 
 ```ts
+// List every assignment in the workspace.
+// → { data: IAssignment[], meta?: { current_page, per_page, total, last_page } }
+const { data, meta } = await client.assignments.list({ page: 1, 'per-page': 20 });
+
 // Signers may be ids or objects — the SDK normalises to the API shape.
 await client.assignments.create(documentId, {
   method: 'virtual',
@@ -204,40 +246,80 @@ await client.assignments.create(documentId, {
   ],
 });
 
-// Estimate cost (signers may omit `id` when only the channel matters)
+// Estimate cost (signers may omit `id` when only the channel matters) → ICostEstimate
 await client.assignments.estimateCost(documentId, { signers: ['signer-1'] });
 await client.assignments.estimateCost(documentId, {
   signers: [{ verification_method: 'Whatsapp' }],
 });
+// → {
+//   documents: 1, credits: 0, needs_extra_document: false, extra_document_cost: 0,
+//   total_credits: 0, breakdown: [], document_balance: 67, credit_balance: 0,
+//   has_sufficient_resources: true, blocking_reason: null, message: null
+// }
 
 await client.assignments.resetExpiration(documentId, assignmentId, '2025-06-30T00:00:00Z');
 await client.assignments.resetExpiration(documentId, assignmentId, null); // remove expiration
+
 await client.assignments.resendNotification(documentId, assignmentId, signerId);
+// → { is_sent: true, document_id: '…', signer_id: '…' }
+
 await client.assignments.estimateResendCost(documentId, assignmentId, signerId);
-await client.assignments.listWhatsAppNotifications(documentId, assignmentId);
-await client.assignments.cancel(documentId, 'No longer needed');
+// → { total: 0, breakdown: [{ code: 'NotificationEmailResend', name: '…', cost: 0 }],
+//     credit_balance: 0, has_sufficient_credits: true }
+
+await client.assignments.listWhatsAppNotifications(documentId, assignmentId); // → IWhatsAppNotification[]
 ```
 
+The `create` response is an `IAssignment`: `{ id, method, signers: [...], items: [...], signing_urls: [{ signer_id, url }], … }`.
+
 For backwards compatibility, the SDK also accepts legacy `signer_ids` and `signerIds` payloads and rewrites them to the current `signers: [{ id }]` format expected by the API.
 
+**Cancelling a signature request.** Assinafy has no workspace-side "cancel" endpoint. To stop a pending request either delete the document (when its status is deletable) or have the signer decline:
+
+```ts
+await client.documents.delete(documentId);                                  // workspace-side
+await client.signerDocuments.decline(documentId, assignmentId, accessCode, 'No longer needed'); // signer-side
+```
+
 ### Templates
 
 ```ts
+// Create a template by uploading a PDF (multipart). The template starts in
+// `Uploaded` status and becomes `Ready` once its pages are processed.
+const created = await client.templates.create(
+  { filePath: './nda.pdf' },          // or { buffer, fileName: 'nda.pdf' }
+  { name: 'NDA template' },
+);
+// →
+// {
+//   resource: 'template', id: '1032...', name: 'nda.pdf',
+//   document_name: 'nda.pdf', message: null, status: 'Uploaded',
+//   roles: [{ id: '1032...', name: 'TemplateEditor', assignment_type: 'Editor' }],
+//   pages: [], tags: [], created_at: '2026-…', updated_at: '2026-…'
+// }
+
 const { data, meta } = await client.templates.list({ search: 'NDA', per_page: 20 });
-const template = await client.templates.get(templateId);
-await client.templates.downloadPage(templateId, pageId);
+const template = await client.templates.get(created.id);   // includes pages[] + default_document_tags
+await client.templates.update(created.id, { name: 'NDA v2', message: 'Please sign' });
+await client.templates.downloadPage(created.id, template.pages![0].id); // → Buffer (JPEG)
+await client.templates.delete(created.id);
 
-// Create a document from a template (each signer maps to a template role)
+// Create a *document* from a template (each signer maps to a template role)
 await client.documents.createFromTemplate(
   templateId,
   [{ role_id: template.roles![0].id, id: signerId, verification_method: 'Email', notification_methods: ['Email'] }],
   { name: 'NDA - John Doe', message: 'Please sign at your earliest convenience.' },
 );
 
-// Estimate the cost before creating
+// Estimate the cost before creating → ICostEstimate
 await client.documents.estimateCostFromTemplate(templateId, [{ role_id: 'role_id', id: signerId }]);
+// → { documents: 1, total_credits: 0, document_balance: 67, credit_balance: 0,
+//     has_sufficient_resources: true, blocking_reason: null, breakdown: [], … }
 ```
 
+Template creation only uploads the PDF and provisions the default editor role —
+configure roles/fields in the Assinafy editor (or the web UI) afterwards.
+
 ### Tags
 
 Workspace-scoped labels that can be attached to documents and templates. Tag names are unique per workspace (case-insensitive).
@@ -326,8 +408,7 @@ await client.webhooks.register({
 });
 
 await client.webhooks.get();          // current subscription or null
-await client.webhooks.inactivate();
-await client.webhooks.delete();
+await client.webhooks.inactivate();   // stop deliveries (no delete route exists)
 await client.webhooks.listEventTypes();
 await client.webhooks.listDispatches({ delivered: false, page: 1, 'per-page': 20 });
 await client.webhooks.retryDispatch(dispatchId);
@@ -373,6 +454,8 @@ await client.signerDocuments.verifyEmail({ signerAccessCode: accessCode, verific
 
 await client.signerDocuments.getCurrent(signerId, accessCode);
 const { data } = await client.signerDocuments.list(signerId, accessCode, { search: 'invoice' });
+// Signer-side counterpart of documents.search(), authorised by the access code.
+const found = await client.signerDocuments.search(signerId, accessCode, 'invoice');
 await client.signerDocuments.download(signerId, documentId, 'original', accessCode);
 
 await client.signerDocuments.confirmData(documentId, accessCode, {
@@ -448,9 +531,12 @@ A real-network test script under [`scripts/live-smoke.ts`](scripts/live-smoke.ts
 ```bash
 ASSINAFY_API_KEY=… ASSINAFY_ACCOUNT_ID=… bun scripts/live-smoke.ts            # read-only
 ASSINAFY_API_KEY=… ASSINAFY_ACCOUNT_ID=… bun scripts/live-smoke.ts --write    # also creates+deletes a signer
-ASSINAFY_API_KEY=… ASSINAFY_ACCOUNT_ID=… bun scripts/live-smoke.ts --upload   # also uploads+deletes a PDF
+ASSINAFY_API_KEY=… ASSINAFY_ACCOUNT_ID=… bun scripts/live-smoke.ts --upload   # also uploads a PDF + a template, then deletes both
 ```
 
+Set `ASSINAFY_BASE_URL=https://sandbox.assinafy.com.br/v1` to run it against the
+sandbox instead of production.
+
 ## Development
 
 ```bash