@signsealer/sdk 1.0.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.
@@ -0,0 +1,796 @@
1
+ /**
2
+ * `@signsealer/sdk` — the client an integration actually holds.
3
+ *
4
+ * Deliberately dependency-free: `fetch` is in the runtime, and a signing SDK
5
+ * that drags a HTTP library into somebody's build is a signing SDK that gets
6
+ * declined at review. It runs anywhere `fetch` does, which is every Node since
7
+ * 18, every edge runtime and the browser — though a key belongs on a server.
8
+ *
9
+ * Three things it does that a hand-rolled client usually does not:
10
+ *
11
+ * - retries the failures worth retrying, with an idempotency key, so a
12
+ * network blip does not become a second waiver;
13
+ * - surfaces the API's own sentence rather than "Request failed with 422";
14
+ * - keeps the request id, so a support mail can quote something we can look
15
+ * up.
16
+ */
17
+ export declare class SignSealerError extends Error {
18
+ readonly status: number;
19
+ readonly code: string;
20
+ readonly message: string;
21
+ readonly hint: string | undefined;
22
+ readonly requestId: string | undefined;
23
+ /** Seconds the server asked you to wait, from `Retry-After`. */
24
+ readonly retryAfter?: number | undefined;
25
+ constructor(status: number, code: string, message: string, hint: string | undefined, requestId: string | undefined,
26
+ /** Seconds the server asked you to wait, from `Retry-After`. */
27
+ retryAfter?: number | undefined);
28
+ /** Worth trying again unchanged: transient by nature, not by hope. */
29
+ get retryable(): boolean;
30
+ /**
31
+ * The month's allowance is spent, or the business set a spending limit and
32
+ * this period reached it.
33
+ *
34
+ * Deliberately not retryable, and that is the point of it having its own
35
+ * status: a 429 means come back shortly, and this will not be there
36
+ * shortly. Handle it by telling somebody, not by waiting — the plan has to
37
+ * change, or the period has to turn.
38
+ */
39
+ get quotaExceeded(): boolean;
40
+ }
41
+ export interface Account {
42
+ tenant_id: string;
43
+ name: string;
44
+ slug: string;
45
+ key_label: string;
46
+ scopes: string[];
47
+ }
48
+ /** What `recordSmsConsent` wrote, with the number as we normalised it. */
49
+ export interface SmsConsentRecorded {
50
+ /** E.164. One number written three ways is one record, and this is it. */
51
+ phone: string;
52
+ /** The link, the reminder and the confirmation — all three, from one call. */
53
+ purposes: string[];
54
+ }
55
+ export interface SmsConsent {
56
+ phone: string;
57
+ /** What the engine will actually do: consent live, and the number not suppressed. */
58
+ may_text: boolean;
59
+ /** Why not, when `may_text` is false: they opted out, we cannot reach the number, or nobody ever asked. */
60
+ why_not: "revoked" | "suppressed" | "no_consent" | null;
61
+ /** Where the business said the number came from, in their words. */
62
+ obtained_via: string | null;
63
+ obtained_at: string | null;
64
+ }
65
+ export interface Template {
66
+ template_id: string;
67
+ code: string;
68
+ name: string;
69
+ kind: string;
70
+ version: number;
71
+ is_published: boolean;
72
+ is_latest: boolean;
73
+ }
74
+ /** One question a template asks besides a signature. */
75
+ export interface Ask {
76
+ /** Lower-case, letters then letters/digits/underscore, up to 59 characters. */
77
+ key: string;
78
+ label?: string;
79
+ kind: string;
80
+ /** Required unless it says otherwise. */
81
+ required?: boolean;
82
+ /**
83
+ * Masks the answer wherever staff read it back. **Not** on the sealed
84
+ * PDF: that is the document which was signed, and hiding part of it
85
+ * afterwards would make the seal a claim about something nobody can see.
86
+ */
87
+ sensitive?: boolean;
88
+ supplied_by?: "adult" | "per_child" | "staff";
89
+ options?: string[];
90
+ hint?: string;
91
+ }
92
+ /** What `createTemplate` takes. */
93
+ export interface TemplateInput {
94
+ /** Lower-case, starting with a letter: `rental-agreement`, `liability_waiver`. */
95
+ code: string;
96
+ name: string;
97
+ kind: "nda" | "waiver" | "contract" | "consent" | "policy" | "other";
98
+ /** The words people will sign. `{{variable}}` is substituted at prepare time. */
99
+ body: string;
100
+ variables?: string[];
101
+ grants?: Record<string, unknown>;
102
+ consent_text?: string | null;
103
+ /** Up to 50. Set here rather than in a second call — see `createTemplate`. */
104
+ fields?: Ask[];
105
+ }
106
+ /** The brand an account shows its signers. SignSealer's own without the white-label add-on. */
107
+ export interface Branding {
108
+ tenant_name: string;
109
+ /** Hex, or null where the business has not set one. */
110
+ colour?: string | null;
111
+ has_logo?: boolean;
112
+ has_logo_dark?: boolean;
113
+ /** The host this business's signing links use. */
114
+ signing_host?: string | null;
115
+ [key: string]: unknown;
116
+ }
117
+ /** Where a one-time code went. The address is masked; you are not told it. */
118
+ export interface CodeSent {
119
+ channel: "email" | "sms";
120
+ /** `d•••@example.com`, or `•••• ••• 0142`. Enough to say where, not enough to learn it. */
121
+ sent_to: string;
122
+ /** ISO 8601. Another code will not be sent before this. */
123
+ resend_after: string;
124
+ }
125
+ /**
126
+ * What came of a code the signer typed.
127
+ *
128
+ * A wrong code is `ok: false` with `attempts_left`, not an error — see
129
+ * `confirmCode`. `already` means this signer was verified before, which is
130
+ * a success, not a failure.
131
+ */
132
+ export interface CodeChecked {
133
+ ok: boolean;
134
+ reason?: string;
135
+ attempts_left?: number;
136
+ expired?: boolean;
137
+ already?: boolean;
138
+ }
139
+ /** What `templatePdf` answers. Everything past `has_pdf` is absent when it is false. */
140
+ export interface TemplatePdf {
141
+ has_pdf: boolean;
142
+ /** Pages in the file. */
143
+ page_count?: number;
144
+ /** Pages that have a picture a signer can read. */
145
+ drawn?: number;
146
+ /** `drawn === page_count`. A PDF template cannot be published until it is. */
147
+ ready?: boolean;
148
+ pages?: Array<{
149
+ n: number;
150
+ width: number;
151
+ height: number;
152
+ rotation?: number;
153
+ }>;
154
+ bytes?: number;
155
+ /** Hex. The fingerprint the template's body names and the certificate commits to. */
156
+ sha256?: string;
157
+ original_name?: string | null;
158
+ uploaded_at?: string;
159
+ }
160
+ /**
161
+ * What a reader will be told about the signer of a sealed PDF.
162
+ *
163
+ * Two fields, because they answer different questions and one field used to
164
+ * answer both wrongly. `selfIssued` is what the certificate says about itself.
165
+ * `trust` is which programme, if any, somebody has established it belongs to —
166
+ * and only `"aatl"` means a reader will show the signer as verified without
167
+ * being told to. Anything else, including `"ca_issued"`, means the PDF itself
168
+ * says the signer's identity is unconfirmed.
169
+ */
170
+ export interface SealSummary {
171
+ commonName: string;
172
+ selfIssued: boolean;
173
+ trust: "unverified" | "ca_issued" | "aatl";
174
+ timestamped: boolean;
175
+ }
176
+ export interface SignerLink {
177
+ signer_id: string;
178
+ email: string;
179
+ full_name?: string;
180
+ role?: string;
181
+ participant?: boolean;
182
+ /** The signing URL. Returned once, and never again — only its hash is kept. */
183
+ token: string;
184
+ }
185
+ export interface StartedWorkflow {
186
+ document_id: string;
187
+ title: string;
188
+ expires_at: string | null;
189
+ signers: SignerLink[];
190
+ }
191
+ export interface PacketSummary {
192
+ packet_id: string;
193
+ code: string;
194
+ state: "open" | "ready" | "blocked" | "expired" | "void";
195
+ required: number;
196
+ completed: number;
197
+ outstanding: number;
198
+ not_started: number;
199
+ }
200
+ export interface Participant {
201
+ ref?: string;
202
+ full_name: string;
203
+ email?: string;
204
+ phone?: string;
205
+ /** YYYY-MM-DD. Required for anyone who might be a minor: minority is judged
206
+ * on the reservation's start date, and a blank date is refused rather than
207
+ * read as an adult. */
208
+ date_of_birth?: string;
209
+ is_primary?: boolean;
210
+ /** The `ref` of the adult who signs for this minor. */
211
+ guardian_ref?: string;
212
+ }
213
+ export interface ClientOptions {
214
+ apiKey: string;
215
+ baseUrl?: string;
216
+ /** Total attempts for a retryable failure, the first included. */
217
+ maxAttempts?: number;
218
+ /**
219
+ * The longest the client will sit inside an `await` waiting out a
220
+ * `Retry-After` before giving the wait back to you instead. Default five
221
+ * seconds. A rate limit's window is usually a minute, and blocking a
222
+ * caller's request for a minute is the library making a scheduling
223
+ * decision that is not its to make — so past this, the refusal is thrown
224
+ * at once with `retryAfter` on it.
225
+ */
226
+ maxWaitMs?: number;
227
+ fetch?: typeof globalThis.fetch;
228
+ }
229
+ export declare class SignSealer {
230
+ #private;
231
+ /**
232
+ * Agreements left in this billing period, as of the last call that said
233
+ * (00271), or null on a plan that counts nothing down.
234
+ *
235
+ * A server with no screen to warn on still gets warned: the count rides on
236
+ * the answer to a send, so an integration can see the wall coming without
237
+ * polling for it.
238
+ */
239
+ agreementsRemaining: number | null;
240
+ constructor(opts: ClientOptions);
241
+ /** Prove the key works, and say whose account it is. */
242
+ /**
243
+ * The brand this account shows its signers.
244
+ *
245
+ * SignSealer's own until the business has the white-label add-on and has
246
+ * set a brand. An embedded platform reads this to match its own chrome to
247
+ * what the signer is about to see, so the two do not disagree at the
248
+ * moment somebody is deciding whether to trust the page.
249
+ */
250
+ branding(): Promise<Branding>;
251
+ account(): Promise<Account>;
252
+ templates(): Promise<Template[]>;
253
+ /**
254
+ * Whether a template is an uploaded PDF, and whether it is usable yet.
255
+ *
256
+ * `ready` is the one to check: a PDF template cannot be published until
257
+ * every page has a picture a signer can read. Uploading the file is a
258
+ * dashboard step — drawing those pictures needs a browser, which a server
259
+ * does not have — so this is read-only on purpose.
260
+ */
261
+ /**
262
+ * Create a template. Version 1, as a draft.
263
+ *
264
+ * A template is not usable until it is published, and publishing is what
265
+ * freezes the text people will have signed — so this is deliberately the
266
+ * *draft* door and there is no `publish` beside it. Publishing is a
267
+ * decision somebody makes looking at the words, in the dashboard.
268
+ *
269
+ * `fields` says what the document asks for besides a signature, and is
270
+ * set in the same call rather than in a second one: a template that
271
+ * exists for a moment asking for nothing is a template somebody can send
272
+ * in that moment.
273
+ */
274
+ createTemplate(input: TemplateInput, idempotencyKey?: string): Promise<{
275
+ template_id: string;
276
+ }>;
277
+ templatePdf(id: string): Promise<TemplatePdf>;
278
+ /**
279
+ * Record that you have consent to text a number.
280
+ *
281
+ * For a number you took somewhere SignSealer is not: your booking form, an
282
+ * order, the counter. Until this existed there was no way to tell us, so a
283
+ * business collecting numbers on its own form had every text held and was
284
+ * told nothing -- the document went out by email and the text quietly did
285
+ * not.
286
+ *
287
+ * `wording` is the field this method exists for. Send the exact words that
288
+ * were in front of the person, because it is kept verbatim and it is what a
289
+ * carrier asks for. It has to say that replying STOP opts out, that HELP
290
+ * gets help, that message and data rates may apply, and that message
291
+ * frequency varies; a disclosure missing any of those is refused with 422
292
+ * naming which, and nothing is recorded.
293
+ *
294
+ * One call covers the link, the reminder and the confirmation. Somebody who
295
+ * agreed to those agreed to all three, and an API that made you post three
296
+ * times would get posted to once.
297
+ *
298
+ * A number that has replied STOP cannot be re-consented this way. They have
299
+ * to opt in again themselves, and recording an attestation on their behalf
300
+ * is not that.
301
+ */
302
+ recordSmsConsent(input: {
303
+ phone: string;
304
+ obtainedVia: string;
305
+ wording: string;
306
+ }, idempotencyKey?: string): Promise<SmsConsentRecorded>;
307
+ /**
308
+ * Whether you may text a number, and since when.
309
+ *
310
+ * Ask before putting the tick box in front of somebody again. It answers
311
+ * about the one number you pass and deliberately will not list every mobile
312
+ * on the account.
313
+ */
314
+ smsConsent(phone: string): Promise<SmsConsent>;
315
+ documents(filter?: {
316
+ status?: string;
317
+ q?: string;
318
+ limit?: number;
319
+ }): Promise<{
320
+ documents: unknown[];
321
+ }>;
322
+ document(id: string): Promise<unknown>;
323
+ prepareDocument(input: {
324
+ template_code: string;
325
+ title?: string;
326
+ values?: Record<string, string>;
327
+ expires_at?: string | null;
328
+ sequential?: boolean;
329
+ }, idempotencyKey?: string): Promise<{
330
+ document_id: string;
331
+ }>;
332
+ send(documentId: string, signers: Array<{
333
+ email: string;
334
+ full_name: string;
335
+ role?: "signer" | "approver" | "witness" | "cc";
336
+ sign_order?: number;
337
+ }>, idempotencyKey?: string): Promise<{
338
+ links: SignerLink[];
339
+ }>;
340
+ void(documentId: string, reason: string, idempotencyKey?: string): Promise<{
341
+ voided: true;
342
+ }>;
343
+ /**
344
+ * The certificate, or null when there is not one yet.
345
+ *
346
+ * Null rather than a throw, because "not finished signing" is an ordinary
347
+ * state a caller polls through, not an exception.
348
+ */
349
+ certificate(documentId: string): Promise<unknown | null>;
350
+ /**
351
+ * The executed agreement and its certificate, sealed, as bytes.
352
+ *
353
+ * Null when the document has not been executed. A PDF headed "Certificate
354
+ * of Completion" for something nobody finished signing is precisely the
355
+ * artefact this product exists to make impossible, so there is no hopeful
356
+ * version of this to return.
357
+ */
358
+ pdf(documentId: string): Promise<{
359
+ filename: string;
360
+ bytes: Uint8Array;
361
+ seal: SealSummary | null;
362
+ } | null>;
363
+ /**
364
+ * The evidence bundle: the sealed PDF with the evidence package printed
365
+ * after the audit trail — every message, every webhook, the record's state
366
+ * — as one sealed file. Null before the document is executed, like `pdf`;
367
+ * `evidence` has the JSON before then.
368
+ */
369
+ bundle(documentId: string): Promise<{
370
+ filename: string;
371
+ bytes: Uint8Array;
372
+ seal: SealSummary | null;
373
+ } | null>;
374
+ workflows(): Promise<{
375
+ workflows: unknown;
376
+ }>;
377
+ /** The QR code for a workflow's public form: its address, an SVG, and a 1024px PNG as base64. 404 with no public address. */
378
+ workflowQr(workflowId: string): Promise<{
379
+ workflow_id: string;
380
+ name: string;
381
+ url: string;
382
+ svg: string;
383
+ png_base64: string;
384
+ }>;
385
+ startWorkflow(workflowId: string, participant: {
386
+ email: string;
387
+ full_name: string;
388
+ phone?: string;
389
+ fields?: Record<string, string>;
390
+ values?: Record<string, string>;
391
+ external_ref?: string;
392
+ }, idempotencyKey?: string): Promise<StartedWorkflow>;
393
+ /**
394
+ * Import a reservation and its guests, and get back what is now required.
395
+ *
396
+ * One call rather than three. A booking system that has a reservation always
397
+ * wants to know what it needs signed, and splitting that into import, then
398
+ * guests, then build would be two round trips that exist only because we
399
+ * split them.
400
+ */
401
+ upsertReservation(input: {
402
+ provider?: string;
403
+ external_id: string;
404
+ label?: string;
405
+ starts_on: string;
406
+ ends_on?: string | null;
407
+ kind?: "reservation" | "activity";
408
+ facts?: Record<string, unknown>;
409
+ participants?: Participant[];
410
+ }): Promise<{
411
+ subject_id: string;
412
+ packet: PacketSummary;
413
+ }>;
414
+ packet(packetId: string): Promise<unknown>;
415
+ startPacketItem(itemId: string, idempotencyKey?: string): Promise<StartedWorkflow>;
416
+ webhooks(): Promise<{
417
+ endpoints: unknown;
418
+ }>;
419
+ addWebhook(input: {
420
+ url: string;
421
+ events?: string[];
422
+ label?: string;
423
+ }, idempotencyKey?: string): Promise<{
424
+ id: string;
425
+ secret: string;
426
+ }>;
427
+ setWebhook(id: string, input: {
428
+ active?: boolean;
429
+ events?: string[];
430
+ label?: string;
431
+ }): Promise<{
432
+ updated: true;
433
+ }>;
434
+ removeWebhook(id: string, reason: string): Promise<{
435
+ deleted: true;
436
+ }>;
437
+ /**
438
+ * A new signing secret for an endpoint, returned **once**.
439
+ *
440
+ * For 24 hours every delivery is signed with both — the signature header
441
+ * carries two comma-separated `v1=` values, the new secret's first — so a
442
+ * receiver can switch over without dropping a delivery. `verifyWebhook`
443
+ * accepts either while both are live, so the safe order is: rotate, store
444
+ * the new secret, pass both to the verifier, then drop the old one.
445
+ *
446
+ * After the window the old secret is forgotten, and a delivery signed
447
+ * with it will not verify.
448
+ */
449
+ rotateWebhookSecret(id: string): Promise<{
450
+ secret: string;
451
+ previous_valid_for_seconds: number;
452
+ }>;
453
+ /**
454
+ * An endpoint's last fifty deliveries, newest first.
455
+ *
456
+ * What each one was, whether it landed, how many attempts it took, when
457
+ * the next is due, and the last error in the words the receiver gave us.
458
+ * A replay names the delivery it repeats in `replay_of`.
459
+ */
460
+ webhookDeliveries(id: string): Promise<{
461
+ deliveries: unknown[];
462
+ }>;
463
+ /**
464
+ * Send one delivery again, as a new delivery marked as its replay.
465
+ *
466
+ * For the afternoon somebody's receiver was down, or deployed a bug that
467
+ * dropped what it was handed. A delivery still in the queue is refused,
468
+ * and so is a second replay while the first is queued — a replay is not a
469
+ * way to send the same event five times.
470
+ */
471
+ replayWebhookDelivery(deliveryId: string, idempotencyKey?: string): Promise<{
472
+ delivery_id: string;
473
+ }>;
474
+ /**
475
+ * Trade a pairing code for a device credential.
476
+ *
477
+ * **Takes no API key**, and it is the only method here that does not: the
478
+ * pairing code *is* the credential, and requiring a key to exchange a code
479
+ * for a key is the circle the whole feature exists to break. So call it on
480
+ * a `SignSealer` built without one, or on the device itself.
481
+ *
482
+ * The code is shown once on the fleet screen, lives fifteen minutes and is
483
+ * spent on first use. What comes back is a key scoped to this device alone.
484
+ * Every refusal reads identically — wrong, expired, spent and belonging to
485
+ * a stopped device are deliberately indistinguishable, because telling them
486
+ * apart tells a guesser whether they are warm.
487
+ */
488
+ pairDevice(input: {
489
+ code: string;
490
+ platform?: "ios" | "android" | "other";
491
+ app_version?: string;
492
+ os_version?: string;
493
+ }): Promise<{
494
+ api_key: string;
495
+ device: Record<string, unknown>;
496
+ }>;
497
+ /**
498
+ * Say the device is still here, and read back what it should be running.
499
+ *
500
+ * The device does not say *which* device it is — the credential it calls
501
+ * with does. So a tablet cannot report on another's behalf, and a
502
+ * heartbeat from a revoked credential resolves to no device at all. The
503
+ * answer carries the device's name and assigned workflow, so a change made
504
+ * on the fleet screen reaches the tablet without re-pairing.
505
+ */
506
+ deviceHeartbeat(input?: {
507
+ app_version?: string;
508
+ os_version?: string;
509
+ }): Promise<Record<string, unknown>>;
510
+ }
511
+ export interface SigningLink {
512
+ ok: boolean;
513
+ /** Why it will not take a signature, in a sentence meant for a person. */
514
+ reason: string | null;
515
+ document_id: string | null;
516
+ title: string | null;
517
+ body: string | null;
518
+ body_sha256_hex: string | null;
519
+ tenant_name: string | null;
520
+ full_name: string | null;
521
+ email: string | null;
522
+ signer_status: string | null;
523
+ consented_at: string | null;
524
+ is_my_turn: boolean | null;
525
+ waiting_on: string | null;
526
+ /**
527
+ * The disclosure and the statement above the signature, as the engine
528
+ * records them — and their versions, which are what the certificate
529
+ * commits to. An embedded page that writes its own consent wording
530
+ * instead of showing these is signing people up to something the
531
+ * evidence does not say.
532
+ */
533
+ consent_text?: string | null;
534
+ consent_version?: string | null;
535
+ intent_text?: string | null;
536
+ intent_version?: string | null;
537
+ /**
538
+ * When the business asks this signer for a one-time code first.
539
+ *
540
+ * `"email"` or `"sms"` while one is wanted, and **null once it is done**
541
+ * — `verified_at` is the other half of the pair. A flow that ignores
542
+ * this will have `sign` refused, so: if `verification_required`, call
543
+ * `requestCode`, take the digits, call `confirmCode`, then carry on.
544
+ */
545
+ verification_required?: "email" | "sms" | null;
546
+ /** Masked. `d•••@example.com`, so the page can say where without learning it. */
547
+ verification_to?: string | null;
548
+ verified_at?: string | null;
549
+ /** When the last code went, so a page can rate-limit its own button. */
550
+ code_sent_at?: string | null;
551
+ /** Everyone on the document — for "waiting on Dana", not for contacting them. */
552
+ signers?: unknown;
553
+ fields: Array<{
554
+ key: string;
555
+ label: string;
556
+ kind: string;
557
+ required: boolean;
558
+ about: string | null;
559
+ supplied: boolean;
560
+ /**
561
+ * Where this question sits on the document, when the template is an
562
+ * uploaded PDF. A fraction of the page a reader *sees*, origin top left,
563
+ * so it means the same thing at any image resolution and any screen
564
+ * width. Absent for a question asked underneath the document.
565
+ */
566
+ place?: Place | null;
567
+ }>;
568
+ /**
569
+ * The pages of an uploaded PDF. Empty for a template that is words.
570
+ *
571
+ * Draw these rather than `body`: a PDF template's body is a sentence
572
+ * naming the file and its fingerprint, because the certificate
573
+ * fingerprints the body and a PDF has no text to fingerprint. Fetch each
574
+ * page with `pageUrl`.
575
+ */
576
+ pages?: Page[];
577
+ }
578
+ /** A rectangle on a page, in fractions of the page a reader sees. */
579
+ export interface Place {
580
+ page: number;
581
+ x: number;
582
+ y: number;
583
+ w: number;
584
+ h: number;
585
+ }
586
+ /** One page of an uploaded PDF, at the size the picture was made. */
587
+ export interface Page {
588
+ n: number;
589
+ width: number;
590
+ height: number;
591
+ }
592
+ /** What a device says about when something happened, when it happened offline. */
593
+ export interface Captured {
594
+ offline?: boolean;
595
+ /** ISO 8601. Recorded as a claim beside our own received time. */
596
+ at?: string;
597
+ device?: string;
598
+ }
599
+ /**
600
+ * The signer's side, which takes **no API key at all**.
601
+ *
602
+ * A separate class rather than methods on `SignSealer`, and the separation is
603
+ * the point rather than tidiness. A signing token is the whole credential on
604
+ * these routes; a client that could send a key alongside one would be a client
605
+ * that widens somebody's authority by accident, and the API deliberately
606
+ * ignores a key here for the same reason.
607
+ *
608
+ * Use this to build your own signing page. If you want ours, send the signer
609
+ * to `https://api.signsealer.com/s/<token>` and skip all of it.
610
+ */
611
+ export declare class SignSealerSigning {
612
+ #private;
613
+ constructor(opts?: {
614
+ baseUrl?: string;
615
+ fetch?: typeof globalThis.fetch;
616
+ });
617
+ /**
618
+ * Everything the page needs from one token.
619
+ *
620
+ * Answers for a token that matches nothing too, with `ok: false` and a
621
+ * reason — a bad link and an expired one are deliberately indistinguishable.
622
+ */
623
+ link(token: string): Promise<SigningLink>;
624
+ /**
625
+ * Where one page of an uploaded PDF lives, for an `<img>` or an `<Image>`.
626
+ *
627
+ * Not under `/v1`, and it takes **no API key**: the signing token is the
628
+ * whole credential, the same one `link` was called with. That is what lets
629
+ * the browser fetch it directly rather than proxying it through your
630
+ * server with a key attached.
631
+ */
632
+ pageUrl(token: string, n: number): string;
633
+ /**
634
+ * Send this signer a one-time code, when the business asks for one.
635
+ *
636
+ * Only when the business has switched it on (Settings → Signing) and the
637
+ * link was delivered to this signer. The code goes to the address or
638
+ * number the link went to — never one your page collects — and the answer
639
+ * says where, masked, so you can render "we sent a code to d•••@example.com"
640
+ * without learning the address.
641
+ *
642
+ * **A signing flow that never calls this will simply fail for those
643
+ * businesses**: `sign` is refused while a required code is unconfirmed,
644
+ * and there is nothing in `link()` you could have done about it. Check
645
+ * `SigningLink.verification` and send a code when it says one is wanted.
646
+ *
647
+ * One a minute, five an hour. Not an identity check: it proves control of
648
+ * that inbox or phone at the moment of signing, and the certificate says
649
+ * `email_otp` or `sms_otp` rather than anything about who the person is.
650
+ */
651
+ requestCode(token: string): Promise<CodeSent>;
652
+ /**
653
+ * Confirm the code the signer typed.
654
+ *
655
+ * A wrong code answers `{ ok: false }` with the tries left rather than
656
+ * throwing — it is an answer, not an error, and a client that treated it
657
+ * as one would show a stack trace to somebody who fat-fingered a digit.
658
+ * After five wrong tries the code is dead and a new one has to be sent.
659
+ *
660
+ * A confirmed code is a verified event on the evidence trail.
661
+ */
662
+ confirmCode(token: string, code: string): Promise<CodeChecked>;
663
+ /** Must happen before signing. The engine refuses a signature without it. */
664
+ consent(token: string, captured?: Captured): Promise<{
665
+ consented: true;
666
+ }>;
667
+ /** Initials, a checkbox, a date. `about` names the child a field is for. */
668
+ supply(token: string, key: string, value: string, about?: string): Promise<{
669
+ supplied: true;
670
+ }>;
671
+ sign(token: string, method: "typed" | "drawn" | "clicked" | "uploaded", value: string, captured?: Captured): Promise<{
672
+ event_id: string;
673
+ }>;
674
+ decline(token: string, reason: string): Promise<{
675
+ declined: true;
676
+ }>;
677
+ /**
678
+ * Check a certificate by its printed code. No credential of any kind.
679
+ *
680
+ * Supply `documentSha256` to have a file you hold compared with the one
681
+ * recorded — the hash is compared, never the file.
682
+ */
683
+ verify(code: string, documentSha256?: string): Promise<Record<string, unknown>>;
684
+ }
685
+ export declare const WEBHOOK_EVENT_HEADER = "signsealer-event-id";
686
+ export declare const WEBHOOK_TIMESTAMP_HEADER = "signsealer-timestamp";
687
+ export declare const WEBHOOK_SIGNATURE_HEADER = "signsealer-signature";
688
+ /** Five minutes each way, matching the sender. */
689
+ export declare const WEBHOOK_TOLERANCE_SECONDS = 300;
690
+ export interface WebhookVerification {
691
+ ok: boolean;
692
+ /** Why not, in a sentence you can log. Absent when it verified. */
693
+ reason?: string;
694
+ }
695
+ export interface VerifyWebhookOptions {
696
+ /** The endpoint's signing secret, from the portal or `addWebhook`. */
697
+ secret: string;
698
+ /**
699
+ * The raw body **exactly as received**, before any JSON parsing.
700
+ *
701
+ * Parsing and re-serialising verifies your own formatter rather than ours:
702
+ * two JSON serialisers disagree about key order and unicode escapes
703
+ * eventually, and the day they do, every delivery fails at once. In Express
704
+ * that means `express.raw({ type: "application/json" })` on this route.
705
+ */
706
+ body: string;
707
+ /** The `signsealer-signature` header. */
708
+ signature?: string | null;
709
+ /** The `signsealer-timestamp` header. */
710
+ timestamp?: string | null;
711
+ /** Defaults to 300. Widen only if your queue is genuinely slower than that. */
712
+ toleranceSeconds?: number;
713
+ /** For tests. */
714
+ now?: number;
715
+ }
716
+ /**
717
+ * Is this delivery really from SignSealer, and recent?
718
+ *
719
+ * ```ts
720
+ * const check = await verifyWebhook({
721
+ * secret: process.env.SIGNSEALER_WEBHOOK_SECRET!,
722
+ * body: rawBody, // the bytes, not the object
723
+ * signature: req.headers["signsealer-signature"],
724
+ * timestamp: req.headers["signsealer-timestamp"],
725
+ * });
726
+ * if (!check.ok) return res.status(400).send(check.reason);
727
+ * ```
728
+ *
729
+ * Three things it does that a hand-written check usually misses.
730
+ *
731
+ * **The timestamp is inside the MAC**, so a captured delivery cannot be
732
+ * replayed tomorrow with a fresh header — and the window is enforced in both
733
+ * directions, because accepting one from the future is how you buy yourself an
734
+ * arbitrarily long replay window.
735
+ *
736
+ * **A rotation carries two signatures.** During a secret rotation's grace
737
+ * window the header is `v1=<new>,v1=<old>`, so a receiver holding either
738
+ * secret still verifies. A check written against a single signature starts
739
+ * rejecting real deliveries the first time the secret is rotated.
740
+ *
741
+ * **Every part is compared**, not the first that matches, and in constant
742
+ * time.
743
+ *
744
+ * Use `signsealer-event-id` for idempotency: a delivery retried six times
745
+ * carries the same id six times, and it is one event.
746
+ */
747
+ export declare function verifyWebhook(opts: VerifyWebhookOptions): Promise<WebhookVerification>;
748
+ /** Headers as any runtime hands them over. */
749
+ export type WebhookHeaders = Headers | Record<string, string | string[] | undefined> | {
750
+ get(name: string): string | null;
751
+ };
752
+ /**
753
+ * The same check, reading the headers for you, and handing back the event id.
754
+ *
755
+ * ```ts
756
+ * const { ok, reason, eventId } = await verifyWebhookRequest({
757
+ * secret, body: rawBody, headers: req.headers,
758
+ * });
759
+ * if (!ok) return res.status(400).send(reason);
760
+ * if (await alreadyHandled(eventId)) return res.status(200).end();
761
+ * ```
762
+ *
763
+ * ## What `eventId` is, and the one thing it does not do
764
+ *
765
+ * It is stable across retries — a delivery attempted six times carries the
766
+ * same id all six — which is what makes it the key to deduplicate on. Use it.
767
+ *
768
+ * What it is **not** is authenticated. The signature covers `timestamp.body`;
769
+ * the id travels beside it in a header, outside the HMAC. So somebody who
770
+ * obtains one valid delivery can, inside the tolerance window, send those same
771
+ * signed bytes again with a different id on them, and a receiver keyed on the
772
+ * id will treat the replay as a new event.
773
+ *
774
+ * There is no way to close that from inside this package today, and it is
775
+ * worth saying rather than implying otherwise. A key derived from the signed
776
+ * material — the hash of `timestamp.body` — is authenticated but is *not*
777
+ * stable across retries, because the sender signs a fresh timestamp on every
778
+ * attempt; this SDK briefly returned one, which deduplicated replays and broke
779
+ * ordinary retries, which is the worse failure of the two. The fix is to bring
780
+ * the id inside the signature under a `v2=` scheme, and that is a change to
781
+ * the wire rather than to this file.
782
+ *
783
+ * Until then: deduplicate on `eventId`, and if a replay inside a five-minute
784
+ * window would be harmful to your system, check the event's own contents
785
+ * against your records before acting on it.
786
+ */
787
+ export declare function verifyWebhookRequest(opts: {
788
+ secret: string;
789
+ body: string;
790
+ headers: WebhookHeaders;
791
+ toleranceSeconds?: number;
792
+ now?: number;
793
+ }): Promise<WebhookVerification & {
794
+ eventId: string | null;
795
+ }>;
796
+ //# sourceMappingURL=index.d.ts.map