nvent 0.4.5 → 0.5.0

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

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

@@ -0,0 +1,67 @@
+import { useNventLogger, useScheduler } from "#imports";
+import { getEventBus } from "../../../events/eventBus.js";
+export async function registerTimeAwait(runId, stepName, flowName, config, position = "after") {
+  const logger = useNventLogger("await-time");
+  const eventBus = getEventBus();
+  const scheduler = useScheduler();
+  if (!config.delay) {
+    throw new Error("Time await requires delay configuration (in milliseconds)");
+  }
+  logger.info(`Registering time await: ${config.delay}ms`, { runId, stepName });
+  const resolveAt = Date.now() + config.delay;
+  const jobId = `await-time-${runId}-${stepName}-${position}`;
+  await scheduler.schedule({
+    id: jobId,
+    name: `Time Await: ${flowName} - ${stepName}`,
+    type: "one-time",
+    executeAt: resolveAt,
+    handler: async () => {
+      await resolveTimeAwait(runId, stepName, flowName, position, { delayCompleted: true });
+    },
+    metadata: {
+      component: "await-pattern",
+      awaitType: "time",
+      runId,
+      stepName,
+      flowName,
+      position,
+      delay: config.delay
+    }
+  });
+  eventBus.publish({
+    type: "await.registered",
+    flowName,
+    runId,
+    stepName,
+    awaitType: "time",
+    position,
+    config,
+    data: {
+      delay: config.delay,
+      resolveAt,
+      registeredAt: Date.now()
+    }
+  });
+  logger.debug(`Time await registered: ${config.delay}ms`, { runId, stepName });
+  return {
+    delay: config.delay,
+    resolveAt
+  };
+}
+export async function resolveTimeAwait(runId, stepName, flowName, position, timeData) {
+  const logger = useNventLogger("await-time");
+  const eventBus = getEventBus();
+  logger.info(`Resolving time await`, { runId, stepName });
+  eventBus.publish({
+    type: "await.resolved",
+    flowName,
+    runId,
+    stepName,
+    position,
+    triggerData: timeData,
+    data: {
+      resolvedAt: Date.now()
+    }
+  });
+  logger.debug(`Time await resolved`, { runId, stepName });
+}

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

@@ -0,0 +1,15 @@
+import type { AwaitConfig } from '../../../../registry/types.js';
+/**
+ * Await Pattern: Webhook
+ *
+ * Creates a dynamic webhook endpoint that resolves when called
+ * Useful for human approval flows, external integrations
+ */
+export declare function registerWebhookAwait(runId: string, stepName: string, flowName: string, config: AwaitConfig, position?: 'before' | 'after'): Promise<{
+    webhookUrl: string;
+    timeout: number | undefined;
+}>;
+/**
+ * Resolve webhook await when webhook is called
+ */
+export declare function resolveWebhookAwait(runId: string, stepName: string, flowName: string, position: 'before' | 'after', webhookData: any): Promise<void>;

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

