@btps/sdk 1.2.0-rc.1 → 1.2.0-rc.3

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.
Files changed (30) hide show
  1. package/CHANGELOG.md +108 -0
  2. package/dist/client/index.d.ts +1 -0
  3. package/dist/client/index.js +7 -1
  4. package/dist/core/crypto/decryptVerify.js +6 -2
  5. package/dist/core/crypto/types.d.ts +3 -0
  6. package/dist/core/server/constants/btps-protocol.js +4 -2
  7. package/dist/core/server/constants/currency.d.ts +6 -0
  8. package/dist/core/server/constants/currency.js +27 -2
  9. package/dist/core/server/constants/limits.d.ts +25 -0
  10. package/dist/core/server/constants/limits.js +27 -0
  11. package/dist/core/server/constants/permissions.d.ts +1 -1
  12. package/dist/core/server/schemas/artifacts/transporterSchema.js +16 -9
  13. package/dist/core/server/schemas/boundView.d.ts +9 -0
  14. package/dist/core/server/schemas/boundView.js +28 -0
  15. package/dist/core/server/schemas/boundViewBindings.d.ts +40 -0
  16. package/dist/core/server/schemas/boundViewBindings.js +128 -0
  17. package/dist/core/server/schemas/boundViewChecks.d.ts +49 -0
  18. package/dist/core/server/schemas/boundViewChecks.js +344 -0
  19. package/dist/core/server/schemas/boundViewSchema.d.ts +1637 -0
  20. package/dist/core/server/schemas/boundViewSchema.js +186 -0
  21. package/dist/core/server/schemas/btpsDocsSchema.d.ts +37094 -8000
  22. package/dist/core/server/schemas/btpsDocsSchema.js +62 -44
  23. package/dist/core/server/schemas/helpers.d.ts +11604 -2312
  24. package/dist/core/trust/types.d.ts +11 -1
  25. package/dist/server/btpsServer.d.ts +11 -1
  26. package/dist/server/btpsServer.js +45 -5
  27. package/dist/server/index.d.ts +1 -0
  28. package/dist/server/index.js +9 -1
  29. package/dist/server/types.d.ts +31 -26
  30. package/package.json +14 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,114 @@ All notable changes to `@btps/sdk` and the BTPS protocol it implements. The
4
4
  format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
