@newhomestar/sdk 0.8.3 → 0.8.5

package/dist/credentials.d.ts

@@ -12,6 +12,18 @@ export interface ResolvedCredentials {
     authMode: AuthMode;
     /** mTLS agent (if auth_mode = 'mtls') — use for ALL API requests to that provider */
     httpsAgent?: https.Agent;
+    /**
+     * Per-connection configuration values filled in by the user during setup.
+     * Populated from `app_integration_configs.config` via the auth server's
+     * credential resolution response. Empty `{}` if no config exists.
+     */
+    config?: Record<string, unknown>;
+    /**
+     * Whether the user has completed all required configuration fields.
+     * `true` when every required configField has a value; `false` otherwise.
+     * `undefined` if the integration has no configFields.
+     */
+    configComplete?: boolean;
 }
 export declare class IntegrationNotFoundError extends Error {
     constructor(slug: string);

package/dist/credentials.js

@@ -262,6 +262,8 @@ export async function resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken,
                 expiresAt,
                 integrationId: `http:${slug}`,
                 authMode: "standard",
+                config: creds.config ?? {},
+                configComplete: creds.configComplete ?? undefined,
             };
         }
         // Standard auth but no access token — user hasn't authorized yet
@@ -303,6 +305,8 @@ export async function resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken,
         integrationId: `http:${slug}`,
         authMode: creds.authMode,
         httpsAgent,
+        config: creds.config ?? {},
+        configComplete: creds.configComplete ?? undefined,
     };
 }
 /**
@@ -459,6 +463,8 @@ export async function resolveCredentialsViaServiceToken(authBaseUrl, slug, servi
                 expiresAt,
                 integrationId: `service:${slug}`,
                 authMode: "standard",
+                config: creds.config ?? {},
+                configComplete: creds.configComplete ?? undefined,
             };
         }
         throw new Error(`[nova-sdk] Standard auth integration "${slug}" requires user context (JWT). ` +
@@ -498,6 +504,8 @@ export async function resolveCredentialsViaServiceToken(authBaseUrl, slug, servi
         integrationId: `service:${slug}`,
         authMode: creds.authMode,
         httpsAgent,
+        config: creds.config ?? {},
+        configComplete: creds.configComplete ?? undefined,
     };
 }
 /**

package/dist/index.d.ts

@@ -168,6 +168,25 @@ export interface ActionCtx {
     authToken?: string;
     /** Validated JWT payload from JWKS verification (HTTP mode only) */
     auth?: JWTPayload;