@@ -0,0 +1,120 @@
+import { useNventLogger, useRuntimeConfig, useScheduler } from "#imports";
+import { getEventBus } from "../../../events/eventBus.js";
+export async function registerWebhookAwait(runId, stepName, flowName, config, position = "after") {
+  const logger = useNventLogger("await-webhook");
+  const eventBus = getEventBus();
+  const runtimeConfig = useRuntimeConfig();
+  const path = `/${flowName}/${runId}/${stepName}`;
+  let baseUrl = runtimeConfig.nvent?.webhooks?.baseUrl;
+  if (!baseUrl) {
+    const nitroApp = runtimeConfig.nitro?.app;
+    if (nitroApp?.baseURL) {
+      baseUrl = `${nitroApp.baseURL}`;
+    }
+    if (!baseUrl) {
+      baseUrl = process.env.NITRO_URL || process.env.URL || (process.env.NODE_ENV === "development" ? "http://localhost:3000" : void 0);
+    }
+  }
+  if (!baseUrl) {
+    logger.warn("No baseUrl configured for webhooks. Set NUXT_PUBLIC_SITE_URL or nvent.webhooks.baseUrl");
+    baseUrl = "http://localhost:3000";
+  }
+  const webhookPath = `/api/_webhook/await${path}`;
+  const fullWebhookUrl = `${baseUrl.replace(/\/$/, "")}${webhookPath}`;
+  logger.info(`Registering webhook await: ${fullWebhookUrl}`, { runId, stepName });
+  eventBus.publish({
+    type: "await.registered",
+    flowName,
+    runId,
+    stepName,
+    awaitType: "webhook",
+    position,
+    config,
+    data: {
+      path,
+      method: config.method || "POST",
+      timeout: config.timeout,
+      registeredAt: Date.now(),
+      webhookUrl: fullWebhookUrl
+    }
+  });
+  if (config.timeout && config.timeout > 0) {
+    const scheduler = useScheduler();
+    const timeoutAt = Date.now() + config.timeout;
+    const jobId = `await-webhook-timeout-${runId}-${stepName}-${position}`;
+    await scheduler.schedule({
+      id: jobId,
+      name: `Webhook Timeout: ${flowName} - ${stepName}`,
+      type: "one-time",
+      executeAt: timeoutAt,
+      handler: async () => {
+        logger.warn("Webhook await timeout", {
+          runId,
+          stepName,
+          flowName,
+          timeout: config.timeout,
+          timeoutAction: config.timeoutAction || "fail"
+        });
+        eventBus.publish({
+          type: "await.timeout",
+          flowName,
+          runId,
+          stepName,
+          position,
+          awaitType: "webhook",
+          timeoutAction: config.timeoutAction || "fail",
+          data: {
+            timeout: config.timeout,
+            registeredAt: Date.now() - (config.timeout || 0),
+            timedOutAt: Date.now()
+          }
+        });
+      },
+      metadata: {
+        component: "await-pattern",
+        awaitType: "webhook",
+        runId,
+        stepName,
+        flowName,
+        position,
+        timeout: config.timeout
+      }
+    });
+    logger.debug(`Webhook timeout scheduled`, {
+      runId,
+      stepName,
+      timeout: config.timeout,
+      timeoutAction: config.timeoutAction
+    });
+  }
+  logger.debug(`Webhook await registered: ${fullWebhookUrl}`, { runId, stepName });
+  return {
+    webhookUrl: fullWebhookUrl,
+    timeout: config.timeout
+  };
+}
+export async function resolveWebhookAwait(runId, stepName, flowName, position, webhookData) {
+  const logger = useNventLogger("await-webhook");
+  const eventBus = getEventBus();
+  const scheduler = useScheduler();
+  logger.info(`Resolving webhook await`, { runId, stepName });
+  const jobId = `await-webhook-timeout-${runId}-${stepName}-${position}`;
+  try {
+    await scheduler.unschedule(jobId);
+    logger.debug("Unscheduled webhook 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: webhookData,
+    data: {
+      resolvedAt: Date.now()
+    }
+  });
+  logger.debug(`Webhook await resolved`, { runId, stepName });
+}

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

@@ -1,8 +1,8 @@
-import { useFlowEngine, useQueueAdapter } from '#imports';
+import { useFlow, useQueueAdapter } from '#imports';
 import type { RunContext, NodeHandler } from '../worker/node/runner.js';
 export type ExtendedRunContext = RunContext & {
     provider: ReturnType<typeof useQueueAdapter>;
-    flow: ReturnType<typeof useFlowEngine>;
+    flow: ReturnType<typeof useFlow>;
     registry: any;
 };
 export type DefineFunction = (handler: (input: any, ctx: ExtendedRunContext) => Promise<any>) => NodeHandler;

