@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 +205 -0
- package/README.md +76 -0
- package/dist/cjs/index.cjs +205 -6
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +582 -25
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/index.js +171 -5
- package/dist/esm/index.js.map +1 -1
- package/package.json +26 -9
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.
|
package/dist/cjs/index.cjs
CHANGED
|
@@ -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
|
|
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
|
-
* `
|
|
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;
|