@objectstack/plugin-webhooks 17.0.0-rc.0 → 17.0.0-rc.2

package/src/translations/es-ES.objects.generated.ts

@@ -1,101 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * Auto-generated by 'os i18n extract' for locale 'es-ES'.
- * Edit translations in place; re-run extract (with --merge) to fill new gaps.
- * Do not hand-edit the structure — only the leaf string values.
- */
-
-import type { TranslationData } from '@objectstack/spec/system';
-
-export const esESObjects: NonNullable<TranslationData['objects']> = {
-  sys_webhook: {
-    label: "Webhook",
-    pluralLabel: "Webhooks",
-    description: "Suscripción saliente de Webhook HTTP. Se crea mediante defineWebhook() en código o con el editor de Studio; la ejecuta el plugin del conector HTTP.",
-    fields: {
-      id: {
-        label: "ID de webhook"
-      },
-      name: {
-        label: "Nombre",
-        help: "Nombre snake_case único; se usa en los registros y en la auditoría."
-      },
-      label: {
-        label: "Nombre visible"
-      },
-      object_name: {
-        label: "Objeto",
-        help: "Nombre corto del objeto cuyos eventos de registro (create/update/delete) activan este Webhook."
-      },
-      triggers: {
-        label: "Desencadenantes",
-        help: "Lista de eventos separada por comas: create,update,delete.",
-        options: {
-          create: "Crear",
-          update: "Actualizar",
-          delete: "Eliminar"
-        }
-      },
-      url: {
-        label: "URL de destino",
-        help: "Endpoint externo que recibe el POST."
-      },
-      method: {
-        label: "Método HTTP",
-        help: "GET / POST / PUT / PATCH / DELETE",
-        options: {
-          get: "GET",
-          post: "POST",
-          put: "PUT",
-          patch: "PATCH",
-          delete: "DELETE"
-        }
-      },
-      description: {
-        label: "Descripción"
-      },
-      active: {
-        label: "Activo",
-        help: "Los Webhooks inactivos se omiten en el despachador."
-      },
-      definition_json: {
-        label: "Definición",
-        help: "JSON serializado de Webhook (consulte @objectstack/spec/automation/webhook): configuración completa de cabeceras/auth/reintentos/payload."
-      },
-      managed_by: {
-        label: "Gestionado por",
-        help: "Procedencia del registro: platform = integrado en el framework / package = declarado por app o paquete (sembrado al arrancar desde los webhooks de defineStack) / admin = creado en Setup.",
-        options: {
-          platform: "Plataforma",
-          package: "Paquete",
-          admin: "Administrador"
-        }
-      },
-      customized: {
-        label: "Personalizado",
-        help: "Se establece cuando un administrador edita un webhook declarado por un paquete; a partir de entonces el sembrado de arranque deja de sobrescribir la fila (un webhook ruidoso desactivado sobrevive a los redespliegues). Sin sentido en filas admin."
-      },
-      created_at: {
-        label: "Creado el"
-      },
-      updated_at: {
-        label: "Actualizado el"
-      }
-    },
-    _views: {
-      active: {
-        label: "Activo"
-      },
-      inactive: {
-        label: "Inactivo"
-      },
-      by_object: {
-        label: "Por objeto"
-      },
-      all_webhooks: {
-        label: "Todos"
-      }
-    }
-  }
-};

package/src/translations/index.ts

@@ -1,23 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * WebhooksTranslations — i18n bundle owned by this plugin (ADR-0029 D8).
- *
- * Object label/field/view/action translations for the sys_* objects this
- * plugin owns. Loaded at runtime via the plugin's `kernel:ready` hook
- * (`i18n.loadTranslations`). Regenerate with `os i18n extract` against
- * `scripts/i18n-extract.config.ts`.
- */
-
-import type { TranslationBundle } from '@objectstack/spec/system';
-import { enObjects } from './en.objects.generated.js';
-import { zhCNObjects } from './zh-CN.objects.generated.js';
-import { jaJPObjects } from './ja-JP.objects.generated.js';
-import { esESObjects } from './es-ES.objects.generated.js';
-
-export const WebhooksTranslations: TranslationBundle = {
-  en: { objects: enObjects },
-  'zh-CN': { objects: zhCNObjects },
-  'ja-JP': { objects: jaJPObjects },
-  'es-ES': { objects: esESObjects },
-};

package/src/translations/ja-JP.objects.generated.ts

