@assinafy/sdk 2.0.0 → 2.1.1

package/docs/API_COVERAGE.md

@@ -0,0 +1,209 @@
+# API coverage
+
+This ledger maps the official Assinafy OpenAPI document to the public SDK API.
+It was reconciled on 2026-08-06 against
+[`GET /v1/docs/openapi.json`](https://api.assinafy.com.br/v1/docs/openapi.json):
+68 paths, 89 HTTP operations, and 37 component schemas. The audited response's
+SHA-256 digest is
+`7e5957082002e8e96c5abc2cadf7b4b463eaa5bd61b76e26f64b90a8b922088c`.
+
+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.
+- **URL helper** — the operation is a browser redirect/callback; the SDK builds
+  its absolute URL instead of following it inside the server process.
+- **Live extension** — verified route retained for compatibility, 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 — 11/11
+
+| Method | Path | SDK method | Status |
+| --- | --- | --- | --- |
+| `GET` | `/v1/auth/authenticate` | `client.auth.getSocialLoginUrl(authClient?)` | URL helper |
+| `GET` | `/v1/login-callback` | `client.auth.getSocialLoginCallbackUrl()` | URL helper |
+| `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 live routes are documented separately under
+[Live template extensions](#live-template-extensions).
+
+## Users — 2/2
+
+| Method | Path | SDK method | Status |
+| --- | --- | --- | --- |
+| `GET` | `/v1/users/self` | `client.users.getCurrent()` | Covered |
+| `GET` | `/v1/users/self/stats` | `client.users.getStats(params?)` | 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 |
+
+## Live template extensions
+
+These routes are available in the live API and covered by the SDK, but they do
+not appear in the 2026-08-06 OpenAPI path set. They are intentionally excluded
+from the official 89-operation coverage count.
+
+| Method | Live path | SDK method | Status |
+| --- | --- | --- | --- |
+| `POST` | `/v1/accounts/{accountId}/templates` | `client.templates.create(source, options?)` | Live extension |
+| `GET` | `/v1/accounts/{accountId}/templates/{templateId}` | `client.templates.get(templateId, accountId?)` | Live extension |
+| `PUT` | `/v1/accounts/{accountId}/templates/{templateId}` | `client.templates.update(templateId, payload, accountId?)` | Live extension |
+| `DELETE` | `/v1/accounts/{accountId}/templates/{templateId}` | `client.templates.delete(templateId, accountId?)` | Live extension |
+| `GET` | `/v1/accounts/{accountId}/templates/{templateId}/pages/{pageId}/download` | `client.templates.downloadPage(templateId, pageId, accountId?)` | Live 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, waits for metadata readiness, reuses or creates signers,
+  creates an assignment, and optionally fetches the final document snapshot.
+- `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). Contract
+differences that require compatibility handling are recorded in
+[COMPATIBILITY.md](COMPATIBILITY.md).

package/docs/COMPATIBILITY.md

