@objectstack/plugin-webhooks 5.2.0 → 6.1.1

package/dist/sql-outbox.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/sql-outbox.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport { randomUUID } from 'node:crypto';\nimport type { IDataEngine } from '@objectstack/spec/contracts';\nimport type {\n    AckResult,\n    ClaimOptions,\n    DeliveryStatus,\n    EnqueueInput,\n    IWebhookOutbox,\n    WebhookDelivery,\n} from './outbox.js';\nimport { hashPartition } from './partition.js';\nimport { SYS_WEBHOOK_DELIVERY } from './schema.js';\n\nexport interface SqlWebhookOutboxOptions {\n    /**\n     * Total partition count — MUST match the dispatcher's `partitionCount`.\n     * Used at enqueue time to precompute `partition_key`.\n     */\n    partitionCount: number;\n    /**\n     * Object name to read/write. Defaults to `sys_webhook_delivery`. Override\n     * only if you've registered the schema under a different name.\n     */\n    objectName?: string;\n}\n\ninterface DeliveryRow {\n    id: string;\n    webhook_id: string;\n    event_id: string;\n    event_type: string;\n    url: string;\n    method?: string | null;\n    headers_json?: string | null;\n    secret?: string | null;\n    timeout_ms?: number | null;\n    payload_json: string;\n    partition_key: number;\n    status: DeliveryStatus;\n    attempts: number;\n    claimed_by?: string | null;\n    claimed_at?: number | null;\n    next_retry_at?: number | null;\n    last_attempted_at?: number | null;\n    response_code?: number | null;\n    response_body?: string | null;\n    error?: string | null;\n    created_at: number;\n    updated_at: number;\n}\n\n/**\n * Durable `IWebhookOutbox` backed by ObjectQL — the production storage\n * impl. Works against any registered driver (SQL, Turso, Mongo, in-memory)\n * because everything goes through the driver-agnostic `IDataEngine` API.\n *\n * **Why no `FOR UPDATE SKIP LOCKED`?** ObjectQL is driver-agnostic — that\n * SQL feature is Postgres-only. We get equivalent safety from two layers:\n *\n *   1. `cluster.lock` held per partition by the dispatcher (the primary\n *      mutex). One node owns one partition at a time → no two claimers.\n *   2. Atomic `UPDATE WHERE status='pending'` (the backup). Even if two\n *      claimers slip through (e.g. admin reschedule + dispatcher), only\n *      the first UPDATE matches each row.\n *\n * **Why precompute `partition_key` on enqueue?** ObjectQL has no\n * cross-driver `hash()` function in WHERE clauses. Storing the partition\n * as a column makes the claim query a plain indexed lookup.\n *\n * **Dedup race**: SELECT-then-INSERT has a tiny window where two\n * concurrent producers both miss the SELECT and both INSERT. The unique\n * index `(event_id, webhook_id)` on the table catches it — the second\n * INSERT errors, the producer ignores it. Receivers MUST be idempotent\n * on the `X-Objectstack-Delivery` header anyway.\n */\nexport class SqlWebhookOutbox implements IWebhookOutbox {\n    private readonly objectName: string;\n    private readonly partitionCount: number;\n\n    constructor(\n        private readonly engine: IDataEngine,\n        opts: SqlWebhookOutboxOptions,\n    ) {\n        if (opts.partitionCount <= 0) {\n            throw new Error('SqlWebhookOutbox: partitionCount must be > 0');\n        }\n        this.objectName = opts.objectName ?? SYS_WEBHOOK_DELIVERY;\n        this.partitionCount = opts.partitionCount;\n    }\n\n    async enqueue(input: EnqueueInput): Promise<string> {\n        // Cheap pre-check to absorb most duplicates without hitting the\n        // unique-index error path. Race window with the INSERT below is\n        // intentional and documented.\n        const existing = await this.engine.findOne(this.objectName, {\n            where: { event_id: input.eventId, webhook_id: input.webhookId },\n            fields: ['id'],\n        });\n        if (existing?.id) return existing.id as string;\n\n        const id = randomUUID();\n        const now = Date.now();\n        const row: Omit<DeliveryRow, 'response_body' | 'error'> = {\n            id,\n            webhook_id: input.webhookId,\n            event_id: input.eventId,\n            event_type: input.eventType,\n            url: input.url,\n            method: input.method ?? 'POST',\n            headers_json: input.headers ? JSON.stringify(input.headers) : undefined,\n            secret: input.secret,\n            timeout_ms: input.timeoutMs,\n            payload_json: JSON.stringify(input.payload ?? null),\n            partition_key: hashPartition(input.webhookId, this.partitionCount),\n            status: 'pending',\n            attempts: 0,\n            created_at: now,\n            updated_at: now,\n        };\n        try {\n            await this.engine.insert(this.objectName, row);\n            return id;\n        } catch (err) {\n            // Unique-index collision (dedup race) → look up the winner and\n            // return its id. Any other error propagates.\n            const winner = await this.engine.findOne(this.objectName, {\n                where: { event_id: input.eventId, webhook_id: input.webhookId },\n                fields: ['id'],\n            });\n            if (winner?.id) return winner.id as string;\n            throw err;\n        }\n    }\n\n    async claim(opts: ClaimOptions): Promise<WebhookDelivery[]> {\n        const now = opts.now ?? Date.now();\n\n        // 1. Reap stale in_flight rows — visibility-timeout recovery.\n        await this.engine.update(\n            this.objectName,\n            { status: 'pending', claimed_by: null, claimed_at: null, updated_at: now },\n            {\n                where: {\n                    status: 'in_flight',\n                    claimed_at: { $lt: now - opts.claimTtlMs },\n                },\n                multi: true,\n            },\n        );\n\n        // 2. Pick candidate ids.\n        const partitionFilter = opts.partition\n            ? { partition_key: opts.partition.index }\n            : {};\n        const candidates = await this.engine.find(this.objectName, {\n            where: {\n                status: 'pending',\n                ...partitionFilter,\n                // next_retry_at <= now OR null\n                $or: [\n                    { next_retry_at: null },\n                    { next_retry_at: { $lte: now } },\n                ],\n            },\n            fields: ['id'],\n            // No orderBy for portability — drivers handle the natural insert order.\n            limit: opts.limit,\n        });\n        if (candidates.length === 0) return [];\n\n        const ids = (candidates as Array<{ id: string }>).map((c) => c.id);\n\n        // 3. Atomic claim. WHERE status='pending' rejects any rows another\n        //    worker swept up between steps 2 and 3.\n        await this.engine.update(\n            this.objectName,\n            {\n                status: 'in_flight',\n                claimed_by: opts.nodeId,\n                claimed_at: now,\n                updated_at: now,\n            },\n            {\n                where: { id: { $in: ids }, status: 'pending' },\n                multi: true,\n            },\n        );\n\n        // 4. Read back the rows we actually own.\n        const claimed = (await this.engine.find(this.objectName, {\n            where: {\n                id: { $in: ids },\n                claimed_by: opts.nodeId,\n                claimed_at: now,\n                status: 'in_flight',\n            },\n        })) as DeliveryRow[];\n\n        return claimed.map((r) => this.toDelivery(r));\n    }\n\n    async ack(id: string, result: AckResult): Promise<void> {\n        // ObjectQL has no atomic $inc across drivers, so read-then-write.\n        // Safe enough: ack is single-writer per row (only the claimer acks).\n        const current = (await this.engine.findOne(this.objectName, {\n            where: { id },\n            fields: ['attempts'],\n        })) as { attempts?: number } | null;\n        if (!current) return;\n\n        const now = Date.now();\n        let status: DeliveryStatus;\n        let nextRetryAt: number | null;\n        let error: string | null;\n\n        if (result.success) {\n            status = 'success';\n            nextRetryAt = null;\n            error = null;\n        } else if (result.dead) {\n            status = 'dead';\n            nextRetryAt = null;\n            error = result.error ?? null;\n        } else {\n            status = 'pending';\n            nextRetryAt = result.nextRetryAt ?? null;\n            error = result.error ?? null;\n        }\n\n        await this.engine.update(\n            this.objectName,\n            {\n                status,\n                attempts: (current.attempts ?? 0) + 1,\n                last_attempted_at: now,\n                claimed_by: null,\n                claimed_at: null,\n                response_code: result.httpStatus ?? null,\n                response_body: result.responseBody ?? null,\n                next_retry_at: nextRetryAt,\n                error,\n                updated_at: now,\n            },\n            { where: { id }, multi: false },\n        );\n    }\n\n    async list(filter?: { status?: DeliveryStatus }): Promise<WebhookDelivery[]> {\n        const rows = (await this.engine.find(this.objectName, {\n            where: filter?.status ? { status: filter.status } : {},\n        })) as DeliveryRow[];\n        return rows.map((r) => this.toDelivery(r));\n    }\n\n    private toDelivery(r: DeliveryRow): WebhookDelivery {\n        return {\n            id: r.id,\n            webhookId: r.webhook_id,\n            eventId: r.event_id,\n            eventType: r.event_type,\n            url: r.url,\n            method: r.method ?? undefined,\n            headers: r.headers_json ? JSON.parse(r.headers_json) : undefined,\n            secret: r.secret ?? undefined,\n            timeoutMs: r.timeout_ms ?? undefined,\n            payload: JSON.parse(r.payload_json),\n            status: r.status,\n            attempts: r.attempts,\n            claimedBy: r.claimed_by ?? undefined,\n            claimedAt: r.claimed_at ?? undefined,\n            nextRetryAt: r.next_retry_at ?? undefined,\n            lastAttemptedAt: r.last_attempted_at ?? undefined,\n            responseCode: r.response_code ?? undefined,\n            responseBody: r.response_body ?? undefined,\n            error: r.error ?? undefined,\n            createdAt: r.created_at,\n            updatedAt: r.updated_at,\n        };\n    }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/plugin-webhooks",
-  "version": "5.2.0",
+  "version": "6.1.1",
   "license": "Apache-2.0",
   "description": "Persistent, cluster-aware webhook dispatcher. Durable outbox + per-partition cluster.lock for exactly-once-ish delivery across nodes. See content/docs/concepts/webhook-delivery.mdx.",
   "type": "module",
@@ -24,10 +24,10 @@
     }
   },
   "dependencies": {
-    "@objectstack/core": "5.2.0",
-    "@objectstack/platform-objects": "5.2.0",
-    "@objectstack/spec": "5.2.0",
-    "@objectstack/service-cluster": "5.1.1"
+    "@objectstack/core": "6.1.1",
+    "@objectstack/platform-objects": "6.1.1",
+    "@objectstack/spec": "6.1.1",
+    "@objectstack/service-cluster": "5.1.4"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",

package/src/index.ts

@@ -53,3 +53,4 @@ export type {
     IWebhookOutbox,
     WebhookDelivery,
 } from './outbox.js';
+export { RedeliverError } from './outbox.js';

package/src/memory-outbox.test.ts

@@ -0,0 +1,86 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * MemoryWebhookOutbox — focused tests for behaviours not already covered
+ * via `dispatcher.test.ts`. Today that's just `redeliver()` — the rest of
+ * the contract is exercised end-to-end through the dispatcher path.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { MemoryWebhookOutbox } from './memory-outbox.js';
+import type { EnqueueInput } from './outbox.js';
+
+function input(webhookId: string, eventId: string): EnqueueInput {
+    return {
+        webhookId,
+        eventId,
+        eventType: 'data.record.created',
+        url: 'https://example.test/hook',
+        payload: { hello: 'world' },
+    };
+}
+
+describe('MemoryWebhookOutbox.redeliver', () => {
+    it('resets a success row back to pending with attempts=0', async () => {
+        const outbox = new MemoryWebhookOutbox();
+        const id = await outbox.enqueue(input('wh-1', 'ev-1'));
+        await outbox.claim({ nodeId: 'A', limit: 10, claimTtlMs: 60_000 });
+        await outbox.ack(id, { success: true, httpStatus: 200, durationMs: 1 });
+
+        const row = await outbox.redeliver(id);
+        expect(row.status).toBe('pending');
+        expect(row.attempts).toBe(0);
+        expect(row.claimedBy).toBeUndefined();
+        expect(row.claimedAt).toBeUndefined();
+        expect(row.nextRetryAt).toBeUndefined();
+        expect(row.error).toBeUndefined();
+        expect(row.responseCode).toBeUndefined();
+        expect(row.responseBody).toBeUndefined();
+        expect(row.url).toBe('https://example.test/hook');
+        expect(row.payload).toEqual({ hello: 'world' });
+    });
+
+    it('resets a dead row and makes it claimable again', async () => {
+        const outbox = new MemoryWebhookOutbox();
+        const id = await outbox.enqueue(input('wh-1', 'ev-1'));
+        await outbox.claim({ nodeId: 'A', limit: 10, claimTtlMs: 60_000 });
+        await outbox.ack(id, {
+            success: false,
+            error: 'final',
+            dead: true,
+            durationMs: 5,
+        });
+
+        await outbox.redeliver(id);
+        const claimed = await outbox.claim({
+            nodeId: 'B',
+            limit: 10,
+            claimTtlMs: 60_000,
+        });
+        expect(claimed.map((r) => r.id)).toContain(id);
+    });
+
+    it('throws not_found when row does not exist', async () => {
+        const outbox = new MemoryWebhookOutbox();
+        await expect(outbox.redeliver('missing')).rejects.toMatchObject({
+            code: 'not_found',
+        });
+    });
+
+    it('throws not_eligible for pending rows', async () => {
+        const outbox = new MemoryWebhookOutbox();
+        const id = await outbox.enqueue(input('wh-1', 'ev-1'));
+        await expect(outbox.redeliver(id)).rejects.toMatchObject({
+            code: 'not_eligible',
+        });
+    });
+
+    it('throws not_eligible for in_flight rows', async () => {
+        const outbox = new MemoryWebhookOutbox();
+        const id = await outbox.enqueue(input('wh-1', 'ev-1'));
+        await outbox.claim({ nodeId: 'A', limit: 10, claimTtlMs: 60_000 });
+        await expect(outbox.redeliver(id)).rejects.toMatchObject({
+            code: 'not_eligible',
+        });
+    });
+});

package/src/memory-outbox.ts

@@ -9,6 +9,7 @@ import type {
     IWebhookOutbox,
     WebhookDelivery,
 } from './outbox.js';
+import { RedeliverError } from './outbox.js';
 import { hashPartition } from './partition.js';
 
 /**
@@ -124,4 +125,31 @@ export class MemoryWebhookOutbox implements IWebhookOutbox {
         const all = Array.from(this.rows.values()).map((r) => ({ ...r }));
         return filter?.status ? all.filter((r) => r.status === filter.status) : all;
     }
+
+    async redeliver(id: string): Promise<WebhookDelivery> {
+        const row = this.rows.get(id);
+        if (!row) {
+            throw new RedeliverError(
+                `Delivery row '${id}' not found`,
+                'not_found',
+            );
+        }
+        if (row.status !== 'success' && row.status !== 'failed' && row.status !== 'dead') {
+            throw new RedeliverError(
+                `Delivery row '${id}' is '${row.status}', expected one of: success, failed, dead`,
+                'not_eligible',
+            );
+        }
+        const now = Date.now();
+        row.status = 'pending';
+        row.attempts = 0;
+        row.claimedBy = undefined;
+        row.claimedAt = undefined;
+        row.nextRetryAt = undefined;
+        row.error = undefined;
+        row.responseCode = undefined;
+        row.responseBody = undefined;
+        row.updatedAt = now;
+        return { ...row };
+    }
 }

package/src/outbox.ts

@@ -113,6 +113,22 @@ export interface AckFailure {
 
 export type AckResult = AckSuccess | AckFailure;
 
+/**
+ * Error raised by `IWebhookOutbox.redeliver` when the requested row is
+ * either missing or in a non-terminal state. The dispatcher / admin UI
+ * surfaces this verbatim to the caller — never throw it for transient
+ * conditions (transport errors should bubble as native `Error`).
+ */
+export class RedeliverError extends Error {
+    constructor(
+        message: string,
+        readonly code: 'not_found' | 'not_eligible',
+    ) {
+        super(message);
+        this.name = 'RedeliverError';
+    }
+}
+
 /**
  * Pluggable storage backend for delivery rows. Implementations MUST make
  * `claim()` atomic across concurrent callers — that property is the
@@ -138,4 +154,22 @@ export interface IWebhookOutbox {
 
     /** Snapshot accessor for tests / admin tooling. */
     list(filter?: { status?: DeliveryStatus }): Promise<WebhookDelivery[]>;
+
+    /**
+     * Reset a terminal row back to `pending` so the dispatcher will pick
+     * it up again on its next tick.
+     *
+     * - Eligible source states: `success`, `failed`, `dead`.
+     * - Rejects `pending` / `in_flight` rows — replaying those would
+     *   double-deliver because they're either already queued or actively
+     *   being sent.
+     * - Resets `attempts=0` so the retry budget restarts.
+     * - Clears `claimed_by`, `claimed_at`, `next_retry_at`, `error`,
+     *   `response_code`, `response_body`. URL / payload / secret are NOT
+     *   touched — replay reproduces the original POST byte-for-byte.
+     *
+     * Throws `RedeliverError` with code `not_found` or `not_eligible`.
+     * Returns the post-reset row.
+     */
+    redeliver(id: string): Promise<WebhookDelivery>;
 }

