@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.
- package/CHANGELOG.md +158 -0
- package/README.md +36 -8
- package/dist/cjs/index.cjs +305 -12
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +642 -21
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/index.js +304 -11
- package/dist/esm/index.js.map +1 -1
- package/package.json +10 -6
package/dist/esm/index.js
CHANGED
|
@@ -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
|
|
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
|
*
|
|
@@ -50,6 +52,37 @@ export class SignSealerError extends Error {
|
|
|
50
52
|
return this.status === 402 || this.code === "quota_exceeded";
|
|
51
53
|
}
|
|
52
54
|
}
|
|
55
|
+
/** This package's version, as `package.json` has it; `tests/sdk.ts` holds the two together. */
|
|
56
|
+
export const SDK_VERSION = "1.26.0";
|
|
57
|
+
/** The `User-Agent` header for a server-side client, or none in a browser or when switched off. */
|
|
58
|
+
function agentHeader(given) {
|
|
59
|
+
if (typeof globalThis.window !== "undefined")
|
|
60
|
+
return {};
|
|
61
|
+
const agent = given === undefined ? `signsealer-sdk/${SDK_VERSION} (node)` : given.trim();
|
|
62
|
+
return agent ? { "user-agent": agent.slice(0, 200) } : {};
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Whether this is a web page (1.26.0): a `window` and a `document`, and none
|
|
66
|
+
* of the server-like runtimes that can have them too -- jsdom in a Node test,
|
|
67
|
+
* Electron, Deno, Bun. Workers and edge runtimes have no `document`.
|
|
68
|
+
*
|
|
69
|
+
* This library's secret keys (an API key, a partner key, a partner's client
|
|
70
|
+
* secret) act for a business, and anybody who opens a page can read whatever
|
|
71
|
+
* the page holds. What takes no such key is still fine in a page and the
|
|
72
|
+
* guard is not about it: `SignSealerSigning` (a signer's link, and at most a
|
|
73
|
+
* paired tablet's own credential), a `SignSealer` with no key (`pairDevice`),
|
|
74
|
+
* `SignaturePad` and `verifyWebhook`.
|
|
75
|
+
*/
|
|
76
|
+
function inWebPage() {
|
|
77
|
+
const g = globalThis;
|
|
78
|
+
if (typeof g.window === "undefined" || typeof g.document === "undefined")
|
|
79
|
+
return false;
|
|
80
|
+
const v = g.process?.versions;
|
|
81
|
+
return typeof v?.node !== "string" && typeof v?.electron !== "string" && typeof g.Deno === "undefined" && typeof g.Bun === "undefined";
|
|
82
|
+
}
|
|
83
|
+
/** What a client built with a secret key in a web page throws (1.26.0). */
|
|
84
|
+
export const KEY_IN_PAGE_MESSAGE = "This is SignSealer's server library and you gave it a secret key in a web page. "
|
|
85
|
+
+ "Keep the key on your server; to show SignSealer's screens in a page, use @signsealer/embed.";
|
|
53
86
|
/* ------------------------------------------------------------------ client */
|
|
54
87
|
/**
|
|
55
88
|
* Strip trailing slashes without a regular expression.
|
|
@@ -70,10 +103,12 @@ function withoutTrailingSlashes(url) {
|
|
|
70
103
|
}
|
|
71
104
|
export class SignSealer {
|
|
72
105
|
#key;
|
|
106
|
+
#business;
|
|
73
107
|
#base;
|
|
74
108
|
#attempts;
|
|
75
109
|
#maxWaitMs;
|
|
76
110
|
#fetch;
|
|
111
|
+
#agent;
|
|
77
112
|
/**
|
|
78
113
|
* Agreements left in this billing period, as of the last call that said
|
|
79
114
|
* (00271), or null on a plan that counts nothing down.
|
|
@@ -84,14 +119,25 @@ export class SignSealer {
|
|
|
84
119
|
*/
|
|
85
120
|
agreementsRemaining = null;
|
|
86
121
|
constructor(opts = {}) {
|
|
87
|
-
if (opts.apiKey
|
|
122
|
+
if (opts.apiKey && inWebPage())
|
|
123
|
+
throw new Error(KEY_IN_PAGE_MESSAGE);
|
|
124
|
+
const partnerKey = opts.apiKey?.startsWith("ss_partner_") ?? false;
|
|
125
|
+
if (opts.apiKey !== undefined && !opts.apiKey.startsWith("mk_") && !partnerKey) {
|
|
88
126
|
throw new Error("a SignSealer API key looks like mk_live_… or mk_test_…");
|
|
89
127
|
}
|
|
128
|
+
if (partnerKey && !opts.business?.trim()) {
|
|
129
|
+
throw new Error("a partner key acts for one of your businesses: name it with `business`");
|
|
130
|
+
}
|
|
131
|
+
if (opts.business !== undefined && !partnerKey) {
|
|
132
|
+
throw new Error("`business` is for a partner key (ss_partner_…); a business's own key already names its business");
|
|
133
|
+
}
|
|
90
134
|
this.#key = opts.apiKey ?? "";
|
|
135
|
+
this.#business = opts.business?.trim() ?? "";
|
|
91
136
|
this.#base = withoutTrailingSlashes(opts.baseUrl ?? "https://api.signsealer.com");
|
|
92
137
|
this.#attempts = Math.max(1, opts.maxAttempts ?? 3);
|
|
93
138
|
this.#maxWaitMs = Math.max(0, opts.maxWaitMs ?? 5_000);
|
|
94
139
|
this.#fetch = opts.fetch ?? globalThis.fetch;
|
|
140
|
+
this.#agent = agentHeader(opts.userAgent);
|
|
95
141
|
}
|
|
96
142
|
/* ------------------------------------------------------------- account */
|
|
97
143
|
/**
|
|
@@ -105,6 +151,38 @@ export class SignSealer {
|
|
|
105
151
|
branding() {
|
|
106
152
|
return this.#call("GET", "/v1/branding");
|
|
107
153
|
}
|
|
154
|
+
/**
|
|
155
|
+
* The business's brand, how its signing links go, and its reminders
|
|
156
|
+
* (00792). `editable` says whether this key may change them: true only for
|
|
157
|
+
* a partner acting for a business it manages.
|
|
158
|
+
*/
|
|
159
|
+
settings() {
|
|
160
|
+
return this.#call("GET", "/v1/settings");
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* Set a managed business's brand, delivery and reminders, as its partner
|
|
164
|
+
* (00792; with `partner.business(id)`). Only what is named changes; null
|
|
165
|
+
* clears it. Any other key is refused with 403: a business that owns its
|
|
166
|
+
* account sets these in its dashboard. A PATCH of the same values, so a
|
|
167
|
+
* retry after a lost answer sets the same thing again.
|
|
168
|
+
*/
|
|
169
|
+
updateSettings(changes) {
|
|
170
|
+
return this.#call("PATCH", "/v1/settings", changes);
|
|
171
|
+
}
|
|
172
|
+
/**
|
|
173
|
+
* Apply for a managed business's texting number, as its partner (00792;
|
|
174
|
+
* with `partner.business(id)`), for a toll-free or a local number. Checked
|
|
175
|
+
* as the carriers would check it; a local number's setup is drawn from
|
|
176
|
+
* your balance now. Sent once, never retried: a second answer would file
|
|
177
|
+
* the application again.
|
|
178
|
+
*/
|
|
179
|
+
applyForTextingNumber(application) {
|
|
180
|
+
return this.#call("POST", "/v1/texting/number", application, undefined, { once: true });
|
|
181
|
+
}
|
|
182
|
+
/** The business's own texting number, its application's steps, and the carriers' wording (00792). */
|
|
183
|
+
textingNumber() {
|
|
184
|
+
return this.#call("GET", "/v1/texting/number");
|
|
185
|
+
}
|
|
108
186
|
/** Prove the key works, and say whose account it is. */
|
|
109
187
|
account() {
|
|
110
188
|
return this.#call("GET", "/v1/account");
|
|
@@ -187,12 +265,55 @@ export class SignSealer {
|
|
|
187
265
|
*
|
|
188
266
|
* `ready` is the one to check: a PDF template cannot be published until
|
|
189
267
|
* SignSealer has drawn a picture of every page from the file itself
|
|
190
|
-
* (00474), which it does as the file is uploaded
|
|
191
|
-
*
|
|
268
|
+
* (00474), which it does as the file is uploaded, in the dashboard or with
|
|
269
|
+
* `createPdfTemplate`.
|
|
192
270
|
*/
|
|
193
271
|
templatePdf(id) {
|
|
194
272
|
return this.#call("GET", `/v1/templates/${encodeURIComponent(id)}/pdf`);
|
|
195
273
|
}
|
|
274
|
+
/**
|
|
275
|
+
* A PDF template, as a draft, from the file (1.26.0): what the dashboard's
|
|
276
|
+
* upload makes. The file is read, sanitised and drawn exactly as an upload
|
|
277
|
+
* is -- up to 12 MB and 60 pages, refused in the dashboard's words past
|
|
278
|
+
* either, or when it is not a PDF or is password-protected -- and the
|
|
279
|
+
* signature and date every PDF starts with are put where the file asks for
|
|
280
|
+
* them, with initials, a printed name and a fillable form's questions each
|
|
281
|
+
* on its box. Check them with `templateFields`, move them with
|
|
282
|
+
* `setTemplateFields`, then `publishTemplate`. `pdf` is the file's bytes
|
|
283
|
+
* or its base64. Needs `signing:templates`.
|
|
284
|
+
*/
|
|
285
|
+
createPdfTemplate(input, idempotencyKey) {
|
|
286
|
+
const { pdf, filename, ...rest } = input;
|
|
287
|
+
const content_base64 = typeof pdf === "string" ? pdf : bytesToBase64(pdf);
|
|
288
|
+
return this.#call("POST", "/v1/templates/pdf", { ...rest, pdf: { filename, content_base64 } }, idempotencyKey);
|
|
289
|
+
}
|
|
290
|
+
/**
|
|
291
|
+
* The questions and boxes a template asks for (1.26.0), with a PDF's pages
|
|
292
|
+
* and the address of each page's picture, for a screen to draw them on.
|
|
293
|
+
*/
|
|
294
|
+
templateFields(id) {
|
|
295
|
+
return this.#call("GET", `/v1/templates/${encodeURIComponent(id)}/fields`);
|
|
296
|
+
}
|
|
297
|
+
/**
|
|
298
|
+
* Replace a draft's questions and boxes (1.26.0): the whole list, as the
|
|
299
|
+
* dashboard's Place step saves it. A box's `place` is its page and
|
|
300
|
+
* fractions of the page from its top-left. Refused, naming the question,
|
|
301
|
+
* for a page the file does not have, a box off its page, a kind that is
|
|
302
|
+
* not one, and a published version (revise it first).
|
|
303
|
+
*
|
|
304
|
+
* `fieldsVersion`, optional, is the `fields_version` of the list these
|
|
305
|
+
* replace, as `templateFields` answered it: given, a save made after the
|
|
306
|
+
* list changed (a box SignSealer placed on a scan, another person's save)
|
|
307
|
+
* is refused with 409 `stale` rather than undoing it.
|
|
308
|
+
*/
|
|
309
|
+
setTemplateFields(id, fields, opts = {}) {
|
|
310
|
+
return this.#call("PUT", `/v1/templates/${encodeURIComponent(id)}/fields`, { fields, ...(opts.fieldsVersion !== undefined ? { fields_version: opts.fieldsVersion } : {}) });
|
|
311
|
+
}
|
|
312
|
+
/** One page of a PDF template as PNG bytes (1.26.0), the picture a signer is shown. 404 until it is drawn. */
|
|
313
|
+
async templatePage(id, page) {
|
|
314
|
+
const out = await this.#call("GET", `/v1/templates/${encodeURIComponent(id)}/pages/${page}`);
|
|
315
|
+
return { page: out.page, width: out.width, height: out.height, contentType: out.content_type, bytes: base64ToBytes(out.bytes_base64) };
|
|
316
|
+
}
|
|
196
317
|
/* ------------------------------------------------------ texting consent */
|
|
197
318
|
/**
|
|
198
319
|
* Record that you have consent to text a number.
|
|
@@ -338,6 +459,16 @@ export class SignSealer {
|
|
|
338
459
|
remind(documentId, signerId, idempotencyKey) {
|
|
339
460
|
return this.#call("POST", `/v1/documents/${encodeURIComponent(documentId)}/signers/${encodeURIComponent(signerId)}/remind`, {}, idempotencyKey);
|
|
340
461
|
}
|
|
462
|
+
/**
|
|
463
|
+
* The sandbox plays a signer (00719): for a test key only, `signed` (their
|
|
464
|
+
* consent and a typed signature, through every check the signing page
|
|
465
|
+
* makes), `declined` (with `reason`) or `expired`, so each outcome and its
|
|
466
|
+
* webhooks can be driven from your tests. Refused (403) for a live key.
|
|
467
|
+
* Sent once: a second call for a signer who has signed is refused anyway.
|
|
468
|
+
*/
|
|
469
|
+
simulateSigning(documentId, signerId, outcome, reason) {
|
|
470
|
+
return this.#call("POST", `/v1/documents/${encodeURIComponent(documentId)}/signers/${encodeURIComponent(signerId)}/simulate`, { outcome, ...(reason ? { reason } : {}) }, undefined, { once: true });
|
|
471
|
+
}
|
|
341
472
|
/**
|
|
342
473
|
* A fresh signing link to put in an `<iframe>` (1.6.0), with the sites it
|
|
343
474
|
* may be framed on. Call it when the page is about to be shown rather than
|
|
@@ -369,6 +500,11 @@ export class SignSealer {
|
|
|
369
500
|
/**
|
|
370
501
|
* Send, and take the links back once.
|
|
371
502
|
*
|
|
503
|
+
* Once means once: a retry with the same idempotency key (the client's own,
|
|
504
|
+
* after a dropped connection, or yours) sends nothing again and answers with
|
|
505
|
+
* every link's `token` and `url` null, `redacted: true` on each and
|
|
506
|
+
* `links_redacted: true` on the answer. Mint a fresh link with `embedLink`.
|
|
507
|
+
*
|
|
372
508
|
* Each signer needs an `email`, a `phone`, or both; a `cc` may have neither.
|
|
373
509
|
* Given both, the same link goes out twice — by mail and by text — because a
|
|
374
510
|
* person who does not check one inbox checks the other. The text goes only
|
|
@@ -376,6 +512,7 @@ export class SignSealer {
|
|
|
376
512
|
* not, the email still goes and the reason is on the evidence trail.
|
|
377
513
|
*/
|
|
378
514
|
send(documentId, signers, idempotencyKey) {
|
|
515
|
+
/* `links_redacted` (1.26.0): the answer to a retry with the same key, whose links went in the first answer only. */
|
|
379
516
|
return this.#call("POST", `/v1/documents/${encodeURIComponent(documentId)}/send`, { signers }, idempotencyKey);
|
|
380
517
|
}
|
|
381
518
|
void(documentId, reason, idempotencyKey) {
|
|
@@ -520,6 +657,13 @@ export class SignSealer {
|
|
|
520
657
|
ensureWebhook(input) {
|
|
521
658
|
return this.#call("PUT", "/v1/webhooks", input);
|
|
522
659
|
}
|
|
660
|
+
/**
|
|
661
|
+
* Add an endpoint. Its signing `secret` is in the first answer only: a
|
|
662
|
+
* retry with the same idempotency key -- the client's own, after a
|
|
663
|
+
* connection dropped, or yours -- adds nothing and answers with the same
|
|
664
|
+
* `id`, `secret` null and `secrets_redacted: true` (1.26.0). Keep the
|
|
665
|
+
* secret from the first answer; if it was lost, `rotateWebhookSecret`.
|
|
666
|
+
*/
|
|
523
667
|
addWebhook(input, idempotencyKey) {
|
|
524
668
|
return this.#call("POST", "/v1/webhooks", input, idempotencyKey);
|
|
525
669
|
}
|
|
@@ -745,7 +889,9 @@ export class SignSealer {
|
|
|
745
889
|
method,
|
|
746
890
|
headers: {
|
|
747
891
|
...(this.#key ? { authorization: `Bearer ${this.#key}` } : {}),
|
|
892
|
+
...(this.#business ? { "signsealer-business": this.#business } : {}),
|
|
748
893
|
"content-type": "application/json",
|
|
894
|
+
...this.#agent,
|
|
749
895
|
...(key ? { "idempotency-key": key } : {}),
|
|
750
896
|
},
|
|
751
897
|
...(body === undefined ? {} : { body: JSON.stringify(body) }),
|
|
@@ -1073,18 +1219,32 @@ export class SignSealerSigning {
|
|
|
1073
1219
|
*/
|
|
1074
1220
|
export class SignSealerPartner {
|
|
1075
1221
|
#auth;
|
|
1222
|
+
#partnerKey;
|
|
1076
1223
|
#base;
|
|
1077
1224
|
#attempts;
|
|
1078
1225
|
#fetch;
|
|
1079
1226
|
constructor(opts) {
|
|
1080
|
-
|
|
1081
|
-
|
|
1227
|
+
/* Every partner client holds a secret: its client secret or its partner key. */
|
|
1228
|
+
if (inWebPage())
|
|
1229
|
+
throw new Error(KEY_IN_PAGE_MESSAGE);
|
|
1230
|
+
if ([opts?.clientId, opts?.clientSecret, opts?.partnerKey].some((v) => v?.startsWith("mk_"))) {
|
|
1231
|
+
throw new Error("that is a business's API key; the partner API takes your OAuth client id and secret, or a partner key");
|
|
1082
1232
|
}
|
|
1083
|
-
if (opts
|
|
1084
|
-
|
|
1233
|
+
if (opts?.partnerKey) {
|
|
1234
|
+
if (!/^ss_partner_(test_)?[0-9a-f]{48}$/.test(opts.partnerKey)) {
|
|
1235
|
+
throw new Error("a partner key looks like ss_partner_ (or ss_partner_test_) and 48 hex digits");
|
|
1236
|
+
}
|
|
1237
|
+
this.#partnerKey = opts.partnerKey;
|
|
1238
|
+
this.#auth = `Bearer ${opts.partnerKey}`;
|
|
1239
|
+
}
|
|
1240
|
+
else {
|
|
1241
|
+
if (!opts?.clientId || !opts?.clientSecret) {
|
|
1242
|
+
throw new Error("a partner client needs its clientId and clientSecret, or a partnerKey");
|
|
1243
|
+
}
|
|
1244
|
+
this.#partnerKey = null;
|
|
1245
|
+
const pair = `${encodeURIComponent(opts.clientId)}:${encodeURIComponent(opts.clientSecret)}`;
|
|
1246
|
+
this.#auth = `Basic ${bytesToBase64(new TextEncoder().encode(pair))}`;
|
|
1085
1247
|
}
|
|
1086
|
-
const pair = `${encodeURIComponent(opts.clientId)}:${encodeURIComponent(opts.clientSecret)}`;
|
|
1087
|
-
this.#auth = `Basic ${bytesToBase64(new TextEncoder().encode(pair))}`;
|
|
1088
1248
|
this.#base = withoutTrailingSlashes(opts.baseUrl ?? "https://api.signsealer.com");
|
|
1089
1249
|
this.#attempts = Math.max(1, opts.maxAttempts ?? 3);
|
|
1090
1250
|
this.#fetch = opts.fetch ?? globalThis.fetch;
|
|
@@ -1115,6 +1275,139 @@ export class SignSealerPartner {
|
|
|
1115
1275
|
const out = await this.#get("/v1/partner/statements");
|
|
1116
1276
|
return out.data;
|
|
1117
1277
|
}
|
|
1278
|
+
/**
|
|
1279
|
+
* 00751: make a business of your own (a Platform agreement). With an
|
|
1280
|
+
* `external_id` it is safe to retry: one already made comes back, with
|
|
1281
|
+
* `existing: true`. Without one it is sent once.
|
|
1282
|
+
*/
|
|
1283
|
+
createBusiness(input) {
|
|
1284
|
+
return this.#send("POST", "/v1/partner/businesses", input, Boolean(input.external_id));
|
|
1285
|
+
}
|
|
1286
|
+
/** 00751: the businesses you made, newest first, with how many your agreement allows. `limit` is 1 to 100. */
|
|
1287
|
+
managedBusinesses(opts = {}) {
|
|
1288
|
+
const q = new URLSearchParams({ managed: "true" });
|
|
1289
|
+
if (opts.limit !== undefined)
|
|
1290
|
+
q.set("limit", String(opts.limit));
|
|
1291
|
+
if (opts.offset !== undefined)
|
|
1292
|
+
q.set("offset", String(opts.offset));
|
|
1293
|
+
return this.#get(`/v1/partner/businesses?${q.toString()}`);
|
|
1294
|
+
}
|
|
1295
|
+
/** 00752: the prepaid balance your businesses draw on, this month by business, and the latest entries. */
|
|
1296
|
+
balance() {
|
|
1297
|
+
return this.#get("/v1/partner/balance");
|
|
1298
|
+
}
|
|
1299
|
+
/** 00751: one business you made, by its id or your own `external_id`. */
|
|
1300
|
+
managedBusiness(id) {
|
|
1301
|
+
return this.#get(`/v1/partner/businesses/${encodeURIComponent(id)}`);
|
|
1302
|
+
}
|
|
1303
|
+
/**
|
|
1304
|
+
* 00751: change its `name`, `timezone` or `profile`; only what you send changes. Safe to retry.
|
|
1305
|
+
* 00752: `status` suspends or resumes it, `membership` is month or year from its next renewal,
|
|
1306
|
+
* `spend_cap_cents` its monthly spending limit (null for none).
|
|
1307
|
+
*/
|
|
1308
|
+
updateBusiness(id, changes) {
|
|
1309
|
+
return this.#send("PATCH", `/v1/partner/businesses/${encodeURIComponent(id)}`, changes, true);
|
|
1310
|
+
}
|
|
1311
|
+
/** 00759: your default prices to your businesses, and what each unit is. */
|
|
1312
|
+
prices() {
|
|
1313
|
+
return this.#get("/v1/partner/prices");
|
|
1314
|
+
}
|
|
1315
|
+
/** 00759: replace your default prices; `{}` takes them all away. Safe to retry. */
|
|
1316
|
+
setPrices(prices) {
|
|
1317
|
+
return this.#send("PUT", "/v1/partner/prices", { prices }, true);
|
|
1318
|
+
}
|
|
1319
|
+
/**
|
|
1320
|
+
* 00759: give one of your businesses credit (`cents` above zero), or take
|
|
1321
|
+
* back what is left (below zero), in your prices. With an `idempotencyKey`
|
|
1322
|
+
* it is safe to retry; without one it is sent once.
|
|
1323
|
+
*/
|
|
1324
|
+
giveCredit(id, gift) {
|
|
1325
|
+
const { idempotencyKey, ...body } = gift;
|
|
1326
|
+
return this.#send("POST", `/v1/partner/businesses/${encodeURIComponent(id)}/gift-credit`, body, Boolean(idempotencyKey), idempotencyKey ? { "idempotency-key": idempotencyKey } : {});
|
|
1327
|
+
}
|
|
1328
|
+
/**
|
|
1329
|
+
* 00760: your webhook endpoints, each hearing every business you made;
|
|
1330
|
+
* with a test key, your sandbox's.
|
|
1331
|
+
*/
|
|
1332
|
+
async webhooks() {
|
|
1333
|
+
return (await this.#get("/v1/partner/webhooks")).data;
|
|
1334
|
+
}
|
|
1335
|
+
/** 00760: add an endpoint for every business you made. Its signing `secret` is in this answer only. Sent once. */
|
|
1336
|
+
addWebhook(endpoint) {
|
|
1337
|
+
return this.#send("POST", "/v1/partner/webhooks", endpoint, false);
|
|
1338
|
+
}
|
|
1339
|
+
/** 00760: change an endpoint on every business at once; `active: true` turns back on every copy that paused. */
|
|
1340
|
+
updateWebhook(id, changes) {
|
|
1341
|
+
return this.#send("PATCH", `/v1/partner/webhooks/${encodeURIComponent(id)}`, changes, true);
|
|
1342
|
+
}
|
|
1343
|
+
/** 00760: remove an endpoint from every business. */
|
|
1344
|
+
async deleteWebhook(id) {
|
|
1345
|
+
await this.#send("DELETE", `/v1/partner/webhooks/${encodeURIComponent(id)}`, undefined, true);
|
|
1346
|
+
}
|
|
1347
|
+
/** 00760: an endpoint's latest deliveries across every business, newest first. */
|
|
1348
|
+
async webhookDeliveries(id, opts = {}) {
|
|
1349
|
+
const q = opts.limit !== undefined ? `?limit=${opts.limit}` : "";
|
|
1350
|
+
return (await this.#get(`/v1/partner/webhooks/${encodeURIComponent(id)}/deliveries${q}`)).data;
|
|
1351
|
+
}
|
|
1352
|
+
/** 00760: deliver one again. */
|
|
1353
|
+
replayWebhookDelivery(id, delivery) {
|
|
1354
|
+
return this.#send("POST", `/v1/partner/webhooks/${encodeURIComponent(id)}/deliveries/${encodeURIComponent(delivery)}/replay`, {}, false);
|
|
1355
|
+
}
|
|
1356
|
+
/**
|
|
1357
|
+
* 00763: a start link to one of your businesses' screens inside your product,
|
|
1358
|
+
* for one of your users. It opens once, within five minutes: ask for it as
|
|
1359
|
+
* the page that frames it loads. Sent once. `components` are the screens:
|
|
1360
|
+
* `documents` (the default), `send` (00789), `templates` (00791), and
|
|
1361
|
+
* `settings` and `texting` (00792). Mount it with `@signsealer/embed`.
|
|
1362
|
+
*/
|
|
1363
|
+
embedSession(id, session) {
|
|
1364
|
+
return this.#send("POST", `/v1/partner/businesses/${encodeURIComponent(id)}/sessions`, session, false);
|
|
1365
|
+
}
|
|
1366
|
+
/** 00759: a calendar month (YYYY-MM, this one when left out) per business, in your prices, with what to bill. */
|
|
1367
|
+
usage(month) {
|
|
1368
|
+
return this.#get(`/v1/partner/usage${month ? `?month=${encodeURIComponent(month)}` : ""}`);
|
|
1369
|
+
}
|
|
1370
|
+
/**
|
|
1371
|
+
* 00751: a client that acts for one of your businesses -- one you made,
|
|
1372
|
+
* or one that connected your app -- by its id or your own `external_id`.
|
|
1373
|
+
* Every `SignSealer` method then works for that business. Needs a partner key.
|
|
1374
|
+
*/
|
|
1375
|
+
business(id) {
|
|
1376
|
+
if (!this.#partnerKey)
|
|
1377
|
+
throw new Error("acting for a business needs a partner key: build this client with partnerKey");
|
|
1378
|
+
return new SignSealer({ apiKey: this.#partnerKey, business: id, baseUrl: this.#base, maxAttempts: this.#attempts, fetch: this.#fetch });
|
|
1379
|
+
}
|
|
1380
|
+
/* A write: retried on a transient failure only when `safe` says asking twice makes nothing twice. */
|
|
1381
|
+
async #send(method, path, body, safe, extra = {}) {
|
|
1382
|
+
for (let attempt = 1;; attempt += 1) {
|
|
1383
|
+
let res;
|
|
1384
|
+
try {
|
|
1385
|
+
res = await this.#fetch(`${this.#base}${path}`, {
|
|
1386
|
+
method,
|
|
1387
|
+
headers: { ...extra, ...agentHeader(undefined), authorization: this.#auth, accept: "application/json",
|
|
1388
|
+
...(body === undefined ? {} : { "content-type": "application/json" }) },
|
|
1389
|
+
...(body === undefined ? {} : { body: JSON.stringify(body) }),
|
|
1390
|
+
});
|
|
1391
|
+
}
|
|
1392
|
+
catch (cause) {
|
|
1393
|
+
if (safe && attempt < this.#attempts) {
|
|
1394
|
+
await sleep(backoff(attempt));
|
|
1395
|
+
continue;
|
|
1396
|
+
}
|
|
1397
|
+
throw new SignSealerError(0, "network", cause instanceof Error ? cause.message : "the request did not reach SignSealer", undefined, undefined);
|
|
1398
|
+
}
|
|
1399
|
+
const requestId = res.headers.get("x-request-id") ?? undefined;
|
|
1400
|
+
const text = await res.text();
|
|
1401
|
+
const parsed = text ? safeJson(text) : {};
|
|
1402
|
+
if (res.ok)
|
|
1403
|
+
return parsed;
|
|
1404
|
+
const err = parsed.error;
|
|
1405
|
+
const failure = new SignSealerError(res.status, err?.code ?? "unknown", err?.message ?? `SignSealer returned ${res.status}`, err?.hint, requestId, waitAsked(res.headers.get("retry-after")));
|
|
1406
|
+
if (!safe || !failure.retryable || attempt >= this.#attempts)
|
|
1407
|
+
throw failure;
|
|
1408
|
+
await sleep(backoff(attempt));
|
|
1409
|
+
}
|
|
1410
|
+
}
|
|
1118
1411
|
/*
|
|
1119
1412
|
Every call only reads, so a transient failure is retried as it is: there
|
|
1120
1413
|
is nothing a second GET could do twice.
|
|
@@ -1125,7 +1418,7 @@ export class SignSealerPartner {
|
|
|
1125
1418
|
try {
|
|
1126
1419
|
res = await this.#fetch(`${this.#base}${path}`, {
|
|
1127
1420
|
method: "GET",
|
|
1128
|
-
headers: { authorization: this.#auth, accept: "application/json" },
|
|
1421
|
+
headers: { ...agentHeader(undefined), authorization: this.#auth, accept: "application/json" },
|
|
1129
1422
|
});
|
|
1130
1423
|
}
|
|
1131
1424
|
catch (cause) {
|