Node client

@signsealer/sdk. No dependencies; runs anywhere fetch does.

npm install @signsealer/sdk

Node 18 or later, every edge runtime, and the browser — though an API key belongs on a server. TypeScript types ship in the package, every version on npm is published by a workflow from a tagged commit, never from somebody's machine, and the changelog ships in the package.

Three things it does that a hand-rolled client usually does not

• Retries the failures worth retrying, with an idempotency key. Every write that creates something gets one automatically, so a network blip does not become a second waiver. A 422 is never retried; it will be refused the same way every time, and the message says why. Pass your own key as the last argument when you have one, for example your order id. A write the server cannot de-duplicate — rotating a webhook secret, adding or pairing a tablet, a replay, the gate’s link — is never repeated after an answer that leaves it unknown whether it happened; it throws, and you decide.
• Surfaces the API's own sentence. SignSealerError carries message, hint, code, status and requestId. The message is frequently the database's own words, which are more specific than anything a client layer could write.
• Keeps the request id. Every response carries one; quote it and we can find the request.

The client with a key

import { SignSealer, SignSealerError } from "@signsealer/sdk";

const signsealer = new SignSealer({
  apiKey: process.env.SIGNSEALER_KEY!,
  baseUrl: "https://api.signsealer.com",  // the default
  maxAttempts: 3,                          // total, the first included
});

Each method's request and response are the ones on the API reference, which is generated from the router; the client adds nothing the API does not have.

The signer's side, with no key

SignSealerSigning takes no API key, because on those routes a signing token is the whole credential. It is a separate class on purpose: a client that could send a key alongside a token would be a client that widens somebody's authority by accident. The one credential it will carry is a paired tablet's own, given as deviceKey, and only on a signature that says when it was taken offline (below).

import { SignSealerSigning } from "@signsealer/sdk";

const signing = new SignSealerSigning();

const link = await signing.link(token);
if (!link.ok) return show(link.reason);   // written for a person to read

await signing.consent(token);             // before signing, always
await signing.supply(token, "emergency_contact", "Sam Reyes, +1 503 555 0199");
await signing.sign(token, "typed", "Dana Reyes");
// or: await signing.decline(token, "wrong dates");

const result = await signing.verify("4KJ72M9PXQ3TVW8H");
// { certificate_found: true, still_matches_record: true, … }

Consent is a separate call and that is not an oversight: ESIGN requires consent to electronic records to precede the transaction, and a system that records both in the same instant cannot show that it did. If you would rather not build a signing page, send the signer to https://api.signsealer.com/s/<token> and skip all of it.

Signing where there is no network

A paired tablet that took a signature offline passes captured with what the device thought the time was; the server records when it received the event and keeps the claim beside it, marked as a claim. The claim is kept only from a paired tablet of the business the link belongs to, because the day it carries is the day written into the document: build the client with the tablet's credential (the key pairDevice answered) and it is sent with that one call. From anybody else captured is left out without an error and the signature is dated when it arrives.

const signing = new SignSealerSigning({ deviceKey: tabletKey });
await signing.sign(token, "drawn", dataUri,
  { offline: true, at: capturedAt.toISOString(), device: "counter-2" });

A template that is a PDF

When the template behind a link is an uploaded PDF, link.pages lists its pages and a field may carry a place. Draw the pages rather than link.body: a PDF template's body is a sentence naming the file and its fingerprint, so rendering it would show somebody a hash where their lease should be. Signing a PDF has the whole of it.

for (const p of link.pages ?? []) {
  const img = new Image();
  img.src = signing.pageUrl(token, p.n);   // no API key: the token is the credential
}

/* And on the keyed side, whether a template is one of these at all. */
const pdf = await signsealer.templatePdf(templateId);
if (pdf.has_pdf && !pdf.ready) { /* not every page is drawn; it cannot be published */ }

Errors

try {
  await signsealer.prepareDocument({ template_code: "rental-agreement", values: {} });
} catch (e) {
  if (e instanceof SignSealerError) {
    console.error(e.status);    // 422
    console.error(e.code);      // "invalid"
    console.error(e.message);   // "no value for guest_name"
    console.error(e.hint);      // "A contract that ships with a placeholder…"
    console.error(e.requestId); // quote this and we can find the request
  }
}

Other languages

Python, Ruby, PHP and Go clients are not written. The API is small enough that a hand-rolled client is a morning's work; the quickstart shows the four calls in Python with requests, and openapi.json feeds any generator.

Versions

This page describes @signsealer/sdk 1.17.0. The package declares Node 18 or later (engines in its package.json), as it has since 1.0.0; outside Node it needs a runtime with fetch. On Node 18, use 1.11.1 or later: before it, every write not given its own idempotency key threw unless Node was started with --experimental-global-webcrypto. Each version's changes are in CHANGELOG.md, which ships in the package.

What you have

npm ls @signsealer/sdk            # the version installed here
npm view @signsealer/sdk version  # the newest on npm

From code, the package exports its own package.json (from an ES module, make require with createRequire):

const { version } = require("@signsealer/sdk/package.json");

In TypeScript, calling a method your copy does not have is a compile error; in JavaScript it is a TypeError when the line runs.

Numbers that never reached npm

Eight versions in the changelog were never published: 1.0.1, 1.1.0, 1.2.0, 1.3.0, 1.5.0, 1.6.0, 1.8.0 and 1.9.0. What each added first reached npm in the next version that was.

When each method arrived

The options listed are the ones you send. Fields in an answer are not listed: the client hands back whatever the API sends, so a newer version only declares them in its types.