@newhomestar/sdk 0.5.2 → 0.6.7

package/dist/integrationSpec.js

@@ -0,0 +1,186 @@
+import { parse as parseYAML } from "yaml";
+import { z } from "zod";
+/**
+ * IntegrationSpec — the shape of nova-integration.yaml
+ * Generated by `nova integrations build` from a defineIntegration() call.
+ */
+const IntegrationSchemaSpecSchema = z.object({
+    slug: z.string(),
+    name: z.string(),
+    type: z.enum(['request', 'response', 'entity', 'webhook_payload', 'configuration']),
+    description: z.string().optional(),
+    schema: z.union([z.string(), z.record(z.string(), z.unknown())]),
+    version: z.string().optional(),
+    fieldCount: z.number().optional(),
+});
+const IntegrationEventSpecSchema = z.object({
+    slug: z.string(),
+    name: z.string(),
+    direction: z.enum(['inbound', 'outbound', 'bidirectional']),
+    description: z.string().optional(),
+    category: z.string().optional(),
+    severity: z.enum(['info', 'warning', 'error', 'critical']).optional(),
+    payloadSchema: z.string().optional(),
+});
+const IntegrationFunctionSpecSchema = z.object({
+    slug: z.string(),
+    name: z.string(),
+    httpMethod: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
+    endpointPath: z.string(),
+    description: z.string().optional(),
+    requestSchema: z.string().optional(),
+    responseSchema: z.string().optional(),
+    requiredScopes: z.array(z.string()).optional(),
+    category: z.string().optional(),
+});
+// Capability schemas (shared with worker spec)
+const WebhookCapabilitySchema = z.object({
+    type: z.literal('webhook'),
+    eventTypes: z.array(z.string()),
+    source: z.string(),
+    endpoint: z.string().optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+    authentication: z.object({
+        type: z.enum(['bearer', 'basic', 'api_key', 'signature']),
+        config: z.record(z.string(), z.unknown()).optional(),
+    }).optional(),
+});
+const ScheduledCapabilitySchema = z.object({
+    type: z.literal('scheduled'),
+    cron: z.string(),
+    timezone: z.string().optional(),
+    description: z.string().optional(),
+});
+const QueueCapabilitySchema = z.object({
+    type: z.literal('queue'),
+    topics: z.array(z.string()),
+    queueName: z.string().optional(),
+    consumerGroup: z.string().optional(),
+});
+const StreamCapabilitySchema = z.object({
+    type: z.literal('stream'),
+    streamName: z.string(),
+    eventTypes: z.array(z.string()).optional(),
+    consumerGroup: z.string().optional(),
+});
+const CapabilitySchema = z.discriminatedUnion('type', [
+    WebhookCapabilitySchema,
+    ScheduledCapabilitySchema,
+    QueueCapabilitySchema,
+    StreamCapabilitySchema,
+]);
+export const IntegrationSpecSchema = z.object({
+    apiVersion: z.string(),
+    kind: z.literal('Integration'),
+    metadata: z.object({
+        slug: z.string(),
+        name: z.string(),
+        displayName: z.string().optional(),
+        description: z.string().optional(),
+        category: z.string().optional(),
+        icon: z.string().optional(),
+        tags: z.array(z.string()).optional(),
+        logoUrl: z.string().optional(),
+        color: z.string().optional(),
+    }),
+    spec: z.object({
+        type: z.enum(['oidc', 'oauth2', 'api_key']),
+        endpoints: z.object({
+            authorization: z.string().optional(),
+            token: z.string().optional(),
+            userinfo: z.string().optional(),
+            revocation: z.string().optional(),
+            jwks: z.string().optional(),
+            baseUrl: z.string().optional(),
+        }).optional(),
+        scopes: z.array(z.string()).optional(),
+        runtime: z.object({
+            type: z.string(),
+            image: z.string(),
+            queue: z.string(),
+            port: z.number().optional(),
+            command: z.array(z.string()),
+            resources: z.object({
+                cpu: z.string(),
+                memory: z.string(),
+            }),
+            envSpec: z.array(z.object({
+                name: z.string(),
+                value: z.string().optional(),
+                secret: z.boolean().optional(),
+                default: z.string().optional(),
+            })).optional(),
+        }),
+        actions: z.array(z.object({
+            name: z.string(),
+            displayName: z.string().optional(),
+            description: z.string().optional(),
+            async: z.boolean().optional(),
+            input: z.unknown().optional(),
+            output: z.unknown().optional(),
+            schema: z.object({
+                input: z.string(),
+                output: z.string(),
+            }).optional(),
+            fga: z.object({
+                resourceType: z.string(),
+                relation: z.string(),
+            }).optional(),
+            capabilities: z.array(CapabilitySchema).optional(),
+        })),
+        capabilities: z.array(CapabilitySchema).optional(),
+        // Integration-specific config sections
+        schemas: z.array(IntegrationSchemaSpecSchema).optional(),
+        events: z.array(IntegrationEventSpecSchema).optional(),
+        functions: z.array(IntegrationFunctionSpecSchema).optional(),
+    }),
+    build: z.object({
+        dockerfile: z.string(),
+        context: z.string(),
+    }).optional(),
+    ui: z.object({
+        category: z.string().optional(),
+        color: z.string().optional(),
+    }).optional(),
+    fga: z.object({
+        types: z.array(z.object({
+            name: z.string(),
+            relations: z.record(z.string(), z.union([
+                z.array(z.string()),
+                z.object({
+                    computedUserset: z.object({
+                        object: z.string(),
+                        relation: z.string(),
+                    }),
+                }),
+            ])),
+        })),
+    }).optional(),
+});
+/**
+ * Parse nova-integration.yaml content and validate against the IntegrationSpec schema.
+ * @param yamlContent String contents of a nova-integration.yaml specification
+ * @returns Parsed IntegrationSpec object
+ * @throws Error with validation details if parsing or validation fail
+ */
+export function parseIntegrationSpec(yamlContent) {
+    let parsed;
+    try {
+        parsed = parseYAML(yamlContent);
+    }
+    catch (e) {
+        throw new Error(`Failed to parse YAML content: ${e.message}`);
+    }
+    try {
+        return IntegrationSpecSchema.parse(parsed);
+    }
+    catch (e) {
+        if (e instanceof z.ZodError) {
+            const details = e.issues
+                .map((issue) => `Path '${issue.path.join(".")}': ${issue.message}`)
+                .join("; ");
+            throw new Error(`nova-integration.yaml validation error(s): ${details}`);
+        }
+        throw e;
+    }
+}

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

