@vertesia/client 1.1.0-dev.20260327.125707Z → 1.1.0

package/src/client.ts

@@ -3,24 +3,27 @@ import { AuthTokenPayload, AuthTokenResponse } from "@vertesia/common";
 import AccountApi from "./AccountApi.js";
 import AccountsApi from "./AccountsApi.js";
 import AnalyticsApi from "./AnalyticsApi.js";
-import AuditTrailApi from "./AuditTrailApi.js";
 import { ApiKeysApi } from "./ApiKeysApi.js";
 import AppsApi from "./AppsApi.js";
+import AuditTrailApi from "./AuditTrailApi.js";
 import CommandsApi from "./CommandsApi.js";
 import EnvironmentsApi from "./EnvironmentsApi.js";
 import { IamApi } from "./IamApi.js";
 import InteractionsApi from "./InteractionsApi.js";
-import MCPOAuthApi from "./MCPOAuthApi.js";
-import OAuthAppsApi from "./OAuthAppsApi.js";
+import OAuthClientsApi from "./OAuthClientsApi.js";
+import OAuthGrantsApi from "./OAuthGrantsApi.js";
+import OAuthProvidersApi from "./OAuthProvidersApi.js";
+import OAuthServerApi from "./OAuthServerApi.js";
 import ProjectsApi from "./ProjectsApi.js";
-import SkillsApi from "./SkillsApi.js";
 import PromptsApi from "./PromptsApi.js";
 import { RefsApi } from "./RefsApi.js";
+import RemoteMcpConnectionsApi from "./RemoteMcpConnectionsApi.js";
 import { RunsApi } from "./RunsApi.js";
+import SkillsApi from "./SkillsApi.js";
 import { ZenoClient } from "./store/client.js";
+import { VERSION, VERSION_HEADER } from "./store/version.js";
 import TrainingApi from "./TrainingApi.js";
 import UsersApi from "./UsersApi.js";
-import { VERSION, VERSION_HEADER } from "./store/version.js";
 
 
 /**
@@ -36,15 +39,21 @@ export type VertesiaClientProps = {
      * advanced configurations, use `serverUrl` and `storeUrl` instead.
      *
      * @example api.vertesia.io
-     * @example api-preview.vertesia.io
-     * @example api-staging.vertesia.io
+     * @example api.us1.vertesia.io
+     * @example api-preview.eu1.vertesia.io
      * @default api.vertesia.io
      * @since 0.52.0
      */
     site?:
-        | "api.vertesia.io"
-        | "api-preview.vertesia.io"
-        | "api-staging.vertesia.io";
+    | "api.vertesia.io"
+    | "api-preview.vertesia.io"
+    | "api.us1.vertesia.io"
+    | "api-preview.us1.vertesia.io"
+    | "api.eu1.vertesia.io"
+    | "api-preview.eu1.vertesia.io"
+    | "api.jp1.vertesia.io"
+    | "api-preview.jp1.vertesia.io"
+    | "api.dev1.vertesia.io";
     serverUrl?: string;
     storeUrl?: string;
     tokenServerUrl?: string;
@@ -76,6 +85,12 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
      */
     tokenServerUrl: string;
 
