@ollie-shop/cli 1.2.1 → 1.2.2

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @ollie-shop/cli@1.2.1 build /home/runner/work/ollie-shop/ollie-shop/packages/cli
+> @ollie-shop/cli@1.2.2 build /home/runner/work/ollie-shop/ollie-shop/packages/cli
 > tsup
 
 CLI Building entry: src/index.tsx
@@ -9,5 +9,5 @@
 CLI Target: node22
 CLI Cleaning output folder
 ESM Build start
-ESM dist/index.js 78.88 KB
-ESM ⚡️ Build success in 157ms
+ESM dist/index.js 85.34 KB
+ESM ⚡️ Build success in 216ms

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @ollie-shop/cli
 
+## 1.2.2
+
+### Patch Changes
+
+- 0268a4b: Bake prod Supabase + builder defaults into the CLI so `ollieshop` runs with zero env setup.
+
+  Agent commands (`whoami`, `store`, `version`, `component`, `function`, `deploy`, `status`) previously threw `Missing required environment variable: OLLIE_SUPABASE_URL` unless the user had exported `OLLIE_SUPABASE_URL`, `OLLIE_SUPABASE_ANON_KEY`, and `OLLIE_BUILDER_URL` in their shell first. All three values are public, so the friction was pure onboarding overhead.
+
+  `packages/cli/src/utils/supabase.ts` now holds a `PROD_DEFAULTS` const and an `envOrDefault()` helper. Env vars still win when set, so devs pointing the CLI at local Supabase (`http://127.0.0.1:54321`) or a non-prod project are unaffected. Fresh contributors can now run `ollieshop login && ollieshop whoami` without any shell setup.
+
 ## 1.2.1
 
 ### Patch Changes

package/CONTEXT.md

@@ -33,6 +33,7 @@ The CLI will throw a clear error if a required env var is missing. See `.env.exa
 ollieshop schema store.create -o json
 ollieshop schema version.create -o json
 ollieshop schema component.create -o json
+ollieshop schema function.create -o json
 
 # 2. Verify identity
 ollieshop whoami -o json
@@ -50,17 +51,21 @@ ollieshop init --store-id <STORE_ID> --version-id <VERSION_ID>
 # 6. Register components
 ollieshop component create --data '{"versionId":"<VERSION_ID>","name":"FreeShippingBar","slot":"cart_header_full_page","active":true}' -o json
 
-# 7. Deploy component (bundle + upload + build)
+# 7. Register functions (optional)
+ollieshop function create --data '{"versionId":"<VERSION_ID>","name":"myHook","active":true}' -o json
+
+# 8. Deploy component (bundle + upload + build)
 ollieshop deploy --component-id <COMPONENT_ID> --name FreeShippingBar --wait -o json
 
-# 8. Check build status
+# 9. Check build status
 ollieshop status --build-id <BUILD_ID> -o json
 ollieshop status --build-id <BUILD_ID> --wait --timeout 300 -o json
 
-# 9. List resources
+# 10. List resources
 ollieshop store list -o json --fields id,name,platform
 ollieshop version list --store-id <STORE_ID> -o json --fields id,name,active
 ollieshop component list --store-id <STORE_ID> -o json --fields id,name,slot,active
+ollieshop function list --store-id <STORE_ID> -o json --fields id,name,active
 ```
 
 ## Deploy Workflow

package/README.md

