@newhomestar/sdk 0.7.15 → 0.7.17

package/dist/index.d.ts

@@ -85,6 +85,45 @@ export interface ActionDef<I extends ZodTypeAny, O extends ZodTypeAny> {
         eventTypes?: string[];
         consumerGroup?: string;
     }>;
+    /**
+     * Sync capability metadata — declares this action as a data sync endpoint.
+     * Read by `nova integrations build` to include sync config in nova-integration.yaml.
+     * Surfaced in the Odyssey UI DataSyncTab for each integration.
+     *
+     * @example
+     * ```ts
+     * sync: {
+     *   entityType: "issue",
+     *   direction: "to_nova",
+     *   label: "Jira Issues",
+     *   description: "Import all Jira issues into Nova",
+     * }
+     * ```
+     */
+    sync?: {
+        /** Entity type identifier (e.g., "issue", "contact", "employee") */
+        entityType: string;
+        /** Direction of sync: to_nova = import from provider; from_nova = export to provider */
+        direction: 'to_nova' | 'from_nova' | 'bidirectional';
+        /** Human-readable label shown in the UI (e.g., "Jira Issues") */
+        label: string;
+        /** Optional description shown below the label in the DataSyncTab */
+        description?: string;
+    };
+    /**
+     * Trigger-based routing declarations.
+     * Used by the SSE worker mode to route incoming messages to this action's handler.
+     * Also read by `nova integrations build` to register event_subscriptions on push.
+     */
+    triggers?: Array<{
+        type: 'event';
+        events: string[];
+    } | {
+        type: 'schedule';
+        cron: string;
+        timezone?: string;
+        description?: string;
+    }>;
 }
 /** Validated JWT claims from express-oauth2-jwt-bearer */
 export interface JWTPayload {
@@ -208,6 +247,30 @@ export declare function action<I extends ZodTypeAny, O extends ZodTypeAny>(cfg:
         eventTypes?: string[];
         consumerGroup?: string;
     }>;
+    /**
+     * Sync capability metadata — declares this action as a data sync endpoint.
+     * Surfaced in the Odyssey UI DataSyncTab and included in nova-integration.yaml
+     * by `nova integrations build`.
+     */
+    sync?: {
+        entityType: string;
+        direction: 'to_nova' | 'from_nova' | 'bidirectional';
+        label: string;
+        description?: string;
+    };
+    /**
+     * Trigger-based routing declarations for event/schedule triggers.
+     * Used by the SSE worker and CLI build pipeline.
+     */
+    triggers?: Array<{
+        type: 'event';
+        events: string[];
+    } | {
+        type: 'schedule';
+        cron: string;
+        timezone?: string;
+        description?: string;
+    }>;
     handler: (input: z.infer<I>, ctx: ActionCtx) => Promise<z.infer<O>>;
 }): ActionDef<I, O>;
 import type { NovaSpec } from './parseSpec.js';

package/dist/index.js

@@ -767,7 +767,10 @@ export function runHttpServer(def, opts = {}) {
                         rawInput[key] = val === 'true' || val === '1';
                     }
                     // Auto-detect from Zod schema shape if no explicit uiType
