@sdods/core 0.2.1 → 0.3.0

package/dist/steps/webhook.steps.d.ts

@@ -0,0 +1,46 @@
+import { type Server } from 'node:http';
+import './params.js';
+/**
+ * An ephemeral callback receiver, for the leg where the application calls BACK.
+ *
+ * WHY — 16 trigger providers deliver by webhook. Without a receiver a suite can
+ * assert that a subscription was created and nothing about whether a delivery
+ * ever arrived, which is the half that actually matters: a trigger that
+ * registers and never fires looks identical to a working one.
+ *
+ * DESIGN — the server binds to an EPHEMERAL port on 127.0.0.1 and its URL is
+ * published into the scenario's template scope as `{{callback.url}}`, so the
+ * scenario never hardcodes a port. It is torn down at scenario end even when
+ * the scenario fails; a leaked listener silently poisons the next run on the
+ * same worker, and that is the kind of failure nobody traces back.
+ *
+ * Deliveries are recorded in arrival order and asserted by POLLING, never by
+ * sleeping. "Wait two seconds then check" is how a webhook suite becomes both
+ * slow and flaky at the same time.
+ *
+ * NOT a public tunnel. This receives from an application that can reach the
+ * runner — a local or in-VPC app under test. Reaching a hosted staging
+ * deployment needs a tunnel, which is an infrastructure decision rather than
+ * something a step library should quietly stand up.
+ */
+export interface Delivery {
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    body: string;
+    receivedAt: number;
+}
+export interface Receiver {
+    server: Server;
+    url: string;
+    deliveries: Delivery[];
+}
+/**
+ * Extracted from the step so the receiver itself is testable without a browser,
+ * a config or a Playwright runner. It is the most intricate piece here — an
+ * HTTP server, async body reading and a shared array — and "it worked when I
+ * tried it" is not a claim anyone can re-check later.
+ */
+export declare function startReceiver(): Promise<Receiver>;
+export declare function closeAllReceivers(): Promise<void>;
+//# sourceMappingURL=webhook.steps.d.ts.map

package/dist/steps/webhook.steps.js