@@ -0,0 +1,285 @@
+# API compatibility
+
+The SDK targets the official Assinafy contract at
+[`/v1/docs/openapi.json`](https://api.assinafy.com.br/v1/docs/openapi.json) and
+keeps compatibility behavior narrow, explicit, and typed. This document records
+the differences observed during the 2026-08-06 contract and sandbox audit. It
+contains no credentials, account identifiers, signer data, or reusable test
+artifacts. The audited OpenAPI response's SHA-256 digest is
+`7e5957082002e8e96c5abc2cadf7b4b463eaa5bd61b76e26f64b90a8b922088c`.
+
+The governing rule is simple: new integrations should send the published
+contract. A compatibility path is used only when the caller selects it
+explicitly or the server returns a validation error that unambiguously requests
+the older shape.
+
+## Template management live extensions
+
+The current OpenAPI document contains only:
+
+```text
+GET /v1/accounts/{accountId}/templates
+```
+
+The live API additionally exposes five routes used by existing integrations:
+
+```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 `client.templates.create`, `get`, `update`, `delete`, and
+`downloadPage`. They are documented and tested as **live compatibility
+extensions**, not counted as official OpenAPI operations. Their absence from a
+future schema is not by itself grounds for removal; removal requires a live
+regression test, a deprecation period, and a major-version decision.
+
+Template status examples have also differed in casing (`Uploaded`/`Ready` in
+live extension responses versus `uploaded`/`ready` in the published schema).
+The exported type intentionally remains `string`. Applications should normalize
+before comparing:
+
+```ts
+if (template.status.toLowerCase() === 'ready') {
+  // rendered pages are available
+}
+```
+
+## Public send-token request
+
+The official operation is:
+
+```http
+PUT /v1/public/documents/{documentId}/send-token
+Content-Type: application/json
+
+{ "email": "signer@example.com" }
+```
+
+That is the default SDK call:
+
+```ts
+await client.documents.sendToken(documentId, 'signer@example.com');
+```
+
+Some older environments 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 API's validation body specifically says that
+`recipient` or `channel` is required. Unrelated errors are never swallowed or
+retried under this compatibility rule.
+
+## Document tag identifiers
+
+The current OpenAPI request schemas for replacing and attaching document tags
+define `tags` as an array of existing **tag IDs**. The SDK follows that contract:
+
+```ts
+const tag = await client.tags.create({ name: 'Contracts' });
+await client.documents.addTags(documentId, [tag.id]);
+await client.documents.replaceTags(documentId, [tag.id]);
+```
+
+Older environments have accepted tag names and auto-created unknown names. The
+wire type remains `string[]` so those deployments are not broken, but name-based
+attachment is a legacy extension and is not the documented default. Production
+code should create/list tags first and submit IDs.
+
+## Account branding fields on create and update
+
+The official `Account` response schema includes `primary_color` and
+`secondary_color`, while the current create/update request schemas list only
+`name` and `notification_sender_type`. The sandbox also accepts the two color
+fields on create/update, and the SDK preserves them for existing integrations.
+They must be six hexadecimal characters without a leading `#`.
+
+The sandbox audited on 2026-08-06 rejects the official optional
+`notification_sender_type` field with `400` on account creation, while accepting
+the same field on update. The SDK still exposes and sends it because it is part
+of the production OpenAPI contract. The live audit creates its prerequisite
+workspace with a name only, then tests the field independently via update so
+the create-side deployment lag cannot prevent the rest of the suite.
+
+The branding read and file operations—`getTheme`, `downloadLogo`, `uploadLogo`,
+and `deleteLogo`—are official operations and are not extensions.
+
+## Field-definition request extensions
+
+The official field-create body defines `type`, `name`, nullable `regex`, and
+`is_required`; the update body defines `name`, nullable `regex`, and
+`is_active`. The audited sandbox also accepts `is_active` on create and
+`type`/`is_required` on update. Those three properties remain typed as explicit
+live extensions so existing integrations keep working. New code should prefer
+the operation-specific official fields.
+
+The field-validation schemas also omit the `signer-access-code` query parameter
+accepted by signer-portal deployments. `fields.validate` and `validateMultiple`
+retain the typed `signerAccessCode` option for those deployments. The 2026-08-06
+full audit exercised account-authenticated validation; it did not have the
+signer-code fixture needed to re-certify this compatibility query.
+
+## Retained signer request compatibility
+
+The current signer create/update schemas use `full_name`, `email`, and
+`whatsapp_phone_number`. The SDK also retains three older integration inputs:
+
+- `phone` is a client-only alias normalized to `whatsapp_phone_number` before
+  transmission;
+- `cpf` is normalized to digits and forwarded; and
+- create-time `metadata` is forwarded unchanged.
+
+These inputs remain source-compatible because removing them without a live
+regression would break existing consumers. They were unit/request-contract
+tested but were not separately re-probed in the 2026-08-06 disposable signer
+matrix, so new integrations should prefer only the published fields.
+
+The official signer `confirm-data` body contains only `full_name`, `email`, and
+`government_id`. Its primary overload exposes exactly those fields. A deprecated
+compatibility overload retains `whatsapp_phone_number`, which was not live-
+certified in this audit. It also preserves the pre-audit `has_accepted_terms`
+pass-through because that behavior could not be live-tested with the supplied
+fixtures. This field is outside the current contract and must **not** be treated
+as legal consent or as a substitute for the separate official `acceptTerms()`
+request. Production signer UIs should call `acceptTerms()` explicitly.
+
+## Signature-image media type
+
+`POST /signature` officially accepts a raw `image/png` body. That is the SDK's
+typed/default request and the only media type claimed by the API contract. The
+deprecated `contentType` compatibility overload is retained so older consumers
+are not silently broken, but non-PNG values were not live-certified because the
+provided audit fixtures contained no signer access code or legal-consent flow.
+Do not use the override in new integrations without verifying the target
+deployment.
+
+## Document upload metadata
+
+The multipart upload schema documents the PDF file but not the SDK's optional
+JSON `metadata` part. The audited sandbox accepted and processed a disposable
+document carrying metadata on 2026-08-06. The option remains an explicit live
+extension; callers should treat metadata keys and values as application-owned,
+opaque JSON.
+
+## Reset-expiration null and public signer-download compatibility
+
+The reset-expiration schema declares `expires_at` as a date-time string. The SDK
+retains `null` as a compatibility value used by older integrations to clear an
+expiration, but the full live audit tested only a future timestamp; `null` is
+unit/request-contract tested and remains live-unverified.
+
+The signer artifact download is the opposite case: OpenAPI explicitly marks it
+public and defines no `signer-access-code` query. The official three-argument SDK
+call therefore sends no code. An optional fourth code remains available for
+older deployments, but it is a compatibility query rather than part of the
+published operation.
+
+## Resend-cost response variants
+
+The published
+`POST /documents/{documentId}/assignments/{assignmentId}/signers/{signerId}/estimate-resend-cost`
+response references the full `CostEstimate` schema. A smaller resend-specific
+shape has also been observed live. The SDK therefore returns the honest union
+`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 synthesize missing fields, so callers never mistake invented
+zeroes for server-provided balances.
+
+## Public-document response variants
+
+The official `GET /public/documents/{documentId}` response references the full
+`Document` schema. Older public responses can be compact and expose only fields
+such as `id`, `name`, `page_count`, and `created_by`. `IPublicDocumentInfo`
+requires the stable `id` and `name`, makes expanded document fields optional,
+and retains the compact fields. Check optional fields before using them:
+
+```ts
+const document = await client.documents.getPublic(documentId);
+if (document.pages) {
+  console.log(document.pages.length);
+} else {
+  console.log(Number(document.page_count ?? 0));
+}
+```
+
+## Empty acknowledgements
+
+Several write operations return a successful status/message envelope with no
+`data` field, while a few older responses use an empty array or object. Methods
+whose contract has no meaningful result resolve to `Promise<void>` and validate
+the HTTP/envelope status. This applies to token dispatch, signer OTP/terms,
+signature-image upload, bulk signer actions, and deletion operations. Success is
+not represented as a fabricated object.
+
+## Webhook signature verification is not in the OpenAPI contract
+
+The official webhook operations define subscription management, event types,
+delivery history, and retry. The current OpenAPI document does **not** define a
+shared-secret field, signature algorithm, digest encoding, or signature header
+for incoming deliveries.
+
+`client.webhookVerifier` is retained as an opt-in HMAC-SHA256 utility for
+environments whose separate Assinafy agreement provides a shared secret and a
+hex digest. Confirm the header name and signing procedure with Assinafy for the
+target environment before enforcing it. Do not assume an
+`X-Assinafy-Signature` header solely from this SDK.
+
+## Authentication isolation
+
+Public documents, login/social login, password-reset, OAuth URL, and
+signer-access-code flows use a separate HTTP transport without `X-Api-Key` or
+`Authorization` defaults. This is a security boundary rather than a
+wire-contract deviation: a credentialless `new AssinafyClient()` can drive
+those flows, and credentials configured for protected resources are not leaked
+to them.
+
+Protected methods still use the authenticated transport and receive the API's
+normal `401` response if credentials are absent or invalid.
+
+## Sandbox user and statistics deployment lag
+
+The current OpenAPI schema defines `GET /users/self` as a direct `AuthUser`
+payload. The sandbox audited on 2026-08-06 still wraps that value as
+`{ user, accounts }` and adds `user.is_password_set`. `users.getCurrent()`
+normalizes both forms to `IAuthenticatedUser`; `is_password_set` is an optional
+live-compatibility field.
+
+The same sandbox returns `404` for the official `GET /users/self/stats` and
+`GET /accounts/{accountId}/stats` routes. The production host recognizes both
+routes (an unauthenticated probe receives `401`), so the SDK retains the exact
+published paths and types. The live audit reports those sandbox-only `404`s as
+explicit `SKIP`s rather than claiming they passed or rewriting calls to an
+undocumented route.
+
+## Updating this record
+
+When the upstream API changes:
+
+1. Diff the new official OpenAPI paths and schemas against the snapshot date
+   above.
+2. Add or update typed methods and request/response tests.
+3. Verify live-only behavior in the sandbox without logging secrets or tokens.
+4. Update [API_COVERAGE.md](API_COVERAGE.md) and this file in the same change.
+5. Keep compatibility behavior isolated and feature-detectable; do not silently
+   broaden retries or coerce malformed success payloads.

package/docs/RELEASING.md

@@ -0,0 +1,138 @@
+# Releasing
+
+GitLab is the canonical repository and push-mirrors branches and tags to
+GitHub. Publishing is performed by `.github/workflows/release.yml` when GitHub
+receives a tag matching `v*`; a mirrored tag does not create a GitHub `release`
+event, and the workflow intentionally does not depend on one.
+
+## Release support matrix
+
+| Runtime | Release responsibility |
+| --- | --- |
+| Bun 1.3.14 | Locked install, tests, build, audit, and packaging |
+| Node.js 22 | Minimum supported consumer runtime |
+| Node.js 24 LTS | Packaging and registry publishing runtime |
+| Node.js 26 Current | Forward-compatibility consumer test |
+
+Keep this table, `package.json`, GitLab CI, and the GitHub workflows synchronized
+when changing runtime support.
+
+## One-time registry setup
+
+### npm trusted publishing
+
+Configure the npm package `@assinafy/sdk` with a GitHub Actions trusted
+publisher using these repository coordinates:
+
+| npm setting | Value |
+| --- | --- |
+| Organization or user | `assinafy` |
+| Repository | `typescript-sdk` |
+| Workflow filename | `release.yml` |
+| Environment | Leave unset unless the workflow is updated to use one |
+
+The `publish-npm` job grants only `contents: read` and `id-token: write`.
+Modern npm exchanges GitHub's short-lived OIDC identity for publish credentials;
+no long-lived `NPM_TOKEN` is required. Test trusted publishing before deleting a
+legacy token, then remove that token from repository and organization secrets.
+
+### GitHub Packages
+
+The `publish-gh` job uses the workflow-scoped `GITHUB_TOKEN` with
+`packages: write`. Confirm that organization policy permits Actions to publish
+the `@assinafy` scope and that the package remains linked to this repository.
+No separate personal access token should be stored.
+
+### Mirror and tag protection
+
+The GitLab push mirror must include tags and be able to update the GitHub
+repository. Protect release tags in GitLab so only release maintainers can
+create patterns matching `v*`. GitHub Actions must be enabled on the mirror.
+
+## Preparing a release
+
+1. Merge the complete change through GitLab and confirm both GitLab and mirrored
+   GitHub CI are green.
+2. Choose the semantic version and update `package.json`. Keep the tag exactly
+   `v<package-version>`; the workflow rejects a mismatch.
+3. Update `CHANGELOG.md`, API coverage, compatibility notes, and public examples
+   for all user-visible changes.
+4. Install and run the complete local release gate from a clean checkout:
+
+   ```sh
+   bun install --frozen-lockfile
+   bun run verify
+   bun run audit
+   bun run audit:api
+   ```
+
+5. For API changes, run the live audit against a dedicated sandbox. Start
+   read-only:
+
+   ```sh
+   ASSINAFY_API_KEY='...' \
+   ASSINAFY_ACCOUNT_ID='...' \
+   ASSINAFY_BASE_URL='https://sandbox.assinafy.com.br/v1' \
+   bun scripts/live-smoke.ts
+   ```
+
+   Then run the reversible suite with two controlled recipients:
+
+   ```sh
+   ASSINAFY_API_KEY='...' \
+   ASSINAFY_ACCOUNT_ID='...' \
+   ASSINAFY_BASE_URL='https://sandbox.assinafy.com.br/v1' \
+   ASSINAFY_TEST_EMAIL_PRIMARY='first@example.com' \
+   ASSINAFY_TEST_EMAIL_SECONDARY='second@example.com' \
+   bun scripts/live-smoke.ts --all
+   ```
+
+   The suite creates and force-deletes a disposable workspace, but an
+   interrupted process can still leave fixtures behind; inspect the sandbox
+   before releasing. Treat every `FAIL` as a release blocker and review each
+   `SKIP` to confirm its password, provider-token, signer-code/OTP, legal-action,
+   final-artifact, or webhook-receiver prerequisite was intentionally absent.
+   Never use production credentials or uncontrolled recipients.
+
+6. Commit the version and release notes, merge them to the canonical default
+   branch, then create a signed or annotated `v<version>` tag on that exact
+   commit and push the tag to GitLab.
+7. Confirm that the tag reaches GitHub and starts the **Release** workflow. Do
+   not create or move a second tag to work around mirror delay.
+
+## What the workflow publishes
+
+The workflow serializes releases repository-wide and performs these steps:
+
+1. verify that the tag and `package.json` versions match;
+2. install from `bun.lock`, run `verify` and `audit`, and build once;
+3. create one `.tgz` with lifecycle scripts disabled and record its SHA-256;
+4. upload that archive and checksum as a one-day workflow artifact;
+5. verify and publish the archive to npm through trusted-publisher OIDC; and
+6. verify and publish the **same bytes** to GitHub Packages using
+   `GITHUB_TOKEN`.
+
+The GitHub Packages job depends on npm publishing, preventing a GitHub-only
+release when npm fails. Both registry jobs validate `SHA256SUMS`; neither
+rebuilds or repacks the SDK. This immutable-artifact flow is part of the release
+contract and must be preserved when editing the workflow.
+
+## Verification and recovery
+
+After publishing, confirm that the expected version appears on npm and GitHub
+Packages and that a clean Node.js consumer can import both the ESM and CommonJS
+entrypoints. Compare the downloaded artifacts when registry tooling permits.
+
+If packaging or npm publishing fails, fix the source, increment or retain the
+version as registry state allows, and create a new tag only after review. Never
+move a tag that has published a package.
+
+If npm succeeds and GitHub Packages fails, rerun only the failed job while the
+original one-day workflow artifact is retained. This preserves the exact
+archive already published to npm. Do not repack an approximation or unpublish a
+released npm version. If the artifact has expired, stop and review recovery with
+the maintainers before changing workflow dependencies or registry state.
+
+For a defective published release, prefer deprecating the affected version and
+shipping a reviewed patch. Record the incident and remediation in the
+changelog and any applicable security advisory.