voidforge-build 23.9.1

package/dist/wizard/lib/financial/stablecoin/circle.js

@@ -0,0 +1,367 @@
+/**
+ * Circle Stablecoin Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements StablecoinSetup (interactive CLI) + StablecoinAdapter (daemon runtime)
+ * for Circle's Business Account API v1.
+ *
+ * Circle API v1:
+ *   Base URL: https://api.circle.com/v1
+ *   Auth: Authorization: Bearer {apiKey}
+ *
+ * PRD Reference: §11.1A, §12.1, §12.4, §12.5
+ * No Stubs Doctrine: every method makes a real API call (except quoteRedemption — local computation).
+ */
+import { randomUUID } from 'node:crypto';
+import { request as httpsRequest } from 'node:https';
+import { toCents, toDollars, computeTransferHash } from './base.js';
+const CIRCLE_HOST = 'api.circle.com';
+// ── HTTP helpers ─────────────────────────────────────
+async function circleGet(path, apiKey, params) {
+    const query = params ? '?' + new URLSearchParams(params).toString() : '';
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            hostname: CIRCLE_HOST,
+            path: `/v1${path}${query}`,
+            method: 'GET',
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+                'Accept': 'application/json',
+            },
+            timeout: 15000,
+        }, (res) => {
+            let data = '';
+            res.on('data', (chunk) => { data += chunk.toString(); });
+            res.on('end', () => resolve({ status: res.statusCode ?? 500, body: data }));
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('Circle API timeout')); });
+        req.end();
+    });
+}
+async function circlePost(path, apiKey, body) {
+    const payload = JSON.stringify(body);
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            hostname: CIRCLE_HOST,
+            path: `/v1${path}`,
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+                'Accept': 'application/json',
+            },
+            timeout: 15000,
+        }, (res) => {
+            let data = '';
+            res.on('data', (chunk) => { data += chunk.toString(); });
+            res.on('end', () => resolve({ status: res.statusCode ?? 500, body: data }));
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('Circle API timeout')); });
+        req.write(payload);
+        req.end();
+    });
+}
+/** Parse JSON response body; on failure return a descriptive error object. */
+function safeParseJson(body) {
+    // VG-R1-005: Wrap error-path JSON.parse in try/catch
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return { error: { message: 'Non-JSON response from Circle API' } };
+    }
+}
+/** Map Circle payout status strings to our TransferStatus union. */
+function mapCircleStatus(circleStatus) {
+    switch (circleStatus) {
+        case 'pending': return 'pending';
+        case 'processing': return 'processing';
+        case 'complete': return 'completed';
+        case 'failed': return 'failed';
+        default: return 'pending';
+    }
+}
+// ── Setup Implementation ─────────────────────────────
+export class CircleSetup {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    async authenticate(_credentials) {
+        try {
+            const { status, body } = await circleGet('/configuration', this.apiKey);
+            if (status === 200) {
+                const data = safeParseJson(body);
+                const payments = data.data?.payments;
+                return {
+                    valid: true,
+                    accountId: payments?.masterWalletId,
+                    permissions: ['read_balances', 'initiate_payouts', 'read_payouts'],
+                };
+            }
+            const parsed = safeParseJson(body);
+            const err = parsed.error;
+            return { valid: false, error: err?.message ?? `HTTP ${status}` };
+        }
+        catch (err) {
+            return { valid: false, error: err instanceof Error ? err.message : 'Connection failed' };
+        }
+    }
+    async verifySupportedAssets(_credentials) {
+        // Circle supports USDC on multiple networks. The /configuration endpoint
+        // confirms available chains but does not list contract addresses per-chain.
+        // We return the known production USDC contract addresses for supported networks.
+        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) },
+            { asset: 'USDC', network: 'AVAX', contractAddress: '0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e', minRedemption: toCents(100) },
+        ];
+    }
+    async verifyLinkedBank(_credentials) {
+        try {
+            const { status, body } = await circleGet('/businessAccount/banks/wires', this.apiKey);
+            if (status !== 200) {
+                const parsed = safeParseJson(body);
+                const err = parsed.error;
+                return { linked: false, error: err?.message ?? `HTTP ${status}` };
+            }
+            const parsed = safeParseJson(body);
+            const banks = parsed.data;
+            if (!banks || banks.length === 0) {
+                return { linked: false, error: 'No linked wire bank accounts found in Circle' };
+            }
+            const primary = banks[0];
+            const billingDetails = primary.billingDetails;
+            return {
+                linked: true,
+                bankId: primary.id,
+                bankName: billingDetails?.name,
+                accountLast4: primary.trackingRef
+                    ? primary.trackingRef.slice(-4)
+                    : undefined,
+            };
+        }
+        catch (err) {
+            return { linked: false, error: err instanceof Error ? err.message : 'Connection failed' };
+        }
+    }
+    async getInitialBalances(_credentials) {
+        try {
+            const { status, body } = await circleGet('/businessAccount/balances', this.apiKey);
+            if (status !== 200)
+                return [];
+            const parsed = safeParseJson(body);
+            const data = parsed.data;
+            const available = data?.available;
+            if (!available)
+                return [];
+            const now = new Date().toISOString();
+            return available
+                .filter(b => b.currency === 'USD')
+                .map(b => ({
+                provider: 'circle',
+                asset: 'USDC',
+                network: 'ETH',
+                balanceCents: toCents(parseFloat(b.amount)),
+                lastUpdated: now,
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+}
+// ── Runtime Adapter Implementation ───────────────────
+export class CircleAdapter {
+    apiKey;
+    bankId;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.bankId = config.bankId;
+    }
+    async getBalances() {
+        const { status, body } = await circleGet('/businessAccount/balances', this.apiKey);
+        if (status !== 200) {
+            // VG-R1-005: safe parse
+            let errorMsg = `HTTP ${status}`;
+            try {
+                const e = JSON.parse(body);
+                errorMsg = e.error?.message ?? errorMsg;
+            }
+            catch { /* non-JSON */ }
+            throw new Error(`Circle getBalances failed: ${errorMsg}`);
+        }
+        const parsed = safeParseJson(body);
+        const data = parsed.data;
+        const available = data?.available ?? [];
+        const now = new Date().toISOString();
+        const stablecoin = available
+            .filter(b => b.currency === 'USD')
+            .map(b => ({
+            provider: 'circle',
+            asset: 'USDC',
+            network: 'ETH',
+            balanceCents: toCents(parseFloat(b.amount)),
+            lastUpdated: now,
+        }));
+        const totalStablecoinCents = stablecoin.reduce((sum, b) => (sum + b.balanceCents), 0);
+        return {
+            stablecoin,
+            fiat: [],
+            totalStablecoinCents,
+            totalFiatAvailableCents: 0,
+        };
+    }
+    async quoteRedemption(amountCents) {
+        // Circle wire payout fee: typically $25 flat for domestic wire.
+        // No API endpoint for quotes — computed locally based on known fee structure.
+        const feeCents = toCents(25);
+        return {
+            provider: 'circle',
+            sourceAsset: 'USDC',
+            sourceNetwork: 'ETH',
+            requestedCents: amountCents,
+            estimatedFeeCents: feeCents,
+            estimatedNetCents: (amountCents - feeCents),
+            estimatedSettlementMinutes: 24 * 60, // 1 business day
+            expiresAt: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
+        };
+    }
+    async initiateOfframp(plan, previousHash) {
+        const { status, body } = await circlePost('/businessAccount/payouts', this.apiKey, {
+            idempotencyKey: plan.idempotencyKey,
+            source: { type: 'wallet', id: 'master' },
+            destination: { type: 'wire', id: this.bankId },
+            amount: { amount: toDollars(plan.requiredCents).toFixed(2), currency: 'USD' },
+        });
+        if (status !== 200 && status !== 201) {
+            // VG-R1-005: safe parse
+            let errorMsg = `HTTP ${status}`;
+            try {
+                const e = JSON.parse(body);
+                errorMsg = e.error?.message ?? errorMsg;
+            }
+            catch { /* non-JSON */ }
+            throw new Error(`Circle initiateOfframp failed: ${errorMsg}`);
+        }
+        const parsed = safeParseJson(body);
+        const payout = parsed.data;
+        const now = new Date().toISOString();
+        const id = randomUUID();
+        const feeCents = toCents(25);
+        const record = {
+            id,
+            fundingPlanId: plan.id,
+            providerTransferId: payout.id,
+            provider: 'circle',
+            direction: 'crypto_to_fiat',
+            sourceAsset: 'USDC',
+            sourceNetwork: 'ETH',
+            amountCents: plan.requiredCents,
+            feesCents: feeCents,
+            netAmountCents: (plan.requiredCents - feeCents),
+            destinationBankId: plan.destinationBankId,
+            status: 'pending',
+            initiatedAt: now,
+            idempotencyKey: plan.idempotencyKey,
+            previousHash,
+        };
+        const hash = computeTransferHash(record, previousHash);
+        return { ...record, hash };
+    }
+    async getTransferStatus(transferId) {
+        const { status, body } = await circleGet(`/businessAccount/payouts/${transferId}`, this.apiKey);
+        if (status !== 200) {
+            let errorMsg = `HTTP ${status}`;
+            try {
+                const e = JSON.parse(body);
+                errorMsg = e.error?.message ?? errorMsg;
+            }
+            catch { /* non-JSON */ }
+            throw new Error(`Circle getTransferStatus failed: ${errorMsg}`);
+        }
+        const parsed = safeParseJson(body);
+        const payout = parsed.data;
+        const amount = payout.amount;
+        const fees = payout.fees;
+        const mappedStatus = mapCircleStatus(payout.status);
+        return {
+            transferId,
+            providerTransferId: payout.id,
+            status: mappedStatus,
+            amountCents: toCents(parseFloat(amount.amount)),
+            feesCents: fees ? toCents(parseFloat(fees.amount)) : 0,
+            initiatedAt: payout.createDate,
+            completedAt: mappedStatus === 'completed' ? payout.updateDate : undefined,
+            estimatedCompletionAt: mappedStatus !== 'completed'
+                ? new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString()
+                : undefined,
+            providerRawStatus: payout.status,
+        };
+    }
+    async cancelTransfer(_transferId) {
+        // Circle does not support programmatic payout cancellation via API.
+        // Wire payouts cannot be cancelled once submitted.
+        return {
+            cancelled: false,
+            reason: 'Circle does not support programmatic payout cancellation. Contact support for pending payouts.',
+        };
+    }
+    async listCompletedTransfers(dateRange) {
+        const params = {
+            destination: this.bankId,
+            status: 'complete',
+        };
+        const { status, body } = await circleGet('/businessAccount/payouts', this.apiKey, params);
+        if (status !== 200) {
+            let errorMsg = `HTTP ${status}`;
+            try {
+                const e = JSON.parse(body);
+                errorMsg = e.error?.message ?? errorMsg;
+            }
+            catch { /* non-JSON */ }
+            throw new Error(`Circle listCompletedTransfers failed: ${errorMsg}`);
+        }
+        const parsed = safeParseJson(body);
+        const payouts = parsed.data ?? [];
+        const rangeStart = new Date(dateRange.start).getTime();
+        const rangeEnd = new Date(dateRange.end).getTime();
+        // Filter by date range client-side (Circle API pagination doesn't support date filters directly)
+        return payouts
+            .filter(p => {
+            const created = new Date(p.createDate).getTime();
+            return created >= rangeStart && created <= rangeEnd;
+        })
+            .map(p => {
+            const amount = p.amount;
+            const fees = p.fees;
+            const amountCents = toCents(parseFloat(amount.amount));
+            const feesCents = fees ? toCents(parseFloat(fees.amount)) : toCents(0);
+            // Use Circle payout ID as stable identifier instead of randomUUID()
+            // to ensure idempotent reads return consistent IDs for the same payout.
+            const id = p.id;
+            const record = {
+                id,
+                fundingPlanId: '',
+                providerTransferId: p.id,
+                provider: 'circle',
+                direction: 'crypto_to_fiat',
+                sourceAsset: 'USDC',
+                sourceNetwork: 'ETH',
+                amountCents,
+                feesCents,
+                netAmountCents: (amountCents - feesCents),
+                destinationBankId: this.bankId,
+                status: 'completed',
+                initiatedAt: p.createDate,
+                completedAt: p.updateDate,
+                idempotencyKey: '',
+                previousHash: '',
+            };
+            const hash = computeTransferHash(record, '');
+            return { ...record, hash };
+        });
+    }
+}

package/dist/wizard/lib/financial/stablecoin/mercury.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Mercury Bank Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements RevenueSourceAdapter for Mercury's REST API.
+ * Mercury is a bank, not a stablecoin provider — this reads bank balances
+ * and transactions for treasury visibility (same pattern as Stripe adapter).
+ *
+ * Mercury API v1:
+ *   Base URL: https://api.mercury.com/api/v1
+ *   Auth: Authorization: Bearer {apiKey}
+ *
+ * PRD Reference: §12.2 (Operating Bank Account)
+ * No Stubs Doctrine: every method makes a real API call.
+ */
+import type { RevenueSourceAdapter, RevenueCredentials, ConnectionResult, TransactionPage, BalanceResult, DateRange } from '../../revenue-types.js';
+export declare class MercuryBankAdapter implements RevenueSourceAdapter {
+    private apiKey;
+    private accountId;
+    constructor(apiKey: string, accountId?: string);
+    connect(_credentials?: RevenueCredentials): Promise<ConnectionResult>;
+    detectCurrency(_credentials?: RevenueCredentials): Promise<string>;
+    getTransactions(range: DateRange, cursor?: string): Promise<TransactionPage>;
+    getBalance(): Promise<BalanceResult>;
+}

package/dist/wizard/lib/financial/stablecoin/mercury.js

@@ -0,0 +1,171 @@
+/**
+ * Mercury Bank Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements RevenueSourceAdapter for Mercury's REST API.
+ * Mercury is a bank, not a stablecoin provider — this reads bank balances
+ * and transactions for treasury visibility (same pattern as Stripe adapter).
+ *
+ * Mercury API v1:
+ *   Base URL: https://api.mercury.com/api/v1
+ *   Auth: Authorization: Bearer {apiKey}
+ *
+ * PRD Reference: §12.2 (Operating Bank Account)
+ * No Stubs Doctrine: every method makes a real API call.
+ */
+import { request as httpsRequest } from 'node:https';
+const MERCURY_HOST = 'api.mercury.com';
+// ── HTTP helper ──────────────────────────────────────
+async function mercuryGet(path, apiKey, params) {
+    const query = params ? '?' + new URLSearchParams(params).toString() : '';
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            hostname: MERCURY_HOST,
+            path: `/api/v1${path}${query}`,
+            method: 'GET',
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+                'Accept': 'application/json',
+            },
+            timeout: 15000,
+        }, (res) => {
+            let data = '';
+            res.on('data', (chunk) => { data += chunk.toString(); });
+            res.on('end', () => resolve({ status: res.statusCode ?? 500, body: data }));
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('Mercury API timeout')); });
+        req.end();
+    });
+}
+// ── Mercury Bank Adapter ─────────────────────────────
+export class MercuryBankAdapter {
+    apiKey;
+    accountId;
+    constructor(apiKey, accountId) {
+        this.apiKey = apiKey;
+        this.accountId = accountId;
+    }
+    async connect(_credentials) {
+        try {
+            const { status, body } = await mercuryGet('/accounts', this.apiKey);
+            if (status === 200) {
+                const data = JSON.parse(body);
+                const accounts = data.accounts ?? [];
+                if (accounts.length === 0) {
+                    return { connected: false, error: 'No accounts found' };
+                }
+                const primary = accounts[0];
+                this.accountId = primary.id;
+                return {
+                    connected: true,
+                    accountId: primary.id,
+                    accountName: primary.name ?? 'Mercury Account',
+                    currency: 'USD',
+                };
+            }
+            // VG-R1-005: Wrap error-path JSON.parse
+            try {
+                const error = JSON.parse(body);
+                return { connected: false, error: error.message ?? error.error ?? `HTTP ${status}` };
+            }
+            catch {
+                return { connected: false, error: `HTTP ${status}` };
+            }
+        }
+        catch (err) {
+            return { connected: false, error: err instanceof Error ? err.message : 'Connection failed' };
+        }
+    }
+    async detectCurrency(_credentials) {
+        // Mercury is USD-only
+        return 'USD';
+    }
+    async getTransactions(range, cursor) {
+        if (!this.accountId) {
+            throw new Error('Mercury: must call connect() before getTransactions()');
+        }
+        const params = {
+            start: range.start,
+            end: range.end,
+            limit: '100',
+        };
+        if (cursor)
+            params.offset = cursor;
+        try {
+            const { status, body } = await mercuryGet(`/account/${this.accountId}/transactions`, this.apiKey, params);
+            if (status !== 200) {
+                // VG-R1-005: Wrap error-path JSON.parse
+                let errorMsg = `HTTP ${status}`;
+                try {
+                    const error = JSON.parse(body);
+                    errorMsg = error.message ?? errorMsg;
+                }
+                catch { /* non-JSON response */ }
+                throw new Error(errorMsg);
+            }
+            const data = JSON.parse(body);
+            const txns = data.transactions ?? [];
+            const transactions = txns
+                .filter(t => t.status === 'sent' || t.status === 'received' || t.status === 'pending')
+                .map(t => ({
+                externalId: t.id ?? '',
+                type: mapMercuryKind(t.kind, t.amount),
+                amount: Math.round((t.amount ?? 0) * 100),
+                currency: 'USD',
+                description: t.note ?? t.counterpartyName ?? 'Mercury transaction',
+                metadata: {},
+                createdAt: t.createdAt ?? new Date().toISOString(),
+            }));
+            const total = data.total ?? 0;
+            const offset = cursor ? parseInt(cursor, 10) : 0;
+            const hasMore = offset + txns.length < total;
+            const nextCursor = hasMore ? String(offset + txns.length) : undefined;
+            return {
+                transactions,
+                hasMore,
+                cursor: nextCursor,
+            };
+        }
+        catch (err) {
+            throw new Error(`Mercury getTransactions failed: ${err instanceof Error ? err.message : 'Unknown error'}`);
+        }
+    }
+    async getBalance() {
+        if (!this.accountId) {
+            throw new Error('Mercury: must call connect() before getBalance()');
+        }
+        try {
+            const { status, body } = await mercuryGet(`/account/${this.accountId}`, this.apiKey);
+            if (status !== 200) {
+                let errorMsg = `HTTP ${status}`;
+                try {
+                    const error = JSON.parse(body);
+                    errorMsg = error.message ?? errorMsg;
+                }
+                catch { /* non-JSON response */ }
+                throw new Error(errorMsg);
+            }
+            const data = JSON.parse(body);
+            const available = Math.round((data.availableBalance ?? data.currentBalance ?? 0) * 100);
+            const pending = Math.round(((data.currentBalance ?? 0) - (data.availableBalance ?? data.currentBalance ?? 0)) * 100);
+            return {
+                available: available,
+                pending: pending,
+                currency: 'USD',
+            };
+        }
+        catch (err) {
+            throw new Error(`Mercury getBalance failed: ${err instanceof Error ? err.message : 'Unknown error'}`);
+        }
+    }
+}
+// ── Helpers ──────────────────────────────────────────
+function mapMercuryKind(kind, amount) {
+    // Mercury transaction kinds: externalTransfer, internalTransfer, outgoingPayment, incomingPayment, etc.
+    // Map to revenue-source-adapter types based on direction (amount sign)
+    if (kind === 'incomingPayment' || (amount !== undefined && amount > 0))
+        return 'charge';
+    if (kind === 'outgoingPayment' || (amount !== undefined && amount < 0))
+        return 'refund';
+    return 'charge';
+}

package/dist/wizard/lib/financial/stablecoin/sandbox-stablecoin.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Sandbox Stablecoin Adapter — full implementation for development/demo.
+ *
+ * Returns realistic fake data matching the StablecoinSetup + StablecoinAdapter
+ * interfaces. Every method returns valid-shaped data. No throws.
+ * This IS a full implementation for a sandbox provider (No Stubs Doctrine).
+ *
+ * Simulates a USDC wallet with ~$50,000 starting balance, realistic off-ramp
+ * lifecycle (pending -> processing -> completed over 3 polls), and deterministic
+ * fee estimates.
+ */
+import type { StablecoinSetup, StablecoinAdapter, ProviderCredentials, SupportedAsset, StablecoinBalance, CombinedBalances, OfframpQuote, TransferRecord, TransferStatusDetail, FundingPlanRef, DateRange } from './base.js';
+type Cents = number & {
+    readonly __brand: 'Cents';
+};
+export declare class SandboxStablecoinSetup implements StablecoinSetup {
+    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[]>;
+}
+export declare class SandboxStablecoinAdapter implements StablecoinAdapter {
+    private balanceCents;
+    private transfers;
+    constructor(initialBalanceDollars?: number);
+    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[]>;
+}
+export {};