-                    else if (!uiType && act.input?._def?.shape) {
+                    // Guard: _def.shape must be a function (Zod v3 thunk) before calling it.
+                    // Some Zod internals expose _def.shape as a plain object; calling a non-function
+                    // throws "act.input._def.shape is not a function" at runtime.
+                    else if (!uiType && typeof act.input?._def?.shape === 'function') {
                         const fieldDef = act.input._def.shape()?.[key];
                         const innerType = fieldDef?._def?.innerType?._def?.typeName ?? fieldDef?._def?.typeName;
                         if (innerType === 'ZodNumber') {

package/dist/next.d.ts

@@ -102,6 +102,50 @@ export interface NovaEndpointEventDef {
     /** Whether this event should trigger a push notification. Defaults to false. */
     triggers_notification?: boolean;
 }
+/**
+ * Human-readable metadata for a single permission slug.
+ * Defined inline in `novaEndpoint()` alongside `requiredPermissions` and
+ * auto-embedded into the IAM permission registry when `nova services push` runs.
+ *
+ * This drives hierarchical/grouped rendering in the Odyssey UI permission
+ * assignment views — permissions in the same `group` are displayed together
+ * under a shared parent label with friendly titles and descriptions.
+ *
+ * @example
+ * ```ts
+ * requiredPermissions: 'iam_admin:roles_view',
+ * permissionMeta: {
+ *   slug: 'iam_admin:roles_view',
+ *   title: 'View Roles',
+ *   description: 'Read access to role definitions and listings',
+ *   group: 'Roles',
+ * },
+ * ```
+ */
+export interface PermissionMeta {
+    /**
+     * The exact permission slug this metadata describes.
+     * Must match a value in `requiredPermissions`.
+     * e.g. `'iam_admin:roles_view'`
+     */
+    slug: string;
+    /**
+     * Human-friendly label shown in the Odyssey UI.
+     * e.g. `'View Roles'`
+     */
+    title: string;
+    /**
+     * Optional description of what this permission grants.
+     * e.g. `'Read access to role definitions and listings'`
+     */
+    description?: string;
+    /**
+     * Parent group label used for hierarchical rendering in the UI.
+     * All permissions with the same `group` value are displayed together.
+     * e.g. `'Roles'`
+     */
+    group: string;
+}
 export interface NovaEndpointDef<I extends ZodTypeAny = ZodTypeAny, O extends ZodTypeAny = ZodTypeAny> {
     /** HTTP method */
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
@@ -139,6 +183,29 @@ export interface NovaEndpointDef<I extends ZodTypeAny = ZodTypeAny, O extends Zo
      *   DELETE → `'hris_admin:manage'`
      */
     requiredPermissions?: string | string[];
+    /**
+     * Human-readable metadata for the permission slug(s) in `requiredPermissions`.
+     * Used to generate hierarchical, grouped permission views in the Odyssey UI.
+     *
+     * Provide one entry per unique permission slug used on this endpoint.
+     * Metadata is deduplicated by slug — defining the same slug on multiple
+     * endpoints is fine; the first definition wins.
+     *
+     * `nova services push` reads this field and embeds title, description,
+     * and group into the IAM permission registry automatically.
+     *
+     * @example
+     * ```ts
+     * requiredPermissions: 'iam_admin:roles_view',
+     * permissionMeta: {
+     *   slug: 'iam_admin:roles_view',
+     *   title: 'View Roles',
+     *   description: 'Read access to role definitions and listings',
+     *   group: 'Roles',
+     * },
+     * ```
+     */
+    permissionMeta?: PermissionMeta | PermissionMeta[];
     /**
      * Event types emitted by this endpoint.
      * Defined here and auto-registered in the platform event_types registry
@@ -303,23 +370,9 @@ export declare function buildPrismaPage(input: CursorPageInputType): {
         id: 'desc';
     }>;
 };
-/**
- * Convert a snake_case string to camelCase.
- * Used internally to normalise sort column names from API query params
- * (snake_case) to Prisma model field names (camelCase).
- *
- * @example
- * ```ts
- * snakeToCamel('modified_at') // → 'modifiedAt'
- * snakeToCamel('createdAt')   // → 'createdAt' (no-op)
- * ```
- */
-export declare function snakeToCamel(s: string): string;
 /**
  * Build Prisma `skip`, `take`, and `orderBy` from an `OffsetPageInput`.
  * Handles offset pagination and sort direction.
- * Sort column names are automatically converted from snake_case (API convention)
- * to camelCase (Prisma convention) via `snakeToCamel()`.
  * Does NOT handle `search` or `filters` — apply those to the `where` clause manually.
  *
  * @example
@@ -442,6 +495,51 @@ export declare const CURSOR_PAGE_PARAMS: Record<string, ParamMeta>;
  * Spread into `novaEndpoint({ params: { ...OFFSET_PAGE_PARAMS, ...yourParams } })`.
  */
 export declare const OFFSET_PAGE_PARAMS: Record<string, ParamMeta>;
+/**
+ * Metadata for a Nova service — passed to `defineService()`.
+ */
+export interface ServiceDef {
+    /** Unique service slug (snake_case). e.g. "nova_ticketing_service" */
+    slug: string;
+    /** Human-readable service name */
+    name: string;
+    /** Short service description */
+    description?: string;
+    /** Service category for Odyssey UI grouping (e.g. "support", "hris") */
+    category?: string;
+    /** Semver version string — defaults to "1.0.0" */
+    version?: string;
+}
+/**
+ * defineService() — declare Nova service identity and auto-set NOVA_SERVICE_SLUG.
+ *
+ * Call this once in a shared module (e.g. `src/lib/service.ts`) and import it
+ * early in your app entrypoint. At import time it sets `process.env.NOVA_SERVICE_SLUG`
+ * so `withServiceEventOutbox()` can stamp `source_service` on all outbound events.
+ *
+ * `nova services push` also detects this export (the `__novaService` marker) to
+ * cross-validate the slug against `nova-service.yaml` during the build scan.
+ *
+ * **Usage:**
+ * ```ts
+ * // src/lib/service.ts
+ * import { defineService } from '@newhomestar/sdk/next';
+ *
+ * export const service = defineService({
+ *   slug: 'nova_ticketing_service',
+ *   name: 'Nova Ticketing Service',
+ *   category: 'support',
+ * });
+ * ```
+ *
+ * Then import it early — e.g. in `src/instrumentation.ts` (Next.js) or your app entry:
+ * ```ts
+ * import '@/lib/service'; // ensures NOVA_SERVICE_SLUG is set before any route runs
+ * ```
+ */
+export declare function defineService<T extends ServiceDef>(def: T): T & {
+    readonly __novaService: true;
+};
 /** @deprecated Use `buildPageResponse` instead */
 export declare function buildPaginatedResponse<T extends {
     id: string;

package/dist/next.js

@@ -191,25 +191,9 @@ export function buildPrismaPage(input) {
         orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],
     };
 }
-/**
- * Convert a snake_case string to camelCase.
- * Used internally to normalise sort column names from API query params
- * (snake_case) to Prisma model field names (camelCase).
- *
- * @example
- * ```ts
- * snakeToCamel('modified_at') // → 'modifiedAt'
- * snakeToCamel('createdAt')   // → 'createdAt' (no-op)
- * ```
- */
-export function snakeToCamel(s) {
-    return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
-}
 /**
  * Build Prisma `skip`, `take`, and `orderBy` from an `OffsetPageInput`.
  * Handles offset pagination and sort direction.
- * Sort column names are automatically converted from snake_case (API convention)
- * to camelCase (Prisma convention) via `snakeToCamel()`.
  * Does NOT handle `search` or `filters` — apply those to the `where` clause manually.
  *
  * @example
@@ -219,7 +203,7 @@ export function snakeToCamel(s) {
  * ```
  */
 export function buildPrismaOffsetPage(input, defaultSort = 'createdAt') {
-    const col = snakeToCamel(input.sort ?? defaultSort);
+    const col = input.sort ?? defaultSort;
     return {
         skip: input.offset,
         take: input.limit,
@@ -339,6 +323,42 @@ export const OFFSET_PAGE_PARAMS = {
     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' },
 };
+/**
+ * defineService() — declare Nova service identity and auto-set NOVA_SERVICE_SLUG.
+ *
+ * Call this once in a shared module (e.g. `src/lib/service.ts`) and import it
+ * early in your app entrypoint. At import time it sets `process.env.NOVA_SERVICE_SLUG`
+ * so `withServiceEventOutbox()` can stamp `source_service` on all outbound events.
+ *
+ * `nova services push` also detects this export (the `__novaService` marker) to
+ * cross-validate the slug against `nova-service.yaml` during the build scan.
+ *
+ * **Usage:**
+ * ```ts
+ * // src/lib/service.ts
+ * import { defineService } from '@newhomestar/sdk/next';
+ *
+ * export const service = defineService({
+ *   slug: 'nova_ticketing_service',
+ *   name: 'Nova Ticketing Service',
+ *   category: 'support',
+ * });
+ * ```
+ *
+ * Then import it early — e.g. in `src/instrumentation.ts` (Next.js) or your app entry:
+ * ```ts
+ * import '@/lib/service'; // ensures NOVA_SERVICE_SLUG is set before any route runs
+ * ```
+ */
+export function defineService(def) {
+    // Set NOVA_SERVICE_SLUG at import time so withServiceEventOutbox() always has
+    // access to source_service without requiring a separate env var. Only sets it
+    // if not already set — explicit env var overrides (e.g. in tests) still work.
+    if (!process.env.NOVA_SERVICE_SLUG) {
+        process.env.NOVA_SERVICE_SLUG = def.slug;
+    }
+    return { ...def, __novaService: true };
+}
 // ─── Legacy re-exports (backward compat) ─────────────────────────────────────
 /** @deprecated Use `buildPageResponse` instead */
 export function buildPaginatedResponse(data, count, pageSize) {

package/package.json

@@ -1,58 +1,58 @@
-{
-  "name": "@newhomestar/sdk",
-  "version": "0.7.15",
-  "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
-  "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
-  "bugs": {
-    "url": "https://github.com/newhomestar/nova-node-sdk/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/newhomestar/nova-node-sdk.git"
-  },
-  "license": "ISC",
-  "author": "Christian Gomez",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./next": {
-      "import": "./dist/next.js",
-      "types": "./dist/next.d.ts"
-    },
-    "./events": {
-      "import": "./dist/events.js",
-      "types": "./dist/events.d.ts"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc"
-  },
-  "dependencies": {
-    "@openfga/sdk": "^0.9.0",
-    "@orpc/openapi": "1.7.4",
-    "@orpc/server": "1.7.4",
-    "@supabase/supabase-js": "^2.39.0",
-    "body-parser": "^1.20.2",
-    "dotenv": "^16.4.3",
-    "express": "^4.18.2",
-    "express-oauth2-jwt-bearer": "^1.7.4",
-    "undici": "^7.24.4",
-    "yaml": "^2.7.1"
-  },
-  "peerDependencies": {
-    "zod": ">=4.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.11.17",
-    "typescript": "^5.4.4",
-    "zod": "^4.3.0"
-  }
-}
+{
+  "name": "@newhomestar/sdk",
+  "version": "0.7.17",
+  "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
+  "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/newhomestar/nova-node-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/newhomestar/nova-node-sdk.git"
+  },
+  "license": "ISC",
+  "author": "Christian Gomez",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./next": {
+      "import": "./dist/next.js",
+      "types": "./dist/next.d.ts"
+    },
+    "./events": {
+      "import": "./dist/events.js",
+      "types": "./dist/events.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@openfga/sdk": "^0.9.0",
+    "@orpc/openapi": "1.7.4",
+    "@orpc/server": "1.7.4",
+    "@supabase/supabase-js": "^2.39.0",
+    "body-parser": "^1.20.2",
+    "dotenv": "^16.4.3",
+    "express": "^4.18.2",
+    "express-oauth2-jwt-bearer": "^1.7.4",
+    "undici": "^7.24.4",
+    "yaml": "^2.7.1"
+  },
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.17",
+    "typescript": "^5.4.4",
+    "zod": "^4.3.0"
+  }
+}