@pacspace-io/sdk 0.9.0 → 0.15.2

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 (152) hide show
  1. package/README.md +53 -132
  2. package/dist/blinding-file.d.ts +13 -0
  3. package/dist/blinding-file.d.ts.map +1 -0
  4. package/dist/blinding-guard.d.ts +7 -0
  5. package/dist/blinding-guard.d.ts.map +1 -0
  6. package/dist/blinding.d.ts +32 -0
  7. package/dist/blinding.d.ts.map +1 -0
  8. package/dist/client.d.ts +28 -4
  9. package/dist/client.d.ts.map +1 -1
  10. package/dist/fingerprint.d.ts +26 -5
  11. package/dist/fingerprint.d.ts.map +1 -1
  12. package/dist/index.d.ts +35 -35
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +7366 -186
  15. package/dist/index.js.map +7 -1
  16. package/dist/inputs.txt +132 -0
  17. package/dist/records-crypto-libraries.json +42 -0
  18. package/dist/records-crypto-types/proof/hiding-commitment-v1.d.ts +19 -0
  19. package/dist/records-crypto-types/proof/jcs.d.ts +4 -0
  20. package/dist/records-crypto-types/proof/layout-document-v1.d.ts +72 -0
  21. package/dist/records-crypto-types/proof/ledger-head-v1.d.ts +22 -0
  22. package/dist/records-crypto-types/proof/merkle-v2.d.ts +5 -0
  23. package/dist/records-crypto-types/proof/payload-ref-v1.d.ts +17 -0
  24. package/dist/records-crypto-types/proof/seal-input.d.ts +2 -0
  25. package/dist/records-crypto-types/proof/semantic-receipt-v2.d.ts +89 -0
  26. package/dist/records-crypto-types/proof/semantic-receipt-v3.d.ts +20 -0
  27. package/dist/records-crypto-types/proof/slot-encoding-v1.d.ts +169 -0
  28. package/dist/records-crypto-types/records/flag-threads-v1.d.ts +53 -0
  29. package/dist/records-crypto-types/records/labels.d.ts +37 -0
  30. package/dist/records-crypto-types/records/reader-crypto-v1.d.ts +198 -0
  31. package/dist/records-crypto-types/records/reader-link-v1.d.ts +164 -0
  32. package/dist/records-crypto-types/records/shared-record-ack-v2.d.ts +72 -0
  33. package/dist/records-crypto-types/records/signed-acknowledgment-v1.d.ts +38 -0
  34. package/dist/records-crypto-types/records/signed-acknowledgment-v2.d.ts +12 -0
  35. package/dist/records-crypto-types/records/trail-index-v1.d.ts +89 -0
  36. package/dist/records-crypto-types/records/trail-rule.d.ts +54 -0
  37. package/dist/records-crypto-types/records-crypto/asymmetric/ack-flag-notes-v1.d.ts +57 -0
  38. package/dist/records-crypto-types/records-crypto/asymmetric/flag-notes-v1.d.ts +55 -0
  39. package/dist/records-crypto-types/records-crypto/asymmetric/index.d.ts +4 -0
  40. package/dist/records-crypto-types/records-crypto/asymmetric/reader-wraps-v1.d.ts +83 -0
  41. package/dist/records-crypto-types/records-crypto/asymmetric/records-asymmetric-v1.d.ts +201 -0
  42. package/dist/records-crypto-types/records-crypto/base64url.d.ts +3 -0
  43. package/dist/records-crypto-types/records-crypto/blinding-file.d.ts +16 -0
  44. package/dist/records-crypto-types/records-crypto/blinding-value.d.ts +10 -0
  45. package/dist/records-crypto-types/records-crypto/bundle-entry.d.ts +2 -0
  46. package/dist/records-crypto-types/records-crypto/disclosure-envelope-v1.d.ts +42 -0
  47. package/dist/records-crypto-types/records-crypto/held-file.d.ts +17 -0
  48. package/dist/records-crypto-types/records-crypto/hmac-node.d.ts +8 -0
  49. package/dist/records-crypto-types/records-crypto/hmac-web.d.ts +8 -0
  50. package/dist/records-crypto-types/records-crypto/index.d.ts +13 -0
  51. package/dist/records-crypto-types/records-crypto/platform-crypto.d.ts +9 -0
  52. package/dist/records-crypto-types/records-crypto/record-disclosure-v1.d.ts +171 -0
  53. package/dist/records-crypto-types/records-crypto/record-hash-v2.d.ts +49 -0
  54. package/dist/records-crypto-types/records-crypto/record-hash-v3.d.ts +36 -0
  55. package/dist/records-crypto-types/records-crypto/records-encryption-v1.d.ts +185 -0
  56. package/dist/records-crypto-types/records-crypto/wrap-shapes-v1.d.ts +23 -0
  57. package/dist/records-crypto.d.ts +1 -0
  58. package/dist/records-crypto.js +16105 -0
  59. package/dist/records-crypto.js.map +7 -0
  60. package/dist/records-encryption/base64url.d.ts +5 -0
  61. package/dist/records-encryption/base64url.d.ts.map +1 -0
  62. package/dist/records-encryption/encrypted-records.d.ts +338 -0
  63. package/dist/records-encryption/encrypted-records.d.ts.map +1 -0
  64. package/dist/records-encryption/index.d.ts +14 -0
  65. package/dist/records-encryption/index.d.ts.map +1 -0
  66. package/dist/records-encryption/keys.d.ts +40 -0
  67. package/dist/records-encryption/keys.d.ts.map +1 -0
  68. package/dist/records-encryption/loader.d.ts +15 -0
  69. package/dist/records-encryption/loader.d.ts.map +1 -0
  70. package/dist/records-encryption/pin-store-file.d.ts +8 -0
  71. package/dist/records-encryption/pin-store-file.d.ts.map +1 -0
  72. package/dist/records-encryption/pin-store.d.ts +17 -0
  73. package/dist/records-encryption/pin-store.d.ts.map +1 -0
  74. package/dist/records-encryption/transport.d.ts +23 -0
  75. package/dist/records-encryption/transport.d.ts.map +1 -0
  76. package/dist/records-encryption/words.d.ts +40 -0
  77. package/dist/records-encryption/words.d.ts.map +1 -0
  78. package/dist/records-encryption/workspace-secret.d.ts +9 -0
  79. package/dist/records-encryption/workspace-secret.d.ts.map +1 -0
  80. package/dist/resources/records.d.ts +112 -2
  81. package/dist/resources/records.d.ts.map +1 -1
  82. package/dist/types/common.d.ts +0 -8
  83. package/dist/types/common.d.ts.map +1 -1
  84. package/dist/types/config.d.ts +7 -5
  85. package/dist/types/config.d.ts.map +1 -1
  86. package/dist/types/records-encryption.d.ts +136 -0
  87. package/dist/types/records-encryption.d.ts.map +1 -0
  88. package/dist/types/records.d.ts +171 -20
  89. package/dist/types/records.d.ts.map +1 -1
  90. package/dist/types/verify.d.ts +84 -0
  91. package/dist/types/verify.d.ts.map +1 -0
  92. package/dist/webhooks/index.d.ts +1 -1
  93. package/dist/webhooks/index.d.ts.map +1 -1
  94. package/dist/webhooks/index.js +229 -5
  95. package/dist/webhooks/index.js.map +7 -1
  96. package/dist/webhooks/types.d.ts +15 -7
  97. package/dist/webhooks/types.d.ts.map +1 -1
  98. package/dist/workspace-secret-file.d.ts +18 -0
  99. package/dist/workspace-secret-file.d.ts.map +1 -0
  100. package/package.json +16 -13
  101. package/dist/client.js +0 -553
  102. package/dist/client.js.map +0 -1
  103. package/dist/errors/index.js +0 -223
  104. package/dist/errors/index.js.map +0 -1
  105. package/dist/fingerprint.js +0 -132
  106. package/dist/fingerprint.js.map +0 -1
  107. package/dist/resources/balance.d.ts +0 -384
  108. package/dist/resources/balance.d.ts.map +0 -1
  109. package/dist/resources/balance.js +0 -1120
  110. package/dist/resources/balance.js.map +0 -1
  111. package/dist/resources/customers.d.ts +0 -33
  112. package/dist/resources/customers.d.ts.map +0 -1
  113. package/dist/resources/customers.js +0 -26
  114. package/dist/resources/customers.js.map +0 -1
  115. package/dist/resources/internal/batch-transport.d.ts +0 -65
  116. package/dist/resources/internal/batch-transport.d.ts.map +0 -1
  117. package/dist/resources/internal/batch-transport.js +0 -42
  118. package/dist/resources/internal/batch-transport.js.map +0 -1
  119. package/dist/resources/receipts.d.ts +0 -46
  120. package/dist/resources/receipts.d.ts.map +0 -1
  121. package/dist/resources/receipts.js +0 -133
  122. package/dist/resources/receipts.js.map +0 -1
  123. package/dist/resources/records.js +0 -232
  124. package/dist/resources/records.js.map +0 -1
  125. package/dist/resources/submission.d.ts +0 -79
  126. package/dist/resources/submission.d.ts.map +0 -1
  127. package/dist/resources/submission.js +0 -398
  128. package/dist/resources/submission.js.map +0 -1
  129. package/dist/types/balance.d.ts +0 -966
  130. package/dist/types/balance.d.ts.map +0 -1
  131. package/dist/types/balance.js +0 -3
  132. package/dist/types/balance.js.map +0 -1
  133. package/dist/types/common.js +0 -3
  134. package/dist/types/common.js.map +0 -1
  135. package/dist/types/config.js +0 -3
  136. package/dist/types/config.js.map +0 -1
  137. package/dist/types/records.js +0 -5
  138. package/dist/types/records.js.map +0 -1
  139. package/dist/types/submission.d.ts +0 -125
  140. package/dist/types/submission.d.ts.map +0 -1
  141. package/dist/types/submission.js +0 -3
  142. package/dist/types/submission.js.map +0 -1
  143. package/dist/utils/polling.d.ts +0 -32
  144. package/dist/utils/polling.d.ts.map +0 -1
  145. package/dist/utils/polling.js +0 -52
  146. package/dist/utils/polling.js.map +0 -1
  147. package/dist/utils/retry.js +0 -21
  148. package/dist/utils/retry.js.map +0 -1
  149. package/dist/webhooks/types.js +0 -3
  150. package/dist/webhooks/types.js.map +0 -1
  151. package/dist/webhooks/verify.js +0 -191
  152. package/dist/webhooks/verify.js.map +0 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @pacspace-io/sdk