+    /**
+     * Per-connection configuration values filled in by the user during setup.
+     * Available in every action handler. Values come from the auth server's
+     * credential resolution response (`app_integration_configs` table).
+     *
+     * Empty object `{}` if the integration has no `configFields` or the
+     * connection has no saved configuration.
+     *
+     * @example
+     * ```ts
+     * handler: async (input, ctx) => {
+     *   const domain = ctx.config.companyDomain as string;
+     *   const baseUrl = `https://api.bamboohr.com/api/gateway.php/${domain}`;
+     *   const res = await ctx.fetch(`${baseUrl}/v1/employees/directory`);
+     *   // ...
+     * }
+     * ```
+     */
+    config: Record<string, unknown>;
     /**
      * Resolve OAuth credentials for the current integration (or a named slug).
      * Handles all auth modes (mtls, client_credentials, standard).
@@ -362,8 +381,8 @@ export type { QueueEventPayload, LogEventPayload, OutboxRelayOptions, ServiceEmi
 export type { ZodTypeAny as SchemaAny, ZodTypeAny };
 export { parseNovaSpec } from "./parseSpec.js";
 export type { NovaSpec } from "./parseSpec.js";
-export { defineIntegration, validateIntegration, integrationSchema, integrationEvent, integrationFunction, schema, event, IntegrationDefSchema, } from "./integration.js";
-export type { IntegrationDef, IntegrationSchemaDef, IntegrationEventDef, IntegrationFunctionDef, ValidationResult, SchemaType, ParamMeta, ParamIn, ParamUiType, SyncMappingDef, SyncMappingFieldDef, WebhookConfig, WebhookTypeDef, WebhookFieldDef, } from "./integration.js";
+export { defineIntegration, validateIntegration, integrationSchema, integrationEvent, integrationFunction, schema, event, IntegrationDefSchema, ConfigPhase, ConfigPhaseSchema, ConfigWidget, ConfigWidgetSchema, } from "./integration.js";
+export type { IntegrationDef, IntegrationSchemaDef, IntegrationEventDef, IntegrationFunctionDef, ValidationResult, SchemaType, ParamMeta, ParamIn, ParamUiType, SyncMappingDef, SyncMappingFieldDef, WebhookConfig, WebhookTypeDef, WebhookFieldDef, ConfigFieldDef, OptionsFetcher, OptionsContext, } from "./integration.js";
 export { parseIntegrationSpec, IntegrationSpecSchema } from "./integrationSpec.js";
 export type { IntegrationSpec } from "./integrationSpec.js";
 export type WebhookCapability = {

package/dist/index.js

@@ -65,10 +65,12 @@ export function createORPCRouter(def) {
             const credCtx = buildCredentialCtx(def.name);
             const ctx = {
                 jobId: context?.jobId || `orpc-${Date.now()}`,
+                config: credCtx._config,
                 progress: (percent, meta) => {
                     console.log(`[${actionName}] Progress: ${percent}%`, meta);
                 },
-                ...credCtx,
+                resolveCredentials: credCtx.resolveCredentials,
+                fetch: credCtx.fetch,
             };
             return await actionDef.handler(input, ctx);
         })
@@ -302,8 +304,10 @@ export async function runWorker(def) {
                 const credCtx = buildCredentialCtx(def.name);
                 const ctx = {
                     jobId,
+                    config: credCtx._config,
                     progress: (percent, meta) => runtime.from("job_events").insert({ job_id: jobId, percent, meta }),
-                    ...credCtx,
+                    resolveCredentials: credCtx.resolveCredentials,
+                    fetch: credCtx.fetch,
                 };
                 const result = await act.handler(parsedInput, ctx);
                 act.output.parse(result);
@@ -461,12 +465,14 @@ async function runWorkerSSE(def) {
                                     const credCtx = buildCredentialCtx(def.name);
                                     const ctx = {
                                         jobId: `sse-${msg_id}`,
+                                        config: credCtx._config,
                                         read_ct: read_ct ?? 0,
                                         progress: (percent, meta) => {
                                             console.log(`[nova] progress ${percent}%`, meta ?? '');
                                         },
                                         heartbeat: (extendBy = 30) => _heartbeatSSE(def.queue, msg_id, extendBy),
-                                        ...credCtx,
+                                        resolveCredentials: credCtx.resolveCredentials,
+                                        fetch: credCtx.fetch,
                                     };
                                     const result = await actionDef.handler(parsedInput, ctx);
                                     actionDef.output.parse(result);
@@ -550,12 +556,20 @@ export async function generateOpenAPISpec(def) {
  * within the same handler invocation.
  * On 401, ctx.fetch() retries once with forceRefresh=true (X-Nova-Token-Invalid).
  *
+ * Returns `_config` — a shared mutable object that gets populated with
+ * config values from the auth server response when resolveCredentials() is
+ * called. Assign `ctx.config = credCtx._config` so that config values
+ * become available to the handler after credential resolution.
+ *
  * @param defaultSlug - Integration slug (e.g., "jira", "bamboohr")
  * @param authToken   - JWT Bearer token from the inbound request (forwarded to auth server)
  */
 function buildCredentialCtx(defaultSlug, authToken) {
     // Per-request credentials cache — avoids duplicate round-trips within a single handler
     let _lastCreds = null;
+    // Shared config ref — populated when resolveCredentials() returns config
+    // from the auth server's credential resolution response.
+    const _config = {};
     const strategy = detectCredentialStrategy();
     const ctxResolveCredentials = async (slug, userId) => {
         const targetSlug = slug ?? defaultSlug;
@@ -569,6 +583,13 @@ function buildCredentialCtx(defaultSlug, authToken) {
             }
             const creds = await _resolveCredentialsViaHttp(authBaseUrl, targetSlug, authToken, userId);
             _lastCreds = creds;
+            // ── Populate shared config ref from credential resolution response ──
+            // The auth server includes config + configComplete in its response.
+            // We merge into _config (mutates in place) so ctx.config is updated.
+            if (creds.config && Object.keys(creds.config).length > 0) {
+                Object.assign(_config, creds.config);
+                console.log(`[nova-sdk] 📋 ctx.config populated with ${Object.keys(creds.config).length} field(s) from credential resolution`);
+            }
             return creds;
         }
         // strategy === "none"
@@ -612,7 +633,7 @@ function buildCredentialCtx(defaultSlug, authToken) {
         }
         return response;
     };
