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

package/src/bootstrap-declared-webhooks.ts

@@ -1,205 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * bootstrapDeclaredWebhooks — materialize stack/connector-declared `webhooks`
- * into `sys_webhook` rows so the dispatcher can actually see them (closes #3461).
- *
- * ## The disconnect this closes
- * The spec authoring surface (`WebhookSchema` — `defineStack({ webhooks })`,
- * `@objectstack/spec/automation/webhook`) declares `object` / `isActive`, and
- * is generically decomposed into the ObjectQL registry at boot as metadata
- * type `webhook`. But the runtime dispatcher ({@link AutoEnqueuer}) reads
- * `sys_webhook` DATA rows (`object_name` / `active`), which until now were only
- * ever written by hand through the object's CRUD UI. Nothing bridged the two —
- * so authoring `webhooks:` on a stack produced metadata artifacts that never
- * became dispatchable rows (a silent no-op; ADR-0078). This seeder is that
- * missing ingestion path.
- *
- * ## Shape translation (authoring → runtime row)
- * The spec shape diverges from the runtime column names; we map only at this
- * boundary and stash the full validated envelope in `definition_json` (whence
- * the enqueuer reads headers / secret / timeout):
- *   - `object`     → `object_name`
- *   - `isActive`   → `active`
- *   - `triggers` / `url` / `method` / `label` / `description` → same-named columns
- *   - the entire parsed {@link Webhook} → `definition_json` (JSON string)
- *
- * Each item is validated through `WebhookSchema.parse()` first — this gives the
- * spec schema a real consumer (defaults for `method`/`isActive`/`timeoutMs` get
- * applied) and rejects malformed authoring with a warning instead of crashing
- * boot.
- *
- * ## Seed-not-clobber (mirrors sys_sharing_rule, #2909)
- * `sys_webhook` is admin-editable (`managedBy: 'config'`). Declared webhooks
- * ship with the app/package, so they seed with `managed_by: 'package'`
- * provenance and re-seed on every boot — but a row an admin has created
- * (`managed_by: 'admin'`) or edited (`customized: true`, stamped by
- * {@link bindWebhookProvenanceStamp}) is never overwritten. Most importantly,
- * an admin's `active: false` on a noisy webhook survives redeploys.
- *
- * MUST run before {@link AutoEnqueuer.start} so the enqueuer's first cache
- * refresh already sees the declared rows.
- */
-
-import type { IDataEngine } from '@objectstack/spec/contracts';
-import { WebhookSchema, type Webhook } from '@objectstack/spec/automation';
-
-/** System write context — the boot seeder is not an admin authoring action. */
-const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;
-
-interface Logger {
-  info?: (msg: string, meta?: unknown) => void;
-  warn?: (msg: string, meta?: unknown) => void;
-}
-
-/** Random id with a stable prefix — mirrors the sharing-rule seeder. */
-function uid(prefix: string): string {
-  const g: any = globalThis as any;
-  if (g.crypto?.randomUUID) return `${prefix}_${g.crypto.randomUUID()}`;
-  return `${prefix}_${Math.random().toString(36).slice(2, 10)}`;
-}
-
-/**
- * Read declared `webhook` items from the ObjectQL registry (where the manifest
- * decomposition parks `stack.webhooks`), falling back to the metadata service.
- * Items may be wrapped as `{ content }` — unwrap to the raw authoring object.
- */
-function readDeclared(engine: any, metadataService: any, type: string): any[] {
-  try {
-    const reg = engine?._registry;
-    if (reg?.listItems) {
-      const items = (reg.listItems(type) ?? []).map((i: any) => i?.content ?? i).filter(Boolean);
-      if (items.length > 0) return items;
-    }
-  } catch {
-    /* fall through to metadata service */
-  }
-  try {
-    const listed = metadataService?.list?.(type);
-    const arr = typeof (listed as any)?.then === 'function' ? [] : (listed ?? []);
-    return Array.isArray(arr) ? arr.map((i: any) => i?.content ?? i).filter(Boolean) : [];
-  } catch {
-    return [];
-  }
-}
-
-export interface BootstrapDeclaredWebhooksResult {
-  seeded: number;
-  skipped: number;
-}
-
-/**
- * Materialize declared webhooks into `sys_webhook`. Idempotent and safe to run
- * on every boot.
- */
-export async function bootstrapDeclaredWebhooks(
-  engine: IDataEngine,
-  metadataService: any,
-  logger?: Logger,
-  subscriptionsObject = 'sys_webhook',
-): Promise<BootstrapDeclaredWebhooksResult> {
-  const declared = readDeclared(engine, metadataService, 'webhook');
-  if (declared.length === 0) return { seeded: 0, skipped: 0 };
-
-  const now = new Date().toISOString();
-  let seeded = 0;
-  let skipped = 0;
-
-  for (const raw of declared) {
-    // Validate + fill defaults through the canonical spec schema. A real
-    // consumer at last — a malformed webhook warns and is skipped, never
-    // crashing boot.
-    let wh: Webhook;
-    try {
-      wh = WebhookSchema.parse(raw);
-    } catch (err: any) {
-      logger?.warn?.('[webhook] declared webhook failed validation — skipped', {
-        name: (raw as any)?.name,
-        error: err?.message ?? String(err),
-      });
-      skipped += 1;
-      continue;
-    }
-
-    try {
-      const existing = await engine.find(subscriptionsObject, {
-        filter: { name: wh.name },
-        limit: 1,
-        context: SYSTEM_CTX,
-      } as any);
-      const row: any = Array.isArray(existing) ? existing[0] : undefined;
-
-      if (row) {
-        // Admin owns a same-named row, or has edited this seeded one — never
-        // clobber. `active: false` on a noisy webhook must survive redeploys.
-        if (row.managed_by === 'admin') {
-          logger?.warn?.('[webhook] declared name collides with an admin-authored row — seed skipped', {
-            name: wh.name,
-          });
-          skipped += 1;
-          continue;
-        }
-        if (row.customized === true) {
-          skipped += 1;
-          continue;
-        }
-        const patch = {
-          id: row.id,
-          ...mapWebhookToRow(wh),
-          // Adopt pristine/legacy (pre-provenance) rows so future boots
-          // recognize them as package-managed.
-          managed_by: 'package',
-          updated_at: now,
-        };
-        await engine.update(subscriptionsObject, patch, { context: SYSTEM_CTX } as any);
-        seeded += 1;
-        continue;
-      }
-
-      const newRow = {
-        id: uid('whk'),
-        ...mapWebhookToRow(wh),
-        managed_by: 'package',
-        customized: false,
-        created_at: now,
-        updated_at: now,
-      };
-      await engine.insert(subscriptionsObject, newRow, { context: SYSTEM_CTX } as any);
-      seeded += 1;
-    } catch (err: any) {
-      logger?.warn?.('[webhook] declared webhook seed failed', {
-        name: wh.name,
-        error: err?.message ?? String(err),
-      });
-      skipped += 1;
-    }
-  }
-
-  logger?.info?.('[webhook] declared webhooks materialized into sys_webhook', {
-    seeded,
-    skipped,
-    total: declared.length,
-  });
-  return { seeded, skipped };
-}
-
-/**
- * Translate a validated {@link Webhook} into `sys_webhook` column values.
- * `object → object_name`, `isActive → active`; the full envelope is stashed in
- * `definition_json` for the enqueuer's advanced-config read (headers/secret/…).
- */
-function mapWebhookToRow(wh: Webhook): Record<string, unknown> {
-  return {
-    name: wh.name,
-    label: wh.label ?? wh.name,
-    object_name: wh.object ?? null,
-    triggers: wh.triggers ?? [],
-    url: wh.url,
-    // Store lowercase to match the object's Field.select option values
-    // (get/post/…); the enqueuer upper-cases before delivery either way.
-    method: String(wh.method ?? 'POST').toLowerCase(),
-    description: wh.description ?? null,
-    active: wh.isActive !== false,
-    definition_json: JSON.stringify(wh),
-  };
-}

package/src/index.ts

@@ -1,29 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * @objectstack/plugin-webhooks
- *
- * Webhook fan-out on top of the shared outbound-HTTP delivery substrate
- * (ADR-0018 M3). The durable outbox, cluster-coordinated dispatcher, retry /
- * backoff / dead-letter, and retention all live in
- * `@objectstack/service-messaging` (`sys_http_delivery` + `HttpDispatcher`).
- *
- * This package ships only the webhook-specific concerns:
- *   - the `sys_webhook` configuration object,
- *   - the {@link AutoEnqueuer} that turns `data.record.*` events into outbox
- *     rows (`source: 'webhook'`),
- *   - the redeliver admin endpoint.
- *
- * **Requires** `MessagingServicePlugin` (a foundational, always-on capability).
- *
- * ## Subpath exports
- * - `@objectstack/plugin-webhooks/schema` — `SysWebhook` object schema.
- */
-
-export {
-    WebhookOutboxPlugin,
-    type WebhookOutboxPluginOptions,
-} from './webhook-outbox-plugin.js';
-
-export { AutoEnqueuer, type AutoEnqueuerOptions, type HttpEnqueueFn } from './auto-enqueuer.js';
-export { SysWebhook } from './sys-webhook.object.js';

package/src/schema.ts

@@ -1,21 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * Public schema subpath: `@objectstack/plugin-webhooks/schema`.
- *
- * Thin re-export barrel kept stable across refactors. The object definition
- * lives in `sys-webhook.object.ts` (matching the `*.object.ts` convention used
- * everywhere else in the monorepo for `sys_*` schemas).
- *
- * `sys_webhook` moved here from `@objectstack/platform-objects` per ADR-0029
- * (K2.a) so this plugin owns its configuration object. Delivery telemetry is no
- * longer a webhook-owned object: post-ADR-0018 M3 deliveries are rows in the
- * shared `sys_http_delivery` outbox owned by `@objectstack/service-messaging`.
- *
- * Note: callers that just need the runtime should import from the package root
- * (`@objectstack/plugin-webhooks`), which auto-registers `sys_webhook` via the
- * plugin manifest. This subpath exists for read-only inspection from a
- * different runtime.
- */
-
-export { SysWebhook } from './sys-webhook.object.js';

package/src/sys-webhook.object.ts

@@ -1,231 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { ObjectSchema, Field } from '@objectstack/spec/data';
-
-/**
- * sys_webhook — Outbound HTTP integration configuration (runtime).
- *
- * Persists a single {@link Webhook} envelope per row so administrators
- * can author, enable/disable, and edit webhook subscriptions from the
- * Studio UI without code changes. The canonical Zod schema for the
- * `definition_json` envelope lives at `@objectstack/spec/automation/webhook`.
- *
- * ## Two authoring doors, one row
- * Rows land here two ways, distinguished by the `managed_by` provenance column:
- *   - **admin** — created/edited directly through this object's CRUD UI.
- *   - **package** — declared in code (`defineStack({ webhooks })` /
- *     `defineWebhook()`) and materialized on boot by
- *     `bootstrapDeclaredWebhooks` (#3461). Re-seeded every boot, but an admin
- *     edit stamps `customized: true` and freezes the row (seed-not-clobber,
- *     mirrors `sys_sharing_rule` #2909).
- *
- * One row per `name`. This plugin's {@link AutoEnqueuer} loads active rows on
- * boot + on `sys_webhook:changed` events, and turns matching `data.record.*`
- * events into deliveries on the shared `service-messaging` HTTP outbox
- * (ADR-0018 M3 — `sys_http_delivery`, drained by the messaging dispatcher).
- *
- * Ownership (ADR-0029 K2.a): this object is **owned by
- * `@objectstack/plugin-webhooks`** — the plugin that consumes these rows. It
- * used to live in the `@objectstack/platform-objects` monolith and be imported
- * here; the definition now lives with its owner so the plugin ships both data
- * and behavior as one unit.
- *
- * Platform-wide on purpose: every project (standalone, single-tenant,
- * cloud) can integrate with external systems (Slack, Stripe, internal
- * services) the same way.
- *
- * @namespace sys
- */
-export const SysWebhook = ObjectSchema.create({
-  name: 'sys_webhook',
-  label: 'Webhook',
-  pluralLabel: 'Webhooks',
-  icon: 'webhook',
-  isSystem: true,
-  managedBy: 'config',
-  // Authoring a webhook from the UI requires a structured form for the
-  // headers / auth / retry / payload blocks — the generic JSON textarea
-  // is acceptable as a v1 until a dedicated builder lands. Re-enable
-  // create/edit/delete so admins can at least toggle `active` and edit
-  // simple URL/method fields without round-tripping through code.
-  userActions: { create: true, edit: true, delete: true, import: false },
-  description: 'Outbound HTTP webhook subscription. Declared in code via defineStack({ webhooks }) / defineWebhook() (materialized into rows on boot) or authored directly in the Studio editor; dispatched by the webhook auto-enqueuer onto the shared HTTP outbox.',
-  displayNameField: 'name',
-  nameField: 'name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
-  titleFormat: '{label}',
-  highlightFields: ['name', 'object_name', 'url', 'active', 'updated_at'],
-
-  listViews: {
-    active: {
-      type: 'grid',
-      name: 'active',
-      label: 'Active',
-      data: { provider: 'object', object: 'sys_webhook' },
-      columns: ['label', 'object_name', 'url', 'method', 'active', 'updated_at'],
-      filter: [{ field: 'active', operator: 'equals', value: true }],
-      sort: [{ field: 'label', order: 'asc' }],
-      pagination: { pageSize: 50 },
-    },
-    inactive: {
-      type: 'grid',
-      name: 'inactive',
-      label: 'Inactive',
-      data: { provider: 'object', object: 'sys_webhook' },
-      columns: ['label', 'object_name', 'url', 'method', 'active', 'updated_at'],
-      filter: [{ field: 'active', operator: 'equals', value: false }],
-      sort: [{ field: 'label', order: 'asc' }],
-      pagination: { pageSize: 50 },
-    },
-    by_object: {
-      type: 'grid',
-      name: 'by_object',
-      label: 'By Object',
-      data: { provider: 'object', object: 'sys_webhook' },
-      columns: ['object_name', 'label', 'url', 'active', 'updated_at'],
-      sort: [{ field: 'object_name', order: 'asc' }, { field: 'label', order: 'asc' }],
-      grouping: { fields: [{ field: 'object_name', order: 'asc', collapsed: false }] },
-      pagination: { pageSize: 100 },
-    },
-    all_webhooks: {
-      type: 'grid',
-      name: 'all_webhooks',
-      label: 'All',
-      data: { provider: 'object', object: 'sys_webhook' },
-      columns: ['label', 'object_name', 'url', 'method', 'active', 'updated_at'],
-      sort: [{ field: 'label', order: 'asc' }],
-      pagination: { pageSize: 50 },
-    },
-  },
-
-  fields: {
-    id: Field.text({ label: 'Webhook ID', required: true, readonly: true, group: 'System' }),
-
-    name: Field.text({
-      label: 'Name',
-      required: true,
-      maxLength: 100,
-      description: 'Unique snake_case name — referenced in logs and audit',
-      group: 'Definition',
-    }),
-
-    label: Field.text({
-      label: 'Display Label',
-      required: false,
-      maxLength: 200,
-      group: 'Definition',
-    }),
-
-    object_name: Field.text({
-      label: 'Object',
-      required: false,
-      maxLength: 100,
-      // Object picker (same widget as sys_sharing_rule) instead of a free-text
-      // machine name. Falls back to a text input when the widget is unavailable.
-      widget: 'object-ref',
-      description: 'Short object name whose record events (create/update/delete) fire this webhook',
-      group: 'Definition',
-    }),
-
-    triggers: Field.select(
-      ['create', 'update', 'delete'],
-      {
-        label: 'Triggers',
-        required: false,
-        // Multi-select instead of a hand-typed comma-separated string. Stored as
-        // an array; the auto-enqueuer parser also tolerates the legacy
-        // comma-separated / JSON-string forms so existing rows keep working.
-        multiple: true,
-        description: 'Record events that fire this webhook',
-        group: 'Definition',
-      },
-    ),
-
-    url: Field.text({
-      label: 'Target URL',
-      required: true,
-      maxLength: 2048,
-      description: 'External endpoint that receives the POST',
-      group: 'Definition',
-    }),
-
-    method: Field.select(
-      ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
-      {
-        label: 'HTTP Method',
-        required: true,
-        // Select instead of free text. Option values are lowercased by the
-        // Field.select helper (get/post/…); the auto-enqueuer upper-cases the
-        // resolved method before delivery, so existing 'POST' rows and the
-        // lowercase option values both normalise correctly.
-        defaultValue: 'post',
-        description: 'HTTP method used for the callback request',
-        group: 'Definition',
-      },
-    ),
-
-    description: Field.textarea({ label: 'Description', required: false, group: 'Definition' }),
-
-    active: Field.boolean({
-      label: 'Active',
-      required: true,
-      defaultValue: true,
-      description: 'Inactive webhooks are skipped by the dispatcher',
-      group: 'Definition',
-    }),
-
-    definition_json: Field.textarea({
-      label: 'Definition',
-      required: true,
-      description: 'Serialised Webhook JSON (see @objectstack/spec/automation/webhook) — full headers/auth/retry/payload config',
-      group: 'Definition',
-    }),
-
-    // ── Provenance (#3461 — record-authoritative seed-not-clobber) ──
-    // Mirrors sys_sharing_rule (#2909). Both columns are `readonly`: the
-    // engine strips them from non-system payloads (forge/clear-proof), while
-    // bootstrapDeclaredWebhooks and the provenance stamp hook write with
-    // isSystem. Deliberately NOT a write gate: webhooks are a first-class admin
-    // authoring/tuning surface — admins may edit or deactivate a package row;
-    // the seeder simply stops overwriting it once `customized` is stamped.
-    managed_by: Field.select(
-      ['platform', 'package', 'admin'],
-      {
-        label: 'Managed By',
-        required: false,
-        readonly: true,
-        defaultValue: 'admin',
-        description:
-          'Record provenance: platform = framework built-in / package = app/package-declared ' +
-          '(boot-seeded from defineStack webhooks) / admin = created in Setup.',
-        group: 'System',
-      },
-    ),
-
-    customized: Field.boolean({
-      label: 'Customized',
-      required: false,
-      readonly: true,
-      defaultValue: false,
-      description:
-        'Set when an admin edits a package-declared webhook; boot seeding will no longer ' +
-        'overwrite the row (a deactivated noisy webhook survives redeploys). Meaningless on admin rows.',
-      group: 'System',
-    }),
-
-    created_at: Field.datetime({
-      label: 'Created At',
-      required: true,
-      defaultValue: 'NOW()',
-      readonly: true,
-      group: 'System',
-    }),
-
-    updated_at: Field.datetime({ label: 'Updated At', required: false, group: 'System' }),
-  },
-
-  indexes: [
-    { fields: ['name'], unique: true },
-    { fields: ['object_name'] },
-    { fields: ['active', 'object_name'] },
-  ],
-});

package/src/translations/bundle-ownership.test.ts

@@ -1,41 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-//
-// Bundle-ownership guard (#2834 ⑤ / ADR-0029 D8): this package's generated
-// object-translation bundles must carry ONLY objects its extract config
-// (`scripts/i18n-extract.config.ts`) actually imports. When an object moves to
-// another package, its translations move with it — a leftover copy here
-// silently DIES on the next `os i18n extract` run, taking curated translations
-// with it (the sys_audit_log incident). This test turns that silent loss into a
-// red build: an object present in the bundle but not in the ownership list below
-// means either (a) the extract config gained an object — add it here — or (b) a
-// moved/removed object's keys were left behind — remove them from the bundles
-// (or migrate them to the owning package), then keep this list in sync.
-
-import { describe, it, expect } from 'vitest';
-import { enObjects } from './en.objects.generated.js';
-
-// Objects the extract config (scripts/i18n-extract.config.ts) imports —
-// keep the two lists in sync when adding/moving objects.
-const OWNED_OBJECTS = new Set([
-  'sys_webhook',
-]);
-
-describe('objects translation bundle ownership (ADR-0029 D8)', () => {
-  it('the en bundle contains no objects owned by other packages', () => {
-    const strays = Object.keys(enObjects).filter((o) => !OWNED_OBJECTS.has(o));
-    expect(
-      strays,
-      `bundle carries objects this package's extract config does not own: ${strays.join(', ')} — ` +
-        'their curated translations would be silently deleted on the next `os i18n extract`. ' +
-        'Remove the dead block from the four locale bundles, or add the object to the extract config + this list.',
-    ).toEqual([]);
-  });
-
-  it('every owned object is present in the bundle (extract config regression)', () => {
-    const missing = [...OWNED_OBJECTS].filter((o) => !(o in enObjects));
-    expect(
-      missing,
-      `objects the extract config should emit are missing from the bundle: ${missing.join(', ')} — was an import dropped from scripts/i18n-extract.config.ts?`,
-    ).toEqual([]);
-  });
-});

package/src/translations/en.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 'en'.
- * 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 enObjects: NonNullable<TranslationData['objects']> = {
-  sys_webhook: {
-    label: "Webhook",
-    pluralLabel: "Webhooks",
-    description: "Outbound HTTP webhook subscription. Authored via defineWebhook() in code or the Studio editor; executed by the HTTP connector plugin.",
-    fields: {
-      id: {
-        label: "Webhook ID"
-      },
-      name: {
-        label: "Name",
-        help: "Unique snake_case name — referenced in logs and audit"
-      },
-      label: {
-        label: "Display Label"
-      },
-      object_name: {
-        label: "Object",
-        help: "Short object name whose record events (create/update/delete) fire this webhook"
-      },
-      triggers: {
-        label: "Triggers",
-        help: "Comma-separated event list: create,update,delete",
-        options: {
-          create: "create",
-          update: "update",
-          delete: "delete"
-        }
-      },
-      url: {
-        label: "Target URL",
-        help: "External endpoint that receives the POST"
-      },
-      method: {
-        label: "HTTP Method",
-        help: "GET / POST / PUT / PATCH / DELETE",
-        options: {
-          get: "GET",
-          post: "POST",
-          put: "PUT",
-          patch: "PATCH",
-          delete: "DELETE"
-        }
-      },
-      description: {
-        label: "Description"
-      },
-      active: {
-        label: "Active",
-        help: "Inactive webhooks are skipped by the dispatcher"
-      },
-      definition_json: {
-        label: "Definition",
-        help: "Serialised Webhook JSON (see @objectstack/spec/automation/webhook) — full headers/auth/retry/payload config"
-      },
-      managed_by: {
-        label: "Managed By",
-        help: "Record provenance: platform = framework built-in / package = app/package-declared (boot-seeded from defineStack webhooks) / admin = created in Setup.",
-        options: {
-          platform: "platform",
-          package: "package",
-          admin: "admin"
-        }
-      },
-      customized: {
-        label: "Customized",
-        help: "Set when an admin edits a package-declared webhook; boot seeding will no longer overwrite the row (a deactivated noisy webhook survives redeploys). Meaningless on admin rows."
-      },
-      created_at: {
-        label: "Created At"
-      },
-      updated_at: {
-        label: "Updated At"
-      }
-    },
-    _views: {
-      active: {
-        label: "Active"
-      },
-      inactive: {
-        label: "Inactive"
-      },
-      by_object: {
-        label: "By Object"
-      },
-      all_webhooks: {
-        label: "All"
-      }
-    }
-  }
-};