@taiga-ai/mcp-server 0.18.0-dev.446 → 0.18.0-dev.448

package/src/client.ts

@@ -1,6 +1,72 @@
-import type { AgentJobType, ApiKeyIntrospection } from '@taiga/types';
+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,
+  PolicyRemediationResult,
+  Product,
+  ProductDocument,
+  ProductDocumentListItem,
+  ProductRepository,
+  ProductRepositoryWithProtection,
+  PublishProductDocumentResponse,
+  QueueEntry,
+  RepositoryBranch,
+  RumSummary,
+  SetupTaskListEntry,
+  TenantDocument,
+  UptimeReport,
+} 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
@@ -13,7 +79,7 @@ import { SERVER_VERSION } from './version.js';
  * 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): T {
+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 }[] = [
@@ -38,7 +104,7 @@ export function withoutTenant<T>(value: T): T {
     }
     Object.defineProperty(target, key, { value: copy, enumerable: true, writable: true, configurable: true });
   }
-  return root.out as T;
+  return root.out as WithoutTenant<T>;
 }
 
 export class TaigaApiError extends Error {
@@ -117,19 +183,12 @@ function parseErrorBody(body: string): { code?: string; message?: string; detail
 }
 
 /**
- * A tenant or factory document as the API returns it: the fields the tools
- * read. `data` holds the content; policies and instructions keep it under
- * `sections` (see tools/sections.ts).
+ * 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 interface TaigaDocument {
-  id: string;
-  type: string;
-  name: string;
-  version: number | null;
-  isDraft: boolean;
-  data: Record<string, unknown>;
-  [key: string]: unknown;
-}
+export type TaigaDocument = WithoutTenant<TenantDocument | FactoryDocument | ProductDocument>;
 
 /**
  * HTTP client for the Taiga API.
@@ -145,12 +204,29 @@ export class TaigaClient {
     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> {
+  ): Promise<T | WithoutTenant<T>> {
     const url = `${this.baseUrl}/v1${path}`;
     const headers: Record<string, string> = {
       Authorization: `Bearer ${this.apiKey}`,
@@ -225,18 +301,15 @@ export class TaigaClient {
     if (opts?.limit) params.set('limit', String(opts.limit));
     if (opts?.cursor) params.set('cursor', opts.cursor);
     const qs = params.toString();
-    return this.request<{ data: unknown[]; nextCursor: string | null }>('GET', `/products${qs ? `?${qs}` : ''}`);
+    return this.request<Page<Product>>('GET', `/products${qs ? `?${qs}` : ''}`);
   }
 
   async getProduct(id: string, signal?: AbortSignal) {
-    return this.request<{ data: unknown }>('GET', `/products/${seg(id)}`, undefined, { signal });
+    return this.request<One<Product>>('GET', `/products/${seg(id)}`, undefined, { signal });
   }
 
   async listProductRepositories(productId: string) {
-    return this.request<{ data: unknown[]; nextCursor: string | null }>(
-      'GET',
-      `/products/${seg(productId)}/repositories`
-    );
+    return this.request<Page<ProductRepository>>('GET', `/products/${seg(productId)}/repositories`);
   }
 
   // ---------------------------------------------------------------------------
@@ -248,27 +321,24 @@ export class TaigaClient {
     if (opts?.limit) params.set('limit', String(opts.limit));
     if (opts?.cursor) params.set('cursor', opts.cursor);
     const qs = params.toString();
-    return this.request<{ data: unknown[]; nextCursor: string | null }>(
-      'GET',
-      `/tenants/current/documents${qs ? `?${qs}` : ''}`
-    );
+    return this.request<Page<TenantDocument>>('GET', `/tenants/current/documents${qs ? `?${qs}` : ''}`);
   }
 
   async getTenantDocument(type: string) {
-    return this.request<{ data: TaigaDocument }>('GET', `/tenants/current/documents/${seg(type)}`);
+    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<{ data: TaigaDocument | null }>('GET', `/tenants/current/documents/${seg(type)}/draft`);
+    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<{ data: TaigaDocument }>('PUT', `/tenants/current/documents/${seg(type)}/draft`, body);
+    return this.request<One<TenantDocument>>('PUT', `/tenants/current/documents/${seg(type)}/draft`, body);
   }
 
   async publishTenantDocument(type: string) {
-    return this.request<{ data: TaigaDocument }>('POST', `/tenants/current/documents/${seg(type)}/publish`);
+    return this.request<One<TenantDocument>>('POST', `/tenants/current/documents/${seg(type)}/publish`);
   }
 
   // ---------------------------------------------------------------------------
@@ -280,34 +350,27 @@ export class TaigaClient {
     if (opts?.limit) params.set('limit', String(opts.limit));
     if (opts?.cursor) params.set('cursor', opts.cursor);
     const qs = params.toString();
-    return this.request<{ data: unknown[]; nextCursor: string | null }>(
-      'GET',
-      `/factories/${seg(factoryId)}/documents${qs ? `?${qs}` : ''}`
-    );
+    return this.request<Page<FactoryDocument>>('GET', `/factories/${seg(factoryId)}/documents${qs ? `?${qs}` : ''}`);
   }
 
   async getFactoryDocument(factoryId: string, type: string) {
-    return this.request<{ data: TaigaDocument }>('GET', `/factories/${seg(factoryId)}/documents/${seg(type)}`);
+    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<{ data: TaigaDocument | null }>(
+    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<{ data: TaigaDocument }>(
-      'PUT',
-      `/factories/${seg(factoryId)}/documents/${seg(type)}/draft`,
-      body
-    );
+    return this.request<One<FactoryDocument>>('PUT', `/factories/${seg(factoryId)}/documents/${seg(type)}/draft`, body);
   }
 
   async publishFactoryDocument(factoryId: string, type: string) {
-    return this.request<{ data: TaigaDocument }>('POST', `/factories/${seg(factoryId)}/documents/${seg(type)}/publish`);
+    return this.request<One<FactoryDocument>>('POST', `/factories/${seg(factoryId)}/documents/${seg(type)}/publish`);
   }
 
   // ---------------------------------------------------------------------------
@@ -319,7 +382,7 @@ export class TaigaClient {
     if (opts?.origin) params.set('origin', opts.origin);
     if (opts?.limit) params.set('limit', String(opts.limit));
     const qs = params.toString();
-    return this.request<{ data: unknown[]; nextCursor: string | null }>(
+    return this.request<Page<ProductDocumentListItem>>(
       'GET',
       `/products/${seg(productId)}/documents${qs ? `?${qs}` : ''}`
     );
@@ -331,7 +394,7 @@ export class TaigaClient {
    * back up.
    */
   async setLineStopped(productId: string, stopped: boolean) {
-    return this.request<{ data: unknown }>('PUT', `/products/${seg(productId)}/line`, { stopped });
+    return this.request<One<Product>>('PUT', `/products/${seg(productId)}/line`, { stopped });
   }
 
   // ---------------------------------------------------------------------------
@@ -346,31 +409,24 @@ export class TaigaClient {
     documentType?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
   }) {
-    return this.request<{ data: unknown }>('POST', '/agent-jobs', body);
+    return this.request<One<AgentJob>>('POST', '/agent-jobs', body);
   }
 
   async getAgentJob(id: string, signal?: AbortSignal) {
-    return this.request<{ data: unknown }>('GET', `/agent-jobs/${seg(id)}`, undefined, { signal });
+    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<{ data: TaigaDocument | null }>(
-      'GET',
-      `/products/${seg(productId)}/documents/${seg(type)}/draft`
-    );
+    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<{ data: TaigaDocument }>(
-      'PUT',
-      `/products/${seg(productId)}/documents/${seg(type)}/draft`,
-      body
-    );
+    return this.request<One<ProductDocument>>('PUT', `/products/${seg(productId)}/documents/${seg(type)}/draft`, body);
   }
 
   async publishProductDocument(productId: string, type: string) {
-    return this.request<{ data: TaigaDocument; warnings?: { unknownPolicyCitations?: string[] } }>(
+    return this.request<PublishProductDocumentResponse>(
       'POST',
       `/products/${seg(productId)}/documents/${seg(type)}/publish`
     );
@@ -378,22 +434,25 @@ export class TaigaClient {
 
   /** Mark the published version reviewed by the caller, as the Documents page shows it. */
   async markProductDocumentReviewed(productId: string, type: string) {
-    return this.request<{ data: unknown }>('POST', `/products/${seg(productId)}/documents/${seg(type)}/review`);
+    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<{ data: unknown }>('POST', `/products/${seg(productId)}/documents/generate-all`);
+    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<{ data: unknown }>('POST', `/products/${seg(productId)}/documents/generate-all/stop`);
+    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<{ data: unknown }>('GET', `/products/${seg(productId)}/documents/${seg(type)}${qs}`);
+    return this.request<One<ProductDocument>>('GET', `/products/${seg(productId)}/documents/${seg(type)}${qs}`);
   }
 
   // ---------------------------------------------------------------------------
@@ -424,19 +483,16 @@ export class TaigaClient {
     if (opts?.limit) params.set('limit', String(opts.limit));
     if (opts?.cursor) params.set('cursor', opts.cursor);
     const qs = params.toString();
-    return this.request<{ data: unknown[]; nextCursor: string | null }>(
-      'GET',
-      `/products/${seg(productId)}/backlog${qs ? `?${qs}` : ''}`
-    );
+    return this.request<Page<BacklogItem>>('GET', `/products/${seg(productId)}/backlog${qs ? `?${qs}` : ''}`);
   }
 
   async getBacklogItem(itemId: string, signal?: AbortSignal) {
-    return this.request<{ data: unknown }>('GET', `/backlog/${seg(itemId)}`, undefined, { signal });
+    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: unknown[] }>('GET', `/backlog/${seg(itemId)}/activity`);
+    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. */
@@ -449,34 +505,34 @@ export class TaigaClient {
       force?: boolean | undefined;
     }
   ) {
-    return this.request<{ data: unknown }>('PUT', `/backlog/${seg(itemId)}/state`, body);
+    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<{ data: unknown }>('POST', `/backlog/${seg(itemId)}/resume`);
+    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<{ data: unknown }>('PUT', `/backlog/${seg(itemId)}/auto-build`, { autoBuild });
+    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: unknown[] }>('GET', `/products/${seg(productId)}/queue`);
+    return this.request<{ data: QueueEntry[] }>('GET', `/products/${seg(productId)}/queue`);
   }
 
   async getActivePlan(itemId: string) {
-    return this.request<{ data: unknown }>('GET', `/backlog/${seg(itemId)}/plans/active`);
+    return this.request<One<BacklogItemPlanWithSteps>>('GET', `/backlog/${seg(itemId)}/plans/active`);
   }
 
   async approvePlan(planId: string) {
-    return this.request<{ data: unknown }>('POST', `/plans/${seg(planId)}/approve`);
+    return this.request<One<BacklogItem>>('POST', `/plans/${seg(planId)}/approve`);
   }
 
   async rejectPlan(planId: string, body: { comment: string }) {
-    return this.request<{ data: unknown }>('POST', `/plans/${seg(planId)}/reject`, body);
+    return this.request<One<BacklogItem>>('POST', `/plans/${seg(planId)}/reject`, body);
   }
 
   // ---------------------------------------------------------------------------
@@ -492,10 +548,7 @@ export class TaigaClient {
     if (opts?.limit) params.set('limit', String(opts.limit));
     if (opts?.cursor) params.set('cursor', opts.cursor);
     const qs = params.toString();
-    return this.request<{ data: unknown[]; nextCursor: string | null }>(
-      'GET',
-      `/products/${seg(productId)}/builds${qs ? `?${qs}` : ''}`
-    );
+    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. */
@@ -510,19 +563,19 @@ export class TaigaClient {
     if (opts?.limit) params.set('limit', String(opts.limit));
     if (opts?.cursor) params.set('cursor', opts.cursor);
     const qs = params.toString();
-    return this.request<{ data: unknown[]; nextCursor: string | null }>('GET', `/builds${qs ? `?${qs}` : ''}`);
+    return this.request<Page<BuildRunWithContext>>('GET', `/builds${qs ? `?${qs}` : ''}`);
   }
 
   async getBuildRun(id: string, signal?: AbortSignal) {
-    return this.request<{ data: unknown }>('GET', `/builds/${seg(id)}`, undefined, { signal });
+    return this.request<One<BuildRunWithContext>>('GET', `/builds/${seg(id)}`, undefined, { signal });
   }
 
   async stopBuildRun(id: string) {
-    return this.request<{ data: unknown }>('POST', `/builds/${seg(id)}/stop`);
+    return this.request<One<BuildRun>>('POST', `/builds/${seg(id)}/stop`);
   }
 
   async listBuildRunSteps(id: string) {
-    return this.request<{ data: unknown[] }>('GET', `/builds/${seg(id)}/steps`);
+    return this.request<{ data: BuildRunStep[] }>('GET', `/builds/${seg(id)}/steps`);
   }
 
   // ---------------------------------------------------------------------------
@@ -530,11 +583,11 @@ export class TaigaClient {
   // ---------------------------------------------------------------------------
 
   async getMaintenanceSummary(productId: string) {
-    return this.request<{ data: unknown }>('GET', `/products/${seg(productId)}/maintenance/summary`);
+    return this.request<One<MaintenanceSummary>>('GET', `/products/${seg(productId)}/maintenance/summary`);
   }
 
   async listMaintenanceSweeps(productId: string, opts?: { limit?: number | undefined }) {
-    return this.request<{ data: unknown[]; nextCursor: string | null }>(
+    return this.request<Page<MaintenanceRun>>(
       'GET',
       `/products/${seg(productId)}/maintenance/runs${query({ limit: opts?.limit })}`
     );
@@ -550,14 +603,14 @@ export class TaigaClient {
       cursor?: string | undefined;
     }
   ) {
-    return this.request<{ data: unknown[]; nextCursor: string | null; totalCount?: number }>(
+    return this.request<Page<MaintenanceFinding> & { totalCount?: number }>(
       'GET',
       `/products/${seg(productId)}/maintenance/findings${query({ ...opts })}`
     );
   }
 
   async getFinding(id: string) {
-    return this.request<{ data: unknown }>('GET', `/maintenance/findings/${seg(id)}`);
+    return this.request<One<MaintenanceFindingDetail>>('GET', `/maintenance/findings/${seg(id)}`);
   }
 
   async updateFinding(
@@ -569,11 +622,11 @@ export class TaigaClient {
       ignoreExpiresAt?: string | null | undefined;
     }
   ) {
-    return this.request<{ data: unknown }>('PATCH', `/maintenance/findings/${seg(id)}`, body);
+    return this.request<One<MaintenanceFinding>>('PATCH', `/maintenance/findings/${seg(id)}`, body);
   }
 
   async remediateFinding(productId: string, findingId: string) {
-    return this.request<{ data: unknown }>(
+    return this.request<One<{ finding: MaintenanceFinding; backlogItemId: string }>>(
       'POST',
       `/products/${seg(productId)}/maintenance/findings/${seg(findingId)}/remediate`,
       {}
@@ -589,15 +642,19 @@ export class TaigaClient {
       productRepositoryId?: string | null | undefined;
     }
   ) {
-    return this.request<{ data: unknown }>('POST', `/products/${seg(productId)}/maintenance/packages/remediate`, body);
+    return this.request<One<{ backlogItemId: string; findingIds: string[] }>>(
+      'POST',
+      `/products/${seg(productId)}/maintenance/packages/remediate`,
+      body
+    );
   }
 
   async getPolicyStanding(productId: string) {
-    return this.request<{ data: unknown }>('GET', `/products/${seg(productId)}/maintenance/policies`);
+    return this.request<One<PolicyConformance>>('GET', `/products/${seg(productId)}/maintenance/policies`);
   }
 
   async remediatePolicyControl(productId: string, controlId: string) {
-    return this.request<{ data: unknown }>(
+    return this.request<One<PolicyRemediationResult>>(
       'POST',
       `/products/${seg(productId)}/maintenance/policies/controls/${seg(controlId)}/remediate`,
       {}
@@ -605,7 +662,7 @@ export class TaigaClient {
   }
 
   async remediatePolicyViolation(productId: string, divergenceId: string) {
-    return this.request<{ data: unknown }>(
+    return this.request<One<PolicyRemediationResult>>(
       'POST',
       `/products/${seg(productId)}/maintenance/policies/divergences/${seg(divergenceId)}/remediate`,
       {}
@@ -626,17 +683,14 @@ export class TaigaClient {
   }) {
     const { productId, ...rest } = opts;
     const path = productId ? `/products/${seg(productId)}/inbox` : '/inbox';
-    return this.request<{ data: unknown[]; nextCursor: string | null; totalCount?: number }>(
-      'GET',
-      `${path}${query({ ...rest })}`
-    );
+    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<{ data: unknown }>('PATCH', `/inbox/${seg(id)}`, body);
+    return this.request<One<InboxItem>>('PATCH', `/inbox/${seg(id)}`, body);
   }
 
   async listSetupTasks(opts: {
@@ -648,10 +702,7 @@ export class TaigaClient {
   }) {
     const { productId, ...rest } = opts;
     const path = productId ? `/products/${seg(productId)}/setup-tasks` : '/setup-tasks';
-    return this.request<{ data: unknown[]; nextCursor: string | null; totalCount?: number }>(
-      'GET',
-      `${path}${query({ ...rest })}`
-    );
+    return this.request<Page<SetupTaskListEntry> & { totalCount?: number }>('GET', `${path}${query({ ...rest })}`);
   }
 
   // ---------------------------------------------------------------------------
@@ -659,59 +710,53 @@ export class TaigaClient {
   // ---------------------------------------------------------------------------
 
   async listEnvironments(productId: string, opts?: { limit?: number | undefined; cursor?: string | undefined }) {
-    return this.request<{ data: unknown[]; nextCursor: string | null }>(
-      'GET',
-      `/products/${seg(productId)}/environments${query({ ...opts })}`
-    );
+    return this.request<Page<Environment>>('GET', `/products/${seg(productId)}/environments${query({ ...opts })}`);
   }
 
   async createEnvironment(productId: string, body: { name: string; type: string }) {
-    return this.request<{ data: unknown }>('POST', `/products/${seg(productId)}/environments`, body);
+    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<{ data: unknown }>('PATCH', `/environments/${seg(id)}`, body);
+    return this.request<One<Environment>>('PATCH', `/environments/${seg(id)}`, body);
   }
 
   async getCurrentDeployments(productId: string) {
-    return this.request<{ data: unknown }>('GET', `/products/${seg(productId)}/deployments/current`);
+    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<{ data: unknown[]; nextCursor: string | null }>(
-      'GET',
-      `/products/${seg(productId)}/deployments${query({ ...opts })}`
-    );
+    return this.request<Page<Deployment>>('GET', `/products/${seg(productId)}/deployments${query({ ...opts })}`);
   }
 
   async getDeploymentSyncStatus(productId: string) {
-    return this.request<{ data: unknown }>('GET', `/products/${seg(productId)}/deployments/sync-status`);
+    return this.request<One<DeploymentSyncStatusView>>('GET', `/products/${seg(productId)}/deployments/sync-status`);
   }
 
   async getDeliveryMetrics(productId: string, environmentId: string, windowDays: number) {
-    return this.request<{ data: unknown }>(
+    return this.request<One<DeploymentInsights>>(
       'GET',
       `/products/${seg(productId)}/deployments/insights${query({ environmentId, windowDays })}`
     );
   }
 
   async getMonitoringHealth(productId: string) {
-    return this.request<{ data: unknown[] }>('GET', `/products/${seg(productId)}/monitoring/health`);
+    return this.request<{ data: EnvironmentHealth[] }>('GET', `/products/${seg(productId)}/monitoring/health`);
   }
 
-  async getMonitoringSignal(
+  async getMonitoringSignal<S extends keyof MonitoringSignals>(
     productId: string,
-    signal: 'uptime' | 'rum' | 'client-health' | 'history',
+    signal: S,
     environmentId: string,
     windowDays: number
   ) {
-    return this.request<{ data: unknown }>(
+    return this.request<One<MonitoringSignals[S]>>(
       'GET',
       `/products/${seg(productId)}/monitoring/${signal}${query({ environmentId, windowDays })}`
     );
@@ -729,21 +774,18 @@ export class TaigaClient {
   }) {
     // 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<{ data: unknown[]; nextCursor: string | null }>(
+    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<{ data: unknown }>('GET', `/custom-documents/${seg(id)}`);
+    return this.request<One<CustomDocumentDto>>('GET', `/custom-documents/${seg(id)}`);
   }
 
   async getKnowledgeDownload(id: string) {
-    return this.request<{ data: { url?: unknown } & Record<string, unknown> }>(
-      'GET',
-      `/custom-documents/${seg(id)}/download`
-    );
+    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. */
@@ -760,15 +802,15 @@ export class TaigaClient {
     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: unknown; deduplicated?: boolean }>('POST', '/custom-documents', form);
+    return this.request<{ data: CustomDocumentDto; deduplicated: boolean }>('POST', '/custom-documents', form);
   }
 
   async retryKnowledge(id: string) {
-    return this.request<{ data: unknown }>('POST', `/custom-documents/${seg(id)}/retry`);
+    return this.request<One<CustomDocumentDto>>('POST', `/custom-documents/${seg(id)}/retry`);
   }
 
   async deleteKnowledge(id: string) {
-    return this.request<{ data?: unknown } | null>('DELETE', `/custom-documents/${seg(id)}`);
+    return this.request<null>('DELETE', `/custom-documents/${seg(id)}`);
   }
 
   // ---------------------------------------------------------------------------
@@ -787,11 +829,11 @@ export class TaigaClient {
       emitDesignStandards?: boolean | null | undefined;
     }
   ) {
-    return this.request<{ data: unknown }>('PATCH', `/products/${seg(productId)}`, body);
+    return this.request<One<Product>>('PATCH', `/products/${seg(productId)}`, body);
   }
 
   async updateBacklogItem(itemId: string, body: { autoMerge?: boolean | null | undefined }) {
-    return this.request<{ data: unknown }>('PATCH', `/backlog/${seg(itemId)}`, body);
+    return this.request<One<BacklogItem>>('PATCH', `/backlog/${seg(itemId)}`, body);
   }
 
   // ---------------------------------------------------------------------------
@@ -799,7 +841,7 @@ export class TaigaClient {
   // ---------------------------------------------------------------------------
 
   async getFactory(id: string) {
-    return this.request<{ data: unknown }>('GET', `/factories/${seg(id)}`);
+    return this.request<One<Factory>>('GET', `/factories/${seg(id)}`);
   }
 
   async listFactories(opts?: { limit?: number | undefined; cursor?: string | undefined }) {
@@ -807,15 +849,15 @@ export class TaigaClient {
     if (opts?.limit) params.set('limit', String(opts.limit));
     if (opts?.cursor) params.set('cursor', opts.cursor);
     const qs = params.toString();
-    return this.request<{ data: unknown[]; nextCursor: string | null }>('GET', `/factories${qs ? `?${qs}` : ''}`);
+    return this.request<Page<Factory>>('GET', `/factories${qs ? `?${qs}` : ''}`);
   }
 
   async createFactory(body: { name: string }) {
-    return this.request<{ data: unknown }>('POST', '/factories', body);
+    return this.request<One<Factory>>('POST', '/factories', body);
   }
 
   async updateFactory(factoryId: string, body: { name?: string | undefined }) {
-    return this.request<{ data: unknown }>('PATCH', `/factories/${seg(factoryId)}`, body);
+    return this.request<One<Factory>>('PATCH', `/factories/${seg(factoryId)}`, body);
   }
 
   // ---------------------------------------------------------------------------
@@ -830,23 +872,26 @@ export class TaigaClient {
     ownsDeployment?: boolean | null | undefined;
     deploymentNotes?: string | undefined;
   }) {
-    return this.request<{ data: unknown }>('POST', '/products', body);
+    return this.request<One<Product>>('POST', '/products', body);
   }
 
   async previewProductMove(productId: string, factoryId: string) {
-    return this.request<{ data: unknown }>('GET', `/products/${seg(productId)}/factory/preview${query({ factoryId })}`);
+    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<Record<string, unknown>>('PUT', `/products/${seg(productId)}/factory`, body);
+    return this.request<MoveProductResult>('PUT', `/products/${seg(productId)}/factory`, body);
   }
 
   async startImport(productId: string) {
-    return this.request<{ data: { jobId: string } }>('POST', `/products/${seg(productId)}/brownfield-import`);
+    return this.request<One<{ jobId: string }>>('POST', `/products/${seg(productId)}/brownfield-import`);
   }
 
   async refreshRealityDocuments(productId: string, docTypes?: readonly string[] | undefined) {
-    return this.request<{ data: { jobId: string } }>(
+    return this.request<One<{ jobId: string }>>(
       'POST',
       `/products/${seg(productId)}/documents/refresh-reality`,
       docTypes ? { docTypes } : undefined
@@ -854,11 +899,11 @@ export class TaigaClient {
   }
 
   async completeSetup(productId: string) {
-    return this.request<{ data: unknown }>('POST', `/products/${seg(productId)}/setup/complete`);
+    return this.request<One<Product>>('POST', `/products/${seg(productId)}/setup/complete`);
   }
 
   async reopenSetup(productId: string) {
-    return this.request<{ data: unknown }>('POST', `/products/${seg(productId)}/setup/reopen`);
+    return this.request<One<Product>>('POST', `/products/${seg(productId)}/setup/reopen`);
   }
 
   // ---------------------------------------------------------------------------
@@ -867,10 +912,10 @@ export class TaigaClient {
 
   /** Every connected GitHub account, page by page: a later account must be findable by its id too. */
   async listGithubInstallations() {
-    const data: unknown[] = [];
+    const data: WithoutTenant<GithubInstallation>[] = [];
     let cursor: string | undefined;
     do {
-      const result = await this.request<{ data: unknown[]; nextCursor: string | null }>(
+      const result = await this.request<Page<GithubInstallation>>(
         'GET',
         `/github/installations${query({ limit: 100, cursor })}`
       );
@@ -884,7 +929,7 @@ export class TaigaClient {
     installationId: string,
     opts: { q?: string | undefined; limit?: number | undefined; cursor?: string | undefined }
   ) {
-    return this.request<{ data: unknown[]; nextCursor: string | null }>(
+    return this.request<Page<GithubRepository>>(
       'GET',
       `/github/installations/${seg(installationId)}/repositories${query({ ...opts })}`
     );
@@ -894,7 +939,7 @@ export class TaigaClient {
     productId: string,
     body: { githubRepositoryId: string; replacesRepositoryId?: string | undefined }
   ) {
-    return this.request<{ data: unknown }>('POST', `/products/${seg(productId)}/repositories`, body);
+    return this.request<One<ProductRepository>>('POST', `/products/${seg(productId)}/repositories`, body);
   }
 
   async updateRepository(
@@ -902,7 +947,7 @@ export class TaigaClient {
     repositoryId: string,
     body: { baseBranch?: string | null | undefined; label?: string | null | undefined }
   ) {
-    return this.request<{ data: unknown }>(
+    return this.request<One<ProductRepositoryWithProtection>>(
       'PATCH',
       `/products/${seg(productId)}/repositories/${seg(repositoryId)}`,
       body
@@ -910,7 +955,7 @@ export class TaigaClient {
   }
 
   async listRepositoryBranches(productId: string, repositoryId: string) {
-    return this.request<{ data: unknown[]; truncated: boolean }>(
+    return this.request<{ data: RepositoryBranch[]; truncated: boolean }>(
       'GET',
       `/products/${seg(productId)}/repositories/${seg(repositoryId)}/branches`
     );