nvent 0.4.5 → 0.5.0

package/dist/runtime/adapters/factory.js

@@ -1,4 +1,5 @@
 import { useAdapterRegistry } from "./registry.js";
+import { useStreamTopics, $useAnalyzedFlows } from "#imports";
 import {
   MemoryQueueAdapter,
   MemoryStreamAdapter,
@@ -39,29 +40,62 @@ async function createStreamAdapter(config) {
 async function createStoreAdapter(config) {
   const type = config.adapter || "file";
   const registry = useAdapterRegistry();
+  let adapter;
   if (registry.hasStore(type)) {
-    const adapter = registry.getStore(type);
-    return adapter;
-  }
-  switch (type) {
-    case "memory": {
-      return new MemoryStoreAdapter();
+    adapter = registry.getStore(type);
+  } else {
+    switch (type) {
+      case "memory": {
+        adapter = new MemoryStoreAdapter();
+        break;
+      }
+      case "file": {
+        const dataDir = config.file?.dataDir || ".data/store";
+        const fileAdapter = new FileStoreAdapter({
+          dataDir
+        });
+        await fileAdapter.init();
+        adapter = fileAdapter;
+        break;
+      }
+      case "redis":
+        throw new Error("Redis store adapter not registered. Install @nvent/adapter-store-redis and add it to your nuxt.config modules.");
+      case "postgres":
+        throw new Error("Postgres store adapter not yet implemented");
+      default:
+        throw new Error(`Unknown store adapter type: ${type}`);
     }
-    case "file": {
-      const dataDir = config.file?.dataDir || ".data/store";
-      const adapter = new FileStoreAdapter({
-        dataDir
-      });
-      await adapter.init();
-      return adapter;
+  }
+  try {
+    const { StoreSubjects } = useStreamTopics();
+    const flowIndexKey = StoreSubjects.flowIndex();
+    const existingFlows = await adapter.index.read(flowIndexKey, { limit: 1 });
+    if (existingFlows.length === 0) {
+      const analyzedFlows = $useAnalyzedFlows();
+      if (analyzedFlows && analyzedFlows.length > 0) {
+        const now = (/* @__PURE__ */ new Date()).toISOString();
+        for (const flow of analyzedFlows) {
+          await adapter.index.add(flowIndexKey, flow.id, Date.now(), {
+            name: flow.id,
+            displayName: flow.id,
+            registeredAt: now,
+            stats: {
+              total: 0,
+              success: 0,
+              failure: 0,
+              cancel: 0,
+              running: 0,
+              awaiting: 0
+            },
+            version: 1
+          });
+        }
+      }
     }
-    case "redis":
-      throw new Error("Redis store adapter not registered. Install @nvent/adapter-store-redis and add it to your nuxt.config modules.");
-    case "postgres":
-      throw new Error("Postgres store adapter not yet implemented");
-    default:
-      throw new Error(`Unknown store adapter type: ${type}`);
+  } catch (err) {
+    console.warn("[factory] Failed to initialize flow index:", err?.message);
   }
+  return adapter;
 }
 async function createQueueAdapter(config) {
   const type = config.adapter || "file";
@@ -86,7 +120,7 @@ async function createQueueAdapter(config) {
     case "redis":
       throw new Error("Redis queue adapter not registered. Install @nvent/adapter-queue-redis and add it to your nuxt.config modules.");
     case "postgres":
-      throw new Error("Postgres queue adapter (PGBoss) not yet implemented");
+      throw new Error("Postgres queue adapter not registered. Install @nvent/adapter-queue-postgres and add it to your nuxt.config modules.");
     default:
       throw new Error(`Unknown queue adapter type: ${type}`);
   }

package/dist/runtime/adapters/interfaces/store.d.ts

@@ -2,66 +2,121 @@
  * Store Adapter Interface
  *
  * Three-tier storage system:
- * 1. Event Stream - Append-only event log (replaces EventStore)
- * 2. Document Store - Generic document storage (for flow wiring, triggers, metadata)
+ * 1. Event Stream - Append-only event log
+ * 2. Sorted Index - Time-ordered metadata storage
  * 3. Key-Value Store - Fast lookups (for state, caching)
+ *
+ * ## Critical Implementation Requirements
+ *
+ * ### 1. Index Operations - add() vs update()
+ *
+ * **index.add()** - MUST completely REPLACE metadata when entry exists:
+ * ```typescript
+ * // First call
+ * await index.add('flows', 'my-flow', 123, { name: 'Flow', stats: {...} })
+ * // Second call - REPLACES entire metadata
+ * await index.add('flows', 'my-flow', 456, { lastRunAt: 789 })
+ * // Result: { lastRunAt: 789 } ← stats are LOST!
+ * ```
+ *
+ * **index.update()** - MUST perform DEEP MERGE of metadata:
+ * ```typescript
+ * // Initial state: { status: 'running', emittedEvents: { test: { completed: 1 } } }
+ * await index.update('runs', 'run-id', { emittedEvents: { another: { fired: 2 } } })
+ * // Result: { status: 'running', emittedEvents: { test: { completed: 1 }, another: { fired: 2 } } }
+ * ```
+ *
+ * ⚠️ **CRITICAL**: update() must perform DEEP merge at ALL nesting levels, not just top-level!
+ * - PostgreSQL `||` operator: Only shallow merge (top-level keys)
+ * - Redis HSET loop: Field-level merge (simulates deep merge for flat structures)
+ * - Memory defu(): True deep merge
+ *
+ * ### 2. Nested Metadata Structure
+ *
+ * Flow orchestration stores deeply nested metadata:
+ * ```typescript
+ * {
+ *   emittedEvents: {
+ *     'step1': {
+ *       'completed': 1234567890,
+ *       'custom_event': 1234567891
+ *     },
+ *     'step2': {
+ *       'completed': 1234567892
+ *     }
+ *   },
+ *   awaitingSteps: {
+ *     'step_name': {
+ *       status: 'awaiting',
+ *       position: 'after',
+ *       awaitType: 'event'
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Multiple updates add to nested structures incrementally. If deep merge fails,
+ * flow orchestration will miss events and steps won't trigger.
+ *
+ * ### 3. Concurrent Updates
+ *
+ * Flow steps run in parallel and update metadata concurrently:
+ * - Multiple steps emit events simultaneously
+ * - Each emits triggers index.updateWithRetry() with partial metadata
+ * - Updates must NOT overwrite each other
+ * - Use optimistic locking (version field) + retries
+ *
+ * ### 4. Testing Deep Merge
+ *
+ * Test that your adapter correctly handles:
+ * ```typescript
+ * // Setup
+ * await index.add('test', 'id', 1, { a: { b: 1 }, c: 2 })
+ *
+ * // Update nested property
+ * await index.update('test', 'id', { a: { d: 3 } })
+ * const result = await index.get('test', 'id')
+ *
+ * // MUST preserve existing nested data
+ * expect(result.metadata).toEqual({ a: { b: 1, d: 3 }, c: 2 })
+ * // NOT: { a: { d: 3 }, c: 2 } ← b is lost!
+ * ```
+ *
  */
 export interface StoreAdapter {
     /**
      * Close/cleanup the adapter
      */
     close(): Promise<void>;
-    /**
-     * Append an event to a subject's event stream
-     * @param subject - Event stream identifier (e.g., 'nq:flow:abc-123')
-     * @param event - Event to append (id and ts will be auto-generated)
-     * @returns The complete event record with generated id and timestamp
-     */
-    append(subject: string, event: Omit<EventRecord, 'id' | 'ts'>): Promise<EventRecord>;
-    /**
-     * Read events from a subject's event stream
-     * @param subject - Event stream identifier
-     * @param opts - Query options (filtering, pagination, etc.)
-     * @returns Array of event records
-     */
-    read(subject: string, opts?: EventReadOptions): Promise<EventRecord[]>;
-    /**
-     * Subscribe to new events in a subject's event stream (optional, not all adapters support this)
-     * @param subject - Event stream identifier (supports wildcards if adapter allows)
-     * @param onEvent - Callback for new events
-     * @returns Subscription handle for unsubscribing
-     */
-    subscribe?(subject: string, onEvent: (event: EventRecord) => void): Promise<EventSubscription>;
-    /**
-     * Save a document to a collection
-     * @param collection - Collection name (e.g., 'flow-wiring', 'triggers', 'flow-metadata')
-     * @param id - Document ID
-     * @param doc - Document data
-     */
-    save(collection: string, id: string, doc: Record<string, any>): Promise<void>;
-    /**
-     * Get a document from a collection
-     * @param collection - Collection name
-     * @param id - Document ID
-     * @returns Document or null if not found
-     */
-    get(collection: string, id: string): Promise<Record<string, any> | null>;
-    /**
-     * List documents in a collection (optional, not all adapters may support complex queries)
-     * @param collection - Collection name
-     * @param opts - Query options (filtering, pagination, sorting)
-     * @returns Array of documents with their IDs
-     */
-    list?(collection: string, opts?: ListOptions): Promise<Array<{
-        id: string;
-        doc: any;
-    }>>;
-    /**
-     * Delete a document from a collection
-     * @param collection - Collection name
-     * @param id - Document ID
-     */
-    delete(collection: string, id: string): Promise<void>;
+    stream: {
+        /**
+         * Append an event to a subject's event stream
+         * @param subject - Event stream identifier (e.g., 'nq:flow:abc-123')
+         * @param event - Event to append (id and ts will be auto-generated)
+         * @returns The complete event record with generated id and timestamp
+         */
+        append(subject: string, event: Omit<EventRecord, 'id' | 'ts'>): Promise<EventRecord>;
+        /**
+         * Read events from a subject's event stream
+         * @param subject - Event stream identifier
+         * @param opts - Query options (filtering, pagination, etc.)
+         * @returns Array of event records
+         */
+        read(subject: string, opts?: EventReadOptions): Promise<EventRecord[]>;
+        /**
+         * Subscribe to new events in a subject's event stream (optional, not all adapters support this)
+         * @param subject - Event stream identifier (supports wildcards if adapter allows)
+         * @param onEvent - Callback for new events
+         * @returns Subscription handle for unsubscribing
+         */
+        subscribe?(subject: string, onEvent: (event: EventRecord) => void): Promise<EventSubscription>;
+        /**
+         * Delete an entire event stream
+         * @param subject - Event stream identifier
+         * @returns True if stream was deleted, false if not found
+         */
+        delete?(subject: string): Promise<boolean>;
+    };
     kv: {
         /**
          * Get a value by key
@@ -89,66 +144,75 @@ export interface StoreAdapter {
          */
         increment?(key: string, by?: number): Promise<number>;
     };
-    /**
-     * Add entry to a sorted index (optional, for efficient time-ordered listings)
-     * @param key - Index key (e.g., 'nq:flows:flowName')
-     * @param id - Entry ID
-     * @param score - Sort score (typically timestamp)
-     * @param metadata - Optional metadata to store with entry
-     */
-    indexAdd?(key: string, id: string, score: number, metadata?: Record<string, any>): Promise<void>;
-    /**
-     * Get a single entry from a sorted index
-     * @param key - Index key
-     * @param id - Entry ID
-     * @returns Entry with score and metadata, or null if not found
-     */
-    indexGet?(key: string, id: string): Promise<{
-        id: string;
-        score: number;
-        metadata?: any;
-    } | null>;
-    /**
-     * Read entries from a sorted index (ordered by score descending)
-     * @param key - Index key
-     * @param opts - Pagination options
-     * @param opts.offset - Number of entries to skip
-     * @param opts.limit - Maximum number of entries to return
-     * @returns Array of entries with scores and metadata
-     */
-    indexRead?(key: string, opts?: {
-        offset?: number;
-        limit?: number;
-    }): Promise<Array<{
-        id: string;
-        score: number;
-        metadata?: any;
-    }>>;
-    /**
-     * Update metadata for an entry in a sorted index
-     * @param key - Index key
-     * @param id - Entry ID
-     * @param metadata - Metadata to update
-     * @returns True if update succeeded, false if version conflict
-     */
-    indexUpdate?(key: string, id: string, metadata: Record<string, any>): Promise<boolean>;
-    /**
-     * Update with automatic retries on version conflicts
-     * @param key - Index key
-     * @param id - Entry ID
-     * @param metadata - Metadata to update
-     * @param maxRetries - Maximum retry attempts (default: 3)
-     */
-    indexUpdateWithRetry?(key: string, id: string, metadata: Record<string, any>, maxRetries?: number): Promise<void>;
-    /**
-     * Atomic increment of a metadata field in an index entry
-     * @param key - Index key
-     * @param id - Entry ID
-     * @param field - Field name to increment
-     * @param increment - Amount to increment by (default: 1)
-     * @returns New value after increment
-     */
-    indexIncrement?(key: string, id: string, field: string, increment?: number): Promise<number>;
+    index: {
+        /**
+         * Add entry to a sorted index
+         * @param key - Index key (e.g., 'nq:flows:flowName')
+         * @param id - Entry ID
+         * @param score - Sort score (typically timestamp)
+         * @param metadata - Optional metadata to store with entry
+         */
+        add(key: string, id: string, score: number, metadata?: Record<string, any>): Promise<void>;
+        /**
+         * Get a single entry from a sorted index
+         * @param key - Index key
+         * @param id - Entry ID
+         * @returns Entry with score and metadata, or null if not found
+         */
+        get(key: string, id: string): Promise<{
+            id: string;
+            score: number;
+            metadata?: any;
+        } | null>;
+        /**
+         * Read entries from a sorted index (ordered by score descending)
+         * @param key - Index key
+         * @param opts - Pagination options
+         * @param opts.offset - Number of entries to skip
+         * @param opts.limit - Maximum number of entries to return
+         * @returns Array of entries with scores and metadata
+         */
+        read(key: string, opts?: {
+            offset?: number;
+            limit?: number;
+        }): Promise<Array<{
+            id: string;
+            score: number;
+            metadata?: any;
+        }>>;
+        /**
+         * Update metadata for an entry in a sorted index
+         * @param key - Index key
+         * @param id - Entry ID
+         * @param metadata - Metadata to update
+         * @returns True if update succeeded, false if version conflict
+         */
+        update(key: string, id: string, metadata: Record<string, any>): Promise<boolean>;
+        /**
+         * Update with automatic retries on version conflicts
+         * @param key - Index key
+         * @param id - Entry ID
+         * @param metadata - Metadata to update
+         * @param maxRetries - Maximum retry attempts (default: 3)
+         */
+        updateWithRetry(key: string, id: string, metadata: Record<string, any>, maxRetries?: number): Promise<void>;
+        /**
+         * Atomic increment of a metadata field in an index entry
+         * @param key - Index key
+         * @param id - Entry ID
+         * @param field - Field name to increment
+         * @param increment - Amount to increment by (default: 1)
+         * @returns New value after increment
+         */
+        increment(key: string, id: string, field: string, increment?: number): Promise<number>;
+        /**
+         * Delete an entry from a sorted index
+         * @param key - Index key
+         * @param id - Entry ID
+         * @returns True if entry was deleted, false if not found
+         */
+        delete(key: string, id: string): Promise<boolean>;
+    };
 }
 /**
  * Event record in the event stream

package/dist/runtime/config/index.d.ts

@@ -1,12 +1,12 @@
 import type { ModuleOptions, ModuleConfig } from './types.js';
 /**
- * Merge and normalize module options with defaults (v0.4.1).
+ * Merge and normalize module options with defaults.
  * Applies connection fallback: adapter-specific connections override connections.redis/postgres.
  * Only includes connection defaults for adapters that are actually used.
  */
 export declare function normalizeModuleOptions(options: ModuleOptions): Required<ModuleOptions>;
 /**
- * Convert normalized module options to runtime config format (v0.4.1).
+ * Convert normalized module options to runtime config format.
  */
 export declare function toRuntimeConfig(normalizedOptions: Required<ModuleOptions>): ModuleConfig;
 /**

package/dist/runtime/config/index.js

@@ -7,7 +7,8 @@ export function normalizeModuleOptions(options) {
     connections: {},
     queue: {
       adapter: "file",
-      prefix: "nq",
+      prefix: "nvent",
+      schema: "nvent_queue",
       defaultJobOptions: {},
       worker: {
         concurrency: 2,
@@ -17,11 +18,12 @@ export function normalizeModuleOptions(options) {
     },
     stream: {
       adapter: "memory",
-      prefix: "nq"
+      prefix: "nvent"
     },
     store: {
       adapter: "file",
-      prefix: "nq",
+      prefix: "nvent",
+      schema: "nvent_store",
       state: {
         autoScope: "always",
         cleanup: {
@@ -35,7 +37,7 @@ export function normalizeModuleOptions(options) {
       metadataTTL: 2592e3
       // 30 days
     },
-    flows: {
+    flow: {
       stallDetection: {
         enabled: true,
         stallTimeout: 30 * 60 * 1e3,
@@ -44,6 +46,11 @@ export function normalizeModuleOptions(options) {
         // 15 minutes
         enablePeriodicCheck: true
       }
+    },
+    webhooks: {
+      // baseUrl will be determined at runtime from Nitro context
+      // Users can override via NUXT_PUBLIC_SITE_URL or explicit config
+      baseUrl: process.env.NUXT_PUBLIC_SITE_URL || void 0
     }
   };
   const normalized = defu(options, defaults);
@@ -83,7 +90,7 @@ export function normalizeModuleOptions(options) {
   }
   if (neededConnections.has("postgres") && !normalized.connections.postgres) {
     normalized.connections.postgres = {
-      connectionString: process.env.DATABASE_URL || "postgresql://localhost:5432/nuxt_queue"
+      connectionString: process.env.DATABASE_URL || "postgresql://localhost:5432/nvent"
     };
   }
   if (neededConnections.has("rabbitmq") && !normalized.connections.rabbitmq) {
@@ -146,7 +153,8 @@ export function toRuntimeConfig(normalizedOptions) {
     stream: normalizedOptions.stream,
     store: normalizedOptions.store,
     connections: normalizedOptions.connections,
-    flows: normalizedOptions.flows
+    flow: normalizedOptions.flow,
+    webhooks: normalizedOptions.webhooks
   };
 }
 export function getRedisStorageConfig(normalizedOptions) {

package/dist/runtime/config/types.d.ts

@@ -133,6 +133,12 @@ export interface QueueConfig {
      * Queue-specific options (BullMQ/PGBoss configuration)
      */
     prefix?: string;
+    /**
+     * PostgreSQL schema name for pg-boss tables
+     * Only applies when adapter is 'postgres'
+     * @default 'pgboss'
+     */
+    schema?: string;
     defaultJobOptions?: {
         attempts?: number;
         backoff?: number | {
@@ -189,6 +195,18 @@ export interface StreamConfig {
     retryAttempts?: number;
     retryDelay?: number;
 }
+/**
+ * Webhooks configuration
+ */
+export interface WebhooksConfig {
+    /**
+     * Base URL for webhook endpoints
+     * Auto-detected from Nitro context in development
+     * Set explicitly for production or to override auto-detection
+     * @default Auto-detected from NUXT_PUBLIC_SITE_URL, NITRO_URL, or dev server (http://localhost:3000 fallback)
+     */
+    baseUrl?: string;
+}
 /**
  * Flow configuration
  */
@@ -281,6 +299,12 @@ export interface StoreConfig {
      * @default 'nq'
      */
     prefix?: string;
+    /**
+     * PostgreSQL schema name for store tables
+     * Only applies when adapter is 'postgres'
+     * @default 'public'
+     */
+    schema?: string;
     /**
      * State management configuration (KV store behavior)
      */
@@ -345,7 +369,12 @@ export interface ModuleOptions {
      * Flow-specific configuration
      * @since v0.4.1
      */
-    flows?: FlowConfig;
+    flow?: FlowConfig;
+    /**
+     * Webhooks configuration
+     * @since v0.5.0
+     */
+    webhooks?: WebhooksConfig;
     /**
      * Shared connection configurations
      * Used as fallback if adapters don't specify their own connections
@@ -361,7 +390,8 @@ export interface ModuleConfig {
     queue: Required<QueueConfig>;
     stream: Required<StreamConfig>;
     store: Required<StoreConfig>;
-    flows: Required<FlowConfig>;
+    flow: Required<FlowConfig>;
+    webhooks: Required<WebhooksConfig>;
     connections: Required<ConnectionsConfig>;
     rootDir?: string;
 }

package/dist/runtime/events/eventBus.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events';
-import type { EventRecord } from '../types.js';
+import type { EventRecord } from './types.js';
 type Handler = (e: EventRecord) => void;
 declare global {
     var __nq_bus_emitter: EventEmitter | undefined;

package/dist/runtime/events/types.d.ts

@@ -15,7 +15,7 @@ export interface PublishPayload<T = any> {
     attempt?: number;
     data?: T;
 }
-export type EventType = 'flow.start' | 'flow.completed' | 'flow.failed' | 'flow.cancel' | 'step.started' | 'step.completed' | 'step.failed' | 'step.retry' | 'log' | 'emit' | 'state' | 'flow.stalled';
+export type EventType = 'flow.start' | 'flow.completed' | 'flow.failed' | 'flow.cancel' | 'step.started' | 'step.completed' | 'step.failed' | 'step.retry' | 'log' | 'emit' | 'state' | 'flow.stalled' | 'trigger.fired' | 'trigger.registered' | 'await.registered' | 'await.resolved' | 'await.timeout';
 export interface BaseEvent {
     id?: string;
     ts?: string;
@@ -113,4 +113,33 @@ export interface StateEvent extends StepEvent {
         value?: any;
     };
 }
-export type FlowEvent = FlowStartEvent | FlowCompletedEvent | FlowFailedEvent | FlowCancelEvent | FlowStalledEvent | StepStartedEvent | StepCompletedEvent | StepFailedEvent | StepRetryEvent | LogEvent | EmitEvent | StateEvent;
+export interface TriggerFiredEvent extends BaseEvent {
+    type: 'trigger.fired';
+    triggerName: string;
+    data: any;
+}
+export interface TriggerRegisteredEvent {
+    type: 'trigger.registered';
+    triggerName: string;
+    triggerType: 'event' | 'webhook' | 'schedule' | 'manual';
+    scope: 'flow' | 'run';
+}
+export interface AwaitRegisteredEvent extends BaseEvent {
+    type: 'await.registered';
+    stepName: string;
+    awaitType: 'webhook' | 'event' | 'schedule' | 'time';
+    position: 'before' | 'after';
+    config: any;
+}
+export interface AwaitResolvedEvent extends BaseEvent {
+    type: 'await.resolved';
+    stepName: string;
+    triggerData: any;
+    position: 'before' | 'after';
+}
+export interface AwaitTimeoutEvent extends BaseEvent {
+    type: 'await.timeout';
+    stepName: string;
+    action: 'fail' | 'continue' | 'retry';
+}
+export type FlowEvent = FlowStartEvent | FlowCompletedEvent | FlowFailedEvent | FlowCancelEvent | FlowStalledEvent | StepStartedEvent | StepCompletedEvent | StepFailedEvent | StepRetryEvent | LogEvent | EmitEvent | StateEvent | TriggerFiredEvent | TriggerRegisteredEvent | AwaitRegisteredEvent | AwaitResolvedEvent | AwaitTimeoutEvent;

package/dist/runtime/events/utils/scheduleTrigger.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Schedule or update a schedule trigger in the scheduler
+ */
+export declare function scheduleTrigger(triggerName: string, scheduleConfig: any, triggerStatus?: string): Promise<void>;
+/**
+ * Unschedule a schedule trigger from the scheduler
+ */
+export declare function unscheduleTrigger(triggerName: string): Promise<void>;