@vertesia/common 0.24.0-dev.202601221707

package/src/access-control.ts

@@ -0,0 +1,98 @@
+/**
+ * @module access-control
+ * @description
+ * Access control interfaces
+ */
+
+import { ProjectRoles } from "./project.js";
+
+export enum Permission {
+    int_read = "interaction:read",
+    int_write = "interaction:write",
+    int_delete = "interaction:delete",
+
+    int_execute = "interaction:execute",
+    run_read = "run:read",
+    run_write = "run:write",
+
+    env_admin = "environment:admin",
+
+    project_admin = "project:admin",
+    project_integration_read = "project:integration_read",
+    project_settings_write = "project:settings_write",
+
+    api_key_create = "api_key:create",
+    api_key_read = "api_key:read",
+    api_key_update = "api_key:update",
+    api_key_delete = "api_key:delete",
+
+    account_read = "account:read",
+    account_write = "account:write",
+    account_admin = "account:admin",
+    manage_billing = "account:billing",
+    account_member = "account:member",
+
+
+    content_read = "content:read",
+    content_write = "content:write",
+    content_delete = "content:delete",
+    content_admin = "content:admin", //manage schemas
+    content_superadmin = "content:superadmin", // list all objects and collections
+
+
+    workflow_run = "workflow:run",
+    workflow_admin = "workflow:admin",
+    workflow_superadmin = "workflow:superadmin",
+
+    iam_impersonate = "iam:impersonate",
+
+    /** whether the user has access to Sutdio App. */
+    studio_access = "studio:access",
+}
+
+export enum AccessControlResourceType {
+    project = "project",
+    environment = "environment",
+    account = "account",
+    interaction = "interaction",
+    app = "application",
+}
+
+export enum AccessControlPrincipalType {
+    user = "user",
+    group = "group",
+    apikey = "apikey",
+}
+
+
+
+export interface AccessControlEntry {
+    role: ProjectRoles;
+    resource_type: AccessControlResourceType;
+    resource: string; //objectId
+    principal_type: AccessControlPrincipalType;
+    principal: string; //objectId
+    tags?: string[];
+    expires_at?: string;
+    created_at?: string;
+    updated_at?: string;
+    id: string;
+}
+
+export interface ACECreatePayload extends
+    Omit<AccessControlEntry, "created_at" | "updated_at" | "id"> {
+}
+
+export interface ACEUpdatePayload extends Partial<ACECreatePayload> {
+}
+
+
+export interface AcesQueryOptions {
+
+    level?: 'resource' | 'project' | 'projects' | 'account'
+    resource?: string
+    principal?: string
+    role?: string
+    type?: AccessControlResourceType
+
+}

package/src/analytics.ts

@@ -0,0 +1,106 @@
+
+export interface AnalyticsAxis {
+    environment?: string;
+    project?: string;
+    interactions?: string[];
+    models?: string[];
+    status?: string[];
+    tags?: string[];
+    selectedOnly?: boolean;
+}
+
+export interface RunAnalyticsQuery {
+
+    /** filters to apply to the query */
+    filterBy: AnalyticsAxis;
+
+    /** The field to group by */
+    groupBy?: RunAnalyticsGroupBy
+
+    /** The start date of the query in EPOCH format */
+    from?: number;
+    /** The end date of the query in EPOCH format */
+    to?: number;
+
+    /** The time resolution unit of the analytics query */
+    resolution?: TimeResolution;
+
+    /** The step size for the resolution (e.g., 4 with resolution='hour' means 4-hour intervals). Defaults to 1. */
+    resolutionStep?: number;
+
+    /** The field to sort by */
+    virtual?: boolean;
+
+}
+
+
+export type RunAnalyticsGroupBy = "interaction" | "modelId" | "project" | "status" | "tags" | "environment";
+
+export type TimeResolution = "minute" | "hour" | "day" | "week" | "month" | "year";
+
+
+export interface RunAnalyticsResult {
+    date: string,
+    timestamp: string,
+    group: string
+    count: number,
+    execution_time: {
+        avg: number,
+        min: number,
+        max: number
+    },
+}
+
+/** Entity with status breakdown (requires compound index for covered queries) */
+export interface EntityStatusCounts {
+    id: string;
+    name: string;
+    /** Total count, or null if query failed */
+    total: number | null;
+    /** Counts by status, values are null if individual status query failed */
+    byStatus: Record<string, number | null>;
+    /** True if any query for this entity failed */
+    hasErrors?: boolean;
+}
+
+/** Lightweight analytics summary using covered queries - scalable to 1M+ documents */
+export interface RunsAnalyticsSummary {
+    /** Total count of runs (from estimatedDocumentCount), null if failed */
+    total: number | null;
+    /** Counts by status, values are null if individual query failed */
+    byStatus: Record<string, number | null>;
+    /** Counts by environment with status breakdown (uses { environment: 1, status: 1 } compound index) */
+    byEnvironment: EntityStatusCounts[];
+    /** Counts by interaction with status breakdown (uses { interaction: 1, status: 1 } compound index) */
+    byInteraction: EntityStatusCounts[];
+    /** Number of queries that failed out of total */
+    queryStats: {
+        total: number;
+        failed: number;
+    };
+}
+
+/** Date range filter for analytics queries (uses created_at field) */
+export interface DateRangeQuery {
+    /** Start date in ISO format, optional (unbounded if omitted) */
+    start?: string;
+    /** End date in ISO format, optional (unbounded if omitted) */
+    end?: string;
+}
+
+/** Token usage for a single environment */
+export interface TokenUsageByEnvironment {
+    environmentId: string;
+    environmentName: string;
+    /** Total prompt tokens, null if query failed */
+    totalPromptTokens: number | null;
+}
+
+/** Summary of token usage by environment (requires { environment: 1, created_at: -1, "token_use.prompt": 1 } index) */
+export interface TokenUsageSummary {
+    byEnvironment: TokenUsageByEnvironment[];
+    queryStats: {
+        total: number;
+        failed: number;
+    };
+}

