@vertesia/common 1.2.0 → 1.3.0-dev.20260620.091720Z

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/types.ts

@@ -0,0 +1,58 @@
+import type { Permission } from '../access-control.js';
+
+/**
+ * Pure types & constants for the role system. This file is intentionally
+ * `class`-free — it is what stays in `@vertesia/common` when the class
+ * hierarchy (`classes.ts`) eventually moves to `studio-utils`. Client SDKs
+ * depend ONLY on these types, never on the registry runtime.
+ */
+
+/**
+ * Kind of object a ContentSet's `resource_props` matches at query time. Used
+ * in `AceConditions.scope` (validated at runtime against this list) and as
+ * the prefix in JWT `content_security` keys (e.g. `collection:read`).
+ *
+ * Each scope is owned by exactly one partition. When adding a new partition
+ * (e.g. tasks), extend this list with the new scope(s) AND extend `RoleDomain`
+ * with the new domain.
+ */
+export const AbacScopes = ['document', 'collection', 'task'] as const;
+export type AbacScope = (typeof AbacScopes)[number];
+
+/**
+ * Logical grouping of roles by the service area that owns them. One domain may
+ * declare roles applicable to multiple scopes (e.g. the `content` domain owns
+ * roles applicable to both `document` and `collection` scopes). The `system`
+ * domain owns the built-in foundational roles (currently exposed as
+ * `SystemRoles`) — registered first so domain partitions cannot shadow them.
+ */
+export type RoleDomain = 'system' | 'content' | 'tasks';
+
+/**
+ * Wire shape of a role returned by the IAM `/roles` endpoint.
+ *
+ * Permissions are typed `string[]` because role names span multiple partitions
+ * (system, content, future tasks/etc.) and each partition has its own
+ * vocabulary. For the tightly-typed system-only view (with `permissions:
+ * Permission[]`) use `SystemRoleDefinition` and the `/roles/system` endpoint.
+ *
+ * NOTE: this interface is intentionally non-generic. The OpenAPI generator
+ * doesn't handle TypeScript generics cleanly in array response types and
+ * produces a degenerate `RoleDefinitionArray` schema. Keeping the wire shapes
+ * concrete avoids that. `SystemRoleDefinition` extends and narrows
+ * `permissions` to `Permission[]`.
+ */
+export interface RoleDefinition {
+    name: string;
+    permissions: string[];
+    domain: RoleDomain;
+}
+
+/**
+ * Tightly-typed view of a system-domain role: permissions are central
+ * `Permission` enum values. Returned by `client.iam.roles.listSystem()` and
+ * by the server's `/roles/system` endpoint.
+ */
+export interface SystemRoleDefinition extends RoleDefinition {
+    permissions: Permission[];
+}

package/src/roles.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'vitest';
+import { SystemRoles } from './project.js';
+import { AbacScopes } from './roles/types.js';
+
+describe('shared role vocabulary', () => {
+    test('exports all system roles', () => {
+        expect(Object.values(SystemRoles).sort()).toEqual(
+            [
+                'admin',
+                'app_member',
+                'application',
+                'auditor',
+                'automation',
+                'billing',
+                'consumer',
+                'content_processor',
+                'content_superadmin',
+                'developer',
+                'executor',
+                'manager',
+                'member',
+                'owner',
+                'reader',
+                'support',
+            ].sort(),
+        );
+    });
+
+    test('exports ABAC scopes used by role wire types', () => {
+        expect(AbacScopes).toEqual(['document', 'collection', 'task']);
+    });
+});

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 {