@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.
- package/CHANGELOG.md +20 -0
- package/LICENSE +202 -0
- package/NOTICE +5 -0
- package/README.md +63 -2
- package/dist/card-inbox-DzsHFRPT.d.cts +312 -0
- package/dist/card-inbox-DzsHFRPT.d.ts +312 -0
- package/dist/chunk-KBS2PWM4.js +2 -0
- package/dist/cli/index.js +6 -0
- package/dist/docs/README.md +9 -0
- package/dist/docs/authentication.md +96 -0
- package/dist/docs/authorization-binding.md +182 -0
- package/dist/docs/authorizations.md +182 -0
- package/dist/docs/concepts.md +36 -0
- package/dist/docs/deliveries.md +170 -0
- package/dist/docs/errors.md +100 -0
- package/dist/docs/getting-access.md +56 -0
- package/dist/docs/idempotency.md +78 -0
- package/dist/docs/integration-checklist.md +15 -0
- package/dist/docs/integration.zh.md +59 -0
- package/dist/docs/interlace-adapter-v1.md +87 -0
- package/dist/docs/interlace-adapter-v1.zh.md +87 -0
- package/dist/docs/not-yet-available.md +13 -0
- package/dist/docs/quickstart.md +126 -0
- package/dist/docs/reconciliation.md +86 -0
- package/dist/docs/reference/api.md +2541 -0
- package/dist/docs/reference/events.md +639 -0
- package/dist/docs/reference/schemas.json +6603 -0
- package/dist/docs/reference/schemas.md +1001 -0
- package/dist/docs/simulator.md +235 -0
- package/dist/docs/versioning.md +9 -0
- package/dist/index.cjs +3 -0
- package/dist/index.d.cts +987 -0
- package/dist/index.d.ts +987 -0
- package/dist/index.js +2 -0
- package/dist/source/build.mjs +5 -0
- package/dist/source/package.json +16 -0
- package/dist/source/src/connect/cli/deliveries.ts +48 -0
- package/dist/source/src/connect/cli/index.ts +57 -0
- package/dist/source/src/connect/server/card-binding-assertion.ts +312 -0
- package/dist/source/src/connect/server/card-client.ts +1018 -0
- package/dist/source/src/connect/server/card-delivery.ts +301 -0
- package/dist/source/src/connect/server/card-events.ts +473 -0
- package/dist/source/src/connect/server/card-idempotency.ts +27 -0
- package/dist/source/src/connect/server/card-inbox.ts +82 -0
- package/dist/source/src/connect/server/card-intent-token.ts +588 -0
- package/dist/source/src/connect/server/card-polling.ts +69 -0
- package/dist/source/src/connect/server/card-signing.ts +115 -0
- package/dist/source/src/connect/server/card-transport.ts +282 -0
- package/dist/source/src/connect/server/errors.ts +280 -0
- package/dist/source/src/connect/server/fixtures/engine/card-events.synthetic.ts +84 -0
- package/dist/source/src/connect/server/retry-after.ts +12 -0
- package/dist/source/src/connect/testing/card-inbox.ts +124 -0
- package/dist/source/src/connect/testing/card-scenarios.ts +243 -0
- package/dist/source/src/connect/testing/card-simulator-vectors.ts +262 -0
- package/dist/source/src/connect/testing/card-simulator.ts +531 -0
- package/dist/source/src/connect/testing/interlace-card-transactions.ts +704 -0
- package/dist/source/src/connect/testing/pure-sha256.ts +123 -0
- package/dist/source/src/connect/wire.d.ts +544 -0
- package/dist/source/src/index.ts +163 -0
- package/dist/source/src/testing-browser.ts +24 -0
- package/dist/source/src/testing.ts +26 -0
- package/dist/source/tsconfig.json +20 -0
- package/dist/testing-browser.d.ts +220 -0
- package/dist/testing-browser.js +5 -0
- package/dist/testing.cjs +6 -0
- package/dist/testing.d.cts +199 -0
- package/dist/testing.d.ts +199 -0
- package/dist/testing.js +5 -0
- 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
|
+
}
|