package/src/sql-outbox.test.ts

@@ -407,4 +407,84 @@ describe('SqlWebhookOutbox', () => {
         const inFlight = await outbox.list({ status: 'in_flight' });
         expect(inFlight).toHaveLength(1);
     });
+
+    describe('redeliver', () => {
+        it('resets a success row back to pending with attempts=0', async () => {
+            const { outbox } = newOutbox();
+            const id = await outbox.enqueue(input('wh-1', 'ev-1'));
+            await outbox.claim({ nodeId: 'A', limit: 10, claimTtlMs: 60_000 });
+            await outbox.ack(id, { success: true, httpStatus: 200, durationMs: 5 });
+
+            const row = await outbox.redeliver(id);
+            expect(row.status).toBe('pending');
+            expect(row.attempts).toBe(0);
+            expect(row.claimedBy).toBeUndefined();
+            expect(row.claimedAt).toBeUndefined();
+            expect(row.nextRetryAt).toBeUndefined();
+            expect(row.error).toBeUndefined();
+            expect(row.responseCode).toBeUndefined();
+            expect(row.responseBody).toBeUndefined();
+            // Original immutable fields preserved
+            expect(row.url).toBe('https://example.test/hook');
+            expect(row.payload).toEqual({ hello: 'world' });
+        });
+
+        it('resets a dead row back to pending and clears retry backoff', async () => {
+            const { outbox } = newOutbox();
+            const id = await outbox.enqueue(input('wh-1', 'ev-1'));
+            await outbox.claim({ nodeId: 'A', limit: 10, claimTtlMs: 60_000 });
+            await outbox.ack(id, {
+                success: false,
+                error: 'final',
+                dead: true,
+                durationMs: 5,
+            });
+
+            const row = await outbox.redeliver(id);
+            expect(row.status).toBe('pending');
+            expect(row.attempts).toBe(0);
+            expect(row.error).toBeUndefined();
+            expect(row.nextRetryAt).toBeUndefined();
+        });
+
+        it('throws not_found when row does not exist', async () => {
+            const { outbox } = newOutbox();
+            await expect(outbox.redeliver('missing')).rejects.toMatchObject({
+                code: 'not_found',
+            });
+        });
+
+        it('throws not_eligible for pending rows', async () => {
+            const { outbox } = newOutbox();
+            const id = await outbox.enqueue(input('wh-1', 'ev-1'));
+            await expect(outbox.redeliver(id)).rejects.toMatchObject({
+                code: 'not_eligible',
+            });
+        });
+
+        it('throws not_eligible for in_flight rows', async () => {
+            const { outbox } = newOutbox();
+            const id = await outbox.enqueue(input('wh-1', 'ev-1'));
+            await outbox.claim({ nodeId: 'A', limit: 10, claimTtlMs: 60_000 });
+            await expect(outbox.redeliver(id)).rejects.toMatchObject({
+                code: 'not_eligible',
+            });
+        });
+
+        it('redelivered row is immediately claimable again', async () => {
+            const { outbox } = newOutbox();
+            const id = await outbox.enqueue(input('wh-1', 'ev-1'));
+            await outbox.claim({ nodeId: 'A', limit: 10, claimTtlMs: 60_000 });
+            await outbox.ack(id, { success: true, httpStatus: 200, durationMs: 1 });
+
+            await outbox.redeliver(id);
+
+            const claimed = await outbox.claim({
+                nodeId: 'B',
+                limit: 10,
+                claimTtlMs: 60_000,
+            });
+            expect(claimed.map((r) => r.id)).toContain(id);
+        });
+    });
 });