package/dist/runtime/{utils → nitro/utils}/defineFunction.js

@@ -1,9 +1,9 @@
-import { $useQueueRegistry, useFlowEngine, useQueueAdapter } from "#imports";
+import { $useFunctionRegistry, useFlow, useQueueAdapter } from "#imports";
 export const defineFunction = (handler) => {
   const wrapped = async (input, ctx) => {
     const provider = useQueueAdapter();
-    const flow = ctx.flow || useFlowEngine();
-    const registry = $useQueueRegistry();
+    const flow = ctx.flow || useFlow();
+    const registry = $useFunctionRegistry();
     const extended = {
       ...ctx,
       provider,

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

@@ -1,4 +1,72 @@
 export type FlowRole = 'entry' | 'step';
+/**
+ * Trigger definition for inline trigger registration
+ * Can be defined in function config alongside subscription
+ */
+export interface TriggerDefinition {
+    /**
+     * Unique trigger name (e.g., 'manual.approve-order')
+     */
+    name: string;
+    /**
+     * Trigger type
+     */
+    type: 'event' | 'webhook' | 'schedule' | 'manual';
+    /**
+     * Trigger scope: 'flow' for entry triggers, 'await' for await patterns
+     */
+    scope?: 'flow' | 'await';
+    /**
+     * Human-readable display name
+     */
+    displayName?: string;
+    /**
+     * Description of what this trigger does
+     */
+    description?: string;
+    /**
+     * Expected flows that should subscribe to this trigger (for validation)
+     */
+    expectedSubscribers?: string[];
+    /**
+     * Webhook-specific configuration
+     */
+    webhook?: {
+        /**
+         * URL path for webhook (e.g., '/api/webhooks/stripe')
+         */
+        path: string;
+        /**
+         * HTTP method
+         */
+        method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+        /**
+         * Authentication configuration
+         */
+        auth?: any;
+    };
+    /**
+     * Schedule-specific configuration
+     */
+    schedule?: {
+        /**
+         * Cron expression (e.g., '0 9 * * *' for 9 AM daily)
+         */
+        cron: string;
+        /**
+         * Timezone for cron expression
+         */
+        timezone?: string;
+        /**
+         * Whether schedule is enabled
+         */
+        enabled?: boolean;
+    };
+    /**
+     * Additional configuration options
+     */
+    config?: Record<string, any>;
+}
 export interface FlowConfig {
     /**
      * One or more flow names this step belongs to.
@@ -22,6 +90,88 @@ export interface FlowConfig {
      * The compiler normalizes this to `string[]` under `subscribes`.
      */
     subscribes?: string | string[];
+    /**
+     * Entry trigger configuration (v0.5)
+     * Define and/or subscribe to triggers to start flow runs
+     */
+    triggers?: {
+        /**
+         * Define a new trigger inline (optional)
+         * If provided, this trigger will be registered at build time
+         */
+        define?: TriggerDefinition;
+        /**
+         * Array of trigger names to subscribe to
+         * Can include the defined trigger or external triggers
+         */
+        subscribe: string[];
+        /**
+         * Trigger mode: 'auto' (immediate) or 'manual' (requires approval)
+         */
+        mode?: 'auto' | 'manual';
+    };
+    /**
+     * Await pattern: Wait BEFORE step execution (v0.5)
+     * Step won't execute until trigger fires
+     */
+    awaitBefore?: AwaitConfig;
+    /**
+     * Await pattern: Wait AFTER step execution (v0.5)
+     * Next steps won't trigger until trigger fires
+     */
+    awaitAfter?: AwaitConfig;
+}
+/**
+ * Await configuration (run-scoped triggers)
+ * Declared in config, no functions allowed (AST-parsed)
+ */
+export interface AwaitConfig {
+    /**
+     * Trigger type
+     */
+    type: 'webhook' | 'event' | 'schedule' | 'time';
+    /**
+     * URL path for webhook (supports template variables: {runId}, {stepId})
+     */
+    path?: string;
+    /**
+     * HTTP method for webhook
+     */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /**
+     * Event name to wait for
+     */
+    event?: string;
+    /**
+     * Key to match between event and step data
+     * e.g., 'orderId' matches event.orderId === step.orderId
+     * Supports nested paths: 'order.id' matches event.order.id === step.order.id
+     */
+    filterKey?: string;
+    /**
+     * Cron expression (e.g., '0 9 * * *' for 9 AM daily)
+     */
+    cron?: string;
+    /**
+     * Hours to add after step completion before calculating next cron occurrence
+     */
+    nextAfterHours?: number;
+    /**
+     * Timezone for cron expression
+     */
+    timezone?: string;
+    /**
+     * Delay in milliseconds
+     */
+    delay?: number;
+    /**
+     * Maximum wait time in milliseconds
+     */
+    timeout?: number;
+    /**
+     * Action to take on timeout
+     */
+    timeoutAction?: 'fail' | 'continue' | 'retry';
 }
 export interface QueueJobDefaults {
     /**
@@ -151,4 +301,10 @@ export interface QueueWorkerConfig {
 }
 export type DefineFunctionConfig = <T extends QueueWorkerConfig>(cfg: T) => T;
 export declare const defineFunctionConfig: DefineFunctionConfig;
+/**
+ * Helper for defining trigger configurations inline
+ * This is just a type helper, actual value is the same as defineFunctionConfig
+ */
+export type DefineTriggerConfig = <T extends TriggerDefinition>(cfg: T) => T;
+export declare const defineTriggerConfig: DefineTriggerConfig;
 export default defineFunctionConfig;

package/dist/runtime/{utils → nitro/utils}/defineFunctionConfig.js

@@ -1,2 +1,3 @@
 export const defineFunctionConfig = (cfg) => cfg;
+export const defineTriggerConfig = (cfg) => cfg;
 export default defineFunctionConfig;

package/dist/runtime/nitro/utils/defineHooks.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Type-safe hook definitions for await patterns
+ * v0.5 - Await Integration
+ */
+import type { RunContext } from '../worker/node/runner.js';
+export interface AwaitRegisterContext extends Pick<RunContext, 'flowId' | 'flowName' | 'stepName' | 'logger' | 'state'> {
+    awaitType: 'webhook' | 'event' | 'schedule' | 'time';
+    awaitConfig: any;
+}
+export interface AwaitResolveContext extends Pick<RunContext, 'flowId' | 'flowName' | 'stepName' | 'logger' | 'state'> {
+    awaitType: 'webhook' | 'event' | 'schedule' | 'time';
+    resolvedData: any;
+}
+/**
+ * Define onAwaitRegister hook with proper types
+ * Called when an await pattern is registered (before handler execution or after completion)
+ *
+ * @example
+ * export const onAwaitRegister = defineAwaitRegisterHook(async (webhookUrl, stepData, ctx) => {
+ *   // Send notification email with webhook URL
+ *   await sendEmail({
+ *     to: stepData.reviewerEmail,
+ *     subject: 'Approval Required',
+ *     approveUrl: webhookUrl
+ *   })
+ * })
+ */
+export declare function defineAwaitRegisterHook(hook: (webhookUrl: string, stepData: any, ctx: AwaitRegisterContext) => Promise<void>): (webhookUrl: string, stepData: any, ctx: AwaitRegisterContext) => Promise<void>;
+/**
+ * Define onAwaitResolve hook with proper types
+ * Called when an await pattern is resolved (external trigger fired)
+ *
+ * @example
+ * export const onAwaitResolve = defineAwaitResolveHook(async (resolvedData, stepData, ctx) => {
+ *   ctx.logger.log('info', 'Approval received', { approved: resolvedData.approved })
+ *
+ *   // Update external system
+ *   await updateTicketStatus(stepData.ticketId, resolvedData.approved ? 'approved' : 'rejected')
+ * })
+ */
+export declare function defineAwaitResolveHook(hook: (resolvedData: any, stepData: any, ctx: AwaitResolveContext) => Promise<void>): (resolvedData: any, stepData: any, ctx: AwaitResolveContext) => Promise<void>;

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

@@ -0,0 +1,6 @@
+export function defineAwaitRegisterHook(hook) {
+  return hook;
+}
+export function defineAwaitResolveHook(hook) {
+  return hook;
+}

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

@@ -3,9 +3,9 @@
  *
  * Used by external adapter modules to register their adapters with nvent
  */
-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 { QueueAdapter } from '../../adapters/interfaces/queue.js';
+import type { StreamAdapter } from '../../adapters/interfaces/stream.js';
+import type { StoreAdapter } from '../../adapters/interfaces/store.js';
 /**
  * Register a queue adapter
  *

package/dist/runtime/{utils → nitro/utils}/registerAdapter.js

@@ -1,4 +1,4 @@
-import { useAdapterRegistry } from "../adapters/registry.js";
+import { useAdapterRegistry } from "../../adapters/registry.js";
 export function registerQueueAdapter(name, adapter) {
   const registry = useAdapterRegistry();
   registry.registerQueue(name, adapter);

package/dist/runtime/nitro/utils/useAwait.d.ts

@@ -0,0 +1,71 @@
+import type { AwaitConfig } from '../../../registry/types.js';
+import { registerAwaitPattern, resolveAwaitPattern, registerWebhookAwait, resolveWebhookAwait, registerEventAwait, resolveEventAwait, registerScheduleAwait, resolveScheduleAwait, registerTimeAwait, resolveTimeAwait } from './awaitPatterns/index.js';
+/**
+ * Await pattern composable
+ * Provides unified API for managing await patterns in flows
+ * Separate from useTrigger which handles entry triggers (manual, webhook, schedule, event)
+ */
+export declare function useAwait(): {
+    /**
+     * Register an await pattern based on config type
+     * Automatically routes to appropriate implementation
+     */
+    register: typeof registerAwaitPattern;
+    /**
+     * Resolve an await pattern by type
+     */
+    resolve: typeof resolveAwaitPattern;
+    /**
+     * Direct access to specific await pattern implementations
+     */
+    webhook: {
+        register: typeof registerWebhookAwait;
+        resolve: typeof resolveWebhookAwait;
+    };
+    event: {
+        register: typeof registerEventAwait;
+        resolve: typeof resolveEventAwait;
+    };
+    schedule: {
+        register: typeof registerScheduleAwait;
+        resolve: typeof resolveScheduleAwait;
+    };
+    time: {
+        register: typeof registerTimeAwait;
+        resolve: typeof resolveTimeAwait;
+    };
+    /**
+     * Query methods for await state
+     */
+    /**
+     * Get await state for a specific flow run and step
+     */
+    getAwaitState(flowName: string, runId: string, stepName?: string): Promise<any>;
+    /**
+     * Check if a step is currently awaiting
+     */
+    isAwaiting(flowName: string, runId: string, stepName: string): Promise<boolean>;
+    /**
+     * Get all active awaits across all flows
+     */
+    getAllActiveAwaits(flowName?: string): Promise<{
+        flowName: string;
+        runId: string;
+        stepName: string;
+        awaitType: string;
+        position: "before" | "after";
+        registeredAt: string;
+    }[]>;
+    /**
+     * Get await history for a specific flow run from stream
+     */
+    getAwaitHistory(runId: string, opts?: {
+        limit?: number;
+        stepName?: string;
+    }): Promise<any>;
+    /**
+     * Cancel/timeout an active await
+     */
+    timeoutAwait(flowName: string, runId: string, stepName: string, reason?: string): Promise<void>;
+};
+export type { AwaitConfig };