@signsealer/sdk 1.19.0 → 1.25.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.
@@ -133,13 +133,39 @@ export interface Account {
133
133
  wording: string;
134
134
  /** The business's own verified texting number (1.13.0), once it has one. */
135
135
  number?: string | null;
136
+ /**
137
+ * Where a text goes (1.24.0): `US` and `CA`, and `GB` while texting UK
138
+ * mobiles is on. A mobile anywhere else is not texted: ask for an email
139
+ * address beside it. A signer with only such a mobile is refused.
140
+ */
141
+ countries?: Array<"US" | "CA" | "GB">;
136
142
  /**
137
143
  * Where its application for one has got to (1.13.0); null when it has not
138
144
  * applied. Each step is also sent as `texting.number_updated`.
139
145
  */
140
146
  application?: TextingApplication | null;
147
+ /**
148
+ * Who texts the signers of documents this key sends (1.21.0):
149
+ * `signsealer` for the business's own keys; for a partner's access
150
+ * token, the partner's answer -- `partner` (your platform texts them and
151
+ * SignSealer sends none), `none`, or `signsealer`.
152
+ */
153
+ sender?: TextingSender;
141
154
  };
142
155
  }
156
+ /** Who texts a document's signers (1.21.0). */
157
+ export type TextingSender = "signsealer" | "partner" | "none";
158
+ /** A business's choice of who texts for one partner app (1.21.0), as `setTextingSender` answers it. */
159
+ export interface TextingSenderChoice {
160
+ /** The app, `ss_client_…`. */
161
+ client_id: string;
162
+ name: string;
163
+ mode: "business_choice";
164
+ /** What the business chose. */
165
+ choice: TextingSender;
166
+ /** What applies now. */
167
+ sender: TextingSender;
168
+ }
143
169
  /** Where a business's texting-number application has got to (1.13.0), as the account and `texting.number_updated` say. */
