@assinafy/sdk 1.4.0 → 2.0.0

package/dist/index.mjs

@@ -3,16 +3,16 @@ import axios2 from "axios";
 
 // src/errors.ts
 var AssinafyError = class extends Error {
+  context;
   constructor(message, context = {}, options) {
-    super(message);
+    super(message, options);
     this.name = "AssinafyError";
     this.context = context;
-    if (options?.cause !== void 0) {
-      this.cause = options.cause;
-    }
   }
 };
 var ApiError = class _ApiError extends AssinafyError {
+  statusCode;
+  responseData;
   constructor(message, statusCode, responseData = null, options) {
     super(message, { statusCode, responseData }, options);
     this.name = "ApiError";
@@ -28,6 +28,7 @@ var ApiError = class _ApiError extends AssinafyError {
   }
 };
 var ValidationError = class extends AssinafyError {
+  errors;
   constructor(message = "Validation failed", errors = {}) {
     super(message, { errors });
     this.name = "ValidationError";
@@ -53,6 +54,23 @@ function handleAssinafyResponse(response) {
   }
   return response;
 }
+function decodeBinaryErrorBody(data) {
+  let text;
+  if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) {
+    text = data.toString("utf8");
+  } else if (data instanceof ArrayBuffer) {
+    text = Buffer.from(data).toString("utf8");
+  } else if (ArrayBuffer.isView(data)) {
+    text = Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("utf8");
+  } else {
+    return data;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text.length > 0 ? { message: text } : null;
+  }
+}
 function toSdkError(error, fallbackMessage) {
   if (error instanceof AssinafyError) {
     return error;
@@ -60,14 +78,15 @@ function toSdkError(error, fallbackMessage) {
   if (axios.isAxiosError(error)) {
     const status = error.response?.status;
     if (status) {
-      return ApiError.fromResponse(status, error.response?.data ?? null);
+      const body = decodeBinaryErrorBody(error.response?.data ?? null);
+      return ApiError.fromResponse(status, body ?? null);
     }
     return new NetworkError(`${fallbackMessage}: ${error.message}`, { cause: error });
   }
   if (error instanceof Error) {
     return new AssinafyError(`${fallbackMessage}: ${error.message}`, {}, { cause: error });
   }
-  return new AssinafyError(fallbackMessage, { cause: error });
+  return new AssinafyError(fallbackMessage, {}, { cause: error });
 }
 function createNoopLogger() {
   return {
@@ -86,12 +105,101 @@ function cleanParams(params) {
   }
   return out;
 }
+function cleanListParams(params) {
+  const out = cleanParams(params);
+  if (out["per_page"] !== void 0) {
+    out["per-page"] ??= out["per_page"];
+    delete out["per_page"];
+  }
+  return out;
+}
 
-// src/resources/documents.ts
+// src/support/retry.ts
+function header(headers, name) {
+  if (!headers) return void 0;
+  const lower = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === lower && value != null) {
+      return Array.isArray(value) ? String(value[0]) : String(value);
+    }
+  }
+  return void 0;
+}
+function retryDelayFromHeaders(headers) {
+  const retryAfter = header(headers, "retry-after");
+  if (retryAfter !== void 0) {
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+    const date = Date.parse(retryAfter);
+    if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  }
+  const reset = header(headers, "x-rate-limit-reset");
+  if (reset !== void 0) {
+    const seconds = Number(reset);
+    if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+  }
+  return void 0;
+}
+function backoffMs(attempt) {
+  return Math.min(1e3 * 2 ** Math.max(0, attempt - 1), 8e3);
+}
+function nextRetryDelayMs(headers, attempt, maxDelayMs = 3e4) {
+  const hinted = retryDelayFromHeaders(headers);
+  if (hinted !== void 0) return Math.min(hinted, maxDelayMs);
+  return Math.min(backoffMs(attempt), maxDelayMs);
+}
+
+// src/resources/upload.ts
 import { promises as fs } from "fs";
 import path from "path";
+var MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
+async function loadSource(source) {
+  if ("buffer" in source) {
+    if (!source.fileName) {
+      throw new ValidationError("fileName is required when uploading a Buffer");
+    }
+    return { buffer: source.buffer, fileName: source.fileName };
+  }
+  if (!source.filePath) {
+    throw new ValidationError("filePath is required");
+  }
+  const buffer = await fs.readFile(source.filePath);
+  return { buffer, fileName: source.fileName ?? path.basename(source.filePath) };
+}
+function validateUpload(buffer, fileName) {
+  if (!buffer || buffer.byteLength === 0) {
+    throw new ValidationError("File buffer is empty", { fileName });
+  }
+  if (!fileName.toLowerCase().endsWith(".pdf")) {
+    throw new ValidationError("Only PDF files are supported", { fileName });
+  }
+  if (buffer.byteLength > MAX_UPLOAD_BYTES) {
+    throw new ValidationError("File size exceeds maximum allowed (25MB)", {
+      fileSize: buffer.byteLength,
+      maxSize: MAX_UPLOAD_BYTES
+    });
+  }
+}
+function toUploadFileName(name) {
+  return name.toLowerCase().endsWith(".pdf") ? name : `${name}.pdf`;
+}
+function buildUploadForm(buffer, fileName, options = {}) {
+  const form = new FormData();
+  const view = new Uint8Array(
+    buffer.buffer,
+    buffer.byteOffset,
+    buffer.byteLength
+  );
+  const partName = options.name === void 0 ? fileName : toUploadFileName(options.name);
+  form.append("file", new Blob([view], { type: "application/pdf" }), partName);
+  if (options.metadata) {
+    form.append("metadata", JSON.stringify(options.metadata));
+  }
+  return form;
+}
 
 // src/resources/base.ts
+var MULTIPART_CONTENT_TYPE = "multipart/form-data";
 var BaseResource = class {
   constructor(http, defaultAccountId, logger = createNoopLogger()) {
     this.http = http;
@@ -153,6 +261,35 @@ var BaseResource = class {
       throw toSdkError(err, label);
     }
   }
+  /**
+   * 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.
+   */
+  async uploadPdf(path2, source, formOptions, labels) {
+    const { buffer, fileName } = await loadSource(source);
+    validateUpload(buffer, fileName);
+    this.logger.info("Uploading PDF", { path: path2, fileName, size: buffer.byteLength });
+    const form = buildUploadForm(buffer, fileName, formOptions);
+    const result = await this.call(
+      labels.errorLabel,
+      () => this.http.post(path2, form, { headers: { "Content-Type": MULTIPART_CONTENT_TYPE } })
+    );
+    if (!result?.id) {
+      throw new ValidationError(labels.missingId, {
+        response: result
+      });
+    }
+    return result;
+  }
   /** Execute a paginated list call and attach meta from `X-Pagination-*` headers. */
   async callList(label, request) {
     try {
@@ -195,7 +332,6 @@ function toInt(value) {
 }
 
 // src/resources/documents.ts
-var MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
 var READY_STATUSES = /* @__PURE__ */ new Set([
   "metadata_ready",
   "pending_signature",
@@ -209,43 +345,153 @@ var FAILED_STATUSES = /* @__PURE__ */ new Set([
 ]);
 var DocumentResource = class 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'
    * ```
    */
   async upload(source, options = {}) {
-    const { buffer, fileName } = await loadSource(source);
-    validateUpload(buffer, fileName);
     const accountId = this.accountId(options.accountId);
-    const form = buildUploadForm(buffer, fileName, options.metadata);
-    this.logger.info("Uploading document", { fileName, size: buffer.byteLength });
-    const document = await this.call(
-      "Document upload failed",
-      () => this.http.post(`/accounts/${accountId}/documents`, form, {
-        headers: { "Content-Type": "multipart/form-data" }
-      })
+    const formOptions = {};
+    if (options.name !== void 0) formOptions.name = options.name;
+    if (options.metadata !== void 0) formOptions.metadata = options.metadata;
+    const document = await this.uploadPdf(
+      `/accounts/${accountId}/documents`,
+      source,
+      formOptions,
+      {
+        errorLabel: "Document upload failed",
+        missingId: "Upload succeeded but no document ID was returned"
+      }
     );
-    if (!document?.id) {
-      throw new ValidationError("Upload succeeded but no document ID was returned", {
-        response: document
-      });
-    }
     this.logger.info("Document uploaded", { documentId: document.id });
     return document;
   }
   /**
    * 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`.
    */
   async list(params = {}, accountId) {
     const id = this.accountId(accountId);
     return this.callList(
       "Failed to list documents",
-      () => this.http.get(`/accounts/${id}/documents`, { params: cleanParams(params) })
+      () => this.http.get(`/accounts/${id}/documents`, { params: cleanListParams(params) })
+    );
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async search(params = {}, accountId) {
+    const id = this.accountId(accountId);
+    return this.callList(
+      "Failed to search documents",
+      () => this.http.get(`/accounts/${id}/documents/search`, { params: cleanListParams(params) })
+    );
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async rename(documentId, name) {
+    const id = this.requireId(documentId, "Document ID");
+    const newName = this.requireId(name, "Name");
+    this.logger.info("Renaming document", { documentId: id });
+    return this.call(
+      "Failed to rename document",
+      () => this.http.patch(`/documents/${id}`, { name: newName })
     );
   }
   /** Get document details. */
@@ -279,6 +525,9 @@ var DocumentResource = class extends BaseResource {
         }
       } catch (err) {
         if (err instanceof ValidationError) throw err;
+        if (err instanceof ApiError && err.statusCode < 500 && err.statusCode !== 429) {
+          throw err;
+        }
         this.logger.warn("Error checking document status", {
           error: err instanceof Error ? err.message : String(err)
         });
@@ -397,7 +646,12 @@ var DocumentResource = class extends BaseResource {
       () => this.http.post(`/accounts/${accId}/templates/${tmplId}/documents`, body)
     );
   }
-  /** Estimate the credit cost of creating a document from a template. */
+  /**
+   * 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.
+   */
   async estimateCostFromTemplate(templateId, signers, accountId) {
     const tmplId = this.requireId(templateId, "Template ID");
     const accId = this.accountId(accountId);
@@ -466,43 +720,6 @@ var DocumentResource = class extends BaseResource {
     return { signed, total, pending, percentage };
   }
 };
-async function loadSource(source) {
-  if ("buffer" in source) {
-    if (!source.fileName) {
-      throw new ValidationError("fileName is required when uploading a Buffer");
-    }
-    return { buffer: source.buffer, fileName: source.fileName };
-  }
-  if (!source.filePath) {
-    throw new ValidationError("filePath is required");
-  }
-  const buffer = await fs.readFile(source.filePath);
-  return { buffer, fileName: source.fileName ?? path.basename(source.filePath) };
-}
-function validateUpload(buffer, fileName) {
-  if (!buffer || buffer.byteLength === 0) {
-    throw new ValidationError("File buffer is empty", { fileName });
-  }
-  if (!fileName.toLowerCase().endsWith(".pdf")) {
-    throw new ValidationError("Only PDF files are supported", { fileName });
-  }
-  if (buffer.byteLength > MAX_UPLOAD_BYTES) {
-    throw new ValidationError("File size exceeds maximum allowed (25MB)", {
-      fileSize: buffer.byteLength,
-      maxSize: MAX_UPLOAD_BYTES
-    });
-  }
-}
-function buildUploadForm(buffer, fileName, metadata) {
-  const form = new FormData();
-  const view = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
-  form.append("file", new Blob([view], { type: "application/pdf" }), fileName);
-  form.append("name", fileName);
-  if (metadata) {
-    form.append("metadata", JSON.stringify(metadata));
-  }
-  return form;
-}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -541,7 +758,8 @@ var SignerResource = class extends BaseResource {
         () => this.http.post(`/accounts/${id}/signers`, normaliseSignerPayload(payload))
       );
     } catch (err) {
-      if (err instanceof ApiError && err.statusCode === 409 && payload.email) {
+      const isDuplicateStatus = err instanceof ApiError && (err.statusCode === 409 || err.statusCode === 400);
+      if (isDuplicateStatus && payload.email) {
         const duplicate = await this.findByEmail(payload.email, id);
         if (duplicate) {
           this.logger.info("Signer already exists, using existing signer", {
@@ -562,12 +780,12 @@ var SignerResource = class extends BaseResource {
       () => this.http.get(`/accounts/${id}/signers/${sid}`)
     );
   }
-  /** List signers for the workspace (supports `page`, `per_page`, `search`, `sort`). */
+  /** List signers for the workspace (supports `page`, `per-page`, `search`, `sort`). */
   async list(params = {}, accountId) {
     const id = this.accountId(accountId);
     return this.callList(
       "Failed to list signers",
-      () => this.http.get(`/accounts/${id}/signers`, { params: cleanParams(params) })
+      () => this.http.get(`/accounts/${id}/signers`, { params: cleanListParams(params) })
     );
   }
   /** Update a signer. Fails if the signer has active assignments. */
@@ -588,11 +806,28 @@ var SignerResource = class extends BaseResource {
       () => this.http.delete(`/accounts/${id}/signers/${sid}`)
     );
   }
-  /** 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.
+   */
   async findByEmail(email, accountId) {
     this.assertEmail(email);
     try {
-      const { data } = await this.list({ search: email, per_page: 100 }, accountId);
+      const { data } = await this.list({ search: email, "per-page": 50 }, accountId);
       const lower = email.toLowerCase();
       return data.find((s) => (s.email ?? "").toLowerCase() === lower) ?? null;
     } catch (err) {
@@ -704,6 +939,58 @@ function normaliseSignerRef(ref, options) {
   throw new ValidationError("Invalid signer reference", { ref });
 }
 var AssignmentResource = class 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 });
+   * ```
+   */
+  async list(params = {}, accountId) {
+    const id = this.accountId(accountId);
+    return this.callList(
+      "Failed to list assignments",
+      () => this.http.get("/assignments", {
+        params: { accountId: id, ...cleanListParams(params) }
+      })
+    );
+  }
   /** Create a signing assignment for a document. */
   async create(documentId, payload) {
     const docId = this.requireId(documentId, "Document ID");
@@ -718,7 +1005,15 @@ var AssignmentResource = class extends BaseResource {
       () => this.http.post(`/documents/${docId}/assignments`, body)
     );
   }
-  /** Estimate the cost (in credits) of creating the assignment. */
+  /**
+   * 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`.
+   */
   async estimateCost(documentId, payload) {
     const docId = this.requireId(documentId, "Document ID");
     return this.call(
@@ -753,7 +1048,11 @@ var AssignmentResource = class extends BaseResource {
       () => this.http.put(`/documents/${docId}/assignments/${asgId}/signers/${sid}/resend`)
     );
   }
-  /** Estimate the cost of resending a signer notification. */
+  /**
+   * Estimate the cost of resending a signer notification.
+   *
+   * @returns an {@link IResendCostEstimate} (`total`, `breakdown`, balances).
+   */
   async estimateResendCost(documentId, assignmentId, signerId) {
     const docId = this.requireId(documentId, "Document ID");
     const asgId = this.requireId(assignmentId, "Assignment ID");
@@ -777,26 +1076,10 @@ var AssignmentResource = class extends BaseResource {
       () => this.http.get(`/documents/${docId}/assignments/${asgId}/whatsapp-notifications`)
     );
   }
-  /**
-   * Cancel a signature request. This endpoint is not listed in the public
-   * Swagger but is exposed by the platform.
-   */
-  async cancel(documentId, reason, accountId) {
-    const docId = this.requireId(documentId, "Document ID");
-    const accId = this.accountId(accountId);
-    this.logger.info("Cancelling signature request", { documentId: docId, reason });
-    return this.call(
-      "Failed to cancel signature request",
-      () => this.http.post(
-        `/accounts/${accId}/signature-requests/${docId}/cancel`,
-        { document_id: docId, reason }
-      )
-    );
-  }
 };
 
 // src/resources/webhooks.ts
-var DEFAULT_EVENTS = [
+var DEFAULT_WEBHOOK_EVENTS = [
   "document_ready",
   "document_prepared",
   "signer_signed_document",
@@ -804,7 +1087,21 @@ var DEFAULT_EVENTS = [
   "document_processing_failed"
 ];
 var WebhookResource = class 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-…' }
+   * ```
+   */
   async register(payload, accountId) {
     if (!payload.url) throw new ValidationError("Webhook URL is required");
     if (!payload.email) throw new ValidationError("Webhook email is required");
@@ -812,7 +1109,7 @@ var WebhookResource = class extends BaseResource {
     const body = {
       url: payload.url,
       email: payload.email,
-      events: payload.events && payload.events.length > 0 ? payload.events : DEFAULT_EVENTS,
+      events: payload.events && payload.events.length > 0 ? payload.events : DEFAULT_WEBHOOK_EVENTS,
       is_active: payload.is_active ?? true
     };
     this.logger.info("Registering webhook", { url: payload.url });
@@ -829,16 +1126,14 @@ var WebhookResource = class extends BaseResource {
       () => this.http.get(`/accounts/${id}/webhooks/subscriptions`)
     );
   }
-  /** Delete the current webhook subscription. */
-  async delete(accountId) {
-    const id = this.accountId(accountId);
-    this.logger.info("Deleting webhook subscription");
-    return this.callVoid(
-      "Failed to delete webhook subscription",
-      () => this.http.delete(`/accounts/${id}/webhooks/subscriptions`)
-    );
-  }
-  /** 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`.
+   */
   async inactivate(accountId) {
     const id = this.accountId(accountId);
     this.logger.info("Inactivating webhook subscription");
@@ -860,7 +1155,7 @@ var WebhookResource = class extends BaseResource {
     return this.callList(
       "Failed to list webhook dispatches",
       () => this.http.get(`/accounts/${id}/webhooks`, {
-        params: cleanParams(params)
+        params: cleanListParams(params)
       })
     );
   }
@@ -877,20 +1172,56 @@ var WebhookResource = class extends BaseResource {
 
 // src/resources/templates.ts
 var TemplateResource = class 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 }
+   * ```
+   */
+  async create(source, options = {}) {
+    const id = this.accountId(options.accountId);
+    const formOptions = {};
+    if (options.name !== void 0) formOptions.name = options.name;
+    const template = await this.uploadPdf(
+      `/accounts/${id}/templates`,
+      source,
+      formOptions,
+      {
+        errorLabel: "Failed to create template",
+        missingId: "Template upload succeeded but no template ID was returned"
+      }
+    );
+    this.logger.info("Template created", { templateId: template.id });
+    return template;
+  }
   /** List templates for the workspace. */
   async list(params = {}, accountId) {
     const id = this.accountId(accountId);
     return this.callList(
       "Failed to list templates",
-      () => this.http.get(`/accounts/${id}/templates`, { params: cleanParams(params) })
+      () => this.http.get(`/accounts/${id}/templates`, { params: cleanListParams(params) })
     );
   }
   /**
-   * 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.
    */
   async get(templateId, accountId) {
     const id = this.accountId(accountId);
@@ -901,9 +1232,40 @@ var TemplateResource = class extends BaseResource {
     );
   }
   /**
-   * `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' });
+   * ```
+   */
+  async update(templateId, payload, accountId) {
+    const id = this.accountId(accountId);
+    const tmplId = this.requireId(templateId, "Template ID");
+    return this.call(
+      "Failed to update template",
+      () => this.http.put(
+        `/accounts/${id}/templates/${tmplId}`,
+        cleanParams(payload)
+      )
+    );
+  }
+  /** Delete a template (`DELETE /accounts/{id}/templates/{template_id}`). */
+  async delete(templateId, accountId) {
+    const id = this.accountId(accountId);
+    const tmplId = this.requireId(templateId, "Template ID");
+    return this.callVoid(
+      "Failed to delete template",
+      () => this.http.delete(`/accounts/${id}/templates/${tmplId}`)
+    );
+  }
+  /**
+   * 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.
    */
   async downloadPage(templateId, pageId, accountId) {
     const id = this.accountId(accountId);
@@ -927,7 +1289,7 @@ var TagResource = class extends BaseResource {
     return this.call(
       "Failed to list tags",
       () => this.http.get(`/accounts/${id}/tags`, {
-        params: cleanParams(params)
+        params: cleanListParams(params)
       })
     );
   }
@@ -1069,7 +1431,7 @@ var FieldsResource = class extends BaseResource {
     return this.call(
       "Failed to list field definitions",
       () => this.http.get(`/accounts/${id}/fields`, {
-        params: cleanParams(params)
+        params: cleanListParams(params)
       })
     );
   }
@@ -1153,7 +1515,44 @@ var SignerDocumentsResource = class extends BaseResource {
     return this.callList(
       "Failed to list signer documents",
       () => this.http.get(`/signers/${sid}/documents`, {
-        params: { "signer-access-code": code, ...cleanParams(params) }
+        params: { "signer-access-code": code, ...cleanListParams(params) }
+      })
+    );
+  }
+  /**
+   * 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',
+   * );
+   * ```
+   */
+  async search(signerId, signerAccessCode, search) {
+    const sid = this.requireId(signerId, "Signer ID");
+    const code = this.requireId(signerAccessCode, "signer-access-code");
+    return this.callList(
+      "Failed to search signer documents",
+      () => this.http.get(`/signers/${sid}/documents/search`, {
+        params: cleanParams({ "signer-access-code": code, search })
       })
     );
   }
@@ -1271,7 +1670,12 @@ var SignerDocumentsResource = class extends BaseResource {
       })
     );
   }
-  /** `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.
+   */
   async getAssignment(signerAccessCode, hasAcceptedTerms) {
     const code = this.requireId(signerAccessCode, "signer-access-code");
     return this.call(
@@ -1301,8 +1705,8 @@ var SignerDocumentsResource = class extends BaseResource {
   }
   /**
    * `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.)
    */
   async decline(documentId, assignmentId, signerAccessCode, declineReason) {
     const did = this.requireId(documentId, "Document ID");
@@ -1368,6 +1772,21 @@ var WebhookVerifier = class {
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.assinafy.com.br/v1";
 var AssinafyClient = class _AssinafyClient {
+  axiosInstance;
+  defaultAccountId;
+  logger;
+  webhookSecret;
+  documents;
+  signers;
+  workspaces;
+  assignments;
+  webhooks;
+  templates;
+  tags;
+  auth;
+  fields;
+  signerDocuments;
+  webhookVerifier;
   constructor(options) {
     if (!options.apiKey && !options.token) {
       throw new ValidationError(
@@ -1393,6 +1812,10 @@ var AssinafyClient = class _AssinafyClient {
       timeout: options.timeout ?? 3e4,
       headers
     });
+    const maxRetries = options.maxRetries ?? 2;
+    if (maxRetries > 0) {
+      installRateLimitRetry(this.axiosInstance, maxRetries, this.logger);
+    }
     this.documents = new DocumentResource(this.axiosInstance, this.defaultAccountId, this.logger);
     this.signers = new SignerResource(this.axiosInstance, this.defaultAccountId, this.logger);
     this.workspaces = new WorkspaceResource(this.axiosInstance, void 0, this.logger);
@@ -1431,6 +1854,7 @@ var AssinafyClient = class _AssinafyClient {
     if (baseUrl !== void 0) opts.baseUrl = baseUrl;
     if (webhookSecret !== void 0) opts.webhookSecret = webhookSecret;
     if (config.timeout !== void 0) opts.timeout = config.timeout;
+    if (config.maxRetries !== void 0) opts.maxRetries = config.maxRetries;
     if (config.logger !== void 0) opts.logger = config.logger;
     return new _AssinafyClient(opts);
   }
@@ -1490,14 +1914,37 @@ var AssinafyClient = class _AssinafyClient {
 function normaliseBaseUrl(raw) {
   return raw.endsWith("/") ? raw.slice(0, -1) : raw;
 }
+function installRateLimitRetry(http, maxRetries, logger) {
+  http.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+      if (!axios2.isAxiosError(error) || error.response?.status !== 429 || !error.config) {
+        throw error;
+      }
+      const config = error.config;
+      const attempt = (config._retryCount ?? 0) + 1;
+      if (attempt > maxRetries) throw error;
+      config._retryCount = attempt;
+      const delayMs = nextRetryDelayMs(
+        error.response.headers,
+        attempt
+      );
+      logger.warn("Rate limited (429); retrying after delay", { attempt, maxRetries, delayMs });
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+      return http(config);
+    }
+  );
+}
 export {
   ApiError,
   AssignmentResource,
   AssinafyClient,
   AssinafyError,
   AuthenticationResource,
+  DEFAULT_WEBHOOK_EVENTS,
   DocumentResource,
   FieldsResource,
+  MAX_UPLOAD_BYTES,
   NetworkError,
   SignerDocumentsResource,
   SignerResource,