@tai42/api-client 19.3.0 → 21.0.0

package/src/client/auth-client.ts

@@ -1,5 +1,5 @@
 /** Auth scopes, routes, roles and API-key sub-client. */
-import { encodeSegment } from '../http';
+import { apiRoutes, buildPath } from '../generated/api-routes';
 import * as s from '../schemas';
 import type { Transport } from './transport';
 
@@ -72,99 +72,199 @@ export interface PinRoutePublicBody {
   readonly pattern?: string;
 }
 
-export function authClient(t: Transport) {
+/**
+ * Body for invoking a declared member action (POST
+ * `/api/auth/member-actions/invoke`). `action_key` is the opaque catalog key;
+ * `target_handle` is the row handle the action acts on, `null` for a page-scoped
+ * action; `input` is the per-action input the backend validates against the action's
+ * declared input model. All three are opaque to Studio — the keys are joined and
+ * echoed, the input is built from the action's `input_schema`, and no provider field
+ * is named here.
+ */
+export interface InvokeMemberActionBody {
+  readonly action_key: string;
+  readonly target_handle: string | null;
+  readonly input: Record<string, unknown>;
+}
+
+/** Scope mapping, the route catalog and the public-route pins. */
+function scopeRouteMethods(t: Transport) {
   const { req } = t;
   return {
-    listScopes: (signal?: AbortSignal) => req('/api/auth/scopes', s.authScopes, { signal }),
+    listScopes: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_auth_scopes.path, s.authScopes, { signal }),
     addUrlToScope: (body: AddUrlToScopeBody) =>
-      req('/api/auth/scopes', s.addUrlToScopeResult, { method: 'POST', body }),
+      req(apiRoutes.post_api_auth_scopes.path, s.addUrlToScopeResult, { method: 'POST', body }),
     removeUrlFromScope: (body: { url: string }) =>
-      req('/api/auth/scopes/urls', s.removeUrlFromScopeResult, { method: 'DELETE', body }),
-    removeScope: (scopeId: string) =>
-      req(`/api/auth/scopes/${encodeSegment(scopeId)}`, s.removeScopeResult, {
+      req(apiRoutes.delete_api_auth_scopes_urls.path, s.removeUrlFromScopeResult, {
         method: 'DELETE',
+        body,
       }),
+    removeScope: (scopeId: string) =>
+      req(
+        buildPath(apiRoutes.delete_api_auth_scopes_scope_id.path, { scope_id: scopeId }),
+        s.removeScopeResult,
+        {
+          method: 'DELETE',
+        },
+      ),
     // The app's HTTP route catalog with each route's current mapping — the only
     // source of the mapper's unassigned-routes bucket (`mapped: null` entries).
-    listAuthRoutes: (signal?: AbortSignal) => req('/api/auth/routes', s.authRoutes, { signal }),
+    listAuthRoutes: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_auth_routes.path, s.authRoutes, { signal }),
     // The urls pinned to the public marker; pinning/unpinning is the dedicated
     // public-routes writer, never the scope machinery.
     listPublicRoutes: (signal?: AbortSignal) =>
-      req('/api/auth/public-routes', s.publicRoutes, { signal }),
+      req(apiRoutes.get_api_auth_public_routes.path, s.publicRoutes, { signal }),
     pinRoutePublic: (body: PinRoutePublicBody) =>
-      req('/api/auth/public-routes', s.pinPublicResult, { method: 'POST', body }),
+      req(apiRoutes.post_api_auth_public_routes.path, s.pinPublicResult, { method: 'POST', body }),
     // Unpin a public url. A url that is absent or scope-mapped is a loud 404.
     unpinPublicRoute: (url: string) =>
-      req('/api/auth/public-routes', s.unpinPublicResult, { method: 'DELETE', body: { url } }),
+      req(apiRoutes.delete_api_auth_public_routes.path, s.unpinPublicResult, {
+        method: 'DELETE',
+        body: { url },
+      }),
+  };
+}
 
+/** Role bodies, their version history and rollback. */
+function roleMethods(t: Transport) {
+  const { req } = t;
+  return {
     // The seeded + operator-authored roles as full bodies (base-tier ceiling +
     // editable per-tag grant map). ADMIN-ONLY — the route is `secret` (a listing
     // exposes each role's raw base-tier jq); a non-admin projection never reaches it.
-    listRoles: (signal?: AbortSignal) => req('/api/auth/roles', s.roleList, { signal }),
+    listRoles: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_auth_roles.path, s.roleList, { signal }),
     // Create an operator-authored role. The server validates the grant map + base
     // tier and 409s on a name collision; the reserved `admin` role cannot be created.
     createRole: (body: RoleCreateBody) =>
-      req('/api/auth/roles', s.roleBody, { method: 'POST', body }),
+      req(apiRoutes.post_api_auth_roles.path, s.roleBody, { method: 'POST', body }),
     // Edit a role's per-tag grant map + description (omit-means-keep). The reserved
     // `admin` role and any `allow_all` role are block-downgrade guarded server-side.
     updateRole: (name: string, body: RoleUpdateBody) =>
-      req(`/api/auth/roles/${encodeSegment(name)}`, s.roleBody, { method: 'PUT', body }),
+      req(buildPath(apiRoutes.put_api_auth_roles_name.path, { name }), s.roleBody, {
+        method: 'PUT',
+        body,
+      }),
     // Delete a role. The reserved `admin` role is undeletable; a role still assigned
     // to any principal is a loud 409.
     deleteRole: (name: string) =>
-      req(`/api/auth/roles/${encodeSegment(name)}`, s.roleDeleted, { method: 'DELETE' }),
+      req(buildPath(apiRoutes.delete_api_auth_roles_name.path, { name }), s.roleDeleted, {
+        method: 'DELETE',
+      }),
     // A role's append-only version history + who/action/before→after audit trail.
     // ADMIN-ONLY (`secret`).
     listRoleVersions: (name: string, signal?: AbortSignal) =>
-      req(`/api/auth/roles/${encodeSegment(name)}/versions`, s.roleVersions, { signal }),
+      req(buildPath(apiRoutes.get_api_auth_roles_name_versions.path, { name }), s.roleVersions, {
+        signal,
+      }),
     // Re-point a role's active version to a prior one (LIVE — holders follow on
     // their next request); returns the re-pointed role body.
     rollbackRole: (name: string, version: number) =>
-      req(`/api/auth/roles/${encodeSegment(name)}/rollback`, s.roleBody, {
+      req(buildPath(apiRoutes.post_api_auth_roles_name_rollback.path, { name }), s.roleBody, {
         method: 'POST',
         body: { version },
       }),
+  };
+}
 
+/** API keys, claim links and the member directory with its actions. */
+function keyMemberMethods(t: Transport) {
+  const { req } = t;
+  return {
     listTokensPayload: (signal?: AbortSignal) =>
-      req('/api/auth/tokens-payload', s.tokensPayload, { signal }),
+      req(apiRoutes.get_api_auth_tokens_payload.path, s.tokensPayload, { signal }),
     createApiKey: (body: ApiKeyBody) =>
-      req('/api/auth/api-keys', s.createdApiKey, { method: 'POST', body }),
+      req(apiRoutes.post_api_auth_api_keys.path, s.createdApiKey, { method: 'POST', body }),
     editApiKey: (userId: string, body: Omit<ApiKeyBody, 'user_id'>) =>
-      req(`/api/auth/api-keys/${encodeSegment(userId)}`, s.editApiKeyResult, {
-        method: 'PUT',
-        body,
-      }),
+      req(
+        buildPath(apiRoutes.put_api_auth_api_keys_user_id.path, { user_id: userId }),
+        s.editApiKeyResult,
+        {
+          method: 'PUT',
+          body,
+        },
+      ),
     revokeApiKey: (userId: string) =>
-      req(`/api/auth/api-keys/${encodeSegment(userId)}`, s.revokeApiKeyResult, {
-        method: 'DELETE',
-      }),
+      req(
+        buildPath(apiRoutes.delete_api_auth_api_keys_user_id.path, { user_id: userId }),
+        s.revokeApiKeyResult,
+        {
+          method: 'DELETE',
+        },
+      ),
     // Mint a one-time claim link carrying a raw key to another device (the QR
     // onboarding leg). The token rides the URL fragment; the server returns a
     // relative `claim_path` and the raw token ONCE.
     createClaimLink: (body: ClaimLinkBody) =>
-      req('/api/auth/claim-links', s.claimLinkCreated, { method: 'POST', body }),
+      req(apiRoutes.post_api_auth_claim_links.path, s.claimLinkCreated, { method: 'POST', body }),
+
+    // The deployment-wide membership: every accounts provider's people and
+    // outstanding invitations, aggregated and platform-joined server-side into one
+    // directory (each row carrying its principal state + opaque routing tokens).
+    // ADMIN-ONLY (`secret`) — a non-admin projection never reaches the route.
+    listMembers: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_auth_members.path, s.memberDirectory, { signal }),
+
+    // The catalog of member-admin actions every accounts provider declares, each
+    // with its opaque key, rendered label, placement, and input/result JSON Schema.
+    // ADMIN-ONLY (`secret`) — the same fence the members listing carries.
+    listMemberActions: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_auth_member_actions.path, s.memberActionCatalog, { signal }),
+    // Invoke one declared action by its opaque key, echoing the target row's handle
+    // and the per-action input. The result is carried opaquely for a read-only,
+    // schema-driven render. ADMIN-ONLY (`fenced`).
+    invokeMemberAction: (body: InvokeMemberActionBody) =>
+      req(apiRoutes.post_api_auth_member_actions_invoke.path, s.invokeMemberActionResult, {
+        method: 'POST',
+        body,
+      }),
+  };
+}
 
