@vertesia/common 1.0.0-dev.20260203.130115Z → 1.0.0-dev.20260227.104700Z

package/src/apps.ts

@@ -2,6 +2,20 @@ import { JSONSchema, ToolDefinition } from "@llumiverse/common";
 import { CatalogInteractionRef } from "./interaction.js";
 import { InCodeTypeDefinition } from "./store/index.js";
 
+/**
+ * Additional navigation item for an app's UI configuration.
+ * Used in AppUIConfig.navigation to define sidebar navigation entries in CompositeApp shell contexts.
+ * Icon values are Lucide icon component names or SVG content strings.
+ */
+export interface AppUINavItem {
+    /** Display label */
+    label: string;
+    /** Lucide icon name or SVG content string */
+    icon: string;
+    /** Route path relative to app base */
+    route: string;
+}
+
 export interface AppUIConfig {
     /**
      * The source URL of the app. The src can be a template which contain
@@ -15,6 +29,18 @@ export interface AppUIConfig {
      * - css - use CSS processing (like prefixing or other isolation techniques). Ligther but plugins may conflict with the host
      */
     isolation?: "shadow" | "css";
+    /**
+     * Navigation items for the app's sidebar UI.
+     * Only applicable for apps with UI capability in shell contexts (ie. CompositeApp shell).
+     */
+    navigation?: AppUINavItem[];
+    /**
+     * Where this app's UI can be displayed.
+     * - 'app_portal': Available in the main app portal (standalone)
+     * - 'composite_app': Available within a CompositeApp shell
+     * Defaults to ['app_portal', 'composite_app'] for new apps.
+     */
+    available_in?: AppAvailableIn[];
 }
 
 /**
@@ -141,6 +167,12 @@ export function normalizeToolCollection(collection: ToolCollection): ToolCollect
  * Tool definition with optional activation control for agent exposure.
  */
 export interface AgentToolDefinition extends ToolDefinition {
+    /**
+     * The tool execution URL. It can be an absolute URL or a path in which case the URL is obtained 
+     * using the base URL of the tool server API. Ex: http://tool-server.com/api/
+     * Example of relative URLs: "tools/my-tool-collection" or "/api/tools/my-tool-collection"
+     */
+    url?: string;
     /**
      * The tool category if any - for UI purposes.
      */
@@ -158,7 +190,8 @@ export interface AgentToolDefinition extends ToolDefinition {
     related_tools?: string[];
 }
 
-export type AppCapabilities = 'ui' | 'tools' | 'interactions' | 'types';
+export type AppCapabilities = 'ui' | 'tools' | 'interactions' | 'types' | 'templates';
+export type AppAvailableIn = 'app_portal' | 'composite_app';
 export interface AppManifestData {
     /**
      * The name of the app, used as the id in the system.
@@ -246,7 +279,7 @@ export interface AppManifestData {
      */
     endpoint?: string;
 }
-export type AppPackageScope = 'ui' | 'tools' | 'interactions' | 'types' | 'settings' | 'all';
+export type AppPackageScope = 'ui' | 'tools' | 'interactions' | 'types' | 'templates' | 'settings' | 'widgets' | 'all';
 export interface AppPackage {
     /**
      * The UI configuration of the app
@@ -268,12 +301,52 @@ export interface AppPackage {
      */
     types?: InCodeTypeDefinition[];
 
+    /**
+     * Templates provided by the app.
+     */
+    templates?: RenderingTemplateDefinitionRef[];
+
+    /**
+     * Widgets provided by the app.
+     */
+    widgets?: Record<string, AppWidgetInfo>;
+
     /**
      * A JSON chema for the app installation settings.
      */
     settings_schema?: JSONSchema;
 }
 
+export interface AppWidgetInfo {
+    collection: string;
+    skill: string;
+    url: string;
+}
+
+export interface RenderingTemplateDefinition {
+    /** Unique template id: "collection:name" */
+    id: string;
+    /** Unique template name (kebab-case) */
+    name: string;
+    /** Display title */
+    title?: string;
+    /** Short description */
+    description: string;
+    /** Template type */
+    type: 'presentation' | 'document';
+    /** Tags for categorization */
+    tags?: string[];
+    /** Absolute paths to asset files */
+    assets: string[];
+    /** The template instructions (markdown) */
+    instructions: string;
+}
+
+export type RenderingTemplateDefinitionRef = Omit<RenderingTemplateDefinition, 'instructions'> & {
+    /** Absolute API path to fetch the full template definition */
+    path: string;
+};
+
 export interface AppManifest extends AppManifestData {
     id: string;
     account: string;
@@ -380,3 +453,121 @@ export interface OAuthMetadataResponse {
     mcp_server_url: string;
     metadata: any;
 }
+
+// ============================================================================
+// CompositeApp Shell Configuration Types
+// These types define the configuration for a CompositeApp shell that combines
+// multiple apps into a unified experience with shared navigation and branding.
+// ============================================================================
+
+/**
+ * App navigation item display overrides.
+ * Allows customizing individual nav items for an app installation within the CompositeApp shell.
+ */
+export interface CompositeAppNavItemOverride {
+    /** Used as identifier to match the nav item to override -- does not change route path */
+    route: string;
+    /** Hide this nav item from the sidebar */
+    hidden?: boolean;
+    /** Override the displayed nav item label */
+    label?: string;
+    /** Override the displayed nav item icon (Lucide icon name or SVG content string) */
+    icon?: string;
+    //TODO: Set permissions for routes
+}
+
+/**
+ * Configuration entry for an individual app in the CompositeApp shell.
+ * References an app installation by name and allows customizing its appearance.
+ */
+export interface CompositeAppEntry {
+    /** App installation name (must match an installed app) */
+    appName: string;
+    /** Override the label displayed for the app */
+    labelOverride?: string;
+    /** Override the icon displayed for the app (Lucide icon name or SVG content string) */
+    iconOverride?: string;
+    /** Overrides for navigation items provided by the app */
+    navigationOverrides?: CompositeAppNavItemOverride[];
+}
+
+/**
+ * Logo overrides for the CompositeApp shell header.
+ * When provided, these URLs replace the default Vertesia logo.
+ */
+export interface CompositeAppLogoOverrides {
+    /** URL for light mode logo (overrides default Vertesia logo) */
+    lightModeUrl?: string;
+    /** URL for dark mode logo (overrides default Vertesia logo) */
+    darkModeUrl?: string;
+}
+
+
+/**
+ * Message banner overrides for the shell header.
+*/
+export type CompositeAppMessageStyle = 'foreground' | 'info' | 'success' | 'attention' | 'destructive';
+export interface CompositeAppMessageOverrides {
+    /** Message text to display */
+    text?: string;
+    /** Whether the message is visible (defaults to true) */
+    visible?: boolean;
+    /** Text color style. Uses semantic colors */
+    style?: CompositeAppMessageStyle;
+}
+
+/**
+ * Switcher visibility overrides for the CompositeApp header.
+ */
+export interface CompositeAppSwitchersOverrides {
+    /** Whether to show the organization switcher (defaults to true) */
+    showOrganization?: boolean;
+    /** Whether to show the project switcher (defaults to true) */
+    showProject?: boolean;
+}
+
+/**
+ * Card display overrides for the CompositeApp in the App Portal.
+ * Similar to AppManifest display properties, but specific to the CompositeApp card.
+ * Allows customers to customize the app portal card (not otherwise possible if using a
+ * shared, Vertesia-managed manifest across accounts).
+ */
+export interface CompositeAppCardOverrides {
+    /** Whether to show the CompositeApp card in App Portal (default: false) */
+    visible?: boolean;
+    /** Override the card label (default: "Composite App") */
+    label?: string;
+    /** Override the card description */
+    description?: string;
+    /** Override the card icon (Lucide icon name or SVG content string) */
+    icon?: string;
+    /** Override the card color (e.g., "blue", "red", "purple") */
+    color?: string;
+}
+
+/**
+ * CompositeApp shell configuration.
+ * This is the main configuration interface for storing CompositeApp settings.
+ * Used as the MongoDB model for persisting CompositeApp configurations.
+ */
+export interface CompositeAppConfig {
+    /**
+     * The unique identifier for this CompositeApp configuration 
+     * Undefined if the configuration doesn't exists yet.
+    */
+    id?: string;
+    /** The project this CompositeApp belongs to */
+    project: string;
+    /** Card display overrides (includes visibility) */
+    card?: CompositeAppCardOverrides;
+    /** Optional logo overrides (replaces default Vertesia logo) */
+    logo?: CompositeAppLogoOverrides;
+    /** Optional message banner overrides */
+    message?: CompositeAppMessageOverrides;
+    /** Optional switcher visibility overrides */
+    switchers?: CompositeAppSwitchersOverrides;
+    /** List of apps to include in the CompositeApp */
+    apps: CompositeAppEntry[];
+}
+
+export type CompositeAppConfigPayload = Partial<Omit<CompositeAppConfig, 'id' | 'project'>>;

package/src/audit-trail.ts

@@ -0,0 +1,61 @@
+export type AuditAction =
+    | 'create'
+    | 'update'
+    | 'delete'
+    | 'bulk_update'
+    | 'bulk_delete'
+    | 'attach'
+    | 'detach'
+    | 'publish'
+    | 'unpublish';
+
+export interface AuditTrailEvent {
+    event_type: 'audit';
+    action: AuditAction;
+    resource_type: string;
+    resource_id: string;
+    timestamp: string;
+    request_id: string;
+    status: number;
+    success: boolean;
+    principal_id: string | null;
+    principal_type: string | null;
+    principal_user_id: string | null;
+    roles: string[];
+    account_id: string | null;
+    project_id: string | null;
+    tenant_id: string | null;
+    account_name: string | null;
+    project_name: string | null;
+}
+
+export interface AuditTrailQuery {
+    /** Filter by action types */
+    actions?: AuditAction[];
+    /** Filter by resource types */
+    resourceTypes?: string[];
+    /** Filter by resource ID */
+    resourceId?: string;
+    /** Filter by principal ID (matches principal_id column — API keys, service accounts) */
+    principalId?: string;
+    /** Filter by principal user ID (matches principal_user_id column — human users) */
+    principalUserId?: string;
+    /** Filter by project ID */
+    projectId?: string;
+    /** Start time (ISO string) */
+    from?: string;
+    /** End time (ISO string) */
+    to?: string;
+    /** Pagination: number of items to return (default 50, max 200) */
+    limit?: number;
+    /** Pagination: offset */
+    offset?: number;
+}
+
+export interface AuditTrailResponse {
+    events: AuditTrailEvent[];
+    /** Whether there are more events after this page */
+    hasNext: boolean;
+    limit: number;
+    offset: number;
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './access-control.js';
 export * from './analytics.js';
+export * from './audit-trail.js';
 export * from './apikey.js';
 export * from './apps.js';
 export * from './ask-user.js';

package/src/integrations.ts

@@ -29,6 +29,14 @@ export interface SerperConfiguration extends IntegrationConfigurationBase {
     url?: string;
 }
 
+export interface ExaConfiguration extends IntegrationConfigurationBase {
+    api_key: string;
+}
+
+export interface LinkupConfiguration extends IntegrationConfigurationBase {
+    api_key: string;
+}
+
 export interface ResendConfiguration extends IntegrationConfigurationBase {
     /** Resend API key for sending emails */
     api_key: string;
@@ -67,6 +75,8 @@ export enum SupportedIntegrations {
     aws = "aws",
     magic_pdf = "magic_pdf",
     serper = "serper",
+    exa = "exa",
+    linkup = "linkup",
     resend = "resend",
     ask_user_webhook = "ask_user_webhook",
 }

package/src/interaction.ts

@@ -9,7 +9,6 @@ import type {
     ToolDefinition,
     ToolUse,
 } from "@llumiverse/common";
-import type { JSONSchema4 } from "json-schema";
 
 import { ExecutionTokenUsage } from "@llumiverse/common";
 
@@ -32,6 +31,7 @@ export interface InteractionExecutionError {
     code: string;
     message: string;
     data?: any;
+    retryable?: boolean;
 }
 
 /**
@@ -41,8 +41,8 @@ export interface InteractionExecutionError {
 export interface ConversationStripOptions {
     /**
      * Number of turns to keep images before stripping them.
-     * - 0: Strip images immediately after each turn (default)
-     * - N > 0: Keep images for N turns before stripping
+     * - 0: Strip images immediately after each turn
+     * - N > 0: Keep images for N turns before stripping (default: 5)
      * - Infinity: Never strip images
      */
     images_after_turns?: number;
@@ -328,7 +328,7 @@ export const InteractionRefWithSchemaPopulate =
     `${InteractionRefPopulate} result_schema`;
 
 export interface InteractionRefWithSchema extends Omit<InteractionRef, "prompts"> {
-    result_schema?: JSONSchema4;
+    result_schema?: JSONSchema;
     prompts?: PromptSegmentDef<PromptTemplateRefWithSchema>[];
 }
 
@@ -401,7 +401,7 @@ export interface InteractionData {
     project: string | ProjectRef;
     tags: string[];
     agent_runner_options?: AgentRunnerOptions;
-    result_schema?: JSONSchema4 | SchemaRef;
+    result_schema?: JSONSchema | SchemaRef;
     environment?: string | ExecutionEnvironmentRef;
     model?: string;
     model_options?: ModelOptions;
@@ -418,7 +418,7 @@ export interface Interaction extends InteractionData {
     visibility: InteractionVisibility;
     version: number;
     test_data?: JSONObject;
-    interaction_schema?: JSONSchema4 | SchemaRef;
+    interaction_schema?: JSONSchema | SchemaRef;
     cache_policy?: CachePolicy;
     prompts: PromptSegmentDef[];
     // only for drafts - when it was last published
@@ -468,7 +468,7 @@ export interface InteractionUpdatePayload
             "result_schema" | "id" | "created_at" | "updated_at" | "created_by" | "updated_by" | "project"
         >
     > {
-    result_schema?: JSONSchema4 | null;
+    result_schema?: JSONSchema | null;
 }
 
 export interface InteractionPublishPayload {
@@ -490,7 +490,7 @@ export interface InteractionExecutionPayload {
     data?: Record<string, any> | `memory:${string}`;
     config?: InteractionExecutionConfiguration;
     //Use null to explicitly state no schema, will not fallback to interaction schema
-    result_schema?: JSONSchema4 | null;
+    result_schema?: JSONSchema | null;
     stream?: boolean;
     do_validate?: boolean;
     tags?: string | string[]; // tags to be added to the execution run
@@ -705,7 +705,7 @@ export interface AsyncConversationExecutionPayload extends AsyncExecutionPayload
     /**
      * The token threshold in thousands (K) for creating checkpoints.
      * If total tokens exceed this value, a checkpoint will be created.
-     * If not specified, default value of 150K tokens will be used.
+     * If not specified, the default is computed from the selected model context window (75%).
      */
     checkpoint_tokens?: number;
 
@@ -926,8 +926,8 @@ export interface BaseExecutionRun<P = any> {
     interaction_code?: string; // Interaction code name in case of in-code interaction (not stored in the DB as an Interaction document)
     /** Environment reference - populated with full object in API responses */
     environment: ExecutionEnvironmentRef;
-    modelId: string;
-    result_schema: JSONSchema4;
+    modelId?: string; //Can be undefined for virtual environments. In most cases should be defined.
+    result_schema: JSONSchema;
     ttl: number;
     status: ExecutionRunStatus;
     finish_reason?: string;
@@ -1186,4 +1186,4 @@ export interface BuiltinToolsCatalogResponse {
      * Total number of tools in the catalog
      */
     total_tools: number;
-}
+}

package/src/project.ts

@@ -1,4 +1,5 @@
 import { SupportedIntegrations } from "./integrations.js";
+import { ContentObjectTypeRef } from "./store/store.js";
 import { AccountRef } from "./user.js";
 
 export interface ICreateProjectPayload {
@@ -339,6 +340,231 @@ export interface IndexingStatusResponse {
     };
 }
 
+// ============================================================================
+// Internal indexing types (used by Temporal workflows)
+// ============================================================================
+
+/**
+ * Document data structure for Elasticsearch indexing
+ */
+export interface ElasticsearchDocumentData {
+    name?: string;
+    text?: string;
+    properties?: Record<string, unknown>;
+    status?: string;
+    type?: ContentObjectTypeRef;
+    security?: {
+        'content:read'?: string[];
+        'content:write'?: string[];
+        'content:delete'?: string[];
+    };
+    revision?: {
+        head?: boolean;
+        root?: string;
+    };
+    embeddings_text?: number[];
+    embeddings_image?: number[];
+    embeddings_properties?: number[];
+    created_at?: Date | string;
+    updated_at?: Date | string;
+}
+
+/**
+ * Result from bulk indexing
+ */
+export interface BulkIndexResult {
+    successful: number;
+    failed: number;
+}
+
+/**
+ * Result from creating a reindex target
+ */
+export interface CreateReindexTargetResult {
+    created: boolean;
+    indexName: string;
+    aliasName: string;
+    version: number;
+}
+
+/**
+ * Result from getting reindex range
+ */
+export interface ReindexRangeResult {
+    first: string | null;
+    last: string | null;
+    count: number;
+}
+
+/**
+ * Result from fetching a batch
+ */
+export interface FetchBatchResult {
+    documents: Array<{
+        id: string;
+        document: ElasticsearchDocumentData;
+    }>;
+    nextCursor: string | null;
+    done: boolean;
+}
+
+/**
+ * Result from indexing a batch
+ */
+export interface IndexBatchResult {
+    successful: number;
+    failed: number;
+    processed: number;
+    nextCursor: string | null;
+    done: boolean;
+}
+
+/**
+ * Result from triggering a reindex
+ */
+export interface TriggerReindexResult {
+    status: string;
+    workflow?: string;
+    workflowId?: string;
+    runId?: string;
+    objectCount?: number;
+    reason?: string;
+    enabled?: boolean;
+}
+
+/**
+ * Elasticsearch index statistics
+ */
+export interface ElasticsearchIndexStats {
+    enabled: boolean;
+    exists?: boolean;
+    documentCount?: number;
+    sizeInBytes?: number;
+    indexName?: string;
+    aliasName?: string;
+}
+
+/**
+ * Embedding configuration for a single type
+ */
+export interface EmbeddingTypeConfig {
+    environment?: string;
+    dimensions?: number;
+    model?: string;
+    provider?: string;
+    enabled?: boolean;
+}
+
+/**
+ * Detailed index configuration
+ */
+export interface IndexConfiguration {
+    enabled: boolean;
+    exists?: boolean;
+    indexName?: string;
+    aliasName?: string;
+    version?: number;
+    documentCount?: number;
+    sizeInBytes?: number;
+    embeddingDimensions?: {
+        text?: number;
+        image?: number;
+        properties?: number;
+    };
+    /** ISO 639-1 language code for text analysis */
+    language?: string;
+    fieldMappings?: Record<string, unknown>;
+    projectEmbeddingsConfig?: {
+        text?: EmbeddingTypeConfig;
+        image?: EmbeddingTypeConfig;
+        properties?: EmbeddingTypeConfig;
+    };
+    createdAt?: Date | null;
+}
+
+/**
+ * Supported languages for full-text search with their display names.
+ * Maps ISO 639-1 codes to human-readable language names.
+ */
+export const SUPPORTED_SEARCH_LANGUAGES: Record<string, string> = {
+    en: 'English',
+    zh: 'Chinese',
+    es: 'Spanish',
+    hi: 'Hindi',
+    ar: 'Arabic',
+    pt: 'Portuguese',
+    bn: 'Bengali',
+    ru: 'Russian',
+    ja: 'Japanese',
+    de: 'German',
+    fr: 'French',
+    ko: 'Korean',
+    it: 'Italian',
+    tr: 'Turkish',
+    vi: 'Vietnamese',
+    pl: 'Polish',
+    uk: 'Ukrainian',
+    nl: 'Dutch',
+    th: 'Thai',
+    el: 'Greek',
+    cs: 'Czech',
+    sv: 'Swedish',
+    ro: 'Romanian',
+    hu: 'Hungarian',
+    da: 'Danish',
+    fi: 'Finnish',
+    no: 'Norwegian',
+    he: 'Hebrew',
+    id: 'Indonesian',
+    fa: 'Persian',
+};
+
+/**
+ * Result from fetching documents by IDs
+ */
+export interface FetchDocumentsByIdsResult {
+    documents: Array<{
+        id: string;
+        document: ElasticsearchDocumentData;
+    }>;
+    notFound: string[];
+}
+
+/**
+ * Result from bulk delete
+ */
+export interface BulkDeleteResult {
+    successful: number;
+    failed: number;
+}
+
+/**
+ * Result from ensure index operation
+ */
+export interface EnsureIndexResult {
+    created: boolean;
+    recreated?: boolean;
+    existed?: boolean;
+    enabled?: boolean;
+    status?: string;
+    dimensions?: {
+        text?: number;
+        image?: number;
+        properties?: number;
+    };
+    language?: string;
+}
+
+/**
+ * Result from swap alias operation
+ */
+export interface SwapAliasResult {
+    swapped: boolean;
+    aliasName?: string;
+    newIndexName?: string;
+    reason?: string;
+}
+
 export interface ProjectIntegrationListEntry {
     id: SupportedIntegrations;
     enabled: boolean;

package/src/prompt.ts

@@ -1,6 +1,5 @@
-import type { JSONObject } from "@llumiverse/common";
+import type { JSONObject, JSONSchema } from "@llumiverse/common";
 import { PromptRole } from "@llumiverse/common";
-import type { JSONSchema4 } from "json-schema";
 import { ProjectRef } from "./project.js";
 
 export interface ChatPromptSchema {
@@ -49,7 +48,7 @@ export interface PromptTemplateRef {
 }
 
 export interface PromptTemplateRefWithSchema extends PromptTemplateRef {
-    inputSchema?: JSONSchema4;
+    inputSchema?: JSONSchema;
 }
 
 export enum TemplateType {
@@ -61,7 +60,7 @@ export interface ExecutablePromptTemplate {
     role: PromptRole;
     content: string;
     content_type: TemplateType;
-    inputSchema?: JSONSchema4;
+    inputSchema?: JSONSchema;
 }
 export interface PromptTemplate extends ExecutablePromptTemplate {
     id: string;