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

package/src/audit-trail.ts

@@ -9,6 +9,8 @@ export type AuditAction =
     | 'bulk_delete'
     | 'attach'
     | 'detach'
+    | 'credentials_fill'
+    | 'credentials_totp_generation'
     | 'publish'
     | 'unpublish'
     // Billable operations
@@ -17,11 +19,7 @@ export type AuditAction =
     | 'image_generation';
 
 /** Billable audit actions for cost analytics queries */
-export const BILLABLE_AUDIT_ACTIONS: AuditAction[] = [
-    'inference',
-    'embedding',
-    'image_generation',
-];
+export const BILLABLE_AUDIT_ACTIONS: AuditAction[] = ['inference', 'embedding', 'image_generation'];
 
 /**
  * Generic metering entry attached to audit events.

package/src/browser-credentials.ts

@@ -0,0 +1,133 @@
+export type WebsiteCredentialCapability = 'password' | 'totp' | 'oauth';
+
+export type WebsiteCredentialTotpAlgorithm = 'SHA1' | 'SHA256' | 'SHA512';
+
+export interface WebsiteCredentialWebsite {
+    /**
+     * Hostname this credential is allowed on. Subdomains match.
+     */
+    host: string;
+    /**
+     * Optional login URL used by agents as a hint.
+     */
+    login_url?: string;
+    /**
+     * Optional narrower origin allowlist for this credential.
+     */
+    allowed_origins?: string[];
+}
+
+export interface WebsiteCredentialTotpMetadata {
+    algorithm?: WebsiteCredentialTotpAlgorithm;
+    digits?: 6 | 8;
+    period?: number;
+    issuer?: string;
+    account?: string;
+}
+
+export interface WebsiteCredentialMetadata {
+    name: string;
+    websites: WebsiteCredentialWebsite[];
+    username?: string;
+    username_hint?: string;
+    username_secret?: boolean;
+    properties?: Record<string, unknown>;
+    tags?: string[];
+    enabled?: boolean;
+    capabilities?: WebsiteCredentialCapability[];
+    notes?: string;
+    totp?: WebsiteCredentialTotpMetadata;
+    /**
+     * Optional ISO timestamp after which the credential is no longer usable.
+     * Expired credentials are hidden from lookup and cannot be filled.
+     */
+    expires_at?: string;
+}
+
+export interface WebsiteCredentialRecord {
+    id: string;
+    credential_ref: string;
+    project: string;
+    name: string;
+    websites: WebsiteCredentialWebsite[];
+    username?: string;
+    username_hint?: string;
+    username_secret_enabled: boolean;
+    properties?: Record<string, unknown>;
+    tags?: string[];
+    enabled?: boolean;
+    capabilities?: WebsiteCredentialCapability[];
+    notes?: string;
+    totp_metadata?: WebsiteCredentialTotpMetadata;
+    /**
+     * Optional ISO timestamp after which the credential is no longer usable.
+     * Expired credentials are hidden from lookup and cannot be filled.
+     */
+    expires_at?: string;
+    created_at?: string;
+    updated_at?: string;
+    has_username_secret: boolean;
+    has_password: boolean;
+    has_totp: boolean;
+    has_oauth: boolean;
+    password_hint?: string;
+}
+
+export interface WebsiteCredentialSecretInput {
+    /**
+     * Optional encrypted username. Prefer metadata.username unless the username itself is sensitive.
+     */
+    username?: string;
+    password?: string;
+    totp?: WebsiteCredentialTotpMetadata & {
+        seed: string;
+    };
+    /**
+     * Future OAuth materialization hook. The token itself remains in the OAuth secret store.
+     */
+    oauth?: {
+        provider_id?: string;
+        token_owner?: 'user' | 'project';
+        token_ref?: string;
+    };
+}
+
+export interface CreateWebsiteCredentialRequest extends WebsiteCredentialMetadata {
+    secret?: WebsiteCredentialSecretInput;
+}
+
+export interface UpdateWebsiteCredentialRequest extends Partial<WebsiteCredentialMetadata> {
+    secret?: WebsiteCredentialSecretInput;
+    clear_username_secret?: boolean;
+    clear_password?: boolean;
+    clear_totp?: boolean;
+    clear_oauth?: boolean;
+}
+
+export interface WebsiteCredentialFillTarget {
+    username_target_id?: string;
+    password_target_id?: string;
+    totp_target_id?: string;
+    submit_target_id?: string;
+}
+
+export interface WebsiteCredentialFillRequest extends WebsiteCredentialFillTarget {
+    /**
+     * Browser-use parent workflow id. The API resolves the Daytona sandbox and
+     * observes the current page server-side before decrypting the credential.
+     */
+    browser_workflow_id: string;
+}
+
+export interface WebsiteCredentialFillResponse {
+    ok: boolean;
+    credential_ref: string;
+    url: string;
+    title: string;
+    filled: {
+        username: boolean;
+        password: boolean;
+        totp: boolean;
+        submitted: boolean;
+    };
+}

