@vertesia/common 1.3.0 → 1.4.0-dev.20260615.042033Z

package/src/prompt.ts

@@ -1,6 +1,5 @@
-import type { JSONObject, JSONSchema } from "@llumiverse/common";
-import { PromptRole } from "@llumiverse/common";
-import { ProjectRef } from "./project.js";
+import type { JSONObject, JSONSchema, PromptRole } from '@llumiverse/common';
+import type { ProjectRef } from './project.js';
 
 export interface ChatPromptSchema {
     role: PromptRole.user | PromptRole.assistant;
@@ -8,43 +7,47 @@ export interface ChatPromptSchema {
 }
 
 export enum PromptStatus {
-    draft = "draft",
-    published = "published",
-    archived = "archived",
+    draft = 'draft',
+    published = 'published',
+    archived = 'archived',
 }
 
-
 export enum PromptSegmentDefType {
-    chat = "chat",
-    template = "template",
+    chat = 'chat',
+    template = 'template',
 }
 
-export interface PromptSegmentDef<
-    T = string | PromptTemplate | PromptTemplateRef,
-> {
+export interface PromptSegmentDef<T = string | PromptTemplate | PromptTemplateRef> {
+    id?: string;
     type: PromptSegmentDefType;
     template?: T; // the template id in case of a prompt template
-    configuration?: any; // the configuration if any in case of builtin prompts
+    configuration?: unknown; // the configuration if any in case of builtin prompts
 }
-export interface PopulatedPromptSegmentDef
-    extends Omit<PromptSegmentDef, "template"> {
+
+export interface PromptSegmentRef<T = string | PromptTemplate | PromptTemplateRef> extends PromptSegmentDef<T> {
+    id: string;
+}
+
+export interface PopulatedPromptSegmentDef extends Omit<PromptSegmentDef, 'template'> {
     template?: PromptTemplate;
 }
 /**
  * Used for prompt rendering at interaction execution
  */
-export interface ExecutablePromptSegmentDef
-    extends Omit<PromptSegmentDef, "template"> {
+export interface ExecutablePromptSegmentDef extends Omit<PromptSegmentDef, 'template'> {
     template?: ExecutablePromptTemplate;
 }
 
 export interface PromptTemplateRef {
     id: string;
     name: string;
+    description?: string;
     role: PromptRole;
     version: number;
     status: PromptStatus;
-    content_type: TemplateType;
+    content_type?: TemplateType;
+    created_at: Date;
+    updated_at: Date;
 }
 
 export interface PromptTemplateRefWithSchema extends PromptTemplateRef {
@@ -52,9 +55,9 @@ export interface PromptTemplateRefWithSchema extends PromptTemplateRef {
 }
 
 export enum TemplateType {
-    jst = "jst",
-    handlebars = "handlebars",
-    text = "text",
+    jst = 'jst',
+    handlebars = 'handlebars',
+    text = 'text',
 }
 export interface ExecutablePromptTemplate {
     role: PromptRole;
@@ -79,8 +82,8 @@ export interface PromptTemplate extends ExecutablePromptTemplate {
     tags?: string[];
     // only for drafts - when it was last published
     last_published_at?: Date;
-    created_by: string,
-    updated_by: string,
+    created_by: string;
+    updated_by: string;
     created_at: Date;
     updated_at: Date;
 }
@@ -93,13 +96,13 @@ export interface PromptTemplateForkPayload {
 export interface PromptTemplateCreatePayload
     extends Omit<
         PromptTemplate,
-        "id" | "created_at" | "updated_at" | "created_by" | "updated_by" | "project" | "status" | "version"
-    > { }
+        'id' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'project' | 'status' | 'version'
+    > {}
 
 export interface PromptTemplateUpdatePayload
     extends Partial<
-        Omit<PromptTemplate, "id" | "created_at" | "updated_at" | "created_by" | "updated_by" | "project">
-    > { }
+        Omit<PromptTemplate, 'id' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'project'>
+    > {}
 
 export interface PromptTemplateInteractionVersion {
     version: number;

package/src/query.ts

@@ -1,6 +1,6 @@
-import { ExecutionRunStatus } from './interaction.js';
-import { CollectionSearchPayload } from './store/collections.js';
-import { SearchTypes, SupportedEmbeddingTypes } from "./project.js";
+import type { ExecutionRunStatus } from './interaction.js';
+import type { SearchTypes, SupportedEmbeddingTypes } from './project.js';
+import type { CollectionSearchPayload } from './store/collections.js';
 
 export type EmbeddingSearchConfig = Partial<Record<SupportedEmbeddingTypes, boolean>>;
 
@@ -13,15 +13,16 @@ export interface RunListingQueryOptions {
 }
 
 export interface RunListingFilters {
-    interaction?: string | string[],
-    status?: ExecutionRunStatus,
-    model?: string,
-    environment?: string,
-    tag?: string,
-    fromDate?: string,
-    toDate?: string,
-    parent?: string | false,
-    workflow_run_ids?: string[],
+    interaction?: string | string[];
+    status?: ExecutionRunStatus;
+    model?: string;
+    environment?: string;
+    tag?: string;
+    fromDate?: string;
+    toDate?: string;
+    parent?: string | string[];
+    is_root?: boolean;
+    workflow_run_ids?: string[];
 }
 
 export type scoreAggregationTypes = 'rrf' | 'rsf' | 'smart';
@@ -88,7 +89,8 @@ export interface RunSearchQuery extends SimpleSearchQuery {
     tags?: string[];
     query?: string;
     default_query_path?: string;
-    parent?: string[] | false;
+    parent?: string[];
+    is_root?: boolean;
     object?: string;
     start?: string;
     end?: string;
@@ -127,8 +129,8 @@ export interface ComplexSearchQuery extends ObjectSearchQuery {
      * e.g. Weights of 5,3,2 will be treated as 0,3,2 if the first search type is not present in the results.
      * Ignored when scoreAggregation is 'smart'
      * Default is 'on'
-    */
-    dynamic_scaling?: dynamicScalingTypes;   // Move to top level
+     */
+    dynamic_scaling?: dynamicScalingTypes; // Move to top level
 
     /**
      * rrf: Reciprocal Rank Fusion
@@ -137,9 +139,9 @@ export interface ComplexSearchQuery extends ObjectSearchQuery {
      */
     score_aggregation?: scoreAggregationTypes;
 
-    match?: Record<string, any>;
+    match?: Record<string, unknown>;
 }
 
 export interface ComplexCollectionSearchQuery extends CollectionSearchPayload {
-    match?: Record<string, any>;
+    match?: Record<string, unknown>;
 }

package/src/rate-limiter.ts

@@ -31,4 +31,4 @@ export interface RateLimiterStatus {
 }
 
 // Always return an array for consistency
-export type RateLimiterStatusResponse = RateLimiterStatus[];
+export type RateLimiterStatusResponse = RateLimiterStatus[];

package/src/refs.ts

@@ -1,34 +1,29 @@
-
-
 export enum ResolvableRefType {
-    project = "Project",
-    projects = "Projects",
-    environment = "Environment",
-    user = "User",
-    account = "Account",
-    interaction = "Interaction",
-    userGroup = "UserGroup"
+    project = 'Project',
+    projects = 'Projects',
+    environment = 'Environment',
+    user = 'User',
+    account = 'Account',
+    interaction = 'Interaction',
+    userGroup = 'UserGroup',
 }
 
 export interface ResolvableRef {
-    type: ResolvableRefType
-    id: string
+    type: ResolvableRefType;
+    id: string;
 }
 
 export interface RefResolutionRequest {
-
-    refs: ResolvableRef[]
-
+    refs: ResolvableRef[];
 }
 
-
 export interface ResourceRef {
-    id: string
-    name: string
-    type: string
-    description?: string
-    version?: number
-    status?: string
-    tags?: string[]
-    endpoint?: string
-}
+    id: string;
+    name: string;
+    type: string;
+    description?: string;
+    version?: number;
+    status?: string;
+    tags?: string[];
+    endpoint?: string;
+}

package/src/roles.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from 'vitest';
+import { Permission } from './access-control.js';
+import { ProjectRoles } from './project.js';
+import { getPermissionsForRoles, getRoleByName, listRoles } from './roles.js';
+
+describe('role permission catalog', () => {
+    test('lists all project roles', () => {
+        expect(
+            listRoles()
+                .map((role) => role.name)
+                .sort(),
+        ).toEqual(Object.values(ProjectRoles).sort());
+    });
+
+    test('derives developer permissions without administrative grants', () => {
+        const developer = getRoleByName(ProjectRoles.developer);
+
+        expect(developer.hasPermission(Permission.int_read)).toBe(true);
+        expect(developer.hasPermission(Permission.account_admin)).toBe(false);
+        expect(developer.hasPermission(Permission.project_admin)).toBe(false);
+    });
+
+    test('deduplicates permissions across multiple roles', () => {
+        const permissions = getPermissionsForRoles([ProjectRoles.reader, ProjectRoles.executor]);
+
+        expect(permissions).toContain(Permission.account_member);
+        expect(permissions).toContain(Permission.content_read);
+        expect(permissions.filter((permission) => permission === Permission.account_member)).toHaveLength(1);
+    });
+});

package/src/roles.ts

@@ -0,0 +1,251 @@
+import { Permission } from './access-control.js';
+import { ProjectRoles } from './project.js';
+
+export class Role {
+    permissions: Set<Permission>;
+    constructor(
+        public name: ProjectRoles,
+        permissions: Permission[],
+    ) {
+        this.permissions = new Set(permissions);
+    }
+
+    hasPermission(permission: Permission) {
+        return this.permissions.has(permission);
+    }
+}
+
+export class RoleList {
+    private constructor(public readonly roles: Role[]) {}
+
+    static fromRoleNames(roleNames: ProjectRoles[]): RoleList {
+        const roles = roleNames.map((r) => getRoleByName(r));
+        return new RoleList(roles);
+    }
+
+    static fromRoleName(roleName: ProjectRoles): RoleList {
+        const roles = [getRoleByName(roleName)];
+        return new RoleList(roles);
+    }
+
+    hasPermission(perm: Permission): boolean {
+        return this.roles.some((role) => role.hasPermission(perm));
+    }
+}
+
+class OrgMemberRole extends Role {
+    constructor(
+        public name: ProjectRoles,
+        permissions: Permission[],
+    ) {
+        super(name, [Permission.account_member, ...permissions]);
+    }
+}
+
+class OwnerRole extends OrgMemberRole {
+    constructor() {
+        super(ProjectRoles.owner, Object.values(Permission));
+    }
+}
+
+class AdminRole extends OrgMemberRole {
+    constructor() {
+        super(ProjectRoles.admin, Object.values(Permission));
+    }
+}
+
+class ManagerRole extends OrgMemberRole {
+    constructor() {
+        super(ProjectRoles.manager, Object.values(Permission));
+        this.permissions.delete(Permission.account_admin);
+        this.permissions.delete(Permission.manage_billing);
+        this.permissions.delete(Permission.audit_read);
+        this.permissions.delete(Permission.agent_run_read);
+        this.permissions.delete(Permission.content_read_all);
+        this.permissions.delete(Permission.content_superadmin);
+        this.permissions.delete(Permission.workflow_superadmin);
+    }
+}
+
+class DeveloperRole extends OrgMemberRole {
+    constructor() {
+        super(ProjectRoles.developer, Object.values(Permission));
+        this.permissions.delete(Permission.account_admin);
+        this.permissions.delete(Permission.project_admin);
+        this.permissions.delete(Permission.project_settings_write);
+        this.permissions.delete(Permission.env_admin);
+        this.permissions.delete(Permission.manage_billing);
+        this.permissions.delete(Permission.audit_read);
+        this.permissions.delete(Permission.agent_run_read);
+        this.permissions.delete(Permission.content_read_all);
+        this.permissions.delete(Permission.content_superadmin);
+        this.permissions.delete(Permission.workflow_superadmin);
+    }
+}
+
+class ApplicationRole extends OrgMemberRole {
+    constructor() {
+        super(ProjectRoles.application, [
+            Permission.int_read,
+            Permission.int_execute,
+            Permission.int_write,
+            Permission.run_read,
+            Permission.content_write,
+            Permission.content_read,
+            Permission.content_write,
+            Permission.content_admin, // required for now as we need to create types
+            Permission.project_admin,
+            Permission.workflow_run,
+            Permission.project_settings_write,
+            Permission.account_write,
+        ]);
+    }
+}
+
+class AutomationRole extends OrgMemberRole {
+    constructor() {
+        super(ProjectRoles.automation, [
+            Permission.content_read,
+            Permission.content_write,
+            Permission.content_admin,
+            Permission.int_read,
+            Permission.int_execute,
+            Permission.run_read,
+            Permission.workflow_run,
+            Permission.project_integration_read,
+        ]);
+    }
+}
+
+class ContentProcessorRole extends OrgMemberRole {
+    constructor() {
+        super(ProjectRoles.content_processor, [
+            Permission.content_read,
+            Permission.content_write,
+            Permission.content_admin,
+            Permission.content_superadmin,
+            Permission.int_execute,
+            Permission.workflow_read,
+            Permission.workflow_run,
+            Permission.run_read,
+        ]);
+    }
+}
+
+class ConsumerRole extends OrgMemberRole {
+    constructor() {
+        super(ProjectRoles.consumer, [
+            Permission.content_admin, // Temporary permission; micro apps will need to create types instead via user roles
+            Permission.content_read,
+            Permission.content_write,
+            Permission.content_delete,
+            Permission.int_read,
+            Permission.int_execute,
+            Permission.run_read,
+            Permission.workflow_run,
+        ]);
+    }
+}
+
+class ExecutorRole extends OrgMemberRole {
+    constructor() {
+        super(ProjectRoles.executor, [Permission.int_execute, Permission.run_read, Permission.workflow_run]);
+    }
+}
+
+class ReaderRole extends OrgMemberRole {
+    constructor() {
+        super(ProjectRoles.reader, [Permission.int_read, Permission.run_read, Permission.content_read]);
+    }
+}
+
+const READ_ONLY_AUDIT_PERMISSIONS = [
+    Permission.studio_access,
+    Permission.account_read,
+    Permission.project_integration_read,
+    Permission.api_key_read,
+    Permission.billing_read,
+    Permission.audit_read,
+    Permission.int_read,
+    Permission.run_read,
+    Permission.content_read,
+    Permission.content_read_all,
+    Permission.task_read,
+    Permission.workflow_read,
+    Permission.agent_run_read,
+];
+
+class ReadOnlyAuditRole extends OrgMemberRole {
+    constructor(name: ProjectRoles.auditor | ProjectRoles.support) {
+        super(name, READ_ONLY_AUDIT_PERMISSIONS);
+    }
+}
+
+class BillingRole extends OrgMemberRole {
+    constructor() {
+        super(ProjectRoles.billing, [Permission.manage_billing]);
+    }
+}
+
+class AppMemberRole extends OrgMemberRole {
+    constructor() {
+        super(ProjectRoles.app_member, [
+            Permission.int_read,
+            Permission.int_execute,
+            Permission.int_write,
+            Permission.run_read,
+            Permission.content_write,
+            Permission.content_read,
+            Permission.content_delete,
+            Permission.workflow_run,
+        ]);
+    }
+}
+
+class ContentSuperAdmin extends DeveloperRole {
+    constructor() {
+        super();
+        this.name = ProjectRoles.content_superadmin;
+        this.permissions.add(Permission.content_superadmin);
+    }
+}
+
+const roles: Record<ProjectRoles, Role> = {
+    [ProjectRoles.owner]: new OwnerRole(),
+    [ProjectRoles.admin]: new AdminRole(),
+    [ProjectRoles.manager]: new ManagerRole(),
+    [ProjectRoles.developer]: new DeveloperRole(),
+    [ProjectRoles.application]: new ApplicationRole(),
+    [ProjectRoles.automation]: new AutomationRole(),
+    [ProjectRoles.content_processor]: new ContentProcessorRole(),
+    [ProjectRoles.consumer]: new ConsumerRole(),
+    [ProjectRoles.executor]: new ExecutorRole(),
+    [ProjectRoles.reader]: new ReaderRole(),
+    [ProjectRoles.auditor]: new ReadOnlyAuditRole(ProjectRoles.auditor),
+    [ProjectRoles.support]: new ReadOnlyAuditRole(ProjectRoles.support),
+    [ProjectRoles.billing]: new BillingRole(),
+    [ProjectRoles.app_member]: new AppMemberRole(),
+    [ProjectRoles.member]: new OrgMemberRole(ProjectRoles.member, []),
+    [ProjectRoles.content_superadmin]: new ContentSuperAdmin(),
+};
+
+export function getRoleByName(name: ProjectRoles): Role {
+    const role = roles[name];
+    if (!role) throw new Error(`Role ${name} not found`);
+    return role;
+}
+
+export function listRoles(): Role[] {
+    return Object.values(roles);
+}
+
+export function getPermissionsForRoles(roleNames: Iterable<ProjectRoles>): Permission[] {
+    const permissions = new Set<Permission>();
+    for (const roleName of roleNames) {
+        const role = getRoleByName(roleName);
+        for (const permission of role.permissions) {
+            permissions.add(permission);
+        }
+    }
+    return Array.from(permissions);
+}

package/src/runs.ts

@@ -1,21 +1,20 @@
-import { FacetResult } from './facets.js';
-import { NamedInteractionExecutionPayload } from './interaction.js';
+import type { FacetResult } from './facets.js';
+import type { NamedInteractionExecutionPayload } from './interaction.js';
 
 /**
  * The run ref is used to identify a run document in the storage
  */
 export interface ExecutionRunDocRef {
-    id: string,
-    account: string,
-    project: string,
+    id: string;
+    account: string;
+    project: string;
 }
 
 /**
  * Interaction execution payload for creating a new run
  * It uses interaction field (from NamedInteractionExecutionPayload) to pass the interaction ID to run
  */
-export interface RunCreatePayload extends NamedInteractionExecutionPayload {
-}
+export interface RunCreatePayload extends NamedInteractionExecutionPayload {}
 
 /**
  * Payload for cloning an existing ExecutionRun.
@@ -36,16 +35,16 @@ export interface RunClonePayload {
  * To be used as a value for a numeric or date filters
  */
 export interface RangeValue {
-    gt?: number | string,
-    gte?: number | string,
-    lt?: number | string,
-    lte?: number | string,
+    gt?: number | string;
+    gte?: number | string;
+    lt?: number | string;
+    lte?: number | string;
 }
 
 export interface RunSearchMetaResponse {
     count: {
-        lower_bound?: number,
-        total?: number,
-    },
-    facet: Record<string, FacetResult>
+        lower_bound?: number;
+        total?: number;
+    };
+    facet: Record<string, FacetResult>;
 }

package/src/secrets.ts

@@ -0,0 +1,60 @@
+import type {
+    WebsiteCredentialMetadata,
+    WebsiteCredentialRecord,
+    WebsiteCredentialSecretInput,
+} from './browser-credentials.js';
+
+// First supported top-level secret kind. OAuth connector grants continue to use
+// the OAuth/MCP token flows and can be materialized later by tools that need them.
+export type SecretKind = 'website_credential';
+
+export interface SecretProjectQuery {
+    /**
+     * Project scope for top-level secret APIs. Must match the authenticated project context.
+     */
+    project_id?: string;
+}
+
+export interface ListSecretsQuery extends SecretProjectQuery {
+    kind?: SecretKind;
+    host?: string;
+    enabled?: boolean;
+}
+
+export interface SecretLookupQuery extends SecretProjectQuery {
+    kind?: SecretKind;
+}
+
+export interface SecretRecord {
+    id: string;
+    secret_ref: string;
+    kind: SecretKind;
+    project: string;
+    name: string;
+    enabled?: boolean;
+    tags?: string[];
+    properties?: Record<string, unknown>;
+    created_at?: string;
+    updated_at?: string;
+    details?: WebsiteCredentialRecord;
+}
+
+export interface ListSecretsResponse {
+    secrets: SecretRecord[];
+}
+
+export interface CreateSecretRequest {
+    kind: SecretKind;
+    metadata: WebsiteCredentialMetadata;
+    secret?: WebsiteCredentialSecretInput;
+}
+
+export interface UpdateSecretRequest {
+    kind?: SecretKind;
+    metadata?: Partial<WebsiteCredentialMetadata>;
+    secret?: WebsiteCredentialSecretInput;
+    clear_username_secret?: boolean;
+    clear_password?: boolean;
+    clear_totp?: boolean;
+    clear_oauth?: boolean;
+}

package/src/skill.ts

@@ -10,7 +10,6 @@
  * These are automatically synced to the sandbox when the skill is used.
  */
 
-
 /**
  * Context provided when searching for relevant skills
  */
@@ -62,7 +61,7 @@ export interface InjectedSkill {
     /**
      * Tools related to this skill
      */
-    related_tools?: string[];
+    tools?: string[];
 
     /**
      * UI module for rendering results

package/src/store/activity-catalog.ts

@@ -1,4 +1,16 @@
-export type TsPropType = "string" | "number" | "boolean" | "record" | "object" | "array" | "enum" | "literal" | "union" | "promise" | "any" | "void";
+export type TsPropType =
+    | 'string'
+    | 'number'
+    | 'boolean'
+    | 'record'
+    | 'object'
+    | 'array'
+    | 'enum'
+    | 'literal'
+    | 'union'
+    | 'promise'
+    | 'any'
+    | 'void';
 
 // generic types are replaced by "any"
 export interface ActivityTypeDefinition {