@vertesia/common 1.1.0-dev.20260427.060440Z → 1.1.1-dev.20260505.160410Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/common",
-  "version": "1.1.0-dev.20260427.060440Z",
+  "version": "1.1.1-dev.20260505.160410Z",
   "license": "Apache-2.0",
   "type": "module",
   "types": "./lib/types/index.d.ts",
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "ajv": "^8.17.1",
-    "@llumiverse/common": "1.1.0-dev.20260427.054520Z"
+    "@llumiverse/common": "1.1.1-dev.20260505.151157Z"
   },
   "repository": {
     "type": "git",

package/src/access-control.ts

@@ -88,6 +88,10 @@ export interface ACECreatePayload extends
 export interface ACEUpdatePayload extends Partial<ACECreatePayload> {
 }
 
+export interface RoleDefinition {
+    name: ProjectRoles;
+    permissions: Permission[];
+}
 
 export interface AcesQueryOptions {
 

package/src/apikey.ts

@@ -28,6 +28,10 @@ export interface ApiKeyWithValue extends Omit<ApiKey, "maskedValue"> {
     value: string;
 }
 
+export interface ApiKeyReadResponse extends ApiKey {
+    value?: string;
+}
+
 export interface CreatePublicKeyPayload {
     name?: string;
     projectId?: string;
@@ -38,6 +42,14 @@ export interface AuthTokenResponse {
     token: string;
 }
 
+export interface ApiKeyListQuery {
+    level?: 'account' | 'project';
+}
+
+export interface ApiKeyReadQuery {
+    withValue?: boolean;
+}
+
 export interface AuthTokenPayload {
     sub: string;
     name: string;

package/src/apps.ts

@@ -1,4 +1,4 @@
-import { JSONSchema, ToolDefinition } from "@llumiverse/common";
+import { JSONObject, JSONSchema, ToolDefinition } from "@llumiverse/common";
 import { CatalogInteractionRef } from "./interaction.js";
 import { DSLActivityOptions, InCodeTypeDefinition } from "./store/index.js";
 
@@ -59,6 +59,16 @@ export interface AppUIConfig {
     available_in?: AppAvailableIn[];
 }
 
+export interface AppInstallationProjectsQuery {
+    name?: string;
+    id?: string;
+}
+
+export interface AppInstallationsQuery {
+    kind?: AppInstallationKind;
+    available_in?: AppAvailableIn;
+}
+
 /**
  * Authentication type for tool collections
  */
@@ -643,6 +653,24 @@ export interface AppInstallationWithManifest extends Omit<AppInstallation, 'mani
     oauth_collection_ids?: string[];
 }
 
+export interface AppInstallationListEntry extends Omit<AppInstallation, 'manifest'> {
+    manifest: AppManifest | null;
+    oauth_collection_ids?: string[];
+}
+
+export interface OrphanedAppInstallation extends Omit<AppInstallation, 'manifest'> {
+    manifest: null;
+}
+
+export interface OAuthClientCredentials {
+    client_id?: string;
+    client_secret?: string;
+    scopes?: string[];
+}
+
+export type AppOAuthCollectionParams = Record<string, OAuthClientCredentials>;
+export type AppOAuthProviderParams = Record<string, OAuthClientCredentials>;
+
 export interface AppInstallationPayload {
     app_id: string;
     settings?: Record<string, any>;
@@ -651,13 +679,17 @@ export interface AppInstallationPayload {
      * Legacy callers may still use collection.name for older manifests.
      * Collected from the user at install time for collections with oauth_config.required_at_install.
      */
-    oauth_params?: Record<string, { client_id?: string; client_secret?: string; scopes?: string[] }>;
+    oauth_params?: AppOAuthCollectionParams;
     /**
      * OAuth credentials for named providers, keyed by the provider key from oauth_providers.
      * Collected from the user at install time for providers with required_at_install.
      * Separate from oauth_params to avoid key collisions between provider keys and collection ids.
      */
-    oauth_provider_params?: Record<string, { client_id?: string; client_secret?: string; scopes?: string[] }>;
+    oauth_provider_params?: AppOAuthProviderParams;
+}
+
+export interface UpdateAppInstallationToolAllowlistPayload {
+    tool_allowlist: string[] | null;
 }
 
 export type AppInstallationKind = 'ui' | 'tools' | 'all';
@@ -766,7 +798,7 @@ export interface OAuthMetadataResponse {
     collection_id: string;
     collection_name: string;
     mcp_server_url: string;
-    metadata: any;
+    metadata: JSONObject;
 }
 
 // ============================================================================

package/src/common.ts

@@ -15,6 +15,28 @@ export interface GenericCommandResponse {
     details?: any;
 }
 
+export interface DeleteByIdResult {
+    id: string;
+}
+
+export interface DeleteCountResult {
+    id: string;
+    count: number;
+}
+
+export interface SuccessResponse {
+    success: true;
+}
+
+export interface DeleteOperationResult {
+    acknowledged: boolean;
+    deletedCount: number;
+}
+
+export interface CountResult {
+    count: number;
+}
+
 export interface BulkOperationPayload {
     /**
      * The operation name
@@ -58,3 +80,9 @@ export interface BulkObjectCreateResult extends BulkOperationResult {
     /** Objects that failed to create */
     failed: { external_id?: string; index: number; error: string }[];
 }
+
+export type BulkOperationResponse =
+    | BulkOperationResult
+    | BulkObjectCreateResult
+    | BulkObjectUpdateResult
+    | BulkObjectDeleteResult;

package/src/cost-analytics.ts

@@ -39,6 +39,12 @@ export interface CostAnalyticsQuery {
     run_id?: string;
     /** Filter by agent run ID */
     agent_run_id?: string;
+    /** Filter by saved-interaction ObjectId */
+    interaction_id?: string;
+    /** Filter by in-code interaction code (e.g. "@sys:chat") */
+    interaction_code?: string;
+    /** Filter by principal (bare user or API key id; matched against the suffix of principal_id) */
+    principal_id?: string;
     /** Filter by account ID (set automatically by server) */
     account_id?: string;
     /** Scope: 'project' (default, current project) or 'org' (all projects in account) */
@@ -49,6 +55,26 @@ export interface CostAnalyticsQuery {
     no_cache?: boolean;
 }
 
+export interface CostModelPricesQuery {
+    /** Start time (ISO string or epoch ms) */
+    from?: string | number;
+    /** End time (ISO string or epoch ms) */
+    to?: string | number;
+}
+
+export interface CostExportQuery {
+    /** Start time (ISO string or epoch ms) */
+    from?: string | number;
+    /** End time (ISO string or epoch ms) */
+    to?: string | number;
+    /** Scope: 'project' (default, current project) or 'org' (all projects in account) */
+    scope?: 'project' | 'org';
+    /** Filter by project ID (optional, for org scope) */
+    project_id?: string;
+    /** Filter by workflow / agent run ID */
+    workflow_id?: string;
+}
+
 // ============================================================================
 // Response
 // ============================================================================

package/src/data-platform.ts

@@ -299,6 +299,15 @@ export interface DataStoreVersion {
     snapshot_name?: string;
 }
 
+export interface ListDataStoreVersionsQuery {
+    limit?: number;
+    snapshots_only?: boolean;
+}
+
+export interface GetDataStoreTableQuery {
+    sample?: boolean;
+}
+
 // ============================================================================
 // Import Types
 // ============================================================================
@@ -395,6 +404,14 @@ export interface CreateTablesPayload {
     message: string;
 }
 
+export interface QueryValidationPayload {
+    queries: Array<{ name: string; sql: string }>;
+}
+
+export interface BatchQueryPayload {
+    queries: Array<{ name: string; sql: string; limit?: number }>;
+}
+
 /**
  * Schema change operation types.
  */
@@ -518,6 +535,72 @@ export interface QueryResult {
     error?: string;
 }
 
+export interface BatchQueryResultItem extends QueryResult {
+    name: string;
+}
+
+export interface BatchQueryResult {
+    results: BatchQueryResultItem[];
+}
+
+export interface QueryValidationError {
+    query: string;
+    error: string;
+}
+
+export interface QueryValidationResult {
+    valid: boolean;
+    errors: QueryValidationError[];
+}
+
+export interface DataStoreDownloadInfo {
+    url: string;
+    gcs_generation: number;
+    schema_version: string;
+    store_id: string;
+    store_name: string;
+    tables: string[];
+    expires_in: number;
+}
+
+export interface DataStoreArchiveResult {
+    id: string;
+    status: DataStoreStatus;
+}
+
+export type DataStoreSchemaResponse = DataSchema | DataSchemaForAI;
+
+export interface DataStoreTableDetail extends DataTable {
+    sample_data?: Record<string, unknown>[];
+}
+
+export interface DataStoreTableDropResult {
+    dropped: string;
+}
+
+export interface DashboardArchiveResult {
+    id: string;
+    status: DashboardStatus;
+}
+
+export interface DashboardBulkArchiveResult {
+    archived: number;
+    failed: number;
+}
+
+export interface DashboardBulkDeleteResult {
+    deleted: number;
+    failed: number;
+}
+
+export interface DashboardVersioningStatusResponse {
+    versioning_enabled: boolean;
+}
+
+export interface DashboardVersioningPayload {
+    enabled: boolean;
+}
+
 // ============================================================================
 // AI Agent Interface
 // ============================================================================

package/src/environment.ts

@@ -1,4 +1,8 @@
-import type { AIModel, ProviderParams, TextFallbackOptions } from "@llumiverse/common";
+import type {
+    AIModel,
+    ProviderParams,
+    TextFallbackOptions
+} from "@llumiverse/common";
 import { ProviderList, Providers } from "@llumiverse/common";
 
 // Virtual providers from studio
@@ -55,6 +59,10 @@ export interface VirtualEnvEntry {
     model: string;
 }
 
+export interface ListEnvironmentsQuery {
+    all?: boolean;
+}
+
 /**
  * Custom configuration for virtual environments
  **/
@@ -121,8 +129,12 @@ export interface ExecutionEnvironmentRef {
 
 export const ExecutionEnvironmentRefPopulate = "id name provider enabled_models default_model endpoint_url allowed_projects account created_at updated_at";
 
-export interface ExecutionEnvironmentCreatePayload extends Omit<ExecutionEnvironment, 'id' | 'account' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'project'> { }
-export interface ExecutionEnvironmentUpdatePayload extends Partial<Omit<ExecutionEnvironment, 'id' | 'account' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by'>> { }
+export interface ExecutionEnvironmentCreatePayload extends Omit<ExecutionEnvironment, 'id' | 'account' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'project' | 'apikey_hint'> { }
+export interface ExecutionEnvironmentUpdatePayload extends Partial<Omit<ExecutionEnvironment, 'id' | 'account' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'apikey_hint'>> { }
+export interface ExecutionEnvironmentConfigUpdatePayload {
+    enabled_models?: AIModel[];
+    config?: MediatorEnvConfig | LoadBalancingEnvConfig;
+}
 
 export interface MigrateInteractionsPayload {
     /**
@@ -144,4 +156,4 @@ export interface MigrateInteractionsPayload {
 export interface MigrateInteractionsResult {
     matched_count: number;
     modified_count: number;
-}
+}

package/src/facets.ts

@@ -42,3 +42,12 @@ export interface FacetNameBucket {
 export interface FacetResult {
     buckets: FacetBucket[]
 }
+
+export interface ComputedFacetBucket {
+    _id: string;
+    count: number;
+}
+
+export type ComputedFacetResponse = Record<string, ComputedFacetBucket[] | number> & {
+    total?: number;
+};

package/src/group.ts

@@ -17,6 +17,18 @@ export interface PopulatesUserGroup extends UserGroup {
     members: UserRef[];
 }
 
+export interface CreateUserGroupPayload {
+    name: string;
+    description?: string;
+    tags?: string[];
+}
+
+export interface UpdateUserGroupPayload {
+    name: string;
+    description?: string;
+    tags?: string[];
+}
+
 export interface UserGroupRef {
     id: string;
     name: string;
@@ -25,4 +37,4 @@ export interface UserGroupRef {
 
 export const UserGroupRefPopulate = 'id name tags description';
 
-export const MEMBERS_GROUP_NAME = 'members';
+export const MEMBERS_GROUP_NAME = 'members';

package/src/index.ts

@@ -19,6 +19,7 @@ export * from './json.js';
 export * from './meters.js';
 export * from './oauth-server.js';
 export * from './model_utility.js';
+export * from './openapi.js';
 export * from './oauth.js';
 export * from './payload.js';
 export * from "./Progress.js";

package/src/integrations.ts

@@ -5,7 +5,9 @@ export interface IntegrationConfigurationBase {
 }
 
 export interface GladiaConfiguration extends IntegrationConfigurationBase {
-    api_key: string;
+    api_key?: string;
+    has_api_key?: boolean;
+    api_key_hint?: string;
     url?: string;
 }
 
@@ -25,27 +27,37 @@ export interface MagicPdfConfiguration extends IntegrationConfigurationBase {
 }
 
 export interface SerperConfiguration extends IntegrationConfigurationBase {
-    api_key: string;
+    api_key?: string;
+    has_api_key?: boolean;
+    api_key_hint?: string;
     url?: string;
 }
 
 export interface ExaConfiguration extends IntegrationConfigurationBase {
-    api_key: string;
+    api_key?: string;
+    has_api_key?: boolean;
+    api_key_hint?: string;
 }
 
 export interface LinkupConfiguration extends IntegrationConfigurationBase {
-    api_key: string;
+    api_key?: string;
+    has_api_key?: boolean;
+    api_key_hint?: string;
 }
 
 export interface ResendConfiguration extends IntegrationConfigurationBase {
     /** Resend API key for sending emails */
-    api_key: string;
+    api_key?: string;
+    has_api_key?: boolean;
+    api_key_hint?: string;
     /** Domain for email (both sending and receiving). Must be verified in Resend. */
     email_domain: string;
     /** Default display name for outgoing emails (e.g., "Vertesia - Project Name") */
     default_from_name?: string;
     /** Webhook secret for validating inbound email webhooks (required for receiving emails) */
-    webhook_secret: string;
+    webhook_secret?: string;
+    has_webhook_secret?: boolean;
+    webhook_secret_hint?: string;
     /** Domains allowed to send emails TO start agents (for inbound validation) */
     allowed_sender_domains?: string[];
     /** Require sender to have project access to start agents via email (default: true) */
@@ -63,6 +75,8 @@ export interface AskUserWebhookConfiguration extends IntegrationConfigurationBas
     webhook_url: string;
     /** Secret for signing webhook payloads (HMAC-SHA256) */
     webhook_secret?: string;
+    has_webhook_secret?: boolean;
+    webhook_secret_hint?: string;
     /** Which events to send: ['requested', 'resolved'] or subset (default: both) */
     events?: ('requested' | 'resolved')[];
     /** Custom headers to include in webhook requests */
@@ -79,4 +93,15 @@ export enum SupportedIntegrations {
     linkup = "linkup",
     resend = "resend",
     ask_user_webhook = "ask_user_webhook",
-}
+}
+
+export type ProjectIntegrationConfig =
+    | GladiaConfiguration
+    | GithubConfiguration
+    | AwsConfiguration
+    | MagicPdfConfiguration
+    | SerperConfiguration
+    | ExaConfiguration
+    | LinkupConfiguration
+    | ResendConfiguration
+    | AskUserWebhookConfiguration;

package/src/interaction.ts

@@ -125,6 +125,30 @@ export interface CatalogInteractionRef {
     description?: string;
 }
 
+export interface CatalogTagQuery {
+    tag?: string;
+}
+
+export interface StoredCatalogInteractionsQuery extends CatalogTagQuery {
+    status?: string;
+    published?: boolean;
+}
+
+export interface ExecuteInteractionByEndpointQuery {
+    tag?: string;
+}
+
+export interface ExecuteInteractionByEndpointHeaders {
+    'x-interaction-tag'?: string;
+}
+
+export interface ResolveInteractionQuery {
+    environment?: string;
+    model?: string;
+    hasImage?: boolean;
+    hasVideo?: boolean;
+}
+
 export interface InCodePrompt {
     role: PromptRole,
     content: string,
@@ -807,6 +831,12 @@ export interface AsyncInteractionExecutionPayload extends AsyncExecutionPayloadB
 
 export type AsyncExecutionPayload = AsyncConversationExecutionPayload | AsyncInteractionExecutionPayload;
 
+export interface AsyncExecutionResult {
+    runId: string;
+    workflowId: string;
+    agentRunId?: string;
+}
+
 /**
  * Telemetry context for streaming mode.
  * Contains info not available in current_state needed to send LlmCallEvent.
@@ -1073,6 +1103,13 @@ export interface InteractionExecutionResult<P = any> extends ExecutionRun<P> {
     options?: StatelessExecutionOptions;
 }
 
+export interface LegacyInteractionExecutionResult<P = any>
+    extends Omit<InteractionExecutionResult<P>, 'result' | 'account' | 'project'> {
+    account: string | AccountRef;
+    project: string | ProjectRef;
+    result?: JSONObject | string | null;
+}
+
 export interface ExecutionRunRef extends Omit<ExecutionRun, "result" | "parameters" | "interaction"> {
     interaction?: InteractionRef;
     interaction_code?: string;
@@ -1118,6 +1155,10 @@ export interface GenerateTestDataPayload {
     config: InteractionExecutionConfiguration;
 }
 
+export interface GeneratedTestDataRecord {
+    [key: string]: unknown;
+}
+
 export interface ImprovePromptPayloadConfig {
     config: InteractionExecutionConfiguration;
 }
@@ -1129,6 +1170,33 @@ export interface ImprovePromptPayload extends ImprovePromptPayloadConfig {
     result_schema?: JSONSchema, // optional interactionr result schema
 }
 
+export interface GeneratedInteractionPromptTemplate {
+    role: 'safety' | 'system' | 'user';
+    name: string;
+    content: string;
+    content_type: 'jst';
+    inputSchema: JSONSchema;
+}
+
+export interface GeneratedInteractionPromptSegment {
+    type: 'template';
+    template: GeneratedInteractionPromptTemplate;
+}
+
+export interface GeneratedInteractionDefinition {
+    name: string;
+    description: string;
+    temperature: number;
+    prompts: GeneratedInteractionPromptSegment[];
+    max_tokens?: number;
+    result_schema: JSONSchema;
+    tags: Array<'generated' | 'agent'>;
+}
+
+export interface PromptImprovementResponse {
+    result: CompletionResult[];
+}
+
 export interface RateLimitRequestPayload {
     interaction: string,
     environment_id?: string,

package/src/oauth-server.ts

@@ -135,7 +135,7 @@ export interface OAuthAuthorizationServerMetadata {
 
 export interface OAuthClientMetadataDocument {
     client_id: string;
-    client_name?: string;
+    client_name: string;
     redirect_uris: string[];
     grant_types?: OAuthGrantType[];
     response_types?: OAuthResponseType[];
@@ -143,6 +143,15 @@ export interface OAuthClientMetadataDocument {
     scope?: string;
     client_uri?: string;
     logo_uri?: string;
+    tos_uri?: string;
+    policy_uri?: string;
+}
+
+export interface OAuthClientDisplayMetadata {
+    client_uri?: string;
+    logo_uri?: string;
+    tos_uri?: string;
+    policy_uri?: string;
 }
 
 export interface OAuthAuthorizeQuery {
@@ -163,6 +172,7 @@ export interface OAuthAuthorizationRequest {
     request_id: string;
     client_id: string;
     client_name: string;
+    client_metadata?: OAuthClientDisplayMetadata;
     client_registration_mode?: OAuthClientRegistrationMode;
     redirect_uri: string;
     redirect_origin: string;

package/src/oauth.ts

@@ -80,6 +80,10 @@ export interface OAuthProvider extends OAuthProviderData {
     id: string;
 }
 
+export interface RevokeOAuthGrantQuery {
+    include_consent?: boolean;
+}
+
 /**
  * Payload for creating an OAuth Provider.
  * The client_secret is accepted as plaintext on create and stored encrypted.
@@ -129,3 +133,12 @@ export interface OAuthProviderAuthorizeResponse {
     state?: string;
     connected?: boolean;
 }
+
+export interface OAuthProviderAccessTokenResponse {
+    access_token: string;
+}
+
+export interface OAuthProviderExchangePayload {
+    code: string;
+    state: string;
+}