@gerbaudo/sdk-node 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import type { EndpointRegistration, InterceptPayload } from './types.js';
+export declare class GerbaudoClient {
+    private daemonUrl;
+    private batchQueue;
+    private batchInterval;
+    private batchSize;
+    private timer;
+    private registered;
+    private flushing;
+    constructor(opts?: {
+        daemonUrl?: string;
+        batchInterval?: number;
+        batchSize?: number;
+    });
+    start(): void;
+    stop(): void;
+    registerEndpoint(endpoint: EndpointRegistration): Promise<void>;
+    recordIntercept(payload: InterceptPayload): void;
+    private flush;
+}

package/dist/client.js

@@ -0,0 +1,63 @@
+const DEFAULT_DAEMON_URL = 'http://127.0.0.1:9876';
+export class GerbaudoClient {
+    daemonUrl;
+    batchQueue = [];
+    batchInterval;
+    batchSize;
+    timer = null;
+    registered = new Set();
+    flushing = false;
+    constructor(opts) {
+        this.daemonUrl = opts?.daemonUrl ?? DEFAULT_DAEMON_URL;
+        this.batchInterval = opts?.batchInterval ?? 2000;
+        this.batchSize = opts?.batchSize ?? 50;
+    }
+    start() {
+        this.timer = setInterval(() => this.flush(), this.batchInterval);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.flush();
+    }
+    async registerEndpoint(endpoint) {
+        const key = `${endpoint.method}:${endpoint.path}`;
+        if (this.registered.has(key))
+            return;
+        try {
+            await fetch(`${this.daemonUrl}/api/catalog/register`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(endpoint),
+            });
+            this.registered.add(key);
+        }
+        catch {
+            // daemon might not be running yet
+        }
+    }
+    recordIntercept(payload) {
+        this.batchQueue.push(payload);
+        if (this.batchQueue.length >= this.batchSize) {
+            this.flush();
+        }
+    }
+    flush() {
+        if (this.flushing || this.batchQueue.length === 0)
+            return;
+        this.flushing = true;
+        const batch = this.batchQueue.splice(0, this.batchSize);
+        fetch(`${this.daemonUrl}/api/intercept/record`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(batch.length === 1 ? batch[0] : batch),
+        }).catch(() => {
+            // re-queue on failure
+            this.batchQueue.unshift(...batch);
+        }).finally(() => {
+            this.flushing = false;
+        });
+    }
+}

package/dist/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/client.test.js

