@signsealer/sdk 1.0.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,205 @@
1
+ # Changelog
2
+
3
+ ## 1.4.0
4
+
5
+ Types and documentation; no request the client sends changed. 1.3.0 was
6
+ never published, so installing 1.4.0 from 1.0.0 gets everything below it
7
+ too.
8
+
9
+ ### Added
10
+
11
+ `document(id)` answers a `DocumentDetail` rather than `unknown`, with
12
+ `answers` and `flagged` (00395): every question in the form's order, the
13
+ signer it belongs to, whether it was `asked` (a question its condition hid
14
+ never is), the value -- masked where the question is sensitive -- and
15
+ whether the template's rules say a person should read it. `flagged` counts
16
+ them. Answers are not in webhooks, deliberately; fetch the document.
17
+
18
+ `Ask` declares `show_if`, `flag_when`, `block`, `block_label`,
19
+ `block_intro`, `block_step` and `place`, with `AnswerRule` and `ShowIf`
20
+ for the first two. The API accepts them on `createTemplate` from this
21
+ release of the server; before it, the route's schema dropped them without
22
+ an error and the template was saved without its conditions, flags and
23
+ sections.
24
+
25
+ `SigningField` names the element of `SigningLink.fields`, and declares what
26
+ the engine has been sending: `options` (a choice's choices), `hint`,
27
+ `sensitive`, `block` (00372, 00379), `show_if` and `visible` (00375). Draw
28
+ the visible questions only. From 00399 it also carries `passed`: the signer
29
+ has been past the question, answering it or leaving an optional one blank
30
+ (supply an empty value to do that), so a page built on the SDK can move on
31
+ from it without the signer having to type something.
32
+
33
+ `WorkflowBundle` declares everything the server has been putting in the
34
+ form a tablet keeps: `id_evidence`, `location`, `photos`,
35
+ `template.body_format`, and from 00398 `questions` -- every question the
36
+ template asks the signer at the counter, as a `BundleQuestion`, which from
37
+ 00399 says whether it is `placed` on the document's pages -- and
38
+ `document_after_questions`.
39
+
40
+ `SigningLink` declares `body_format` -- a `markdown` body should be drawn
41
+ as headings and lists, not as marks -- `document_after_questions` (00393),
42
+ `document_status`, `signer_id`, `signed_at`, `powered_by`, `theme`,
43
+ `mark`, `footer` and `id_evidence`.
44
+
45
+ ### Fixed
46
+
47
+ `bundle()`'s documentation pointed at an `evidence` method that has never
48
+ existed.
49
+
50
+ ## 1.3.0
51
+
52
+ The first version on npm since 1.0.0. 1.0.1 and 1.2.0 were tagged while
53
+ the publish workflow was not running, so the entries below this one
54
+ describe changes that never reached the registry; installing 1.3.0 gets
55
+ all of them.
56
+
57
+ ### Added
58
+
59
+ `location(token)` and `recordLocation(token, position)` (00231, 00359,
60
+ 00363): whether the business asks where the signer is, the wording to
61
+ show before asking, and the answer — a decline included, because under
62
+ `require` the engine waits for an *answer* and "no" is one. The reply's
63
+ `offered` says what a counter tablet does with the same setting; a client
64
+ driving a signing from its own front end reads `mode`.
65
+
66
+ `phone` on a signer, and `email` may be null (00361). A signer needs an
67
+ email, a phone, or both; a `cc` may have neither. Given both, the link
68
+ goes out by mail and by text where the business has consent on file.
69
+
70
+ `return_url` on `send()`: where the signed page sends the person
71
+ afterwards. Must be https on a domain the business has proven, or the
72
+ send is refused with 422.
73
+
74
+ ### Changed
75
+
76
+ `homepage` points at signsealer.com/docs; the www and docs subdomains
77
+ are gone.
78
+
79
+ ## 1.2.0
80
+
81
+ ### Added
82
+
83
+ The routes the tablet app grew this month, for your own tablet software.
84
+ `documentSigners(id)` answers who has signed one document and nothing
85
+ else; `gateLink(documentId, signerId)` mints a fresh signing link for a
86
+ signer who has not, with a QR code drawn as SVG (00340).
87
+ `packetByCode(code)` resolves a signing code from the receipt to what is
88
+ still owed, by first name and last initial, for a paired tablet's own
89
+ credential (00321). `deviceHeartbeat` takes `queue_waiting`,
90
+ `queue_refused` and `synced`, and `reportProblem(input)` sends a problem
91
+ as names and numbers, never text (00341).
92
+
93
+ On the signer's side: `supplyPhoto(token, key, image)` answers a `photo`
94
+ field with a photograph (00342); `idEvidence(token)` and
95
+ `captureIdEvidence(token, kind, image)` read and take the ID photo the
96
+ business asked for (00228, 00339). Images are `{ contentType, bytes }`
97
+ with bytes as a `Uint8Array` or already base64.
98
+
99
+ ## 1.1.0
100
+
101
+ ### Added
102
+
103
+ Tablets, from your own software. `devices()`, `addDevice()`, `newDeviceCode()`,
104
+ `setDevice()` and `removeDevice()` do what the portal's Apps & tablets page
105
+ does, for a platform that runs many businesses and puts a tablet on each
106
+ counter from its own back office. The key needs the `signing:devices` scope.
107
+ Pairing itself is unchanged and still takes no key.
108
+
109
+ Starting with no network. `workflowBundle()` is everything a tablet needs
110
+ to run a workflow offline (the published form and its version, the consent
111
+ and intent wording, the page list of an uploaded PDF) and `workflowPage()`
112
+ is one of those pages as PNG bytes. `startWorkflow()` takes
113
+ `expected_template_version` and `captured` for a start reconciled
114
+ afterwards; a `409 template_changed` means the form moved on and the
115
+ customer signs again on the current one.
116
+
117
+ ### Fixed
118
+
119
+ `workflows()` and `documents()` answered `unknown`; they answer `Workflow[]`
120
+ and `DocumentRow[]` now. Typing them caught the DeckPOS example reading a
121
+ `workflow_id` the API never sent (it is `id`).
122
+
123
+ `pairDevice()` said to call it on a client built without a key — and the
124
+ constructor refused to build one. `apiKey` is optional now; a keyless client
125
+ sends no authorization header, pairs, and is refused everything else. Found
126
+ by driving the client against the real API in `tests/http.ts`.
127
+
128
+ `pairDevice()` declared an answer nobody sent (`api_key`, `device`). It
129
+ returns what the API returns: `device_id`, `name`, `key`, `workflow_id`,
130
+ `workflow_name`.
131
+
132
+ ## 1.0.1
133
+
134
+ ### Fixed
135
+
136
+ `documents()` takes `offset`. It always took `status`, `q` and `limit` and the
137
+ API always took `offset` as well, so a business with more than two hundred
138
+ documents had no way to reach the second page from this client. One field on
139
+ one type; the query string was already built from whatever the filter held.
140
+
141
+ ## 1.0.0
142
+
143
+ The first release under this name, and the first one on npm.
144
+
145
+ ### Renamed
146
+
147
+ `@signsealer/node` → **`@signsealer/sdk`**. The old name said where it ran,
148
+ which was never the interesting part and was going to be wrong the first time
149
+ somebody used it from an edge runtime or a browser. Nothing was ever published
150
+ under the old name, so there is no migration: this is the only name there has
151
+ been.
152
+
153
+ ### What it does that a hand-rolled client usually does not
154
+
155
+ **No dependencies.** `fetch` is in the runtime. A signing client that drags an
156
+ HTTP library into somebody's build is one that gets declined at review, and the
157
+ build refuses outright if `dependencies` is ever non-empty.
158
+
159
+ **Retries the failures worth retrying, with an idempotency key.** Every write
160
+ that creates something gets one automatically, so a network blip does not
161
+ become a second waiver. `422` is never retried. `429` is retried only when the
162
+ server says how long to wait and the wait is short — the rate-limit window is a
163
+ minute, so three guessed backoffs would land inside the same window and spend
164
+ the next one's budget too. A longer wait comes back as `error.retryAfter`, in
165
+ seconds, to schedule rather than block on.
166
+
167
+ **Surfaces the API's own sentence.** `SignSealerError` carries `message`,
168
+ `hint`, `code`, `status` and `requestId`. The message is frequently the
169
+ database's own words, which are more specific than anything a client layer
170
+ could write.
171
+
172
+ **Watches the allowance.** Every send reports how many agreements are left, kept
173
+ on `client.agreementsRemaining` — `null` on a plan that bills for overage, where
174
+ there is nothing to count down. A spent allowance answers `402`, not `429`, and
175
+ `error.quotaExceeded` says so. Never retried, by this client or any other worth
176
+ using: it comes back when the billing period turns.
177
+
178
+ ### The signer's side is a separate class
179
+
180
+ `SignSealerSigning` takes **no API key**, because on those routes a signing
181
+ token is the whole credential. A client that could send a key alongside a token
182
+ would be a client that widens somebody's authority by accident.
183
+
184
+ It covers consent, signing, one-time codes (`requestCode` / `confirmCode`), and
185
+ PDF templates — `link.pages` and `pageUrl(token, n)`, with each field's `place`
186
+ in fractions of the page a reader sees.
187
+
188
+ Consent is its own call and that is not an oversight: ESIGN requires consent to
189
+ electronic records to precede the transaction, and a system that records both
190
+ in the same instant cannot show that it did.
191
+
192
+ ### Shipped as ESM, CJS and types
193
+
194
+ `tsc` twice rather than a bundler — a bundler would be a build-time dependency
195
+ on a package whose selling point is having none. CJS is emitted as `.cjs`,
196
+ unambiguous to every Node since 12, so the `"type": "module"` at the root does
197
+ not have to be argued with.
198
+
199
+ The build smoke-tests the artefact rather than the source: it imports both
200
+ outputs, checks the client rejects a key that is not one, and checks the
201
+ declarations name what the README names.
202
+
203
+ ### Requires
204
+
205
+ Node 18 or newer, or any runtime with `fetch`. An API key belongs on a server.
package/README.md CHANGED
@@ -106,6 +106,47 @@ Consent is a separate call and that is not an oversight: ESIGN requires consent
106
106
  to electronic records to precede the transaction, and a system that records
107
107
  both in the same instant cannot show that it did.
108
108
 
109
+ A field of kind `photo` takes a photograph, not text; the ID photo the business
110
+ asked for is taken the same way, and both are shrunk on the server:
111
+
112
+ ```ts
113
+ await signing.supplyPhoto(token, "boat_condition", { contentType: "image/jpeg", bytes });
114
+ const asked = await signing.idEvidence(token); // { offered: "id" | "id_selfie" | "off", … }
115
+ if (asked?.offered !== "off") await signing.captureIdEvidence(token, "id", { contentType: "image/jpeg", bytes });
116
+ ```
117
+
118
+ ### Drawing the questions
119
+
120
+ A template's questions arrive on `link.fields`, and three things about them
121
+ decide what a page should show:
122
+
123
+ - **`visible`** is the engine's own answer to a question's condition. Draw only
124
+ the visible ones. A hidden question is not required, and the signature is
125
+ checked against the same value, so a page that follows it is never refused
126
+ for a question it hid. Answering the earlier question differently clears
127
+ the hidden one on the server.
128
+ - **`block`** groups questions under one heading and introduction; `step: true`
129
+ means the block wants a page of its own with a Next button.
130
+ - **`link.body_format`** is `text` or `markdown`. A markdown body has headings,
131
+ bold, italics and lists, and printing it as text shows the signer the marks.
132
+
133
+ ```ts
134
+ const asked = link.fields.filter((f) => f.visible !== false);
135
+ for (const f of asked) await signing.supply(token, f.key, answerFor(f));
136
+ ```
137
+
138
+ When `link.document_after_questions` is true the business asked for the
139
+ questions first: show the document once no required visible question is left
140
+ unanswered, which is also exactly when a signature is accepted.
141
+
142
+ ### At the gate, and from a signing code
143
+
144
+ `documentSigners(id)` answers who has signed one document and nothing else;
145
+ `gateLink(documentId, signerId)` mints a fresh link for whoever has not, with
146
+ a QR code drawn as SVG to hold up. A paired tablet resolves the signing code
147
+ on a receipt with `packetByCode(code)` and starts what it owes with
148
+ `startPacketItem(itemId)`.
149
+
109
150
  ### When the business asks the signer for a code
110
151
 
111
152
  A business can require a one-time code before a signature (Settings →
@@ -276,6 +317,41 @@ publishing is what freezes the text people will have signed — so there is no
276
317
  `publish` method here on purpose. That is a decision somebody makes looking at
277
318
  the words.
278
319
 
320
+ Questions can be grouped, asked only when an earlier answer says so, and
321
+ flagged for a person to read:
322
+
323
+ ```ts
324
+ fields: [
325
+ { key: "drank", label: "Have you had a drink today?", kind: "choice", options: ["Yes", "No"],
326
+ flag_when: { equals: ["Yes"] },
327
+ block: "safety", block_label: "Before you shoot", block_step: true },
328
+ { key: "how_much", label: "How much?", kind: "paragraph",
329
+ show_if: { field: "drank", equals: ["Yes"] }, block: "safety" },
330
+ ],
331
+ ```
332
+
333
+ A condition can only look at a question above it, and a block's heading is
334
+ given once. The engine checks both and refuses by name, and a refused list
335
+ leaves no template behind.
336
+
337
+ ## Reading what was answered
338
+
339
+ ```ts
340
+ const doc = await client.document(documentId);
341
+ if (doc.flagged > 0) {
342
+ for (const a of doc.answers.filter((a) => a.flagged)) notify(a.label, a.value);
343
+ }
344
+ ```
345
+
346
+ `answers` lists every question in the form's order, with the signer it belongs
347
+ to. `asked: false` is a question its condition hid: no value, never flagged. A
348
+ sensitive answer is masked, as it is for the business's own staff.
349
+
350
+ Answers are read from the document and are **not in webhooks**, on purpose: a
351
+ webhook goes to whatever address was typed, often somebody else's tool, and
352
+ some answers are about a person's health. A webhook says something happened;
353
+ fetch the document to see what was said.
354
+
279
355
  ## Checking a certificate
280
356
 
281
357
  No credential at all. Anybody holding the printed code can do this.
@@ -15,6 +15,39 @@
15
15
  * - keeps the request id, so a support mail can quote something we can look
16
16
  * up.
17
17
  */
18
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
19
+ if (k2 === undefined) k2 = k;
20
+ var desc = Object.getOwnPropertyDescriptor(m, k);
21
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
22
+ desc = { enumerable: true, get: function() { return m[k]; } };
23
+ }
24
+ Object.defineProperty(o, k2, desc);
25
+ }) : (function(o, m, k, k2) {
26
+ if (k2 === undefined) k2 = k;
27
+ o[k2] = m[k];
28
+ }));
29
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
30
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
31
+ }) : function(o, v) {
32
+ o["default"] = v;
33
+ });
34
+ var __importStar = (this && this.__importStar) || (function () {
35
+ var ownKeys = function(o) {
36
+ ownKeys = Object.getOwnPropertyNames || function (o) {
37
+ var ar = [];
38
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
39
+ return ar;
40
+ };
41
+ return ownKeys(o);
42
+ };
43
+ return function (mod) {
44
+ if (mod && mod.__esModule) return mod;
45
+ var result = {};
46
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
47
+ __setModuleDefault(result, mod);
48
+ return result;
49
+ };
50
+ })();
18
51
  Object.defineProperty(exports, "__esModule", { value: true });