package/src/apikey.ts

@@ -0,0 +1,116 @@
+import { UserGroupRef } from "./group.js";
+import { ProjectRef, ProjectRoles } from "./project.js";
+import { AccountRef } from "./user.js";
+
+export enum ApiKeyTypes {
+    secret = "sk",
+}
+export interface ApiKey {
+    id: string;
+    name: string;
+    type: ApiKeyTypes;
+    role: ProjectRoles;
+    maskedValue?: string; //masked value
+    account: string; // the account id
+    project: ProjectRef; // the project id if any
+    enabled: boolean;
+    created_by: string;
+    updated_by: string;
+    created_at: Date;
+    updated_at: Date;
+    expires_at?: Date; // in case of public key only
+}
+
+export interface CreateOrUpdateApiKeyPayload extends Partial<ApiKey> {}
+
+export interface ApiKeyWithValue extends Omit<ApiKey, "maskedValue"> {
+    value: string;
+}
+
+export interface CreatePublicKeyPayload {
+    name?: string;
+    projectId?: string;
+    ttl?: number;
+}
+
+export interface AuthTokenResponse {
+    token: string;
+}
+
+export interface AuthTokenPayload {
+    sub: string;
+    name: string;
+    email?: string;
+    picture?: string;
+
+    type: PrincipalType;
+    account: AccountRef;
+
+    account_roles: ProjectRoles[];
+    accounts: AccountRef[];
+
+    project?: ProjectRef;
+    project_roles?: ProjectRoles[];
+
+    /**
+     * The app names enabled for this token. Defaults to an empty array if no apps are enabled.
+     */
+    apps: string[];
+
+    /**
+     * The user ID (if any) attached to the token.
+     * This is set when the token is a user token or an agent token running as a user.
+     * Not set for impersonating tokens like project tokens.
+     */
+    user_id?: string;
+
+    /** groups */
+    groups?: UserGroupRef[]; //group ids
+
+    /**
+     * API endpoints information to be used with this token.
+     * Either a n API domain like 'api.vertesia.io' | 'api-preview.vertesia.io' | 'api-staging.vertesia.io' | 'local'
+     * or explicit studio, store, and token URLs.
+     */
+    endpoints?:
+        | string
+        | {
+              studio: string;
+              store: string;
+              token?: string;
+          };
+
+    iss: string; //issuer
+    aud: string; //audience
+    exp: number; //expires in (EPOC seconds)
+    tags?: string[]; //tags
+
+    permissions?: string[]; //permissions
+    scopes?: string[]; //scopes
+
+    /**
+     * Service caller information for agent and service account tokens.
+     * Contains audit information about who/what initiated the token request.
+     * For agent tokens, includes `onBehalfOf` with the original user's token payload.
+     */
+    service_caller?: {
+        /** The principal that requested the token (e.g., service account identity) */
+        id?: string;
+        name?: string;
+        email?: string;
+        /**
+         * For agent tokens: the verified token payload of the user/apikey the agent acts on behalf of.
+         * Contains the original user's name, email, picture, user_id, etc.
+         */
+        onBehalfOf?: AuthTokenPayload;
+        [key: string]: unknown;
+    };
+}
+
+export enum PrincipalType {
+    User = "user",
+    Group = "group",
+    ApiKey = "apikey",
+    ServiceAccount = "service_account",
+    Agent = "agent",
+}

