@taiga-ai/mcp-server 0.25.0-rc.474 → 0.26.0-dev.479

package/src/client.ts

@@ -1,977 +0,0 @@
-import type {
-  ActivityEvent,
-  AgentJob,
-  AgentJobType,
-  ApiKeyIntrospection,
-  BacklogItem,
-  BacklogItemPlanWithSteps,
-  BuildRun,
-  BuildRunStep,
-  BuildRunWithContext,
-  ClientHealthSummary,
-  CurrentDeployments,
-  CustomDocumentDownloadView,
-  CustomDocumentDto,
-  Deployment,
-  DeploymentInsights,
-  DeploymentSyncStatusView,
-  DocumentReviewState,
-  Environment,
-  EnvironmentHealth,
-  Factory,
-  FactoryDocument,
-  FactoryMovePreview,
-  GithubInstallation,
-  GithubRepository,
-  InboxItem,
-  MaintenanceFinding,
-  MaintenanceFindingDetail,
-  MaintenanceRun,
-  MaintenanceSummary,
-  MonitoringHistory,
-  MoveProductResult,
-  PolicyConformance,
-  PolicyRemediationInput,
-  PolicyRemediationResult,
-  Product,
-  ProductDocument,
-  ProductDocumentListItem,
-  ProductRepository,
-  ProductRepositoryWithProtection,
-  PublishProductDocumentResponse,
-  QueueEntry,
-  RepositoryBranch,
-  RumSummary,
-  SetupTaskListEntry,
-  TenantDocument,
-  UptimeReport,
-  CreateFactoryInput,
-  CreateProductInput,
-} from '@taiga/types';
-import { SERVER_VERSION } from './version.js';
-
-/** A response type as the tools see it: `withoutTenant` has removed every `tenantId`, at any depth. */
-export type WithoutTenant<T> = T extends readonly (infer Item)[]
-  ? WithoutTenant<Item>[]
-  : T extends object
-    ? { [K in keyof T as K extends 'tenantId' ? never : K]: WithoutTenant<T[K]> }
-    : T;
-
-/** What each monitoring signal route returns. */
-interface MonitoringSignals {
-  uptime: UptimeReport;
-  rum: RumSummary;
-  'client-health': ClientHealthSummary;
-  history: MonitoringHistory;
-}
-
-/** The API's single-resource envelope. */
-type One<T> = { data: T };
-/** The API's paginated envelope. */
-type Page<T> = { data: T[]; nextCursor: string | null };
-
-/**
- * The same value without any `tenantId`, at any depth. Build run and step
- * rows carry one; the key is scoped to one tenant already, so the id is
- * never something the model acts on. Applied to every response here, once,
- * so no tool, resource or prompt can hand it over by forgetting to; only
- * the key's own introspection keeps it, typed and never handed over.
- *
- * An explicit stack rather than recursion: a document body a person stored
- * can nest as deep as JSON.parse allows, and a walk must not overflow where
- * the parse did not. Every key is defined as a data property, so an own
- * "__proto__" key stays a key instead of becoming the copy's prototype.
- */
-export function withoutTenant<T>(value: T): WithoutTenant<T> {
-  const root: { out?: unknown } = {};
-  // Siblings keep their order and nested values are copied in full: see the loop.
-  const pending: { source: unknown; target: object; key: string | number }[] = [
-    { source: value, target: root, key: 'out' },
-  ];
-  while (pending.length > 0) {
-    const { source, target, key } = pending.pop()!;
-    let copy: unknown = source;
-    // Children are pushed last-first so they pop first-first: key order is
-    // meaning in a section map (the order sections render in) and must survive.
-    if (Array.isArray(source)) {
-      copy = new Array(source.length);
-      for (let index = source.length - 1; index >= 0; index -= 1) {
-        pending.push({ source: source[index], target: copy as object, key: index });
-      }
-    } else if (source !== null && typeof source === 'object') {
-      copy = {};
-      const entries = Object.entries(source as Record<string, unknown>).filter(([inner]) => inner !== 'tenantId');
-      for (let index = entries.length - 1; index >= 0; index -= 1) {
-        pending.push({ source: entries[index]![1], target: copy as object, key: entries[index]![0] });
-      }
-    }
-    Object.defineProperty(target, key, { value: copy, enumerable: true, writable: true, configurable: true });
-  }
-  return root.out as WithoutTenant<T>;
-}
-
-export class TaigaApiError extends Error {
-  readonly status: number;
-  readonly code: string | undefined;
-  readonly apiMessage: string | undefined;
-  /** A refusal's structured reason, when the API sent one: `{ reason, ... }` (a 409's discriminator and its data). */
-  readonly details: Record<string, unknown> | undefined;
-
-  constructor(method: string, path: string, status: number, body: string) {
-    const parsed = parseErrorBody(body);
-    super(`Taiga API ${method} ${path} failed (${status}): ${parsed.message ?? body}`);
-    this.name = 'TaigaApiError';
-    this.status = status;
-    this.code = parsed.code;
-    this.apiMessage = parsed.message;
-    this.details = parsed.details;
-  }
-}
-
-/**
- * One path segment. Every id and type a tool passes is validated at the
- * tool boundary; this is the second wall. Encoding keeps a slash inside the
- * segment, and the dot segments are refused outright: encodeURIComponent
- * leaves "." and ".." as they are, and the URL parser in fetch would then
- * collapse `/documents/../publish` into a different route.
- */
-function seg(value: string): string {
-  if (value === '' || value === '.' || value === '..') {
-    throw new TypeError(`Invalid path segment: ${JSON.stringify(value)}`);
-  }
-  return encodeURIComponent(value);
-}
-
-/**
- * A query string from the defined values only, prefixed with "?" when there
- * is one. Every value goes through URLSearchParams, so nothing a tool passes
- * can add a parameter of its own.
- */
-function query(params: Record<string, string | number | boolean | null | undefined>): string {
-  const search = new URLSearchParams();
-  for (const [key, value] of Object.entries(params)) {
-    if (value !== undefined && value !== null && value !== '') search.set(key, String(value));
-  }
-  const text = search.toString();
-  return text ? `?${text}` : '';
-}
-
-function parseErrorBody(body: string): { code?: string; message?: string; details?: Record<string, unknown> } {
-  try {
-    const json = JSON.parse(body) as { code?: unknown; message?: unknown; details?: unknown };
-    const message = typeof json.message === 'string' ? json.message : undefined;
-    // A 400 from route validation says only "Request validation failed";
-    // the field and the reason are in `details`, and the model needs them.
-    const details = Array.isArray(json.details)
-      ? json.details
-          .map((d: { instancePath?: unknown; message?: unknown }) =>
-            [d.instancePath, d.message].filter((x) => typeof x === 'string' && x).join(' ')
-          )
-          .filter(Boolean)
-      : [];
-    // A service refusal names its gate in an object (`reason`, and what it
-    // found, such as the documents still missing); the model needs both.
-    const structured =
-      typeof json.details === 'object' && json.details !== null && !Array.isArray(json.details)
-        ? (json.details as Record<string, unknown>)
-        : undefined;
-    return {
-      ...(typeof json.code === 'string' ? { code: json.code } : {}),
-      ...(message ? { message: details.length ? `${message}: ${details.join('; ')}` : message } : {}),
-      ...(structured ? { details: structured } : {}),
-    };
-  } catch {
-    return {};
-  }
-}
-
-/**
- * A tenant, factory or product document as the tools read it. `data` holds
- * the content; policies, instructions and product documents keep it under
- * `sections` (see tools/sections.ts). Only tenant and factory documents have a
- * `name`; a product document is named by its type.
- */
-export type TaigaDocument = WithoutTenant<TenantDocument | FactoryDocument | ProductDocument>;
-
-/**
- * HTTP client for the Taiga API.
- * Used by the MCP server to proxy tool calls to the backend.
- */
-export class TaigaClient {
-  private baseUrl: string;
-  private apiKey: string;
-  private introspection: ApiKeyIntrospection | null = null;
-
-  constructor(opts: { baseUrl: string; apiKey: string }) {
-    this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
-    this.apiKey = opts.apiKey;
-  }
-
-  /**
-   * One API call, its body typed as the route's response. The body is not
-   * validated: the server trusts the API, and `T` names what the route
-   * returns. Every `tenantId` is removed unless the caller keeps it.
-   */
-  private request<T>(
-    method: string,
-    path: string,
-    body: unknown,
-    options: { keepTenant: true; signal?: AbortSignal | undefined }
-  ): Promise<T>;
-  private request<T>(
-    method: string,
-    path: string,
-    body?: unknown,
-    options?: { signal?: AbortSignal | undefined }
-  ): Promise<WithoutTenant<T>>;
-  private async request<T>(
-    method: string,
-    path: string,
-    body?: unknown,
-    options: { keepTenant?: true; signal?: AbortSignal | undefined } = {}
-  ): Promise<T | WithoutTenant<T>> {
-    const url = `${this.baseUrl}/v1${path}`;
-    const headers: Record<string, string> = {
-      Authorization: `Bearer ${this.apiKey}`,
-      'User-Agent': `taiga-ai-mcp-server/${SERVER_VERSION}`,
-    };
-    // Only with a body: Fastify refuses an empty body under a JSON
-    // content type, which is what a bodiless POST (publish) would send. A
-    // form (a file upload) sets its own multipart type with its boundary.
-    const form = body instanceof FormData;
-    if (body !== undefined && !form) headers['Content-Type'] = 'application/json';
-
-    const response = await fetch(url, {
-      method,
-      headers,
-      body: body === undefined ? null : form ? body : JSON.stringify(body),
-      // A caller that must stop waiting (a wait's deadline, a cancelled call) ends the read too.
-      ...(options.signal ? { signal: options.signal } : {}),
-    });
-
-    if (!response.ok) {
-      const text = await response.text().catch(() => '');
-      throw new TaigaApiError(method, path, response.status, text);
-    }
-
-    // A delete answers 204 with no body: there is nothing to parse.
-    if (response.status === 204) return null as T;
-    const parsed = (await response.json()) as T;
-    return options.keepTenant ? parsed : withoutTenant(parsed);
-  }
-
-  // ---------------------------------------------------------------------------
-  // Auth
-  // ---------------------------------------------------------------------------
-
-  async introspect(): Promise<ApiKeyIntrospection> {
-    // The key's own identity keeps its tenant: typed so, and never handed to the model.
-    const result = await this.request<{ data: ApiKeyIntrospection }>('GET', '/auth/introspect', undefined, {
-      keepTenant: true,
-    });
-    this.introspection = result.data;
-    return result.data;
-  }
-
-  getIntrospection(): ApiKeyIntrospection | null {
-    return this.introspection;
-  }
-
-  hasCapability(capability: string): boolean {
-    if (!this.introspection) return false;
-    return this.introspection.capabilities.includes(capability);
-  }
-
-  // ---------------------------------------------------------------------------
-  // Products
-  // ---------------------------------------------------------------------------
-
-  async listProducts(opts?: {
-    factoryId?: string | undefined;
-    status?: string | undefined;
-    slug?: string | undefined;
-    repository?: string | undefined;
-    repositoryHost?: string | undefined;
-    limit?: number | undefined;
-    cursor?: string | undefined;
-  }) {
-    const params = new URLSearchParams();
-    if (opts?.factoryId) params.set('factoryId', opts.factoryId);
-    if (opts?.status) params.set('status', opts.status);
-    if (opts?.slug) params.set('slug', opts.slug);
-    if (opts?.repository) params.set('repository', opts.repository);
-    if (opts?.repositoryHost) params.set('repositoryHost', opts.repositoryHost);
-    if (opts?.limit) params.set('limit', String(opts.limit));
-    if (opts?.cursor) params.set('cursor', opts.cursor);
-    const qs = params.toString();
-    return this.request<Page<Product>>('GET', `/products${qs ? `?${qs}` : ''}`);
-  }
-
-  async getProduct(id: string, signal?: AbortSignal) {
-    return this.request<One<Product>>('GET', `/products/${seg(id)}`, undefined, { signal });
-  }
-
-  async listProductRepositories(productId: string) {
-    return this.request<Page<ProductRepository>>('GET', `/products/${seg(productId)}/repositories`);
-  }
-
-  // ---------------------------------------------------------------------------
-  // Documents (tenant-level policies)
-  // ---------------------------------------------------------------------------
-
-  async listTenantDocuments(opts?: { limit?: number | undefined; cursor?: string | undefined }) {
-    const params = new URLSearchParams();
-    if (opts?.limit) params.set('limit', String(opts.limit));
-    if (opts?.cursor) params.set('cursor', opts.cursor);
-    const qs = params.toString();
-    return this.request<Page<TenantDocument>>('GET', `/tenants/current/documents${qs ? `?${qs}` : ''}`);
-  }
-
-  async getTenantDocument(type: string) {
-    return this.request<One<TenantDocument>>('GET', `/tenants/current/documents/${seg(type)}`);
-  }
-
-  /** The shared draft for a document type, or `{ data: null }` when none exists. */
-  async getTenantDocumentDraft(type: string) {
-    return this.request<One<TenantDocument | null>>('GET', `/tenants/current/documents/${seg(type)}/draft`);
-  }
-
-  async saveTenantDocumentDraft(type: string, body: { data: Record<string, unknown> }) {
-    return this.request<One<TenantDocument>>('PUT', `/tenants/current/documents/${seg(type)}/draft`, body);
-  }
-
-  async publishTenantDocument(type: string) {
-    return this.request<One<TenantDocument>>('POST', `/tenants/current/documents/${seg(type)}/publish`);
-  }
-
-  // ---------------------------------------------------------------------------
-  // Factory Documents
-  // ---------------------------------------------------------------------------
-
-  async getFactoryDocument(factoryId: string, type: string) {
-    return this.request<One<FactoryDocument>>('GET', `/factories/${seg(factoryId)}/documents/${seg(type)}`);
-  }
-
-  /** The shared draft for a factory document type, or `{ data: null }` when none exists. */
-  async getFactoryDocumentDraft(factoryId: string, type: string) {
-    return this.request<One<FactoryDocument | null>>(
-      'GET',
-      `/factories/${seg(factoryId)}/documents/${seg(type)}/draft`
-    );
-  }
-
-  async saveFactoryDocumentDraft(factoryId: string, type: string, body: { data: Record<string, unknown> }) {
-    return this.request<One<FactoryDocument>>('PUT', `/factories/${seg(factoryId)}/documents/${seg(type)}/draft`, body);
-  }
-
-  async publishFactoryDocument(factoryId: string, type: string) {
-    return this.request<One<FactoryDocument>>('POST', `/factories/${seg(factoryId)}/documents/${seg(type)}/publish`);
-  }
-
-  // ---------------------------------------------------------------------------
-  // Product Documents
-  // ---------------------------------------------------------------------------
-
-  async listProductDocuments(productId: string, opts?: { origin?: string | undefined; limit?: number | undefined }) {
-    const params = new URLSearchParams();
-    if (opts?.origin) params.set('origin', opts.origin);
-    if (opts?.limit) params.set('limit', String(opts.limit));
-    const qs = params.toString();
-    return this.request<Page<ProductDocumentListItem>>(
-      'GET',
-      `/products/${seg(productId)}/documents${qs ? `?${qs}` : ''}`
-    );
-  }
-
-  /**
-   * Stop or start the product's line. Stopping halts pulls and builds and
-   * stops the plan and build in flight; starting picks the interrupted work
-   * back up.
-   */
-  async setLineStopped(productId: string, stopped: boolean) {
-    return this.request<One<Product>>('PUT', `/products/${seg(productId)}/line`, { stopped });
-  }
-
-  // ---------------------------------------------------------------------------
-  // Agent jobs
-  // ---------------------------------------------------------------------------
-
-  /** Ask an agent for work: the job is queued and runs in the background. */
-  async createAgentJob(body: {
-    scope: 'product' | 'tenant';
-    type: AgentJobType;
-    targetId: string;
-    documentType?: string | undefined;
-    metadata?: Record<string, unknown> | undefined;
-  }) {
-    return this.request<One<AgentJob>>('POST', '/agent-jobs', body);
-  }
-
-  async getAgentJob(id: string, signal?: AbortSignal) {
-    return this.request<One<AgentJob>>('GET', `/agent-jobs/${seg(id)}`, undefined, { signal });
-  }
-
-  /** The plan-side draft of a product document, or `{ data: null }` when none exists. */
-  async getProductDocumentDraft(productId: string, type: string) {
-    return this.request<One<ProductDocument | null>>('GET', `/products/${seg(productId)}/documents/${seg(type)}/draft`);
-  }
-
-  async saveProductDocumentDraft(productId: string, type: string, body: { data: Record<string, unknown> }) {
-    return this.request<One<ProductDocument>>('PUT', `/products/${seg(productId)}/documents/${seg(type)}/draft`, body);
-  }
-
-  async publishProductDocument(productId: string, type: string) {
-    return this.request<PublishProductDocumentResponse>(
-      'POST',
-      `/products/${seg(productId)}/documents/${seg(type)}/publish`
-    );
-  }
-
-  /** Mark the published version reviewed by the caller, as the Documents page shows it. */
-  async markProductDocumentReviewed(productId: string, type: string) {
-    return this.request<One<DocumentReviewState>>('POST', `/products/${seg(productId)}/documents/${seg(type)}/review`);
-  }
-
-  /** Generate remaining: every missing and outdated document, in chain order. */
-  async generateRemainingDocuments(productId: string) {
-    return this.request<One<{ jobIds: string[] }>>('POST', `/products/${seg(productId)}/documents/generate-all`);
-  }
-
-  /** Cancel a Generate remaining run still in flight. */
-  async stopGeneratingDocuments(productId: string) {
-    return this.request<One<{ cancelledJobIds: string[] }>>(
-      'POST',
-      `/products/${seg(productId)}/documents/generate-all/stop`
-    );
-  }
-
-  async getProductDocument(productId: string, type: string, origin?: string) {
-    const qs = origin ? `?${new URLSearchParams({ origin })}` : '';
-    return this.request<One<ProductDocument>>('GET', `/products/${seg(productId)}/documents/${seg(type)}${qs}`);
-  }
-
-  // ---------------------------------------------------------------------------
-  // Factory Documents
-  // ---------------------------------------------------------------------------
-
-  // ---------------------------------------------------------------------------
-  // Backlog
-  // ---------------------------------------------------------------------------
-
-  async listBacklogItems(
-    productId: string,
-    opts?: {
-      status?: string | undefined;
-      planningStatus?: string | undefined;
-      category?: string | undefined;
-      includeArchived?: boolean | undefined;
-      limit?: number | undefined;
-      cursor?: string | undefined;
-    }
-  ) {
-    const params = new URLSearchParams();
-    if (opts?.status) params.set('status', opts.status);
-    if (opts?.planningStatus) params.set('planningStatus', opts.planningStatus);
-    if (opts?.category) params.set('category', opts.category);
-    // The route reads the literal strings 'true' and 'false'.
-    if (opts?.includeArchived) params.set('includeArchived', 'true');
-    if (opts?.limit) params.set('limit', String(opts.limit));
-    if (opts?.cursor) params.set('cursor', opts.cursor);
-    const qs = params.toString();
-    return this.request<Page<BacklogItem>>('GET', `/products/${seg(productId)}/backlog${qs ? `?${qs}` : ''}`);
-  }
-
-  async getBacklogItem(itemId: string, signal?: AbortSignal) {
-    return this.request<One<BacklogItem>>('GET', `/backlog/${seg(itemId)}`, undefined, { signal });
-  }
-
-  /** The initiative's history, oldest first: every turn event and audited move, each with who did it. */
-  async listBacklogItemActivity(itemId: string) {
-    return this.request<{ data: ActivityEvent[] }>('GET', `/backlog/${seg(itemId)}/activity`);
-  }
-
-  /** A person's move on the line board: the column dropped into, and what to follow there. */
-  async transitionInitiative(
-    itemId: string,
-    body: {
-      state: string;
-      afterId?: string | null | undefined;
-      archived?: boolean | undefined;
-      force?: boolean | undefined;
-    }
-  ) {
-    return this.request<One<BacklogItem>>('PUT', `/backlog/${seg(itemId)}/state`, body);
-  }
-
-  /** Answer the needs-human flag: plan again, resume the run, or clear a refused start. */
-  async resumeInitiative(itemId: string) {
-    return this.request<One<BacklogItem>>('POST', `/backlog/${seg(itemId)}/resume`);
-  }
-
-  /** The initiative's own review gate: true builds a landed plan at once, false stops for a person, null follows the product. */
-  async setAutoBuild(itemId: string, autoBuild: boolean | null) {
-    return this.request<One<BacklogItem>>('PUT', `/backlog/${seg(itemId)}/auto-build`, { autoBuild });
-  }
-
-  /** The product's live queue, in order. */
-  async listQueue(productId: string) {
-    return this.request<{ data: QueueEntry[] }>('GET', `/products/${seg(productId)}/queue`);
-  }
-
-  async getActivePlan(itemId: string) {
-    return this.request<One<BacklogItemPlanWithSteps>>('GET', `/backlog/${seg(itemId)}/plans/active`);
-  }
-
-  async approvePlan(planId: string) {
-    return this.request<One<BacklogItem>>('POST', `/plans/${seg(planId)}/approve`);
-  }
-
-  async rejectPlan(planId: string, body: { comment: string }) {
-    return this.request<One<BacklogItem>>('POST', `/plans/${seg(planId)}/reject`, body);
-  }
-
-  // ---------------------------------------------------------------------------
-  // Build runs
-  // ---------------------------------------------------------------------------
-
-  async listBuildRuns(
-    productId: string,
-    opts?: { backlogItemId?: string | undefined; limit?: number | undefined; cursor?: string | undefined }
-  ) {
-    const params = new URLSearchParams();
-    if (opts?.backlogItemId) params.set('backlogItemId', opts.backlogItemId);
-    if (opts?.limit) params.set('limit', String(opts.limit));
-    if (opts?.cursor) params.set('cursor', opts.cursor);
-    const qs = params.toString();
-    return this.request<Page<BuildRunWithContext>>('GET', `/products/${seg(productId)}/builds${qs ? `?${qs}` : ''}`);
-  }
-
-  /** The runs of every product the key can see, newest first; `active` narrows to the ones executing now. */
-  async listBuildRunActivity(opts?: {
-    active?: boolean | undefined;
-    limit?: number | undefined;
-    cursor?: string | undefined;
-  }) {
-    const params = new URLSearchParams();
-    // The route reads the literal strings 'true' and 'false'.
-    if (opts?.active) params.set('active', 'true');
-    if (opts?.limit) params.set('limit', String(opts.limit));
-    if (opts?.cursor) params.set('cursor', opts.cursor);
-    const qs = params.toString();
-    return this.request<Page<BuildRunWithContext>>('GET', `/builds${qs ? `?${qs}` : ''}`);
-  }
-
-  async getBuildRun(id: string, signal?: AbortSignal) {
-    return this.request<One<BuildRunWithContext>>('GET', `/builds/${seg(id)}`, undefined, { signal });
-  }
-
-  async stopBuildRun(id: string) {
-    return this.request<One<BuildRun>>('POST', `/builds/${seg(id)}/stop`);
-  }
-
-  async listBuildRunSteps(id: string) {
-    return this.request<{ data: BuildRunStep[] }>('GET', `/builds/${seg(id)}/steps`);
-  }
-
-  // ---------------------------------------------------------------------------
-  // Maintaining
-  // ---------------------------------------------------------------------------
-
-  async getMaintenanceSummary(productId: string) {
-    return this.request<One<MaintenanceSummary>>('GET', `/products/${seg(productId)}/maintenance/summary`);
-  }
-
-  async listMaintenanceSweeps(productId: string, opts?: { limit?: number | undefined }) {
-    return this.request<Page<MaintenanceRun>>(
-      'GET',
-      `/products/${seg(productId)}/maintenance/runs${query({ limit: opts?.limit })}`
-    );
-  }
-
-  async listFindings(
-    productId: string,
-    opts?: {
-      status?: string | undefined;
-      severity?: string | undefined;
-      kind?: string | undefined;
-      limit?: number | undefined;
-      cursor?: string | undefined;
-    }
-  ) {
-    return this.request<Page<MaintenanceFinding> & { totalCount?: number }>(
-      'GET',
-      `/products/${seg(productId)}/maintenance/findings${query({ ...opts })}`
-    );
-  }
-
-  async getFinding(id: string) {
-    return this.request<One<MaintenanceFindingDetail>>('GET', `/maintenance/findings/${seg(id)}`);
-  }
-
-  async updateFinding(
-    id: string,
-    body: {
-      status: 'open' | 'ignored';
-      ignoreReason?: string | undefined;
-      ignoreNote?: string | null | undefined;
-      ignoreExpiresAt?: string | null | undefined;
-    }
-  ) {
-    return this.request<One<MaintenanceFinding>>('PATCH', `/maintenance/findings/${seg(id)}`, body);
-  }
-
-  async remediateFinding(productId: string, findingId: string) {
-    return this.request<One<{ finding: MaintenanceFinding; backlogItemId: string }>>(
-      'POST',
-      `/products/${seg(productId)}/maintenance/findings/${seg(findingId)}/remediate`,
-      {}
-    );
-  }
-
-  async remediatePackage(
-    productId: string,
-    body: {
-      ecosystem: string;
-      packageName: string;
-      currentVersion?: string | null | undefined;
-      productRepositoryId?: string | null | undefined;
-    }
-  ) {
-    return this.request<One<{ backlogItemId: string; findingIds: string[] }>>(
-      'POST',
-      `/products/${seg(productId)}/maintenance/packages/remediate`,
-      body
-    );
-  }
-
-  async getPolicyStanding(productId: string) {
-    return this.request<One<PolicyConformance>>('GET', `/products/${seg(productId)}/maintenance/policies`);
-  }
-
-  async remediatePolicyControl(productId: string, controlId: string, body: PolicyRemediationInput = {}) {
-    return this.request<One<PolicyRemediationResult>>(
-      'POST',
-      `/products/${seg(productId)}/maintenance/policies/controls/${seg(controlId)}/remediate`,
-      body
-    );
-  }
-
-  async remediatePolicyViolation(productId: string, divergenceId: string, body: PolicyRemediationInput = {}) {
-    return this.request<One<PolicyRemediationResult>>(
-      'POST',
-      `/products/${seg(productId)}/maintenance/policies/divergences/${seg(divergenceId)}/remediate`,
-      body
-    );
-  }
-
-  // ---------------------------------------------------------------------------
-  // Action Required
-  // ---------------------------------------------------------------------------
-
-  async listInbox(opts: {
-    productId?: string | undefined;
-    category?: string | undefined;
-    resolved?: boolean | undefined;
-    withTotal?: boolean | undefined;
-    limit?: number | undefined;
-    cursor?: string | undefined;
-  }) {
-    const { productId, ...rest } = opts;
-    const path = productId ? `/products/${seg(productId)}/inbox` : '/inbox';
-    return this.request<Page<InboxItem> & { totalCount?: number }>('GET', `${path}${query({ ...rest })}`);
-  }
-
-  async updateInboxItem(
-    id: string,
-    body: { status?: 'in_progress' | 'done' | 'dismissed' | undefined; snoozedUntil?: string | null | undefined }
-  ) {
-    return this.request<One<InboxItem>>('PATCH', `/inbox/${seg(id)}`, body);
-  }
-
-  async listSetupTasks(opts: {
-    productId?: string | undefined;
-    openOnly?: boolean | undefined;
-    withTotal?: boolean | undefined;
-    limit?: number | undefined;
-    cursor?: string | undefined;
-  }) {
-    const { productId, ...rest } = opts;
-    const path = productId ? `/products/${seg(productId)}/setup-tasks` : '/setup-tasks';
-    return this.request<Page<SetupTaskListEntry> & { totalCount?: number }>('GET', `${path}${query({ ...rest })}`);
-  }
-
-  // ---------------------------------------------------------------------------
-  // Deployments, environments and monitoring (observed, never driven)
-  // ---------------------------------------------------------------------------
-
-  async listEnvironments(productId: string, opts?: { limit?: number | undefined; cursor?: string | undefined }) {
-    return this.request<Page<Environment>>('GET', `/products/${seg(productId)}/environments${query({ ...opts })}`);
-  }
-
-  async createEnvironment(productId: string, body: { name: string; type: string }) {
-    return this.request<One<Environment>>('POST', `/products/${seg(productId)}/environments`, body);
-  }
-
-  async updateEnvironment(
-    id: string,
-    body: { name?: string | undefined; type?: string | undefined; url?: string | null | undefined }
-  ) {
-    return this.request<One<Environment>>('PATCH', `/environments/${seg(id)}`, body);
-  }
-
-  async getCurrentDeployments(productId: string) {
-    return this.request<One<CurrentDeployments>>('GET', `/products/${seg(productId)}/deployments/current`);
-  }
-
-  async listDeployments(
-    productId: string,
-    opts?: { environmentId?: string | undefined; limit?: number | undefined; cursor?: string | undefined }
-  ) {
-    return this.request<Page<Deployment>>('GET', `/products/${seg(productId)}/deployments${query({ ...opts })}`);
-  }
-
-  async getDeploymentSyncStatus(productId: string) {
-    return this.request<One<DeploymentSyncStatusView>>('GET', `/products/${seg(productId)}/deployments/sync-status`);
-  }
-
-  async getDeliveryMetrics(productId: string, environmentId: string, windowDays: number) {
-    return this.request<One<DeploymentInsights>>(
-      'GET',
-      `/products/${seg(productId)}/deployments/insights${query({ environmentId, windowDays })}`
-    );
-  }
-
-  async getMonitoringHealth(productId: string) {
-    return this.request<{ data: EnvironmentHealth[] }>('GET', `/products/${seg(productId)}/monitoring/health`);
-  }
-
-  async getMonitoringSignal<S extends keyof MonitoringSignals>(
-    productId: string,
-    signal: S,
-    environmentId: string,
-    windowDays: number
-  ) {
-    return this.request<One<MonitoringSignals[S]>>(
-      'GET',
-      `/products/${seg(productId)}/monitoring/${signal}${query({ environmentId, windowDays })}`
-    );
-  }
-
-  // ---------------------------------------------------------------------------
-  // Knowledge
-  // ---------------------------------------------------------------------------
-
-  async listKnowledge(opts: {
-    factoryId?: string | null | undefined;
-    productId?: string | null | undefined;
-    limit?: number | undefined;
-    cursor?: string | undefined;
-  }) {
-    // The route reads the literal 'null' as "this level only, not below it".
-    const scope = (value: string | null | undefined) => (value === null ? 'null' : value);
-    return this.request<Page<CustomDocumentDto>>(
-      'GET',
-      `/custom-documents${query({ ...opts, factoryId: scope(opts.factoryId), productId: scope(opts.productId) })}`
-    );
-  }
-
-  async getKnowledge(id: string) {
-    return this.request<One<CustomDocumentDto>>('GET', `/custom-documents/${seg(id)}`);
-  }
-
-  async getKnowledgeDownload(id: string) {
-    return this.request<One<CustomDocumentDownloadView>>('GET', `/custom-documents/${seg(id)}/download`);
-  }
-
-  /** A text file filed as knowledge at one level: the organization, a factory, or a product in its factory. */
-  async addKnowledge(file: {
-    fileName: string;
-    mime: 'text/markdown' | 'text/plain';
-    content: string;
-    factoryId?: string | undefined;
-    productId?: string | undefined;
-  }) {
-    const form = new FormData();
-    // Fields before the file: the route reads them in any order, but the
-    // order a person would read them in costs nothing.
-    if (file.factoryId) form.set('factoryId', file.factoryId);
-    if (file.productId) form.set('productId', file.productId);
-    form.set('file', new Blob([file.content], { type: file.mime }), file.fileName);
-    return this.request<{ data: CustomDocumentDto; deduplicated: boolean }>('POST', '/custom-documents', form);
-  }
-
-  async retryKnowledge(id: string) {
-    return this.request<One<CustomDocumentDto>>('POST', `/custom-documents/${seg(id)}/retry`);
-  }
-
-  async deleteKnowledge(id: string) {
-    return this.request<null>('DELETE', `/custom-documents/${seg(id)}`);
-  }
-
-  // ---------------------------------------------------------------------------
-  // Autonomy
-  // ---------------------------------------------------------------------------
-
-  async updateProduct(
-    productId: string,
-    body: {
-      autoMerge?: boolean | null | undefined;
-      autoBuild?: boolean | undefined;
-      name?: string | undefined;
-      ownsInfrastructure?: boolean | null | undefined;
-      ownsDeployment?: boolean | null | undefined;
-      deploymentNotes?: string | null | undefined;
-      emitDesignStandards?: boolean | null | undefined;
-    }
-  ) {
-    return this.request<One<Product>>('PATCH', `/products/${seg(productId)}`, body);
-  }
-
-  async updateBacklogItem(itemId: string, body: { autoMerge?: boolean | null | undefined }) {
-    return this.request<One<BacklogItem>>('PATCH', `/backlog/${seg(itemId)}`, body);
-  }
-
-  // ---------------------------------------------------------------------------
-  // Factories
-  // ---------------------------------------------------------------------------
-
-  async getFactory(id: string) {
-    return this.request<One<Factory>>('GET', `/factories/${seg(id)}`);
-  }
-
-  async listFactories(opts?: { limit?: number | undefined; cursor?: string | undefined }) {
-    const params = new URLSearchParams();
-    if (opts?.limit) params.set('limit', String(opts.limit));
-    if (opts?.cursor) params.set('cursor', opts.cursor);
-    const qs = params.toString();
-    return this.request<Page<Factory>>('GET', `/factories${qs ? `?${qs}` : ''}`);
-  }
-
-  async createFactory(body: CreateFactoryInput) {
-    return this.request<One<Factory>>('POST', '/factories', body);
-  }
-
-  async updateFactory(factoryId: string, body: { name?: string | undefined }) {
-    return this.request<One<Factory>>('PATCH', `/factories/${seg(factoryId)}`, body);
-  }
-
-  // ---------------------------------------------------------------------------
-  // Setting a product up
-  // ---------------------------------------------------------------------------
-
-  async createProduct(
-    body: Pick<
-      CreateProductInput,
-      | 'name'
-      | 'factoryId'
-      | 'projectType'
-      | 'ownsInfrastructure'
-      | 'ownsDeployment'
-      | 'deploymentNotes'
-      | 'refuseDuplicateName'
-    >
-  ) {
-    return this.request<One<Product>>('POST', '/products', body);
-  }
-
-  async previewProductMove(productId: string, factoryId: string) {
-    return this.request<One<FactoryMovePreview>>(
-      'GET',
-      `/products/${seg(productId)}/factory/preview${query({ factoryId })}`
-    );
-  }
-
-  async moveProduct(productId: string, body: { factoryId: string; stopLine?: boolean | undefined }) {
-    return this.request<MoveProductResult>('PUT', `/products/${seg(productId)}/factory`, body);
-  }
-
-  async startImport(productId: string) {
-    return this.request<One<{ jobId: string }>>('POST', `/products/${seg(productId)}/brownfield-import`);
-  }
-
-  async refreshRealityDocuments(productId: string, docTypes?: readonly string[] | undefined) {
-    return this.request<One<{ jobId: string }>>(
-      'POST',
-      `/products/${seg(productId)}/documents/refresh-reality`,
-      docTypes ? { docTypes } : undefined
-    );
-  }
-
-  /** What still blocks finishing setup: required documents unpublished, required checks unstamped (PRO-2800). */
-  async getProductSetupBlockers(productId: string) {
-    return this.request<{
-      data: {
-        inSetup: boolean;
-        missingDocuments: string[];
-        openChecks: { templateName: string; itemKey: string; criterion: string }[];
-      };
-    }>('GET', `/products/${seg(productId)}/setup`);
-  }
-
-  async completeSetup(productId: string) {
-    return this.request<One<Product>>('POST', `/products/${seg(productId)}/setup/complete`);
-  }
-
-  async reopenSetup(productId: string) {
-    return this.request<One<Product>>('POST', `/products/${seg(productId)}/setup/reopen`);
-  }
-
-  // ---------------------------------------------------------------------------
-  // Repositories
-  // ---------------------------------------------------------------------------
-
-  /** Every connected GitHub account, page by page: a later account must be findable by its id too. */
-  async listGithubInstallations() {
-    const data: WithoutTenant<GithubInstallation>[] = [];
-    let cursor: string | undefined;
-    do {
-      const result = await this.request<Page<GithubInstallation>>(
-        'GET',
-        `/github/installations${query({ limit: 100, cursor })}`
-      );
-      data.push(...result.data);
-      cursor = result.nextCursor ?? undefined;
-    } while (cursor);
-    return { data };
-  }
-
-  async listInstallationRepositories(
-    installationId: string,
-    opts: { q?: string | undefined; limit?: number | undefined; cursor?: string | undefined }
-  ) {
-    return this.request<Page<GithubRepository>>(
-      'GET',
-      `/github/installations/${seg(installationId)}/repositories${query({ ...opts })}`
-    );
-  }
-
-  async linkRepository(
-    productId: string,
-    body: { githubRepositoryId: string; replacesRepositoryId?: string | undefined }
-  ) {
-    return this.request<One<ProductRepository>>('POST', `/products/${seg(productId)}/repositories`, body);
-  }
-
-  async updateRepository(
-    productId: string,
-    repositoryId: string,
-    body: { baseBranch?: string | null | undefined; label?: string | null | undefined }
-  ) {
-    return this.request<One<ProductRepositoryWithProtection>>(
-      'PATCH',
-      `/products/${seg(productId)}/repositories/${seg(repositoryId)}`,
-      body
-    );
-  }
-
-  async listRepositoryBranches(productId: string, repositoryId: string) {
-    return this.request<{ data: RepositoryBranch[]; truncated: boolean }>(
-      'GET',
-      `/products/${seg(productId)}/repositories/${seg(repositoryId)}/branches`
-    );
-  }
-
-  async unlinkRepository(productId: string, repositoryId: string) {
-    return this.request<null>('DELETE', `/products/${seg(productId)}/repositories/${seg(repositoryId)}`);
-  }
-}