@newhomestar/sdk 0.7.13 → 0.7.15

package/dist/credentials.d.ts

@@ -45,6 +45,12 @@ export declare class TokenExchangeError extends Error {
  * Reads from PLATFORM_SUPABASE_URL + PLATFORM_SUPABASE_SERVICE_ROLE_KEY.
  */
 export declare function createPlatformClient(): SupabaseClient;
+/**
+ * Evict a cached token for the given integration slug and optional userId.
+ * Call this when an API returns 401 so the next resolveCredentials() call
+ * fetches a fresh token instead of re-using the revoked one.
+ */
+export declare function clearTokenCache(slug: string, userId?: string): void;
 /**
  * Resolves an access token for an integration, handling all auth modes.
  *
@@ -90,7 +96,9 @@ export declare function emitPlatformEvent(platformDB: SupabaseClient, topic: str
  * @param bearerToken - JWT to authenticate with the auth server
  * @param userId      - Optional user ID (for cache key differentiation)
  */
-export declare function resolveCredentialsViaHttp(authBaseUrl: string, slug: string, bearerToken: string, userId?: string): Promise<ResolvedCredentials>;
+export declare function resolveCredentialsViaHttp(authBaseUrl: string, slug: string, bearerToken: string, userId?: string, options?: {
+    forceRefresh?: boolean;
+}): Promise<ResolvedCredentials>;
 /**
  * Detect which credential resolution strategy to use.
  * Returns 'db' if PLATFORM_SUPABASE_* are available, 'http' if AUTH_ISSUER_BASE_URL

package/dist/credentials.js

@@ -78,6 +78,16 @@ const SYSTEM_USER_ID = "00000000-0000-0000-0000-000000000000";
 function getCacheKey(integrationSlug, userId) {
     return `${integrationSlug}:${userId ?? SYSTEM_USER_ID}`;
 }
+/**
+ * Evict a cached token for the given integration slug and optional userId.
+ * Call this when an API returns 401 so the next resolveCredentials() call
+ * fetches a fresh token instead of re-using the revoked one.
+ */
+export function clearTokenCache(slug, userId) {
+    const key = getCacheKey(slug, userId);
+    const deleted = _tokenCache.delete(key);
+    console.log(`[nova-sdk] 🗑️  Cleared in-memory token cache for "${slug}" (key=${key}, existed=${deleted})`);
+}
 function getCachedToken(key) {
     const cached = _tokenCache.get(key);
     if (!cached)
@@ -613,20 +623,23 @@ function buildMtlsAgentFromPem(slug, certPem, keyPem) {
  * Requires a valid JWT Bearer token (the same one that authenticated the
  * inbound request to this container).
  *
- * @param authBaseUrl - Auth server base URL (e.g., "http://localhost:3001")
- * @param slug        - Integration slug (e.g., "adp")
- * @param bearerToken - JWT to forward as Authorization header
+ * @param authBaseUrl  - Auth server base URL (e.g., "http://localhost:3001")
+ * @param slug         - Integration slug (e.g., "adp")
+ * @param bearerToken  - JWT to forward as Authorization header
+ * @param forceRefresh - When true, sends X-Nova-Token-Invalid: true to trigger a forced refresh
  */
-async function fetchCredentialsFromAuthServer(authBaseUrl, slug, bearerToken) {
+async function fetchCredentialsFromAuthServer(authBaseUrl, slug, bearerToken, forceRefresh = false) {
     const url = `${authBaseUrl}/api/integrations/${encodeURIComponent(slug)}/credentials`;
-    console.log(`[nova-sdk] 🌐 Fetching credentials via HTTP: GET ${url}`);
-    const res = await fetch(url, {
-        method: "GET",
-        headers: {
-            Authorization: `Bearer ${bearerToken}`,
-            Accept: "application/json",
-        },
-    });
+    console.log(`[nova-sdk] 🌐 Fetching credentials via HTTP: GET ${url}${forceRefresh ? " (force-refresh)" : ""}`);
+    const headers = {
+        Authorization: `Bearer ${bearerToken}`,
+        Accept: "application/json",
+    };
+    // Signal the auth server to discard its stored token and force a refresh
+    if (forceRefresh) {
+        headers["X-Nova-Token-Invalid"] = "true";
+    }
+    const res = await fetch(url, { method: "GET", headers });
     if (!res.ok) {
         const errBody = await res.text().catch(() => "");
         if (res.status === 401) {
@@ -656,12 +669,13 @@ async function fetchCredentialsFromAuthServer(authBaseUrl, slug, bearerToken) {
  * @param bearerToken - JWT to authenticate with the auth server
  * @param userId      - Optional user ID (for cache key differentiation)
  */
-export async function resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken, userId) {
+export async function resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken, userId, options) {
     const effectiveUserId = userId ?? SYSTEM_USER_ID;
     const cacheKey = getCacheKey(slug, effectiveUserId);
-    console.log(`[nova-sdk] 🔑 Resolving credentials for "${slug}" via HTTP (userId: ${effectiveUserId})`);
-    // ── Step 1: Check in-memory cache ─────────────────────────────────────
-    const cached = getCachedToken(cacheKey);
+    const forceRefresh = options?.forceRefresh ?? false;
+    console.log(`[nova-sdk] 🔑 Resolving credentials for "${slug}" via HTTP (userId: ${effectiveUserId}${forceRefresh ? ", forceRefresh=true" : ""})`);
+    // ── Step 1: Check in-memory cache (skip if forcing refresh) ──────────
+    const cached = forceRefresh ? null : getCachedToken(cacheKey);
     if (cached) {
         // Derive authMode: use stored value if available, otherwise infer from httpsAgent
         const cachedAuthMode = cached.authMode ?? (cached.httpsAgent ? "mtls" : "client_credentials");
@@ -675,7 +689,7 @@ export async function resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken,
         };
     }
     // ── Step 2: Fetch credentials from auth server ────────────────────────
-    const creds = await fetchCredentialsFromAuthServer(authBaseUrl, slug, bearerToken);
+    const creds = await fetchCredentialsFromAuthServer(authBaseUrl, slug, bearerToken, forceRefresh);
     // ── Step 2b: Standard auth — use pre-resolved access token if available ──
     if (creds.authMode === "standard") {
         if (creds.accessToken) {

package/dist/events.d.ts

@@ -339,6 +339,70 @@ export declare function withInboundEvent(db: any, msg: InboundMessage, handler:
  * process.on('SIGTERM', () => consumer.abort());
  */
 export declare function startInboundConsumer(db: any, options: InboundConsumerOptions): AbortController;
+/** Options for startPollConsumer() — extends InboundConsumerOptions */
+export interface PollConsumerOptions extends InboundConsumerOptions {
+    /**
+     * Messages to request per poll (default: 5).
+     * All messages in the batch are processed sequentially before the next poll.
+     * At-least-once: messages not ACKed within `vt` seconds become visible again.
+     */
+    batch?: number;
+    /**
+     * Milliseconds to sleep between polls when the queue is empty (default: 2000).
+     * Prevents hot-polling against the Events Service.
+     */
+    idleDelayMs?: number;
+}
+/**
+ * Start a worker-pull consumer that polls POST /events/queue/poll, processes
+ * each message via withInboundEvent(), and ACKs on success.
+ *
+ * **This is the recommended pattern for DO App Platform** (and any platform that
+ * doesn't support long-lived SSE connections). Unlike startInboundConsumer (SSE),
+ * each poll is a short HTTP request — no persistent connections, no proxy timeouts.
+ *
+ * ## Loop flow (sequential, never overlaps):
+ *   1. POST /events/queue/poll → up to `batch` messages
+ *   2. For each message (in order):
+ *      a. withInboundEvent(db, msg, handler) → ACID tx + ACK
+ *      b. On failure: NACK → PGMQ re-delivers after VT expires
+ *   3. Sleep `idleDelayMs` if queue was empty, 100ms pause between batches
+ *   4. Repeat — next poll only fires after the current batch is fully processed
+ *
+ * ## ACID / at-least-once guarantee:
+ * Same as startInboundConsumer — withInboundEvent() wraps each message in a
+ * Prisma transaction (inbound_events INSERT + handler). If the handler fails,
+ * no ACK is sent — PGMQ re-delivers after VT. If ACK fails after a successful
+ * transaction, PGMQ re-delivers but the UNIQUE(msg_id) constraint prevents
+ * double-processing (duplicate is ACKed and skipped).
+ *
+ * ## Competing consumers:
+ * Multiple replicas can all call startPollConsumer() on the same queue.
+ * PGMQ's FOR UPDATE SKIP LOCKED ensures each replica gets different messages.
+ *
+ * @param db      - Prisma client (must have `inboundEvent` model)
+ * @param options - Consumer configuration
+ * @returns       - AbortController — call `.abort()` for graceful shutdown
+ *
+ * @example
+ * // Drop-in replacement for startInboundConsumer:
+ * const consumer = startPollConsumer(db, {
+ *   queueName:   'jira_queue',
+ *   batch:       5,      // process up to 5 messages per poll
+ *   vt:          60,     // 60s visibility timeout — must be > max handler time
+ *   idleDelayMs: 2000,   // sleep 2s when queue is empty
+ *   handlers: {
+ *     'nova_ticketing_service.ticket_created': async (tx, event) => {
+ *       await tx.jiraIssue.upsert({ ... });
+ *       return { status: 'processed' };
+ *     },
+ *   },
+ * });
+ *
+ * // Graceful shutdown
+ * process.on('SIGTERM', () => consumer.abort());
+ */
+export declare function startPollConsumer(db: any, options: PollConsumerOptions): AbortController;
 /**
  * Class-based client when you need more control than the top-level functions.
  * Useful when you want to pass configuration explicitly rather than relying on env vars.

package/dist/events.js

@@ -883,6 +883,196 @@ export function startInboundConsumer(db, options) {
     });
     return abort;
 }
+/**
+ * Start a worker-pull consumer that polls POST /events/queue/poll, processes
+ * each message via withInboundEvent(), and ACKs on success.
+ *
+ * **This is the recommended pattern for DO App Platform** (and any platform that
+ * doesn't support long-lived SSE connections). Unlike startInboundConsumer (SSE),
+ * each poll is a short HTTP request — no persistent connections, no proxy timeouts.
+ *
+ * ## Loop flow (sequential, never overlaps):
+ *   1. POST /events/queue/poll → up to `batch` messages
+ *   2. For each message (in order):
+ *      a. withInboundEvent(db, msg, handler) → ACID tx + ACK
+ *      b. On failure: NACK → PGMQ re-delivers after VT expires
+ *   3. Sleep `idleDelayMs` if queue was empty, 100ms pause between batches
+ *   4. Repeat — next poll only fires after the current batch is fully processed
+ *
+ * ## ACID / at-least-once guarantee:
+ * Same as startInboundConsumer — withInboundEvent() wraps each message in a
+ * Prisma transaction (inbound_events INSERT + handler). If the handler fails,
+ * no ACK is sent — PGMQ re-delivers after VT. If ACK fails after a successful
+ * transaction, PGMQ re-delivers but the UNIQUE(msg_id) constraint prevents
+ * double-processing (duplicate is ACKed and skipped).
+ *
+ * ## Competing consumers:
+ * Multiple replicas can all call startPollConsumer() on the same queue.
+ * PGMQ's FOR UPDATE SKIP LOCKED ensures each replica gets different messages.
+ *
+ * @param db      - Prisma client (must have `inboundEvent` model)
+ * @param options - Consumer configuration
+ * @returns       - AbortController — call `.abort()` for graceful shutdown
+ *
+ * @example
+ * // Drop-in replacement for startInboundConsumer:
+ * const consumer = startPollConsumer(db, {
+ *   queueName:   'jira_queue',
+ *   batch:       5,      // process up to 5 messages per poll
+ *   vt:          60,     // 60s visibility timeout — must be > max handler time
+ *   idleDelayMs: 2000,   // sleep 2s when queue is empty
+ *   handlers: {
+ *     'nova_ticketing_service.ticket_created': async (tx, event) => {
+ *       await tx.jiraIssue.upsert({ ... });
+ *       return { status: 'processed' };
+ *     },
+ *   },
+ * });
+ *
+ * // Graceful shutdown
+ * process.on('SIGTERM', () => consumer.abort());
+ */
+export function startPollConsumer(db, options) {
+    const { queueName, handlers, defaultHandler, vt = 30, batch = 5, idleDelayMs = 2_000, } = options;
+    const eventsUrl = options.eventsUrl ?? process.env.NOVA_EVENTS_SERVICE_URL;
+    const serviceToken = options.serviceToken ?? process.env.NOVA_SERVICE_TOKEN;
+    if (!eventsUrl || !serviceToken) {
+        console.error('[nova/events] startPollConsumer: NOVA_EVENTS_SERVICE_URL and NOVA_SERVICE_TOKEN ' +
+            'must be set. Poll consumer will NOT start.');
+        return new AbortController();
+    }
+    const abort = new AbortController();
+    /** Derive the event topic from a raw PGMQ message payload */
+    function _deriveEventType(payload) {
+        if (typeof payload.topic === 'string')
+            return payload.topic;
+        if (typeof payload.entity_type === 'string' && typeof payload.action === 'string') {
+            return `${payload.entity_type}.${payload.action}`;
+        }
+        return 'unknown.event';
+    }
+    /** Send a NACK to the events service to release the visibility timeout early */
+    async function _nack(msgId, readCt) {
+        try {
+            await fetch(`${eventsUrl}/events/queue/nack`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${serviceToken}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ queue: queueName, msg_id: msgId }),
+            });
+        }
+        catch (err) {
+            console.error(`[nova/events] NACK failed for msg_id=${msgId} read_ct=${readCt}:`, String(err).slice(0, 200));
+        }
+    }
+    /** Sleep for ms, returning early if the consumer is aborted */
+    function _sleep(ms) {
+        return new Promise((resolve) => {
+            const t = setTimeout(resolve, ms);
+            abort.signal.addEventListener('abort', () => { clearTimeout(t); resolve(); }, { once: true });
+        });
+    }
+    /** Sequential poll loop — one batch at a time, never overlaps */
+    async function _pollLoop() {
+        const tokenSuffix = serviceToken ? `***${serviceToken.slice(-4)}` : 'MISSING';
+        console.log(`[nova/events] Poll consumer starting — url=${eventsUrl} ` +
+            `token=${tokenSuffix} queue=${queueName} vt=${vt}s batch=${batch} idleDelay=${idleDelayMs}ms`);
+        while (!abort.signal.aborted) {
+            let messages = [];
+            // ── 1. Poll for a batch of messages ────────────────────────────────────
+            try {
+                const res = await fetch(`${eventsUrl}/events/queue/poll`, {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': `Bearer ${serviceToken}`,
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({ queue: queueName, vt, batch }),
+                    signal: abort.signal,
+                });
+                if (!res.ok) {
+                    const text = await res.text().catch(() => '');
+                    console.error(`[nova/events] Poll failed for queue "${queueName}": HTTP ${res.status} — ${text.slice(0, 200)}`);
+                    await _sleep(idleDelayMs);
+                    continue;
+                }
+                const data = await res.json();
+                messages = data.messages ?? [];
+            }
+            catch (err) {
+                if (abort.signal.aborted)
+                    return;
+                const isAbortError = err?.name === 'AbortError' || err?.code === 20;
+                if (isAbortError)
+                    return;
+                console.error(`[nova/events] Poll network error for queue "${queueName}":`, String(err).slice(0, 500));
+                await _sleep(idleDelayMs);
+                continue;
+            }
+            // Queue empty — sleep before polling again
+            if (messages.length === 0) {
+                await _sleep(idleDelayMs);
+                continue;
+            }
+            // ── 2. Process each message sequentially ───────────────────────────────
+            // Processing is intentionally sequential (not concurrent) so that:
+            //   a) Messages for the same entity are handled in order
+            //   b) No poll fires until the current batch is fully processed
+            for (const raw of messages) {
+                if (abort.signal.aborted)
+                    return;
+                // DLQ-routed messages — already moved to DLQ by the server; just log
+                if (raw.event === 'dlq') {
+                    console.warn(`[nova/events] msg_id=${raw.msg_id} moved to DLQ "${raw.dlq_queue}" ` +
+                        `(read_ct=${raw.read_ct}) — skipping processing`);
+                    continue;
+                }
+                const payload = raw.message;
+                const eventType = _deriveEventType(payload);
+                const handler = handlers[eventType] ?? defaultHandler;
+                const msg = {
+                    msg_id: raw.msg_id,
+                    queue: queueName,
+                    payload,
+                    read_ct: raw.read_ct,
+                };
+                if (!handler) {
+                    // No handler registered and no default — ACK to unblock the queue
+                    console.log(`[nova/events] No handler for event type "${eventType}" (msg_id=${raw.msg_id}) — ACK and skip`);
+                    try {
+                        await fetch(`${eventsUrl}/events/queue/ack`, {
+                            method: 'POST',
+                            headers: { 'Authorization': `Bearer ${serviceToken}`, 'Content-Type': 'application/json' },
+                            body: JSON.stringify({ queue: queueName, msg_id: raw.msg_id }),
+                        });
+                    }
+                    catch { /* best-effort */ }
+                    continue;
+                }
+                try {
+                    const outcome = await withInboundEvent(db, msg, handler);
+                    console.log(`[nova/events] msg_id=${raw.msg_id} event="${eventType}" status=${outcome.status} read_ct=${raw.read_ct}`);
+                }
+                catch (err) {
+                    console.error(`[nova/events] Handler failed for msg_id=${raw.msg_id} event="${eventType}" read_ct=${raw.read_ct}:`, err);
+                    // NACK — extends visibility timeout so PGMQ will re-deliver
+                    await _nack(raw.msg_id, raw.read_ct);
+                }
+            }
+            // Short pause between non-empty batches — breathing room for the
+            // Prisma connection pool before the next poll
+            await _sleep(100);
+        }
+        console.log(`[nova/events] Poll consumer for queue "${queueName}" shut down gracefully`);
+    }
+    // Start the poll loop (non-blocking — does not await)
+    _pollLoop().catch((err) => {
+        console.error(`[nova/events] startPollConsumer fatal error for queue "${queueName}":`, err);
+    });
+    return abort;
+}
 // ── NovaEventsClient ───────────────────────────────────────────────────────────
 /**
  * Class-based client when you need more control than the top-level functions.

package/dist/index.d.ts

@@ -293,8 +293,8 @@ export declare function runHttpServer<T extends WorkerDef>(def: T, opts?: HttpSe
 export declare function runDualMode<T extends WorkerDef>(def: T, opts?: {
     port?: number;
 }): void;
-export { withServiceEventOutbox, withEventOutbox, isIntegrationSync, queueEvent, logEvent, startOutboxRelay, NovaEventsClient, } from './events.js';
-export type { QueueEventPayload, LogEventPayload, OutboxRelayOptions, ServiceEmitFn, } from './events.js';
+export { withServiceEventOutbox, withEventOutbox, isIntegrationSync, queueEvent, logEvent, startOutboxRelay, startInboundConsumer, startPollConsumer, NovaEventsClient, } from './events.js';
+export type { QueueEventPayload, LogEventPayload, OutboxRelayOptions, ServiceEmitFn, InboundConsumerOptions, PollConsumerOptions, } from './events.js';
 export type { ZodTypeAny as SchemaAny, ZodTypeAny };
 export { parseNovaSpec } from "./parseSpec.js";
 export type { NovaSpec } from "./parseSpec.js";

package/dist/index.js

@@ -6,7 +6,7 @@ import { createServer } from "node:http";
 import { os } from "@orpc/server";
 import { RPCHandler } from "@orpc/server/node";
 import { CORSPlugin } from "@orpc/server/plugins";
-import { createPlatformClient, resolveCredentials as _resolveCredentials, resolveCredentialsViaHttp as _resolveCredentialsViaHttp, detectCredentialStrategy, integrationFetch as _integrationFetch, } from "./credentials.js";
+import { createPlatformClient, resolveCredentials as _resolveCredentials, resolveCredentialsViaHttp as _resolveCredentialsViaHttp, detectCredentialStrategy, integrationFetch as _integrationFetch, clearTokenCache as _clearTokenCache, } from "./credentials.js";
 if (!process.env.RUNTIME_SUPABASE_URL) {
     // local dev – read .env.local
     dotenv.config({ path: ".env.local", override: true });
@@ -580,7 +580,42 @@ function buildCredentialCtx(defaultSlug, authToken) {
     };
     const ctxFetch = async (url, options, credentials) => {
         const creds = credentials ?? _lastCreds ?? await ctxResolveCredentials();
-        return _integrationFetch(url, creds, options);
+        const response = await _integrationFetch(url, creds, options);
+        // ── 401 auto-retry: token may have been revoked ──────────────────────────
+        // If the API returns 401 AND the caller didn't supply explicit credentials
+        // (i.e., we used the cached/resolved ones), clear the in-memory cache and
+        // force-refresh from the auth server, then retry once.
+        // This handles the "user re-authenticated but container still holds the old
+        // revoked token" scenario.
+        if (response.status === 401 && !credentials) {
+            console.warn(`[nova-sdk] ⚠️ 401 received from ${url} — clearing cache and force-refreshing credentials for "${defaultSlug}"`);
+            _clearTokenCache(defaultSlug);
+            _lastCreds = null;
+            let freshCreds;
+            if (strategy === "http") {
+                // HTTP strategy: signal auth server to bypass its stored token and refresh
+                const authBaseUrl = process.env.AUTH_ISSUER_BASE_URL;
+                if (!authToken) {
+                    console.error("[nova-sdk] ❌ Cannot force-refresh: no authToken available");
+                    return response; // return original 401
+                }
+                freshCreds = await _resolveCredentialsViaHttp(authBaseUrl, defaultSlug, authToken, undefined, { forceRefresh: true });
+            }
+            else {
+                // DB strategy: just re-resolve (DB always reads latest from vault)
+                freshCreds = await ctxResolveCredentials();
+            }
+            _lastCreds = freshCreds;
+            // Only retry if we got a different (fresh) token — avoid an infinite loop
+            if (freshCreds.accessToken !== creds.accessToken) {
+                console.log(`[nova-sdk] 🔄 Retrying request with refreshed token for "${defaultSlug}"`);
+                return _integrationFetch(url, freshCreds, options);
+            }
+            else {
+                console.warn(`[nova-sdk] ⚠️ Force-refresh returned the same token for "${defaultSlug}" — not retrying`);
+            }
+        }
+        return response;
     };
     return { resolveCredentials: ctxResolveCredentials, fetch: ctxFetch };
 }
@@ -865,7 +900,7 @@ export function runDualMode(def, opts = {}) {
 /*──────────────── Event Outbox (re-exports for convenience) ───────────────*/
 // Full API is also available via '@newhomestar/sdk/events' subpath.
 // These re-exports allow import { withServiceEventOutbox } from '@newhomestar/sdk'.
-export { withServiceEventOutbox, withEventOutbox, isIntegrationSync, queueEvent, logEvent, startOutboxRelay, NovaEventsClient, } from './events.js';
+export { withServiceEventOutbox, withEventOutbox, isIntegrationSync, queueEvent, logEvent, startOutboxRelay, startInboundConsumer, startPollConsumer, NovaEventsClient, } from './events.js';
 // YAML spec parsing utility
 export { parseNovaSpec } from "./parseSpec.js";
 // Integration definition API

package/dist/next.d.ts

@@ -303,9 +303,23 @@ export declare function buildPrismaPage(input: CursorPageInputType): {
         id: 'desc';
     }>;
 };
+/**
+ * Convert a snake_case string to camelCase.
+ * Used internally to normalise sort column names from API query params
+ * (snake_case) to Prisma model field names (camelCase).
+ *
+ * @example
+ * ```ts
+ * snakeToCamel('modified_at') // → 'modifiedAt'
+ * snakeToCamel('createdAt')   // → 'createdAt' (no-op)
+ * ```
+ */
+export declare function snakeToCamel(s: string): string;
 /**
  * Build Prisma `skip`, `take`, and `orderBy` from an `OffsetPageInput`.
  * Handles offset pagination and sort direction.
+ * Sort column names are automatically converted from snake_case (API convention)
+ * to camelCase (Prisma convention) via `snakeToCamel()`.
  * Does NOT handle `search` or `filters` — apply those to the `where` clause manually.
  *
  * @example

package/dist/next.js

@@ -191,9 +191,25 @@ export function buildPrismaPage(input) {
         orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],
     };
 }
+/**
+ * Convert a snake_case string to camelCase.
+ * Used internally to normalise sort column names from API query params
+ * (snake_case) to Prisma model field names (camelCase).
+ *
+ * @example
+ * ```ts
+ * snakeToCamel('modified_at') // → 'modifiedAt'
+ * snakeToCamel('createdAt')   // → 'createdAt' (no-op)
+ * ```
+ */
+export function snakeToCamel(s) {
+    return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
 /**
  * Build Prisma `skip`, `take`, and `orderBy` from an `OffsetPageInput`.
  * Handles offset pagination and sort direction.
+ * Sort column names are automatically converted from snake_case (API convention)
+ * to camelCase (Prisma convention) via `snakeToCamel()`.
  * Does NOT handle `search` or `filters` — apply those to the `where` clause manually.
  *
  * @example
@@ -203,7 +219,7 @@ export function buildPrismaPage(input) {
  * ```
  */
 export function buildPrismaOffsetPage(input, defaultSort = 'createdAt') {
-    const col = input.sort ?? defaultSort;
+    const col = snakeToCamel(input.sort ?? defaultSort);
     return {
         skip: input.offset,
         take: input.limit,

package/package.json

@@ -1,58 +1,58 @@
-{
-  "name": "@newhomestar/sdk",
-  "version": "0.7.13",
-  "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.7.15",
+  "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"
+  }
+}