@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 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
- 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.
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: the page pictures have
225
- to be drawn by a browser, and a server does not have one — so a route that took
226
- the bytes would leave a template that could never be published.
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
- Pass `captured` with what the device thought the time was. The server records
231
- when *it* received the event — that is the part we can attest to — and keeps
232
- your claim beside it, marked as a claim, with the clock difference computed
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 — so there is no
323
- `publish` method here on purpose. That is a decision somebody makes looking at
324
- the words.
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
@@ -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, and that message
250
- * frequency varies; a disclosure missing any of those is refused with 422
251
- * naming which, and nothing is recorded.
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, and for
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: body === undefined ? {} : { "content-type": "application/json" },
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
- * There is no way to close that from inside this package today, and it is
1129
- * worth saying rather than implying otherwise. A key derived from the signed
1130
- * material — the hash of `timestamp.body` — is authenticated but is *not*
1131
- * stable across retries, because the sender signs a fresh timestamp on every
1132
- * attempt; this SDK briefly returned one, which deduplicated replays and broke
1133
- * ordinary retries, which is the worse failure of the two. The fix is to bring
1134
- * the id inside the signature under a `v2=` scheme, and that is a change to
1135
- * the wire rather than to this file.
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`, and if a replay inside a five-minute
1138
- * window would be harmful to your system, check the event's own contents
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({