@btps/sdk 1.2.0-rc.2 → 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.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,75 @@ 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
+
7
76
  ## [1.2.0-rc.2] — 2026-11-11 (beta, release candidate)
8
77
 
9
78
  What eBill found running 1.2.0-rc.1. Everything in rc.1 below still holds.
@@ -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"];
@@ -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 {};