+/** The deployment's principals. */
+function principalMethods(t: Transport) {
+  const { req } = t;
+  return {
     // The deployment's principals (identities). ADMIN-ONLY (`secret`) — a
     // non-admin projection never reaches the route.
     listPrincipals: (signal?: AbortSignal) =>
-      req('/api/auth/principals', s.principalList, { signal }),
+      req(apiRoutes.get_api_auth_principals.path, s.principalList, { signal }),
     // Create a `human` or `service` principal and apply its role (admin only).
     // A duplicate id is a loud 409; an unknown role a loud 400.
     createPrincipal: (body: {
       user_id?: string;
-      kind: 'human' | 'service';
+      kind: s.PrincipalKind;
       display_name: string;
       role: string;
-    }) => req('/api/auth/principals', s.principal, { method: 'POST', body }),
+    }) => req(apiRoutes.post_api_auth_principals.path, s.principal, { method: 'POST', body }),
     // Update a principal's display name and/or `disabled` flag (omit-means-keep;
     // an all-absent body is a loud 400). Disabling turns off every credential the
     // principal owns.
     updatePrincipal: (userId: string, body: { display_name?: string; disabled?: boolean }) =>
-      req(`/api/auth/principals/${encodeSegment(userId)}`, s.principal, { method: 'PUT', body }),
+      req(
+        buildPath(apiRoutes.put_api_auth_principals_user_id.path, { user_id: userId }),
+        s.principal,
+        { method: 'PUT', body },
+      ),
     // Delete a principal — revokes every key it owns and its policy row.
     deletePrincipal: (userId: string) =>
