stable-ci 0.1.0

package/dist/adapters/http-demo.js

@@ -0,0 +1,232 @@
+import { startDemoPaymentApp, } from '../core/demo-payment-app.js';
+import { createBvnkProvider } from '../providers/bvnk.js';
+async function post(baseUrl, path, body = {}) {
+    const response = await fetch(baseUrl + path, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok && response.status !== 409) {
+        throw new Error('HTTP ' + response.status + ' from ' + path);
+    }
+    return response;
+}
+async function getState(baseUrl) {
+    const response = await fetch(baseUrl + '/state');
+    if (!response.ok) {
+        throw new Error('Failed to read demo application state.');
+    }
+    return await response.json();
+}
+export function createHttpDemoAdapter(profile) {
+    return {
+        name: 'http-demo:' + profile,
+        async runScenario(scenario) {
+            const app = await startDemoPaymentApp(profile);
+            const paymentId = 'pay_http_001';
+            const amount = 100;
+            let providerStatus = 'completed';
+            let chainStatus = 'confirmed';
+            let webhookAccepted;
+            const webhook = async (eventId, status) => {
+                await post(app.baseUrl, '/webhook', {
+                    eventId,
+                    paymentId,
+                    status,
+                    amount,
+                });
+            };
+            try {
+                await post(app.baseUrl, '/reset');
+                switch (scenario) {
+                    case 'duplicate_webhook':
+                        await webhook('evt_complete_1', 'completed');
+                        await webhook('evt_complete_1', 'completed');
+                        break;
+                    case 'out_of_order_webhook':
+                        await webhook('evt_complete_1', 'completed');
+                        await webhook('evt_pending_2', 'pending');
+                        break;
+                    case 'missing_webhook':
+                        await post(app.baseUrl, '/reconcile', {
+                            paymentId,
+                            chainStatus: 'confirmed',
+                            amount,
+                        });
+                        break;
+                    case 'provider_timeout_after_broadcast':
+                        providerStatus = 'timeout';
+                        await post(app.baseUrl, '/mark-unknown');
+                        await post(app.baseUrl, '/retry', {
+                            paymentId,
+                            amount,
+                        });
+                        await post(app.baseUrl, '/reconcile', {
+                            paymentId,
+                            chainStatus: 'confirmed',
+                            amount,
+                        });
+                        break;
+                    case 'late_chain_confirmation':
+                        providerStatus = 'timeout';
+                        await post(app.baseUrl, '/mark-unknown');
+                        await post(app.baseUrl, '/retry', {
+                            paymentId,
+                            amount,
+                        });
+                        await new Promise((resolve) => setTimeout(resolve, 10));
+                        await post(app.baseUrl, '/reconcile', {
+                            paymentId,
+                            chainStatus: 'confirmed',
+                            amount,
+                        });
+                        break;
+                    case 'retry_after_unknown_settlement':
+                        providerStatus = 'timeout';
+                        await post(app.baseUrl, '/mark-unknown');
+                        await post(app.baseUrl, '/retry', {
+                            paymentId,
+                            amount,
+                        });
+                        await post(app.baseUrl, '/reconcile', {
+                            paymentId,
+                            chainStatus: 'confirmed',
+                            amount,
+                        });
+                        break;
+                    case 'underpayment': {
+                        providerStatus = 'underpaid';
+                        const provider = createBvnkProvider('stable-ci-local-secret');
+                        const rendered = provider.render({
+                            eventId: 'evt_underpayment_1',
+                            paymentId,
+                            eventType: 'transactionConfirmed',
+                            status: 'underpaid',
+                            amount,
+                            actualAmount: 60,
+                            asset: 'USDC',
+                        });
+                        const response = await fetch(app.baseUrl + '/webhook', {
+                            method: 'POST',
+                            headers: rendered.headers,
+                            body: rendered.body,
+                        });
+                        if (!response.ok) {
+                            throw new Error('Underpayment webhook returned HTTP ' +
+                                response.status);
+                        }
+                        break;
+                    }
+                    case 'overpayment': {
+                        const provider = createBvnkProvider('stable-ci-local-secret');
+                        const rendered = provider.render({
+                            eventId: 'evt_overpayment_1',
+                            paymentId,
+                            eventType: 'transactionConfirmed',
+                            status: 'completed',
+                            amount,
+                            actualAmount: 140,
+                            asset: 'USDC',
+                        });
+                        const response = await fetch(app.baseUrl + '/webhook', {
+                            method: 'POST',
+                            headers: rendered.headers,
+                            body: rendered.body,
+                        });
+                        if (!response.ok) {
+                            throw new Error('Overpayment webhook returned HTTP ' +
+                                response.status);
+                        }
+                        break;
+                    }
+                    case 'late_payment': {
+                        providerStatus = 'expired';
+                        const provider = createBvnkProvider('stable-ci-local-secret');
+                        const rendered = provider.render({
+                            eventId: 'evt_late_payment_1',
+                            paymentId,
+                            eventType: 'transactionLate',
+                            status: 'expired',
+                            amount,
+                            actualAmount: amount,
+                            asset: 'USDC',
+                        });
+                        const response = await fetch(app.baseUrl + '/webhook', {
+                            method: 'POST',
+                            headers: rendered.headers,
+                            body: rendered.body,
+                        });
+                        if (!response.ok) {
+                            throw new Error('Late payment webhook returned HTTP ' +
+                                response.status);
+                        }
+                        break;
+                    }
+                    case 'invalid_signature': {
+                        providerStatus = 'failed';
+                        chainStatus = 'not_broadcast';
+                        const payload = JSON.stringify({
+                            source: 'payment',
+                            event: 'statusChanged',
+                            data: {
+                                uuid: paymentId,
+                                reference: 'evt_invalid_signature',
+                                type: 'IN',
+                                subType: 'merchantPayIn',
+                                status: 'COMPLETE',
+                                displayCurrency: {
+                                    currency: 'USDC',
+                                    amount,
+                                    actual: amount,
+                                },
+                                paidCurrency: {
+                                    currency: 'USDC',
+                                    amount,
+                                    actual: amount,
+                                },
+                            },
+                        });
+                        const response = await fetch(app.baseUrl + '/webhook', {
+                            method: 'POST',
+                            headers: {
+                                'content-type': 'application/json',
+                                'x-signature': 'invalid-signature',
+                            },
+                            body: payload,
+                        });
+                        webhookAccepted = response.ok;
+                        break;
+                    }
+                }
+                const state = await getState(app.baseUrl);
+                return {
+                    scenario,
+                    paymentId,
+                    expectedAmount: amount,
+                    receivedAmount: scenario === 'underpayment'
+                        ? 60
+                        : scenario === 'overpayment'
+                            ? 140
+                            : scenario === 'late_payment'
+                                ? 100
+                                : undefined,
+                    providerStatus,
+                    chainStatus,
+                    webhookDeliveries: state.webhookDeliveries,
+                    ledgerEntries: state.ledgerEntries,
+                    creditedAmount: state.creditedAmount,
+                    applicationStatus: state.applicationStatus,
+                    retryAttempts: state.retryAttempts,
+                    settlementWasUnknown: state.settlementWasUnknown,
+                    recovered: state.recovered,
+                    webhookAccepted,
+                };
+            }
+            finally {
+                await app.close();
+            }
+        },
+    };
+}

