@signsealer/sdk 1.22.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,6 +133,12 @@ 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`.
@@ -225,8 +231,12 @@ export interface SmsConsent {
225
231
  phone: string;
226
232
  /** What the engine will actually do: consent live, and the number not suppressed. */
227
233
  may_text: boolean;
228
- /** Why not, when `may_text` is false: they opted out, we cannot reach the number, or nobody ever asked. */
229
- 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;
230
240
  /** Where the business said the number came from, in their words. */
231
241
  obtained_via: string | null;
232
242
  obtained_at: string | null;
@@ -347,7 +357,7 @@ export interface Ask {
347
357
  */
348
358
  sensitive?: boolean;
349
359
  /** `business` (1.16.0): answered by whoever signs for the business, and nobody else (00611). */
350
- supplied_by?: "adult" | "per_child" | "staff" | "business";
360
+ supplied_by?: "adult" | "per_child" | "everyone" | "staff" | "business";
351
361
  options?: string[];
352
362
  hint?: string;
353
363
  /**
@@ -875,6 +885,13 @@ export interface ClientOptions {
875
885
  * header and every other route refuses it, which is the right answer.
876
886
  */
877
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;
878
895
  baseUrl?: string;
879
896
  /** Total attempts for a retryable failure, the first included. */
880
897
  maxAttempts?: number;
@@ -888,7 +905,17 @@ export interface ClientOptions {
888
905
  */
889
906
  maxWaitMs?: number;
890
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;
891
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";
892
919
  export declare class SignSealer {
893
920
  #private;
894
921
  /**
@@ -1144,6 +1171,19 @@ export declare class SignSealer {
1144
1171
  reminded: true;
1145
1172
  by: "email" | "sms";
1146
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
+ }>;
1147
1187
  /**
1148
1188
  * A fresh signing link to put in an `<iframe>` (1.6.0), with the sites it
1149
1189
  * may be framed on. Call it when the page is about to be shown rather than
@@ -1341,6 +1381,10 @@ export declare class SignSealer {
1341
1381
  packet_id: string;
1342
1382
  voided: number;
1343
1383
  kept: number;
1384
+ signed: Array<{
1385
+ document_id: string;
1386
+ title: string;
1387
+ }>;
1344
1388
  }>;
1345
1389
  /**
1346
1390
  * The booking systems this business can connect, and its connections (00424).
@@ -2038,7 +2082,7 @@ export interface Device {
2038
2082
  }
2039
2083
  export interface Captured {
2040
2084
  offline?: boolean;
2041
- /** 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. */
2042
2086
  at?: string;
2043
2087
  device?: string;
2044
2088
  }
@@ -2185,7 +2229,7 @@ export declare class SignSealerSigning {
2185
2229
  * the business did not ask; refused as busy, to be sent again after
2186
2230
  * `retryAfter` seconds, as `supplyPhoto` is.
2187
2231
  */
2188
- captureIdEvidence(token: string, kind: "id" | "selfie", image: {
2232
+ captureIdEvidence(token: string, kind: "id" | "id_back" | "selfie", image: {
2189
2233
  contentType: string;
2190
2234
  bytes: Uint8Array | string;
2191
2235
  }, captured?: Captured): Promise<{
@@ -2281,6 +2325,9 @@ export interface PartnerProfile {
2281
2325
  month_to_date: PartnerMonthToDate;
2282
2326
  /** The link to hand a business: signing up through it makes the business yours. */
2283
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;
2284
2331
  }
2285
2332
  /** A business you brought (1.8.0). */
2286
2333
  export interface PartnerBusiness {
@@ -2321,13 +2368,189 @@ export interface PartnerStatement {
2321
2368
  revenue_cents: number;
2322
2369
  }>;
2323
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
+ }
2324
2545
  export interface PartnerOptions {
2325
- /** Your OAuth client's id, `ss_client_…`. */
2326
- clientId: string;
2546
+ /** Your OAuth client's id, `ss_client_…`. With `clientSecret`; or give `partnerKey` instead. */
2547
+ clientId?: string;
2327
2548
  /** Its secret, `ss_secret_…`: the one shown once when SignSealer registered you. */
2328
- 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;
2329
2552
  baseUrl?: string;
2330
- /** 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. */
2331
2554
  maxAttempts?: number;
2332
2555
  fetch?: typeof globalThis.fetch;
2333
2556
  }
@@ -2361,6 +2584,118 @@ export declare class SignSealerPartner {
2361
2584
  }>;
2362
2585
  /** Every closed month, newest first. */
2363
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;
2364
2699
  }
2365
2700
  /** What a partner's app may ask a business for. Your client is registered with a subset; ask for no more than that. */
2366
2701
  export type OAuthScope = "signing:read" | "signing:write" | "signing:templates" | "signing:workflows" | "signing:webhooks" | "signing:subjects" | "signing:send" | "signing:remind" | "signing:links" | "signing:void";