thevoidforge 21.0.0

package/dist/wizard/lib/patterns/revenue-source-adapter.js

@@ -0,0 +1,182 @@
+/**
+ * Pattern: Revenue Source Adapter (Read-Only)
+ *
+ * Key principles:
+ * - Read-only interface — VoidForge never processes payments directly
+ * - Separate from AdPlatformAdapter — revenue in, ad spend out
+ * - Polling with overlapping windows for gap-free coverage (ADR-5)
+ * - Dedup by externalId to prevent double-counting
+ * - Webhook signature verification mandatory when webhooks are implemented
+ * - USD-only enforcement (ADR-6) at connection time
+ *
+ * Agents: Dockson (treasury), Vin (analytics)
+ *
+ * PRD Reference: §9.4, §9.9, §9.17 (polling improvements), ADR-5/ADR-6
+ */
+// ── Reference Implementation: Stripe ──────────────────
+class StripeAdapter {
+    apiKey = '';
+    baseUrl = 'https://api.stripe.com/v1';
+    async connect(credentials) {
+        this.apiKey = credentials.apiKey || '';
+        try {
+            const account = await this.apiCall('GET', '/account');
+            return {
+                connected: true,
+                accountId: account.id,
+                accountName: account.business_profile?.name || account.email,
+                currency: account.default_currency?.toUpperCase(),
+            };
+        }
+        catch (err) {
+            return { connected: false, error: err.message };
+        }
+    }
+    async detectCurrency(credentials) {
+        const result = await this.connect(credentials);
+        return result.currency || 'USD';
+    }
+    async getTransactions(range, cursor) {
+        // Use Stripe Events API for sequential, immutable event log (§9.18)
+        const params = {
+            type: 'charge.succeeded',
+            'created[gte]': String(Math.floor(new Date(range.start).getTime() / 1000)),
+            'created[lte]': String(Math.floor(new Date(range.end).getTime() / 1000)),
+            limit: '100',
+        };
+        if (cursor)
+            params.starting_after = cursor;
+        const data = await this.apiCall('GET', '/events', params);
+        const transactions = data.data.map((event) => {
+            const charge = event.data?.object;
+            return {
+                externalId: event.id,
+                type: 'charge',
+                amount: (charge?.amount || 0), // Stripe amounts are already in cents
+                currency: 'USD',
+                description: charge?.description || '',
+                customerId: charge?.customer ? hashCustomerId(charge.customer) : undefined,
+                subscriptionId: charge?.subscription,
+                metadata: charge?.metadata || {},
+                createdAt: new Date(event.created * 1000).toISOString(),
+            };
+        });
+        return {
+            transactions,
+            hasMore: data.has_more,
+            cursor: data.data.length > 0 ? data.data[data.data.length - 1].id : undefined,
+        };
+    }
+    async getBalance() {
+        const data = await this.apiCall('GET', '/balance');
+        const usd = data.available.find((b) => b.currency === 'usd');
+        const pending = data.pending.find((b) => b.currency === 'usd');
+        return {
+            available: (usd?.amount || 0),
+            pending: (pending?.amount || 0),
+            currency: 'USD',
+        };
+    }
+    verifyWebhookSignature(payload, signature, secret) {
+        // Stripe uses HMAC-SHA256 for webhook signatures
+        const { createHmac } = require('node:crypto');
+        const parts = signature.split(',').reduce((acc, part) => {
+            const [key, value] = part.split('=');
+            acc[key] = value;
+            return acc;
+        }, {});
+        const timestamp = parts['t'];
+        const expected = parts['v1'];
+        if (!timestamp || !expected)
+            return false;
+        const signed = createHmac('sha256', secret)
+            .update(`${timestamp}.${payload.toString()}`)
+            .digest('hex');
+        // VG-006: Use timing-safe comparison to prevent timing attacks on signature
+        const { timingSafeEqual } = require('node:crypto');
+        if (signed.length !== expected.length)
+            return false;
+        return timingSafeEqual(Buffer.from(signed), Buffer.from(expected));
+    }
+    async apiCall(method, path, params) {
+        // Implementation: raw HTTPS (no Stripe SDK — zero dependency principle)
+        // Headers: Authorization: Bearer {apiKey}, Content-Type: application/x-www-form-urlencoded
+        // Sanitize response strings per §9.19.16 before returning
+        throw new Error('HTTP implementation — use node:https, no SDK dependencies');
+    }
+}
+// ── Paddle Adapter ────────────────────────────────────
+class PaddleAdapter {
+    apiKey = '';
+    baseUrl = 'https://api.paddle.com';
+    async connect(credentials) {
+        this.apiKey = credentials.apiKey || '';
+        try {
+            const data = await this.apiCall('GET', '/businesses');
+            const biz = data.data?.[0];
+            return {
+                connected: true,
+                accountId: biz?.id,
+                accountName: biz?.name,
+                currency: biz?.currency_code,
+            };
+        }
+        catch (err) {
+            return { connected: false, error: err.message };
+        }
+    }
+    async detectCurrency(credentials) {
+        const result = await this.connect(credentials);
+        return result.currency || 'USD';
+    }
+    async getTransactions(range, cursor) {
+        const params = {
+            'created_at[gte]': range.start,
+            'created_at[lte]': range.end,
+            per_page: '100',
+        };
+        if (cursor)
+            params.after = cursor;
+        const data = await this.apiCall('GET', '/transactions', params);
+        const transactions = data.data.map((txn) => {
+            const details = txn.details;
+            const totals = details?.totals;
+            const items = txn.items;
+            const firstItemPrice = items?.[0]?.price;
+            return {
+                externalId: txn.id,
+                type: mapPaddleStatus(txn.status),
+                amount: Math.round(parseFloat(totals?.total || '0') * 100),
+                currency: 'USD',
+                description: firstItemPrice?.description || '',
+                customerId: txn.customer_id ? hashCustomerId(txn.customer_id) : undefined,
+                subscriptionId: txn.subscription_id,
+                metadata: txn.custom_data || {},
+                createdAt: txn.created_at,
+            };
+        });
+        return {
+            transactions,
+            hasMore: !!data.meta?.pagination?.next,
+            cursor: data.meta?.pagination?.next,
+        };
+    }
+    async apiCall(method, path, params) {
+        throw new Error('HTTP implementation — use node:https, no SDK dependencies');
+    }
+}
+// ── Helpers ───────────────────────────────────────────
+function hashCustomerId(customerId) {
+    const { createHash } = require('node:crypto');
+    return createHash('sha256').update(customerId).digest('hex').substring(0, 16);
+}
+function mapPaddleStatus(status) {
+    if (status === 'completed' || status === 'paid')
+        return 'charge';
+    if (status === 'refunded' || status === 'partially_refunded')
+        return 'refund';
+    if (status === 'disputed')
+        return 'dispute';
+    return 'charge';
+}
+export { StripeAdapter, PaddleAdapter, hashCustomerId };

