@signsealer/sdk 1.25.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,7 +133,11 @@ 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;
136
142
  /**
137
143
  * Where a text goes (1.24.0): `US` and `CA`, and `GB` while texting UK
@@ -171,10 +177,14 @@ export interface TextingApplication {
171
177
  /** `applied`, `submitted`, `in_review`, `needs_changes`, `verified`, `paused`, `failed`, and the steps of bringing a number. */
172
178
  status: string;
173
179
  kind: TextingNumberKind;
174
- /** 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
+ */
175
185
  phone: string | null;
176
186
  area_code: string | null;
177
- /** 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). */
178
188
  reason: string | null;
179
189
  /** True for a number the business already had and is bringing. */
180
190
  brought: boolean;
@@ -220,6 +230,123 @@ export interface TextingNumberInvitation {
220
230
  fields: string[];
221
231
  expires_at: string;
222
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
+ }
223
350
  /** What `recordSmsConsent` wrote, with the number as we normalised it. */
224
351
  export interface SmsConsentRecorded {
225
352
  /** E.164. One number written three ways is one record, and this is it. */
@@ -463,6 +590,11 @@ export interface TemplateInput {
463
590
  consent_text?: string | null;
464
591
  /** Up to 50. Set here rather than in a second call — see `createTemplate`. */
465
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";
466
598
  }
467
599
  /**
468
600
  * The brand an account shows its signers (00220). SignSealer's own without
@@ -584,6 +716,52 @@ export interface TemplatePdf {
584
716
  original_name?: string | null;
585
717
  uploaded_at?: string;
586
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
+ }
587
765
  /**
588
766
  * What a reader will be told about the signer of a sealed PDF.
589
767
  *
@@ -613,7 +791,8 @@ export interface SignerLink {
613
791
  * The signing token. Returned once, and never again — only its hash is kept.
614
792
  * Null for a signer held for their turn on a document signed in order
615
793
  * (00609): their link is made and sent to them when the step before them is
616
- * signed.
794
+ * signed. Null too, with `redacted`, on the answer to a retry with the same
795
+ * idempotency key (1.26.0).
617
796
  */
618
797
  token: string | null;
619
798
  /** The page to send them to, built from the token (1.6.0); null when `token` is. */
@@ -626,6 +805,12 @@ export interface SignerLink {
626
805
  for_business?: boolean;
627
806
  /** Signed only by an approval from the application it was bound to (1.18.0, 00684); it has no link. */
628
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;
629
814
  }
630
815
  /** Who has signed one document (00340): names and states, nothing else. */
631
816
  export interface DocumentSigners {
@@ -693,6 +878,8 @@ export interface StartedWorkflow {
693
878
  signers: SignerLink[];
694
879
  /** 00541: the roles whose `show_if` these answers did not meet, by label; absent when every role signs. */
695
880
  not_needed?: string[];
881
+ /** A retry's answer whose tokens were taken out (1.26.0): see `SignerLink.redacted`. */
882
+ links_redacted?: true;
696
883
  }
697
884
  export interface PacketSummary {
698
885
  packet_id: string;
@@ -915,7 +1102,9 @@ export interface ClientOptions {
915
1102
  userAgent?: string;
916
1103
  }
917
1104
  /** 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";
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;
919
1108
  export declare class SignSealer {
920
1109
  #private;
921
1110
  /**
@@ -937,6 +1126,30 @@ export declare class SignSealer {
937
1126
  * moment somebody is deciding whether to trust the page.
938
1127
  */
939
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>;
940
1153
  /** Prove the key works, and say whose account it is. */
941
1154
  account(): Promise<Account>;
942
1155
  /** Every version of every template, newest first; `code` narrows it to one template's versions. No text: `template(id)` has that. */
@@ -965,7 +1178,13 @@ export declare class SignSealer {
965
1178
  * is wrong, for a placeholder the template does not declare or a PDF with
966
1179
  * pages nobody has drawn.
967
1180
  */
968
- 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
+ }>;
969
1188
  /**
970
1189
  * The next version of a published template, as a draft (1.6.0): the
971
1190
  * newest version copied, with whatever you change. `id` must be the
@@ -1030,10 +1249,56 @@ export declare class SignSealer {
1030
1249
  *
1031
1250
  * `ready` is the one to check: a PDF template cannot be published until
1032
1251
  * SignSealer has drawn a picture of every page from the file itself
1033
- * (00474), which it does as the file is uploaded. Uploading the file is a
1034
- * 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`.
1035
1254
  */
1036
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
+ }>;
1037
1302
  /**
1038
1303
  * Record that you have consent to text a number.
1039
1304
  *
@@ -1238,6 +1503,11 @@ export declare class SignSealer {
1238
1503
  /**
1239
1504
  * Send, and take the links back once.
1240
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
+ *
1241
1511
  * Each signer needs an `email`, a `phone`, or both; a `cc` may have neither.
1242
1512
  * Given both, the same link goes out twice — by mail and by text — because a
1243
1513
  * person who does not check one inbox checks the other. The text goes only
@@ -1273,6 +1543,7 @@ export declare class SignSealer {
1273
1543
  };
1274
1544
  }>, idempotencyKey?: string): Promise<{
1275
1545
  links: SignerLink[];
1546
+ links_redacted?: true;
1276
1547
  }>;
1277
1548
  void(documentId: string, reason: string, idempotencyKey?: string): Promise<{
1278
1549
  voided: true;
@@ -1414,14 +1685,18 @@ export declare class SignSealer {
1414
1685
  events?: string[];
1415
1686
  label?: string;
1416
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
+ */
1417
1695
  addWebhook(input: {
1418
1696
  url: string;
1419
1697
  events?: string[];
1420
1698
  label?: string;
1421
- }, idempotencyKey?: string): Promise<{
1422
- id: string;
1423
- secret: string;
1424
- }>;
1699
+ }, idempotencyKey?: string): Promise<AddedWebhook>;
1425
1700
  /**
1426
1701
  * Change an endpoint. Turning one back on forgives its failures and sends
1427
1702
  * what it held: `resumed` says it was paused, `waiting` how many are now
@@ -2677,7 +2952,9 @@ export declare class SignSealerPartner {
2677
2952
  /**
2678
2953
  * 00763: a start link to one of your businesses' screens inside your product,
2679
2954
  * for one of your users. It opens once, within five minutes: ask for it as
2680
- * the page that frames it loads. Sent once.
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`.
2681
2958
  */
2682
2959
  embedSession(id: string, session: {
2683
2960
  user: {
@@ -2686,7 +2963,7 @@ export declare class SignSealerPartner {
2686
2963
  email?: string;
2687
2964
  role?: "admin" | "member";
2688
2965
  };
2689
- components?: Array<"documents">;
2966
+ components?: Array<"documents" | "send" | "templates" | "settings" | "texting">;
2690
2967
  }): Promise<PartnerEmbedSession>;
2691
2968
  /** 00759: a calendar month (YYYY-MM, this one when left out) per business, in your prices, with what to bill. */
2692
2969
  usage(month?: string): Promise<PartnerUsage>;
@@ -3159,6 +3436,15 @@ export interface DocumentFromPdf {
3159
3436
  /** What was taken out of the file because it could act on its own. */
3160
3437
  removed: string[];
3161
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
+ }
3162
3448
  export interface EnsuredWebhook {
3163
3449
  id: string;
3164
3450
  created: boolean;