-    return { resolveCredentials: ctxResolveCredentials, fetch: ctxFetch };
+    return { resolveCredentials: ctxResolveCredentials, fetch: ctxFetch, _config };
 }
 /*──────────────── HTTP Server Harness (Enhanced) ───────────────*/
 import express from "express";
@@ -788,13 +809,15 @@ export function runHttpServer(def, opts = {}) {
                 const credCtx = buildCredentialCtx(def.name, authToken);
                 const ctx = {
                     jobId,
+                    config: credCtx._config, // populated from credential resolution when resolveCredentials() is called
                     progress: (percent, meta) => {
                         console.log(`[nova][${actionName}] Progress: ${percent}%`, meta ?? '');
                     },
                     headers: req.headers,
                     authToken,
                     auth: jwtPayload,
-                    ...credCtx,
+                    resolveCredentials: credCtx.resolveCredentials,
+                    fetch: credCtx.fetch,
                 };
                 const authLabel = jwtPayload?.sub
                     ? ` [auth ✓ sub=${jwtPayload.sub}]`
@@ -847,6 +870,59 @@ export function runHttpServer(def, opts = {}) {
             app.get('/health', handler);
         }
     }
+    // ── Auto-register optionsFetcher routes for configFields ──
+    // When an integration has configFields with optionsFetcher handlers,
+    // the SDK automatically registers POST /config-options/:fieldKey routes.
+    // This is transparent to the integration author — they just define the handler.
+    const integrationDef = def;
+    if (integrationDef.configFields) {
+        for (const field of integrationDef.configFields) {
+            if (field.optionsFetcher) {
+                const optionsRoute = `/config-options/${field.key}`;
+                app.post(optionsRoute, async (req, res) => {
+                    try {
+                        const authHeader = req.headers['authorization'];
+                        const authToken = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : undefined;
+                        if (!authToken) {
+                            return res.status(401).json({
+                                error: 'Authorization required',
+                                message: 'optionsFetcher requires a valid Bearer token',
+                            });
+                        }
+                        // Resolve credentials (same flow as action handlers)
+                        const credCtx = buildCredentialCtx(def.name, authToken);
+                        const credentials = await credCtx.resolveCredentials();
+                        // Build OptionsContext for the handler
+                        const optionsCtx = {
+                            fetch: credCtx.fetch,
+                            config: req.body?.config ?? {},
+                            credentials,
+                            tenantId: req.auth?.sub ?? 'unknown',
+                        };
+                        // Run the optionsFetcher handler
+                        console.log(`[nova] 🔧 Running optionsFetcher for config field "${field.key}"`);
+                        const rawOptions = await field.optionsFetcher.handler(optionsCtx);
+                        // Validate each option against the declared schema
+                        const validated = rawOptions.map((item, i) => {
+                            const result = field.optionsFetcher.schema.safeParse(item);
+                            if (!result.success) {
+                                throw new Error(`optionsFetcher "${field.key}" returned invalid item at index ${i}: ` +
+                                    JSON.stringify(result.error.issues ?? result.error.message));
+                            }
+                            return result.data;
+                        });
+                        console.log(`[nova] ✅ optionsFetcher "${field.key}" returned ${validated.length} options`);
+                        res.json({ options: validated });
+                    }
+                    catch (err) {
+                        console.error(`[nova] ❌ optionsFetcher "${field.key}" failed:`, err.message);
+                        res.status(500).json({ error: err.message });
+                    }
+                });
+                console.log(`[nova] 🔧 POST ${optionsRoute} -> optionsFetcher("${field.key}") 🔐`);
+            }
+        }
+    }
     // ── Log credential resolution strategy ──
     const credStrategy = detectCredentialStrategy();
     const strategyLabels = {
@@ -905,7 +981,9 @@ export { defineIntegration, validateIntegration,
 // Verbose helpers (backward-compatible)
 integrationSchema, integrationEvent, integrationFunction, 
 // Lean helpers (recommended)
-schema, event, IntegrationDefSchema, } from "./integration.js";
+schema, event, IntegrationDefSchema, 
+// Config field enums + Zod schemas (Phase 1: SDK Foundation)
+ConfigPhase, ConfigPhaseSchema, ConfigWidget, ConfigWidgetSchema, } from "./integration.js";
 // Integration spec parsing utility
 export { parseIntegrationSpec, IntegrationSpecSchema } from "./integrationSpec.js";
 /*──────────────── Credential Resolution (re-exports) ───────────────*/

