@signsealer/sdk 1.19.0 → 1.25.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 CHANGED
@@ -1,5 +1,146 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.25.0
4
+
5
+ Nothing that worked before changes.
6
+
7
+ ### Added
8
+
9
+ - The client says what it is: `User-Agent: signsealer-sdk/<version> (node)` on
10
+ every call a `SignSealer` or `SignSealerPartner` client makes from a server,
11
+ so a request can be traced to the library and version that sent it.
12
+ `userAgent` in the client's options names your own integration instead, and
13
+ `""` sends none. Nothing is sent from a browser, which sets its own.
14
+ `SDK_VERSION` is exported.
15
+
16
+ - For a partner on a Platform agreement (00751), on `SignSealerPartner`:
17
+ `createBusiness()` makes a business of your own (its terms acceptance as
18
+ you took it is required; with an `external_id` it is safe to retry, and one
19
+ already made comes back with `existing: true`), `managedBusinesses()`,
20
+ `managedBusiness(id)` and `updateBusiness(id, changes)`.
21
+ - `partnerKey` on `SignSealerPartner`, a key from your partner dashboard
22
+ (`ss_partner_…`), in place of the client id and secret.
23
+ - `SignSealerPartner.business(id)`: a `SignSealer` client that acts for one of
24
+ your businesses, by its id or your `external_id`, with your partner key.
25
+ The same as `new SignSealer({ apiKey: partnerKey, business: id })`.
26
+ - `balance()` on `SignSealerPartner` (00752): the prepaid balance your
27
+ businesses draw on, its grace period, this month by business, and the
28
+ latest entries. `membership` on `createBusiness()`; `status`, `membership`
29
+ and `spend_cap_cents` on `updateBusiness()`; `membership`,
30
+ `spend_cap_cents` and `month_to_date_cents` on a `ManagedBusiness`.
31
+ - `terms_version` and `terms_url` on `profile()`, `terms` on a
32
+ `ManagedBusiness` (what it accepted, and a newer version due), and `terms`
33
+ on `updateBusiness()` to record its acceptance of a newer version (00756).
34
+ - Your prices to your businesses (00759): `prices()` and `setPrices()` for
35
+ your default, `prices` on `updateBusiness()` for one business; gift credit
36
+ with `giveCredit(id, { cents, expires_at, note, idempotencyKey })`, and
37
+ `gift_credit` and `prices` on a `ManagedBusiness`; `usage(month)`, a month
38
+ per business in your prices with what is left to bill.
39
+ - One webhook endpoint for every business you made (00760): `webhooks()`,
40
+ `addWebhook()` (its secret, once), `updateWebhook()`, `deleteWebhook()`,
41
+ `webhookDeliveries()` and `replayWebhookDelivery()` on `SignSealerPartner`;
42
+ each delivery carries `business_id` and your `external_id`.
43
+ - A test partner key (`ss_partner_test_…`, 00761) as `partnerKey`: everything
44
+ happens in your sandbox, whose businesses send nothing and are not billed;
45
+ `sandbox` on a `ManagedBusiness`.
46
+ - `embedSession(id, { user, components })` on `SignSealerPartner` (00763): a
47
+ start link to a business's Documents screen inside your own product, for one
48
+ of your users, to load in an iframe on your page.
49
+
50
+ ## 1.24.0
51
+
52
+ Nothing that worked before changes, except where a text goes.
53
+
54
+ ### Added
55
+
56
+ - `countries` on `account().texting` (00732): where a text goes, `["US", "CA"]`,
57
+ with `"GB"` while texting UK mobiles is on. Texts go only to US and Canadian
58
+ numbers for now: not every +1 number (the Caribbean, the US territories,
59
+ toll-free and premium codes are not texted) and nowhere else. A mobile
60
+ outside those is kept and not texted; the link goes to the signer's email.
61
+ A signer with only such a mobile is refused by `send()` with 422, naming them.
62
+ - `country` as `why_not` on `smsConsent()`: a number outside the US and
63
+ Canada, which is not texted whatever the consent.
64
+
65
+ ## 1.23.0
66
+
67
+ Nothing that worked before changes.
68
+
69
+ ### Added
70
+
71
+ - `signed` on what `voidPacket()` answers (00724): the documents the void kept
72
+ because they were executed, each by `document_id` and `title`. A document
73
+ whose closing signature was being written while the void ran is waited
74
+ for, then kept and named; before, the void of the whole packet failed.
75
+
76
+ ## 1.22.0
77
+
78
+ Nothing that worked before changes.
79
+
80
+ ### Added
81
+
82
+ - `blank` on a template question (`Ask`, 00699): the answer fills the blank
83
+ of the same name in a written template's text, `{{plate}}` for `plate`.
84
+ A send may leave that blank out of `values`; the first signer answers it,
85
+ and their signature writes it into the text before it is fingerprinted.
86
+ - `recipient` on `Ask` (00685): the one signer a question is for, by their
87
+ `sign_order`. The engine already kept it; `POST /v1/templates` now does too.
88
+
89
+ ## 1.21.0
90
+
91
+ Nothing that worked before changes.
92
+
93
+ ### Added
94
+
95
+ - A partner's platform may text its businesses' signers itself (00692).
96
+ The partner decides on its dashboard: SignSealer texts them (as before,
97
+ and every partner's starting point), the partner does, or each business
98
+ chooses. For documents sent through the partner's app with a business's
99
+ access token, when the answer is the partner or nobody, SignSealer sends
100
+ no texts: no link, no reminder, no confirmation. Email and webhooks are
101
+ unchanged, and a one-time code a signer asks for is still sent.
102
+ - `setTextingSender(sender, clientId?)`: `PUT /v1/texting/sender`, the
103
+ business's choice where the partner leaves it to each business. With
104
+ the partner's own access token, `clientId` is left out. Type
105
+ `TextingSenderChoice`.
106
+ - `texting.sender` on `account()`: who texts the signers of what this key
107
+ sends. Type `TextingSender`.
108
+ - A partner client made from the partner form may now ask a business for
109
+ `signing:workflows` and `signing:webhooks` as well as `signing:read` and
110
+ `signing:write`.
111
+
112
+ ## 1.20.0
113
+
114
+ Nothing that worked before changes.
115
+
116
+ ### Added
117
+
118
+ - "Connect with SignSealer" for a partner's server (00090, 00207):
119
+ `SignSealerOAuth`, made with your OAuth client's `clientId` and
120
+ `clientSecret`.
121
+ - `createPkce()` makes a verifier and its S256 challenge, and
122
+ `pkceChallenge()` works out the challenge for a verifier, in WebCrypto
123
+ (Node 18 through `node:crypto`, every edge runtime).
124
+ - `authorizeUrl({ redirectUri, scopes, state, codeChallenge })` is where to
125
+ send the business's browser; `callback(query, state)` reads the answer,
126
+ checks `state` and gives the code.
127
+ - `exchangeCode({ code, redirectUri, codeVerifier })` and
128
+ `refresh(refreshToken)` post to `/oauth/token` as a form, the client by
129
+ HTTP Basic. The answer is the endpoint's, with `expires_at` (absolute)
130
+ and `scopes` (what the business actually gave) added. The access token
131
+ is an API key: `new SignSealer({ apiKey: tokens.access_token })`.
132
+ - **Neither is ever sent twice.** A refresh token or a code presented
133
+ again is treated as stolen and ends the connection, so these two calls
134
+ do not retry the way every other call in this package does. Serialise
135
+ refreshes per grant, and store the new refresh token before using the
136
+ access token.
137
+ - `SignSealerOAuthError`, a `SignSealerError` whose `error` and
138
+ `errorDescription` are RFC 6749's. `reconnect` is true for
139
+ `invalid_grant` (send the business through `authorizeUrl` again);
140
+ `transient` for the network, a `429` or a `5xx`, after which a
141
+ refresh token's state is unknown. `retryable` is always false.
142
+ - Types `OAuthOptions`, `OAuthScope`, `OAuthTokens` and `Pkce`.
143
+
3
144
  ## 1.19.0
4
145
 
5
146
  Nothing that worked before changes.
package/README.md CHANGED
@@ -573,6 +573,237 @@ changed since it was issued. That is reported and never corrected — a
573
573
  verification service that quietly re-derived could not answer the one question
574
574
  it exists for.
575
575
 
576
+ ## Connecting a business with one click (OAuth)
577
+
578
+ When your product acts for *other* businesses' SignSealer accounts, they
579
+ connect it on SignSealer's consent screen rather than pasting you a key
580
+ (1.20.0). `SignSealerOAuth` is the partner's half: authorization code with
581
+ PKCE (S256, which SignSealer requires of every client), on your server,
582
+ with your OAuth client's id and secret. What comes back is an API key for
583
+ that one business, limited to what it agreed to.
584
+
585
+ **Send the business to SignSealer.** Make a PKCE pair and a `state` for each
586
+ attempt, keep both on your server, and redirect:
587
+
588
+ ```ts
589
+ import { SignSealerOAuth, createPkce } from "@signsealer/sdk";
590
+
591
+ const oauth = new SignSealerOAuth({
592
+ clientId: process.env.SIGNSEALER_CLIENT_ID!, // ss_client_…
593
+ clientSecret: process.env.SIGNSEALER_CLIENT_SECRET!, // ss_secret_…, server only
594
+ });
595
+ const REDIRECT = "https://pos.example.com/oauth/signsealer"; // exactly as registered
596
+
597
+ app.get("/connect/signsealer", async (req, res) => {
598
+ const { verifier, challenge } = await createPkce();
599
+ const state = crypto.randomUUID();
600
+ await attempts.put(state, { verifier, tenantId: req.user.tenantId }, { ttlSeconds: 1800 });
601
+ res.redirect(oauth.authorizeUrl({
602
+ redirectUri: REDIRECT,
603
+ scopes: ["signing:read", "signing:write", "signing:workflows", "signing:webhooks"],
604
+ state,
605
+ codeChallenge: challenge,
606
+ }));
607
+ });
608
+ ```
609
+
610
+ Keep the attempt for half an hour, not a minute: a business with no
611
+ SignSealer account can make one on the way, name its business and agree to
612
+ the terms, and SignSealer brings it back to the consent screen afterwards.
613
+
614
+ **The callback.** `callback` checks the `state` and gives you the code, or
615
+ throws the consent screen's error (`access_denied` when they pressed Not now).
616
+ Exchange the code at once: it lives sixty seconds and is good once.
617
+
618
+ ```ts
619
+ import { SignSealer, SignSealerOAuthError } from "@signsealer/sdk";
620
+
621
+ app.get("/oauth/signsealer", async (req, res) => {
622
+ const attempt = await attempts.take(String(req.query.state ?? "")); // read once, then deleted
623
+ if (!attempt) return res.status(400).send("That connection has expired. Start again.");
624
+ try {
625
+ const { code } = oauth.callback(req.url, req.query.state as string);
626
+ const tokens = await oauth.exchangeCode({ code, redirectUri: REDIRECT, codeVerifier: attempt.verifier });
627
+ const account = await new SignSealer({ apiKey: tokens.access_token }).account();
628
+ await db.signsealer.upsert({
629
+ tenantId: attempt.tenantId,
630
+ businessId: account.tenant_id,
631
+ accessToken: seal(tokens.access_token), // encrypted at rest, never logged
632
+ refreshToken: seal(tokens.refresh_token!),
633
+ expiresAt: tokens.expires_at,
634
+ scopes: tokens.scopes, // what they gave, which can be less than you asked
635
+ needsReconnect: false,
636
+ });
637
+ res.redirect("/settings/signing?connected=1");
638
+ } catch (e) {
639
+ if (e instanceof SignSealerOAuthError) return res.redirect(`/settings/signing?error=${e.error}`);
640
+ throw e;
641
+ }
642
+ });
643
+ ```
644
+
645
+ `tokens.scopes` is what the business actually granted. A grant never holds
646
+ more than the person who made it may do themselves, so check it before
647
+ offering a feature that needs a scope you asked for.
648
+
649
+ **Refresh, one at a time.** An access token lives an hour; refresh it a
650
+ little before `expires_at`. **The SDK never retries a refresh, and neither
651
+ should you.** Each refresh token is good once: the answer carries the next
652
+ one, and presenting a spent one revokes the whole connection, every token
653
+ under it, and the business has to connect again. So serialise refreshes per
654
+ business, and store the new refresh token before using the new access token,
655
+ inside the same lock:
656
+
657
+ ```ts
658
+ async function clientFor(tenantId: string): Promise<SignSealer> {
659
+ return db.transaction(async (tx) => {
660
+ const row = await tx.signsealer.forUpdate(tenantId); // the lock: one refresh per grant
661
+ if (row.needsReconnect) throw new NeedsReconnect(tenantId);
662
+ if (Date.parse(row.expiresAt) - Date.now() > 5 * 60_000) {
663
+ return new SignSealer({ apiKey: unseal(row.accessToken) });
664
+ }
665
+ try {
666
+ const t = await oauth.refresh(unseal(row.refreshToken));
667
+ await tx.signsealer.update(tenantId, { // stored before it is used
668
+ accessToken: seal(t.access_token), refreshToken: seal(t.refresh_token!),
669
+ expiresAt: t.expires_at, scopes: t.scopes,
670
+ });
671
+ return new SignSealer({ apiKey: t.access_token });
672
+ } catch (e) {
673
+ if (e instanceof SignSealerOAuthError && e.reconnect) {
674
+ await tx.signsealer.update(tenantId, { needsReconnect: true });
675
+ throw new NeedsReconnect(tenantId);
676
+ }
677
+ throw e; // e.transient: see below. Never a loop.
678
+ }
679
+ });
680
+ }
681
+ ```
682
+
683
+ `SignSealerOAuthError` carries RFC 6749's `error` and `errorDescription`, and
684
+ two flags that decide what happens next:
685
+
686
+ - **`reconnect`**: `invalid_grant`. The business disconnected you, the person
687
+ who connected you left or can no longer give what you hold, or a token was
688
+ used twice. Ask the business to connect again.
689
+ - **`transient`**: the network, a `429` or a `5xx`. The connection may well
690
+ be fine, but **whether the refresh token was spent is unknown**: if the
691
+ request arrived and the answer was lost, it is spent and its successor went
692
+ with the answer. Sending it once more, later and under the same lock,
693
+ either works or ends the connection, which losing the successor had
694
+ already made certain. That is a decision for your code to make knowingly,
695
+ not a retry loop.
696
+
697
+ `invalid_client` is neither: your client id or secret was refused, which is
698
+ your configuration and affects every business at once. `retryable` is
699
+ `false` on every OAuth error.
700
+
701
+ **A `401` from the API means reconnect.** A business can end the connection at
702
+ any moment, and its tokens stop working that minute, not at the end of the
703
+ hour. Refreshing ahead of `expires_at` means an unexpired token answered `401`
704
+ has been revoked:
705
+
706
+ ```ts
707
+ try {
708
+ await (await clientFor(tenantId)).send(documentId, signers);
709
+ } catch (e) {
710
+ if (e instanceof SignSealerError && e.status === 401) {
711
+ await db.signsealer.update(tenantId, { needsReconnect: true }); // show "Reconnect SignSealer"
712
+ } else throw e;
713
+ }
714
+ ```
715
+
716
+ The [OAuth reference](https://signsealer.com/docs/authentication) has the
717
+ endpoints themselves.
718
+
719
+ ## Onboarding a business
720
+
721
+ What to ask for, and what a business needs in place before signing works
722
+ inside your product.
723
+
724
+ **Scopes.** Ask for the fewest that do the job; a consent screen that asks
725
+ for everything is one people decline. For e-signing and waivers:
726
+
727
+ | Scope | Why you need it |
728
+ | --- | --- |
729
+ | `signing:read` | `account()` (including `frame_origins`), documents, signers, PDFs and certificates, the list of workflows |
730
+ | `signing:write` | prepare and `send()` documents, `embedLink()`, remind, void. If your client was registered with its parts, `signing:send` and `signing:links` are the minimum |
731
+ | `signing:workflows` | `startWorkflow()`: a waiver from one of the business's forms |
732
+ | `signing:webhooks` | `ensureWebhook()` on the business, to hear `signing.completed` rather than poll |
733
+
734
+ Add `signing:subjects` only if you sync reservations and their packets
735
+ (`upsertReservation`, `startPacket`), and `signing:templates` only if you
736
+ make templates or use `documentFromPdf()`. Your client can ask only for the
737
+ scopes SignSealer registered it with, and anything else comes back as
738
+ `error=invalid_scope`. A client made from the partner form is registered with
739
+ `signing:read`, `signing:write`, `signing:workflows` and `signing:webhooks`
740
+ (1.21.0); write to partners@signsealer.com for the others. The person pressing Connect must be able to manage API keys on that
741
+ business (an owner or admin, unless given it), and a scope they could not
742
+ use themselves is left out of the grant.
743
+
744
+ **Where the signing page can be framed.** An embedded signing page
745
+ (`delivery: "embedded"`, then `embedLink()`) shows only inside a site the
746
+ business has proven is its own; anywhere else the browser leaves the frame
747
+ empty. `frame_origins` on `account()` and on each `embedLink()` lists them:
748
+
749
+ ```ts
750
+ const { frame_origins } = await client.account();
751
+ // ["https://pos.example.com", "https://dockside.example", "https://*.dockside.example"]
752
+ ```
753
+
754
+ There are three ways onto that list:
755
+
756
+ - **Your app, once connected.** The host of each of your redirect addresses
757
+ is added for every business that connects you, exactly that host and no
758
+ other. Register a redirect on the host your product frames the page on and
759
+ embedded signing there works with nothing for the business to do.
760
+ - **A company sign-in domain** the business proves in the dashboard under
761
+ [Settings → Single sign-on](https://app.signsealer.com/settings/sso): that
762
+ domain and every host under it, which is how a page on its own main site
763
+ qualifies.
764
+ - **A signing domain** it verifies under
765
+ [Settings → Your own domains](https://app.signsealer.com/settings#domains)
766
+ (with white label): that host and the hosts under it.
767
+
768
+ Check `frame_origins` before showing a frame, and open the link in a new tab
769
+ when the page's site is not on it. The owner-facing steps are in the help
770
+ pages, not here: [Signing inside your product](https://signsealer.com/docs/embedding),
771
+ [Branding and your own domains](https://signsealer.com/docs/branding), and
772
+ [Teams, roles and sign-in](https://signsealer.com/docs/teams) for who may
773
+ connect an app and where a business sees and ends it (Integrations →
774
+ Connected apps).
775
+
776
+ **Who texts the signers.** SignSealer texts a signer the link and one
777
+ reminder where it holds their consent. Your platform may do that instead
778
+ (1.21.0): on your partner dashboard choose SignSealer, your platform, or each
779
+ business. For documents sent with a business's access token, when the answer
780
+ is your platform or nobody, SignSealer sends those signers no texts at all,
781
+ reminders included; email goes as before, and the webhooks are how you hear
782
+ what to text. A one-time code a signer asks for is always sent by SignSealer.
783
+
784
+ ```ts
785
+ const { texting } = await client.account();
786
+ texting?.sender; // "partner": text the links yourself; "signsealer": we do; "none": nobody does
787
+
788
+ // Where your dashboard leaves it to each business, record its answer with its token:
789
+ await client.setTextingSender("partner");
790
+ ```
791
+
792
+ When `texting.sender` is `partner`, the business needs no texting number of
793
+ its own for these documents, so do not show it `textingNumberInvitation`.
794
+
795
+ **A business with no account yet.** It can make one from the consent screen
796
+ itself, as above, and the emailed link brings it back to your consent screen
797
+ even when it is opened on another device. To send one to SignSealer first, with the business counted
798
+ as yours, use your signup link:
799
+
800
+ ```ts
801
+ import { SignSealerPartner } from "@signsealer/sdk";
802
+
803
+ SignSealerPartner.signupUrl("deckpos");
804
+ // "https://app.signsealer.com/signup?partner=deckpos"
805
+ ```
806
+
576
807
  ## For partners: what you have earned
577
808
 
578
809
  A platform SignSealer has enrolled as a partner shares in the revenue of every