@newhomestar/sdk 0.7.16 → 0.7.18

package/dist/events.d.ts

@@ -1,7 +1,15 @@
 /** Full request body for POST /events/queue */
 export interface QueueEventPayload {
-    entity_type: string;
-    action: string;
+    /**
+     * Fully-qualified event slug — preferred way to identify the event.
+     * e.g. "nova_ticketing_service.ticket_created"
+     * When provided, entity_type and action are not required.
+     */
+    event_slug?: string;
+    /** Legacy: entity category. Use event_slug instead. */
+    entity_type?: string;
+    /** Legacy: event action. Use event_slug instead. */
+    action?: string;
     /** Auto-stamped from NOVA_SERVICE_SLUG if not provided */
     source_service?: string;
     /** ISO 8601 — when the event actually happened (defaults to now()) */

package/dist/events.js

@@ -185,30 +185,10 @@ export async function withServiceEventOutbox(db, reqOrCallback, maybeCallback) {
         const callbackResult = await callback(tx, emit);
         // Write one outbox row per staged emit
         for (const staged of stagedEmits) {
-            // ── Derive entity_type + action from topic string ──────────────────
-            // Supports dot notation   ("employee.created"  → entity_type=employee, action=created)
-            //           dotted path   ("hris.employee.created" → entity_type=hris.employee, action=created)
-            //           UPPER_SNAKE   ("EMPLOYEE_CREATED"  → entity_type=employee, action=created)
-            //           bare string   ("employee"          → entity_type=employee, action=event)
-            let entity_type;
-            let action;
-            if (staged.topic.includes('.')) {
-                const lastDot = staged.topic.lastIndexOf('.');
-                entity_type = staged.topic.slice(0, lastDot);
-                action = staged.topic.slice(lastDot + 1);
-            }
-            else if (staged.topic.includes('_')) {
-                const firstUnderscore = staged.topic.indexOf('_');
-                entity_type = staged.topic.slice(0, firstUnderscore).toLowerCase();
-                action = staged.topic.slice(firstUnderscore + 1).toLowerCase().replace(/_/g, '.');
-            }
-            else {
-                entity_type = staged.topic.toLowerCase();
-                action = 'event';
-            }
+            // Pass the topic directly as event_slug — no decomposition needed.
+            // The Events Service uses event_slug to look up the event_type and fan-out.
             const fullPayload = {
-                entity_type,
-                action,
+                event_slug: staged.topic,
                 source_service: serviceSlug ?? undefined,
                 attributes: staged.payload,
                 metadata: {

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
@@ -428,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

@@ -323,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,6 +1,6 @@
 {
   "name": "@newhomestar/sdk",
-  "version": "0.7.16",
+  "version": "0.7.18",
   "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
   "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
   "bugs": {