+    oauthClients: OAuthClientsApi;
+    oauthGrants: OAuthGrantsApi;
+    oauthServer: OAuthServerApi;
+    oauthProviders: OAuthProvidersApi;
+    remoteMcpConnections: RemoteMcpConnectionsApi;
+
     /**
      * Create a client from the given token.
      * If you already have the decoded token you can pass it as the second argument to avoid decodinf it again.
@@ -101,7 +116,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         }).withApiKey(token);
     }
 
-    static decodeEndpoints() {}
+    static decodeEndpoints() { }
 
     constructor(
         opts: VertesiaClientProps = {
@@ -136,45 +151,35 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         if (opts.tokenServerUrl) {
             this.tokenServerUrl = opts.tokenServerUrl;
         } else if (opts.site) {
-            // Preview uses production STS, staging uses its own STS
-            if (opts.site === "api-preview.vertesia.io" || opts.site === "api.vertesia.io") {
-                this.tokenServerUrl = "https://sts.vertesia.io";
-            } else {
-                this.tokenServerUrl = `https://${opts.site.replace(/^api/, "sts")}`;
-            }
+            // Strip -preview (preview uses the same STS as production for the same region),
+            // then replace api prefix with sts.
+            // Examples:
+            //   api.vertesia.io          -> sts.vertesia.io
+            //   api-preview.vertesia.io  -> sts.vertesia.io
+            //   api.us1.vertesia.io      -> sts.us1.vertesia.io
+            //   api-preview.eu1.vertesia.io -> sts.eu1.vertesia.io
+            const stsHost = opts.site.replace('api-preview.', 'api.').replace(/^api/, 'sts');
+            this.tokenServerUrl = `https://${stsHost}`;
         } else if (opts.serverUrl || opts.storeUrl) {
             // Determine STS URL based on environment in serverUrl or storeUrl
             const urlToCheck = opts.serverUrl || opts.storeUrl || "";
             try {
                 const url = new URL(urlToCheck);
-                // Check for environment patterns
-                if (url.hostname.includes("-production.")) {
-                    // zeno-server-production.api.vertesia.io -> sts.vertesia.io
-                    this.tokenServerUrl = "https://sts.vertesia.io";
-                } else if (url.hostname.includes("-preview.")) {
-                    // zeno-server-preview.api.vertesia.io -> sts.vertesia.io
-                    this.tokenServerUrl = "https://sts.vertesia.io";
-                } else if (url.hostname === "api.vertesia.io") {
-                    this.tokenServerUrl = "https://sts.vertesia.io";
-                } else if (url.hostname === "api-preview.vertesia.io") {
-                    this.tokenServerUrl = "https://sts.vertesia.io";
-                } else if (url.hostname === "api-staging.vertesia.io") {
-                    this.tokenServerUrl = "https://sts-staging.vertesia.io";
-                } else if (url.hostname.startsWith("api")) {
-                    // Generic api.* pattern replacement
-                    url.hostname = url.hostname.replace(/^api/, "sts");
-                    this.tokenServerUrl = url.toString();
+                if (url.hostname.startsWith("api")) {
+                    // Strip -preview and replace api with sts.
+                    // api.us1.vertesia.io         -> sts.us1.vertesia.io
+                    // api-preview.us1.vertesia.io -> sts.us1.vertesia.io
+                    // api.vertesia.io             -> sts.vertesia.io
+                    const stsHost = url.hostname.replace('api-preview.', 'api.').replace(/^api/, 'sts');
+                    this.tokenServerUrl = `https://${stsHost}`;
                 } else {
-                    // Default to staging for everything else
-                    this.tokenServerUrl = "https://sts-staging.vertesia.io";
+                    this.tokenServerUrl = "https://sts.dev1.vertesia.io";
                 }
             } catch (e) {
-                // Default to staging if URL parsing fails
-                this.tokenServerUrl = "https://sts-staging.vertesia.io";
+                this.tokenServerUrl = "https://sts.dev1.vertesia.io";
             }
         } else {
-            // Default to staging if no URL provided
-            this.tokenServerUrl = "https://sts-staging.vertesia.io";
+            this.tokenServerUrl = "https://sts.dev1.vertesia.io";
         }
 
         this.store = new ZenoClient({
@@ -192,6 +197,11 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         this.onRequest = opts.onRequest;
         this.onResponse = opts.onResponse;
         this.sessionTags = opts.sessionTags;
+        this.oauthClients = new OAuthClientsApi(this);
+        this.oauthGrants = new OAuthGrantsApi(this);
+        this.oauthServer = new OAuthServerApi(this);
+        this.oauthProviders = new OAuthProvidersApi(this);
+        this.remoteMcpConnections = new RemoteMcpConnectionsApi(this);
     }
 
     withApiVersion(version: string | number | null) {
@@ -217,16 +227,16 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         return this.withAuthCallback(
             apiKey
                 ? async () => {
-                      if (!isApiKey(apiKey)) {
-                          return `Bearer ${apiKey}`;
-                      }
-
-                      if (isTokenExpired(this._jwt)) {
-                          const jwt = await this.getAuthToken(apiKey);
-                          this._jwt = jwt.token;
-                      }
-                      return `Bearer ${this._jwt}`;
-                  }
+                    if (!isApiKey(apiKey)) {
+                        return `Bearer ${apiKey}`;
+                    }
+
+                    if (isTokenExpired(this._jwt)) {
+                        const jwt = await this.getAuthToken(apiKey);
+                        this._jwt = jwt.token;
+                    }
+                    return `Bearer ${this._jwt}`;
+                }
                 : undefined,
         );
     }
@@ -349,8 +359,6 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
     refs = new RefsApi(this);
     commands = new CommandsApi(this);
     apps = new AppsApi(this);
-    mcpOAuth = new MCPOAuthApi(this);
-    oauthApps = new OAuthAppsApi(this);
 }
 
 function isApiKey(apiKey: string) {
@@ -374,6 +382,25 @@ export function decodeJWT(jwt: string): AuthTokenPayload {
     return JSON.parse(decodedJson);
 }
 
+type RuntimeProcess = {
+    env?: Record<string, string | undefined>;
+};
+
+type RuntimeBuffer = {
+    from(input: string, encoding: string): {
+        toString(encoding: string): string;
+    };
+};
+
+function getRuntimeBuffer() {
+    return (globalThis as typeof globalThis & { Buffer?: RuntimeBuffer }).Buffer;
+}
+
+function getRuntimeStsUrl() {
+    const runtimeProcess = (globalThis as typeof globalThis & { process?: RuntimeProcess }).process;
+    return runtimeProcess?.env?.STS_URL;
+}
+
 function base64UrlDecode(input: string): string {
     // Convert base64url to base64
     const base64 = input
@@ -382,9 +409,10 @@ function base64UrlDecode(input: string): string {
         // Pad with '=' to make length a multiple of 4
         .padEnd(Math.ceil(input.length / 4) * 4, "=");
 
-    if (typeof Buffer !== "undefined") {
+    const runtimeBuffer = getRuntimeBuffer();
+    if (runtimeBuffer) {
         // Node.js
-        return Buffer.from(base64, "base64").toString("utf-8");
+        return runtimeBuffer.from(base64, "base64").toString("utf-8");
     } else if (
         typeof atob !== "undefined" &&
         typeof TextDecoder !== "undefined"
@@ -417,7 +445,7 @@ function getEndpointsFromDomain(domain: string) {
         return {
             studio: `http://localhost:8091`,
             store: `http://localhost:8092`,
-            token: process.env.STS_URL ?? "https://sts-staging.vertesia.io",
+            token: getRuntimeStsUrl() ?? "https://sts.dev1.vertesia.io",
         };
     } else {
         const url = `https://${domain}`;

package/src/index.ts

@@ -3,6 +3,11 @@ export * from './client.js';
 export type { GroupsQueryOptions } from './GroupsApi.js';
 export * from './InteractionBase.js';
 export * from './InteractionOutput.js';
+export { default as OAuthClientsApi } from './OAuthClientsApi.js';
+export { default as OAuthGrantsApi } from './OAuthGrantsApi.js';
+export { default as OAuthProvidersApi } from './OAuthProvidersApi.js';
+export { default as OAuthServerApi } from './OAuthServerApi.js';
+export { default as RemoteMcpConnectionsApi } from './RemoteMcpConnectionsApi.js';
 export type { AsyncExecutionResult, ComputeInteractionFacetsResponse } from './InteractionsApi.js';
 export type { ComputePromptFacetsResponse, ListInteractionsResponse } from './PromptsApi.js';
 export type { ComputeRunFacetsResponse, FilterOption } from './RunsApi.js';

package/src/store/AgentsApi.ts

@@ -2,36 +2,47 @@ import { ApiTopic, ClientBase } from '@vertesia/api-fetch-client';
 import {
     ActiveWorkstreamsQueryResult,
     AgentEvent,
+    AgentArtifactUrlResponse,
     AgentMessage,
     AgentMessageType,
     AgentRun,
+    AgentRunDetailsStreamEvent,
     AgentRunInternals,
-    AgentRunStatus,
+    AgentRunUpdatesResponse,
     CompactMessage,
-    ConversationActivityState,
     CreateAgentRunPayload,
     ErrorAnalyticsResponse,
     FirstResponseBehaviorAnalyticsResponse,
     LatencyAnalyticsResponse,
     ListAgentRunsQuery,
+    ListAgentRunsResponse,
     ListWorkflowRunsResponse,
     parseMessage,
     PromptSizeAnalyticsResponse,
+    PostAgentRunUpdatePayload,
+    PostAgentRunUpdateResponse,
+    RecordAgentRunPayload,
     RunsByAgentAnalyticsResponse,
     SearchAgentRunsQuery,
     SearchAgentRunsResponse,
+    SignalAgentPayload,
+    SignalAgentResponse,
     TimeToFirstResponseAnalyticsResponse,
+    TerminateAgentRunResponse,
     toAgentMessage,
     TokenUsageAnalyticsResponse,
     ToolAnalyticsResponse,
     ToolParameterAnalyticsResponse,
     TopPrincipalsAnalyticsResponse,
+    UpdateAgentRunStatusPayload,
     WorkflowAnalyticsFilterOptionsResponse,
     WorkflowAnalyticsSummaryQuery,
     WorkflowAnalyticsSummaryResponse,
     WorkflowAnalyticsTimeSeriesQuery,
     WorkflowRunWithDetails,
     WorkflowToolParametersQuery,
+    IngestAgentEventsPayload,
+    IngestAgentEventsResponse,
 } from '@vertesia/common';
 import { VertesiaClient } from '../client.js';
 import { EventSourceProvider } from '../execute.js';
@@ -49,7 +60,7 @@ export class AgentsApi extends ApiTopic {
      * Create and start a new agent run.
      * Returns the created AgentRun with its stable id.
      */
