@vertesia/client 1.6.0-dev.20261009.095813Z → 1.6.0-dev.20261019.172735Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "1.6.0-dev.20261009.095813Z",
+  "version": "1.6.0-dev.20261019.172735Z",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -12,16 +12,16 @@
   ],
   "license": "Apache-2.0",
   "devDependencies": {
-    "@types/node": "^24.19.0",
+    "@types/node": "^24.19.1",
     "@vertesia/tsconfig": "0.1.0",
-    "rolldown": "1.2.11",
+    "rolldown": "1.2.12",
     "typescript": "7.0.2",
-    "vitest": "5.0.2"
+    "vitest": "5.0.3"
   },
   "dependencies": {
-    "@llumiverse/common": "1.6.0-dev.20261009.095504Z",
-    "@vertesia/api-fetch-client": "1.6.0-dev.20261009.095813Z",
-    "@vertesia/common": "1.6.0-dev.20261009.095813Z",
+    "@llumiverse/common": "1.6.0-dev.20261019.165531Z",
+    "@vertesia/api-fetch-client": "1.6.0-dev.20261019.172735Z",
+    "@vertesia/common": "1.6.0-dev.20261019.172735Z",
     "eventsource": "^5.1.2"
   },
   "exports": {
@@ -49,7 +49,7 @@
     "ai",
     "typescript"
   ],