-      req(`/api/auth/principals/${encodeSegment(userId)}`, s.principalDeleted, {
-        method: 'DELETE',
-      }),
+      req(
+        buildPath(apiRoutes.delete_api_auth_principals_user_id.path, { user_id: userId }),
+        s.principalDeleted,
+        {
+          method: 'DELETE',
+        },
+      ),
+  };
+}
+
+export function authClient(t: Transport) {
+  return {
+    ...scopeRouteMethods(t),
+    ...roleMethods(t),
+    ...keyMemberMethods(t),
+    ...principalMethods(t),
   };
 }

package/src/client/backend-client.ts

@@ -1,4 +1,5 @@
 /** Backend identity and worker-bus fleet sub-client. */
+import { apiRoutes } from '../generated/api-routes';
 import * as s from '../schemas';
 import type { Transport } from './transport';
 
@@ -11,15 +12,19 @@ export function backendClient(t: Transport) {
     // plugin is registered. `listFleetWorkers` reads the live bus presence census
     // (every subscribed worker, ASGI + backend-runtime) and never fabricates an empty
     // fleet — a census read that fails surfaces as a loud 500.
-    getBackendInfo: (signal?: AbortSignal) => req('/api/backend', s.backendInfo, { signal }),
+    getBackendInfo: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_backend.path, s.backendInfo, { signal }),
     listFleetWorkers: (signal?: AbortSignal) =>