package/dist/config.js

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import { parse } from 'yaml';
+import { z } from 'zod';
+const scenarioSchema = z.enum([
+    'duplicate_webhook',
+    'out_of_order_webhook',
+    'missing_webhook',
+    'invalid_signature',
+    'underpayment',
+    'overpayment',
+    'late_payment',
+]);
+const applicationStatusSchema = z.enum([
+    'none',
+    'pending',
+    'completed',
+    'failed',
+    'manual_review',
+]);
+const expectedOutcomeSchema = z.object({
+    applicationStatus: z.union([
+        applicationStatusSchema,
+        z.array(applicationStatusSchema),
+    ]).optional(),
+    ledgerEntries: z.number().int().nonnegative().optional(),
+    credit: z.enum([
+        'exact_expected',
+        'none',
+        'received_amount',
+        'any',
+    ]).optional(),
+    retryAttempts: z.number().int().nonnegative().optional(),
+    webhookAccepted: z.boolean().optional(),
+});
+const configSchema = z.object({
+    provider: z.enum(['generic', 'bvnk']).default('generic'),
+    webhookSecret: z.string().min(1).optional(),
+    target: z.object({
+        name: z.string().min(1),
+        baseUrl: z.string().url(),
+        endpoints: z.object({
+            reset: z.string().min(1),
+            webhook: z.string().min(1),
+            state: z.string().min(1),
+            reconcile: z.string().min(1).optional(),
+        }),
+    }),
+    payment: z.object({
+        id: z.string().min(1),
+        amount: z.number().positive(),
+        asset: z.string().min(1),
+    }),
+    scenarios: z.array(scenarioSchema).min(1),
+    expectations: z.record(z.string(), expectedOutcomeSchema).optional(),
+});
+export function loadConfig(path) {
+    if (!fs.existsSync(path)) {
+        throw new Error('Config file not found: ' + path);
+    }
+    const raw = fs.readFileSync(path, 'utf8');
+    const parsed = configSchema.parse(parse(raw));
+    return {
+        ...parsed,
+        scenarios: parsed.scenarios,
+        expectations: parsed.expectations,
+    };
+}

