nvent 0.4.4 → 0.5.0

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/nitro/utils/adapters.d.ts

@@ -0,0 +1,66 @@
+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;
+}
+/**
+ * Set the global adapter set (called by plugin during initialization)
+ */
+export declare function setAdapters(adapters: AdapterSet): void;
+/**
+ * Get all adapters (internal use)
+ */
+export declare function getAdapters(): AdapterSet;
+/**
+ * Access QueueAdapter for job queue operations
+ *
+ * @example
+ * const queue = useQueueAdapter()
+ * await queue.enqueue('my-queue', { name: 'job', data: {...} })
+ */
+export declare function useQueueAdapter(): QueueAdapter;
+/**
+ * Access StreamAdapter for cross-instance pub/sub
+ *
+ * @example
+ * const stream = useStreamAdapter()
+ * await stream.subscribe('store:append:*', (event) => {
+ *   console.log('Remote update:', event)
+ * })
+ */
+export declare function useStreamAdapter(): StreamAdapter;
+/**
+ * Access StoreAdapter for storage operations
+ *
+ * @example
+ * const store = useStoreAdapter()
+ * 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;
+/**
+ * State provider interface for flow state management
+ */
+export interface StateAdapter {
+    get<T = any>(key: string): Promise<T | null>;
+    set<T = any>(key: string, value: T, opts?: {
+        ttl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(pattern: string): Promise<number>;
+    increment?: (key: string, by?: number) => Promise<number>;
+}
+/**
+ * Access StateAdapter for scoped key-value state storage
+ *
+ * State is backed by StoreAdapter's KV store with automatic namespacing.
+ * Used by worker context (ctx.state) for flow-scoped state management.
+ *
+ * @example
+ * const state = useStateAdapter()
+ * await state.set('lastEmail', { to: 'user@example.com' })
+ * const value = await state.get('lastEmail')
+ */
+export declare function useStateAdapter(): StateAdapter;

package/dist/runtime/nitro/utils/adapters.js

@@ -0,0 +1,51 @@
+import { useRuntimeConfig } from "#imports";
+export function setAdapters(adapters) {
+  globalThis.__nq_adapters = adapters;
+}
+export function getAdapters() {
+  if (!globalThis.__nq_adapters) {
+    throw new Error("[nvent] Adapters not initialized. Make sure the nvent plugin is loaded.");
+  }
+  return globalThis.__nq_adapters;
+}
+export function useQueueAdapter() {
+  return getAdapters().queue;
+}
+export function useStreamAdapter() {
+  return getAdapters().stream;
+}
+export function useStoreAdapter() {
+  return getAdapters().store;
+}
+export function useStateAdapter() {
+  const store = useStoreAdapter();
+  let namespace = "nq";
+  try {
+    const rc = useRuntimeConfig();
+    namespace = rc?.nvent?.state?.namespace || "nq";
+  } catch {
+  }
+  return {
+    async get(key) {
+      return store.kv.get(`${namespace}:${key}`);
+    },
+    async set(key, value, opts) {
+      await store.kv.set(`${namespace}:${key}`, value, opts?.ttl);
+    },
+    async delete(key) {
+      await store.kv.delete(`${namespace}:${key}`);
+    },
+    async clear(pattern) {
+      if (!store.kv.clear) {
+        throw new Error("Store adapter does not support clear operation");
+      }
+      return store.kv.clear(`${namespace}:${pattern}`);
+    },
+    increment: store.kv.increment ? async (key, by = 1) => {
+      if (!store.kv.increment) {
+        throw new Error("Store adapter does not support increment operation");
+      }
+      return store.kv.increment(`${namespace}:${key}`, by);
+    } : void 0
+  };
+}

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>;

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

@@ -0,0 +1,78 @@
+import { useNventLogger, useScheduler } from "#imports";
+import { getEventBus } from "../../../events/eventBus.js";
+import { CronJob } from "cron";
+export async function registerScheduleAwait(runId, stepName, flowName, config, position = "after") {
+  const logger = useNventLogger("await-schedule");
+  const eventBus = getEventBus();
+  const scheduler = useScheduler();
+  if (!config.cron) {
+    throw new Error("Schedule await requires cron expression configuration");
+  }
+  logger.info(`Registering schedule await: ${config.cron}`, { runId, stepName });
+  const cronJob = new CronJob(config.cron, () => {
+  }, null, false, config.timezone || "UTC");
+  const nextDate = cronJob.nextDate();
+  const nextOccurrence = nextDate ? nextDate.toMillis() : Date.now() + 6e4;
+  const timeUntilNext = nextOccurrence - Date.now();
+  const jobId = `await-schedule-${runId}-${stepName}-${position}`;
+  await scheduler.schedule({
+    id: jobId,
+    name: `Schedule Await: ${flowName} - ${stepName}`,
+    type: "one-time",
+    executeAt: nextOccurrence,
+    handler: async () => {
+      await resolveScheduleAwait(runId, stepName, flowName, position, { scheduledAt: nextOccurrence });
+    },
+    metadata: {
+      component: "await-pattern",
+      awaitType: "schedule",
+      runId,
+      stepName,
+      flowName,
+      position,
+      cron: config.cron,
+      timezone: config.timezone
+    }
+  });
+  eventBus.publish({
+    type: "await.registered",
+    flowName,
+    runId,
+    stepName,
+    awaitType: "schedule",
+    position,
+    config,
+    data: {
+      cron: config.cron,
+      nextOccurrence,
+      timeUntilNext,
+      registeredAt: Date.now()
+    }
+  });
+  logger.debug(`Schedule await registered: ${config.cron} (next: ${new Date(nextOccurrence).toISOString()})`, {
+    runId,
+    stepName
+  });
+  return {
+    cron: config.cron,
+    nextOccurrence,
+    timeUntilNext
+  };
+}
+export async function resolveScheduleAwait(runId, stepName, flowName, position, scheduleData) {
+  const logger = useNventLogger("await-schedule");
+  const eventBus = getEventBus();
+  logger.info(`Resolving schedule await`, { runId, stepName });
+  eventBus.publish({
+    type: "await.resolved",
+    flowName,
+    runId,
+    stepName,
+    position,
+    triggerData: scheduleData,
+    data: {
+      resolvedAt: Date.now()
+    }
+  });
+  logger.debug(`Schedule await resolved`, { runId, stepName });
+}

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

@@ -0,0 +1,15 @@
+import type { AwaitConfig } from '../../../../registry/types.js';
+/**
+ * Await Pattern: Time
+ *
+ * Simple delay/timeout - waits for a specific duration
+ * Useful for cooldown periods, rate limiting, delayed notifications
+ */
+export declare function registerTimeAwait(runId: string, stepName: string, flowName: string, config: AwaitConfig, position?: 'before' | 'after'): Promise<{
+    delay: number;
+    resolveAt: number;
+}>;
+/**
+ * Resolve time await when delay completes
+ */
+export declare function resolveTimeAwait(runId: string, stepName: string, flowName: string, position: 'before' | 'after', timeData: any): Promise<void>;