@assinafy/sdk 1.4.0 → 1.5.0

package/dist/index.d.ts

@@ -34,6 +34,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 +75,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`. */
@@ -131,23 +140,56 @@ interface ICreateAssignmentPayload {
     /** 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 +197,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 +259,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;
@@ -206,7 +291,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 +300,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 +321,7 @@ interface IDocumentDetailsResponse {
     resource?: string;
     id: string;
     account_id: string;
+    template_id?: string | null;
     name: string;
     status: DocumentStatus;
     assignment: IAssignment | null;
@@ -253,7 +341,7 @@ interface IDocumentDetailsResponse {
     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 +388,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,13 +407,16 @@ 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 {
@@ -372,8 +463,18 @@ 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;
@@ -613,7 +714,7 @@ declare abstract class BaseResource {
 }
 type RequestFn = () => Promise<AxiosResponse>;
 
-/** Input for uploading a document: either an on-disk file or an in-memory buffer. */
+/** Input for an upload: either an on-disk file or an in-memory buffer. */
 type DocumentUploadSource = {
     filePath: string;
     fileName?: string;
@@ -621,6 +722,7 @@ type DocumentUploadSource = {
     buffer: Buffer;
     fileName: string;
 };
+
 interface IDocumentUploadOptions {
     /** Optional metadata sent alongside the file (JSON-encoded). */
     metadata?: Record<string, unknown>;
@@ -684,8 +786,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>>;
     /**
@@ -756,8 +863,16 @@ declare function buildAssignmentPayload(payload: ICreateAssignmentPayload, optio
 declare class AssignmentResource extends BaseResource {
     /** 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,22 +880,40 @@ 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>;
@@ -797,20 +930,55 @@ 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.
+     * Unlike the list endpoint, the single-template response includes `pages`
+     * (with per-page `download_url`) and `default_document_tags`.
      */
     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>;
 }
@@ -990,14 +1158,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 +1210,7 @@ interface ClientConfigInput {
     webhook_secret?: string;
     webhookSecret?: string;
     timeout?: number;
+    maxRetries?: number;
     logger?: Logger;
 }
 /**
@@ -1120,4 +1294,4 @@ declare class NetworkError extends AssinafyError {
     });
 }
 
-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 { 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 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 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 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, NetworkError, type PaginatedResult, type PaginationMeta, type SendTokenChannel, SignerDocumentsResource, type SignerReference, SignerResource, TagResource, TemplateResource, ValidationError, type WebhookEventType, WebhookResource, WebhookVerifier, WorkspaceResource, buildAssignmentPayload };