package/dist/core/demo-payment-app.js

@@ -0,0 +1,254 @@
+import { createServer } from 'node:http';
+import { createHmac } from 'node:crypto';
+function initialState() {
+    return {
+        paymentId: '',
+        applicationStatus: 'none',
+        webhookDeliveries: 0,
+        ledgerEntries: 0,
+        creditedAmount: 0,
+        retryAttempts: 0,
+        settlementWasUnknown: false,
+        recovered: false,
+        seenEventIds: [],
+    };
+}
+async function readJson(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.from(chunk));
+    }
+    const raw = Buffer.concat(chunks).toString('utf8');
+    if (!raw) {
+        return {};
+    }
+    return JSON.parse(raw);
+}
+async function readRawJson(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.from(chunk));
+    }
+    const raw = Buffer.concat(chunks).toString('utf8');
+    return {
+        raw,
+        body: raw
+            ? JSON.parse(raw)
+            : {},
+    };
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, {
+        'content-type': 'application/json',
+    });
+    res.end(JSON.stringify(body));
+}
+export async function startDemoPaymentApp(profile, port = 0) {
+    let state = initialState();
+    const server = createServer(async (req, res) => {
+        try {
+            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+            if (req.method === 'POST' && url.pathname === '/reset') {
+                state = initialState();
+                sendJson(res, 200, state);
+                return;
+            }
+            if (req.method === 'POST' && url.pathname === '/mark-unknown') {
+                state.settlementWasUnknown = true;
+                sendJson(res, 200, state);
+                return;
+            }
+            if (req.method === 'POST' && url.pathname === '/webhook') {
+                const { body, raw } = await readRawJson(req);
+                const data = typeof body.data === 'object' &&
+                    body.data !== null
+                    ? body.data
+                    : undefined;
+                const displayCurrency = data &&
+                    typeof data.displayCurrency === 'object' &&
+                    data.displayCurrency !== null
+                    ? data.displayCurrency
+                    : undefined;
+                const paidCurrency = data &&
+                    typeof data.paidCurrency === 'object' &&
+                    data.paidCurrency !== null
+                    ? data.paidCurrency
+                    : undefined;
+                const walletCurrency = data &&
+                    typeof data.walletCurrency === 'object' &&
+                    data.walletCurrency !== null
+                    ? data.walletCurrency
+                    : undefined;
+                const isBvnk = body.source === 'payment' &&
+                    (body.event === 'statusChanged' ||
+                        body.event === 'transactionConfirmed' ||
+                        body.event === 'transactionLate') &&
+                    data !== undefined;
+                if (profile === 'safe' && isBvnk) {
+                    const suppliedSignature = String(req.headers['x-signature'] ?? '');
+                    const expectedSignature = createHmac('sha256', 'stable-ci-local-secret')
+                        .update(raw, 'utf8')
+                        .digest('base64');
+                    if (suppliedSignature !== expectedSignature) {
+                        sendJson(res, 401, {
+                            error: 'Invalid BVNK webhook signature',
+                        });
+                        return;
+                    }
+                }
+                const rawStatus = isBvnk
+                    ? String(data.status ?? '')
+                    : String(body.status ?? 'pending');
+                const status = isBvnk &&
+                    body.event === 'transactionLate'
+                    ? 'manual_review'
+                    : rawStatus === 'COMPLETE'
+                        ? 'completed'
+                        : rawStatus === 'PROCESSING'
+                            ? 'pending'
+                            : rawStatus === 'EXPIRED'
+                                ? 'failed'
+                                : rawStatus === 'UNDERPAID'
+                                    ? 'manual_review'
+                                    : rawStatus;
+                const paymentId = isBvnk
+                    ? String(data.uuid ?? '')
+                    : String(body.paymentId ?? '');
+                const eventId = isBvnk
+                    ? String(data.reference ?? '') +
+                        ':' +
+                        String(body.event ?? '') +
+                        ':' +
+                        rawStatus
+                    : String(body.eventId ?? '');
+                const amount = isBvnk
+                    ? Number(paidCurrency?.amount ??
+                        displayCurrency?.amount ??
+                        0)
+                    : Number(body.amount ?? 0);
+                const actualAmount = isBvnk
+                    ? Number(body.event === 'transactionLate'
+                        ? walletCurrency?.actual ??
+                            paidCurrency?.actual ??
+                            displayCurrency?.actual ??
+                            amount
+                        : paidCurrency?.actual ??
+                            displayCurrency?.actual ??
+                            amount)
+                    : amount;
+                state.paymentId = paymentId;
+                state.webhookDeliveries += 1;
+                const duplicate = state.seenEventIds.includes(eventId);
+                if (profile === 'safe' && duplicate) {
+                    sendJson(res, 200, {
+                        duplicate: true,
+                        state,
+                    });
+                    return;
+                }
+                state.seenEventIds.push(eventId);
+                if (profile === 'safe') {
+                    if (status === 'pending' &&
+                        state.applicationStatus === 'completed') {
+                        sendJson(res, 200, state);
+                        return;
+                    }
+                    state.applicationStatus = status;
+                    if (status === 'completed' &&
+                        state.ledgerEntries === 0) {
+                        state.ledgerEntries = 1;
+                        state.creditedAmount = amount;
+                    }
+                }
+                else {
+                    if (isBvnk &&
+                        body.event === 'transactionLate') {
+                        state.applicationStatus = 'completed';
+                        state.ledgerEntries += 1;
+                        state.creditedAmount += actualAmount;
+                    }
+                    else if (rawStatus === 'UNDERPAID') {
+                        state.applicationStatus = 'completed';
+                        state.ledgerEntries += 1;
+                        state.creditedAmount += amount;
+                    }
+                    else {
+                        state.applicationStatus = status;
+                        if (status === 'completed') {
+                            const creditAmount = isBvnk &&
+                                body.event === 'transactionConfirmed' ||
+                                body.event === 'transactionLate' &&
+                                    actualAmount > amount
+                                ? actualAmount
+                                : amount;
+                            state.ledgerEntries += 1;
+                            state.creditedAmount += creditAmount;
+                        }
+                    }
+                }
+                sendJson(res, 200, state);
+                return;
+            }
+            if (req.method === 'POST' && url.pathname === '/retry') {
+                const { body, raw } = await readRawJson(req);
+                const amount = Number(body.amount ?? 0);
+                if (profile === 'safe' &&
+                    state.settlementWasUnknown) {
+                    sendJson(res, 409, {
+                        error: 'Settlement outcome is unknown. Reconcile before retrying.',
+                    });
+                    return;
+                }
+                state.retryAttempts += 1;
+                if (profile === 'unsafe') {
+                    state.applicationStatus = 'completed';
+                    state.ledgerEntries += 1;
+                    state.creditedAmount += amount;
+                }
+                sendJson(res, 200, state);
+                return;
+            }
+            if (req.method === 'POST' && url.pathname === '/reconcile') {
+                const { body, raw } = await readRawJson(req);
+                const chainStatus = String(body.chainStatus ?? '');
+                const amount = Number(body.amount ?? 0);
+                if (profile === 'safe' &&
+                    chainStatus === 'confirmed') {
+                    if (state.ledgerEntries === 0) {
+                        state.ledgerEntries = 1;
+                        state.creditedAmount = amount;
+                    }
+                    state.applicationStatus = 'completed';
+                    state.recovered = true;
+                }
+                sendJson(res, 200, state);
+                return;
+            }
+            if (req.method === 'GET' && url.pathname === '/state') {
+                sendJson(res, 200, state);
+                return;
+            }
+            sendJson(res, 404, { error: 'Not found' });
+        }
+        catch (error) {
+            sendJson(res, 500, {
+                error: error instanceof Error
+                    ? error.message
+                    : 'Unknown error',
+            });
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    return {
+        baseUrl: 'http://127.0.0.1:' + address.port,
+        async close() {
+            await new Promise((resolve) => {
+                server.close(() => resolve());
+            });
+        },
+    };
+}

package/dist/core/runner.js

@@ -0,0 +1,16 @@
+import { evaluateInvariants } from '../invariants/builtins.js';
+import { scenarios } from '../scenarios/builtins.js';
+export async function runSuite(adapter, selectedScenarios = scenarios) {
+    const results = [];
+    for (const scenario of selectedScenarios) {
+        const observation = await adapter.runScenario(scenario.name);
+        const invariantResults = evaluateInvariants(observation, scenario.expected);
+        results.push({
+            scenario,
+            observation,
+            invariants: invariantResults,
+            passed: invariantResults.every((result) => result.passed),
+        });
+    }
+    return results;
+}