@signsealer/sdk 1.25.0 → 1.27.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 +106 -0
- package/README.md +36 -8
- package/dist/cjs/index.cjs +153 -6
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +396 -15
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/index.js +152 -5
- package/dist/esm/index.js.map +1 -1
- package/package.json +10 -6
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,111 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.27.0
|
|
4
|
+
|
|
5
|
+
Everything that worked in 1.26.0 still compiles and works.
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- `templateTranslations(id)`, `templateTranslation(id, language)`,
|
|
10
|
+
`setTemplateTranslation(id, language, input)` and
|
|
11
|
+
`withdrawTemplateTranslation(id, language)` (00795): a business's own
|
|
12
|
+
official translation of a written template's version, in any language on
|
|
13
|
+
our list. A signer who reads its language reads it in place of the
|
|
14
|
+
original and signs it, and the certificate says what was read and what
|
|
15
|
+
was signed, each with its hash. Refused, saying why, unless only the words
|
|
16
|
+
differ from the original. A revision leaves translations behind until
|
|
17
|
+
they are copied to it. Typed as `TemplateTranslations`,
|
|
18
|
+
`TemplateTranslation` and `TranslatedField`.
|
|
19
|
+
- `language` on a template and on `editTemplate` (00794): the language a
|
|
20
|
+
version is written in; a new one takes the business's default.
|
|
21
|
+
- `language.default_language` on `settings()` (00794): the language the
|
|
22
|
+
business writes in and offers its signers first.
|
|
23
|
+
|
|
24
|
+
## 1.26.0
|
|
25
|
+
|
|
26
|
+
Everything that worked in 1.25.0 still compiles and works, with three
|
|
27
|
+
exceptions the API made for security (Changed, below): two on a retry with
|
|
28
|
+
the same idempotency key, and what an app a business connected is told about
|
|
29
|
+
its texting number. One of them narrows a type: `addWebhook`'s `secret` is
|
|
30
|
+
now `string | null`.
|
|
31
|
+
|
|
32
|
+
### Added
|
|
33
|
+
|
|
34
|
+
- More screens in `embedSession(id, { user, components })`: `components` may
|
|
35
|
+
name `send` (00789), the Send screen, to send from one of the business's
|
|
36
|
+
templates or hand the signing links back to your page; `templates` (00791),
|
|
37
|
+
the business's templates, written and edited in the dashboard's editor
|
|
38
|
+
inside your page and published by an `admin`; and `settings` and `texting`
|
|
39
|
+
(00792), the business's brand, delivery and reminders, and its texting
|
|
40
|
+
number, set and applied for by an `admin`. 1.25.0 took `documents` only.
|
|
41
|
+
The browser package `@signsealer/embed` mounts any of them on your page.
|
|
42
|
+
- `settings()` and `updateSettings(changes)` (00792): a business's brand (the
|
|
43
|
+
name, colours, sender name, reply-to address and logo its signers see), who
|
|
44
|
+
sends its signing links, and its reminders; changed only by a partner for a
|
|
45
|
+
business it manages, through `partner.business(id)`. Typed as `Settings`
|
|
46
|
+
and `SettingsChanges`.
|
|
47
|
+
- `textingNumber()` and `applyForTextingNumber(application)` (00792): the
|
|
48
|
+
business's own texting number, where its application has got to and the
|
|
49
|
+
carriers' wording, as data; and, for a business a partner manages, its
|
|
50
|
+
application for a toll-free or a local number, filed by the partner. Typed
|
|
51
|
+
as `TextingNumberState` and `TextingNumberApplication`.
|
|
52
|
+
- `body_format` on `createTemplate()` (`TemplateInput`, 00791): `markdown`
|
|
53
|
+
writes a template with formatting from its first version, rather than
|
|
54
|
+
switching it after.
|
|
55
|
+
- PDF templates through the API (14 November 2026): `createPdfTemplate({
|
|
56
|
+
name, filename, pdf, kind?, code? })` makes a draft from the file, as the
|
|
57
|
+
dashboard's upload does -- read, sanitised and drawn, its signature, date
|
|
58
|
+
and other boxes put where the file asks for them -- and answers with the
|
|
59
|
+
template, its pages and what was found (`PdfTemplate`). `templateFields(id)`
|
|
60
|
+
lists a draft's questions and boxes with its pages (`TemplateFields`,
|
|
61
|
+
`TemplatePage`), `setTemplateFields(id, fields, { fieldsVersion? })`
|
|
62
|
+
replaces them whole, and `templatePage(id, n)` is a page's picture as PNG
|
|
63
|
+
bytes. `fields_version` on `TemplateFields` names the list; given back as
|
|
64
|
+
`fieldsVersion`, a save made after the list changed (a box SignSealer
|
|
65
|
+
placed on a scan, another person's save) is refused with 409 `stale`
|
|
66
|
+
instead of undoing it.
|
|
67
|
+
- `warnings` on what `publishTemplate` answers: `nothing_placed`, a PDF
|
|
68
|
+
template nobody can sign where it is.
|
|
69
|
+
- `redacted` on `SignerLink`, `links_redacted` on `send`'s answer and on
|
|
70
|
+
`StartedWorkflow`, and `AddedWebhook` (`redacted`, `secrets_redacted`) for
|
|
71
|
+
what `addWebhook` answers: the types of the two security changes below.
|
|
72
|
+
- The client refuses a secret key in a web page: a `SignSealer` built with an
|
|
73
|
+
API key or a partner key, or any `SignSealerPartner`, throws in a browser
|
|
74
|
+
page and says to keep the key on your server and use `@signsealer/embed`
|
|
75
|
+
to show SignSealer's screens in a page. Node, Deno, Bun, edge runtimes and
|
|
76
|
+
workers are unaffected, and so are `SignaturePad`, `verifyWebhook` and a
|
|
77
|
+
client with no key (`pairDevice`).
|
|
78
|
+
|
|
79
|
+
### Changed (security)
|
|
80
|
+
|
|
81
|
+
- A retry of `send`, `startWorkflow` or `startPacketItem` with the same
|
|
82
|
+
idempotency key -- the client's own, after a connection dropped, or yours --
|
|
83
|
+
still sends and starts nothing twice, and now answers without the signing
|
|
84
|
+
links: each `token` and `url` is null, the link is marked `redacted: true`
|
|
85
|
+
and the answer `links_redacted: true` (the API, 14 November 2026). The API
|
|
86
|
+
keeps a link only as its hash, and the copy of an answer it keeps for a
|
|
87
|
+
retry used to hold them whole. To show a signer whose link was lost, mint a
|
|
88
|
+
fresh one with `embedLink`. This is the API's behaviour, whichever version
|
|
89
|
+
of the client asks.
|
|
90
|
+
- A retry of `addWebhook` with the same idempotency key still adds nothing,
|
|
91
|
+
and now answers without the endpoint's signing secret: `secret` is null,
|
|
92
|
+
with `redacted: true` and `secrets_redacted: true` (the API, 14 November
|
|
93
|
+
2026). The copy of an answer the API kept for a retry used to hold the
|
|
94
|
+
secret whole, and whoever holds it can forge deliveries. `addWebhook` now
|
|
95
|
+
answers `AddedWebhook`, whose `secret` is `string | null`: code that
|
|
96
|
+
assigned it to a `string` needs a check. Keep the secret from the first
|
|
97
|
+
answer; if it was lost, `rotateWebhookSecret`.
|
|
98
|
+
- A connected app no longer sees a business's texting number or the
|
|
99
|
+
carriers' reason (the API, 16 November 2026). `account().texting.number`,
|
|
100
|
+
and `texting.application`'s `phone` and `reason`, are null to an app the
|
|
101
|
+
business connected and to a tablet; it is told the application's `status`
|
|
102
|
+
and `kind`. The business's own API key, and a partner for a business it
|
|
103
|
+
manages, see them as before, as `textingNumber()` already decided. The
|
|
104
|
+
`texting.number_updated` webhook is told the same way: `phone` and
|
|
105
|
+
`reason` are null at a partner's endpoint on a business that only
|
|
106
|
+
connected its app. The types were already `string | null`. This is the API's behaviour, whichever
|
|
107
|
+
version of the client asks.
|
|
108
|
+
|
|
3
109
|
## 1.25.0
|
|
4
110
|
|
|
5
111
|
Nothing that worked before changes.
|
package/README.md
CHANGED
|
@@ -1,12 +1,26 @@
|
|
|
1
1
|
# @signsealer/sdk
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
**For your server.** [SignSealer](https://signsealer.com)'s server library: it
|
|
4
|
+
holds your secret key (an API key, or a partner key) and makes the calls that
|
|
5
|
+
send, read and manage. To show SignSealer's screens in your web page, use
|
|
6
|
+
[`@signsealer/embed`](https://www.npmjs.com/package/@signsealer/embed): your
|
|
7
|
+
server gets the session link with this package, and the page mounts it with
|
|
8
|
+
that one.
|
|
9
|
+
|
|
10
|
+
| Package | Where it runs | What it does | Holds a key? |
|
|
11
|
+
|---|---|---|---|
|
|
12
|
+
| `@signsealer/sdk` (this one) | Your server: Node 18+, edge runtimes | Sends documents, reads their evidence, manages the businesses you serve, verifies webhooks | Yes, your secret key |
|
|
13
|
+
| `@signsealer/embed` | Your web page, in the browser | Mounts SignSealer's screens in an iframe on your page | No |
|
|
14
|
+
|
|
15
|
+
Since 1.26.0 a `SignSealer` built with a key, or any `SignSealerPartner`, throws
|
|
16
|
+
in a web page rather than put the key where anybody who opens the page can read
|
|
17
|
+
it. What holds no secret key still works in a browser: `SignSealerSigning` (the
|
|
18
|
+
signer's side), the `SignaturePad` in `@signsealer/sdk/react`, and
|
|
19
|
+
`verifyWebhook`.
|
|
5
20
|
|
|
6
21
|
**No dependencies.** `fetch` is in the runtime, and a signing SDK that drags a
|
|
7
22
|
HTTP library into somebody's build is a signing SDK that gets declined at
|
|
8
|
-
review.
|
|
9
|
-
browser — though an API key belongs on a server.
|
|
23
|
+
review.
|
|
10
24
|
|
|
11
25
|
```
|
|
12
26
|
npm install @signsealer/sdk
|
|
@@ -239,10 +253,24 @@ if (pdf.has_pdf && !pdf.ready) {
|
|
|
239
253
|
}
|
|
240
254
|
```
|
|
241
255
|
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
256
|
+
The file goes up in the dashboard, or from your server with
|
|
257
|
+
`createPdfTemplate` (1.26.0): read, sanitised and drawn as an upload is, with
|
|
258
|
+
its signature, date and other boxes put where the file asks for them. Check
|
|
259
|
+
and move them with `templateFields` and `setTemplateFields`, then publish.
|
|
260
|
+
SignSealer draws the pictures a signer sees from the file itself as it is
|
|
261
|
+
uploaded, and a template cannot be published until every page has one.
|
|
262
|
+
Publishing one with nothing placed on its pages answers with
|
|
263
|
+
`warnings: [{ code: "nothing_placed" }]`: nobody can sign it where it is.
|
|
264
|
+
|
|
265
|
+
```ts
|
|
266
|
+
const made = await client.createPdfTemplate({
|
|
267
|
+
name: "Boat rental", filename: "boat-rental.pdf", pdf: await readFile("boat-rental.pdf"),
|
|
268
|
+
});
|
|
269
|
+
const { fields } = await client.templateFields(made.template_id);
|
|
270
|
+
await client.setTemplateFields(made.template_id, fields.map((f) =>
|
|
271
|
+
f.key === "signature" ? { ...f, place: { page: 2, x: 0.1, y: 0.7, w: 0.35, h: 0.05 } } : f));
|
|
272
|
+
await client.publishTemplate(made.template_id);
|
|
273
|
+
```
|
|
246
274
|
|
|
247
275
|
### Signing where there is no network
|
|
248
276
|
|
package/dist/cjs/index.cjs
CHANGED
|
@@ -5,7 +5,9 @@
|
|
|
5
5
|
* Deliberately dependency-free: `fetch` is in the runtime, and a signing SDK
|
|
6
6
|
* that drags a HTTP library into somebody's build is a signing SDK that gets
|
|
7
7
|
* declined at review. It runs anywhere `fetch` does, which is every Node since
|
|
8
|
-
* 18
|
|
8
|
+
* 18 and every edge runtime. It is the server's half: a client given a secret
|
|
9
|
+
* key in a web page throws (1.26.0), and the page's half, which holds no key,
|
|
10
|
+
* is `@signsealer/embed`.
|
|
9
11
|
*
|
|
10
12
|
* Three things it does that a hand-rolled client usually does not:
|
|
11
13
|
*
|
|
@@ -49,7 +51,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
49
51
|
};
|
|
50
52
|
})();
|
|
51
53
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
52
|
-
exports.WEBHOOK_TOLERANCE_SECONDS = exports.WEBHOOK_SIGNATURE_HEADER = exports.WEBHOOK_TIMESTAMP_HEADER = exports.WEBHOOK_EVENT_HEADER = exports.SignSealerOAuth = exports.SignSealerOAuthError = exports.SignSealerPartner = exports.SignSealerSigning = exports.SignSealer = exports.SDK_VERSION = exports.SignSealerError = void 0;
|
|
54
|
+
exports.WEBHOOK_TOLERANCE_SECONDS = exports.WEBHOOK_SIGNATURE_HEADER = exports.WEBHOOK_TIMESTAMP_HEADER = exports.WEBHOOK_EVENT_HEADER = exports.SignSealerOAuth = exports.SignSealerOAuthError = exports.SignSealerPartner = exports.SignSealerSigning = exports.SignSealer = exports.KEY_IN_PAGE_MESSAGE = exports.SDK_VERSION = exports.SignSealerError = void 0;
|
|
53
55
|
exports.createPkce = createPkce;
|
|
54
56
|
exports.pkceChallenge = pkceChallenge;
|
|
55
57
|
exports.verifyWebhook = verifyWebhook;
|
|
@@ -94,7 +96,7 @@ class SignSealerError extends Error {
|
|
|
94
96
|
}
|
|
95
97
|
exports.SignSealerError = SignSealerError;
|
|
96
98
|
/** This package's version, as `package.json` has it; `tests/sdk.ts` holds the two together. */
|
|
97
|
-
exports.SDK_VERSION = "1.
|
|
99
|
+
exports.SDK_VERSION = "1.27.0";
|
|
98
100
|
/** The `User-Agent` header for a server-side client, or none in a browser or when switched off. */
|
|
99
101
|
function agentHeader(given) {
|
|
100
102
|
if (typeof globalThis.window !== "undefined")
|
|
@@ -102,6 +104,28 @@ function agentHeader(given) {
|
|
|
102
104
|
const agent = given === undefined ? `signsealer-sdk/${exports.SDK_VERSION} (node)` : given.trim();
|
|
103
105
|
return agent ? { "user-agent": agent.slice(0, 200) } : {};
|
|
104
106
|
}
|
|
107
|
+
/**
|
|
108
|
+
* Whether this is a web page (1.26.0): a `window` and a `document`, and none
|
|
109
|
+
* of the server-like runtimes that can have them too -- jsdom in a Node test,
|
|
110
|
+
* Electron, Deno, Bun. Workers and edge runtimes have no `document`.
|
|
111
|
+
*
|
|
112
|
+
* This library's secret keys (an API key, a partner key, a partner's client
|
|
113
|
+
* secret) act for a business, and anybody who opens a page can read whatever
|
|
114
|
+
* the page holds. What takes no such key is still fine in a page and the
|
|
115
|
+
* guard is not about it: `SignSealerSigning` (a signer's link, and at most a
|
|
116
|
+
* paired tablet's own credential), a `SignSealer` with no key (`pairDevice`),
|
|
117
|
+
* `SignaturePad` and `verifyWebhook`.
|
|
118
|
+
*/
|
|
119
|
+
function inWebPage() {
|
|
120
|
+
const g = globalThis;
|
|
121
|
+
if (typeof g.window === "undefined" || typeof g.document === "undefined")
|
|
122
|
+
return false;
|
|
123
|
+
const v = g.process?.versions;
|
|
124
|
+
return typeof v?.node !== "string" && typeof v?.electron !== "string" && typeof g.Deno === "undefined" && typeof g.Bun === "undefined";
|
|
125
|
+
}
|
|
126
|
+
/** What a client built with a secret key in a web page throws (1.26.0). */
|
|
127
|
+
exports.KEY_IN_PAGE_MESSAGE = "This is SignSealer's server library and you gave it a secret key in a web page. "
|
|
128
|
+
+ "Keep the key on your server; to show SignSealer's screens in a page, use @signsealer/embed.";
|
|
105
129
|
/* ------------------------------------------------------------------ client */
|
|
106
130
|
/**
|
|
107
131
|
* Strip trailing slashes without a regular expression.
|
|
@@ -138,6 +162,8 @@ class SignSealer {
|
|
|
138
162
|
*/
|
|
139
163
|
agreementsRemaining = null;
|
|
140
164
|
constructor(opts = {}) {
|
|
165
|
+
if (opts.apiKey && inWebPage())
|
|
166
|
+
throw new Error(exports.KEY_IN_PAGE_MESSAGE);
|
|
141
167
|
const partnerKey = opts.apiKey?.startsWith("ss_partner_") ?? false;
|
|
142
168
|
if (opts.apiKey !== undefined && !opts.apiKey.startsWith("mk_") && !partnerKey) {
|
|
143
169
|
throw new Error("a SignSealer API key looks like mk_live_… or mk_test_…");
|
|
@@ -168,6 +194,38 @@ class SignSealer {
|
|
|
168
194
|
branding() {
|
|
169
195
|
return this.#call("GET", "/v1/branding");
|
|
170
196
|
}
|
|
197
|
+
/**
|
|
198
|
+
* The business's brand, how its signing links go, and its reminders
|
|
199
|
+
* (00792). `editable` says whether this key may change them: true only for
|
|
200
|
+
* a partner acting for a business it manages.
|
|
201
|
+
*/
|
|
202
|
+
settings() {
|
|
203
|
+
return this.#call("GET", "/v1/settings");
|
|
204
|
+
}
|
|
205
|
+
/**
|
|
206
|
+
* Set a managed business's brand, delivery and reminders, as its partner
|
|
207
|
+
* (00792; with `partner.business(id)`). Only what is named changes; null
|
|
208
|
+
* clears it. Any other key is refused with 403: a business that owns its
|
|
209
|
+
* account sets these in its dashboard. A PATCH of the same values, so a
|
|
210
|
+
* retry after a lost answer sets the same thing again.
|
|
211
|
+
*/
|
|
212
|
+
updateSettings(changes) {
|
|
213
|
+
return this.#call("PATCH", "/v1/settings", changes);
|
|
214
|
+
}
|
|
215
|
+
/**
|
|
216
|
+
* Apply for a managed business's texting number, as its partner (00792;
|
|
217
|
+
* with `partner.business(id)`), for a toll-free or a local number. Checked
|
|
218
|
+
* as the carriers would check it; a local number's setup is drawn from
|
|
219
|
+
* your balance now. Sent once, never retried: a second answer would file
|
|
220
|
+
* the application again.
|
|
221
|
+
*/
|
|
222
|
+
applyForTextingNumber(application) {
|
|
223
|
+
return this.#call("POST", "/v1/texting/number", application, undefined, { once: true });
|
|
224
|
+
}
|
|
225
|
+
/** The business's own texting number, its application's steps, and the carriers' wording (00792). */
|
|
226
|
+
textingNumber() {
|
|
227
|
+
return this.#call("GET", "/v1/texting/number");
|
|
228
|
+
}
|
|
171
229
|
/** Prove the key works, and say whose account it is. */
|
|
172
230
|
account() {
|
|
173
231
|
return this.#call("GET", "/v1/account");
|
|
@@ -221,6 +279,34 @@ class SignSealer {
|
|
|
221
279
|
discardTemplate(id) {
|
|
222
280
|
return this.#call("DELETE", `/v1/templates/${encodeURIComponent(id)}`);
|
|
223
281
|
}
|
|
282
|
+
/**
|
|
283
|
+
* The language a template version is written in, and the business's own
|
|
284
|
+
* official translations of every version of its code (1.27.0). A signer
|
|
285
|
+
* who reads a translation's language reads it in place of the original and
|
|
286
|
+
* signs it; a revision leaves translations behind until copied forward.
|
|
287
|
+
*/
|
|
288
|
+
templateTranslations(id) {
|
|
289
|
+
return this.#call("GET", `/v1/templates/${encodeURIComponent(id)}/translations`);
|
|
290
|
+
}
|
|
291
|
+
/** One official translation of this version, whole (1.27.0). */
|
|
292
|
+
templateTranslation(id, language) {
|
|
293
|
+
return this.#call("GET", `/v1/templates/${encodeURIComponent(id)}/translations/${encodeURIComponent(language)}`);
|
|
294
|
+
}
|
|
295
|
+
/**
|
|
296
|
+
* Save the business's own official translation of this version (1.27.0),
|
|
297
|
+
* replacing the one there was. Refused with 422, saying why, unless only
|
|
298
|
+
* the words differ: exactly the original's blanks, the same paragraphs that
|
|
299
|
+
* depend on an answer, every question's words (and its line, choices and
|
|
300
|
+
* group, where the original has them), and the template's own consent line
|
|
301
|
+
* where it has one. Not for an uploaded PDF.
|
|
302
|
+
*/
|
|
303
|
+
setTemplateTranslation(id, language, input) {
|
|
304
|
+
return this.#call("PUT", `/v1/templates/${encodeURIComponent(id)}/translations/${encodeURIComponent(language)}`, input);
|
|
305
|
+
}
|
|
306
|
+
/** Withdraw this version's translation in a language (1.27.0): signers who have not read it read the original. */
|
|
307
|
+
withdrawTemplateTranslation(id, language) {
|
|
308
|
+
return this.#call("DELETE", `/v1/templates/${encodeURIComponent(id)}/translations/${encodeURIComponent(language)}`);
|
|
309
|
+
}
|
|
224
310
|
/**
|
|
225
311
|
* The settings a template's code carries to every version (1.6.0).
|
|
226
312
|
* `resign: true` asks everybody who signed an older version to sign the
|
|
@@ -250,12 +336,55 @@ class SignSealer {
|
|
|
250
336
|
*
|
|
251
337
|
* `ready` is the one to check: a PDF template cannot be published until
|
|
252
338
|
* SignSealer has drawn a picture of every page from the file itself
|
|
253
|
-
* (00474), which it does as the file is uploaded
|
|
254
|
-
*
|
|
339
|
+
* (00474), which it does as the file is uploaded, in the dashboard or with
|
|
340
|
+
* `createPdfTemplate`.
|
|
255
341
|
*/
|
|
256
342
|
templatePdf(id) {
|
|
257
343
|
return this.#call("GET", `/v1/templates/${encodeURIComponent(id)}/pdf`);
|
|
258
344
|
}
|
|
345
|
+
/**
|
|
346
|
+
* A PDF template, as a draft, from the file (1.26.0): what the dashboard's
|
|
347
|
+
* upload makes. The file is read, sanitised and drawn exactly as an upload
|
|
348
|
+
* is -- up to 12 MB and 60 pages, refused in the dashboard's words past
|
|
349
|
+
* either, or when it is not a PDF or is password-protected -- and the
|
|
350
|
+
* signature and date every PDF starts with are put where the file asks for
|
|
351
|
+
* them, with initials, a printed name and a fillable form's questions each
|
|
352
|
+
* on its box. Check them with `templateFields`, move them with
|
|
353
|
+
* `setTemplateFields`, then `publishTemplate`. `pdf` is the file's bytes
|
|
354
|
+
* or its base64. Needs `signing:templates`.
|
|
355
|
+
*/
|
|
356
|
+
createPdfTemplate(input, idempotencyKey) {
|
|
357
|
+
const { pdf, filename, ...rest } = input;
|
|
358
|
+
const content_base64 = typeof pdf === "string" ? pdf : bytesToBase64(pdf);
|
|
359
|
+
return this.#call("POST", "/v1/templates/pdf", { ...rest, pdf: { filename, content_base64 } }, idempotencyKey);
|
|
360
|
+
}
|
|
361
|
+
/**
|
|
362
|
+
* The questions and boxes a template asks for (1.26.0), with a PDF's pages
|
|
363
|
+
* and the address of each page's picture, for a screen to draw them on.
|
|
364
|
+
*/
|
|
365
|
+
templateFields(id) {
|
|
366
|
+
return this.#call("GET", `/v1/templates/${encodeURIComponent(id)}/fields`);
|
|
367
|
+
}
|
|
368
|
+
/**
|
|
369
|
+
* Replace a draft's questions and boxes (1.26.0): the whole list, as the
|
|
370
|
+
* dashboard's Place step saves it. A box's `place` is its page and
|
|
371
|
+
* fractions of the page from its top-left. Refused, naming the question,
|
|
372
|
+
* for a page the file does not have, a box off its page, a kind that is
|
|
373
|
+
* not one, and a published version (revise it first).
|
|
374
|
+
*
|
|
375
|
+
* `fieldsVersion`, optional, is the `fields_version` of the list these
|
|
376
|
+
* replace, as `templateFields` answered it: given, a save made after the
|
|
377
|
+
* list changed (a box SignSealer placed on a scan, another person's save)
|
|
378
|
+
* is refused with 409 `stale` rather than undoing it.
|
|
379
|
+
*/
|
|
380
|
+
setTemplateFields(id, fields, opts = {}) {
|
|
381
|
+
return this.#call("PUT", `/v1/templates/${encodeURIComponent(id)}/fields`, { fields, ...(opts.fieldsVersion !== undefined ? { fields_version: opts.fieldsVersion } : {}) });
|
|
382
|
+
}
|
|
383
|
+
/** One page of a PDF template as PNG bytes (1.26.0), the picture a signer is shown. 404 until it is drawn. */
|
|
384
|
+
async templatePage(id, page) {
|
|
385
|
+
const out = await this.#call("GET", `/v1/templates/${encodeURIComponent(id)}/pages/${page}`);
|
|
386
|
+
return { page: out.page, width: out.width, height: out.height, contentType: out.content_type, bytes: base64ToBytes(out.bytes_base64) };
|
|
387
|
+
}
|
|
259
388
|
/* ------------------------------------------------------ texting consent */
|
|
260
389
|
/**
|
|
261
390
|
* Record that you have consent to text a number.
|
|
@@ -442,6 +571,11 @@ class SignSealer {
|
|
|
442
571
|
/**
|
|
443
572
|
* Send, and take the links back once.
|
|
444
573
|
*
|
|
574
|
+
* Once means once: a retry with the same idempotency key (the client's own,
|
|
575
|
+
* after a dropped connection, or yours) sends nothing again and answers with
|
|
576
|
+
* every link's `token` and `url` null, `redacted: true` on each and
|
|
577
|
+
* `links_redacted: true` on the answer. Mint a fresh link with `embedLink`.
|
|
578
|
+
*
|
|
445
579
|
* Each signer needs an `email`, a `phone`, or both; a `cc` may have neither.
|
|
446
580
|
* Given both, the same link goes out twice — by mail and by text — because a
|
|
447
581
|
* person who does not check one inbox checks the other. The text goes only
|
|
@@ -449,6 +583,7 @@ class SignSealer {
|
|
|
449
583
|
* not, the email still goes and the reason is on the evidence trail.
|
|
450
584
|
*/
|
|
451
585
|
send(documentId, signers, idempotencyKey) {
|
|
586
|
+
/* `links_redacted` (1.26.0): the answer to a retry with the same key, whose links went in the first answer only. */
|
|
452
587
|
return this.#call("POST", `/v1/documents/${encodeURIComponent(documentId)}/send`, { signers }, idempotencyKey);
|
|
453
588
|
}
|
|
454
589
|
void(documentId, reason, idempotencyKey) {
|
|
@@ -593,6 +728,13 @@ class SignSealer {
|
|
|
593
728
|
ensureWebhook(input) {
|
|
594
729
|
return this.#call("PUT", "/v1/webhooks", input);
|
|
595
730
|
}
|
|
731
|
+
/**
|
|
732
|
+
* Add an endpoint. Its signing `secret` is in the first answer only: a
|
|
733
|
+
* retry with the same idempotency key -- the client's own, after a
|
|
734
|
+
* connection dropped, or yours -- adds nothing and answers with the same
|
|
735
|
+
* `id`, `secret` null and `secrets_redacted: true` (1.26.0). Keep the
|
|
736
|
+
* secret from the first answer; if it was lost, `rotateWebhookSecret`.
|
|
737
|
+
*/
|
|
596
738
|
addWebhook(input, idempotencyKey) {
|
|
597
739
|
return this.#call("POST", "/v1/webhooks", input, idempotencyKey);
|
|
598
740
|
}
|
|
@@ -1155,6 +1297,9 @@ class SignSealerPartner {
|
|
|
1155
1297
|
#attempts;
|
|
1156
1298
|
#fetch;
|
|
1157
1299
|
constructor(opts) {
|
|
1300
|
+
/* Every partner client holds a secret: its client secret or its partner key. */
|
|
1301
|
+
if (inWebPage())
|
|
1302
|
+
throw new Error(exports.KEY_IN_PAGE_MESSAGE);
|
|
1158
1303
|
if ([opts?.clientId, opts?.clientSecret, opts?.partnerKey].some((v) => v?.startsWith("mk_"))) {
|
|
1159
1304
|
throw new Error("that is a business's API key; the partner API takes your OAuth client id and secret, or a partner key");
|
|
1160
1305
|
}
|
|
@@ -1284,7 +1429,9 @@ class SignSealerPartner {
|
|
|
1284
1429
|
/**
|
|
1285
1430
|
* 00763: a start link to one of your businesses' screens inside your product,
|
|
1286
1431
|
* for one of your users. It opens once, within five minutes: ask for it as
|
|
1287
|
-
* the page that frames it loads. Sent once.
|
|
1432
|
+
* the page that frames it loads. Sent once. `components` are the screens:
|
|
1433
|
+
* `documents` (the default), `send` (00789), `templates` (00791), and
|
|
1434
|
+
* `settings` and `texting` (00792). Mount it with `@signsealer/embed`.
|
|
1288
1435
|
*/
|
|
1289
1436
|
embedSession(id, session) {
|
|
1290
1437
|
return this.#send("POST", `/v1/partner/businesses/${encodeURIComponent(id)}/sessions`, session, false);
|