@assinafy/sdk 1.4.0

package/dist/index.d.ts

@@ -0,0 +1,1123 @@
+import { AxiosInstance, AxiosResponse } from 'axios';
+
+/** Document lifecycle states emitted by the API. */
+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';
+/** Assignment methods supported by the API. */
+type AssignmentMethod = 'virtual' | 'collect';
+/** Verification methods accepted by assignment signer entries. */
+type AssignmentVerificationMethod = 'Email' | 'Whatsapp' | string;
+/** Notification methods accepted by assignment signer entries. */
+type AssignmentNotificationMethod = 'Email' | 'Whatsapp' | string;
+/** Minimal logger contract (compatible with console, pino, winston, etc.). */
+interface Logger {
+    debug: (message: string, context?: Record<string, unknown>) => void;
+    info: (message: string, context?: Record<string, unknown>) => void;
+    warn: (message: string, context?: Record<string, unknown>) => void;
+    error: (message: string, context?: Record<string, unknown>) => void;
+}
+/** Client configuration options. */
+interface AssinafyClientOptions {
+    /** Assinafy API key. Preferred authentication method (sends `X-Api-Key` header). */
+    apiKey?: string;
+    /**
+     * Legacy access token. If provided (and `apiKey` is not), the client will send
+     * `Authorization: Bearer <token>` instead. Kept for backwards compatibility.
+     */
+    token?: string;
+    /** Default account (workspace) ID applied to account-scoped endpoints. */
+    accountId?: string;
+    /** Override the API base URL. Defaults to https://api.assinafy.com.br/v1. */
+    baseUrl?: string;
+    /** Secret used to verify webhook payload signatures (HMAC-SHA256). */
+    webhookSecret?: string;
+    /** Request timeout in milliseconds. Defaults to 30_000. */
+    timeout?: number;
+    /** Optional logger. Defaults to a no-op logger. */
+    logger?: Logger;
+}
+/**
+ * Payload for creating a signer.
+ *
+ * `email` is optional: the API accepts a signer with only a
+ * `whatsapp_phone_number`. At least one of the two must be supplied.
+ */
+interface ICreateSignerPayload {
+    full_name: string;
+    email?: string;
+    whatsapp_phone_number?: string;
+    /** PHP SDK compatibility alias for `whatsapp_phone_number`. */
+    phone?: string;
+    /** Brazilian tax ID (CPF). Non-digits are stripped before sending. */
+    cpf?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Payload for updating a signer. */
+interface IUpdateSignerPayload {
+    full_name?: string;
+    email?: string;
+    whatsapp_phone_number?: string;
+    /** PHP SDK compatibility alias for `whatsapp_phone_number`. */
+    phone?: string;
+    /** Brazilian tax ID (CPF). Non-digits are stripped before sending. */
+    cpf?: string;
+}
+/** Signer object as returned by the API. */
+interface ISigner {
+    resource?: string;
+    id: string;
+    full_name: string;
+    email: string | null;
+    whatsapp_phone_number?: string | null;
+    cpf?: string | null;
+    has_accepted_terms?: boolean;
+    /** Only returned by `GET /signers/self`. */
+    has_signature?: boolean;
+    /** Only returned by `GET /signers/self`. */
+    has_initial?: boolean;
+    metadata?: Record<string, unknown>;
+}
+type ICreateSignerResponse = ISigner;
+/** Pagination metadata extracted from `X-Pagination-*` response headers. */
+interface PaginationMeta {
+    current_page?: number;
+    last_page?: number;
+    per_page?: number;
+    total?: number;
+}
+/** Shape returned by every paginated list call in the SDK. */
+interface PaginatedResult<T> {
+    data: T[];
+    meta?: PaginationMeta;
+}
+/** @deprecated use {@link PaginatedResult} — retained for existing type imports. */
+type IPaginatedResponse<T> = PaginatedResult<T>;
+type ISignerListResponse = PaginatedResult<ISigner>;
+/** Signer reference accepted by the assignment endpoints. */
+type SignerReference = string | {
+    id?: string;
+    signer_id?: string;
+    verification_method?: AssignmentVerificationMethod;
+    notification_methods?: AssignmentNotificationMethod[];
+    /**
+     * Positive integer controlling signing order. Signers sharing a step
+     * sign in parallel; a step is activated (and its signers notified)
+     * only after every signer in the previous step has signed. If supplied
+     * for one signer it must be supplied for all, forming a contiguous
+     * sequence starting at 1.
+     */
+    step?: number;
+};
+/** Payload for creating an assignment. */
+interface ICreateAssignmentPayload {
+    method?: AssignmentMethod;
+    /**
+     * List of signers. Each entry may be a signer id string, or an object with
+     * `id` / `signer_id`. For cost estimation, entries may omit the ID and
+     * specify only `verification_method` / `notification_methods`.
+     *
+     * The SDK normalises them to the docs-sanctioned `signers: [{ ... }]`
+     * shape before sending.
+     */
+    signers?: SignerReference[];
+    /** Legacy field still accepted by the API docs and used by the PHP SDK. */
+    signer_ids?: string[];
+    /** Camel-case legacy alias used by the quick-start docs. */
+    signerIds?: string[];
+    message?: string;
+    expires_at?: string;
+    copy_receivers?: string[];
+    /** Field placement entries used when `method` is `collect`. */
+    entries?: unknown[];
+}
+/** Assignment object as returned by the API. */
+interface IAssignment {
+    id: string;
+    sender_email?: string;
+    method: AssignmentMethod;
+    expires_at?: string;
+    expiration?: string;
+    message?: string;
+    signers: ISigner[];
+    copy_receivers?: string[];
+    items?: unknown[];
+    summary?: {
+        signer_count: number;
+        completed_count: number;
+        signers: unknown[];
+    };
+    signing_urls?: Record<string, string>;
+}
+type ICreateAssignmentResponse = IAssignment;
+interface IResendEmailResponse {
+    is_sent?: boolean;
+    document_id?: string;
+    signer_id?: string;
+}
+/** Webhook payload envelope. */
+interface IWebhookPayload {
+    id?: number;
+    event?: string;
+    type?: string;
+    message?: string | null;
+    payload?: Record<string, unknown> | null;
+    origin?: Record<string, unknown> | null;
+    subject?: Record<string, unknown>;
+    object?: Record<string, unknown>;
+    account_id?: string;
+    data?: {
+        document_uuid?: string;
+        document_id?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/** Known webhook event names. */
+type WebhookEventType = 'document_uploaded' | 'document_metadata_ready' | 'document_prepared' | 'assignment_created' | 'document_ready' | 'signature_requested' | 'signer_created' | 'signer_email_verified' | 'signer_whatsapp_verified' | 'signer_data_confirmed' | 'signer_viewed_document' | 'signer_signed_document' | 'signer_rejected_document' | 'user_rejected_document' | 'document_processing_failed' | 'template_created' | 'template_processed' | 'template_processing_failed';
+/** Document listing item (paginated). */
+interface IDocumentListItem {
+    id: string;
+    name: string;
+    status: DocumentStatus;
+    account_id?: string;
+    template_id?: string | null;
+    /** Tags attached to the document (inline `{ id, name, color }` shape). */
+    tags?: IInlineTag[];
+    created_at: string;
+    updated_at?: string;
+    is_closed?: boolean;
+}
+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;
+    /** Filter by signature method (`virtual` or `collect`). */
+    method?: AssignmentMethod;
+    /** Comma-separated list of tag IDs (AND semantics). */
+    tags?: string;
+}
+/** Document upload response. */
+interface IDocumentUploadResponse {
+    resource?: string;
+    id: string;
+    account_id: string;
+    template_id: string | null;
+    name: string;
+    status: DocumentStatus;
+    assignment: unknown;
+    artifacts: {
+        original: string;
+        certificated?: string;
+        'certificate-page'?: string;
+        bundle?: string;
+        thumbnail?: string;
+    };
+    pages: Array<{
+        id: string;
+        number: number;
+        height: number;
+        width: number;
+        download_url: string;
+    }>;
+    /** Tags attached to the document (inline `{ id, name, color }` shape). */
+    tags?: IInlineTag[];
+    created_at: string;
+    updated_at: string;
+    is_closed: boolean;
+    decline_reason: string | null;
+    declined_by: string | null;
+}
+/** Detailed document response. */
+interface IDocumentDetailsResponse {
+    resource?: string;
+    id: string;
+    account_id: string;
+    name: string;
+    status: DocumentStatus;
+    assignment: IAssignment | null;
+    download_url?: string;
+    download_final_url?: string;
+    signing_url?: string;
+    artifacts?: {
+        original: string;
+        certificated?: string;
+        'certificate-page'?: string;
+        bundle?: string;
+        thumbnail?: string;
+    };
+    pages: unknown[];
+    /** Tags attached to the document (inline `{ id, name, color }` shape). */
+    tags?: IInlineTag[];
+    created_at: string;
+    updated_at: string;
+    is_closed: boolean;
+    decline_reason?: string;
+    declined_by?: ISigner | null;
+    activities?: Array<IDocumentActivity>;
+}
+interface IDocumentActivity {
+    id: number;
+    event: string;
+    message: string;
+    /** Event-specific payload snapshot. Object for most events, occasionally `[]`. */
+    payload?: Record<string, unknown> | unknown[];
+    /** Request origin (`ip` / `user-agent`) when available; `null` for system events. */
+    origin: {
+        ip?: string;
+        'user-agent'?: string;
+    } | string | null;
+    created_at: string;
+}
+/** Progress summary returned by `documents.getSigningProgress`. */
+interface ISigningProgress {
+    signed: number;
+    total: number;
+    percentage: number;
+    pending: number;
+}
+/** Query parameters accepted by paginated list endpoints. */
+interface IListParams {
+    page?: number;
+    per_page?: number;
+    'per-page'?: number;
+    search?: string;
+    sort?: string;
+    [key: string]: string | number | boolean | undefined;
+}
+/** Workspace creation payload. */
+interface ICreateWorkspacePayload {
+    name: string;
+    primary_color?: string;
+    secondary_color?: string;
+}
+interface IUpdateWorkspacePayload {
+    name?: string;
+    primary_color?: string | null;
+    secondary_color?: string | null;
+}
+interface IWorkspaceResponse {
+    id: string;
+    name: string;
+    primary_color?: string;
+    secondary_color?: string;
+    created_at: string;
+}
+interface IWorkspaceListItem {
+    id: string;
+    name: string;
+    is_delete_allowed: boolean;
+    roles: string[];
+    created_at: string;
+}
+type IWorkspaceListResponse = PaginatedResult<IWorkspaceListItem>;
+/** Webhook subscription payload. */
+interface IWebhookRegisterPayload {
+    url: string;
+    email: string;
+    events?: WebhookEventType[] | string[];
+    is_active?: boolean;
+}
+interface IWebhookSubscription {
+    id?: string;
+    url: string;
+    email: string;
+    events: string[];
+    is_active: boolean;
+    created_at?: string;
+    updated_at?: string;
+}
+interface IWebhookEventTypeInfo {
+    id: WebhookEventType | string;
+    description: string;
+}
+interface IWebhookDispatch {
+    id: string;
+    event: WebhookEventType | string;
+    activity_id: number;
+    endpoint: string | null;
+    payload: IWebhookPayload | Record<string, unknown> | null;
+    delivered: boolean;
+    http_status: number | null;
+    response_body: string | null;
+    error: string | null;
+    created_at: number;
+    updated_at?: number;
+}
+interface IWebhookDispatchListParams extends IListParams {
+    event?: WebhookEventType | string;
+    delivered?: boolean | 'true' | 'false';
+    from?: number;
+    to?: number;
+}
+/** Shape of the high-level `uploadAndRequestSignatures` helper result. */
+interface IUploadAndRequestSignaturesResult {
+    document: IDocumentUploadResponse;
+    assignment: IAssignment;
+    signer_ids: string[];
+}
+/** Input for a signer in `uploadAndRequestSignatures`. */
+interface IUploadAndRequestSignaturesSigner {
+    name: string;
+    email?: string;
+    whatsapp_phone_number?: string;
+    /** PHP SDK compatibility alias for `whatsapp_phone_number`. */
+    phone?: string;
+    /** Brazilian tax ID (CPF). Non-digits are stripped before sending. */
+    cpf?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Template role definition. */
+interface ITemplateRole {
+    id: string;
+    name: string;
+    [key: string]: unknown;
+}
+/** Template list item (paginated). */
+interface ITemplateListItem {
+    resource?: string;
+    id: string;
+    name: string;
+    document_name?: string | null;
+    message?: string | null;
+    status: string;
+    account_id?: string;
+    roles?: ITemplateRole[];
+    /** Tags attached to the template itself (inline `{ id, name }` shape). */
+    tags?: IInlineTag[];
+    created_at: string;
+    updated_at?: string;
+}
+type ITemplateListResponse = PaginatedResult<ITemplateListItem>;
+/** Full template details. */
+interface ITemplateDetailsResponse {
+    resource?: string;
+    id: string;
+    name: string;
+    document_name?: string | null;
+    message?: string | null;
+    status: string;
+    account_id?: string;
+    pages?: unknown[];
+    roles?: ITemplateRole[];
+    /** Tags attached to the template itself. */
+    tags?: IInlineTag[];
+    /** Tags auto-applied to every document created from this template. */
+    default_document_tags?: IInlineTag[];
+    created_at: string;
+    updated_at?: string;
+    [key: string]: unknown;
+}
+/** Signer assignment for creating a document from a template. */
+interface ITemplateSigner {
+    role_id: string;
+    id: string;
+    verification_method?: string;
+    notification_methods?: string[];
+    /** Positive integer controlling signing order (see {@link SignerReference}). */
+    step?: number;
+}
+/** Options for creating a document from a template. */
+interface ICreateDocumentFromTemplateOptions {
+    name?: string;
+    message?: string;
+    expires_at?: string;
+    editor_fields?: unknown[];
+    /**
+     * Tag names to attach to the new document. Names that don't exist yet are
+     * auto-created; the template's default-document-tags are always merged in.
+     */
+    tags?: string[];
+}
+/**
+ * Item returned by `GET /documents/statuses`.
+ *
+ * The API uses `code` (the status name); we mirror that field. `description`
+ * is documented in the table but is not currently present in the JSON payload.
+ */
+interface IDocumentStatusInfo {
+    code: DocumentStatus | string;
+    deletable: boolean;
+    description?: string;
+}
+/** Item returned by `GET /public/documents/{id}`. */
+interface IPublicDocumentInfo {
+    resource?: string;
+    id: string;
+    name: string;
+    page_count?: string | number;
+    created_by?: string;
+    [key: string]: unknown;
+}
+/** Channel accepted by the `send-token` endpoint. */
+type SendTokenChannel = 'email' | 'whatsapp' | string;
+/** Authentication: login response (also returned by social login). */
+interface ILoginResponse {
+    access_token: string;
+    user: {
+        id: string;
+        name: string;
+        email: string;
+        telephone?: string;
+        government_id?: string;
+        is_email_verified?: boolean;
+        has_accepted_terms?: boolean;
+        created_at?: string;
+        to_be_deleted_at?: string | null;
+    };
+    accounts: Array<{
+        id: string;
+        name: string;
+        roles: string[];
+        is_delete_allowed: boolean;
+        created_at: string;
+    }>;
+}
+/** Authentication: API key payload returned by `POST /users/api-keys`. */
+interface IApiKeyResponse {
+    api_key: string;
+}
+/** Authentication: masked API key returned by `GET /users/api-keys` (or null when never generated). */
+type IMaskedApiKeyResponse = {
+    api_key: string;
+} | null;
+/** Field definition object. */
+interface IFieldDefinition {
+    resource?: string;
+    id: string;
+    name: string;
+    type: string;
+    regex?: string | null;
+    is_pre_defined?: boolean;
+    is_active: boolean;
+    is_required?: boolean;
+    is_standard?: boolean;
+    is_read_only?: boolean;
+    is_visible?: boolean;
+}
+/** Payload for creating a field definition. */
+interface ICreateFieldPayload {
+    type: string;
+    name: string;
+    regex?: string;
+    is_required?: boolean;
+    is_active?: boolean;
+}
+/** Payload for updating a field definition. */
+interface IUpdateFieldPayload {
+    type?: string;
+    name?: string;
+    regex?: string | null;
+    is_required?: boolean;
+    is_active?: boolean;
+}
+/** Field type description returned by `GET /field-types`. */
+interface IFieldType {
+    type: string;
+    name: string;
+}
+/** Single result returned by `POST /accounts/{id}/fields/{id}/validate`. */
+interface IFieldValidationResult {
+    type?: string;
+    field_id?: string;
+    success: boolean;
+    error_message: string;
+}
+/** Payload entry for `POST /accounts/{id}/fields/validate-multiple`. */
+interface IFieldValidateMultipleEntry {
+    field_id: string;
+    value: unknown;
+}
+/** Item returned by `GET /documents/{id}/assignments/{id}/whatsapp-notifications`. */
+interface IWhatsAppNotification {
+    sent_at: number;
+    header: string;
+    body: string;
+    buttons: Array<{
+        text: string;
+        url?: string;
+    }>;
+    phone_number: string;
+    signer_id: string;
+}
+/** Body entry for the signer-side `POST /documents/{id}/assignments/{id}` sign endpoint. */
+interface ISignFieldEntry {
+    itemId: string;
+    fieldId: string;
+    pageId: string;
+    value: string;
+}
+/**
+ * Workspace tag object. Tag names are unique per workspace (case-insensitive)
+ * and `color` is an optional 6-char hex string (without the leading `#`).
+ */
+interface ITag {
+    resource?: string;
+    id: string;
+    name: string;
+    color: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** Inline tag shape embedded inside documents/templates (`{ id, name, color? }`). */
+interface IInlineTag {
+    id: string;
+    name: string;
+    color?: string | null;
+}
+/** Payload for `POST /accounts/{id}/tags`. */
+interface ICreateTagPayload {
+    name: string;
+    /** 6-char hex color, with or without a leading `#`. Omit/`null` for none. */
+    color?: string | null;
+}
+/** Payload for `PUT /accounts/{id}/tags/{id}`. Omit a field to leave it unchanged. */
+interface IUpdateTagPayload {
+    name?: string;
+    /** Pass `null` to clear the color; omit to leave unchanged. */
+    color?: string | null;
+}
+
+/**
+ * Shared plumbing for every Assinafy resource:
+ *
+ *  - holds the axios instance, default account ID, and logger
+ *  - provides `accountId()` / `requireId()` argument guards
+ *  - wraps HTTP calls in a single `try/catch` → typed-error pipeline
+ *  - unwraps the Assinafy response envelope
+ *  - parses `X-Pagination-*` headers into a typed meta object
+ *
+ * Resources should never `try/catch` or touch the envelope directly — they call
+ * one of `call` / `callVoid` / `callBinary` / `callList` instead.
+ */
+declare abstract class BaseResource {
+    protected readonly http: AxiosInstance;
+    protected readonly defaultAccountId?: string | undefined;
+    protected readonly logger: Logger;
+    constructor(http: AxiosInstance, defaultAccountId?: string | undefined, logger?: Logger);
+    /** Resolve the effective account id, throwing if none is available. */
+    protected accountId(explicit?: string): string;
+    /** Guard required path arguments (documentId, signerId, …). */
+    protected requireId<T extends string>(value: T | undefined | null, name: string): T;
+    /** Execute an HTTP call and return the unwrapped envelope body. */
+    protected call<T>(label: string, request: RequestFn): Promise<T>;
+    /** Like {@link call} but returns `null` when the API responds with 404. */
+    protected callOptional<T>(label: string, request: RequestFn): Promise<T | null>;
+    /** Execute an HTTP call that returns no body (DELETE / 204). */
+    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>;
+    /** 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;
+};
+interface IDocumentUploadOptions {
+    /** Optional metadata sent alongside the file (JSON-encoded). */
+    metadata?: Record<string, unknown>;
+    /** Override the default account ID configured on the client. */
+    accountId?: string;
+}
+declare class DocumentResource extends BaseResource {
+    /**
+     * Upload a PDF to the workspace.
+     *
+     * @example
+     * ```ts
+     * await client.documents.upload({ filePath: './contract.pdf' });
+     * await client.documents.upload({ buffer, fileName: 'contract.pdf' }, { metadata });
+     * ```
+     */
+    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`.
+     */
+    list(params?: IDocumentListParams, accountId?: string): Promise<IDocumentListResponse>;
+    /** Get document details. */
+    details(documentId: string): Promise<IDocumentDetailsResponse>;
+    /** Alias for {@link details}. */
+    get(documentId: string): Promise<IDocumentDetailsResponse>;
+    /** Poll document status until ready (or a terminal status / timeout). */
+    waitUntilReady(documentId: string, options?: {
+        maxWaitMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<IDocumentDetailsResponse>;
+    /** Download a document artifact. Defaults to the certificated (signed) PDF. */
+    download(documentId: string, artifactName?: DocumentArtifactName): Promise<Buffer>;
+    /** Download the document thumbnail. */
+    thumbnail(documentId: string): Promise<Buffer>;
+    /** Download a single page as a JPEG. */
+    downloadPage(documentId: string, pageId: string): Promise<Buffer>;
+    /** Fetch the document activity log. */
+    activities(documentId: string): Promise<IDocumentActivity[]>;
+    /** Delete a document. */
+    delete(documentId: string): Promise<void>;
+    /** List the tags attached to a document. */
+    listTags(documentId: string, accountId?: string): Promise<ITag[]>;
+    /**
+     * Replace the document's tag set with `tags` (an array of tag names).
+     * Unknown names are auto-created; an empty array detaches all tags.
+     */
+    replaceTags(documentId: string, tags: string[], accountId?: string): Promise<ITag[]>;
+    /** Attach additional tags (by name) without removing existing ones. Idempotent. */
+    addTags(documentId: string, tags: string[], accountId?: string): Promise<ITag[]>;
+    /** Detach a single tag from a document (the tag itself is not deleted). */
+    detachTag(documentId: string, tagId: string, accountId?: string): Promise<void>;
+    /**
+     * Create a document from a template.
+     *
+     * @example
+     * ```ts
+     * await client.documents.createFromTemplate('tmpl_id', [
+     *   { role_id: 'role_id', id: 'signer_id', verification_method: 'Email', notification_methods: ['Email'] },
+     * ], { name: 'My Contract' });
+     * ```
+     */
+    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>>;
+    /** Verify a document by its signature hash. */
+    verify(hash: string): Promise<Record<string, unknown>>;
+    /**
+     * `GET /documents/statuses` — list every possible document status with
+     * its description and whether documents in that status can be deleted.
+     */
+    statuses(): Promise<IDocumentStatusInfo[]>;
+    /**
+     * `GET /public/documents/{document_id}` — public, unauthenticated lookup of
+     * basic document info (used by the signing portal before the signer
+     * authenticates via the access code).
+     */
+    getPublic(documentId: string): Promise<IPublicDocumentInfo>;
+    /**
+     * `PUT /public/documents/{document_id}/send-token` — send the 6-digit
+     * verification token to the signer's email / WhatsApp.
+     */
+    sendToken(documentId: string, recipient: string, channel?: SendTokenChannel): Promise<unknown>;
+    /** Quick check: has every signer completed their assignment? */
+    isFullySigned(documentId: string): Promise<boolean>;
+    /** Summarise signing progress for UI display. */
+    getSigningProgress(documentId: string): Promise<ISigningProgress>;
+}
+
+declare class SignerResource extends BaseResource {
+    /**
+     * Create a signer in the workspace.
+     *
+     * `email` is optional — the API also accepts whatsapp-only signers — but at
+     * least one of `email` / `whatsapp_phone_number` (or the `phone` alias) is
+     * required. When an `email` is supplied the call is idempotent by email:
+     * an existing signer with that address is reused instead of duplicated.
+     */
+    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(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. */
+    findByEmail(email: string, accountId?: string): Promise<ISigner | null>;
+    private assertEmail;
+}
+
+declare class WorkspaceResource extends BaseResource {
+    /** Create a new workspace. */
+    create(payload: ICreateWorkspacePayload): Promise<IWorkspaceResponse>;
+    /** List workspaces the authenticated user can access. */
+    list(): Promise<IWorkspaceListResponse>;
+    /** Fetch a single workspace. */
+    get(accountId: string): Promise<IWorkspaceResponse>;
+    /** Update a workspace. */
+    update(accountId: string, payload: IUpdateWorkspacePayload): Promise<IWorkspaceResponse>;
+    /** Delete a workspace. */
+    delete(accountId: string): Promise<void>;
+}
+
+/**
+ * Normalise an assignment payload into the shape the API expects:
+ * `signers: [{ id }]` plus optional docs-level fields.
+ */
+declare function buildAssignmentPayload(payload: ICreateAssignmentPayload, options?: {
+    allowSignersWithoutId?: boolean;
+}): Record<string, unknown>;
+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>>;
+    /**
+     * Update the expiration date of an existing assignment.
+     * Pass `null` to remove the expiration entirely.
+     */
+    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>>;
+    /**
+     * `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>;
+}
+
+declare class WebhookResource extends BaseResource {
+    /** Register (or replace) the webhook subscription for the workspace. */
+    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(accountId?: string): Promise<IWebhookSubscription>;
+    /** List currently supported webhook event types. */
+    listEventTypes(): Promise<IWebhookEventTypeInfo[]>;
+    /** List webhook delivery history for the workspace. */
+    listDispatches(params?: IWebhookDispatchListParams, accountId?: string): Promise<PaginatedResult<IWebhookDispatch>>;
+    /** Retry delivery of a specific webhook dispatch. */
+    retryDispatch(dispatchId: string, accountId?: string): Promise<IWebhookDispatch>;
+}
+
+declare class TemplateResource extends BaseResource {
+    /** List templates for the workspace. */
+    list(params?: IListParams, accountId?: string): Promise<ITemplateListResponse>;
+    /**
+     * Get a template by 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.
+     */
+    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).
+     */
+    downloadPage(templateId: string, pageId: string, accountId?: string): Promise<Buffer>;
+}
+
+/**
+ * Workspace-scoped tags used to label documents and templates.
+ *
+ * Covers the full Tag section of the API docs:
+ *  - `GET    /accounts/{id}/tags`            → {@link list}
+ *  - `POST   /accounts/{id}/tags`            → {@link create}
+ *  - `PUT    /accounts/{id}/tags/{tag_id}`   → {@link update}
+ *  - `DELETE /accounts/{id}/tags/{tag_id}`   → {@link delete}
+ *
+ * Document-level attach/detach lives on {@link DocumentResource} (`listTags`,
+ * `replaceTags`, `addTags`, `detachTag`).
+ */
+declare class TagResource extends BaseResource {
+    /** List the workspace's tags, ordered alphabetically. Optional case-insensitive `search`. */
+    list(params?: {
+        search?: string;
+    }, accountId?: string): Promise<ITag[]>;
+    /** Create a tag. Throws `ApiError` (409) if the name already exists (case-insensitive). */
+    create(payload: ICreateTagPayload, accountId?: string): Promise<ITag>;
+    /**
+     * Update a tag's name and/or color. Omit a field to leave it unchanged;
+     * pass `color: null` to clear the color. Throws `ApiError` (409) if another
+     * tag already uses the new name.
+     */
+    update(tagId: string, payload: IUpdateTagPayload, accountId?: string): Promise<ITag>;
+    /**
+     * Delete a tag. By default fails with `ApiError` (409) if the tag is still
+     * attached to anything; pass `{ force: true }` to detach everywhere first.
+     */
+    delete(tagId: string, options?: {
+        force?: boolean;
+        accountId?: string;
+    }): Promise<void>;
+}
+
+/**
+ * Authentication endpoints (login, social login, password management) and
+ * personal API key management (`/users/api-keys`).
+ *
+ * Most of these endpoints are intended to bootstrap an authenticated session
+ * for a human user. Production server-to-server integrations should use
+ * `X-Api-Key` and skip this resource entirely.
+ */
+declare class AuthenticationResource extends BaseResource {
+    /** `POST /login` — exchange email + password for a JWT access token. */
+    login(email: string, password: string): Promise<ILoginResponse>;
+    /** `POST /authentication/social-login` — exchange a provider token for an Assinafy JWT. */
+    socialLogin(payload: {
+        provider: string;
+        token: string;
+        has_accepted_terms: boolean;
+    }): Promise<ILoginResponse>;
+    /** `POST /users/api-keys` — generate (and rotate) the current user's API key. */
+    createApiKey(password: string): Promise<IApiKeyResponse>;
+    /**
+     * `GET /users/api-keys` — fetch a masked version of the current API key, or
+     * `null` if no key has been generated yet.
+     */
+    getApiKey(): Promise<IMaskedApiKeyResponse>;
+    /** `DELETE /users/api-keys` — revoke the current API key. */
+    deleteApiKey(): Promise<void>;
+    /** `PUT /authentication/change-password` — change the authenticated user's password. */
+    changePassword(payload: {
+        email: string;
+        password: string;
+        new_password: string;
+    }): Promise<{
+        email: string;
+    }>;
+    /** `PUT /authentication/request-password-reset` — email a reset link to the user. */
+    requestPasswordReset(email: string): Promise<{
+        email: string;
+    }>;
+    /** `PUT /authentication/reset-password` — complete a password reset using the emailed token. */
+    resetPassword(payload: {
+        email: string;
+        token?: string;
+        new_password: string;
+    }): Promise<{
+        email: string;
+    }>;
+}
+
+/**
+ * Custom field definitions used by `collect` assignments.
+ *
+ * Covers the full Field Definition section of the API docs:
+ *  - `POST /accounts/{id}/fields`
+ *  - `GET /accounts/{id}/fields`
+ *  - `GET /accounts/{id}/fields/{id}`
+ *  - `PUT /accounts/{id}/fields/{id}`
+ *  - `DELETE /accounts/{id}/fields/{id}`
+ *  - `POST /accounts/{id}/fields/{id}/validate?signer-access-code=…`
+ *  - `POST /accounts/{id}/fields/validate-multiple?signer-access-code=…`
+ *  - `GET /field-types`
+ */
+declare class FieldsResource extends BaseResource {
+    /** Create a field definition. */
+    create(payload: ICreateFieldPayload, accountId?: string): Promise<IFieldDefinition>;
+    /**
+     * List field definitions for the workspace.
+     *
+     * @param params.include_inactive  return inactive fields too
+     * @param params.include_standard  also return `signature`, `initial`, `signatureDate`
+     */
+    list(params?: {
+        include_inactive?: boolean;
+        include_standard?: boolean;
+    }, accountId?: string): Promise<IFieldDefinition[]>;
+    /** Get a single field definition by ID. */
+    get(fieldId: string, accountId?: string): Promise<IFieldDefinition>;
+    /** Update a field definition. */
+    update(fieldId: string, payload: IUpdateFieldPayload, accountId?: string): Promise<IFieldDefinition>;
+    /** Delete a field definition. Fails if the field has been used. */
+    delete(fieldId: string, accountId?: string): Promise<void>;
+    /**
+     * Validate a single value against a field definition.
+     *
+     * Pass `signerAccessCode` for signer-side validation (the typical use case);
+     * omit it when the caller is authenticated via API key.
+     */
+    validate(fieldId: string, value: unknown, options?: {
+        signerAccessCode?: string;
+        accountId?: string;
+    }): Promise<IFieldValidationResult>;
+    /** Validate multiple values at once. */
+    validateMultiple(entries: IFieldValidateMultipleEntry[], options?: {
+        signerAccessCode?: string;
+        accountId?: string;
+    }): Promise<IFieldValidationResult[]>;
+    /** List the platform's supported field types. */
+    listTypes(): Promise<IFieldType[]>;
+}
+
+/**
+ * Signer-side endpoints. Every call here is authenticated by `signer-access-code`
+ * (the one-time link emailed/whatsapped to the signer), not by the workspace
+ * API key. Use this resource when building a custom signer UI.
+ */
+declare class SignerDocumentsResource extends BaseResource {
+    /** `GET /signers/{signer_id}/document?signer-access-code=…` */
+    getCurrent(signerId: string, signerAccessCode: string): Promise<IDocumentDetailsResponse>;
+    /** `GET /signers/{signer_id}/documents?signer-access-code=…` */
+    list(signerId: string, signerAccessCode: string, params?: IListParams): 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=…` */
+    signMultiple(documentIds: string[], signerAccessCode: string): Promise<unknown>;
+    /** `PUT /signers/documents/decline-multiple?signer-access-code=…` */
+    declineMultiple(documentIds: string[], declineReason: string, signerAccessCode: string): Promise<unknown>;
+    /** `GET /signers/self?signer-access-code=…` — fetch the signer's own profile. */
+    self(signerAccessCode: string): Promise<unknown>;
+    /** `PUT /signers/accept-terms` — accept the platform terms as the signer. */
+    acceptTerms(signerAccessCode: string): Promise<unknown>;
+    /** `POST /verify` — verify the email OTP for a signer. */
+    verifyEmail(payload: {
+        signerAccessCode: string;
+        verificationCode: string;
+    }): Promise<unknown>;
+    /** `PUT /documents/{documentId}/signers/confirm-data?signer-access-code=…` */
+    confirmData(documentId: string, signerAccessCode: string, payload: {
+        email?: string;
+        whatsapp_phone_number?: string;
+        has_accepted_terms?: boolean;
+    }): Promise<unknown>;
+    /**
+     * `POST /signature?signer-access-code=…&type=…` — upload the signer's
+     * signature or initial image. `imageType` defaults to `signature`.
+     */
+    uploadSignature(signerAccessCode: string, image: Buffer, options?: {
+        imageType?: 'signature' | 'initial';
+        contentType?: string;
+    }): 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. */
+    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.)
+     */
+    decline(documentId: string, assignmentId: string, signerAccessCode: string, declineReason: string): Promise<unknown>;
+}
+
+/**
+ * Verifier for Assinafy webhook payloads.
+ *
+ * The Assinafy platform signs webhook bodies with HMAC-SHA256 using the
+ * workspace webhook secret and sends the hex digest in an `X-Assinafy-Signature`
+ * header. Use {@link WebhookVerifier.verify} to confirm the signature before
+ * trusting the payload.
+ */
+declare class WebhookVerifier {
+    private readonly webhookSecret?;
+    constructor(webhookSecret?: string | undefined);
+    /** Returns `true` if `signature` is a valid HMAC-SHA256 of `payload`. */
+    verify(payload: string | Buffer, signature: string): boolean;
+    /** Parse the raw webhook body into a JSON event envelope. */
+    extractEvent(payload: string | Buffer): IWebhookPayload | null;
+    /** Extract the event name (`event` or `type`) from an event envelope. */
+    getEventType(event: IWebhookPayload | null | undefined): string | null;
+    /** Extract the event data (`data` or `object`) from an event envelope. */
+    getEventData(event: IWebhookPayload | null | undefined): Record<string, unknown>;
+}
+
+/** Flexible input accepted by {@link AssinafyClient.fromConfig} (snake_case or camelCase). */
+interface ClientConfigInput {
+    api_key?: string;
+    apiKey?: string;
+    token?: string;
+    access_token?: string;
+    accessToken?: string;
+    account_id?: string;
+    accountId?: string;
+    base_url?: string;
+    baseUrl?: string;
+    webhook_secret?: string;
+    webhookSecret?: string;
+    timeout?: number;
+    logger?: Logger;
+}
+/**
+ * Primary entry point for the Assinafy API.
+ *
+ * @example
+ * ```ts
+ * const client = new AssinafyClient({
+ *   apiKey: process.env.ASSINAFY_API_KEY!,
+ *   accountId: process.env.ASSINAFY_ACCOUNT_ID!,
+ *   webhookSecret: process.env.ASSINAFY_WEBHOOK_SECRET,
+ * });
+ *
+ * const document = await client.documents.upload({ filePath: './contract.pdf' });
+ * ```
+ */
+declare class AssinafyClient {
+    private readonly axiosInstance;
+    private readonly defaultAccountId;
+    private readonly logger;
+    private readonly webhookSecret;
+    readonly documents: DocumentResource;
+    readonly signers: SignerResource;
+    readonly workspaces: WorkspaceResource;
+    readonly assignments: AssignmentResource;
+    readonly webhooks: WebhookResource;
+    readonly templates: TemplateResource;
+    readonly tags: TagResource;
+    readonly auth: AuthenticationResource;
+    readonly fields: FieldsResource;
+    readonly signerDocuments: SignerDocumentsResource;
+    readonly webhookVerifier: WebhookVerifier;
+    constructor(options: AssinafyClientOptions);
+    /** Convenience factory for the common apiKey + accountId setup. */
+    static create(apiKey: string, accountId: string, options?: Omit<AssinafyClientOptions, 'apiKey' | 'accountId'>): AssinafyClient;
+    /** Build a client from a plain object (supports snake_case and camelCase keys). */
+    static fromConfig(config: ClientConfigInput): AssinafyClient;
+    /**
+     * High-level helper that uploads a PDF, ensures it's processed, creates any
+     * missing signers, and kicks off a virtual signature assignment.
+     */
+    uploadAndRequestSignatures(options: {
+        source: DocumentUploadSource;
+        signers: IUploadAndRequestSignaturesSigner[];
+        message?: string;
+        metadata?: Record<string, unknown>;
+        waitForReady?: boolean;
+        expiresAt?: string;
+        copyReceivers?: string[];
+        accountId?: string;
+    }): Promise<IUploadAndRequestSignaturesResult>;
+    /** Expose the underlying axios instance for advanced use cases (interceptors, custom endpoints). */
+    getAxiosInstance(): AxiosInstance;
+}
+
+/** 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;
+    });
+}
+/** 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;
+    });
+    static fromResponse(statusCode: number, responseData: unknown): ApiError;
+}
+/** Thrown when client-side validation fails before the request is sent. */
+declare class ValidationError extends AssinafyError {
+    readonly errors: Record<string, unknown>;
+    constructor(message?: string, errors?: Record<string, unknown>);
+}
+/** Thrown when the HTTP transport itself fails (DNS, timeout, etc.). */
+declare class NetworkError extends AssinafyError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+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 };