-      req('/api/fleet/workers', s.fleetWorkers, { signal }),
+      req(apiRoutes.get_api_fleet_workers.path, s.fleetWorkers, { signal }),
     // Soft-restart the fleet: `targets` names the workers to reload, or `null` for
     // the whole fleet. The serving worker applies locally then broadcasts; a 200
     // response carries the per-worker fleet report, so workers that did not converge
     // are named, not hidden. A failed local apply instead re-raises as a loud error
     // (the transport throws with the failure message), not a returned report.
     reloadFleetConfig: (targets: string[] | null) =>
-      req('/api/fleet/reload-config', s.fleetReloadResult, { method: 'POST', body: { targets } }),
+      req(apiRoutes.post_api_fleet_reload_config.path, s.fleetReloadResult, {
+        method: 'POST',
+        body: { targets },
+      }),
   };
 }

package/src/client/backup-client.ts

@@ -1,4 +1,5 @@
 /** Backup section listing, export and import sub-client. */
+import { apiRoutes } from '../generated/api-routes';
 import { apiDownload } from '../http';
 import * as s from '../schemas';
 import type { Transport } from './transport';
@@ -7,10 +8,14 @@ export function backupClient(t: Transport) {
   const { config, req } = t;
   return {
     listBackupSections: (signal?: AbortSignal) =>
-      req('/api/backup/sections', s.backupSections, { signal }),
+      req(apiRoutes.get_api_backup_sections.path, s.backupSections, { signal }),
     exportBackup: (sections: string[], signal?: AbortSignal): Promise<Blob> =>
-      apiDownload(config, '/api/backup/export', { method: 'POST', body: { sections }, signal }),
+      apiDownload(config, apiRoutes.post_api_backup_export.path, {
+        method: 'POST',
+        body: { sections },
+        signal,
+      }),
     importBackup: (body: { document: unknown; sections: string[] }) =>
-      req('/api/backup/import', s.backupImportReport, { method: 'POST', body }),
+      req(apiRoutes.post_api_backup_import.path, s.backupImportReport, { method: 'POST', body }),
   };
 }

package/src/client/capabilities-client.ts

@@ -1,4 +1,5 @@
 /** Caller capability projection and auth-capabilities sub-clients. */
+import { apiRoutes } from '../generated/api-routes';
 import * as s from '../schemas';
 import type { Transport } from './transport';
 
@@ -7,7 +8,8 @@ export function capabilitiesGetMe(t: Transport) {
   return {
     // The derived (path, method) surface + tools/agents the caller can reach
     // right now — the projection the Studio filters its nav and pages on.
-    getMe: (signal?: AbortSignal) => req('/api/auth/me', s.meProjection, { signal }),
+    getMe: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_auth_me.path, s.meProjection, { signal }),
   };
 }
 
@@ -17,6 +19,6 @@ export function capabilitiesGetCaps(t: Transport) {
     // Whether this deployment can mint API keys locally (the settings key-create
     // UI gates on `mintable`). AUTHED.
     getAuthCapabilities: (signal?: AbortSignal) =>
-      req('/api/auth/capabilities', s.authCapabilities, { signal }),
+      req(apiRoutes.get_api_auth_capabilities.path, s.authCapabilities, { signal }),
   };
 }

package/src/client/channels-client.ts

@@ -1,4 +1,5 @@
 /** Installed channel-plugin catalog sub-client. */
