@newhomestar/sdk 0.6.7 → 0.6.9

package/dist/next.js

@@ -27,6 +27,7 @@
  * }
  * ```
  */
+import { z } from 'zod';
 // ─── Factory function ─────────────────────────────────────────────────────────
 /**
  * novaEndpoint() — define a Nova service endpoint co-located with its route.
@@ -59,9 +60,181 @@ export function novaEndpoint(cfg) {
             const body = await req.json();
             return cfg.input.parse(body);
         },
-        respond(data, status = 200) {
+        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/dist/parseSpec.d.ts

@@ -73,7 +73,7 @@ export declare const NovaSpecSchema: 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">;
@@ -105,7 +105,7 @@ export declare const NovaSpecSchema: 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>;
     build: z.ZodOptional<z.ZodObject<{
         dockerfile: z.ZodString;

package/dist/workerSchema.d.ts

@@ -83,6 +83,15 @@ export declare const WorkerDefSchema: z.ZodObject<{
             resourceIdKey: z.ZodOptional<z.ZodString>;
             policy: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
+        triggers: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            type: z.ZodLiteral<"event">;
+            events: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"schedule">;
+            cron: z.ZodString;
+            timezone: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>>;
         capabilities: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
             type: z.ZodLiteral<"webhook">;
             eventTypes: z.ZodArray<z.ZodString>;

package/dist/workerSchema.js

@@ -61,7 +61,24 @@ export const WorkerDefSchema = z.object({
             resourceIdKey: z.string().optional(),
             policy: z.string().optional(),
         }).optional(),
-        // NEW: Capabilities array for event subscriptions and external triggers
+        // NEW: Trigger-based routing (preferred over capabilities for SSE-based workers)
+        // Use triggers to declaratively map event topics and cron schedules to this action.
+        // `nova workers push` / `nova integrations push` reads these to register
+        // event_subscriptions and ensure PGMQ queues exist.
+        triggers: z.array(z.union([
+            z.object({
+                type: z.literal('event'),
+                events: z.array(z.string()), // e.g. ['employee.updated', 'employee.created']
+            }),
+            z.object({
+                type: z.literal('schedule'),
+                cron: z.string(), // standard 5-field cron e.g. '0 8 * * *'
+                timezone: z.string().optional(),
+                description: z.string().optional(),
+            }),
+        ])).optional(),
+        // LEGACY: Capabilities array — still supported for backward compatibility.
+        // New code should use `triggers` instead.
         capabilities: z.array(z.union([
             z.object({
                 type: z.literal('webhook'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newhomestar/sdk",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
   "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
   "bugs": {
@@ -23,6 +23,10 @@
     "./next": {
       "import": "./dist/next.js",
       "types": "./dist/next.d.ts"
+    },
+    "./events": {
+      "import": "./dist/events.js",
+      "types": "./dist/events.d.ts"
     }
   },
   "files": [
@@ -40,11 +44,14 @@
     "dotenv": "^16.4.3",
     "express": "^4.18.2",
     "express-oauth2-jwt-bearer": "^1.7.4",
-    "yaml": "^2.7.1",
-    "zod": "^4.0.5"
+    "yaml": "^2.7.1"
+  },
+  "peerDependencies": {
+    "zod": ">=4.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.11.17",
-    "typescript": "^5.4.4"
+    "typescript": "^5.4.4",
+    "zod": "^4.3.0"
   }
 }