@assinafy/sdk 2.0.0 → 2.1.2

package/docs/API_COVERAGE.md

@@ -0,0 +1,207 @@
+# API coverage
+
+This ledger maps the official
+[`GET /v1/docs/openapi.json`](https://api.assinafy.com.br/v1/docs/openapi.json)
+contract to the public SDK API: 67 paths, 89 HTTP operations, and 39 component
+schemas.
+
+All paths below include the `/v1` prefix shown by the OpenAPI document. The
+SDK's default `baseUrl` already ends in `/v1`, so resource implementations use
+the corresponding relative path without repeating that prefix.
+
+Status meanings:
+
+- **Covered** — a public, typed SDK method sends the operation.
+- **Compatibility extension** — route retained for existing integrations but
+  absent from the current OpenAPI path set and excluded from the 89-operation
+  total.
+
+## Accounts — 10/10
+
+| Method | Path | SDK method | Status |
+| --- | --- | --- | --- |
+| `GET` | `/v1/accounts` | `client.workspaces.list()` | Covered |
+| `POST` | `/v1/accounts` | `client.workspaces.create(payload)` | Covered |
+| `GET` | `/v1/accounts/{accountId}` | `client.workspaces.get(accountId)` | Covered |
+| `PUT` | `/v1/accounts/{accountId}` | `client.workspaces.update(accountId, payload)` | Covered |
+| `DELETE` | `/v1/accounts/{accountId}` | `client.workspaces.delete(accountId, options?)` | Covered |
+| `GET` | `/v1/accounts/{accountId}/theme` | `client.workspaces.getTheme(accountId)` | Covered |
+| `GET` | `/v1/accounts/{accountId}/logo` | `client.workspaces.downloadLogo(accountId)` | Covered |
+| `POST` | `/v1/accounts/{accountId}/logo` | `client.workspaces.uploadLogo(accountId, source)` | Covered |
+| `DELETE` | `/v1/accounts/{accountId}/logo` | `client.workspaces.deleteLogo(accountId)` | Covered |
+| `GET` | `/v1/accounts/{accountId}/stats` | `client.workspaces.getStats(accountId, params?)` | Covered |
+
+## Assignments — 7/7
+
+| Method | Path | SDK method | Status |
+| --- | --- | --- | --- |
+| `GET` | `/v1/assignments` | `client.assignments.list(params?, accountId?)` | Covered |
+| `POST` | `/v1/documents/{documentId}/assignments` | `client.assignments.create(documentId, payload)` | Covered |
+| `POST` | `/v1/documents/{documentId}/assignments/estimate-cost` | `client.assignments.estimateCost(documentId, payload)` | Covered |
+| `PUT` | `/v1/documents/{documentId}/assignments/{assignmentId}/signers/{signerId}/resend` | `client.assignments.resendNotification(documentId, assignmentId, signerId)` | Covered |
+| `POST` | `/v1/documents/{documentId}/assignments/{assignmentId}/signers/{signerId}/estimate-resend-cost` | `client.assignments.estimateResendCost(documentId, assignmentId, signerId)` | Covered |
+| `PUT` | `/v1/documents/{documentId}/assignments/{assignmentId}/reset-expiration` | `client.assignments.resetExpiration(documentId, assignmentId, expiresAt)` | Covered |
+| `GET` | `/v1/documents/{documentId}/assignments/{assignmentId}/whatsapp-notifications` | `client.assignments.listWhatsAppNotifications(documentId, assignmentId)` | Covered |
+
+## Authentication — 9/9
+
+| Method | Path | SDK method | Status |
+| --- | --- | --- | --- |
+| `POST` | `/v1/login` | `client.auth.login(email, password)` | Covered |
+| `PUT` | `/v1/authentication/request-password-reset` | `client.auth.requestPasswordReset(email)` | Covered |
+| `PUT` | `/v1/authentication/reset-password` | `client.auth.resetPassword(payload)` | Covered |
+| `PUT` | `/v1/authentication/change-password` | `client.auth.changePassword(payload)` | Covered |
+| `POST` | `/v1/authentication/social-login` | `client.auth.socialLogin(payload)` | Covered |
+| `POST` | `/v1/auth/link-social-login` | `client.auth.linkSocialLogin(payload)` | Covered |
+| `GET` | `/v1/users/api-keys` | `client.auth.getApiKey()` | Covered |
+| `POST` | `/v1/users/api-keys` | `client.auth.createApiKey(password)` | Covered |
+| `DELETE` | `/v1/users/api-keys` | `client.auth.deleteApiKey()` | Covered |
+
+## Documents — 18/18
+
+| Method | Path | SDK method | Status |
+| --- | --- | --- | --- |
+| `GET` | `/v1/accounts/{accountId}/documents` | `client.documents.list(params?, accountId?)` | Covered |
+| `POST` | `/v1/accounts/{accountId}/documents` | `client.documents.upload(source, options?)` | Covered |
+| `GET` | `/v1/accounts/{accountId}/documents/search` | `client.documents.search(params?, accountId?)` | Covered |
+| `GET` | `/v1/documents/statuses` | `client.documents.statuses()` | Covered |
+| `GET` | `/v1/documents/{documentId}` | `client.documents.details(documentId)` / `get(documentId)` | Covered |
+| `DELETE` | `/v1/documents/{documentId}` | `client.documents.delete(documentId)` | Covered |
+| `PATCH` | `/v1/documents/{documentId}` | `client.documents.rename(documentId, name)` | Covered |
+| `GET` | `/v1/documents/{documentId}/activities` | `client.documents.activities(documentId)` | Covered |
+| `GET` | `/v1/documents/{documentId}/download/{artifactName}` | `client.documents.download(documentId, artifactName)` | Covered |
+| `GET` | `/v1/documents/{documentSignatureHash}/verify` | `client.documents.verify(documentSignatureHash)` | Covered |
+| `GET` | `/v1/documents/{documentId}/thumbnail` | `client.documents.thumbnail(documentId)` | Covered |
+| `GET` | `/v1/documents/{documentId}/pages/{pageId}/download` | `client.documents.downloadPage(documentId, pageId)` | Covered |
+| `GET` | `/v1/accounts/{accountId}/documents/{documentId}/tags` | `client.documents.listTags(documentId, accountId?)` | Covered |
+| `PUT` | `/v1/accounts/{accountId}/documents/{documentId}/tags` | `client.documents.replaceTags(documentId, tagIds, accountId?)` | Covered |
+| `POST` | `/v1/accounts/{accountId}/documents/{documentId}/tags` | `client.documents.addTags(documentId, tagIds, accountId?)` | Covered |
+| `DELETE` | `/v1/accounts/{accountId}/documents/{documentId}/tags/{tagId}` | `client.documents.detachTag(documentId, tagId, accountId?)` | Covered |
+| `POST` | `/v1/accounts/{accountId}/templates/{templateId}/documents` | `client.documents.createFromTemplate(templateId, signers, options?, accountId?)` | Covered |
+| `POST` | `/v1/accounts/{accountId}/templates/{templateId}/documents/estimate-cost` | `client.documents.estimateCostFromTemplate(templateId, signers, accountId?)` | Covered |
+
+## Fields — 8/8
+
+| Method | Path | SDK method | Status |
+| --- | --- | --- | --- |
+| `GET` | `/v1/accounts/{accountId}/fields` | `client.fields.list(params?, accountId?)` | Covered |
+| `POST` | `/v1/accounts/{accountId}/fields` | `client.fields.create(payload, accountId?)` | Covered |
+| `GET` | `/v1/accounts/{accountId}/fields/{fieldId}` | `client.fields.get(fieldId, accountId?)` | Covered |
+| `PUT` | `/v1/accounts/{accountId}/fields/{fieldId}` | `client.fields.update(fieldId, payload, accountId?)` | Covered |
+| `DELETE` | `/v1/accounts/{accountId}/fields/{fieldId}` | `client.fields.delete(fieldId, accountId?)` | Covered |
+| `POST` | `/v1/accounts/{accountId}/fields/{fieldId}/validate` | `client.fields.validate(fieldId, value, options?)` | Covered |
+| `POST` | `/v1/accounts/{accountId}/fields/validate-multiple` | `client.fields.validateMultiple(entries, options?)` | Covered |
+| `GET` | `/v1/field-types` | `client.fields.listTypes()` | Covered |
+
+## Signers — 5/5
+
+| Method | Path | SDK method | Status |
+| --- | --- | --- | --- |
+| `GET` | `/v1/accounts/{accountId}/signers` | `client.signers.list(params?, accountId?)` | Covered |
+| `POST` | `/v1/accounts/{accountId}/signers` | `client.signers.create(payload, accountId?)` | Covered |
+| `GET` | `/v1/accounts/{accountId}/signers/{signerId}` | `client.signers.get(signerId, accountId?)` | Covered |
+| `PUT` | `/v1/accounts/{accountId}/signers/{signerId}` | `client.signers.update(signerId, payload, accountId?)` | Covered |
+| `DELETE` | `/v1/accounts/{accountId}/signers/{signerId}` | `client.signers.delete(signerId, accountId?)` | Covered |
+
+## Signing and public flows — 17/17
+
+All methods in this section use the auth-free transport. Most signer operations
+authenticate with the `signer-access-code` query parameter required by the
+OpenAPI security scheme. The artifact download is explicitly public and accepts
+an optional fourth access-code argument only for legacy compatibility.
+
+| Method | Path | SDK method | Status |
+| --- | --- | --- | --- |
+| `GET` | `/v1/public/documents/{documentId}` | `client.documents.getPublic(documentId)` | Covered |
+| `PUT` | `/v1/public/documents/{documentId}/send-token` | `client.documents.sendToken(documentId, email)` | Covered |
+| `GET` | `/v1/signers/self` | `client.signerDocuments.self(accessCode)` | Covered |
+| `GET` | `/v1/signers/{signerId}/document` | `client.signerDocuments.getCurrent(signerId, accessCode)` | Covered |
+| `GET` | `/v1/sign` | `client.signerDocuments.getAssignment(accessCode, hasAcceptedTerms?)` | Covered |
+| `POST` | `/v1/documents/{documentId}/assignments/{assignmentId}` | `client.signerDocuments.sign(documentId, assignmentId, accessCode, entries)` | Covered |
+| `PUT` | `/v1/documents/{documentId}/assignments/{assignmentId}/reject` | `client.signerDocuments.decline(documentId, assignmentId, accessCode, reason)` | Covered |
+| `PUT` | `/v1/signers/documents/sign-multiple` | `client.signerDocuments.signMultiple(documentIds, accessCode)` | Covered |
+| `PUT` | `/v1/signers/documents/decline-multiple` | `client.signerDocuments.declineMultiple(documentIds, reason, accessCode)` | Covered |
+| `POST` | `/v1/verify` | `client.signerDocuments.verifyEmail(payload)` | Covered |
+| `PUT` | `/v1/documents/{documentId}/signers/confirm-data` | `client.signerDocuments.confirmData(documentId, accessCode, payload)` | Covered |
+| `PUT` | `/v1/signers/accept-terms` | `client.signerDocuments.acceptTerms(accessCode)` | Covered |
+| `POST` | `/v1/signature` | `client.signerDocuments.uploadSignature(accessCode, image, options?)` | Covered |
+| `GET` | `/v1/signature/{signatureType}` | `client.signerDocuments.downloadSignature(accessCode, signatureType)` | Covered |
+| `GET` | `/v1/signers/{signerId}/documents` | `client.signerDocuments.list(signerId, accessCode, params?)` | Covered |
+| `GET` | `/v1/signers/{signerId}/documents/search` | `client.signerDocuments.search(signerId, accessCode, search)` | Covered |
+| `GET` | `/v1/signers/{signerId}/documents/{documentId}/download/{artifactName}` | `client.signerDocuments.download(signerId, documentId, artifactName)` | Covered |
+
+## Tags — 4/4
+
+| Method | Path | SDK method | Status |
+| --- | --- | --- | --- |
+| `GET` | `/v1/accounts/{accountId}/tags` | `client.tags.list(params?, accountId?)` | Covered |
+| `POST` | `/v1/accounts/{accountId}/tags` | `client.tags.create(payload, accountId?)` | Covered |
+| `PUT` | `/v1/accounts/{accountId}/tags/{tagId}` | `client.tags.update(tagId, payload, accountId?)` | Covered |
+| `DELETE` | `/v1/accounts/{accountId}/tags/{tagId}` | `client.tags.delete(tagId, options?)` | Covered |
+
+## Templates — 1/1 official
+
+| Method | Path | SDK method | Status |
+| --- | --- | --- | --- |
+| `GET` | `/v1/accounts/{accountId}/templates` | `client.templates.list(params?, accountId?)` | Covered |
+
+Five additional routes are documented separately under
+[Template compatibility routes](#template-compatibility-routes).
+
+## Users — 4/4
+
+| Method | Path | SDK method | Status |
+| --- | --- | --- | --- |
+| `GET` | `/v1/users/self` | `client.users.getCurrent()` | Covered |
+| `GET` | `/v1/users/self/stats` | `client.users.getStats(params?)` | Covered |
+| `GET` | `/v1/users/self/notification-preferences` | `client.users.getNotificationPreferences()` | Covered |
+| `PUT` | `/v1/users/self/notification-preferences` | `client.users.updateNotificationPreferences(preferences)` | Covered |
+
+## Webhooks — 6/6
+
+| Method | Path | SDK method | Status |
+| --- | --- | --- | --- |
+| `GET` | `/v1/accounts/{accountId}/webhooks/subscriptions` | `client.webhooks.get(accountId?)` | Covered |
+| `PUT` | `/v1/accounts/{accountId}/webhooks/subscriptions` | `client.webhooks.register(payload, accountId?)` | Covered |
+| `PUT` | `/v1/accounts/{accountId}/webhooks/inactivate` | `client.webhooks.inactivate(accountId?)` | Covered |
+| `GET` | `/v1/webhooks/event-types` | `client.webhooks.listEventTypes()` | Covered |
+| `GET` | `/v1/accounts/{accountId}/webhooks` | `client.webhooks.listDispatches(params?, accountId?)` | Covered |
+| `POST` | `/v1/accounts/{accountId}/webhooks/{historyId}/retry` | `client.webhooks.retryDispatch(historyId, accountId?)` | Covered |
+
+## Template compatibility routes
+
+These routes are available to existing integrations but do not appear in the
+current OpenAPI path set. They are excluded from the official 89-operation
+coverage count.
+
+| Method | Path | SDK method | Status |
+| --- | --- | --- | --- |
+| `POST` | `/v1/accounts/{accountId}/templates` | `client.templates.create(source, options?)` | Compatibility extension |
+| `GET` | `/v1/accounts/{accountId}/templates/{templateId}` | `client.templates.get(templateId, accountId?)` | Compatibility extension |
+| `PUT` | `/v1/accounts/{accountId}/templates/{templateId}` | `client.templates.update(templateId, payload, accountId?)` | Compatibility extension |
+| `DELETE` | `/v1/accounts/{accountId}/templates/{templateId}` | `client.templates.delete(templateId, accountId?)` | Compatibility extension |
+| `GET` | `/v1/accounts/{accountId}/templates/{templateId}/pages/{pageId}/download` | `client.templates.downloadPage(templateId, pageId, accountId?)` | Compatibility extension |
+
+## SDK conveniences
+
+These helpers compose or derive official operations and therefore do not add to
+the endpoint count:
+
+- `client.uploadAndRequestSignatures(options)` validates the complete input,
+  uploads a document, reuses or creates signers, creates its virtual assignment
+  while metadata may still be processing, and optionally polls before returning
+  current document details.
+- `client.documents.waitUntilReady(documentId, options?)` polls the official
+  document-details operation with terminal-state and timeout handling.
+- `client.documents.isFullySigned(documentId)` and
+  `getSigningProgress(documentId)` derive state from document details.
+- `client.signers.findByEmail(email, accountId?)` uses the official signer list.
+- `client.webhookVerifier` parses webhook envelopes and optionally verifies a
+  caller-configured HMAC contract; signature verification itself is not in the
+  current OpenAPI document.
+
+For request and response payload definitions, use the exported TypeScript
+interfaces and each method's JSDoc examples together with the
+[official API reference](https://api.assinafy.com.br/v1/docs). Deployment
+variants that require compatibility handling are recorded in
+[COMPATIBILITY.md](COMPATIBILITY.md).

package/docs/COMPATIBILITY.md

@@ -0,0 +1,362 @@
+# API compatibility
+
+The SDK targets the official Assinafy contract at
+[`/v1/docs/openapi.json`](https://api.assinafy.com.br/v1/docs/openapi.json).
+New integrations should send the published request shape. Compatibility paths
+are narrow, typed, and used only when a caller selects one or when a validation
+response unambiguously requests an older shape.
+
+## Host availability
+
+The production contract includes these account and authenticated-user routes:
+
+```text
+GET, POST          /v1/accounts
+GET, PUT, DELETE   /v1/accounts/{accountId}
+GET, POST, DELETE  /v1/accounts/{accountId}/logo
+GET                /v1/accounts/{accountId}/theme
+GET                /v1/accounts/{accountId}/stats
+GET                /v1/users/self
+GET, PUT           /v1/users/self/notification-preferences
+GET                /v1/users/self/stats
+```
+
+Sandbox deployments can return `404` for user statistics, account statistics,
+or notification preferences while still accepting the production methods on
+the production host. The SDK keeps the official paths and response types. A
+sandbox `404` does not cause the client to route a request elsewhere.
+
+Two browser URL helpers used by older deployments remain available:
+
+```text
+GET /v1/auth/authenticate
+GET /v1/login-callback
+```
+
+They map to `auth.getSocialLoginUrl()` and
+`auth.getSocialLoginCallbackUrl()` and are not part of the official
+89-operation total.
+
+The SDK also includes the production contract additions for:
+
+- the `pades` document artifact;
+- `DigitalCertificate` verification on assignment and template-document
+  creation and cost estimation;
+- typed `display_settings` for collect fields;
+- signer `government_id` updates;
+- signature-image `reuse`;
+- the documented `400` response from `GET /sign`; and
+- the dedicated `SignerSelf` response fields.
+
+Older signer-self responses can omit `has_signature`, `has_initial`, and
+`is_signature_reusable`; assignment signers can omit `notification_history`.
+Those fields are optional in the SDK response types.
+
+`DocumentStatsRow` separates notification-channel counters from verification
+method counters. Notification counters are not mutually exclusive.
+`signature_requests_verification_{email,whatsapp,bypass,digital_certificate}`
+are mutually exclusive and sum to `signature_requests`. Older unsuffixed email
+and WhatsApp counters remain optional.
+
+## Assignment list account context
+
+`GET /v1/assignments` requires the workspace in the camel-case `accountId`
+query parameter even though most account-scoped routes place it in the path.
+The SDK obtains it from the optional method argument or the client default:
+
+```ts
+const page = await client.assignments.list(
+  { page: 1, 'per-page': 20 },
+  'account-id',
+);
+// Request query: ?page=1&per-page=20&accountId=account-id
+// Response: { data: IAssignment[], meta?: PaginationMeta }
+```
+
+If neither source supplies an account ID, the SDK throws `ValidationError`
+before making the request.
+
+## Template management extensions
+
+The official OpenAPI document contains only:
+
+```text
+GET /v1/accounts/{accountId}/templates
+```
+
+Existing integrations can also use these routes:
+
+```text
+POST   /v1/accounts/{accountId}/templates
+GET    /v1/accounts/{accountId}/templates/{templateId}
+PUT    /v1/accounts/{accountId}/templates/{templateId}
+DELETE /v1/accounts/{accountId}/templates/{templateId}
+GET    /v1/accounts/{accountId}/templates/{templateId}/pages/{pageId}/download
+```
+
+They map to `templates.create`, `get`, `update`, `delete`, and `downloadPage`
+and are excluded from the official operation count. Template status casing can
+vary, so normalize before branching:
+
+```ts
+if (template.status.toLowerCase() === 'ready') {
+  // rendered pages are available
+}
+```
+
+A page object's `download_url` is protected by account authentication. Prefer
+`templates.downloadPage(templateId, pageId)` so the SDK attaches credentials
+and returns the JPEG bytes as a `Buffer`.
+
+## Public send-token request
+
+The official operation sends an email body:
+
+```http
+PUT /v1/public/documents/{documentId}/send-token
+Content-Type: application/json
+
+{ "email": "signer@example.com" }
+```
+
+```ts
+await client.documents.sendToken(documentId, 'signer@example.com');
+```
+
+Older environments can require `{ recipient, channel }`. The explicit
+three-argument overload sends that shape:
+
+```ts
+await client.documents.sendToken(documentId, '+5511999990000', 'whatsapp');
+```
+
+For a two-argument call, the SDK starts with `{ email }` and retries the older
+email shape only when the validation response names `recipient` or `channel` as
+required. Other errors are returned unchanged.
+
+## Document tags
+
+Replace and attach requests require existing tag IDs:
+
+```ts
+const tag = await client.tags.create({ name: 'Contracts', color: '#ff8800' });
+await client.documents.addTags(documentId, [tag.id]);
+await client.documents.replaceTags(documentId, [tag.id]);
+const result = await client.documents.detachTag(documentId, tag.id);
+// result → { detached: true }
+```
+
+The API accepts a tag color with or without a leading `#` and returns the
+stored six-character value without it. Unknown tag names are not the normal
+attachment input; create or list the tag first and send its ID. An empty array
+passed to `replaceTags` detaches every tag.
+
+## Account branding fields
+
+The official account create/update request schemas define `name` and
+`notification_sender_type`. The response includes `primary_color` and
+`secondary_color`. Some deployments also accept those two color fields on
+create/update, so the SDK retains them as optional inputs. Account colors must
+be six hexadecimal characters without a leading `#`.
+
+Some sandbox plans reject `notification_sender_type` during account creation
+while accepting it on update. If that occurs, create with `{ name }` and apply
+the sender type in a separate update. `getTheme`, `downloadLogo`, `uploadLogo`,
+and `deleteLogo` are official operations.
+
+`workspaces.delete(accountId, { force: true })` requests cancellation of an
+active paid subscription as part of account deletion. It is not a general
+override for unrelated deletion restrictions.
+
+## Field-definition extensions
+
+The official field-create body defines `type`, `name`, nullable `regex`, and
+`is_required`; update defines `name`, nullable `regex`, and `is_active`. The SDK
+also retains `is_active` on create and `type` or `is_required` on update for
+deployments that accept them. New code should prefer the operation-specific
+official fields.
+
+The field-validation schemas omit the `signer-access-code` query parameter used
+by some signer portals. `fields.validate()` and `validateMultiple()` retain the
+typed `signerAccessCode` option for those environments.
+
+## Signer request extensions
+
+The official signer-create schema uses `full_name`, `email`, and
+`whatsapp_phone_number`. Signer update adds `government_id`, which the SDK
+normalizes to digits. Three older integration inputs remain accepted:
+
+- `phone` is normalized to `whatsapp_phone_number` before transmission;
+- `cpf` is normalized to digits and forwarded; and
+- create-time `metadata` is forwarded unchanged.
+
+New integrations should use the official create fields and `government_id` on
+update. `cpf` is not an alias for the official update field, and signer
+responses do not return it.
+
+## Digital certificate and collect placement
+
+`DigitalCertificate` requires the account feature, a CPF or CNPJ stored in the
+signer's `government_id`, and exactly one certificate signer in that signing
+step. It costs two credits per signer in addition to the selected notification
+cost. Notification methods remain `Email` and `Whatsapp`.
+
+For a `collect` assignment, each field can include `display_settings`.
+`left`, `top`, `width`, `height`, and `fontSize` are required; `fontFamily` and
+`backgroundColor` are optional. Values use Assinafy's 150-DPI page-image pixels
+from the upper-left corner and must stay within the page.
+
+## Document responses and artifacts
+
+`documents.rename()` can return a document without `pages` or `assignment`.
+`IRenameDocumentResponse` therefore keeps those two properties optional while
+retaining the other document fields.
+
+`documents.details()` returns `decline_reason` only when the access token
+belongs to the document creator. Do not infer the absence of a decline merely
+because that field is missing for another authenticated user.
+
+Owner and signer downloads accept `original`, `certificated`,
+`certificate-page`, `pades`, and `bundle`:
+
+- `pades` exists only when the document had an ICP-Brasil certificate signer;
+- `bundle` is a ZIP containing `original`, `certificated`, and
+  `certificate-page`, plus `pades` when it exists; and
+- a generated artifact can return `404` until processing or certification is
+  complete.
+
+Document and page download URLs in JSON responses are protected. Prefer the
+typed download methods so credentials are applied and binary data is returned
+as a `Buffer`.
+
+## Signer-side preconditions
+
+The signer `confirm-data` body contains `full_name`, `email`,
+`government_id`, and `has_accepted_terms`. A certificate signer must confirm
+data and accept terms before `getAssignment()`; either send
+`has_accepted_terms: true` with `confirmData()` or call `acceptTerms()` first.
+The `has_accepted_terms` query on `getAssignment()` is too late to open that
+gate for a certificate signer.
+
+`getAssignment()` uses `GET /sign`, but the API records the signer as having
+viewed the assignment. The SDK therefore excludes this request from automatic
+HTTP 429 replay.
+
+`sign()` sends a non-empty array of `{ itemId, fieldId, pageId, value }` and is
+intended for collect assignments. A virtual signer must confirm their data
+before signing and should use `signMultiple()`, which accepts only virtual
+documents. Certificate signers cannot use `sign()`; they complete the
+certificate-start and certificate-complete browser flow.
+
+Signature image upload sends raw PNG bytes with `Content-Type: image/png`.
+`reuse: true` persists the image for later documents. A deprecated
+`contentType` option remains for older integrations, but the official contract
+supports PNG only.
+
+## Upload metadata and expiration reset
+
+Document upload accepts a PDF of at most 25 MB and 2,000 pages. The multipart
+schema documents the file; the SDK's optional `metadata` JSON part is retained
+for deployments that accept application-owned opaque metadata.
+
+The reset-expiration schema requires an ISO-8601 date-time string. The SDK also
+accepts `null` for older integrations that clear an expiration this way. Confirm
+support in the target deployment before sending `null`.
+
+## Resend-cost response variants
+
+The official resend-cost response is `ICostEstimate`. Older deployments can
+return a compact branch, so the SDK exposes `IResendCostEstimate`:
+
+```ts
+const estimate = await client.assignments.estimateResendCost(
+  documentId,
+  assignmentId,
+  signerId,
+);
+
+if ('total_credits' in estimate) {
+  console.log(estimate.has_sufficient_resources);
+} else {
+  console.log(estimate.total, estimate.has_sufficient_credits);
+}
+```
+
+The SDK does not add absent balance fields.
+
+## Public document and signer download
+
+The official public-document response is the full `Document` schema. Compact
+responses can contain only `id`, `name`, `page_count`, and `created_by`.
+`IPublicDocumentInfo` requires `id` and `name`, keeps expanded fields optional,
+and retains the compact fields:
+
+```ts
+const document = await client.documents.getPublic(documentId);
+const pages = document.pages?.length ?? Number(document.page_count ?? 0);
+```
+
+Signer artifact download is public in the OpenAPI document and requires no
+access-code query in the official three-argument call. An optional fourth code
+is available only for older deployments that require it.
+
+## Empty acknowledgements
+
+Several write operations return a success envelope without `data`; older
+responses can use an empty array or object. Methods with no meaningful result
+resolve to `Promise<void>` after validating the HTTP and envelope status. This
+applies to token dispatch, signer OTP and terms, signature-image upload, bulk
+signer actions, and deletions without a documented result. Tag deletion and
+document-tag detachment preserve `{ deleted: boolean }` and
+`{ detached: boolean }`.
+
+## WhatsApp notification buttons
+
+The published notification button schema requires `text`. Some deployments
+also return `url`, so the SDK types it as optional. A button URL can contain a
+signer access or verification value; treat it as a credential and never log it.
+
+## Webhook delivery
+
+Assinafy sends webhook events as HTTP `POST` JSON requests with
+`Connection: close`. Any `2xx` is successful. There are at most two automatic
+attempts per event with a three-second wait. After ten consecutive failed
+events, ordinary delivery pauses and about 5% of later events are attempted
+until one succeeds. `webhooks.retryDispatch()` requests immediate redelivery.
+Only the first 2,000 characters of the receiver response body are retained in
+dispatch history.
+
+The common body contains `id`, `event`, nullable `message`, nullable `payload`,
+nullable `origin`, Unix-second `created_at`, polymorphic `subject` and `object`,
+and `account_id`. Use `id` for idempotent handling and accept unknown fields.
+
+## Webhook signature verification is not in the OpenAPI contract
+
+The official webhook operations define subscription management, event types,
+delivery history, and retry. They do not define a shared-secret field,
+signature algorithm, digest encoding, or signature header for incoming events.
+
+`client.webhookVerifier` is an opt-in HMAC-SHA256 utility for environments whose
+separate Assinafy agreement provides a shared secret and hex digest. Confirm the
+header name and signing procedure for the target environment before enforcing
+it. Do not assume an `X-Assinafy-Signature` header solely from this SDK.
+
+## Authentication isolation
+
+Public documents, login and social login, password reset, OAuth URLs, and
+signer-access-code flows use a separate HTTP transport without `X-Api-Key` or
+`Authorization` defaults. A credentialless `new AssinafyClient()` can drive
+those flows, and credentials configured for protected resources are not sent.
+
+Protected methods use the authenticated transport and receive the API's normal
+`401` response when credentials are absent or invalid. The authenticated
+transport accepts same-origin absolute URLs, rejects cross-origin requests
+before dispatch, and treats credentials as redirect-sensitive. Use a separate
+HTTP client for unrelated origins.
+
+## Authenticated-user response variants
+
+`GET /users/self` officially returns `AuthUser` directly. Some sandbox
+deployments return `{ user, accounts }` and add `user.is_password_set`.
+`users.getCurrent()` normalizes both forms to `IAuthenticatedUser`, where
+`is_password_set` is optional.