@signsealer/sdk 1.22.0 → 1.26.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.
@@ -4,7 +4,9 @@
4
4
  * Deliberately dependency-free: `fetch` is in the runtime, and a signing SDK
5
5
  * that drags a HTTP library into somebody's build is a signing SDK that gets
6
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.
7
+ * 18 and every edge runtime. It is the server's half: a client given a secret
8
+ * key in a web page throws (1.26.0), and the page's half, which holds no key,
9
+ * is `@signsealer/embed`.
8
10
  *
9
11
  * Three things it does that a hand-rolled client usually does not:
10
12
  *
@@ -131,8 +133,18 @@ export interface Account {
131
133
  available: boolean;
132
134
  why_not: "test" | "plan" | "number" | "beta" | null;
133
135
  wording: string;
134
- /** The business's own verified texting number (1.13.0), once it has one. */
136
+ /**
137
+ * The business's own verified texting number (1.13.0), once it has one.
138
+ * Null to an app the business connected, and to a tablet (1.26.0): only
139
+ * the business's own key, and a partner for a business it manages, see it.
140
+ */
135
141
  number?: string | null;
142
+ /**
143
+ * Where a text goes (1.24.0): `US` and `CA`, and `GB` while texting UK
144
+ * mobiles is on. A mobile anywhere else is not texted: ask for an email
145
+ * address beside it. A signer with only such a mobile is refused.
146
+ */
147
+ countries?: Array<"US" | "CA" | "GB">;
136
148
  /**
137
149
  * Where its application for one has got to (1.13.0); null when it has not
138
150
  * applied. Each step is also sent as `texting.number_updated`.
@@ -165,10 +177,14 @@ export interface TextingApplication {
165
177
  /** `applied`, `submitted`, `in_review`, `needs_changes`, `verified`, `paused`, `failed`, and the steps of bringing a number. */
166
178
  status: string;
167
179
  kind: TextingNumberKind;
168
- /** The number, once it is the business's: verified or paused. */
180
+ /**
181
+ * The number, once it is the business's: verified or paused. On
182
+ * `account()`, null to an app the business connected and to a tablet
183
+ * (1.26.0), as `reason` is.
184
+ */
169
185
  phone: string | null;
170
186
  area_code: string | null;
171
- /** What the carriers asked to change, or why it is held up; null otherwise. */
187
+ /** What the carriers asked to change, or why it is held up; null otherwise, and null to a connected app (1.26.0). */
172
188
  reason: string | null;
173
189
  /** True for a number the business already had and is bringing. */
174
190
  brought: boolean;
@@ -214,6 +230,123 @@ export interface TextingNumberInvitation {
214
230
  fields: string[];
215
231
  expires_at: string;
216
232
  }
233
+ /**
234
+ * A business's brand, delivery and reminders (00792). `editable` is true only
235
+ * for a partner key acting for a business it manages.
236
+ */
237
+ export interface Settings {
238
+ editable: boolean;
239
+ branding: {
240
+ business_name: string;
241
+ brand_name: string | null;
242
+ /** Hex colours, `#` and six digits. */
243
+ primary_color: string | null;
244
+ accent_color: string | null;
245
+ /** The name the business's emails come from. */
246
+ sender_name: string | null;
247
+ /** Where a signer's reply goes. */
248
+ reply_to: string | null;
249
+ has_logo: boolean;
250
+ logo_url: string | null;
251
+ };
252
+ /** `signsealer`: we send the links; `mine`: your system does; `both`: see `GET /v1/settings`. */
253
+ delivery: {
254
+ who_sends: "signsealer" | "mine" | "both";
255
+ };
256
+ /** Days before an unsigned link is reminded (0 is never), and how long a link lives. */
257
+ reminders: {
258
+ remind_after_days: number;
259
+ link_days: number;
260
+ };
261
+ }
262
+ /** What `updateSettings` changes: only what is named; null clears it (00792). */
263
+ export interface SettingsChanges {
264
+ brand_name?: string | null;
265
+ primary_color?: string | null;
266
+ accent_color?: string | null;
267
+ sender_name?: string | null;
268
+ reply_to?: string | null;
269
+ /** A PNG, base64, a megabyte at most; null takes the logo away. */
270
+ logo_png_base64?: string | null;
271
+ who_sends?: "signsealer" | "mine" | "both";
272
+ remind_after_days?: number | null;
273
+ link_days?: number | null;
274
+ }
275
+ /** A managed business's texting-number application, filed by its partner (00792). */
276
+ export interface TextingNumberApplication {
277
+ /** A sole proprietor applies themselves: the registry texts them a code. */
278
+ kind: "toll_free" | "local";
279
+ legal_name: string;
280
+ entity_type: "PRIVATE_PROFIT" | "PUBLIC_PROFIT" | "NON_PROFIT" | "GOVERNMENT";
281
+ ein: string;
282
+ website: string;
283
+ address_line1: string;
284
+ address_line2?: string;
285
+ city: string;
286
+ state: string;
287
+ postal_code: string;
288
+ contact_first_name: string;
289
+ contact_last_name: string;
290
+ contact_email: string;
291
+ contact_phone: string;
292
+ volume: "10" | "100" | "1,000" | "10,000" | "100,000";
293
+ /** For a local number. */
294
+ area_code?: string;
295
+ vertical?: string;
296
+ privacy_url?: string;
297
+ terms_url?: string;
298
+ opt_in_url?: string;
299
+ own_opt_in?: string;
300
+ /** Your statement, for the business, that it is all true and it texts only people who asked. */
301
+ attest: true;
302
+ }
303
+ /** The business's own texting number, where its application has got to, and the carriers' wording (00792). */
304
+ export interface TextingNumberState {
305
+ /**
306
+ * False for a key the application is not its to read (an app the business
307
+ * connected): `number` then has its status, `application` empty, `reason`
308
+ * null, and `events` empty.
309
+ */
310
+ detail: boolean;
311
+ /** True for a live partner key acting for a business it manages. */
312
+ may_apply: boolean;
313
+ /** `own_account`: the business applies in its own dashboard; `sandbox`: it never texts anybody. */
314
+ why_not: "own_account" | "sandbox" | null;
315
+ member: boolean;
316
+ ready: boolean;
317
+ kinds: Array<{
318
+ kind: TextingNumberKind;
319
+ name: string;
320
+ monthly_cents: number;
321
+ setup_cents: number;
322
+ needs_cents: number;
323
+ by_partner: boolean;
324
+ }>;
325
+ number: null | {
326
+ status: string;
327
+ kind: TextingNumberKind | null;
328
+ area_code: string | null;
329
+ phone: string | null;
330
+ reason: string | null;
331
+ applied_at: string;
332
+ submitted_at: string | null;
333
+ verified_at: string | null;
334
+ setup_cents: number;
335
+ filed: boolean;
336
+ application: Record<string, string | null>;
337
+ };
338
+ events: Array<{
339
+ at: string;
340
+ status: string;
341
+ note: string | null;
342
+ }>;
343
+ /** Word for word: the consent a signer ticks, the texts they get, the answer to HELP. */
344
+ wording: {
345
+ consent: string;
346
+ samples: string[];
347
+ help: string;
348
+ };
349
+ }
217
350
  /** What `recordSmsConsent` wrote, with the number as we normalised it. */
218
351
  export interface SmsConsentRecorded {
219
352
  /** E.164. One number written three ways is one record, and this is it. */
@@ -225,8 +358,12 @@ export interface SmsConsent {
225
358
  phone: string;
226
359
  /** What the engine will actually do: consent live, and the number not suppressed. */
227
360
  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;
361
+ /**
362
+ * Why not, when `may_text` is false: they opted out, we cannot reach the
363
+ * number, or nobody ever asked; or (1.24.0) `country`, a number outside the
364
+ * US and Canada, which is not texted whatever the consent.
365
+ */
366
+ why_not: "country" | "revoked" | "suppressed" | "no_consent" | null;
230
367
  /** Where the business said the number came from, in their words. */
231
368
  obtained_via: string | null;
232
369
  obtained_at: string | null;
@@ -347,7 +484,7 @@ export interface Ask {
347
484
  */
348
485
  sensitive?: boolean;
349
486
  /** `business` (1.16.0): answered by whoever signs for the business, and nobody else (00611). */
350
- supplied_by?: "adult" | "per_child" | "staff" | "business";
487
+ supplied_by?: "adult" | "per_child" | "everyone" | "staff" | "business";
351
488
  options?: string[];
352
489
  hint?: string;
353
490
  /**
@@ -453,6 +590,11 @@ export interface TemplateInput {
453
590
  consent_text?: string | null;
454
591
  /** Up to 50. Set here rather than in a second call — see `createTemplate`. */
455
592
  fields?: Ask[];
593
+ /**
594
+ * `markdown` to write it with the dashboard's formatting (headings, bold,
595
+ * italic, lists) from the first version; `text`, the default, otherwise.
596
+ */
597
+ body_format?: "text" | "markdown";
456
598
  }
457
599
  /**
458
600
  * The brand an account shows its signers (00220). SignSealer's own without
@@ -574,6 +716,52 @@ export interface TemplatePdf {
574
716
  original_name?: string | null;
575
717
  uploaded_at?: string;
576
718
  }
719
+ /** A page of a PDF template (1.26.0): its size in points as a reader sees it, and where its picture is. */
720
+ export interface TemplatePage {
721
+ n: number;
722
+ width: number;
723
+ height: number;
724
+ rotation?: number;
725
+ /** The API path of its picture (`templatePage`), with the same key; null until SignSealer has drawn it. */
726
+ image_url: string | null;
727
+ }
728
+ /** What `templateFields` and `setTemplateFields` answer (1.26.0). */
729
+ export interface TemplateFields {
730
+ template_id: string;
731
+ code: string;
732
+ version: number;
733
+ is_published: boolean;
734
+ has_pdf: boolean;
735
+ /** Null for a written template, which has no pages. */
736
+ page_count: number | null;
737
+ pages: TemplatePage[];
738
+ /** Each question, a box on the page with its `place`. */
739
+ fields: Ask[];
740
+ /** Names this list: give it to `setTemplateFields` to have a save made from an older list refused (409 `stale`). */
741
+ fields_version: string;
742
+ }
743
+ /** What `createPdfTemplate` answers (1.26.0): the draft, as `template` answers it, and what was found in the file. */
744
+ export interface PdfTemplate extends TemplateDetail {
745
+ pdf: {
746
+ page_count: number;
747
+ /** Hex. The fingerprint the body names and the certificate commits to. */
748
+ sha256: string;
749
+ pages: TemplatePage[];
750
+ /** How many boxes of each kind were put where the file asks for them; `more_to_sign`, the pages of any further place to sign, left for you. */
751
+ found: {
752
+ signature: number;
753
+ date: number;
754
+ initials: number;
755
+ questions: number;
756
+ business: number;
757
+ more_to_sign: number[];
758
+ };
759
+ /** A scan: `all` pages are pictures, or these pages are. Read only where the business switched on Read scanned PDFs. */
760
+ scan: "all" | number[] | null;
761
+ /** What was taken out of the file because it could act on its own. */
762
+ removed: string[];
763
+ };
764
+ }
577
765
  /**
578
766
  * What a reader will be told about the signer of a sealed PDF.
579
767
  *
@@ -603,7 +791,8 @@ export interface SignerLink {
603
791
  * The signing token. Returned once, and never again — only its hash is kept.
604
792
  * Null for a signer held for their turn on a document signed in order
605
793
  * (00609): their link is made and sent to them when the step before them is
606
- * signed.
794
+ * signed. Null too, with `redacted`, on the answer to a retry with the same
795
+ * idempotency key (1.26.0).
607
796
  */
608
797
  token: string | null;
609
798
  /** The page to send them to, built from the token (1.6.0); null when `token` is. */
@@ -616,6 +805,12 @@ export interface SignerLink {
616
805
  for_business?: boolean;
617
806
  /** Signed only by an approval from the application it was bound to (1.18.0, 00684); it has no link. */
618
807
  application_bound?: true;
808
+ /**
809
+ * The answer to a retry with the same idempotency key (1.26.0): the link was
810
+ * in the first answer only, so `token` and `url` are null here. Mint a fresh
811
+ * one with `embedLink`, or send one with `remind`.
812
+ */
813
+ redacted?: true;
619
814
  }
620
815
  /** Who has signed one document (00340): names and states, nothing else. */
621
816
  export interface DocumentSigners {
@@ -683,6 +878,8 @@ export interface StartedWorkflow {
683
878
  signers: SignerLink[];
684
879
  /** 00541: the roles whose `show_if` these answers did not meet, by label; absent when every role signs. */
685
880
  not_needed?: string[];
881
+ /** A retry's answer whose tokens were taken out (1.26.0): see `SignerLink.redacted`. */
882
+ links_redacted?: true;
686
883
  }
687
884
  export interface PacketSummary {
688
885
  packet_id: string;
@@ -875,6 +1072,13 @@ export interface ClientOptions {
875
1072
  * header and every other route refuses it, which is the right answer.
876
1073
  */
877
1074
  apiKey?: string;
1075
+ /**
1076
+ * 00751: a partner acting for one of its businesses. With a partner key
1077
+ * (`ss_partner_…`) as `apiKey`, every call is made as the business this
1078
+ * names -- its id, or your own `external_id` for it -- in the
1079
+ * `SignSealer-Business` header. `SignSealerPartner.business(id)` builds one.
1080
+ */
1081
+ business?: string;
878
1082
  baseUrl?: string;
879
1083
  /** Total attempts for a retryable failure, the first included. */
880
1084
  maxAttempts?: number;
@@ -888,7 +1092,19 @@ export interface ClientOptions {
888
1092
  */
889
1093
  maxWaitMs?: number;
890
1094
  fetch?: typeof globalThis.fetch;
1095
+ /**
1096
+ * What the client says it is, in `User-Agent`. By default
1097
+ * `signsealer-sdk/<version> (node)`, so a request can be traced to the
1098
+ * library and version that made it; give your own to name your integration
1099
+ * too (`"acme-bookings/2.1 signsealer-sdk"`), or `""` to send none. Sent
1100
+ * only outside a browser: a browser sets its own.
1101
+ */
1102
+ userAgent?: string;
891
1103
  }
1104
+ /** This package's version, as `package.json` has it; `tests/sdk.ts` holds the two together. */
1105
+ export declare const SDK_VERSION = "1.26.0";
1106
+ /** What a client built with a secret key in a web page throws (1.26.0). */
1107
+ export declare const KEY_IN_PAGE_MESSAGE: string;
892
1108
  export declare class SignSealer {
893
1109
  #private;
894
1110
  /**
@@ -910,6 +1126,30 @@ export declare class SignSealer {
910
1126
  * moment somebody is deciding whether to trust the page.
911
1127
  */
912
1128
  branding(): Promise<Branding>;
1129
+ /**
1130
+ * The business's brand, how its signing links go, and its reminders
1131
+ * (00792). `editable` says whether this key may change them: true only for
1132
+ * a partner acting for a business it manages.
1133
+ */
1134
+ settings(): Promise<Settings>;
1135
+ /**
1136
+ * Set a managed business's brand, delivery and reminders, as its partner
1137
+ * (00792; with `partner.business(id)`). Only what is named changes; null
1138
+ * clears it. Any other key is refused with 403: a business that owns its
1139
+ * account sets these in its dashboard. A PATCH of the same values, so a
1140
+ * retry after a lost answer sets the same thing again.
1141
+ */
1142
+ updateSettings(changes: SettingsChanges): Promise<Settings>;
1143
+ /**
1144
+ * Apply for a managed business's texting number, as its partner (00792;
1145
+ * with `partner.business(id)`), for a toll-free or a local number. Checked
1146
+ * as the carriers would check it; a local number's setup is drawn from
1147
+ * your balance now. Sent once, never retried: a second answer would file
1148
+ * the application again.
1149
+ */
1150
+ applyForTextingNumber(application: TextingNumberApplication): Promise<TextingNumberState>;
1151
+ /** The business's own texting number, its application's steps, and the carriers' wording (00792). */
1152
+ textingNumber(): Promise<TextingNumberState>;
913
1153
  /** Prove the key works, and say whose account it is. */
914
1154
  account(): Promise<Account>;
915
1155
  /** Every version of every template, newest first; `code` narrows it to one template's versions. No text: `template(id)` has that. */
@@ -938,7 +1178,13 @@ export declare class SignSealer {
938
1178
  * is wrong, for a placeholder the template does not declare or a PDF with
939
1179
  * pages nobody has drawn.
940
1180
  */
941
- publishTemplate(id: string, idempotencyKey?: string): Promise<TemplateDetail>;
1181
+ publishTemplate(id: string, idempotencyKey?: string): Promise<TemplateDetail & {
1182
+ /** 1.26.0: what was published but cannot be signed where it is: `nothing_placed`, a PDF with no box on its pages. */
1183
+ warnings?: Array<{
1184
+ code: string;
1185
+ message: string;
1186
+ }>;
1187
+ }>;
942
1188
  /**
943
1189
  * The next version of a published template, as a draft (1.6.0): the
944
1190
  * newest version copied, with whatever you change. `id` must be the
@@ -1003,10 +1249,56 @@ export declare class SignSealer {
1003
1249
  *
1004
1250
  * `ready` is the one to check: a PDF template cannot be published until
1005
1251
  * SignSealer has drawn a picture of every page from the file itself
1006
- * (00474), which it does as the file is uploaded. Uploading the file is a
1007
- * dashboard step, where the boxes are placed; there is no API route for it.
1252
+ * (00474), which it does as the file is uploaded, in the dashboard or with
1253
+ * `createPdfTemplate`.
1008
1254
  */
1009
1255
  templatePdf(id: string): Promise<TemplatePdf>;
1256
+ /**
1257
+ * A PDF template, as a draft, from the file (1.26.0): what the dashboard's
1258
+ * upload makes. The file is read, sanitised and drawn exactly as an upload
1259
+ * is -- up to 12 MB and 60 pages, refused in the dashboard's words past
1260
+ * either, or when it is not a PDF or is password-protected -- and the
1261
+ * signature and date every PDF starts with are put where the file asks for
1262
+ * them, with initials, a printed name and a fillable form's questions each
1263
+ * on its box. Check them with `templateFields`, move them with
1264
+ * `setTemplateFields`, then `publishTemplate`. `pdf` is the file's bytes
1265
+ * or its base64. Needs `signing:templates`.
1266
+ */
1267
+ createPdfTemplate(input: {
1268
+ name: string;
1269
+ pdf: Uint8Array | string;
1270
+ filename: string;
1271
+ kind?: "nda" | "waiver" | "contract" | "consent" | "policy" | "other";
1272
+ code?: string;
1273
+ }, idempotencyKey?: string): Promise<PdfTemplate>;
1274
+ /**
1275
+ * The questions and boxes a template asks for (1.26.0), with a PDF's pages
1276
+ * and the address of each page's picture, for a screen to draw them on.
1277
+ */
1278
+ templateFields(id: string): Promise<TemplateFields>;
1279
+ /**
1280
+ * Replace a draft's questions and boxes (1.26.0): the whole list, as the
1281
+ * dashboard's Place step saves it. A box's `place` is its page and
1282
+ * fractions of the page from its top-left. Refused, naming the question,
1283
+ * for a page the file does not have, a box off its page, a kind that is
1284
+ * not one, and a published version (revise it first).
1285
+ *
1286
+ * `fieldsVersion`, optional, is the `fields_version` of the list these
1287
+ * replace, as `templateFields` answered it: given, a save made after the
1288
+ * list changed (a box SignSealer placed on a scan, another person's save)
1289
+ * is refused with 409 `stale` rather than undoing it.
1290
+ */
1291
+ setTemplateFields(id: string, fields: Ask[], opts?: {
1292
+ fieldsVersion?: string;
1293
+ }): Promise<TemplateFields>;
1294
+ /** One page of a PDF template as PNG bytes (1.26.0), the picture a signer is shown. 404 until it is drawn. */
1295
+ templatePage(id: string, page: number): Promise<{
1296
+ page: number;
1297
+ width: number;
1298
+ height: number;
1299
+ contentType: string;
1300
+ bytes: Uint8Array<ArrayBufferLike>;
1301
+ }>;
1010
1302
  /**
1011
1303
  * Record that you have consent to text a number.
1012
1304
  *
@@ -1144,6 +1436,19 @@ export declare class SignSealer {
1144
1436
  reminded: true;
1145
1437
  by: "email" | "sms";
1146
1438
  }>;
1439
+ /**
1440
+ * The sandbox plays a signer (00719): for a test key only, `signed` (their
1441
+ * consent and a typed signature, through every check the signing page
1442
+ * makes), `declined` (with `reason`) or `expired`, so each outcome and its
1443
+ * webhooks can be driven from your tests. Refused (403) for a live key.
1444
+ * Sent once: a second call for a signer who has signed is refused anyway.
1445
+ */
1446
+ simulateSigning(documentId: string, signerId: string, outcome: "signed" | "declined" | "expired", reason?: string): Promise<{
1447
+ document_id: string;
1448
+ signer_id: string;
1449
+ outcome: "signed" | "declined" | "expired";
1450
+ simulated: true;
1451
+ }>;
1147
1452
  /**
1148
1453
  * A fresh signing link to put in an `<iframe>` (1.6.0), with the sites it
1149
1454
  * may be framed on. Call it when the page is about to be shown rather than
@@ -1198,6 +1503,11 @@ export declare class SignSealer {
1198
1503
  /**
1199
1504
  * Send, and take the links back once.
1200
1505
  *
1506
+ * Once means once: a retry with the same idempotency key (the client's own,
1507
+ * after a dropped connection, or yours) sends nothing again and answers with
1508
+ * every link's `token` and `url` null, `redacted: true` on each and
1509
+ * `links_redacted: true` on the answer. Mint a fresh link with `embedLink`.
1510
+ *
1201
1511
  * Each signer needs an `email`, a `phone`, or both; a `cc` may have neither.
1202
1512
  * Given both, the same link goes out twice — by mail and by text — because a
1203
1513
  * person who does not check one inbox checks the other. The text goes only
@@ -1233,6 +1543,7 @@ export declare class SignSealer {
1233
1543
  };
1234
1544
  }>, idempotencyKey?: string): Promise<{
1235
1545
  links: SignerLink[];
1546
+ links_redacted?: true;
1236
1547
  }>;
1237
1548
  void(documentId: string, reason: string, idempotencyKey?: string): Promise<{
1238
1549
  voided: true;
@@ -1341,6 +1652,10 @@ export declare class SignSealer {
1341
1652
  packet_id: string;
1342
1653
  voided: number;
1343
1654
  kept: number;
1655
+ signed: Array<{
1656
+ document_id: string;
1657
+ title: string;
1658
+ }>;
1344
1659
  }>;
1345
1660
  /**
1346
1661
  * The booking systems this business can connect, and its connections (00424).
@@ -1370,14 +1685,18 @@ export declare class SignSealer {
1370
1685
  events?: string[];
1371
1686
  label?: string;
1372
1687
  }): Promise<EnsuredWebhook>;
1688
+ /**
1689
+ * Add an endpoint. Its signing `secret` is in the first answer only: a
1690
+ * retry with the same idempotency key -- the client's own, after a
1691
+ * connection dropped, or yours -- adds nothing and answers with the same
1692
+ * `id`, `secret` null and `secrets_redacted: true` (1.26.0). Keep the
1693
+ * secret from the first answer; if it was lost, `rotateWebhookSecret`.
1694
+ */
1373
1695
  addWebhook(input: {
1374
1696
  url: string;
1375
1697
  events?: string[];
1376
1698
  label?: string;
1377
- }, idempotencyKey?: string): Promise<{
1378
- id: string;
1379
- secret: string;
1380
- }>;
1699
+ }, idempotencyKey?: string): Promise<AddedWebhook>;
1381
1700
  /**
1382
1701
  * Change an endpoint. Turning one back on forgives its failures and sends
1383
1702
  * what it held: `resumed` says it was paused, `waiting` how many are now
@@ -2038,7 +2357,7 @@ export interface Device {
2038
2357
  }
2039
2358
  export interface Captured {
2040
2359
  offline?: boolean;
2041
- /** ISO 8601. Recorded as a claim beside our own received time. */
2360
+ /** 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
2361
  at?: string;
2043
2362
  device?: string;
2044
2363
  }
@@ -2185,7 +2504,7 @@ export declare class SignSealerSigning {
2185
2504
  * the business did not ask; refused as busy, to be sent again after
2186
2505
  * `retryAfter` seconds, as `supplyPhoto` is.
2187
2506
  */
2188
- captureIdEvidence(token: string, kind: "id" | "selfie", image: {
2507
+ captureIdEvidence(token: string, kind: "id" | "id_back" | "selfie", image: {
2189
2508
  contentType: string;
2190
2509
  bytes: Uint8Array | string;
2191
2510
  }, captured?: Captured): Promise<{
@@ -2281,6 +2600,9 @@ export interface PartnerProfile {
2281
2600
  month_to_date: PartnerMonthToDate;
2282
2601
  /** The link to hand a business: signing up through it makes the business yours. */
2283
2602
  signup_url: string;
2603
+ /** 00756: the current version of SignSealer's terms, which a business you make accepts (a date), and where to show it. */
2604
+ terms_version: string;
2605
+ terms_url: string;
2284
2606
  }
2285
2607
  /** A business you brought (1.8.0). */
2286
2608
  export interface PartnerBusiness {
@@ -2321,13 +2643,189 @@ export interface PartnerStatement {
2321
2643
  revenue_cents: number;
2322
2644
  }>;
2323
2645
  }
2646
+ /** 00751: a business a partner on a Platform agreement made. */
2647
+ export interface ManagedBusiness {
2648
+ id: string;
2649
+ /** Your own id for it, or null when you gave none. */
2650
+ external_id: string | null;
2651
+ name: string;
2652
+ slug: string;
2653
+ status: string;
2654
+ created_at: string;
2655
+ /** 00761: made with a test key: nothing it does reaches anybody or is billed. */
2656
+ sandbox: boolean;
2657
+ timezone: string | null;
2658
+ /** Its address and contact details, as `account()` describes them, with what is `missing`. */
2659
+ profile: Record<string, unknown>;
2660
+ /** Its membership, paid from your balance; null if it has not started. */
2661
+ membership: "monthly" | "yearly" | null;
2662
+ /** The monthly spending limit you set for it, in cents; null for none. */
2663
+ spend_cap_cents: number | null;
2664
+ /** What your balance has drawn for it this month, in cents. */
2665
+ month_to_date_cents: number;
2666
+ /** 00756: the version of our terms it accepted, as you recorded it, and a newer one it must accept by `due.by`, if any. */
2667
+ terms: {
2668
+ version: string | null;
2669
+ accepted_at: string | null;
2670
+ due: {
2671
+ version: string;
2672
+ by: string | null;
2673
+ on_hold: boolean;
2674
+ } | null;
2675
+ };
2676
+ /** 00759: the credit you gave it, in your prices, and when what is left expires (null: never). */
2677
+ gift_credit: {
2678
+ left_cents: number;
2679
+ expires_at: string | null;
2680
+ };
2681
+ /** 00759: the prices you set for it alone, over your default; {} for none. */
2682
+ prices: PartnerPriceList;
2683
+ can_send: boolean;
2684
+ /** Why it cannot send: its address, suspended, or your balance's grace period over. */
2685
+ why_not: string | null;
2686
+ }
2687
+ /**
2688
+ * 00759: what you charge your businesses, in cents for one of our units, and
2689
+ * `markup_bp` (hundredths of a percent) on anything else. Never charged by us.
2690
+ */
2691
+ export interface PartnerPriceList {
2692
+ membership_month?: number;
2693
+ membership_year?: number;
2694
+ signing?: number;
2695
+ text?: number;
2696
+ passcode?: number;
2697
+ id_evidence?: number;
2698
+ ai?: number;
2699
+ id_check?: number;
2700
+ markup_bp?: number;
2701
+ }
2702
+ /** 00759: your price list, and what each unit is. */
2703
+ export interface PartnerPrices {
2704
+ prices: PartnerPriceList;
2705
+ units: Record<string, string>;
2706
+ }
2707
+ /** 00760: one of your webhook endpoints, copied onto every business you made (of its mode). */
2708
+ export interface PartnerWebhook {
2709
+ id: string;
2710
+ url: string;
2711
+ label: string | null;
2712
+ events: string[];
2713
+ active: boolean;
2714
+ /** `test` for one added with a test key: it hears your sandbox businesses only. */
2715
+ mode: "live" | "test";
2716
+ created_at: string;
2717
+ /** How many businesses it is copied onto, and how many of those copies paused themselves after failing. */
2718
+ businesses: number;
2719
+ paused: number;
2720
+ last_delivered_at: string | null;
2721
+ }
2722
+ /** 00760: one delivery to one of your endpoints, and the business it was for. */
2723
+ export interface PartnerWebhookDelivery {
2724
+ id: string;
2725
+ business_id: string;
2726
+ external_id: string | null;
2727
+ event: string;
2728
+ status: string;
2729
+ attempts: number;
2730
+ response_status: number | null;
2731
+ error: string | null;
2732
+ created_at: string;
2733
+ delivered_at: string | null;
2734
+ replay_of: string | null;
2735
+ }
2736
+ /** 00763: a start link to a business's embedded screens: load `url` in an iframe on your page, within `expires_in` seconds. */
2737
+ export interface PartnerEmbedSession {
2738
+ session_id: string;
2739
+ url: string;
2740
+ expires_at: string;
2741
+ expires_in: number;
2742
+ components: string[];
2743
+ business_id: string;
2744
+ }
2745
+ /** 00759: a business's gift credit after a change. */
2746
+ export interface PartnerGiftCredit {
2747
+ left_cents: number;
2748
+ expires_at: string | null;
2749
+ /** False when the idempotency key was used before: nothing changed. */
2750
+ applied: boolean;
2751
+ }
2752
+ /** 00759: a month of your businesses' use, in our prices and yours. */
2753
+ export interface PartnerUsage {
2754
+ month: string;
2755
+ businesses: Array<{
2756
+ id: string;
2757
+ external_id: string | null;
2758
+ name: string;
2759
+ items: Array<{
2760
+ item: string;
2761
+ draws: number;
2762
+ our_cents: number;
2763
+ partner_cents: number;
2764
+ }>;
2765
+ our_cents: number;
2766
+ partner_cents: number;
2767
+ gift_used_cents: number;
2768
+ /** Your prices, less the gift credit it spent: what is left for you to bill it. */
2769
+ to_bill_cents: number;
2770
+ }>;
2771
+ our_cents: number;
2772
+ partner_cents: number;
2773
+ gift_used_cents: number;
2774
+ to_bill_cents: number;
2775
+ }
2776
+ /** 00752: the prepaid balance your businesses draw on. */
2777
+ export interface PartnerBalance {
2778
+ balance_cents: number;
2779
+ /** What your businesses may spend now: the balance and the grace period's room, or, frozen, nothing more. */
2780
+ available_cents: number;
2781
+ grace_limit_cents: number;
2782
+ in_grace: boolean;
2783
+ grace_started_at: string | null;
2784
+ grace_ends_at: string | null;
2785
+ /** The grace period is over: your businesses cannot send until you add credit. */
2786
+ frozen: boolean;
2787
+ businesses: Array<{
2788
+ id: string;
2789
+ external_id: string | null;
2790
+ name: string;
2791
+ month_to_date_cents: number;
2792
+ }>;
2793
+ entries: Array<{
2794
+ at: string;
2795
+ cents: number;
2796
+ kind: "purchase" | "usage" | "grant" | "refund" | "adjustment";
2797
+ business_id: string | null;
2798
+ note: string | null;
2799
+ }>;
2800
+ }
2801
+ /** 00751: what a business is made with. */
2802
+ export interface NewManagedBusiness {
2803
+ name: string;
2804
+ /** Your own id for it. Asking again with one already made returns that business, unchanged. */
2805
+ external_id?: string;
2806
+ /** An IANA name, like America/Chicago. */
2807
+ timezone?: string;
2808
+ /** `address_line1`, `city`, `region`, `postal_code`, `country`, `office_email`, `office_phone`, `website`, `legal_name`. */
2809
+ profile?: Record<string, string | null>;
2810
+ /** The business's acceptance of SignSealer's terms, as you took it. Required. */
2811
+ terms: {
2812
+ version: string;
2813
+ accepted_at: string;
2814
+ ip?: string;
2815
+ user_agent?: string;
2816
+ };
2817
+ /** Its membership, paid from your balance: by the month (the default; the first month by the day) or the year. */
2818
+ membership?: "monthly" | "yearly";
2819
+ }
2324
2820
  export interface PartnerOptions {
2325
- /** Your OAuth client's id, `ss_client_…`. */
2326
- clientId: string;
2821
+ /** Your OAuth client's id, `ss_client_…`. With `clientSecret`; or give `partnerKey` instead. */
2822
+ clientId?: string;
2327
2823
  /** Its secret, `ss_secret_…`: the one shown once when SignSealer registered you. */
2328
- clientSecret: string;
2824
+ clientSecret?: string;
2825
+ /** 00751: a partner key from your dashboard, `ss_partner_…`, instead of the client id and secret. Needed to act for a business. */
2826
+ partnerKey?: string;
2329
2827
  baseUrl?: string;
2330
- /** Total attempts for a retryable failure, the first included. Every call here only reads. */
2828
+ /** Total attempts for a retryable failure, the first included. A write is retried only when it is safe to. */
2331
2829
  maxAttempts?: number;
2332
2830
  fetch?: typeof globalThis.fetch;
2333
2831
  }
@@ -2361,6 +2859,120 @@ export declare class SignSealerPartner {
2361
2859
  }>;
2362
2860
  /** Every closed month, newest first. */
2363
2861
  statements(): Promise<PartnerStatement[]>;
2862
+ /**
2863
+ * 00751: make a business of your own (a Platform agreement). With an
2864
+ * `external_id` it is safe to retry: one already made comes back, with
2865
+ * `existing: true`. Without one it is sent once.
2866
+ */
2867
+ createBusiness(input: NewManagedBusiness): Promise<ManagedBusiness & {
2868
+ existing: boolean;
2869
+ }>;
2870
+ /** 00751: the businesses you made, newest first, with how many your agreement allows. `limit` is 1 to 100. */
2871
+ managedBusinesses(opts?: {
2872
+ limit?: number;
2873
+ offset?: number;
2874
+ }): Promise<{
2875
+ data: ManagedBusiness[];
2876
+ has_more: boolean;
2877
+ licensed: number | null;
2878
+ carried: number;
2879
+ }>;
2880
+ /** 00752: the prepaid balance your businesses draw on, this month by business, and the latest entries. */
2881
+ balance(): Promise<PartnerBalance>;
2882
+ /** 00751: one business you made, by its id or your own `external_id`. */
2883
+ managedBusiness(id: string): Promise<ManagedBusiness>;
2884
+ /**
2885
+ * 00751: change its `name`, `timezone` or `profile`; only what you send changes. Safe to retry.
2886
+ * 00752: `status` suspends or resumes it, `membership` is month or year from its next renewal,
2887
+ * `spend_cap_cents` its monthly spending limit (null for none).
2888
+ */
2889
+ updateBusiness(id: string, changes: {
2890
+ name?: string;
2891
+ timezone?: string;
2892
+ profile?: Record<string, string | null>;
2893
+ status?: "active" | "suspended";
2894
+ membership?: "monthly" | "yearly";
2895
+ spend_cap_cents?: number | null;
2896
+ /** 00756: its acceptance of a newer version of our terms, as you took it. */
2897
+ terms?: {
2898
+ version: string;
2899
+ accepted_at: string;
2900
+ ip?: string;
2901
+ user_agent?: string;
2902
+ };
2903
+ /** 00759: your prices for it alone, over your default; null or {} takes them away. */
2904
+ prices?: PartnerPriceList | null;
2905
+ }): Promise<ManagedBusiness>;
2906
+ /** 00759: your default prices to your businesses, and what each unit is. */
2907
+ prices(): Promise<PartnerPrices>;
2908
+ /** 00759: replace your default prices; `{}` takes them all away. Safe to retry. */
2909
+ setPrices(prices: PartnerPriceList): Promise<PartnerPrices>;
2910
+ /**
2911
+ * 00759: give one of your businesses credit (`cents` above zero), or take
2912
+ * back what is left (below zero), in your prices. With an `idempotencyKey`
2913
+ * it is safe to retry; without one it is sent once.
2914
+ */
2915
+ giveCredit(id: string, gift: {
2916
+ cents: number;
2917
+ expires_at?: string | null;
2918
+ note?: string;
2919
+ idempotencyKey?: string;
2920
+ }): Promise<PartnerGiftCredit>;
2921
+ /**
2922
+ * 00760: your webhook endpoints, each hearing every business you made;
2923
+ * with a test key, your sandbox's.
2924
+ */
2925
+ webhooks(): Promise<PartnerWebhook[]>;
2926
+ /** 00760: add an endpoint for every business you made. Its signing `secret` is in this answer only. Sent once. */
2927
+ addWebhook(endpoint: {
2928
+ url: string;
2929
+ events?: string[];
2930
+ label?: string;
2931
+ }): Promise<PartnerWebhook & {
2932
+ secret: string;
2933
+ }>;
2934
+ /** 00760: change an endpoint on every business at once; `active: true` turns back on every copy that paused. */
2935
+ updateWebhook(id: string, changes: {
2936
+ url?: string;
2937
+ events?: string[];
2938
+ label?: string | null;
2939
+ active?: boolean;
2940
+ }): Promise<PartnerWebhook>;
2941
+ /** 00760: remove an endpoint from every business. */
2942
+ deleteWebhook(id: string): Promise<void>;
2943
+ /** 00760: an endpoint's latest deliveries across every business, newest first. */
2944
+ webhookDeliveries(id: string, opts?: {
2945
+ limit?: number;
2946
+ }): Promise<PartnerWebhookDelivery[]>;
2947
+ /** 00760: deliver one again. */
2948
+ replayWebhookDelivery(id: string, delivery: string): Promise<{
2949
+ id: string;
2950
+ replay_of: string;
2951
+ }>;
2952
+ /**
2953
+ * 00763: a start link to one of your businesses' screens inside your product,
2954
+ * for one of your users. It opens once, within five minutes: ask for it as
2955
+ * the page that frames it loads. Sent once. `components` are the screens:
2956
+ * `documents` (the default), `send` (00789), `templates` (00791), and
2957
+ * `settings` and `texting` (00792). Mount it with `@signsealer/embed`.
2958
+ */
2959
+ embedSession(id: string, session: {
2960
+ user: {
2961
+ external_id: string;
2962
+ name: string;
2963
+ email?: string;
2964
+ role?: "admin" | "member";
2965
+ };
2966
+ components?: Array<"documents" | "send" | "templates" | "settings" | "texting">;
2967
+ }): Promise<PartnerEmbedSession>;
2968
+ /** 00759: a calendar month (YYYY-MM, this one when left out) per business, in your prices, with what to bill. */
2969
+ usage(month?: string): Promise<PartnerUsage>;
2970
+ /**
2971
+ * 00751: a client that acts for one of your businesses -- one you made,
2972
+ * or one that connected your app -- by its id or your own `external_id`.
2973
+ * Every `SignSealer` method then works for that business. Needs a partner key.
2974
+ */
2975
+ business(id: string): SignSealer;
2364
2976
  }
2365
2977
  /** What a partner's app may ask a business for. Your client is registered with a subset; ask for no more than that. */
2366
2978
  export type OAuthScope = "signing:read" | "signing:write" | "signing:templates" | "signing:workflows" | "signing:webhooks" | "signing:subjects" | "signing:send" | "signing:remind" | "signing:links" | "signing:void";
@@ -2824,6 +3436,15 @@ export interface DocumentFromPdf {
2824
3436
  /** What was taken out of the file because it could act on its own. */
2825
3437
  removed: string[];
2826
3438
  }
3439
+ /** What `addWebhook` answers. */
3440
+ export interface AddedWebhook {
3441
+ id: string;
3442
+ /** Keep it, it is not shown again: null on a retry with the same idempotency key (1.26.0). */
3443
+ secret: string | null;
3444
+ /** On such a retry: the secret was taken out of the copy the API kept (1.26.0). */
3445
+ redacted?: true;
3446
+ secrets_redacted?: true;
3447
+ }
2827
3448
  export interface EnsuredWebhook {
2828
3449
  id: string;
2829
3450
  created: boolean;