package/dist/integration.d.ts

@@ -1,4 +1,5 @@
 import { z, type ZodTypeAny } from "zod";
+import type { ResolvedCredentials } from "./credentials.js";
 /** Where the parameter is sent in the HTTP request */
 export type ParamIn = 'path' | 'query' | 'body' | 'header';
 /** UI input widget type hint for the admin dashboard form builder */
@@ -54,6 +55,217 @@ export interface ParamMeta {
     /** Group name for visual grouping in the form (e.g., "Identity", "Options") */
     group?: string;
 }
+/** Zod schema for config field lifecycle phase validation */
+export declare const ConfigPhaseSchema: z.ZodEnum<{
+    before_auth: "before_auth";
+    after_auth: "after_auth";
+}>;
+/** Config field lifecycle phase type — `"before_auth" | "after_auth"` */
+export type ConfigPhase = z.infer<typeof ConfigPhaseSchema>;
+/**
+ * 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 declare const ConfigPhase: {
+    /** Collected before OAuth redirect (e.g., company domain needed to build auth URL) */
+    readonly BeforeAuth: "before_auth";
+    /** Collected after OAuth completes (e.g., preferences that need API access) */
+    readonly AfterAuth: "after_auth";
+};
+/** Zod schema for config field widget type validation */
+export declare const ConfigWidgetSchema: z.ZodEnum<{
+    number: "number";
+    boolean: "boolean";
+    date: "date";
+    text: "text";
+    textarea: "textarea";
+    select: "select";
+    password: "password";
+}>;
+/** Config field widget type — UI input hint */
+export type ConfigWidget = z.infer<typeof ConfigWidgetSchema>;
+/**
+ * Named constants for config field widget types.
+ *
+ * @example
+ * ```ts
+ * import { ConfigWidget } from "@newhomestar/sdk";
+ *
+ * { widget: ConfigWidget.Select }  // ✅
+ * { widget: "select" }             // ✅ also works
+ * ```
+ */
+export declare const ConfigWidget: {
+    readonly Text: "text";
+    readonly Select: "select";
+    readonly Boolean: "boolean";
+    readonly Number: "number";
+    readonly Textarea: "textarea";
+    readonly Password: "password";
+    readonly Date: "date";
+};
+/**
+ * Context available inside `optionsFetcher.handler`.
+ * Same authenticated environment as action handlers — token-injected fetch,
+ * previously-saved config values, and full resolved credentials.
+ *
+ * @example
+ * ```ts
+ * optionsFetcher: {
+ *   schema: z.object({ label: z.string(), value: z.string() }),
+ *   handler: async (ctx) => {
+ *     // ctx.fetch has the OAuth token injected automatically
+ *     const res = await ctx.fetch("https://api.atlassian.com/oauth/token/accessible-resources");
+ *     const sites = await res.json();
+ *     return sites.map(s => ({ label: s.name, value: s.id }));
+ *   },
+ * }
+ * ```
+ */
+export interface OptionsContext {
+    /** Token-injected fetch — same as ctx.fetch in action handlers */
+    fetch: (url: string, options?: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: string;
+    }, credentials?: ResolvedCredentials) => Promise<Response>;
+    /** Previously-saved config values for this connection (so field B can depend on field A) */
+    config: Record<string, unknown>;
+    /** Full resolved credentials (accessToken, refreshToken, etc.) */
+    credentials: ResolvedCredentials;
+    /** Tenant ID for calling internal Nova platform services */
+    tenantId: string;
+}
+/**
+ * A handler function that fetches select options dynamically.
+ * Runs inside the integration container (not in the UI or auth server).
+ *
+ * Can make multiple API calls, call internal services, transform data, etc.
+ * Output is validated against the provided Zod schema at runtime.
+ *
+ * @example
+ * ```ts
+ * optionsFetcher: {
+ *   schema: z.object({ label: z.string(), value: z.string() }),
+ *   handler: async (ctx) => {
+ *     const res = await ctx.fetch("https://api.atlassian.com/oauth/token/accessible-resources");
+ *     const sites = await res.json();
+ *     return sites.map(s => ({ label: s.name, value: s.id }));
+ *   },
+ * }
+ * ```
+ */
+export interface OptionsFetcher<TItem extends {
+    label: string;
+    value: string;
+} = {
+    label: string;
+    value: string;
+}> {
+    /** Zod schema for each returned option item — enforces shape at runtime */
+    schema: z.ZodType<TItem>;
+    /**
+     * Handler function that fetches and returns the options array.
+     * Has access to authenticated fetch, saved config, and credentials.
+     */
+    handler: (ctx: OptionsContext) => Promise<TItem[]>;
+}
+/**
+ * A single configurable field declared by an integration.
+ * Reuses the same ParamMeta rendering system used for action parameters.
+ *
+ * Values are stored per connection and available at runtime via `ctx.config`.
+ *
+ * @example
+ * ```ts
+ * import { ConfigPhase, ConfigWidget } from "@newhomestar/sdk";
+ *
+ * configFields: [
+ *   {
+ *     key: "companyDomain",
+ *     label: "Company Domain",
+ *     schema: z.string().min(1).regex(/^[a-z0-9-]+$/i),
+ *     when: ConfigPhase.BeforeAuth,
+ *     required: true,
+ *     helpText: "Your BambooHR subdomain (the 'acme' part of acme.bamboohr.com)",
+ *     placeholder: "acme",
+ *     widget: ConfigWidget.Text,
+ *   },
+ *   {
+ *     key: "cloudId",
+ *     label: "Jira Site",
+ *     schema: z.string(),
+ *     when: ConfigPhase.AfterAuth,
+ *     widget: ConfigWidget.Select,
+ *     optionsFetcher: {
+ *       schema: z.object({ label: z.string(), value: z.string() }),
+ *       handler: async (ctx) => {
+ *         const res = await ctx.fetch("https://api.atlassian.com/...");
+ *         return (await res.json()).map(s => ({ label: s.name, value: s.id }));
+ *       },
+ *     },
+ *   },
+ * ]
+ * ```
+ */
+export interface ConfigFieldDef<T extends z.ZodType = z.ZodType> {
+    /** Unique key for this field (used in ctx.config[key]) — must be a valid JS identifier */
+    key: string;
+    /** Human-readable label for the UI */
+    label: string;
+    /** Zod schema for validation (converted to JSON Schema at build time) */
+    schema: T;
+    /** When to collect this field in the connect flow */
+    when: ConfigPhase;
+    /** Whether this field is required (default: true) */
+    required?: boolean;
+    /** Default value if not provided by user */
+    defaultValue?: z.infer<T>;
+    /** Help text shown below the field in the UI */
+    helpText?: string;
+    /** Placeholder text for input fields */
+    placeholder?: string;
+    /** UI widget type hint (reuses ParamMeta widgets) */
+    widget?: ConfigWidget;
+    /** Static options for select widgets */
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    /**
+     * Dynamic options handler — fetches options from APIs at runtime.
+     * Runs inside the integration container with full auth context.
+     * Only valid for `when: ConfigPhase.AfterAuth` (needs credentials).
+     *
+     * The SDK automatically registers a `POST /config-options/:key` route
+     * for each field with an optionsFetcher — transparent to the integration author.
+     */
+    optionsFetcher?: OptionsFetcher;
+    /** Group label for organizing related fields in the UI */
+    group?: string;
+    /**
+     * Conditional visibility: only show this field when another field
+     * matches a specific value. Enables progressive disclosure.
+     *
+     * @example
+     * ```ts
+     * { visibleWhen: { field: "syncTimeOff", equals: true } }
+     * ```
+     */
+    visibleWhen?: {
+        field: string;
+        equals: unknown;
+    };
+}
 export type SchemaType = 'request' | 'response' | 'entity' | 'webhook_payload' | 'configuration';
 export interface IntegrationSchemaDef<T extends ZodTypeAny = ZodTypeAny> {
     /** Human-readable name for this schema */
@@ -426,6 +638,44 @@ export interface IntegrationDef {
      * The integration's handler action does the actual processing.
      */
     webhooks?: WebhookConfig;
+    /**
+     * Configuration fields that users fill in during the connect flow.
+     * Values are stored per connection and available at runtime via `ctx.config`.
+     *
+     * Fields are split into two lifecycle phases:
+     *   - `ConfigPhase.BeforeAuth` — collected before OAuth (e.g., company domain for auth URL)
+     *   - `ConfigPhase.AfterAuth` — collected after OAuth (e.g., sync preferences, dynamic selects)
+     *
+     * @example
+     * ```ts
+     * import { ConfigPhase } from "@newhomestar/sdk";
+     *
+     * configFields: [
+     *   {
+     *     key: "companyDomain",
+     *     label: "Company Domain",
+     *     schema: z.string().min(1),
+     *     when: ConfigPhase.BeforeAuth,
+     *     helpText: "Your subdomain (e.g., 'acme' from acme.bamboohr.com)",
+     *     widget: "text",
+     *   },
+     *   {
+     *     key: "syncInterval",
+     *     label: "Sync Interval",
+     *     schema: z.enum(["1h", "6h", "24h"]),
+     *     when: ConfigPhase.AfterAuth,
+     *     defaultValue: "6h",
+     *     widget: "select",
+     *     options: [
+     *       { label: "Every hour", value: "1h" },
+     *       { label: "Every 6 hours", value: "6h" },
+     *       { label: "Every 24 hours", value: "24h" },
+     *     ],
+     *   },
+     * ]
+     * ```
+     */
+    configFields?: ConfigFieldDef[];
 }
 export declare const IntegrationDefSchema: z.ZodObject<{
     slug: z.ZodString;
@@ -570,6 +820,38 @@ export declare const IntegrationDefSchema: z.ZodObject<{
             }, z.core.$strip>>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    configFields: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        schema: z.ZodAny;
+        when: z.ZodEnum<{
+            before_auth: "before_auth";
+            after_auth: "after_auth";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        defaultValue: z.ZodOptional<z.ZodUnknown>;
+        helpText: z.ZodOptional<z.ZodString>;
+        placeholder: z.ZodOptional<z.ZodString>;
+        widget: z.ZodOptional<z.ZodEnum<{
+            number: "number";
+            boolean: "boolean";
+            date: "date";
+            text: "text";
+            textarea: "textarea";
+            select: "select";
+            password: "password";
+        }>>;
+        options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strip>>>;
+        optionsFetcher: z.ZodOptional<z.ZodAny>;
+        group: z.ZodOptional<z.ZodString>;
+        visibleWhen: z.ZodOptional<z.ZodObject<{
+            field: z.ZodString;
+            equals: z.ZodUnknown;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 /**
  * Result of validating an integration definition before build/push.