2
2
 
3
- Official TypeScript SDK for the [PacSpace Balance API](https://docs.pacspace.io). Zero dependencies, fully typed, built for Node.js 18+.
3
+ Official TypeScript SDK for the [PacSpace API](https://docs.pacspace.io). Zero dependencies, fully typed, built for Node.js 18+.
4
4
 
5
5
  ## Install
6
6
 
@@ -11,26 +11,25 @@ npm install @pacspace-io/sdk
11
11
  ## Quick Start
12
12
 
13
13
  ```typescript
14
- import { PacSpace } from '@pacspace-io/sdk';
14
+ import { PacSpace, fingerprint } from '@pacspace-io/sdk';
15
15
 
16
16
  const pac = new PacSpace({ apiKey: process.env.PACSPACE_API_KEY! });
17
17
 
18
- // Record a delta
19
- const delta = await pac.balance.emit('cust_123', -42.50, 'usage_charge');
20
- console.log(delta.receiptId); // Store for later verification
21
-
22
- // Derive balance
23
- const { computedBalance } = await pac.balance.derive('cust_123');
24
-
25
- // Compare against counterparty
26
- const report = await pac.balance.compare('cust_123', {
27
- yours: 95000,
28
- theirs: 98000,
18
+ // Fingerprint a file and record an entry
19
+ const { ref, blinding } = await fingerprint(fileBytes);
20
+ const entry = await pac.records.emit({
21
+ record: 'build-1',
22
+ title: 'Handoff',
23
+ occurredAt: '2026-09-14T10:02:00Z',
24
+ actorId: 'ci',
25
+ payloads: [ref],
29
26
  });
30
27
 
31
- // Period-end checkpoint
32
- const checkpoint = await pac.balance.checkpoint('cust_123', {
33
- period: '2026-02',
28
+ // Read the history and check it in your process
29
+ const history = await pac.records.history({ record: 'build-1' });
30
+ const check = await pac.records.check({
31
+ history,
32
+ expect: [{ entry: 1, files: [{ source: fileBytes, blinding }] }],
34
33
  });
35
34
  ```
36
35
 
@@ -40,7 +39,7 @@ const checkpoint = await pac.balance.checkpoint('cust_123', {
40
39
 
41
40
  | Option | Type | Default | Description |
42
41
  |--------|------|---------|-------------|
43
- | `apiKey` | `string` | **required** | Your Balance API key (`pk_live_*` or `pk_test_*`) |
42
+ | `apiKey` | `string` | **required** | Your PacSpace API key (`pk_live_*` or `pk_test_*`) |
44
43
  | `baseUrl` | `string` | `https://app.pacspace.io` | API base URL (overrides the key-based choice if provided) |
45
44
  | `sandboxUrl` | `string` | `https://app.pacspace.io` | Custom sandbox URL for a private sandbox host (used for `pk_test_*` keys) |
46
45
  | `productionUrl` | `string` | `https://app.pacspace.io` | Custom production URL (used for `pk_live_*` keys) |
@@ -49,28 +48,11 @@ const checkpoint = await pac.balance.checkpoint('cust_123', {
49
48
  | `timeout` | `number` | `30000` | Request timeout in ms |
50
49
  | `webhookSecret` | `string` | — | Webhook signing secret (enables `pac.webhooks`) |
51
50
 
52
- ### Balance API
53
-
54
- #### `pac.balance.emit(customerId, delta, reason, options?)`
55
-
56
- Record a credit or debit delta. Returns immediately with `QUEUED` status.
57
-
58
- ```typescript
59
- const delta = await pac.balance.emit('cust_123', -42.50, 'usage_charge', {
60
- referenceId: 'inv_001',
61
- metadata: { plan: 'growth' },
62
- });
63
-
64
- const adjustment = await pac.balance.emit('cust_123', -10, 'adjustment', {
65
- adjusts: { referenceId: 'inv_001' },
66
- });
67
- ```
68
-
69
- `adjusts` names the committed entry this delta adjusts, by that entry's `referenceId` or `recordId`. The original stays visible. The API refuses the write when the named entry is missing, pending, or out of scope.
51
+ ### Records
70
52
 
71
53
  #### `pac.records.emit({ record, title, occurredAt, actorId, payloads, amends? })`
72
54
 
73
- Record a records entry. `amends` names a committed entry by `recordKey` and `entry` (the SDK sends `seq` on the wire).
55
+ Record a records entry. `amends` names a committed entry by `recordKey` and `entry`. The SDK counts entries from 1, as every PacSpace page does: `entry: 1` is the first entry of the record, the one the record page calls "Entry 1". The HTTP API and the history file carry the same position as `seq`, counted from 0; the SDK converts at its boundary (`seq = entry - 1`), so you never send or read a `seq`. An `entry` below 1 is refused before anything is sent.
74
56
 
75
57
  ```typescript
76
58
  const entry = await pac.records.emit({
@@ -79,79 +61,64 @@ const entry = await pac.records.emit({
79
61
  occurredAt: '2026-09-14T10:02:00Z',
80
62
  actorId: 'ci',
81
63
  payloads: [{ alg: 'sha-256', digest: 'bb'.repeat(32), byteLength: '1' }],
82
- amends: { recordKey: '0xab', entry: 1 },
64
+ amends: { recordKey: '0xab', entry: 1 }, // corrects the first entry
83
65
  note: 'handoff restated',
84
66
  lifecycle: 'amended',
85
67
  });
86
68
  ```
87
69
 
88
- `pac.records.history({ record })` returns the record's history file and `pac.records.check({ history, expect?, source? })` runs the check in your process. Someone who holds only that file and the fingerprint printed on a statement, with no PacSpace account and no SDK, runs the same check with the standalone checker: `npx @pacspace-io/check history.json --fingerprint 0x...` ([`@pacspace-io/check`](https://www.npmjs.com/package/@pacspace-io/check)). It reads the public source and never calls PacSpace.
70
+ The answer's `entry` is the number this entry will have in its record, counted from 1.
89
71
 
90
- #### `pac.balance.emitAndWait(customerId, delta, reason, options?)`
72
+ `labels` puts up to 10 `name=value` pairs on the record, as an object (`{ model: 'm-0926' }`) or a string (`'model=m-0926, site=press-line-4'`, split on commas, semicolons or new lines, names lowercased). Labels go on the record, never in an entry, and are never committed. Names are lowercase letters, digits, `_`, `.` and `-`, up to 32 characters; values are letters, digits and `._:/-`, up to 64. Labels outside those limits are refused with `RECORD_LABELS_INVALID` before anything is sent. With a workspace secret set, each label is blinded under your workspace's key before it is sent: PacSpace can tell which records share a label, never what the label says.
91
73
 
92
- Record a delta and poll until it reaches a terminal status (`VERIFIED` or `FAILED`).
74
+ #### `pac.records.close(record, { recordType?, lastEntry? })`
75
+
76
+ Closes a record. A close is a fact about the record, not an entry: nothing is written into the record. The close names the record's last entry, counted from 1. Left out, `lastEntry` is the last entry this process wrote to the record, or the record's own last entry, read from PacSpace. A close made while entries are still on their way is refused with `RECORD_CLOSE_SEQ_MISMATCH`; a write to a closed record is refused with `RECORD_CLOSED`. Closing again after the same entry returns `idempotent: true`. With a workspace secret set, the record is closed by its wire id; `encrypted: false` closes a plaintext record.
93
77
 
94
78
  ```typescript
95
- const verified = await pac.balance.emitAndWait('cust_123', -42.50, 'usage', {
96
- timeout: 30_000,
97
- pollInterval: 1000,
98
- });
79
+ await pac.records.emit({ record: 'session-12', title: 'Session 12', occurredAt, actorId: 'agent-7', payloads: [ref], labels: { model: 'm-0926' } });
80
+ const closed = await pac.records.close('session-12');
81
+ // closed.lastEntry, closed.closedAt, closed.lastSeal
99
82
  ```
100
83
 
101
- #### `pac.balance.derive(customerId, options?)`
84
+ `pac.records.receipt({ record, entry })`, `pac.records.history({ record, fromEntry?, toEntry? })`, and `check`'s `expect[].entry` count the same way. The history file itself is the wire document the check verifies by its digest, so its `receipts[].seq` and `entries[].seq` stay the wire's numbers; `check` reports each result as `entry` (`seq + 1`).
102
85
 
103
- Derive a customer's balance from all verified deltas.
86
+ `pac.records.history({ record })` returns the record's history file and `pac.records.check({ history, expect?, source? })` runs the check in your process: every seal, the chain between entries, the file's own digest, and the current word when `source` names the public source. On an encrypted record it first opens each entry with the record's key: the workspace secret's, or the one `grant` and `owner`, `recordKey` or `holderFor` name, as `history` takes them. The verifier is bundled into the SDK (0.10.0 and later); `ethers` is its one runtime dependency. Someone who holds only that file and the fingerprint printed on a statement, with no PacSpace account and no SDK, runs the same check with the standalone checker: `npx @pacspace-io/check history.json --fingerprint 0x...` ([`@pacspace-io/check`](https://www.npmjs.com/package/@pacspace-io/check)). It reads the public source and never calls PacSpace.
104
87
 
105
- ```typescript
106
- const result = await pac.balance.derive('cust_123');
107
- console.log(result.computedBalance);
88
+ #### `fingerprint(input, options?)`
108
89
 
109
- // With checkpointing for efficiency:
110
- const next = await pac.balance.derive('cust_123', {
111
- startingBalance: result.computedBalance,
112
- startingCheckpoint: result.latestReceiptId!,
113
- });
114
- ```
90
+ fingerprint() blinds by default: it mixes a random 32-byte value into the fingerprint, so the fingerprint cannot be matched to a guessed file without the file's blinding file.
115
91
 
116
- #### `pac.balance.compare(customerId, balances, options?)`
92
+ It returns { ref, blinding }. Send ref as the payload. Save blinding beside the file with writeBlindingFile(path, blinding); anyone checking the file later needs it.
117
93
 
118
- Compare balances against neutral truth for dispute resolution.
94
+ To check a file later, pass it with its blinding file: in records.check, expect: [{ entry, files: [{ source, blinding }] }], or fingerprint(file, { blinding }). A blinding belongs to one file; another file is refused.
119
95
 
120
- ```typescript
121
- const report = await pac.balance.compare('cust_123', {
122
- yours: 95000,
123
- theirs: 98000,
124
- });
96
+ The blinding file is as private as the file: whoever holds both can confirm the file is in the record. The file's size is stored as before.
125
97
 
126
- if (report.matchesYours) {
127
- console.log('Your balance is correct');
128
- }
129
- ```
98
+ blind: false, or alg: 'sha-256', gives today's plain sha-256 fingerprint as { ref, blinding: null }. It is not blinded.
99
+
100
+ On Windows the blinding file's permissions are not restricted to you; keep it somewhere only you can read.
130
101
 
131
- #### `pac.balance.receipt(customerId, options?)`
102
+ #### `readWorkspaceSecretFile(path)`
132
103
 
133
- Generate a verifiable receipt. With `options.period` (YYYY-MM), returns a period-specific receipt with `proofRoot`, `verifyUrl`, and `verificationReference`. Treat `verifyUrl` as an opaque invoice link; when Shared Record is enabled it may point at a persistent `/c/{handle}` customer record instead of a proof-root URL.
104
+ readWorkspaceSecretFile() reads a workspace secret file and returns its text, for `records: { secret }`. Node only.
134
105
 
135
106
  ```typescript
136
- // Period receipt (shareable proof for invoices)
137
- const receipt = await pac.balance.receipt('cust_123', { period: '2026-02' });
138
- console.log(receipt.proofRoot); // Proof root for verification
139
- console.log(receipt.verifyUrl); // Share this opaque URL on invoices
140
- console.log(receipt.verificationApiUrl); // Machine endpoint for tools and auditors
141
- console.log(receipt.finalBalance);
142
-
143
- // Full record receipt (all verified deltas)
144
- const full = await pac.balance.receipt('cust_123');
145
- console.log(full.finalBalance);
146
- console.log(full.verification.itemHashes);
107
+ import { PacSpace, readWorkspaceSecretFile } from '@pacspace-io/sdk';
108
+
109
+ const pac = PacSpace.init(process.env.PACSPACE_API_KEY!, {
110
+ records: { secret: await readWorkspaceSecretFile('./pacspace-workspace-secret-sandbox-v1.json') },
111
+ });
147
112
  ```
148
113
 
114
+ It reads the file under either name: Sandbox's `pacspace-workspace-secret-sandbox-v1.json`, or `pacspace-workspace-secret-v1.json`. A file that isn't a workspace secret is refused with RECORDS_SECRET_INVALID. workspaceSecretFileName(version, environment) gives the name the dashboard downloads it under.
115
+
149
116
  #### `pac.verify(proofRoot, options?)`
150
117
 
151
118
  Verify a proof root via the verification endpoint. No API key required. The response contains proof-only facts (validity, timestamps, and chain references); record contents are never returned here.
152
119
 
153
120
  ```typescript
154
- const result = await pac.verify(receipt.proofRoot);
121
+ const result = await pac.verify('0x7f3a9b2c1d4e5f6a...');
155
122
  if (result.verified) {
156
123
  console.log(result.recordedAt);
157
124
  console.log(result.verification?.verificationExplorerUrl);
@@ -161,56 +128,9 @@ if (result.verified) {
161
128
  Use `options.source` to select the verification source:
162
129
 
163
130
  ```typescript
164
- await pac.verify(receipt.proofRoot, { source: 'both' }); // 'db' (default), 'chain', or 'both'
165
- ```
166
-
167
- Use `receipt.verifyUrl` for human invoice links. Use
168
- `receipt.verificationApiUrl` when a tool, agent, or auditor needs to call the
169
- machine verification endpoint. `receipt.verificationExplorerUrl` is a deprecated
170
- legacy compatibility field and will be retained until a future major version.
171
-
172
- #### `pac.balance.checkpoint(customerId?, options?)`
173
-
174
- Commit a period-end checkpoint. The proof root is recorded on the proof layer for independent verification.
175
-
176
- ```typescript
177
- const checkpoint = await pac.balance.checkpoint('cust_123', {
178
- period: '2026-02',
179
- });
180
- console.log(checkpoint.proofRoot); // Include in your invoice
131
+ await pac.verify('0x7f3a9b2c1d4e5f6a...', { source: 'both' }); // 'db' (default), 'chain', or 'both'
181
132
  ```
182
133
 
183
- #### Receipt access grants
184
-
185
- Issue separately revocable, optionally expiring authorizations for receipt
186
- retrieval. The grant token is returned once and only its hash is stored —
187
- share `grantUrl` with the counterparty and revoke the grant at any time to
188
- cut off later retrieval.
189
-
190
- ```typescript
191
- // Issue a recipient-bound grant for an auditor, valid for 30 days
192
- const { grantUrl, grant } = await pac.balance.receipts.createGrant('chk_abc123', {
193
- kind: 'RECIPIENT_BOUND',
194
- recipientEmail: 'auditor@counterparty.com',
195
- ttlHours: 24 * 30,
196
- label: 'Q3 audit',
197
- });
198
- // Deliver grantUrl to the auditor; they confirm their email on retrieval.
199
-
200
- // List every path to a receipt (grants plus Shared Record step-up)
201
- const grants = await pac.balance.receipts.listGrants('chk_abc123');
202
-
203
- // Revoke when the engagement ends
204
- await pac.balance.receipts.revokeGrant('chk_abc123', grant.grantId, {
205
- reason: 'engagement ended',
206
- });
207
- ```
208
-
209
- Grant scopes control what the retrieved receipt carries: `SEMANTIC` (default)
210
- serves record contents with chain-correlation fields stripped, while
211
- `CHAIN_BEARING` produces a self-contained receipt that also carries the proof
212
- root and chain reference for independent verification (ADR 0008 §5).
213
-
214
134
  ### Webhooks
215
135
 
216
136
  Verify webhook signatures and process events with type safety.
@@ -229,8 +149,8 @@ app.use('/webhooks', express.json({
229
149
  app.post('/webhooks/pacspace', pac.webhooks!.middleware(), (req, res) => {
230
150
  const event = (req as any).pacspaceEvent;
231
151
 
232
- if (event.event === 'delta.verified') {
233
- console.log('Delta verified:', event.data.receiptId);
152
+ if (event.event === 'record.committed') {
153
+ console.log('Record committed:', event.data.receiptId);
234
154
  }
235
155
 
236
156
  res.status(200).json({ received: true });
@@ -240,6 +160,8 @@ app.post('/webhooks/pacspace', pac.webhooks!.middleware(), (req, res) => {
240
160
  const event = pac.webhooks!.verify(signature, timestamp, rawBody);
241
161
  ```
242
162
 
163
+ `record.closed` arrives when a record is closed, by your code or by PacSpace after the source's timeout: `{ recordType, entityId, closedBy, lastSeq, lastSeal, closedOn }`, where `closedBy` is `code` or `timeout` and `lastSeq` counts from 0, as the wire does.
164
+
243
165
  ### Error Handling
244
166
 
245
167
  All errors extend `PacSpaceError` with structured data:
@@ -248,7 +170,7 @@ All errors extend `PacSpaceError` with structured data:
248
170
  import { PacSpace, InsufficientCreditsError, RateLimitError } from '@pacspace-io/sdk';
249
171
 
250
172
  try {
251
- await pac.balance.emit('cust_123', -1000, 'charge');
173
+ await pac.records.emit(input);
252
174
  } catch (err) {
253
175
  if (err instanceof InsufficientCreditsError) {
254
176
  console.log('Buy more credits');
@@ -266,7 +188,6 @@ try {
266
188
  | `NotFoundError` | 404 | Resource not found |
267
189
  | `ContractNotDeployedError` | 412 | No contract provisioned |
268
190
  | `RateLimitError` | 429 | Rate limit exceeded |
269
- | `TimeoutError` | — | Polling timeout exceeded |
270
191
 
271
192
  ## Environment Detection
272
193
 
@@ -0,0 +1,13 @@
1
+ import { Blinding } from './blinding';
2
+ /** The name the blinding file takes beside the file it belongs to. */
3
+ export declare const BLINDING_FILE_SUFFIX = ".pacspace.json";
4
+ /**
5
+ * Write the blinding beside its file, as `<filePath>.pacspace.json`, readable
6
+ * by you only (mode 0600; not enforced on Windows). A link or anything but a
7
+ * regular file at that path is refused. The same bytes already there are
8
+ * left as they are; other bytes are refused. Node only. Returns the path.
9
+ */
10
+ export declare function writeBlindingFile(filePath: string, blinding: Blinding): Promise<string>;
11
+ /** Read a blinding file exactly (at most 1024 bytes, the canonical form only). Node only. */
12
+ export declare function readBlindingFile(path: string): Promise<Blinding>;
13
+ //# sourceMappingURL=blinding-file.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"blinding-file.d.ts","sourceRoot":"","sources":["../src/blinding-file.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,QAAQ,EAAoB,MAAM,YAAY,CAAC;AAQxE,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AAUrD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB7F;AAsBD,6FAA6F;AAC7F,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsBtE"}
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Refuse blinding material before anything is sent: a Blinding, a whole
3
+ * fingerprint result, and Rule B (a blinding file, a ref paired with its
4
+ * blinding, or a blinded ref with other fields) at any depth.
5
+ */
6
+ export declare function refuseBlindingMaterial(content: unknown): void;
7
+ //# sourceMappingURL=blinding-guard.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"blinding-guard.d.ts","sourceRoot":"","sources":["../src/blinding-guard.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAe7D"}
@@ -0,0 +1,32 @@
1
+ export declare const BLINDING_WORDS: {
2
+ readonly hidden: "[Blinding: value hidden]";
3
+ readonly noJson: "A blinding cannot be turned into JSON. Save it with writeBlindingFile, or pass the fingerprint's ref.";
4
+ readonly notAFile: "This is not a valid blinding file.";
5
+ readonly otherBytes: "This blinding file does not match these bytes.";
6
+ readonly valueSize: "A blinding value is exactly 32 bytes.";
7
+ };
8
+ /**
9
+ * The blinding value of one blinded fingerprint, beside the digest and size
10
+ * it was made for. The value is held privately and never shown: printing,
11
+ * inspecting or spreading a Blinding shows no value, and JSON.stringify
12
+ * throws. `blindingFileText` is the one way to get the file's text.
13
+ */
14
+ export declare class Blinding {
15
+ #private;
16
+ /** The blinded digest this value was made for (lowercase hex). */
17
+ readonly digest: string;
18
+ /** The file's length, as a decimal string. */
19
+ readonly byteLength: string;
20
+ /** Made by `fingerprint` and `readBlindingFile`; not part of the public API. */
21
+ constructor(value: Uint8Array, digest: string, byteLength: string);
22
+ toJSON(): never;
23
+ toString(): string;
24
+ }
25
+ /** The value, for the SDK's own HMAC and file writer only. */
26
+ export declare function blindingValueOf(blinding: Blinding): Uint8Array;
27
+ /**
28
+ * The blinding file's canonical text. This is the one export that yields the
29
+ * value: keep the text as private as the file it belongs to.
30
+ */
31
+ export declare function blindingFileText(blinding: Blinding): string;
32
+ //# sourceMappingURL=blinding.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"blinding.d.ts","sourceRoot":"","sources":["../src/blinding.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,cAAc;;;;;;CAMjB,CAAC;AAOX;;;;;GAKG;AACH,qBAAa,QAAQ;;IAEnB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAM5B,gFAAgF;gBACpE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;IAcjE,MAAM,IAAI,KAAK;IAIf,QAAQ,IAAI,MAAM;CAOnB;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,UAAU,CAE9D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAQ3D"}
package/dist/client.d.ts CHANGED
@@ -1,6 +1,14 @@
1
1
  import type { PacSpaceConfig, RequestOptions } from './types/config';
2
+ /** Per-call options inside the SDK: extra headers ride beside the public ones. */
3
+ export interface ClientRequestOptions extends RequestOptions {
4
+ headers?: Record<string, string>;
5
+ }
6
+ /** The refusal's own fields (as `recordKid` on a version refusal), for the SDK's retry rules. @internal */
7
+ export declare function apiErrorBody(error: unknown): Record<string, unknown> | undefined;
8
+ /** Keeps a refusal's own fields beside it, for a transport other than this client. @internal */
9
+ export declare function registerApiErrorBody(error: Error, body: Record<string, unknown>): void;
2
10
  /**
3
- * Low-level HTTP client for the Balance API.
11
+ * Low-level HTTP client for the PacSpace API.
4
12
  * Handles authentication, response unwrapping, retries, and error mapping.
5
13
  *
6
14
  * @internal — Use the PacSpace class instead of this directly.
@@ -36,12 +44,27 @@ export declare class HttpClient {
36
44
  /**
37
45
  * Make a GET request and return unwrapped data.
38
46
  */
39
- get<T>(path: string, options?: RequestOptions): Promise<T>;
47
+ get<T>(path: string, options?: ClientRequestOptions): Promise<T>;
48
+ /** PUT, unwrapped; never buffered. */
49
+ put<T>(path: string, body: unknown, options?: ClientRequestOptions): Promise<T>;
50
+ /** DELETE, unwrapped; never buffered. */
51
+ delete<T>(path: string, options?: ClientRequestOptions): Promise<T>;
52
+ /** POST, unwrapped, never buffered: a write whose refusal the caller acts on. */
53
+ postNow<T>(path: string, body: unknown, options?: ClientRequestOptions): Promise<T>;
54
+ /**
55
+ * A request to a link's public routes: no API key, no retries, the
56
+ * response as it came. `init.headers` is the whole header set.
57
+ */
58
+ fetchPublic(path: string, init: {
59
+ method: string;
60
+ headers: Record<string, string>;
61
+ body?: string;
62
+ }): Promise<Response>;
40
63
  /**
41
64
  * GET that returns the parsed body and response headers without requiring
42
65
  * the `{ success, data }` envelope (record history is the digested bundle).
43
66
  */
44
- getRaw<T>(path: string, options?: RequestOptions): Promise<{
67
+ getRaw<T>(path: string, options?: ClientRequestOptions): Promise<{
45
68
  body: T;
46
69
  headers: Headers;
47
70
  status: number;
@@ -49,7 +72,7 @@ export declare class HttpClient {
49
72
  /**
50
73
  * Make a POST request and return unwrapped data.
51
74
  */
52
- post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
75
+ post<T>(path: string, body?: unknown, options?: ClientRequestOptions): Promise<T>;
53
76
  /**
54
77
  * Core request method with retry logic, auth injection, and response unwrapping.
55
78
  */
@@ -72,6 +95,7 @@ export declare class HttpClient {
72
95
  * Safely parse JSON from a response, returning null on failure.
73
96
  */
74
97
  private safeParseJson;
98
+ private mapError;
75
99
  /**
76
100
  * Extract normalized API error fields from an error payload.
77
101
  */
@@ -1 +1 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAoFrE;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuC;IACtE,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,MAAM,CAAS;IAEvB,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,8BAA8B;IAC9B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAC;gBAErC,MAAM,EAAE,cAAc;IAyClC;;OAEG;IACH,UAAU,IAAI,MAAM;IAIpB;;OAEG;IACH,KAAK,CAAC,MAAM,SAAkB,GAAG,IAAI;IAYrC;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAIhE;;;OAGG;IACG,MAAM,CAAC,CAAC,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAIzD;;OAEG;IACG,IAAI,CAAC,CAAC,EACV,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,CAAC,CAAC;IAIb;;OAEG;YACW,OAAO;YA+IP,UAAU;IAqCxB;;OAEG;IACH,OAAO,CAAC,YAAY;IA4BpB;;OAEG;YACW,gBAAgB;IAoC9B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAoBrB;;OAEG;YACW,aAAa;IAU3B;;OAEG;IACH,OAAO,CAAC,eAAe;IAkCvB,OAAO,CAAC,SAAS;IAgBjB,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,QAAQ;IAahB,OAAO,CAAC,mBAAmB;IA6B3B,OAAO,CAAC,sBAAsB;IA4D9B,OAAO,CAAC,qBAAqB;IAO7B,OAAO,CAAC,mBAAmB;YAiBb,mBAAmB;IA0CjC,OAAO,CAAC,gBAAgB;IAYxB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAWrB;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;IACH,OAAO,CAAC,KAAK;CAGd"}
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAqFrE,kFAAkF;AAClF,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAID,2GAA2G;AAC3G,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEhF;AAED,gGAAgG;AAChG,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAEtF;AAOD;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuC;IACtE,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,MAAM,CAAS;IAEvB,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,8BAA8B;IAC9B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAC;gBAErC,MAAM,EAAE,cAAc;IAyClC;;OAEG;IACH,UAAU,IAAI,MAAM;IAIpB;;OAEG;IACH,KAAK,CAAC,MAAM,SAAkB,GAAG,IAAI;IAYrC;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,CAAC,CAAC;IAItE,sCAAsC;IAChC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,CAAC,CAAC;IAIrF,yCAAyC;IACnC,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,CAAC,CAAC;IAIzE,iFAAiF;IAC3E,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,CAAC,CAAC;IAIzF;;;OAGG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;IAO5H;;;OAGG;IACG,MAAM,CAAC,CAAC,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAIzD;;OAEG;IACG,IAAI,CAAC,CAAC,EACV,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,CAAC,CAAC;IAIb;;OAEG;YACW,OAAO;YA6HP,UAAU;IA+BxB;;OAEG;IACH,OAAO,CAAC,YAAY;IA4BpB;;OAEG;YACW,gBAAgB;IAoC9B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAoBrB;;OAEG;YACW,aAAa;IAU3B,OAAO,CAAC,QAAQ;IAIhB;;OAEG;IACH,OAAO,CAAC,eAAe;IAoCvB,OAAO,CAAC,SAAS;IAgBjB,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,QAAQ;IAahB,OAAO,CAAC,mBAAmB;IA6B3B,OAAO,CAAC,sBAAsB;IA4D9B,OAAO,CAAC,qBAAqB;IAO7B,OAAO,CAAC,mBAAmB;YAiBb,mBAAmB;IA0CjC,OAAO,CAAC,gBAAgB;IAYxB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAWrB;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;IACH,OAAO,CAAC,KAAK;CAGd"}
@@ -1,14 +1,35 @@
1
+ import { Blinding } from './blinding';
1
2
  export interface PayloadRef {
2
- alg: 'sha-256';
3
+ alg: 'sha-256' | 'hmac-sha-256';
3
4
  digest: string;
4
5
  byteLength: string;
5
6
  }
7
+ export interface FingerprintOptions {
8
+ /** Blind the fingerprint with a fresh random value (the default). */
9
+ blind?: boolean;
10
+ /** An alias: 'sha-256' is blind: false, 'hmac-sha-256' is blind: true. */
11
+ alg?: 'sha-256' | 'hmac-sha-256';
12
+ /** The same file again: recompute with this blinding and return the same ref. */
13
+ blinding?: Blinding;
14
+ }
15
+ export interface FingerprintResult {
16
+ /** Send this as the payload. */
17
+ ref: PayloadRef;
18
+ /** Save this beside the file with writeBlindingFile; null when not blinded. */
19
+ blinding: Blinding | null;
20
+ }
21
+ /** True for an object `fingerprint` returned: the whole result, never a payload. */
22
+ export declare function isFingerprintResult(value: unknown): boolean;
6
23
  export type FingerprintInput = File | Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array> | Iterable<Uint8Array> | AsyncIterable<Uint8Array>;
24
+ export declare function chunksOf(input: FingerprintInput): AsyncGenerator<Uint8Array>;
7
25
  /**
8
26
  * Fingerprint bytes where they live. PacSpace receives the digest and size,
9
- * never the file. Wraps the same sha-256 rule as `digestPayload`.
27
+ * never the file. Blinded by default: an HMAC-SHA256 under a fresh 32-byte
28
+ * value, returned as `{ ref, blinding }`; send `ref` and keep `blinding`
29
+ * beside the file. `{ blind: false }` gives the plain sha-256 reference
30
+ * (the same rule as `digestPayload`) with `blinding: null`.
10
31
  */
11
- export declare function fingerprint(input: FingerprintInput, options?: {
12
- alg?: 'sha-256';
13
- }): Promise<PayloadRef>;
32
+ export declare function fingerprint(input: FingerprintInput, options?: FingerprintOptions): Promise<FingerprintResult>;
33
+ /** The plain sha-256 reference, unchanged from 0.11.0. */
34
+ export declare function plainRef(input: FingerprintInput): Promise<PayloadRef>;
14
35
  //# sourceMappingURL=fingerprint.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,gBAAgB,GACxB,IAAI,GACJ,IAAI,GACJ,WAAW,GACX,UAAU,GACV,cAAc,CAAC,UAAU,CAAC,GAC1B,QAAQ,CAAC,UAAU,CAAC,GACpB,aAAa,CAAC,UAAU,CAAC,CAAC;AAwD9B;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,gBAAgB,EACvB,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,SAAS,CAAA;CAAE,GAC5B,OAAO,CAAC,UAAU,CAAC,CA6CrB"}
1
+ {"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,QAAQ,EAAmB,MAAM,YAAY,CAAC;AAGvE,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,SAAS,GAAG,cAAc,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0EAA0E;IAC1E,GAAG,CAAC,EAAE,SAAS,GAAG,cAAc,CAAC;IACjC,iFAAiF;IACjF,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,GAAG,EAAE,UAAU,CAAC;IAChB,+EAA+E;IAC/E,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC3B;AASD,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED,MAAM,MAAM,gBAAgB,GACxB,IAAI,GACJ,IAAI,GACJ,WAAW,GACX,UAAU,GACV,cAAc,CAAC,UAAU,CAAC,GAC1B,QAAQ,CAAC,UAAU,CAAC,GACpB,aAAa,CAAC,UAAU,CAAC,CAAC;AAc9B,wBAAuB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,cAAc,CAAC,UAAU,CAAC,CAwCnF;AAyCD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAMnH;AAED,0DAA0D;AAC1D,wBAAsB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAqC3E"}
package/dist/index.d.ts CHANGED
@@ -1,35 +1,35 @@
1
- import { BalanceResource } from './resources/balance';
2
- import { CustomersResource } from './resources/customers';
3
1
  import { RecordsResource } from './resources/records';
4
2
  import { Webhooks } from './webhooks/verify';
5
3
  import type { PacSpaceConfig } from './types/config';
6
- import type { VerifyResponse, VerifySource } from './types/balance';
4
+ import type { VerifyResponse, VerifySource } from './types/verify';
7
5
  /**
8
- * PacSpace SDK — the official TypeScript client for the PacSpace Balance API.
6
+ * PacSpace SDK: the official TypeScript client for the PacSpace API.
9
7
  *
10
8
  * @example
11
9
  * ```typescript
12
- * import { PacSpace } from '@pacspace-io/sdk';
10
+ * import { PacSpace, fingerprint } from '@pacspace-io/sdk';
13
11
  *
14
12
  * const pac = new PacSpace({ apiKey: process.env.PACSPACE_API_KEY! });
15
13
  *
16
- * // Record a delta
17
- * const delta = await pac.balance.emit('cust_123', -42.50, 'usage_charge');
18
- *
19
- * // Derive balance
20
- * const { computedBalance } = await pac.balance.derive('cust_123');
21
- *
22
- * // Compare against counterparty
23
- * const report = await pac.balance.compare('cust_123', {
24
- * yours: 95000,
25
- * theirs: 98000,
14
+ * // Record an entry
15
+ * const { ref, blinding } = await fingerprint(fileBytes);
16
+ * const entry = await pac.records.emit({
17
+ * record: 'build-1',
18
+ * title: 'Handoff',
19
+ * occurredAt: '2026-09-14T10:02:00Z',
20
+ * actorId: 'ci',
21
+ * payloads: [ref],
26
22
  * });
27
23
  *
28
- * // Period-end receipt (shareable verification proof)
29
- * const receipt = await pac.balance.receipt('cust_123', { period: '2026-02' });
24
+ * // Read the history and check it in your process
25
+ * const history = await pac.records.history({ record: 'build-1' });
26
+ * const check = await pac.records.check({
27
+ * history,
28
+ * expect: [{ entry: 1, files: [{ source: fileBytes, blinding }] }],
29
+ * });
30
30
  *
31
31
  * // Verify a proof root (public, no auth)
32
- * const verification = await pac.verify(receipt.proofRoot);
32
+ * const verification = await pac.verify('0x7f3a9b2c1d4e5f6a...');
33
33
  * ```
34
34
  */
35
35
  export declare class PacSpace {
@@ -43,14 +43,6 @@ export declare class PacSpace {
43
43
  private readonly baseUrl;
44
44
  private readonly fetchFn;
45
45
  private readonly timeoutMs;
46
- /**
47
- * Balance API resource — emit deltas, derive balances, compare, receipt, checkpoint.
48
- */
49
- readonly balance: BalanceResource;
50
- /**
51
- * Dashboard customer helpers.
52
- */
53
- readonly customers: CustomersResource;
54
46
  /**
55
47
  * Records API resource — fingerprint a file, emit, read a receipt or history, check.
56
48
  */
@@ -64,7 +56,7 @@ export declare class PacSpace {
64
56
  * Create a new PacSpace SDK instance.
65
57
  *
66
58
  * @param config - SDK configuration.
67
- * @param config.apiKey - Your Balance API key (required).
59
+ * @param config.apiKey - Your PacSpace API key (required).
68
60
  * @param config.baseUrl - API base URL (optional, overrides the key-based choice).
69
61
  * @param config.sandboxUrl - Custom sandbox URL (optional, used for `pk_test_*` keys; the default is the same host as production, where the key decides the environment).
70
62
  * @param config.productionUrl - Custom production URL (optional, used for `pk_live_*` keys).
@@ -78,7 +70,7 @@ export declare class PacSpace {
78
70
  */
79
71
  close(reason?: string): void;
80
72
  /**
81
- * Graceful shutdown: flush summary queue and close the client.
73
+ * Graceful shutdown: an async alias of `close()`.
82
74
  */
83
75
  shutdown(reason?: string): Promise<void>;
84
76
  /**
@@ -111,15 +103,23 @@ export declare class PacSpace {
111
103
  }): Promise<VerifyResponse>;
112
104
  }
113
105
  export type { PacSpaceConfig, RequestOptions } from './types/config';
114
- export type { RecordStatus, CheckpointType } from './types/common';
115
- export type { AdjustsRef, EmitOptions, EmitAndWaitOptions, EmitResponse, DeriveOptions, DeriveResponse, VerifiedDelta, WindowSummary, CompareOptions, CompareBalances, CompareResponse, DiscrepancyReport, ReceiptResponse, ReceiptDocument, ReceiptStatementRow, ReceiptDailyTotal, ReceiptListItem, ReceiptGetOptions, ReceiptListOptions, ReceiptGrantKind, ReceiptGrantScope, ReceiptGrantStatus, ReceiptAccessGrant, CreateReceiptGrantParams, CreateReceiptGrantResponse, CheckpointOptions, CheckpointResponse, CheckpointTimelinePoint, CheckpointTimelineGap, CheckpointTimelineResponse, ListCheckpointTimelineOptions, CheckpointDiffResponse, DeltaStatusResponse, WaitForVerifiedOptions, UsageResponse, SequenceGapsOptions, SequenceGapRange, SequenceGapsResponse, ListWebhookDeliveriesOptions, ListWebhookDeliveriesResponse, CustomerRecordSummary, CustomerRecordDetail, CustomerRecordActivity, ListCustomersOptions, ListCustomersResponse, GetCustomerOptions, InvoiceProofOptions, InvoiceProofResponse, InvoiceProofDelta, InvoiceProofWindowSummary, InvoiceProofVerification, VerifySource, VerifyResponse, VerifySummary, VerifyRecord, VerifyVerification, } from './types/balance';
116
- export type { CreateCustomerOptions, CreateCustomerResponse, CustomerEventCadence, CustomerSharingState, } from './resources/customers';
117
- export type { SubmissionProfile, SubmissionAutomationOptions, CustomerUsageSummary, QueuedUsageSummary, FlushSummariesOptions, SummaryFlushFailure, SummaryFlushResult, SubmissionQueueState, } from './types/submission';
106
+ export type { VerifySource, VerifyResponse, VerifySummary, VerifyRecord, VerifyVerification, } from './types/verify';
118
107
  export { PacSpaceError, InvalidApiKeyError, InsufficientCreditsError, NotFoundError, ContractNotDeployedError, CadenceLimitError, RateLimitError, ServiceUnavailableError, ValidationError, InvalidScopeCombinationError, ScopeTooWideError, ReceiptNotFoundError, ReceiptNotReadyError, TimeoutError, WebhookVerificationError, } from './errors';
119
108
  export { Webhooks } from './webhooks/verify';
120
109
  export type { VerifyOptions, } from './webhooks/verify';
121
- export type { KnownWebhookEventType, WebhookEventType, WebhookEvent, WebhookEventMap, WebhookHeaders, DeltaVerifiedPayload, DeltaFailedPayload, CustomerCreatedPayload, RecordCommittedPayload, RecordFailedPayload, } from './webhooks/types';
110
+ export type { KnownWebhookEventType, WebhookEventType, WebhookEvent, WebhookEventMap, WebhookHeaders, DeltaVerifiedPayload, DeltaFailedPayload, RecordCommittedPayload, RecordFailedPayload, RecordClosedPayload, } from './webhooks/types';
122
111
  export { fingerprint } from './fingerprint';
123
- export type { FingerprintInput, PayloadRef } from './fingerprint';
124
- export type { RecordCheckExpect, RecordCheckInput, RecordCheckSource, RecordEmitInput, RecordEmitResponse, RecordEntryStatus, RecordHistory, RecordHistoryCheck, RecordHistoryInput, RecordLifecycle, RecordReceiptInput, RecordReceiptResponse, } from './types/records';
112
+ export type { FingerprintInput, FingerprintOptions, FingerprintResult, PayloadRef } from './fingerprint';
113
+ export { blindingFileText } from './blinding';
114
+ export type { Blinding } from './blinding';
115
+ export { readBlindingFile, writeBlindingFile } from './blinding-file';
116
+ export type { EntryNumber, RecordCheckEntryResult, RecordCheckExpect, RecordCheckFile, RecordCheckInput, RecordCheckSource, RecordDiscloseEntry, RecordDiscloseInput, RecordDisclosureFile, RecordEmitInput, RecordEmitResponse, RecordEntryRef, RecordEntryStatus, RecordHistory, RecordHistoryEntry, RecordHistoryCheck, RecordHistoryInput, RecordLifecycle, RecordLabels, RecordCloseOptions, RecordCloseResponse, RecordReceiptInput, RecordReceiptResponse, RecordReadOptions, OpenedRecordEntry, } from './types/records';
117
+ export { generateWorkspaceSecret, nextWorkspaceSecret } from './records-encryption/workspace-secret';
118
+ export { readWorkspaceSecretFile, workspaceSecretFileName, type WorkspaceSecretEnvironment } from './workspace-secret-file';
119
+ export { memoryPinStore } from './records-encryption/pin-store';
120
+ export { filePinStore } from './records-encryption/pin-store-file';
121
+ export type { RecordsPin, RecordsPinStore } from './records-encryption/pin-store';
122
+ export { RecordsEncryptionError, RECORDS_ENCRYPTION_WORDS } from './records-encryption/words';
123
+ export type { RecordsEncryptionCode } from './records-encryption/words';
124
+ export type { RecordCopyFile, RecordOpenOptions, RecordOpenResult, RecordRekeyInput, RecordRekeyResult, RecordRotateResult, RecordTarget, RecordsEncryptionOptions, RecordsGrantCreateInput, RecordsHolderAddInput, RecordsHolderAddResult, RecordsHoldingResult, RecordsIdentityResult, RecordsSecretSource, RecordsShareKeyWrapInput, } from './types/records-encryption';
125
125
  //# sourceMappingURL=index.d.ts.map