@objectstack/trigger-api 9.3.0

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+import { Plugin, PluginContext } from '@objectstack/core';
+import { AutomationContext } from '@objectstack/spec/contracts';
+
+/** Mount point for inbound hooks on the host HTTP server. */
+declare const HOOKS_PATH = "/api/v1/automation/hooks/:flowName/:hookId";
+/**
+ * ApiTriggerPlugin (ADR-0041 Tier 1)
+ *
+ * Makes `type: 'api'` flows actually fire. The automation engine derives an
+ * `api` binding from the flow; this plugin provides the concrete trigger:
+ *
+ *  - mounts `POST /api/v1/automation/hooks/:flowName/:hookId` on the host
+ *    Hono app (resolved via the `http-server` service);
+ *  - validates hookId + HMAC signature (`x-objectstack-signature`,
+ *    GitHub/Stripe style, constant-time) against the flow's start-node
+ *    config;
+ *  - **enqueues** the payload (`queue` service) and ACKs 202 — flow
+ *    execution happens on the queue consumer, never in-band with the
+ *    inbound request (ADR-0041 §5: boundary triggers must not let a slow
+ *    flow drop or block events). `x-idempotency-key` passes through to the
+ *    queue's dedup window.
+ *
+ * Webhook payloads surface to the flow as the trigger record (`$record` /
+ * `record.*` / bare field references) — the same authoring surface
+ * record-change flows use.
+ */
+declare class ApiTriggerPlugin implements Plugin {
+    name: string;
+    type: string;
+    version: string;
+    dependencies: string[];
+    init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+    private resolveService;
+}
+
+/**
+ * Structural mirror of the automation engine's `FlowTriggerBinding` — same
+ * decoupling pattern as `trigger-schedule` / `trigger-record-change`: this
+ * package never imports `service-automation`.
+ */
+interface FlowTriggerBinding {
+    readonly flowName: string;
+    readonly object?: string;
+    readonly event?: string;
+    readonly condition?: string | {
+        dialect?: string;
+        source?: string;
+        ast?: unknown;
+    };
+    readonly schedule?: unknown;
+    readonly config?: Record<string, unknown>;
+}
+/** Structural mirror of the engine's `FlowTrigger` extension point. */
+interface FlowTrigger {
+    readonly type: string;
+    start(binding: FlowTriggerBinding, callback: (ctx: AutomationContext) => Promise<void>): void;
+    stop(flowName: string): void;
+}
+/**
+ * The slice of `IQueueService` this trigger needs. Boundary triggers MUST
+ * ingest through the queue (ADR-0041 §5): inbound HTTP is the first event
+ * source whose rate we don't control, and a slow flow execution may neither
+ * drop nor block inbound events. At-least-once delivery; flows should be
+ * authored idempotently (an `x-idempotency-key` header passes through to the
+ * queue's dedup window).
+ */
+interface QueueServiceSurface {
+    publish<T = unknown>(queue: string, data: T, options?: {
+        idempotencyKey?: string;
+    }): Promise<string>;
+    subscribe<T = unknown>(queue: string, handler: (message: {
+        data: T;
+    }) => Promise<void> | void): Promise<void>;
+    unsubscribe(queue: string): Promise<void>;
+}
+/** Minimal logger surface (matches core's `ctx.logger`). */
+interface TriggerLogger {
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    debug?(msg: string, ...args: unknown[]): void;
+}
+/**
+ * GitHub/Stripe-style HMAC verification: the sender computes
+ * `sha256=<hex hmac of the raw body>` with the shared per-flow secret and
+ * sends it as `x-objectstack-signature`.
+ */
+declare function verifySignature(secret: string, rawBody: string, header: string | undefined): boolean;
+/**
+ * `api` flow trigger (ADR-0041 Tier 1) — inbound webhook/HTTP.
+ *
+ * The engine binds every `type: 'api'` flow to this trigger; `start()` arms a
+ * hook (URL path + optional HMAC secret from the start node's `config`) and
+ * subscribes a queue consumer that runs the flow. The HTTP side
+ * ({@link handleRequest}) validates and **enqueues** — it never executes the
+ * flow in-band:
+ *
+ *   POST /api/v1/automation/hooks/:flowName/:hookId
+ *     → 404 unknown flow / wrong hookId
+ *     → 401 missing/bad HMAC signature (when the flow declares a `secret`)
+ *     → 400 non-JSON body
+ *     → 202 { accepted, messageId } — queued; a consumer executes the flow
+ *
+ * The JSON payload is exposed to the flow as the trigger record (`$record` /
+ * `record.*`, fields flattened to bare references) plus `params` — the same
+ * authoring surface record-change flows use.
+ *
+ * Start-node config keys:
+ *   - `hookId`  — URL path token (default `'default'`); rotate it to revoke
+ *                 old URLs without renaming the flow.
+ *   - `secret`  — HMAC-SHA256 shared secret. Strongly recommended; without it
+ *                 the endpoint accepts unsigned posts (the trigger logs a
+ *                 warning at arm time).
+ */
+declare class ApiTrigger implements FlowTrigger {
+    private readonly getQueue;
+    private readonly logger;
+    readonly type = "api";
+    private hooks;
+    constructor(getQueue: () => QueueServiceSurface | null, logger: TriggerLogger);
+    /** Currently armed hooks (for diagnostics/tests). */
+    listHooks(): Array<{
+        flowName: string;
+        hookId: string;
+        signed: boolean;
+    }>;
+    start(binding: FlowTriggerBinding, callback: (ctx: AutomationContext) => Promise<void>): void;
+    stop(flowName: string): void;
+    /**
+     * Handle one inbound request. Transport-agnostic: the plugin adapts this
+     * to the host HTTP server. Returns the response to send.
+     */
+    handleRequest(input: {
+        flowName: string;
+        hookId: string;
+        rawBody: string;
+        signatureHeader?: string;
+        idempotencyKey?: string;
+    }): Promise<{
+        status: number;
+        body: Record<string, unknown>;
+    }>;
+}
+
+export { ApiTrigger, ApiTriggerPlugin, type FlowTrigger, type FlowTriggerBinding, HOOKS_PATH, type QueueServiceSurface, type TriggerLogger, verifySignature };