package/src/sql-outbox.ts

@@ -10,6 +10,7 @@ import type {
     IWebhookOutbox,
     WebhookDelivery,
 } from './outbox.js';
+import { RedeliverError } from './outbox.js';
 import { hashPartition } from './partition.js';
 import { SYS_WEBHOOK_DELIVERY } from './schema.js';
 
@@ -254,6 +255,66 @@ export class SqlWebhookOutbox implements IWebhookOutbox {
         return rows.map((r) => this.toDelivery(r));
     }
 
+    async redeliver(id: string): Promise<WebhookDelivery> {
+        const current = (await this.engine.findOne(this.objectName, {
+            where: { id },
+        })) as DeliveryRow | null;
+        if (!current) {
+            throw new RedeliverError(
+                `Delivery row '${id}' not found`,
+                'not_found',
+            );
+        }
+        if (
+            current.status !== 'success' &&
+            current.status !== 'failed' &&
+            current.status !== 'dead'
+        ) {
+            throw new RedeliverError(
+                `Delivery row '${id}' is '${current.status}', expected one of: success, failed, dead`,
+                'not_eligible',
+            );
+        }
+        const now = Date.now();
+        // Guarded UPDATE — re-check status server-side so two concurrent
+        // redeliver calls cannot both flip the row, and so a dispatcher
+        // tick that flipped the row to in_flight between our SELECT and
+        // UPDATE cannot be clobbered.
+        await this.engine.update(
+            this.objectName,
+            {
+                status: 'pending',
+                attempts: 0,
+                claimed_by: null,
+                claimed_at: null,
+                next_retry_at: null,
+                last_attempted_at: null,
+                response_code: null,
+                response_body: null,
+                error: null,
+                updated_at: now,
+            },
+            {
+                where: {
+                    id,
+                    status: { $in: ['success', 'failed', 'dead'] },
+                },
+                multi: false,
+            },
+        );
+        const after = (await this.engine.findOne(this.objectName, {
+            where: { id },
+        })) as DeliveryRow | null;
+        if (!after || after.status !== 'pending') {
+            // Lost the race — another writer flipped the row.
+            throw new RedeliverError(
+                `Delivery row '${id}' state changed during redeliver`,
+                'not_eligible',
+            );
+        }
+        return this.toDelivery(after);
+    }
+
     private toDelivery(r: DeliveryRow): WebhookDelivery {
         return {
             id: r.id,

package/src/sys-webhook-delivery.object.ts

@@ -42,6 +42,28 @@ export const SysWebhookDelivery = ObjectSchema.create({
     titleFormat: '{event_type} → {url}',
     compactLayout: ['event_type', 'url', 'status', 'attempts', 'next_retry_at'],
 
+    actions: [
+        {
+            name: 'redeliver',
+            label: 'Redeliver',
+            icon: 'refresh-cw',
+            variant: 'secondary',
+            locations: ['list_item', 'record_header'],
+            type: 'api',
+            target: '/api/v1/webhooks/redeliver',
+            method: 'POST',
+            recordIdParam: 'deliveryId',
+            confirmText:
+                'Replay this delivery? The receiver will get the original payload again — they must be idempotent on the X-Objectstack-Delivery header.',
+            successMessage: 'Queued for redelivery',
+            refreshAfter: true,
+            // Only terminal rows are safe to replay. Pending / in_flight rows
+            // are either already queued or actively being sent — replaying
+            // would double-deliver.
+            disabled: "!(status in ['success', 'failed', 'dead'])",
+        },
+    ],
+
     listViews: {
         recent: {
             type: 'grid',

package/src/webhook-outbox-plugin.ts

@@ -15,6 +15,7 @@ import {
     DeliveryRetentionSweeper,
     type DeliveryRetentionOptions,
 } from './retention.js';
+import { SqlWebhookOutbox } from './sql-outbox.js';
 import { SysWebhookDelivery } from './sys-webhook-delivery.object.js';
 
 export interface WebhookOutboxPluginOptions
@@ -171,11 +172,13 @@ export class WebhookOutboxPlugin implements Plugin {
         }
 
         // Loud warning when running with the in-memory outbox in production —
-        // it loses data on restart and never shares rows across nodes.
+        // it loses data on restart and never shares rows across nodes. With
+        // the auto-pick logic above this only fires when no IDataEngine is
+        // available, but flag it loudly anyway.
         const usingMemoryOutbox = outbox instanceof MemoryWebhookOutbox;
         if (usingMemoryOutbox && process.env.NODE_ENV === 'production') {
             ctx.logger.warn?.(
-                '[webhook-outbox] MemoryWebhookOutbox in production — webhook deliveries WILL be lost on process exit. Pass `outbox: (ctx) => new SqlWebhookOutbox(ctx.getService("objectql"), { partitionCount: 8 })` from `@objectstack/plugin-webhooks/sql`.',
+                '[webhook-outbox] MemoryWebhookOutbox in production — webhook deliveries WILL be lost on process exit. Ensure ObjectQL is registered before WebhookOutboxPlugin so the SQL outbox can auto-select.',
             );
         }
 
@@ -192,6 +195,20 @@ export class WebhookOutboxPlugin implements Plugin {
             });
         }
 
+        // Admin REST endpoint — POST /api/v1/webhooks/redeliver { deliveryId }.
+        // Wired in `kernel:ready` so the auth + http services are guaranteed
+        // resolvable. Gated on a session cookie so anonymous callers cannot
+        // replay deliveries; finer-grained RBAC (e.g. "only admins") can be
+        // layered on later — for now any signed-in user with access to the
+        // Setup app can redeliver. The action is also `disabled`-gated by
+        // status on the Studio side so the button only lights up on
+        // success / failed / dead rows.
+        if (typeof (ctx as any).hook === 'function') {
+            (ctx as any).hook('kernel:ready', () => {
+                this.registerAdminRoutes(ctx);
+            });
+        }
+
         ctx.logger.info?.('[webhook-outbox] initialised', {
             nodeId,
             partitions: this.options.partitionCount ?? 8,
@@ -209,9 +226,32 @@ export class WebhookOutboxPlugin implements Plugin {
 
     private resolveOutbox(ctx: PluginContext): IWebhookOutbox {
         const opt = this.options.outbox;
-        if (!opt) return new MemoryWebhookOutbox();
-        if (typeof opt === 'function') return (opt as (c: PluginContext) => IWebhookOutbox)(ctx);
-        return opt;
+        if (opt) {
+            return typeof opt === 'function'
+                ? (opt as (c: PluginContext) => IWebhookOutbox)(ctx)
+                : opt;
+        }
+        // No explicit override — auto-pick the right backend for the host.
+        // SqlWebhookOutbox needs an `IDataEngine`; if one is resolvable
+        // (the usual case in CLI-served stacks), use it so durable rows
+        // in `sys_webhook_delivery` actually round-trip through the
+        // dispatcher and the redeliver REST endpoint. Memory is only a
+        // last-resort fallback for tests / edge environments without an
+        // engine.
+        const engine = this.tryGetService<IDataEngine>(ctx, ['objectql', 'data']);
+        if (engine) {
+            const partitionCount = this.options.partitionCount ?? 8;
+            const sql = new SqlWebhookOutbox(engine, { partitionCount });
+            ctx.logger.info?.(
+                '[webhook-outbox] auto-selected SqlWebhookOutbox (objectql engine detected)',
+                { partitionCount },
+            );
+            return sql;
+        }
+        ctx.logger.warn?.(
+            '[webhook-outbox] no IDataEngine available — falling back to MemoryWebhookOutbox. Deliveries will NOT survive process restart and the redeliver REST endpoint will not see rows written through ObjectQL.',
+        );
+        return new MemoryWebhookOutbox();
     }
 
     private async bootAutoEnqueue(
@@ -277,4 +317,126 @@ export class WebhookOutboxPlugin implements Plugin {
         }
         return undefined;
     }
+
+    /**
+     * Mount POST /api/v1/webhooks/redeliver on the host Hono app, if one
+     * is available. Silently no-ops in environments without an HTTP
+     * server (MSW, edge tests, pure library use). Auth is delegated to
+     * the better-auth session cookie — every authenticated user counts.
+     */
+    private registerAdminRoutes(ctx: PluginContext): void {
+        const http = this.tryGetService<any>(ctx, ['http-server']);
+        if (!http || typeof http.getRawApp !== 'function') {
+            ctx.logger.debug?.(
+                '[webhook-outbox] HTTP server not available; redeliver REST endpoint not mounted',
+            );
+            return;
+        }
+        const rawApp = http.getRawApp();
+        const outbox = this.outboxInstance;
+        if (!rawApp || !outbox) return;
+
+        rawApp.post('/api/v1/webhooks/redeliver', async (c: any) => {
+            // Auth gate — require a signed-in session.
+            const userId = await this.resolveSessionUserId(ctx, c);
+            if (!userId) {
+                return c.json(
+                    {
+                        success: false,
+                        error: 'unauthenticated',
+                        message: 'Sign in to redeliver webhook deliveries.',
+                    },
+                    401,
+                );
+            }
+            let body: any;
+            try {
+                body = await c.req.json();
+            } catch {
+                return c.json(
+                    {
+                        success: false,
+                        error: 'invalid_body',
+                        message: 'Request body must be JSON.',
+                    },
+                    400,
+                );
+            }
+            const deliveryId =
+                typeof body?.deliveryId === 'string' ? body.deliveryId.trim() : '';
+            if (!deliveryId) {
+                return c.json(
+                    {
+                        success: false,
+                        error: 'missing_delivery_id',
+                        message: 'Body must include `deliveryId: string`.',
+                    },
+                    400,
+                );
+            }
+            try {
+                const row = await outbox.redeliver(deliveryId);
+                ctx.logger.info?.('[webhook-outbox] redelivered', {
+                    deliveryId,
+                    requestedBy: userId,
+                });
+                return c.json({ success: true, data: { id: row.id, status: row.status } });
+            } catch (err: any) {
+                const code = err?.code;
+                if (code === 'not_found') {
+                    return c.json(
+                        { success: false, error: 'not_found', message: err.message },
+                        404,
+                    );
+                }
+                if (code === 'not_eligible') {
+                    return c.json(
+                        { success: false, error: 'not_eligible', message: err.message },
+                        409,
+                    );
+                }
+                ctx.logger.error?.(
+                    '[webhook-outbox] redeliver failed',
+                    err as Error,
+                );
+                return c.json(
+                    {
+                        success: false,
+                        error: 'internal_error',
+                        message: err?.message ?? String(err),
+                    },
+                    500,
+                );
+            }
+        });
+
+        ctx.logger.info?.(
+            '[webhook-outbox] redeliver endpoint mounted at POST /api/v1/webhooks/redeliver',
+        );
+    }
+
+    /**
+     * Resolve the requesting user's id from a better-auth session cookie.
+     * Returns `undefined` for anonymous callers — the caller decides
+     * whether that's a 401.
+     */
+    private async resolveSessionUserId(
+        ctx: PluginContext,
+        c: any,
+    ): Promise<string | undefined> {
+        try {
+            const authService: any = this.tryGetService<any>(ctx, ['auth']);
+            if (!authService) return undefined;
+            let api: any = authService.api;
+            if (!api && typeof authService.getApi === 'function') {
+                api = await authService.getApi();
+            }
+            if (!api?.getSession) return undefined;
+            const session = await api.getSession({ headers: c.req.raw.headers });
+            const uid = session?.user?.id;
+            return typeof uid === 'string' && uid.length > 0 ? uid : undefined;
+        } catch {
+            return undefined;
+        }
+    }
 }