package/src/apps.ts

@@ -0,0 +1,296 @@
+import { JSONSchema } from "@llumiverse/common";
+
+export interface AppUIConfig {
+    /**
+     * The source URL of the app. The src can be a template which contain
+     * a variable named `buildId` which will be replaced with the current build id.
+     * For example: `/plugins/vertesia-review-center-${buildId}`
+     */
+    src: string;
+    /**
+     * The isolation strategy. If not specified it defaults to shadow
+     * - shadow - use Shadow DOM to fully isolate the plugin from the host.
+     * - css - use CSS processing (like prefixing or other isolation techniques). Ligther but plugins may conflict with the host
+     */
+    isolation?: "shadow" | "css";
+}
+
+/**
+ * Authentication type for tool collections
+ */
+export type ToolCollectionAuthType = "oauth" | "other";
+
+/**
+ * Tool collection type
+ */
+export type ToolCollectionType = "mcp" | "vertesia_sdk";
+
+/**
+ * Base tool collection configuration
+ */
+interface BaseToolCollectionObject {
+    /**
+     * The URL endpoint for the tool collection
+     */
+    url: string;
+
+    /**
+     * Optional authentication type required for this tool collection
+     */
+    auth?: ToolCollectionAuthType;
+}
+
+/**
+ * MCP tool collection configuration (requires name, description, and namespace)
+ */
+export interface MCPToolCollectionObject extends BaseToolCollectionObject {
+    type: "mcp";
+
+    /**
+     * Name for the tool collection.
+     * Used as an identifier for the collection (e.g., for OAuth authentication).
+     */
+    name: string;
+
+    /**
+     * Description for the tool collection.
+     * Helps users understand what tools this collection provides.
+     */
+    description: string;
+
+    /**
+     * Prefix to use for tool names from this collection.
+     * Provides clean, readable tool names (e.g., "jira" instead of "https://mcp.atlassian.com/v1/mcp")
+     */
+    namespace: string;
+}
+
+/**
+ * Vertesia SDK tool collection configuration
+ */
+export interface VertesiaSDKToolCollectionObject extends BaseToolCollectionObject {
+    type: "vertesia_sdk";
+
+    /**
+     * Optional namespace to use for tool names from this collection.
+     * If not provided, the tool server default will be used.
+     */
+    namespace?: string;
+
+    /**
+     * Optional name for the tool collection.
+     * If not provided, the tool server default will be used.
+     */
+    name?: string;
+
+    /**
+     * Optional description for the tool collection.
+     * If not provided, the tool server default will be used.
+     */
+    description?: string;
+}
+
+/**
+ * Tool collection configuration (object format)
+ */
+export type ToolCollectionObject = MCPToolCollectionObject | VertesiaSDKToolCollectionObject;
+
+/**
+ * Tool collection can be either:
+ * - A string URL (legacy format, with "mcp:" prefix for MCP servers)
+ * - An object with url, type, and optional auth (new format)
+ */
+export type ToolCollection = string | ToolCollectionObject;
+
+/**
+ * Normalizes a tool collection to the object format.
+ * Handles backward compatibility with string URLs.
+ *
+ * @param collection - String URL or ToolCollectionObject
+ * @returns Normalized ToolCollectionObject
+ */
+export function normalizeToolCollection(collection: ToolCollection): ToolCollectionObject {
+    if (typeof collection === 'string') {
+        // Legacy string format
+        if (collection.startsWith('mcp:')) {
+            const url = collection.substring('mcp:'.length);
+            // For legacy MCP strings, derive name and prefix from URL
+            const urlObj = new URL(url);
+            const name = urlObj.hostname.replace(/\./g, '-');
+            return {
+                url,
+                type: 'mcp',
+                name,
+                description: `MCP server at ${url}`,
+                namespace: name
+            };
+        }
+        return {
+            url: collection,
+            type: 'vertesia_sdk'
+        };
+    }
+    // Already in object format
+    return collection;
+}
+
+export interface AppManifestData {
+    /**
+     * The name of the app, used as the id in the system.
+     * Must be in kebab case (e.g. my-app).
+     */
+    name: string;
+
+    /**
+     * Visibility level of the app:
+     * - "public": visible to all accounts
+     * - "private": visible only to the owning account
+     * - "vertesia": visible only to Vertesia team members (any project)
+     */
+    visibility: "public" | "private" | "vertesia";
+
+    title: string;
+    description: string;
+    publisher: string;
+
+    /**
+     * A svg icon for the app.
+     */
+    icon?: string;
+
+    /**
+     * A color name to be used as the color of the app card (e.g. blue, red, green, etc.)
+     * If not specified a random color will be picked.
+     */
+    color?: string;
+
+    status: "beta" | "stable" | "deprecated"
+
+    ui?: AppUIConfig
+
+    /**
+     * A list of tool collections endpoints to be used by this app.
+     * A tools collection endpoint is an URL which may end with a `?import` query string.
+     * If the `?import` query string is used the tool will be imported as a javascript module and not executed through a POST on the collections endpoint.
+     */
+    tool_collections?: ToolCollection[]
+
+    /**
+     * An URL providing interactions definitions in JSON format.
+     * The URL must provide 2 endpoints:
+     * 1. GET URL - must return a JSON array with the list of interactions (as AppInteractionRef[])
+     * 2. GET URL/{interaction_name} - must return the full interaction definition for the specified interaction.
+     */
+    interactions?: string;
+
+    /**
+     * A JSON chema for the app installation settings.
+     */
+    settings_schema?: JSONSchema;
+}
+export interface AppManifest extends AppManifestData {
+    id: string;
+    account: string;
+    created_at: string;
+    updated_at: string;
+}
+
+export interface AppInstallation {
+    id: string;
+    project: string; // the project where the app is installed
+    manifest: string; // the app manifest
+    settings?: Record<string, any>; // settings for the app installation
+    created_at: string;
+    updated_at: string;
+}
+
+export interface AppInstallationWithManifest extends Omit<AppInstallation, 'manifest'> {
+    manifest: AppManifest; // the app manifest data
+}
+
+export interface AppInstallationPayload {
+    app_id: string,
+    settings?: Record<string, any>
+}
+
+export type AppInstallationKind = 'ui' | 'tools' | 'all';
+
+/**
+ * A description of the tools provided by an app
+ */
+export interface AppToolCollection {
+    /**
+     * The collection name
+     */
+    name: string;
+
+    /**
+     * Optional collection description
+     */
+    description?: string;
+
+    /**
+     * the tools provided by this collection
+     */
+    tools: { name: string, description?: string }[]
+}
+
+/**
+ * Information about a tool and its associated app installation.
+ * Used to look up which app provides a specific tool.
+ */
+export interface ProjectToolInfo {
+    /**
+     * The tool name
+     */
+    tool_name: string;
+
+    /**
+     * Optional tool description
+     */
+    tool_description?: string;
+
+    /**
+     * The app name that provides this tool
+     */
+    app_name: string;
+
+    /**
+     * The app installation ID
+     */
+    app_install_id: string;
+
+    /**
+     * The app installation settings.
+     * Only included for agent tokens, not user tokens (security: may contain API keys).
+     */
+    settings?: Record<string, any>;
+}
+
+/**
+ * OAuth authentication status for an MCP tool collection
+ */
+export interface OAuthAuthStatus {
+    collection_name: string;
+    authenticated: boolean;
+    mcp_server_url: string;
+    expires_at?: string;
+    scope?: string;
+}
+
+/**
+ * Response from OAuth authorization endpoint
+ */
+export interface OAuthAuthorizeResponse {
+    authorization_url: string;
+    state: string;
+}
+
+/**
+ * Response from OAuth metadata endpoint
+ */
+export interface OAuthMetadataResponse {
+    collection_name: string;
+    mcp_server_url: string;
+    metadata: any;
+}

package/src/ask-user.ts

@@ -0,0 +1,35 @@
+/**
+ * Types for ask_user tool UX configuration.
+ * These types enable the model to transmit structured UX parameters
+ * that render as interactive widgets instead of plain text.
+ */
+
+/** Option for user selection in ask_user widget */
+export interface AskUserOption {
+    /** Unique identifier returned when this option is selected */
+    id: string;
+    /** Display text for the option */
+    label: string;
+    /** Optional tooltip/description shown on hover */
+    description?: string;
+}
+
+/** UX configuration for ask_user messages */
+export interface AskUserUxConfig {
+    /** Predefined options for the user to select from */
+    options?: AskUserOption[];
+    /** Visual style variant */
+    variant?: 'default' | 'warning' | 'info' | 'success';
+    /** Allow selecting multiple options (renders checkboxes instead of buttons) */
+    multiSelect?: boolean;
+    /** Show text input for free-form response */
+    allowFreeResponse?: boolean;
+    /** Placeholder text for free-form input */
+    placeholder?: string;
+}
+
+/** Message details structure for REQUEST_INPUT messages with UX config */
+export interface AskUserMessageDetails {
+    /** UX configuration for rendering the ask_user widget */
+    ux?: AskUserUxConfig;
+}