@signingstudio/sdk 1.0.0

package/dist/index.cjs

@@ -0,0 +1,696 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ApiError: () => ApiError,
+  AuthenticationError: () => AuthenticationError,
+  Documents: () => Documents,
+  NotFoundError: () => NotFoundError,
+  RateLimitError: () => RateLimitError,
+  SigningStudio: () => SigningStudio,
+  SigningStudioError: () => SigningStudioError,
+  Templates: () => Templates,
+  ValidationError: () => ValidationError,
+  verifyWebhook: () => verifyWebhook
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/http.ts
+var import_promises = require("timers/promises");
+var import_undici = require("undici");
+
+// src/errors/index.ts
+var SigningStudioError = class extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "SigningStudioError";
+    if (options?.cause !== void 0) {
+      this.cause = options.cause;
+    }
+  }
+};
+var ApiError = class extends SigningStudioError {
+  statusCode;
+  requestId;
+  body;
+  constructor(message, init) {
+    super(message);
+    this.name = "ApiError";
+    this.statusCode = init.statusCode;
+    this.requestId = init.requestId ?? null;
+    this.body = init.body ?? null;
+  }
+};
+var AuthenticationError = class extends ApiError {
+  constructor(message, init) {
+    super(message, init);
+    this.name = "AuthenticationError";
+  }
+};
+var NotFoundError = class extends ApiError {
+  constructor(message, init) {
+    super(message, init);
+    this.name = "NotFoundError";
+  }
+};
+var ValidationError = class extends ApiError {
+  errors;
+  constructor(message, init) {
+    super(message, init);
+    this.name = "ValidationError";
+    this.errors = init.errors;
+  }
+};
+var RateLimitError = class extends ApiError {
+  retryAfter;
+  window;
+  constructor(message, init) {
+    super(message, init);
+    this.name = "RateLimitError";
+    this.retryAfter = init.retryAfter;
+    this.window = init.window;
+  }
+};
+
+// src/http.ts
+var HttpClient = class {
+  opts;
+  constructor(opts) {
+    this.opts = {
+      ...opts,
+      fetchImpl: opts.fetchImpl ?? import_undici.request
+    };
+  }
+  /**
+   * JSON-returning request. Callers get the parsed data + envelope meta +
+   * rate-limit + request-id, or a typed error.
+   */
+  async requestJson(req) {
+    const raw = await this.execute(req, "json");
+    return raw;
+  }
+  /**
+   * Binary-returning request (PDF download). Skips JSON parsing; returns
+   * the raw body as a Uint8Array.
+   */
+  async requestBinary(req) {
+    const raw = await this.execute({ ...req, binary: true }, "binary");
+    return raw;
+  }
+  async execute(req, kind) {
+    const url = this.buildUrl(req.path, req.query);
+    const headers = {
+      authorization: `Bearer ${this.opts.apiKey}`,
+      accept: kind === "binary" ? "application/pdf, application/octet-stream, */*" : "application/json",
+      "user-agent": this.opts.userAgent
+    };
+    let body;
+    if (req.form !== void 0) {
+      body = req.form;
+    } else if (req.json !== void 0) {
+      body = JSON.stringify(req.json);
+      headers["content-type"] = "application/json";
+    }
+    let attempt = 0;
+    while (true) {
+      let response;
+      try {
+        response = await this.opts.fetchImpl(url, {
+          method: req.method,
+          headers,
+          // Only include `body` when we actually have one — undici's
+          // RequestOptions.body doesn't accept undefined under
+          // exactOptionalPropertyTypes, so conditional-spread it.
+          ...body !== void 0 ? { body } : {},
+          bodyTimeout: this.opts.requestTimeoutMs,
+          headersTimeout: this.opts.requestTimeoutMs
+        });
+      } catch (err) {
+        if (attempt >= this.opts.maxRetries) {
+          throw new SigningStudioError(
+            `Network error contacting Signing Studio: ${err.message}`,
+            { cause: err }
+          );
+        }
+        await (0, import_promises.setTimeout)(this.backoffMs(attempt));
+        attempt += 1;
+        continue;
+      }
+      const status = response.statusCode;
+      if (status >= 200 && status < 300) {
+        if (kind === "binary") {
+          return await this.readBinary(response);
+        }
+        return await this.parseSuccess(response, status);
+      }
+      if (status === 429 && attempt < this.opts.maxRetries) {
+        const retryAfter = this.extractRetryAfter(response);
+        if (retryAfter !== null && retryAfter <= 60) {
+          await (0, import_promises.setTimeout)(retryAfter * 1e3);
+          attempt += 1;
+          continue;
+        }
+      }
+      if (status >= 500 && attempt < this.opts.maxRetries) {
+        await (0, import_promises.setTimeout)(this.backoffMs(attempt));
+        attempt += 1;
+        continue;
+      }
+      throw await this.buildApiError(response, status);
+    }
+  }
+  buildUrl(path, query) {
+    const base = `${this.opts.baseUrl.replace(/\/$/, "")}/api/v1/`;
+    const url = new URL(path.replace(/^\/+/, ""), base);
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v === void 0 || v === null) continue;
+        url.searchParams.set(k, String(v));
+      }
+    }
+    return url.toString();
+  }
+  async parseSuccess(response, status) {
+    const bodyStr = await this.readText(response);
+    const requestId = this.headerString(response, "x-request-id");
+    if (bodyStr === "") {
+      return {
+        data: null,
+        meta: {},
+        requestId,
+        rateLimit: this.readRateLimit(response)
+      };
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(bodyStr);
+    } catch (err) {
+      throw new SigningStudioError(
+        `Malformed JSON in server response (HTTP ${status})`,
+        { cause: err }
+      );
+    }
+    const envelope = typeof parsed === "object" && parsed !== null ? parsed : {};
+    return {
+      data: envelope.data ?? null,
+      meta: typeof envelope.meta === "object" && envelope.meta !== null ? envelope.meta : {},
+      requestId,
+      rateLimit: this.readRateLimit(response)
+    };
+  }
+  readRateLimit(response) {
+    return {
+      remainingMinute: this.parseIntHeader(response, "x-ratelimit-remaining-minute"),
+      remainingDay: this.parseIntHeader(response, "x-ratelimit-remaining-day"),
+      limitMinute: this.parseIntHeader(response, "x-ratelimit-limit-minute"),
+      limitDay: this.parseIntHeader(response, "x-ratelimit-limit-day")
+    };
+  }
+  async buildApiError(response, status) {
+    let body = null;
+    let message = `Signing Studio API returned HTTP ${status}`;
+    let requestId = this.headerString(response, "x-request-id");
+    const raw = await this.readText(response);
+    if (raw !== "") {
+      try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" && parsed !== null) {
+          body = parsed;
+          if (typeof body.message === "string") message = body.message;
+          if (!requestId && typeof body.requestId === "string") requestId = body.requestId;
+        }
+      } catch {
+      }
+    }
+    const init = { statusCode: status, requestId, body };
+    switch (status) {
+      case 401:
+        return new AuthenticationError(message, init);
+      case 404:
+        return new NotFoundError(message, init);
+      case 422: {
+        const errors = body && typeof body.errors === "object" && body.errors !== null ? body.errors : {};
+        return new ValidationError(message, { ...init, errors });
+      }
+      case 429:
+        return new RateLimitError(message, {
+          ...init,
+          retryAfter: this.extractRetryAfter(response),
+          window: this.headerString(response, "x-ratelimit-window")
+        });
+      default:
+        return new ApiError(message, init);
+    }
+  }
+  extractRetryAfter(response) {
+    const raw = this.headerString(response, "retry-after");
+    if (raw === null) return null;
+    const n = Number(raw);
+    return Number.isFinite(n) ? Math.trunc(n) : null;
+  }
+  headerString(response, name) {
+    const value = response.headers[name];
+    if (value === void 0) return null;
+    if (Array.isArray(value)) return value[0] ?? null;
+    return String(value);
+  }
+  parseIntHeader(response, name) {
+    const s = this.headerString(response, name);
+    if (s === null) return null;
+    const n = Number(s);
+    return Number.isFinite(n) ? Math.trunc(n) : null;
+  }
+  async readText(response) {
+    try {
+      return await response.body.text();
+    } catch {
+      return "";
+    }
+  }
+  async readBinary(response) {
+    const chunks = [];
+    for await (const chunk of response.body) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return new Uint8Array(Buffer.concat(chunks));
+  }
+  /**
+   * Exponential backoff (500 ms · 1 s · 2 s · 4 s) plus a small jitter to
+   * avoid herd effects when many callers retry at once.
+   */
+  backoffMs(attempt) {
+    const base = 500 * 2 ** attempt;
+    const jitter = Math.floor(Math.random() * (base / 4));
+    return base + jitter;
+  }
+};
+
+// src/resources/documents.ts
+var Documents = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * List documents. All parameters are optional.
+   *
+   * The `view` toggle controls which lifecycle bucket to read from:
+   *   - `active`   (default) — non-archived, non-deleted
+   *   - `archived` — archived only
+   *   - `deleted`  — soft-deleted only
+   *   - `all`      — active + archived, still excludes trash
+   */
+  async list(params = {}) {
+    const response = await this.http.requestJson({
+      method: "GET",
+      path: "documents",
+      query: {
+        status: params.status,
+        view: params.view,
+        limit: params.limit,
+        offset: params.offset
+      }
+    });
+    return {
+      data: response.data ?? [],
+      meta: response.meta ?? {
+        total: 0,
+        limit: 50,
+        offset: 0,
+        view: params.view ?? "active"
+      }
+    };
+  }
+  /**
+   * Send a new document built from a template.
+   *
+   * Server-side rules to be aware of (surfaced as {@link import("../errors/index.js").ValidationError}):
+   *   - `template_id` is required.
+   *   - At least one recipient must be supplied.
+   *   - `prefill_values[]` needs either `field_id` or `field_name` + `value`.
+   *   - Signature / initials fields can't be prefilled.
+   *   - Any template field that is both required AND readonly must be prefilled.
+   *
+   * Successful sends count against the account's monthly document quota.
+   */
+  async send(payload) {
+    const response = await this.http.requestJson({
+      method: "POST",
+      path: "documents",
+      json: payload
+    });
+    return response.data;
+  }
+  async get(id) {
+    const response = await this.http.requestJson({
+      method: "GET",
+      path: `documents/${encodeURIComponent(id)}`
+    });
+    return response.data;
+  }
+  /**
+   * Delete a document. `hard: true` also purges the file from storage.
+   * Only valid on cancelled / completed / declined / expired documents;
+   * cancel first if the document is still in flight.
+   */
+  async delete(id, options = {}) {
+    const response = await this.http.requestJson({
+      method: "DELETE",
+      path: `documents/${encodeURIComponent(id)}`,
+      ...options.hard && { query: { hard: "true" } }
+    });
+    return response.data;
+  }
+  async restore(id) {
+    return (await this.http.requestJson({
+      method: "POST",
+      path: `documents/${encodeURIComponent(id)}/restore`
+    })).data;
+  }
+  async archive(id) {
+    return (await this.http.requestJson({
+      method: "POST",
+      path: `documents/${encodeURIComponent(id)}/archive`
+    })).data;
+  }
+  async unarchive(id) {
+    return (await this.http.requestJson({
+      method: "POST",
+      path: `documents/${encodeURIComponent(id)}/unarchive`
+    })).data;
+  }
+  async cancel(id) {
+    return (await this.http.requestJson({
+      method: "POST",
+      path: `documents/${encodeURIComponent(id)}/cancel`
+    })).data;
+  }
+  /**
+   * Read the current signing progress — cheaper than {@link get} when
+   * polling. Returns overall counts plus per-recipient state, no field
+   * or template data.
+   */
+  async progress(id) {
+    return (await this.http.requestJson({
+      method: "GET",
+      path: `documents/${encodeURIComponent(id)}/progress`
+    })).data;
+  }
+  /**
+   * Get a presigned download URL for the document PDF. For completed
+   * documents this is the flattened final PDF plus the audit-trail page;
+   * while in flight it's the in-progress snapshot (or source PDF if no
+   * signatures yet).
+   */
+  async downloadUrl(id) {
+    return (await this.http.requestJson({
+      method: "GET",
+      path: `documents/${encodeURIComponent(id)}/download`
+    })).data;
+  }
+  /**
+   * Fetch the document PDF as raw bytes in one call (follows the presigned
+   * URL redirect server-side). Handy for saving straight to disk.
+   */
+  async downloadPdf(id) {
+    return await this.http.requestBinary({
+      method: "GET",
+      path: `documents/${encodeURIComponent(id)}/download`,
+      query: { redirect: "1" }
+    });
+  }
+  async activity(id) {
+    const response = await this.http.requestJson({
+      method: "GET",
+      path: `documents/${encodeURIComponent(id)}/activity`
+    });
+    return response.data ?? [];
+  }
+  /**
+   * Re-send the signing invite (or first invite, if it hasn't gone out
+   * yet) to a specific recipient. Response includes a freshly-minted
+   * signing URL — this is the only endpoint where a URL is returned in
+   * plaintext, so capture it if you need to relay it out-of-band.
+   */
+  async remind(documentId, recipientId) {
+    return (await this.http.requestJson({
+      method: "POST",
+      path: `documents/${encodeURIComponent(documentId)}/recipients/${encodeURIComponent(recipientId)}/remind`
+    })).data;
+  }
+};
+
+// src/resources/templates.ts
+var import_promises2 = require("fs/promises");
+var import_undici2 = require("undici");
+var Templates = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  async list() {
+    const response = await this.http.requestJson({
+      method: "GET",
+      path: "templates"
+    });
+    return response.data ?? [];
+  }
+  /**
+   * Create a new template from a PDF plus metadata.
+   *
+   * The `pdf` argument can be a filesystem path, a Uint8Array/Buffer of
+   * raw bytes, a Blob, or an object with an explicit filename. See
+   * {@link PdfInput}.
+   */
+  async create(pdf, metadata, options = {}) {
+    const form = await this.buildPdfForm(pdf, options.filename, metadata);
+    const response = await this.http.requestJson({
+      method: "POST",
+      path: "templates",
+      form
+    });
+    return response.data;
+  }
+  async get(id) {
+    return (await this.http.requestJson({
+      method: "GET",
+      path: `templates/${encodeURIComponent(id)}`
+    })).data;
+  }
+  async update(id, metadata) {
+    return (await this.http.requestJson({
+      method: "PATCH",
+      path: `templates/${encodeURIComponent(id)}`,
+      json: metadata
+    })).data;
+  }
+  /**
+   * Soft-delete. There is no hard-delete on this route; contact support
+   * if you need permanent removal.
+   */
+  async delete(id) {
+    return (await this.http.requestJson({
+      method: "DELETE",
+      path: `templates/${encodeURIComponent(id)}`
+    })).data;
+  }
+  async pdfUrl(id) {
+    return (await this.http.requestJson({
+      method: "GET",
+      path: `templates/${encodeURIComponent(id)}/pdf`
+    })).data;
+  }
+  async downloadPdf(id) {
+    return await this.http.requestBinary({
+      method: "GET",
+      path: `templates/${encodeURIComponent(id)}/pdf`,
+      query: { redirect: "1" }
+    });
+  }
+  /**
+   * Replace the template's PDF. Prior versions are kept in history —
+   * download via {@link historyPdfUrl}.
+   */
+  async replacePdf(id, pdf, options = {}) {
+    const form = await this.buildPdfForm(pdf, options.filename);
+    return (await this.http.requestJson({
+      method: "PUT",
+      path: `templates/${encodeURIComponent(id)}/pdf`,
+      form
+    })).data;
+  }
+  /**
+   * Replace ALL fields on the template. The server deletes existing rows
+   * and inserts the supplied set — the SDK does not support partial
+   * updates because the server doesn't.
+   */
+  async setFields(id, fields) {
+    const response = await this.http.requestJson({
+      method: "PUT",
+      path: `templates/${encodeURIComponent(id)}/fields`,
+      json: { fields }
+    });
+    return response.data ?? [];
+  }
+  async duplicate(id) {
+    return (await this.http.requestJson({
+      method: "POST",
+      path: `templates/${encodeURIComponent(id)}/duplicate`
+    })).data;
+  }
+  async archive(id) {
+    return (await this.http.requestJson({
+      method: "POST",
+      path: `templates/${encodeURIComponent(id)}/archive`
+    })).data;
+  }
+  async history(id) {
+    const response = await this.http.requestJson({
+      method: "GET",
+      path: `templates/${encodeURIComponent(id)}/history`
+    });
+    return response.data ?? [];
+  }
+  async historyPdfUrl(templateId, historyId) {
+    return (await this.http.requestJson({
+      method: "GET",
+      path: `templates/${encodeURIComponent(templateId)}/history/${historyId}/pdf`
+    })).data;
+  }
+  async downloadHistoryPdf(templateId, historyId) {
+    return await this.http.requestBinary({
+      method: "GET",
+      path: `templates/${encodeURIComponent(templateId)}/history/${historyId}/pdf`,
+      query: { redirect: "1" }
+    });
+  }
+  /**
+   * Build the multipart form: PDF blob under field name `file` (required
+   * by the server) + JSON-encoded scalar/array metadata fields.
+   *
+   * Nested arrays/objects (like `signers`, `delivery_methods`) are
+   * serialized with JSON.stringify so they survive the form-data trip —
+   * the server route unwraps them.
+   */
+  async buildPdfForm(pdf, filenameOverride, metadata) {
+    const form = new import_undici2.FormData();
+    if (metadata) {
+      for (const [key, value] of Object.entries(metadata)) {
+        if (value === void 0 || value === null) continue;
+        const encoded = typeof value === "string" ? value : JSON.stringify(value);
+        form.append(key, encoded);
+      }
+    }
+    const { blob, filename } = await this.resolvePdf(pdf, filenameOverride);
+    form.append("file", blob, filename);
+    return form;
+  }
+  async resolvePdf(pdf, override) {
+    if (typeof pdf === "string") {
+      const data = await (0, import_promises2.readFile)(pdf);
+      return {
+        blob: new Blob([data], { type: "application/pdf" }),
+        filename: override ?? basename(pdf)
+      };
+    }
+    if (pdf instanceof Uint8Array) {
+      return {
+        blob: new Blob([pdf], { type: "application/pdf" }),
+        filename: override ?? "template.pdf"
+      };
+    }
+    if (pdf instanceof Blob) {
+      return { blob: pdf, filename: override ?? "template.pdf" };
+    }
+    if ("path" in pdf) {
+      const data = await (0, import_promises2.readFile)(pdf.path);
+      return {
+        blob: new Blob([data], { type: "application/pdf" }),
+        filename: override ?? basename(pdf.path)
+      };
+    }
+    return {
+      blob: new Blob([pdf.data], { type: pdf.contentType ?? "application/pdf" }),
+      filename: override ?? pdf.filename ?? "template.pdf"
+    };
+  }
+};
+function basename(p) {
+  const trimmed = p.replace(/[\\/]+$/, "");
+  const idx = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
+  return idx === -1 ? trimmed : trimmed.slice(idx + 1);
+}
+
+// src/client.ts
+var SigningStudio = class {
+  documents;
+  templates;
+  /** Escape hatch — the raw HTTP layer for callers that need to consume
+   *  headers (rate-limit remaining, request id) alongside the parsed data. */
+  http;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new TypeError("SigningStudio: `apiKey` is required");
+    }
+    this.http = new HttpClient({
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl ?? "https://api.signingstudio.com",
+      maxRetries: options.maxRetries ?? 3,
+      requestTimeoutMs: options.requestTimeoutMs ?? 12e4,
+      userAgent: options.userAgent ?? "signingstudio-node/1.0",
+      fetchImpl: options.fetchImpl ?? void 0
+    });
+    this.documents = new Documents(this.http);
+    this.templates = new Templates(this.http);
+  }
+};
+
+// src/webhooks.ts
+var import_node_crypto = require("crypto");
+var import_node_buffer = require("buffer");
+function verifyWebhook(rawBody, header, secret) {
+  if (!secret || typeof secret !== "string") {
+    throw new TypeError("verifyWebhook: secret must be a non-empty string");
+  }
+  if (header == null || header === "") return false;
+  const received = header.startsWith("sha256=") ? header.slice("sha256=".length) : header;
+  if (received.length !== 64 || !/^[0-9a-f]+$/i.test(received)) return false;
+  const bodyBuf = typeof rawBody === "string" ? import_node_buffer.Buffer.from(rawBody, "utf8") : import_node_buffer.Buffer.from(rawBody);
+  const expected = (0, import_node_crypto.createHmac)("sha256", secret).update(bodyBuf).digest("hex");
+  const receivedBuf = import_node_buffer.Buffer.from(received, "hex");
+  const expectedBuf = import_node_buffer.Buffer.from(expected, "hex");
+  if (receivedBuf.length !== expectedBuf.length) return false;
+  return (0, import_node_crypto.timingSafeEqual)(expectedBuf, receivedBuf);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiError,
+  AuthenticationError,
+  Documents,
+  NotFoundError,
+  RateLimitError,
+  SigningStudio,
+  SigningStudioError,
+  Templates,
+  ValidationError,
+  verifyWebhook
+});
+//# sourceMappingURL=index.cjs.map