@newhomestar/sdk 0.6.5 → 0.6.7

package/dist/next.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @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 } 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;
+}
+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 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;
+}
+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>;

package/dist/next.js

@@ -0,0 +1,67 @@
+/**
+ * @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 });
+ * }
+ * ```
+ */
+// ─── 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, status = 200) {
+            const validated = cfg.output.parse(data);
+            return Response.json(validated, { status });
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newhomestar/sdk",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "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": [