144
170
  export interface TextingApplication {
145
171
  /** `applied`, `submitted`, `in_review`, `needs_changes`, `verified`, `paused`, `failed`, and the steps of bringing a number. */
@@ -205,8 +231,12 @@ export interface SmsConsent {
205
231
  phone: string;
206
232
  /** What the engine will actually do: consent live, and the number not suppressed. */
207
233
  may_text: boolean;
208
- /** Why not, when `may_text` is false: they opted out, we cannot reach the number, or nobody ever asked. */
209
- why_not: "revoked" | "suppressed" | "no_consent" | null;
234
+ /**
235
+ * Why not, when `may_text` is false: they opted out, we cannot reach the
236
+ * number, or nobody ever asked; or (1.24.0) `country`, a number outside the
237
+ * US and Canada, which is not texted whatever the consent.
238
+ */
239
+ why_not: "country" | "revoked" | "suppressed" | "no_consent" | null;
210
240
  /** Where the business said the number came from, in their words. */
211
241
  obtained_via: string | null;
212
242
  obtained_at: string | null;
@@ -327,7 +357,7 @@ export interface Ask {
327
357
  */
328
358
  sensitive?: boolean;
329
359
  /** `business` (1.16.0): answered by whoever signs for the business, and nobody else (00611). */
330
- supplied_by?: "adult" | "per_child" | "staff" | "business";
360
+ supplied_by?: "adult" | "per_child" | "everyone" | "staff" | "business";
331
361
  options?: string[];
332
362
  hint?: string;
333
363
  /**
@@ -355,6 +385,14 @@ export interface Ask {
355
385
  block_step?: boolean | null;
356
386
  /** Where it is answered on an uploaded PDF's page (00243), in fractions of the page. */
357
387
  place?: Place | null;
388
+ /** The one signer this question is for, by their `sign_order` (00685); absent, every signer's. */
389
+ recipient?: number | null;
390
+ /**
391
+ * The answer fills the blank of the same name in a written template's text
392
+ * (00699): `{{plate}}` for `plate`. A send may leave it out of `values`;
393
+ * the first signer answers it and their signature writes it in.
394
+ */
395
+ blank?: boolean | null;
358
396
  }
359
397
  /**
360
398
  * A rule about an answer, exactly one of these (00373, 00375): `equals` for a
@@ -847,6 +885,13 @@ export interface ClientOptions {
847
885
  * header and every other route refuses it, which is the right answer.
848
886
  */
849
887
  apiKey?: string;
888
+ /**
889
+ * 00751: a partner acting for one of its businesses. With a partner key
890
+ * (`ss_partner_…`) as `apiKey`, every call is made as the business this
891
+ * names -- its id, or your own `external_id` for it -- in the
892
+ * `SignSealer-Business` header. `SignSealerPartner.business(id)` builds one.
893
+ */
894
+ business?: string;
850
895
  baseUrl?: string;
851
896
  /** Total attempts for a retryable failure, the first included. */
852
897
  maxAttempts?: number;
@@ -860,7 +905,17 @@ export interface ClientOptions {
860
905
  */
861
906
  maxWaitMs?: number;
862
907
  fetch?: typeof globalThis.fetch;
908
+ /**
909
+ * What the client says it is, in `User-Agent`. By default
910
+ * `signsealer-sdk/<version> (node)`, so a request can be traced to the
911
+ * library and version that made it; give your own to name your integration
912
+ * too (`"acme-bookings/2.1 signsealer-sdk"`), or `""` to send none. Sent
913
+ * only outside a browser: a browser sets its own.
914
+ */
915
+ userAgent?: string;
863
916
  }
917
+ /** This package's version, as `package.json` has it; `tests/sdk.ts` holds the two together. */
918
+ export declare const SDK_VERSION = "1.25.0";
864
919
  export declare class SignSealer {
865
920
  #private;
866
921
  /**
@@ -1035,6 +1090,19 @@ export declare class SignSealer {
1035
1090
  * nobody was handed. If the answer is lost, ask again when you need one.
1036
1091
  */
1037
1092
  textingNumberInvitation(prefill?: TextingNumberPrefill): Promise<TextingNumberInvitation>;
1093
+ /**
1094
+ * Who texts the signers of documents sent through a partner's app, for a
1095
+ * partner whose dashboard leaves it to each business (1.21.0).
1096
+ *
1097
+ * As the partner, with the business's access token, leave `clientId` out:
1098
+ * the choice is yours for that business. With the business's own key, name
1099
+ * the app by its `ss_client_…` id (the key needs `signing:webhooks`). With
1100
+ * `partner` or `none`, SignSealer sends no texts for those documents -- no
1101
+ * link, no reminder, no confirmation -- while email and webhooks go on as
1102
+ * before; a one-time code a signer asks for is still sent. A PUT, so a
1103
+ * retry after a lost answer sets the same thing again.
1104
+ */
1105
+ setTextingSender(sender: TextingSender, clientId?: string): Promise<TextingSenderChoice>;
1038
1106
  /**
1039
1107
  * Documents, filtered and paged.
1040
1108
  *
@@ -1103,6 +1171,19 @@ export declare class SignSealer {
1103
1171
  reminded: true;
1104
1172
  by: "email" | "sms";
1105
1173
  }>;
1174
+ /**
1175
+ * The sandbox plays a signer (00719): for a test key only, `signed` (their
1176
+ * consent and a typed signature, through every check the signing page
1177
+ * makes), `declined` (with `reason`) or `expired`, so each outcome and its
1178
+ * webhooks can be driven from your tests. Refused (403) for a live key.
1179
+ * Sent once: a second call for a signer who has signed is refused anyway.
1180
+ */
1181
+ simulateSigning(documentId: string, signerId: string, outcome: "signed" | "declined" | "expired", reason?: string): Promise<{
1182
+ document_id: string;
1183
+ signer_id: string;
1184
+ outcome: "signed" | "declined" | "expired";
1185
+ simulated: true;
1186
+ }>;
1106
1187
  /**
1107
1188
  * A fresh signing link to put in an `<iframe>` (1.6.0), with the sites it
1108
1189
  * may be framed on. Call it when the page is about to be shown rather than
@@ -1300,6 +1381,10 @@ export declare class SignSealer {
1300
1381
  packet_id: string;
1301
1382
  voided: number;
1302
1383
  kept: number;
1384
+ signed: Array<{
1385
+ document_id: string;
1386
+ title: string;
1387
+ }>;
1303
1388
  }>;
1304
1389
  /**
1305
1390
  * The booking systems this business can connect, and its connections (00424).
@@ -1997,7 +2082,7 @@ export interface Device {
1997
2082
  }
1998
2083
  export interface Captured {
1999
2084
  offline?: boolean;
2000
- /** ISO 8601. Recorded as a claim beside our own received time. */
2085
+ /** ISO 8601, ending in `Z` or a UTC offset (`2026-11-09T14:03:00-06:00`); every route that takes it takes both. Recorded as a claim beside our own received time. */
2001
2086
  at?: string;
2002
2087
  device?: string;
2003
2088
  }
@@ -2144,7 +2229,7 @@ export declare class SignSealerSigning {
2144
2229
  * the business did not ask; refused as busy, to be sent again after
2145
2230
  * `retryAfter` seconds, as `supplyPhoto` is.
2146
2231
  */
2147
- captureIdEvidence(token: string, kind: "id" | "selfie", image: {
2232
+ captureIdEvidence(token: string, kind: "id" | "id_back" | "selfie", image: {
2148
2233
  contentType: string;
2149
2234
  bytes: Uint8Array | string;
2150
2235
  }, captured?: Captured): Promise<{
@@ -2240,6 +2325,9 @@ export interface PartnerProfile {
2240
2325
  month_to_date: PartnerMonthToDate;
2241
2326
  /** The link to hand a business: signing up through it makes the business yours. */
2242
2327
  signup_url: string;
2328
+ /** 00756: the current version of SignSealer's terms, which a business you make accepts (a date), and where to show it. */
2329
+ terms_version: string;
2330
+ terms_url: string;
2243
2331
  }
2244
2332
  /** A business you brought (1.8.0). */
2245
2333
  export interface PartnerBusiness {
@@ -2280,13 +2368,189 @@ export interface PartnerStatement {
2280
2368
  revenue_cents: number;
2281
2369
  }>;
2282
2370
  }
2371
+ /** 00751: a business a partner on a Platform agreement made. */
2372
+ export interface ManagedBusiness {
2373
+ id: string;
2374
+ /** Your own id for it, or null when you gave none. */
2375
+ external_id: string | null;
2376
+ name: string;
2377
+ slug: string;
2378
+ status: string;
2379
+ created_at: string;
2380
+ /** 00761: made with a test key: nothing it does reaches anybody or is billed. */
2381
+ sandbox: boolean;
2382
+ timezone: string | null;
2383
+ /** Its address and contact details, as `account()` describes them, with what is `missing`. */
2384
+ profile: Record<string, unknown>;
2385
+ /** Its membership, paid from your balance; null if it has not started. */
2386
+ membership: "monthly" | "yearly" | null;
2387
+ /** The monthly spending limit you set for it, in cents; null for none. */
2388
+ spend_cap_cents: number | null;
2389
+ /** What your balance has drawn for it this month, in cents. */
2390
+ month_to_date_cents: number;
2391
+ /** 00756: the version of our terms it accepted, as you recorded it, and a newer one it must accept by `due.by`, if any. */
2392
+ terms: {
2393
+ version: string | null;
2394
+ accepted_at: string | null;
2395
+ due: {
2396
+ version: string;
2397
+ by: string | null;
2398
+ on_hold: boolean;
2399
+ } | null;
2400
+ };
2401
+ /** 00759: the credit you gave it, in your prices, and when what is left expires (null: never). */
2402
+ gift_credit: {
2403
+ left_cents: number;
2404
+ expires_at: string | null;
2405
+ };
2406
+ /** 00759: the prices you set for it alone, over your default; {} for none. */
2407
+ prices: PartnerPriceList;
2408
+ can_send: boolean;
2409
+ /** Why it cannot send: its address, suspended, or your balance's grace period over. */
2410
+ why_not: string | null;
2411
+ }
2412
+ /**
2413
+ * 00759: what you charge your businesses, in cents for one of our units, and
2414
+ * `markup_bp` (hundredths of a percent) on anything else. Never charged by us.
2415
+ */
2416
+ export interface PartnerPriceList {
2417
+ membership_month?: number;
2418
+ membership_year?: number;
2419
+ signing?: number;
2420
+ text?: number;
2421
+ passcode?: number;
2422
+ id_evidence?: number;
2423
+ ai?: number;
2424
+ id_check?: number;
2425
+ markup_bp?: number;
2426
+ }
2427
+ /** 00759: your price list, and what each unit is. */
2428
+ export interface PartnerPrices {
2429
+ prices: PartnerPriceList;
2430
+ units: Record<string, string>;
2431
+ }
2432
+ /** 00760: one of your webhook endpoints, copied onto every business you made (of its mode). */
2433
+ export interface PartnerWebhook {
2434
+ id: string;
2435
+ url: string;
2436
+ label: string | null;
2437
+ events: string[];
2438
+ active: boolean;
2439
+ /** `test` for one added with a test key: it hears your sandbox businesses only. */
2440
+ mode: "live" | "test";
2441
+ created_at: string;
2442
+ /** How many businesses it is copied onto, and how many of those copies paused themselves after failing. */
2443
+ businesses: number;
2444
+ paused: number;
2445
+ last_delivered_at: string | null;
2446
+ }
2447
+ /** 00760: one delivery to one of your endpoints, and the business it was for. */
2448
+ export interface PartnerWebhookDelivery {
2449
+ id: string;
2450
+ business_id: string;
2451
+ external_id: string | null;
2452
+ event: string;
2453
+ status: string;
2454
+ attempts: number;
2455
+ response_status: number | null;
2456
+ error: string | null;
2457
+ created_at: string;
2458
+ delivered_at: string | null;
2459
+ replay_of: string | null;
2460
+ }
2461
+ /** 00763: a start link to a business's embedded screens: load `url` in an iframe on your page, within `expires_in` seconds. */
2462
+ export interface PartnerEmbedSession {
2463
+ session_id: string;
2464
+ url: string;
2465
+ expires_at: string;
2466
+ expires_in: number;
2467
+ components: string[];
2468
+ business_id: string;
2469
+ }
2470
+ /** 00759: a business's gift credit after a change. */
2471
+ export interface PartnerGiftCredit {
2472
+ left_cents: number;
2473
+ expires_at: string | null;
2474
+ /** False when the idempotency key was used before: nothing changed. */
2475
+ applied: boolean;
2476
+ }
2477
+ /** 00759: a month of your businesses' use, in our prices and yours. */
2478
+ export interface PartnerUsage {
2479
+ month: string;
2480
+ businesses: Array<{
2481
+ id: string;
2482
+ external_id: string | null;
2483
+ name: string;
2484
+ items: Array<{
2485
+ item: string;
2486
+ draws: number;
2487
+ our_cents: number;
2488
+ partner_cents: number;
2489
+ }>;
2490
+ our_cents: number;
2491
+ partner_cents: number;
2492
+ gift_used_cents: number;
2493
+ /** Your prices, less the gift credit it spent: what is left for you to bill it. */
2494
+ to_bill_cents: number;
2495
+ }>;
2496
+ our_cents: number;
2497
+ partner_cents: number;
2498
+ gift_used_cents: number;
2499
+ to_bill_cents: number;
2500
+ }
2501
+ /** 00752: the prepaid balance your businesses draw on. */
2502
+ export interface PartnerBalance {
2503
+ balance_cents: number;
2504
+ /** What your businesses may spend now: the balance and the grace period's room, or, frozen, nothing more. */
2505
+ available_cents: number;
2506
+ grace_limit_cents: number;
2507
+ in_grace: boolean;
2508
+ grace_started_at: string | null;
2509
+ grace_ends_at: string | null;
2510
+ /** The grace period is over: your businesses cannot send until you add credit. */
2511
+ frozen: boolean;
2512
+ businesses: Array<{
2513
+ id: string;
2514
+ external_id: string | null;
2515
+ name: string;
2516
+ month_to_date_cents: number;
2517
+ }>;
2518
+ entries: Array<{
2519
+ at: string;
2520
+ cents: number;
2521
+ kind: "purchase" | "usage" | "grant" | "refund" | "adjustment";
2522
+ business_id: string | null;
2523
+ note: string | null;
2524
+ }>;
2525
+ }
2526
+ /** 00751: what a business is made with. */
2527
+ export interface NewManagedBusiness {
2528
+ name: string;
2529
+ /** Your own id for it. Asking again with one already made returns that business, unchanged. */
2530
+ external_id?: string;
2531
+ /** An IANA name, like America/Chicago. */
2532
+ timezone?: string;
2533
+ /** `address_line1`, `city`, `region`, `postal_code`, `country`, `office_email`, `office_phone`, `website`, `legal_name`. */
2534
+ profile?: Record<string, string | null>;
2535
+ /** The business's acceptance of SignSealer's terms, as you took it. Required. */
2536
+ terms: {
2537
+ version: string;
2538
+ accepted_at: string;
2539
+ ip?: string;
2540
+ user_agent?: string;
2541
+ };
2542
+ /** Its membership, paid from your balance: by the month (the default; the first month by the day) or the year. */
2543
+ membership?: "monthly" | "yearly";
2544
+ }
2283
2545
  export interface PartnerOptions {
2284
- /** Your OAuth client's id, `ss_client_…`. */
2285
- clientId: string;
2546
+ /** Your OAuth client's id, `ss_client_…`. With `clientSecret`; or give `partnerKey` instead. */
2547
+ clientId?: string;
2286
2548
  /** Its secret, `ss_secret_…`: the one shown once when SignSealer registered you. */
2287
- clientSecret: string;
2549
+ clientSecret?: string;
2550
+ /** 00751: a partner key from your dashboard, `ss_partner_…`, instead of the client id and secret. Needed to act for a business. */
2551
+ partnerKey?: string;
2288
2552
  baseUrl?: string;
2289
- /** Total attempts for a retryable failure, the first included. Every call here only reads. */
2553
+ /** Total attempts for a retryable failure, the first included. A write is retried only when it is safe to. */
2290
2554
  maxAttempts?: number;
2291
2555
  fetch?: typeof globalThis.fetch;
2292
2556
  }
@@ -2320,6 +2584,296 @@ export declare class SignSealerPartner {
2320
2584
  }>;
2321
2585
  /** Every closed month, newest first. */
2322
2586
  statements(): Promise<PartnerStatement[]>;
2587
+ /**
2588
+ * 00751: make a business of your own (a Platform agreement). With an
2589
+ * `external_id` it is safe to retry: one already made comes back, with
2590
+ * `existing: true`. Without one it is sent once.
2591
+ */
2592
+ createBusiness(input: NewManagedBusiness): Promise<ManagedBusiness & {
2593
+ existing: boolean;
2594
+ }>;
2595
+ /** 00751: the businesses you made, newest first, with how many your agreement allows. `limit` is 1 to 100. */
2596
+ managedBusinesses(opts?: {
2597
+ limit?: number;
2598
+ offset?: number;
2599
+ }): Promise<{
2600
+ data: ManagedBusiness[];
2601
+ has_more: boolean;
2602
+ licensed: number | null;
2603
+ carried: number;
2604
+ }>;
2605
+ /** 00752: the prepaid balance your businesses draw on, this month by business, and the latest entries. */
2606
+ balance(): Promise<PartnerBalance>;
2607
+ /** 00751: one business you made, by its id or your own `external_id`. */
2608
+ managedBusiness(id: string): Promise<ManagedBusiness>;
2609
+ /**
2610
+ * 00751: change its `name`, `timezone` or `profile`; only what you send changes. Safe to retry.
2611
+ * 00752: `status` suspends or resumes it, `membership` is month or year from its next renewal,
2612
+ * `spend_cap_cents` its monthly spending limit (null for none).
2613
+ */
2614
+ updateBusiness(id: string, changes: {
2615
+ name?: string;
2616
+ timezone?: string;
2617
+ profile?: Record<string, string | null>;
2618
+ status?: "active" | "suspended";
2619
+ membership?: "monthly" | "yearly";
2620
+ spend_cap_cents?: number | null;
2621
+ /** 00756: its acceptance of a newer version of our terms, as you took it. */
2622
+ terms?: {
2623
+ version: string;
2624
+ accepted_at: string;
2625
+ ip?: string;
2626
+ user_agent?: string;
2627
+ };
2628
+ /** 00759: your prices for it alone, over your default; null or {} takes them away. */
2629
+ prices?: PartnerPriceList | null;
2630
+ }): Promise<ManagedBusiness>;
2631
+ /** 00759: your default prices to your businesses, and what each unit is. */
2632
+ prices(): Promise<PartnerPrices>;
2633
+ /** 00759: replace your default prices; `{}` takes them all away. Safe to retry. */
2634
+ setPrices(prices: PartnerPriceList): Promise<PartnerPrices>;
2635
+ /**
2636
+ * 00759: give one of your businesses credit (`cents` above zero), or take
2637
+ * back what is left (below zero), in your prices. With an `idempotencyKey`
2638
+ * it is safe to retry; without one it is sent once.
2639
+ */
2640
+ giveCredit(id: string, gift: {
2641
+ cents: number;
2642
+ expires_at?: string | null;
2643
+ note?: string;
2644
+ idempotencyKey?: string;
2645
+ }): Promise<PartnerGiftCredit>;
2646
+ /**
2647
+ * 00760: your webhook endpoints, each hearing every business you made;
2648
+ * with a test key, your sandbox's.
2649
+ */
2650
+ webhooks(): Promise<PartnerWebhook[]>;
2651
+ /** 00760: add an endpoint for every business you made. Its signing `secret` is in this answer only. Sent once. */
2652
+ addWebhook(endpoint: {
2653
+ url: string;
2654
+ events?: string[];
2655
+ label?: string;
2656
+ }): Promise<PartnerWebhook & {
2657
+ secret: string;
2658
+ }>;
2659
+ /** 00760: change an endpoint on every business at once; `active: true` turns back on every copy that paused. */
2660
+ updateWebhook(id: string, changes: {
2661
+ url?: string;
2662
+ events?: string[];
2663
+ label?: string | null;
2664
+ active?: boolean;
2665
+ }): Promise<PartnerWebhook>;
2666
+ /** 00760: remove an endpoint from every business. */
2667
+ deleteWebhook(id: string): Promise<void>;
2668
+ /** 00760: an endpoint's latest deliveries across every business, newest first. */
2669
+ webhookDeliveries(id: string, opts?: {
2670
+ limit?: number;
2671
+ }): Promise<PartnerWebhookDelivery[]>;
2672
+ /** 00760: deliver one again. */
2673
+ replayWebhookDelivery(id: string, delivery: string): Promise<{
2674
+ id: string;
2675
+ replay_of: string;
2676
+ }>;
2677
+ /**
2678
+ * 00763: a start link to one of your businesses' screens inside your product,
2679
+ * for one of your users. It opens once, within five minutes: ask for it as
2680
+ * the page that frames it loads. Sent once.
2681
+ */
2682
+ embedSession(id: string, session: {
2683
+ user: {
2684
+ external_id: string;
2685
+ name: string;
2686
+ email?: string;
2687
+ role?: "admin" | "member";
2688
+ };
2689
+ components?: Array<"documents">;
2690
+ }): Promise<PartnerEmbedSession>;
2691
+ /** 00759: a calendar month (YYYY-MM, this one when left out) per business, in your prices, with what to bill. */
2692
+ usage(month?: string): Promise<PartnerUsage>;
2693
+ /**
2694
+ * 00751: a client that acts for one of your businesses -- one you made,
2695
+ * or one that connected your app -- by its id or your own `external_id`.
2696
+ * Every `SignSealer` method then works for that business. Needs a partner key.
2697
+ */
2698
+ business(id: string): SignSealer;
2699
+ }
2700
+ /** What a partner's app may ask a business for. Your client is registered with a subset; ask for no more than that. */
2701
+ export type OAuthScope = "signing:read" | "signing:write" | "signing:templates" | "signing:workflows" | "signing:webhooks" | "signing:subjects" | "signing:send" | "signing:remind" | "signing:links" | "signing:void";
2702
+ export interface OAuthOptions {
2703
+ /** Your OAuth client's id, `ss_client_…`. */
2704
+ clientId: string;
2705
+ /** Its secret, `ss_secret_…`: shown once, when the client was made or a new one was made on your partner dashboard. */
2706
+ clientSecret: string;
2707
+ /** Where `/oauth/authorize` and `/oauth/token` are. Default `https://api.signsealer.com`. */
2708
+ baseUrl?: string;
2709
+ fetch?: typeof globalThis.fetch;
2710
+ }
2711
+ /** A PKCE pair (RFC 7636): keep `verifier` for the exchange, send `challenge` to authorise. */
2712
+ export interface Pkce {
2713
+ verifier: string;
2714
+ challenge: string;
2715
+ method: "S256";
2716
+ }
2717
+ /**
2718
+ * The token endpoint's answer, as it sends it, with two additions.
2719
+ *
2720
+ * `access_token` is an API key (`mk_live_…`): hand it to `new SignSealer({
2721
+ * apiKey })`. `scopes` is `scope` split, and it is what the business
2722
+ * actually gave, which can be less than you asked for: a grant never holds
2723
+ * more than the person who made it may do. `expires_at` is absolute, worked
2724
+ * out from the moment the request was sent, so it errs early.
2725
+ */
2726
+ export interface OAuthTokens {
2727
+ access_token: string;
2728
+ token_type: "Bearer";
2729
+ /** Seconds the access token lives: an hour. */
2730
+ expires_in: number;
2731
+ /** When the access token stops working, as an ISO time. */
2732
+ expires_at: string;
2733
+ scope: string;
2734
+ scopes: string[];
2735
+ /** Good once, for thirty days. Store it before you use `access_token`. Null for a client that is given none. */
2736
+ refresh_token: string | null;
2737
+ }
2738
+ /**
2739
+ * A refusal from the OAuth endpoints, or from the consent screen's answer.
2740
+ *
2741
+ * `code` is RFC 6749's `error` and `message` its `error_description` (both
2742
+ * also under their RFC names). Two questions decide what to do:
2743
+ *
2744
+ * - `reconnect`: the grant is over, or the code is spent. `invalid_grant`
2745
+ * -- the business disconnected you, the person who connected you can no
2746
+ * longer give what you hold, a token or code was used twice, or it
2747
+ * expired. Send the business through `authorizeUrl` again; nothing else
2748
+ * will bring it back.
2749
+ * - `transient`: the network or SignSealer, not your request. The grant may
2750
+ * well still be good. On a refresh, **whether the token was spent is
2751
+ * unknown**: read `refresh()` before deciding to send it again.
2752
+ *
2753
+ * `invalid_client` is neither: your client id or secret did not
2754
+ * authenticate, which is your configuration, for every business at once.
2755
+ *
2756
+ * `retryable` is always false. SignSealerError's "worth trying again
2757
+ * unchanged" is exactly the advice that turns a lost answer into a revoked
2758
+ * grant here.
2759
+ */
2760
+ export declare class SignSealerOAuthError extends SignSealerError {
2761
+ constructor(status: number, code: string, message: string, requestId?: string, retryAfter?: number);
2762
+ /** RFC 6749's name for `code`. */
2763
+ get error(): string;
2764
+ /** RFC 6749's name for `message`. */
2765
+ get errorDescription(): string;
2766
+ get retryable(): boolean;
2767
+ /** The grant is over or the code spent: send the business to connect again. */
2768
+ get reconnect(): boolean;
2769
+ /** The network or SignSealer failed, not the request. On a refresh, the token may or may not have been spent. */
2770
+ get transient(): boolean;
2771
+ }
2772
+ /**
2773
+ * A fresh PKCE pair, one per authorise request: 32 random bytes as a
2774
+ * 43-character verifier, and its S256 challenge.
2775
+ *
2776
+ * Keep the verifier on your server, against the `state` you send (a
2777
+ * session, or a short-lived row), and give it to `exchangeCode`. Never put
2778
+ * it in the authorise address: the challenge goes there, and the verifier
2779
+ * is what proves the code came back to the same party that asked.
2780
+ */
2781
+ export declare function createPkce(): Promise<Pkce>;
2782
+ /** The S256 challenge for a verifier: base64url of its SHA-256, without padding (RFC 7636, section 4.2). */
2783
+ export declare function pkceChallenge(verifier: string): Promise<string>;
2784
+ /**
2785
+ * "Connect with SignSealer", for a partner's server (1.20.0).
2786
+ *
2787
+ * ```ts
2788
+ * const oauth = new SignSealerOAuth({ clientId, clientSecret });
2789
+ * const { verifier, challenge } = await createPkce();
2790
+ * redirect(oauth.authorizeUrl({ redirectUri, scopes: ["signing:read", "signing:write"], state, codeChallenge: challenge }));
2791
+ * // …and on the way back:
2792
+ * const { code } = oauth.callback(request.url, savedState);
2793
+ * const tokens = await oauth.exchangeCode({ code, redirectUri, codeVerifier: verifier });
2794
+ * const client = new SignSealer({ apiKey: tokens.access_token });
2795
+ * ```
2796
+ *
2797
+ * The client is authenticated to `/oauth/token` by HTTP Basic, which RFC
2798
+ * 6749 prefers and the server reads first. Every token request is sent
2799
+ * exactly once: see `refresh()` for why that is the whole point.
2800
+ */
2801
+ export declare class SignSealerOAuth {
2802
+ #private;
2803
+ constructor(opts: OAuthOptions);
2804
+ /**
2805
+ * Where to send the business's browser. SignSealer signs them in (or lets
2806
+ * them make an account and name their business on the way), shows your
2807
+ * registered name and what each scope allows, and sends them back to
2808
+ * `redirectUri` with `code` and your `state`, or with `error`.
2809
+ *
2810
+ * `redirectUri` must be one you registered, byte for byte, and the same
2811
+ * string you give `exchangeCode`. `state` is yours, returned untouched:
2812
+ * make it unguessable, keep it with the verifier, and check it in
2813
+ * `callback`. Ask for the fewest scopes that do the job; a scope your
2814
+ * client was not registered with is refused as `invalid_scope`.
2815
+ */
2816
+ authorizeUrl(opts: {
2817
+ redirectUri: string;
2818
+ scopes: OAuthScope[];
2819
+ state: string;
2820
+ codeChallenge: string;
2821
+ }): string;
2822
+ /**
2823
+ * Read the consent screen's answer from your redirect's query: the code,
2824
+ * once `state` matches the one you kept. A business that pressed Not now
2825
+ * comes back as `access_denied`, and a request the screen could not
2826
+ * answer as its RFC 6749 error; both are thrown as SignSealerOAuthError,
2827
+ * with `status` 400. A `state` that does not match is `state_mismatch`:
2828
+ * do not exchange that code.
2829
+ */
2830
+ callback(query: string | URL | URLSearchParams, expectedState: string): {
2831
+ code: string;
2832
+ };
2833
+ /**
2834
+ * Exchange the code from `callback` for the business's tokens. Do it at
2835
+ * once: a code lives sixty seconds and is good once.
2836
+ *
2837
+ * Sent once and never again. A code presented twice is a replay, and the
2838
+ * server revokes the grant it made, so a retry after a lost answer would
2839
+ * disconnect the business it just connected. If this throws `transient`,
2840
+ * send the business through `authorizeUrl` again.
2841
+ */
2842
+ exchangeCode(opts: {
2843
+ code: string;
2844
+ redirectUri: string;
2845
+ codeVerifier: string;
2846
+ }): Promise<OAuthTokens>;
2847
+ /**
2848
+ * Swap a refresh token for a new access token **and a new refresh token**.
2849
+ *
2850
+ * **THIS IS NEVER RETRIED, AND YOU MUST NOT RETRY IT EITHER WITHOUT
2851
+ * THINKING.** The refresh token you send is spent the moment SignSealer
2852
+ * reads it. Presenting a spent one is treated as theft: the whole family
2853
+ * is revoked -- every refresh token from that connection, the grant, and
2854
+ * every access token issued under it -- and the business has to connect
2855
+ * again. From the server's side a buggy retry and a stolen token look the
2856
+ * same.
2857
+ *
2858
+ * So:
2859
+ *
2860
+ * 1. **Serialise refreshes per grant.** One at a time for each business
2861
+ * (a row lock, an advisory lock, a queue). Two workers refreshing the
2862
+ * same grant at once will end it.
2863
+ * 2. **Store the new refresh token before you use the access token**,
2864
+ * atomically, while still holding the lock. A new refresh token you
2865
+ * lose cannot be got back.
2866
+ * 3. **A `transient` failure leaves the token's state unknown.** If the
2867
+ * request reached SignSealer and the answer was lost, the token you
2868
+ * hold is spent and its successor lost with the answer; if it never
2869
+ * arrived, it is still good. Sending it again either works or ends
2870
+ * the connection (`reconnect`), which losing the successor had
2871
+ * already made inevitable. That is your decision, made under the
2872
+ * lock, never a loop.
2873
+ * 4. **`reconnect` means reconnect.** Mark the business disconnected and
2874
+ * ask them to connect again; do not try the token again.
2875
+ */
2876
+ refresh(refreshToken: string): Promise<OAuthTokens>;
2323
2877
  }
2324
2878
  export declare const WEBHOOK_EVENT_HEADER = "signsealer-event-id";
2325
2879
  export declare const WEBHOOK_TIMESTAMP_HEADER = "signsealer-timestamp";