@signingstudio/sdk 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,702 @@
+import { request, FormData } from 'undici';
+import { Buffer } from 'node:buffer';
+
+interface HttpClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    maxRetries: number;
+    requestTimeoutMs: number;
+    userAgent: string;
+    /** Test seam — overridable fetch-like transport for the test suite. */
+    fetchImpl?: FetchFn;
+}
+/**
+ * Minimal fetch surface the SDK consumes. Undici's `request` fits this
+ * shape; tests use a mocked implementation.
+ */
+type FetchFn = typeof request;
+/**
+ * Successful response with the envelope unwrapped and rate-limit metadata
+ * hoisted to typed fields for easy access.
+ */
+interface ApiResponse<T> {
+    data: T;
+    meta: Record<string, unknown>;
+    requestId: string | null;
+    rateLimit: {
+        remainingMinute: number | null;
+        remainingDay: number | null;
+        limitMinute: number | null;
+        limitDay: number | null;
+    };
+}
+interface RequestOptions {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    query?: Record<string, string | number | boolean | undefined | null>;
+    json?: unknown;
+    /**
+     * Multipart body — passed straight to undici. Provide a FormData with
+     * one entry per field; PDF upload fields must be named `file`.
+     */
+    form?: FormData;
+    /**
+     * If true, the raw response body is returned as a Uint8Array instead of
+     * being decoded as JSON. Used for the `?redirect=1` PDF download endpoints.
+     */
+    binary?: boolean;
+}
+/**
+ * HTTP transport for the SDK. Wraps undici with:
+ *   - Authorization header injection
+ *   - JSON / multipart body handling
+ *   - Envelope unwrap ({ success, data, meta })
+ *   - Status → typed error mapping
+ *   - Bounded retry on 429 (with Retry-After ≤ 60s) + 5xx + network errors
+ */
+declare class HttpClient {
+    private readonly opts;
+    constructor(opts: HttpClientOptions);
+    /**
+     * JSON-returning request. Callers get the parsed data + envelope meta +
+     * rate-limit + request-id, or a typed error.
+     */
+    requestJson<T>(req: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Binary-returning request (PDF download). Skips JSON parsing; returns
+     * the raw body as a Uint8Array.
+     */
+    requestBinary(req: RequestOptions): Promise<Uint8Array>;
+    private execute;
+    private buildUrl;
+    private parseSuccess;
+    private readRateLimit;
+    private buildApiError;
+    private extractRetryAfter;
+    private headerString;
+    private parseIntHeader;
+    private readText;
+    private readBinary;
+    /**
+     * Exponential backoff (500 ms · 1 s · 2 s · 4 s) plus a small jitter to
+     * avoid herd effects when many callers retry at once.
+     */
+    private backoffMs;
+}
+
+/**
+ * Response types for the Signing Studio v1 REST API.
+ *
+ * These interfaces mirror the exact JSON shapes the server returns. The
+ * runtime SDK does no coercion beyond parsing the outer `{ success, data,
+ * meta }` envelope — callers that receive an object shaped by these types
+ * are looking at what the server actually sent.
+ *
+ * Field-level nullability follows the server: `string | null` means the
+ * server may emit `null`; a missing `| null` means the server always emits
+ * the field. Optionality (`?`) is only used when the SDK builds a request
+ * object; response types are exhaustive.
+ */
+type DocumentStatus = "draft" | "sent" | "viewed" | "completed" | "declined" | "cancelled" | "expired";
+type RecipientStatus = "pending" | "sent" | "viewed" | "signed" | "declined";
+type ListView = "active" | "archived" | "deleted" | "all";
+/**
+ * Fields on the list endpoint — a lighter subset than the detail view.
+ * See {@link DocumentDetail} for the full shape.
+ */
+interface DocumentListItem {
+    id: string;
+    title: string;
+    status: DocumentStatus;
+    file_name: string;
+    page_count: number;
+    created_at: string;
+    sent_at: string | null;
+    completed_at: string | null;
+    expires_at: string | null;
+    is_archived: 0 | 1;
+    is_deleted: 0 | 1;
+    template_id: string | null;
+}
+interface DocumentListParams {
+    status?: DocumentStatus;
+    view?: ListView;
+    limit?: number;
+    offset?: number;
+}
+interface DocumentListMeta {
+    total: number;
+    limit: number;
+    offset: number;
+    view: string;
+}
+interface DocumentListResponse {
+    data: DocumentListItem[];
+    meta: DocumentListMeta;
+}
+type FieldType = "signature" | "initials" | "text" | "date" | "checkbox" | "radio" | "dropdown" | "email" | "phone" | "label";
+interface DocumentField {
+    id: string;
+    document_id: string;
+    field_type: FieldType;
+    page: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    label: string | null;
+    name: string | null;
+    placeholder: string | null;
+    required: 0 | 1;
+    readonly: 0 | 1;
+    signer_index: number;
+    options: string | null;
+    value: string | null;
+}
+interface Recipient {
+    id: string;
+    name: string;
+    email: string;
+    phone: string | null;
+    signing_order: number;
+    status: RecipientStatus;
+    viewed_at: string | null;
+    signed_at: string | null;
+    declined_at: string | null;
+    decline_reason: string | null;
+    role: string | null;
+    delivery: Array<"email" | "sms">;
+    /** Always null on the detail view. Use `remind()` to mint a fresh URL. */
+    signing_url: null;
+    signing_url_expires_at: string | null;
+    signing_url_used: boolean;
+}
+interface DocumentTemplateSummary {
+    id: string;
+    name: string;
+    signer_count: number;
+    signers: TemplateSigner[];
+    delivery_methods: Array<"email" | "sms" | "webhook">;
+    webhook_id: number | null;
+    default_subject: string | null;
+    default_message: string | null;
+}
+interface DocumentDetail {
+    id: string;
+    title: string;
+    status: DocumentStatus;
+    message: string | null;
+    email_subject: string | null;
+    instructions: string | null;
+    email_from_name: string | null;
+    email_from_address: string | null;
+    email_body_template: string | null;
+    sms_body_template: string | null;
+    file_name: string;
+    file_size: number;
+    page_count: number;
+    expires_at: string | null;
+    sent_at: string | null;
+    completed_at: string | null;
+    created_at: string;
+    updated_at: string;
+    is_archived: 0 | 1;
+    is_deleted: 0 | 1;
+    reminder_enabled: 0 | 1;
+    reminder_interval_days: number | null;
+    last_reminder_sent_at: string | null;
+    created_by_name: string | null;
+    fields: DocumentField[];
+    recipients: Recipient[];
+    fileUrl: string;
+    template: DocumentTemplateSummary | null;
+}
+interface DocumentProgress {
+    document_id: string;
+    status: DocumentStatus;
+    sent_at: string | null;
+    completed_at: string | null;
+    expires_at: string | null;
+    progress: {
+        total: number;
+        signed: number;
+        declined: number;
+        viewed: number;
+        pending: number;
+        percent_complete: number;
+    };
+    recipients: Array<Pick<Recipient, "id" | "name" | "email" | "signing_order" | "status" | "viewed_at" | "signed_at" | "declined_at" | "decline_reason">>;
+}
+/** One row from the audit log. */
+interface ActivityEntry {
+    id: number;
+    account_id: number;
+    user_id: number | null;
+    entity_type: "document" | "signing";
+    entity_id: number;
+    action: string;
+    metadata: Record<string, unknown> | null;
+    ip_address: string | null;
+    user_agent: string | null;
+    created_at: string;
+    user_name: string | null;
+    user_email: string | null;
+}
+interface SendPrefillValue {
+    /** Either `field_id` (uuid) OR `field_name` must be set. */
+    field_id?: string;
+    field_name?: string;
+    value: string;
+}
+interface SendRecipient {
+    name: string;
+    email: string;
+    phone?: string;
+    /** 0-indexed. First to sign in a sequential chain is `0`. */
+    signing_order?: number;
+    role?: string;
+    email_subject?: string;
+    email_body_template?: string;
+    sms_body_template?: string;
+    email_from_name?: string;
+}
+interface SendDocumentPayload {
+    template_id: string;
+    title: string;
+    message?: string;
+    subject?: string;
+    expires_at?: string;
+    recipients: SendRecipient[];
+    prefill_values?: SendPrefillValue[];
+    instructions?: string;
+    email_from_name?: string;
+    email_from_address?: string;
+    email_body_template?: string;
+    sms_body_template?: string;
+}
+interface RemindResponse {
+    success: true;
+    signing_url: string;
+}
+interface SuccessAck {
+    success: true;
+}
+interface DeleteResponse extends SuccessAck {
+    mode: "soft" | "hard";
+}
+interface PresignedUrl {
+    url: string;
+}
+interface TemplateSigner {
+    role?: string;
+    default_name?: string;
+    default_email?: string;
+    delivery?: Array<"email" | "sms">;
+    email_subject?: string;
+    email_body_template?: string;
+    sms_body_template?: string;
+    email_from_name?: string;
+}
+interface TemplateListItem {
+    id: string;
+    name: string;
+    description: string | null;
+    file_name: string;
+    page_count: number;
+    created_at: string;
+    signer_count: number;
+    delivery_methods: Array<"email" | "sms" | "webhook">;
+    is_archived: 0 | 1;
+    created_by_name: string | null;
+}
+interface TemplateField {
+    id: string;
+    field_type: FieldType;
+    page: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    label: string | null;
+    name: string | null;
+    placeholder: string | null;
+    required: 0 | 1;
+    readonly: 0 | 1;
+    signer_index: number;
+    options: string | null;
+}
+interface TemplateDetail {
+    id: string;
+    name: string;
+    description: string | null;
+    file_key: string;
+    file_name: string;
+    file_size: number;
+    page_count: number;
+    signer_count: number;
+    signers: TemplateSigner[];
+    delivery_methods: Array<"email" | "sms" | "webhook">;
+    webhook_id: number | null;
+    default_subject: string | null;
+    default_message: string | null;
+    email_from_name: string | null;
+    email_from_address: string | null;
+    email_body_template: string | null;
+    sms_body_template: string | null;
+    default_instructions: string | null;
+    is_archived: 0 | 1;
+    is_deleted: 0 | 1;
+    created_at: string;
+    updated_at: string;
+    created_by_name: string | null;
+    fields: TemplateField[];
+    fileUrl: string;
+}
+/** Metadata payload accepted by create + update. */
+interface TemplateMetadata {
+    name?: string;
+    description?: string;
+    signer_count?: number;
+    signers?: TemplateSigner[];
+    delivery_methods?: Array<"email" | "sms" | "webhook">;
+    webhook_id?: number | null;
+    default_subject?: string;
+    default_message?: string;
+    email_from_name?: string;
+    email_from_address?: string;
+    email_body_template?: string;
+    sms_body_template?: string;
+    default_instructions?: string;
+}
+/**
+ * Field-editing shape. Wider than {@link TemplateField} — the input allows
+ * `options` as a real array (server-side it's persisted as a JSON string).
+ */
+interface TemplateFieldInput {
+    field_type: FieldType;
+    page: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    label?: string;
+    name?: string;
+    placeholder?: string;
+    required?: boolean;
+    readonly?: boolean;
+    signer_index?: number;
+    options?: string[];
+}
+interface TemplateHistoryEntry {
+    id: number;
+    file_name: string;
+    file_size: number;
+    page_count: number;
+    replaced_at: string;
+    replaced_by_name: string | null;
+}
+type WebhookEvent = "document.sent" | "document.viewed" | "document.signed" | "document.declined" | "document.completed";
+interface WebhookPayload {
+    event: WebhookEvent;
+    data: {
+        document: {
+            id: string;
+            title: string;
+            status: DocumentStatus;
+            template_id: string | null;
+            sent_at: string | null;
+            completed_at: string | null;
+        };
+        download_url: string | null;
+        download_expires_in_seconds: number;
+        recipients: Array<Pick<Recipient, "id" | "name" | "email" | "signing_order" | "status" | "viewed_at" | "signed_at" | "declined_at" | "decline_reason">>;
+        [k: string]: unknown;
+    };
+    timestamp: string;
+}
+
+/**
+ * Documents resource — send documents from templates, poll status,
+ * download completed PDFs, remind signers.
+ *
+ * Every method returns the parsed data payload. If you need the full
+ * envelope (rate-limit headers, request id) drop down to
+ * `client.http.requestJson`.
+ */
+declare class Documents {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * 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
+     */
+    list(params?: DocumentListParams): Promise<DocumentListResponse>;
+    /**
+     * 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.
+     */
+    send(payload: SendDocumentPayload): Promise<DocumentDetail>;
+    get(id: string): Promise<DocumentDetail>;
+    /**
+     * 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.
+     */
+    delete(id: string, options?: {
+        hard?: boolean;
+    }): Promise<DeleteResponse>;
+    restore(id: string): Promise<SuccessAck>;
+    archive(id: string): Promise<SuccessAck>;
+    unarchive(id: string): Promise<SuccessAck>;
+    cancel(id: string): Promise<SuccessAck>;
+    /**
+     * Read the current signing progress — cheaper than {@link get} when
+     * polling. Returns overall counts plus per-recipient state, no field
+     * or template data.
+     */
+    progress(id: string): Promise<DocumentProgress>;
+    /**
+     * 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).
+     */
+    downloadUrl(id: string): Promise<PresignedUrl>;
+    /**
+     * Fetch the document PDF as raw bytes in one call (follows the presigned
+     * URL redirect server-side). Handy for saving straight to disk.
+     */
+    downloadPdf(id: string): Promise<Uint8Array>;
+    activity(id: string): Promise<ActivityEntry[]>;
+    /**
+     * 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.
+     */
+    remind(documentId: string, recipientId: string): Promise<RemindResponse>;
+}
+
+/** Anything the SDK accepts as a PDF payload. */
+type PdfInput = string | Uint8Array | Buffer | Blob | {
+    path: string;
+} | {
+    data: Uint8Array | Buffer;
+    filename?: string;
+    contentType?: string;
+};
+/**
+ * Templates resource — create / update / version PDF templates.
+ *
+ * PDF upload constraints (server-enforced, 400 on violation):
+ *   - Max 50 MB per file
+ *   - `application/pdf` only
+ *   - Multipart form field must be `file` — the SDK sets this for you
+ */
+declare class Templates {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(): Promise<TemplateListItem[]>;
+    /**
+     * 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}.
+     */
+    create(pdf: PdfInput, metadata: TemplateMetadata, options?: {
+        filename?: string;
+    }): Promise<TemplateDetail>;
+    get(id: string): Promise<TemplateDetail>;
+    update(id: string, metadata: TemplateMetadata): Promise<TemplateDetail>;
+    /**
+     * Soft-delete. There is no hard-delete on this route; contact support
+     * if you need permanent removal.
+     */
+    delete(id: string): Promise<SuccessAck>;
+    pdfUrl(id: string): Promise<PresignedUrl>;
+    downloadPdf(id: string): Promise<Uint8Array>;
+    /**
+     * Replace the template's PDF. Prior versions are kept in history —
+     * download via {@link historyPdfUrl}.
+     */
+    replacePdf(id: string, pdf: PdfInput, options?: {
+        filename?: string;
+    }): Promise<TemplateDetail>;
+    /**
+     * 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.
+     */
+    setFields(id: string, fields: TemplateFieldInput[]): Promise<TemplateField[]>;
+    duplicate(id: string): Promise<TemplateDetail>;
+    archive(id: string): Promise<SuccessAck>;
+    history(id: string): Promise<TemplateHistoryEntry[]>;
+    historyPdfUrl(templateId: string, historyId: number): Promise<PresignedUrl>;
+    downloadHistoryPdf(templateId: string, historyId: number): Promise<Uint8Array>;
+    /**
+     * 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.
+     */
+    private buildPdfForm;
+    private resolvePdf;
+}
+
+interface ClientOptions {
+    /** Your API key from Signing Studio → Settings → API Keys. Required. */
+    apiKey: string;
+    /** Override for staging / self-hosted deployments. Default: production. */
+    baseUrl?: string;
+    /** How many times to retry transient failures (429 short Retry-After, 5xx, network). Default 3. */
+    maxRetries?: number;
+    /** Full request-timeout in milliseconds — generous by default so a 50 MB PDF upload has time to finish. */
+    requestTimeoutMs?: number;
+    /** Custom User-Agent — replace or extend with your app's identifier. */
+    userAgent?: string;
+    /**
+     * Test-only seam. Replace the transport with a mocked implementation
+     * in the test suite. Undici's `request` fits by default.
+     */
+    fetchImpl?: FetchFn;
+}
+/**
+ * Top-level entry point for the Signing Studio Node.js SDK.
+ *
+ *   import { SigningStudio } from "@signingstudio/sdk";
+ *
+ *   const client = new SigningStudio({ apiKey: process.env.SIGNING_STUDIO_API_KEY! });
+ *   const doc = await client.documents.send({
+ *     template_id: "…",
+ *     title: "MSA — Acme",
+ *     recipients: [{ name: "Alex", email: "alex@acme.com" }],
+ *   });
+ *
+ * The Client is safe to reuse across concurrent requests. Undici keeps an
+ * internal connection pool per host, which is the recommended shape for
+ * long-running processes (workers, cron, servers).
+ */
+declare class SigningStudio {
+    readonly documents: Documents;
+    readonly templates: Templates;
+    /** Escape hatch — the raw HTTP layer for callers that need to consume
+     *  headers (rate-limit remaining, request id) alongside the parsed data. */
+    readonly http: HttpClient;
+    constructor(options: ClientOptions);
+}
+
+/**
+ * Verify an incoming Signing Studio webhook delivery.
+ *
+ * The server signs the raw JSON body with HMAC-SHA256 keyed on the
+ * webhook's secret and sends it as `X-DDS-Signature: sha256=<hex>`.
+ *
+ * Usage (Express-style example):
+ *
+ *   import express from "express";
+ *   import { verifyWebhook } from "@signingstudio/sdk";
+ *
+ *   const app = express();
+ *   app.post("/webhooks/signing-studio",
+ *     express.raw({ type: "application/json" }),  // do NOT pre-parse
+ *     (req, res) => {
+ *       const ok = verifyWebhook(req.body, req.get("X-DDS-Signature"), SECRET);
+ *       if (!ok) return res.status(401).end();
+ *       const payload = JSON.parse(req.body.toString("utf8"));
+ *       // ...act on payload.event
+ *       res.status(200).end();
+ *     }
+ *   );
+ *
+ * You MUST pass the RAW body — a parsed & re-serialized body will fail
+ * verification, even if it looks identical.
+ */
+declare function verifyWebhook(rawBody: string | Uint8Array | Buffer, header: string | null | undefined, secret: string): boolean;
+
+/**
+ * Every exception the SDK throws extends {@link SigningStudioError}, so
+ * integrators can catch a single type at the outer boundary of their code
+ * and inspect the subclass for specifics.
+ *
+ *   try {
+ *     await client.documents.send(payload);
+ *   } catch (err) {
+ *     if (err instanceof ValidationError) { /* field-map available *​/ }
+ *     if (err instanceof RateLimitError)  { /* retryAfter, window   *​/ }
+ *     if (err instanceof SigningStudioError) { /* fallback          *​/ }
+ *     throw err;
+ *   }
+ */
+declare class SigningStudioError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+interface ApiErrorInit {
+    statusCode: number;
+    requestId?: string | null;
+    body?: Record<string, unknown> | null;
+}
+/**
+ * Non-2xx HTTP response from the API. Carries the parsed error envelope,
+ * the request id (for support tickets), and the status code (for
+ * programmatic branching).
+ */
+declare class ApiError extends SigningStudioError {
+    readonly statusCode: number;
+    readonly requestId: string | null;
+    readonly body: Record<string, unknown> | null;
+    constructor(message: string, init: ApiErrorInit);
+}
+/** HTTP 401 — API key missing, unknown, or the account behind it is inactive. */
+declare class AuthenticationError extends ApiError {
+    constructor(message: string, init: ApiErrorInit);
+}
+/** HTTP 404 — resource does not exist under the caller's account. */
+declare class NotFoundError extends ApiError {
+    constructor(message: string, init: ApiErrorInit);
+}
+interface ValidationErrorInit extends ApiErrorInit {
+    errors: Record<string, string[]>;
+}
+/**
+ * HTTP 422 — Zod-level or business-rule validation failure. `errors` is
+ * the field-name → messages map from the server; empty when the failure
+ * was purely business-rule (e.g. prefill of a signature field).
+ */
+declare class ValidationError extends ApiError {
+    readonly errors: Record<string, string[]>;
+    constructor(message: string, init: ValidationErrorInit);
+}
+interface RateLimitErrorInit extends ApiErrorInit {
+    retryAfter: number | null;
+    window: string | null;
+}
+/**
+ * HTTP 429 — rate limit or monthly quota. `retryAfter` is present for
+ * sliding-window rate limits (seconds until safe to retry) and null for
+ * monthly quota exhaustion.
+ */
+declare class RateLimitError extends ApiError {
+    readonly retryAfter: number | null;
+    readonly window: string | null;
+    constructor(message: string, init: RateLimitErrorInit);
+}
+
+export { type ActivityEntry, ApiError, AuthenticationError, type ClientOptions, type DeleteResponse, type DocumentDetail, type DocumentField, type DocumentListItem, type DocumentListMeta, type DocumentListParams, type DocumentListResponse, type DocumentProgress, type DocumentStatus, type DocumentTemplateSummary, Documents, type FieldType, type ListView, NotFoundError, type PdfInput, type PresignedUrl, RateLimitError, type Recipient, type RecipientStatus, type RemindResponse, type SendDocumentPayload, type SendPrefillValue, type SendRecipient, SigningStudio, SigningStudioError, type SuccessAck, type TemplateDetail, type TemplateField, type TemplateFieldInput, type TemplateHistoryEntry, type TemplateListItem, type TemplateMetadata, type TemplateSigner, Templates, ValidationError, type WebhookEvent, type WebhookPayload, verifyWebhook };