@vertesia/common 1.0.0 → 1.1.0-dev.20260427.060440Z

package/src/audit-trail.ts

@@ -1,14 +1,43 @@
 export type AuditAction =
+    // CRUD operations
     | 'create'
     | 'update'
     | 'delete'
     | 'bulk_create'
+    | 'bulk_change_type'
     | 'bulk_update'
     | 'bulk_delete'
     | 'attach'
     | 'detach'
     | 'publish'
-    | 'unpublish';
+    | 'unpublish'
+    // Billable operations
+    | 'inference'
+    | 'embedding'
+    | 'image_generation';
+
+/** Billable audit actions for cost analytics queries */
+export const BILLABLE_AUDIT_ACTIONS: AuditAction[] = [
+    'inference',
+    'embedding',
+    'image_generation',
+];
+
+/**
+ * Generic metering entry attached to audit events.
+ * Used for cost attribution, usage tracking, and billing.
+ *
+ * Examples:
+ *   { category: "tokens", type: "input", quantity: 1234 }
+ *   { category: "tokens", type: "output", quantity: 567 }
+ *   { category: "compute", type: "duration_ms", quantity: 2100 }
+ *   { category: "processing", type: "pages", quantity: 12 }
+ */
+export interface AuditMeter {
+    category: string;
+    type: string;
+    quantity: number;
+}
 
 export interface AuditTrailEvent {
     event_type: 'audit';
@@ -21,13 +50,19 @@ export interface AuditTrailEvent {
     success: boolean;
     principal_id: string | null;
     principal_type: string | null;
-    principal_user_id: string | null;
+    effective_principal_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;
+    /** Provider type for billable/provider-backed events, e.g. vertexai, bedrock. */
+    provider?: string | null;
+    /** Generic metering data for cost attribution and usage tracking */
+    meters?: AuditMeter[];
+    /** Event-specific metadata — shape varies by action/resource_type */
+    details?: Record<string, unknown>;
 }
 
 export interface AuditTrailQuery {
@@ -37,10 +72,14 @@ export interface AuditTrailQuery {
     resourceTypes?: string[];
     /** Filter by resource ID */
     resourceId?: string;
-    /** Filter by principal ID (matches principal_id column — API keys, service accounts) */
+    /** Filter by exact actor principal ref (matches principal_id column). */
     principalId?: string;
-    /** Filter by principal user ID (matches principal_user_id column — human users) */
-    principalUserId?: string;
+    /** Filter by top-level actor category (matches principal_type column). */
+    principalType?: string;
+    /** Filter by delegated/direct effective principal ref (matches effective_principal_id column). */
+    effectivePrincipalId?: string;
+    /** Filter by whether an event has an effective principal ref. */
+    hasEffectivePrincipal?: boolean;
     /** Filter by project ID */
     projectId?: string;
     /** Start time (ISO string) */

package/src/cost-analytics.ts

@@ -0,0 +1,165 @@
+/**
+ * Cost Analytics Types
+ *
+ * Types for the cost attribution dashboard.
+ * Combines audit trail metering data with billing export pricing
+ * to compute per-org/project/env/model cost breakdowns.
+ */
+
+import { BILLABLE_AUDIT_ACTIONS } from './audit-trail.js';
+
+export { BILLABLE_AUDIT_ACTIONS };
+
+// ============================================================================
+// Query
+// ============================================================================
+
+export interface CostAnalyticsQuery {
+    /** Start time (ISO string or epoch ms) */
+    from?: string | number;
+    /** 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';
+    /** Time series resolution */
+    resolution?: 'hour' | 'day' | 'week' | 'month';
+    /** Filter by model pattern */
+    model?: string;
+    /** Filter by environment ID */
+    environment_id?: string;
+    /** Filter by provider */
+    provider?: string;
+    /** Filter by project ID (optional, for org scope) */
+    project_id?: string;
+    /** Filter by workflow / agent run ID */
+    workflow_id?: string;
+    /** Filter by Temporal workflow run ID */
+    workflow_run_id?: string;
+    /** Filter by interaction execution run ID */
+    run_id?: string;
+    /** Filter by agent run ID */
+    agent_run_id?: string;
+    /** Filter by account ID (set automatically by server) */
+    account_id?: string;
+    /** Scope: 'project' (default, current project) or 'org' (all projects in account) */
+    scope?: 'project' | 'org';
+    /** Pricing source: 'list' (latest daily prices) or 'historical' (daily effective prices over the query range). Default: 'list' */
+    pricing_source?: 'list' | 'historical';
+    /** Skip cache and force fresh query */
+    no_cache?: boolean;
+}
+
+// ============================================================================
+// Response
+// ============================================================================
+
+export interface CostSummary {
+    total_cost: number;
+    total_input_tokens: number;
+    total_cached_input_tokens?: number;
+    total_cache_write_input_tokens?: number;
+    total_output_tokens: number;
+    total_calls: number;
+    total_duration_ms: number;
+}
+
+export interface CostByDimension {
+    dimension: string;
+    label?: string;
+    provider?: string;
+    cost: number;
+    input_tokens: number;
+    cached_input_tokens?: number;
+    cache_write_input_tokens?: number;
+    output_tokens: number;
+    calls: number;
+    periods?: CostTimeSeriesPoint[];
+}
+
+export interface CostTimeSeriesPoint {
+    timestamp: string;
+    cost: number;
+    input_tokens: number;
+    cached_input_tokens?: number;
+    cache_write_input_tokens?: number;
+    output_tokens: number;
+    calls: number;
+}
+
+export interface ModelPricing {
+    model: string;
+    provider?: string;
+    provider_account_id?: string;
+    input_price_per_m_tokens: number;
+    cached_input_price_per_m_tokens?: number;
+    cache_write_input_price_per_m_tokens?: number;
+    output_price_per_m_tokens: number;
+    source: 'billing_export' | 'model_pricing_daily' | 'unavailable';
+}
+
+export interface ModelPriceComparison {
+    model: string;
+    provider?: string;
+    provider_account_id?: string;
+    list_price_date?: string;
+    effective_from?: string;
+    effective_to?: string;
+    input_list_price_per_m_tokens?: number;
+    input_effective_price_per_m_tokens?: number;
+    cached_input_list_price_per_m_tokens?: number;
+    cached_input_effective_price_per_m_tokens?: number;
+    cache_write_input_list_price_per_m_tokens?: number;
+    cache_write_input_effective_price_per_m_tokens?: number;
+    output_list_price_per_m_tokens?: number;
+    output_effective_price_per_m_tokens?: number;
+    source: 'model_pricing_daily';
+}
+
+export interface ModelPriceComparisonResponse {
+    prices: ModelPriceComparison[];
+    effective_range: { from: string; to: string };
+    list_price_date?: string;
+}
+
+export interface CostAnalyticsResponse {
+    summary: CostSummary;
+    by_dimension: CostByDimension[];
+    time_series: CostTimeSeriesPoint[];
+    pricing: ModelPricing[];
+    query_range: { from: string; to: string };
+    cached: boolean;
+}
+
+export interface CostRunPriceQuery {
+    /** Interaction execution run ID */
+    run_id?: string;
+    /** Agent run ID */
+    agent_run_id?: string;
+    /** Workflow ID, when known */
+    workflow_id?: string;
+    /** Temporal workflow run ID, when known */
+    workflow_run_id?: string;
+    /** Optional lower bound for audit events */
+    from?: string | number;
+    /** Optional upper bound for audit events */
+    to?: string | number;
+    /** Pricing source. Defaults to historical effective prices for run pricing. */
+    pricing_source?: 'list' | 'historical';
+    /** Include the full pricing catalog for cross-model comparison. Defaults to false. */
+    include_comparison_pricing?: boolean;
+    /** Project filter; server fills current project by default */
+    project_id?: string;
+    /** Account filter; server fills current account */
+    account_id?: string;
+    /** Scope: 'project' (default, current project) or 'org' */
+    scope?: 'project' | 'org';
+}
+
+export interface CostRunPriceResponse {
+    summary: CostSummary;
+    by_model: CostByDimension[];
+    pricing?: ModelPricing[];
+    query_range?: { from: string; to: string };
+    pricing_source: 'list' | 'historical';
+    matched_events: number;
+}

package/src/group.ts

@@ -23,4 +23,6 @@ export interface UserGroupRef {
     tags?: string[];
 }
 
-export const UserGroupRefPopulate = 'id name tags description';
+export const UserGroupRefPopulate = 'id name tags description';
+
+export const MEMBERS_GROUP_NAME = 'members';

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './access-control.js';
 export * from './analytics.js';
 export * from './audit-trail.js';
+export * from './cost-analytics.js';
 export * from './apikey.js';
 export * from './apps.js';
 export * from './ask-user.js';
@@ -11,13 +12,14 @@ export * from './environment.js';
 export * from "./facets.js";
 export * from './group.js';
 export * from './integrations.js';
-export * from './oauth.js';
 export * from './interaction.js';
 export * from './pending-asks.js';
 export * from './json-schema.js';
 export * from './json.js';
 export * from './meters.js';
+export * from './oauth-server.js';
 export * from './model_utility.js';
+export * from './oauth.js';
 export * from './payload.js';
 export * from "./Progress.js";
 export * from './project.js';
@@ -39,4 +41,3 @@ export * from './utils/schemas.js';
 export type * from './utils/type-helpers.js';
 export * from './versions.js';
 export * from './workflow-analytics.js';
-

package/src/interaction.ts

@@ -26,6 +26,7 @@ import { ExecutionRunDocRef } from "./runs.js";
 import { ConversationState } from "./store/conversation-state.js";
 import { AccountRef } from "./user.js";
 import { LlmCallType } from "./workflow-analytics.js";
+import type { MCPToolAnnotations } from "./apps.js";
 
 export interface InteractionExecutionError {
     code: string;
@@ -288,6 +289,11 @@ export interface InteractionEndpointQuery {
      * Whether or not to return the result schema
      */
     include_result_schema?: boolean;
+
+    /**
+     * When true, filter results to only interactions with is_skill=true.
+     */
+    is_skill?: boolean;
 }
 
 /**
@@ -362,6 +368,8 @@ export enum InteractionStatus {
     draft = "draft",
     published = "published",
     archived = "archived",
+    code = "code", // for in-code interactions that are not stored in the database
+    unknown = "unknown", // for interactions with unknown status
 }
 
 export enum ExecutionRunStatus {
@@ -760,6 +768,18 @@ export interface AsyncConversationExecutionPayload extends AsyncExecutionPayload
      */
     restart_from_workflow_run_id?: string;
 
+    /**
+     * The Temporal firstExecutionRunId of the original workflow being restarted/forked.
+     * Used by loadConversationForRestart to look up the original ExecutionRun
+     * so that token accumulation and status updates target a valid run.
+     */
+    source_first_workflow_run_id?: string;
+
+    /**
+     * When true, indicates this is a fork (new ExecutionRun) rather than a restart (reuse original).
+     */
+    is_fork?: boolean;
+
     /**
      * The AgentRun MongoDB _id. Used for artifact storage paths: agents/{agent_run_id}/
      * Flows into ConversationState and down to workstreams.
@@ -1206,14 +1226,26 @@ export interface BuiltinToolDefinition {
     name: string;
 
     /**
-     * Human-readable description of what the tool does
+     * One-line summary shown in the tool selector UI
      */
-    description: string;
+    summary?: string;
 
     /**
      * JSON schema for the tool's parameters
      */
     params: JSONSchema;
+
+    /**
+     * Whether this tool is active by default when no explicit tool list is provided.
+     * Tools with default: false are only activated by skills.
+     */
+    default: boolean;
+
+    /**
+     * Behavioral hints following the MCP ToolAnnotations spec.
+     * Used for display purposes only — not sent to LLMs.
+     */
+    annotations?: MCPToolAnnotations;
 }
 
 /**
@@ -1229,7 +1261,9 @@ export interface SystemSkillCatalogEntry {
     title: string;
     /** Description of what the skill unlocks */
     description: string;
-    /** Builtin tools that become available when this skill is called */
+    /** Tools that become available when this skill is called */
+    tools: string[];
+    /** Related tools that complement this skill */
     related_tools: string[];
 }
 

package/src/oauth-server.ts

@@ -0,0 +1,248 @@
+import type { AuthTokenPayload } from './apikey.js';
+import type { ProjectRef } from './project.js';
+
+export type OAuthClientType = 'public' | 'confidential';
+export type OAuthClientStatus = 'active' | 'disabled';
+export type OAuthRegistrationSource = 'admin' | 'dynamic';
+export type OAuthProjectBindingMode = 'user_select' | 'fixed';
+export type OAuthTokenEndpointAuthMethod = 'none' | 'client_secret_post' | 'client_secret_basic';
+export type OAuthGrantType = 'authorization_code' | 'refresh_token';
+export type OAuthResponseType = 'code';
+export type OAuthAuthorizationRequestStatus = 'pending' | 'denied' | 'consumed';
+export type OAuthClientRegistrationMode = 'registered' | 'client_id_metadata_document';
+export type OAuthGrantStatus = 'active' | 'revoked' | 'expired';
+export type OAuthGrantSortField = 'granted_at' | 'client_name' | 'user_name' | 'resource' | 'last_used_at' | 'expires_at' | 'status';
+export type OAuthGrantSortOrder = 'asc' | 'desc';
+
+export interface OAuthClientData {
+    client_name: string;
+    client_type: OAuthClientType;
+    redirect_uris: string[];
+    grant_types: OAuthGrantType[];
+    response_types: OAuthResponseType[];
+    token_endpoint_auth_method: OAuthTokenEndpointAuthMethod;
+    allowed_scopes: string[];
+    registration_source: OAuthRegistrationSource;
+    status: OAuthClientStatus;
+    project_binding_mode: OAuthProjectBindingMode;
+    fixed_project_id?: string;
+    metadata?: Record<string, unknown>;
+    created_by?: string;
+    client_secret_configured?: boolean;
+    created_at: string;
+    updated_at: string;
+}
+
+export interface OAuthClient extends OAuthClientData {
+    client_id: string;
+}
+
+export interface OAuthClientCreateResponse extends OAuthClient {
+    client_secret?: string;
+}
+
+export interface OAuthGrant {
+    grant_id: string;
+    client_id: string;
+    client_name: string;
+    user_id: string;
+    user_name?: string;
+    user_email?: string;
+    account_id: string;
+    project_id: string;
+    resource: string;
+    scope: string[];
+    status: OAuthGrantStatus;
+    token_count: number;
+    granted_at: string;
+    created_at: string;
+    last_used_at?: string;
+    expires_at?: string;
+}
+
+export interface ListOAuthGrantsQuery {
+    account_id?: string;
+    project_id?: string;
+    user_id?: string;
+    client_id?: string;
+    resource?: string;
+    status?: OAuthGrantStatus | 'all';
+    limit?: number;
+    offset?: number;
+    sort_by?: OAuthGrantSortField;
+    sort_order?: OAuthGrantSortOrder;
+}
+
+export interface OAuthGrantListResponse {
+    grants: OAuthGrant[];
+    total_count: number;
+    limit: number;
+    offset: number;
+}
+
+export interface BulkRevokeOAuthGrantsPayload extends ListOAuthGrantsQuery {
+    grant_ids?: string[];
+    include_consent?: boolean;
+}
+
+export interface OAuthGrantRevokeResponse {
+    revoked_tokens: number;
+    revoked_consents: number;
+}
+
+export interface CreateOAuthClientPayload {
+    client_name: string;
+    client_type?: OAuthClientType;
+    redirect_uris: string[];
+    grant_types?: OAuthGrantType[];
+    response_types?: OAuthResponseType[];
+    token_endpoint_auth_method?: OAuthTokenEndpointAuthMethod;
+    allowed_scopes?: string[];
+    project_binding_mode?: OAuthProjectBindingMode;
+    fixed_project_id?: string;
+    client_secret?: string;
+    metadata?: Record<string, unknown>;
+}
+
+export interface UpdateOAuthClientPayload {
+    client_name?: string;
+    redirect_uris?: string[];
+    grant_types?: OAuthGrantType[];
+    response_types?: OAuthResponseType[];
+    token_endpoint_auth_method?: OAuthTokenEndpointAuthMethod;
+    allowed_scopes?: string[];
+    status?: OAuthClientStatus;
+    project_binding_mode?: OAuthProjectBindingMode;
+    fixed_project_id?: string;
+    client_secret?: string;
+    metadata?: Record<string, unknown>;
+}
+
+export interface OAuthAuthorizationServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    jwks_uri: string;
+    registration_endpoint?: string;
+    revocation_endpoint?: string;
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    code_challenge_methods_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+    scopes_supported: string[];
+    client_id_metadata_document_supported?: boolean;
+}
+
+export interface OAuthClientMetadataDocument {
+    client_id: string;
+    client_name?: string;
+    redirect_uris: string[];
+    grant_types?: OAuthGrantType[];
+    response_types?: OAuthResponseType[];
+    token_endpoint_auth_method?: OAuthTokenEndpointAuthMethod;
+    scope?: string;
+    client_uri?: string;
+    logo_uri?: string;
+}
+
+export interface OAuthAuthorizeQuery {
+    response_type: 'code';
+    client_id: string;
+    redirect_uri: string;
+    resource?: string;
+    scope?: string;
+    state?: string;
+    code_challenge: string;
+    code_challenge_method: 'S256';
+    project_id?: string;
+}
+
+export interface CreateOAuthAuthorizationRequestPayload extends OAuthAuthorizeQuery {}
+
+export interface OAuthAuthorizationRequest {
+    request_id: string;
+    client_id: string;
+    client_name: string;
+    client_registration_mode?: OAuthClientRegistrationMode;
+    redirect_uri: string;
+    redirect_origin: string;
+    resource?: string;
+    requested_scopes: string[];
+    requested_project_id?: string;
+    project_binding_mode: OAuthProjectBindingMode;
+    fixed_project_id?: string;
+    status: OAuthAuthorizationRequestStatus;
+    created_at: string;
+    expires_at: string;
+}
+
+export interface ApproveOAuthAuthorizationRequestPayload {
+    project_id?: string;
+}
+
+export interface OAuthAuthorizationDecisionResponse {
+    redirect_url: string;
+}
+
+export interface OAuthTokenRequestAuthorizationCode {
+    grant_type: 'authorization_code';
+    code: string;
+    redirect_uri: string;
+    client_id: string;
+    resource?: string;
+    code_verifier: string;
+    client_secret?: string;
+}
+
+export interface OAuthTokenRequestRefreshToken {
+    grant_type: 'refresh_token';
+    refresh_token: string;
+    client_id: string;
+    resource?: string;
+    client_secret?: string;
+}
+
+export type OAuthTokenRequest = OAuthTokenRequestAuthorizationCode | OAuthTokenRequestRefreshToken;
+
+export interface OAuthTokenResponse {
+    access_token: string;
+    token_type: 'Bearer';
+    expires_in: number;
+    scope: string;
+    refresh_token?: string;
+    id_token?: string;
+}
+
+export interface OAuthAuthorizationCodeRecord {
+    code: string;
+    client_id: string;
+    user_id: string;
+    account_id: string;
+    project_id: string;
+    resource: string;
+    scope: string[];
+    redirect_uri: string;
+    code_challenge: string;
+    code_challenge_method: 'S256';
+    expires_at: string;
+}
+
+export interface OAuthConsentRecord {
+    user_id: string;
+    client_id: string;
+    account_id: string;
+    project_id: string;
+    scope: string[];
+    granted_at: string;
+    revoked_at?: string;
+}
+
+export interface OAuthAccessTokenPayload extends Omit<AuthTokenPayload, 'type' | 'project'> {
+    type: 'oauth_access';
+    client_id: string;
+    scope: string;
+    user_id: string;
+    project: ProjectRef;
+    allowed_collections?: string[];
+    resource?: string;
+}