@vertesia/client 1.5.0-dev.20260725.083715Z → 1.5.0-dev.20260806.125520Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "1.5.0-dev.20260725.083715Z",
+  "version": "1.5.0-dev.20260806.125520Z",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,15 +13,15 @@
   "devDependencies": {
     "@types/node": "^24.13.3",
     "rolldown": "1.2.0",
-    "typescript": "^6.0.3",
+    "typescript": "7.0.2",
     "vitest": "^4.1.10",
     "@vertesia/tsconfig": "0.1.0"
   },
   "dependencies": {
     "eventsource": "^4.1.0",
-    "@llumiverse/common": "1.5.0-dev.20260725.065646Z",
-    "@vertesia/api-fetch-client": "1.5.0-dev.20260725.083715Z",
-    "@vertesia/common": "1.5.0-dev.20260725.083715Z"
+    "@llumiverse/common": "1.5.0-dev.20260806.124634Z",
+    "@vertesia/common": "1.5.0-dev.20260806.125520Z",
+    "@vertesia/api-fetch-client": "1.5.0-dev.20260806.125520Z"
   },
   "exports": {
     ".": {
@@ -48,7 +48,7 @@
     "ai",
     "typescript"
   ],
-  "gitHead": "57bcc2f27dd17b3387f27c18e89329c4c37f98ac",
+  "gitHead": "416423ef4182d8668809604902a871ca79629298",
   "scripts": {
     "lint": "biome lint src",
     "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",

package/src/AccountApi.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it, vi } from 'vitest';
+import { VertesiaClient } from './client.js';
+
+describe('AccountApi', () => {
+    it('returns onboarding.completed_at as the ISO string received over JSON', async () => {
+        const completedAt = '2026-07-29T10:00:00.000Z';
+        const fetchMock = vi.fn(async () => {
+            return new Response(
+                JSON.stringify({
+                    id: 'account-id',
+                    onboarding: { completed: true, completed_at: completedAt },
+                }),
+                {
+                    status: 200,
+                    headers: { 'content-type': 'application/json' },
+                },
+            );
+        });
+        const client = new VertesiaClient({
+            serverUrl: 'https://api.example.com',
+            storeUrl: 'https://api.example.com',
+            fetch: fetchMock,
+        });
+
+        const account = await client.account.info();
+
+        expect(account.onboarding.completed_at).toBe(completedAt);
+        expect(account.onboarding.completed_at).not.toBeInstanceOf(Date);
+    });
+});

package/src/AccountApi.ts

@@ -9,10 +9,9 @@ import type {
     OnboardingProgress,
     ProjectRef,
     StripeBillingStatusResponse,
-    TransientToken,
     UpdateAccountPayload,
     User,
-    UserInviteTokenData,
+    UserInviteToken,
 } from '@vertesia/common';
 
 export default class AccountApi extends ApiTopic {
@@ -56,17 +55,20 @@ export default class AccountApi extends ApiTopic {
 
     /**
      * Fetch Invites for Principal
-     * @returns UserInviteTokenData[]
-     * */
-    listInvites(): Promise<TransientToken<UserInviteTokenData>[]> {
+     *
+     * Returns `UserInviteToken[]`, not `TransientToken<UserInviteTokenData>[]`. The latter declared
+     * `Date` for `expires`, `created_at` and `updated_at`, which no HTTP response can carry — the
+     * client hands back whatever `JSON.parse` produced, so those three were always strings. It now
+     * says so.
+     */
+    listInvites(): Promise<UserInviteToken[]> {
         return this.get('/invites');
     }
     /**
      * Fetch Invites for specific account or project
      * @param type Filter for the type of invitation, either "project" or "account"
-     * @returns UserInviteTokenData[]
-     * */
-    listInvitation(type: 'project' | 'account' = 'project'): Promise<TransientToken<UserInviteTokenData>[]> {
+     */
+    listInvitation(type: 'project' | 'account' = 'project'): Promise<UserInviteToken[]> {
         return this.get(`/invites/${type}`);
     }
 

package/src/ApiKeysApi.ts

@@ -4,9 +4,10 @@ import type {
     ApiKeyReadResponse,
     ApiKeyWithValue,
     AuthTokenResponse,
-    CreateOrUpdateApiKeyPayload,
+    CreateApiKeyPayload,
     CreatePublicKeyPayload,
     DeleteOperationResult,
+    UpdateApiKeyPayload,
 } from '@vertesia/common';
 
 export class ApiKeysApi extends ApiTopic {
@@ -28,7 +29,7 @@ export class ApiKeysApi extends ApiTopic {
      * ALL REQUESTS ARE LOGGED IN SECURITY AUDIT LOG
      * @returns ApiKeyWithValue
      */
-    create(payload: CreateOrUpdateApiKeyPayload): Promise<ApiKeyWithValue> {
+    create(payload: CreateApiKeyPayload): Promise<ApiKeyWithValue> {
         return this.post('/', { payload });
     }
 
@@ -36,7 +37,7 @@ export class ApiKeysApi extends ApiTopic {
      * Update an existing ApiKey for account
      * @returns ApiKey
      */
-    update(id: string, payload: CreateOrUpdateApiKeyPayload): Promise<ApiKey> {
+    update(id: string, payload: UpdateApiKeyPayload): Promise<ApiKey> {
         return this.put(`/${id}`, { payload });
     }
 

package/src/AppsApi.ts

@@ -1,5 +1,6 @@
 import { ApiTopic, type ClientBase, type ServerError } from '@vertesia/api-fetch-client';
 import type {
+    AppApiKeyCollectionParams,
     AppBuildProgress,
     AppDeleteSummary,
     AppDevelopmentTaskDetails,
@@ -26,9 +27,11 @@ import type {
     CountResult,
     CreateAppRepoBranchRequest,
     DeleteAppVersionResponse,
+    McpApiKeyStatus,
     ProjectRef,
     PromoteAppVersionResponse,
     RequireAtLeastOne,
+    SetMcpApiKeyRequest,
     StartAppBuildRequest,
     StartAppBuildResponse,
     StartAppScaffoldRequest,
@@ -64,6 +67,27 @@ export default class AppsApi extends ApiTopic {
         return this.del(`/${id}`);
     }
 
+    /**
+     * Store the API key of an MCP tool collection declared with `auth: 'api_key'`.
+     * The key is write-only: it is encrypted server-side and never returned by any endpoint,
+     * so the response carries only the configured flag and a masked hint.
+     */
+    setMcpCollectionApiKey(appId: string, collectionId: string, apiKey: string): Promise<McpApiKeyStatus> {
+        return this.put(`/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collectionId)}/api-key`, {
+            payload: { api_key: apiKey } satisfies SetMcpApiKeyRequest,
+        });
+    }
+
+    /** Whether an MCP tool collection has an API key stored, with a masked hint for display. */
+    getMcpCollectionApiKeyStatus(appId: string, collectionId: string): Promise<McpApiKeyStatus> {
+        return this.get(`/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collectionId)}/api-key`);
+    }
+
+    /** Remove the stored API key of an MCP tool collection. */
+    deleteMcpCollectionApiKey(appId: string, collectionId: string): Promise<McpApiKeyStatus> {
+        return this.del(`/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collectionId)}/api-key`);
+    }
+
     /**
      * Cascade-delete an app and everything attached to it (versions,
      * installations + ACEs, git repo on the app-git server). Pass through
@@ -288,6 +312,7 @@ export default class AppsApi extends ApiTopic {
         settings?: Record<string, unknown>,
         oauthParams?: Record<string, { client_id?: string; client_secret?: string; scopes?: string[] }>,
         oauthProviderParams?: Record<string, { client_id?: string; client_secret?: string; scopes?: string[] }>,
+        apiKeyParams?: AppApiKeyCollectionParams,
     ): Promise<AppInstallation> {
         return this.post(`/install`, {
             payload: {
@@ -295,6 +320,7 @@ export default class AppsApi extends ApiTopic {
                 settings,
                 oauth_params: oauthParams,
                 oauth_provider_params: oauthProviderParams,
+                api_key_params: apiKeyParams,
             } satisfies AppInstallationPayload,
         });
     }

package/src/EnvironmentsApi.ts

@@ -5,11 +5,9 @@ import type {
     EmbeddingsApiResult,
     EnableEnvironmentModelPayload,
     ExecutionEnvironment,
+    ExecutionEnvironmentConfigUpdatePayload,
     ExecutionEnvironmentCreatePayload,
-    ExecutionEnvironmentRef,
     ExecutionEnvironmentUpdatePayload,
-    LoadBalancingEnvConfig,
-    MediatorEnvConfig,
     MigrateInteractionsPayload,
     MigrateInteractionsResult,
 } from '@vertesia/common';
@@ -23,7 +21,7 @@ export default class EnvironmentsApi extends ApiTopic {
      * List all environments for the current project
      * @param all if true, list all environments, otherwise only the ones for the current project
      */
-    list(all: boolean = false): Promise<ExecutionEnvironmentRef[]> {
+    list(all: boolean = false): Promise<ExecutionEnvironment[]> {
         const query = all ? { all: true } : undefined;
 
         return this.get('/', { query });
@@ -54,13 +52,7 @@ export default class EnvironmentsApi extends ApiTopic {
      * @param payload
      * @returns
      */
-    updateConfig(
-        id: string,
-        payload: {
-            enabled_models?: AIModel[];
-            config?: MediatorEnvConfig | LoadBalancingEnvConfig;
-        },
-    ): Promise<ExecutionEnvironment> {
+    updateConfig(id: string, payload: ExecutionEnvironmentConfigUpdatePayload): Promise<ExecutionEnvironment> {
         return this.put(`/${id}/config`, {
             payload,
         });

package/src/GroupsApi.ts

@@ -12,6 +12,8 @@ export interface GroupsQueryOptions {
     tags?: string[];
     limit?: number;
     offset?: number;
+    /** Only return groups usable in this project (org-wide + restricted-to-this-project). */
+    project?: string;
     [key: string]: string | string[] | number | undefined;
 }
 

package/src/OAuthGrantsApi.ts

@@ -5,6 +5,7 @@ import type {
     OAuthGrant,
     OAuthGrantListResponse,
     OAuthGrantRevokeResponse,
+    RevokeOAuthGrantQuery,
 } from '@vertesia/common';
 
 function toQueryRecord(query?: ListOAuthGrantsQuery): Record<string, string> | undefined {
@@ -32,7 +33,7 @@ export default class OAuthGrantsApi extends ApiTopic {
         return this.get(`/${grantId}`);
     }
 
-    revoke(grantId: string, query?: { include_consent?: boolean }): Promise<OAuthGrantRevokeResponse> {
+    revoke(grantId: string, query?: RevokeOAuthGrantQuery): Promise<OAuthGrantRevokeResponse> {
         return this.del(`/${grantId}`, { query });
     }
 

package/src/OAuthProvidersApi.ts

@@ -30,7 +30,12 @@ export default class OAuthProvidersApi extends ApiTopic {
         return this.put(`/${id}`, { payload });
     }
 
-    remove(id: string): Promise<void> {
+    /**
+     * `SuccessResponse`, not `void`: the endpoint has always returned `{ success: true }` and the
+     * document has always published it. Typing it as `void` meant a caller could not read the one
+     * field it sends without casting.
+     */
+    remove(id: string): Promise<SuccessResponse> {
         return this.del(`/${id}`);
     }
 

package/src/PromptsApi.ts

@@ -1,29 +1,28 @@
-import type { PromptRole } from '@llumiverse/common';
 import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
 import type {
+    ComputedFacetResponse,
     ComputePromptFacetPayload,
     PromptSearchPayload,
     PromptSearchQuery,
     PromptTemplate,
     PromptTemplateCreatePayload,
     PromptTemplateForkPayload,
+    PromptTemplateInteractionsResponse,
     PromptTemplateRef,
     PromptTemplateUpdatePayload,
-    TemplateType,
+    RenderPromptPayload,
+    RenderPromptResponse,
 } from '@vertesia/common';
 
-export interface ComputePromptFacetsResponse {
-    role?: { _id: string; count: number }[];
-    total?: { count: number }[];
-}
+/**
+ * @deprecated Use `ComputedFacetResponse` from `@vertesia/common`, which is what the endpoint
+ * publishes. This restated the facet buckets in their pre-collapse shape: `total` is a number by
+ * the time the response is written, not a one-element array.
+ */
+export type ComputePromptFacetsResponse = ComputedFacetResponse;
 
-export interface PromptRenderResponse {
-    id: string;
-    name: string;
-    role: PromptRole;
-    content_type: TemplateType;
-    rendered: string;
-}
+/** @deprecated Use `RenderPromptResponse` from `@vertesia/common`. */
+export type PromptRenderResponse = RenderPromptResponse;
 
 export default class PromptsApi extends ApiTopic {
     constructor(parent: ClientBase) {
@@ -48,9 +47,9 @@ export default class PromptsApi extends ApiTopic {
     /**
      * Get the list of all prompt facets
      * @param payload query payload to filter facet search
-     * @returns ComputePromptFacetsResponse[]
+     * @returns ComputedFacetResponse
      **/
-    computeFacets(query: ComputePromptFacetPayload): Promise<ComputePromptFacetsResponse> {
+    computeFacets(query: ComputePromptFacetPayload): Promise<ComputedFacetResponse> {
         return this.post('/facets', {
             payload: query,
         });
@@ -125,7 +124,7 @@ export default class PromptsApi extends ApiTopic {
      * @throws 404 if not found
      * @throws 403 if the prompt is not in the current project
      */
-    render(id: string, payload: object): Promise<PromptRenderResponse> {
+    render(id: string, payload: RenderPromptPayload): Promise<RenderPromptResponse> {
         return this.post(`/${id}/render`, {
             payload,
         });
@@ -153,7 +152,7 @@ export default class PromptsApi extends ApiTopic {
     /**
      * Retrieve list of interactions that use the prompt template
      */
-    listInteractions(id: string): Promise<ListInteractionsResponse> {
+    listInteractions(id: string): Promise<PromptTemplateInteractionsResponse> {
         return this.get(`/${id}/interactions`);
     }
 
@@ -167,11 +166,9 @@ export default class PromptsApi extends ApiTopic {
     }
 }
 
-export interface ListInteractionsResponse {
-    prompt: string;
-    interactions: {
-        id: string;
-        name: string;
-        versions: string[];
-    }[];
-}
+/**
+ * @deprecated Use `PromptTemplateInteractionsResponse` from `@vertesia/common`, which is what the
+ * endpoint publishes. This declared `versions: string[]`; the endpoint has always sent
+ * `[{ version: number }]`.
+ */
+export type ListInteractionsResponse = PromptTemplateInteractionsResponse;

package/src/client.test.ts

@@ -1,3 +1,4 @@
+import { APP_VERSION_HEADER } from '@vertesia/common';
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
 import { isTokenExpired, VertesiaClient } from './client.js';
 
@@ -145,6 +146,21 @@ describe('Test Vertesia Client', () => {
         expect(client.baseUrl).toBe('https://studio-server-production.api.becomposable.com');
         expect(client.storeUrl).toBe('https://zeno-server-production.api.becomposable.com');
     });
+
+    test('withAppVersion keeps Studio and Store requests pinned together', () => {
+        const client = new VertesiaClient({
+            serverUrl: 'https://studio-server-production.api.becomposable.com',
+            storeUrl: 'https://zeno-server-production.api.becomposable.com',
+        });
+
+        expect(client.withAppVersion('candidate-v1')).toBe(client);
+        expect(client.headers[APP_VERSION_HEADER]).toBe('candidate-v1');
+        expect(client.store.headers[APP_VERSION_HEADER]).toBe('candidate-v1');
+
+        client.withAppVersion(null);
+        expect(client.headers[APP_VERSION_HEADER]).toBeUndefined();
+        expect(client.store.headers[APP_VERSION_HEADER]).toBeUndefined();
+    });
 });
 
 describe('isTokenExpired', () => {

package/src/client.ts

@@ -248,6 +248,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
      * exact built version instead of the promoted version. Pass null/empty to clear (→ promoted).
      */
     withAppVersion(version: string | null | undefined) {
+        this.store.withAppVersion(version);
         if (!version) {
             delete this.headers[APP_VERSION_HEADER];
         } else {