@newhomestar/sdk 0.7.1 → 0.7.4

package/dist/index.d.ts

@@ -25,6 +25,40 @@ export interface ActionDef<I extends ZodTypeAny, O extends ZodTypeAny> {
      *   - UI type inferred from Zod type (string→text, number→number, boolean→boolean, enum→select)
      */
     params?: Record<string, import("./integration.js").ParamMeta>;
+    /**
+     * Expandable relations for this action — enables ?expand=field1,field2 query param.
+     *
+     * When a caller sends `?expand=author,contact`, the HTTP server automatically:
+     * 1. Collects all unique foreign-key UUIDs from the response
+     * 2. Calls each resolver once with the batch of IDs (no N+1)
+     * 3. Replaces UUIDs with full objects inline before returning the response
+     *
+     * @example
+     * ```ts
+     * expandable: {
+     *   author: {
+     *     model: 'ticketing_user',
+     *     resolver: async (ids, ctx) => {
+     *       const users = await db.ticketingUser.findMany({ where: { id: { in: ids } } });
+     *       return new Map(users.map(u => [u.id, u]));
+     *     },
+     *   },
+     *   contact: {
+     *     model: 'contact',
+     *     resolver: async (ids, ctx) => {
+     *       const contacts = await db.contact.findMany({ where: { id: { in: ids } } });
+     *       return new Map(contacts.map(c => [c.id, c]));
+     *     },
+     *   },
+     * },
+     * ```
+     */
+    expandable?: Record<string, {
+        /** The entity/model slug being referenced (for documentation only) */
+        model: string;
+        /** Batch resolver — given an array of unique IDs, return a Map<id, full_object>. Called once per field. */
+        resolver: (ids: string[], ctx: ActionCtx) => Promise<Map<string, Record<string, unknown>>>;
+    }>;
     capabilities?: Array<{
         type: 'webhook';
         eventTypes: string[];
@@ -239,8 +273,13 @@ export interface HttpServerOptions {
  */
 export declare function runHttpServer<T extends WorkerDef>(def: T, opts?: HttpServerOptions): void;
 /**
- * Run both HTTP server and queue consumer concurrently
- * This gives you the best of both worlds: direct API access AND event processing
+ * Run both HTTP server and queue consumer concurrently.
+ * This gives you the best of both worlds: direct API access AND event processing.
+ *
+ * Queue consumer mode is selected automatically by runWorker():
+ *   - SSE mode (preferred): NOVA_EVENTS_SERVICE_URL + NOVA_SERVICE_TOKEN are set
+ *   - Legacy mode: RUNTIME_SUPABASE_* env vars are set (pgmq_public RPC)
+ *   - HTTP-only: neither set — queue consumer is skipped with a warning
  */
 export declare function runDualMode<T extends WorkerDef>(def: T, opts?: {
     port?: number;

package/dist/index.js

@@ -761,9 +761,37 @@ export function runHttpServer(def, opts = {}) {
                         : ' [no auth]';
                 console.log(`[nova] ▶ ${method.toUpperCase()} ${route} → ${actionName} (${jobId})${authLabel}`);
                 const out = await act.handler(input, ctx);
-                act.output.parse(out);
+                // ── Expand support: ?expand=field1,field2 ──────────────────────────────
+                // Batch-resolves foreign-key UUID fields to full objects (no N+1).
+                // Declare expandable fields on the ActionDef to opt-in.
+                let finalOut = out;
+                if (act.expandable && typeof out === 'object' && out !== null) {
+                    const rawExpand = req.query?.expand ?? '';
+                    const expandFields = rawExpand.split(',').map((s) => s.trim()).filter(Boolean);
+                    if (expandFields.length > 0) {
+                        const rows = Array.isArray(out) ? out : (out.results ?? []);
+                        for (const field of expandFields) {
+                            const cfg = act.expandable[field];
+                            if (!cfg || rows.length === 0)
+                                continue;
+                            // Collect unique non-null string IDs
+                            const ids = [...new Set(rows.map((r) => r[field]).filter((v) => typeof v === 'string' && v))];
+                            if (ids.length === 0)
+                                continue;
+                            const map = await cfg.resolver(ids, ctx);
+                            // Replace UUIDs with full objects inline (mutates rows copy)
+                            for (const row of rows) {
+                                if (typeof row[field] === 'string' && map.has(row[field])) {
+                                    row[field] = map.get(row[field]);
+                                }
+                            }
+                        }
+                        finalOut = Array.isArray(out) ? rows : { ...out, results: rows };
+                    }
+                }
+                act.output.parse(finalOut);
                 console.log(`[nova] ✅ ${actionName} completed (${jobId})`);
-                res.json(out);
+                res.json(finalOut);
             }
             catch (err) {
                 console.error(`[nova] ❌ ${actionName} failed:`, err.message);
@@ -798,26 +826,31 @@ export function runHttpServer(def, opts = {}) {
 }
 /*──────────────── Dual Mode: HTTP + Queue Consumer ───────────────*/
 /**
- * Run both HTTP server and queue consumer concurrently
- * This gives you the best of both worlds: direct API access AND event processing
+ * Run both HTTP server and queue consumer concurrently.
+ * This gives you the best of both worlds: direct API access AND event processing.
+ *
+ * Queue consumer mode is selected automatically by runWorker():
+ *   - SSE mode (preferred): NOVA_EVENTS_SERVICE_URL + NOVA_SERVICE_TOKEN are set
+ *   - Legacy mode: RUNTIME_SUPABASE_* env vars are set (pgmq_public RPC)
+ *   - HTTP-only: neither set — queue consumer is skipped with a warning
  */
 export function runDualMode(def, opts = {}) {
     console.log(`🚀 Worker "${def.name}" starting in DUAL MODE`);
     console.log(`📡 HTTP API + 🎯 Event Queue Consumer`);
     // Start HTTP server
     runHttpServer(def, opts);
-    // Start queue consumer (if runtime env vars are available)
-    if (process.env.RUNTIME_SUPABASE_URL && process.env.RUNTIME_SUPABASE_KEY) {
-        console.log(`🎯 Starting queue consumer for events...`);
-        // Run queue consumer in background (don't await)
+    // Start queue consumer in background (don't await).
+    // runWorker() selects the correct mode (SSE vs. legacy) based on env vars.
+    if (process.env.NOVA_EVENTS_SERVICE_URL || process.env.RUNTIME_SUPABASE_URL) {
+        console.log(`🎯 Starting queue consumer for "${def.name}" (queue: ${def.queue})…`);
         runWorker(def).catch((error) => {
             console.error(`[nova] ❌ Queue consumer error:`, error);
             console.error(`[nova] 💡 HTTP server continues running for direct API access`);
         });
     }
     else {
-        console.warn(`⚠️  RUNTIME_SUPABASE_* env vars not set - queue consumer disabled`);
-        console.log(`💡 Worker running in HTTP-only mode. Set RUNTIME_SUPABASE_URL and RUNTIME_SUPABASE_SERVICE_ROLE_KEY to enable event processing`);
+        console.warn(`⚠️  No event consumer env vars found — queue consumer disabled.\n` +
+            `   Set NOVA_EVENTS_SERVICE_URL + NOVA_SERVICE_TOKEN to enable SSE mode.`);
     }
 }
 /*──────────────── Event Outbox (re-exports for convenience) ───────────────*/

package/dist/next.d.ts

@@ -319,6 +319,105 @@ export declare function buildPrismaOffsetPage(input: OffsetPageInputType, defaul
     take: number;
     orderBy: Record<string, 'asc' | 'desc'>;
 };
+/**
+ * Configuration for a single expandable relation on a list or detail endpoint.
+ *
+ * The `resolver` receives an array of unique foreign-key IDs collected from the
+ * response and must return a `Map<id, expanded_object>` so the framework can
+ * replace UUIDs with full objects in a single batch (no N+1 queries).
+ *
+ * @example
+ * ```ts
+ * const expandConfig: Record<string, ExpandConfig> = {
+ *   author: {
+ *     foreignKey: 'author',
+ *     resolver: async (ids) => {
+ *       const users = await db.ticketingUser.findMany({ where: { id: { in: ids } } });
+ *       return new Map(users.map(u => [u.id, u]));
+ *     },
+ *   },
+ *   contact: {
+ *     foreignKey: 'contact',
+ *     resolver: async (ids) => {
+ *       const contacts = await db.contact.findMany({ where: { id: { in: ids } } });
+ *       return new Map(contacts.map(c => [c.id, c]));
+ *     },
+ *   },
+ * };
+ * ```
+ */
+export interface ExpandConfig {
+    /**
+     * The field name on the parent record that holds the foreign-key UUID.
+     * Usually the same as the expand key name (e.g., `"author"` → `record.author`).
+     */
+    foreignKey: string;
+    /**
+     * Batch resolver — given an array of unique IDs, return a Map<id, full_object>.
+     * Called once per expand field; never called with an empty array.
+     *
+     * Use a single `findMany` query to batch-resolve all IDs at once.
+     */
+    resolver: (ids: string[]) => Promise<Map<string, Record<string, unknown>>>;
+}
+/**
+ * Parse the `?expand=` query parameter into an array of field names.
+ *
+ * Accepts comma-separated values: `?expand=author,contact` → `["author", "contact"]`
+ * Returns an empty array when no expand param is present.
+ *
+ * @example
+ * ```ts
+ * const expands = parseExpand(input.expand); // ["author", "contact"]
+ * ```
+ */
+export declare function parseExpand(raw?: string | null): string[];
+/**
+ * Apply inline expansion to an array of records.
+ *
+ * For each field in `expandFields` that has a matching entry in `expandConfig`,
+ * this function:
+ * 1. Collects all unique foreign-key values from the records
+ * 2. Calls the resolver once with the batch of IDs
+ * 3. Replaces each UUID value with the full resolved object in-place
+ *
+ * Records that have `null` / `undefined` for the field are left unchanged.
+ * Unknown expand fields (not in `expandConfig`) are silently ignored.
+ *
+ * @param results      Array of records to expand (mutated in-place)
+ * @param expandFields List of field names to expand (from `parseExpand()`)
+ * @param expandConfig Map of expand configurations keyed by field name
+ * @returns The same `results` array with UUIDs replaced by full objects
+ *
+ * @example
+ * ```ts
+ * // In a route handler:
+ * const expands = parseExpand(input.expand);
+ * const expanded = await applyExpand(data, expands, {
+ *   author: {
+ *     foreignKey: 'author',
+ *     resolver: async (ids) => {
+ *       const users = await db.ticketingUser.findMany({ where: { id: { in: ids } } });
+ *       return new Map(users.map(u => [u.id, u]));
+ *     },
+ *   },
+ * });
+ * return nova.respond({ results: expanded, next, total_count: count ?? 0 });
+ * ```
+ */
+export declare function applyExpand<T extends Record<string, any>>(results: T[], expandFields: string[], expandConfig: Record<string, ExpandConfig>): Promise<T[]>;
+/**
+ * Standard `params` metadata for the `?expand=` query parameter.
+ * Spread into `novaEndpoint({ params: { ...EXPAND_PARAM, ...yourParams } })`.
+ *
+ * @example
+ * ```ts
+ * export const nova = novaEndpoint({
+ *   params: { ...CURSOR_PAGE_PARAMS, ...EXPAND_PARAM, ...myParams },
+ * });
+ * ```
+ */
+export declare const EXPAND_PARAM: Record<string, ParamMeta>;
 /**
  * Standard `params` metadata for cursor-based pagination fields.
  * Spread into `novaEndpoint({ params: { ...CURSOR_PAGE_PARAMS, ...yourParams } })`.

package/dist/next.js

@@ -210,7 +210,97 @@ export function buildPrismaOffsetPage(input, defaultSort = 'createdAt') {
         orderBy: { [col]: input.sort_dir },
     };
 }
+/**
+ * Parse the `?expand=` query parameter into an array of field names.
+ *
+ * Accepts comma-separated values: `?expand=author,contact` → `["author", "contact"]`
+ * Returns an empty array when no expand param is present.
+ *
+ * @example
+ * ```ts
+ * const expands = parseExpand(input.expand); // ["author", "contact"]
+ * ```
+ */
+export function parseExpand(raw) {
+    if (!raw)
+        return [];
+    return raw.split(',').map(s => s.trim()).filter(Boolean);
+}
+/**
+ * Apply inline expansion to an array of records.
+ *
+ * For each field in `expandFields` that has a matching entry in `expandConfig`,
+ * this function:
+ * 1. Collects all unique foreign-key values from the records
+ * 2. Calls the resolver once with the batch of IDs
+ * 3. Replaces each UUID value with the full resolved object in-place
+ *
+ * Records that have `null` / `undefined` for the field are left unchanged.
+ * Unknown expand fields (not in `expandConfig`) are silently ignored.
+ *
+ * @param results      Array of records to expand (mutated in-place)
+ * @param expandFields List of field names to expand (from `parseExpand()`)
+ * @param expandConfig Map of expand configurations keyed by field name
+ * @returns The same `results` array with UUIDs replaced by full objects
+ *
+ * @example
+ * ```ts
+ * // In a route handler:
+ * const expands = parseExpand(input.expand);
+ * const expanded = await applyExpand(data, expands, {
+ *   author: {
+ *     foreignKey: 'author',
+ *     resolver: async (ids) => {
+ *       const users = await db.ticketingUser.findMany({ where: { id: { in: ids } } });
+ *       return new Map(users.map(u => [u.id, u]));
+ *     },
+ *   },
+ * });
+ * return nova.respond({ results: expanded, next, total_count: count ?? 0 });
+ * ```
+ */
+export async function applyExpand(results, expandFields, expandConfig) {
+    for (const field of expandFields) {
+        const config = expandConfig[field];
+        if (!config)
+            continue; // unknown expand field — silently skip
+        // Collect unique non-null IDs from the foreign-key field
+        const ids = [...new Set(results.map(r => r[config.foreignKey]).filter((v) => Boolean(v)))];
+        if (ids.length === 0)
+            continue;
+        // Single batch call — no N+1
+        const resolved = await config.resolver(ids);
+        // Replace UUID → full object in-place
+        for (const item of results) {
+            const fkValue = item[config.foreignKey];
+            if (typeof fkValue === 'string' && resolved.has(fkValue)) {
+                item[config.foreignKey] = resolved.get(fkValue);
+            }
+        }
+    }
+    return results;
+}
 // ─── Standard param metadata ──────────────────────────────────────────────────
+/**
+ * Standard `params` metadata for the `?expand=` query parameter.
+ * Spread into `novaEndpoint({ params: { ...EXPAND_PARAM, ...yourParams } })`.
+ *
+ * @example
+ * ```ts
+ * export const nova = novaEndpoint({
+ *   params: { ...CURSOR_PAGE_PARAMS, ...EXPAND_PARAM, ...myParams },
+ * });
+ * ```
+ */
+export const EXPAND_PARAM = {
+    expand: {
+        in: 'query',
+        uiType: 'text',
+        label: 'Expand',
+        description: 'Comma-separated list of relations to expand inline (e.g., "author,contact"). Returns full objects instead of UUIDs.',
+        placeholder: 'author,contact',
+    },
+};
 /**
  * Standard `params` metadata for cursor-based pagination fields.
  * Spread into `novaEndpoint({ params: { ...CURSOR_PAGE_PARAMS, ...yourParams } })`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newhomestar/sdk",
-  "version": "0.7.1",
+  "version": "0.7.4",
   "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
   "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
   "bugs": {