package/dist/wizard/lib/patterns/stablecoin-adapter.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Pattern: Stablecoin Treasury Adapter (Split Interface)
+ *
+ * Key principles:
+ * - Split interface: StablecoinSetup (interactive CLI/Danger Room) + StablecoinAdapter (daemon runtime)
+ * - Single-writer constraint: only Heartbeat daemon calls the runtime adapter
+ * - Funding lifecycle: USDC held at provider → off-ramp instruction → fiat settlement at linked bank
+ * - All amounts in branded integer cents (Cents type from financial-transaction.ts)
+ * - Hash-chained TransferRecord for tamper-evident audit trail
+ * - Idempotency keys on all write operations (off-ramp, cancel)
+ * - Provider abstraction: Circle first-class, Bridge secondary, manual fallback
+ * - The adapter does NOT move money between bank and ad platform — that is ad-billing-adapter.ts
+ *
+ * Agents: Dockson (treasury), Heartbeat daemon
+ *
+ * PRD Reference: §11.1A, §12.1, §12.4, §12.5
+ *
+ * Circle API reference (v1):
+ *   Auth: Bearer token via API key — header `Authorization: Bearer {apiKey}`
+ *   Base URL: https://api.circle.com/v1
+ *   GET  /wallets                       → list wallets
+ *   GET  /wallets/{id}/balances         → wallet balances (amount, currency, chain)
+ *   GET  /configuration                 → supported chains and assets
+ *   GET  /banks/wires                   → linked bank accounts
+ *   POST /payouts                       → initiate wire payout (off-ramp)
+ *   GET  /payouts/{id}                  → transfer status
+ *   GET  /payouts?destination={bankId}  → list completed payouts for reconciliation
+ *
+ *   Response shape (balance):
+ *     { data: { available: [{ amount: "1000.00", currency: "USD" }] } }
+ *   Response shape (payout):
+ *     { data: { id, status, amount: { amount, currency }, destination, createDate, updateDate } }
+ *   Payout statuses: pending → processing → complete | failed
+ *
+ * Bridge API reference:
+ *   Auth: API key header `Api-Key: {apiKey}`
+ *   Base URL: https://api.bridge.xyz/v0
+ *   POST /customers/{id}/liquidation_addresses → create liquidation address
+ *   GET  /customers/{id}/liquidation_addresses → list addresses
+ *   GET  /liquidation_addresses/{id}           → transfer status
+ *   Transfers settle via ACH to linked bank — status polling required
+ */
+type Cents = number & {
+    readonly __brand: 'Cents';
+};
+declare function toCents(dollars: number): Cents;
+declare function toDollars(cents: Cents): number;
+type StablecoinProvider = 'circle' | 'bridge';
+interface SupportedAsset {
+    asset: string;
+    network: string;
+    contractAddress: string;
+    minRedemption: Cents;
+}
+interface ProviderCredentials {
+    provider: StablecoinProvider;
+    apiKey: string;
+    environment: 'sandbox' | 'production';
+}
+interface StablecoinBalance {
+    provider: StablecoinProvider;
+    asset: string;
+    network: string;
+    balanceCents: Cents;
+    lastUpdated: string;
+}
+interface FiatBalance {
+    provider: 'mercury' | 'external';
+    accountId: string;
+    availableCents: Cents;
+    pendingCents: Cents;
+    currency: 'USD';
+    lastUpdated: string;
+}
+interface CombinedBalances {
+    stablecoin: StablecoinBalance[];
+    fiat: FiatBalance[];
+    totalStablecoinCents: Cents;
+    totalFiatAvailableCents: Cents;
+}
+interface OfframpQuote {
+    provider: StablecoinProvider;
+    sourceAsset: string;
+    sourceNetwork: string;
+    requestedCents: Cents;
+    estimatedFeeCents: Cents;
+    estimatedNetCents: Cents;
+    estimatedSettlementMinutes: number;
+    expiresAt: string;
+    quoteId?: string;
+}
+type TransferStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled';
+interface TransferRecord {
+    id: string;
+    fundingPlanId: string;
+    providerTransferId: string;
+    bankTransactionId?: string;
+    provider: StablecoinProvider;
+    direction: 'crypto_to_fiat';
+    sourceAsset: string;
+    sourceNetwork: string;
+    amountCents: Cents;
+    feesCents: Cents;
+    netAmountCents: Cents;
+    destinationBankId: string;
+    status: TransferStatus;
+    statusReason?: string;
+    initiatedAt: string;
+    completedAt?: string;
+    idempotencyKey: string;
+    previousHash: string;
+    hash: string;
+}
+interface TransferStatusDetail {
+    transferId: string;
+    providerTransferId: string;
+    status: TransferStatus;
+    amountCents: Cents;
+    feesCents: Cents;
+    initiatedAt: string;
+    completedAt?: string;
+    estimatedCompletionAt?: string;
+    providerRawStatus: string;
+}
+interface DateRange {
+    start: string;
+    end: string;
+}
+interface StablecoinSetup {
+    /** Verify provider API key is valid and has required permissions */
+    authenticate(credentials: ProviderCredentials): Promise<{
+        valid: boolean;
+        accountId?: string;
+        permissions?: string[];
+        error?: string;
+    }>;
+    /** List stablecoins and networks the provider supports for off-ramp */
+    verifySupportedAssets(credentials: ProviderCredentials): Promise<SupportedAsset[]>;
+    /** Confirm the provider has a linked bank destination for wire/ACH payouts */
+    verifyLinkedBank(credentials: ProviderCredentials): Promise<{
+        linked: boolean;
+        bankId?: string;
+        bankName?: string;
+        accountLast4?: string;
+        error?: string;
+    }>;
+    /** Fetch current stablecoin balances for initial state snapshot */
+    getInitialBalances(credentials: ProviderCredentials): Promise<StablecoinBalance[]>;
+}
+interface StablecoinAdapter {
+    /** Current stablecoin + fiat balances across all connected accounts */
+    getBalances(): Promise<CombinedBalances>;
+    /** Estimate fees, settlement time, and net proceeds for an off-ramp */
+    quoteRedemption(amountCents: Cents): Promise<OfframpQuote>;
+    /**
+     * Create an off-ramp instruction with the provider.
+     * Requires an idempotencyKey on the FundingPlan to prevent duplicate transfers.
+     * Returns the created TransferRecord (with hash chain linking).
+     */
+    initiateOfframp(plan: FundingPlanRef, previousHash: string): Promise<TransferRecord>;
+    /** Poll provider for transfer status updates */
+    getTransferStatus(transferId: string): Promise<TransferStatusDetail>;
+    /** Cancel a pending transfer if the provider supports cancellation */
+    cancelTransfer(transferId: string): Promise<{
+        cancelled: boolean;
+        reason?: string;
+    }>;
+    /** List completed transfers in a date range for reconciliation */
+    listCompletedTransfers(dateRange: DateRange): Promise<TransferRecord[]>;
+}
+interface FundingPlanRef {
+    id: string;
+    sourceFundingId: string;
+    destinationBankId: string;
+    requiredCents: Cents;
+    idempotencyKey: string;
+}
+declare function computeTransferHash(record: Omit<TransferRecord, 'hash'>, previousHash: string): string;
+declare class CircleAdapter implements StablecoinSetup, StablecoinAdapter {
+    private config;
+    private readonly baseUrl;
+    private apiKey;
+    private bankId;
+    constructor(config: {
+        apiKey: string;
+        bankId: string;
+        environment: 'sandbox' | 'production';
+    });
+    authenticate(credentials: ProviderCredentials): Promise<{
+        valid: boolean;
+        accountId?: string;
+        permissions?: string[];
+        error?: string;
+    }>;
+    verifySupportedAssets(_credentials: ProviderCredentials): Promise<SupportedAsset[]>;
+    verifyLinkedBank(_credentials: ProviderCredentials): Promise<{
+        linked: boolean;
+        bankId?: string;
+        bankName?: string;
+        accountLast4?: string;
+        error?: string;
+    }>;
+    getInitialBalances(_credentials: ProviderCredentials): Promise<StablecoinBalance[]>;
+    getBalances(): Promise<CombinedBalances>;
+    quoteRedemption(amountCents: Cents): Promise<OfframpQuote>;
+    initiateOfframp(plan: FundingPlanRef, previousHash: string): Promise<TransferRecord>;
+    getTransferStatus(transferId: string): Promise<TransferStatusDetail>;
+    cancelTransfer(transferId: string): Promise<{
+        cancelled: boolean;
+        reason?: string;
+    }>;
+    listCompletedTransfers(dateRange: DateRange): Promise<TransferRecord[]>;
+    private fetchStablecoinBalances;
+    private apiCall;
+}
+declare function mapCircleStatus(circleStatus: string): TransferStatus;
+export type { StablecoinSetup, StablecoinAdapter, StablecoinProvider, SupportedAsset, ProviderCredentials, StablecoinBalance, FiatBalance, CombinedBalances, OfframpQuote, TransferStatus, TransferRecord, TransferStatusDetail, FundingPlanRef, DateRange, };
+export { toCents, toDollars, computeTransferHash, mapCircleStatus, CircleAdapter };

