@critical-path/client 0.18.0 → 0.20.0

package/dist/routes.test.js

@@ -0,0 +1,95 @@
+import { describe, it, expect } from 'vitest';
+import { ROUTES } from '@critical-path/server';
+import { CriticalPathClient } from './index.js';
+/**
+ * Every server route must be reachable through the SDK. When a route is added to the router (and
+ * its OpenAPI `ROUTES` table), add the client method that calls it here.
+ */
+const CLIENT_METHOD_FOR_ROUTE = {
+    'GET /webhooks': 'getWebhooks',
+    'POST /webhooks': 'createWebhook',
+    'GET /webhooks/{webhookId}': 'getWebhook',
+    'PATCH /webhooks/{webhookId}': 'updateWebhook',
+    'DELETE /webhooks/{webhookId}': 'deleteWebhook',
+    'GET /workflows': 'getWorkflows',
+    'POST /workflows': 'createWorkflow',
+    'GET /workflows/{workflowId}': 'getWorkflow',
+    'PATCH /workflows/{workflowId}': 'updateWorkflow',
+    'DELETE /workflows/{workflowId}': 'deleteWorkflow',
+    'GET /projects': 'getProjects',
+    'POST /projects': 'createProject',
+    'GET /projects/{projectId}': 'getProject',
+    'PATCH /projects/{projectId}': 'updateProject',
+    'DELETE /projects/{projectId}': 'deleteProject',
+    'GET /projects/{projectId}/critical-path': 'calculateCriticalPath',
+    'GET /projects/{projectId}/ladder': 'getTimelineLadder',
+    'GET /projects/{projectId}/workload': 'getWorkloadDistribution',
+    'GET /tasks': 'queryTasks',
+    'POST /tasks': 'createTask',
+    'GET /tasks/{taskId}': 'getTask',
+    'PATCH /tasks/{taskId}': 'updateTask',
+    'DELETE /tasks/{taskId}': 'deleteTask',
+    // Task-scoped aliases of the comment and attachment collections
+    'GET /tasks/{taskId}/comments': 'getComments',
+    'POST /tasks/{taskId}/comments': 'addComment',
+    'GET /tasks/{taskId}/attachments': 'getAttachments',
+    'POST /tasks/{taskId}/attachments': 'createAttachment',
+    'GET /tasks/{taskId}/dependencies': 'getTaskDependencies',
+    'POST /tasks/{taskId}/dependencies': 'addDependency',
+    'DELETE /tasks/{taskId}/dependencies/{dependencyId}': 'removeDependency',
+    'GET /tasks/{taskId}/lifecycle': 'getTaskLifecycleState',
+    'GET /tasks/{taskId}/transitions': 'getAllowedTaskTransitions',
+    'GET /tasks/{taskId}/ladder': 'getTaskLadder',
+    'GET /tasks/{taskId}/metrics': 'getTaskMetrics',
+    'GET /tasks/{taskId}/progress-history': 'getTaskProgressHistory',
+    'GET /teams': 'getTeams',
+    'POST /teams': 'createTeam',
+    'GET /teams/{teamId}': 'getTeam',
+    'PATCH /teams/{teamId}': 'updateTeam',
+    'DELETE /teams/{teamId}': 'deleteTeam',
+    'GET /containers': 'getContainers',
+    'POST /containers': 'createContainer',
+    'GET /containers/{containerId}': 'getContainer',
+    'PATCH /containers/{containerId}': 'updateContainer',
+    'DELETE /containers/{containerId}': 'deleteContainer',
+    'GET /deliverables': 'getDeliverables',
+    'POST /deliverables': 'createDeliverable',
+    'GET /deliverables/{deliverableId}': 'getDeliverable',
+    'GET /deliverables/{deliverableId}/summary': 'getDeliverableSummary',
+    'PATCH /deliverables/{deliverableId}': 'updateDeliverable',
+    'DELETE /deliverables/{deliverableId}': 'deleteDeliverable',
+    'GET /iterations': 'getIterations',
+    'POST /iterations': 'createIteration',
+    'GET /iterations/{iterationId}': 'getIteration',
+    'PATCH /iterations/{iterationId}': 'updateIteration',
+    'DELETE /iterations/{iterationId}': 'deleteIteration',
+    'GET /activities': 'queryActivities',
+    'GET /comments': 'getComments',
+    'POST /comments': 'addComment',
+    'GET /comments/{commentId}': 'getComment',
+    'PATCH /comments/{commentId}': 'updateComment',
+    'DELETE /comments/{commentId}': 'deleteComment',
+    'POST /comments/{commentId}/reactions': 'addCommentReaction',
+    'DELETE /comments/{commentId}/reactions': 'removeCommentReaction',
+    'GET /attachments': 'getAttachments',
+    'POST /attachments': 'createAttachment',
+    'POST /attachments/upload': 'uploadAttachmentFile',
+    'POST /attachments/presign': 'getPresignedAttachmentUploadUrl',
+    'GET /attachments/{attachmentId}': 'getAttachment',
+    'DELETE /attachments/{attachmentId}': 'deleteAttachment',
+    'GET /time-entries': 'getTimeEntries',
+    'POST /time-entries': 'logTime',
+    'GET /workload': 'getWorkloadDistribution',
+    'POST /status': 'updateStatus'
+};
+describe('client route coverage', () => {
+    it('has a client method for every server route', () => {
+        const client = new CriticalPathClient({ baseUrl: 'http://localhost' });
+        const missing = ROUTES.map((r) => `${r.method.toUpperCase()} ${r.path}`).filter((key) => {
+            const method = CLIENT_METHOD_FOR_ROUTE[key];
+            return !method || typeof client[method] !== 'function';
+        });
+        expect(missing).toEqual([]);
+    });
+});
+//# sourceMappingURL=routes.test.js.map