@@ -0,0 +1,129 @@
+import { createServer } from 'node:http';
+import { expect } from '@playwright/test';
+import './params.js';
+import { AfterScenario, Given, Then, When } from '../fixtures/test.js';
+import { render } from '../api/template.js';
+import { SdodsError } from '../errors.js';
+const receivers = new Map();
+function key(apiContext) {
+    return String(apiContext.runId ?? 'default');
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+function requireReceiver(k) {
+    const r = receivers.get(k);
+    if (!r) {
+        throw new SdodsError('NOT_SUPPORTED', 'No callback receiver is listening.', {
+            hint: 'Use `Given a callback receiver is listening` first; its URL is available as {{callback.url}}.',
+        });
+    }
+    return r;
+}
+/**
+ * Extracted from the step so the receiver itself is testable without a browser,
+ * a config or a Playwright runner. It is the most intricate piece here — an
+ * HTTP server, async body reading and a shared array — and "it worked when I
+ * tried it" is not a claim anyone can re-check later.
+ */
+export async function startReceiver() {
+    const deliveries = [];
+    const server = createServer((req, res) => {
+        void readBody(req).then((body) => {
+            deliveries.push({
+                method: req.method ?? 'GET',
+                path: req.url ?? '/',
+                headers: Object.fromEntries(Object.entries(req.headers).map(([h, v]) => [
+                    h,
+                    Array.isArray(v) ? v.join(', ') : (v ?? ''),
+                ])),
+                body,
+                receivedAt: Date.now(),
+            });
+            // 200 with an empty body: a provider that retries on a non-2xx would
+            // otherwise deliver the same event repeatedly and the counts below would
+            // be meaningless.
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end('{}');
+        });
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        throw new SdodsError('INTERNAL', 'The callback receiver did not report a port.');
+    }
+    return { server, url: `http://127.0.0.1:${address.port}`, deliveries };
+}
+Given('a callback receiver is listening', async ({ apiContext }) => {
+    const k = key(apiContext);
+    if (receivers.has(k))
+        return;
+    const receiver = await startReceiver();
+    receivers.set(k, receiver);
+    // Published as a scope value so the scenario writes {{callback.url}} rather
+    // than a port it cannot know.
+    apiContext.vars.set('callback', {
+        url: receiver.url,
+    });
+});
+When('I stop the callback receiver', async ({ apiContext }) => {
+    const k = key(apiContext);
+    const r = receivers.get(k);
+    if (!r)
+        return;
+    await new Promise((resolve) => r.server.close(() => resolve()));
+    receivers.delete(k);
+});
+Then('the callback receiver should receive {int} delivery/deliveries', async ({ apiContext }, count) => {
+    const r = requireReceiver(key(apiContext));
+    await expect
+        .poll(() => r.deliveries.length, {
+        message: `expected ${count} callback delivery/deliveries`,
+    })
+        .toBe(count);
+});
+Then('the callback receiver should receive a delivery', async ({ apiContext }) => {
+    const r = requireReceiver(key(apiContext));
+    await expect
+        .poll(() => r.deliveries.length, { message: 'no callback delivery arrived' })
+        .toBeGreaterThan(0);
+});
+Then('the callback receiver should receive a delivery containing {string}', async ({ apiContext, env }, text) => {
+    const r = requireReceiver(key(apiContext));
+    const needle = render(text, apiContext.vars.toObject(), env.vars);
+    await expect
+        .poll(() => r.deliveries.some((d) => d.body.includes(needle)), {
+        message: `no callback delivery contained "${needle}"`,
+    })
+        .toBe(true);
+});
+Then('the last callback delivery should have the header {string} set to {string}', async ({ apiContext, env }, header, value) => {
+    const r = requireReceiver(key(apiContext));
+    await expect
+        .poll(() => r.deliveries.length, { message: 'no callback delivery arrived' })
+        .toBeGreaterThan(0);
+    const scopes = [
+        apiContext.vars.toObject(),
+        env.vars,
+    ];
+    const last = r.deliveries[r.deliveries.length - 1];
+    expect(last.headers[render(header, ...scopes).toLowerCase()]).toBe(render(value, ...scopes));
+});
+/**
+ * Torn down after EVERY scenario, including a failing one — hence a hook rather
+ * than a step. A leaked listener silently poisons the next scenario on the same
+ * worker, and that is a failure nobody traces back to the scenario that leaked.
+ */
+AfterScenario(async () => {
+    await closeAllReceivers();
+});
+export async function closeAllReceivers() {
+    for (const [k, r] of receivers) {
+        await new Promise((resolve) => r.server.close(() => resolve()));
+        receivers.delete(k);
+    }
+}
+//# sourceMappingURL=webhook.steps.js.map

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.2.1";
+export declare const VERSION = "0.2.2";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = '0.2.1';
+export const VERSION = '0.2.2';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdods/core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "SDODS runtime: configuration, project registry, fixtures, step libraries, data providers, screenshot narratives and self-healing locators.",
   "license": "Apache-2.0",
   "author": "SDODS <admin@sdods.com>",
@@ -42,14 +42,13 @@
     "playwright-bdd": ">=9"
   },
   "dependencies": {
-    "@sdods/contracts": "0.2.1",
+    "@sdods/contracts": "0.3.0",
     "@cucumber/gherkin": "^42.0.1",
     "@cucumber/messages": "^34.2.1",
     "@faker-js/faker": "^10.6.0",
     "@scalar/openapi-parser": "^0.29.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "chart.js": "^4.5.1",
     "csv-parse": "^7.0.2",
     "cucumber-tag-expressions": "^2.0.3",
     "dotenv": "^17.4.2",
@@ -59,7 +58,7 @@
     "ts-morph": "^28.0.0",
     "yaml": "^2.9.0",
     "zod": "^4.5.4",
-    "@sdods/db": "0.2.1"
+    "@sdods/db": "0.3.0"
   },
   "homepage": "https://sdods.com",
   "bugs": {