@@ -0,0 +1,87 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { GerbaudoClient } from './client.js';
+describe('GerbaudoClient', () => {
+    let client;
+    let fetchMock;
+    beforeEach(() => {
+        fetchMock = vi.fn();
+        fetchMock.mockResolvedValue(new Response(null, { status: 200 }));
+        vi.stubGlobal('fetch', fetchMock);
+        vi.useFakeTimers();
+        client = new GerbaudoClient({ daemonUrl: 'http://127.0.0.1:9999', batchInterval: 5000, batchSize: 10 });
+    });
+    afterEach(() => {
+        client.stop();
+        vi.restoreAllMocks();
+        vi.useRealTimers();
+    });
+    describe('start / stop', () => {
+        it('starts a timer that flushes on interval', () => {
+            client.start();
+            expect(fetchMock).not.toHaveBeenCalled();
+            vi.advanceTimersByTime(5000);
+            expect(fetchMock).not.toHaveBeenCalled(); // nothing to flush
+        });
+        it('flushes remaining items on stop', () => {
+            client.start();
+            client.recordIntercept({
+                endpointId: 'ep1', method: 'GET', path: '/api/test', status: 200, durationMs: 10,
+            });
+            client.stop();
+            expect(fetchMock).toHaveBeenCalledTimes(1);
+        });
+    });
+    describe('registerEndpoint', () => {
+        it('POSTs to daemon and deduplicates', async () => {
+            await client.registerEndpoint({ method: 'GET', path: '/api/users' });
+            expect(fetchMock).toHaveBeenCalledTimes(1);
+            await client.registerEndpoint({ method: 'GET', path: '/api/users' });
+            expect(fetchMock).toHaveBeenCalledTimes(1); // dedup
+        });
+        it('does not throw when daemon is unreachable', async () => {
+            fetchMock.mockRejectedValue(new Error('ECONNREFUSED'));
+            await expect(client.registerEndpoint({ method: 'GET', path: '/api/test' })).resolves.toBeUndefined();
+        });
+    });
+    describe('recordIntercept', () => {
+        it('queues items and flushes when batch size is reached', () => {
+            client.start();
+            for (let i = 0; i < 10; i++) {
+                client.recordIntercept({
+                    endpointId: `ep${i}`, method: 'GET', path: '/api/test', status: 200, durationMs: i,
+                });
+            }
+            expect(fetchMock).toHaveBeenCalledTimes(1);
+            const callBody = JSON.parse(fetchMock.mock.calls[0][1].body);
+            expect(Array.isArray(callBody)).toBe(true);
+            expect(callBody).toHaveLength(10);
+        });
+        it('does not flush concurrently when a flush is in flight', () => {
+            fetchMock.mockImplementation(() => new Promise(() => { })); // never resolves
+            client.start();
+            for (let i = 0; i < 20; i++) {
+                client.recordIntercept({
+                    endpointId: `ep${i}`, method: 'GET', path: '/api/test', status: 200, durationMs: i,
+                });
+            }
+            // Only one flush should have been triggered (first batch of 10)
+            expect(fetchMock).toHaveBeenCalledTimes(1);
+        });
+        it('re-queues batch on failure', async () => {
+            fetchMock.mockRejectedValueOnce(new Error('fail'));
+            fetchMock.mockResolvedValue(new Response(null, { status: 200 }));
+            client.start();
+            for (let i = 0; i < 10; i++) {
+                client.recordIntercept({
+                    endpointId: `ep${i}`, method: 'GET', path: '/api/test', status: 200, durationMs: i,
+                });
+            }
+            expect(fetchMock).toHaveBeenCalledTimes(1);
+            // After the failed fetch, items should be re-queued
+            // Wait for the next timer tick
+            await vi.advanceTimersByTimeAsync(5000);
+            // The timer flush should try again
+            expect(fetchMock).toHaveBeenCalledTimes(2);
+        });
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { GerbaudoOptions } from './types.js';
+export declare function gerbaudo(opts?: GerbaudoOptions): {
+    (req: import("express").Request, res: import("express").Response, next: import("express").NextFunction): void;
+    discover: (app: {
+        _router?: {
+            stack: unknown[];
+        };
+    }) => void;
+};

package/dist/index.js

@@ -0,0 +1,4 @@
+import { createMiddleware } from './middleware.js';
+export function gerbaudo(opts) {
+    return createMiddleware(opts);
+}

package/dist/middleware.d.ts

@@ -0,0 +1,10 @@
+import type { Request, Response, NextFunction } from 'express';
+import type { GerbaudoOptions } from './types.js';
+export declare function createMiddleware(opts?: GerbaudoOptions): {
+    (req: Request, res: Response, next: NextFunction): void;
+    discover: (app: {
+        _router?: {
+            stack: unknown[];
+        };
+    }) => void;
+};

package/dist/middleware.js

@@ -0,0 +1,82 @@
+import { GerbaudoClient } from './client.js';
+function extractRoutePath(req) {
+    return req.route?.path ?? req.path;
+}
+function getEndpointId(client, method, path) {
+    return `${method}:${path}`;
+}
+export function createMiddleware(opts) {
+    const client = new GerbaudoClient({
+        daemonUrl: opts?.daemonUrl,
+        batchInterval: opts?.batchInterval,
+        batchSize: opts?.batchSize,
+    });
+    client.start();
+    if (opts?.app) {
+        discoverRoutes(opts.app);
+    }
+    function discoverRoutes(app) {
+        if (!app._router?.stack)
+            return;
+        for (const layer of app._router.stack) {
+            if (layer.route) {
+                const route = layer.route;
+                const methods = Object.keys(route.methods);
+                for (const method of methods) {
+                    client.registerEndpoint({
+                        method: method.toUpperCase(),
+                        path: route.path,
+                    });
+                }
+            }
+        }
+    }
+    function safeStringify(val) {
+        try {
+            return JSON.stringify(val);
+        }
+        catch {
+            return String(val);
+        }
+    }
+    function middleware(req, res, next) {
+        const start = performance.now();
+        let responseBody = null;
+        const _json = res.json.bind(res);
+        const _send = res.send.bind(res);
+        const _end = res.end.bind(res);
+        res.json = function (body, ...args) {
+            responseBody = body;
+            return _json(body, ...args);
+        };
+        res.send = function (body, ...args) {
+            responseBody = body ?? responseBody;
+            return _send(body, ...args);
+        };
+        res.end = function (chunk, ...args) {
+            try {
+                const durationMs = Math.round(performance.now() - start);
+                const path = extractRoutePath(req);
+                const endpointId = getEndpointId(client, req.method, path);
+                client.recordIntercept({
+                    endpointId,
+                    method: req.method.toUpperCase(),
+                    path,
+                    status: res.statusCode,
+                    requestHeaders: safeStringify(req.headers),
+                    requestBody: safeStringify(req.body),
+                    responseHeaders: safeStringify(res.getHeaders()),
+                    responseBody: typeof responseBody === 'string' ? responseBody : safeStringify(responseBody),
+                    durationMs,
+                });
+            }
+            catch {
+                // never crash the backend because of instrumentation
+            }
+            return _end(chunk, ...args);
+        };
+        next();
+    }
+    middleware.discover = discoverRoutes;
+    return middleware;
+}

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+export interface EndpointRegistration {
+    method: string;
+    path: string;
+    params?: string;
+    bodySchema?: string;
+    responseSchema?: string;
+}
+export interface InterceptPayload {
+    endpointId: string;
+    method: string;
+    path: string;
+    status: number;
+    requestHeaders?: string;
+    requestBody?: string;
+    responseHeaders?: string;
+    responseBody?: string;
+    durationMs: number;
+}
+export interface GerbaudoOptions {
+    daemonUrl?: string;
+    batchInterval?: number;
+    batchSize?: number;
+    app?: {
+        _router?: {
+            stack: unknown[];
+        };
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@gerbaudo/sdk-node",
+  "version": "0.1.0",
+  "description": "Express middleware for Gerbaudo API instrumentation",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.9"
+  },
+  "license": "MIT"
+}