@newhomestar/sdk 0.7.20 → 0.7.23

package/dist/next.d.ts

@@ -50,6 +50,183 @@ export interface ParamMeta {
     order?: number;
     group?: string;
 }
+/**
+ * A single FGA relation definition for an object type.
+ * Declared in `defineService().fga.relations[]` and auto-registered in the
+ * IAM service's `entity_relation_definitions` table at `nova services push` time.
+ */
+export interface NovaFgaRelationDef {
+    /** Object type this relation applies to (e.g. 'community', 'trnVideo') */
+    object_type: string;
+    /** The relation name (e.g. 'admin', 'editor', 'member', 'viewer') */
+    relation: string;
+    /**
+     * Relations this relation implies (e.g. admin implies ['editor', 'member']).
+     * The IAM DB trigger pre-expands implied relations into entity_computed_access
+     * automatically — no application code needed for propagation.
+     */
+    implies?: string[];
+    /** Priority for ordering (default: 0). Higher = evaluated first. */
+    priority?: number;
+}
+/**
+ * IAM resource declaration for `defineService().iam.resources[]`.
+ * Declares how the service's permission namespace maps to the Odyssey UI resource tree.
+ * Used by `nova services push` to set resource types, hierarchy levels, and parent-child
+ * relationships between resources.
+ *
+ * @example
+ * ```ts
+ * iam: {
+ *   resources: [
+ *     { name: 'HRIS Admin', resource_path: 'hris_admin', resource_type: 'module', level: 50,
+ *       description: 'HRIS module — unified HR and payroll data' },
+ *     { name: 'Employees', resource_path: 'hris_employees', resource_type: 'block', level: 60,
+ *       parent_resource_path: 'hris_admin', description: 'Employee records' },
+ *   ],
+ * }
+ * ```
+ */
+export interface NovaIamResourceDef {
+    /** Human-readable display name shown in Odyssey UI (e.g. 'Employees', 'HRIS Admin') */
+    name: string;
+    /** Unique resource path — must match the permission slug prefix (e.g. 'hris_employees') */
+    resource_path: string;
+    /** Position in the resource hierarchy */
+    resource_type: 'system' | 'module' | 'block' | 'resource';
+    /** Hierarchy level: 50=module, 60=block, 80=resource */
+    level: number;
+    /** Optional description shown in Odyssey UI */
+    description?: string;
+    /**
+     * resource_path of the parent resource.
+     * Resolved to parentResourceId at `nova services push` time by the IAM service.
+     * e.g. set to 'hris_admin' to nest this resource under the HRIS Admin module.
+     */
+    parent_resource_path?: string;
+    /** Arbitrary metadata stored on the resource record */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * FGA check declared on a novaEndpoint() — runtime-only.
+ * Describes which relation on which object a request's subject must hold.
+ * The schema (relation hierarchy) is declared in `defineService().fga.relations`.
+ *
+ * Used by `nova.assertFga(req, context)` at runtime (Phase 2).
+ * Stored on the endpoint record in the platform DB for Odyssey UI display.
+ */
+export interface NovaFgaCheckDef {
+    /** Object type to check (e.g. 'community', 'trnVideo') */
+    object_type: string;
+    /** Relation the subject must hold (e.g. 'member', 'viewer', 'editor') */
+    relation: string;
+    /**
+     * Where to resolve object_id from in the request:
+     *   'path'  → Next.js route params (e.g. params.id for /communities/:id)
+     *   'query' → URL query string param
+     */
+    object_id_from: 'path' | 'query';
+    /** The param name to extract object_id from (e.g. 'id', 'community_id') */
+    object_id_param: string;
+    /** Optional tenant_id param name for multi-tenant scoped checks */
+    tenant_id_param?: string;
+}
+/**
+ * Service manifest definition — the code-first single source of truth for a
+ * Nova service. `nova services push` reads this to generate nova-service.yaml
+ * and sync all service metadata to the platform.
+ *
+ * Place this in `src/service.ts` (or `src/app/service.ts`) and export as `service`.
+ *
+ * @example
+ * ```ts
+ * // src/service.ts
+ * import { defineService } from '@newhomestar/sdk/next';
+ *
+ * export const service = defineService({
+ *   slug:     'community',
+ *   name:     'Community Service',
+ *   category: 'social',
+ *   runtime:  'nextjs',
+ *   apiDir:   './src/app',
+ *
+ *   fga: {
+ *     relations: [
+ *       { object_type: 'community', relation: 'admin',  implies: ['editor', 'member'], priority: 100 },
+ *       { object_type: 'community', relation: 'editor', implies: ['viewer'],           priority: 50  },
+ *       { object_type: 'community', relation: 'member', implies: ['viewer'],           priority: 30  },
+ *       { object_type: 'community', relation: 'viewer', implies: [],                   priority: 10  },
+ *     ],
+ *   },
+ * });
+ * ```
+ */
+export interface NovaServiceDef {
+    /** Unique service slug (e.g. 'community', 'hris', 'iam') */
+    slug: string;
+    /** Human-readable service name */
+    name: string;
+    /** Service description */
+    description?: string;
+    /** Category for grouping in Odyssey UI (e.g. 'platform', 'social', 'hris') */
+    category?: string;
+    /** Service version (default: '1.0.0') */
+    version?: string;
+    /** Runtime mode (default: 'nextjs') */
+    runtime?: 'nextjs' | 'sdk';
+    /** Path to route files directory (default: './src/app') */
+    apiDir?: string;
+    /** Public base URL for Odyssey UI API tester */
+    baseUrl?: string;
+    /** Shared Zod schemas registered in platform DB on push */
+    schemas?: Array<{
+        slug: string;
+        name: string;
+        file: string;
+        description?: string;
+        version?: string;
+        schemaType?: string;
+    }>;
+    /** Environment variable declarations */
+    envSpec?: Array<{
+        name: string;
+        secret?: boolean;
+        default?: string;
+    }>;
+    /** Container resource requests */
+    resources?: {
+        cpu?: string;
+        memory?: string;
+    };
+    /**
+     * FGA schema — defines relation hierarchies for all object types owned by
+     * this service. Registered in IAM `entity_relation_definitions` at push time.
+     *
+     * This MUST be pushed before any `entity_grants` are assigned, as the
+     * trigger-based expansion relies on these definitions to propagate implied
+     * relations through `entity_computed_access`.
+     */
+    fga?: {
+        relations: NovaFgaRelationDef[];
+    };
+    /**
+     * IAM resource hierarchy — declares how this service's permission namespace
+     * maps to the Odyssey UI resource tree (module → block → resource).
+     *
+     * Resources declared here override the auto-derived defaults (which default
+     * to resource_type: 'module', level: 50, no parent). Use this to:
+     *   - Declare a parent module resource (e.g. 'hris_admin')
+     *   - Nest entity resources as blocks under that module
+     *   - Control display names, descriptions, and hierarchy levels
+     *
+     * At `nova services push` time the CLI reads this, merges with auto-derived
+     * resources from permission slugs, and sends `parent_resource_path` to the
+     * IAM service which resolves it to `parentResourceId` in the DB.
+     */
+    iam?: {
+        resources: NovaIamResourceDef[];
+    };
+}
 /**
  * An event type emitted by a service endpoint.
  * Defined inline in `novaEndpoint()` and auto-registered in the platform
@@ -218,6 +395,47 @@ export interface NovaEndpointDef<I extends ZodTypeAny = ZodTypeAny, O extends Zo
      * ```
      */
     events?: NovaEndpointEventDef[];
+    /**
+     * FGA (Fine-Grained Authorization) check(s) required to access this endpoint.
+     *
+     * The authenticated subject (user) must hold the declared `relation` on the
+     * specified `object_type:object_id` to be granted access.
+     *
+     * The FGA schema (relation hierarchy) is declared separately in
+     * `defineService().fga.relations` and registered at `nova services push` time.
+     * The fgaCheck here is **runtime-only** — it describes how to resolve the
+     * object_id from the current request and which relation to verify.
+     *
+     * Runtime enforcement is via `nova.assertFga(req, { path: params })` (Phase 2).
+     * At push time, the declarations are stored on the endpoint record in the
+     * platform DB for Odyssey UI display.
+     *
+     * @example
+     * ```ts
+     * // Single check: user must be a member of the community
+     * fgaCheck: {
+     *   object_type:     'community',
+     *   relation:        'member',
+     *   object_id_from:  'path',
+     *   object_id_param: 'id',
+     * }
+     *
+     * // Multiple checks: user must be member of community AND editor of the video
+     * fgaCheck: [
+     *   { object_type: 'community', relation: 'member', object_id_from: 'path', object_id_param: 'community_id' },
+     *   { object_type: 'trnVideo',  relation: 'editor', object_id_from: 'path', object_id_param: 'video_id' },
+     * ],
+     * fgaMode: 'all',
+     * ```
+     */
+    fgaCheck?: NovaFgaCheckDef | NovaFgaCheckDef[];
+    /**
+     * When multiple `fgaCheck` entries are declared, controls evaluation logic:
+     *   'all' → every check must pass (default — AND logic, most restrictive)
+     *   'any' → at least one check must pass (OR logic)
+     * Ignored when fgaCheck is a single object.
+     */
+    fgaMode?: 'all' | 'any';
 }
 export type NovaEndpoint<I extends ZodTypeAny = ZodTypeAny, O extends ZodTypeAny = ZodTypeAny> = NovaEndpointDef<I, O> & {
     /**
@@ -370,9 +588,23 @@ 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
@@ -497,6 +729,8 @@ export declare const CURSOR_PAGE_PARAMS: Record<string, ParamMeta>;
 export declare const OFFSET_PAGE_PARAMS: Record<string, ParamMeta>;
 /**
  * Metadata for a Nova service — passed to `defineService()`.
+ * Extends `NovaServiceDef` to include FGA relation schema and IAM resource
+ * hierarchy declarations consumed by `nova services push`.
  */
 export interface ServiceDef {
     /** Unique service slug (snake_case). e.g. "nova_ticketing_service" */
@@ -509,6 +743,21 @@ export interface ServiceDef {
     category?: string;
     /** Semver version string — defaults to "1.0.0" */
     version?: string;
+    /**
+     * FGA schema — relation hierarchies for object types owned by this service.
+     * Registered in IAM `entity_relation_definitions` at `nova services push` time.
+     */
+    fga?: {
+        relations: NovaFgaRelationDef[];
+    };
+    /**
+     * IAM resource hierarchy — maps permission namespace to the Odyssey UI tree.
+     * Overrides auto-derived resource names/types/levels and sets parent-child links.
+     * See `NovaIamResourceDef` for field documentation.
+     */
+    iam?: {
+        resources: NovaIamResourceDef[];
+    };
 }
 /**
  * defineService() — declare Nova service identity and auto-set NOVA_SERVICE_SLUG.

package/dist/next.js

@@ -191,9 +191,25 @@ 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
@@ -203,7 +219,7 @@ export function buildPrismaPage(input) {
  * ```
  */
 export function buildPrismaOffsetPage(input, defaultSort = 'createdAt') {
-    const col = input.sort ?? defaultSort;
+    const col = snakeToCamel(input.sort ?? defaultSort);
     return {
         skip: input.offset,
         take: input.limit,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newhomestar/sdk",
-  "version": "0.7.20",
+  "version": "0.7.23",
   "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
   "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
   "bugs": {