@assinafy/sdk 1.4.0 → 1.5.0

package/dist/index.js

@@ -35,6 +35,7 @@ __export(index_exports, {
   AssinafyClient: () => AssinafyClient,
   AssinafyError: () => AssinafyError,
   AuthenticationResource: () => AuthenticationResource,
+  DEFAULT_WEBHOOK_EVENTS: () => DEFAULT_WEBHOOK_EVENTS,
   DocumentResource: () => DocumentResource,
   FieldsResource: () => FieldsResource,
   NetworkError: () => NetworkError,
@@ -139,9 +140,40 @@ function cleanParams(params) {
   return out;
 }
 
-// src/resources/documents.ts
-var import_node_fs = require("fs");
-var import_node_path = __toESM(require("path"));
+// 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/base.ts
 var BaseResource = class {
@@ -246,8 +278,49 @@ function toInt(value) {
   return Number.isFinite(n) ? n : void 0;
 }
 
-// src/resources/documents.ts
+// src/resources/upload.ts
+var import_node_fs = require("fs");
+var import_node_path = __toESM(require("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 import_node_fs.promises.readFile(source.filePath);
+  return { buffer, fileName: source.fileName ?? import_node_path.default.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, options = {}) {
+  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", options.name ?? fileName);
+  if (options.metadata) {
+    form.append("metadata", JSON.stringify(options.metadata));
+  }
+  return form;
+}
+
+// src/resources/documents.ts
 var READY_STATUSES = /* @__PURE__ */ new Set([
   "metadata_ready",
   "pending_signature",
@@ -273,7 +346,9 @@ var DocumentResource = class extends BaseResource {
     const { buffer, fileName } = await loadSource(source);
     validateUpload(buffer, fileName);
     const accountId = this.accountId(options.accountId);
-    const form = buildUploadForm(buffer, fileName, options.metadata);
+    const formOptions = {};
+    if (options.metadata !== void 0) formOptions.metadata = options.metadata;
+    const form = buildUploadForm(buffer, fileName, formOptions);
     this.logger.info("Uploading document", { fileName, size: buffer.byteLength });
     const document = await this.call(
       "Document upload failed",
@@ -449,7 +524,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);
@@ -518,43 +598,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 import_node_fs.promises.readFile(source.filePath);
-  return { buffer, fileName: source.fileName ?? import_node_path.default.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));
 }
@@ -770,7 +813,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(
@@ -805,7 +856,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");
@@ -829,26 +884,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",
@@ -856,7 +895,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");
@@ -864,7 +917,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 });
@@ -929,6 +982,46 @@ 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 { buffer, fileName } = await loadSource(source);
+    validateUpload(buffer, fileName);
+    const id = this.accountId(options.accountId);
+    const formOptions = {};
+    if (options.name !== void 0) formOptions.name = options.name;
+    const form = buildUploadForm(buffer, fileName, formOptions);
+    this.logger.info("Creating template", { fileName, size: buffer.byteLength });
+    const template = await this.call(
+      "Failed to create template",
+      () => this.http.post(`/accounts/${id}/templates`, form, {
+        headers: { "Content-Type": "multipart/form-data" }
+      })
+    );
+    if (!template?.id) {
+      throw new ValidationError("Template upload succeeded but no template ID was returned", {
+        response: template
+      });
+    }
+    this.logger.info("Template created", { templateId: template.id });
+    return template;
+  }
   /** List templates for the workspace. */
   async list(params = {}, accountId) {
     const id = this.accountId(accountId);
@@ -938,11 +1031,10 @@ var TemplateResource = class extends BaseResource {
     );
   }
   /**
-   * 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`.
    */
   async get(templateId, accountId) {
     const id = this.accountId(accountId);
@@ -953,9 +1045,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);
@@ -1323,7 +1446,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(
@@ -1353,8 +1481,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");
@@ -1445,6 +1573,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);
@@ -1483,6 +1615,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);
   }
@@ -1542,6 +1675,27 @@ 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 (!import_axios2.default.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);
+    }
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ApiError,
@@ -1549,6 +1703,7 @@ function normaliseBaseUrl(raw) {
   AssinafyClient,
   AssinafyError,
   AuthenticationResource,
+  DEFAULT_WEBHOOK_EVENTS,
   DocumentResource,
   FieldsResource,
   NetworkError,