5
5
  versions follow [Semantic Versioning](https://semver.org/).
6
6
 
7
+ ## [1.2.0-rc.3] — 2026-11-15 (beta, release candidate)
8
+
9
+ BoundView: a document's own look, signed with it, every fact drawn from its
10
+ signed data. It replaces rc.1's templates. Everything in rc.2 and rc.1 below
11
+ still holds, except where this section changes it.
12
+
13
+ ### Added
14
+
15
+ - **BoundView.** A document may carry its BoundView in
16
+ `boundView` (`BTPBoundView`), `1.2.0` only: a canvas captured from the
17
+ sender's own preview, signed with the document, so the receiver sees what
18
+ the sender saw. Text that shows a fact binds a signed field and is drawn from
19
+ it, never carried as text; fonts travel as glyph outlines and images as
20
+ pixels, so nothing is fetched and no font or image file is parsed. A
21
+ receiver checks a BoundView wherever the document is opened (`checkBoundView`): a
22
+ BoundView that breaks its schema or a limit, or binds a missing field, is refused
23
+ with the document; one that hides, shrinks or leaves out a key fact is not
24
+ shown, and the receiver shows its own view of the data. `decryptVerify`
25
+ returns whether an opened document's BoundView may be shown (`boundView`,
26
+ `BTPBoundViewResult`), and a server hands its transporter handlers the same,
27
+ once an artifact's signature and trust are checked. `checkBoundView` and
28
+ `writtenValue` are exported from `@btps/sdk/server` and `@btps/sdk/client`.
29
+ Images inflate with fflate, a new dependency (MIT, no dependencies of its
30
+ own), stopping once past their stated length. Specified on the new
31
+ BoundView pages, with golden vectors for the schema in
32
+ `documents-1.2.vectors.json` and for the checks in `boundview.vectors.json`.
33
+ A BoundView is optional: without one, a receiver shows its own view of the
34
+ data.
35
+ - **`@btps/boundview`, a new package.** `snapshotBoundView` captures a
36
+ platform's own HTML preview as a BoundView in the browser: every fact found
37
+ by its value, fonts read as glyph outlines, images as pixels, an SVG logo as
38
+ outlines when they draw as the browser drew it. It throws
39
+ `BoundViewSnapshotError` with what a receiver would refuse or not show.
40
+ `renderBoundView` draws a received one with resvg compiled to WebAssembly,
41
+ handed only checked values, and gives a PNG, the same bytes everywhere
42
+ (`boundview-pictures.vectors.json`), or null when a check fails. It bundles
43
+ open-licence glyph outlines for label fallbacks and typed signatures.
44
+ - **`@btps/sdk/boundview`.** A BoundView's schema, bindings and checks alone,
45
+ for a browser or app without the rest of the SDK.
46
+ - **Totals, line roles and the recipient.** An invoice or receipt may carry
47
+ `subtotalAmount` and `taxAmount`, and name what each line-item column holds
48
+ (`lineItems.roles`, `BTPLineRole`); an invoice, receipt, letter or agreement
49
+ may name its `recipient`. `1.2.0` only.
50
+ - **A letter's signatory.** A letter or an agreement may carry `signatory`
51
+ (`BTPSignatory`), `1.2.0` only: a name, a title, and a visual signature,
52
+ typed (drawn in the open-licence script font Caveat) or drawn as integer
53
+ strokes on a 1,000 by 300 canvas, never markup. Such a signature is
54
+ decoration and proves no agreement.
55
+
56
+ ### Changed
57
+
58
+ - **`template` is `1.1.0` only.** A `1.1.0` invoice or receipt's `template`
59
+ is read as 1.1 reads it, `{ name, data }` with free data, and nothing is
60
+ drawn from it. A `1.2.0` artifact with one is refused: "template is 1.1.0
61
+ only; in 1.2.0 a document's look is its boundView". A document with a
62
+ `template` and nothing from 1.2 is still sent as `1.1.0`; once a platform
63
+ adds anything from 1.2 to it, its own SDK refuses it until `template` is
64
+ removed. See Migrating from 1.1 to 1.2, Dropping `template`.
65
+
66
+ ### Removed
67
+
68
+ - **Templates by reference, and template formats 1 and 2** (rc.1). A `1.2.0`
69
+ template's named data fields (`version`, `sha256`, `source`, `logo`), a
70
+ letter's or payslip's template, and a letter template's signature values
71
+ (`template.data.values`, `BTPTemplateValues`) are gone: a document's look is
72
+ its BoundView, and a letter's sign-off its `signatory`. Removed with them:
73
+ the Templates page, `schemas/btps-template.schema.json` and
74
+ `templates.vectors.json`.
75
+
76
+ ## [1.2.0-rc.2] — 2026-11-11 (beta, release candidate)
77
+
78
+ What eBill found running 1.2.0-rc.1. Everything in rc.1 below still holds.
79
+
80
+ ### Added
81
+
82
+ - **A signer's own signature on its acceptance.** An agreement statement may
83
+ carry `visualSignature`, typed (`{ type: 'typed', text }`) or drawn
84
+ (`{ type: 'drawn', strokes }`), with a letter signature's limits, on an
85
+ `accepted` statement only. It is inside the statement, so the statement's
86
+ signature covers it and the evidence bundle keeps it. It is optional in the
87
+ protocol; a platform may require one. A 1.2.0-rc.1 receiver refuses a
88
+ statement that carries one.
89
+ - The server option `entityTypeOf`: whether one of the platform's own
90
+ addresses is a person or an organisation, so the server can tell what a
91
+ person's trust request owes (see Changed).
92
+
93
+ ### Changed
94
+
95
+ - A `1.2.0` trust request carries `permissions`. One without them is refused
96
+ on arrival; a request for everything is a `1.1.0` one, which every server
97
+ still takes.
98
+ - A person asking an organisation for details gives nothing in return. An
99
+ organisation's request still gives what it asks for to anyone, and a
100
+ person's to another person. Only the receiver's own server knows what the
101
+ receiver is, so a person's request is now checked there, against
102
+ `entityTypeOf`, instead of by the schema; without the option, every receiver
103
+ is held to be a person, as before.
104
+
105
+ ### Fixed
106
+
107
+ - A refusal of a trust's permissions reaches the sender as itself:
108
+ `BTP_ERROR_PERMISSION_REQUIRED` for a grant that withholds a required name,
109
+ `BTP_ERROR_PERMISSION` for a name not granted or not asked for,
110
+ `BTP_ERROR_DOCUMENT_TYPE_MISMATCH` and `BTP_ERROR_DETAILS_NOT_HELD`. Each
111
+ read `BTP_ERROR_TRUST_NOT_ALLOWED` on the wire, so a platform could not tell
112
+ its user what to fix. Refusals about a trust's state still read "not
113
+ allowed", so a stranger learns nothing of it.
114
+
7
115
  ## [1.2.0-rc.1] — 2026-11-08 (beta, release candidate)
