@facto-to/card 0.0.0-stage → 0.0.1-beta.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 (69) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +5 -0
  4. package/README.md +63 -2
  5. package/dist/card-inbox-DzsHFRPT.d.cts +312 -0
  6. package/dist/card-inbox-DzsHFRPT.d.ts +312 -0
  7. package/dist/chunk-KBS2PWM4.js +2 -0
  8. package/dist/cli/index.js +6 -0
  9. package/dist/docs/README.md +9 -0
  10. package/dist/docs/authentication.md +96 -0
  11. package/dist/docs/authorization-binding.md +182 -0
  12. package/dist/docs/authorizations.md +182 -0
  13. package/dist/docs/concepts.md +36 -0
  14. package/dist/docs/deliveries.md +170 -0
  15. package/dist/docs/errors.md +100 -0
  16. package/dist/docs/getting-access.md +56 -0
  17. package/dist/docs/idempotency.md +78 -0
  18. package/dist/docs/integration-checklist.md +15 -0
  19. package/dist/docs/integration.zh.md +59 -0
  20. package/dist/docs/interlace-adapter-v1.md +87 -0
  21. package/dist/docs/interlace-adapter-v1.zh.md +87 -0
  22. package/dist/docs/not-yet-available.md +13 -0
  23. package/dist/docs/quickstart.md +126 -0
  24. package/dist/docs/reconciliation.md +86 -0
  25. package/dist/docs/reference/api.md +2541 -0
  26. package/dist/docs/reference/events.md +639 -0
  27. package/dist/docs/reference/schemas.json +6603 -0
  28. package/dist/docs/reference/schemas.md +1001 -0
  29. package/dist/docs/simulator.md +235 -0
  30. package/dist/docs/versioning.md +9 -0
  31. package/dist/index.cjs +3 -0
  32. package/dist/index.d.cts +987 -0
  33. package/dist/index.d.ts +987 -0
  34. package/dist/index.js +2 -0
  35. package/dist/source/build.mjs +5 -0
  36. package/dist/source/package.json +16 -0
  37. package/dist/source/src/connect/cli/deliveries.ts +48 -0
  38. package/dist/source/src/connect/cli/index.ts +57 -0
  39. package/dist/source/src/connect/server/card-binding-assertion.ts +312 -0
  40. package/dist/source/src/connect/server/card-client.ts +1018 -0
  41. package/dist/source/src/connect/server/card-delivery.ts +301 -0
  42. package/dist/source/src/connect/server/card-events.ts +473 -0
  43. package/dist/source/src/connect/server/card-idempotency.ts +27 -0
  44. package/dist/source/src/connect/server/card-inbox.ts +82 -0
  45. package/dist/source/src/connect/server/card-intent-token.ts +588 -0
  46. package/dist/source/src/connect/server/card-polling.ts +69 -0
  47. package/dist/source/src/connect/server/card-signing.ts +115 -0
  48. package/dist/source/src/connect/server/card-transport.ts +282 -0
  49. package/dist/source/src/connect/server/errors.ts +280 -0
  50. package/dist/source/src/connect/server/fixtures/engine/card-events.synthetic.ts +84 -0
  51. package/dist/source/src/connect/server/retry-after.ts +12 -0
  52. package/dist/source/src/connect/testing/card-inbox.ts +124 -0
  53. package/dist/source/src/connect/testing/card-scenarios.ts +243 -0
  54. package/dist/source/src/connect/testing/card-simulator-vectors.ts +262 -0
  55. package/dist/source/src/connect/testing/card-simulator.ts +531 -0
  56. package/dist/source/src/connect/testing/interlace-card-transactions.ts +704 -0
  57. package/dist/source/src/connect/testing/pure-sha256.ts +123 -0
  58. package/dist/source/src/connect/wire.d.ts +544 -0
  59. package/dist/source/src/index.ts +163 -0
  60. package/dist/source/src/testing-browser.ts +24 -0
  61. package/dist/source/src/testing.ts +26 -0
  62. package/dist/source/tsconfig.json +20 -0
  63. package/dist/testing-browser.d.ts +220 -0
  64. package/dist/testing-browser.js +5 -0
  65. package/dist/testing.cjs +6 -0
  66. package/dist/testing.d.cts +199 -0
  67. package/dist/testing.d.ts +199 -0
  68. package/dist/testing.js +5 -0
  69. package/package.json +60 -4