19
52
  exports.WEBHOOK_TOLERANCE_SECONDS = exports.WEBHOOK_SIGNATURE_HEADER = exports.WEBHOOK_TIMESTAMP_HEADER = exports.WEBHOOK_EVENT_HEADER = exports.SignSealerSigning = exports.SignSealer = exports.SignSealerError = void 0;
20
53
  exports.verifyWebhook = verifyWebhook;
@@ -90,11 +123,11 @@ class SignSealer {
90
123
  * polling for it.
91
124
  */
92
125
  agreementsRemaining = null;
93
- constructor(opts) {
94
- if (!opts.apiKey?.startsWith("mk_")) {
126
+ constructor(opts = {}) {
127
+ if (opts.apiKey !== undefined && !opts.apiKey.startsWith("mk_")) {
95
128
  throw new Error("a SignSealer API key looks like mk_live_… or mk_test_…");
96
129
  }
97
- this.#key = opts.apiKey;
130
+ this.#key = opts.apiKey ?? "";
98
131
  this.#base = withoutTrailingSlashes(opts.baseUrl ?? "https://api.signsealer.com");
99
132
  this.#attempts = Math.max(1, opts.maxAttempts ?? 3);
100
133
  this.#maxWaitMs = Math.max(0, opts.maxWaitMs ?? 5_000);
@@ -191,18 +224,58 @@ class SignSealer {
191
224
  return this.#call("GET", `/v1/sms-consents?phone=${encodeURIComponent(phone)}`);
192
225
  }
193
226
  /* ----------------------------------------------------------- documents */
227
+ /**
228
+ * Documents, filtered and paged.
229
+ *
230
+ * `limit` is 1–200 (50 by default); asking for more than 200 gets 200.
231
+ * `offset` was missing, so a business with more than two hundred documents
232
+ * had no way to reach the second page from this client at all — the API
233
+ * had always taken it.
234
+ */
194
235
  documents(filter = {}) {
195
236
  const q = new URLSearchParams(Object.entries(filter)
196
237
  .filter(([, v]) => v !== undefined)
197
238
  .map(([k, v]) => [k, String(v)]));
198
239
  return this.#call("GET", `/v1/documents?${q}`);
199
240
  }
241
+ /**
242
+ * One document: its text, its signers, the whole trail, and every answer
243
+ * (00395). `flagged` counts the answers the template's rules say a person
244
+ * should read -- the question an integration usually wants answered first.
245
+ * Answers are here and deliberately not in webhooks.
246
+ */
200
247
  document(id) {
201
248
  return this.#call("GET", `/v1/documents/${encodeURIComponent(id)}`);
202
249
  }
250
+ /**
251
+ * Who has signed one document (00340): each signer's name, role and state
252
+ * and nothing else -- no text, no addresses, no trail. The question a gate
253
+ * attendant asks; the route a paired tablet may read.
254
+ */
255
+ documentSigners(id) {
256
+ return this.#call("GET", `/v1/documents/${encodeURIComponent(id)}/signers`);
257
+ }
258
+ /**
259
+ * A fresh signing link for a signer who has not signed, as a QR code to
260
+ * hold up (00340). The link they were sent stops working; the trail says
261
+ * a link was shown at the gate. Refused for a signer who has signed or
262
+ * declined, a copied recipient, or a document that is not open.
263
+ */
264
+ gateLink(documentId, signerId) {
265
+ return this.#call("POST", `/v1/documents/${encodeURIComponent(documentId)}/signers/${encodeURIComponent(signerId)}/link`, {});
266
+ }
203
267
  prepareDocument(input, idempotencyKey) {
204
268
  return this.#call("POST", "/v1/documents", input, idempotencyKey);
205
269
  }
270
+ /**
271
+ * Send, and take the links back once.
272
+ *
273
+ * Each signer needs an `email`, a `phone`, or both; a `cc` may have neither.
274
+ * Given both, the same link goes out twice — by mail and by text — because a
275
+ * person who does not check one inbox checks the other. The text goes only
276
+ * where the business has consent on file for `signing.link`; where it does
277
+ * not, the email still goes and the reason is on the evidence trail.
278
+ */
206
279
  send(documentId, signers, idempotencyKey) {
207
280
  return this.#call("POST", `/v1/documents/${encodeURIComponent(documentId)}/send`, { signers }, idempotencyKey);
208
281
  }
@@ -252,7 +325,7 @@ class SignSealer {
252
325
  * The evidence bundle: the sealed PDF with the evidence package printed
253
326
  * after the audit trail — every message, every webhook, the record's state
254
327
  * — as one sealed file. Null before the document is executed, like `pdf`;
255
- * `evidence` has the JSON before then.
328
+ * `document` has the answers and the trail before then.
256
329
  */
257
330
  async bundle(documentId) {
258
331
  try {
@@ -295,6 +368,15 @@ class SignSealer {
295
368
  packet(packetId) {
296
369
  return this.#call("GET", `/v1/packets/${encodeURIComponent(packetId)}`);
297
370
  }
371
+ /**
372
+ * A signing code from the receipt, resolved (00321): what is still owed,
373
+ * each item by first name and last initial. Only a paired tablet's own
374
+ * credential may ask; a code from another business, a code nobody holds
375
+ * and a malformed one answer `found: false` the same way.
376
+ */
377
+ packetByCode(code) {
378
+ return this.#call("GET", `/v1/packets/code/${encodeURIComponent(code)}`);
379
+ }
298
380
  startPacketItem(itemId, idempotencyKey) {
299
381
  return this.#call("POST", `/v1/packets/items/${encodeURIComponent(itemId)}/start`, undefined, idempotencyKey);
300
382
  }
@@ -365,6 +447,49 @@ class SignSealer {
365
447
  pairDevice(input) {
366
448
  return this.#call("POST", "/v1/devices/pair", input);
367
449
  }
450
+ /**
451
+ * Tablets, from your own software (00335).
452
+ *
453
+ * Everything the Apps & tablets page does: a platform that runs many
454
+ * businesses puts a tablet on each counter from its own back office. The
455
+ * key needs `signing:devices`. The pairing itself stays with `pairDevice`,
456
+ * which takes no key: the code is the credential.
457
+ */
458
+ devices() {
459
+ return this.#call("GET", "/v1/devices");
460
+ }
461
+ /** Add a tablet. The pairing code comes back once and never again. */
462
+ addDevice(input) {
463
+ return this.#call("POST", "/v1/devices", input);
464
+ }
465
+ /** A new code for a tablet; any tablet paired to it stops the moment the code is made. */
466
+ newDeviceCode(id) {
467
+ return this.#call("POST", `/v1/devices/${encodeURIComponent(id)}/code`);
468
+ }
469
+ /** Rename a tablet or change what it runs; `workflow_id: null` makes it a staff tablet. */
470
+ setDevice(id, input) {
471
+ return this.#call("PATCH", `/v1/devices/${encodeURIComponent(id)}`, input);
472
+ }
473
+ /**
474
+ * Everything a tablet needs to run a workflow with no network (00336):
475
+ * the workflow, the published template with its version, the consent and
476
+ * intent wording with theirs, and the page list of an uploaded PDF. Keep
477
+ * it, render the form yourself when the connection is down, then start
478
+ * the workflow naming `expected_template_version`; a 409 `template_changed`
479
+ * means the form moved on and the customer signs again on the current one.
480
+ */
481
+ workflowBundle(id) {
482
+ return this.#call("GET", `/v1/workflows/${encodeURIComponent(id)}/bundle`);
483
+ }
484
+ /** One page of the workflow's PDF template as PNG bytes, for the same purpose. 404 for a text template. */
485
+ async workflowPage(id, page) {
486
+ const out = await this.#call("GET", `/v1/workflows/${encodeURIComponent(id)}/pages/${page}`);
487
+ return { page: out.page, contentType: out.content_type, bytes: base64ToBytes(out.bytes_base64) };
488
+ }
489
+ /** Stop a tablet. Its credential stops with it; the reason goes on the audit trail. */
490
+ removeDevice(id, reason) {
491
+ return this.#call("DELETE", `/v1/devices/${encodeURIComponent(id)}?reason=${encodeURIComponent(reason)}`);
492
+ }
368
493
  /**
369
494
  * Say the device is still here, and read back what it should be running.
370
495
  *
@@ -377,6 +502,14 @@ class SignSealer {
377
502
  deviceHeartbeat(input = {}) {
378
503
  return this.#call("POST", "/v1/devices/heartbeat", input);
379
504
  }
505
+ /**
506
+ * A problem, as a tablet may state it (00341): names and numbers, never
507
+ * text. There is no field for a message, because a message is where a
508
+ * customer's name ends up. Thirty an hour per tablet.
509
+ */
510
+ reportProblem(input) {
511
+ return this.#call("POST", "/v1/devices/report", input);
512
+ }
380
513
  /* ------------------------------------------------------------ the wire */
381
514
  async #call(method, path, body, idempotencyKey) {
382
515
  /*
@@ -393,7 +526,7 @@ class SignSealer {
393
526
  res = await this.#fetch(`${this.#base}${path}`, {
394
527
  method,
395
528
  headers: {
396
- authorization: `Bearer ${this.#key}`,
529
+ ...(this.#key ? { authorization: `Bearer ${this.#key}` } : {}),
397
530
  "content-type": "application/json",
398
531
  ...(key ? { "idempotency-key": key } : {}),
399
532
  },
@@ -544,6 +677,64 @@ class SignSealerSigning {
544
677
  supply(token, key, value, about) {
545
678
  return this.#call("POST", `/v1/sign/${encodeURIComponent(token)}/fields`, { key, value, ...(about ? { about } : {}) });
546
679
  }
680
+ /**
681
+ * A photograph as a field's answer (00342): a JPEG or PNG for a field of
682
+ * kind `photo`, shrunk on the server, kept encrypted with the document
683
+ * for as long as the document is kept; the field carries its hash. A
684
+ * second photograph replaces the first.
685
+ */
686
+ supplyPhoto(token, key, image, options = {}) {
687
+ return this.#call("POST", `/v1/sign/${encodeURIComponent(token)}/fields/${encodeURIComponent(key)}/photo`, {
688
+ content_type: image.contentType,
689
+ bytes_base64: typeof image.bytes === "string" ? image.bytes : bytesToBase64(image.bytes),
690
+ ...(options.about ? { about: options.about } : {}),
691
+ ...(options.captured ? { captured: options.captured } : {}),
692
+ });
693
+ }
694
+ /**
695
+ * Whether the business asks where the signer is (00231), and the wording
696
+ * the capture is taken under. `mode` is `off`, `ask` or `require`;
697
+ * `require` means the signature is refused until an answer is on record.
698
+ *
699
+ * Show `disclosure.text` before you ask the device, not after.
700
+ */
701
+ location(token) {
702
+ return this.#call("GET", `/v1/sign/${encodeURIComponent(token)}/location`);
703
+ }
704
+ /**
705
+ * Where the signer is, or that they would not say.
706
+ *
707
+ * Send the refusal too. Under `require` the engine waits for an *answer*,
708
+ * and a decline is one — so a person who says no, or a device that cannot
709
+ * get a fix, is told here rather than at the signature, which is the last
710
+ * screen and the worst place to find out.
711
+ */
712
+ recordLocation(token, position) {
713
+ return this.#call("POST", `/v1/sign/${encodeURIComponent(token)}/location`, position.shared
714
+ ? { shared: true, lat: position.lat, lon: position.lon,
715
+ ...(position.accuracyM !== undefined ? { accuracy_m: position.accuracyM } : {}) }
716
+ : { shared: false });
717
+ }
718
+ /**
719
+ * What the business asks the signer for by way of ID evidence (00228,
720
+ * 00339): the mode, what is captured so far by hash, and the words each
721
+ * capture is taken under. Never an identity check, and never the image.
722
+ */
723
+ idEvidence(token) {
724
+ return this.#call("GET", `/v1/sign/${encodeURIComponent(token)}/id-evidence`);
725
+ }
726
+ /**
727
+ * A photo of the ID, or of the person, when the business asked (00339).
728
+ * Kept encrypted for thirty days, the hash on the trail. Refused when
729
+ * the business did not ask.
730
+ */
731
+ captureIdEvidence(token, kind, image, captured) {
732
+ return this.#call("POST", `/v1/sign/${encodeURIComponent(token)}/id-evidence`, {
733
+ kind, content_type: image.contentType,
734
+ bytes_base64: typeof image.bytes === "string" ? image.bytes : bytesToBase64(image.bytes),
735
+ ...(captured ? { captured } : {}),
736
+ });
737
+ }
547
738
  sign(token, method, value, captured) {
548
739
  return this.#call("POST", `/v1/sign/${encodeURIComponent(token)}`, { method, value, ...(captured ? { captured } : {}) });
549
740
  }
@@ -617,6 +808,14 @@ function backoff(attempt) {
617
808
  return base + Math.random() * base * 0.3;
618
809
  }
619
810
  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
811
+ /** Bytes to base64, the same way round: `btoa` is everywhere `fetch` is. */
812
+ function bytesToBase64(bytes) {
813
+ let binary = "";
814
+ for (let i = 0; i < bytes.length; i += 0x8000) {
815
+ binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
816
+ }
817
+ return btoa(binary);
818
+ }
620
819
  /** Base64 to bytes, without assuming Node: `atob` is in every runtime that
621
820
  * has `fetch`, and `Buffer` is not. */
622
821
  function base64ToBytes(b64) {
@@ -701,7 +900,7 @@ function webCrypto() {
701
900
  if (here)
702
901
  return here;
703
902
  try {
704
- const mod = await Promise.resolve(`${"node:" + "crypto"}`).then(s => require(s));
903
+ const mod = await Promise.resolve(`${"node:" + "crypto"}`).then(s => __importStar(require(s)));
705
904
  const fallback = mod.webcrypto?.subtle;
706
905
  if (fallback)
707
906
  return fallback;