-    start<TData = Record<string, any>>(
+    start<TData = Record<string, unknown>>(
         payload: CreateAgentRunPayload<TData>,
     ): Promise<AgentRun<TData>> {
         return this.post('/', { payload });
@@ -59,29 +70,21 @@ export class AgentsApi extends ApiTopic {
      * Record an AgentRun for an already-running workflow (e.g. schedule-triggered).
      * Only creates the MongoDB document — the workflow passes its own Temporal IDs.
      */
-    createRecord(payload: {
-        interaction: string;
-        schedule_id?: string;
-        workflow_id: string;
-        first_workflow_run_id: string;
-        visibility?: string;
-        data?: Record<string, any>;
-        type?: string;
-    }): Promise<AgentRun> {
+    createRecord(payload: RecordAgentRunPayload): Promise<AgentRun> {
         return this.post('/record', { payload });
     }
 
     /**
      * Get agent run by id.
      */
-    retrieve<TData = Record<string, any>>(id: string): Promise<AgentRun<TData>> {
+    retrieve<TData = Record<string, unknown>>(id: string): Promise<AgentRun<TData>> {
         return this.get(`/${id}`);
     }
 
     /**
      * List agent runs with optional filters.
      */
-    list(query?: ListAgentRunsQuery): Promise<AgentRun[]> {
+    list(query?: ListAgentRunsQuery): Promise<ListAgentRunsResponse> {
         const params: Record<string, string> = {};
         if (query?.id) params.id = query.id;
         if (query?.status) {
@@ -90,10 +93,12 @@ export class AgentsApi extends ApiTopic {
         if (query?.interaction) params.interaction = query.interaction;
         if (query?.started_by) params.started_by = query.started_by;
         if (query?.since) params.since = query.since.toISOString();
+        if (query?.until) params.until = query.until.toISOString();
         if (query?.schedule_id) params.schedule_id = query.schedule_id;
         if (query?.type) params.type = query.type;
         if (query?.limit) params.limit = String(query.limit);
         if (query?.offset) params.offset = String(query.offset);
+        if (query?.cursor) params.cursor = query.cursor;
         if (query?.sort) params.sort = query.sort;
         if (query?.order) params.order = query.order;
         return this.get('/', { query: params });
@@ -114,6 +119,7 @@ export class AgentsApi extends ApiTopic {
         if (query?.tags?.length) params.tags = query.tags.join(',');
         if (query?.content_type_name) params.content_type_name = query.content_type_name;
         if (query?.since) params.since = query.since.toISOString();
+        if (query?.until) params.until = query.until.toISOString();
         if (query?.limit) params.limit = String(query.limit);
         if (query?.offset) params.offset = String(query.offset);
         return this.get('/search', { query: params });
@@ -122,7 +128,7 @@ export class AgentsApi extends ApiTopic {
     /**
      * Cancel/terminate an agent run.
      */
-    terminate(id: string, reason?: string): Promise<{ message: string }> {
+    terminate(id: string, reason?: string): Promise<TerminateAgentRunResponse> {
         const query = reason ? { reason } : undefined;
         return this.del(`/${id}`, { query });
     }
@@ -150,15 +156,7 @@ export class AgentsApi extends ApiTopic {
      */
     updateStatus(
         id: string,
-        update: {
-            status?: AgentRunStatus;
-            activity_state?: ConversationActivityState;
-            title?: string;
-            topic?: string;
-            lessons_learned?: string[];
-            /** ES-only: conversation content text (not stored in MongoDB) */
-            content?: string;
-        },
+        update: UpdateAgentRunStatusPayload,
     ): Promise<AgentRun> {
         return this.post(`/${id}/status`, { payload: update });
     }
@@ -171,7 +169,7 @@ export class AgentsApi extends ApiTopic {
      * Send a signal to a running agent.
      * Signals: "UserInput", "Stop", "FileUploaded"
      */
-    sendSignal(id: string, signalName: string, payload?: any): Promise<{ message: string }> {
+    sendSignal(id: string, signalName: string, payload?: SignalAgentPayload): Promise<SignalAgentResponse> {
         return this.post(`/${id}/signal/${signalName}`, { payload });
     }
 
@@ -200,16 +198,14 @@ export class AgentsApi extends ApiTopic {
      */
     async retrieveMessages(id: string, since?: number): Promise<AgentMessage[]> {
         const query = since ? { since } : undefined;
-        const response = (await this.get(`/${id}/updates`, { query })) as {
-            messages: CompactMessage[];
-        };
+        const response = await this.get(`/${id}/updates`, { query }) as AgentRunUpdatesResponse;
         return response.messages.map((m: CompactMessage) => toAgentMessage(m, id));
     }
 
     /**
      * Post a message/update to an agent run.
      */
-    postMessage(id: string, msg: Partial<AgentMessage>): Promise<void> {
+    postMessage(id: string, msg: PostAgentRunUpdatePayload): Promise<PostAgentRunUpdateResponse> {
         return this.post(`/${id}/updates`, { payload: msg });
     }
 
@@ -240,7 +236,7 @@ export class AgentsApi extends ApiTopic {
         let lastMessageTimestamp = since || 0;
         let isClosed = false;
         let currentSse: EventSource | null = null;
-        let interval: NodeJS.Timeout | null = null;
+        let interval: ReturnType<typeof setInterval> | null = null;
         let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
         let abortHandler: (() => void) | null = null;
 
@@ -372,7 +368,7 @@ export class AgentsApi extends ApiTopic {
                     }
                 };
 
-                sse.onerror = (_err: any) => {
+                sse.onerror = (_err: unknown) => {
                     if (isClosed) return;
                     cleanup();
 
@@ -452,7 +448,7 @@ export class AgentsApi extends ApiTopic {
      */
     async streamRunDetails(
         id: string,
-        onEvent?: (event: { type: string; data: unknown }) => void,
+        onEvent?: (event: AgentRunDetailsStreamEvent) => void,
         signal?: AbortSignal,
     ): Promise<void> {
         const EventSourceImpl = await EventSourceProvider();
@@ -486,16 +482,16 @@ export class AgentsApi extends ApiTopic {
 
             sse.addEventListener('history', (ev: MessageEvent) => {
                 try {
-                    const data = JSON.parse(ev.data);
+                    const data = JSON.parse(ev.data) as Extract<AgentRunDetailsStreamEvent, { type: 'history' }>['data'];
                     if (onEvent) onEvent({ type: 'history', data });
                 } catch (_err) { /* ignore parse errors */ }
             });
 
             sse.addEventListener('control', (ev: MessageEvent) => {
                 try {
-                    const data = JSON.parse(ev.data);
+                    const data = JSON.parse(ev.data) as Extract<AgentRunDetailsStreamEvent, { type: 'control' }>['data'];
                     if (onEvent) onEvent({ type: 'control', data });
-                    if (data.type === 'done') {
+                    if ('type' in data && data.type === 'done') {
                         cleanup();
                         resolve();
                     }
@@ -504,7 +500,7 @@ export class AgentsApi extends ApiTopic {
 
             sse.addEventListener('error', (ev: MessageEvent) => {
                 try {
-                    const data = JSON.parse(ev.data);
+                    const data = JSON.parse(ev.data) as Extract<AgentRunDetailsStreamEvent, { type: 'error' }>['data'];
                     if (onEvent) onEvent({ type: 'error', data });
                 } catch (_err) { /* ignore parse errors */ }
             });
@@ -523,15 +519,34 @@ export class AgentsApi extends ApiTopic {
         return this.get(`/${id}/children`);
     }
 
+    /**
+     * Get details for a specific child workflow.
+     * Serves from GCS archive when available, falls back to Temporal.
+     */
+    getChildDetails(
+        id: string,
+        childWorkflowId: string,
+        options?: { includeHistory?: boolean },
+    ): Promise<WorkflowRunWithDetails> {
+        const query: Record<string, string> = {};
+        if (options?.includeHistory) query.include_history = 'true';
+        return this.get(`/${id}/children/${childWorkflowId}/details`, { query });
+    }
+
     // ========================================================================
     // Artifacts
     // ========================================================================
 
     /**
      * List artifacts for an agent run.
+     * visibility:
+     * - 'user' (default): only user-facing artifacts
+     * - 'internal': only system-managed state files such as conversation snapshots
+     * - 'all': both user-facing and internal files
      */
-    listArtifacts(id: string): Promise<string[]> {
-        return this.get(`/${id}/artifacts`);
+    listArtifacts(id: string, options?: { visibility?: 'user' | 'internal' | 'all' }): Promise<string[]> {
+        const query = options?.visibility ? { visibility: options.visibility } : undefined;
+        return this.get(`/${id}/artifacts`, { query });
     }
 
     /**
@@ -541,9 +556,11 @@ export class AgentsApi extends ApiTopic {
         id: string,
         path: string,
         disposition?: 'inline' | 'attachment',
-    ): Promise<{ url: string; path: string }> {
+        fileName?: string,
+    ): Promise<AgentArtifactUrlResponse> {
         const query: Record<string, string> = { url: '1' };
         if (disposition) query.disposition = disposition;
+        if (fileName) query.filename = fileName;
         return this.get(`/${id}/artifacts/${path}`, { query });
     }
 
@@ -561,13 +578,13 @@ export class AgentsApi extends ApiTopic {
         path: string,
         content: Blob | ReadableStream | ArrayBuffer | string,
         contentType?: string,
-    ): Promise<{ url: string; path: string }> {
+    ): Promise<AgentArtifactUrlResponse> {
         const mimeType = contentType || 'application/octet-stream';
 
         // 1. Get signed upload URL from the agents API
         const result = await this.put(`/${id}/artifacts/${path}`, {
             headers: { 'Content-Type': mimeType },
-        }) as { url: string; path: string };
+        }) as AgentArtifactUrlResponse;
 
         // 2. Upload directly to cloud storage
         const res = await fetch(result.url, {
@@ -612,8 +629,9 @@ export class AgentsApi extends ApiTopic {
     ingestEvents(
         agentRunId: string,
         events: AgentEvent[],
-    ): Promise<{ ingested: number; status?: string; error?: string }> {
-        return this.post(`/${agentRunId}/events`, { payload: { events } });
+    ): Promise<IngestAgentEventsResponse> {
+        const payload: IngestAgentEventsPayload = { events };
+        return this.post(`/${agentRunId}/events`, { payload });
     }
 
     // ========================================================================
@@ -762,4 +780,5 @@ export class AgentsApi extends ApiTopic {
     ): Promise<FirstResponseBehaviorAnalyticsResponse> {
         return this.post('/analytics/first-response-behavior', { payload: query });
     }
+
 }

package/src/store/CostApi.ts

@@ -0,0 +1,67 @@
+import { ApiTopic, ClientBase } from '@vertesia/api-fetch-client';
+import { CostAnalyticsQuery, CostAnalyticsResponse, CostRunPriceQuery, CostRunPriceResponse, ModelPriceComparisonResponse } from '@vertesia/common';
+
+export class CostApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, '/api/v1/cost');
+    }
+
+    /**
+     * Get cost analytics for the current project.
+     * Returns cost breakdown by model/environment with pricing from billing export.
+     * Covers all inference types: direct, agent, embedding.
+     */
+    getAnalytics(
+        query: CostAnalyticsQuery = {}
+    ): Promise<CostAnalyticsResponse> {
+        return this.post('/analytics', { payload: query });
+    }
+
+    /**
+     * Get platform-wide cost analytics across all customers.
+     * Requires Vertesia staff privileges. Defaults to group_by='account'.
+     */
+    getGlobalAnalytics(
+        query: CostAnalyticsQuery = {}
+    ): Promise<CostAnalyticsResponse> {
+        return this.post('/analytics/global', { payload: query });
+    }
+
+    /**
+     * Get current list prices and effective prices for the selected period.
+     */
+    getModelPrices(
+        query: Pick<CostAnalyticsQuery, 'from' | 'to'> = {}
+    ): Promise<ModelPriceComparisonResponse> {
+        return this.get('/model-prices', { query });
+    }
+
+    /**
+     * Price a single interaction run or agent run.
+     */
+    getRunPrice(
+        query: CostRunPriceQuery
+    ): Promise<CostRunPriceResponse> {
+        return this.post('/run-price', { payload: query });
+    }
+
+    /**
+     * Price a run and include the full model pricing catalog for comparison.
+     */
+    getRunPriceComparison(
+        query: CostRunPriceQuery
+    ): Promise<CostRunPriceResponse> {
+        return this.post('/run-price', { payload: { ...query, include_comparison_pricing: true } });
+    }
+
+    /**
+     * Get the CSV export URL for raw inference audit events.
+     */
+    getExportUrl(params?: { from?: string | number; to?: string | number }): string {
+        const searchParams = new URLSearchParams();
+        if (params?.from) searchParams.set('from', typeof params.from === 'number' ? new Date(params.from).toISOString() : params.from);
+        if (params?.to) searchParams.set('to', typeof params.to === 'number' ? new Date(params.to).toISOString() : params.to);
+        const qs = searchParams.toString();
+        return `${this.baseUrl}/export${qs ? `?${qs}` : ''}`;
+    }
+}