@@ -29,11 +29,54 @@ export declare const WorkerDefSchema: z.ZodObject<{
         method: z.ZodOptional<z.ZodEnum<{
             GET: "GET";
             POST: "POST";
-            PUT: "PUT";
-            DELETE: "DELETE";
             PATCH: "PATCH";
+            DELETE: "DELETE";
+            PUT: "PUT";
         }>>;
         path: z.ZodOptional<z.ZodString>;
+        scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        category: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            in: z.ZodEnum<{
+                body: "body";
+                path: "path";
+                query: "query";
+                header: "header";
+            }>;
+            uiType: z.ZodOptional<z.ZodEnum<{
+                number: "number";
+                boolean: "boolean";
+                date: "date";
+                text: "text";
+                uuid: "uuid";
+                json: "json";
+                textarea: "textarea";
+                integer: "integer";
+                datetime: "datetime";
+                select: "select";
+                multiselect: "multiselect";
+                password: "password";
+                email: "email";
+                url: "url";
+                hidden: "hidden";
+            }>>;
+            label: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            placeholder: z.ZodOptional<z.ZodString>;
+            required: z.ZodOptional<z.ZodBoolean>;
+            defaultValue: z.ZodOptional<z.ZodAny>;
+            options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+            }, z.core.$strip>>>;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            step: z.ZodOptional<z.ZodNumber>;
+            pattern: z.ZodOptional<z.ZodString>;
+            order: z.ZodOptional<z.ZodNumber>;
+            group: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
         fga: z.ZodOptional<z.ZodObject<{
             resourceType: z.ZodString;
             relation: z.ZodString;

package/dist/workerSchema.js

@@ -26,6 +26,34 @@ export const WorkerDefSchema = z.object({
         // NEW: HTTP routing support for oRPC
         method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']).optional(),
         path: z.string().optional(),
+        // Integration function metadata
+        scopes: z.array(z.string()).optional(),
+        category: z.string().optional(),
+        description: z.string().optional(),
+        // Per-field parameter metadata (path/query/body/header + UI type hints)
+        params: z.record(z.string(), z.object({
+            in: z.enum(['path', 'query', 'body', 'header']),
+            uiType: z.enum([
+                'text', 'textarea', 'number', 'integer', 'boolean',
+                'date', 'datetime', 'select', 'multiselect',
+                'password', 'email', 'url', 'uuid', 'json', 'hidden',
+            ]).optional(),
+            label: z.string().optional(),
+            description: z.string().optional(),
+            placeholder: z.string().optional(),
+            required: z.boolean().optional(),
+            defaultValue: z.any().optional(),
+            options: z.array(z.object({
+                label: z.string(),
+                value: z.union([z.string(), z.number(), z.boolean()]),
+            })).optional(),
+            min: z.number().optional(),
+            max: z.number().optional(),
+            step: z.number().optional(),
+            pattern: z.string().optional(),
+            order: z.number().optional(),
+            group: z.string().optional(),
+        })).optional(),
         // Optional per-action OpenFGA hints: resource type, relation, ID key, and optional policy caveat
         fga: z.object({
             resourceType: z.string(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newhomestar/sdk",
-  "version": "0.5.2",
+  "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": [
@@ -35,6 +39,7 @@
     "body-parser": "^1.20.2",
     "dotenv": "^16.4.3",
     "express": "^4.18.2",
+    "express-oauth2-jwt-bearer": "^1.7.4",
     "yaml": "^2.7.1",
     "zod": "^4.0.5"
   },