@@ -1,101 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * Auto-generated by 'os i18n extract' for locale 'ja-JP'.
- * Edit translations in place; re-run extract (with --merge) to fill new gaps.
- * Do not hand-edit the structure — only the leaf string values.
- */
-
-import type { TranslationData } from '@objectstack/spec/system';
-
-export const jaJPObjects: NonNullable<TranslationData['objects']> = {
-  sys_webhook: {
-    label: "Webhook",
-    pluralLabel: "Webhook",
-    description: "送信 HTTP Webhook サブスクリプション。defineWebhook() またはスタジオエディタで作成し、HTTP コネクタプラグインが実行します。",
-    fields: {
-      id: {
-        label: "Webhook ID"
-      },
-      name: {
-        label: "名前",
-        help: "一意の snake_case 名 — ログおよび監査で参照"
-      },
-      label: {
-        label: "表示名"
-      },
-      object_name: {
-        label: "オブジェクト",
-        help: "このウェブフックを発火するレコードイベント（create/update/delete）のオブジェクト短縮名"
-      },
-      triggers: {
-        label: "トリガー",
-        help: "カンマ区切りのイベントリスト: create,update,delete",
-        options: {
-          create: "作成",
-          update: "更新",
-          delete: "削除"
-        }
-      },
-      url: {
-        label: "ターゲット URL",
-        help: "POST を受信する外部エンドポイント"
-      },
-      method: {
-        label: "HTTP メソッド",
-        help: "GET / POST / PUT / PATCH / DELETE",
-        options: {
-          get: "GET",
-          post: "POST",
-          put: "PUT",
-          patch: "PATCH",
-          delete: "DELETE"
-        }
-      },
-      description: {
-        label: "説明"
-      },
-      active: {
-        label: "有効",
-        help: "無効にするとディスパッチャにスキップされます"
-      },
-      definition_json: {
-        label: "定義",
-        help: "シリアライズされた Webhook JSON（@objectstack/spec/automation/webhook 参照）— ヘッダー/認証/リトライ/ペイロード設定を含む"
-      },
-      managed_by: {
-        label: "管理元",
-        help: "レコードの出所: platform = フレームワーク組み込み / package = アプリ・パッケージ宣言（defineStack の webhooks から起動時シード）/ admin = Setup で作成。",
-        options: {
-          platform: "プラットフォーム",
-          package: "パッケージ",
-          admin: "管理者"
-        }
-      },
-      customized: {
-        label: "カスタマイズ済み",
-        help: "管理者がパッケージ宣言の webhook を編集すると設定されます。以後、起動時シードはこの行を上書きしません（無効化したノイジーな webhook は再デプロイ後も保持）。admin 行では意味を持ちません。"
-      },
-      created_at: {
-        label: "作成日時"
-      },
-      updated_at: {
-        label: "更新日時"
-      }
-    },
-    _views: {
-      active: {
-        label: "有効"
-      },
-      inactive: {
-        label: "無効"
-      },
-      by_object: {
-        label: "オブジェクト別"
-      },
-      all_webhooks: {
-        label: "すべて"
-      }
-    }
-  }
-};

package/src/translations/zh-CN.objects.generated.ts

