stable-ci 0.1.3 → 0.2.0

package/README.md

@@ -129,6 +129,16 @@ PASS  late_payment
 
 A failed scenario causes a non-zero exit code, so it can fail CI.
 
+## Working example
+
+A complete external integration example is available here:
+
+https://github.com/saldfsdk/stable-ci-example
+
+The example repository installs `stable-ci` from npm, starts a test payment application, and runs `saldfsdk/stable-ci@v0.1.3` as a GitHub Action from a separate repository.
+
+Its CI verifies the full external integration path and produces a JUnit report.
+
 ## Expected outcomes
 
 Different applications may intentionally handle payment exceptions differently.
@@ -161,9 +171,9 @@ This repository includes a composite GitHub Action.
 
 ```yaml
 steps:
-  - uses: actions/checkout@v4
+  - uses: actions/checkout@v7
 
-  - uses: saldfsdk/stable-ci@v0.1.1
+  - uses: saldfsdk/stable-ci@v0.2.0
     with:
       config: stable-ci.yml
       junit: reports/stable-ci.xml
@@ -212,6 +222,97 @@ Current scenarios include:
 - `overpayment`
 - `late_payment`
 
+## Custom webhook providers
+
+`stable-ci` can test payment integrations that use providers without a built-in adapter.
+
+Use JSON webhook fixtures to describe the provider payloads that your application already accepts.
+
+Example `stable-ci.yml`:
+
+```yaml
+provider: custom
+
+webhookSecret: your-test-webhook-secret
+
+customProvider:
+  name: onswitch-like
+
+  fixtures:
+    pending: fixtures/pending.json
+    completed: fixtures/completed.json
+    underpaid: fixtures/underpaid.json
+    expired: fixtures/expired.json
+
+  signature:
+    header: x-switch-signature
+    algorithm: sha256
+    encoding: base64
+
+target:
+  name: payment-app
+  baseUrl: http://127.0.0.1:4310
+  endpoints:
+    reset: /reset
+    webhook: /webhook
+    state: /state
+    reconcile: /reconcile
+
+payment:
+  id: pay_test_001
+  amount: 100
+  asset: USDC
+
+scenarios:
+  - duplicate_webhook
+  - out_of_order_webhook
+  - missing_webhook
+  - invalid_signature
+  - underpayment
+  - overpayment
+  - late_payment
+```
+
+A fixture can use placeholders:
+
+```json
+{
+  "id": "{{eventId}}",
+  "paymentId": "{{paymentId}}",
+  "status": "{{status}}",
+  "amount": "{{amount}}",
+  "actualAmount": "{{actualAmount}}",
+  "asset": "{{asset}}",
+  "eventType": "{{eventType}}"
+}
+```
+
+Available placeholders:
+
+- `{{eventId}}`
+- `{{paymentId}}`
+- `{{status}}`
+- `{{amount}}`
+- `{{actualAmount}}`
+- `{{asset}}`
+- `{{eventType}}`
+
+When a placeholder is the entire JSON string value, numbers remain numbers instead of being converted to strings.
+
+Fixture paths are resolved relative to `stable-ci.yml`.
+
+Custom headers may also contain placeholders:
+
+```yaml
+customProvider:
+  headers:
+    x-payment-id: "{{paymentId}}"
+```
+
+For signed webhooks, `stable-ci` signs the final rendered raw JSON body. The signature header name is configurable, so providers using headers such as `x-switch-signature` can be tested without adding provider-specific code to `stable-ci`.
+
+The target application still exposes the stable-ci test observer endpoints (`reset`, `state`, and optionally `reconcile`). These endpoints are intended for test and CI environments only.
+
 ## Provider support
 
 ### BVNK

package/dist/adapters/configured-http.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { createBvnkProvider } from '../providers/bvnk.js';
 import { createGenericProvider } from '../providers/generic.js';
+import { createCustomProvider } from '../providers/custom.js';
 const stateSchema = z.object({
     applicationStatus: z.enum([
         'none',
@@ -20,6 +21,19 @@ function getProvider(config) {
     if (config.provider === 'bvnk') {
         return createBvnkProvider(config.webhookSecret ?? 'stable-ci-local-secret');
     }
+    if (config.provider === 'custom') {
+        const custom = config.customProvider;
+        if (!custom) {
+            throw new Error('Custom provider configuration is missing.');
+        }
+        return createCustomProvider({
+            name: custom.name,
+            fixtures: custom.fixtures,
+            headers: custom.headers,
+            signature: custom.signature,
+            webhookSecret: config.webhookSecret,
+        });
+    }
     return createGenericProvider();
 }
 async function postJson(baseUrl, path, body = {}) {
@@ -63,12 +77,16 @@ async function sendInvalidSignatureWebhook(config, provider) {
         amount: config.payment.amount,
         asset: config.payment.asset,
     });
+    const signatureHeader = provider.signatureHeader;
+    if (!signatureHeader) {
+        throw new Error('invalid_signature requires a provider with a configured signature header.');
+    }
     const response = await fetch(config.target.baseUrl +
         config.target.endpoints.webhook, {
         method: 'POST',
         headers: {
             ...rendered.headers,
-            'x-signature': 'invalid-signature',
+            [signatureHeader]: 'stable-ci-invalid-signature',
         },
         body: rendered.body,
     });
@@ -115,33 +133,30 @@ export function createConfiguredHttpAdapter(config) {
                     }
                     break;
                 case 'invalid_signature':
-                    if (provider.name !== 'bvnk') {
-                        throw new Error('invalid_signature currently requires the BVNK provider.');
-                    }
                     webhookAccepted =
                         await sendInvalidSignatureWebhook(config, provider);
                     providerStatus = 'failed';
                     chainStatus = 'not_broadcast';
                     break;
                 case 'underpayment':
-                    if (provider.name !== 'bvnk') {
-                        throw new Error('underpayment currently requires the BVNK provider.');
+                    if (config.provider === 'generic') {
+                        throw new Error('underpayment requires the BVNK or custom provider.');
                     }
                     receivedAmount = payment.amount * 0.6;
                     providerStatus = 'underpaid';
                     await sendWebhook(config, provider, 'evt_underpayment_1', 'underpaid', receivedAmount, 'transactionConfirmed');
                     break;
                 case 'overpayment':
-                    if (provider.name !== 'bvnk') {
-                        throw new Error('overpayment currently requires the BVNK provider.');
+                    if (config.provider === 'generic') {
+                        throw new Error('overpayment requires the BVNK or custom provider.');
                     }
                     receivedAmount = payment.amount * 1.4;
                     providerStatus = 'completed';
                     await sendWebhook(config, provider, 'evt_overpayment_1', 'completed', receivedAmount, 'transactionConfirmed');
                     break;
                 case 'late_payment':
-                    if (provider.name !== 'bvnk') {
-                        throw new Error('late_payment currently requires the BVNK provider.');
+                    if (config.provider === 'generic') {
+                        throw new Error('late_payment requires the BVNK or custom provider.');
                     }
                     receivedAmount = payment.amount;
                     providerStatus = 'expired';

package/dist/config.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { dirname, resolve, } from 'node:path';
 import { parse } from 'yaml';
 import { z } from 'zod';
 const scenarioSchema = z.enum([
@@ -32,9 +33,31 @@ const expectedOutcomeSchema = z.object({
     retryAttempts: z.number().int().nonnegative().optional(),
     webhookAccepted: z.boolean().optional(),
 });
+const fixtureSchema = z.object({
+    pending: z.string().min(1).optional(),
+    completed: z.string().min(1).optional(),
+    failed: z.string().min(1).optional(),
+    underpaid: z.string().min(1).optional(),
+    expired: z.string().min(1).optional(),
+});
+const customProviderSchema = z.object({
+    name: z.string().min(1).default('custom'),
+    fixtures: fixtureSchema,
+    headers: z.record(z.string(), z.string()).optional(),
+    signature: z.object({
+        header: z.string().min(1),
+        algorithm: z.literal('sha256').default('sha256'),
+        encoding: z.enum(['base64', 'hex']).default('base64'),
+    }).optional(),
+});
 const configSchema = z.object({
-    provider: z.enum(['generic', 'bvnk']).default('generic'),
+    provider: z.enum([
+        'generic',
+        'bvnk',
+        'custom',
+    ]).default('generic'),
     webhookSecret: z.string().min(1).optional(),
+    customProvider: customProviderSchema.optional(),
     target: z.object({
         name: z.string().min(1),
         baseUrl: z.string().url(),
@@ -53,14 +76,72 @@ const configSchema = z.object({
     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);
+function resolveFixtures(fixtures, configDir) {
+    return Object.fromEntries(Object.entries(fixtures).map(([status, fixturePath]) => [
+        status,
+        resolve(configDir, fixturePath),
+    ]));
+}
+export function loadConfig(configPath) {
+    if (!fs.existsSync(configPath)) {
+        throw new Error('Config file not found: ' + configPath);
     }
-    const raw = fs.readFileSync(path, 'utf8');
+    const raw = fs.readFileSync(configPath, 'utf8');
     const parsed = configSchema.parse(parse(raw));
+    const configDir = dirname(resolve(configPath));
+    const customProvider = parsed.customProvider
+        ? {
+            ...parsed.customProvider,
+            fixtures: resolveFixtures(parsed.customProvider.fixtures, configDir),
+        }
+        : undefined;
+    if (parsed.provider === 'custom' &&
+        !customProvider) {
+        throw new Error('provider custom requires customProvider configuration.');
+    }
+    if (parsed.provider === 'custom' &&
+        customProvider) {
+        const requiredFixtures = new Set();
+        for (const scenario of parsed.scenarios) {
+            switch (scenario) {
+                case 'duplicate_webhook':
+                case 'overpayment':
+                case 'invalid_signature':
+                    requiredFixtures.add('completed');
+                    break;
+                case 'out_of_order_webhook':
+                    requiredFixtures.add('completed');
+                    requiredFixtures.add('pending');
+                    break;
+                case 'underpayment':
+                    requiredFixtures.add('underpaid');
+                    break;
+                case 'late_payment':
+                    requiredFixtures.add('expired');
+                    break;
+                case 'missing_webhook':
+                    break;
+            }
+        }
+        for (const status of requiredFixtures) {
+            if (!customProvider.fixtures[status]) {
+                throw new Error('Custom provider is missing the ' +
+                    status +
+                    ' webhook fixture required by the configured scenarios.');
+            }
+        }
+        if (customProvider.signature &&
+            !parsed.webhookSecret) {
+            throw new Error('customProvider.signature requires webhookSecret.');
+        }
+        if (parsed.scenarios.includes('invalid_signature') &&
+            !customProvider.signature) {
+            throw new Error('invalid_signature requires customProvider.signature.');
+        }
+    }
     return {
         ...parsed,
+        customProvider,
         scenarios: parsed.scenarios,
         expectations: parsed.expectations,
     };

package/dist/providers/bvnk.js

@@ -15,6 +15,7 @@ function toBvnkStatus(status) {
 export function createBvnkProvider(webhookSecret = 'stable-ci-local-secret') {
     return {
         name: 'bvnk',
+        signatureHeader: 'x-signature',
         render(event) {
             const eventType = event.eventType ?? 'statusChanged';
             const actualAmount = event.actualAmount ?? event.amount;

package/dist/providers/custom.js

@@ -0,0 +1,82 @@
+import { createHmac } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+function templateValues(event) {
+    return {
+        eventId: event.eventId,
+        paymentId: event.paymentId,
+        status: event.status,
+        amount: event.amount,
+        actualAmount: event.actualAmount ?? event.amount,
+        asset: event.asset,
+        eventType: event.eventType ?? null,
+    };
+}
+function renderString(value, values) {
+    const exact = value.match(/^\{\{(eventId|paymentId|status|amount|actualAmount|asset|eventType)\}\}$/);
+    if (exact) {
+        return values[exact[1]];
+    }
+    return value.replace(/\{\{(eventId|paymentId|status|amount|actualAmount|asset|eventType)\}\}/g, (_match, key) => String(values[key] ?? ''));
+}
+function renderTemplateValue(value, values) {
+    if (typeof value === 'string') {
+        return renderString(value, values);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => renderTemplateValue(item, values));
+    }
+    if (typeof value === 'object' &&
+        value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            renderTemplateValue(item, values),
+        ]));
+    }
+    return value;
+}
+function renderBodyTemplate(template, event) {
+    const parsed = JSON.parse(template);
+    const rendered = renderTemplateValue(parsed, templateValues(event));
+    return JSON.stringify(rendered);
+}
+function renderHeaderTemplate(template, event) {
+    const values = templateValues(event);
+    return template.replace(/\{\{(eventId|paymentId|status|amount|actualAmount|asset|eventType)\}\}/g, (_match, key) => String(values[key] ?? ''));
+}
+export function createCustomProvider(options) {
+    if (options.signature &&
+        !options.webhookSecret) {
+        throw new Error('custom provider signature requires webhookSecret.');
+    }
+    return {
+        name: options.name,
+        signatureHeader: options.signature?.header,
+        render(event) {
+            const fixturePath = options.fixtures[event.status];
+            if (!fixturePath) {
+                throw new Error('No custom webhook fixture configured for status: ' +
+                    event.status);
+            }
+            const template = readFileSync(fixturePath, 'utf8');
+            const body = renderBodyTemplate(template, event);
+            const headers = {
+                'content-type': 'application/json',
+            };
+            for (const [name, value] of Object.entries(options.headers ?? {})) {
+                headers[name] =
+                    renderHeaderTemplate(value, event);
+            }
+            if (options.signature) {
+                const signature = createHmac(options.signature.algorithm, options.webhookSecret)
+                    .update(body, 'utf8')
+                    .digest(options.signature.encoding);
+                headers[options.signature.header] =
+                    signature;
+            }
+            return {
+                body,
+                headers,
+            };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stable-ci",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Reliability CI for stablecoin payment integrations",
   "scripts": {
     "test": "vitest run",