@newhomestar/sdk 0.6.7 → 0.6.9

package/dist/index.js

@@ -141,7 +141,46 @@ function buildTopicActionMap(def) {
     }
     return topicMap;
 }
+/**
+ * Build a topic → actionDef map from the new `triggers` API (and legacy `capabilities`).
+ * Used by runWorkerSSE() to route incoming SSE messages to the correct handler.
+ */
+function buildTriggerMap(def) {
+    const map = new Map();
+    for (const [, actionDef] of Object.entries(def.actions)) {
+        // New: triggers API (preferred)
+        const triggers = actionDef.triggers;
+        if (triggers) {
+            for (const trigger of triggers) {
+                if (trigger.type === 'event' && Array.isArray(trigger.events)) {
+                    for (const topic of trigger.events) {
+                        map.set(topic, actionDef);
+                    }
+                }
+            }
+        }
+        // Legacy: capabilities API (backward compat)
+        if (actionDef.capabilities) {
+            for (const cap of actionDef.capabilities) {
+                if (cap.type === 'queue' && cap.topics) {
+                    for (const topic of cap.topics) {
+                        if (!map.has(topic))
+                            map.set(topic, actionDef); // triggers take precedence
+                    }
+                }
+            }
+        }
+    }
+    return map;
+}
 export async function runWorker(def) {
+    // ── SSE mode (preferred): NOVA_EVENTS_SERVICE_URL + NOVA_SERVICE_TOKEN ─────
+    // When these env vars are set the worker connects via SSE to the events service.
+    // No Supabase connection is required on the worker side.
+    if (process.env.NOVA_EVENTS_SERVICE_URL) {
+        return runWorkerSSE(def);
+    }
+    // ── Legacy mode: RUNTIME_SUPABASE_* + pgmq_public RPC ────────────────────
     if (!runtime)
         throw new Error("RUNTIME_SUPABASE_* env vars not configured");
     // Build topic-to-action mapping for capability-based routing
@@ -277,6 +316,177 @@ async function nack(id, q) {
     await runtime.schema("pgmq_public").rpc("nack", { queue_name: q, message_id: id });
 }
 function delay(ms) { return new Promise(r => setTimeout(r, ms)); }
+/*──────────────── SSE Worker Mode ───────────────*/
+const _EVENTS_BASE = () => (process.env.NOVA_EVENTS_SERVICE_URL ?? '').replace(/\/$/, '');
+const _EVENTS_TOKEN = () => process.env.NOVA_SERVICE_TOKEN ?? '';
+async function _ackSSE(queue, msgId) {
+    const res = await fetch(`${_EVENTS_BASE()}/events/queue/ack`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${_EVENTS_TOKEN()}`,
+        },
+        body: JSON.stringify({ queue, msg_id: msgId }),
+    });
+    if (!res.ok)
+        console.error(`[nova] ack failed for msg_id=${msgId}: ${await res.text()}`);
+}
+async function _nackSSE(queue, msgId, readCt) {
+    const res = await fetch(`${_EVENTS_BASE()}/events/queue/nack`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${_EVENTS_TOKEN()}`,
+        },
+        body: JSON.stringify({ queue, msg_id: msgId, read_ct: readCt }),
+    });
+    if (!res.ok)
+        console.error(`[nova] nack failed for msg_id=${msgId}: ${await res.text()}`);
+}
+async function _heartbeatSSE(queue, msgId, extendBy = 30) {
+    const res = await fetch(`${_EVENTS_BASE()}/events/queue/heartbeat`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${_EVENTS_TOKEN()}`,
+        },
+        body: JSON.stringify({ queue, msg_id: msgId, extend_by: extendBy }),
+    });
+    if (!res.ok)
+        console.error(`[nova] heartbeat failed for msg_id=${msgId}: ${await res.text()}`);
+}
+async function runWorkerSSE(def) {
+    const baseUrl = _EVENTS_BASE();
+    const token = _EVENTS_TOKEN();
+    if (!baseUrl)
+        throw new Error('[nova] NOVA_EVENTS_SERVICE_URL is required for SSE worker mode');
+    if (!token)
+        throw new Error('[nova] NOVA_SERVICE_TOKEN is required for SSE worker mode');
+    // ── Ensure the worker's queue exists before connecting ──────────────────
+    const ensureRes = await fetch(`${baseUrl}/events/queue/ensure`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ queue: def.queue }),
+    });
+    if (!ensureRes.ok) {
+        throw new Error(`[nova] Failed to ensure queue '${def.queue}': ${await ensureRes.text()}`);
+    }
+    console.log(`[nova] ✅ Queue '${def.queue}' ready`);
+    const triggerMap = buildTriggerMap(def);
+    console.log(`[nova] SSE worker '${def.name}' → ${baseUrl}/events/queue/stream?queue=${def.queue}`);
+    console.log(`[nova] Trigger map:`, Object.fromEntries(triggerMap));
+    let reconnectDelay = 1_000; // start 1 s, double up to 30 s
+    // ── Outer reconnect loop ─────────────────────────────────────────────────
+    while (true) {
+        try {
+            const streamRes = await fetch(`${baseUrl}/events/queue/stream?queue=${encodeURIComponent(def.queue)}`, { headers: { Authorization: `Bearer ${token}` } });
+            if (!streamRes.ok || !streamRes.body) {
+                const errText = await streamRes.text().catch(() => '');
+                console.error(`[nova] SSE HTTP ${streamRes.status}: ${errText}`);
+                await delay(reconnectDelay);
+                reconnectDelay = Math.min(reconnectDelay * 2, 30_000);
+                continue;
+            }
+            // Successful connection — reset backoff
+            reconnectDelay = 1_000;
+            console.log(`[nova] 📡 SSE stream connected`);
+            // ── Stream reader ──────────────────────────────────────────────────
+            const reader = streamRes.body.getReader();
+            const decoder = new TextDecoder();
+            let buf = '';
+            let currentEvent = null;
+            let currentData = null;
+            readLoop: while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    console.warn(`[nova] SSE stream closed — will reconnect`);
+                    break readLoop;
+                }
+                buf += decoder.decode(value, { stream: true });
+                const lines = buf.split('\n');
+                buf = lines.pop() ?? '';
+                for (const line of lines) {
+                    if (line.startsWith('event:')) {
+                        currentEvent = line.slice(6).trim();
+                    }
+                    else if (line.startsWith('data:')) {
+                        currentData = line.slice(5).trim();
+                    }
+                    else if (line === '') {
+                        // ── End of SSE frame ────────────────────────────────────────
+                        if (currentData) {
+                            try {
+                                const frame = JSON.parse(currentData);
+                                // Server-side DLQ event — already moved; just log
+                                if (currentEvent === 'dlq') {
+                                    console.warn(`[nova] ⚠️  Message ${frame.msg_id} moved to DLQ (read_ct=${frame.read_ct})`);
+                                    currentEvent = null;
+                                    currentData = null;
+                                    continue;
+                                }
+                                // Keepalive heartbeat — ignore
+                                if (frame.type === 'keepalive') {
+                                    currentEvent = null;
+                                    currentData = null;
+                                    continue;
+                                }
+                                // ── Normal message ─────────────────────────────────────
+                                const { msg_id, read_ct, message } = frame;
+                                const topic = message?.topic ?? message?.event_type ?? message?.type ?? '';
+                                const actionDef = triggerMap.get(topic);
+                                if (!actionDef) {
+                                    console.error(`[nova] ❌ No handler for topic '${topic}' — nacking (available: ${[...triggerMap.keys()].join(', ')})`);
+                                    await _nackSSE(def.queue, msg_id, read_ct ?? 0);
+                                    currentEvent = null;
+                                    currentData = null;
+                                    continue;
+                                }
+                                console.log(`[nova] 🚀 topic='${topic}' msg_id=${msg_id} read_ct=${read_ct}`);
+                                // ── Invoke handler ─────────────────────────────────────
+                                try {
+                                    const rawPayload = message?.payload ?? message;
+                                    const parsedInput = actionDef.input.parse(rawPayload);
+                                    const credCtx = buildCredentialCtx(def.name);
+                                    const ctx = {
+                                        jobId: `sse-${msg_id}`,
+                                        read_ct: read_ct ?? 0,
+                                        progress: (percent, meta) => {
+                                            console.log(`[nova] progress ${percent}%`, meta ?? '');
+                                        },
+                                        heartbeat: (extendBy = 30) => _heartbeatSSE(def.queue, msg_id, extendBy),
+                                        ...credCtx,
+                                    };
+                                    const result = await actionDef.handler(parsedInput, ctx);
+                                    actionDef.output.parse(result);
+                                    await _ackSSE(def.queue, msg_id);
+                                    console.log(`[nova] ✅ ack msg_id=${msg_id}`);
+                                }
+                                catch (handlerErr) {
+                                    console.error(`[nova] ❌ handler error msg_id=${msg_id}:`, handlerErr);
+                                    await _nackSSE(def.queue, msg_id, read_ct ?? 0);
+                                }
+                            }
+                            catch (parseErr) {
+                                console.error(`[nova] Failed to parse SSE frame:`, parseErr);
+                            }
+                        }
+                        currentEvent = null;
+                        currentData = null;
+                    }
+                }
+            }
+        }
+        catch (connErr) {
+            console.error(`[nova] SSE connection error:`, connErr);
+        }
+        console.log(`[nova] Reconnecting in ${reconnectDelay}ms…`);
+        await delay(reconnectDelay);
+        reconnectDelay = Math.min(reconnectDelay * 2, 30_000);
+    }
+}
 /*──────────────── NEW: OpenAPI Spec Generation ───────────────*/
 export async function generateOpenAPISpec(def) {
     // This would use oRPC's built-in OpenAPI generation
@@ -610,6 +820,10 @@ export function runDualMode(def, opts = {}) {
         console.log(`💡 Worker running in HTTP-only mode. Set RUNTIME_SUPABASE_URL and RUNTIME_SUPABASE_SERVICE_ROLE_KEY to enable event processing`);
     }
 }
+/*──────────────── 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';
 // YAML spec parsing utility
 export { parseNovaSpec } from "./parseSpec.js";
 // Integration definition API

package/dist/integration.d.ts

@@ -203,6 +203,48 @@ export interface IntegrationFunctionDef {
  * ```
  */
 export declare function integrationFunction(cfg: IntegrationFunctionDef): IntegrationFunctionDef;
+/**
+ * A single field mapping rule: one source field → one target field,
+ * with an optional JSONata transform expression.
+ *
+ * Seeded into `integration_field_mappings` by `nova integrations push`.
+ */
+export interface SyncMappingFieldDef {
+    /** Top-level field name from the provider payload (e.g., "workEmail") */
+    source: string;
+    /**
+     * Optional dot-path for nested extraction.
+     * e.g., ["status", "status"] extracts payload.status.status
+     * When set, takes precedence over `source` for deep access.
+     */
+    sourcePath?: string[];
+    /** Normalized field name on the target Nova service schema (e.g., "work_email") */
+    target: string;
+    /**
+     * Optional JSONata expression applied after extraction.
+     * null / undefined = pass-through (no transform).
+     * @example "status = 'Active' ? 'ACTIVE' : 'INACTIVE'"
+     * @example "firstName & ' ' & lastName"
+     * @example "$lowercase(workEmail)"
+     */
+    transform?: string;
+}
+/**
+ * Declares how one integration entity maps to one Nova service schema.
+ * E.g.: `bamboohr.employee → hris.employee`
+ *
+ * Seeded into `integration_sync_pairs` by `nova integrations push`.
+ */
+export interface SyncMappingDef {
+    /** Target Nova service slug (e.g., "hris") */
+    service: string;
+    /** Target schema slug on the service side (e.g., "employee") */
+    targetSchema: string;
+    /** Direction of data flow. Defaults to "integration_to_service". */
+    direction?: 'integration_to_service' | 'service_to_integration' | 'bidirectional';
+    /** Per-field mapping rules */
+    fields: SyncMappingFieldDef[];
+}
 /**
  * Full integration definition — the single source of truth.
  *
@@ -272,6 +314,30 @@ export interface IntegrationDef {
     events: Record<string, IntegrationEventDef>;
     /** Function definitions — describe external API endpoints */
     functions: Record<string, IntegrationFunctionDef>;
+    /**
+     * Sync mapping declarations — seeded into `integration_sync_pairs` +
+     * `integration_field_mappings` by `nova integrations push`.
+     *
+     * Key = source entity slug (e.g., "employee", "time_off_request").
+     * Value = target service/schema + field-level mapping rules.
+     *
+     * @example
+     * ```ts
+     * syncMappings: {
+     *   employee: {
+     *     service: "hris",
+     *     targetSchema: "employee",
+     *     direction: "integration_to_service",
+     *     fields: [
+     *       { source: "workEmail",  target: "work_email" },
+     *       { source: "status", target: "employment_status",
+     *         transform: "status = 'Active' ? 'ACTIVE' : 'INACTIVE'" },
+     *     ],
+     *   },
+     * }
+     * ```
+     */
+    syncMappings?: Record<string, SyncMappingDef>;
 }
 export declare const IntegrationDefSchema: z.ZodObject<{
     slug: z.ZodString;
@@ -360,6 +426,21 @@ export declare const IntegrationDefSchema: z.ZodObject<{
         category: z.ZodOptional<z.ZodString>;
         capabilities: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>>;
     }, z.core.$strip>>;
+    syncMappings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        service: z.ZodString;
+        targetSchema: z.ZodString;
+        direction: z.ZodOptional<z.ZodEnum<{
+            bidirectional: "bidirectional";
+            integration_to_service: "integration_to_service";
+            service_to_integration: "service_to_integration";
+        }>>;
+        fields: z.ZodArray<z.ZodObject<{
+            source: z.ZodString;
+            sourcePath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            target: z.ZodString;
+            transform: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 /**
  * Result of validating an integration definition before build/push.

package/dist/integration.js

@@ -154,6 +154,18 @@ const IntegrationFunctionDefSchema = z.object({
     category: z.string().optional(),
     capabilities: z.array(z.union([z.string(), z.record(z.string(), z.unknown())])).optional(),
 });
+const SyncMappingFieldDefSchema = z.object({
+    source: z.string(),
+    sourcePath: z.array(z.string()).optional(),
+    target: z.string(),
+    transform: z.string().optional(),
+});
+const SyncMappingDefSchema = z.object({
+    service: z.string(),
+    targetSchema: z.string(),
+    direction: z.enum(['integration_to_service', 'service_to_integration', 'bidirectional']).optional(),
+    fields: z.array(SyncMappingFieldDefSchema),
+});
 export const IntegrationDefSchema = z.object({
     slug: z.string().regex(/^[a-z][a-z0-9_]*$/, 'Integration slug must be snake_case'),
     name: z.string(),
@@ -190,6 +202,7 @@ export const IntegrationDefSchema = z.object({
     schemas: z.record(z.string(), IntegrationSchemaDefSchema),
     events: z.record(z.string(), IntegrationEventDefSchema),
     functions: z.record(z.string(), IntegrationFunctionDefSchema),
+    syncMappings: z.record(z.string(), SyncMappingDefSchema).optional(),
 });
 /**
  * Validate an integration definition before build or push.

package/dist/integrationSpec.d.ts

@@ -90,7 +90,7 @@ export declare const IntegrationSpecSchema: z.ZodObject<{
                 streamName: z.ZodString;
                 eventTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 consumerGroup: z.ZodOptional<z.ZodString>;
-            }, z.core.$strip>]>>>;
+            }, z.core.$strip>], "type">>>;
         }, z.core.$strip>>;
         capabilities: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"webhook">;
@@ -122,7 +122,7 @@ export declare const IntegrationSpecSchema: z.ZodObject<{
             streamName: z.ZodString;
             eventTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
             consumerGroup: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>]>>>;
+        }, z.core.$strip>], "type">>>;
         schemas: z.ZodOptional<z.ZodArray<z.ZodObject<{
             slug: z.ZodString;
             name: z.ZodString;

package/dist/next.d.ts

@@ -27,7 +27,8 @@
  * }
  * ```
  */
-import type { ZodTypeAny } from 'zod';
+import type { ZodTypeAny, ZodObject } from 'zod';
+import { z } from 'zod';
 export type ParamIn = 'path' | 'query' | 'body' | 'header';
 export type ParamUiType = 'text' | 'textarea' | 'number' | 'integer' | 'boolean' | 'date' | 'datetime' | 'select' | 'multiselect' | 'password' | 'email' | 'url' | 'uuid' | 'json' | 'hidden';
 export interface ParamMeta {
@@ -49,11 +50,65 @@ export interface ParamMeta {
     order?: number;
     group?: string;
 }
+/**
+ * An event type emitted by a service endpoint.
+ * Defined inline in `novaEndpoint()` and auto-registered in the platform
+ * event_types registry when `nova services push` is run.
+ *
+ * @example
+ * ```ts
+ * events: [
+ *   {
+ *     slug: 'EMPLOYEE_UPDATED',
+ *     name: 'Employee Updated',
+ *     description: 'Fired when an employee record is updated',
+ *     category: 'hris',
+ *     entity_type: 'EMPLOYEE',
+ *     action: 'UPDATED',
+ *     priority_level: 'medium',
+ *   }
+ * ]
+ * ```
+ */
+export interface NovaEndpointEventDef {
+    /**
+     * Unique event slug in ENTITY_ACTION format (e.g. "EMPLOYEE_UPDATED").
+     * Used as the event identifier in workers and integrations.
+     * If entity_type and action are not provided, they are derived from this slug
+     * by splitting on the last underscore.
+     */
+    slug: string;
+    /** Human-readable event name (e.g. "Employee Updated") */
+    name: string;
+    /** Description of when this event fires */
+    description?: string;
+    /**
+     * Event category for grouping in Odyssey UI (e.g. "hris", "payroll").
+     * Defaults to the service slug if omitted.
+     */
+    category?: string;
+    /**
+     * Entity type portion of the slug (e.g. "EMPLOYEE").
+     * Auto-derived from slug if omitted.
+     */
+    entity_type?: string;
+    /**
+     * Action portion of the slug (e.g. "UPDATED", "CREATED", "DELETED").
+     * Auto-derived from slug if omitted.
+     */
+    action?: string;
+    /** Event priority for notification routing. Defaults to "medium". */
+    priority_level?: 'low' | 'medium' | 'high';
+    /** Whether this event should trigger a push notification. Defaults to false. */
+    triggers_notification?: boolean;
+}
 export interface NovaEndpointDef<I extends ZodTypeAny = ZodTypeAny, O extends ZodTypeAny = ZodTypeAny> {
     /** HTTP method */
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     /** REST path template. Use :param for path params. e.g. "/hris/employees/:id" */
     path: string;
+    /** Human-readable name shown in Odyssey UI endpoint list */
+    name?: string;
     /** Human-readable description shown in Odyssey UI endpoint tester */
     description?: string;
     /** Endpoint group for Odyssey UI organization */
@@ -70,6 +125,32 @@ export interface NovaEndpointDef<I extends ZodTypeAny = ZodTypeAny, O extends Zo
     requiresAuth?: boolean;
     /** Whether this endpoint returns sensitive data (SSN, DOB, etc.) */
     sensitiveFields?: boolean;
+    /**
+     * Permission slug(s) required to call this endpoint.
+     * e.g. `'hris_admin:view'` or `['hris_admin:view', 'hris_admin:edit']`
+     *
+     * `nova services push` auto-discovers all unique slugs across route files
+     * and upserts the corresponding IAM resources + permissions — no manual
+     * `iam:` section upkeep needed.
+     *
+     * Convention (HRIS example):
+     *   GET    → `'hris_admin:view'`
+     *   POST / PATCH / PUT → `'hris_admin:edit'`
+     *   DELETE → `'hris_admin:manage'`
+     */
+    requiredPermissions?: string | string[];
+    /**
+     * Event types emitted by this endpoint.
+     * Defined here and auto-registered in the platform event_types registry
+     * when `nova services push` is run. Use `nova events list` to see all
+     * registered events.
+     *
+     * @example
+     * ```ts
+     * events: [{ slug: 'EMPLOYEE_UPDATED', name: 'Employee Updated', category: 'hris' }]
+     * ```
+     */
+    events?: NovaEndpointEventDef[];
 }
 export type NovaEndpoint<I extends ZodTypeAny = ZodTypeAny, O extends ZodTypeAny = ZodTypeAny> = NovaEndpointDef<I, O> & {
     /**
@@ -103,3 +184,153 @@ export type NovaEndpoint<I extends ZodTypeAny = ZodTypeAny, O extends ZodTypeAny
  * ```
  */
 export declare function novaEndpoint<I extends ZodTypeAny, O extends ZodTypeAny>(cfg: NovaEndpointDef<I, O>): NovaEndpoint<I, O>;
+export interface CursorPayload {
+    id: string;
+    created_at: string;
+}
+/**
+ * Encode a record into an opaque base64url cursor string.
+ * The cursor encodes `id` and `created_at` for stable keyset pagination.
+ */
+export declare function encodeCursor(record: {
+    id: string;
+    created_at: string;
+}): string;
+/**
+ * Decode a cursor string back into its `id` and `created_at` fields.
+ * Throws a descriptive error if the cursor is malformed.
+ */
+export declare function parseCursor(cursor: string): CursorPayload;
+/**
+ * Standard paginated response envelope used by all Nova list endpoints.
+ *
+ * - `results`        — the page of records
+ * - `total`          — total count of ALL records (ignores active search/filters)
+ * - `filtered_total` — count after search/filters applied (equals `total` when none are active)
+ * - `next`           — opaque cursor for next page; `null` if this is the last page or offset-based
+ */
+export interface PagedResponse<T> {
+    results: T[];
+    total: number;
+    filtered_total: number;
+    next: string | null;
+}
+/**
+ * Build the unified `PagedResponse` from a DB result set.
+ *
+ * @param results       Mapped row objects for this page
+ * @param total         Total count of ALL records (pre-filter)
+ * @param filteredTotal Count after search/filters applied (pass same as `total` if no filter active)
+ * @param pageSize      The page_size / limit that was requested
+ */
+export declare function buildPageResponse<T extends {
+    id: string;
+    created_at: string;
+}>(results: T[], total: number, filteredTotal: number, pageSize: number): PagedResponse<T>;
+/**
+ * Standard input schema for cursor-based list endpoints (programmatic APIs).
+ * Spread into `novaEndpoint({ input: CursorPageInput.extend({ ... }) })` to add resource filters.
+ *
+ * @example
+ * ```ts
+ * input: CursorPageInput.extend({ employee_id: z.string().uuid().optional() })
+ * ```
+ */
+export declare const CursorPageInput: ZodObject<{
+    page_size: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+    modified_after: z.ZodOptional<z.ZodString>;
+    include_deleted: z.ZodDefault<z.ZodCoercedBoolean<unknown>>;
+}, z.core.$strip>;
+export type CursorPageInputType = z.infer<typeof CursorPageInput>;
+/**
+ * Standard input schema for offset-based list endpoints (UI-facing browsing).
+ * Matches what `ParquetDataTable` / Odyssey UI data browsers send.
+ *
+ * @example
+ * ```ts
+ * input: OffsetPageInput.extend({ status: StatusEnum.optional() })
+ * ```
+ */
+export declare const OffsetPageInput: ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    search: z.ZodOptional<z.ZodString>;
+    sort: z.ZodOptional<z.ZodString>;
+    sort_dir: z.ZodDefault<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    filters: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type OffsetPageInputType = z.infer<typeof OffsetPageInput>;
+/**
+ * Build the Zod output schema for any paginated list endpoint.
+ * Always produces `{ results, total, filtered_total, next }`.
+ *
+ * @example
+ * ```ts
+ * output: paginatedOutput(HrisEmployeeZod)
+ * ```
+ */
+export declare function paginatedOutput<T extends ZodTypeAny>(itemSchema: T): ZodObject<{
+    results: z.ZodArray<T>;
+    total: z.ZodNumber;
+    filtered_total: z.ZodNumber;
+    next: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Build Prisma `where`, `take`, and `orderBy` from a `CursorPageInput`.
+ * Handles cursor keyset pagination and `modified_after` filtering.
+ * Merge with resource-specific filters before passing to Prisma.
+ *
+ * @example
+ * ```ts
+ * const page = buildPrismaPage(input);
+ * const [data, total] = await Promise.all([
+ *   db.hrisEmployee.findMany({ where: { remoteWasDeleted: input.include_deleted, ...page.where }, take: page.take, orderBy: page.orderBy }),
+ *   db.hrisEmployee.count({   where: { remoteWasDeleted: input.include_deleted, ...page.where } }),
+ * ]);
+ * return nova.respond(buildPageResponse(data.map(mapRow), total, total, input.page_size));
+ * ```
+ */
+export declare function buildPrismaPage(input: CursorPageInputType): {
+    where: Record<string, unknown>;
+    take: number;
+    orderBy: Array<{
+        createdAt: 'desc';
+    } | {
+        id: 'desc';
+    }>;
+};
+/**
+ * Build Prisma `skip`, `take`, and `orderBy` from an `OffsetPageInput`.
+ * Handles offset pagination and sort direction.
+ * Does NOT handle `search` or `filters` — apply those to the `where` clause manually.
+ *
+ * @example
+ * ```ts
+ * const page = buildPrismaOffsetPage(input);
+ * const data = await db.example.findMany({ where, skip: page.skip, take: page.take, orderBy: page.orderBy });
+ * ```
+ */
+export declare function buildPrismaOffsetPage(input: OffsetPageInputType, defaultSort?: string): {
+    skip: number;
+    take: number;
+    orderBy: Record<string, 'asc' | 'desc'>;
+};
+/**
+ * Standard `params` metadata for cursor-based pagination fields.
+ * Spread into `novaEndpoint({ params: { ...CURSOR_PAGE_PARAMS, ...yourParams } })`.
+ */
+export declare const CURSOR_PAGE_PARAMS: Record<string, ParamMeta>;
+/**
+ * Standard `params` metadata for offset-based pagination fields.
+ * Spread into `novaEndpoint({ params: { ...OFFSET_PAGE_PARAMS, ...yourParams } })`.
+ */
+export declare const OFFSET_PAGE_PARAMS: Record<string, ParamMeta>;
+/** @deprecated Use `buildPageResponse` instead */
+export declare function buildPaginatedResponse<T extends {
+    id: string;
+    created_at: string;
+}>(data: T[], count: number | null, pageSize: number): PagedResponse<T>;