nvent 1.0.0-alpha.11 → 1.0.0-alpha.12

package/dist/module.d.mts

@@ -40,345 +40,300 @@ type NventQueueConfig = {
  * `iii/config.ts` can import them without creating a circular dependency with
  * `module.ts`.
  */
+
 interface NventIiiOptions {
-    iii?: {
-        /** Version of the iii engine to install. Default: 'latest' */
-        version?: string;
-        /** 'local' uses a local binary, 'docker' uses Docker, 'remote' skips lifecycle management */
-        mode?: 'local' | 'docker' | 'remote';
-        /** WebSocket URL for workers to connect to (default: ws://localhost:49134) */
-        wsUrl?: string;
-        /** HTTP port for iii REST API (default: 3111) */
-        httpPort?: number;
-        /** HTTP host for iii REST API (default: 'localhost') */
-        httpHost?: string;
-        /** WebSocket port for workers (default: 49134) */
-        wsPort?: number;
-        /** WebSocket port for the Stream module (default: 3112) */
-        streamPort?: number;
-        /** Whether nvent manages engine lifecycle. Default: true in dev, false in prod */
-        managed?: boolean;
-        modules?: {
-            state?: boolean;
-            queue?: boolean;
-            cron?: boolean;
-            observability?: boolean;
-            stream?: boolean;
-        };
-        /** State module adapter configuration */
-        state?: {
-            adapter?: {
-                type: 'kv';
-                storeMethod?: 'file_based' | 'in_memory';
-                filePath?: string;
-                saveIntervalMs?: number;
-            } | {
-                type: 'redis';
-                redisUrl?: string;
-            } | {
-                type: 'bridge';
-                bridgeUrl: string;
-            };
-        };
-        /**
-         * Queue module configuration.
-         * Named queues must be declared here for the iii engine to route messages through them.
-         */
-        queue?: {
-            adapter?: {
-                type: 'builtin';
-                storeMethod?: 'file_based' | 'in_memory';
-                filePath?: string;
-                saveIntervalMs?: number;
-                maxAttempts?: number;
-                backoffMs?: number;
-                concurrency?: number;
-                pollIntervalMs?: number;
-                /** Processing order. 'concurrent' (parallel) or 'fifo' (sequential). Default: 'concurrent' */
-                mode?: 'concurrent' | 'fifo';
-            } | {
-                type: 'redis';
-                redisUrl?: string;
-            } | {
-                type: 'rabbitmq';
-                amqpUrl?: string;
-                maxAttempts?: number;
-                prefetchCount?: number;
-                /** 'standard' or 'quorum' (HA replicated). Default: 'standard' */
-                queueMode?: 'standard' | 'quorum';
-            } | {
-                type: 'bridge';
-                bridgeUrl: string;
-            };
-            queueConfigs?: Record<string, {
-                type?: 'standard' | 'fifo';
-                concurrency?: number;
-                /** Alias of maxRetries */
-                retries?: number;
-                maxRetries?: number;
-                /** Alias of backoffMs */
-                backoff?: number;
-                backoffMs?: number;
-                /** Optional visibility timeout / lease timeout if supported by the engine */
-                visibilityTimeoutMs?: number;
-                leaseTimeoutMs?: number;
-                /** Optional dead-letter / fallback queue names if supported by the engine */
-                deadLetterQueue?: string;
-                fallbackQueue?: string;
-                /** FIFO only: field in the payload used to group messages */
-                messageGroupField?: string;
-            }>;
-        };
-        /** Cron module adapter configuration */
-        cron?: {
-            adapter?: {
-                type: 'kv';
-                lockTtlMs?: number;
-                lockIndex?: string;
-                storeMethod?: 'file_based' | 'in_memory';
-                filePath?: string;
-                saveIntervalMs?: number;
-            } | {
-                type: 'redis';
-                redisUrl?: string;
-            };
-        };
-        /** WebSocket Stream module configuration */
-        stream?: {
-            host?: string;
-            authFunction?: string | null;
-            adapter?: {
-                type: 'kv';
-                storeMethod?: 'file_based' | 'in_memory';
-                filePath?: string;
-                saveIntervalMs?: number;
-            } | {
-                type: 'redis';
-                redisUrl?: string;
-            } | {
-                type: 'bridge';
-                bridgeUrl: string;
-            };
-        };
-        /** REST API module extra settings */
-        restApi?: {
-            host?: string;
-            defaultTimeout?: number;
-            concurrencyRequestLimit?: number;
-            /** CORS configuration for browser clients */
-            cors?: {
-                /** Origins allowed to make requests. Use '*' for any, or list specific domains. */
-                allowedOrigins?: string[];
-                /** HTTP methods permitted for cross-origin requests. */
-                allowedMethods?: string[];
-            };
-        };
-        /** OtelModule (observability) configuration */
-        observability?: {
-            enabled?: boolean;
-            serviceName?: string;
-            serviceVersion?: string;
-            serviceNamespace?: string;
-            /**
-             * Trace export destination.
-             * 'memory' = queryable via iii API / console (default).
-             * 'otlp'   = external collector (set endpoint too).
-             * 'both'   = memory + otlp.
-             */
-            exporter?: 'memory' | 'otlp' | 'both';
-            endpoint?: string;
-            samplingRatio?: number;
-            memoryMaxSpans?: number;
-            metricsEnabled?: boolean;
-            metricsExporter?: 'memory' | 'otlp';
-            metricsRetentionSeconds?: number;
-            metricsMaxCount?: number;
-            logsEnabled?: boolean;
-            logsExporter?: 'memory' | 'otlp' | 'both';
-            logsMaxCount?: number;
-            logsRetentionSeconds?: number;
-            logsBatchSize?: number;
-            logsFlushIntervalMs?: number;
-            logsSamplingRatio?: number;
-            logsConsoleOutput?: boolean;
-            /** Advanced sampling rules — override samplingRatio for matched operations. */
-            sampling?: {
-                default?: number;
-                parentBased?: boolean;
-                rules?: Array<{
-                    operation?: string;
-                    service?: string;
-                    rate: number;
-                }>;
-                rateLimit?: {
-                    maxTracesPerSecond?: number;
-                };
-            };
-            /** Alert rules — trigger a webhook or function when a metric crosses a threshold. */
-            alerts?: Array<{
-                name: string;
-                metric: string;
-                threshold: number;
-                operator: '>' | '>=' | '<' | '<=' | '==' | '!=';
-                windowSeconds: number;
-                enabled?: boolean;
-                cooldownSeconds?: number;
-                action: {
-                    type: 'webhook';
-                    url: string;
-                } | {
-                    type: 'function';
-                    path: string;
-                };
-            }>;
-            level?: 'trace' | 'debug' | 'info' | 'warn' | 'error';
-            format?: 'default' | 'json';
-        };
-        /**
-         * Minimum log level for iii engine output.
-         * 'none' silences all output, 'error' shows only errors, 'warn' shows warnings + errors,
-         * 'info' shows everything. Default: 'warn'
-         */
-        logLevel?: 'none' | 'error' | 'warn' | 'info';
-        /**
-         * Enable the iii-console web UI (separate binary, http://localhost:3113).
-         * Pass `true` for defaults or an object to customise.
-         */
-        console?: boolean | {
-            /** Version to install. Default: same as iii engine version */
-            version?: string;
-            /** Port for the console web UI. Default: 3113 */
-            port?: number;
-            /** Host for the console web UI. Default: 'localhost' */
-            host?: string;
-            /** Enable the Flow visualization page */
-            flow?: boolean;
-        };
-        /** PubSub worker — topic-based event fanout across functions. */
-        pubsub?: {
-            adapter?: {
-                type: 'local';
-            } | {
-                type: 'redis';
-                redisUrl?: string;
-            };
-        };
-        /**
-         * HTTP Functions worker — enables outbound HTTP calls from the engine.
-         * Required for functions registered with HttpInvocationConfig.
-         */
-        httpFunctions?: {
-            security?: {
-                /** URL patterns allowed for outbound requests. Use '*' to allow all. */
-                urlAllowlist?: string[];
-                /** Block requests to private/internal IP ranges (SSRF prevention). Default: true */
-                blockPrivateIps?: boolean;
-                /** Require HTTPS for all outbound requests. Default: true */
-                requireHttps?: boolean;
-            };
-        };
-        /**
-         * Additional iii-worker-manager instance with RBAC.
-         * nvent uses this automatically when browser SDK is enabled.
-         * Can also be configured manually for custom auth scenarios.
-         */
-        workerManager?: {
-            rbac?: {
-                /** Port for the RBAC worker manager. Default: 49135 */
-                port?: number;
-                /** Function ID called on every WebSocket upgrade for auth. */
-                authFunctionId?: string;
-                /** Functions the connecting worker is allowed to invoke (patterns supported). */
-                exposeFunctions?: string[];
-                /** Function invoked before each handler — enrich or audit requests. */
-                middlewareFunctionId?: string;
-                /** Allow workers to register their own function handlers. Default: true */
-                allowFunctionRegistration?: boolean;
-                /** Allow workers to register new trigger types. Default: false */
-                allowTriggerTypeRegistration?: boolean;
-                /** Prefix prepended to every function the worker registers. */
-                functionRegistrationPrefix?: string;
-                /** TTL for signed browser auth tokens generated by the Nuxt proxy. Default: 120 */
-                tokenTtlSeconds?: number;
-                /** Allow browser connections without a custom resolver returning user context. Default: true */
-                allowAnonymous?: boolean;
-                /** Optional path (relative to project root) to a custom browser auth resolver module. */
-                authResolverPath?: string;
-            };
-        };
-        /**
-         * Bridge client workers — connects this engine to remote iii instances.
-         * Each entry creates an `iii-bridge` worker in the config.
-         */
-        bridge?: Array<{
-            url: string;
-            serviceId: string;
-            serviceName?: string;
-            expose?: Array<{
-                localFunction: string;
-                remoteFunction?: string;
-            }>;
-            forward?: Array<{
-                localFunction: string;
-                remoteFunction: string;
-                timeoutMs?: number;
-            }>;
-        }>;
-        /**
-         * Exec workers — spawns external processes alongside the engine.
-         * Each entry creates an `iii-exec` worker in the config.
-         */
-        exec?: Array<{
-            watch?: string[];
-            exec: string[];
-        }>;
-        /** Anonymous usage telemetry. Set enabled: false to opt out. */
-        telemetry?: {
-            enabled?: boolean;
-            apiKey?: string;
-            sdkApiKey?: string;
-            heartbeatIntervalSecs?: number;
-        };
-    };
-    functions?: {
-        /** Directory under server/ where functions are, relative to serverDir (default: 'functions') */
-        dir?: string;
-        /**
-         * Function ID prefix for this layer's functions.
-         * Set in a layer's `nuxt.config.ts` to namespace its functions.
-         * Priority: this value → `$meta.name` → package.json name → directory name.
-         * Set to `''` (empty string) to explicitly opt out of any prefix.
-         * Has no effect in the root project (always un-prefixed).
-         * Example: 'myorg::auth'
-         */
-        prefix?: string;
-        python?: {
-            /**
-             * Path to the Python executable used **in development only** (e.g. a virtualenv).
-             * Has no effect in production — set `NVENT_PYTHON_BIN` env var instead.
-             * Default: 'python3'
-             * Example: '.venv/bin/python3'
-             */
-            devPath?: string;
-            /**
-             * Skip Python worker support entirely (no Python scanning, no workers started).
-             * Useful when the project has no Python functions. Default: false
-             */
-            skip?: boolean;
-        };
-    };
-    app?: {
-        /** Enable the nvent app UI and its built-in route. Default: true */
-        enabled?: boolean;
-        /** Route path for the nvent app. Default: '/_nvent' */
-        routePath?: string;
-        /**
-         * Layout to use for the nvent app route.
-         * Set to false for no layout, or a string to use a named layout.
-         * Default: false
-         */
-        layout?: string | false;
-    };
+  iii?: {
+    /** Version of the iii engine to install. Default: 'latest' */
+    version?: string
+    /** 'local' uses a local binary, 'docker' uses Docker, 'remote' skips lifecycle management */
+    mode?: 'local' | 'docker' | 'remote'
+    /** WebSocket URL for workers to connect to (default: ws://localhost:49134) */
+    wsUrl?: string
+    /** HTTP port for iii REST API (default: 3111) */
+    httpPort?: number
+    /** HTTP host for iii REST API (default: 'localhost') */
+    httpHost?: string
+    /** WebSocket port for workers (default: 49134) */
+    wsPort?: number
+    /** WebSocket port for the Stream module (default: 3112) */
+    streamPort?: number
+    /** Whether nvent manages engine lifecycle. Default: true in dev, false in prod */
+    managed?: boolean
+    /** Exit with non-zero code if engine installation fails. Default: false */
+    failOnInstallFailure?: boolean
+    modules?: {
+      state?: boolean
+      queue?: boolean
+      cron?: boolean
+      observability?: boolean
+      stream?: boolean
+    }
+    /** State module adapter configuration */
+    state?: {
+      adapter?:
+        | { type: 'kv'; storeMethod?: 'file_based' | 'in_memory'; filePath?: string; saveIntervalMs?: number }
+        | { type: 'redis'; redisUrl?: string }
+        | { type: 'bridge'; bridgeUrl: string }
+    }
+    /**
+     * Queue module configuration.
+     * Named queues must be declared here for the iii engine to route messages through them.
+     */
+    queue?: {
+      adapter?:
+        | {
+            type: 'builtin'
+            storeMethod?: 'file_based' | 'in_memory'
+            filePath?: string
+            saveIntervalMs?: number
+            maxAttempts?: number
+            backoffMs?: number
+            concurrency?: number
+            pollIntervalMs?: number
+            /** Processing order. 'concurrent' (parallel) or 'fifo' (sequential). Default: 'concurrent' */
+            mode?: 'concurrent' | 'fifo'
+          }
+        | { type: 'redis'; redisUrl?: string }
+        | {
+            type: 'rabbitmq'
+            amqpUrl?: string
+            maxAttempts?: number
+            prefetchCount?: number
+            /** 'standard' or 'quorum' (HA replicated). Default: 'standard' */
+            queueMode?: 'standard' | 'quorum'
+          }
+        | { type: 'bridge'; bridgeUrl: string }
+      queueConfigs?: Record<string, {
+        type?: 'standard' | 'fifo'
+        concurrency?: number
+        /** Alias of maxRetries */
+        retries?: number
+        maxRetries?: number
+        /** Alias of backoffMs */
+        backoff?: number
+        backoffMs?: number
+        /** Optional visibility timeout / lease timeout if supported by the engine */
+        visibilityTimeoutMs?: number
+        leaseTimeoutMs?: number
+        /** Optional dead-letter / fallback queue names if supported by the engine */
+        deadLetterQueue?: string
+        fallbackQueue?: string
+        /** FIFO only: field in the payload used to group messages */
+        messageGroupField?: string
+      }>
+    }
+    /** Cron module adapter configuration */
+    cron?: {
+      adapter?:
+        | { type: 'kv'; lockTtlMs?: number; lockIndex?: string; storeMethod?: 'file_based' | 'in_memory'; filePath?: string; saveIntervalMs?: number }
+        | { type: 'redis'; redisUrl?: string }
+    }
+    /** WebSocket Stream module configuration */
+    stream?: {
+      host?: string
+      authFunction?: string | null
+      adapter?:
+        | { type: 'kv'; storeMethod?: 'file_based' | 'in_memory'; filePath?: string; saveIntervalMs?: number }
+        | { type: 'redis'; redisUrl?: string }
+        | { type: 'bridge'; bridgeUrl: string }
+    }
+    /** REST API module extra settings */
+    restApi?: {
+      host?: string
+      defaultTimeout?: number
+      concurrencyRequestLimit?: number
+      /** CORS configuration for browser clients */
+      cors?: {
+        /** Origins allowed to make requests. Use '*' for any, or list specific domains. */
+        allowedOrigins?: string[]
+        /** HTTP methods permitted for cross-origin requests. */
+        allowedMethods?: string[]
+      }
+    }
+    /** OtelModule (observability) configuration */
+    observability?: {
+      enabled?: boolean
+      serviceName?: string
+      serviceVersion?: string
+      serviceNamespace?: string
+      /**
+       * Trace export destination.
+       * 'memory' = queryable via iii API / console (default).
+       * 'otlp'   = external collector (set endpoint too).
+       * 'both'   = memory + otlp.
+       */
+      exporter?: 'memory' | 'otlp' | 'both'
+      endpoint?: string
+      samplingRatio?: number
+      memoryMaxSpans?: number
+      metricsEnabled?: boolean
+      metricsExporter?: 'memory' | 'otlp'
+      metricsRetentionSeconds?: number
+      metricsMaxCount?: number
+      logsEnabled?: boolean
+      logsExporter?: 'memory' | 'otlp' | 'both'
+      logsMaxCount?: number
+      logsRetentionSeconds?: number
+      logsBatchSize?: number
+      logsFlushIntervalMs?: number
+      logsSamplingRatio?: number
+      logsConsoleOutput?: boolean
+      /** Advanced sampling rules — override samplingRatio for matched operations. */
+      sampling?: {
+        default?: number
+        parentBased?: boolean
+        rules?: Array<{ operation?: string; service?: string; rate: number }>
+        rateLimit?: { maxTracesPerSecond?: number }
+      }
+      /** Alert rules — trigger a webhook or function when a metric crosses a threshold. */
+      alerts?: Array<{
+        name: string
+        metric: string
+        threshold: number
+        operator: '>' | '>=' | '<' | '<=' | '==' | '!='
+        windowSeconds: number
+        enabled?: boolean
+        cooldownSeconds?: number
+        action: { type: 'webhook'; url: string } | { type: 'function'; path: string }
+      }>
+      level?: 'trace' | 'debug' | 'info' | 'warn' | 'error'
+      format?: 'default' | 'json'
+    }
+    /**
+     * Minimum log level for iii engine output.
+     * 'none' silences all output, 'error' shows only errors, 'warn' shows warnings + errors,
+     * 'info' shows everything. Default: 'warn'
+     */
+    logLevel?: 'none' | 'error' | 'warn' | 'info'
+    /**
+     * Enable the iii-console web UI (separate binary, http://localhost:3113).
+     * Pass `true` for defaults or an object to customise.
+     */
+    console?: boolean | {
+      /** Version to install. Default: same as iii engine version */
+      version?: string
+      /** Port for the console web UI. Default: 3113 */
+      port?: number
+      /** Host for the console web UI. Default: 'localhost' */
+      host?: string
+      /** Enable the Flow visualization page */
+      flow?: boolean
+    }
+    /** PubSub worker — topic-based event fanout across functions. */
+    pubsub?: {
+      adapter?:
+        | { type: 'local' }
+        | { type: 'redis'; redisUrl?: string }
+    }
+    /**
+     * HTTP Functions worker — enables outbound HTTP calls from the engine.
+     * Required for functions registered with HttpInvocationConfig.
+     */
+    httpFunctions?: {
+      security?: {
+        /** URL patterns allowed for outbound requests. Use '*' to allow all. */
+        urlAllowlist?: string[]
+        /** Block requests to private/internal IP ranges (SSRF prevention). Default: true */
+        blockPrivateIps?: boolean
+        /** Require HTTPS for all outbound requests. Default: true */
+        requireHttps?: boolean
+      }
+    }
+    /**
+     * Additional iii-worker-manager instance with RBAC.
+     * nvent uses this automatically when browser SDK is enabled.
+     * Can also be configured manually for custom auth scenarios.
+     */
+    workerManager?: {
+      rbac?: {
+        /** Port for the RBAC worker manager. Default: 49135 */
+        port?: number
+        /** Function ID called on every WebSocket upgrade for auth. */
+        authFunctionId?: string
+        /** Functions the connecting worker is allowed to invoke (patterns supported). */
+        exposeFunctions?: string[]
+        /** Function invoked before each handler — enrich or audit requests. */
+        middlewareFunctionId?: string
+        /** Allow workers to register their own function handlers. Default: true */
+        allowFunctionRegistration?: boolean
+        /** Allow workers to register new trigger types. Default: false */
+        allowTriggerTypeRegistration?: boolean
+        /** Prefix prepended to every function the worker registers. */
+        functionRegistrationPrefix?: string
+        /** TTL for signed browser auth tokens generated by the Nuxt proxy. Default: 120 */
+        tokenTtlSeconds?: number
+        /** Allow browser connections without a custom resolver returning user context. Default: true */
+        allowAnonymous?: boolean
+        /** Optional path (relative to project root) to a custom browser auth resolver module. */
+        authResolverPath?: string
+      }
+    }
+    /**
+     * Bridge client workers — connects this engine to remote iii instances.
+     * Each entry creates an `iii-bridge` worker in the config.
+     */
+    bridge?: Array<{
+      url: string
+      serviceId: string
+      serviceName?: string
+      expose?: Array<{ localFunction: string; remoteFunction?: string }>
+      forward?: Array<{ localFunction: string; remoteFunction: string; timeoutMs?: number }>
+    }>
+    /**
+     * Exec workers — spawns external processes alongside the engine.
+     * Each entry creates an `iii-exec` worker in the config.
+     */
+    exec?: Array<{
+      watch?: string[]
+      exec: string[]
+    }>
+    /** Anonymous usage telemetry. Set enabled: false to opt out. */
+    telemetry?: {
+      enabled?: boolean
+      apiKey?: string
+      sdkApiKey?: string
+      heartbeatIntervalSecs?: number
+    }
+  }
+  functions?: {
+    /** Directory under server/ where functions are, relative to serverDir (default: 'functions') */
+    dir?: string
+    /**
+     * Function ID prefix for this layer's functions.
+     * Set in a layer's `nuxt.config.ts` to namespace its functions.
+     * Priority: this value → `$meta.name` → package.json name → directory name.
+     * Set to `''` (empty string) to explicitly opt out of any prefix.
+     * Has no effect in the root project (always un-prefixed).
+     * Example: 'myorg::auth'
+     */
+    prefix?: string
+    python?: {
+      /**
+       * Path to the Python executable used **in development only** (e.g. a virtualenv).
+       * Has no effect in production — set `NVENT_PYTHON_BIN` env var instead.
+       * Default: 'python3'
+       * Example: '.venv/bin/python3'
+       */
+      devPath?: string
+      /**
+       * Skip Python worker support entirely (no Python scanning, no workers started).
+       * Useful when the project has no Python functions. Default: false
+       */
+      skip?: boolean
+    }
+  }
+  app?: {
+    /** Enable the nvent app UI and its built-in route. Default: true */
+    enabled?: boolean
+    /** Route path for the nvent app. Default: '/_nvent' */
+    routePath?: string
+    /**
+     * Layout to use for the nvent app route.
+     * Set to false for no layout, or a string to use a named layout.
+     * Default: false
+     */
+    layout?: string | false
+  }
 }
 
 interface LayerInfo {

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "nvent",
-  "version": "1.0.0-alpha.11",
+  "version": "1.0.0-alpha.12",
   "configKey": "nvent",
   "builder": {
     "@nuxt/module-builder": "1.0.2",

package/dist/module.mjs

@@ -699,8 +699,100 @@ async function ensureIiiEngine(options) {
   if (!existsSync(binDir)) {
     mkdirSync(binDir, { recursive: true });
   }
-  const asset = getPlatformAsset(version);
-  await downloadAndExtract(asset.url, asset.ext, binDir, logLevel);
+  getPlatformAsset(version);
+  const tried = [];
+  async function tryDownloadForVersion(ver) {
+    try {
+      const a = getPlatformAsset(ver);
+      tried.push(a.url);
+      await downloadAndExtract(a.url, a.ext, binDir, logLevel);
+      return true;
+    } catch (err) {
+      if (logLevel === "info") logger$1.info(`Download for ${ver} failed: ${String(err)}`);
+      return false;
+    }
+  }
+  let downloaded = false;
+  downloaded = await tryDownloadForVersion(version);
+  if (!downloaded && !version.includes("/")) {
+    const releaseTag = toReleaseTag$1(version);
+    const variants = [
+      `iii/${releaseTag}`,
+      releaseTag,
+      semverFromTag$1(releaseTag),
+      `iii/${semverFromTag$1(releaseTag)}`
+    ];
+    for (const v of variants) {
+      if (downloaded) break;
+      if (v === version) continue;
+      downloaded = await tryDownloadForVersion(v);
+    }
+  }
+  if (!downloaded) {
+    const candidateTags = [version];
+    if (!version.includes("/")) candidateTags.push(toReleaseTag$1(version), `iii/${toReleaseTag$1(version)}`);
+    for (const tag of candidateTags) {
+      try {
+        const apiUrl = `https://api.github.com/repos/iii-hq/iii/releases/tags/${encodeURIComponent(tag)}`;
+        if (logLevel === "info") logger$1.info(`Querying GitHub Release: ${apiUrl}`);
+        const res = await fetch(apiUrl, { headers: { "Accept": "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28" } });
+        if (!res.ok) {
+          if (logLevel === "info") logger$1.info(`GitHub API responded ${res.status} ${res.statusText} for tag ${tag}`);
+          continue;
+        }
+        const data = await res.json();
+        const assets = Array.isArray(data.assets) ? data.assets : [];
+        const platformCandidates = [
+          "x86_64-unknown-linux-gnu",
+          "aarch64-unknown-linux-gnu",
+          "x86_64-apple-darwin",
+          "aarch64-apple-darwin",
+          "x86_64-pc-windows-msvc",
+          "aarch64-pc-windows-msvc"
+        ];
+        const match = assets.find((a) => platformCandidates.some((p) => a.name.includes(p)));
+        if (match && match.browser_download_url) {
+          if (logLevel === "info") logger$1.info(`Found asset via GitHub API: ${match.name}`);
+          await downloadAndExtract(match.browser_download_url, match.name.endsWith(".zip") ? "zip" : "tar.gz", binDir, logLevel);
+          downloaded = true;
+          break;
+        }
+      } catch (err) {
+        if (logLevel === "info") logger$1.info(`GitHub API lookup failed for tag ${tag}: ${String(err)}`);
+        continue;
+      }
+    }
+  }
+  if (!downloaded) {
+    try {
+      const releasesRes = await fetch("https://api.github.com/repos/iii-hq/iii/releases?per_page=50", {
+        headers: { "Accept": "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28" }
+      });
+      let tags = [];
+      if (releasesRes.ok) {
+        const releases = await releasesRes.json();
+        tags = releases.map((r) => r.tag_name).filter(Boolean);
+      } else {
+        try {
+          const tagsRes = await fetch("https://api.github.com/repos/iii-hq/iii/tags?per_page=50", {
+            headers: { "Accept": "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28" }
+          });
+          if (tagsRes.ok) {
+            const tagsData = await tagsRes.json();
+            tags = tagsData.map((t) => t.name).filter(Boolean);
+          }
+        } catch {
+        }
+      }
+      const shown = tags.slice(0, 20);
+      const tagPart = shown.length ? ` Available release tags (first ${shown.length}): ${shown.join(", ")}.` : "";
+      throw new Error(
+        `Failed to download iii engine from tried URLs: ${tried.join(", ")}.` + tagPart + ` Set a matching 'nvent.iii.version' in your nuxt config (e.g. 'iii/v0.22.1' or 'v0.22.1').`
+      );
+    } catch (err) {
+      throw new Error(`Failed to download iii engine from tried URLs: ${tried.join(", ")}. (${String(err)})`);
+    }
+  }
   if (process.platform !== "win32") {
     chmodSync(binaryPath, 493);
   }
@@ -1352,6 +1444,7 @@ const module$1 = defineNuxtModule({
     const managed = iiiOpts.managed ?? mode === "local";
     const version = iiiOpts.version ?? "latest";
     const logLevel = iiiOpts.logLevel ?? "warn";
+    const failOnInstallFailure = iiiOpts.failOnInstallFailure ?? false;
     const consoleCfg = typeof iiiOpts.console === "object" ? iiiOpts.console : {};
     installNventPyToSitePackages(pythonBin, readFileSync(PYTHON_NVENT_HELPER_SRC, "utf-8"));
     if (hasNuxtModule("@nvent-addon/app")) {
@@ -1547,44 +1640,74 @@ const module$1 = defineNuxtModule({
       const nventDir = join(nuxt.options.rootDir, "node_modules", ".nvent");
       const binDir = join(nventDir, "bin");
       if (managed && mode === "local") {
-        const binaryPath = await ensureIiiEngine({ binDir, version, logLevel });
-        const consoleBinaryPath = iiiOpts.console ? await ensureIiiConsole({ binDir, version: consoleCfg.version ?? version, logLevel }) : void 0;
-        const nventConfigPath = join(nventDir, "iii-config.yaml");
-        writeIiiConfig(nventConfigPath, engineCfg);
-        const engine = createEngineManager({
-          binaryPath,
-          configPath: nventConfigPath,
-          httpPort: engineCfg.httpPort,
-          wsPort: engineCfg.wsPort,
-          logLevel
-        });
-        await engine.start();
-        nuxt.hook("close", async () => {
-          await engine.stop();
-        });
-        if (consoleBinaryPath) {
-          const consolePort = consoleCfg.port ?? 3113;
-          const consoleManager = new ConsoleManager({
-            binaryPath: consoleBinaryPath,
-            port: consolePort,
-            enginePort: engineCfg.httpPort,
-            bridgePort: engineCfg.wsPort,
-            flow: consoleCfg.flow ?? true,
+        let binaryPath;
+        let consoleBinaryPath;
+        try {
+          binaryPath = await ensureIiiEngine({ binDir, version, logLevel });
+          consoleBinaryPath = iiiOpts.console ? await ensureIiiConsole({ binDir, version: consoleCfg.version ?? version, logLevel }) : void 0;
+        } catch (err) {
+          console.error("[nvent] III engine installation failed \u2014 skipping engine start. Error:");
+          if (err && err.stack) console.error(err.stack);
+          else console.error(JSON.stringify(err, Object.getOwnPropertyNames(err)));
+          if (failOnInstallFailure) {
+            console.error("[nvent] failOnInstallFailure enabled \u2014 aborting startup.");
+            process.exit(1);
+          }
+        }
+        if (binaryPath) {
+          const nventConfigPath = join(nventDir, "iii-config.yaml");
+          writeIiiConfig(nventConfigPath, engineCfg);
+          const engine = createEngineManager({
+            binaryPath,
+            configPath: nventConfigPath,
+            httpPort: engineCfg.httpPort,
+            wsPort: engineCfg.wsPort,
+            workingDir: nventDir,
             logLevel
           });
-          await consoleManager.start();
-          nuxt.hook("close", async () => {
-            await consoleManager.stop();
-          });
-          addCustomTab({
-            name: "nvent-console",
-            title: "nvent",
-            icon: "carbon:flow",
-            view: {
-              type: "iframe",
-              src: `http://localhost:${consolePort}`
+          try {
+            await engine.start();
+            nuxt.hook("close", async () => {
+              await engine.stop();
+            });
+          } catch (err) {
+            console.error("[nvent] Failed to start iii engine \u2014 continuing without engine. Error:");
+            if (err && err.stack) console.error(err.stack);
+            else console.error(JSON.stringify(err, Object.getOwnPropertyNames(err)));
+            if (failOnInstallFailure) {
+              console.error("[nvent] failOnInstallFailure enabled \u2014 aborting startup.");
+              process.exit(1);
             }
-          });
+          }
+          if (consoleBinaryPath) {
+            const consolePort = consoleCfg.port ?? 3113;
+            const consoleManager = new ConsoleManager({
+              binaryPath: consoleBinaryPath,
+              port: consolePort,
+              enginePort: engineCfg.httpPort,
+              bridgePort: engineCfg.wsPort,
+              flow: consoleCfg.flow ?? true,
+              logLevel
+            });
+            try {
+              await consoleManager.start();
+              nuxt.hook("close", async () => {
+                await consoleManager.stop();
+              });
+              addCustomTab({
+                name: "nvent-console",
+                title: "nvent",
+                icon: "carbon:flow",
+                view: {
+                  type: "iframe",
+                  src: `http://localhost:${consolePort}`
+                }
+              });
+            } catch (err) {
+              console.error("[nvent] Failed to start iii console UI \u2014 continuing. Error:");
+              console.error(err && err.message ? err.message : err);
+            }
+          }
         }
       }
       if (!skipPython) {
@@ -1630,17 +1753,26 @@ const module$1 = defineNuxtModule({
     } else {
       if (managed && mode === "local") {
         const binDir = join(nuxt.options.rootDir, "node_modules", ".nvent", "bin");
-        const binaryPath = await ensureIiiEngine({ binDir, version, logLevel });
-        const consoleBinaryPath = iiiOpts.console ? await ensureIiiConsole({ binDir, version: consoleCfg.version ?? version, logLevel }) : void 0;
-        nuxt.hook("nitro:build:public-assets", async (nitro) => {
-          const outputNventDir = join(nitro.options.output.dir, "nvent");
-          const outputBinDir = join(outputNventDir, "bin");
-          mkdirSync(outputBinDir, { recursive: true });
-          copyFileSync(binaryPath, join(outputBinDir, basename(binaryPath)));
-          if (consoleBinaryPath) copyFileSync(consoleBinaryPath, join(outputBinDir, basename(consoleBinaryPath)));
-          writeFileSync(join(outputNventDir, "iii-config.yaml"), engineConfigYaml, "utf-8");
-          console.log("[nvent] Engine binaries + config copied to .output/nvent/");
-        });
+        let binaryPath;
+        let consoleBinaryPath;
+        try {
+          binaryPath = await ensureIiiEngine({ binDir, version, logLevel });
+          consoleBinaryPath = iiiOpts.console ? await ensureIiiConsole({ binDir, version: consoleCfg.version ?? version, logLevel }) : void 0;
+        } catch (err) {
+          console.warn("[nvent] Could not download iii engine for build embedding \u2014 skipping binary copy. Error:");
+          console.warn(err && err.message ? err.message : err);
+        }
+        if (binaryPath) {
+          nuxt.hook("nitro:build:public-assets", async (nitro) => {
+            const outputNventDir = join(nitro.options.output.dir, "nvent");
+            const outputBinDir = join(outputNventDir, "bin");
+            mkdirSync(outputBinDir, { recursive: true });
+            copyFileSync(binaryPath, join(outputBinDir, basename(binaryPath)));
+            if (consoleBinaryPath) copyFileSync(consoleBinaryPath, join(outputBinDir, basename(consoleBinaryPath)));
+            writeFileSync(join(outputNventDir, "iii-config.yaml"), engineConfigYaml, "utf-8");
+            console.log("[nvent] Engine binaries + config copied to .output/nvent/");
+          });
+        }
       }
       if (!skipPython) {
         nuxt.hook("nitro:build:public-assets", async (nitro) => {

package/dist/runtime/nitro/server.d.ts

@@ -10,5 +10,6 @@
 export { defineFunction } from './utils/defineFunction.js';
 export type { FunctionDef, FunctionHandler, TriggerConfig, HttpTriggerConfig, CronTriggerConfig, QueueTriggerConfig, StateTriggerConfig, StreamTriggerConfig, SubscribeTriggerConfig, LogTriggerConfig, CustomTriggerConfig, HttpRequest, } from './utils/defineFunction.js';
 export { useIii, useIiiHealth } from './utils/useIii.js';
-export { Logger, registerWorker, TriggerAction } from 'iii-sdk';
-export type { ISdk, InitOptions, TriggerConfig as IiiTriggerConfig } from 'iii-sdk';
+export { registerWorker, TriggerAction } from 'iii-sdk';
+export { Logger } from '@iii-dev/helpers/observability';
+export type { IIIClient, InitOptions } from 'iii-sdk';

package/dist/runtime/nitro/server.js

@@ -1,3 +1,4 @@
 export { defineFunction } from "./utils/defineFunction.js";
 export { useIii, useIiiHealth } from "./utils/useIii.js";
-export { Logger, registerWorker, TriggerAction } from "iii-sdk";
+export { registerWorker, TriggerAction } from "iii-sdk";
+export { Logger } from "@iii-dev/helpers/observability";

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

@@ -10,6 +10,8 @@ export interface EngineManagerOptions {
     configPath: string;
     httpPort?: number;
     wsPort?: number;
+    /** Working directory for the engine process. Defaults to process.cwd() */
+    workingDir?: string;
     /** Minimum log level for engine output. Default: 'warn' */
     logLevel?: 'none' | 'error' | 'warn' | 'info';
 }

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

@@ -50,7 +50,13 @@ export class EngineManager {
   pendingGroup = null;
   pendingTimer = null;
   constructor(opts) {
-    this.opts = { httpPort: 3111, wsPort: 49134, logLevel: "warn", ...opts };
+    this.opts = {
+      httpPort: 3111,
+      wsPort: 49134,
+      logLevel: "warn",
+      workingDir: process.cwd(),
+      ...opts
+    };
   }
   isRunning() {
     return this.process !== null && !this.process.killed && this.process.exitCode === null;
@@ -126,7 +132,8 @@ export class EngineManager {
     this.startupComplete = false;
     this.process = spawn(binaryPath, ["--config", configPath], {
       stdio: ["ignore", "pipe", "pipe"],
-      detached: false
+      detached: false,
+      cwd: this.opts.workingDir
     });
     this.process.stdout?.on("data", (chunk) => {
       for (const line of chunk.toString().split("\n").filter(Boolean))

package/dist/runtime/python/nvent.py

@@ -35,11 +35,13 @@ def cron(expression: str) -> dict:
 
 
 # ── Request / Response ─────────────────────────────────────────────────────
+# Stubs for Pylance. Runtime imports real types from iii_helpers.http via _runtime.py.
 
-class ApiRequest:
+class HttpRequest:
     """HTTP request input for http-triggered Python functions.
 
-    The iii SDK uses snake_case field names:
+    The iii SDK 0.21.3+ uses HttpRequest from iii_helpers.http.
+    Fields use snake_case:
       req.headers       — dict[str, str]
       req.method        — 'GET' | 'POST' | ...
       req.path_params   — dict[str, str]
@@ -53,23 +55,51 @@ class ApiRequest:
     body: Optional[Any]
 
 
-class ApiResponse:
+class HttpResponse:
     """HTTP response returned from an http-triggered handler.
 
+    The iii SDK 0.21.3+ uses HttpResponse from iii_helpers.http.
+
     Example::
 
-        return ApiResponse(statusCode=200, body={"ok": True})
-        return ApiResponse(statusCode=201, body=result, headers={"x-request-id": rid})
+        return HttpResponse(status_code=200, body={"ok": True})
+        return HttpResponse(status_code=201, body=result, headers={"x-request-id": rid})
     """
     def __init__(
         self,
         *,
-        statusCode: int = 200,
+        status_code: int = 200,
         body: Any = None,
         headers: dict[str, str] = None,
     ) -> None: ...
 
 
+# Backward compatibility aliases
+ApiRequest = HttpRequest
+ApiResponse = HttpResponse
+
+
+# ── Logger ─────────────────────────────────────────────────────────────────
+# Stub for Pylance. Runtime imports real Logger from iii_helpers.observability.
+
+class Logger:
+    """Structured logger from iii_helpers.observability.
+    
+    Emits logs as OpenTelemetry LogRecords with automatic trace/span correlation.
+    
+    Usage::
+    
+        logger = Logger("my-function")
+        logger.info("Processing order", {"orderId": order_id})
+        logger.error("Validation failed", {"field": "email"})
+    """
+    def __init__(self, name: str = "nvent"): ...
+    def debug(self, message: str, attributes: dict[str, Any] | None = None) -> None: ...
+    def info(self, message: str, attributes: dict[str, Any] | None = None) -> None: ...
+    def warn(self, message: str, attributes: dict[str, Any] | None = None) -> None: ...
+    def error(self, message: str, attributes: dict[str, Any] | None = None) -> None: ...
+
+
 # ── Stream ─────────────────────────────────────────────────────────────────
 
 class IStream:
@@ -314,8 +344,10 @@ try:
         cron,
         define_function,
         FlowContext,
+        ApiRequest,
+        ApiResponse,
     )
-    from iii import ApiRequest, ApiResponse, Logger  # type: ignore[no-redef]  # noqa: F401, E402
+    from iii_helpers.observability import Logger  # type: ignore[no-redef]  # noqa: F401, E402
 except ImportError:
     pass
 

package/dist/runtime/python/worker_runtime.py

@@ -22,8 +22,10 @@ import logging as _logging
 
 try:
     import iii as _iii_sdk
+    from iii_helpers.http import HttpRequest as _HttpRequest, HttpResponse as _HttpResponse
+    from iii_helpers.observability import Logger
 except ImportError:
-    print("[nvent] iii package not found — install it: pip install iii-sdk[otel]", flush=True)
+    print("[nvent] iii package not found — install it: pip install iii-sdk[otel] iii-helpers", flush=True)
     sys.exit(1)
 
 # Direct Python logging to stdout so nvent captures it alongside other output.
@@ -103,6 +105,15 @@ def set_span_ok(span) -> None:
 _NVENT_STREAM_KEY = '__nventStream'
 
 
+# ---------------------------------------------------------------------------
+# HTTP Request/Response wrappers — convenience aliases for iii_helpers.http
+# ---------------------------------------------------------------------------
+
+# Expose iii_helpers.http types as ApiRequest/ApiResponse for backward compatibility
+ApiRequest = _HttpRequest
+ApiResponse = _HttpResponse
+
+
 # ---------------------------------------------------------------------------
 # Trigger config helpers — use these in config["triggers"]
 # ---------------------------------------------------------------------------
@@ -403,7 +414,7 @@ class FlowContext:
         self._input = input_data
         self._stream_name = stream_name or fn_id.split("::")[0]
         self._stream_group_id = inherited_group_id
-        self.logger = _iii_sdk.Logger(fn_id)
+        self.logger = Logger(fn_id)
         self.state = _State(client, fn_id)
         self.stream = _Stream(client, self._stream_name, self._get_or_create_group_id)
 
@@ -621,7 +632,8 @@ def _register_one(client, mod, default_id: str, fn_def: dict) -> None:
 
         def _make_wrapper_thin(_h, _is_http):
             async def _wrapped(data):
-                input_data = _iii_sdk.ApiRequest(**data) if (_is_http and isinstance(data, dict)) else data
+                # Wrap dict in HttpRequest for HTTP triggers
+                input_data = ApiRequest(**data) if (_is_http and isinstance(data, dict)) else data
                 return await _h(input_data)
             return _wrapped
 
@@ -702,7 +714,8 @@ def _register_legacy(client, mod, default_id: str) -> None:
                         inherited_group = nvent_stream.get('groupId')
                         effective_stream = nvent_stream.get('name') or _stream_name
                     clean_data = {k: v for k, v in data.items() if k != _NVENT_STREAM_KEY}
-                input_data = _iii_sdk.ApiRequest(**clean_data) if (_is_http and isinstance(clean_data, dict)) else clean_data
+                # Wrap dict in HttpRequest for HTTP triggers
+                input_data = ApiRequest(**clean_data) if (_is_http and isinstance(clean_data, dict)) else clean_data
                 if not _hc:
                     return await _h(input_data)
                 ctx = FlowContext(client, _fn_id, _t_type, input_data, effective_stream, inherited_group)

package/dist/runtime/virtual.d.ts

@@ -30,6 +30,7 @@ declare module '#nvent/server' {
     HttpRequest,
   } from '../nitro/utils/defineFunction'
   export { useIii, useIiiHealth } from '../nitro/utils/useIii'
-  export { Logger, registerWorker, TriggerAction } from 'iii-sdk'
-  export type { ISdk, InitOptions } from 'iii-sdk'
+  export { registerWorker, TriggerAction } from 'iii-sdk'
+  export { Logger } from '@iii-dev/helpers/observability'
+  export type { IIIClient, InitOptions} from 'iii-sdk'
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nvent",
-  "version": "1.0.0-alpha.11",
+  "version": "1.0.0-alpha.12",
 
   "description": "Event-driven workflows for Nuxt",
   "repository": "nhealthorg/nvent",
@@ -24,22 +24,23 @@
   },
   "dependencies": {
     "@nuxt/devtools-kit": "^3.2.4",
-    "@nuxt/kit": "4.4.4",
+    "@nuxt/kit": "4.4.8",
     "chokidar": "^5.0.0",
     "confbox": "^0.2.4",
-    "globby": "16.2.0",
-    "iii-browser-sdk": "^0.11.6",
-    "iii-sdk": "^0.11.6",
+    "globby": "16.2.1",
+    "iii-browser-sdk": "0.21.3",
+    "iii-sdk": "0.21.3",
+    "@iii-dev/helpers": "0.21.3",
     "knitwork": "^1.3.0",
-    "nuxt": "4.4.4",
+    "nuxt": "4.4.8",
     "pathe": "^2.0.3",
     "perfect-debounce": "^2.1.0"
   },
   "devDependencies": {
     "@nuxt/module-builder": "^1.0.2",
-    "@nuxt/schema": "4.4.4",
-    "@types/node": "^25.6.0",
-    "typescript": "latest",
-    "vitest": "^4.1.5"
+    "@nuxt/schema": "4.4.8",
+    "@types/node": "^26.1.1",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.10"
   }
 }