+import { apiRoutes } from '../generated/api-routes';
 import * as s from '../schemas';
 import type { Transport } from './transport';
 
@@ -6,6 +7,7 @@ export function channelsClient(t: Transport) {
   const { req } = t;
   return {
     // The installed channel-plugin names (delivery media for ask questions).
-    listChannels: (signal?: AbortSignal) => req('/api/channels', s.channels, { signal }),
+    listChannels: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_channels.path, s.channels, { signal }),
   };
 }

package/src/client/config-client.ts

@@ -1,14 +1,19 @@
 /** Environment-config and reload sub-client. */
+import { apiRoutes } from '../generated/api-routes';
 import * as s from '../schemas';
 import type { Transport } from './transport';
 
 export function configClient(t: Transport) {
   const { req } = t;
   return {
-    getEnvConfig: (signal?: AbortSignal) => req('/api/config/env', s.envConfig, { signal }),
-    setEnvConfig: (env: Record<string, string>) =>
-      req('/api/config/env', s.reloadConfigResult, { method: 'POST', body: env }),
-    getConfigMode: (signal?: AbortSignal) => req('/api/config/mode', s.configMode, { signal }),
+    getEnvConfig: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_config_env.path, s.envConfig, { signal }),
+    // `env` MERGES into the stored env ('' deletes a key); `secret_keys`, when a list,
+    // REPLACES the operator's secret marks (absent or `null` leaves them untouched).
+    setEnvConfig: (body: { env: Record<string, string>; secret_keys?: string[] | null }) =>
+      req(apiRoutes.post_api_config_env.path, s.reloadConfigResult, { method: 'POST', body }),
+    getConfigMode: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_config_mode.path, s.configMode, { signal }),
     // The LOCAL soft-restart door (distinct from the System page's fleet door
     // `/api/fleet/reload-config`): refresh env from the config manager, reset the
     // settings caches, and re-initialize from the manifest — applied on the serving
@@ -16,6 +21,9 @@ export function configClient(t: Transport) {
     // Admin-`fenced`; the 200 body is the bare per-worker fleet report so an
     // unconverged sibling is visible, never hidden.
     reloadConfig: (targets: string[] | null = null) =>
-      req('/api/config/reload', s.fleetReloadResult, { method: 'POST', body: { targets } }),
+      req(apiRoutes.post_api_config_reload.path, s.fleetReloadResult, {
+        method: 'POST',
+        body: { targets },
+      }),
   };
 }

package/src/client/connectors-client.ts

@@ -1,5 +1,5 @@
 /** Connector provider and connection lifecycle sub-client. */
-import { encodeSegment } from '../http';
+import { apiRoutes, buildPath } from '../generated/api-routes';
 import * as s from '../schemas';
 import type { Transport } from './transport';
 
@@ -11,42 +11,117 @@ export interface StartConnectArgs {
   readonly return_url?: string;
 }
 
