@assinafy/sdk 1.4.0 → 2.0.0

package/dist/index.d.ts

@@ -4,12 +4,26 @@ import { AxiosInstance, AxiosResponse } from 'axios';
 type DocumentStatus = 'uploading' | 'uploaded' | 'metadata_processing' | 'metadata_ready' | 'pending_signature' | 'expired' | 'certificating' | 'certificated' | 'rejected_by_signer' | 'rejected_by_user' | 'failed';
 /** Artifact names available for document download. */
 type DocumentArtifactName = 'original' | 'certificated' | 'certificate-page' | 'bundle';
+/**
+ * Any string, while keeping editor autocomplete for the literals it is unioned
+ * with.
+ *
+ * `'Email' | 'Whatsapp' | string` collapses to plain `string`, so the literals
+ * vanish from autocomplete. `'Email' | 'Whatsapp' | AnyString` keeps them
+ * suggested while staying assignable from any string, so a value the API adds
+ * later still type-checks.
+ *
+ * This deliberately does **not** reject unknown strings — these fields mirror
+ * server-controlled vocabularies, so forward-compatibility is worth more than
+ * rejecting a typo at compile time.
+ */
+type AnyString = string & {};
 /** Assignment methods supported by the API. */
 type AssignmentMethod = 'virtual' | 'collect';
 /** Verification methods accepted by assignment signer entries. */
-type AssignmentVerificationMethod = 'Email' | 'Whatsapp' | string;
+type AssignmentVerificationMethod = 'Email' | 'Whatsapp' | AnyString;
 /** Notification methods accepted by assignment signer entries. */