package/src/channels.ts

@@ -1,4 +1,4 @@
-import { EmailChannel, isEmailChannel, UserChannel } from "./interaction.js";
+import { type EmailChannel, isEmailChannel, type UserChannel } from './interaction.js';
 
 /**
  * Find the email channel from a list of channels.
@@ -22,7 +22,7 @@ export function hasEmailChannel(channels?: UserChannel[]): boolean {
  */
 export function updateEmailChannel(
     channels: UserChannel[] | undefined,
-    updates: Partial<Omit<EmailChannel, "type">>
+    updates: Partial<Omit<EmailChannel, 'type'>>,
 ): UserChannel[] {
     const existing = channels || [];
     const emailIndex = existing.findIndex(isEmailChannel);
@@ -30,7 +30,7 @@ export function updateEmailChannel(
     if (emailIndex === -1) {
         // No email channel exists, create one if we have required fields
         if (updates.to_email) {
-            return [...existing, { type: "email", ...updates } as EmailChannel];
+            return [...existing, { type: 'email', ...updates } as EmailChannel];
         }
         return existing;
     }
@@ -40,7 +40,7 @@ export function updateEmailChannel(
     updated[emailIndex] = {
         ...updated[emailIndex],
         ...updates,
-        type: "email",
+        type: 'email',
     } as EmailChannel;
     return updated;
 }
@@ -52,7 +52,7 @@ export function updateEmailChannel(
 export function updateEmailThreading(
     channels: UserChannel[] | undefined,
     messageId: string,
-    subject?: string
+    subject?: string,
 ): UserChannel[] {
     const emailChannel = findEmailChannel(channels);
     if (!emailChannel) return channels || [];

package/src/common.ts

@@ -1,5 +1,5 @@
 export interface FindPayload {
-    query: Record<string, any>;
+    query: Record<string, unknown>;
     offset?: number;
     limit?: number;
     select?: string;
@@ -7,12 +7,11 @@ export interface FindPayload {
     from_root?: string;
 }
 
-
 export interface GenericCommandResponse {
     status: string;
     message: string;
-    err?: any;
-    details?: any;
+    err?: unknown;
+    details?: unknown;
 }
 
 export interface DeleteByIdResult {
@@ -41,7 +40,7 @@ export interface BulkOperationPayload {
     /**
      * The operation name
      */
-    name: "change_type" | "create" | "delete" | "start_workflow" | "update";
+    name: 'change_type' | 'create' | 'delete' | 'start_workflow' | 'update';
 
     /**
      * The IDs of the objects to operate on
@@ -51,28 +50,32 @@ export interface BulkOperationPayload {
     /**
      * The operation parameters.
      */
-    params: Record<string, any>;
+    params: Record<string, unknown>;
 }
 
-export interface BulkOperationResult {
-    status: "in_progress" | "completed" | "failed";
+export interface BulkOperationResult<TOperation extends string = 'generic'> {
+    operation: TOperation;
+    status: 'in_progress' | 'completed' | 'failed';
 }
 
-export interface BulkObjectDeleteResult extends BulkOperationResult {
+export interface BulkObjectDeleteResult extends BulkOperationResult<'delete'> {
+    operation: 'delete';
     /** Number of documents deleted (including revisions) */
     deleted: number;
     /** IDs that were not found or user had no permission to delete */
     failed: string[];
 }
 
-export interface BulkObjectUpdateResult extends BulkOperationResult {
+export interface BulkObjectUpdateResult extends BulkOperationResult<'update'> {
+    operation: 'update';
     /** Number of documents successfully updated */
     updated: number;
     /** IDs that were not found, not authorized, or failed to update */
     failed: string[];
 }
 
-export interface BulkObjectCreateResult extends BulkOperationResult {
+export interface BulkObjectCreateResult extends BulkOperationResult<'create'> {
+    operation: 'create';
     /** Number of documents successfully created */
     created: number;
     /** Successfully created objects with their IDs */
@@ -81,6 +84,9 @@ export interface BulkObjectCreateResult extends BulkOperationResult {
     failed: { external_id?: string; index: number; error: string }[];
 }
 
+/**
+ * @discriminator operation
+ */
 export type BulkOperationResponse =
     | BulkOperationResult
     | BulkObjectCreateResult

package/src/cost-analytics.ts

@@ -20,7 +20,15 @@ export interface CostAnalyticsQuery {
     /** End time (ISO string or epoch ms) */
     to?: string | number;
     /** Group results by this dimension */
-    group_by?: 'model' | 'environment' | 'account' | 'project' | 'project_tag' | 'provider' | 'interaction' | 'workflow';
+    group_by?:
+        | 'model'
+        | 'environment'
+        | 'account'
+        | 'project'
+        | 'project_tag'
+        | 'provider'
+        | 'interaction'
+        | 'workflow';
     /** Time series resolution */
     resolution?: 'hour' | 'day' | 'week' | 'month';
     /** Filter by model pattern */
@@ -39,10 +47,8 @@ export interface CostAnalyticsQuery {
     run_id?: string;
     /** Filter by agent run ID */
     agent_run_id?: string;
-    /** Filter by saved-interaction ObjectId */
+    /** Filter by interaction id: stored ObjectId or namespaced in-code id */
     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) */

package/src/data-platform.ts

@@ -5,7 +5,7 @@
  * Supports AI-manageable schemas and multi-table atomic operations.
  */
 
-import { BaseObject } from './store/common.js';
+import type { BaseObject } from './store/common.js';
 
 // ============================================================================
 // Column Types
@@ -205,6 +205,10 @@ export interface DataSchema {
     updated_by?: string;
 }
 
+export interface DataStoreFullSchemaResponse extends DataSchema {
+    schema_format: 'full';
+}
+
 // ============================================================================
 // Data Store Types
 // ============================================================================
@@ -415,6 +419,9 @@ export interface BatchQueryPayload {
 /**
  * Schema change operation types.
  */
+/**
+ * @discriminator op
+ */
 export type AlterTableOperation =
     | { op: 'add_column'; column: DataColumn }
     | { op: 'drop_column'; column: string }
@@ -568,7 +575,10 @@ export interface DataStoreArchiveResult {
     status: DataStoreStatus;
 }
 
-export type DataStoreSchemaResponse = DataSchema | DataSchemaForAI;
+/**
+ * @discriminator schema_format
+ */
+export type DataStoreSchemaResponse = DataStoreFullSchemaResponse | DataSchemaForAI;
 
 export interface DataStoreTableDetail extends DataTable {
     sample_data?: Record<string, unknown>[];
@@ -668,6 +678,7 @@ export interface DataRelationshipForAI {
  * Provides semantic context for understanding the data model.
  */
 export interface DataSchemaForAI {
+    schema_format: 'ai';
     /** Store name */
     name: string;
     /** Schema version */
@@ -810,6 +821,99 @@ export interface DashboardQueryParameters {
     defaults: Record<string, string>;
 }
 
+/**
+ * Elasticsearch DSL supported by dashboard data sources.
+ * Queries execute through Vertesia Store, so project/security filtering remains server-side.
+ */
+export interface DashboardElasticsearchDsl {
+    query?: Record<string, unknown>;
+    aggs?: Record<string, unknown>;
+    size?: number;
+    from?: number;
+    sort?: Array<Record<string, unknown>>;
+}
+
+/**
+ * How an Elasticsearch DSL result should be converted into Vega rows.
+ */
+export type DashboardElasticsearchResultMapping =
+    | {
+          type: 'hits';
+      }
+    | {
+          type: 'aggregation_buckets';
+          /** Dot path under `aggregations` that contains a `buckets` array. */
+          path: string;
+          /** Output field name for bucket key. Defaults to `key`. */
+          keyField?: string;
+          /** Output field name for doc count. Defaults to `doc_count`. */
+          countField?: string;
+      };
+
+/**
+ * Dashboard data source backed by a Data Platform SQL query.
+ */
+export interface DashboardSqlDataSource {
+    kind: 'data_sql';
+    /** SQL query that returns all rows for the dashboard. */
+    query: string;
+    /** Maximum rows to return from the query. */
+    queryLimit?: number;
+    /** Default values for SQL {{param}} placeholders. */
+    queryParameters?: Record<string, string>;
+}
+
+/**
+ * Dashboard data source backed by Vertesia Store Elasticsearch DSL.
+ */
+export interface DashboardStoreElasticsearchDataSource {
+    kind: 'store_es_dsl';
+    /** Elasticsearch DSL query executed through the secured Store query API. */
+    dsl: DashboardElasticsearchDsl;
+    /** Result mapping. Defaults to `hits`. */
+    result?: DashboardElasticsearchResultMapping;
+}
+
+/**
+ * Data source for a Vega dashboard.
+ */
+export type DashboardDataSource = DashboardSqlDataSource | DashboardStoreElasticsearchDataSource;
+
+/**
+ * Dashboard definition contributed by an app package.
+ *
+ * App dashboard IDs are local to the app. The platform exposes them as
+ * `app:<app_name>:<id>` when listing or retrieving dashboards.
+ */
+export interface AppDashboardDefinition {
+    /** Local app dashboard ID. */
+    id: string;
+    /** Machine-friendly dashboard name. Defaults to `id`. */
+    name?: string;
+    /** Display title. Defaults to `name` or `id`. */
+    title?: string;
+    /** User-facing description. */
+    description?: string;
+    /** Tags for discovery and filtering. */
+    tags?: string[];
+    /** Data source used to populate Vega `data.values`. */
+    dataSource?: DashboardDataSource;
+    /** SQL query shortcut for app dashboards backed by data stores. */
+    query?: string;
+    /** Maximum SQL rows to return. */
+    queryLimit?: number;
+    /** Default values for SQL {{param}} placeholders. */
+    queryParameters?: Record<string, string>;
+    /** Complete Vega-Lite specification for the dashboard. */
+    spec?: Record<string, unknown>;
+    /** Legacy named SQL queries. */
+    queries?: DashboardQuery[];
+    /** Legacy panel definitions. */
+    panels?: DashboardPanel[];
+    /** Legacy dashboard layout. */
+    layout?: DashboardLayout;
+}
+
 /**
  * Summary view of a dashboard (for listings).
  */
@@ -826,15 +930,22 @@ export interface DashboardItem extends BaseObject {
     last_rendered_at?: string;
     /** Tags for organization */
     tags: string[];
+    /** Source of the dashboard definition. Defaults to stored dashboards. */
+    source?: 'stored' | 'app';
+    /** App name when `source` is `app`. */
+    app_name?: string;
+    /** App dashboards are read-only until cloned into a stored dashboard. */
+    readonly?: boolean;
 }
 
 /**
  * Full dashboard with SQL query and Vega-Lite specification.
  *
  * **New architecture (v2):**
- * - Single `query` field with SQL (use JOINs/CTEs for complex data needs)
+ * - `dataSource` field with either SQL or Store Elasticsearch DSL
  * - Single `spec` field with complete Vega-Lite spec (vconcat/hconcat for multiple panels)
  * - Cross-panel interactivity via Vega selections
+ * - Legacy top-level `query` fields are treated as a SQL data source
  *
  * **Legacy architecture (v1, deprecated):**
  * - Multiple `queries` with named data sources
@@ -844,18 +955,26 @@ export interface DashboardItem extends BaseObject {
  */
 export interface Dashboard extends DashboardItem {
     // ============= New architecture (v2) =============
+    /**
+     * Data source used to populate Vega `data.values`.
+     * When omitted, top-level `query` is treated as a SQL data source for backwards compatibility.
+     */
+    dataSource?: DashboardDataSource;
     /**
      * SQL query that returns all data for the dashboard.
      * Use JOINs, CTEs, or UNION ALL to combine data from multiple tables.
      * Can include {{param_name}} placeholders for dynamic values.
+     * @deprecated Use `dataSource: { kind: 'data_sql', query }` instead.
      */
     query?: string;
     /**
      * Maximum rows to return from the query (default: 10000).
+     * @deprecated Use `dataSource.queryLimit` instead.
      */
     queryLimit?: number;
     /**
      * Default values for SQL parameters.
+     * @deprecated Use `dataSource.queryParameters` instead.
      */
     queryParameters?: Record<string, string>;
     /**
@@ -889,15 +1008,17 @@ export interface Dashboard extends DashboardItem {
 
 /**
  * Payload for creating a new dashboard.
- * Requires query (SQL) and spec (Vega-Lite).
+ * Requires a data source and spec (Vega-Lite).
  */
 export interface CreateDashboardPayload {
     /** Dashboard name (unique within store) */
     name: string;
     /** Dashboard summary */
     summary?: string;
-    /** SQL query that returns all data for the dashboard */
-    query: string;
+    /** Data source used to populate Vega `data.values`. */
+    dataSource?: DashboardDataSource;
+    /** SQL query that returns all data for the dashboard. Deprecated shortcut for a SQL data source. */
+    query?: string;
     /** Maximum rows to return from the query (default: 10000) */
     queryLimit?: number;
     /** Default values for SQL {{param}} placeholders */
@@ -914,7 +1035,9 @@ export interface UpdateDashboardPayload {
     name?: string;
     /** Dashboard summary */
     summary?: string;
-    /** SQL query that returns all data for the dashboard */
+    /** Data source used to populate Vega `data.values`. */
+    dataSource?: DashboardDataSource;
+    /** SQL query that returns all data for the dashboard. Deprecated shortcut for a SQL data source. */
     query?: string;
     /** Maximum rows to return from the query (default: 10000) */
     queryLimit?: number;
@@ -931,6 +1054,8 @@ export interface UpdateDashboardPayload {
  */
 export interface PreviewDashboardPayload {
     // ============= New architecture (v2) =============
+    /** Data source used to populate Vega `data.values`. */
+    dataSource?: DashboardDataSource;
     /** SQL query that returns all data for the dashboard */
     query?: string;
     /** Maximum rows to return from the query (default: 10000) */
@@ -994,6 +1119,16 @@ export interface DashboardVersion {
     version_number: number;
     /** Commit message describing the change */
     message: string;
+    /** Snapshot of v2 data source at this version */
+    dataSource?: DashboardDataSource;
+    /** Snapshot of v2 SQL query at this version */
+    query?: string;
+    /** Snapshot of v2 query limit at this version */
+    queryLimit?: number;
+    /** Snapshot of v2 query parameters at this version */
+    queryParameters?: Record<string, string>;
+    /** Snapshot of v2 Vega-Lite spec at this version */
+    spec?: Record<string, unknown>;
     /** Snapshot of queries at this version */
     queries: DashboardQuery[];
     /** Snapshot of panels at this version */

package/src/email.ts

@@ -9,7 +9,7 @@
  * Used for email-based agent communication.
  */
 export interface EmailChannel {
-    type: "email";
+    type: 'email';
     /** Email address to send agent messages to */
     to_email: string;
     /** Subject for the email thread (without "Re:" prefix) */
@@ -27,26 +27,29 @@ export interface EmailChannel {
  * Used for real-time chat interface communication.
  */
 export interface InteractiveChannel {
-    type: "interactive";
+    type: 'interactive';
 }
 
 /**
  * Union of all supported user communication channel types.
  */
+/**
+ * @discriminator type
+ */
 export type UserChannel = EmailChannel | InteractiveChannel;
 
 /**
  * Type guard for email channels
  */
 export function isEmailChannel(channel: UserChannel): channel is EmailChannel {
-    return channel.type === "email";
+    return channel.type === 'email';
 }
 
 /**
  * Type guard for interactive channels
  */
 export function isInteractiveChannel(channel: UserChannel): channel is InteractiveChannel {
-    return channel.type === "interactive";
+    return channel.type === 'interactive';
 }
 
 // ================= Email Routing ====================

package/src/embeddings.ts

@@ -0,0 +1,76 @@
+import type { EmbeddingsResult, EmbeddingTaskType } from '@llumiverse/common';
+
+/**
+ * Wire-format inputs accepted by the studio-server embeddings endpoint.
+ * Mirror of @llumiverse/common's EmbeddingInput, but binary modalities
+ * carry a JSON-friendly source (URL or base64) instead of a DataSource.
+ *
+ * The server wraps each source in a Base64DataSource or URLDataSource
+ * before passing the request to the llumiverse driver.
+ */
+export type EmbeddingsApiInput =
+    | EmbeddingsApiTextInput
+    | EmbeddingsApiImageInput
+    | EmbeddingsApiVideoInput
+    | EmbeddingsApiAudioInput;
+
+export interface EmbeddingsApiSource {
+    /** Display name for the source (defaults to "embedding-input"). */
+    name?: string;
+    /** MIME type of the binary content. Required for most providers. */
+    mime_type?: string;
+    /**
+     * Provider-native URL the driver may pass through directly:
+     * - gs:// or https://storage.googleapis.com/ for Vertex AI
+     * - s3:// or https://*.amazonaws.com for Bedrock
+     * - https:// for fetch fallback
+     * Mutually exclusive with base64.
+     */
+    url?: string;
+    /** Base64-encoded bytes. Mutually exclusive with url. */
+    base64?: string;
+}
+
+export interface EmbeddingsApiTextInput {
+    type: 'text';
+    text: string;
+    task_type?: EmbeddingTaskType;
+    title?: string;
+}
+
+export interface EmbeddingsApiImageInput {
+    type: 'image';
+    source: EmbeddingsApiSource;
+}
+
+export interface EmbeddingsApiVideoInput {
+    type: 'video';
+    source: EmbeddingsApiSource;
+    start_sec?: number;
+    length_sec?: number;
+    interval_sec?: number;
+    use_fixed_length_sec?: boolean;
+    min_clip_sec?: number;
+    embedding_option?: ('visual-text' | 'visual-image' | 'audio')[];
+}
+
+export interface EmbeddingsApiAudioInput {
+    type: 'audio';
+    source: EmbeddingsApiSource;
+    start_sec?: number;
+    length_sec?: number;
+}
+
+export interface EmbeddingsApiRequest {
+    inputs: EmbeddingsApiInput[];
+    model?: string;
+    task_type?: EmbeddingTaskType;
+    dimensions?: number;
+}
+
+/**
+ * Wire-format result. Identical to @llumiverse/common's EmbeddingsResult
+ * (vectors and metadata are JSON-friendly), re-exported here for callers
+ * that prefer to consume types from @vertesia/common.
+ */
+export type EmbeddingsApiResult = EmbeddingsResult;