@signsealer/sdk 1.16.0 → 1.22.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.
@@ -138,8 +138,28 @@ export interface Account {
138
138
  * applied. Each step is also sent as `texting.number_updated`.
139
139
  */
140
140
  application?: TextingApplication | null;
141
+ /**
142
+ * Who texts the signers of documents this key sends (1.21.0):
143
+ * `signsealer` for the business's own keys; for a partner's access
144
+ * token, the partner's answer -- `partner` (your platform texts them and
145
+ * SignSealer sends none), `none`, or `signsealer`.
146
+ */
147
+ sender?: TextingSender;
141
148
  };
142
149
  }
150
+ /** Who texts a document's signers (1.21.0). */
151
+ export type TextingSender = "signsealer" | "partner" | "none";
152
+ /** A business's choice of who texts for one partner app (1.21.0), as `setTextingSender` answers it. */
153
+ export interface TextingSenderChoice {
154
+ /** The app, `ss_client_…`. */
155
+ client_id: string;
156
+ name: string;
157
+ mode: "business_choice";
158
+ /** What the business chose. */
159
+ choice: TextingSender;
160
+ /** What applies now. */
161
+ sender: TextingSender;
162
+ }
143
163
  /** Where a business's texting-number application has got to (1.13.0), as the account and `texting.number_updated` say. */
144
164
  export interface TextingApplication {
145
165
  /** `applied`, `submitted`, `in_review`, `needs_changes`, `verified`, `paused`, `failed`, and the steps of bringing a number. */
@@ -355,6 +375,14 @@ export interface Ask {
355
375
  block_step?: boolean | null;
356
376
  /** Where it is answered on an uploaded PDF's page (00243), in fractions of the page. */
357
377
  place?: Place | null;
378
+ /** The one signer this question is for, by their `sign_order` (00685); absent, every signer's. */
379
+ recipient?: number | null;
380
+ /**
381
+ * The answer fills the blank of the same name in a written template's text
382
+ * (00699): `{{plate}}` for `plate`. A send may leave it out of `values`;
383
+ * the first signer answers it and their signature writes it in.
384
+ */
385
+ blank?: boolean | null;
358
386
  }
359
387
  /**
360
388
  * A rule about an answer, exactly one of these (00373, 00375): `equals` for a
@@ -586,6 +614,8 @@ export interface SignerLink {
586
614
  delivery?: "send" | "embedded";
587
615
  /** The person who signs for the business, and answers its own questions (1.16.0, 00611). */
588
616
  for_business?: boolean;
617
+ /** Signed only by an approval from the application it was bound to (1.18.0, 00684); it has no link. */
618
+ application_bound?: true;
589
619
  }
590
620
  /** Who has signed one document (00340): names and states, nothing else. */
