nvent 0.4.5 → 0.5.1

package/dist/runtime/{server → nitro}/plugins/02.workers.js

@@ -1,4 +1,4 @@
-import { defineNitroPlugin, $useWorkerHandlers, $useQueueRegistry, useQueueAdapter } from "#imports";
+import { defineNitroPlugin, $useWorkerHandlers, $useFunctionRegistry, useQueueAdapter, useHookRegistry } from "#imports";
 import { createJobProcessor } from "../../worker/node/runner.js";
 export default defineNitroPlugin(async (nitroApp) => {
   nitroApp.hooks.hook("close", async () => {
@@ -9,10 +9,10 @@ export default defineNitroPlugin(async (nitroApp) => {
     const queueAdapter = useQueueAdapter();
     try {
       const handlers = $useWorkerHandlers();
-      const registry = $useQueueRegistry() || { workers: [] };
+      const registry = $useFunctionRegistry() || { workers: [] };
       const registeredQueues = /* @__PURE__ */ new Set();
       for (const entry of handlers) {
-        const { queue, id, handler } = entry;
+        const { queue, id, handler, module } = entry;
         const w = registry.workers.find((rw) => rw?.id === id || rw?.queue?.name === queue && rw?.absPath === entry.absPath);
         let jobName;
         if (w?.flow?.step) {
@@ -20,6 +20,24 @@ export default defineNitroPlugin(async (nitroApp) => {
         } else {
           jobName = id.includes("/") ? id.split("/").pop() : id;
         }
+        if (module && w?.flow) {
+          const hooks = {};
+          if (typeof module.onAwaitRegister === "function") {
+            hooks.onAwaitRegister = module.onAwaitRegister;
+          }
+          if (typeof module.onAwaitResolve === "function") {
+            hooks.onAwaitResolve = module.onAwaitResolve;
+          }
+          if (Object.keys(hooks).length > 0) {
+            const hookRegistry = useHookRegistry();
+            const flowNames = w.flow.names ? Array.isArray(w.flow.names) ? w.flow.names : [w.flow.names] : w.flow.name ? Array.isArray(w.flow.name) ? w.flow.name : [w.flow.name] : [];
+            for (const flowName of flowNames) {
+              if (flowName) {
+                hookRegistry.register(flowName, jobName, hooks);
+              }
+            }
+          }
+        }
         if (typeof handler === "function") {
           const workerCfg = w && w.worker || {};
           const queueCfg = w && w.queue || {};

package/dist/runtime/nitro/plugins/03.triggers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Trigger Registration Plugin
+ *
+ * Loads pre-analyzed triggers and subscriptions from build-time registry
+ * and registers them via event bus (trigger.registered events).
+ * The trigger wiring will handle the actual registration logic.
+ *
+ * This plugin is ONLY for registering dev/build-time discovered triggers.
+ * Trigger wiring and event handling is done in the wiring registry.
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/nitro/plugins/03.triggers.js

@@ -0,0 +1,55 @@
+import { defineNitroPlugin, $useTriggerRegistry, useNventLogger, useTrigger } from "#imports";
+import { getEventBus } from "../../events/eventBus.js";
+export default defineNitroPlugin(async (nitroApp) => {
+  nitroApp.hooks.hook("nvent:adapters:ready", async () => {
+    const logger = useNventLogger("trigger-registration");
+    const eventBus = getEventBus();
+    const trigger = useTrigger();
+    try {
+      logger.info("Registering build-time triggers...");
+      const triggerRegistry = $useTriggerRegistry();
+      const subscriptions = triggerRegistry?.subscriptions || [];
+      const triggers = triggerRegistry?.triggers || [];
+      logger.info(`Found ${triggers.length} triggers and ${subscriptions.length} subscriptions from build`);
+      let newTriggers = 0;
+      for (const triggerData of triggers) {
+        if (!trigger.hasTrigger(triggerData.name)) {
+          await eventBus.publish({
+            type: "trigger.registered",
+            triggerName: triggerData.name,
+            data: triggerData
+          });
+          newTriggers++;
+        } else {
+          logger.debug(`Trigger '${triggerData.name}' already registered, skipping`);
+        }
+      }
+      let newSubscriptions = 0;
+      for (const sub of subscriptions) {
+        const existing = trigger.getSubscription(sub.triggerName, sub.flowName);
+        if (!existing) {
+          await eventBus.publish({
+            type: "subscription.added",
+            triggerName: sub.triggerName,
+            data: {
+              trigger: sub.triggerName,
+              flow: sub.flowName,
+              mode: sub.mode,
+              source: "build-time"
+            }
+          });
+          newSubscriptions++;
+        } else {
+          logger.debug(`Subscription '${sub.flowName}' -> '${sub.triggerName}' already exists, skipping`);
+        }
+      }
+      logger.info(
+        `Build-time trigger registration complete (${newTriggers} new triggers, ${newSubscriptions} new subscriptions)`
+      );
+    } catch (error) {
+      logger.error("Failed to register build-time triggers", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  });
+});

package/dist/runtime/nitro/routes/webhook.await.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Dynamic webhook handler for await patterns
+ * Handles webhook calls and resolves awaiting steps
+ *
+ * Routes:
+ * - POST /api/_webhook/await/{flowName}/{runId}/{stepName}
+ * - GET /api/_webhook/await/{flowName}/{runId}/{stepName}
+ *
+ * Architecture:
+ * 1. Parse URL params to get flowName, runId, stepName
+ * 2. Look up flow in store index to verify it exists and is awaiting
+ * 3. Verify flow status and await configuration
+ * 4. Use useAwait().webhook.resolve() which publishes await.resolved event
+ * 5. Trigger wiring handles the actual flow resumption
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
+    success: boolean;
+    runId: string;
+    stepName: string;
+    flowName: string;
+    message: string;
+}>>;
+export default _default;

package/dist/runtime/nitro/routes/webhook.await.js

@@ -0,0 +1,90 @@
+import { defineEventHandler, readBody, getRouterParams, createError, setResponseStatus } from "h3";
+import { useStoreAdapter, useStreamTopics, useNventLogger, useAwait } from "#imports";
+export default defineEventHandler(async (event) => {
+  const logger = useNventLogger("webhook-handler");
+  const store = useStoreAdapter();
+  const await$ = useAwait();
+  const { StoreSubjects } = useStreamTopics();
+  const params = getRouterParams(event);
+  const flowName = params.flowName;
+  const runId = params.runId;
+  const stepName = params.stepName;
+  if (!flowName || !runId || !stepName) {
+    logger.warn("Missing required webhook parameters", { params });
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Invalid webhook path",
+      message: "Webhook path must include flowName, runId, and stepName"
+    });
+  }
+  logger.info(`Webhook received: ${event.method} for ${flowName}/${runId}/${stepName}`);
+  const indexKey = StoreSubjects.flowRunIndex(flowName);
+  const flowEntry = await store.index.get?.(indexKey, runId);
+  if (!flowEntry) {
+    logger.warn(`Flow not found`, { flowName, runId, stepName });
+    setResponseStatus(event, 404);
+    throw createError({
+      statusCode: 404,
+      statusMessage: "Flow not found",
+      message: "The flow associated with this webhook no longer exists."
+    });
+  }
+  const status = flowEntry.metadata?.status;
+  if (status && status !== "running") {
+    logger.warn(`Flow is not running`, { flowName, runId, stepName, status });
+    setResponseStatus(event, 410);
+    throw createError({
+      statusCode: 410,
+      statusMessage: `Flow is ${status}`,
+      message: `This webhook is no longer valid because the flow is ${status}.`
+    });
+  }
+  const awaitState = flowEntry.metadata?.awaitingSteps?.[stepName];
+  if (!awaitState || awaitState.status !== "awaiting") {
+    logger.warn(`Step is not awaiting`, { flowName, runId, stepName, awaitState });
+    setResponseStatus(event, 410);
+    throw createError({
+      statusCode: 410,
+      statusMessage: "Step is not awaiting",
+      message: "This webhook has already been called or the await has expired."
+    });
+  }
+  if (awaitState.awaitType !== "webhook") {
+    logger.warn(`Step is not waiting for webhook`, { flowName, runId, stepName, awaitType: awaitState.awaitType });
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Invalid await type",
+      message: `This step is waiting for ${awaitState.awaitType}, not a webhook.`
+    });
+  }
+  const expectedMethod = awaitState.config?.method || "POST";
+  if (event.method !== expectedMethod) {
+    logger.warn(`Method mismatch: expected ${expectedMethod}, got ${event.method}`, { flowName, runId, stepName });
+    throw createError({
+      statusCode: 405,
+      statusMessage: "Method Not Allowed",
+      message: `This webhook expects ${expectedMethod} requests.`
+    });
+  }
+  const position = awaitState.position || "after";
+  let webhookData;
+  if (event.method === "GET") {
+    webhookData = getRouterParams(event, { decode: true });
+  } else {
+    webhookData = await readBody(event).catch(() => ({}));
+  }
+  logger.debug(`Webhook data received`, {
+    runId,
+    stepName,
+    dataKeys: Object.keys(webhookData || {})
+  });
+  await await$.webhook.resolve(runId, stepName, flowName, position, webhookData);
+  logger.info(`Webhook await resolved`, { flowName, runId, stepName });
+  return {
+    success: true,
+    runId,
+    stepName,
+    flowName,
+    message: "Webhook processed successfully. Flow will resume shortly."
+  };
+});

package/dist/runtime/nitro/routes/webhook.trigger.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Dynamic webhook trigger handler for entry triggers (flow-scoped)
+ * Receives webhook calls and fires triggers to start flows
+ *
+ * Routes:
+ * - POST /api/_webhook/trigger/{triggerName}
+ * - GET /api/_webhook/trigger/{triggerName}
+ *
+ * Different from await webhooks:
+ * - Entry triggers are flow-scoped (start new flow runs)
+ * - Await webhooks are run-scoped (resume specific steps)
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
+    error: string;
+    message: string;
+    triggerName?: undefined;
+    expectedType?: undefined;
+    actualType?: undefined;
+    expectedMethod?: undefined;
+    actualMethod?: undefined;
+    success?: undefined;
+    subscribedFlows?: undefined;
+    timestamp?: undefined;
+} | {
+    error: string;
+    triggerName: string;
+    message: string;
+    expectedType?: undefined;
+    actualType?: undefined;
+    expectedMethod?: undefined;
+    actualMethod?: undefined;
+    success?: undefined;
+    subscribedFlows?: undefined;
+    timestamp?: undefined;
+} | {
+    error: string;
+    triggerName: string;
+    expectedType: string;
+    actualType: any;
+    message?: undefined;
+    expectedMethod?: undefined;
+    actualMethod?: undefined;
+    success?: undefined;
+    subscribedFlows?: undefined;
+    timestamp?: undefined;
+} | {
+    error: string;
+    expectedMethod: any;
+    actualMethod: import("h3").HTTPMethod;
+    message?: undefined;
+    triggerName?: undefined;
+    expectedType?: undefined;
+    actualType?: undefined;
+    success?: undefined;
+    subscribedFlows?: undefined;
+    timestamp?: undefined;
+} | {
+    success: boolean;
+    triggerName: string;
+    subscribedFlows: any;
+    message: string;
+    timestamp: string;
+    error?: undefined;
+    expectedType?: undefined;
+    actualType?: undefined;
+    expectedMethod?: undefined;
+    actualMethod?: undefined;
+}>>;
+export default _default;

package/dist/runtime/nitro/routes/webhook.trigger.js

@@ -0,0 +1,64 @@
+import { defineEventHandler, readBody } from "h3";
+import { useNventLogger, useTrigger } from "#imports";
+export default defineEventHandler(async (event) => {
+  const logger = useNventLogger("webhook-trigger");
+  const trigger = useTrigger();
+  const triggerName = event.context.params?.triggerName;
+  if (!triggerName) {
+    logger.warn("No trigger name provided in request");
+    return {
+      error: "Missing trigger name",
+      message: "Trigger name is required"
+    };
+  }
+  logger.info(`Webhook trigger received: ${event.method} ${triggerName}`);
+  const triggerEntry = trigger.getTrigger(triggerName);
+  if (!triggerEntry) {
+    logger.warn(`Trigger not found: ${triggerName}`);
+    return {
+      error: "Trigger not found",
+      triggerName,
+      message: `No trigger registered with name '${triggerName}'`
+    };
+  }
+  if (triggerEntry.type !== "webhook") {
+    logger.warn(`Trigger is not a webhook: ${triggerName} (type: ${triggerEntry.type})`);
+    return {
+      error: "Invalid trigger type",
+      triggerName,
+      expectedType: "webhook",
+      actualType: triggerEntry.type
+    };
+  }
+  const expectedMethod = triggerEntry.webhook?.method || "POST";
+  if (event.method !== expectedMethod) {
+    logger.warn(`Method mismatch: expected ${expectedMethod}, got ${event.method}`);
+    return {
+      error: "Method not allowed",
+      expectedMethod,
+      actualMethod: event.method
+    };
+  }
+  let webhookData;
+  if (event.method === "GET") {
+    webhookData = event.context.params || {};
+  } else {
+    webhookData = await readBody(event);
+  }
+  logger.debug(`Webhook data received`, {
+    triggerName,
+    dataKeys: Object.keys(webhookData || {})
+  });
+  await trigger.emitTrigger(triggerName, webhookData);
+  logger.info(`Webhook trigger fired`, {
+    triggerName,
+    subscribedFlows: trigger.getSubscribedFlows(triggerName).length
+  });
+  return {
+    success: true,
+    triggerName,
+    subscribedFlows: trigger.getSubscribedFlows(triggerName),
+    message: "Trigger fired successfully",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+});

package/dist/runtime/{utils → nitro/utils}/adapters.d.ts

@@ -1,7 +1,7 @@
-import type { QueueAdapter } from '../adapters/interfaces/queue.js';
-import type { StreamAdapter } from '../adapters/interfaces/stream.js';
-import type { StoreAdapter } from '../adapters/interfaces/store.js';
-import type { AdapterSet } from '../adapters/factory.js';
+import type { QueueAdapter } from '../../adapters/interfaces/queue.js';
+import type { StreamAdapter } from '../../adapters/interfaces/stream.js';
+import type { StoreAdapter } from '../../adapters/interfaces/store.js';
+import type { AdapterSet } from '../../adapters/factory.js';
 declare global {
     var __nq_adapters: AdapterSet | undefined;
 }
@@ -36,8 +36,8 @@ export declare function useStreamAdapter(): StreamAdapter;
  *
  * @example
  * const store = useStoreAdapter()
- * await store.append('nq:flow:abc-123', { type: 'step.completed', data: {...} })
- * const events = await store.read('nq:flow:abc-123')
+ * await store.stream.append('nq:flow:abc-123', { type: 'step.completed', data: {...} })
+ * const events = await store.stream.read('nq:flow:abc-123')
  */
 export declare function useStoreAdapter(): StoreAdapter;
 /**

package/dist/runtime/nitro/utils/awaitPatterns/event.d.ts

@@ -0,0 +1,15 @@
+import type { AwaitConfig } from '../../../../registry/types.js';
+/**
+ * Await Pattern: Event
+ *
+ * Waits for a specific event to be emitted (internal or external)
+ * Useful for cross-flow coordination, external system notifications
+ */
+export declare function registerEventAwait(runId: string, stepName: string, flowName: string, config: AwaitConfig, position?: 'before' | 'after'): Promise<{
+    eventName: string;
+    timeout: number | undefined;
+}>;
+/**
+ * Resolve event await when target event is received
+ */
+export declare function resolveEventAwait(runId: string, stepName: string, flowName: string, position: 'before' | 'after', eventData: any): Promise<void>;

package/dist/runtime/nitro/utils/awaitPatterns/event.js

@@ -0,0 +1,120 @@
+import { useNventLogger, useScheduler } from "#imports";
+import { getEventBus } from "../../../events/eventBus.js";
+export async function registerEventAwait(runId, stepName, flowName, config, position = "after") {
+  const logger = useNventLogger("await-event");
+  const eventBus = getEventBus();
+  if (!config.event) {
+    throw new Error("Event await requires event name configuration");
+  }
+  logger.info(`Registering event await: ${config.event}`, { runId, stepName });
+  const unsubscribe = eventBus.onType(config.event, async (event) => {
+    if (config.filterKey) {
+      const awaitValue = event.data?.[config.filterKey];
+      const stepValue = event.data?.stepData?.[config.filterKey];
+      if (awaitValue !== stepValue) {
+        return;
+      }
+    }
+    await resolveEventAwait(runId, stepName, flowName, position, event.data);
+    unsubscribe();
+  });
+  eventBus.publish({
+    type: "await.registered",
+    flowName,
+    runId,
+    stepName,
+    awaitType: "event",
+    position,
+    config,
+    data: {
+      eventName: config.event,
+      filterKey: config.filterKey,
+      timeout: config.timeout,
+      registeredAt: Date.now()
+    }
+  });
+  if (config.timeout && config.timeout > 0) {
+    const scheduler = useScheduler();
+    const timeoutAt = Date.now() + config.timeout;
+    const jobId = `await-event-timeout-${runId}-${stepName}-${position}`;
+    await scheduler.schedule({
+      id: jobId,
+      name: `Event Await Timeout: ${flowName} - ${stepName}`,
+      type: "one-time",
+      executeAt: timeoutAt,
+      handler: async () => {
+        logger.warn("Event await timeout", {
+          runId,
+          stepName,
+          flowName,
+          eventName: config.event,
+          timeout: config.timeout,
+          timeoutAction: config.timeoutAction || "fail"
+        });
+        eventBus.publish({
+          type: "await.timeout",
+          flowName,
+          runId,
+          stepName,
+          position,
+          awaitType: "event",
+          timeoutAction: config.timeoutAction || "fail",
+          data: {
+            eventName: config.event,
+            timeout: config.timeout,
+            registeredAt: Date.now() - (config.timeout || 0),
+            timedOutAt: Date.now()
+          }
+        });
+        unsubscribe();
+      },
+      metadata: {
+        component: "await-pattern",
+        awaitType: "event",
+        runId,
+        stepName,
+        flowName,
+        position,
+        timeout: config.timeout,
+        eventName: config.event
+      }
+    });
+    logger.debug(`Event timeout scheduled`, {
+      runId,
+      stepName,
+      eventName: config.event,
+      timeout: config.timeout,
+      timeoutAction: config.timeoutAction
+    });
+  }
+  logger.debug(`Event await registered: ${config.event}`, { runId, stepName });
+  return {
+    eventName: config.event,
+    timeout: config.timeout
+  };
+}
+export async function resolveEventAwait(runId, stepName, flowName, position, eventData) {
+  const logger = useNventLogger("await-event");
+  const eventBus = getEventBus();
+  const scheduler = useScheduler();
+  logger.info(`Resolving event await`, { runId, stepName });
+  const jobId = `await-event-timeout-${runId}-${stepName}-${position}`;
+  try {
+    await scheduler.unschedule(jobId);
+    logger.debug("Unscheduled event timeout job", { runId, stepName, jobId });
+  } catch {
+    logger.debug("Could not unschedule timeout job (may not exist)", { runId, stepName, jobId });
+  }
+  eventBus.publish({
+    type: "await.resolved",
+    flowName,
+    runId,
+    stepName,
+    position,
+    triggerData: eventData,
+    data: {
+      resolvedAt: Date.now()
+    }
+  });
+  logger.debug(`Event await resolved`, { runId, stepName });
+}

package/dist/runtime/nitro/utils/awaitPatterns/index.d.ts

@@ -0,0 +1,28 @@
+import type { AwaitConfig } from '../../../../registry/types.js';
+import { registerWebhookAwait, resolveWebhookAwait } from './webhook.js';
+import { registerEventAwait, resolveEventAwait } from './event.js';
+import { registerScheduleAwait, resolveScheduleAwait } from './schedule.js';
+import { registerTimeAwait, resolveTimeAwait } from './time.js';
+/**
+ * Unified await pattern registry
+ * Routes to appropriate await implementation based on type
+ */
+export declare function registerAwaitPattern(runId: string, stepName: string, flowName: string, config: AwaitConfig, position?: 'before' | 'after'): Promise<{
+    delay: number;
+    resolveAt: number;
+} | {
+    cron: string;
+    nextOccurrence: number;
+    timeUntilNext: number;
+} | {
+    webhookUrl: string;
+    timeout: number | undefined;
+} | {
+    eventName: string;
+    timeout: number | undefined;
+}>;
+/**
+ * Resolve await pattern by type
+ */
+export declare function resolveAwaitPattern(type: 'webhook' | 'event' | 'schedule' | 'time', runId: string, stepName: string, flowName: string, position: 'before' | 'after', data: any): Promise<void>;
+export { registerWebhookAwait, resolveWebhookAwait, registerEventAwait, resolveEventAwait, registerScheduleAwait, resolveScheduleAwait, registerTimeAwait, resolveTimeAwait, };

package/dist/runtime/nitro/utils/awaitPatterns/index.js

@@ -0,0 +1,55 @@
+import { useNventLogger } from "#imports";
+import { registerWebhookAwait, resolveWebhookAwait } from "./webhook.js";
+import { registerEventAwait, resolveEventAwait } from "./event.js";
+import { registerScheduleAwait, resolveScheduleAwait } from "./schedule.js";
+import { registerTimeAwait, resolveTimeAwait } from "./time.js";
+export async function registerAwaitPattern(runId, stepName, flowName, config, position = "after") {
+  const logger = useNventLogger("await-patterns");
+  logger.info(`Registering await pattern: ${config.type}`, {
+    runId,
+    stepName,
+    type: config.type
+  });
+  switch (config.type) {
+    case "webhook":
+      return await registerWebhookAwait(runId, stepName, flowName, config, position);
+    case "event":
+      return await registerEventAwait(runId, stepName, flowName, config, position);
+    case "schedule":
+      return await registerScheduleAwait(runId, stepName, flowName, config, position);
+    case "time":
+      return await registerTimeAwait(runId, stepName, flowName, config, position);
+    default:
+      throw new Error(`Unknown await pattern type: ${config.type}`);
+  }
+}
+export async function resolveAwaitPattern(type, runId, stepName, flowName, position, data) {
+  const logger = useNventLogger("await-patterns");
+  logger.info(`Resolving await pattern: ${type}`, {
+    runId,
+    stepName,
+    type
+  });
+  switch (type) {
+    case "webhook":
+      return await resolveWebhookAwait(runId, stepName, data);
+    case "event":
+      return await resolveEventAwait(runId, stepName, data);
+    case "schedule":
+      return await resolveScheduleAwait(runId, stepName, data);
+    case "time":
+      return await resolveTimeAwait(runId, stepName, flowName, position, data);
+    default:
+      throw new Error(`Unknown await pattern type: ${type}`);
+  }
+}
+export {
+  registerWebhookAwait,
+  resolveWebhookAwait,
+  registerEventAwait,
+  resolveEventAwait,
+  registerScheduleAwait,
+  resolveScheduleAwait,
+  registerTimeAwait,
+  resolveTimeAwait
+};

package/dist/runtime/nitro/utils/awaitPatterns/schedule.d.ts

@@ -0,0 +1,16 @@
+import type { AwaitConfig } from '../../../../registry/types.js';
+/**
+ * Await Pattern: Schedule
+ *
+ * Waits until next cron schedule occurrence
+ * Useful for batch processing, daily reports, scheduled operations
+ */
+export declare function registerScheduleAwait(runId: string, stepName: string, flowName: string, config: AwaitConfig, position?: 'before' | 'after'): Promise<{
+    cron: string;
+    nextOccurrence: number;
+    timeUntilNext: number;
+}>;
+/**
+ * Resolve schedule await when cron time is reached
+ */
+export declare function resolveScheduleAwait(runId: string, stepName: string, flowName: string, position: 'before' | 'after', scheduleData: any): Promise<void>;