-type AssignmentNotificationMethod = 'Email' | 'Whatsapp' | string;
+type AssignmentNotificationMethod = 'Email' | 'Whatsapp' | AnyString;
 /** Minimal logger contract (compatible with console, pino, winston, etc.). */
 interface Logger {
     debug: (message: string, context?: Record<string, unknown>) => void;
@@ -34,6 +48,11 @@ interface AssinafyClientOptions {
     webhookSecret?: string;
     /** Request timeout in milliseconds. Defaults to 30_000. */
     timeout?: number;
+    /**
+     * Max automatic retries on HTTP 429 (rate limit), honoring `Retry-After`.
+     * Defaults to `2`. Set to `0` to disable retrying.
+     */
+    maxRetries?: number;
     /** Optional logger. Defaults to a no-op logger. */
     logger?: Logger;
 }
@@ -70,6 +89,10 @@ interface ISigner {
     full_name: string;
     email: string | null;
     whatsapp_phone_number?: string | null;
+    /**
+     * Accepted on create/update payloads but **never echoed back** on any signer
+     * response — present here only so response objects stay assignable from inputs.
+     */
     cpf?: string | null;
     has_accepted_terms?: boolean;
     /** Only returned by `GET /signers/self`. */
@@ -127,27 +150,74 @@ interface ICreateAssignmentPayload {
     signerIds?: string[];
     message?: string;
     expires_at?: string;
+    /**
+     * Recipients CC'd on the signature request.
+     *
+     * ⚠️ Observed to be **silently dropped** on the sandbox plan: values sent
+     * here came back as `[]` from `assignments.create`, `assignments.list` and
+     * `documents.details().assignment` alike, for both email addresses and
+     * signer IDs. The field is accepted (no error) but nothing is persisted.
+     *
+     * It is retained because this was verified on a single sandbox account and
+     * may be plan-gated — the WhatsApp channel on the same account is rejected
+     * with an explicit plan error, so silent no-ops for un-provisioned features
+     * are plausible. **Do not rely on it without verifying against your own
+     * account**, and do not treat a CC as delivered.
+     */
     copy_receivers?: string[];
     /** Field placement entries used when `method` is `collect`. */
     entries?: unknown[];
 }
+/** A signer as embedded inside an assignment (richer than the bare {@link ISigner}). */
+interface IAssignmentSigner extends ISigner {
+    completed: boolean;
+    notification_history: unknown[];
+    verification_method: AssignmentVerificationMethod;
+    notification_methods: AssignmentNotificationMethod[];
+    /** 1-based signing order. See {@link SignerReference.step}. */
+    step: number;
+    notified: boolean;
+}
+/** A placed field/item within an assignment (one row per signer × field). */
+interface IAssignmentItem {
+    id: string;
+    page: {
+        id: string;
+        number: number;
+        height: number;
+        width: number;
+        download_url: string;
+    } | null;
+    signer: ISigner;
+    field: IFieldDefinition;
+    value: string | null;
+    completed?: boolean;
+    [key: string]: unknown;
+}
 /** Assignment object as returned by the API. */
 interface IAssignment {
+    resource?: string;
     id: string;
     sender_email?: string;
     method: AssignmentMethod;
-    expires_at?: string;
+    expires_at?: string | null;
     expiration?: string;
     message?: string;
-    signers: ISigner[];
+    signers: IAssignmentSigner[];
     copy_receivers?: string[];
-    items?: unknown[];
+    items?: IAssignmentItem[];
     summary?: {
         signer_count: number;
         completed_count: number;
-        signers: unknown[];
+        signers: Array<ISigner & {
+            completed?: boolean;
+        }>;
     };
-    signing_urls?: Record<string, string>;
+    /** Per-signer signing URLs. Array of `{ signer_id, url }` (not a map). */
+    signing_urls?: Array<{
+        signer_id: string;
+        url: string;
+    }>;
 }
 type ICreateAssignmentResponse = IAssignment;
 interface IResendEmailResponse {
@@ -155,6 +225,41 @@ interface IResendEmailResponse {
     document_id?: string;
     signer_id?: string;
 }
+/**
+ * Credit/document cost estimate returned by `assignments.estimateCost` and
+ * `documents.estimateCostFromTemplate`.
+ */
+interface ICostEstimate {
+    documents: number;
+    credits: number;
+    needs_extra_document: boolean;
+    extra_document_cost: number;
+    total_credits: number;
+    breakdown: Array<{
+        code: string;
+        name: string;
+        cost: number;
+        quantity?: number;
+        unit_cost?: number;
+    }>;
+    document_balance: number;
+    credit_balance: number;
+    has_sufficient_resources: boolean;
+    /** `null` when the operation can proceed; otherwise a reason code. */
+    blocking_reason: string | null;
+    message: string | null;
+}
+/** Cost estimate returned by `assignments.estimateResendCost`. */
+interface IResendCostEstimate {
+    total: number;
+    breakdown: Array<{
+        code: string;
+        name: string;
+        cost: number;
+    }>;
+    credit_balance: number;
+    has_sufficient_credits: boolean;
+}
 /** Webhook payload envelope. */
 interface IWebhookPayload {
     id?: number;
@@ -182,6 +287,14 @@ interface IDocumentListItem {
     status: DocumentStatus;
     account_id?: string;
     template_id?: string | null;
+    /** Artifact download URLs keyed by name (`original`, `thumbnail`, …). */
+    artifacts?: IDocumentUploadResponse['artifacts'];
+    /** Public signing-portal URL for the document. */
+    signing_url?: string;
+    pages?: IDocumentUploadResponse['pages'];
+    assignment?: IAssignment | null;
+    decline_reason?: string | null;
+    declined_by?: ISigner | null;
     /** Tags attached to the document (inline `{ id, name, color }` shape). */
     tags?: IInlineTag[];
     created_at: string;
@@ -192,12 +305,44 @@ type IDocumentListResponse = PaginatedResult<IDocumentListItem>;
 /** Query parameters accepted by `documents.list`. */
 interface IDocumentListParams extends IListParams {
     /** Filter by document status, e.g. `pending_signature`. */
-    status?: DocumentStatus | string;
+    status?: DocumentStatus | AnyString;
     /** Filter by signature method (`virtual` or `collect`). */
     method?: AssignmentMethod;
     /** Comma-separated list of tag IDs (AND semantics). */
     tags?: string;
 }
+/**
+ * Response of `documents.rename` (`PATCH /documents/{documentId}`).
+ *
+ * The rename endpoint returns the document **without** `pages` or
+ * `assignment` — verified against the live API, which echoes only
+ * `resource`, `id`, `account_id`, `template_id`, `name`, `status`,
+ * `artifacts`, `signing_url`, `is_closed`, `decline_reason`, `declined_by`,
+ * `tags`, `created_at` and `updated_at`. Typing it as a full
+ * {@link IDocumentDetailsResponse} would promise a required `pages` array that
+ * is absent at runtime, so `result.pages.length` would throw.
+ */
+type IRenameDocumentResponse = Omit<IDocumentDetailsResponse, 'pages' | 'assignment'>;
+/** Query parameters accepted by `documents.search`. */
+interface IDocumentSearchParams extends IListParams {
+    /** Free-text term matched against the document name. */
+    search?: string;
+    /** Filter by document status, e.g. `pending_signature`. */
+    status?: DocumentStatus | AnyString;
+    /** Page number (1-based). */
+    page?: number;
+    /** Results per page. */
+    'per-page'?: number;
+}
+/** Query parameters accepted by `assignments.list`. */
+interface IAssignmentListParams extends IListParams {
+    /** Page number (1-based). */
+    page?: number;
+    /** Results per page. */
+    'per-page'?: number;
+}
+/** Paginated result of `assignments.list`. */
+type IAssignmentListResponse = PaginatedResult<IAssignment>;
 /** Document upload response. */
 interface IDocumentUploadResponse {
     resource?: string;
@@ -206,7 +351,8 @@ interface IDocumentUploadResponse {
     template_id: string | null;
     name: string;
     status: DocumentStatus;
-    assignment: unknown;
+    /** Absent on a fresh upload; an {@link IAssignment} (or `null`) once one exists. */
+    assignment?: IAssignment | null;
     artifacts: {
         original: string;
         certificated?: string;
@@ -214,6 +360,7 @@ interface IDocumentUploadResponse {
         bundle?: string;
         thumbnail?: string;
     };
+    /** Empty (`[]`) on fresh upload (status `uploaded`); populated once `metadata_ready`. */
     pages: Array<{
         id: string;
         number: number;
@@ -234,6 +381,7 @@ interface IDocumentDetailsResponse {
     resource?: string;
     id: string;
     account_id: string;
+    template_id?: string | null;
     name: string;
     status: DocumentStatus;
     assignment: IAssignment | null;
@@ -247,13 +395,14 @@ interface IDocumentDetailsResponse {
         bundle?: string;
         thumbnail?: string;
     };
-    pages: unknown[];
+    /** Rendered pages. Empty until the document reaches `metadata_ready`. */
+    pages: IPage[];
     /** Tags attached to the document (inline `{ id, name, color }` shape). */
     tags?: IInlineTag[];
     created_at: string;
     updated_at: string;
     is_closed: boolean;
-    decline_reason?: string;
+    decline_reason?: string | null;
     declined_by?: ISigner | null;
     activities?: Array<IDocumentActivity>;
 }
@@ -300,8 +449,8 @@ interface IUpdateWorkspacePayload {
 interface IWorkspaceResponse {
     id: string;
     name: string;
-    primary_color?: string;
-    secondary_color?: string;
+    primary_color?: string | null;
+    secondary_color?: string | null;
     created_at: string;
 }
 interface IWorkspaceListItem {
@@ -319,22 +468,25 @@ interface IWebhookRegisterPayload {
     events?: WebhookEventType[] | string[];
     is_active?: boolean;
 }
+/**
+ * Webhook subscription as returned by the API. There is exactly one
+ * subscription per workspace, keyed by URL — the API returns
+ * `{ events, is_active, url, email, updated_at }` (no `id` / `created_at`).
+ */
 interface IWebhookSubscription {
-    id?: string;
     url: string;
     email: string;
     events: string[];
     is_active: boolean;
-    created_at?: string;
     updated_at?: string;
 }
 interface IWebhookEventTypeInfo {
-    id: WebhookEventType | string;
+    id: WebhookEventType | AnyString;
     description: string;
 }
 interface IWebhookDispatch {
     id: string;
-    event: WebhookEventType | string;
+    event: WebhookEventType | AnyString;
     activity_id: number;
     endpoint: string | null;
     payload: IWebhookPayload | Record<string, unknown> | null;
@@ -342,11 +494,13 @@ interface IWebhookDispatch {
     http_status: number | null;
     response_body: string | null;
     error: string | null;
-    created_at: number;
-    updated_at?: number;
+    /** ISO-8601 UTC timestamp, e.g. `'2026-07-15T20:04:36Z'`. */
+    created_at: string;
+    /** ISO-8601 UTC timestamp, e.g. `'2026-07-15T20:04:36Z'`. */
+    updated_at?: string;
 }
 interface IWebhookDispatchListParams extends IListParams {
-    event?: WebhookEventType | string;
+    event?: WebhookEventType | AnyString;
     delivered?: boolean | 'true' | 'false';
     from?: number;
     to?: number;
@@ -372,17 +526,33 @@ interface IUploadAndRequestSignaturesSigner {
 interface ITemplateRole {
     id: string;
     name: string;
+    /** Role kind, e.g. `Editor` or `Signer`. */
+    assignment_type?: string;
+    created_at?: string;
+    updated_at?: string;
     [key: string]: unknown;
 }
+/** Payload for `PUT /accounts/{id}/templates/{template_id}`. Omit a field to leave it unchanged. */
+interface IUpdateTemplatePayload {
+    name?: string;
+    /** Default invitation message applied to documents created from the template. */
+    message?: string;
+}
 /** Template list item (paginated). */
 interface ITemplateListItem {
-    resource?: string;
     id: string;
     name: string;
     document_name?: string | null;
     message?: string | null;
     status: string;
-    account_id?: string;
+    /**
+     * Rendered pages, each with a `download_url`. Empty until the template
+     * finishes processing (`status: 'Ready'`).
+     *
+     * The list endpoint does return `pages` — contrary to what
+     * `templates.get`'s documentation implies.
+     */
+    pages?: IPage[];
     roles?: ITemplateRole[];
     /** Tags attached to the template itself (inline `{ id, name }` shape). */
     tags?: IInlineTag[];
@@ -391,6 +561,38 @@ interface ITemplateListItem {
 }
 type ITemplateListResponse = PaginatedResult<ITemplateListItem>;
 /** Full template details. */
+/**
+ * A rendered page of a document or template.
+ *
+ * `download_url` is an absolute, API-key-authenticated URL for the page's JPEG
+ * rendering — the same bytes returned by `templates.downloadPage()` /
+ * `documents.downloadPage()`.
+ *
+ * @example
+ * ```jsonc
+ * {
+ *   "id": "e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
+ *   "number": 1,
+ *   "height": 1651,
+ *   "width": 1275,
+ *   "download_url": "https://api.assinafy.com.br/v1/accounts/…/pages/…/download",
+ *   "fields": []
+ * }
+ * ```
+ */
+interface IPage {
+    id: string;
+    /** 1-based page number. */
+    number: number;
+    /** Rendered height in pixels (150 DPI). */
+    height: number;
+    /** Rendered width in pixels (150 DPI). */
+    width: number;
+    /** Absolute URL of the page's JPEG rendering. */
+    download_url?: string;
+    /** Fields positioned on this page. Present on templates; absent on documents. */
+    fields?: unknown[];
+}
 interface ITemplateDetailsResponse {
     resource?: string;
     id: string;
@@ -398,8 +600,8 @@ interface ITemplateDetailsResponse {
     document_name?: string | null;
     message?: string | null;
     status: string;
-    account_id?: string;
-    pages?: unknown[];
+    /** Empty until the template finishes processing (`status: 'Ready'`). */
+    pages?: IPage[];
     roles?: ITemplateRole[];
     /** Tags attached to the template itself. */
     tags?: IInlineTag[];
@@ -437,7 +639,7 @@ interface ICreateDocumentFromTemplateOptions {
  * is documented in the table but is not currently present in the JSON payload.
  */
 interface IDocumentStatusInfo {
-    code: DocumentStatus | string;
+    code: DocumentStatus | AnyString;
     deletable: boolean;
     description?: string;
 }
@@ -451,7 +653,7 @@ interface IPublicDocumentInfo {
     [key: string]: unknown;
 }
 /** Channel accepted by the `send-token` endpoint. */
-type SendTokenChannel = 'email' | 'whatsapp' | string;
+type SendTokenChannel = 'email' | 'whatsapp' | AnyString;
 /** Authentication: login response (also returned by social login). */
 interface ILoginResponse {
     access_token: string;
@@ -579,6 +781,17 @@ interface IUpdateTagPayload {
     color?: string | null;
 }
 
+/** Maximum upload size accepted by the API (hard limit, 25 MB). */
+declare const MAX_UPLOAD_BYTES: number;
+/** Input for an upload: either an on-disk file or an in-memory buffer. */
+type DocumentUploadSource = {
+    filePath: string;
+    fileName?: string;
+} | {
+    buffer: Buffer;
+    fileName: string;
+};
+
 /**
  * Shared plumbing for every Assinafy resource:
  *
@@ -608,20 +821,43 @@ declare abstract class BaseResource {
     protected callVoid(label: string, request: RequestFn): Promise<void>;
     /** Execute an HTTP call that returns binary data (artifact downloads). */
     protected callBinary(label: string, request: () => Promise<AxiosResponse<ArrayBuffer>>): Promise<Buffer>;
+    /**
+     * Upload a PDF as `multipart/form-data` and assert the API echoed an id.
+     *
+     * Shared by `documents.upload` and `templates.create`, which are the same
+     * sequence over different paths: load → validate → build form → POST →
+     * assert an id came back. Callers keep their own success logging.
+     *
+     * @param path - Account-scoped endpoint to POST to.
+     * @param source - The PDF, as a file path or in-memory buffer.
+     * @param formOptions - `name` (display name) and optional `metadata`.
+     * @param labels - `errorLabel` for the request failure, `missingId` for a
+     * `2xx` that returned no id.
+     */
+    protected uploadPdf<T extends {
+        id?: string;
+    }>(path: string, source: DocumentUploadSource, formOptions: {
+        name?: string;
+        metadata?: Record<string, unknown>;
+    }, labels: {
+        errorLabel: string;
+        missingId: string;
+    }): Promise<T>;
     /** Execute a paginated list call and attach meta from `X-Pagination-*` headers. */
     protected callList<T>(label: string, request: RequestFn): Promise<PaginatedResult<T>>;
 }
 type RequestFn = () => Promise<AxiosResponse>;
 
-/** Input for uploading a document: either an on-disk file or an in-memory buffer. */
-type DocumentUploadSource = {
-    filePath: string;
-    fileName?: string;
-} | {
-    buffer: Buffer;
-    fileName: string;
-};
+/** Options accepted by {@link DocumentResource.upload}. */
 interface IDocumentUploadOptions {
+    /**
+     * Display name for the document. Defaults to the uploaded file's own name.
+     *
+     * `.pdf` is appended when absent, so `'Service agreement'` is stored as
+     * `'Service agreement.pdf'`. Accents are transliterated by the API
+     * (`'Contrato de Serviço'` → `'Contrato de Servico.pdf'`).
+     */
+    name?: string;
     /** Optional metadata sent alongside the file (JSON-encoded). */
     metadata?: Record<string, unknown>;
     /** Override the default account ID configured on the client. */
@@ -629,20 +865,119 @@ interface IDocumentUploadOptions {
 }
 declare class DocumentResource extends BaseResource {
     /**
-     * Upload a PDF to the workspace.
+     * Upload a PDF to the workspace (`POST /accounts/{accountId}/documents`).
+     *
+     * The document is created in `metadata_processing` status and becomes
+     * usable once it reaches `metadata_ready`; use
+     * {@link DocumentResource.waitUntilReady} to await that transition. Note
+     * that {@link DocumentResource.rename} and {@link DocumentResource.delete}
+     * return `400` while the document is still processing.
+     *
+     * @param source - The PDF to upload, as a file path or an in-memory buffer.
+     * @param options - Display name, metadata, and account override.
+     * @returns The created document. Response shape:
+     * ```jsonc
+     * {
+     *   "resource": "document",
+     *   "id": "c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
+     *   "name": "Service agreement.pdf",
+     *   "status": "metadata_processing",
+     *   "created_at": "2026-07-15T16:15:33Z",
+     *   "updated_at": "2026-07-15T16:15:33Z"
+     * }
+     * ```
+     * @throws {ValidationError} If the file is empty, not a `.pdf`, exceeds
+     * 25 MB, or the API returns no document ID.
+     * @throws {ApiError} If the API rejects the upload.
      *
      * @example
      * ```ts
      * await client.documents.upload({ filePath: './contract.pdf' });
-     * await client.documents.upload({ buffer, fileName: 'contract.pdf' }, { metadata });
+     * await client.documents.upload(
+     *   { buffer, fileName: 'contract.pdf' },
+     *   { name: 'Service agreement', metadata: { orderId: 'A-1' } },
+     * );
+     * // → name is stored as 'Service agreement.pdf'
      * ```
      */
     upload(source: DocumentUploadSource, options?: IDocumentUploadOptions): Promise<IDocumentUploadResponse>;
     /**
      * List workspace documents. Pagination info (if any) is attached in `meta`.
-     * Supports `status`, `method`, `tags`, `search`, `sort`, `page`, `per_page`.
+     * Supports `status`, `method`, `tags`, `search`, `sort`, `page`, `per-page`.
      */
     list(params?: IDocumentListParams, accountId?: string): Promise<IDocumentListResponse>;
+    /**
+     * Search workspace documents
+     * (`GET /accounts/{accountId}/documents/search`).
+     *
+     * A lighter-weight alternative to {@link DocumentResource.list}: it returns
+     * a compact representation with no expanded `assignment` or `pages`, so
+     * prefer it for name lookups and pickers.
+     *
+     * @param params - `search`, `status`, `page`, `per-page`.
+     * @param accountId - Override the client's default account ID.
+     * @returns Matching documents, with pagination in `meta`. Each item:
+     * ```jsonc
+     * {
+     *   "id": "c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
+     *   "account_id": "d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
+     *   "template_id": null,
+     *   "name": "Service agreement.pdf",
+     *   "status": "pending_signature",
+     *   "artifacts": { "original": "https://…" },
+     *   "is_closed": false,
+     *   "signing_url": "https://…",
+     *   "decline_reason": null,
+     *   "declined_by": null,
+     *   "tags": [],
+     *   "created_at": "2026-07-15T16:15:33Z",
+     *   "updated_at": "2026-07-15T16:15:40Z"
+     * }
+     * ```
+     * @throws {ValidationError} If no account ID is available.
+     * @throws {ApiError} If the API rejects the request.
+     *
+     * @example
+     * ```ts
+     * const { data, meta } = await client.documents.search({
+     *   search: 'agreement',
+     *   status: 'pending_signature',
+     *   'per-page': 20,
+     * });
+     * ```
+     */
+    search(params?: IDocumentSearchParams, accountId?: string): Promise<IDocumentListResponse>;
+    /**
+     * Rename a document (`PATCH /documents/{documentId}`).
+     *
+     * Only valid while the document is still renameable: the API returns `400`
+     * ("Document cannot be renamed after the signature process has started")
+     * both once signing has begun **and** while the document is still in
+     * `metadata_processing` immediately after upload. Await
+     * {@link DocumentResource.waitUntilReady} before renaming a fresh upload.
+     *
+     * To set a name at upload time instead, pass `name` to
+     * {@link DocumentResource.upload} — that avoids the extra round-trip and
+     * the processing race entirely.
+     *
+     * @param documentId - The document to rename.
+     * @param name - The new display name (max 255 chars), e.g.
+     * `'Service agreement.pdf'`.
+     * @returns The updated document — **without** `pages` or `assignment`,
+     * which this endpoint does not return (unlike
+     * {@link DocumentResource.details}). Call `details()` if you need them.
+     * @throws {ValidationError} If `documentId` or `name` is missing.
+     * @throws {ApiError} `400` if the document is processing or already in
+     * signing; `404` if it does not exist.
+     *
+     * @example
+     * ```ts
+     * const doc = await client.documents.upload({ filePath: './c.pdf' });
+     * await client.documents.waitUntilReady(doc.id);   // else 400
+     * await client.documents.rename(doc.id, 'Service agreement.pdf');
+     * ```
+     */
+    rename(documentId: string, name: string): Promise<IRenameDocumentResponse>;
     /** Get document details. */
     details(documentId: string): Promise<IDocumentDetailsResponse>;
     /** Alias for {@link details}. */
@@ -684,8 +1019,13 @@ declare class DocumentResource extends BaseResource {
      * ```
      */
     createFromTemplate(templateId: string, signers: ITemplateSigner[], options?: ICreateDocumentFromTemplateOptions, accountId?: string): Promise<IDocumentDetailsResponse>;
-    /** Estimate the credit cost of creating a document from a template. */
-    estimateCostFromTemplate(templateId: string, signers: ITemplateSigner[], accountId?: string): Promise<Record<string, unknown>>;
+    /**
+     * Estimate the credit cost of creating a document from a template.
+     *
+     * @returns an {@link ICostEstimate}: `total_credits`, balances, and a
+     * per-line `breakdown` of what the operation would consume.
+     */
+    estimateCostFromTemplate(templateId: string, signers: ITemplateSigner[], accountId?: string): Promise<ICostEstimate>;
     /** Verify a document by its signature hash. */
     verify(hash: string): Promise<Record<string, unknown>>;
     /**
@@ -722,13 +1062,30 @@ declare class SignerResource extends BaseResource {
     create(payload: ICreateSignerPayload, accountId?: string): Promise<ICreateSignerResponse>;
     /** Get a signer by ID. */
     get(signerId: string, accountId?: string): Promise<ISigner>;
-    /** List signers for the workspace (supports `page`, `per_page`, `search`, `sort`). */
+    /** List signers for the workspace (supports `page`, `per-page`, `search`, `sort`). */
     list(params?: IListParams, accountId?: string): Promise<ISignerListResponse>;
     /** Update a signer. Fails if the signer has active assignments. */
     update(signerId: string, payload: IUpdateSignerPayload, accountId?: string): Promise<ICreateSignerResponse>;
     /** Delete a signer. */
     delete(signerId: string, accountId?: string): Promise<void>;
-    /** Find a signer by email via the API's `search` parameter. Returns `null` if none match. */
+    /**
+     * Find a signer by exact email, using the API's `search` filter to narrow
+     * the page first. Returns `null` if none match.
+     *
+     * `search` is a substring match across signer fields, so the result is
+     * re-filtered here for an exact, case-insensitive email match.
+     *
+     * Page size is pinned to the API's maximum of 50: larger values are
+     * silently clamped to 50 by the server, so asking for more is misleading.
+     * An exact address realistically matches one signer, but a search term that
+     * matched more than 50 could in principle miss one — the API exposes no
+     * exact-email filter to rule that out.
+     *
+     * @param email - Exact email address to look for.
+     * @param accountId - Override the client's default account ID.
+     * @returns The matching {@link ISigner}, or `null`.
+     * @throws {ValidationError} If `email` is not a valid address.
+     */
     findByEmail(email: string, accountId?: string): Promise<ISigner | null>;
     private assertEmail;
 }
@@ -754,10 +1111,62 @@ declare function buildAssignmentPayload(payload: ICreateAssignmentPayload, optio
     allowSignersWithoutId?: boolean;
 }): Record<string, unknown>;
 declare class AssignmentResource extends BaseResource {
+    /**
+     * List assignments across the workspace (`GET /assignments`).
+     *
+     * The account is passed as an `accountId` **query parameter** — the API
+     * responds `400` ("Um contexto de conta é necessário e não foi fornecido")
+     * without it. Note the camelCase spelling: `account_id` and an
+     * `X-Account-Id` header are both rejected.
+     *
+     * @param params - `page`, `per-page`.
+     * @param accountId - Override the client's default account ID.
+     * @returns Assignments, with pagination in `meta`. Each item:
+     * ```jsonc
+     * {
+     *   "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4",
+     *   "sender_email": "sender@example.com",
+     *   "method": "virtual",
+     *   "expires_at": null,
+     *   "message": "Please sign this contract",
+     *   "signers": [
+     *     {
+     *       "id": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5",
+     *       "full_name": "Ana Souza",
+     *       "email": "signer@example.com",
+     *       "whatsapp_phone_number": null,
+     *       "has_accepted_terms": false,
+     *       "completed": false,
+     *       "notification_history": [],
+     *       "verification_method": "Email",
+     *       "notification_methods": ["Email"],
+     *       "step": 1,
+     *       "notified": true
+     *     }
+     *   ]
+     * }
+     * ```
+     * @throws {ValidationError} If no account ID is available.
+     * @throws {ApiError} If the API rejects the request.
+     *
+     * @example
+     * ```ts
+     * const { data, meta } = await client.assignments.list({ 'per-page': 20 });
+     * ```
+     */
+    list(params?: IAssignmentListParams, accountId?: string): Promise<IAssignmentListResponse>;
     /** Create a signing assignment for a document. */
     create(documentId: string, payload: ICreateAssignmentPayload): Promise<ICreateAssignmentResponse>;
-    /** Estimate the cost (in credits) of creating the assignment. */
-    estimateCost(documentId: string, payload: ICreateAssignmentPayload): Promise<Record<string, unknown>>;
+    /**
+     * Estimate the cost (in credits/documents) of creating the assignment.
+     *
+     * Signer entries may omit `id` and supply only `verification_method` /
+     * `notification_methods` when only the channel mix matters for the estimate.
+     *
+     * @returns an {@link ICostEstimate} with `total_credits`, balances, and a
+     * line-item `breakdown`.
+     */
+    estimateCost(documentId: string, payload: ICreateAssignmentPayload): Promise<ICostEstimate>;
     /**
      * Update the expiration date of an existing assignment.
      * Pass `null` to remove the expiration entirely.
@@ -765,28 +1174,51 @@ declare class AssignmentResource extends BaseResource {
     resetExpiration(documentId: string, assignmentId: string, expiresAt: string | null): Promise<IAssignment>;
     /** Resend the signing notification to a single signer. */
     resendNotification(documentId: string, assignmentId: string, signerId: string): Promise<IResendEmailResponse>;
-    /** Estimate the cost of resending a signer notification. */
-    estimateResendCost(documentId: string, assignmentId: string, signerId: string): Promise<Record<string, unknown>>;
+    /**
+     * Estimate the cost of resending a signer notification.
+     *
+     * @returns an {@link IResendCostEstimate} (`total`, `breakdown`, balances).
+     */
+    estimateResendCost(documentId: string, assignmentId: string, signerId: string): Promise<IResendCostEstimate>;
     /**
      * `GET /documents/{documentId}/assignments/{assignmentId}/whatsapp-notifications`
      * — list every WhatsApp notification rendered + sent for an assignment.
      */
     listWhatsAppNotifications(documentId: string, assignmentId: string): Promise<IWhatsAppNotification[]>;
-    /**
-     * Cancel a signature request. This endpoint is not listed in the public
-     * Swagger but is exposed by the platform.
-     */
-    cancel(documentId: string, reason: string, accountId?: string): Promise<unknown>;
 }
 
+/**
+ * Default webhook events applied by {@link WebhookResource.register} when the
+ * caller omits `events` (or passes an empty array).
+ */
+declare const DEFAULT_WEBHOOK_EVENTS: WebhookEventType[];
 declare class WebhookResource extends BaseResource {
-    /** Register (or replace) the webhook subscription for the workspace. */
+    /**
+     * Register (or replace) the workspace's single webhook subscription
+     * (`PUT /accounts/{id}/webhooks/subscriptions`). There is exactly one
+     * subscription per workspace, keyed by URL.
+     *
+     * When `events` is omitted or empty, {@link DEFAULT_WEBHOOK_EVENTS} is used
+     * (`document_ready`, `document_prepared`, `signer_signed_document`,
+     * `signer_rejected_document`, `document_processing_failed`).
+     *
+     * @example
+     * ```ts
+     * await client.webhooks.register({ url: 'https://example.com/hook', email: 'ops@example.com' });
+     * // → { url, email, events: [...], is_active: true, updated_at: '2026-…' }
+     * ```
+     */
     register(payload: IWebhookRegisterPayload, accountId?: string): Promise<IWebhookSubscription>;
     /** Fetch the current webhook subscription. Returns `null` if none exists. */
     get(accountId?: string): Promise<IWebhookSubscription | null>;
-    /** Delete the current webhook subscription. */
-    delete(accountId?: string): Promise<void>;
-    /** Inactivate the current webhook subscription without deleting it. */
+    /**
+     * Inactivate the current webhook subscription.
+     *
+     * This is the only supported way to stop deliveries — the API has no
+     * subscription-delete route. The subscription is retained (with its `url`
+     * and `events`) and simply stops firing; re-enable it by calling
+     * {@link WebhookResource.register} again with `is_active: true`.
+     */
     inactivate(accountId?: string): Promise<IWebhookSubscription>;
     /** List currently supported webhook event types. */
     listEventTypes(): Promise<IWebhookEventTypeInfo[]>;
@@ -797,20 +1229,58 @@ declare class WebhookResource extends BaseResource {
 }
 
 declare class TemplateResource extends BaseResource {
+    /**
+     * Create a template by uploading a PDF (`POST /accounts/{id}/templates`).
+     *
+     * The template is created in `Uploaded` status and transitions to `Ready`
+     * once the platform finishes processing its pages. Configure roles/fields
+     * afterwards in the Assinafy editor.
+     *
+     * @example
+     * ```ts
+     * const tmpl = await client.templates.create(
+     *   { filePath: './nda.pdf' },
+     *   { name: 'NDA template' },
+     * );
+     * // → { resource: 'template', id, name, status: 'Uploaded',
+     * //     roles: [{ id, name: 'TemplateEditor', assignment_type: 'Editor' }],
+     * //     pages: [], tags: [], created_at, updated_at }
+     * ```
+     */
+    create(source: DocumentUploadSource, options?: {
+        name?: string;
+        accountId?: string;
+    }): Promise<ITemplateDetailsResponse>;
     /** List templates for the workspace. */
     list(params?: IListParams, accountId?: string): Promise<ITemplateListResponse>;
     /**
-     * Get a template by ID.
+     * Get a template by ID (`GET /accounts/{id}/templates/{template_id}`).
      *
-     * Note: the swagger only documents the list endpoint; this single-resource
-     * `GET /accounts/{id}/templates/{id}` is exposed by the platform and used
-     * by the official PHP SDK.
+     * Returns the same shape as {@link TemplateResource.list} plus
+     * `default_document_tags` (the tags auto-applied to every document created
+     * from this template) and `resource`. Both endpoints return `pages` with
+     * per-page `download_url`, so fetching a template again purely to read its
+     * pages is unnecessary.
      */
     get(templateId: string, accountId?: string): Promise<ITemplateDetailsResponse>;
     /**
-     * `GET /accounts/{id}/templates/{template_id}/pages/{page_id}/download` —
-     * download a template page as a JPEG (used by template editors to render
-     * thumbnails on the client).
+     * Update a template's `name` and/or default `message`
+     * (`PUT /accounts/{id}/templates/{template_id}`). Returns the updated template.
+     *
+     * @example
+     * ```ts
+     * await client.templates.update(templateId, { name: 'NDA v2', message: 'Please sign' });
+     * ```
+     */
+    update(templateId: string, payload: IUpdateTemplatePayload, accountId?: string): Promise<ITemplateDetailsResponse>;
+    /** Delete a template (`DELETE /accounts/{id}/templates/{template_id}`). */
+    delete(templateId: string, accountId?: string): Promise<void>;
+    /**
+     * Download a template page as a JPEG
+     * (`GET /accounts/{id}/templates/{template_id}/pages/{page_id}/download`).
+     *
+     * Used by template editors to render page thumbnails on the client. The
+     * matching `download_url` is also returned on each `template.pages[]` entry.
      */
     downloadPage(templateId: string, pageId: string, accountId?: string): Promise<Buffer>;
 }
@@ -959,6 +1429,34 @@ declare class SignerDocumentsResource extends BaseResource {
     getCurrent(signerId: string, signerAccessCode: string): Promise<IDocumentDetailsResponse>;
     /** `GET /signers/{signer_id}/documents?signer-access-code=…` */
     list(signerId: string, signerAccessCode: string, params?: IListParams): Promise<IDocumentListResponse>;
+    /**
+     * Search the documents awaiting a given signer
+     * (`GET /signers/{signer_id}/documents/search?signer-access-code=…`).
+     *
+     * The signer-side counterpart of {@link DocumentResource.search}, scoped to
+     * one signer and authorised by their access code rather than the API key.
+     * Like {@link SignerDocumentsResource.list}, it requires
+     * `signer-access-code`; the published spec omits that parameter, but the
+     * endpoint is not usable without it.
+     *
+     * @param signerId - The signer whose documents are searched.
+     * @param signerAccessCode - The signer's access code, from their signing link.
+     * @param search - Free-text term matched against the document name.
+     * @returns Matching documents for that signer, in the compact
+     * {@link IDocumentListItem} shape, with pagination in `meta`.
+     * @throws {ValidationError} If `signerId` or `signerAccessCode` is missing.
+     * @throws {ApiError} If the access code is invalid or expired.
+     *
+     * @example
+     * ```ts
+     * const { data } = await client.signerDocuments.search(
+     *   signerId,
+     *   accessCode,
+     *   'agreement',
+     * );
+     * ```
+     */
+    search(signerId: string, signerAccessCode: string, search?: string): Promise<IDocumentListResponse>;
     /** `GET /signers/{signer_id}/documents/{document_id}/download/{artifact}?signer-access-code=…` */
     download(signerId: string, documentId: string, artifactName: DocumentArtifactName, signerAccessCode: string): Promise<Buffer>;
     /** `PUT /signers/documents/sign-multiple?signer-access-code=…` */
@@ -990,14 +1488,19 @@ declare class SignerDocumentsResource extends BaseResource {
     }): Promise<unknown>;
     /** `GET /signature/{type}?signer-access-code=…` — download the signer's signature/initial. */
     downloadSignature(signerAccessCode: string, imageType?: 'signature' | 'initial'): Promise<Buffer>;
-    /** `GET /sign?signer-access-code=…` — fetch the assignment as the signer sees it. */
+    /**
+     * `GET /sign?signer-access-code=…` — fetch the assignment as the signer sees it.
+     *
+     * @param hasAcceptedTerms maps to the `has_accepted_terms` query param
+     *   (server default `false`); pass `true` once the signer has accepted terms.
+     */
     getAssignment(signerAccessCode: string, hasAcceptedTerms?: boolean): Promise<unknown>;
     /** `POST /documents/{documentId}/assignments/{assignmentId}?signer-access-code=…` — sign. */
     sign(documentId: string, assignmentId: string, signerAccessCode: string, entries: ISignFieldEntry[]): Promise<unknown>;
     /**
      * `PUT /documents/{documentId}/assignments/{assignmentId}/reject?signer-access-code=…`
-     * — signer-side decline. (Distinct from `assignments.cancel`, which is the
-     * workspace-side cancellation flow.)
+     * — signer-side decline. (The workspace-side equivalent is to delete the
+     * document via `documents.delete`; there is no workspace "cancel" endpoint.)
      */
     decline(documentId: string, assignmentId: string, signerAccessCode: string, declineReason: string): Promise<unknown>;
 }
@@ -1037,6 +1540,7 @@ interface ClientConfigInput {
     webhook_secret?: string;
     webhookSecret?: string;
     timeout?: number;
+    maxRetries?: number;
     logger?: Logger;
 }
 /**
@@ -1095,17 +1599,13 @@ declare class AssinafyClient {
 /** Base class for all Assinafy SDK errors. */
 declare class AssinafyError extends Error {
     readonly context: Record<string, unknown>;
-    constructor(message: string, context?: Record<string, unknown>, options?: {
-        cause?: unknown;
-    });
+    constructor(message: string, context?: Record<string, unknown>, options?: ErrorOptions);
 }
 /** Thrown when the API returns a non-success HTTP status. */
 declare class ApiError extends AssinafyError {
     readonly statusCode: number;
     readonly responseData: unknown;
-    constructor(message: string, statusCode: number, responseData?: unknown, options?: {
-        cause?: unknown;
-    });
+    constructor(message: string, statusCode: number, responseData?: unknown, options?: ErrorOptions);
     static fromResponse(statusCode: number, responseData: unknown): ApiError;
 }
 /** Thrown when client-side validation fails before the request is sent. */
@@ -1115,9 +1615,7 @@ declare class ValidationError extends AssinafyError {
 }
 /** Thrown when the HTTP transport itself fails (DNS, timeout, etc.). */
 declare class NetworkError extends AssinafyError {
-    constructor(message: string, options?: {
-        cause?: unknown;
-    });
+    constructor(message: string, options?: ErrorOptions);
 }
 
-export { ApiError, type AssignmentMethod, type AssignmentNotificationMethod, AssignmentResource, type AssignmentVerificationMethod, AssinafyClient, type AssinafyClientOptions, AssinafyError, AuthenticationResource, type ClientConfigInput, type DocumentArtifactName, DocumentResource, type DocumentStatus, type DocumentUploadSource, FieldsResource, type IApiKeyResponse, type IAssignment, type ICreateAssignmentPayload, type ICreateAssignmentResponse, type ICreateDocumentFromTemplateOptions, type ICreateFieldPayload, type ICreateSignerPayload, type ICreateSignerResponse, type ICreateTagPayload, type ICreateWorkspacePayload, type IDocumentActivity, type IDocumentDetailsResponse, type IDocumentListItem, type IDocumentListParams, type IDocumentListResponse, type IDocumentStatusInfo, type IDocumentUploadOptions, type IDocumentUploadResponse, type IFieldDefinition, type IFieldType, type IFieldValidateMultipleEntry, type IFieldValidationResult, type IInlineTag, type IListParams, type ILoginResponse, type IMaskedApiKeyResponse, type IPaginatedResponse, type IPublicDocumentInfo, type IResendEmailResponse, type ISignFieldEntry, type ISigner, type ISignerListResponse, type ISigningProgress, type ITag, type ITemplateDetailsResponse, type ITemplateListItem, type ITemplateListResponse, type ITemplateRole, type ITemplateSigner, type IUpdateFieldPayload, type IUpdateSignerPayload, type IUpdateTagPayload, type IUpdateWorkspacePayload, type IUploadAndRequestSignaturesResult, type IUploadAndRequestSignaturesSigner, type IWebhookDispatch, type IWebhookDispatchListParams, type IWebhookEventTypeInfo, type IWebhookPayload, type IWebhookRegisterPayload, type IWebhookSubscription, type IWhatsAppNotification, type IWorkspaceListItem, type IWorkspaceListResponse, type IWorkspaceResponse, type Logger, NetworkError, type PaginatedResult, type PaginationMeta, type SendTokenChannel, SignerDocumentsResource, type SignerReference, SignerResource, TagResource, TemplateResource, ValidationError, type WebhookEventType, WebhookResource, WebhookVerifier, WorkspaceResource, buildAssignmentPayload };
+export { type AnyString, ApiError, type AssignmentMethod, type AssignmentNotificationMethod, AssignmentResource, type AssignmentVerificationMethod, AssinafyClient, type AssinafyClientOptions, AssinafyError, AuthenticationResource, type ClientConfigInput, DEFAULT_WEBHOOK_EVENTS, type DocumentArtifactName, DocumentResource, type DocumentStatus, type DocumentUploadSource, FieldsResource, type IApiKeyResponse, type IAssignment, type IAssignmentItem, type IAssignmentListParams, type IAssignmentListResponse, type IAssignmentSigner, type ICostEstimate, type ICreateAssignmentPayload, type ICreateAssignmentResponse, type ICreateDocumentFromTemplateOptions, type ICreateFieldPayload, type ICreateSignerPayload, type ICreateSignerResponse, type ICreateTagPayload, type ICreateWorkspacePayload, type IDocumentActivity, type IDocumentDetailsResponse, type IDocumentListItem, type IDocumentListParams, type IDocumentListResponse, type IDocumentSearchParams, type IDocumentStatusInfo, type IDocumentUploadOptions, type IDocumentUploadResponse, type IFieldDefinition, type IFieldType, type IFieldValidateMultipleEntry, type IFieldValidationResult, type IInlineTag, type IListParams, type ILoginResponse, type IMaskedApiKeyResponse, type IPage, type IPaginatedResponse, type IPublicDocumentInfo, type IRenameDocumentResponse, type IResendCostEstimate, type IResendEmailResponse, type ISignFieldEntry, type ISigner, type ISignerListResponse, type ISigningProgress, type ITag, type ITemplateDetailsResponse, type ITemplateListItem, type ITemplateListResponse, type ITemplateRole, type ITemplateSigner, type IUpdateFieldPayload, type IUpdateSignerPayload, type IUpdateTagPayload, type IUpdateTemplatePayload, type IUpdateWorkspacePayload, type IUploadAndRequestSignaturesResult, type IUploadAndRequestSignaturesSigner, type IWebhookDispatch, type IWebhookDispatchListParams, type IWebhookEventTypeInfo, type IWebhookPayload, type IWebhookRegisterPayload, type IWebhookSubscription, type IWhatsAppNotification, type IWorkspaceListItem, type IWorkspaceListResponse, type IWorkspaceResponse, type Logger, MAX_UPLOAD_BYTES, NetworkError, type PaginatedResult, type PaginationMeta, type SendTokenChannel, SignerDocumentsResource, type SignerReference, SignerResource, TagResource, TemplateResource, ValidationError, type WebhookEventType, WebhookResource, WebhookVerifier, WorkspaceResource, buildAssignmentPayload };