package/dist/routes.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.test.js","sourceRoot":"","sources":["../src/routes.test.ts"],"names":[],"mappings":"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"}

package/dist/transport.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transport.test.d.ts.map

package/dist/transport.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.test.d.ts","sourceRoot":"","sources":["../src/transport.test.ts"],"names":[],"mappings":""}

package/dist/transport.test.js

@@ -0,0 +1,89 @@
+import { describe, it, expect, vi } from 'vitest';
+import { CriticalPathRouter } from '@critical-path/server';
+import { CriticalPathClient, CriticalPathError } from './index.js';
+function recordingFetch(respond) {
+    const calls = [];
+    const fetchImpl = (async (url, init) => {
+        const call = { url, method: init.method ?? 'GET', headers: init.headers };
+        calls.push(call);
+        return respond(call, calls.length);
+    });
+    return { calls, fetchImpl };
+}
+const ok = (body) => Response.json(body);
+describe('client transport', () => {
+    it('throws CriticalPathError with status and server details', async () => {
+        const router = new CriticalPathRouter();
+        const client = new CriticalPathClient({
+            baseUrl: 'http://localhost/api/critical-path',
+            fetch: ((input, init) => router.handleRequest(new Request(input, init)))
+        });
+        const project = await client.createProject({ name: 'Errors' });
+        const a = await client.createTask({ projectId: project.id, title: 'A' });
+        const b = await client.createTask({ projectId: project.id, title: 'B' });
+        await client.addDependency(a.id, { dependsOnTaskId: b.id });
+        const cycle = await client.addDependency(b.id, { dependsOnTaskId: a.id }).catch((e) => e);
+        expect(cycle).toBeInstanceOf(CriticalPathError);
+        expect(cycle.status).toBe(409);
+        expect(cycle.body.cyclePath).toBeDefined();
+        const invalid = await client.createTask({ projectId: project.id, title: '' }).catch((e) => e);
+        expect(invalid.status).toBe(400);
+        expect(invalid.issues?.[0].path).toBe('title');
+        const missing = await client.getTask('nope').catch((e) => e);
+        expect(missing.isNotFound).toBe(true);
+    });
+    it('resolves the headers provider for every request and sends Content-Type only with a body', async () => {
+        let token = 0;
+        const { calls, fetchImpl } = recordingFetch(() => ok({ projects: [], project: { id: 'p' } }));
+        const client = new CriticalPathClient({
+            baseUrl: 'http://api.test',
+            fetch: fetchImpl,
+            headers: async () => ({ Authorization: `Bearer t${++token}` })
+        });
+        await client.getProjects();
+        await client.createProject({ name: 'x' });
+        expect(calls.map((c) => c.headers.Authorization)).toEqual(['Bearer t1', 'Bearer t2']);
+        expect(calls[0].headers['Content-Type']).toBeUndefined();
+        expect(calls[1].headers['Content-Type']).toBe('application/json');
+    });
+    it('encodes ids in paths', async () => {
+        const { calls, fetchImpl } = recordingFetch(() => ok({ task: {} }));
+        await new CriticalPathClient({ baseUrl: 'http://api.test', fetch: fetchImpl }).getTask('../projects/p1');
+        expect(calls[0].url).toBe('http://api.test/tasks/..%2Fprojects%2Fp1');
+    });
+    it('times out hung requests', async () => {
+        const hanging = ((_url, init) => new Promise((_resolve, reject) => init.signal.addEventListener('abort', () => reject(init.signal.reason))));
+        const client = new CriticalPathClient({ baseUrl: 'http://api.test', fetch: hanging, timeoutMs: 10 });
+        await expect(client.getProjects()).rejects.toMatchObject({ name: 'TimeoutError' });
+    });
+    it('scopes signals and headers with with(), leaving the original client untouched', async () => {
+        const { calls, fetchImpl } = recordingFetch(() => ok({ projects: [] }));
+        const client = new CriticalPathClient({ baseUrl: 'http://api.test', fetch: fetchImpl, headers: { 'X-App': 'web' } });
+        const controller = new AbortController();
+        controller.abort();
+        const aborting = ((_url, init) => Promise.reject(init.signal?.reason));
+        const cancelled = new CriticalPathClient({ baseUrl: 'http://api.test', fetch: aborting }).with({ signal: controller.signal });
+        await expect(cancelled.getProjects()).rejects.toMatchObject({ name: 'AbortError' });
+        await client.with({ headers: { 'X-Trace': 'abc' } }).getProjects();
+        await client.getProjects();
+        expect(calls[0].headers).toMatchObject({ 'X-App': 'web', 'X-Trace': 'abc' });
+        expect(calls[1].headers['X-Trace']).toBeUndefined();
+    });
+    it('retries GET requests on retryable failures but never writes', async () => {
+        const { calls, fetchImpl } = recordingFetch((_call, n) => (n < 3 ? new Response(null, { status: 503 }) : ok({ projects: [] })));
+        const client = new CriticalPathClient({ baseUrl: 'http://api.test', fetch: fetchImpl, retry: { retries: 2, baseDelayMs: 1 } });
+        await expect(client.getProjects()).resolves.toEqual([]);
+        expect(calls).toHaveLength(3);
+        const { calls: writes, fetchImpl: failingWrites } = recordingFetch(() => new Response(null, { status: 503 }));
+        const writer = new CriticalPathClient({ baseUrl: 'http://api.test', fetch: failingWrites, retry: { retries: 2, baseDelayMs: 1 } });
+        await expect(writer.createProject({ name: 'x' })).rejects.toBeInstanceOf(CriticalPathError);
+        expect(writes).toHaveLength(1);
+    });
+    it('does not retry client errors', async () => {
+        const fetchSpy = vi.fn(async () => Response.json({ error: 'nope' }, { status: 400 }));
+        const client = new CriticalPathClient({ baseUrl: 'http://api.test', fetch: fetchSpy, retry: { retries: 3 } });
+        await expect(client.getProjects()).rejects.toMatchObject({ status: 400 });
+        expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+});
+//# sourceMappingURL=transport.test.js.map

package/dist/transport.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.test.js","sourceRoot":"","sources":["../src/transport.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@critical-path/client",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Type-safe JavaScript/TypeScript client SDK for consuming Critical Path API endpoints",
   "author": "Jack James",
   "license": "MIT",
@@ -21,13 +21,13 @@
     }
   },
   "dependencies": {
-    "@critical-path/core": "0.30.0"
+    "@critical-path/core": "0.31.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0",
-    "@critical-path/server": "0.22.0"
+    "@critical-path/server": "0.23.0"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/index.ts

@@ -123,12 +123,68 @@ export interface UpdateStatusResult {
   timestamp: number;
 }
 
+type HeaderMap = Record<string, string>;
+
 export interface ClientOptions {
-  baseUrl: string; // e.g. "http://localhost:3000/api/critical-path"
-  headers?: Record<string, string>;
+  /** API base URL, e.g. `http://localhost:3000/api/critical-path`. */
+  baseUrl: string;
+  /**
+   * Headers sent with every request. Pass a function to compute them per request, e.g. to attach
+   * a freshly refreshed access token: `headers: async () => ({ Authorization: `Bearer ${await getToken()}` })`.
+   */
+  headers?: HeaderMap | (() => HeaderMap | Promise<HeaderMap>);
   fetch?: typeof fetch;
+  /** Abort requests that take longer than this. Default: no timeout. */
+  timeoutMs?: number;
+  /**
+   * Retry GET requests that fail with a network error, 429, 502, 503 or 504. Default: no retries.
+   * Delays double from `baseDelayMs` (default 250 ms) and honour `Retry-After` on 429/503.
+   */
+  retry?: { retries: number; baseDelayMs?: number };
 }
 
+/** Per-call options for a scoped client (see `CriticalPathClient.with`). */
+export interface RequestOptions {
+  signal?: AbortSignal;
+  headers?: HeaderMap;
+  timeoutMs?: number;
+}
+
+/**
+ * Error thrown for non-2xx responses. Carries the HTTP status and the server's error details
+ * (`issues` for validation errors, `cyclePath` for dependency cycles, and so on).
+ */
+export class CriticalPathError extends Error {
+  /** HTTP status code. */
+  readonly status: number;
+  /** Field-level validation problems for 400 responses. */
+  readonly issues?: Array<{ path: string; message: string }>;
+  /** The parsed JSON error body, if any (e.g. `fromStatus`, `toStatus`, `cyclePath`, `fieldKey`). */
+  readonly body?: Record<string, unknown>;
+
+  constructor(message: string, status: number, body?: Record<string, unknown>) {
+    super(message);
+    this.name = 'CriticalPathError';
+    this.status = status;
+    this.body = body;
+    this.issues = Array.isArray(body?.issues) ? (body!.issues as CriticalPathError['issues']) : undefined;
+  }
+
+  get isNotFound(): boolean {
+    return this.status === 404;
+  }
+}
+
+const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
+const sleep = (ms: number, signal?: AbortSignal | null) =>
+  new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    }, { once: true });
+  });
+
 function toBase64(data: Uint8Array | ArrayBuffer): string {
   const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
   let binary = '';
@@ -138,22 +194,32 @@ function toBase64(data: Uint8Array | ArrayBuffer): string {
   return btoa(binary);
 }
 
-class NotFoundResponseError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'NotFoundResponseError';
-  }
-}
-
 export class CriticalPathClient {
-  private baseUrl: string;
-  private headers: Record<string, string>;
-  private customFetch: typeof fetch;
+  private readonly baseUrl: string;
+  private readonly options: ClientOptions;
+  private readonly customFetch: typeof fetch;
+  /** Set on scoped clients created by `with()`. */
+  private readonly requestOptions?: RequestOptions;
 
   constructor(options: ClientOptions) {
+    this.options = options;
     this.baseUrl = options.baseUrl.replace(/\/+$/, '');
-    this.headers = options.headers || {};
-    this.customFetch = options.fetch || globalThis.fetch;
+    this.customFetch = options.fetch || ((...args) => globalThis.fetch(...args));
+  }
+
+  /**
+   * Returns a client that applies `options` to every call, e.g. to cancel requests when a
+   * component unmounts: `client.with({ signal: controller.signal }).getTasks(projectId)`.
+   */
+  with(options: RequestOptions): CriticalPathClient {
+    const scoped = Object.create(this) as CriticalPathClient;
+    const merged: RequestOptions = {
+      ...this.requestOptions,
+      ...options,
+      headers: { ...this.requestOptions?.headers, ...options.headers }
+    };
+    Object.defineProperty(scoped, 'requestOptions', { value: merged });
+    return scoped;
   }
 
   /**
@@ -165,36 +231,61 @@ export class CriticalPathClient {
       const res = await this.request<{ success: boolean }>(endpoint, { method: 'DELETE' });
       return res.success;
     } catch (err) {
-      if (err instanceof NotFoundResponseError) return false;
+      if (err instanceof CriticalPathError && err.isNotFound) return false;
       throw err;
     }
   }
 
-  private async request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
+  private async request<T>(endpoint: string, init: RequestInit = {}): Promise<T> {
     const url = `${this.baseUrl}${endpoint.startsWith('/') ? endpoint : `/${endpoint}`}`;
-    const response = await this.customFetch(url, {
-      ...options,
-      headers: {
-        'Content-Type': 'application/json',
-        ...this.headers,
-        ...options.headers
+    const method = (init.method ?? 'GET').toUpperCase();
+    const configured = typeof this.options.headers === 'function' ? await this.options.headers() : this.options.headers;
+    const headers: HeaderMap = {
+      ...(init.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+      ...configured,
+      ...this.requestOptions?.headers
+    };
+    const timeoutMs = this.requestOptions?.timeoutMs ?? this.options.timeoutMs;
+    const signals = [this.requestOptions?.signal, timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined].filter(
+      (s): s is AbortSignal => !!s
+    );
+    const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
+    const retries = method === 'GET' ? this.options.retry?.retries ?? 0 : 0;
+    const baseDelay = this.options.retry?.baseDelayMs ?? 250;
+
+    for (let attempt = 0; ; attempt++) {
+      let response: Response;
+      try {
+        response = await this.customFetch(url, { ...init, method, headers, signal });
+      } catch (err) {
+        // Network failure; never retry after an abort or timeout.
+        if (attempt < retries && !signal?.aborted) {
+          await sleep(baseDelay * 2 ** attempt, signal);
+          continue;
+        }
+        throw err;
       }
-    });
 
-    if (!response.ok) {
-      let errorMsg = `HTTP Error ${response.status}: ${response.statusText}`;
+      if (response.ok) return response.json() as Promise<T>;
+
+      if (attempt < retries && RETRYABLE_STATUSES.has(response.status)) {
+        const retryAfter = Number(response.headers.get('Retry-After'));
+        await sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : baseDelay * 2 ** attempt, signal);
+        continue;
+      }
+
+      let body: Record<string, unknown> | undefined;
       try {
-        const errJson = await response.json();
-        if (errJson.error) errorMsg = errJson.error;
+        body = await response.json();
       } catch {
-        // Fallback to HTTP error
+        // Non-JSON error body
       }
-      throw response.status === 404 ? new NotFoundResponseError(errorMsg) : new Error(errorMsg);
+      const message = typeof body?.error === 'string' ? body.error : `HTTP Error ${response.status}: ${response.statusText}`;
+      throw new CriticalPathError(message, response.status, body);
     }
-
-    return response.json();
   }
 
+
   // Workflows
   async getWorkflows(): Promise<Workflow[]> {
     const res = await this.request<{ workflows: Workflow[] }>('/workflows');
@@ -202,7 +293,7 @@ export class CriticalPathClient {
   }
 
   async getWorkflow(id: string): Promise<Workflow> {
-    const res = await this.request<{ workflow: Workflow }>(`/workflows/${id}`);
+    const res = await this.request<{ workflow: Workflow }>(`/workflows/${encodeURIComponent(id)}`);
     return res.workflow;
   }
 
@@ -215,7 +306,7 @@ export class CriticalPathClient {
   }
 
   async updateWorkflow(id: string, updates: UpdateWorkflowBody): Promise<Workflow> {
-    const res = await this.request<{ workflow: Workflow }>(`/workflows/${id}`, {
+    const res = await this.request<{ workflow: Workflow }>(`/workflows/${encodeURIComponent(id)}`, {
       method: 'PATCH',
       body: JSON.stringify(updates)
     });
@@ -223,7 +314,7 @@ export class CriticalPathClient {
   }
 
   async deleteWorkflow(id: string): Promise<boolean> {
-    return this.deleteRequest(`/workflows/${id}`);
+    return this.deleteRequest(`/workflows/${encodeURIComponent(id)}`);
   }
 
   // Projects
@@ -233,7 +324,7 @@ export class CriticalPathClient {
   }
 
   async getProject(id: string): Promise<Project> {
-    const res = await this.request<{ project: Project }>(`/projects/${id}`);
+    const res = await this.request<{ project: Project }>(`/projects/${encodeURIComponent(id)}`);
     return res.project;
   }
 
@@ -339,7 +430,7 @@ export class CriticalPathClient {
   }
 
   async getTask(id: string): Promise<Task> {
-    const res = await this.request<{ task: Task }>(`/tasks/${id}`);
+    const res = await this.request<{ task: Task }>(`/tasks/${encodeURIComponent(id)}`);
     return res.task;
   }
 
@@ -373,7 +464,7 @@ export class CriticalPathClient {
   }
 
   async updateTask(id: string, updates: UpdateTaskBody): Promise<Task> {
-    const res = await this.request<{ task: Task }>(`/tasks/${id}`, {
+    const res = await this.request<{ task: Task }>(`/tasks/${encodeURIComponent(id)}`, {
       method: 'PATCH',
       body: JSON.stringify(updates)
     });
@@ -450,6 +541,10 @@ export class CriticalPathClient {
     return (await this.request<{ webhooks: PublicWebhook[] }>('/webhooks')).webhooks;
   }
 
+  async getWebhook(id: string): Promise<PublicWebhook> {
+    return (await this.request<{ webhook: PublicWebhook }>(`/webhooks/${encodeURIComponent(id)}`)).webhook;
+  }
+
   /** Registers a webhook. The returned `secret` is shown only once; store it to verify deliveries. */
   async createWebhook(data: CreateWebhookBody): Promise<{ webhook: PublicWebhook; secret: string }> {
     return this.request<{ webhook: PublicWebhook; secret: string }>('/webhooks', {
@@ -519,7 +614,7 @@ export class CriticalPathClient {
   }
 
   async getTeam(id: string): Promise<Team> {
-    const res = await this.request<{ team: Team }>(`/teams/${id}`);
+    const res = await this.request<{ team: Team }>(`/teams/${encodeURIComponent(id)}`);
     return res.team;
   }
 
@@ -532,7 +627,7 @@ export class CriticalPathClient {
   }
 
   async updateTeam(id: string, updates: UpdateTeamBody): Promise<Team> {
-    const res = await this.request<{ team: Team }>(`/teams/${id}`, {
+    const res = await this.request<{ team: Team }>(`/teams/${encodeURIComponent(id)}`, {
       method: 'PATCH',
       body: JSON.stringify(updates)
     });
@@ -540,7 +635,7 @@ export class CriticalPathClient {
   }
 
   async deleteTeam(id: string): Promise<boolean> {
-    return this.deleteRequest(`/teams/${id}`);
+    return this.deleteRequest(`/teams/${encodeURIComponent(id)}`);
   }
 
   // Containers
@@ -549,6 +644,10 @@ export class CriticalPathClient {
     return res.containers;
   }
 
+  async getContainer(id: string): Promise<TaskContainer> {
+    return (await this.request<{ container: TaskContainer }>(`/containers/${encodeURIComponent(id)}`)).container;
+  }
+
   async createContainer(data: CreateContainerBody): Promise<TaskContainer> {
     const res = await this.request<{ container: TaskContainer }>('/containers', {
       method: 'POST',
@@ -558,7 +657,7 @@ export class CriticalPathClient {
   }
 
   async updateContainer(id: string, updates: UpdateContainerBody): Promise<TaskContainer> {
-    const res = await this.request<{ container: TaskContainer }>(`/containers/${id}`, {
+    const res = await this.request<{ container: TaskContainer }>(`/containers/${encodeURIComponent(id)}`, {
       method: 'PATCH',
       body: JSON.stringify(updates)
     });
@@ -566,7 +665,7 @@ export class CriticalPathClient {
   }
 
   async deleteContainer(id: string): Promise<boolean> {
-    return this.deleteRequest(`/containers/${id}`);
+    return this.deleteRequest(`/containers/${encodeURIComponent(id)}`);
   }
 
   // Deliverables
@@ -576,12 +675,12 @@ export class CriticalPathClient {
   }
 
   async getDeliverable(id: string): Promise<Deliverable> {
-    const res = await this.request<{ deliverable: Deliverable }>(`/deliverables/${id}`);
+    const res = await this.request<{ deliverable: Deliverable }>(`/deliverables/${encodeURIComponent(id)}`);
     return res.deliverable;
   }
 
   async getDeliverableSummary(id: string): Promise<DeliverableSummary> {
-    const res = await this.request<{ summary: DeliverableSummary }>(`/deliverables/${id}/summary`);
+    const res = await this.request<{ summary: DeliverableSummary }>(`/deliverables/${encodeURIComponent(id)}/summary`);
     return res.summary;
   }
 
@@ -594,7 +693,7 @@ export class CriticalPathClient {
   }
 
   async updateDeliverable(id: string, updates: UpdateDeliverableBody): Promise<Deliverable> {
-    const res = await this.request<{ deliverable: Deliverable }>(`/deliverables/${id}`, {
+    const res = await this.request<{ deliverable: Deliverable }>(`/deliverables/${encodeURIComponent(id)}`, {
       method: 'PATCH',
       body: JSON.stringify(updates)
     });
@@ -602,7 +701,7 @@ export class CriticalPathClient {
   }
 
   async deleteDeliverable(id: string): Promise<boolean> {
-    return this.deleteRequest(`/deliverables/${id}`);
+    return this.deleteRequest(`/deliverables/${encodeURIComponent(id)}`);
   }
 
   // Iterations
@@ -611,6 +710,10 @@ export class CriticalPathClient {
     return res.iterations;
   }
 
+  async getIteration(id: string): Promise<Iteration> {
+    return (await this.request<{ iteration: Iteration }>(`/iterations/${encodeURIComponent(id)}`)).iteration;
+  }
+
   async createIteration(data: CreateIterationBody): Promise<Iteration> {
     const res = await this.request<{ iteration: Iteration }>('/iterations', {
       method: 'POST',
@@ -620,7 +723,7 @@ export class CriticalPathClient {
   }
 
   async updateIteration(id: string, updates: UpdateIterationBody): Promise<Iteration> {
-    const res = await this.request<{ iteration: Iteration }>(`/iterations/${id}`, {
+    const res = await this.request<{ iteration: Iteration }>(`/iterations/${encodeURIComponent(id)}`, {
       method: 'PATCH',
       body: JSON.stringify(updates)
     });
@@ -628,7 +731,7 @@ export class CriticalPathClient {
   }
 
   async deleteIteration(id: string): Promise<boolean> {
-    return this.deleteRequest(`/iterations/${id}`);
+    return this.deleteRequest(`/iterations/${encodeURIComponent(id)}`);
   }
 
   // Activity Stream