package/dist/index.js

@@ -0,0 +1,204 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ApiTrigger: () => ApiTrigger,
+  ApiTriggerPlugin: () => ApiTriggerPlugin,
+  HOOKS_PATH: () => HOOKS_PATH,
+  verifySignature: () => verifySignature
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/api-trigger.ts
+var import_node_crypto = require("crypto");
+var QUEUE_PREFIX = "flow-api";
+function safeEqual(a, b) {
+  const ab = Buffer.from(a, "utf8");
+  const bb = Buffer.from(b, "utf8");
+  if (ab.length !== bb.length) return false;
+  return (0, import_node_crypto.timingSafeEqual)(ab, bb);
+}
+function verifySignature(secret, rawBody, header) {
+  if (!header) return false;
+  const expected = "sha256=" + (0, import_node_crypto.createHmac)("sha256", secret).update(rawBody, "utf8").digest("hex");
+  return safeEqual(expected, header.trim());
+}
+var ApiTrigger = class {
+  constructor(getQueue, logger) {
+    this.getQueue = getQueue;
+    this.logger = logger;
+    this.type = "api";
+    this.hooks = /* @__PURE__ */ new Map();
+  }
+  /** Currently armed hooks (for diagnostics/tests). */
+  listHooks() {
+    return [...this.hooks.values()].map((h) => ({
+      flowName: h.flowName,
+      hookId: h.hookId,
+      signed: !!h.secret
+    }));
+  }
+  start(binding, callback) {
+    const cfg = binding.config ?? {};
+    const hookId = typeof cfg.hookId === "string" && cfg.hookId.trim() ? cfg.hookId.trim() : "default";
+    const secret = typeof cfg.secret === "string" && cfg.secret.trim() ? cfg.secret.trim() : void 0;
+    const queue = `${QUEUE_PREFIX}:${binding.flowName}`;
+    const hook = { flowName: binding.flowName, hookId, secret, queue, callback };
+    this.hooks.set(binding.flowName, hook);
+    const q = this.getQueue();
+    if (!q) {
+      this.logger.warn(
+        `[trigger-api] no queue service \u2014 inbound posts for flow '${binding.flowName}' will be rejected until one is registered`
+      );
+    } else {
+      void q.subscribe(queue, async (message) => {
+        const payload = message?.data?.payload ?? {};
+        await hook.callback({
+          // The webhook body IS the trigger record: `$record`, `record.*`,
+          // and bare field references all resolve, matching how
+          // record-change flows are authored.
+          record: payload,
+          params: { ...payload },
+          event: "api"
+        });
+      }).catch((err) => {
+        this.logger.warn(`[trigger-api] subscribe failed for '${queue}': ${err?.message ?? err}`);
+      });
+    }
+    if (!secret) {
+      this.logger.warn(
+        `[trigger-api] flow '${binding.flowName}' armed WITHOUT a secret \u2014 endpoint accepts unsigned posts`
+      );
+    }
+    this.logger.info(
+      `[trigger-api] armed: POST .../automation/hooks/${binding.flowName}/${hookId}${secret ? " (HMAC required)" : ""}`
+    );
+  }
+  stop(flowName) {
+    const hook = this.hooks.get(flowName);
+    if (!hook) return;
+    this.hooks.delete(flowName);
+    const q = this.getQueue();
+    if (q) void q.unsubscribe(hook.queue).catch(() => {
+    });
+    this.logger.info(`[trigger-api] disarmed: flow '${flowName}'`);
+  }
+  /**
+   * Handle one inbound request. Transport-agnostic: the plugin adapts this
+   * to the host HTTP server. Returns the response to send.
+   */
+  async handleRequest(input) {
+    const hook = this.hooks.get(input.flowName);
+    if (!hook || !safeEqual(hook.hookId, input.hookId)) {
+      return { status: 404, body: { error: "not_found" } };
+    }
+    if (hook.secret && !verifySignature(hook.secret, input.rawBody, input.signatureHeader)) {
+      return { status: 401, body: { error: "invalid_signature" } };
+    }
+    let payload;
+    try {
+      const parsed = input.rawBody.trim() ? JSON.parse(input.rawBody) : {};
+      if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { status: 400, body: { error: "invalid_body", message: "Body must be a JSON object." } };
+      }
+      payload = parsed;
+    } catch {
+      return { status: 400, body: { error: "invalid_body", message: "Body must be valid JSON." } };
+    }
+    const q = this.getQueue();
+    if (!q) {
+      return { status: 503, body: { error: "queue_unavailable", message: "No queue service is registered." } };
+    }
+    try {
+      const messageId = await q.publish(hook.queue, { payload }, {
+        idempotencyKey: input.idempotencyKey
+      });
+      return { status: 202, body: { accepted: true, messageId } };
+    } catch (err) {
+      this.logger.warn(`[trigger-api] enqueue failed for '${hook.queue}': ${err?.message ?? err}`);
+      return { status: 503, body: { error: "enqueue_failed" } };
+    }
+  }
+};
+
+// src/plugin.ts
+var HOOKS_PATH = "/api/v1/automation/hooks/:flowName/:hookId";
+var ApiTriggerPlugin = class {
+  constructor() {
+    this.name = "com.objectstack.trigger.api";
+    this.type = "standard";
+    this.version = "1.0.0";
+    this.dependencies = ["com.objectstack.service.queue"];
+  }
+  async init(ctx) {
+    ctx.logger.info("API trigger plugin initialized");
+  }
+  async start(ctx) {
+    ctx.hook("kernel:ready", async () => {
+      const automation = this.resolveService(ctx, "automation");
+      if (!automation || typeof automation.registerTrigger !== "function") {
+        ctx.logger.warn("ApiTriggerPlugin: automation service not available \u2014 api trigger NOT installed");
+        return;
+      }
+      if (!this.resolveService(ctx, "queue")) {
+        ctx.logger.warn("ApiTriggerPlugin: queue service not available \u2014 inbound posts will 503 until one is registered");
+      }
+      const trigger = new ApiTrigger(
+        () => this.resolveService(ctx, "queue"),
+        ctx.logger
+      );
+      automation.registerTrigger(trigger);
+      const http = this.resolveService(ctx, "http-server");
+      const rawApp = http && typeof http.getRawApp === "function" ? http.getRawApp() : null;
+      if (!rawApp) {
+        ctx.logger.warn("ApiTriggerPlugin: HTTP server not available \u2014 hooks endpoint not mounted");
+        return;
+      }
+      rawApp.post(HOOKS_PATH, async (c) => {
+        const rawBody = await c.req.text();
+        const out = await trigger.handleRequest({
+          flowName: c.req.param("flowName"),
+          hookId: c.req.param("hookId"),
+          rawBody,
+          signatureHeader: c.req.header("x-objectstack-signature"),
+          idempotencyKey: c.req.header("x-idempotency-key") || void 0
+        });
+        return c.json(out.body, out.status);
+      });
+      ctx.logger.info(`ApiTriggerPlugin: api trigger registered, hooks mounted at POST ${HOOKS_PATH}`);
+    });
+  }
+  resolveService(ctx, name) {
+    try {
+      return ctx.getService(name) ?? null;
+    } catch {
+      return null;
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiTrigger,
+  ApiTriggerPlugin,
+  HOOKS_PATH,
+  verifySignature
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/api-trigger.ts","../src/plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nexport { ApiTriggerPlugin, HOOKS_PATH } from './plugin.js';\nexport { ApiTrigger, verifySignature } from './api-trigger.js';\nexport type {\n    FlowTrigger,\n    FlowTriggerBinding,\n    QueueServiceSurface,\n    TriggerLogger,\n} from './api-trigger.js';\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport { createHmac, timingSafeEqual } from 'node:crypto';\nimport type { AutomationContext } from '@objectstack/spec/contracts';\n\n/**\n * Structural mirror of the automation engine's `FlowTriggerBinding` — same\n * decoupling pattern as `trigger-schedule` / `trigger-record-change`: this\n * package never imports `service-automation`.\n */\nexport interface FlowTriggerBinding {\n    readonly flowName: string;\n    readonly object?: string;\n    readonly event?: string;\n    readonly condition?: string | { dialect?: string; source?: string; ast?: unknown };\n    readonly schedule?: unknown;\n    readonly config?: Record<string, unknown>;\n}\n\n/** Structural mirror of the engine's `FlowTrigger` extension point. */\nexport interface FlowTrigger {\n    readonly type: string;\n    start(binding: FlowTriggerBinding, callback: (ctx: AutomationContext) => Promise<void>): void;\n    stop(flowName: string): void;\n}\n\n/**\n * The slice of `IQueueService` this trigger needs. Boundary triggers MUST\n * ingest through the queue (ADR-0041 §5): inbound HTTP is the first event\n * source whose rate we don't control, and a slow flow execution may neither\n * drop nor block inbound events. At-least-once delivery; flows should be\n * authored idempotently (an `x-idempotency-key` header passes through to the\n * queue's dedup window).\n */\nexport interface QueueServiceSurface {\n    publish<T = unknown>(queue: string, data: T, options?: { idempotencyKey?: string }): Promise<string>;\n    subscribe<T = unknown>(queue: string, handler: (message: { data: T }) => Promise<void> | void): Promise<void>;\n    unsubscribe(queue: string): Promise<void>;\n}\n\n/** Minimal logger surface (matches core's `ctx.logger`). */\nexport interface TriggerLogger {\n    info(msg: string, ...args: unknown[]): void;\n    warn(msg: string, ...args: unknown[]): void;\n    debug?(msg: string, ...args: unknown[]): void;\n}\n\nconst QUEUE_PREFIX = 'flow-api';\n\n/** One armed inbound hook. */\ninterface ArmedHook {\n    flowName: string;\n    hookId: string;\n    secret?: string;\n    queue: string;\n    callback: (ctx: AutomationContext) => Promise<void>;\n}\n\n/** Constant-time string compare (length leak only). */\nfunction safeEqual(a: string, b: string): boolean {\n    const ab = Buffer.from(a, 'utf8');\n    const bb = Buffer.from(b, 'utf8');\n    if (ab.length !== bb.length) return false;\n    return timingSafeEqual(ab, bb);\n}\n\n/**\n * GitHub/Stripe-style HMAC verification: the sender computes\n * `sha256=<hex hmac of the raw body>` with the shared per-flow secret and\n * sends it as `x-objectstack-signature`.\n */\nexport function verifySignature(secret: string, rawBody: string, header: string | undefined): boolean {\n    if (!header) return false;\n    const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');\n    return safeEqual(expected, header.trim());\n}\n\n/**\n * `api` flow trigger (ADR-0041 Tier 1) — inbound webhook/HTTP.\n *\n * The engine binds every `type: 'api'` flow to this trigger; `start()` arms a\n * hook (URL path + optional HMAC secret from the start node's `config`) and\n * subscribes a queue consumer that runs the flow. The HTTP side\n * ({@link handleRequest}) validates and **enqueues** — it never executes the\n * flow in-band:\n *\n *   POST /api/v1/automation/hooks/:flowName/:hookId\n *     → 404 unknown flow / wrong hookId\n *     → 401 missing/bad HMAC signature (when the flow declares a `secret`)\n *     → 400 non-JSON body\n *     → 202 { accepted, messageId } — queued; a consumer executes the flow\n *\n * The JSON payload is exposed to the flow as the trigger record (`$record` /\n * `record.*`, fields flattened to bare references) plus `params` — the same\n * authoring surface record-change flows use.\n *\n * Start-node config keys:\n *   - `hookId`  — URL path token (default `'default'`); rotate it to revoke\n *                 old URLs without renaming the flow.\n *   - `secret`  — HMAC-SHA256 shared secret. Strongly recommended; without it\n *                 the endpoint accepts unsigned posts (the trigger logs a\n *                 warning at arm time).\n */\nexport class ApiTrigger implements FlowTrigger {\n    readonly type = 'api';\n\n    private hooks = new Map<string, ArmedHook>();\n\n    constructor(\n        private readonly getQueue: () => QueueServiceSurface | null,\n        private readonly logger: TriggerLogger,\n    ) {}\n\n    /** Currently armed hooks (for diagnostics/tests). */\n    listHooks(): Array<{ flowName: string; hookId: string; signed: boolean }> {\n        return [...this.hooks.values()].map(h => ({\n            flowName: h.flowName, hookId: h.hookId, signed: !!h.secret,\n        }));\n    }\n\n    start(binding: FlowTriggerBinding, callback: (ctx: AutomationContext) => Promise<void>): void {\n        const cfg = (binding.config ?? {}) as Record<string, unknown>;\n        const hookId = typeof cfg.hookId === 'string' && cfg.hookId.trim() ? cfg.hookId.trim() : 'default';\n        const secret = typeof cfg.secret === 'string' && cfg.secret.trim() ? cfg.secret.trim() : undefined;\n        const queue = `${QUEUE_PREFIX}:${binding.flowName}`;\n\n        const hook: ArmedHook = { flowName: binding.flowName, hookId, secret, queue, callback };\n        this.hooks.set(binding.flowName, hook);\n\n        const q = this.getQueue();\n        if (!q) {\n            this.logger.warn(\n                `[trigger-api] no queue service — inbound posts for flow '${binding.flowName}' will be rejected until one is registered`,\n            );\n        } else {\n            void q.subscribe<{ payload: Record<string, unknown> }>(queue, async (message) => {\n                const payload = (message?.data as any)?.payload ?? {};\n                await hook.callback({\n                    // The webhook body IS the trigger record: `$record`, `record.*`,\n                    // and bare field references all resolve, matching how\n                    // record-change flows are authored.\n                    record: payload,\n                    params: { ...payload },\n                    event: 'api',\n                } as AutomationContext);\n            }).catch((err: any) => {\n                this.logger.warn(`[trigger-api] subscribe failed for '${queue}': ${err?.message ?? err}`);\n            });\n        }\n\n        if (!secret) {\n            this.logger.warn(\n                `[trigger-api] flow '${binding.flowName}' armed WITHOUT a secret — endpoint accepts unsigned posts`,\n            );\n        }\n        this.logger.info(\n            `[trigger-api] armed: POST .../automation/hooks/${binding.flowName}/${hookId}${secret ? ' (HMAC required)' : ''}`,\n        );\n    }\n\n    stop(flowName: string): void {\n        const hook = this.hooks.get(flowName);\n        if (!hook) return;\n        this.hooks.delete(flowName);\n        const q = this.getQueue();\n        if (q) void q.unsubscribe(hook.queue).catch(() => { /* already gone */ });\n        this.logger.info(`[trigger-api] disarmed: flow '${flowName}'`);\n    }\n\n    /**\n     * Handle one inbound request. Transport-agnostic: the plugin adapts this\n     * to the host HTTP server. Returns the response to send.\n     */\n    async handleRequest(input: {\n        flowName: string;\n        hookId: string;\n        rawBody: string;\n        signatureHeader?: string;\n        idempotencyKey?: string;\n    }): Promise<{ status: number; body: Record<string, unknown> }> {\n        const hook = this.hooks.get(input.flowName);\n        // Unknown flow and wrong hookId answer identically — no oracle for\n        // probing which flows exist.\n        if (!hook || !safeEqual(hook.hookId, input.hookId)) {\n            return { status: 404, body: { error: 'not_found' } };\n        }\n        if (hook.secret && !verifySignature(hook.secret, input.rawBody, input.signatureHeader)) {\n            return { status: 401, body: { error: 'invalid_signature' } };\n        }\n\n        let payload: Record<string, unknown>;\n        try {\n            const parsed: unknown = input.rawBody.trim() ? JSON.parse(input.rawBody) : {};\n            if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n                return { status: 400, body: { error: 'invalid_body', message: 'Body must be a JSON object.' } };\n            }\n            payload = parsed as Record<string, unknown>;\n        } catch {\n            return { status: 400, body: { error: 'invalid_body', message: 'Body must be valid JSON.' } };\n        }\n\n        const q = this.getQueue();\n        if (!q) {\n            return { status: 503, body: { error: 'queue_unavailable', message: 'No queue service is registered.' } };\n        }\n        try {\n            const messageId = await q.publish(hook.queue, { payload }, {\n                idempotencyKey: input.idempotencyKey,\n            });\n            return { status: 202, body: { accepted: true, messageId } };\n        } catch (err: any) {\n            this.logger.warn(`[trigger-api] enqueue failed for '${hook.queue}': ${err?.message ?? err}`);\n            return { status: 503, body: { error: 'enqueue_failed' } };\n        }\n    }\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport { ApiTrigger } from './api-trigger.js';\nimport type { FlowTrigger, QueueServiceSurface } from './api-trigger.js';\n\n/**\n * The slice of the automation engine this plugin needs. Declared structurally\n * so the plugin does not take a build dependency on\n * `@objectstack/service-automation`.\n */\ninterface AutomationTriggerRegistry {\n    registerTrigger(trigger: FlowTrigger): void;\n    unregisterTrigger?(type: string): void;\n}\n\n/** The slice of the Hono host server this plugin needs. */\ninterface HttpServerSurface {\n    getRawApp(): {\n        post(path: string, handler: (c: any) => Promise<unknown> | unknown): void;\n    } | null;\n}\n\n/** Mount point for inbound hooks on the host HTTP server. */\nexport const HOOKS_PATH = '/api/v1/automation/hooks/:flowName/:hookId';\n\n/**\n * ApiTriggerPlugin (ADR-0041 Tier 1)\n *\n * Makes `type: 'api'` flows actually fire. The automation engine derives an\n * `api` binding from the flow; this plugin provides the concrete trigger:\n *\n *  - mounts `POST /api/v1/automation/hooks/:flowName/:hookId` on the host\n *    Hono app (resolved via the `http-server` service);\n *  - validates hookId + HMAC signature (`x-objectstack-signature`,\n *    GitHub/Stripe style, constant-time) against the flow's start-node\n *    config;\n *  - **enqueues** the payload (`queue` service) and ACKs 202 — flow\n *    execution happens on the queue consumer, never in-band with the\n *    inbound request (ADR-0041 §5: boundary triggers must not let a slow\n *    flow drop or block events). `x-idempotency-key` passes through to the\n *    queue's dedup window.\n *\n * Webhook payloads surface to the flow as the trigger record (`$record` /\n * `record.*` / bare field references) — the same authoring surface\n * record-change flows use.\n */\nexport class ApiTriggerPlugin implements Plugin {\n    name = 'com.objectstack.trigger.api';\n    type = 'standard';\n    version = '1.0.0';\n    dependencies = ['com.objectstack.service.queue'];\n\n    async init(ctx: PluginContext): Promise<void> {\n        ctx.logger.info('API trigger plugin initialized');\n    }\n\n    async start(ctx: PluginContext): Promise<void> {\n        // Resolve at kernel:ready — the automation engine, queue service, and\n        // HTTP server may all start after this plugin.\n        ctx.hook('kernel:ready', async () => {\n            const automation = this.resolveService<AutomationTriggerRegistry>(ctx, 'automation');\n            if (!automation || typeof automation.registerTrigger !== 'function') {\n                ctx.logger.warn('ApiTriggerPlugin: automation service not available — api trigger NOT installed');\n                return;\n            }\n            if (!this.resolveService<QueueServiceSurface>(ctx, 'queue')) {\n                ctx.logger.warn('ApiTriggerPlugin: queue service not available — inbound posts will 503 until one is registered');\n            }\n\n            const trigger = new ApiTrigger(\n                () => this.resolveService<QueueServiceSurface>(ctx, 'queue'),\n                ctx.logger,\n            );\n            automation.registerTrigger(trigger);\n\n            const http = this.resolveService<HttpServerSurface>(ctx, 'http-server');\n            const rawApp = http && typeof http.getRawApp === 'function' ? http.getRawApp() : null;\n            if (!rawApp) {\n                ctx.logger.warn('ApiTriggerPlugin: HTTP server not available — hooks endpoint not mounted');\n                return;\n            }\n            rawApp.post(HOOKS_PATH, async (c: any) => {\n                const rawBody = await c.req.text();\n                const out = await trigger.handleRequest({\n                    flowName: c.req.param('flowName'),\n                    hookId: c.req.param('hookId'),\n                    rawBody,\n                    signatureHeader: c.req.header('x-objectstack-signature'),\n                    idempotencyKey: c.req.header('x-idempotency-key') || undefined,\n                });\n                return c.json(out.body, out.status);\n            });\n            ctx.logger.info(`ApiTriggerPlugin: api trigger registered, hooks mounted at POST ${HOOKS_PATH}`);\n        });\n    }\n\n    private resolveService<T>(ctx: PluginContext, name: string): T | null {\n        try {\n            return ctx.getService<T>(name) ?? null;\n        } catch {\n            return null;\n        }\n    }\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,174 @@
+// src/api-trigger.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var QUEUE_PREFIX = "flow-api";
+function safeEqual(a, b) {
+  const ab = Buffer.from(a, "utf8");
+  const bb = Buffer.from(b, "utf8");
+  if (ab.length !== bb.length) return false;
+  return timingSafeEqual(ab, bb);
+}
+function verifySignature(secret, rawBody, header) {
+  if (!header) return false;
+  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
+  return safeEqual(expected, header.trim());
+}
+var ApiTrigger = class {
+  constructor(getQueue, logger) {
+    this.getQueue = getQueue;
+    this.logger = logger;
+    this.type = "api";
+    this.hooks = /* @__PURE__ */ new Map();
+  }
+  /** Currently armed hooks (for diagnostics/tests). */
+  listHooks() {
+    return [...this.hooks.values()].map((h) => ({
+      flowName: h.flowName,
+      hookId: h.hookId,
+      signed: !!h.secret
+    }));
+  }
+  start(binding, callback) {
+    const cfg = binding.config ?? {};
+    const hookId = typeof cfg.hookId === "string" && cfg.hookId.trim() ? cfg.hookId.trim() : "default";
+    const secret = typeof cfg.secret === "string" && cfg.secret.trim() ? cfg.secret.trim() : void 0;
+    const queue = `${QUEUE_PREFIX}:${binding.flowName}`;
+    const hook = { flowName: binding.flowName, hookId, secret, queue, callback };
+    this.hooks.set(binding.flowName, hook);
+    const q = this.getQueue();
+    if (!q) {
+      this.logger.warn(
+        `[trigger-api] no queue service \u2014 inbound posts for flow '${binding.flowName}' will be rejected until one is registered`
+      );
+    } else {
+      void q.subscribe(queue, async (message) => {
+        const payload = message?.data?.payload ?? {};
+        await hook.callback({
+          // The webhook body IS the trigger record: `$record`, `record.*`,
+          // and bare field references all resolve, matching how
+          // record-change flows are authored.
+          record: payload,
+          params: { ...payload },
+          event: "api"
+        });
+      }).catch((err) => {
+        this.logger.warn(`[trigger-api] subscribe failed for '${queue}': ${err?.message ?? err}`);
+      });
+    }
+    if (!secret) {
+      this.logger.warn(
+        `[trigger-api] flow '${binding.flowName}' armed WITHOUT a secret \u2014 endpoint accepts unsigned posts`
+      );
+    }
+    this.logger.info(
+      `[trigger-api] armed: POST .../automation/hooks/${binding.flowName}/${hookId}${secret ? " (HMAC required)" : ""}`
+    );
+  }
+  stop(flowName) {
+    const hook = this.hooks.get(flowName);
+    if (!hook) return;
+    this.hooks.delete(flowName);
+    const q = this.getQueue();
+    if (q) void q.unsubscribe(hook.queue).catch(() => {
+    });
+    this.logger.info(`[trigger-api] disarmed: flow '${flowName}'`);
+  }
+  /**
+   * Handle one inbound request. Transport-agnostic: the plugin adapts this
+   * to the host HTTP server. Returns the response to send.
+   */
+  async handleRequest(input) {
+    const hook = this.hooks.get(input.flowName);
+    if (!hook || !safeEqual(hook.hookId, input.hookId)) {
+      return { status: 404, body: { error: "not_found" } };
+    }
+    if (hook.secret && !verifySignature(hook.secret, input.rawBody, input.signatureHeader)) {
+      return { status: 401, body: { error: "invalid_signature" } };
+    }
+    let payload;
+    try {
+      const parsed = input.rawBody.trim() ? JSON.parse(input.rawBody) : {};
+      if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { status: 400, body: { error: "invalid_body", message: "Body must be a JSON object." } };
+      }
+      payload = parsed;
+    } catch {
+      return { status: 400, body: { error: "invalid_body", message: "Body must be valid JSON." } };
+    }
+    const q = this.getQueue();
+    if (!q) {
+      return { status: 503, body: { error: "queue_unavailable", message: "No queue service is registered." } };
+    }
+    try {
+      const messageId = await q.publish(hook.queue, { payload }, {
+        idempotencyKey: input.idempotencyKey
+      });
+      return { status: 202, body: { accepted: true, messageId } };
+    } catch (err) {
+      this.logger.warn(`[trigger-api] enqueue failed for '${hook.queue}': ${err?.message ?? err}`);
+      return { status: 503, body: { error: "enqueue_failed" } };
+    }
+  }
+};
+
+// src/plugin.ts
+var HOOKS_PATH = "/api/v1/automation/hooks/:flowName/:hookId";
+var ApiTriggerPlugin = class {
+  constructor() {
+    this.name = "com.objectstack.trigger.api";
+    this.type = "standard";
+    this.version = "1.0.0";
+    this.dependencies = ["com.objectstack.service.queue"];
+  }
+  async init(ctx) {
+    ctx.logger.info("API trigger plugin initialized");
+  }
+  async start(ctx) {
+    ctx.hook("kernel:ready", async () => {
+      const automation = this.resolveService(ctx, "automation");
+      if (!automation || typeof automation.registerTrigger !== "function") {
+        ctx.logger.warn("ApiTriggerPlugin: automation service not available \u2014 api trigger NOT installed");
+        return;
+      }
+      if (!this.resolveService(ctx, "queue")) {
+        ctx.logger.warn("ApiTriggerPlugin: queue service not available \u2014 inbound posts will 503 until one is registered");
+      }
+      const trigger = new ApiTrigger(
+        () => this.resolveService(ctx, "queue"),
+        ctx.logger
+      );
+      automation.registerTrigger(trigger);
+      const http = this.resolveService(ctx, "http-server");
+      const rawApp = http && typeof http.getRawApp === "function" ? http.getRawApp() : null;
+      if (!rawApp) {
+        ctx.logger.warn("ApiTriggerPlugin: HTTP server not available \u2014 hooks endpoint not mounted");
+        return;
+      }
+      rawApp.post(HOOKS_PATH, async (c) => {
+        const rawBody = await c.req.text();
+        const out = await trigger.handleRequest({
+          flowName: c.req.param("flowName"),
+          hookId: c.req.param("hookId"),
+          rawBody,
+          signatureHeader: c.req.header("x-objectstack-signature"),
+          idempotencyKey: c.req.header("x-idempotency-key") || void 0
+        });
+        return c.json(out.body, out.status);
+      });
+      ctx.logger.info(`ApiTriggerPlugin: api trigger registered, hooks mounted at POST ${HOOKS_PATH}`);
+    });
+  }
+  resolveService(ctx, name) {
+    try {
+      return ctx.getService(name) ?? null;
+    } catch {
+      return null;
+    }
+  }
+};
+export {
+  ApiTrigger,
+  ApiTriggerPlugin,
+  HOOKS_PATH,
+  verifySignature
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api-trigger.ts","../src/plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport { createHmac, timingSafeEqual } from 'node:crypto';\nimport type { AutomationContext } from '@objectstack/spec/contracts';\n\n/**\n * Structural mirror of the automation engine's `FlowTriggerBinding` — same\n * decoupling pattern as `trigger-schedule` / `trigger-record-change`: this\n * package never imports `service-automation`.\n */\nexport interface FlowTriggerBinding {\n    readonly flowName: string;\n    readonly object?: string;\n    readonly event?: string;\n    readonly condition?: string | { dialect?: string; source?: string; ast?: unknown };\n    readonly schedule?: unknown;\n    readonly config?: Record<string, unknown>;\n}\n\n/** Structural mirror of the engine's `FlowTrigger` extension point. */\nexport interface FlowTrigger {\n    readonly type: string;\n    start(binding: FlowTriggerBinding, callback: (ctx: AutomationContext) => Promise<void>): void;\n    stop(flowName: string): void;\n}\n\n/**\n * The slice of `IQueueService` this trigger needs. Boundary triggers MUST\n * ingest through the queue (ADR-0041 §5): inbound HTTP is the first event\n * source whose rate we don't control, and a slow flow execution may neither\n * drop nor block inbound events. At-least-once delivery; flows should be\n * authored idempotently (an `x-idempotency-key` header passes through to the\n * queue's dedup window).\n */\nexport interface QueueServiceSurface {\n    publish<T = unknown>(queue: string, data: T, options?: { idempotencyKey?: string }): Promise<string>;\n    subscribe<T = unknown>(queue: string, handler: (message: { data: T }) => Promise<void> | void): Promise<void>;\n    unsubscribe(queue: string): Promise<void>;\n}\n\n/** Minimal logger surface (matches core's `ctx.logger`). */\nexport interface TriggerLogger {\n    info(msg: string, ...args: unknown[]): void;\n    warn(msg: string, ...args: unknown[]): void;\n    debug?(msg: string, ...args: unknown[]): void;\n}\n\nconst QUEUE_PREFIX = 'flow-api';\n\n/** One armed inbound hook. */\ninterface ArmedHook {\n    flowName: string;\n    hookId: string;\n    secret?: string;\n    queue: string;\n    callback: (ctx: AutomationContext) => Promise<void>;\n}\n\n/** Constant-time string compare (length leak only). */\nfunction safeEqual(a: string, b: string): boolean {\n    const ab = Buffer.from(a, 'utf8');\n    const bb = Buffer.from(b, 'utf8');\n    if (ab.length !== bb.length) return false;\n    return timingSafeEqual(ab, bb);\n}\n\n/**\n * GitHub/Stripe-style HMAC verification: the sender computes\n * `sha256=<hex hmac of the raw body>` with the shared per-flow secret and\n * sends it as `x-objectstack-signature`.\n */\nexport function verifySignature(secret: string, rawBody: string, header: string | undefined): boolean {\n    if (!header) return false;\n    const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');\n    return safeEqual(expected, header.trim());\n}\n\n/**\n * `api` flow trigger (ADR-0041 Tier 1) — inbound webhook/HTTP.\n *\n * The engine binds every `type: 'api'` flow to this trigger; `start()` arms a\n * hook (URL path + optional HMAC secret from the start node's `config`) and\n * subscribes a queue consumer that runs the flow. The HTTP side\n * ({@link handleRequest}) validates and **enqueues** — it never executes the\n * flow in-band:\n *\n *   POST /api/v1/automation/hooks/:flowName/:hookId\n *     → 404 unknown flow / wrong hookId\n *     → 401 missing/bad HMAC signature (when the flow declares a `secret`)\n *     → 400 non-JSON body\n *     → 202 { accepted, messageId } — queued; a consumer executes the flow\n *\n * The JSON payload is exposed to the flow as the trigger record (`$record` /\n * `record.*`, fields flattened to bare references) plus `params` — the same\n * authoring surface record-change flows use.\n *\n * Start-node config keys:\n *   - `hookId`  — URL path token (default `'default'`); rotate it to revoke\n *                 old URLs without renaming the flow.\n *   - `secret`  — HMAC-SHA256 shared secret. Strongly recommended; without it\n *                 the endpoint accepts unsigned posts (the trigger logs a\n *                 warning at arm time).\n */\nexport class ApiTrigger implements FlowTrigger {\n    readonly type = 'api';\n\n    private hooks = new Map<string, ArmedHook>();\n\n    constructor(\n        private readonly getQueue: () => QueueServiceSurface | null,\n        private readonly logger: TriggerLogger,\n    ) {}\n\n    /** Currently armed hooks (for diagnostics/tests). */\n    listHooks(): Array<{ flowName: string; hookId: string; signed: boolean }> {\n        return [...this.hooks.values()].map(h => ({\n            flowName: h.flowName, hookId: h.hookId, signed: !!h.secret,\n        }));\n    }\n\n    start(binding: FlowTriggerBinding, callback: (ctx: AutomationContext) => Promise<void>): void {\n        const cfg = (binding.config ?? {}) as Record<string, unknown>;\n        const hookId = typeof cfg.hookId === 'string' && cfg.hookId.trim() ? cfg.hookId.trim() : 'default';\n        const secret = typeof cfg.secret === 'string' && cfg.secret.trim() ? cfg.secret.trim() : undefined;\n        const queue = `${QUEUE_PREFIX}:${binding.flowName}`;\n\n        const hook: ArmedHook = { flowName: binding.flowName, hookId, secret, queue, callback };\n        this.hooks.set(binding.flowName, hook);\n\n        const q = this.getQueue();\n        if (!q) {\n            this.logger.warn(\n                `[trigger-api] no queue service — inbound posts for flow '${binding.flowName}' will be rejected until one is registered`,\n            );\n        } else {\n            void q.subscribe<{ payload: Record<string, unknown> }>(queue, async (message) => {\n                const payload = (message?.data as any)?.payload ?? {};\n                await hook.callback({\n                    // The webhook body IS the trigger record: `$record`, `record.*`,\n                    // and bare field references all resolve, matching how\n                    // record-change flows are authored.\n                    record: payload,\n                    params: { ...payload },\n                    event: 'api',\n                } as AutomationContext);\n            }).catch((err: any) => {\n                this.logger.warn(`[trigger-api] subscribe failed for '${queue}': ${err?.message ?? err}`);\n            });\n        }\n\n        if (!secret) {\n            this.logger.warn(\n                `[trigger-api] flow '${binding.flowName}' armed WITHOUT a secret — endpoint accepts unsigned posts`,\n            );\n        }\n        this.logger.info(\n            `[trigger-api] armed: POST .../automation/hooks/${binding.flowName}/${hookId}${secret ? ' (HMAC required)' : ''}`,\n        );\n    }\n\n    stop(flowName: string): void {\n        const hook = this.hooks.get(flowName);\n        if (!hook) return;\n        this.hooks.delete(flowName);\n        const q = this.getQueue();\n        if (q) void q.unsubscribe(hook.queue).catch(() => { /* already gone */ });\n        this.logger.info(`[trigger-api] disarmed: flow '${flowName}'`);\n    }\n\n    /**\n     * Handle one inbound request. Transport-agnostic: the plugin adapts this\n     * to the host HTTP server. Returns the response to send.\n     */\n    async handleRequest(input: {\n        flowName: string;\n        hookId: string;\n        rawBody: string;\n        signatureHeader?: string;\n        idempotencyKey?: string;\n    }): Promise<{ status: number; body: Record<string, unknown> }> {\n        const hook = this.hooks.get(input.flowName);\n        // Unknown flow and wrong hookId answer identically — no oracle for\n        // probing which flows exist.\n        if (!hook || !safeEqual(hook.hookId, input.hookId)) {\n            return { status: 404, body: { error: 'not_found' } };\n        }\n        if (hook.secret && !verifySignature(hook.secret, input.rawBody, input.signatureHeader)) {\n            return { status: 401, body: { error: 'invalid_signature' } };\n        }\n\n        let payload: Record<string, unknown>;\n        try {\n            const parsed: unknown = input.rawBody.trim() ? JSON.parse(input.rawBody) : {};\n            if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n                return { status: 400, body: { error: 'invalid_body', message: 'Body must be a JSON object.' } };\n            }\n            payload = parsed as Record<string, unknown>;\n        } catch {\n            return { status: 400, body: { error: 'invalid_body', message: 'Body must be valid JSON.' } };\n        }\n\n        const q = this.getQueue();\n        if (!q) {\n            return { status: 503, body: { error: 'queue_unavailable', message: 'No queue service is registered.' } };\n        }\n        try {\n            const messageId = await q.publish(hook.queue, { payload }, {\n                idempotencyKey: input.idempotencyKey,\n            });\n            return { status: 202, body: { accepted: true, messageId } };\n        } catch (err: any) {\n            this.logger.warn(`[trigger-api] enqueue failed for '${hook.queue}': ${err?.message ?? err}`);\n            return { status: 503, body: { error: 'enqueue_failed' } };\n        }\n    }\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport { ApiTrigger } from './api-trigger.js';\nimport type { FlowTrigger, QueueServiceSurface } from './api-trigger.js';\n\n/**\n * The slice of the automation engine this plugin needs. Declared structurally\n * so the plugin does not take a build dependency on\n * `@objectstack/service-automation`.\n */\ninterface AutomationTriggerRegistry {\n    registerTrigger(trigger: FlowTrigger): void;\n    unregisterTrigger?(type: string): void;\n}\n\n/** The slice of the Hono host server this plugin needs. */\ninterface HttpServerSurface {\n    getRawApp(): {\n        post(path: string, handler: (c: any) => Promise<unknown> | unknown): void;\n    } | null;\n}\n\n/** Mount point for inbound hooks on the host HTTP server. */\nexport const HOOKS_PATH = '/api/v1/automation/hooks/:flowName/:hookId';\n\n/**\n * ApiTriggerPlugin (ADR-0041 Tier 1)\n *\n * Makes `type: 'api'` flows actually fire. The automation engine derives an\n * `api` binding from the flow; this plugin provides the concrete trigger:\n *\n *  - mounts `POST /api/v1/automation/hooks/:flowName/:hookId` on the host\n *    Hono app (resolved via the `http-server` service);\n *  - validates hookId + HMAC signature (`x-objectstack-signature`,\n *    GitHub/Stripe style, constant-time) against the flow's start-node\n *    config;\n *  - **enqueues** the payload (`queue` service) and ACKs 202 — flow\n *    execution happens on the queue consumer, never in-band with the\n *    inbound request (ADR-0041 §5: boundary triggers must not let a slow\n *    flow drop or block events). `x-idempotency-key` passes through to the\n *    queue's dedup window.\n *\n * Webhook payloads surface to the flow as the trigger record (`$record` /\n * `record.*` / bare field references) — the same authoring surface\n * record-change flows use.\n */\nexport class ApiTriggerPlugin implements Plugin {\n    name = 'com.objectstack.trigger.api';\n    type = 'standard';\n    version = '1.0.0';\n    dependencies = ['com.objectstack.service.queue'];\n\n    async init(ctx: PluginContext): Promise<void> {\n        ctx.logger.info('API trigger plugin initialized');\n    }\n\n    async start(ctx: PluginContext): Promise<void> {\n        // Resolve at kernel:ready — the automation engine, queue service, and\n        // HTTP server may all start after this plugin.\n        ctx.hook('kernel:ready', async () => {\n            const automation = this.resolveService<AutomationTriggerRegistry>(ctx, 'automation');\n            if (!automation || typeof automation.registerTrigger !== 'function') {\n                ctx.logger.warn('ApiTriggerPlugin: automation service not available — api trigger NOT installed');\n                return;\n            }\n            if (!this.resolveService<QueueServiceSurface>(ctx, 'queue')) {\n                ctx.logger.warn('ApiTriggerPlugin: queue service not available — inbound posts will 503 until one is registered');\n            }\n\n            const trigger = new ApiTrigger(\n                () => this.resolveService<QueueServiceSurface>(ctx, 'queue'),\n                ctx.logger,\n            );\n            automation.registerTrigger(trigger);\n\n            const http = this.resolveService<HttpServerSurface>(ctx, 'http-server');\n            const rawApp = http && typeof http.getRawApp === 'function' ? http.getRawApp() : null;\n            if (!rawApp) {\n                ctx.logger.warn('ApiTriggerPlugin: HTTP server not available — hooks endpoint not mounted');\n                return;\n            }\n            rawApp.post(HOOKS_PATH, async (c: any) => {\n                const rawBody = await c.req.text();\n                const out = await trigger.handleRequest({\n                    flowName: c.req.param('flowName'),\n                    hookId: c.req.param('hookId'),\n                    rawBody,\n                    signatureHeader: c.req.header('x-objectstack-signature'),\n                    idempotencyKey: c.req.header('x-idempotency-key') || undefined,\n                });\n                return c.json(out.body, out.status);\n            });\n            ctx.logger.info(`ApiTriggerPlugin: api trigger registered, hooks mounted at POST ${HOOKS_PATH}`);\n        });\n    }\n\n    private resolveService<T>(ctx: PluginContext, name: string): T | null {\n        try {\n            return ctx.getService<T>(name) ?? null;\n        } catch {\n            return null;\n        }\n    }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@objectstack/trigger-api",
+  "version": "9.3.0",
+  "license": "Apache-2.0",
+  "description": "Inbound HTTP/webhook flow trigger for ObjectStack — per-flow HMAC-verified endpoints with queue-backed ingestion (ADR-0041)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@objectstack/core": "9.3.0",
+    "@objectstack/spec": "9.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "keywords": [
+    "objectstack",
+    "trigger",
+    "webhook",
+    "automation"
+  ],
+  "scripts": {
+    "build": "tsup --config ../../../tsup.config.ts",
+    "test": "vitest run --passWithNoTests"
+  }
+}