@newhomestar/sdk 0.6.5 → 0.6.8

package/dist/index.d.ts

@@ -235,7 +235,7 @@ 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, } from "./integration.js";
+export type { IntegrationDef, IntegrationSchemaDef, IntegrationEventDef, IntegrationFunctionDef, ValidationResult, SchemaType, ParamMeta, ParamIn, ParamUiType, SyncMappingDef, SyncMappingFieldDef, } from "./integration.js";
 export { parseIntegrationSpec, IntegrationSpecSchema } from "./integrationSpec.js";
 export type { IntegrationSpec } from "./integrationSpec.js";
 export type WebhookCapability = {

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/next.d.ts

@@ -0,0 +1,336 @@
+/**
+ * @newhomestar/sdk/next
+ *
+ * Utilities for building Nova service endpoints in Next.js App Router.
+ * Each route file exports a `nova` constant using `novaEndpoint()`.
+ *
+ * `nova services push` scans all route files for this export and
+ * auto-registers the endpoint in the platform DB (app_service_endpoints).
+ *
+ * @example
+ * ```ts
+ * // src/app/api/hris/employees/route.ts
+ * import { novaEndpoint } from '@newhomestar/sdk/next';
+ * import { z } from 'zod';
+ *
+ * export const nova = novaEndpoint({
+ *   method: 'GET',
+ *   path: '/hris/employees',
+ *   category: 'employees',
+ *   input: z.object({ page_size: z.coerce.number().default(25) }),
+ *   output: z.object({ results: z.array(z.any()), next: z.string().nullable() }),
+ * });
+ *
+ * export async function GET(req: Request) {
+ *   const input = nova.parseQuery(req);
+ *   return nova.respond({ results: [], next: null });
+ * }
+ * ```
+ */
+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 {
+    in: ParamIn;
+    uiType?: ParamUiType;
+    label?: string;
+    description?: string;
+    placeholder?: string;
+    required?: boolean;
+    defaultValue?: unknown;
+    options?: Array<{
+        label: string;
+        value: string | number | boolean;
+    }>;
+    min?: number;
+    max?: number;
+    step?: number;
+    pattern?: string;
+    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 */
+    category?: string;
+    /** Reference to a service schema slug for the response */
+    responseSchema?: string;
+    /** Zod schema for query/path params — converted to JSON Schema on push */
+    input: I;
+    /** Zod schema for the response body — converted to JSON Schema on push */
+    output: O;
+    /** Per-field parameter metadata */
+    params?: Record<string, ParamMeta>;
+    /** Whether this endpoint requires a valid JWT (default: true) */
+    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> & {
+    /**
+     * Parse and validate URL query string params against the input schema.
+     * Uses z.coerce for string→number/boolean conversion automatically.
+     */
+    parseQuery(req: Request): ReturnType<I['parse']>;
+    /**
+     * Parse and validate JSON request body against the input schema.
+     */
+    parseBody(req: Request): Promise<ReturnType<I['parse']>>;
+    /**
+     * Validate output data and serialize to a Response.
+     */
+    respond(data: ReturnType<O['parse']>, status?: number): Response;
+};
+/**
+ * novaEndpoint() — define a Nova service endpoint co-located with its route.
+ *
+ * Export the result as `nova` and `nova services push` will auto-discover
+ * and register this endpoint in the platform DB.
+ *
+ * @example
+ * ```ts
+ * export const nova = novaEndpoint({
+ *   method: 'GET',
+ *   path: '/hris/employees',
+ *   input: z.object({ page_size: z.coerce.number().default(25) }),
+ *   output: z.object({ results: z.array(EmployeeZod), next: z.string().nullable() }),
+ * });
+ * ```
+ */
+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>;

package/dist/next.js

@@ -0,0 +1,240 @@
+/**
+ * @newhomestar/sdk/next
+ *
+ * Utilities for building Nova service endpoints in Next.js App Router.
+ * Each route file exports a `nova` constant using `novaEndpoint()`.
+ *
+ * `nova services push` scans all route files for this export and
+ * auto-registers the endpoint in the platform DB (app_service_endpoints).
+ *
+ * @example
+ * ```ts
+ * // src/app/api/hris/employees/route.ts
+ * import { novaEndpoint } from '@newhomestar/sdk/next';
+ * import { z } from 'zod';
+ *
+ * export const nova = novaEndpoint({
+ *   method: 'GET',
+ *   path: '/hris/employees',
+ *   category: 'employees',
+ *   input: z.object({ page_size: z.coerce.number().default(25) }),
+ *   output: z.object({ results: z.array(z.any()), next: z.string().nullable() }),
+ * });
+ *
+ * export async function GET(req: Request) {
+ *   const input = nova.parseQuery(req);
+ *   return nova.respond({ results: [], next: null });
+ * }
+ * ```
+ */
+import { z } from 'zod';
+// ─── Factory function ─────────────────────────────────────────────────────────
+/**
+ * novaEndpoint() — define a Nova service endpoint co-located with its route.
+ *
+ * Export the result as `nova` and `nova services push` will auto-discover
+ * and register this endpoint in the platform DB.
+ *
+ * @example
+ * ```ts
+ * export const nova = novaEndpoint({
+ *   method: 'GET',
+ *   path: '/hris/employees',
+ *   input: z.object({ page_size: z.coerce.number().default(25) }),
+ *   output: z.object({ results: z.array(EmployeeZod), next: z.string().nullable() }),
+ * });
+ * ```
+ */
+export function novaEndpoint(cfg) {
+    return {
+        ...cfg,
+        parseQuery(req) {
+            const url = new URL(req.url);
+            const raw = {};
+            url.searchParams.forEach((value, key) => {
+                raw[key] = value;
+            });
+            return cfg.input.parse(raw);
+        },
+        async parseBody(req) {
+            const body = await req.json();
+            return cfg.input.parse(body);
+        },
+        respond(data, init) {
+            const status = typeof init === 'number' ? init : (init?.status ?? 200);
+            const validated = cfg.output.parse(data);
+            return Response.json(validated, { status });
+        },
+    };
+}
+/**
+ * Encode a record into an opaque base64url cursor string.
+ * The cursor encodes `id` and `created_at` for stable keyset pagination.
+ */
+export function encodeCursor(record) {
+    const payload = { id: record.id, created_at: record.created_at };
+    return Buffer.from(JSON.stringify(payload)).toString('base64url');
+}
+/**
+ * Decode a cursor string back into its `id` and `created_at` fields.
+ * Throws a descriptive error if the cursor is malformed.
+ */
+export function parseCursor(cursor) {
+    try {
+        const json = Buffer.from(cursor, 'base64url').toString('utf-8');
+        const parsed = JSON.parse(json);
+        if (!parsed.id || !parsed.created_at)
+            throw new Error('Missing required cursor fields');
+        return parsed;
+    }
+    catch {
+        throw new Error(`Invalid cursor: "${cursor}". Cursors must be generated by encodeCursor().`);
+    }
+}
+/**
+ * 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 function buildPageResponse(results, total, filteredTotal, pageSize) {
+    return {
+        results,
+        total,
+        filtered_total: filteredTotal,
+        next: results.length === pageSize ? encodeCursor(results[results.length - 1]) : null,
+    };
+}
+// ─── Zod schemas ─────────────────────────────────────────────────────────────
+/**
+ * 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 const CursorPageInput = z.object({
+    page_size: z.coerce.number().min(1).max(100).default(25),
+    cursor: z.string().optional(),
+    modified_after: z.string().datetime().optional(),
+    include_deleted: z.coerce.boolean().default(false),
+});
+/**
+ * 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 const OffsetPageInput = z.object({
+    limit: z.coerce.number().min(1).max(500).default(20),
+    offset: z.coerce.number().min(0).default(0),
+    search: z.string().optional(),
+    sort: z.string().optional(),
+    sort_dir: z.enum(['asc', 'desc']).default('desc'),
+    filters: z.string().optional(), // JSON-encoded FilterCondition[]
+});
+/**
+ * Build the Zod output schema for any paginated list endpoint.
+ * Always produces `{ results, total, filtered_total, next }`.
+ *
+ * @example
+ * ```ts
+ * output: paginatedOutput(HrisEmployeeZod)
+ * ```
+ */
+export function paginatedOutput(itemSchema) {
+    return z.object({
+        results: z.array(itemSchema),
+        total: z.number().describe('Total record count (unfiltered)'),
+        filtered_total: z.number().describe('Record count after active search/filters'),
+        next: z.string().nullable().describe('Cursor for next page; null if last page'),
+    });
+}
+// ─── Prisma helpers ───────────────────────────────────────────────────────────
+/**
+ * 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 function buildPrismaPage(input) {
+    const where = {};
+    if (input.modified_after) {
+        where.modifiedAt = { gte: new Date(input.modified_after) };
+    }
+    if (input.cursor) {
+        const { id, created_at } = parseCursor(input.cursor);
+        where.OR = [
+            { createdAt: { lt: new Date(created_at) } },
+            { createdAt: new Date(created_at), id: { lt: id } },
+        ];
+    }
+    return {
+        where,
+        take: input.page_size,
+        orderBy: [{ 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 function buildPrismaOffsetPage(input, defaultSort = 'createdAt') {
+    const col = input.sort ?? defaultSort;
+    return {
+        skip: input.offset,
+        take: input.limit,
+        orderBy: { [col]: input.sort_dir },
+    };
+}
+// ─── Standard param metadata ──────────────────────────────────────────────────
+/**
+ * Standard `params` metadata for cursor-based pagination fields.
+ * Spread into `novaEndpoint({ params: { ...CURSOR_PAGE_PARAMS, ...yourParams } })`.
+ */
+export const CURSOR_PAGE_PARAMS = {
+    page_size: { in: 'query', uiType: 'number', label: 'Page Size', description: 'Records per page (1–100, default 25)' },
+    cursor: { in: 'query', uiType: 'text', label: 'Cursor', description: 'Opaque pagination cursor from previous response' },
+    modified_after: { in: 'query', uiType: 'datetime', label: 'Modified After', description: 'Return records modified after this ISO 8601 timestamp' },
+    include_deleted: { in: 'query', uiType: 'boolean', label: 'Include Deleted', description: 'Include soft-deleted records (default false)' },
+};
+/**
+ * Standard `params` metadata for offset-based pagination fields.
+ * Spread into `novaEndpoint({ params: { ...OFFSET_PAGE_PARAMS, ...yourParams } })`.
+ */
+export const OFFSET_PAGE_PARAMS = {
+    limit: { in: 'query', uiType: 'number', label: 'Limit', description: 'Records per page (1–500, default 20)' },
+    offset: { in: 'query', uiType: 'number', label: 'Offset', description: 'Number of records to skip' },
+    search: { in: 'query', uiType: 'text', label: 'Search', description: 'Free-text search across indexed fields' },
+    sort: { in: 'query', uiType: 'text', label: 'Sort By', description: 'Column name to sort by' },
+    sort_dir: { in: 'query', uiType: 'select', label: 'Sort Dir', description: 'asc or desc', options: [{ label: 'Ascending', value: 'asc' }, { label: 'Descending', value: 'desc' }] },
+    filters: { in: 'query', uiType: 'json', label: 'Filters', description: 'JSON array of FilterCondition objects' },
+};
+// ─── Legacy re-exports (backward compat) ─────────────────────────────────────
+/** @deprecated Use `buildPageResponse` instead */
+export function buildPaginatedResponse(data, count, pageSize) {
+    return buildPageResponse(data, count ?? 0, count ?? 0, pageSize);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newhomestar/sdk",
-  "version": "0.6.5",
+  "version": "0.6.8",
   "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
   "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
   "bugs": {
@@ -19,6 +19,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./next": {
+      "import": "./dist/next.js",
+      "types": "./dist/next.d.ts"
     }
   },
   "files": [