@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.
- package/CHANGELOG.md +141 -0
- package/README.md +231 -0
- package/dist/cjs/index.cjs +493 -9
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +563 -9
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/index.js +488 -8
- package/dist/esm/index.js.map +1 -1
- package/package.json +1 -1
package/dist/esm/index.d.ts
CHANGED
|
@@ -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
|
-
/**
|
|
209
|
-
|
|
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
|
|
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
|
|
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.
|
|
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";
|