@signingstudio/sdk 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `@signingstudio/sdk` are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0] — 2026-07-20
+
+Initial public release. Covers 100% of the Signing Studio v1 REST API.
+
+### Added
+- `SigningStudio` client with `documents` and `templates` resources.
+- Full TypeScript typings for every request and response shape.
+- `Documents` resource: list, send, get, delete (soft + hard), restore, archive, unarchive, cancel, progress, download URL, download PDF, activity, remind.
+- `Templates` resource: list, create (PDF upload), get, update, delete, PDF URL, download PDF, replace PDF, set fields, duplicate, archive, history, history-PDF download.
+- `verifyWebhook` helper — constant-time HMAC-SHA256 signature check.
+- Typed error hierarchy: `SigningStudioError` → `ApiError` → `AuthenticationError`, `NotFoundError`, `ValidationError`, `RateLimitError`.
+- Bounded retry policy — 429 (with Retry-After ≤ 60s), 5xx, and transport errors are retried with exponential backoff.
+- Dual ESM + CJS build with source maps.
+- Vitest test suite covering the HTTP transport, resources, and webhook verifier.
+- GitHub Actions CI on Node 18 / 20 / 22, publish workflow with npm provenance.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Signing Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# Signing Studio Node.js SDK
+
+[![CI](https://github.com/alyasdds/signingstudio-node/actions/workflows/ci.yml/badge.svg)](https://github.com/alyasdds/signingstudio-node/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@signingstudio/sdk.svg)](https://www.npmjs.com/package/@signingstudio/sdk)
+[![License](https://img.shields.io/npm/l/@signingstudio/sdk.svg)](LICENSE)
+
+Official Node.js / TypeScript client for the **[Signing Studio](https://signingstudio.com)** e-signature API. Covers every public v1 endpoint — send documents from templates, poll signing progress, manage templates and their fields, and verify webhook deliveries.
+
+Ships as ESM + CJS with full TypeScript typings. Node **18+**.
+
+## Install
+
+```bash
+npm  install @signingstudio/sdk
+pnpm add @signingstudio/sdk
+yarn add @signingstudio/sdk
+```
+
+## Quick start
+
+```ts
+import { SigningStudio } from "@signingstudio/sdk";
+
+const client = new SigningStudio({ apiKey: process.env.SIGNING_STUDIO_API_KEY! });
+
+const doc = await client.documents.send({
+  template_id: "11111111-2222-3333-4444-555555555555",
+  title: "MSA — Acme",
+  recipients: [{ name: "Alex Doe", email: "alex@acme.com" }],
+});
+
+console.log(`Sent ${doc.id} (${doc.status})`);
+```
+
+Get your API key from **Signing Studio → Settings → API Keys**. The plaintext key is shown once at creation — store it in a secrets manager.
+
+## Configuration
+
+```ts
+new SigningStudio({
+  apiKey: "sk_live_...",
+  baseUrl: "https://api.signingstudio.com",   // default
+  maxRetries: 3,                              // 429 + 5xx + network
+  requestTimeoutMs: 120_000,                  // per request
+  userAgent: "my-app/1.4",
+});
+```
+
+**Retry policy** — conservative and predictable:
+- **429** with `Retry-After ≤ 60s` → sleep and retry, up to `maxRetries`.
+- **429** with `Retry-After > 60s` (typically monthly quota) → throw `RateLimitError` immediately.
+- **5xx** and **network errors** → exponential backoff (500ms · 1s · 2s · 4s) with jitter.
+
+## Documents
+
+```ts
+// List
+const list = await client.documents.list({ status: "sent", view: "active", limit: 50 });
+
+// Send from a template
+const doc = await client.documents.send({
+  template_id,
+  title: "MSA — Acme",
+  subject: "Please sign",
+  message: "Signing at your convenience",
+  expires_at: "2026-08-01T00:00:00Z",
+  recipients: [
+    { name: "Alex", email: "alex@acme.com", signing_order: 0 },
+    { name: "Bo",   email: "bo@acme.com",   signing_order: 1 },
+  ],
+  prefill_values: [{ field_name: "company", value: "Acme Inc." }],
+});
+
+// Read
+await client.documents.get(id);
+await client.documents.progress(id);           // cheap; ideal for polling
+await client.documents.activity(id);
+
+// Actions
+await client.documents.cancel(id);
+await client.documents.archive(id);
+await client.documents.unarchive(id);
+await client.documents.restore(id);
+await client.documents.delete(id);             // soft
+await client.documents.delete(id, { hard: true });
+
+// Reminder — mints a fresh signing URL for a specific recipient
+const { signing_url } = await client.documents.remind(documentId, recipientId);
+
+// Download
+const { url } = await client.documents.downloadUrl(id);   // presigned URL
+const bytes    = await client.documents.downloadPdf(id);  // Uint8Array
+```
+
+### Send-payload rules the server enforces
+
+- `template_id` is required; ad-hoc PDF sends without a template are not exposed on v1.
+- `recipients` must have at least one entry. Sequential signing runs in `signing_order`.
+- `prefill_values[]` must have either `field_id` (uuid) or a non-empty `field_name` slug plus a `value`.
+- Signature / initials fields cannot be prefilled — 422 if attempted.
+- Any template field that is both `required` and `readonly` MUST be prefilled — 422 with a list of missing labels.
+- Sends count against the account's monthly `documents_per_month` quota — 429 when tripped.
+
+## Templates
+
+```ts
+// List active templates
+const templates = await client.templates.list();
+
+// Create from a PDF — path, Buffer/Uint8Array, or Blob all accepted
+const template = await client.templates.create("./msa.pdf", {
+  name: "MSA v2",
+  signer_count: 1,
+  delivery_methods: ["email"],
+  signers: [{ role: "Customer", delivery: ["email"] }],
+});
+
+// Update / delete
+await client.templates.update(template.id, { name: "MSA v3" });
+await client.templates.delete(template.id);
+
+// PDF versioning
+await client.templates.replacePdf(template.id, "./msa-updated.pdf");
+const versions = await client.templates.history(template.id);
+const oldPdf   = await client.templates.downloadHistoryPdf(template.id, versions[0].id);
+
+// Fields — full replace
+await client.templates.setFields(template.id, [
+  { field_type: "signature", page: 1, x: 60, y: 82, width: 30, height: 6, signer_index: 0, required: true },
+  { field_type: "text",      page: 1, x: 10, y: 20, width: 30, height: 4, signer_index: 0, name: "company", label: "Company name", required: true },
+]);
+
+// Duplicate + archive
+const copy = await client.templates.duplicate(template.id);
+await client.templates.archive(template.id);
+```
+
+### PDF upload constraints
+
+- Max **50 MB** per file.
+- `application/pdf` only — other content types 400.
+- The multipart form field name must be `file` — the SDK sets this for you.
+
+## Webhooks
+
+```ts
+import express from "express";
+import { verifyWebhook, type WebhookPayload } from "@signingstudio/sdk";
+
+const app = express();
+
+app.post(
+  "/webhooks/signing-studio",
+  express.raw({ type: "application/json" }),   // do NOT pre-parse
+  (req, res) => {
+    if (!verifyWebhook(req.body, req.header("X-DDS-Signature") ?? null, process.env.WEBHOOK_SECRET!)) {
+      return res.status(401).end();
+    }
+    const payload = JSON.parse(req.body.toString("utf8")) as WebhookPayload;
+    // payload.event is one of:
+    //   "document.sent" | "document.viewed" | "document.signed" | "document.declined" | "document.completed"
+    res.status(200).end();
+  },
+);
+```
+
+**Always sign the RAW body**, not a parsed-and-re-encoded body. Any whitespace shift breaks the HMAC.
+
+### Payload shape
+
+See [types.ts](src/types.ts) — `WebhookPayload` is fully typed.
+
+## Errors
+
+```ts
+import {
+  SigningStudioError,
+  ApiError,
+  AuthenticationError,
+  NotFoundError,
+  ValidationError,
+  RateLimitError,
+} from "@signingstudio/sdk";
+
+try {
+  await client.documents.send(payload);
+} catch (err) {
+  if (err instanceof ValidationError) {
+    // err.errors is Record<string, string[]>
+  } else if (err instanceof RateLimitError) {
+    // err.window === "minute" | "day" | null
+    // err.retryAfter === number | null
+  } else if (err instanceof AuthenticationError) {
+    // Refresh the API key.
+  } else if (err instanceof NotFoundError) {
+    // Doesn't exist on this tenant.
+  } else if (err instanceof ApiError) {
+    console.error(`request=${err.requestId} status=${err.statusCode}`);
+  }
+  throw err;
+}
+```
+
+All SDK-thrown exceptions inherit from `SigningStudioError`.
+
+## Rate limits
+
+Every response carries:
+
+- `X-RateLimit-Limit-Minute`, `X-RateLimit-Remaining-Minute`
+- `X-RateLimit-Limit-Day`, `X-RateLimit-Remaining-Day`
+
+Access them via the low-level HTTP layer if you need to display or throttle:
+
+```ts
+const response = await client.http.requestJson({ method: "GET", path: "documents" });
+console.log(response.rateLimit.remainingMinute);
+```
+
+Platform defaults: **120 req/min** and **20,000 req/day** per API key.
+
+## Testing
+
+```bash
+npm ci
+npm run typecheck
+npm run test
+npm run build
+```
+
+CI runs against Node 18, 20, 22 on every push/PR.
+
+## Versioning
+
+Semantic versioning. `CHANGELOG.md` records every release.
+
+## License
+
+MIT. See [LICENSE](LICENSE).