591
621
  export interface DocumentSigners {
@@ -771,12 +801,16 @@ export interface Workflow {
771
801
  template_code?: string;
772
802
  template_published: boolean;
773
803
  public_slug?: string | null;
774
- /** 00541: with what each question is, when it is not words, so a signer's condition can be about it. */
804
+ /**
805
+ * 00541: with what each question is, when it is not words, so a signer's
806
+ * condition can be about it. `address` (1.17.0, 00654): asked on the public
807
+ * form as street, city, state or region and ZIP, and written as one line.
808
+ */
775
809
  form_fields: Array<{
776
810
  key: string;
777
811
  label: string;
778
812
  required?: boolean;
779
- kind?: "text" | "email" | "phone" | "checkbox" | "choice" | "number" | "date" | "birthdate" | "time" | "datetime";
813
+ kind?: "text" | "email" | "phone" | "address" | "checkbox" | "choice" | "number" | "date" | "birthdate" | "time" | "datetime";
780
814
  options?: string[];
781
815
  }>;
782
816
  /** Every blank a person starting it is asked (00478); `sender_fields` are the boxes whoever sends it fills. */
@@ -798,8 +832,41 @@ export interface Workflow {
798
832
  party_ages?: "tick" | "dob";
799
833
  majority_age?: number;
800
834
  minors_also_sign?: boolean;
835
+ /** 1.17.0 (00670): one document the party shares, or a document for each person, each its own signing. */
836
+ party_documents?: "one" | "each";
801
837
  /** 00476: the zone its documents' times are written in. */
802
838
  time_zone?: string | null;
839
+ /**
840
+ * 1.17.0 (00654): a visitor who signs from the public address confirms the
841
+ * email they typed with a code first. Free, and not the one-time passcodes
842
+ * setting. A start through the API or a tablet is not asked.
843
+ */
844
+ email_check?: boolean;
845
+ /**
846
+ * 1.17.0 (00654): the public address's limits, which a start through the
847
+ * API or a tablet is neither stopped by nor counted toward: stop after so
848
+ * many documents started from the address are signed; stop after a day
849
+ * (`YYYY-MM-DD`, on the form's own calendar); and the same email within so
850
+ * many days is emailed its signed copy again instead of a new document.
851
+ * Null is no limit.
852
+ */
853
+ stop_after_signed?: number | null;
854
+ closes_on?: string | null;
855
+ once_within_days?: number | null;
856
+ /** 1.17.0 (00654): why the public address takes no more signatures, in a visitor's words; null while it does. */
857
+ closed?: string | null;
858
+ /**
859
+ * 1.17.0 (00654): a live public address that fails a check of its
860
+ * pre-flight: the first such check, in words, and whether visitors are
861
+ * stopped by it (told the form is not ready) or sign as before, with only a
862
+ * change to the form waiting for the fix. Null while it passes.
863
+ */
864
+ needs_attention?: {
865
+ key: string;
866
+ says: string;
867
+ fix: string | null;
868
+ stops_visitors: boolean;
869
+ } | null;
803
870
  }
804
871
  export interface ClientOptions {
805
872
  /**
@@ -996,6 +1063,19 @@ export declare class SignSealer {
996
1063
  * nobody was handed. If the answer is lost, ask again when you need one.
997
1064
  */
998
1065
  textingNumberInvitation(prefill?: TextingNumberPrefill): Promise<TextingNumberInvitation>;
1066
+ /**
1067
+ * Who texts the signers of documents sent through a partner's app, for a
1068
+ * partner whose dashboard leaves it to each business (1.21.0).
1069
+ *
1070
+ * As the partner, with the business's access token, leave `clientId` out:
1071
+ * the choice is yours for that business. With the business's own key, name
1072
+ * the app by its `ss_client_…` id (the key needs `signing:webhooks`). With
1073
+ * `partner` or `none`, SignSealer sends no texts for those documents -- no
1074
+ * link, no reminder, no confirmation -- while email and webhooks go on as
1075
+ * before; a one-time code a signer asks for is still sent. A PUT, so a
1076
+ * retry after a lost answer sets the same thing again.
1077
+ */
1078
+ setTextingSender(sender: TextingSender, clientId?: string): Promise<TextingSenderChoice>;
999
1079
  /**
1000
1080
  * Documents, filtered and paged.
1001
1081
  *
@@ -1092,6 +1172,29 @@ export declare class SignSealer {
1092
1172
  }, idempotencyKey?: string): Promise<{
1093
1173
  document_id: string;
1094
1174
  }>;
1175
+ /**
1176
+ * A document from a PDF and the places to sign it, in one call (1.19.0,
1177
+ * 00685): the file is read, sanitised and drawn as a dashboard upload is,
1178
+ * kept as a one-time template, and the document prepared as a draft.
1179
+ * Each box is one `recipient`'s -- the `sign_order` you give that signer
1180
+ * on `send()` -- given in `fields` (fractions of the page, from its
1181
+ * top-left) or found from text tags in the file's words with
1182
+ * `text_tags: true` (`{{signature:1}}`, `{{date:1}}`, `{{initials:2}}`,
1183
+ * `{{text:1:Job number}}`, `{{checkbox:2:Label}}`). Needs `signing:templates`
1184
+ * and `signing:send` on the key. `pdf` is the file's bytes or its base64.
1185
+ */
1186
+ documentFromPdf(input: {
1187
+ title: string;
1188
+ pdf: Uint8Array | string;
1189
+ filename?: string;
1190
+ fields?: PdfBox[];
1191
+ text_tags?: boolean;
1192
+ expires_at?: string;
1193
+ sequential?: boolean;
1194
+ external_ref?: string;
1195
+ metadata?: Record<string, string>;
1196
+ return_url?: string;
1197
+ }, idempotencyKey?: string): Promise<DocumentFromPdf>;
1095
1198
  /**
1096
1199
  * Send, and take the links back once.
1097
1200
  *
@@ -1117,6 +1220,17 @@ export declare class SignSealer {
1117
1220
  * date and name on an uploaded PDF -- are theirs, and nobody else's.
1118
1221
  */
1119
1222
  for_business?: boolean;
1223
+ /**
1224
+ * This line is signed by an approval from the business's own
1225
+ * application, as this one of its people (1.18.0, 00684): `id` is the
1226
+ * application's, `subject` your id for the person, as your approvals
1227
+ * name them in `sub`. Needs `delivery: "embedded"`. The line gets no
1228
+ * link: its `token` and `url` are null and `application_bound` true.
1229
+ */
1230
+ application?: {
1231
+ id: string;
1232
+ subject: string;
1233
+ };
1120
1234
  }>, idempotencyKey?: string): Promise<{
1121
1235
  links: SignerLink[];
1122
1236
  }>;
@@ -1244,6 +1358,18 @@ export declare class SignSealer {
1244
1358
  webhooks(): Promise<{
1245
1359
  endpoints: unknown;
1246
1360
  }>;
1361
+ /**
1362
+ * Make sure an endpoint is registered for an address (1.19.0, 00685): the
1363
+ * business's endpoint for `url`, its events and label set to these, or a
1364
+ * new one when it has none -- so calling it on every start-up never makes
1365
+ * a second. `created` says which; `secret` is there only when it is new.
1366
+ * An endpoint the business turned off stays off (`active`, `paused`).
1367
+ */
1368
+ ensureWebhook(input: {
1369
+ url: string;
1370
+ events?: string[];
1371
+ label?: string;
1372
+ }): Promise<EnsuredWebhook>;
1247
1373
  addWebhook(input: {
1248
1374
  url: string;
1249
1375
  events?: string[];
@@ -1415,6 +1541,62 @@ export declare class SignSealer {
1415
1541
  report_id: string;
1416
1542
  device_id: string;
1417
1543
  }>;
1544
+ /**
1545
+ * The business's own applications whose servers vouch for their people's
1546
+ * approvals, each with its public keys (00684). Needs `signing:applications`.
1547
+ */
1548
+ signingApplications(): Promise<SigningApplication[]>;
1549
+ /** Register an application. Then register the public key it signs approvals with. */
1550
+ addSigningApplication(name: string, idempotencyKey?: string): Promise<SigningApplication>;
1551
+ /**
1552
+ * Register a public key, as a JWK: EC P-256 for ES256, OKP Ed25519 for
1553
+ * EdDSA. Only the public half; one with `d` is refused. `kid` defaults to
1554
+ * the key's RFC 7638 thumbprint.
1555
+ */
1556
+ addSigningApplicationKey(applicationId: string, input: {
1557
+ public_jwk: {
1558
+ kty: "EC" | "OKP";
1559
+ crv: "P-256" | "Ed25519";
1560
+ x: string;
1561
+ y?: string;
1562
+ };
1563
+ kid?: string;
1564
+ expires_at?: string;
1565
+ }, idempotencyKey?: string): Promise<SigningApplication>;
1566
+ /** Revoke a key: every approval it signed and has not sent is refused from now on. */
1567
+ revokeSigningApplicationKey(applicationId: string, keyId: string, reason: string): Promise<SigningApplication>;
1568
+ /** Disable an application: every approval from it is refused from now on. */
1569
+ disableSigningApplication(applicationId: string, reason: string): Promise<SigningApplication>;
1570
+ /**
1571
+ * Hand over one person's saved signature for one signing, server to
1572
+ * server (00684). The reference is single-use, short-lived and bound to
1573
+ * the application and the person; the image is never served back.
1574
+ * Possession of the reference authorises nothing on its own: only an
1575
+ * approval from the same application naming the same person, with
1576
+ * `signature.sha256` equal to `sha256` here, spends it. Needs
1577
+ * `signing:assert`.
1578
+ */
1579
+ addSignatureReference(input: {
1580
+ application_id: string;
1581
+ subject: string;
1582
+ image: string;
1583
+ ttl_seconds?: number;
1584
+ }): Promise<SignatureReference>;
1585
+ /**
1586
+ * Sign with an approval your application's server signed (`createApproval`).
1587
+ * Recorded as authenticated by your application, never as an identity
1588
+ * SignSealer checked. The same approval sent again answers with the
1589
+ * signing it made (`replayed: true`); retried with the same idempotency
1590
+ * key, the stored answer. Needs `signing:assert`.
1591
+ */
1592
+ signWithApproval(input: {
1593
+ assertion: string;
1594
+ signature: ApprovalSignature;
1595
+ }, idempotencyKey?: string): Promise<SigningTransaction>;
1596
+ /** One signing an approval made. */
1597
+ signingTransaction(id: string): Promise<SigningTransaction>;
1598
+ /** The signing an approval made, by your application's id and the approval's `jti`: for a client that lost the answer. */
1599
+ signingTransactionByApproval(applicationId: string, approvalId: string): Promise<SigningTransaction>;
1418
1600
  }
1419
1601
  export interface SigningLink {
1420
1602
  ok: boolean;
@@ -2180,6 +2362,184 @@ export declare class SignSealerPartner {
2180
2362
  /** Every closed month, newest first. */
2181
2363
  statements(): Promise<PartnerStatement[]>;
2182
2364
  }
2365
+ /** What a partner's app may ask a business for. Your client is registered with a subset; ask for no more than that. */
2366
+ export type OAuthScope = "signing:read" | "signing:write" | "signing:templates" | "signing:workflows" | "signing:webhooks" | "signing:subjects" | "signing:send" | "signing:remind" | "signing:links" | "signing:void";
2367
+ export interface OAuthOptions {
2368
+ /** Your OAuth client's id, `ss_client_…`. */
2369
+ clientId: string;
2370
+ /** Its secret, `ss_secret_…`: shown once, when the client was made or a new one was made on your partner dashboard. */
2371
+ clientSecret: string;
2372
+ /** Where `/oauth/authorize` and `/oauth/token` are. Default `https://api.signsealer.com`. */
2373
+ baseUrl?: string;
2374
+ fetch?: typeof globalThis.fetch;
2375
+ }
2376
+ /** A PKCE pair (RFC 7636): keep `verifier` for the exchange, send `challenge` to authorise. */
2377
+ export interface Pkce {
2378
+ verifier: string;
2379
+ challenge: string;
2380
+ method: "S256";
2381
+ }
2382
+ /**
2383
+ * The token endpoint's answer, as it sends it, with two additions.
2384
+ *
2385
+ * `access_token` is an API key (`mk_live_…`): hand it to `new SignSealer({
2386
+ * apiKey })`. `scopes` is `scope` split, and it is what the business
2387
+ * actually gave, which can be less than you asked for: a grant never holds
2388
+ * more than the person who made it may do. `expires_at` is absolute, worked
2389
+ * out from the moment the request was sent, so it errs early.
2390
+ */
2391
+ export interface OAuthTokens {
2392
+ access_token: string;
2393
+ token_type: "Bearer";
2394
+ /** Seconds the access token lives: an hour. */
2395
+ expires_in: number;
2396
+ /** When the access token stops working, as an ISO time. */
2397
+ expires_at: string;
2398
+ scope: string;
2399
+ scopes: string[];
2400
+ /** Good once, for thirty days. Store it before you use `access_token`. Null for a client that is given none. */
2401
+ refresh_token: string | null;
2402
+ }
2403
+ /**
2404
+ * A refusal from the OAuth endpoints, or from the consent screen's answer.
2405
+ *
2406
+ * `code` is RFC 6749's `error` and `message` its `error_description` (both
2407
+ * also under their RFC names). Two questions decide what to do:
2408
+ *
2409
+ * - `reconnect`: the grant is over, or the code is spent. `invalid_grant`
2410
+ * -- the business disconnected you, the person who connected you can no
2411
+ * longer give what you hold, a token or code was used twice, or it
2412
+ * expired. Send the business through `authorizeUrl` again; nothing else
2413
+ * will bring it back.
2414
+ * - `transient`: the network or SignSealer, not your request. The grant may
2415
+ * well still be good. On a refresh, **whether the token was spent is
2416
+ * unknown**: read `refresh()` before deciding to send it again.
2417
+ *
2418
+ * `invalid_client` is neither: your client id or secret did not
2419
+ * authenticate, which is your configuration, for every business at once.
2420
+ *
2421
+ * `retryable` is always false. SignSealerError's "worth trying again
2422
+ * unchanged" is exactly the advice that turns a lost answer into a revoked
2423
+ * grant here.
2424
+ */
2425
+ export declare class SignSealerOAuthError extends SignSealerError {
2426
+ constructor(status: number, code: string, message: string, requestId?: string, retryAfter?: number);
2427
+ /** RFC 6749's name for `code`. */
2428
+ get error(): string;
2429
+ /** RFC 6749's name for `message`. */
2430
+ get errorDescription(): string;
2431
+ get retryable(): boolean;
2432
+ /** The grant is over or the code spent: send the business to connect again. */
2433
+ get reconnect(): boolean;
2434
+ /** The network or SignSealer failed, not the request. On a refresh, the token may or may not have been spent. */
2435
+ get transient(): boolean;
2436
+ }
2437
+ /**
2438
+ * A fresh PKCE pair, one per authorise request: 32 random bytes as a
2439
+ * 43-character verifier, and its S256 challenge.
2440
+ *
2441
+ * Keep the verifier on your server, against the `state` you send (a
2442
+ * session, or a short-lived row), and give it to `exchangeCode`. Never put
2443
+ * it in the authorise address: the challenge goes there, and the verifier
2444
+ * is what proves the code came back to the same party that asked.
2445
+ */
2446
+ export declare function createPkce(): Promise<Pkce>;
2447
+ /** The S256 challenge for a verifier: base64url of its SHA-256, without padding (RFC 7636, section 4.2). */
2448
+ export declare function pkceChallenge(verifier: string): Promise<string>;
2449
+ /**
2450
+ * "Connect with SignSealer", for a partner's server (1.20.0).
2451
+ *
2452
+ * ```ts
2453
+ * const oauth = new SignSealerOAuth({ clientId, clientSecret });
2454
+ * const { verifier, challenge } = await createPkce();
2455
+ * redirect(oauth.authorizeUrl({ redirectUri, scopes: ["signing:read", "signing:write"], state, codeChallenge: challenge }));
2456
+ * // …and on the way back:
2457
+ * const { code } = oauth.callback(request.url, savedState);
2458
+ * const tokens = await oauth.exchangeCode({ code, redirectUri, codeVerifier: verifier });
2459
+ * const client = new SignSealer({ apiKey: tokens.access_token });
2460
+ * ```
2461
+ *
2462
+ * The client is authenticated to `/oauth/token` by HTTP Basic, which RFC
2463
+ * 6749 prefers and the server reads first. Every token request is sent
2464
+ * exactly once: see `refresh()` for why that is the whole point.
2465
+ */
2466
+ export declare class SignSealerOAuth {
2467
+ #private;
2468
+ constructor(opts: OAuthOptions);
2469
+ /**
2470
+ * Where to send the business's browser. SignSealer signs them in (or lets
2471
+ * them make an account and name their business on the way), shows your
2472
+ * registered name and what each scope allows, and sends them back to
2473
+ * `redirectUri` with `code` and your `state`, or with `error`.
2474
+ *
2475
+ * `redirectUri` must be one you registered, byte for byte, and the same
2476
+ * string you give `exchangeCode`. `state` is yours, returned untouched:
2477
+ * make it unguessable, keep it with the verifier, and check it in
2478
+ * `callback`. Ask for the fewest scopes that do the job; a scope your
2479
+ * client was not registered with is refused as `invalid_scope`.
2480
+ */
2481
+ authorizeUrl(opts: {
2482
+ redirectUri: string;
2483
+ scopes: OAuthScope[];
2484
+ state: string;
2485
+ codeChallenge: string;
2486
+ }): string;
2487
+ /**
2488
+ * Read the consent screen's answer from your redirect's query: the code,
2489
+ * once `state` matches the one you kept. A business that pressed Not now
2490
+ * comes back as `access_denied`, and a request the screen could not
2491
+ * answer as its RFC 6749 error; both are thrown as SignSealerOAuthError,
2492
+ * with `status` 400. A `state` that does not match is `state_mismatch`:
2493
+ * do not exchange that code.
2494
+ */
2495
+ callback(query: string | URL | URLSearchParams, expectedState: string): {
2496
+ code: string;
2497
+ };
2498
+ /**
2499
+ * Exchange the code from `callback` for the business's tokens. Do it at
2500
+ * once: a code lives sixty seconds and is good once.
2501
+ *
2502
+ * Sent once and never again. A code presented twice is a replay, and the
2503
+ * server revokes the grant it made, so a retry after a lost answer would
2504
+ * disconnect the business it just connected. If this throws `transient`,
2505
+ * send the business through `authorizeUrl` again.
2506
+ */
2507
+ exchangeCode(opts: {
2508
+ code: string;
2509
+ redirectUri: string;
2510
+ codeVerifier: string;
2511
+ }): Promise<OAuthTokens>;
2512
+ /**
2513
+ * Swap a refresh token for a new access token **and a new refresh token**.
2514
+ *
2515
+ * **THIS IS NEVER RETRIED, AND YOU MUST NOT RETRY IT EITHER WITHOUT
2516
+ * THINKING.** The refresh token you send is spent the moment SignSealer
2517
+ * reads it. Presenting a spent one is treated as theft: the whole family
2518
+ * is revoked -- every refresh token from that connection, the grant, and
2519
+ * every access token issued under it -- and the business has to connect
2520
+ * again. From the server's side a buggy retry and a stolen token look the
2521
+ * same.
2522
+ *
2523
+ * So:
2524
+ *
2525
+ * 1. **Serialise refreshes per grant.** One at a time for each business
2526
+ * (a row lock, an advisory lock, a queue). Two workers refreshing the
2527
+ * same grant at once will end it.
2528
+ * 2. **Store the new refresh token before you use the access token**,
2529
+ * atomically, while still holding the lock. A new refresh token you
2530
+ * lose cannot be got back.
2531
+ * 3. **A `transient` failure leaves the token's state unknown.** If the
2532
+ * request reached SignSealer and the answer was lost, the token you
2533
+ * hold is spent and its successor lost with the answer; if it never
2534
+ * arrived, it is still good. Sending it again either works or ends
2535
+ * the connection (`reconnect`), which losing the successor had
2536
+ * already made inevitable. That is your decision, made under the
2537
+ * lock, never a loop.
2538
+ * 4. **`reconnect` means reconnect.** Mark the business disconnected and
2539
+ * ask them to connect again; do not try the token again.
2540
+ */
2541
+ refresh(refreshToken: string): Promise<OAuthTokens>;
2542
+ }
2183
2543
  export declare const WEBHOOK_EVENT_HEADER = "signsealer-event-id";
2184
2544
  export declare const WEBHOOK_TIMESTAMP_HEADER = "signsealer-timestamp";
2185
2545
  export declare const WEBHOOK_SIGNATURE_HEADER = "signsealer-signature";
@@ -2292,4 +2652,187 @@ export declare function verifyWebhookRequest(opts: {
2292
2652
  }): Promise<WebhookVerification & {
2293
2653
  eventId: string | null;
2294
2654
  }>;
2655
+ /** A public key an application signs approvals with. */
2656
+ export interface SigningApplicationKey {
2657
+ id: string;
2658
+ kid: string;
2659
+ alg: "ES256" | "EdDSA";
2660
+ public_jwk: {
2661
+ kty: string;
2662
+ crv: string;
2663
+ x: string;
2664
+ y?: string;
2665
+ };
2666
+ created_at: string;
2667
+ expires_at: string | null;
2668
+ revoked_at: string | null;
2669
+ revoked_reason: string | null;
2670
+ }
2671
+ /** A business's own application, registered to vouch for its people (00684). */
2672
+ export interface SigningApplication {
2673
+ id: string;
2674
+ name: string;
2675
+ created_at: string;
2676
+ disabled_at: string | null;
2677
+ disabled_reason: string | null;
2678
+ keys: SigningApplicationKey[];
2679
+ }
2680
+ /** A saved signature handed over for one signing: spend it within `expires_at`. */
2681
+ export interface SignatureReference {
2682
+ /** Opaque, single-use. Authorises nothing on its own. */
2683
+ reference: string;
2684
+ /** SHA-256 of the image, hex: put it in the approval's `signature.sha256`. */
2685
+ sha256: string;
2686
+ expires_at: string;
2687
+ }
2688
+ /** The signature itself, as sent beside the approval. */
2689
+ export type ApprovalSignature = {
2690
+ method: "drawn";
2691
+ image: string;
2692
+ } | {
2693
+ method: "typed";
2694
+ text: string;
2695
+ } | {
2696
+ method: "saved";
2697
+ reference: string;
2698
+ };
2699
+ /** What an approval signed. */
2700
+ export interface SigningTransaction {
2701
+ transaction_id: string;
2702
+ /** The approval's `jti`. */
2703
+ approval_id: string;
2704
+ application_id: string;
2705
+ document_id: string;
2706
+ signer_id: string;
2707
+ event_id: string;
2708
+ subject: string;
2709
+ status: "signed";
2710
+ signed_at: string;
2711
+ /** Where the document has got to: `completed` once everybody has signed. */
2712
+ document_status: string;
2713
+ document_sha256: string;
2714
+ signature_method: "drawn" | "typed" | "saved";
2715
+ signature_sha256: string;
2716
+ /** Always this: the application vouched; SignSealer did not check the person. */
2717
+ authentication: "external_application";
2718
+ /** On `signWithApproval`: true when the same approval was sent again and this is the signing it already made. */
2719
+ replayed?: boolean;
2720
+ }
2721
+ /** One person's approval of one exact text, as your application's server states it. */
2722
+ export interface ApprovalInput {
2723
+ /** Your application's id in SignSealer. */
2724
+ applicationId: string;
2725
+ /** The business's id: `account().tenant_id`. */
2726
+ tenantId: string;
2727
+ documentId: string;
2728
+ /** The document's `body_sha256_hex` as the person was shown it. */
2729
+ documentSha256: string;
2730
+ /** Optional: the line, when you have it from the send. */
2731
+ signerId?: string;
2732
+ /** Your id for the person, as the line was bound to it, and their name. */
2733
+ person: {
2734
+ subject: string;
2735
+ name: string;
2736
+ };
2737
+ /** How they signed in to your application: RFC 8176 methods (`pwd`, `otp`, `hwk`...), a level if you have one, and when. */
2738
+ auth: {
2739
+ methods: string[];
2740
+ level?: string;
2741
+ at: Date | number;
2742
+ };
2743
+ /** When they pressed approve. */
2744
+ approvedAt: Date | number;
2745
+ /** The signature as you will send it beside the approval: its hash goes into the approval. */
2746
+ signature: {
2747
+ method: "drawn";
2748
+ image: string;
2749
+ } | {
2750
+ method: "typed";
2751
+ text: string;
2752
+ } | {
2753
+ method: "saved";
2754
+ sha256: string;
2755
+ };
2756
+ /** Recorded as supplied by your application, not as anything SignSealer saw. */
2757
+ ip?: string;
2758
+ device?: string;
2759
+ /** `online`. `offline` is described, and refused until it is accepted. */
2760
+ origin?: "online" | "offline";
2761
+ /** The approval's id; a random one when left out. Keep it to find the signing again. */
2762
+ approvalId?: string;
2763
+ /** Seconds the approval lives, at most 300. Default 120. */
2764
+ ttlSeconds?: number;
2765
+ }
2766
+ /** SHA-256 of a string's UTF-8, as lowercase hex: a signature's, or a document's text. */
2767
+ export declare function sha256Hex(text: string): Promise<string>;
2768
+ /**
2769
+ * Sign one approval with your application's private key: a compact JWS
2770
+ * that `signWithApproval` sends. `privateKey` is a WebCrypto key or a
2771
+ * private JWK -- ECDSA P-256 (ES256) or Ed25519 (EdDSA) -- and `kid` the
2772
+ * name you registered its public half under.
2773
+ *
2774
+ * Make one per approval, when the person approves, and send it at once: it
2775
+ * lives two minutes by default and five at most, and its `jti` is spent by
2776
+ * the signing it makes.
2777
+ */
2778
+ export declare function createApproval(opts: {
2779
+ privateKey: CryptoKey | JsonWebKey;
2780
+ kid: string;
2781
+ approval: ApprovalInput;
2782
+ /** For tests: the clock, in milliseconds. */
2783
+ now?: number;
2784
+ }): Promise<{
2785
+ assertion: string;
2786
+ approvalId: string;
2787
+ claims: Record<string, unknown>;
2788
+ }>;
2789
+ /** A box on a page of a PDF: one recipient's, in fractions of the page as a reader sees it, from its top-left. */
2790
+ export interface PdfBox {
2791
+ kind: "signature" | "initials" | "date" | "text" | "checkbox";
2792
+ /** The `sign_order` you give that signer on `send()`. */
2793
+ recipient: number;
2794
+ /** Defaults to `signature_1`, `date_signed_1`, `text_1_2` and so on. */
2795
+ key?: string;
2796
+ /** A `date` box labelled `Date signed` (the default) is filled with the day they sign. */
2797
+ label?: string;
2798
+ required?: boolean;
2799
+ page: number;
2800
+ x: number;
2801
+ y: number;
2802
+ w: number;
2803
+ h: number;
2804
+ }
2805
+ export interface DocumentFromPdf {
2806
+ document_id: string;
2807
+ template_id: string;
2808
+ template_code: string;
2809
+ pages: number;
2810
+ /** SHA-256 of the file as kept: sanitised, which is what is sealed. */
2811
+ sha256: string;
2812
+ /** The recipient numbers its boxes are for: give each a signer of that `sign_order`. */
2813
+ recipients: number[];
2814
+ fields: Array<Required<Omit<PdfBox, "page" | "x" | "y" | "w" | "h">> & {
2815
+ place: {
2816
+ page: number;
2817
+ x: number;
2818
+ y: number;
2819
+ w: number;
2820
+ h: number;
2821
+ };
2822
+ from: "given" | "tag";
2823
+ }>;
2824
+ /** What was taken out of the file because it could act on its own. */
2825
+ removed: string[];
2826
+ }
2827
+ export interface EnsuredWebhook {
2828
+ id: string;
2829
+ created: boolean;
2830
+ /** Only when `created`: keep it, it is not shown again. */
2831
+ secret: string | null;
2832
+ url: string;
2833
+ events: string[];
2834
+ label: string | null;
2835
+ active: boolean;
2836
+ paused: boolean;
2837
+ }
2295
2838
  //# sourceMappingURL=index.d.ts.map