@signsealer/sdk 1.0.0 → 1.7.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,297 @@
1
+ # Changelog
2
+
3
+ ## 1.7.0
4
+
5
+ ### Added
6
+
7
+ - `DocumentSigners.link_allowed` (00409): whether `gateLink` will mint a link
8
+ for this caller. Always true for a key; for a paired tablet, only on a
9
+ document it or its form started, unless the business let that tablet show
10
+ links for every open document.
11
+ - `Device.hand_off` and `Device.gate`, and `setDevice(id, { hand_off, gate })`.
12
+ `gate` is `own` (the default) or `account`.
13
+ - `Account.mode` (00413): `test` for a test key (`mk_test_`), which acts on
14
+ the business's sandbox, where nothing is sent to anybody and nothing is
15
+ billed. Nothing changes in how the client is used: a test key is a key.
16
+ - `restoreTemplate(id, { change_note })` (00412): an older published version
17
+ back as a new draft at the top, with its text, questions, consent wording
18
+ and file.
19
+ - `change_note` on `editTemplate` and `reviseTemplate`, and on
20
+ `TemplateDetail` and each of its `versions`, with each version's `name`,
21
+ `created_at`, `has_pdf` and `documents`.
22
+
23
+ ### Changed
24
+
25
+ - A tablet added from now on starts with `gate: "own"`: `gateLink` from it is
26
+ refused with 403 for a document it did not start and its form did not
27
+ start, until the business sets `gate: "account"`. Tablets paired before
28
+ keep `account`, so nothing that worked stops working. A link a tablet
29
+ shows is one whoever holds it could open.
30
+
31
+ ## 1.6.0
32
+
33
+ ### Added
34
+
35
+ Templates, all the way through (00408). Until now the client could create a
36
+ draft and nothing else, so a template made from your own software could not
37
+ be sent until somebody published it in the dashboard.
38
+
39
+ - `template(id)` -- one version whole: `body`, `body_format`, `variables`,
40
+ `consent_text`, `fields`, `settings`, and `versions`, every version of its
41
+ code newest first.
42
+ - `templates({ code })` -- one template's versions.
43
+ - `editTemplate(id, …)` -- change a draft. A published version refuses.
44
+ - `publishTemplate(id)` -- publish a draft.
45
+ - `reviseTemplate(id, …)` -- the next version of a published template, as a
46
+ draft. `id` must be the newest version; an older one is a 409 naming it.
47
+ - `discardTemplate(id)` -- throw away a draft nothing was made from.
48
+ - `setTemplateSettings(id, …)` -- `one_time`, `show_address`,
49
+ `valid_months`, `remind_days`, and `resign`.
50
+
51
+ Documents:
52
+
53
+ - `prepareDocument` takes `external_ref`, `metadata` and `return_url`.
54
+ Webhooks carry the reference back as `document.metadata.external_ref`, and
55
+ `documents({ external_ref })` finds it.
56
+ - `documents()` answers `has_more`, `limit` and `offset` beside `total`.
57
+ - `send` takes `delivery: "embedded"` for a signer you show the page to
58
+ yourself: nothing is emailed or texted to them, and the automatic
59
+ reminders leave them alone. Each link now carries `url`.
60
+ - `remind(documentId, signerId)` sends a signer a fresh link.
61
+ - `embedLink(documentId, signerId)` mints a fresh link to put in an
62
+ `<iframe>`, with `frame_origins`, the sites it may be framed on. The page
63
+ posts an `EmbedEvent` to its parent: `ready`, `signed`, `declined`.
64
+ - `Account.frame_origins`.
65
+
66
+ ### Fixed
67
+
68
+ Retries. The client minted an idempotency key for every write and retried
69
+ every one after a lost response or a 5xx, but the server only honours keys
70
+ on the writes that create things. On the others a retry did the work twice.
71
+ The worst case was `rotateWebhookSecret`: two rotations drop the secret your
72
+ receiver is still using. `rotateWebhookSecret`, `replayWebhookDelivery`,
73
+ `pairDevice`, `addDevice`, `reportProblem` and `gateLink` are now sent once
74
+ after an ambiguous failure. A 429, which says nothing happened, is still
75
+ waited out.
76
+
77
+ ## 1.5.0
78
+
79
+ ### Added
80
+
81
+ `standing({ template, email?, phone? })` asks `GET /v1/standing` (00406)
82
+ whether a person's signature on a template is still good: their newest
83
+ completed signature on any version of it, with `standing` -- `current`,
84
+ `expired`, `resign` (signed on a version the business has since asked
85
+ everybody to sign again) or `on_file` (the template has no period) -- and
86
+ `valid_until`. `found: false` means they have never signed it.
87
+
88
+ `DocumentRow`, `DocumentSigners` and `DocumentDetail` declare `standing`
89
+ and `valid_until`, which the server now sends on a signed document, and
90
+ `DocumentDetail` declares `renewed_by`: the newer signing by the same
91
+ person that replaced it. `Template` declares `valid_months`,
92
+ `remind_days` and `resign_from_version`. The `Standing` and
93
+ `PersonStanding` types name them.
94
+
95
+ ## 1.4.0
96
+
97
+ Types and documentation; no request the client sends changed. 1.3.0 was
98
+ never published, so installing 1.4.0 from 1.0.0 gets everything below it
99
+ too.
100
+
101
+ ### Added
102
+
103
+ `document(id)` answers a `DocumentDetail` rather than `unknown`, with
104
+ `answers` and `flagged` (00395): every question in the form's order, the
105
+ signer it belongs to, whether it was `asked` (a question its condition hid
106
+ never is), the value -- masked where the question is sensitive -- and
107
+ whether the template's rules say a person should read it. `flagged` counts
108
+ them. Answers are not in webhooks, deliberately; fetch the document.
109
+
110
+ `Ask` declares `show_if`, `flag_when`, `block`, `block_label`,
111
+ `block_intro`, `block_step` and `place`, with `AnswerRule` and `ShowIf`
112
+ for the first two. The API accepts them on `createTemplate` from this
113
+ release of the server; before it, the route's schema dropped them without
114
+ an error and the template was saved without its conditions, flags and
115
+ sections.
116
+
117
+ `SigningField` names the element of `SigningLink.fields`, and declares what
118
+ the engine has been sending: `options` (a choice's choices), `hint`,
119
+ `sensitive`, `block` (00372, 00379), `show_if` and `visible` (00375). Draw
120
+ the visible questions only. From 00399 it also carries `passed`: the signer
121
+ has been past the question, answering it or leaving an optional one blank
122
+ (supply an empty value to do that), so a page built on the SDK can move on
123
+ from it without the signer having to type something.
124
+
125
+ `WorkflowBundle` declares everything the server has been putting in the
126
+ form a tablet keeps: `id_evidence`, `location`, `photos`,
127
+ `template.body_format`, and from 00398 `questions` -- every question the
128
+ template asks the signer at the counter, as a `BundleQuestion`, which from
129
+ 00399 says whether it is `placed` on the document's pages -- and
130
+ `document_after_questions`.
131
+
132
+ `SigningLink` declares `body_format` -- a `markdown` body should be drawn
133
+ as headings and lists, not as marks -- `document_after_questions` (00393),
134
+ `document_status`, `signer_id`, `signed_at`, `powered_by`, `theme`,
135
+ `mark`, `footer` and `id_evidence`.
136
+
137
+ ### Fixed
138
+
139
+ `bundle()`'s documentation pointed at an `evidence` method that has never
140
+ existed.
141
+
142
+ ## 1.3.0
143
+
144
+ The first version on npm since 1.0.0. 1.0.1 and 1.2.0 were tagged while
145
+ the publish workflow was not running, so the entries below this one
146
+ describe changes that never reached the registry; installing 1.3.0 gets
147
+ all of them.
148
+
149
+ ### Added
150
+
151
+ `location(token)` and `recordLocation(token, position)` (00231, 00359,
152
+ 00363): whether the business asks where the signer is, the wording to
153
+ show before asking, and the answer — a decline included, because under
154
+ `require` the engine waits for an *answer* and "no" is one. The reply's
155
+ `offered` says what a counter tablet does with the same setting; a client
156
+ driving a signing from its own front end reads `mode`.
157
+
158
+ `phone` on a signer, and `email` may be null (00361). A signer needs an
159
+ email, a phone, or both; a `cc` may have neither. Given both, the link
160
+ goes out by mail and by text where the business has consent on file.
161
+
162
+ `return_url` on `send()`: where the signed page sends the person
163
+ afterwards. Must be https on a domain the business has proven, or the
164
+ send is refused with 422.
165
+
166
+ ### Changed
167
+
168
+ `homepage` points at signsealer.com/docs; the www and docs subdomains
169
+ are gone.
170
+
171
+ ## 1.2.0
172
+
173
+ ### Added
174
+
175
+ The routes the tablet app grew this month, for your own tablet software.
176
+ `documentSigners(id)` answers who has signed one document and nothing
177
+ else; `gateLink(documentId, signerId)` mints a fresh signing link for a
178
+ signer who has not, with a QR code drawn as SVG (00340).
179
+ `packetByCode(code)` resolves a signing code from the receipt to what is
180
+ still owed, by first name and last initial, for a paired tablet's own
181
+ credential (00321). `deviceHeartbeat` takes `queue_waiting`,
182
+ `queue_refused` and `synced`, and `reportProblem(input)` sends a problem
183
+ as names and numbers, never text (00341).
184
+
185
+ On the signer's side: `supplyPhoto(token, key, image)` answers a `photo`
186
+ field with a photograph (00342); `idEvidence(token)` and
187
+ `captureIdEvidence(token, kind, image)` read and take the ID photo the
188
+ business asked for (00228, 00339). Images are `{ contentType, bytes }`
189
+ with bytes as a `Uint8Array` or already base64.
190
+
191
+ ## 1.1.0
192
+
193
+ ### Added
194
+
195
+ Tablets, from your own software. `devices()`, `addDevice()`, `newDeviceCode()`,
196
+ `setDevice()` and `removeDevice()` do what the portal's Apps & tablets page
197
+ does, for a platform that runs many businesses and puts a tablet on each
198
+ counter from its own back office. The key needs the `signing:devices` scope.
199
+ Pairing itself is unchanged and still takes no key.
200
+
201
+ Starting with no network. `workflowBundle()` is everything a tablet needs
202
+ to run a workflow offline (the published form and its version, the consent
203
+ and intent wording, the page list of an uploaded PDF) and `workflowPage()`
204
+ is one of those pages as PNG bytes. `startWorkflow()` takes
205
+ `expected_template_version` and `captured` for a start reconciled
206
+ afterwards; a `409 template_changed` means the form moved on and the
207
+ customer signs again on the current one.
208
+
209
+ ### Fixed
210
+
211
+ `workflows()` and `documents()` answered `unknown`; they answer `Workflow[]`
212
+ and `DocumentRow[]` now. Typing them caught the DeckPOS example reading a
213
+ `workflow_id` the API never sent (it is `id`).
214
+
215
+ `pairDevice()` said to call it on a client built without a key — and the
216
+ constructor refused to build one. `apiKey` is optional now; a keyless client
217
+ sends no authorization header, pairs, and is refused everything else. Found
218
+ by driving the client against the real API in `tests/http.ts`.
219
+
220
+ `pairDevice()` declared an answer nobody sent (`api_key`, `device`). It
221
+ returns what the API returns: `device_id`, `name`, `key`, `workflow_id`,
222
+ `workflow_name`.
223
+
224
+ ## 1.0.1
225
+
226
+ ### Fixed
227
+
228
+ `documents()` takes `offset`. It always took `status`, `q` and `limit` and the
229
+ API always took `offset` as well, so a business with more than two hundred
230
+ documents had no way to reach the second page from this client. One field on
231
+ one type; the query string was already built from whatever the filter held.
232
+
233
+ ## 1.0.0
234
+
235
+ The first release under this name, and the first one on npm.
236
+
237
+ ### Renamed
238
+
239
+ `@signsealer/node` → **`@signsealer/sdk`**. The old name said where it ran,
240
+ which was never the interesting part and was going to be wrong the first time
241
+ somebody used it from an edge runtime or a browser. Nothing was ever published
242
+ under the old name, so there is no migration: this is the only name there has
243
+ been.
244
+
245
+ ### What it does that a hand-rolled client usually does not
246
+
247
+ **No dependencies.** `fetch` is in the runtime. A signing client that drags an
248
+ HTTP library into somebody's build is one that gets declined at review, and the
249
+ build refuses outright if `dependencies` is ever non-empty.
250
+
251
+ **Retries the failures worth retrying, with an idempotency key.** Every write
252
+ that creates something gets one automatically, so a network blip does not
253
+ become a second waiver. `422` is never retried. `429` is retried only when the
254
+ server says how long to wait and the wait is short — the rate-limit window is a
255
+ minute, so three guessed backoffs would land inside the same window and spend
256
+ the next one's budget too. A longer wait comes back as `error.retryAfter`, in
257
+ seconds, to schedule rather than block on.
258
+
259
+ **Surfaces the API's own sentence.** `SignSealerError` carries `message`,
260
+ `hint`, `code`, `status` and `requestId`. The message is frequently the
261
+ database's own words, which are more specific than anything a client layer
262
+ could write.
263
+
264
+ **Watches the allowance.** Every send reports how many agreements are left, kept
265
+ on `client.agreementsRemaining` — `null` on a plan that bills for overage, where
266
+ there is nothing to count down. A spent allowance answers `402`, not `429`, and
267
+ `error.quotaExceeded` says so. Never retried, by this client or any other worth
268
+ using: it comes back when the billing period turns.
269
+
270
+ ### The signer's side is a separate class
271
+
272
+ `SignSealerSigning` takes **no API key**, because on those routes a signing
273
+ token is the whole credential. A client that could send a key alongside a token
274
+ would be a client that widens somebody's authority by accident.
275
+
276
+ It covers consent, signing, one-time codes (`requestCode` / `confirmCode`), and
277
+ PDF templates — `link.pages` and `pageUrl(token, n)`, with each field's `place`
278
+ in fractions of the page a reader sees.
279
+
280
+ Consent is its own call and that is not an oversight: ESIGN requires consent to
281
+ electronic records to precede the transaction, and a system that records both
282
+ in the same instant cannot show that it did.
283
+
284
+ ### Shipped as ESM, CJS and types
285
+
286
+ `tsc` twice rather than a bundler — a bundler would be a build-time dependency
287
+ on a package whose selling point is having none. CJS is emitted as `.cjs`,
288
+ unambiguous to every Node since 12, so the `"type": "module"` at the root does
289
+ not have to be argued with.
290
+
291
+ The build smoke-tests the artefact rather than the source: it imports both
292
+ outputs, checks the client rejects a key that is not one, and checks the
293
+ declarations name what the README names.
294
+
295
+ ### Requires
296
+
297
+ Node 18 or newer, or any runtime with `fetch`. An API key belongs on a server.
package/README.md CHANGED
@@ -72,6 +72,12 @@ back when the billing period turns, and no amount of backing off will reach it.
72
72
  Subscribe to `billing.quota_approaching` if you would rather hear about it
73
73
  before the call that fails.
74
74
 
75
+ On the membership, which is paid from prepaid credit, the count is the
76
+ month's free signings left plus the signings the balance still covers, and a
77
+ `402` there clears as soon as credit is added or an automatic reload lands,
78
+ not only when the month turns; on Free, starting the membership clears it
79
+ too. `error.hint` says which case it is.
80
+
75
81
  ```ts
76
82
  try {
77
83
  await signsealer.send(documentId, signers);
@@ -106,6 +112,47 @@ Consent is a separate call and that is not an oversight: ESIGN requires consent
106
112
  to electronic records to precede the transaction, and a system that records
107
113
  both in the same instant cannot show that it did.
108
114
 
115
+ A field of kind `photo` takes a photograph, not text; the ID photo the business
116
+ asked for is taken the same way, and both are shrunk on the server:
117
+
118
+ ```ts
119
+ await signing.supplyPhoto(token, "boat_condition", { contentType: "image/jpeg", bytes });
120
+ const asked = await signing.idEvidence(token); // { offered: "id" | "id_selfie" | "off", … }
121
+ if (asked?.offered !== "off") await signing.captureIdEvidence(token, "id", { contentType: "image/jpeg", bytes });
122
+ ```
123
+
124
+ ### Drawing the questions
125
+
126
+ A template's questions arrive on `link.fields`, and three things about them
127
+ decide what a page should show:
128
+
129
+ - **`visible`** is the engine's own answer to a question's condition. Draw only
130
+ the visible ones. A hidden question is not required, and the signature is
131
+ checked against the same value, so a page that follows it is never refused
132
+ for a question it hid. Answering the earlier question differently clears
133
+ the hidden one on the server.
134
+ - **`block`** groups questions under one heading and introduction; `step: true`
135
+ means the block wants a page of its own with a Next button.
136
+ - **`link.body_format`** is `text` or `markdown`. A markdown body has headings,
137
+ bold, italics and lists, and printing it as text shows the signer the marks.
138
+
139
+ ```ts
140
+ const asked = link.fields.filter((f) => f.visible !== false);
141
+ for (const f of asked) await signing.supply(token, f.key, answerFor(f));
142
+ ```
143
+
144
+ When `link.document_after_questions` is true the business asked for the
145
+ questions first: show the document once no required visible question is left
146
+ unanswered, which is also exactly when a signature is accepted.
147
+
148
+ ### At the gate, and from a signing code
149
+
150
+ `documentSigners(id)` answers who has signed one document and nothing else;
151
+ `gateLink(documentId, signerId)` mints a fresh link for whoever has not, with
152
+ a QR code drawn as SVG to hold up. A paired tablet resolves the signing code
153
+ on a receipt with `packetByCode(code)` and starts what it owes with
154
+ `startPacketItem(itemId)`.
155
+
109
156
  ### When the business asks the signer for a code
110
157
 
111
158
  A business can require a one-time code before a signature (Settings →
@@ -276,6 +323,41 @@ publishing is what freezes the text people will have signed — so there is no
276
323
  `publish` method here on purpose. That is a decision somebody makes looking at
277
324
  the words.
278
325
 
326
+ Questions can be grouped, asked only when an earlier answer says so, and
327
+ flagged for a person to read:
328
+
329
+ ```ts
330
+ fields: [
331
+ { key: "drank", label: "Have you had a drink today?", kind: "choice", options: ["Yes", "No"],
332
+ flag_when: { equals: ["Yes"] },
333
+ block: "safety", block_label: "Before you shoot", block_step: true },
334
+ { key: "how_much", label: "How much?", kind: "paragraph",
335
+ show_if: { field: "drank", equals: ["Yes"] }, block: "safety" },
336
+ ],
337
+ ```
338
+
339
+ A condition can only look at a question above it, and a block's heading is
340
+ given once. The engine checks both and refuses by name, and a refused list
341
+ leaves no template behind.
342
+
343
+ ## Reading what was answered
344
+
345
+ ```ts
346
+ const doc = await client.document(documentId);
347
+ if (doc.flagged > 0) {
348
+ for (const a of doc.answers.filter((a) => a.flagged)) notify(a.label, a.value);
349
+ }
350
+ ```
351
+
352
+ `answers` lists every question in the form's order, with the signer it belongs
353
+ to. `asked: false` is a question its condition hid: no value, never flagged. A
354
+ sensitive answer is masked, as it is for the business's own staff.
355
+
356
+ Answers are read from the document and are **not in webhooks**, on purpose: a
357
+ webhook goes to whatever address was typed, often somebody else's tool, and
358
+ some answers are about a person's health. A webhook says something happened;
359
+ fetch the document to see what was said.
360
+
279
361
  ## Checking a certificate
280
362
 
281
363
  No credential at all. Anybody holding the printed code can do this.