@signsealer/sdk 1.4.0 → 1.10.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.
@@ -14,6 +14,74 @@
14
14
  * - keeps the request id, so a support mail can quote something we can look
15
15
  * up.
16
16
  */
17
+ /** What `startPacket` started and what it could not (00424). */
18
+ export interface PacketStart {
19
+ packet_id: string;
20
+ started: Array<{
21
+ item_id: string;
22
+ requirement: string;
23
+ participant: string;
24
+ document_id: string;
25
+ }>;
26
+ skipped: Array<{
27
+ item_id: string;
28
+ requirement: string;
29
+ participant: string;
30
+ reason: string;
31
+ }>;
32
+ }
33
+ /** A booking system SignSealer connects to, and where it has got to (00424). */
34
+ export interface IntegrationProvider {
35
+ key: string;
36
+ label: string;
37
+ category: "vacation_rentals" | "tours_activities" | "automation" | "crm" | "storage" | "accounting";
38
+ status: "available" | "beta" | "pending_partner_access" | "planned" | "deprecated" | "disabled";
39
+ connects: "webhook" | "external_app" | "none";
40
+ auth_type: string;
41
+ verification: string;
42
+ connector_version: string;
43
+ api_version: string;
44
+ deprecates_at: string | null;
45
+ sunsets_at: string | null;
46
+ }
47
+ /** One of the business's connections. Credentials and its address are never included. */
48
+ export interface IntegrationConnection {
49
+ id: string;
50
+ provider: string;
51
+ label: string;
52
+ status: "active" | "paused" | "error" | "disconnected";
53
+ /** `membership` when it was paused because the membership ended; it resumes by itself when it starts again (00425). */
54
+ paused_reason: "membership" | null;
55
+ config: {
56
+ send: "on_booking" | "manual";
57
+ void_on_cancel: boolean;
58
+ kind: "reservation" | "activity";
59
+ };
60
+ created_at: string;
61
+ last_event_at: string | null;
62
+ last_success_at: string | null;
63
+ last_error: string | null;
64
+ last_error_at: string | null;
65
+ waiting: number;
66
+ dead: number;
67
+ }
68
+ /** One delivery from a connection, and what became of it. */
69
+ export interface IntegrationEvent {
70
+ id: string;
71
+ event_type: string;
72
+ external_ref: string;
73
+ status: "queued" | "processing" | "done" | "ignored" | "superseded" | "failed" | "dead";
74
+ attempts: number;
75
+ received_at: string;
76
+ processed_at: string | null;
77
+ next_attempt_at: string;
78
+ error: string | null;
79
+ verified_by: string;
80
+ /** What the provider's data said about consent to text. Only NO_CONSENT changes anything, and only to take a number away. */
81
+ consent_evidence: "VERIFIED_CONSENT" | "NO_CONSENT" | "INSUFFICIENT_EVIDENCE" | null;
82
+ subject_id: string | null;
83
+ result: Record<string, unknown>;
84
+ }
17
85
  export declare class SignSealerError extends Error {
18
86
  readonly status: number;
19
87
  readonly code: string;
@@ -44,6 +112,24 @@ export interface Account {
44
112
  slug: string;
45
113
  key_label: string;
46
114
  scopes: string[];
115
+ /** The sites this business's signing pages may be framed on (1.6.0); empty until it proves one. */
116
+ frame_origins?: string[];
117
+ /**
118
+ * `test` when the key is a test key (1.7.0): its account is the business's
119
+ * sandbox, where nothing is sent to anybody and nothing is billed.
120
+ */
121
+ mode?: "live" | "test";
122
+ /**
123
+ * Whether this business can text people (00458). Offer a "text me" box only
124
+ * when `available` is true, put `wording` beside it, and record exactly
125
+ * that wording with `recordSmsConsent` when it is ticked. `why_not` is
126
+ * `plan` (no texting on its plan) or `test` (a sandbox) when it cannot.
127
+ */
128
+ texting?: {
129
+ available: boolean;
130
+ why_not: "test" | "plan" | null;
131
+ wording: string;
132
+ };
47
133
  }
48
134
  /** What `recordSmsConsent` wrote, with the number as we normalised it. */
49
135
  export interface SmsConsentRecorded {
@@ -70,7 +156,99 @@ export interface Template {
70
156
  version: number;
71
157
  is_published: boolean;
72
158
  is_latest: boolean;
159
+ /** How long a signature on this template stays good, in months; null when it does not run out (00406). */
160
+ valid_months?: number | null;
161
+ /** Days before the end each signer is emailed a link to sign again (00406). */
162
+ remind_days?: number | null;
163
+ /** Signatures on versions older than this are not current: the terms changed (00406). */
164
+ resign_from_version?: number | null;
165
+ }
166
+ /**
167
+ * One template version, whole (1.6.0): its text, what it asks, the settings
168
+ * its code carries, and every version of the code beside it.
169
+ */
170
+ export interface TemplateDetail extends Template {
171
+ published_at: string | null;
172
+ created_at: string;
173
+ body: string;
174
+ body_format: "text" | "markdown";
175
+ variables: string[];
176
+ grants: Record<string, unknown>;
177
+ consent_text: string | null;
178
+ fields: Ask[];
179
+ has_pdf: boolean;
180
+ documents: number;
181
+ /** Per code, not per version: they carry over to every version after. */
182
+ settings: TemplateSettings;
183
+ /** What changed in this version (1.7.0), written while it was a draft and frozen when it was published. */
184
+ change_note?: string | null;
185
+ /** Every version of this code, newest first. A published version is never changed or removed. */
186
+ versions: Array<{
187
+ template_id: string;
188
+ version: number;
189
+ is_published: boolean;
190
+ published_at: string | null;
191
+ name?: string;
192
+ created_at?: string;
193
+ change_note?: string | null;
194
+ has_pdf?: boolean;
195
+ documents?: number;
196
+ }>;
197
+ }
198
+ export interface TemplateSettings {
199
+ /** Made to send once rather than reused. */
200
+ one_time: boolean;
201
+ /** The business's address printed under it. */
202
+ show_address: boolean;
203
+ /** The photographs a signer takes as answers are printed after the certificate in the signed PDF (1.10.0). */
204
+ photos_in_copy: boolean;
205
+ /** How long a signature stays good, in months; null when it does not run out. */
206
+ valid_months: number | null;
207
+ /** Days before the end each signer is sent a link to sign again. */
208
+ remind_days: number | null;
209
+ /** Signatures on versions older than this must be made again. */
210
+ resign_from_version: number | null;
73
211
  }
212
+ /** A fresh signing link to put in a frame (1.6.0). */
213
+ export interface EmbedLink {
214
+ document_id: string;
215
+ signer_id: string;
216
+ url: string;
217
+ /** The sites the page may be framed on. Anywhere else the browser refuses it; empty means nowhere yet. */
218
+ frame_origins: string[];
219
+ expires_at: string | null;
220
+ }
221
+ /**
222
+ * What the signing page tells the page framing it, by `postMessage` (1.6.0).
223
+ * `ready` on every page, with its height; `signed` and `declined` once.
224
+ */
225
+ export interface EmbedEvent {
226
+ source: "signsealer";
227
+ event: "ready" | "signed" | "declined";
228
+ document_id: string | null;
229
+ signer_id: string | null;
230
+ height: number;
231
+ }
232
+ /**
233
+ * Whether a signed document is still good (00406): `current`, `expired`,
234
+ * `resign` (signed on a version the business has since asked everybody to
235
+ * sign again), `renewed` (the same person has signed the template since) or
236
+ * `on_file` (the template has no period).
237
+ */
238
+ export type Standing = "current" | "expired" | "resign" | "renewed" | "on_file";
239
+ /** What `standing` answers: a person's newest signature on one template (00406). */
240
+ export type PersonStanding = {
241
+ template: string;
242
+ found: false;
243
+ } | {
244
+ template: string;
245
+ found: true;
246
+ document_id: string;
247
+ signed_at: string;
248
+ template_version: number;
249
+ standing: Standing;
250
+ valid_until: string | null;
251
+ };
74
252
  /** One question a template asks besides a signature. */
75
253
  export interface Ask {
76
254
  /** Lower-case, letters then letters/digits/underscore, up to 59 characters. */
@@ -223,8 +401,12 @@ export interface SignerLink {
223
401
  full_name?: string;
224
402
  role?: string;
225
403
  participant?: boolean;
226
- /** The signing URL. Returned once, and never again — only its hash is kept. */
404
+ /** The signing token. Returned once, and never again — only its hash is kept. */
227
405
  token: string;
406
+ /** The page to send them to, built from the token (1.6.0). */
407
+ url?: string;
408
+ /** `embedded`: nothing was sent to them; show them `url` yourself (1.6.0). */
409
+ delivery?: "send" | "embedded";
228
410
  }
229
411
  /** Who has signed one document (00340): names and states, nothing else. */
230
412
  export interface DocumentSigners {
@@ -233,6 +415,9 @@ export interface DocumentSigners {
233
415
  status: string;
234
416
  sent_at: string | null;
235
417
  completed_at: string | null;
418
+ /** Whether it is still good once signed, and until when (00406). */
419
+ standing?: Standing | null;
420
+ valid_until?: string | null;
236
421
  signers: Array<{
237
422
  signer_id: string;
238
423
  full_name: string;
@@ -242,6 +427,13 @@ export interface DocumentSigners {
242
427
  signed_at: string | null;
243
428
  declined_at: string | null;
244
429
  }>;
430
+ /**
431
+ * Whether you may mint a fresh link for it with `gateLink` (00409). Always
432
+ * true for a key; for a paired tablet, only on a document it or its form
433
+ * started, unless the business let that tablet show links for every open
434
+ * document (`setDevice(id, { gate: "account" })`).
435
+ */
436
+ link_allowed?: boolean;
245
437
  }
246
438
  /** A fresh signing link for a signer who has not signed, with a QR code to hold up (00340). */
247
439
  export interface GateLink {
@@ -309,6 +501,11 @@ export interface DocumentRow {
309
501
  waiting_on: string | null;
310
502
  sent_at: string | null;
311
503
  completed_at: string | null;
504
+ /** Whether it is still good once signed, and until when (00406). */
505
+ standing?: Standing | null;
506
+ valid_until?: string | null;
507
+ /** Your own reference, when you gave one (1.6.0). */
508
+ external_ref?: string | null;
312
509
  }
313
510
  /** What `document` answers. The trail and the signers are as the API documents them. */
314
511
  export interface DocumentDetail {
@@ -326,6 +523,10 @@ export interface DocumentDetail {
326
523
  void_reason: string | null;
327
524
  integrity_ok: boolean | null;
328
525
  redacted_at?: string | null;
526
+ /** Whether it is still good, until when, and the newer signing that replaced it (00406). */
527
+ standing?: Standing | null;
528
+ valid_until?: string | null;
529
+ renewed_by?: string | null;
329
530
  signers: Array<Record<string, unknown>>;
330
531
  events: Array<Record<string, unknown>>;
331
532
  /** Every question, in the form's order, with the signer it belongs to (00395). */
@@ -333,6 +534,10 @@ export interface DocumentDetail {
333
534
  /** How many answers want a person to read them. */
334
535
  flagged: number;
335
536
  [key: string]: unknown;
537
+ /** What you set when you made it (1.6.0). */
538
+ external_ref?: string | null;
539
+ metadata?: Record<string, string>;
540
+ return_url?: string | null;
336
541
  }
337
542
  /**
338
543
  * One answer on a document (00395).
@@ -419,7 +624,76 @@ export declare class SignSealer {
419
624
  */
420
625
  branding(): Promise<Branding>;
421
626
  account(): Promise<Account>;
422
- templates(): Promise<Template[]>;
627
+ /** Every version of every template, newest first; `code` narrows it to one template's versions. No text: `template(id)` has that. */
628
+ templates(filter?: {
629
+ code?: string;
630
+ }): Promise<Template[]>;
631
+ /** One template version, whole: text, questions, settings, and every version of its code (1.6.0). */
632
+ template(id: string): Promise<TemplateDetail>;
633
+ /**
634
+ * Change a draft (1.6.0). `fields`, when given, replaces the whole list.
635
+ * A published version refuses: what people signed does not change, so
636
+ * make the next version with `reviseTemplate`.
637
+ */
638
+ editTemplate(id: string, input: {
639
+ name?: string;
640
+ body?: string;
641
+ body_format?: "text" | "markdown";
642
+ variables?: string[];
643
+ fields?: Ask[];
644
+ /** What changed in this draft (1.7.0); null clears it. */
645
+ change_note?: string | null;
646
+ }): Promise<TemplateDetail>;
647
+ /**
648
+ * Publish a draft (1.6.0): from now on documents made from its code use
649
+ * this version, and its text can no longer change. Refused, naming what
650
+ * is wrong, for a placeholder the template does not declare or a PDF with
651
+ * pages nobody has drawn.
652
+ */
653
+ publishTemplate(id: string, idempotencyKey?: string): Promise<TemplateDetail>;
654
+ /**
655
+ * The next version of a published template, as a draft (1.6.0): the
656
+ * newest version copied, with whatever you change. `id` must be the
657
+ * newest version; an older one answers 409 naming the newest. Documents
658
+ * already sent keep the version they were sent on.
659
+ */
660
+ reviseTemplate(id: string, input?: {
661
+ name?: string;
662
+ body?: string;
663
+ variables?: string[];
664
+ fields?: Ask[];
665
+ /** What changed (1.7.0), kept in the template's history. */
666
+ change_note?: string;
667
+ }, idempotencyKey?: string): Promise<TemplateDetail>;
668
+ /**
669
+ * An older published version back as a new draft at the top (1.7.0): its
670
+ * text, questions, consent wording and file. Its `change_note` says
671
+ * "Restored from version N", and yours after it. Refused for the newest
672
+ * version, a draft, and while the template has an open draft.
673
+ */
674
+ restoreTemplate(id: string, input?: {
675
+ change_note?: string;
676
+ }, idempotencyKey?: string): Promise<TemplateDetail>;
677
+ /** Throw away a draft nothing was made from (1.6.0). A published version is never discarded. */
678
+ discardTemplate(id: string): Promise<{
679
+ template_id: string;
680
+ code: string;
681
+ version: number;
682
+ discarded: true;
683
+ }>;
684
+ /**
685
+ * The settings a template's code carries to every version (1.6.0).
686
+ * `resign: true` asks everybody who signed an older version to sign the
687
+ * newest published one; `valid_months: null` clears the period.
688
+ */
689
+ setTemplateSettings(id: string, input: {
690
+ one_time?: boolean;
691
+ show_address?: boolean;
692
+ photos_in_copy?: boolean;
693
+ valid_months?: number | null;
694
+ remind_days?: number | null;
695
+ resign?: boolean;
696
+ }): Promise<TemplateDetail>;
423
697
  /**
424
698
  * Whether a template is an uploaded PDF, and whether it is usable yet.
425
699
  *
@@ -432,9 +706,9 @@ export declare class SignSealer {
432
706
  * Create a template. Version 1, as a draft.
433
707
  *
434
708
  * A template is not usable until it is published, and publishing is what
435
- * freezes the text people will have signed — so this is deliberately the
436
- * *draft* door and there is no `publish` beside it. Publishing is a
437
- * decision somebody makes looking at the words, in the dashboard.
709
+ * freezes the text people will have signed. Publish it with
710
+ * `publishTemplate` once the words are right -- in the dashboard, or from
711
+ * here when your own software is where the words are decided (1.6.0).
438
712
  *
439
713
  * `fields` says what the document asks for besides a signature, and is
440
714
  * set in the same call rather than in a second one: a template that
@@ -495,9 +769,14 @@ export declare class SignSealer {
495
769
  q?: string;
496
770
  limit?: number;
497
771
  offset?: number;
772
+ /** Your own reference, exactly as you gave it (1.6.0). */
773
+ external_ref?: string;
498
774
  }): Promise<{
499
775
  documents: DocumentRow[];
500
776
  total: number;
777
+ has_more: boolean;
778
+ limit: number;
779
+ offset: number;
501
780
  }>;
502
781
  /**
503
782
  * One document: its text, its signers, the whole trail, and every answer
@@ -512,6 +791,16 @@ export declare class SignSealer {
512
791
  * attendant asks; the route a paired tablet may read.
513
792
  */
514
793
  documentSigners(id: string): Promise<DocumentSigners>;
794
+ /**
795
+ * Does this person have a current signature on this template (00406)? By
796
+ * the template's code and the person's email or phone. `found: false` is
797
+ * "send them the form", not an error.
798
+ */
799
+ standing(who: {
800
+ template: string;
801
+ email?: string;
802
+ phone?: string;
803
+ }): Promise<PersonStanding>;
515
804
  /**
516
805
  * A fresh signing link for a signer who has not signed, as a QR code to
517
806
  * hold up (00340). The link they were sent stops working; the trail says
@@ -519,12 +808,36 @@ export declare class SignSealer {
519
808
  * declined, a copied recipient, or a document that is not open.
520
809
  */
521
810
  gateLink(documentId: string, signerId: string): Promise<GateLink>;
811
+ /**
812
+ * Send one signer a reminder with a fresh link (1.6.0); the one they had
813
+ * stops working. Refused inside an hour of their last reminder, and for
814
+ * somebody there is no way to reach -- with their link left as it was.
815
+ */
816
+ remind(documentId: string, signerId: string, idempotencyKey?: string): Promise<{
817
+ document_id: string;
818
+ signer_id: string;
819
+ reminded: true;
820
+ by: "email" | "sms";
821
+ }>;
822
+ /**
823
+ * A fresh signing link to put in an `<iframe>` (1.6.0), with the sites it
824
+ * may be framed on. Call it when the page is about to be shown rather than
825
+ * keeping a link; the one the signer had stops working. Inside the frame
826
+ * the page posts an `EmbedEvent` to its parent.
827
+ */
828
+ embedLink(documentId: string, signerId: string): Promise<EmbedLink>;
522
829
  prepareDocument(input: {
523
830
  template_code: string;
524
831
  title?: string;
525
832
  values?: Record<string, string>;
526
833
  expires_at?: string | null;
527
834
  sequential?: boolean;
835
+ /** Your own reference; every webhook about it carries it back as `document.metadata.external_ref` (1.6.0). */
836
+ external_ref?: string;
837
+ /** Up to 20 names of your own with text values; back as `document.metadata.custom` (1.6.0). */
838
+ metadata?: Record<string, string>;
839
+ /** Where the signed page offers to take them: https, on a host the business has proven (1.6.0). */
840
+ return_url?: string;
528
841
  }, idempotencyKey?: string): Promise<{
529
842
  document_id: string;
530
843
  }>;
@@ -544,6 +857,9 @@ export declare class SignSealer {
544
857
  full_name: string;
545
858
  role?: "signer" | "approver" | "witness" | "cc";
546
859
  sign_order?: number;
860
+ party_id?: string | null;
861
+ /** `embedded`: nothing is sent to them; you show them the page yourself (1.6.0). */
862
+ delivery?: "send" | "embedded";
547
863
  }>, idempotencyKey?: string): Promise<{
548
864
  links: SignerLink[];
549
865
  }>;
@@ -601,7 +917,7 @@ export declare class SignSealer {
601
917
  external_ref?: string;
602
918
  /** The template version the form was rendered from, for a start run with no network; 409 `template_changed` if it moved on. */
603
919
  expected_template_version?: number;
604
- /** The device's own clock and name, kept as a claim with the skew computed. */
920
+ /** The device's own clock and name, kept as a claim with the skew computed. A paired tablet only (422 from any other key). */
605
921
  captured?: {
606
922
  offline: boolean;
607
923
  at: string;
@@ -640,6 +956,34 @@ export declare class SignSealer {
640
956
  */
641
957
  packetByCode(code: string): Promise<PacketLookup>;
642
958
  startPacketItem(itemId: string, idempotencyKey?: string): Promise<StartedWorkflow>;
959
+ /**
960
+ * Start everything a packet still owes (00424). Items already started are
961
+ * left alone, so this is safe to call on every booking update; an item
962
+ * that cannot be started comes back under `skipped` with the reason.
963
+ */
964
+ startPacket(packetId: string): Promise<PacketStart>;
965
+ /**
966
+ * Void a packet because the booking was cancelled (00424): what nobody has
967
+ * finished is voided with the reason, what somebody signed is kept.
968
+ */
969
+ voidPacket(packetId: string, reason: string): Promise<{
970
+ packet_id: string;
971
+ voided: number;
972
+ kept: number;
973
+ }>;
974
+ /**
975
+ * The booking systems this business can connect, and its connections (00424).
976
+ * `needs_membership` is true on Free: connecting one comes with the membership (00425).
977
+ */
978
+ integrations(): Promise<{
979
+ providers: IntegrationProvider[];
980
+ connections: IntegrationConnection[];
981
+ needs_membership: boolean;
982
+ }>;
983
+ /** What arrived from one connection and what became of it, newest first. */
984
+ integrationEvents(connectionId: string): Promise<{
985
+ events: IntegrationEvent[];
986
+ }>;
643
987
  webhooks(): Promise<{
644
988
  endpoints: unknown;
645
989
  }>;
@@ -741,6 +1085,9 @@ export declare class SignSealer {
741
1085
  setDevice(id: string, input: {
742
1086
  name?: string;
743
1087
  workflow_id?: string | null;
1088
+ hand_off?: "walk_up" | "same_device" | "separate";
1089
+ /** `own` (the default) or `account`: a link a tablet shows is one whoever holds it could open. */
1090
+ gate?: "own" | "account";
744
1091
  }): Promise<{
745
1092
  updated: true;
746
1093
  }>;
@@ -890,7 +1237,7 @@ export interface SigningLink {
890
1237
  export interface SigningField {
891
1238
  key: string;
892
1239
  label: string;
893
- /** `text`, `paragraph`, `email`, `phone`, `address`, `number`, `date`, `birthdate`, `choice`, `checkbox`, `initials`, `signature`, `photo`. */
1240
+ /** `text`, `paragraph`, `email`, `phone`, `address`, `number`, `date`, `birthdate`, `time` (`HH:MM`), `datetime` (`YYYY-MM-DDTHH:MM`), `choice`, `checkbox`, `initials`, `signature`, `photo`. */
894
1241
  kind: string;
895
1242
  required: boolean;
896
1243
  about: string | null;
@@ -922,6 +1269,34 @@ export interface SigningField {
922
1269
  * `supplied` says an answer was given. Absent from a server before it.
923
1270
  */
924
1271
  passed?: boolean;
1272
+ /**
1273
+ * 00427: a box on the page that signing fills in -- `signature` for a
1274
+ * signature box, `date` for the box that carries the day it was signed.
1275
+ * Draw it; do not ask for it. Null for a question that is asked.
1276
+ */
1277
+ at_signing?: "signature" | "date" | null;
1278
+ /**
1279
+ * 00427: what a box on the page carries, so a page can show the document
1280
+ * the way it will be sealed: the answer given, or for a date box filled at
1281
+ * signing, the day it would be today. Null for a sensitive answer and for
1282
+ * a question asked underneath the document.
1283
+ */
1284
+ placed_value?: string | null;
1285
+ /**
1286
+ * 00438: the words a box on the page shows for `placed_value` -- a date or
1287
+ * a time as a person writes it ("September 27, 2026 at 2:30 pm"), anything
1288
+ * else as given. `placed_value` stays the answer itself, which is what an
1289
+ * input box is filled with. Null where `placed_value` is; absent from a
1290
+ * server before it.
1291
+ */
1292
+ placed_words?: string | null;
1293
+ /**
1294
+ * 00437: a box on the page filled in by whoever sent the document (a
1295
+ * `staff` question placed on an uploaded PDF, given under `values` when it
1296
+ * was sent). Already answered: show `placed_value`, never ask for it --
1297
+ * supplying it is refused. Absent from a server before it.
1298
+ */
1299
+ from_sender?: boolean;
925
1300
  }
926
1301
  /** A set of questions asked as one thing, under one heading. */
927
1302
  export interface FieldBlock {
@@ -1084,6 +1459,10 @@ export interface Device {
1084
1459
  pairing_open: boolean;
1085
1460
  pair_expires_at: string | null;
1086
1461
  review?: boolean;
1462
+ /** How the tablet is handed a customer (00343). */
1463
+ hand_off?: "walk_up" | "same_device" | "separate";
1464
+ /** Whose documents its Gate screen may show a signing link for (00409): its own and its form's, or every open one. */
1465
+ gate?: "own" | "account";
1087
1466
  }
1088
1467
  export interface Captured {
1089
1468
  offline?: boolean;
@@ -1239,6 +1618,125 @@ export declare class SignSealerSigning {
1239
1618
  */
1240
1619
  verify(code: string, documentSha256?: string): Promise<Record<string, unknown>>;
1241
1620
  }
1621
+ /** This month so far, computed the way it will close (1.8.0). */
1622
+ export interface PartnerMonthToDate {
1623
+ /** The first day of the month, `YYYY-MM-DD`. */
1624
+ month: string;
1625
+ businesses: number;
1626
+ /** What the businesses you brought paid for and used this month, in cents. */
1627
+ gross_cents: number;
1628
+ /** The card fees on that, and the carrier's cost of their texts: both come off before the share. */
1629
+ fees_cents: number;
1630
+ sms_cost_cents: number;
1631
+ /** What is left, which is what the share is of. */
1632
+ revenue_cents: number;
1633
+ share_bp: number;
1634
+ share_cents: number;
1635
+ }
1636
+ /** Your programme (1.8.0). */
1637
+ export interface PartnerProfile {
1638
+ partner: string;
1639
+ client_id: string;
1640
+ referral_code: string;
1641
+ /** A percentage: 12.5 means 12.5%. */
1642
+ share_percent: number;
1643
+ /** False when the programme is paused: businesses already yours stay yours, new ones are not attributed. */
1644
+ active: boolean;
1645
+ /** Your name, colours and logo on your businesses' signing pages: free, set up from your partner dashboard. */
1646
+ custom_branding: boolean;
1647
+ /**
1648
+ * Where the review of your partner account stands. `pending` until a person at SignSealer approves it:
1649
+ * businesses are recorded as yours meanwhile, and nothing accrues until then.
1650
+ */
1651
+ review?: "pending" | "approved" | "declined";
1652
+ /** True once your account is approved; your share is counted from `earning_since`. */
1653
+ earning?: boolean;
1654
+ earning_since?: string | null;
1655
+ businesses: number;
1656
+ month_to_date: PartnerMonthToDate;
1657
+ /** The link to hand a business: signing up through it makes the business yours. */
1658
+ signup_url: string;
1659
+ }
1660
+ /** A business you brought (1.8.0). */
1661
+ export interface PartnerBusiness {
1662
+ tenant_id: string;
1663
+ name: string;
1664
+ status: string;
1665
+ /** How it came to you: your signup link, installing your app in its first thirty days, your promotion code, or SignSealer setting it. */
1666
+ source: "referral_link" | "oauth_install" | "promotion" | "ops";
1667
+ attributed_at: string;
1668
+ /** What it has added this month after card fees and texts' cost, in cents. Credit SignSealer gave away earns nothing. */
1669
+ month_to_date_cents: number;
1670
+ }
1671
+ /** One closed month (1.8.0). Written once, when the month is over; only `paid` changes after. */
1672
+ export interface PartnerStatement {
1673
+ /** `YYYY-MM`. */
1674
+ month: string;
1675
+ businesses: number;
1676
+ /** What the businesses paid for and used, the card fees and the carrier's cost of texts, and what was left. */
1677
+ gross_cents: number;
1678
+ fees_cents: number;
1679
+ sms_cost_cents: number;
1680
+ revenue_cents: number;
1681
+ share_percent: number;
1682
+ share_cents: number;
1683
+ /** A shortfall from an earlier month, zero or negative. */
1684
+ carried_in_cents: number;
1685
+ payable_cents: number;
1686
+ /** A shortfall carried into the next month, zero or negative. */
1687
+ carried_out_cents: number;
1688
+ paid: boolean;
1689
+ paid_at: string | null;
1690
+ lines: Array<{
1691
+ tenant_id: string;
1692
+ name: string;
1693
+ gross_cents: number;
1694
+ fees_cents: number;
1695
+ sms_cost_cents: number;
1696
+ revenue_cents: number;
1697
+ }>;
1698
+ }
1699
+ export interface PartnerOptions {
1700
+ /** Your OAuth client's id, `ss_client_…`. */
1701
+ clientId: string;
1702
+ /** Its secret, `ss_secret_…`: the one shown once when SignSealer registered you. */
1703
+ clientSecret: string;
1704
+ baseUrl?: string;
1705
+ /** Total attempts for a retryable failure, the first included. Every call here only reads. */
1706
+ maxAttempts?: number;
1707
+ fetch?: typeof globalThis.fetch;
1708
+ }
1709
+ /**
1710
+ * A partner reading its own revenue share (1.8.0): the businesses it brought,
1711
+ * what they have paid this month, and every closed month's statement.
1712
+ *
1713
+ * Authenticated with the partner's OAuth client id and secret, by HTTP Basic
1714
+ * -- never with a business's API key or access token, which act as one
1715
+ * business. Only a partner SignSealer has enrolled can use it, and it only
1716
+ * reads: the share and the programme are set by SignSealer, from the signed
1717
+ * agreement. Keep the secret on a server.
1718
+ */
1719
+ export declare class SignSealerPartner {
1720
+ #private;
1721
+ constructor(opts: PartnerOptions);
1722
+ /**
1723
+ * The link to hand a business, from your referral code, without a call.
1724
+ * `profile().signup_url` is the same link.
1725
+ */
1726
+ static signupUrl(referralCode: string, appOrigin?: string): string;
1727
+ /** Your programme, this month so far, and your signup link. */
1728
+ profile(): Promise<PartnerProfile>;
1729
+ /** The businesses you brought, newest first. `limit` is 1 to 200, 50 when left out. */
1730
+ businesses(opts?: {
1731
+ limit?: number;
1732
+ offset?: number;
1733
+ }): Promise<{
1734
+ data: PartnerBusiness[];
1735
+ has_more: boolean;
1736
+ }>;
1737
+ /** Every closed month, newest first. */
1738
+ statements(): Promise<PartnerStatement[]>;
1739
+ }
1242
1740
  export declare const WEBHOOK_EVENT_HEADER = "signsealer-event-id";
1243
1741
  export declare const WEBHOOK_TIMESTAMP_HEADER = "signsealer-timestamp";
1244
1742
  export declare const WEBHOOK_SIGNATURE_HEADER = "signsealer-signature";