@@ -106,6 +106,18 @@ ollieshop component list --store-id <STORE_UUID> -o json --fields id,name,slot,a
 ollieshop component create --version-id <VERSION_UUID> --name FreeShippingBar --slot cart_header_full_page -o json
 ```
 
+#### `function create|list`
+
+Create or list functions for a version.
+
+```bash
+# List functions
+ollieshop function list --store-id <STORE_UUID> -o json --fields id,name,active
+
+# Create a function
+ollieshop function create --version-id <VERSION_UUID> --name myHook -o json
+```
+
 #### `deploy`
 
 Bundle a component directory into a zip and upload to the Builder service.
@@ -207,6 +219,7 @@ src/
 │   ├── store-cmd.ts     # Agent: store CRUD
 │   ├── version-cmd.ts   # Agent: version CRUD
 │   ├── component-cmd.ts # Agent: component CRUD
+│   ├── function-cmd.ts  # Agent: function CRUD
 │   ├── deploy-cmd.ts    # Agent: bundle + upload builds
 │   ├── status-cmd.ts    # Agent: check/poll build status
 │   ├── schema-cmd.ts    # Agent: schema introspection
@@ -218,6 +231,7 @@ src/
 │   ├── store.ts         # Store business logic + Supabase queries
 │   ├── version.ts       # Version business logic + Supabase queries
 │   ├── component.ts     # Component business logic + Supabase queries
+│   ├── function.ts      # Function business logic + Supabase queries
 │   ├── deploy.ts        # Builder API client (upload, status, poll)
 │   └── schema.ts        # Zod schemas + JSON Schema generation
 └── utils/

package/dist/index.js

@@ -50,6 +50,10 @@ function HelpCommand() {
         /* @__PURE__ */ jsx(Box, { width: 24, children: /* @__PURE__ */ jsx(Text, { color: "green", children: "component create|list" }) }),
         /* @__PURE__ */ jsx(Text, { children: "Create or list components" })
       ] }),
+      /* @__PURE__ */ jsxs(Box, { children: [
+        /* @__PURE__ */ jsx(Box, { width: 24, children: /* @__PURE__ */ jsx(Text, { color: "green", children: "function create|list" }) }),
+        /* @__PURE__ */ jsx(Text, { children: "Create or list functions" })
+      ] }),
       /* @__PURE__ */ jsxs(Box, { children: [
         /* @__PURE__ */ jsx(Box, { width: 24, children: /* @__PURE__ */ jsx(Text, { color: "green", children: "deploy" }) }),
         /* @__PURE__ */ jsx(Text, { children: "Bundle and upload a component/function build" })
@@ -121,6 +125,7 @@ function HelpCommand() {
       ] }),
       /* @__PURE__ */ jsx(Text, { dimColor: true, children: "$ ollieshop version create --store-id UUID --name v1 --active" }),
       /* @__PURE__ */ jsx(Text, { dimColor: true, children: "$ ollieshop init --store-id UUID --version-id UUID" }),
+      /* @__PURE__ */ jsx(Text, { dimColor: true, children: "$ ollieshop function create --version-id UUID --name myHook" }),
       /* @__PURE__ */ jsx(Text, { dimColor: true, children: "$ ollieshop deploy --component-id UUID --name FreeShippingBar --wait" }),
       /* @__PURE__ */ jsx(Text, { dimColor: true, children: "$ ollieshop status --build-id BUILD_ID --wait -o json" })
     ] })
@@ -1467,6 +1472,39 @@ function validateRequired(value, name) {
   }
   return rejectControlChars(value.trim(), name);
 }
+function validateInteger(value, name, opts) {
+  const n = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : Number.NaN;
+  if (!Number.isFinite(n) || !Number.isInteger(n)) {
+    throw new Error(`Invalid ${name}: "${String(value)}". Must be an integer.`);
+  }
+  if (opts?.min !== void 0 && n < opts.min) {
+    throw new Error(`Invalid ${name}: ${n}. Must be >= ${opts.min}.`);
+  }
+  return n;
+}
+function validateTriggerUrl(value, name) {
+  rejectControlChars(value, name);
+  const trimmed = value.trim();
+  if (trimmed === "") {
+    throw new Error(
+      `Invalid ${name}: must be a non-empty absolute http(s) URL or a relative path starting with "/".`
+    );
+  }
+  if (trimmed.startsWith("/")) {
+    return trimmed;
+  }
+  try {
+    const parsed2 = new URL(trimmed);
+    if (parsed2.protocol !== "http:" && parsed2.protocol !== "https:") {
+      throw new Error("unsupported protocol");
+    }
+    return trimmed;
+  } catch {
+    throw new Error(
+      `Invalid ${name}: "${value}". Must be an absolute http(s) URL or a relative path starting with "/".`
+    );
+  }
+}
 
 // src/commands/business-rule-cmd.ts
 async function businessRuleCommand(parsed2) {
@@ -1625,8 +1663,12 @@ var componentListSchema = z2.object({
 var functionCreateSchema = z2.object({
   versionId: z2.string().uuid().describe("Parent version UUID"),
   name: z2.string().min(1).describe("Function name"),
-  trigger: z2.string().min(1).describe("Function trigger (e.g. beforePayment, afterShipping)"),
-  active: z2.boolean().default(true).describe("Whether function is active")
+  trigger: z2.string().min(1).optional().describe(
+    "Function trigger URL \u2014 absolute http(s) URL or relative path starting with /"
+  ),
+  active: z2.boolean().default(false).describe("Whether function is active (default: false)"),
+  onError: z2.enum(["throw", "skip"]).optional().describe("Error handling: throw (default) or skip"),
+  priority: z2.number().int().min(0).optional().describe("Execution order priority (default: 0)")
 });
 var functionListSchema = z2.object({
   versionId: z2.string().uuid().describe("Version UUID to list functions for")
@@ -2005,6 +2047,137 @@ async function deployCommand(parsed2) {
   }
 }
 
+// src/core/function.ts
+async function createFunction(client, input) {
+  const parsed2 = functionCreateSchema.safeParse(input);
+  if (!parsed2.success) {
+    return {
+      success: false,
+      error: {
+        message: parsed2.error.issues.map((i) => i.message).join("; ")
+      }
+    };
+  }
+  const { data, error } = await client.from("functions").insert({
+    name: parsed2.data.name,
+    active: parsed2.data.active,
+    version_id: parsed2.data.versionId,
+    trigger: parsed2.data.trigger ?? null,
+    on_error: parsed2.data.onError ?? "throw",
+    priority: parsed2.data.priority ?? 0
+  }).select("id").single();
+  if (error) {
+    return { success: false, error: { message: error.message } };
+  }
+  return { success: true, data: { id: data.id } };
+}
+async function listFunctions(client, storeId, versionId) {
+  let query = client.from("functions").select(
+    "id, name, active, urn, on_error, priority, trigger, invocation, version_id, created_at, versions!inner(id, name)"
+  ).eq("versions.store_id", storeId);
+  if (versionId) {
+    query = query.eq("versions.id", versionId);
+  }
+  const { data, error } = await query;
+  if (error) {
+    return { success: false, error: { message: error.message } };
+  }
+  return { success: true, data: data ?? [] };
+}
+
+// src/commands/function-cmd.ts
+var ON_ERROR_VALUES = ["throw", "skip"];
+async function functionCommand(parsed2) {
+  const sub = parsed2.subcommand;
+  if (sub === "create") return functionCreateCommand(parsed2);
+  if (sub === "list" || sub === "ls") return functionListCommand(parsed2);
+  console.error(
+    `Unknown function subcommand: ${sub}. Use: function create | function list`
+  );
+  process.exit(1);
+}
+async function functionCreateCommand(parsed2) {
+  const format = detectOutputFormat(parsed2.global.output);
+  try {
+    let input;
+    if (parsed2.global.data) {
+      const raw = JSON.parse(parsed2.global.data);
+      input = {
+        versionId: validateUuid(raw.versionId, "versionId"),
+        name: validateRequired(raw.name, "name"),
+        trigger: raw.trigger !== void 0 && raw.trigger !== null ? validateTriggerUrl(String(raw.trigger), "trigger") : void 0,
+        active: raw.active === true,
+        onError: raw.onError !== void 0 && raw.onError !== null ? validateEnum(String(raw.onError), ON_ERROR_VALUES, "on-error") : "throw",
+        priority: raw.priority !== void 0 && raw.priority !== null ? validateInteger(raw.priority, "priority", { min: 0 }) : 0
+      };
+    } else {
+      const triggerFlag = getFlag(parsed2.flags, "trigger");
+      const onErrorFlag = getFlag(parsed2.flags, "on-error");
+      const priorityFlag = getFlag(parsed2.flags, "priority");
+      input = {
+        versionId: validateUuid(
+          validateRequired(getFlag(parsed2.flags, "version-id"), "version-id"),
+          "version-id"
+        ),
+        name: validateRequired(getFlag(parsed2.flags, "name", "n"), "name"),
+        trigger: triggerFlag !== void 0 ? validateTriggerUrl(triggerFlag, "trigger") : void 0,
+        active: getBoolFlag(parsed2.flags, "active"),
+        onError: onErrorFlag !== void 0 ? validateEnum(onErrorFlag, ON_ERROR_VALUES, "on-error") : "throw",
+        priority: priorityFlag !== void 0 ? validateInteger(priorityFlag, "priority", { min: 0 }) : 0
+      };
+    }
+    const validated = functionCreateSchema.safeParse(input);
+    if (!validated.success) {
+      throw new Error(validated.error.issues.map((i) => i.message).join("; "));
+    }
+    if (parsed2.global.dryRun) {
+      outputDryRun(
+        "function.create",
+        validated.data,
+        format
+      );
+      return;
+    }
+    const client = await getAuthenticatedClient();
+    const result = await createFunction(client, validated.data);
+    outputResult(result, format, parsed2.global.fields);
+    if (!result.success) process.exit(1);
+  } catch (err) {
+    outputResult(
+      {
+        success: false,
+        error: { message: err instanceof Error ? err.message : String(err) }
+      },
+      format
+    );
+    process.exit(1);
+  }
+}
+async function functionListCommand(parsed2) {
+  const format = detectOutputFormat(parsed2.global.output);
+  try {
+    const storeId = validateUuid(
+      validateRequired(getFlag(parsed2.flags, "store-id"), "store-id"),
+      "store-id"
+    );
+    const versionId = getFlag(parsed2.flags, "version-id");
+    if (versionId) validateUuid(versionId, "version-id");
+    const client = await getAuthenticatedClient();
+    const result = await listFunctions(client, storeId, versionId);
+    outputResult(result, format, parsed2.global.fields);
+    if (!result.success) process.exit(1);
+  } catch (err) {
+    outputResult(
+      {
+        success: false,
+        error: { message: err instanceof Error ? err.message : String(err) }
+      },
+      format
+    );
+    process.exit(1);
+  }
+}
+
 // src/commands/init-cmd.ts
 async function initCommand(parsed2) {
   const format = detectOutputFormat(parsed2.global.output);
@@ -2376,6 +2549,7 @@ var AGENT_COMMANDS = {
   version: versionCommand,
   component: componentCommand,
   "business-rule": businessRuleCommand,
+  function: functionCommand,
   schema: schemaCommand,
   init: initCommand,
   deploy: deployCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ollie-shop/cli",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Ollie Shop CLI - Development tools for custom checkouts",
   "type": "module",
   "main": "dist/index.js",

package/src/commands/function-cmd.ts

@@ -0,0 +1,146 @@
+import { createFunction, listFunctions } from "../core/function.js";
+import { functionCreateSchema } from "../core/schema.js";
+import {
+  detectOutputFormat,
+  outputDryRun,
+  outputResult,
+} from "../utils/output.js";
+import { type ParsedArgs, getBoolFlag, getFlag } from "../utils/parse-args.js";
+import { getAuthenticatedClient } from "../utils/supabase.js";
+import {
+  validateEnum,
+  validateInteger,
+  validateRequired,
+  validateTriggerUrl,
+  validateUuid,
+} from "../utils/validate.js";
+
+const ON_ERROR_VALUES = ["throw", "skip"] as const;
+
+export async function functionCommand(parsed: ParsedArgs): Promise<void> {
+  const sub = parsed.subcommand;
+  if (sub === "create") return functionCreateCommand(parsed);
+  if (sub === "list" || sub === "ls") return functionListCommand(parsed);
+
+  console.error(
+    `Unknown function subcommand: ${sub}. Use: function create | function list`,
+  );
+  process.exit(1);
+}
+
+async function functionCreateCommand(parsed: ParsedArgs): Promise<void> {
+  const format = detectOutputFormat(parsed.global.output);
+
+  try {
+    let input: {
+      versionId: string;
+      name: string;
+      trigger?: string;
+      active?: boolean;
+      onError?: "throw" | "skip";
+      priority?: number;
+    };
+
+    if (parsed.global.data) {
+      const raw = JSON.parse(parsed.global.data);
+      input = {
+        versionId: validateUuid(raw.versionId, "versionId"),
+        name: validateRequired(raw.name, "name"),
+        trigger:
+          raw.trigger !== undefined && raw.trigger !== null
+            ? validateTriggerUrl(String(raw.trigger), "trigger")
+            : undefined,
+        active: raw.active === true,
+        onError:
+          raw.onError !== undefined && raw.onError !== null
+            ? validateEnum(String(raw.onError), ON_ERROR_VALUES, "on-error")
+            : "throw",
+        priority:
+          raw.priority !== undefined && raw.priority !== null
+            ? validateInteger(raw.priority, "priority", { min: 0 })
+            : 0,
+      };
+    } else {
+      const triggerFlag = getFlag(parsed.flags, "trigger");
+      const onErrorFlag = getFlag(parsed.flags, "on-error");
+      const priorityFlag = getFlag(parsed.flags, "priority");
+      input = {
+        versionId: validateUuid(
+          validateRequired(getFlag(parsed.flags, "version-id"), "version-id"),
+          "version-id",
+        ),
+        name: validateRequired(getFlag(parsed.flags, "name", "n"), "name"),
+        trigger:
+          triggerFlag !== undefined
+            ? validateTriggerUrl(triggerFlag, "trigger")
+            : undefined,
+        active: getBoolFlag(parsed.flags, "active"),
+        onError:
+          onErrorFlag !== undefined
+            ? validateEnum(onErrorFlag, ON_ERROR_VALUES, "on-error")
+            : "throw",
+        priority:
+          priorityFlag !== undefined
+            ? validateInteger(priorityFlag, "priority", { min: 0 })
+            : 0,
+      };
+    }
+
+    const validated = functionCreateSchema.safeParse(input);
+    if (!validated.success) {
+      throw new Error(validated.error.issues.map((i) => i.message).join("; "));
+    }
+
+    if (parsed.global.dryRun) {
+      outputDryRun(
+        "function.create",
+        validated.data as Record<string, unknown>,
+        format,
+      );
+      return;
+    }
+
+    const client = await getAuthenticatedClient();
+    const result = await createFunction(client, validated.data);
+
+    outputResult(result, format, parsed.global.fields);
+    if (!result.success) process.exit(1);
+  } catch (err) {
+    outputResult(
+      {
+        success: false,
+        error: { message: err instanceof Error ? err.message : String(err) },
+      },
+      format,
+    );
+    process.exit(1);
+  }
+}
+
+async function functionListCommand(parsed: ParsedArgs): Promise<void> {
+  const format = detectOutputFormat(parsed.global.output);
+
+  try {
+    const storeId = validateUuid(
+      validateRequired(getFlag(parsed.flags, "store-id"), "store-id"),
+      "store-id",
+    );
+    const versionId = getFlag(parsed.flags, "version-id");
+    if (versionId) validateUuid(versionId, "version-id");
+
+    const client = await getAuthenticatedClient();
+    const result = await listFunctions(client, storeId, versionId);
+
+    outputResult(result, format, parsed.global.fields);
+    if (!result.success) process.exit(1);
+  } catch (err) {
+    outputResult(
+      {
+        success: false,
+        error: { message: err instanceof Error ? err.message : String(err) },
+      },
+      format,
+    );
+    process.exit(1);
+  }
+}

package/src/commands/help.tsx

@@ -61,6 +61,12 @@ export function HelpCommand() {
           </Box>
           <Text>Create or list components</Text>
         </Box>
+        <Box>
+          <Box width={24}>
+            <Text color="green">function create|list</Text>
+          </Box>
+          <Text>Create or list functions</Text>
+        </Box>
         <Box>
           <Box width={24}>
             <Text color="green">deploy</Text>
@@ -158,6 +164,9 @@ export function HelpCommand() {
           $ ollieshop version create --store-id UUID --name v1 --active
         </Text>
         <Text dimColor>$ ollieshop init --store-id UUID --version-id UUID</Text>
+        <Text dimColor>
+          $ ollieshop function create --version-id UUID --name myHook
+        </Text>
         <Text dimColor>
           $ ollieshop deploy --component-id UUID --name FreeShippingBar --wait
         </Text>

package/src/core/function.ts

@@ -0,0 +1,92 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import { functionCreateSchema } from "./schema.js";
+
+export interface CreateFunctionInput {
+  versionId: string;
+  name: string;
+  trigger?: string;
+  active?: boolean;
+  onError?: "throw" | "skip";
+  priority?: number;
+}
+
+export interface FunctionRecord {
+  id: string;
+  name: string;
+  active: boolean;
+  urn: string | null;
+  on_error: string;
+  priority: number;
+  trigger: { url: string; expression: string } | null;
+  invocation: string | null;
+  version_id: string;
+  created_at: string;
+  versions?: { id: string; name: string };
+}
+
+export async function createFunction(
+  client: SupabaseClient,
+  input: CreateFunctionInput,
+): Promise<
+  | { success: true; data: { id: string } }
+  | { success: false; error: { message: string } }
+> {
+  const parsed = functionCreateSchema.safeParse(input);
+  if (!parsed.success) {
+    return {
+      success: false,
+      error: {
+        message: parsed.error.issues
+          .map((i: { message: string }) => i.message)
+          .join("; "),
+      },
+    };
+  }
+
+  const { data, error } = await client
+    .from("functions")
+    .insert({
+      name: parsed.data.name,
+      active: parsed.data.active,
+      version_id: parsed.data.versionId,
+      trigger: parsed.data.trigger ?? null,
+      on_error: parsed.data.onError ?? "throw",
+      priority: parsed.data.priority ?? 0,
+    })
+    .select("id")
+    .single();
+
+  if (error) {
+    return { success: false, error: { message: error.message } };
+  }
+
+  return { success: true, data: { id: data.id } };
+}
+
+export async function listFunctions(
+  client: SupabaseClient,
+  storeId: string,
+  versionId?: string,
+): Promise<
+  | { success: true; data: FunctionRecord[] }
+  | { success: false; error: { message: string } }
+> {
+  let query = client
+    .from("functions")
+    .select(
+      "id, name, active, urn, on_error, priority, trigger, invocation, version_id, created_at, versions!inner(id, name)",
+    )
+    .eq("versions.store_id", storeId);
+
+  if (versionId) {
+    query = query.eq("versions.id", versionId);
+  }
+
+  const { data, error } = await query;
+
+  if (error) {
+    return { success: false, error: { message: error.message } };
+  }
+
+  return { success: true, data: (data ?? []) as unknown as FunctionRecord[] };
+}

package/src/core/schema.ts

@@ -67,8 +67,24 @@ export const functionCreateSchema = z.object({
   trigger: z
     .string()
     .min(1)
-    .describe("Function trigger (e.g. beforePayment, afterShipping)"),
-  active: z.boolean().default(true).describe("Whether function is active"),
+    .optional()
+    .describe(
+      "Function trigger URL — absolute http(s) URL or relative path starting with /",
+    ),
+  active: z
+    .boolean()
+    .default(false)
+    .describe("Whether function is active (default: false)"),
+  onError: z
+    .enum(["throw", "skip"])
+    .optional()
+    .describe("Error handling: throw (default) or skip"),
+  priority: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Execution order priority (default: 0)"),
 });
 
 export const functionListSchema = z.object({

package/src/index.tsx

@@ -3,6 +3,7 @@ import { App } from "./cli.js";
 import { businessRuleCommand } from "./commands/business-rule-cmd.js";
 import { componentCommand } from "./commands/component-cmd.js";
 import { deployCommand } from "./commands/deploy-cmd.js";
+import { functionCommand } from "./commands/function-cmd.js";
 import { initCommand } from "./commands/init-cmd.js";
 import { schemaCommand } from "./commands/schema-cmd.js";
 import { statusCommand } from "./commands/status-cmd.js";
@@ -21,6 +22,7 @@ const AGENT_COMMANDS: Record<
   version: versionCommand,
   component: componentCommand,
   "business-rule": businessRuleCommand,
+  function: functionCommand,
   schema: schemaCommand,
   init: initCommand,
   deploy: deployCommand,

package/src/utils/validate.ts

@@ -56,3 +56,47 @@ export function validateRequired(
   }
   return rejectControlChars(value.trim(), name);
 }
+
+export function validateInteger(
+  value: unknown,
+  name: string,
+  opts?: { min?: number },
+): number {
+  const n =
+    typeof value === "number"
+      ? value
+      : typeof value === "string" && value.trim() !== ""
+        ? Number(value)
+        : Number.NaN;
+  if (!Number.isFinite(n) || !Number.isInteger(n)) {
+    throw new Error(`Invalid ${name}: "${String(value)}". Must be an integer.`);
+  }
+  if (opts?.min !== undefined && n < opts.min) {
+    throw new Error(`Invalid ${name}: ${n}. Must be >= ${opts.min}.`);
+  }
+  return n;
+}
+
+export function validateTriggerUrl(value: string, name: string): string {
+  rejectControlChars(value, name);
+  const trimmed = value.trim();
+  if (trimmed === "") {
+    throw new Error(
+      `Invalid ${name}: must be a non-empty absolute http(s) URL or a relative path starting with "/".`,
+    );
+  }
+  if (trimmed.startsWith("/")) {
+    return trimmed;
+  }
+  try {
+    const parsed = new URL(trimmed);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new Error("unsupported protocol");
+    }
+    return trimmed;
+  } catch {
+    throw new Error(
+      `Invalid ${name}: "${value}". Must be an absolute http(s) URL or a relative path starting with "/".`,
+    );
+  }
+}