@tokeflow_com/connector-sdk

The versioned contract for Tokeflow payment connectors. A connector is a stateless translator for one PSP: it builds requests, interprets responses/errors/webhooks, converts currency units, and verifies webhook signatures. Everything else — persistence, queues, events, state machines, refund reconciliation, credential storage, vault dispatch, retries and cascade — lives in the Tokeflow orchestrator and is deliberately out of reach.

The contract is PaymentConnector (see src/connector.ts); every type it references ships from this package, alongside zod runtime schemas (xSchema for each data type X) used by the conformance suite.

Install

npm install @tokeflow_com/connector-sdk

Then bind the conformance suite — it is the definition of done for any connector built against this contract:

import { describeConformance } from '@tokeflow_com/connector-sdk/testing';

describeConformance('my-psp', () => makeSubject());

Invariants

These are the contract's spine. A connector that violates any of them fails certification regardless of how well it otherwise works.

1. Minor units everywhere at the boundary. Every amount crossing the PaymentConnector boundary is an integer in minor units (cents/centavos), in both directions. Conversion to/from the PSP's wire unit happens INSIDE the connector, driven by capabilities.providerAmountUnit, using the helpers shipped in this package (toProviderAmount / fromProviderAmount). Never reimplement the conversion.

2. Unknown discipline. Every mutating operation's outcome union has an unknown arm. Post-send ambiguity on a write — timeout, connection reset, 5xx after dispatch — MUST surface as status: 'unknown' (with RAIL_TIMEOUT where applicable), never 'failed', and never a throw. This is the double-charge guard. getTransactionStatus returns { status: 'unknown' } when the lookup itself fails; it never throws.

3. Host-supplied idempotency; deterministic event IDs. idempotencyKey is always provided by the orchestrator — connectors forward it to the PSP on every mutating call and never generate their own. Webhook providerEventId must be deterministic for a given delivery (no Date.now()/random fallbacks) — deduplication depends on it.

4. Statelessness. No DB, no queues, no environment variables, no global mutable state, no direct observability SDKs — use ctx.logger. Rotated credentials persist only via ctx.persistCredentials. Honor ctx.signal on every outbound call. Never log or persist card ciphertexts or webhook secrets.

Layout

| Module | Contents | |---|---| | money | MinorUnits, unit-conversion helpers, currency decimal tables | | errors | 12-code ConnectorErrorCode taxonomy, ConnectorError | | context | ConnectorContext, ConnectorLogger | | capabilities | ConnectorCapabilities | | outcomes | PaymentOutcome, CaptureOutcome, VoidOutcome, RefundOutcome, StatusLookup | | webhook | ConnectorWebhookEvent (14 kinds), WebhookVerification | | vault | VaultProxyRequest, VaultCardCiphertext | | inputs | ChargeInput, MitChargeInput, PayerDetails, customer/payment-method inputs | | connector | PaymentConnector — the contract |