@signsealer/sdk 1.7.0 → 1.11.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 +139 -4
- package/README.md +79 -11
- package/dist/cjs/index.cjs +193 -31
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +469 -34
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/index.js +191 -30
- package/dist/esm/index.js.map +1 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,140 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.11.0
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- `new SignSealerSigning({ deviceKey })`. Since 2 October the server keeps
|
|
8
|
+
`captured` on a signature only from a paired tablet of the business the
|
|
9
|
+
link belongs to, which sends its own credential as the bearer; from
|
|
10
|
+
anybody else the claim is dropped without an error and the signature is
|
|
11
|
+
dated when it arrives. This client sent no credential at all, so an
|
|
12
|
+
offline signature made through it lost the time it was taken. Given the
|
|
13
|
+
key `pairDevice` answered, `sign()` now sends it with a signature that
|
|
14
|
+
carries `captured`, and with nothing else.
|
|
15
|
+
- A photo refused because the server is reading others is a `429` with
|
|
16
|
+
`code: "busy"` and `Retry-After` (thirty seconds), where it was a `422`
|
|
17
|
+
(3 October). `supplyPhoto` and `captureIdEvidence` throw it as a
|
|
18
|
+
`SignSealerError` whose `retryable` is true and `retryAfter` is the wait;
|
|
19
|
+
nothing was kept, and the same photo can be sent again then. Code that
|
|
20
|
+
treated every refusal of a photo as final now has one it should retry.
|
|
21
|
+
|
|
22
|
+
### Fixed
|
|
23
|
+
|
|
24
|
+
- `Branding` declares what `GET /v1/branding` answers: `businessName`,
|
|
25
|
+
`primaryColor`, `hasLogo`, `signingHost`, `logoUrl` and the rest, in
|
|
26
|
+
camelCase. It declared `tenant_name`, `colour`, `has_logo`,
|
|
27
|
+
`has_logo_dark` and `signing_host`, which the API has never sent, so each
|
|
28
|
+
read as undefined. Code that compiled against the old names was reading
|
|
29
|
+
nothing; it now fails to compile, which is the point.
|
|
30
|
+
- `SignSealerSigning`'s errors carry `retryAfter`, read from `Retry-After`
|
|
31
|
+
as `SignSealer`'s do. They never did, so a `429` from a signing link --
|
|
32
|
+
a code asked for too soon, a busy photo -- said nothing about how long.
|
|
33
|
+
- `setWebhook`'s doc comment: since 3 October the server checks the
|
|
34
|
+
`events` a change sends as it checks `addWebhook`'s, and refuses a name
|
|
35
|
+
that is not an event with a `422` whose `hint` lists every one (00507).
|
|
36
|
+
This client sends what it is given, so a typo that used to be stored and
|
|
37
|
+
never fire is now an error you can see.
|
|
38
|
+
- `remind`'s doc comment says what 00507 changed: a signer is texted one
|
|
39
|
+
reminder over the life of their link, after which a reminder goes by
|
|
40
|
+
email alone, and one with no email address is refused with a `422`.
|
|
41
|
+
- `setWebhook()` is typed with what turning an endpoint back on answers:
|
|
42
|
+
`resumed`, `waiting` and `dropped_while_paused` (00289).
|
|
43
|
+
- Doc comments that described the API as it was: `templatePdf` (the server
|
|
44
|
+
draws a PDF's pages since 00474, not the uploader's browser), `remind`
|
|
45
|
+
(three a day per signer, twenty-five per document, 00500),
|
|
46
|
+
`recordSmsConsent` (all seven things the wording must say), and
|
|
47
|
+
`verifyWebhookRequest` (a hash of the raw body is a retry-stable key the
|
|
48
|
+
signature covers).
|
|
49
|
+
|
|
50
|
+
### Added
|
|
51
|
+
|
|
52
|
+
- `workflow_ids` on `setDevice` (00420): every form a tablet runs, in the
|
|
53
|
+
order its kiosk lists them. `PATCH /v1/devices/:id` has taken it since
|
|
54
|
+
00420 and this client could not send it.
|
|
55
|
+
- `TemplatePdf.drawing_failed` (00474): why the pages could not be drawn
|
|
56
|
+
from the file, when they could not.
|
|
57
|
+
- `StartedWorkflow.template_version` and `party_size`; `PacketSummary.added`
|
|
58
|
+
and `dropped`; the rest of a `DocumentRow` (`integrity_ok`,
|
|
59
|
+
`template_code`, `expires_at` and the others); `Workflow.asked_fields`,
|
|
60
|
+
`sender_fields`, `public_slug`, `time_zone` and the party settings
|
|
61
|
+
(`each_person_signs`, 00484); `Device.workflows` and the queue and version
|
|
62
|
+
fields its heartbeat keeps (00337, 00341, 00420); and every key of
|
|
63
|
+
`SigningLink.party` (`lead_name`, `described`, `minors`, `signing_for`,
|
|
64
|
+
and each added person's `open`, `claimed` and `opened`, 00491). All
|
|
65
|
+
optional: each is what the API already answered.
|
|
66
|
+
- `SigningField.from_sender` (00437). A box on an uploaded PDF that whoever
|
|
67
|
+
sent the document filled in: already answered, shown and never asked for.
|
|
68
|
+
- `SigningField.placed_words` (00438). What a placed box shows: a date or a
|
|
69
|
+
time in words, beside `placed_value`, which stays the answer.
|
|
70
|
+
- `PartnerProfile.review`, `PartnerProfile.earning` and
|
|
71
|
+
`PartnerProfile.earning_since` (00451). A partner account that enrolled
|
|
72
|
+
itself is reviewed by a person before its share starts: `review` is
|
|
73
|
+
`pending` until then, businesses are attributed meanwhile, and nothing
|
|
74
|
+
accrues until `earning` is true, counted from `earning_since`.
|
|
75
|
+
- `Account.texting` (00458): whether the business can text people, why
|
|
76
|
+
not when it cannot (`plan` or `test`), and the opt-in sentence to put
|
|
77
|
+
beside a "text me" box and record with `recordSmsConsent` when ticked.
|
|
78
|
+
- `time_zone` on `prepareDocument`, and `SigningLink.time_zone` (00476). The
|
|
79
|
+
zone a document's times are in ("America/Denver"): a time blank given as
|
|
80
|
+
`2026-10-03T09:00` is written "October 3, 2026 at 9:00 am MDT". An unknown
|
|
81
|
+
zone is refused with a 422. Without it, values go in as sent.
|
|
82
|
+
- `PartnerBusiness.source` can be `promotion`: a business that redeemed a
|
|
83
|
+
promotion code the partner handed out (00421).
|
|
84
|
+
|
|
85
|
+
## 1.10.0
|
|
86
|
+
|
|
87
|
+
### Added
|
|
88
|
+
|
|
89
|
+
- `SigningField.at_signing` and `SigningField.placed_value` (00427). A
|
|
90
|
+
signature box or a signing-date box placed on an uploaded PDF is filled by
|
|
91
|
+
signing itself -- the signature as typed, and the day it was signed in the
|
|
92
|
+
business's timezone -- so a signing page draws those boxes rather than
|
|
93
|
+
asking for them, and `sign()` no longer refuses for them.
|
|
94
|
+
`placed_value` is what a box on the page carries, for showing the
|
|
95
|
+
document as it will be sealed.
|
|
96
|
+
- `TemplateSettings.photos_in_copy`, and `photos_in_copy` on
|
|
97
|
+
`setTemplateSettings` (00428). The photographs a signer takes as answers
|
|
98
|
+
are printed on pages after the certificate in the signed PDF, each with
|
|
99
|
+
its question, when it was taken and its SHA-256, under the same seal. On
|
|
100
|
+
unless turned off; the certificate keeps every hash either way.
|
|
101
|
+
|
|
102
|
+
## 1.9.0
|
|
103
|
+
|
|
104
|
+
### Added
|
|
105
|
+
|
|
106
|
+
- `startPacket(packetId)` (00424): starts everything a packet still owes.
|
|
107
|
+
Items already started are left alone, so it is safe on every booking
|
|
108
|
+
update; one that cannot be started comes back under `skipped` with the
|
|
109
|
+
reason. Type `PacketStart`.
|
|
110
|
+
- `voidPacket(packetId, reason)`: the booking was cancelled. What nobody has
|
|
111
|
+
finished is voided; what somebody signed is kept and counted.
|
|
112
|
+
- `integrations()` and `integrationEvents(connectionId)`: the booking systems
|
|
113
|
+
this business can connect and its connections, and what arrived from one
|
|
114
|
+
and what became of it. Credentials and a connection's address are never
|
|
115
|
+
returned. Types `IntegrationProvider`, `IntegrationConnection`,
|
|
116
|
+
`IntegrationEvent`.
|
|
117
|
+
- `integrations()` also answers `needs_membership`, true on Free, because
|
|
118
|
+
connecting a booking system comes with the membership (00425); and each
|
|
119
|
+
connection carries `paused_reason`, `membership` when it was paused because
|
|
120
|
+
the membership ended. Such a connection resumes by itself when the
|
|
121
|
+
membership starts again.
|
|
122
|
+
|
|
123
|
+
## 1.8.0
|
|
124
|
+
|
|
125
|
+
### Added
|
|
126
|
+
|
|
127
|
+
- `SignSealerPartner` (00418): a partner reading its own revenue share, with
|
|
128
|
+
its OAuth client id and secret by HTTP Basic. `profile()` (the share,
|
|
129
|
+
custom branding and its monthly fee, businesses brought, this month so far,
|
|
130
|
+
and `signup_url`), `businesses({ limit, offset })` and `statements()`.
|
|
131
|
+
Read-only; every call is retried on a transient failure. A business's API
|
|
132
|
+
key is refused by the constructor.
|
|
133
|
+
- `SignSealerPartner.signupUrl(code)`: the partner's signup link, built
|
|
134
|
+
without a call.
|
|
135
|
+
- Types `PartnerProfile`, `PartnerMonthToDate`, `PartnerBusiness`,
|
|
136
|
+
`PartnerStatement` and `PartnerOptions`.
|
|
137
|
+
|
|
3
138
|
## 1.7.0
|
|
4
139
|
|
|
5
140
|
### Added
|
|
@@ -141,10 +276,10 @@ existed.
|
|
|
141
276
|
|
|
142
277
|
## 1.3.0
|
|
143
278
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
all of them.
|
|
279
|
+
Meant as the first version on npm since 1.0.0, and never published: its tag,
|
|
280
|
+
like 1.0.1's and 1.2.0's, was pushed while the publish workflow was not
|
|
281
|
+
running, so this entry and the ones below it describe changes that first
|
|
282
|
+
reached the registry in 1.4.0, which carries all of them.
|
|
148
283
|
|
|
149
284
|
### Added
|
|
150
285
|
|
package/README.md
CHANGED
|
@@ -94,7 +94,8 @@ try {
|
|
|
94
94
|
`SignSealerSigning` takes **no API key**, because on those routes a signing
|
|
95
95
|
token is the whole credential. It is a separate class on purpose: a client that
|
|
96
96
|
could send a key alongside a token would be a client that widens somebody's
|
|
97
|
-
authority by accident.
|
|
97
|
+
authority by accident. The one credential it carries is a paired tablet's own,
|
|
98
|
+
on an offline signature only (below).
|
|
98
99
|
|
|
99
100
|
```ts
|
|
100
101
|
import { SignSealerSigning } from "@signsealer/sdk";
|
|
@@ -121,6 +122,23 @@ const asked = await signing.idEvidence(token); // { offered: "id" | "id
|
|
|
121
122
|
if (asked?.offered !== "off") await signing.captureIdEvidence(token, "id", { contentType: "image/jpeg", bytes });
|
|
122
123
|
```
|
|
123
124
|
|
|
125
|
+
A photo the server could not read just then, because it was reading others,
|
|
126
|
+
is refused with a `429` whose `code` is `busy`: nothing was kept, and
|
|
127
|
+
`err.retryAfter` says how many seconds to wait (thirty). Tell the person, and
|
|
128
|
+
send the same photo again then. Any other refusal of a photo (`422`) will be
|
|
129
|
+
the same next time, and its message says why.
|
|
130
|
+
|
|
131
|
+
```ts
|
|
132
|
+
try {
|
|
133
|
+
await signing.supplyPhoto(token, "boat_condition", { contentType: "image/jpeg", bytes });
|
|
134
|
+
} catch (e) {
|
|
135
|
+
if (e instanceof SignSealerError && e.code === "busy") {
|
|
136
|
+
showNote(e.message); // "Photos are queueing here just now. …"
|
|
137
|
+
setTimeout(() => sendAgain(), (e.retryAfter ?? 30) * 1000);
|
|
138
|
+
} else throw e;
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
124
142
|
### Drawing the questions
|
|
125
143
|
|
|
126
144
|
A template's questions arrive on `link.fields`, and three things about them
|
|
@@ -221,18 +239,28 @@ if (pdf.has_pdf && !pdf.ready) {
|
|
|
221
239
|
}
|
|
222
240
|
```
|
|
223
241
|
|
|
224
|
-
Uploading the file is a dashboard step, not an API call:
|
|
225
|
-
|
|
226
|
-
|
|
242
|
+
Uploading the file is a dashboard step, not an API call: that is where the boxes
|
|
243
|
+
are placed on its pages. SignSealer draws the pictures a signer sees from the
|
|
244
|
+
file itself as it is uploaded, and a template cannot be published until every
|
|
245
|
+
page has one.
|
|
227
246
|
|
|
228
247
|
### Signing where there is no network
|
|
229
248
|
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
rather than accepted.
|
|
249
|
+
A paired tablet that took a signature offline passes `captured` with what the
|
|
250
|
+
device thought the time was. The server records when *it* received the event —
|
|
251
|
+
that is the part we can attest to — and keeps the claim beside it, marked as a
|
|
252
|
+
claim, with the clock difference computed rather than accepted.
|
|
253
|
+
|
|
254
|
+
The claim is kept only from a paired tablet of the business the link belongs
|
|
255
|
+
to, because the day it carries is the day written into the document. Give the
|
|
256
|
+
client the tablet's own credential — the `key` that `pairDevice` answered — and
|
|
257
|
+
it is sent with a `sign` that carries `captured`, and with nothing else. Without
|
|
258
|
+
it, `captured` is left out without an error and the signature is dated when it
|
|
259
|
+
arrives.
|
|
234
260
|
|
|
235
261
|
```ts
|
|
262
|
+
const signing = new SignSealerSigning({ deviceKey: tabletKey });
|
|
263
|
+
|
|
236
264
|
await signing.sign(token, "drawn", dataUri, {
|
|
237
265
|
offline: true,
|
|
238
266
|
at: capturedAt.toISOString(),
|
|
@@ -261,6 +289,8 @@ app.post("/hooks/signsealer",
|
|
|
261
289
|
if (!ok) return res.status(400).send(reason);
|
|
262
290
|
|
|
263
291
|
// Deliveries are at-least-once: the same event id arrives again on a retry.
|
|
292
|
+
// (A SHA-256 of the raw body is the same on a retry too, and is covered by
|
|
293
|
+
// the signature, which the id is not; see `verifyWebhookRequest`.)
|
|
264
294
|
if (await alreadyHandled(eventId)) return res.sendStatus(200);
|
|
265
295
|
|
|
266
296
|
await act(JSON.parse(req.body.toString("utf8")));
|
|
@@ -319,9 +349,10 @@ const { template_id } = await client.createTemplate({
|
|
|
319
349
|
```
|
|
320
350
|
|
|
321
351
|
Version 1, as a **draft**. A template is not usable until it is published, and
|
|
322
|
-
publishing is what freezes the text people will have signed
|
|
323
|
-
|
|
324
|
-
|
|
352
|
+
publishing is what freezes the text people will have signed. That is a decision
|
|
353
|
+
somebody makes looking at the words: `editTemplate(template_id, …)` changes the
|
|
354
|
+
draft until then, `publishTemplate(template_id)` publishes it, and
|
|
355
|
+
`reviseTemplate` makes the next version as a draft afterwards.
|
|
325
356
|
|
|
326
357
|
Questions can be grouped, asked only when an earlier answer says so, and
|
|
327
358
|
flagged for a person to read:
|
|
@@ -372,6 +403,43 @@ changed since it was issued. That is reported and never corrected — a
|
|
|
372
403
|
verification service that quietly re-derived could not answer the one question
|
|
373
404
|
it exists for.
|
|
374
405
|
|
|
406
|
+
## For partners: what you have earned
|
|
407
|
+
|
|
408
|
+
A platform SignSealer has enrolled as a partner shares in the revenue of every
|
|
409
|
+
business it brings, for as long as that business pays. A business is yours
|
|
410
|
+
when it signs up through your link, installs your app in its first weeks, or
|
|
411
|
+
redeems a promotion code made for you; a business your own people own is not.
|
|
412
|
+
`SignSealerPartner` reads it, with your OAuth client's id and secret, never a
|
|
413
|
+
business's key:
|
|
414
|
+
|
|
415
|
+
```ts
|
|
416
|
+
import { SignSealerPartner } from "@signsealer/sdk";
|
|
417
|
+
|
|
418
|
+
const partner = new SignSealerPartner({
|
|
419
|
+
clientId: process.env.SIGNSEALER_CLIENT_ID!,
|
|
420
|
+
clientSecret: process.env.SIGNSEALER_CLIENT_SECRET!,
|
|
421
|
+
});
|
|
422
|
+
|
|
423
|
+
const me = await partner.profile();
|
|
424
|
+
// { referral_code: "deckpos", businesses: 12,
|
|
425
|
+
// month_to_date: { revenue_cents: 41250, share_cents: …, … },
|
|
426
|
+
// signup_url: "https://app.signsealer.com/signup?partner=deckpos" }
|
|
427
|
+
|
|
428
|
+
const { data, has_more } = await partner.businesses({ limit: 100 });
|
|
429
|
+
const months = await partner.statements(); // every closed month, newest first
|
|
430
|
+
|
|
431
|
+
SignSealerPartner.signupUrl("deckpos"); // the same link, without a call
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
It only reads. Your share and programme come from your partner agreement, and
|
|
435
|
+
a month's statement is written once, when the month is over; `paid` turns true
|
|
436
|
+
when the payment is recorded. A partner account that enrolled itself is looked
|
|
437
|
+
at by a person first: `review` is `pending` until then, businesses are recorded
|
|
438
|
+
as yours meanwhile, and nothing accrues until `earning` is true, counted from
|
|
439
|
+
`earning_since`. The revenue shared is what a business paid for
|
|
440
|
+
and used, after card fees and the carrier's cost of its texts; credit
|
|
441
|
+
SignSealer gave away earns nothing.
|
|
442
|
+
|
|
375
443
|
## Options
|
|
376
444
|
|
|
377
445
|
```ts
|
package/dist/cjs/index.cjs
CHANGED
|
@@ -49,10 +49,9 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
49
49
|
};
|
|
50
50
|
})();
|
|
51
51
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
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;
|
|
52
|
+
exports.WEBHOOK_TOLERANCE_SECONDS = exports.WEBHOOK_SIGNATURE_HEADER = exports.WEBHOOK_TIMESTAMP_HEADER = exports.WEBHOOK_EVENT_HEADER = exports.SignSealerPartner = exports.SignSealerSigning = exports.SignSealer = exports.SignSealerError = void 0;
|
|
53
53
|
exports.verifyWebhook = verifyWebhook;
|
|
54
54
|
exports.verifyWebhookRequest = verifyWebhookRequest;
|
|
55
|
-
/* ------------------------------------------------------------------ errors */
|
|
56
55
|
class SignSealerError extends Error {
|
|
57
56
|
status;
|
|
58
57
|
code;
|
|
@@ -134,7 +133,6 @@ class SignSealer {
|
|
|
134
133
|
this.#fetch = opts.fetch ?? globalThis.fetch;
|
|
135
134
|
}
|
|
136
135
|
/* ------------------------------------------------------------- account */
|
|
137
|
-
/** Prove the key works, and say whose account it is. */
|
|
138
136
|
/**
|
|
139
137
|
* The brand this account shows its signers.
|
|
140
138
|
*
|
|
@@ -146,6 +144,7 @@ class SignSealer {
|
|
|
146
144
|
branding() {
|
|
147
145
|
return this.#call("GET", "/v1/branding");
|
|
148
146
|
}
|
|
147
|
+
/** Prove the key works, and say whose account it is. */
|
|
149
148
|
account() {
|
|
150
149
|
return this.#call("GET", "/v1/account");
|
|
151
150
|
}
|
|
@@ -206,14 +205,6 @@ class SignSealer {
|
|
|
206
205
|
setTemplateSettings(id, input) {
|
|
207
206
|
return this.#call("PATCH", `/v1/templates/${encodeURIComponent(id)}/settings`, input);
|
|
208
207
|
}
|
|
209
|
-
/**
|
|
210
|
-
* Whether a template is an uploaded PDF, and whether it is usable yet.
|
|
211
|
-
*
|
|
212
|
-
* `ready` is the one to check: a PDF template cannot be published until
|
|
213
|
-
* every page has a picture a signer can read. Uploading the file is a
|
|
214
|
-
* dashboard step — drawing those pictures needs a browser, which a server
|
|
215
|
-
* does not have — so this is read-only on purpose.
|
|
216
|
-
*/
|
|
217
208
|
/**
|
|
218
209
|
* Create a template. Version 1, as a draft.
|
|
219
210
|
*
|
|
@@ -230,6 +221,14 @@ class SignSealer {
|
|
|
230
221
|
createTemplate(input, idempotencyKey) {
|
|
231
222
|
return this.#call("POST", "/v1/templates", input, idempotencyKey);
|
|
232
223
|
}
|
|
224
|
+
/**
|
|
225
|
+
* Whether a template is an uploaded PDF, and whether it is usable yet.
|
|
226
|
+
*
|
|
227
|
+
* `ready` is the one to check: a PDF template cannot be published until
|
|
228
|
+
* SignSealer has drawn a picture of every page from the file itself
|
|
229
|
+
* (00474), which it does as the file is uploaded. Uploading the file is a
|
|
230
|
+
* dashboard step, where the boxes are placed; there is no API route for it.
|
|
231
|
+
*/
|
|
233
232
|
templatePdf(id) {
|
|
234
233
|
return this.#call("GET", `/v1/templates/${encodeURIComponent(id)}/pdf`);
|
|
235
234
|
}
|
|
@@ -246,9 +245,12 @@ class SignSealer {
|
|
|
246
245
|
* `wording` is the field this method exists for. Send the exact words that
|
|
247
246
|
* were in front of the person, because it is kept verbatim and it is what a
|
|
248
247
|
* carrier asks for. It has to say that replying STOP opts out, that HELP
|
|
249
|
-
* gets help, that message and data rates may apply,
|
|
250
|
-
* frequency varies
|
|
251
|
-
*
|
|
248
|
+
* gets help, that message and data rates may apply, that message
|
|
249
|
+
* frequency varies, that consent is not a condition of purchase, and that
|
|
250
|
+
* the number is not shared or sold, and link the terms and the privacy
|
|
251
|
+
* policy; a disclosure missing any of those is refused with 422 naming
|
|
252
|
+
* which, and nothing is recorded. `account().texting.wording` is a
|
|
253
|
+
* sentence that passes.
|
|
252
254
|
*
|
|
253
255
|
* One call covers the link, the reminder and the confirmation. Somebody who
|
|
254
256
|
* agreed to those agreed to all three, and an API that made you post three
|
|
@@ -331,8 +333,13 @@ class SignSealer {
|
|
|
331
333
|
}
|
|
332
334
|
/**
|
|
333
335
|
* Send one signer a reminder with a fresh link (1.6.0); the one they had
|
|
334
|
-
* stops working. Refused inside an hour of their last reminder,
|
|
336
|
+
* stops working. Refused (422) inside an hour of their last reminder, past
|
|
337
|
+
* three to one signer or twenty-five for one document in a day, and for
|
|
335
338
|
* somebody there is no way to reach -- with their link left as it was.
|
|
339
|
+
* A signer is texted one reminder over the life of their link, because
|
|
340
|
+
* that is what they agreed to (00507): after it, a reminder goes by email
|
|
341
|
+
* alone (`by: "email"`), and one with no email address is refused (422).
|
|
342
|
+
* `reminded: true` means it was queued: it is screened before it leaves.
|
|
336
343
|
*/
|
|
337
344
|
remind(documentId, signerId, idempotencyKey) {
|
|
338
345
|
return this.#call("POST", `/v1/documents/${encodeURIComponent(documentId)}/signers/${encodeURIComponent(signerId)}/remind`, {}, idempotencyKey);
|
|
@@ -462,6 +469,33 @@ class SignSealer {
|
|
|
462
469
|
startPacketItem(itemId, idempotencyKey) {
|
|
463
470
|
return this.#call("POST", `/v1/packets/items/${encodeURIComponent(itemId)}/start`, undefined, idempotencyKey);
|
|
464
471
|
}
|
|
472
|
+
/**
|
|
473
|
+
* Start everything a packet still owes (00424). Items already started are
|
|
474
|
+
* left alone, so this is safe to call on every booking update; an item
|
|
475
|
+
* that cannot be started comes back under `skipped` with the reason.
|
|
476
|
+
*/
|
|
477
|
+
startPacket(packetId) {
|
|
478
|
+
return this.#call("POST", `/v1/packets/${encodeURIComponent(packetId)}/start`);
|
|
479
|
+
}
|
|
480
|
+
/**
|
|
481
|
+
* Void a packet because the booking was cancelled (00424): what nobody has
|
|
482
|
+
* finished is voided with the reason, what somebody signed is kept.
|
|
483
|
+
*/
|
|
484
|
+
voidPacket(packetId, reason) {
|
|
485
|
+
return this.#call("POST", `/v1/packets/${encodeURIComponent(packetId)}/void`, { reason });
|
|
486
|
+
}
|
|
487
|
+
/* -------------------------------------------------------- integrations */
|
|
488
|
+
/**
|
|
489
|
+
* The booking systems this business can connect, and its connections (00424).
|
|
490
|
+
* `needs_membership` is true on Free: connecting one comes with the membership (00425).
|
|
491
|
+
*/
|
|
492
|
+
integrations() {
|
|
493
|
+
return this.#call("GET", "/v1/integrations");
|
|
494
|
+
}
|
|
495
|
+
/** What arrived from one connection and what became of it, newest first. */
|
|
496
|
+
integrationEvents(connectionId) {
|
|
497
|
+
return this.#call("GET", `/v1/integrations/${encodeURIComponent(connectionId)}/events`);
|
|
498
|
+
}
|
|
465
499
|
/* ------------------------------------------------------------ webhooks */
|
|
466
500
|
webhooks() {
|
|
467
501
|
return this.#call("GET", "/v1/webhooks");
|
|
@@ -469,6 +503,14 @@ class SignSealer {
|
|
|
469
503
|
addWebhook(input, idempotencyKey) {
|
|
470
504
|
return this.#call("POST", "/v1/webhooks", input, idempotencyKey);
|
|
471
505
|
}
|
|
506
|
+
/**
|
|
507
|
+
* Change an endpoint. Turning one back on forgives its failures and sends
|
|
508
|
+
* what it held: `resumed` says it was paused, `waiting` how many are now
|
|
509
|
+
* on their way, and `dropped_while_paused` how many the hold could not
|
|
510
|
+
* keep (00289). `events`, when given, replaces the list and is checked as
|
|
511
|
+
* `addWebhook`'s is: a name that is not an event is refused (422), and the
|
|
512
|
+
* error's `hint` lists every one there is (00507).
|
|
513
|
+
*/
|
|
472
514
|
setWebhook(id, input) {
|
|
473
515
|
return this.#call("PATCH", `/v1/webhooks/${encodeURIComponent(id)}`, input);
|
|
474
516
|
}
|
|
@@ -706,13 +748,26 @@ exports.SignSealer = SignSealer;
|
|
|
706
748
|
*
|
|
707
749
|
* Use this to build your own signing page. If you want ours, send the signer
|
|
708
750
|
* to `https://api.signsealer.com/s/<token>` and skip all of it.
|
|
751
|
+
*
|
|
752
|
+
* The one exception is a paired tablet's own credential, `deviceKey` (1.11.0),
|
|
753
|
+
* sent on one call only: a signature that carries `captured`. The server keeps
|
|
754
|
+
* an offline signature's claim about when it was taken only from a paired
|
|
755
|
+
* tablet of the business the link belongs to, because that day is the day the
|
|
756
|
+
* document says it was signed, and it asks for the tablet's credential to know
|
|
757
|
+
* it is one. Without it the claim is dropped -- silently, not refused -- and the
|
|
758
|
+
* signature is dated when it arrives. Nothing else here ever sends it.
|
|
709
759
|
*/
|
|
710
760
|
class SignSealerSigning {
|
|
711
761
|
#base;
|
|
712
762
|
#fetch;
|
|
763
|
+
#deviceKey;
|
|
713
764
|
constructor(opts = {}) {
|
|
765
|
+
if (opts.deviceKey !== undefined && !opts.deviceKey.startsWith("mk_")) {
|
|
766
|
+
throw new Error("a device credential looks like mk_live_… or mk_test_…: the key pairDevice answered");
|
|
767
|
+
}
|
|
714
768
|
this.#base = withoutTrailingSlashes(opts.baseUrl ?? "https://api.signsealer.com");
|
|
715
769
|
this.#fetch = opts.fetch ?? globalThis.fetch;
|
|
770
|
+
this.#deviceKey = opts.deviceKey;
|
|
716
771
|
}
|
|
717
772
|
/**
|
|
718
773
|
* Everything the page needs from one token.
|
|
@@ -781,6 +836,12 @@ class SignSealerSigning {
|
|
|
781
836
|
* kind `photo`, shrunk on the server, kept encrypted with the document
|
|
782
837
|
* for as long as the document is kept; the field carries its hash. A
|
|
783
838
|
* second photograph replaces the first.
|
|
839
|
+
*
|
|
840
|
+
* When the server is reading other photos, or another from this link, it
|
|
841
|
+
* is refused with a 429 `busy` and nothing is kept: the error's
|
|
842
|
+
* `retryable` is true and `retryAfter` says how many seconds to wait
|
|
843
|
+
* (thirty). Show the person its message and send the same photo again
|
|
844
|
+
* then; this client does not wait that long inside a call for you.
|
|
784
845
|
*/
|
|
785
846
|
supplyPhoto(token, key, image, options = {}) {
|
|
786
847
|
return this.#call("POST", `/v1/sign/${encodeURIComponent(token)}/fields/${encodeURIComponent(key)}/photo`, {
|
|
@@ -825,7 +886,8 @@ class SignSealerSigning {
|
|
|
825
886
|
/**
|
|
826
887
|
* A photo of the ID, or of the person, when the business asked (00339).
|
|
827
888
|
* Kept encrypted for thirty days, the hash on the trail. Refused when
|
|
828
|
-
* the business did not ask
|
|
889
|
+
* the business did not ask; refused as busy, to be sent again after
|
|
890
|
+
* `retryAfter` seconds, as `supplyPhoto` is.
|
|
829
891
|
*/
|
|
830
892
|
captureIdEvidence(token, kind, image, captured) {
|
|
831
893
|
return this.#call("POST", `/v1/sign/${encodeURIComponent(token)}/id-evidence`, {
|
|
@@ -834,8 +896,13 @@ class SignSealerSigning {
|
|
|
834
896
|
...(captured ? { captured } : {}),
|
|
835
897
|
});
|
|
836
898
|
}
|
|
899
|
+
/**
|
|
900
|
+
* Sign. `captured` is for a signature a paired tablet took with no
|
|
901
|
+
* network, and is kept only when the client was built with that tablet's
|
|
902
|
+
* `deviceKey`, which goes with this call and no other; see the class.
|
|
903
|
+
*/
|
|
837
904
|
sign(token, method, value, captured) {
|
|
838
|
-
return this.#call("POST", `/v1/sign/${encodeURIComponent(token)}`, { method, value, ...(captured ? { captured } : {}) });
|
|
905
|
+
return this.#call("POST", `/v1/sign/${encodeURIComponent(token)}`, { method, value, ...(captured ? { captured } : {}) }, captured ? this.#deviceKey : undefined);
|
|
839
906
|
}
|
|
840
907
|
decline(token, reason) {
|
|
841
908
|
return this.#call("POST", `/v1/sign/${encodeURIComponent(token)}/decline`, { reason });
|
|
@@ -857,12 +924,16 @@ class SignSealerSigning {
|
|
|
857
924
|
second signature the engine correctly declines. Retrying would turn a
|
|
858
925
|
clear refusal into a confusing one.
|
|
859
926
|
*/
|
|
860
|
-
async #call(method, path, body) {
|
|
927
|
+
async #call(method, path, body, deviceKey) {
|
|
861
928
|
let res;
|
|
862
929
|
try {
|
|
863
930
|
res = await this.#fetch(`${this.#base}${path}`, {
|
|
864
931
|
method,
|
|
865
|
-
headers:
|
|
932
|
+
headers: {
|
|
933
|
+
...(body === undefined ? {} : { "content-type": "application/json" }),
|
|
934
|
+
/* Only ever `sign` with `captured`, from a client given a tablet's credential. */
|
|
935
|
+
...(deviceKey ? { authorization: `Bearer ${deviceKey}` } : {}),
|
|
936
|
+
},
|
|
866
937
|
...(body === undefined ? {} : { body: JSON.stringify(body) }),
|
|
867
938
|
});
|
|
868
939
|
}
|
|
@@ -875,10 +946,100 @@ class SignSealerSigning {
|
|
|
875
946
|
if (res.ok)
|
|
876
947
|
return parsed;
|
|
877
948
|
const err = parsed.error;
|
|
878
|
-
throw new SignSealerError(res.status, err?.code ?? "unknown", err?.message ?? `SignSealer returned ${res.status}`, err?.hint, requestId
|
|
949
|
+
throw new SignSealerError(res.status, err?.code ?? "unknown", err?.message ?? `SignSealer returned ${res.status}`, err?.hint, requestId,
|
|
950
|
+
/* 1.11.0: how long the server asked for, so a page can say "in half a minute" and try then. */
|
|
951
|
+
waitAsked(res.headers.get("retry-after")));
|
|
879
952
|
}
|
|
880
953
|
}
|
|
881
954
|
exports.SignSealerSigning = SignSealerSigning;
|
|
955
|
+
/**
|
|
956
|
+
* A partner reading its own revenue share (1.8.0): the businesses it brought,
|
|
957
|
+
* what they have paid this month, and every closed month's statement.
|
|
958
|
+
*
|
|
959
|
+
* Authenticated with the partner's OAuth client id and secret, by HTTP Basic
|
|
960
|
+
* -- never with a business's API key or access token, which act as one
|
|
961
|
+
* business. Only a partner SignSealer has enrolled can use it, and it only
|
|
962
|
+
* reads: the share and the programme are set by SignSealer, from the signed
|
|
963
|
+
* agreement. Keep the secret on a server.
|
|
964
|
+
*/
|
|
965
|
+
class SignSealerPartner {
|
|
966
|
+
#auth;
|
|
967
|
+
#base;
|
|
968
|
+
#attempts;
|
|
969
|
+
#fetch;
|
|
970
|
+
constructor(opts) {
|
|
971
|
+
if (!opts?.clientId || !opts?.clientSecret) {
|
|
972
|
+
throw new Error("a partner client needs its clientId and clientSecret");
|
|
973
|
+
}
|
|
974
|
+
if (opts.clientId.startsWith("mk_") || opts.clientSecret.startsWith("mk_")) {
|
|
975
|
+
throw new Error("that is a business's API key; the partner API takes your OAuth client id and secret");
|
|
976
|
+
}
|
|
977
|
+
const pair = `${encodeURIComponent(opts.clientId)}:${encodeURIComponent(opts.clientSecret)}`;
|
|
978
|
+
this.#auth = `Basic ${bytesToBase64(new TextEncoder().encode(pair))}`;
|
|
979
|
+
this.#base = withoutTrailingSlashes(opts.baseUrl ?? "https://api.signsealer.com");
|
|
980
|
+
this.#attempts = Math.max(1, opts.maxAttempts ?? 3);
|
|
981
|
+
this.#fetch = opts.fetch ?? globalThis.fetch;
|
|
982
|
+
}
|
|
983
|
+
/**
|
|
984
|
+
* The link to hand a business, from your referral code, without a call.
|
|
985
|
+
* `profile().signup_url` is the same link.
|
|
986
|
+
*/
|
|
987
|
+
static signupUrl(referralCode, appOrigin = "https://app.signsealer.com") {
|
|
988
|
+
return `${withoutTrailingSlashes(appOrigin)}/signup?partner=${encodeURIComponent(referralCode)}`;
|
|
989
|
+
}
|
|
990
|
+
/** Your programme, this month so far, and your signup link. */
|
|
991
|
+
profile() {
|
|
992
|
+
return this.#get("/v1/partner");
|
|
993
|
+
}
|
|
994
|
+
/** The businesses you brought, newest first. `limit` is 1 to 200, 50 when left out. */
|
|
995
|
+
businesses(opts = {}) {
|
|
996
|
+
const q = new URLSearchParams();
|
|
997
|
+
if (opts.limit !== undefined)
|
|
998
|
+
q.set("limit", String(opts.limit));
|
|
999
|
+
if (opts.offset !== undefined)
|
|
1000
|
+
q.set("offset", String(opts.offset));
|
|
1001
|
+
const qs = q.toString();
|
|
1002
|
+
return this.#get(`/v1/partner/businesses${qs ? `?${qs}` : ""}`);
|
|
1003
|
+
}
|
|
1004
|
+
/** Every closed month, newest first. */
|
|
1005
|
+
async statements() {
|
|
1006
|
+
const out = await this.#get("/v1/partner/statements");
|
|
1007
|
+
return out.data;
|
|
1008
|
+
}
|
|
1009
|
+
/*
|
|
1010
|
+
Every call only reads, so a transient failure is retried as it is: there
|
|
1011
|
+
is nothing a second GET could do twice.
|
|
1012
|
+
*/
|
|
1013
|
+
async #get(path) {
|
|
1014
|
+
for (let attempt = 1;; attempt += 1) {
|
|
1015
|
+
let res;
|
|
1016
|
+
try {
|
|
1017
|
+
res = await this.#fetch(`${this.#base}${path}`, {
|
|
1018
|
+
method: "GET",
|
|
1019
|
+
headers: { authorization: this.#auth, accept: "application/json" },
|
|
1020
|
+
});
|
|
1021
|
+
}
|
|
1022
|
+
catch (cause) {
|
|
1023
|
+
if (attempt < this.#attempts) {
|
|
1024
|
+
await sleep(backoff(attempt));
|
|
1025
|
+
continue;
|
|
1026
|
+
}
|
|
1027
|
+
throw new SignSealerError(0, "network", cause instanceof Error ? cause.message : "the request did not reach SignSealer", undefined, undefined);
|
|
1028
|
+
}
|
|
1029
|
+
const requestId = res.headers.get("x-request-id") ?? undefined;
|
|
1030
|
+
const text = await res.text();
|
|
1031
|
+
const parsed = text ? safeJson(text) : {};
|
|
1032
|
+
if (res.ok)
|
|
1033
|
+
return parsed;
|
|
1034
|
+
const err = parsed.error;
|
|
1035
|
+
const failure = new SignSealerError(res.status, err?.code ?? "unknown", err?.message ?? `SignSealer returned ${res.status}`, err?.hint, requestId, waitAsked(res.headers.get("retry-after")));
|
|
1036
|
+
if (!failure.retryable || attempt >= this.#attempts)
|
|
1037
|
+
throw failure;
|
|
1038
|
+
await sleep(backoff(attempt));
|
|
1039
|
+
}
|
|
1040
|
+
}
|
|
1041
|
+
}
|
|
1042
|
+
exports.SignSealerPartner = SignSealerPartner;
|
|
882
1043
|
/**
|
|
883
1044
|
* `Retry-After`, as seconds, when it is a number we believe.
|
|
884
1045
|
*
|
|
@@ -1125,18 +1286,19 @@ function headerOf(headers, name) {
|
|
|
1125
1286
|
* signed bytes again with a different id on them, and a receiver keyed on the
|
|
1126
1287
|
* id will treat the replay as a new event.
|
|
1127
1288
|
*
|
|
1128
|
-
*
|
|
1129
|
-
*
|
|
1130
|
-
*
|
|
1131
|
-
*
|
|
1132
|
-
*
|
|
1133
|
-
*
|
|
1134
|
-
*
|
|
1135
|
-
* the
|
|
1289
|
+
* A key derived from `timestamp.body` is authenticated but is *not* stable
|
|
1290
|
+
* across retries, because the sender signs a fresh timestamp on every attempt;
|
|
1291
|
+
* this SDK briefly returned one, which deduplicated replays and broke ordinary
|
|
1292
|
+
* retries, which is the worse failure of the two. A SHA-256 of the body alone
|
|
1293
|
+
* is both: the signature covers the body, and a delivery's body is built once
|
|
1294
|
+
* and sent unchanged on every retry. That is what the WordPress plugin keys on
|
|
1295
|
+
* (1.14.4). What it cannot tell apart is a replay a person asked for
|
|
1296
|
+
* (`replayWebhookDelivery`), which sends the same body under a new id. The
|
|
1297
|
+
* whole fix is to bring the id inside the signature under a `v2=` scheme,
|
|
1298
|
+
* and that is a change to the wire rather than to this file.
|
|
1136
1299
|
*
|
|
1137
|
-
* Until then: deduplicate on `eventId`,
|
|
1138
|
-
* window would be harmful to your system
|
|
1139
|
-
* against your records before acting on it.
|
|
1300
|
+
* Until then: deduplicate on `eventId`, or on a hash of the raw body when a
|
|
1301
|
+
* replay inside a five-minute window would be harmful to your system.
|
|
1140
1302
|
*/
|
|
1141
1303
|
async function verifyWebhookRequest(opts) {
|
|
1142
1304
|
const result = await verifyWebhook({
|