+/** Look a server up by its address, or the server of an existing provider. */
+export type DiscoverServerTarget = { readonly url: string } | { readonly providerId: string };
+
+/** The body of `POST /api/connectors/providers`: add the MCP server at `url`. */
+export interface AddServerArgs {
+  readonly url: string;
+  readonly id?: string;
+  readonly display_name?: string;
+  readonly description?: string;
+  readonly icon_url?: string;
+  readonly category?: string;
+  readonly scopes?: string[];
+}
+
+/** The body of `PUT /api/connectors/providers/{id}/client`: an app registered by hand. */
+export interface SetProviderClientArgs {
+  readonly client_id: string;
+  readonly client_secret?: string | null;
+  readonly token_endpoint_auth_method?: 'client_secret_post' | 'client_secret_basic' | 'none';
+  readonly issuer?: string;
+}
+
 export function connectorsClient(t: Transport) {
   const { req } = t;
   return {
     listProviders: (signal?: AbortSignal) =>
-      req('/api/connectors/providers', s.providers, { signal }),
+      req(apiRoutes.get_api_connectors_providers.path, s.providers, { signal }),
     listConnections: (signal?: AbortSignal) =>
-      req('/api/connectors/connections', s.connectionsList, { signal }),
+      req(apiRoutes.get_api_connectors_connections.path, s.connectionsList, { signal }),
     getConnection: (id: string, signal?: AbortSignal) =>
-      req(`/api/connectors/connections/${encodeSegment(id)}`, s.connectionView, { signal }),
+      req(
+        buildPath(apiRoutes.get_api_connectors_connections_connection_id.path, {
+          connection_id: id,
+        }),
+        s.connectionView,
+        { signal },
+      ),
     startConnect: (args: StartConnectArgs) =>
-      req('/api/connectors/connections/start', s.startConnectResult, {
+      req(apiRoutes.post_api_connectors_connections_start.path, s.startConnectResult, {
         method: 'POST',
         body: args,
       }),
     disconnect: (id: string) =>
-      req(`/api/connectors/connections/${encodeSegment(id)}`, s.disconnectResult, {
-        method: 'DELETE',
-      }),
+      req(
+        buildPath(apiRoutes.delete_api_connectors_connections_connection_id.path, {
+          connection_id: id,
+        }),
+        s.disconnectResult,
+        {
+          method: 'DELETE',
+        },
+      ),
     reconnect: (id: string, enabled_sub_services: string[], return_url?: string) =>
-      req(`/api/connectors/connections/${encodeSegment(id)}/reconnect`, s.reconnectResult, {
-        method: 'POST',
-        body: { enabled_sub_services, return_url },
-      }),
+      req(
+        buildPath(apiRoutes.post_api_connectors_connections_connection_id_reconnect.path, {
+          connection_id: id,
+        }),
+        s.reconnectResult,
+        {
+          method: 'POST',
+          body: { enabled_sub_services, return_url },
+        },
+      ),
     patchSubServices: (id: string, enabled_sub_services: string[], return_url?: string) =>
       req(
-        `/api/connectors/connections/${encodeSegment(id)}/sub-services`,
+        buildPath(apiRoutes.patch_api_connectors_connections_connection_id_sub_services.path, {
+          connection_id: id,
+        }),
         s.patchSubServicesResult,
         {
           method: 'PATCH',
           body: { enabled_sub_services, return_url },
         },
       ),
-    completeOAuth: (state: string, code: string, error?: string) =>
-      req('/api/connectors/oauth/complete', s.oauthCompleteResult, {
+    // `iss` is the redirect's issuer parameter, sent when the redirect carried one.
+    completeOAuth: (state: string, code: string, error?: string, iss?: string) =>
+      req(apiRoutes.post_api_connectors_oauth_complete.path, s.oauthCompleteResult, {
+        method: 'POST',
+        body: { state, code, error, iss },
+      }),
+    ...providerSetupClient(t),
+  };
+}
+
+/** The provider-setup calls: look a server up, add it, set its sign-in client, remove it. */
+function providerSetupClient(t: Transport) {
+  const { req } = t;
+  return {
+    discoverServer: (target: DiscoverServerTarget) =>
+      req(apiRoutes.post_api_connectors_providers_discover.path, s.discoveredServer, {
+        method: 'POST',
+        body: 'url' in target ? { url: target.url } : { provider_id: target.providerId },
+      }),
+    addServer: (args: AddServerArgs) =>
+      req(apiRoutes.post_api_connectors_providers.path, s.providerMutationResult, {
         method: 'POST',
-        body: { state, code, error },
+        body: args,
       }),
+    removeProvider: (id: string) =>
+      req(
+        buildPath(apiRoutes.delete_api_connectors_providers_provider_id.path, { provider_id: id }),
+        s.removeProviderResult,
+        { method: 'DELETE' },
+      ),
+    setProviderClient: (id: string, args: SetProviderClientArgs) =>
+      req(
+        buildPath(apiRoutes.put_api_connectors_providers_provider_id_client.path, {
+          provider_id: id,
+        }),
+        s.providerMutationResult,
+        { method: 'PUT', body: args },
+      ),
   };
 }