@@ -1,101 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * Auto-generated by 'os i18n extract' for locale 'zh-CN'.
- * Edit translations in place; re-run extract (with --merge) to fill new gaps.
- * Do not hand-edit the structure — only the leaf string values.
- */
-
-import type { TranslationData } from '@objectstack/spec/system';
-
-export const zhCNObjects: NonNullable<TranslationData['objects']> = {
-  sys_webhook: {
-    label: "Webhook",
-    pluralLabel: "Webhook",
-    description: "外发 HTTP Webhook 订阅。可在代码中通过 defineWebhook() 编写，或在 Studio 编辑器中维护；由 HTTP 连接器插件执行。",
-    fields: {
-      id: {
-        label: "Webhook ID"
-      },
-      name: {
-        label: "名称",
-        help: "唯一的 snake_case 名称——用于日志和审计引用"
-      },
-      label: {
-        label: "显示标签"
-      },
-      object_name: {
-        label: "对象",
-        help: "触发该 Webhook 的记录事件（create/update/delete）的短对象名"
-      },
-      triggers: {
-        label: "触发器",
-        help: "以逗号分隔的事件列表：create,update,delete",
-        options: {
-          create: "创建",
-          update: "更新",
-          delete: "删除"
-        }
-      },
-      url: {
-        label: "目标 URL",
-        help: "接收 POST 请求的外部端点"
-      },
-      method: {
-        label: "HTTP 方法",
-        help: "GET / POST / PUT / PATCH / DELETE",
-        options: {
-          get: "GET",
-          post: "POST",
-          put: "PUT",
-          patch: "PATCH",
-          delete: "DELETE"
-        }
-      },
-      description: {
-        label: "描述"
-      },
-      active: {
-        label: "启用",
-        help: "停用的 Webhook 会被调度器跳过"
-      },
-      definition_json: {
-        label: "定义",
-        help: "序列化的 Webhook JSON（参见 @objectstack/spec/automation/webhook）——包含完整的 headers/auth/retry/payload 配置"
-      },
-      managed_by: {
-        label: "管理来源",
-        help: "记录来源：platform = 框架内置 / package = 应用包声明（由 defineStack 的 webhooks 在启动时种入）/ admin = 在 Setup 中创建。",
-        options: {
-          platform: "平台",
-          package: "包",
-          admin: "管理员"
-        }
-      },
-      customized: {
-        label: "已定制",
-        help: "当管理员编辑应用包声明的 webhook 时置位；此后启动种入不再覆盖该行（被停用的嘈杂 webhook 可跨重新部署保留）。对 admin 来源的记录无意义。"
-      },
-      created_at: {
-        label: "创建时间"
-      },
-      updated_at: {
-        label: "更新时间"
-      }
-    },
-    _views: {
-      active: {
-        label: "启用"
-      },
-      inactive: {
-        label: "停用"
-      },
-      by_object: {
-        label: "按对象"
-      },
-      all_webhooks: {
-        label: "全部"
-      }
-    }
-  }
-};

package/src/webhook-outbox-plugin.ts