package/dist/wizard/lib/patterns/stablecoin-adapter.js

@@ -0,0 +1,264 @@
+/**
+ * Pattern: Stablecoin Treasury Adapter (Split Interface)
+ *
+ * Key principles:
+ * - Split interface: StablecoinSetup (interactive CLI/Danger Room) + StablecoinAdapter (daemon runtime)
+ * - Single-writer constraint: only Heartbeat daemon calls the runtime adapter
+ * - Funding lifecycle: USDC held at provider → off-ramp instruction → fiat settlement at linked bank
+ * - All amounts in branded integer cents (Cents type from financial-transaction.ts)
+ * - Hash-chained TransferRecord for tamper-evident audit trail
+ * - Idempotency keys on all write operations (off-ramp, cancel)
+ * - Provider abstraction: Circle first-class, Bridge secondary, manual fallback
+ * - The adapter does NOT move money between bank and ad platform — that is ad-billing-adapter.ts
+ *
+ * Agents: Dockson (treasury), Heartbeat daemon
+ *
+ * PRD Reference: §11.1A, §12.1, §12.4, §12.5
+ *
+ * Circle API reference (v1):
+ *   Auth: Bearer token via API key — header `Authorization: Bearer {apiKey}`
+ *   Base URL: https://api.circle.com/v1
+ *   GET  /wallets                       → list wallets
+ *   GET  /wallets/{id}/balances         → wallet balances (amount, currency, chain)
+ *   GET  /configuration                 → supported chains and assets
+ *   GET  /banks/wires                   → linked bank accounts
+ *   POST /payouts                       → initiate wire payout (off-ramp)
+ *   GET  /payouts/{id}                  → transfer status
+ *   GET  /payouts?destination={bankId}  → list completed payouts for reconciliation
+ *
+ *   Response shape (balance):
+ *     { data: { available: [{ amount: "1000.00", currency: "USD" }] } }
+ *   Response shape (payout):
+ *     { data: { id, status, amount: { amount, currency }, destination, createDate, updateDate } }
+ *   Payout statuses: pending → processing → complete | failed
+ *
+ * Bridge API reference:
+ *   Auth: API key header `Api-Key: {apiKey}`
+ *   Base URL: https://api.bridge.xyz/v0
+ *   POST /customers/{id}/liquidation_addresses → create liquidation address
+ *   GET  /customers/{id}/liquidation_addresses → list addresses
+ *   GET  /liquidation_addresses/{id}           → transfer status
+ *   Transfers settle via ACH to linked bank — status polling required
+ */
+import { createHash } from 'node:crypto';
+function toCents(dollars) {
+    return Math.round(dollars * 100);
+}
+function toDollars(cents) {
+    return cents / 100;
+}
+// ── Hash Chain Helper ───────────────────────────────
+function computeTransferHash(record, previousHash) {
+    const payload = JSON.stringify({
+        id: record.id,
+        fundingPlanId: record.fundingPlanId,
+        providerTransferId: record.providerTransferId,
+        amountCents: record.amountCents,
+        feesCents: record.feesCents,
+        status: record.status,
+        initiatedAt: record.initiatedAt,
+    }) + previousHash;
+    return createHash('sha256').update(payload).digest('hex');
+}
+// ── Reference Implementation Sketch: Circle ─────────
+// Production implementation would live in wizard/lib/financial/stablecoin/circle.ts
+class CircleAdapter {
+    config;
+    baseUrl = 'https://api.circle.com/v1';
+    apiKey = '';
+    bankId = '';
+    constructor(config) {
+        this.config = config;
+        this.apiKey = config.apiKey;
+        this.bankId = config.bankId;
+        if (config.environment === 'sandbox') {
+            // Circle sandbox base URL is the same but uses sandbox API keys
+        }
+    }
+    // ── Setup (interactive) ──────────
+    async authenticate(credentials) {
+        // GET /configuration — verifies API key works
+        // Circle returns { data: { payments: { masterWalletId } } }
+        const res = await this.apiCall('GET', '/configuration');
+        const data = res.data;
+        const payments = data?.payments;
+        return {
+            valid: true,
+            accountId: payments?.masterWalletId,
+        };
+    }
+    async verifySupportedAssets(_credentials) {
+        // Circle supports USDC on ETH, SOL, MATIC, AVAX, etc.
+        // GET /configuration → data.payments.supportedCurrencies
+        // Hardcoded for pattern — real implementation queries the API
+        return [
+            { asset: 'USDC', network: 'ETH', contractAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', minRedemption: toCents(100) },
+            { asset: 'USDC', network: 'SOL', contractAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', minRedemption: toCents(100) },
+            { asset: 'USDC', network: 'MATIC', contractAddress: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359', minRedemption: toCents(100) },
+        ];
+    }
+    async verifyLinkedBank(_credentials) {
+        // GET /banks/wires — lists linked wire destinations
+        // Response: { data: [{ id, description, trackingRef, bankAddress, billingDetails, status }] }
+        const res = await this.apiCall('GET', '/banks/wires');
+        const banks = res.data;
+        if (!banks || banks.length === 0) {
+            return { linked: false, error: 'No linked bank accounts found in Circle' };
+        }
+        const primary = banks[0];
+        return {
+            linked: true,
+            bankId: primary.id,
+            bankName: primary.billingDetails?.name,
+            accountLast4: primary.trackingRef
+                ? primary.trackingRef.slice(-4)
+                : undefined,
+        };
+    }
+    async getInitialBalances(_credentials) {
+        return this.fetchStablecoinBalances();
+    }
+    // ── Runtime (daemon) ──────────
+    async getBalances() {
+        const stablecoin = await this.fetchStablecoinBalances();
+        const totalStablecoinCents = stablecoin.reduce((sum, b) => (sum + b.balanceCents), 0);
+        // Fiat balances come from the bank adapter, not the stablecoin provider.
+        // The caller (Treasury Planner) combines stablecoin + bank balances.
+        return {
+            stablecoin,
+            fiat: [],
+            totalStablecoinCents,
+            totalFiatAvailableCents: 0,
+        };
+    }
+    async quoteRedemption(amountCents) {
+        // Circle payout fees vary by destination and amount.
+        // For wire payouts: typically $25 flat fee.
+        // Settlement: 1-2 business days for domestic wire.
+        const feeCents = toCents(25);
+        return {
+            provider: 'circle',
+            sourceAsset: 'USDC',
+            sourceNetwork: 'ETH',
+            requestedCents: amountCents,
+            estimatedFeeCents: feeCents,
+            estimatedNetCents: (amountCents - feeCents),
+            estimatedSettlementMinutes: 24 * 60, // 1 business day estimate
+            expiresAt: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
+        };
+    }
+    async initiateOfframp(plan, previousHash) {
+        // POST /payouts
+        // Body: { idempotencyKey, source: { type: "wallet", id: "master" },
+        //         destination: { type: "wire", id: bankId },
+        //         amount: { amount: "1000.00", currency: "USD" },
+        //         metadata: { beneficiaryEmail: "..." } }
+        const res = await this.apiCall('POST', '/payouts', {
+            idempotencyKey: plan.idempotencyKey,
+            source: { type: 'wallet', id: 'master' },
+            destination: { type: 'wire', id: this.bankId },
+            amount: { amount: toDollars(plan.requiredCents).toFixed(2), currency: 'USD' },
+        });
+        const payout = res.data;
+        const now = new Date().toISOString();
+        const id = crypto.randomUUID();
+        const record = {
+            id,
+            fundingPlanId: plan.id,
+            providerTransferId: payout.id,
+            provider: 'circle',
+            direction: 'crypto_to_fiat',
+            sourceAsset: 'USDC',
+            sourceNetwork: 'ETH',
+            amountCents: plan.requiredCents,
+            feesCents: toCents(25),
+            netAmountCents: (plan.requiredCents - toCents(25)),
+            destinationBankId: plan.destinationBankId,
+            status: 'pending',
+            initiatedAt: now,
+            idempotencyKey: plan.idempotencyKey,
+            previousHash,
+        };
+        const hash = computeTransferHash(record, previousHash);
+        return { ...record, hash };
+    }
+    async getTransferStatus(transferId) {
+        // GET /payouts/{id}
+        // Response: { data: { id, status, amount, fees, createDate, updateDate } }
+        // Circle statuses: pending → processing → complete | failed
+        const res = await this.apiCall('GET', `/payouts/${transferId}`);
+        const payout = res.data;
+        const amount = payout.amount;
+        const fees = payout.fees;
+        return {
+            transferId,
+            providerTransferId: payout.id,
+            status: mapCircleStatus(payout.status),
+            amountCents: toCents(parseFloat(amount.amount)),
+            feesCents: fees ? toCents(parseFloat(fees.amount)) : 0,
+            initiatedAt: payout.createDate,
+            completedAt: payout.status === 'complete' ? payout.updateDate : undefined,
+            providerRawStatus: payout.status,
+        };
+    }
+    async cancelTransfer(transferId) {
+        // Circle does not support cancellation of payouts once processing begins.
+        // Only pending payouts may be cancellable via support — no direct API.
+        return {
+            cancelled: false,
+            reason: 'Circle does not support programmatic payout cancellation. Contact support for pending payouts.',
+        };
+    }
+    async listCompletedTransfers(dateRange) {
+        // GET /payouts?destination={bankId}&status=complete
+        //   &pageBefore=...&pageAfter=...
+        // Filter by createDate within dateRange on the client side.
+        // Returns array of TransferRecords for reconciliation.
+        // In production: paginate and filter by date.
+        throw new Error('HTTP implementation — use node:https, no SDK dependencies');
+    }
+    // ── Private helpers ──────────
+    async fetchStablecoinBalances() {
+        // GET /wallets/master/balances (or /wallets → pick master → /ballets/{id}/balances)
+        // Response: { data: { available: [{ amount: "1500.50", currency: "USD" }] } }
+        const res = await this.apiCall('GET', '/wallets');
+        const wallets = res.data;
+        const now = new Date().toISOString();
+        const balances = [];
+        for (const wallet of wallets) {
+            const available = wallet.balances ?? [];
+            for (const bal of available) {
+                if (bal.currency === 'USD') {
+                    balances.push({
+                        provider: 'circle',
+                        asset: 'USDC',
+                        network: 'ETH', // Circle aggregates across chains for USD balance
+                        balanceCents: toCents(parseFloat(bal.amount)),
+                        lastUpdated: now,
+                    });
+                }
+            }
+        }
+        return balances;
+    }
+    async apiCall(method, path, body) {
+        // Implementation: raw HTTPS (no SDK — zero dependency principle)
+        // Headers:
+        //   Authorization: Bearer {this.apiKey}
+        //   Content-Type: application/json
+        //   Accept: application/json
+        // Sanitize response strings per §9.19.16 before returning
+        throw new Error('HTTP implementation — use node:https, no SDK dependencies');
+    }
+}
+// ── Status Mapping ──────────────────────────────────
+function mapCircleStatus(circleStatus) {
+    switch (circleStatus) {
+        case 'pending': return 'pending';
+        case 'processing': return 'processing';
+        case 'complete': return 'completed';
+        case 'failed': return 'failed';
+        default: return 'pending';
+    }
+}
+export { toCents, toDollars, computeTransferHash, mapCircleStatus, CircleAdapter };