-  "gitHead": "e45bc09ecf2de4c8fe8a8d39fb52c1521980e7b9",
+  "gitHead": "85a3010750ab97192d236928b1fca55015a18000",
   "scripts": {
     "lint": "biome lint src",
     "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",

package/src/AppsApi.ts

@@ -6,12 +6,16 @@ import type {
     AppDeleteSummary,
     AppDevelopmentTaskDetails,
     AppDevelopmentTaskList,
+    AppGithubConfiguration,
+    AppGithubRepositoryList,
+    AppGithubRepositorySetup,
     AppInspectionResult,
     AppInstallation,
     AppInstallationKind,
     AppInstallationListEntry,
     AppInstallationPayload,
     AppInstallationWithManifest,
+    AppInstanceAvailability,
     AppManifest,
     AppManifestData,
     AppPackage,
@@ -29,6 +33,7 @@ import type {
     CountResult,
     CreateAppRepoBranchRequest,
     DeleteAppVersionResponse,
+    ExchangeAppGithubAuthorizationResponse,
     McpApiKeyStatus,
     ProjectRef,
     PromoteAppVersionResponse,
@@ -37,6 +42,7 @@ import type {
     StartAppBuildRequest,
     StartAppBuildResponse,
     StartAppDevelopmentTaskRequest,
+    StartAppGithubAuthorizationResponse,
     StartAppScaffoldRequest,
     StartAppScaffoldResponse,
     UpdateAppInstallationOAuthApprovalPayload,
@@ -75,6 +81,27 @@ export default class AppsApi extends ApiTopic {
      * 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.
      */
+    setInstallationMcpApiKey(installationId: string, collectionId: string, apiKey: string): Promise<McpApiKeyStatus> {
+        return this.put(
+            `/installations/${encodeURIComponent(installationId)}/collections/${encodeURIComponent(collectionId)}/api-key`,
+            {
+                payload: { api_key: apiKey },
+            },
+        );
+    }
+
+    getInstallationMcpApiKeyStatus(installationId: string, collectionId: string): Promise<McpApiKeyStatus> {
+        return this.get(
+            `/installations/${encodeURIComponent(installationId)}/collections/${encodeURIComponent(collectionId)}/api-key`,
+        );
+    }
+
+    deleteInstallationMcpApiKey(installationId: string, collectionId: string): Promise<McpApiKeyStatus> {
+        return this.del(
+            `/installations/${encodeURIComponent(installationId)}/collections/${encodeURIComponent(collectionId)}/api-key`,
+        );
+    }
+
     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,
@@ -149,6 +176,63 @@ export default class AppsApi extends ApiTopic {
         return this.get(`/scaffolds/${encodeURIComponent(workflowId)}/${encodeURIComponent(runId)}/progress`);
     }
 
+    /**
+     * Return whether the global App Builder GitHub App is configured, together with its slug and
+     * installation URL when available.
+     */
+    getGithubConfiguration(): Promise<AppGithubConfiguration> {
+        return this.get('/source-providers/github');
+    }
+
+    /**
+     * Start GitHub user authorization. The server creates a short-lived, single-use OAuth state
+     * bound to the current Vertesia user/account/project and returns the GitHub authorization URL.
+     */
+    startGithubAuthorization(): Promise<StartAppGithubAuthorizationResponse> {
+        return this.post('/source-providers/github/authorize', {});
+    }
+
+    /**
+     * Complete GitHub authorization with the callback code and state. The server consumes the state,
+     * verifies the current user's writable GitHub App installations, discards the GitHub user token,
+     * and returns those installations plus an opaque `connection_id`. That id references a
+     * short-lived server-side snapshot of the writable repositories verified for this Vertesia
+     * user/account/project; selecting a repository consumes it once.
+     */
+    exchangeGithubAuthorization(code: string, state: string): Promise<ExchangeAppGithubAuthorizationResponse> {
+        return this.post('/source-providers/github/exchange', { payload: { code, state } });
+    }
+
+    /**
+     * List repositories with push access for one installation verified during authorization. The
+     * connection id is scoped to the current Vertesia user/account/project and expires shortly.
+     */
+    listGithubRepositories(connectionId: string, installationId: string): Promise<AppGithubRepositoryList> {
+        return this.get('/source-providers/github/repositories', {
+            query: { connection_id: connectionId, installation_id: installationId },
+        });
+    }
+
+    /**
+     * List branches and verify whether a selected branch can safely receive generated source.
+     * The verified connection remains reusable until app creation consumes it.
+     */
+    getGithubRepositorySetup(
+        connectionId: string,
+        installationId: string,
+        repository: string,
+        branch: string,
+    ): Promise<AppGithubRepositorySetup> {
+        return this.get('/source-providers/github/repository-setup', {
+            query: {
+                connection_id: connectionId,
+                installation_id: installationId,
+                repository,
+                branch,
+            },
+        });
+    }
+
     /**
      * Get the list if tools provided by the given app.
      * @param appId
@@ -328,14 +412,20 @@ export default class AppsApi extends ApiTopic {
         oauthParams?: Record<string, { client_id?: string; client_secret?: string; scopes?: string[] }>,
         oauthProviderParams?: Record<string, { client_id?: string; client_secret?: string; scopes?: string[] }>,
         apiKeyParams?: AppApiKeyCollectionParams,
+        mcpParameters?: AppInstallationPayload['mcp_parameters'],
+        mcpSharedParameters?: AppInstallationPayload['mcp_shared_parameters'],
+        instance?: Pick<AppInstallationPayload, 'instance_key' | 'display_name' | 'namespace_overrides'>,
     ): Promise<AppInstallation> {
         return this.post(`/install`, {
             payload: {
                 app_id: appId,
+                ...instance,
                 settings,
                 oauth_params: oauthParams,
                 oauth_provider_params: oauthProviderParams,
                 api_key_params: apiKeyParams,
+                mcp_parameters: mcpParameters,
+                mcp_shared_parameters: mcpSharedParameters,
             } satisfies AppInstallationPayload,
         });
     }
@@ -353,6 +443,14 @@ export default class AppsApi extends ApiTopic {
      * get an app unstallation given its name or null if the app is not installed
      * @returns
      */
+    getAppInstanceAvailability(): Promise<AppInstanceAvailability> {
+        return this.get('/instance-availability');
+    }
+
+    getAppInstallation(installationId: string): Promise<AppInstallationWithManifest> {
+        return this.get(`/installations/id/${encodeURIComponent(installationId)}`);
+    }
+
     getAppInstallationByName(appName: string): Promise<AppInstallationWithManifest | null> {
         return this.get<AppInstallationWithManifest>(`/installations/name/${appName}`).catch((err: ServerError) => {
             if (err.status === 404) {
@@ -426,6 +524,14 @@ export default class AppsApi extends ApiTopic {
                 // clear an override). The server uses `'access_control' in payload` to distinguish
                 // "leave unchanged" from "clear", so only spread the key when it was supplied.
                 ...('access_control' in settingsPayload ? { access_control: settingsPayload.access_control } : {}),
+                ...('display_name' in settingsPayload ? { display_name: settingsPayload.display_name } : {}),
+                ...('namespace_overrides' in settingsPayload
+                    ? { namespace_overrides: settingsPayload.namespace_overrides }
+                    : {}),
+                ...('mcp_parameters' in settingsPayload ? { mcp_parameters: settingsPayload.mcp_parameters } : {}),
+                ...('mcp_shared_parameters' in settingsPayload
+                    ? { mcp_shared_parameters: settingsPayload.mcp_shared_parameters }
+                    : {}),
             } satisfies AppInstallationPayload,
         });
     }

package/src/OAuthServerApi.ts

@@ -9,6 +9,9 @@ import type {
     OAuthGrantableScopesResponse,
     OAuthLoginDecisionResponse,
     OAuthLoginPayload,
+    OAuthTokenExchangeRequest,
+    OAuthTokenExchangeResponse,
+    ProjectRef,
 } from '@vertesia/common';
 
 export default class OAuthServerApi extends ClientBase {
@@ -22,6 +25,30 @@ export default class OAuthServerApi extends ClientBase {
         this.verboseErrors = parent.verboseErrors;
     }
 
+    /** Exchange a signed IdP assertion; optional client authentication follows the connection policy. */
+    exchangeToken(
+        payload: OAuthTokenExchangeRequest,
+        basic?: { client_id: string; client_secret: string },
+    ): Promise<OAuthTokenExchangeResponse> {
+        if (
+            basic &&
+            (payload.client_secret !== undefined ||
+                payload.client_assertion !== undefined ||
+                (payload.client_id !== undefined && payload.client_id !== basic.client_id))
+        )
+            throw new Error('Use exactly one client authentication method');
+        return this.post('/token', {
+            payload,
+            ...(basic
+                ? {
+                      headers: {
+                          Authorization: `Basic ${btoa(`${encodeURIComponent(basic.client_id)}:${encodeURIComponent(basic.client_secret)}`)}`,
+                      },
+                  }
+                : {}),
+        });
+    }
+
     login(requestId: string, payload: OAuthLoginPayload): Promise<OAuthLoginDecisionResponse> {
         return this.post(`/requests/${encodeURIComponent(requestId)}/login`, { payload });
     }
@@ -76,6 +103,10 @@ export default class OAuthServerApi extends ClientBase {
         return this.get(`/requests/${requestId}`);
     }
 
+    retrieveGrantableProjects(requestId: string): Promise<ProjectRef[]> {
+        return this.get(`/requests/${encodeURIComponent(requestId)}/grantable-projects`);
+    }
+
     retrieveGrantableScopes(requestId: string, projectId: string): Promise<OAuthGrantableScopesResponse> {
         return this.get(`/requests/${requestId}/grantable-scopes`, { query: { project_id: projectId } });
     }

package/src/OidcFederationApi.ts

@@ -0,0 +1,23 @@
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type { OidcFederationConnection, OidcFederationConnectionPayload, SuccessResponse } from '@vertesia/common';
+
+export default class OidcFederationApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, '/api/v1/oidc-federation');
+    }
+    retrieve(id: string): Promise<OidcFederationConnection> {
+        return this.get(`/${encodeURIComponent(id)}`);
+    }
+    list(): Promise<OidcFederationConnection[]> {
+        return this.get('/');
+    }
+    create(payload: OidcFederationConnectionPayload): Promise<OidcFederationConnection> {
+        return this.post('/', { payload });
+    }
+    update(id: string, payload: OidcFederationConnectionPayload): Promise<OidcFederationConnection> {
+        return this.put(`/${encodeURIComponent(id)}`, { payload });
+    }
+    remove(id: string): Promise<SuccessResponse> {
+        return this.del(`/${encodeURIComponent(id)}`);
+    }
+}

package/src/client.ts

@@ -18,6 +18,7 @@ import OAuthClientsApi from './OAuthClientsApi.js';
 import OAuthGrantsApi from './OAuthGrantsApi.js';
 import OAuthProvidersApi from './OAuthProvidersApi.js';
 import OAuthServerApi from './OAuthServerApi.js';
+import OidcFederationApi from './OidcFederationApi.js';
 import ProjectsApi from './ProjectsApi.js';
 import PromptsApi from './PromptsApi.js';
 import QuotaApi from './QuotaApi.js';
@@ -120,6 +121,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
      */
     tokenServerUrl: string;
 
+    oidcFederation: OidcFederationApi;
     oauthClients: OAuthClientsApi;
     oauthGrants: OAuthGrantsApi;
     oauthServer: OAuthServerApi;
@@ -251,6 +253,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         this.onRequest = opts.onRequest;
         this.onResponse = opts.onResponse;
         this.sessionTags = opts.sessionTags;
+        this.oidcFederation = new OidcFederationApi(this);
         this.oauthClients = new OAuthClientsApi(this);
         this.oauthGrants = new OAuthGrantsApi(this);
         this.oauthServer = new OAuthServerApi(this, this.tokenServerUrl);

package/src/index.ts

@@ -12,6 +12,7 @@ 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 OidcFederationApi } from './OidcFederationApi.js';
 export type { ComputePromptFacetsResponse, ListInteractionsResponse } from './PromptsApi.js';
 export { default as RemoteMcpConnectionsApi } from './RemoteMcpConnectionsApi.js';
 export type { ComputeRunFacetsResponse, FilterOption } from './RunsApi.js';

package/src/store/ObjectsApi.ts

@@ -39,6 +39,7 @@ import {
     type ObjectSearchResponse,
     type ProjectedContentObjectApiResponse,
     type SetObjectEmbeddingsResponse,
+    type SetObjectTextPayload,
     type StartContentObjectExportRequest,
     type StartContentObjectExportResponse,
     type SupportedEmbeddingTypes,
@@ -280,6 +281,18 @@ export class ObjectsApi extends ApiTopic {
         return this.get(`/${id}/text`);
     }
 
+    /**
+     * Store the extracted text of an object as a text artifact.
+     *
+     * Pass the content etag the text was extracted from so the server records it as the
+     * object `text_etag`, allowing extraction to be skipped while the content is unchanged.
+     */
+    setObjectText(id: string, payload: SetObjectTextPayload): Promise<ContentObjectTextResponse> {
+        return this.put(`/${id}/text`, {
+            payload,
+        });
+    }
+
     async upload(source: StreamSource | File) {
         const isStream = source instanceof StreamSource;
         // get a signed URL to upload the file a computed mimeType and the file object id.

package/src/store/ProcessApi.ts

@@ -50,8 +50,15 @@ export class ProcessApi extends ApiTopic {
         return this.get(`/${id}/versions`);
     }
 
+    /**
+     * Publish a draft revision. Set `idempotency_key` to make the call safe to retry: without one, a
+     * replay of a publish that already succeeded is rejected, so no client retry applies.
+     */
     publish(id: string, payload: PublishProcessDefinitionPayload): Promise<ProcessDefinition> {
-        return this.post(`/${id}/publish`, { payload });
+        return this.post(`/${id}/publish`, {
+            payload,
+            retryPolicy: payload.idempotency_key ? undefined : false,
+        });
     }
 
     revert(id: string, payload: RevertProcessDefinitionPayload): Promise<ProcessDefinition> {
@@ -82,8 +89,15 @@ export class ProcessApi extends ApiTopic {
         return this.del(`/${processId}/test-suites/${suiteId}`);
     }
 
+    /**
+     * Start a test run against a stored process revision. Set `idempotency_key` to make the call
+     * safe to retry: without one, a replay would start a second run, so no client retry applies.
+     */
     startTestRun(processId: string, payload: StartProcessTestRunPayload): Promise<ProcessTestRun> {
-        return this.post(`/${processId}/test-runs`, { payload });
+        return this.post(`/${processId}/test-runs`, {
+            payload,
+            retryPolicy: payload.idempotency_key ? undefined : false,
+        });
     }
 
     listTestRuns(processId: string, query?: ListProcessTestRunsQuery): Promise<ProcessTestRun[]> {

package/src/store/ProcessTestRunApi.ts

@@ -17,13 +17,17 @@ export class ProcessTestRunApi extends ApiTopic {
      * Start a test run against an in-code process or an inline definition, with the scenarios
      * supplied in the request instead of a stored suite. Use
      * `client.store.processes.startTestRun()` for stored process definitions and their suites.
+     *
+     * Set `idempotency_key` to make the call safe to retry: the client's retry policy then applies,
+     * and a replayed request returns the run the first one started.
      */
     submit(payload: SubmitProcessTestRunPayload): Promise<ProcessTestRun> {
-        // Starting a run is not idempotent and the contract carries no request key, so a replay
-        // would create a second run. Opt out of any client-level retry policy explicitly rather
-        // than relying on POST being absent from its method list. Rate-limiter pacing retries are
-        // unaffected: those happen before the request reaches the handler.
-        return this.post('/', { payload, retryPolicy: false });
+        // Without a key, starting a run is not idempotent: a request abandoned client-side can still
+        // complete server-side, so a replay would create a second run. Opt out of any client-level
+        // retry policy explicitly rather than relying on POST being absent from its method list.
+        // Rate-limiter pacing retries are unaffected: those happen before the request reaches the
+        // handler.
+        return this.post('/', { payload, retryPolicy: payload.idempotency_key ? undefined : false });
     }
 
     retrieve(runId: string): Promise<ProcessTestRun> {