@@ -1,305 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { Plugin, PluginContext } from '@objectstack/core';
-import type { IDataEngine, IRealtimeService } from '@objectstack/spec/contracts';
-import type { EnqueueHttpInput } from '@objectstack/service-messaging';
-import { AutoEnqueuer, type AutoEnqueuerOptions } from './auto-enqueuer.js';
-import { SysWebhook } from './sys-webhook.object.js';
-import { bootstrapDeclaredWebhooks } from './bootstrap-declared-webhooks.js';
-import { bindWebhookProvenanceStamp, unbindWebhookProvenanceStamp } from './webhook-provenance.js';
-
-/**
- * Structural view of `@objectstack/service-messaging`'s HTTP-outbox surface
- * (ADR-0018 M3) — declared locally so this plugin doesn't take a hard runtime
- * import on the service. Webhook deliveries are enqueued onto the shared
- * `sys_http_delivery` outbox and drained by the messaging `HttpDispatcher`.
- */
-interface MessagingHttpSurface {
-    isHttpDeliveryReady(): boolean;
-    enqueueHttp(input: EnqueueHttpInput): Promise<string>;
-    redeliverHttp(id: string): Promise<{ id: string; status: string }>;
-}
-
-export interface WebhookOutboxPluginOptions {
-    /**
-     * Auto-enqueue config. When enabled (default `true` if the realtime + data
-     * engine services are available), the plugin subscribes to `data.record.*`
-     * events and enqueues a delivery onto the shared messaging HTTP outbox for
-     * every matching `sys_webhook` row.
-     *
-     * Set `false` to disable and enqueue webhooks imperatively elsewhere.
-     */
-    autoEnqueue?: boolean | AutoEnqueuerOptions;
-}
-
-/**
- * Wires webhook fan-out on top of the shared outbound-HTTP delivery substrate
- * (ADR-0018 M3).
- *
- * Webhooks are no longer their own delivery engine: the durable outbox, the
- * cluster-coordinated dispatcher, the retry/backoff/dead-letter schedule, and
- * the retention sweep all live in `@objectstack/service-messaging`
- * (`sys_http_delivery` + `HttpDispatcher`). This plugin owns only the
- * webhook-specific concerns:
- *   - the `sys_webhook` configuration object,
- *   - the {@link AutoEnqueuer} that turns `data.record.*` events into outbox
- *     rows (`source: 'webhook'`), and
- *   - the redeliver admin endpoint.
- *
- * End-to-end flow:
- *
- *   engine.insert('contact', {...})
- *     → engine publishes data.record.created via IRealtimeService
- *     → AutoEnqueuer matches active sys_webhook rows in O(1)
- *     → messaging.enqueueHttp() runs fire-and-forget (off the write path)
- *     → messaging HttpDispatcher claims and POSTs (cluster-coordinated, retried)
- *
- * **Requires** `MessagingServicePlugin` (`@objectstack/service-messaging`),
- * which is a foundational, always-on capability.
- */
-export class WebhookOutboxPlugin implements Plugin {
-    name = 'com.objectstack.plugin-webhook-outbox';
-    version = '2.0.0';
-    type = 'standard' as const;
-    dependencies = ['com.objectstack.service.messaging'];
-
-    private autoEnqueuer: AutoEnqueuer | undefined;
-    /** Engine the provenance hook was bound to, so `dispose()` can unbind it. */
-    private boundEngine: any;
-
-    constructor(private readonly options: WebhookOutboxPluginOptions = {}) {}
-
-    async init(ctx: PluginContext): Promise<void> {
-        // Register the webhook config object (ADR-0029 K2.a). The delivery
-        // telemetry now lives in messaging's `sys_http_delivery`, so the nav's
-        // "Deliveries" entry points there (filtered to source=webhook in views).
-        const manifest = ctx.getService<{ register(m: any): void }>('manifest');
-        if (manifest && typeof manifest.register === 'function') {
-            manifest.register({
-                id: 'com.objectstack.plugin-webhook-outbox.schema',
-                namespace: 'sys',
-                version: this.version,
-                type: 'plugin',
-                scope: 'system',
-                name: 'Webhook Schemas',
-                description: 'Registers sys_webhook (configuration). Deliveries use messaging\'s sys_http_delivery outbox.',
-                objects: [SysWebhook],
-                navigationContributions: [
-                    {
-                        app: 'setup',
-                        group: 'group_integrations',
-                        priority: 100,
-                        items: [
-                            { id: 'nav_webhooks', type: 'object', label: 'Webhooks', objectName: 'sys_webhook', icon: 'webhook', requiresObject: 'sys_webhook' },
-                            { id: 'nav_http_deliveries', type: 'object', label: 'HTTP Deliveries', objectName: 'sys_http_delivery', icon: 'send', requiresObject: 'sys_http_delivery' },
-                        ],
-                    },
-                ],
-            });
-        } else {
-            ctx.logger.warn?.(
-                '[webhook-outbox] manifest service unavailable — sys_webhook will NOT appear in REST or Studio nav. Register MetadataService before WebhookOutboxPlugin.',
-            );
-        }
-
-        // ADR-0029 D8 — contribute object translations once i18n is up.
-        if (typeof (ctx as any).hook === 'function') {
-            (ctx as any).hook('kernel:ready', async () => {
-                try {
-                    const i18n = ctx.getService<any>('i18n');
-                    if (i18n && typeof i18n.loadTranslations === 'function') {
-                        const { WebhooksTranslations } = await import('./translations/index.js');
-                        for (const [locale, data] of Object.entries(WebhooksTranslations)) {
-                            i18n.loadTranslations(locale, data as Record<string, unknown>);
-                        }
-                    }
-                } catch { /* i18n optional */ }
-            });
-        }
-
-        const autoEnqueueOpt = this.options.autoEnqueue ?? true;
-
-        if (typeof (ctx as any).hook === 'function') {
-            (ctx as any).hook('kernel:ready', async () => {
-                // Materialize declared webhooks FIRST — this only needs the data
-                // engine, so it must not be gated behind the auto-enqueue
-                // dispatch prerequisites (realtime + messaging). Otherwise a
-                // deployment without realtime would silently fail to materialize
-                // declared webhooks — the very no-op this bridge closes (#3461).
-                await this.bootDeclaredWebhooks(ctx);
-                await this.bootAutoEnqueue(ctx, autoEnqueueOpt);
-                this.registerAdminRoutes(ctx);
-            });
-        }
-
-        ctx.logger.info?.('[webhook-outbox] initialised (delivery via shared messaging HTTP outbox)', {
-            autoEnqueue: autoEnqueueOpt !== false,
-        });
-    }
-
-    async dispose(): Promise<void> {
-        await this.autoEnqueuer?.stop();
-        if (this.boundEngine) {
-            try { unbindWebhookProvenanceStamp(this.boundEngine); } catch { /* best effort */ }
-            this.boundEngine = undefined;
-        }
-    }
-
-    private getMessaging(ctx: PluginContext): MessagingHttpSurface | undefined {
-        const svc = this.tryGetService<MessagingHttpSurface>(ctx, ['messaging']);
-        return svc && typeof svc.enqueueHttp === 'function' ? svc : undefined;
-    }
-
-    /**
-     * [#3461] Bridge the declarative authoring surface to the dispatcher:
-     * materialize stack/connector-declared `webhook` metadata into `sys_webhook`
-     * rows so the auto-enqueuer (and the Studio UI) can see them.
-     *
-     * Gated on the DATA ENGINE alone — deliberately independent of the
-     * auto-enqueue dispatch prerequisites (realtime + messaging). Materializing
-     * rows is a pure write; a deployment that mounts the webhook plugin without
-     * realtime must still get its declared webhooks into the table (and the
-     * Setup UI), even if nothing dispatches them yet. Runs before
-     * {@link bootAutoEnqueue} so the enqueuer's first cache refresh sees the rows.
-     */
-    private async bootDeclaredWebhooks(ctx: PluginContext): Promise<void> {
-        const engine = this.tryGetService<IDataEngine>(ctx, ['objectql', 'data']);
-        if (!engine) {
-            ctx.logger.warn?.('[webhook] declared-webhook bootstrap skipped — no data engine available');
-            return;
-        }
-        // Bind the provenance stamp so an admin edit freezes a seeded row.
-        this.boundEngine = engine;
-        bindWebhookProvenanceStamp(engine as any, ctx.logger as any);
-        let metadataService: any;
-        try { metadataService = ctx.getService('metadata'); } catch { /* optional */ }
-        try {
-            await bootstrapDeclaredWebhooks(engine, metadataService, ctx.logger as any);
-        } catch (err: any) {
-            ctx.logger.warn?.('[webhook] declared-webhook bootstrap failed (dispatcher still serves admin rows)', {
-                error: err?.message ?? String(err),
-            });
-        }
-    }
-
-    private async bootAutoEnqueue(
-        ctx: PluginContext,
-        opt: boolean | AutoEnqueuerOptions,
-    ): Promise<void> {
-        if (opt === false) return;
-        const engine = this.tryGetService<IDataEngine>(ctx, ['objectql', 'data']);
-        const realtime = this.tryGetService<IRealtimeService>(ctx, ['realtime']);
-        const messaging = this.getMessaging(ctx);
-        if (!engine || !realtime || !messaging) {
-            ctx.logger.warn?.(
-                '[webhook-auto-enqueuer] disabled — ObjectQL, Realtime, or Messaging service not available',
-                { hasEngine: !!engine, hasRealtime: !!realtime, hasMessaging: !!messaging },
-            );
-            return;
-        }
-        if (!messaging.isHttpDeliveryReady()) {
-            ctx.logger.warn?.(
-                '[webhook-auto-enqueuer] messaging HTTP outbox not ready (no data engine / reliableDelivery off) — webhook deliveries will not be durable',
-            );
-        }
-
-        const enqOpts = (typeof opt === 'object' ? opt : {}) as AutoEnqueuerOptions;
-        this.autoEnqueuer = new AutoEnqueuer(
-            engine,
-            realtime,
-            (input) => messaging.enqueueHttp(input),
-            { ...enqOpts, logger: ctx.logger },
-        );
-        await this.autoEnqueuer.start();
-        ctx.registerService('webhook.autoEnqueuer', this.autoEnqueuer);
-        ctx.logger.info?.('[webhook-auto-enqueuer] started (enqueues source=webhook onto sys_http_delivery)');
-    }
-
-    private tryGetService<T>(ctx: PluginContext, names: string[]): T | undefined {
-        for (const n of names) {
-            try {
-                const svc = ctx.getService<T>(n);
-                if (svc) return svc;
-            } catch {
-                // fall through
-            }
-        }
-        return undefined;
-    }
-
-    /**
-     * Mount POST /api/v1/webhooks/redeliver on the host Hono app, if one is
-     * available. Delegates to `messaging.redeliverHttp(deliveryId)`. Auth is 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 endpoint not mounted');
-            return;
-        }
-        const rawApp = http.getRawApp();
-        const messaging = this.getMessaging(ctx);
-        if (!rawApp || !messaging) return;
-
-        rawApp.post('/api/v1/webhooks/redeliver', async (c: any) => {
-            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 messaging.redeliverHttp(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');
-    }
-
-    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;
-        }
-    }
-}