@@ -0,0 +1,262 @@
1
+ import { randomUUID } from 'node:crypto'
2
+ import { createCardClient } from '../server/card-client'
3
+ import { signCardRequest, type CardApiKeySecret } from '../server/card-signing'
4
+ import { CardError } from '../server/errors'
5
+ import { isCardNestedErrorEnvelope } from '../server/card-transport'
6
+ import { deliveryInboxVectors } from './card-inbox'
7
+ import { simulatorIdentity, simulatorSelection, simulatorTarget } from './card-simulator'
8
+
9
+ function hasStatus(error: unknown, status: number, code?: string): boolean {
10
+ if (!error || typeof error !== 'object' || !('status' in error) || error.status !== status) return false
11
+ if (!code) return true
12
+ return 'details' in error && !!error.details && typeof error.details === 'object' && 'error' in error.details && error.details.error === code
13
+ }
14
+
15
+ export async function runCardSimulatorVectors(url: string, report: (line: string) => void = console.log): Promise<boolean> {
16
+ const endpoint = new URL(url)
17
+ if (endpoint.protocol !== 'http:' || endpoint.hostname !== '127.0.0.1' || endpoint.pathname !== '/' || endpoint.search || endpoint.hash || endpoint.username || endpoint.password) throw new Error('Simulator vectors only support a loopback HTTP origin')
18
+ const client = (extra: { apiKeySecret?: CardApiKeySecret; nowSeconds?: () => number; createNonce?: () => string } = {}) =>
19
+ createCardClient({ environment: 'dev', ...simulatorIdentity, apiBaseUrl: endpoint.origin, ...extra })
20
+ const instance = client()
21
+ const suffix = randomUUID()
22
+ const auth = {
23
+ external_card_id: 'synthetic-card',
24
+ external_authorization_id: `synthetic-${suffix}`,
25
+ supplier_transaction_id: `synthetic-supplier-${suffix}`,
26
+ amount: '1.00',
27
+ currency: 'USD' as const,
28
+ cardholder_verification: { method: 'provider_attested' as const, verified_at: '2026-01-01T00:00:00Z', evidence_id: 'synthetic-proof' },
29
+ resource_version: 'v1',
30
+ mapping_revision: 'v1',
31
+ }
32
+ const key = `synthetic-key-${suffix}`
33
+ const separate = (name: string) => ({
34
+ ...auth,
35
+ external_authorization_id: `${auth.external_authorization_id}-${name}`,
36
+ supplier_transaction_id: `${auth.supplier_transaction_id}-${name}`,
37
+ })
38
+ const lookupByKey = (idempotencyKey: string) =>
39
+ instance.authorizations.lookup({
40
+ by: 'idempotency_key',
41
+ idempotency_key: idempotencyKey,
42
+ original_credential_key_id: simulatorIdentity.apiKeyId,
43
+ })
44
+ const rawPost = async (target: string, body: string, idempotencyKey: string) => {
45
+ const headers = signCardRequest({
46
+ secret: simulatorIdentity.apiKeySecret,
47
+ apiKeyId: simulatorIdentity.apiKeyId,
48
+ method: 'POST',
49
+ target,
50
+ timestamp: Math.floor(Date.now() / 1000),
51
+ nonce: randomUUID(),
52
+ body,
53
+ idempotencyKey,
54
+ })
55
+ headers.set('content-type', 'application/json')
56
+ return fetch(`${endpoint.origin}${target}`, { method: 'POST', headers, body, redirect: 'error' })
57
+ }
58
+
59
+ let good = true
60
+ let chargeId = ''
61
+ async function vector(name: string, fn: () => Promise<boolean>) {
62
+ try { if (await fn()) { report(`vector_passed:${name}`); return } } catch { /* Report failures without leaking response bodies. */ }
63
+ good = false; report(`vector_failed:${name}`)
64
+ }
65
+
66
+ await vector('authorization', async () => {
67
+ const accepted = await instance.authorizations.create(auth, { idempotencyKey: key })
68
+ chargeId = accepted.charge_id
69
+ return accepted.status === 'processing'
70
+ })
71
+ await vector('authorization_replay', async () =>
72
+ (await instance.authorizations.create(auth, { idempotencyKey: key })).charge_id === chargeId && chargeId !== '',
73
+ )
74
+ await vector('integrity_conflict', async () => {
75
+ try { await instance.authorizations.create({ ...auth, amount: '2.00' }, { idempotencyKey: key }); return false }
76
+ catch (e) { return hasStatus(e, 409, 'integrity_conflict') }
77
+ })
78
+ await vector('operation_identity_conflict', async () => {
79
+ try { await instance.authorizations.create({ ...auth, amount: '2.00' }, { idempotencyKey: `different-key-${suffix}` }); return false }
80
+ catch (e) { return hasStatus(e, 409, 'integrity_conflict') }
81
+ })
82
+ await vector('byte_integrity_conflict', async () => {
83
+ const response = await rawPost('/api/card/authorizations', JSON.stringify({ ...auth, program_id: simulatorIdentity.programId }, null, 2), key)
84
+ const body: unknown = await response.json()
85
+ return response.status === 409 && !!body && typeof body === 'object' && 'error' in body && body.error === 'integrity_conflict'
86
+ })
87
+
88
+ const fact = {
89
+ fact_type: 'clearing' as const,
90
+ supplier_transaction_id: auth.supplier_transaction_id,
91
+ amount: '1.00',
92
+ currency: 'USD' as const,
93
+ resource_version: 'v2',
94
+ predecessor_version: 'v1',
95
+ mapping_revision: 'v1',
96
+ recorded_at: '2026-01-01T01:00:00Z',
97
+ }
98
+ await vector('clearing_fact', async () =>
99
+ (await instance.authorizations.recordFact(auth.external_authorization_id, fact, { idempotencyKey: `fact-${suffix}` })).status === 'recorded',
100
+ )
101
+ await vector('fact_status', async () => {
102
+ const result = await instance.authorizations.lookup({
103
+ by: 'external_authorization_id',
104
+ external_authorization_id: auth.external_authorization_id,
105
+ resource_version: fact.resource_version,
106
+ mapping_revision: fact.mapping_revision,
107
+ })
108
+ return result.resolution === 'unknown' && result.authorization.facts?.[0]?.state === 'unobserved' && result.authorization.facts?.[1]?.state === 'confirmed'
109
+ })
110
+ await vector('fact_missing_predecessor', async () => {
111
+ const { predecessor_version: _predecessor, ...missing } = fact
112
+ const response = await rawPost(`/api/card/authorizations/${encodeURIComponent(auth.external_authorization_id)}/facts`, JSON.stringify({ ...missing, program_id: simulatorIdentity.programId }), `missing-${suffix}`)
113
+ return response.status === 400
114
+ })
115
+ await vector('fact_version_conflict', async () => {
116
+ try {
117
+ await instance.authorizations.recordFact(auth.external_authorization_id, { ...fact, fact_type: 'reversal', resource_version: 'v1', predecessor_version: 'v2' }, { idempotencyKey: `conflict-${suffix}` })
118
+ return false
119
+ } catch (e) { return hasStatus(e, 409, 'integrity_conflict') }
120
+ })
121
+ for (const [index, fact_type] of (['authorization_updated', 'reversal', 'refund', 'chargeback', 'settlement'] as const).entries()) {
122
+ await vector(`fact_${fact_type}`, async () =>
123
+ (await instance.authorizations.recordFact(auth.external_authorization_id, { ...fact, fact_type, resource_version: `v${index + 3}`, predecessor_version: `v${index + 2}` }, { idempotencyKey: `fact-${fact_type}-${suffix}` })).status === 'recorded',
124
+ )
125
+ }
126
+
127
+ await vector('status', async () => {
128
+ const result = await instance.authorizations.lookup({
129
+ by: 'external_authorization_id',
130
+ external_authorization_id: auth.external_authorization_id,
131
+ resource_version: auth.resource_version,
132
+ mapping_revision: auth.mapping_revision,
133
+ })
134
+ return result.resolution === 'pending' && result.authorization.facts?.[0]?.state === 'confirmed' && result.authorization.facts?.[1]?.state === 'confirmed'
135
+ })
136
+ await vector('status_supplier_ref', async () =>
137
+ (await instance.authorizations.lookup({
138
+ by: 'supplier_transaction_id',
139
+ supplier_transaction_id: auth.supplier_transaction_id,
140
+ resource_version: auth.resource_version,
141
+ mapping_revision: auth.mapping_revision,
142
+ })).resolution === 'pending',
143
+ )
144
+ await vector('trimmed_supplier_ref', async () => {
145
+ const input = { ...separate('trimmed'), supplier_transaction_id: ` supplier-trim-${suffix} ` }
146
+ await instance.authorizations.create(input, { idempotencyKey: `trimmed-${suffix}` })
147
+ const result = await instance.authorizations.lookup({
148
+ by: 'supplier_transaction_id',
149
+ supplier_transaction_id: input.supplier_transaction_id.trim(),
150
+ resource_version: input.resource_version,
151
+ mapping_revision: input.mapping_revision,
152
+ })
153
+ return result.resolution === 'pending' && result.authorization.supplier_transaction_id === input.supplier_transaction_id.trim()
154
+ })
155
+ await vector('supplier_namespace_conflict', async () => {
156
+ try {
157
+ await instance.authorizations.create({ ...separate('supplier-conflict'), supplier_transaction_id: auth.supplier_transaction_id, mapping_revision: 'other-mapping' }, { idempotencyKey: `supplier-conflict-${suffix}` })
158
+ return false
159
+ } catch (error) { return hasStatus(error, 409, 'integrity_conflict') }
160
+ })
161
+ await vector('status_idempotency_key', async () => (await lookupByKey(key)).resolution === 'pending')
162
+ await vector('status_charge_id', async () =>
163
+ (await instance.authorizations.lookup({ by: 'charge_id', charge_id: chargeId })).resolution === 'pending',
164
+ )
165
+ await vector('status_not_observed', async () => (await lookupByKey(`absent-${suffix}`)).resolution === 'not_observed')
166
+ await vector('status_failed_receipt', async () => {
167
+ const failedKey = `failed-${suffix}`
168
+ await instance.authorizations.create({ ...separate('failed'), external_card_id: 'synthetic-failed-card' }, { idempotencyKey: failedKey })
169
+ if ((await lookupByKey(failedKey)).resolution !== 'pending') return false
170
+ const result = await lookupByKey(failedKey)
171
+ return result.resolution === 'resolved' && result.authorization.processing_status === 'failed'
172
+ && result.authorization.final_receipt?.execution_outcome === 'failed'
173
+ && result.authorization.final_receipt.terminal_action === 'cancelReservation'
174
+ })
175
+
176
+ const syncKey = `sync-${suffix}`, expiredKey = `expired-${suffix}`, declinedKey = `declined-${suffix}`
177
+ await vector('sync_closed', async () => {
178
+ const result = await instance.authorizations.create({ ...separate('sync'), decision_mode: 'synchronous' }, { idempotencyKey: syncKey })
179
+ return 'error' in result && result.error === 'sync_approval_admission_closed'
180
+ })
181
+ await vector('sync_expired', async () => {
182
+ const result = await instance.authorizations.create({ ...separate('expired'), decision_mode: 'synchronous', deadline_at: '2020-01-01T00:00:00Z' }, { idempotencyKey: expiredKey })
183
+ return 'error' in result && result.error === 'decision_deadline_exceeded'
184
+ })
185
+ await vector('explicit_402', async () => {
186
+ try { await instance.authorizations.create({ ...separate('declined'), external_card_id: 'synthetic-declined-card' }, { idempotencyKey: declinedKey }); return false }
187
+ catch (e) { return hasStatus(e, 402, 'spending_limit_exceeded') }
188
+ })
189
+ await vector('status_sync_closed', async () => {
190
+ const result = await lookupByKey(syncKey)
191
+ return result.resolution === 'resolved' && result.authorization.processing_status === 'failed'
192
+ && result.authorization.decision === 'declined'
193
+ && result.authorization.decline_reason_code === 'sync_approval_admission_closed'
194
+ && result.authorization.charge_id === undefined
195
+ })
196
+ await vector('status_sync_expired', async () => {
197
+ const result = await lookupByKey(expiredKey)
198
+ return result.resolution === 'resolved' && result.authorization.processing_status === 'failed'
199
+ && result.authorization.decision === 'self_reversed_timeout'
200
+ && result.authorization.decline_reason_code === 'decision_deadline_exceeded'
201
+ && result.authorization.charge_id === undefined
202
+ })
203
+ await vector('status_explicit_402', async () => {
204
+ const result = await lookupByKey(declinedKey)
205
+ return result.resolution === 'resolved' && result.authorization.processing_status === 'failed'
206
+ && result.authorization.decline_reason_code === 'spending_limit_exceeded'
207
+ })
208
+ await vector('retry_503', async () => {
209
+ const retryInput = { ...separate('retry'), external_card_id: 'synthetic-retry-card' }
210
+ const retryKey = `retry-${suffix}`
211
+ try { await instance.authorizations.create(retryInput, { idempotencyKey: retryKey }); return false }
212
+ catch (error) {
213
+ if (!hasStatus(error, 503) || !error || typeof error !== 'object' || !('retryable' in error) || error.retryable !== true) return false
214
+ }
215
+ return (await instance.authorizations.create(retryInput, { idempotencyKey: retryKey })).status === 'processing'
216
+ })
217
+ await vector('retry_after_429', async () => {
218
+ try { await instance.authorizations.create({ ...separate('rate'), external_card_id: 'synthetic-rate-limited-card' }, { idempotencyKey: `rate-${suffix}` }); return false }
219
+ catch (error) {
220
+ return error instanceof CardError && error.status === 429 && error.code === 'FACTO_ENGINE_REQUEST_FAILED'
221
+ && error.outcome === 'unknown' && error.retryable && error.retryAfterSeconds === 2
222
+ && isCardNestedErrorEnvelope(error.details) && error.details.error.code === 'too_many_requests'
223
+ }
224
+ })
225
+ await vector('invalid_502', async () => {
226
+ try { await instance.authorizations.create({ ...separate('gateway'), external_card_id: 'synthetic-bad-gateway-card' }, { idempotencyKey: `gateway-${suffix}` }); return false }
227
+ catch (error) {
228
+ return error instanceof CardError && error.status === 502 && error.code === 'FACTO_ENGINE_RESPONSE_INVALID'
229
+ && error.outcome === 'unknown' && error.retryable && error.retryAfterSeconds === 2
230
+ }
231
+ })
232
+ await vector('nested_500_hint_false', async () => {
233
+ try { await instance.authorizations.create({ ...separate('nested-500'), external_card_id: 'synthetic-nested-500-card' }, { idempotencyKey: `nested-500-${suffix}` }); return false }
234
+ catch (error) {
235
+ return error instanceof CardError && error.status === 500 && error.code === 'FACTO_ENGINE_REQUEST_FAILED'
236
+ && error.outcome === 'unknown' && error.retryable && isCardNestedErrorEnvelope(error.details) && error.details.error.retryable === false
237
+ }
238
+ })
239
+ await vector('bad_signature', async () => {
240
+ try { await client({ apiKeySecret: { encoding: 'utf8', value: 'wrong-synthetic-test-key' } }).deliveries.list({ target_revision: simulatorTarget, selection_id: simulatorSelection, page_size: 1 }); return false }
241
+ catch (e) { return hasStatus(e, 401) }
242
+ })
243
+ await vector('expired_timestamp', async () => {
244
+ try { await client({ nowSeconds: () => Math.floor(Date.now() / 1000) - 301 }).deliveries.list({ target_revision: simulatorTarget, selection_id: simulatorSelection, page_size: 1 }); return false }
245
+ catch (e) { return hasStatus(e, 401) }
246
+ })
247
+ await vector('nonce_replay', async () => {
248
+ const c = client({ createNonce: () => `nonce-${suffix}` })
249
+ const query = { target_revision: simulatorTarget, selection_id: simulatorSelection, page_size: 1 }
250
+ await c.deliveries.list(query)
251
+ try { await c.deliveries.list(query); return false } catch (e) { return hasStatus(e, 401) }
252
+ })
253
+ await vector('reconciliation', async () => {
254
+ const page = await instance.deliveries.list({ target_revision: simulatorTarget, selection_id: simulatorSelection, page_size: 1 })
255
+ const eventId = deliveryInboxVectors.duplicate.deliveries[0].headers.find(([name]) => name === 'facto-event-id')?.[1]
256
+ return page.complete && page.items.length === 1 && page.items[0]?.event_id === eventId
257
+ })
258
+ await vector('history_replay', async () =>
259
+ (await instance.deliveryReplays.create({ selection_id: simulatorSelection }, { idempotencyKey: `replay-${suffix}` })).status === 'accepted',
260
+ )
261
+ return good
262
+ }