8
116
 
9
117
  What's new, with a guide for each feature: [What's new in 1.2](https://www.openbtps.org/docs/next/whats-new/1-2).
@@ -9,4 +9,5 @@ export { BtpsAgent } from './btpsAgent.js';
9
9
  export { BtpsClient } from './btpsClient.js';
10
10
  export { BtpsTransporter } from './btpsTransporter.js';
11
11
  export * from './constants/index.js';
12
+ export { checkBoundView, writtenValue, type BTPBoundViewResult, } from '../core/server/schemas/boundViewChecks.js';
12
13
  export { MIN_CONNECT_TIMEOUT_MS, DEFAULT_CONNECT_TIMEOUT_MS, MIN_REPLY_TIMEOUT_MS, DEFAULT_REPLY_TIMEOUT_MS, KEY_CHAIN_REPLY_TIMEOUT_MS, } from './libs/timeouts.js';
@@ -10,6 +10,10 @@ import { BtpsAgent } from "./btpsAgent.js";
10
10
  import { BtpsClient } from "./btpsClient.js";
11
11
  import { BtpsTransporter } from "./btpsTransporter.js";
12
12
  export * from "./constants/index.js";
13
+ import {
14
+ checkBoundView,
15
+ writtenValue
16
+ } from "../core/server/schemas/boundViewChecks.js";
13
17
  import {
14
18
  MIN_CONNECT_TIMEOUT_MS,
15
19
  DEFAULT_CONNECT_TIMEOUT_MS,
@@ -25,5 +29,7 @@ export {
25
29
  DEFAULT_REPLY_TIMEOUT_MS,
26
30
  KEY_CHAIN_REPLY_TIMEOUT_MS,
27
31
  MIN_CONNECT_TIMEOUT_MS,
28
- MIN_REPLY_TIMEOUT_MS
32
+ MIN_REPLY_TIMEOUT_MS,
33
+ checkBoundView,
34
+ writtenValue
29
35
  };
@@ -13,6 +13,7 @@ import {
13
13
  BTP_ERROR_VALIDATION
14
14
  } from "../error/constant.js";
15
15
  import { decryptedDocumentProblem } from "../server/schemas/helpers.js";
16
+ import { boundViewResultOf } from "../server/schemas/boundViewChecks.js";
16
17
  import { verifierRefusal } from "../trust/verification.js";
17
18
  import isEmpty from "lodash/isEmpty.js";
18
19
  const genDecryptError = (error) => ({
@@ -53,9 +54,12 @@ const genDecryptError = (error) => ({
53
54
  ...restEncryptedPayload,
54
55
  signature
55
56
  };
56
- return decryptedData && (decryptedPayload.document = decryptedData), delegation && (decryptedPayload.delegation = delegation), {
57
+ decryptedData && (decryptedPayload.document = decryptedData), delegation && (decryptedPayload.delegation = delegation);
58
+ const boundView = restEncryptedPayload.type === "BTPS_DOC" ? boundViewResultOf(decryptedData) : void 0;
59
+ return {
57
60
  payload: decryptedPayload,
58
- error: void 0
61
+ error: void 0,
62
+ ...boundView && { boundView }
59
63
  };
60
64
  };
61
65
  export {
@@ -8,6 +8,7 @@ import { BTPErrorException } from '../error/index.js';
8
8
  import { BTPAgentArtifact, BTPArtifact, BTPDelegation, BTPDocType, BTPServerResponse, BTPShaped, BTPTransporterArtifact } from '../server/types.js';
9
9
  import type { Signer } from './signer-interface.js';
10
10
  import type { Decrypter } from './decrypter-interface.js';
11
+ import type { BTPBoundViewResult } from '../server/schemas/boundViewChecks.js';
11
12
  export type EncryptionMode = 'none' | 'standardEncrypt' | '2faEncrypt';
12
13
  export type EncryptionAlgorithmType = 'aes-256-gcm';
13
14
  export type BTPEncryption = {
@@ -54,6 +55,8 @@ export interface BTPCryptoResponse<T = BTPDocType> {
54
55
  error?: BTPErrorException;
55
56
  /** Since 1.2: a trust request sent as its 1.1 receiver allows, and what it left out */
56
57
  shaped?: BTPShaped;
58
+ /** Since 1.2: whether the opened document's BoundView may be shown, when it carries one */
59
+ boundView?: BTPBoundViewResult;
57
60
  }
58
61
  export interface VerifyEncryptedPayload<T = unknown | string> {
59
62
  document?: T;
@@ -37,8 +37,10 @@ const BTP_PROTOCOL_VERSION = "1.2.0", MIN_SUPPORTED_VERSION = "1.1.0", MAX_SUPPO
37
37
  (artifact) => documentOf(artifact)?.type === "agreement",
38
38
 
39
39
  (artifact) => {
40
- const document = documentOf(artifact);
41
- return (document?.type === "letter" || document?.type === "payslip") && document.template !== void 0;
40
+ const document = documentOf(artifact), lineItems = document?.lineItems;
41
+ return document !== void 0 && (["boundView", "recipient", "signatory", "subtotalAmount", "taxAmount"].some(
42
+ (field) => document[field] !== void 0
43
+ ) || typeof lineItems == "object" && lineItems !== null && "roles" in lineItems);
42
44
  },
43
45
 
44
46
  (artifact) => Object.keys(PERMISSION_ENVELOPE_FIELDS).some((field) => artifact[field] !== void 0),
@@ -5,3 +5,9 @@
5
5
  * https://www.apache.org/licenses/LICENSE-2.0
6
6
  */
7
7
  export declare const CURRENCY_CODES: readonly ["AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "FOK", "GBP", "GEL", "GGP", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "IMP", "INR", "IQD", "IRR", "ISK", "JEP", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KID", "KMF", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "SSP", "STN", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TVD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VES", "VND", "VUV", "WST", "XAF", "XCD", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWL"];
8
+ /**
9
+ * The decimal places ISO 4217 gives each currency whose minor unit is not two
10
+ * hundredths. Every other code has 2. Fixed here rather than read from a
11
+ * runtime's Intl data, so every receiver writes an amount the same way.
12
+ */
13
+ export declare const CURRENCY_DECIMALS: Partial<Record<(typeof CURRENCY_CODES)[number], number>>;
@@ -326,7 +326,32 @@ const CURRENCY_CODES = [
326
326
 
327
327
  "ZWL"
328
328
 
329
- ];
329
+ ], CURRENCY_DECIMALS = {
330
+ BIF: 0,
331
+ CLP: 0,
332
+ DJF: 0,
333
+ GNF: 0,
334
+ ISK: 0,
335
+ JPY: 0,
336
+ KMF: 0,
337
+ KRW: 0,
338
+ PYG: 0,
339
+ RWF: 0,
340
+ UGX: 0,
341
+ VND: 0,
342
+ VUV: 0,
343
+ XAF: 0,
344
+ XOF: 0,
345
+ XPF: 0,
346
+ BHD: 3,
347
+ IQD: 3,
348
+ JOD: 3,
349
+ KWD: 3,
350
+ LYD: 3,
351
+ OMR: 3,
352
+ TND: 3
353
+ };
330
354
  export {
331
- CURRENCY_CODES
355
+ CURRENCY_CODES,
356
+ CURRENCY_DECIMALS
332
357
  };
@@ -86,5 +86,30 @@ export declare const BTPS_FIELD_LIMITS: {
86
86
  readonly width: 1000;
87
87
  readonly height: 300;
88
88
  };
89
+ readonly recipientName: 200;
90
+ readonly boundView: {
91
+ readonly json: number;
92
+ readonly pageWidth: 2000;
93
+ readonly pageHeight: 20000;
94
+ readonly breaks: 100;
95
+ readonly elements: 2000;
96
+ readonly textElements: 1000;
97
+ readonly position: 20000;
98
+ readonly label: 500;
99
+ readonly path: 20000;
100
+ readonly paths: 100000;
101
+ readonly stops: 8;
102
+ readonly fonts: 4;
103
+ readonly glyphs: 256;
104
+ readonly glyphPath: 4000;
105
+ readonly kerning: 4096;
106
+ readonly fallback: 4;
107
+ readonly images: 8;
108
+ readonly imageSide: 1024;
109
+ readonly imagePixels: 262144;
110
+ readonly imageData: number;
111
+ readonly affix: 8;
112
+ readonly groups: 32;
113
+ };
89
114
  readonly detailNumber: 64;
90
115
  };
@@ -86,6 +86,33 @@ const BTPS_FIELD_LIMITS = {
86
86
 
87
87
  signature: { text: 100, strokes: 32, strokePoints: 512, points: 2048, width: 1e3, height: 300 },
88
88
 
89
+ recipientName: 200,
90
+
91
+ boundView: {
92
+ json: 393216,
93
+ pageWidth: 2e3,
94
+ pageHeight: 2e4,
95
+ breaks: 100,
96
+ elements: 2e3,
97
+ textElements: 1e3,
98
+ position: 2e4,
99
+ label: 500,
100
+ path: 2e4,
101
+ paths: 1e5,
102
+ stops: 8,
103
+ fonts: 4,
104
+ glyphs: 256,
105
+ glyphPath: 4e3,
106
+ kerning: 4096,
107
+ fallback: 4,
108
+ images: 8,
109
+ imageSide: 1024,
110
+ imagePixels: 262144,
111
+ imageData: 262144,
112
+ affix: 8,
113
+ groups: 32
114
+ },
115
+
89
116
  detailNumber: 64
90
117
  };
91
118
  export {
@@ -13,7 +13,7 @@ export declare const DOCUMENT_TYPES: readonly ["invoice", "receipt", "payslip",
13
13
  export declare const DETAIL_TYPES: readonly ["legalName", "profile", "email", "phone", "address", "taxNo", "dob", "registrationNumber"];
14
14
  /** Since 1.2: what owns a BTPS address. */
15
15
  export declare const ENTITY_TYPES: readonly ["person", "organisation"];
16
- export declare const SEND_PERMISSIONS: ("send:payslip" | "send:letter" | "send:agreement" | "send:invoice" | "send:receipt")[];
16
+ export declare const SEND_PERMISSIONS: ("send:invoice" | "send:receipt" | "send:payslip" | "send:letter" | "send:agreement")[];
17
17
  export declare const DETAIL_PERMISSIONS: ("detail:legalName" | "detail:profile" | "detail:email" | "detail:phone" | "detail:address" | "detail:taxNo" | "detail:dob" | "detail:registrationNumber")[];
18
18
  /** Since 1.2: details refresh: a notice that details changed, a request for some, and its answer. */
19
19
  export declare const DETAILS_ARTIFACT_TYPES: readonly ["DETAILS_CHANGED", "DETAILS_REQ", "DETAILS_RES"];
@@ -60,6 +60,13 @@ const BtpSyncOfSchema = z.object({ id: z.string().min(1), sha256: sha256Hex }).s
60
60
  documentType: z.enum(DOCUMENT_TYPES).optional(),
61
61
  details: namesFrom(DETAIL_PERMISSIONS, 1).optional()
62
62
  });
63
+ function detailsOwed(permissions, entityType, given = []) {
64
+ const identities = Object.values(IDENTITY_DETAIL);
65
+ return permissions.filter(({ name }) => name.startsWith("detail:")).map(({ name }) => ({
66
+ asked: name,
67
+ owed: identities.includes(name) ? IDENTITY_DETAIL[entityType] : name
68
+ })).filter(({ owed }) => !given.includes(owed));
69
+ }
63
70
  function permissionEnvelopeProblems(data) {
64
71
  const problems = [];
65
72
  for (const [field, types] of Object.entries(PERMISSION_ENVELOPE_FIELDS))
@@ -74,15 +81,14 @@ function permissionEnvelopeProblems(data) {
74
81
  const twice = names && duplicateOf(names);
75
82
  twice && problems.push([field, `${twice} appears more than once`]);
76
83
  }
84
+ data.type === "TRUST_REQ" && !isVersionBelow(data.version, "1.2.0") && !data.permissions && problems.push([
85
+ "permissions",
86
+ "a 1.2.0 TRUST_REQ asks for permissions; a request for everything is a 1.1.0 one"
87
+ ]);
77
88
  const { entityType } = data, other = entityType && IDENTITY_DETAIL[entityType === "person" ? "organisation" : "person"];
78
- if (data.permissions && !entityType && problems.push(["entityType", "entityType comes with permissions"]), data.granted && !entityType && problems.push(["entityType", "entityType comes with granted"]), data.permissions && entityType) {
79
- const given = data.given ?? [], identities = Object.values(IDENTITY_DETAIL);
80
- for (const { name } of data.permissions) {
81
- if (!name.startsWith("detail:")) continue;
82
- const gives = identities.includes(name) ? IDENTITY_DETAIL[entityType] : name;
83
- given.includes(gives) || problems.push(["given", `asks for ${name} without giving ${gives}`]);
84
- }
85
- }
89
+ if (data.permissions && !entityType && problems.push(["entityType", "entityType comes with permissions"]), data.granted && !entityType && problems.push(["entityType", "entityType comes with granted"]), data.permissions && entityType === "organisation")
90
+ for (const { asked, owed } of detailsOwed(data.permissions, entityType, data.given))
91
+ problems.push(["given", `asks for ${asked} without giving ${owed}`]);
86
92
  if (other && data.given?.includes(other) && problems.push(["given", `a ${entityType} never gives ${other}`]), other && data.granted?.includes(other) && problems.push(["granted", `a ${entityType} never grants ${other}`]), DETAILS_ARTIFACT_TYPES.includes(data.type) && data.details === void 0 && problems.push(["details", `a ${data.type} names the details it is about`]), data.type === "DETAILS_RES" && data.encryption === null && problems.push(["encryption", "a DETAILS_RES is always encrypted to the requester"]), data.encryption === null) {
87
93
  const document = documentRecord(data.document);
88
94
  data.type === "TRUST_REQ" && document?.own !== void 0 && problems.push(["document", "a request with its own values is encrypted"]), data.type === "TRUST_REQ" && document?.verification !== void 0 && problems.push(["document", "a request with a verification is encrypted"]), data.type === "TRUST_RES" && document?.details !== void 0 && problems.push(["document", "a response with details is encrypted"]), data.type === "TRUST_RES" && data.granted && document?.decision !== "accepted" && problems.push(["granted", "only an accepted answer carries granted"]);
@@ -136,5 +142,6 @@ export {
136
142
  BtpTransporterArtifactBaseSchema,
137
143
  BtpTransporterArtifactSchema,
138
144
  BtpTrustPermissionsSchema,
139
- BtpTrustRecordPermissionsSchema
145
+ BtpTrustRecordPermissionsSchema,
146
+ detailsOwed
140
147
  };
@@ -0,0 +1,9 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+ export { BtpBoundViewSchema, isPathData, type BTPBoundView, type BTPBoundViewElement, type BTPBoundViewFont, } from './boundViewSchema.js';
8
+ export { boundValue, bindingProblem, type BoundValue } from './boundViewBindings.js';
9
+ export { checkBoundView, boundViewResultOf, writtenValue, CONTRAST_WORK_LIMIT, type BTPBoundViewResult, type BTPBoundViewProblem, type BTPBoundViewCheck, } from './boundViewChecks.js';
@@ -0,0 +1,28 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+
8
+ import {
9
+ BtpBoundViewSchema,
10
+ isPathData
11
+ } from "./boundViewSchema.js";
12
+ import { boundValue, bindingProblem } from "./boundViewBindings.js";
13
+ import {
14
+ checkBoundView,
15
+ boundViewResultOf,
16
+ writtenValue,
17
+ CONTRAST_WORK_LIMIT
18
+ } from "./boundViewChecks.js";
19
+ export {
20
+ BtpBoundViewSchema,
21
+ CONTRAST_WORK_LIMIT,
22
+ bindingProblem,
23
+ boundValue,
24
+ boundViewResultOf,
25
+ checkBoundView,
26
+ isPathData,
27
+ writtenValue
28
+ };
@@ -0,0 +1,40 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+ export type BoundKind = 'text' | 'money' | 'date' | 'percent';
8
+ /** A bound field's value: text, a date, whole basis points, or an amount in minor units of its currency. */
9
+ export type BoundValue = {
10
+ kind: 'text';
11
+ text: string;
12
+ } | {
13
+ kind: 'date';
14
+ date: string;
15
+ } | {
16
+ kind: 'percent';
17
+ basisPoints: number;
18
+ } | {
19
+ kind: 'money';
20
+ amount: number;
21
+ currency: string;
22
+ };
23
+ type Doc = Record<string, unknown>;
24
+ /** What `field` names in `document`, or undefined when a BoundView may not bind it or the document lacks it. */
25
+ export declare const boundValue: (document: Doc, field: string) => BoundValue | undefined;
26
+ type Bind = {
27
+ field: string;
28
+ format?: {
29
+ money?: unknown;
30
+ date?: unknown;
31
+ percent?: unknown;
32
+ groups?: {
33
+ sizes: number[];
34
+ };
35
+ };
36
+ range?: [number, number];
37
+ };
38
+ /** Why a binding cannot be drawn from `document`, or undefined when it can. */
39
+ export declare const bindingProblem: (document: Doc, bind: Bind) => string | undefined;
40
+ export {};
@@ -0,0 +1,128 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+
8
+ const ISSUER = [
9
+ ["id", "text"],
10
+ ["title", "text"],
11
+ ["issuedAt", "date"],
12
+ ["issuer.name", "text"],
13
+ ["issuer.email", "text"],
14
+ ["issuer.phone", "text"],
15
+ ["issuer.address", "text"],
16
+ ["issuer.identifiers.*", "text"]
17
+ ], BILL = [
18
+ ...ISSUER,
19
+ ["totalAmount", "money"],
20
+ ["subtotalAmount", "money"],
21
+ ["taxAmount", "money"],
22
+ ["discount.amount", "money"],
23
+ ["discount.percent", "percent"],
24
+ ["recipient.name", "text"],
25
+ ["description", "text"],
26
+ ["lineItems.rows.#.*", "cell"]
27
+ ], LETTER = [
28
+ ...ISSUER,
29
+ ["body.content", "text"],
30
+ ["recipient.name", "text"],
31
+ ["signatory.name", "text"],
32
+ ["signatory.title", "text"]
33
+ ], PATTERNS = {
34
+ invoice: [...BILL, ["dueAt", "date"]],
35
+ receipt: [
36
+ ...BILL,
37
+ ["payment.amount", "money"],
38
+ ["payment.paidAt", "date"],
39
+ ["payment.method", "text"],
40
+ ["payment.reference", "text"]
41
+ ],
42
+ payslip: [
43
+ ...ISSUER,
44
+ ["payDate", "date"],
45
+ ["payPeriod.start", "date"],
46
+ ["payPeriod.end", "date"],
47
+ ["payRate.asAt", "date"],
48
+ ["employee.name", "text"],
49
+ ["employee.employeeId", "text"],
50
+ ["payRate.amount", "money"],
51
+ ["gross", "money"],
52
+ ["net", "money"],
53
+ ["taxWithheld", "money"],
54
+ ["yearToDate.*", "money"],
55
+ ...["description", "category", "rate", "rateUnit", "quantity"].map(
56
+ (key) => [`earnings.#.${key}`, "text"]
57
+ ),
58
+ ["earnings.#.amount", "money"],
59
+ ["deductions.#.description", "text"],
60
+ ["deductions.#.category", "text"],
61
+ ["deductions.#.payee.name", "text"],
62
+ ["deductions.#.amount", "money"],
63
+ ["contributions.#.category", "text"],
64
+ ["contributions.#.fund.name", "text"],
65
+ ["contributions.#.amount", "money"],
66
+ ...["description", "category", "unit", "balance", "accrued", "taken"].map(
67
+ (key) => [`leave.#.${key}`, "text"]
68
+ )
69
+ ],
70
+ letter: LETTER,
71
+ agreement: [...LETTER, ["acceptance.by", "date"]]
72
+ }, isRecord = (value) => typeof value == "object" && value !== null && !Array.isArray(value), walk = (document, pattern, field) => {
73
+ const want = pattern.split("."), have = field.split(".");
74
+ let at = document;
75
+ for (let i = 0; i < want.length; i++) {
76
+ const segment = want[i];
77
+ if (segment === "*") {
78
+ const key = have.slice(i).join(".");
79
+ return isRecord(at) && key !== "" && Object.hasOwn(at, key) ? at[key] : void 0;
80
+ }
81
+ const part = have[i];
82
+ if (part === void 0) return;
83
+ if (segment === "#") {
84
+ if (!Array.isArray(at) || !/^(0|[1-9]\d*)$/.test(part)) return;
85
+ at = at[Number(part)];
86
+ } else {
87
+ if (segment !== part || !isRecord(at) || !Object.hasOwn(at, part)) return;
88
+ at = at[part];
89
+ }
90
+ }
91
+ return have.length === want.length ? at : void 0;
92
+ }, currencyOf = (document) => {
93
+ const total = document.totalAmount;
94
+ return isRecord(total) && typeof total.currency == "string" ? total.currency : void 0;
95
+ }, boundValue = (document, field) => {
96
+ const type = typeof document.type == "string" ? document.type : "";
97
+ for (const [pattern, kind] of PATTERNS[type] ?? []) {
98
+ const value = walk(document, pattern, field);
99
+ if (value !== void 0) {
100
+ if (kind === "cell" || kind === "money" && typeof value == "number") {
101
+ const currency = currencyOf(document);
102
+ return typeof value == "number" && currency !== void 0 ? { kind: "money", amount: value, currency } : typeof value == "string" ? { kind: "text", text: value } : void 0;
103
+ }
104
+ return kind === "money" ? isRecord(value) && typeof value.amount == "number" && typeof value.currency == "string" ? { kind: "money", amount: value.amount, currency: value.currency } : void 0 : kind === "percent" ? typeof value == "number" ? { kind: "percent", basisPoints: value } : void 0 : kind === "date" ? typeof value == "string" ? { kind: "date", date: value } : void 0 : isRecord(value) && typeof value.content == "string" ? { kind: "text", text: value.content } : typeof value == "string" ? { kind: "text", text: value } : void 0;
105
+ }
106
+ }
107
+ }, bindingProblem = (document, bind) => {
108
+ const value = boundValue(document, bind.field);
109
+ if (value === void 0) return `binds ${bind.field}, which a BoundView may not bind or the document does not carry`;
110
+ const format = bind.format ?? {};
111
+ if (value.kind === "money" && format.money === void 0) return "a money field is written with a money format";
112
+ if (value.kind === "date" && format.date === void 0) return "a date field is written with a date format";
113
+ if (value.kind === "percent" && format.percent === void 0) return "a percent is written with a percent format";
114
+ if (value.kind === "text") {
115
+ if (format.money !== void 0 || format.date !== void 0 || format.percent !== void 0)
116
+ return "text is written as it is, or in groups";
117
+ if (format.groups !== void 0) {
118
+ const length = [...value.text.replace(/ /g, "")].length;
119
+ if (format.groups.sizes.reduce((total, part) => total + part, 0) !== length) return "a groups format's sizes add up to the value's length";
120
+ }
121
+ if (bind.range !== void 0 && bind.range[1] > [...value.text].length)
122
+ return "a range lies inside the value's characters";
123
+ }
124
+ };
125
+ export {
126
+ bindingProblem,
127
+ boundValue
128
+ };
@@ -0,0 +1,49 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+ import { type BTPBoundView, type BTPBoundViewElement } from './boundViewSchema.js';
8
+ import { type BoundValue } from './boundViewBindings.js';
9
+ type Doc = Record<string, unknown>;
10
+ type TextElement = Extract<BTPBoundViewElement, {
11
+ type: 'text';
12
+ }>;
13
+ export type BTPBoundViewCheck = 'wellFormed' | 'keyFacts' | 'shownInFull' | 'notHidden';
14
+ export type BTPBoundViewProblem = {
15
+ check: BTPBoundViewCheck;
16
+ message: string;
17
+ /** The element the problem is on, by its index in `elements`. */
18
+ element?: number;
19
+ /** The key fact the problem is about. */
20
+ field?: string;
21
+ };
22
+ /** Whether a BoundView may be shown, and why not when it may not. */
23
+ export type BTPBoundViewResult = {
24
+ show: true;
25
+ } | {
26
+ show: false;
27
+ problems: BTPBoundViewProblem[];
28
+ };
29
+ /** A bound value as the receiver draws it, by its binding's format and range (Bindings and formats). */
30
+ export declare const writtenValue: (value: BoundValue, bind: TextElement["bind"]) => string;
31
+ /**
32
+ * The most edge and point tests the contrast check makes on one BoundView. A
33
+ * BoundView that would need more fails the check: a receiver is never made to
34
+ * work without end on a crafted one.
35
+ */
36
+ export declare const CONTRAST_WORK_LIMIT = 20000000;
37
+ /**
38
+ * The checks on a well-formed BoundView, against the signed document it
39
+ * belongs to: every key fact shown, every bound value shown in full, and
40
+ * nothing bound hidden. Run wherever the document is opened, before it is shown.
41
+ */
42
+ export declare const checkBoundView: (document: Doc, view: BTPBoundView) => BTPBoundViewResult;
43
+ /**
44
+ * Whether an opened document's BoundView may be shown, or undefined when it
45
+ * carries none. A document is checked against its schema before it is opened;
46
+ * one that was not, and whose BoundView is not well formed, is never shown.
47
+ */
48
+ export declare const boundViewResultOf: (document: unknown) => BTPBoundViewResult | undefined;
49
+ export {};