@newhomestar/sdk 0.8.3 → 0.8.5

package/dist/integration.js

@@ -12,6 +12,55 @@ import { z } from "zod";
 /** Symbol used to tag lean schema/event wrappers (non-enumerable) */
 const NOVA_SCHEMA = Symbol.for('nova.schema');
 const NOVA_EVENT = Symbol.for('nova.event');
+/*─────────────────────────*  Config Field Definitions  *──────────────────────────*/
+// ─── Lifecycle Phase ───────────────────────────────────────────────────────
+// Zod schema for runtime validation — no magic strings.
+/** Zod schema for config field lifecycle phase validation */
+export const ConfigPhaseSchema = z.enum(["before_auth", "after_auth"]);
+/**
+ * Named constants for config field lifecycle phases.
+ * Use these instead of raw strings for IDE autocomplete and compile-time safety.
+ *
+ * @example
+ * ```ts
+ * import { ConfigPhase } from "@newhomestar/sdk";
+ *
+ * { when: ConfigPhase.BeforeAuth }  // ✅ autocomplete + type-safe
+ * { when: "before_auth" }           // ✅ also works (same type)
+ * { when: "beforeAuth" }            // ❌ TypeScript error
+ * ```
+ */
+export const ConfigPhase = {
+    /** Collected before OAuth redirect (e.g., company domain needed to build auth URL) */
+    BeforeAuth: "before_auth",
+    /** Collected after OAuth completes (e.g., preferences that need API access) */
+    AfterAuth: "after_auth",
+};
+// ─── Widget Type ───────────────────────────────────────────────────────────
+/** Zod schema for config field widget type validation */
+export const ConfigWidgetSchema = z.enum([
+    "text", "select", "boolean", "number", "textarea", "password", "date",
+]);
+/**
+ * Named constants for config field widget types.
+ *
+ * @example
+ * ```ts
+ * import { ConfigWidget } from "@newhomestar/sdk";
+ *
+ * { widget: ConfigWidget.Select }  // ✅
+ * { widget: "select" }             // ✅ also works
+ * ```
+ */
+export const ConfigWidget = {
+    Text: "text",
+    Select: "select",
+    Boolean: "boolean",
+    Number: "number",
+    Textarea: "textarea",
+    Password: "password",
+    Date: "date",
+};
 /**
  * **Verbose** helper — define a schema with all metadata explicitly.
  *
@@ -228,7 +277,153 @@ export const IntegrationDefSchema = z.object({
             })).optional(),
         })),
     }).optional(),
+    configFields: z.array(z.object({
+        key: z.string().regex(/^[a-zA-Z_$][a-zA-Z0-9_$]*$/, 'Config field key must be a valid JS identifier'),
+        label: z.string().min(1),
+        schema: z.any(), // Zod schema instance — validated structurally by normalizeConfigFields
+        when: ConfigPhaseSchema,
+        required: z.boolean().optional(),
+        defaultValue: z.unknown().optional(),
+        helpText: z.string().optional(),
+        placeholder: z.string().optional(),
+        widget: ConfigWidgetSchema.optional(),
+        options: z.array(z.object({
+            label: z.string(),
+            value: z.string(),
+        })).optional(),
+        optionsFetcher: z.any().optional(), // { schema, handler } — validated structurally by normalizeConfigFields
+        group: z.string().optional(),
+        visibleWhen: z.object({
+            field: z.string(),
+            equals: z.unknown(),
+        }).optional(),
+    })).optional(),
 });
+/*─────────────────────────*  Config Field Normalization  *──────────────────────────*/
+/**
+ * Infer a widget type from a Zod schema when the developer doesn't explicitly set one.
+ * Falls back to "text" if the schema type can't be determined.
+ */
+function inferWidget(zodSchema) {
+    // Walk through wrappers (ZodOptional, ZodDefault, ZodNullable)
+    let inner = zodSchema;
+    while (inner?._def) {
+        const typeName = inner._def.typeName;
+        if (typeName === 'ZodOptional' || typeName === 'ZodDefault' || typeName === 'ZodNullable') {
+            inner = inner._def.innerType;
+            continue;
+        }
+        break;
+    }
+    const typeName = inner?._def?.typeName ?? '';
+    switch (typeName) {
+        case 'ZodString':
+            return 'text';
+        case 'ZodNumber':
+        case 'ZodBigInt':
+            return 'number';
+        case 'ZodBoolean':
+            return 'boolean';
+        case 'ZodEnum':
+        case 'ZodNativeEnum':
+            return 'select';
+        case 'ZodDate':
+            return 'date';
+        default:
+            return 'text';
+    }
+}
+/**
+ * Normalize and validate `configFields` array.
+ * Runs as Phase 0 of defineIntegration(), before schema/event normalization.
+ *
+ * Validates:
+ * - Keys are valid JS identifiers (no duplicates)
+ * - `when` is a valid ConfigPhase
+ * - `widget` is a valid ConfigWidget (if provided)
+ * - `optionsFetcher` requires `when: AfterAuth` (needs credentials)
+ * - `optionsFetcher.handler` must be a function
+ * - `visibleWhen.field` references another config field key
+ * - Infers widget from Zod schema when not explicitly set
+ * - Defaults `required` to `true`
+ *
+ * Stores validated config fields (with `optionsFetcher` handlers) as a
+ * non-enumerable `__configFields` property for runtime route registration.
+ *
+ * @throws {Error} on validation failures (descriptive messages with field index/key)
+ */
+function normalizeConfigFields(fields) {
+    if (!fields || fields.length === 0)
+        return;
+    const allKeys = fields.map(f => f.key);
+    const seen = new Set();
+    for (let i = 0; i < fields.length; i++) {
+        const field = fields[i];
+        const ctx = `configFields[${i}] ("${field.key}")`;
+        // ── Validate: key must be a valid JS identifier ──
+        if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(field.key)) {
+            throw new Error(`${ctx}: invalid key "${field.key}" — must be a valid JS identifier ` +
+                `(letters, digits, underscore, dollar sign; cannot start with a digit)`);
+        }
+        // ── Validate: no duplicate keys ──
+        if (seen.has(field.key)) {
+            throw new Error(`configFields: duplicate key "${field.key}" — each config field must have a unique key`);
+        }
+        seen.add(field.key);
+        // ── Validate: phase is a valid enum value (Zod runtime check) ──
+        const phaseResult = ConfigPhaseSchema.safeParse(field.when);
+        if (!phaseResult.success) {
+            throw new Error(`${ctx}: invalid "when" phase "${field.when}" — ` +
+                `must be "${ConfigPhase.BeforeAuth}" or "${ConfigPhase.AfterAuth}". ` +
+                `Use ConfigPhase.BeforeAuth or ConfigPhase.AfterAuth for type safety.`);
+        }
+        // ── Validate: widget is a valid enum value if provided ──
+        if (field.widget) {
+            const widgetResult = ConfigWidgetSchema.safeParse(field.widget);
+            if (!widgetResult.success) {
+                throw new Error(`${ctx}: invalid widget "${field.widget}" — ` +
+                    `must be one of: ${ConfigWidgetSchema.options.join(', ')}. ` +
+                    `Use ConfigWidget.* constants for type safety.`);
+            }
+        }
+        // ── Validate: optionsFetcher constraints ──
+        if (field.optionsFetcher) {
+            // optionsFetcher requires after_auth (needs credentials for API calls)
+            if (field.when === ConfigPhase.BeforeAuth) {
+                throw new Error(`${ctx}: has optionsFetcher but when: "${ConfigPhase.BeforeAuth}" — ` +
+                    `dynamic options require credentials from OAuth, so they can only be used with ` +
+                    `when: ConfigPhase.AfterAuth ("${ConfigPhase.AfterAuth}").`);
+            }
+            // handler must be a function
+            if (typeof field.optionsFetcher.handler !== 'function') {
+                throw new Error(`${ctx}: optionsFetcher.handler must be a function, got ${typeof field.optionsFetcher.handler}`);
+            }
+            // schema must be present
+            if (!field.optionsFetcher.schema) {
+                throw new Error(`${ctx}: optionsFetcher.schema is required — provide a Zod schema for the option items ` +
+                    `(e.g., z.object({ label: z.string(), value: z.string() }))`);
+            }
+        }
+        // ── Validate: visibleWhen.field references another config field key ──
+        if (field.visibleWhen) {
+            if (!allKeys.includes(field.visibleWhen.field)) {
+                throw new Error(`${ctx}: visibleWhen.field references unknown config field "${field.visibleWhen.field}" — ` +
+                    `available keys: ${allKeys.join(', ')}`);
+            }
+            // Cannot reference itself
+            if (field.visibleWhen.field === field.key) {
+                throw new Error(`${ctx}: visibleWhen.field cannot reference itself`);
+            }
+        }
+        // ── Apply defaults: required → true, widget → inferred ──
+        if (field.required === undefined) {
+            field.required = true;
+        }
+        if (!field.widget) {
+            field.widget = inferWidget(field.schema);
+        }
+    }
+}
 /**
  * Validate an integration definition before build or push.
  *
@@ -350,6 +545,16 @@ function camelToSnake(str) {
     return str.replace(/([A-Z])/g, '_$1').toLowerCase().replace(/^_/, '');
 }
 export function defineIntegration(def) {
+    // ── Phase 0: Normalize and validate config fields ──
+    // Must run before Zod validation (Phase 4) because it applies defaults
+    // (required=true, widget inference) that make the fields pass Zod checks.
+    // Also validates semantic constraints that Zod can't express (unique keys,
+    // optionsFetcher requires AfterAuth, visibleWhen references, etc.)
+    if (def.configFields && def.configFields.length > 0) {
+        normalizeConfigFields(def.configFields);
+        console.log(`[nova] ✅ Validated ${def.configFields.length} config fields: ` +
+            `${def.configFields.map(f => f.key).join(', ')}`);
+    }
     // ── Phase 1: Normalize lean schemas ──
     // Fill slug/name from the key when using schema() helper
     for (const [key, schemaDef] of Object.entries(def.schemas)) {

package/package.json

@@ -1,58 +1,58 @@
-{
-  "name": "@newhomestar/sdk",
-  "version": "0.8.3",
-  "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
-  "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
-  "bugs": {
-    "url": "https://github.com/newhomestar/nova-node-sdk/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/newhomestar/nova-node-sdk.git"
-  },
-  "license": "ISC",
-  "author": "Christian Gomez",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./next": {
-      "import": "./dist/next.js",
-      "types": "./dist/next.d.ts"
-    },
-    "./events": {
-      "import": "./dist/events.js",
-      "types": "./dist/events.d.ts"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc"
-  },
-  "dependencies": {
-    "@openfga/sdk": "^0.9.0",
-    "@orpc/openapi": "1.7.4",
-    "@orpc/server": "1.7.4",
-    "@supabase/supabase-js": "^2.39.0",
-    "body-parser": "^1.20.2",
-    "dotenv": "^16.4.3",
-    "express": "^4.18.2",
-    "express-oauth2-jwt-bearer": "^1.7.4",
-    "undici": "^7.24.4",
-    "yaml": "^2.7.1"
-  },
-  "peerDependencies": {
-    "zod": ">=4.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.11.17",
-    "typescript": "^5.4.4",
-    "zod": "^4.3.0"
-  }
-}
+{
+  "name": "@newhomestar/sdk",
+  "version": "0.8.5",
+  "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
+  "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/newhomestar/nova-node-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/newhomestar/nova-node-sdk.git"
+  },
+  "license": "ISC",
+  "author": "Christian Gomez",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./next": {
+      "import": "./dist/next.js",
+      "types": "./dist/next.d.ts"
+    },
+    "./events": {
+      "import": "./dist/events.js",
+      "types": "./dist/events.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@openfga/sdk": "^0.9.0",
+    "@orpc/openapi": "1.7.4",
+    "@orpc/server": "1.7.4",
+    "@supabase/supabase-js": "^2.39.0",
+    "body-parser": "^1.20.2",
+    "dotenv": "^16.4.3",
+    "express": "^4.18.2",
+    "express-oauth2-jwt-bearer": "^1.7.4",
+    "undici": "^7.24.4",
+    "yaml": "^2.7.1"
+  },
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.17",
+    "typescript": "^5.4.4",
+    "zod": "^4.3.0"
+  }
+}