@vertesia/client 1.1.1-dev.20260505.163000Z → 1.3.0-dev.20260620.061059Z

package/src/GroupsApi.ts

@@ -1,5 +1,11 @@
-import { CreateUserGroupPayload, DeleteByIdResult, UpdateUserGroupPayload, UserGroup, UserRef } from "@vertesia/common";
-import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type {
+    CreateUserGroupPayload,
+    DeleteByIdResult,
+    UpdateUserGroupPayload,
+    UserGroup,
+    UserRef,
+} from '@vertesia/common';
 
 export interface GroupsQueryOptions {
     search?: string;
@@ -10,9 +16,8 @@ export interface GroupsQueryOptions {
 }
 
 export class GroupsApi extends ApiTopic {
-
     constructor(parent: ClientBase) {
-        super(parent, "/groups");
+        super(parent, '/groups');
     }
 
     /**
@@ -39,7 +44,7 @@ export class GroupsApi extends ApiTopic {
      * @returns The UserGroup object
      */
     retrieve(groupId: string): Promise<UserGroup> {
-        return this.get('/' + groupId);
+        return this.get(`/${groupId}`);
     }
 
     /**
@@ -49,7 +54,7 @@ export class GroupsApi extends ApiTopic {
      * @returns The updated UserGroup object
      */
     update(groupId: string, payload: UpdateUserGroupPayload): Promise<UserGroup> {
-        return this.put('/' + groupId, { payload });
+        return this.put(`/${groupId}`, { payload });
     }
 
     /**
@@ -58,7 +63,7 @@ export class GroupsApi extends ApiTopic {
      * @returns Object with the deleted group ID
      */
     delete(groupId: string): Promise<DeleteByIdResult> {
-        return this.del('/' + groupId);
+        return this.del(`/${groupId}`);
     }
 
     /**
@@ -67,7 +72,7 @@ export class GroupsApi extends ApiTopic {
      * @returns Array of UserRef objects representing group members
      */
     listMembers(groupId: string): Promise<UserRef[]> {
-        return this.get('/' + groupId + '/members');
+        return this.get(`/${groupId}/members`);
     }
 
     /**
@@ -77,7 +82,7 @@ export class GroupsApi extends ApiTopic {
      * @returns The updated UserGroup object
      */
     addMember(groupId: string, userId: string): Promise<UserGroup> {
-        return this.post('/' + groupId + '/members/' + userId);
+        return this.post(`/${groupId}/members/${userId}`);
     }
 
     /**
@@ -87,7 +92,7 @@ export class GroupsApi extends ApiTopic {
      * @returns The updated UserGroup object
      */
     removeMember(groupId: string, userId: string): Promise<UserGroup> {
-        return this.del('/' + groupId + '/members/' + userId);
+        return this.del(`/${groupId}/members/${userId}`);
     }
 
     /**

package/src/IamApi.ts

@@ -1,43 +1,66 @@
-import { AccessControlEntry, ACECreatePayload, AcesQueryOptions, DeleteByIdResult, RoleDefinition } from "@vertesia/common";
-import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
-import { GroupsApi } from "./GroupsApi.js";
-
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type {
+    ACECreatePayload,
+    ACEUpdatePayload,
+    AccessControlEntry,
+    AcesQueryOptions,
+    DeleteByIdResult,
+    PrincipalIdentity,
+    RoleDefinition,
+    SystemRoleDefinition,
+} from '@vertesia/common';
+import { GroupsApi } from './GroupsApi.js';
 
 export interface FilterOption {
-    id: string,
-    name: string,
-    count: number
+    id: string;
+    name: string;
+    count: number;
 }
 
-
 export class IamApi extends ApiTopic {
-
     constructor(parent: ClientBase) {
-        super(parent, "/api/v1/iam")
+        super(parent, '/api/v1/iam');
     }
 
-    aces = new AcesApi(this)
-    roles = new RolesApi(this)
-    groups = new GroupsApi(this)
+    aces = new AcesApi(this);
+    roles = new RolesApi(this);
+    groups = new GroupsApi(this);
+
+    /**
+     * Fetch the current user's principal identity — the id plus the merged
+     * ABAC principal context (clearance, compartments, email, tags, properties).
+     *
+     * Rejects with HTTP 400 if the caller is not a user principal
+     * (API keys, service accounts, etc. — they have no underlying user context).
+     */
+    getPrincipalIdentity(): Promise<PrincipalIdentity> {
+        return this.get('/users/identity');
+    }
 }
 
 export class RolesApi extends ApiTopic {
-
     constructor(parent: ClientBase) {
-        super(parent, "/roles")
+        super(parent, '/roles');
     }
 
+    /** List every built-in role across all partitions. Permissions are loosely typed (`string[]`). */
     list(): Promise<RoleDefinition[]> {
         return this.get('/');
     }
 
+    /**
+     * List system-domain roles only. Permissions are tightly typed as `Permission[]` —
+     * suited for client-side permission gating (button visibility, route guards).
+     * ABAC roles are excluded and must be consumed via the JWT `content_security` claim.
+     */
+    listSystem(): Promise<SystemRoleDefinition[]> {
+        return this.get('/system');
+    }
 }
 
-
 export class AcesApi extends ApiTopic {
-
     constructor(parent: ClientBase) {
-        super(parent, "/aces")
+        super(parent, '/aces');
     }
 
     /**
@@ -50,21 +73,32 @@ export class AcesApi extends ApiTopic {
         return this.get('/', { query: { ...options } });
     }
 
+    /**
+     * List all ACEs scoped to the current project.
+     * Returns both regular project ACEs and dynamic (content_set/principal_set) ACEs.
+     */
+    listProjectAces(): Promise<AccessControlEntry[]> {
+        return this.get('/project');
+    }
+
     /**
      * Get an ACE by its Id
      * @param id
      * @returns InteractionResult
      **/
     retrieve(id: string): Promise<AccessControlEntry> {
-        return this.get('/' + id);
+        return this.get(`/${id}`);
     }
 
     create(payload: ACECreatePayload): Promise<AccessControlEntry> {
-        return this.post('/', { payload })
+        return this.post('/', { payload });
     }
 
-    delete(id: string): Promise<DeleteByIdResult> {
-        return this.del('/' + id)
+    update(id: string, payload: ACEUpdatePayload): Promise<AccessControlEntry> {
+        return this.put(`/${id}`, { payload });
     }
 
+    delete(id: string): Promise<DeleteByIdResult> {
+        return this.del(`/${id}`);
+    }
 }

package/src/InteractionBase.ts

@@ -1,11 +1,18 @@
-import { ExecutionRun, InteractionUpdatePayload, InteractionExecutionPayload } from "@vertesia/common";
-import { VertesiaClient, VertesiaClientProps } from "./client.js";
-import { executeInteraction } from "./execute.js";
+import type {
+    InteractionExecutionPayload,
+    InteractionExecutionResult,
+    InteractionUpdatePayload,
+} from '@vertesia/common';
+import { VertesiaClient, type VertesiaClientProps } from './client.js';
+import { executeInteraction } from './execute.js';
 
-export class InteractionBase<P = any> {
+export class InteractionBase<P = unknown> {
     client: VertesiaClient;
 
-    constructor(public id: string, clientOrOpts: VertesiaClient | VertesiaClientProps) {
+    constructor(
+        public id: string,
+        clientOrOpts: VertesiaClient | VertesiaClientProps,
+    ) {
         if (clientOrOpts instanceof VertesiaClient) {
             this.client = clientOrOpts;
         } else {
@@ -23,7 +30,7 @@ export class InteractionBase<P = any> {
 
     //TODO - Not implemented
     render(_data: P) {
-        throw new Error("Not implemented");
+        throw new Error('Not implemented');
     }
 
     /**
@@ -35,10 +42,12 @@ export class InteractionBase<P = any> {
      * @param id of the interaction to execute
      * @param payload InteractionExecutionPayload
      * @param onChunk callback to be called when the next chunk of the response is available
-     * @returns the resolved execution run as Promise<ExecutionRun>
+     * @returns the resolved interaction execution result
      */
-    async execute(payload: InteractionExecutionPayload = {},
-        onChunk?: (chunk: string) => void): Promise<ExecutionRun<P>> {
+    async execute(
+        payload: InteractionExecutionPayload = {},
+        onChunk?: (chunk: string) => void,
+    ): Promise<InteractionExecutionResult<P>> {
         return executeInteraction<P>(this.client, this.id, payload, onChunk);
     }
 }

package/src/InteractionCatalogApi.ts

@@ -1,31 +1,26 @@
-import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
-import {
-    CatalogInteractionRef,
-    InCodeInteraction,
-    InteractionStatus
-} from "@vertesia/common";
-
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type { CatalogInteractionRef, InCodeInteraction, InteractionStatus } from '@vertesia/common';
 
 export class InteractionCatalogApi extends ApiTopic {
     constructor(parent: ClientBase) {
-        super(parent, "/api/v1/interactions/catalog");
+        super(parent, '/api/v1/interactions/catalog');
     }
 
     /**
      * List all project interactions
      */
-    list(query: { status?: InteractionStatus, tag?: string } = {}): Promise<CatalogInteractionRef[]> {
-        return this.get("/", {
-            query
+    list(query: { status?: InteractionStatus; tag?: string } = {}): Promise<CatalogInteractionRef[]> {
+        return this.get('/', {
+            query,
         });
     }
 
     /**
      * List all stored interactions
      */
-    listStoredInteractions(query: { status?: InteractionStatus, tag?: string } = {}): Promise<CatalogInteractionRef[]> {
-        return this.get("/stored", {
-            query
+    listStoredInteractions(query: { status?: InteractionStatus; tag?: string } = {}): Promise<CatalogInteractionRef[]> {
+        return this.get('/stored', {
+            query,
         });
     }
 
@@ -35,8 +30,8 @@ export class InteractionCatalogApi extends ApiTopic {
     listSysInteractions(tag?: string): Promise<CatalogInteractionRef[]> {
         return this.get(`/sys`, {
             query: {
-                tag
-            }
+                tag,
+            },
         });
     }
 
@@ -46,8 +41,8 @@ export class InteractionCatalogApi extends ApiTopic {
     listAppInteractions(appName: string, tag?: string): Promise<CatalogInteractionRef[]> {
         return this.get(`/apps/${appName}`, {
             query: {
-                tag
-            }
+                tag,
+            },
         });
     }
 
@@ -57,8 +52,8 @@ export class InteractionCatalogApi extends ApiTopic {
     listAllAppInteractions(tag?: string): Promise<CatalogInteractionRef[]> {
         return this.get(`/apps`, {
             query: {
-                tag
-            }
+                tag,
+            },
         });
     }
 

package/src/InteractionOutput.test.ts

@@ -1,4 +1,4 @@
-import { CompletionResult } from '@llumiverse/common';
+import type { CompletionResult } from '@llumiverse/common';
 import { describe, expect, it } from 'vitest';
 import { InteractionOutput, IS_INTERACTION_OUTPUT } from './InteractionOutput.js';
 
@@ -9,7 +9,7 @@ describe('InteractionOutput', () => {
         { type: 'json', value: { name: 'Alice', age: 30 } },
         { type: 'json', value: { title: 'Engineer', level: 'Senior' } },
         { type: 'image', value: 'data:image/png;base64,iVBORw0K...' },
-        { type: 'image', value: 'https://example.com/image.jpg' }
+        { type: 'image', value: 'https://example.com/image.jpg' },
     ];
 
     describe('text accessors', () => {
@@ -19,9 +19,7 @@ describe('InteractionOutput', () => {
         });
 
         it('should return empty string when no text results exist', () => {
-            const output = InteractionOutput.from([
-                { type: 'json', value: { foo: 'bar' } }
-            ]);
+            const output = InteractionOutput.from([{ type: 'json', value: { foo: 'bar' } }]);
             expect(output.text()).toBe('');
         });
 
@@ -29,7 +27,6 @@ describe('InteractionOutput', () => {
             const output = InteractionOutput.from(sampleResults);
             expect(output.texts()).toEqual(['Hello, ', 'World!']);
         });
-
     });
 
     describe('object accessors', () => {
@@ -44,28 +41,22 @@ describe('InteractionOutput', () => {
             const objects = output.objects();
             expect(objects).toEqual([
                 { name: 'Alice', age: 30 },
-                { title: 'Engineer', level: 'Senior' }
+                { title: 'Engineer', level: 'Senior' },
             ]);
         });
 
         it('should parse text as JSON when no JSON result exists', () => {
-            const output = InteractionOutput.from([
-                { type: 'text', value: '{"foo":"bar"}' }
-            ]);
+            const output = InteractionOutput.from([{ type: 'text', value: '{"foo":"bar"}' }]);
             expect(output.object()).toEqual({ foo: 'bar' });
         });
 
         it('should throw error when no JSON result and text is not valid JSON', () => {
-            const output = InteractionOutput.from([
-                { type: 'text', value: 'not json' }
-            ]);
+            const output = InteractionOutput.from([{ type: 'text', value: 'not json' }]);
             expect(() => output.object()).toThrow();
         });
 
         it('should throw error when no JSON result and no text', () => {
-            const output = InteractionOutput.from([
-                { type: 'image', value: 'data:image/png;base64,abc' }
-            ]);
+            const output = InteractionOutput.from([{ type: 'image', value: 'data:image/png;base64,abc' }]);
             expect(() => output.object()).toThrow('No JSON result found and no text available to parse');
         });
     });
@@ -78,19 +69,13 @@ describe('InteractionOutput', () => {
 
         it('should return all images', () => {
             const output = InteractionOutput.from(sampleResults);
-            expect(output.images()).toEqual([
-                'data:image/png;base64,iVBORw0K...',
-                'https://example.com/image.jpg'
-            ]);
+            expect(output.images()).toEqual(['data:image/png;base64,iVBORw0K...', 'https://example.com/image.jpg']);
         });
 
         it('should throw error when no image result exists', () => {
-            const output = InteractionOutput.from([
-                { type: 'text', value: 'hello' }
-            ]);
+            const output = InteractionOutput.from([{ type: 'text', value: 'hello' }]);
             expect(() => output.image()).toThrow('No image result found');
         });
-
     });
 
     describe('utility methods', () => {
@@ -106,43 +91,37 @@ describe('InteractionOutput', () => {
 
         it('should stringify all parts with default separator and compact JSON', () => {
             const output = InteractionOutput.from(sampleResults);
-            const result = output.stringify('\n', 0);  // Explicitly request compact JSON
+            const result = output.stringify('\n', 0); // Explicitly request compact JSON
 
             expect(result).toBe(
                 'Hello, \n' +
-                'World!\n' +
-                '{"name":"Alice","age":30}\n' +
-                '{"title":"Engineer","level":"Senior"}\n' +
-                'data:image/png;base64,iVBORw0K...\n' +
-                'https://example.com/image.jpg'
+                    'World!\n' +
+                    '{"name":"Alice","age":30}\n' +
+                    '{"title":"Engineer","level":"Senior"}\n' +
+                    'data:image/png;base64,iVBORw0K...\n' +
+                    'https://example.com/image.jpg',
             );
         });
 
         it('should stringify all parts with formatted JSON', () => {
             const mixed: CompletionResult[] = [
                 { type: 'text', value: 'Result:' },
-                { type: 'json', value: { score: 95, status: 'pass' } }
+                { type: 'json', value: { score: 95, status: 'pass' } },
             ];
             const output = InteractionOutput.from(mixed);
             const result = output.stringify('\n', 2);
 
-            expect(result).toBe(
-                'Result:\n' +
-                '{\n' +
-                '  "score": 95,\n' +
-                '  "status": "pass"\n' +
-                '}'
-            );
+            expect(result).toBe('Result:\n' + '{\n' + '  "score": 95,\n' + '  "status": "pass"\n' + '}');
         });
 
         it('should stringify with custom separator', () => {
             const mixed: CompletionResult[] = [
                 { type: 'text', value: 'A' },
                 { type: 'json', value: { x: 1 } },
-                { type: 'text', value: 'B' }
+                { type: 'text', value: 'B' },
             ];
             const output = InteractionOutput.from(mixed);
-            const result = output.stringify(' | ', 0);  // Explicitly request compact JSON
+            const result = output.stringify(' | ', 0); // Explicitly request compact JSON
 
             expect(result).toBe('A | {"x":1} | B');
         });
@@ -150,14 +129,13 @@ describe('InteractionOutput', () => {
         it('should stringify with empty separator', () => {
             const mixed: CompletionResult[] = [
                 { type: 'text', value: 'Hello' },
-                { type: 'text', value: 'World' }
+                { type: 'text', value: 'World' },
             ];
             const output = InteractionOutput.from(mixed);
             const result = output.stringify('');
 
             expect(result).toBe('HelloWorld');
         });
-
     });
 
     describe('Proxy functionality', () => {
@@ -172,10 +150,10 @@ describe('InteractionOutput', () => {
             expect(output.length).toBe(6);
 
             // Array methods
-            const types = output.map(r => r.type);
+            const types = output.map((r) => r.type);
             expect(types).toEqual(['text', 'text', 'json', 'json', 'image', 'image']);
 
-            const textResults = output.filter(r => r.type === 'text');
+            const textResults = output.filter((r) => r.type === 'text');
             expect(textResults).toHaveLength(2);
         });
 
@@ -190,9 +168,10 @@ describe('InteractionOutput', () => {
 
         it('should be marked with IS_INTERACTION_OUTPUT symbol', () => {
             const output = InteractionOutput.from(sampleResults);
+            const markedOutput = output as { [IS_INTERACTION_OUTPUT]?: boolean };
 
             // Check that the symbol marker is present
-            expect((output as any)[IS_INTERACTION_OUTPUT]).toBe(true);
+            expect(markedOutput[IS_INTERACTION_OUTPUT]).toBe(true);
         });
 
         it('should return the same instance when calling from() on an already wrapped array', () => {
@@ -249,7 +228,7 @@ describe('InteractionOutput', () => {
             const mixed: CompletionResult[] = [
                 { type: 'text', value: 'Start' },
                 { type: 'json', value: { count: 5 } },
-                { type: 'text', value: 'End' }
+                { type: 'text', value: 'End' },
             ];
 
             const output = InteractionOutput.from(mixed);
@@ -258,9 +237,7 @@ describe('InteractionOutput', () => {
         });
 
         it('should handle results with only one type', () => {
-            const textOnly: CompletionResult[] = [
-                { type: 'text', value: 'Only text here' }
-            ];
+            const textOnly: CompletionResult[] = [{ type: 'text', value: 'Only text here' }];
 
             const output = InteractionOutput.from(textOnly);
             expect(output.text()).toBe('Only text here');
@@ -271,11 +248,12 @@ describe('InteractionOutput', () => {
 
     describe('Type safety with generics', () => {
         it('should provide type safety with generic parameter', () => {
-            interface User { name: string; age: number; }
+            interface User {
+                name: string;
+                age: number;
+            }
 
-            const results: CompletionResult[] = [
-                { type: 'json', value: { name: 'Bob', age: 25 } }
-            ];
+            const results: CompletionResult[] = [{ type: 'json', value: { name: 'Bob', age: 25 } }];
 
             const output = InteractionOutput.from<User>(results);
             const user = output.object(); // TypeScript knows this is User
@@ -284,14 +262,19 @@ describe('InteractionOutput', () => {
             expect(user.age).toBe(25);
         });
 
-
         it('should allow type override at method level', () => {
-            interface Person { name: string; age: number; }
-            interface Address { street: string; city: string; }
+            interface Person {
+                name: string;
+                age: number;
+            }
+            interface Address {
+                street: string;
+                city: string;
+            }
 
             const results: CompletionResult[] = [
                 { type: 'json', value: { name: 'Alice', age: 30 } },
-                { type: 'json', value: { street: '123 Main', city: 'NYC' } }
+                { type: 'json', value: { street: '123 Main', city: 'NYC' } },
             ];
 
             const output = InteractionOutput.from<Person>(results);