@critical-path/client 0.17.0 → 0.19.0

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.17.0",
+  "version": "0.19.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.29.0"
+    "@critical-path/core": "0.30.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0",
-    "@critical-path/server": "0.21.0"
+    "@critical-path/server": "0.22.0"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/contract.test.ts

@@ -68,6 +68,12 @@ describe('client ↔ server contract', () => {
     expect((await client.getWebhooks()).map((w) => w.id)).toContain(webhook.id);
     expect(await client.deleteWebhook(webhook.id)).toBe(true);
 
+    const page = await client.queryTasks({ projectId: project.id, limit: 1, parentId: null });
+    expect(page.items).toHaveLength(1);
+    expect(page.nextCursor).toBeTruthy();
+    expect((await client.getTasks(project.id)).length).toBeGreaterThan(1);
+    expect((await client.getActivities({ projectId: project.id })).length).toBeGreaterThan(0);
+
     expect(await client.deleteProject(project.id)).toBe(true);
     expect(await client.deleteProject(project.id)).toBe(false);
   });

package/src/index.ts

@@ -25,6 +25,9 @@ import type {
   UpdateWebhookBody
 } from '@critical-path/core/schemas';
 import type {
+  ActivityQuery,
+  Page,
+  TaskQuery,
   PublicWebhook,
   TaskDependency,
   Project,
@@ -120,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 = '';
@@ -135,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;
   }
 
   /**
@@ -162,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');
@@ -199,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;
   }
 
@@ -212,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)
     });
@@ -220,7 +314,7 @@ export class CriticalPathClient {
   }
 
   async deleteWorkflow(id: string): Promise<boolean> {
-    return this.deleteRequest(`/workflows/${id}`);
+    return this.deleteRequest(`/workflows/${encodeURIComponent(id)}`);
   }
 
   // Projects
@@ -230,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;
   }
 
@@ -303,14 +397,40 @@ export class CriticalPathClient {
   }
 
   // Tasks
+  /** All tasks (optionally in one project), following pagination. Prefer `queryTasks` for large lists. */
   async getTasks(projectId?: string): Promise<Task[]> {
-    const query = projectId ? `?projectId=${encodeURIComponent(projectId)}` : '';
-    const res = await this.request<{ tasks: Task[] }>(`/tasks${query}`);
-    return res.tasks;
+    return this.collectPages((cursor) => this.queryTasks({ projectId, cursor, limit: 500 }));
+  }
+
+  /**
+   * One page of tasks, oldest first. Filters: `status` and `priority` (arrays), `assigneeId`,
+   * `iterationId`, `deliverableId`, `containerId`, `parentId` (`null` for top-level tasks).
+   */
+  async queryTasks(query: TaskQuery = {}): Promise<Page<Task>> {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined || key === 'projectIds') continue;
+      if (key === 'parentId' && value === null) params.set('parentId', 'none');
+      else params.set(key, Array.isArray(value) ? value.join(',') : String(value));
+    }
+    const qs = params.size ? `?${params}` : '';
+    const res = await this.request<{ tasks: Task[]; nextCursor?: string }>(`/tasks${qs}`);
+    return { items: res.tasks, nextCursor: res.nextCursor };
+  }
+
+  private async collectPages<T>(fetchPage: (cursor?: string) => Promise<Page<T>>): Promise<T[]> {
+    const items: T[] = [];
+    let cursor: string | undefined;
+    do {
+      const page = await fetchPage(cursor);
+      items.push(...page.items);
+      cursor = page.nextCursor;
+    } while (cursor);
+    return items;
   }
 
   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;
   }
 
@@ -344,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)
     });
@@ -421,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', {
@@ -490,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;
   }
 
@@ -503,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)
     });
@@ -511,7 +635,7 @@ export class CriticalPathClient {
   }
 
   async deleteTeam(id: string): Promise<boolean> {
-    return this.deleteRequest(`/teams/${id}`);
+    return this.deleteRequest(`/teams/${encodeURIComponent(id)}`);
   }
 
   // Containers
@@ -520,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',
@@ -529,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)
     });
@@ -537,7 +665,7 @@ export class CriticalPathClient {
   }
 
   async deleteContainer(id: string): Promise<boolean> {
-    return this.deleteRequest(`/containers/${id}`);
+    return this.deleteRequest(`/containers/${encodeURIComponent(id)}`);
   }
 
   // Deliverables
@@ -547,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;
   }
 
@@ -565,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)
     });
@@ -573,7 +701,7 @@ export class CriticalPathClient {
   }
 
   async deleteDeliverable(id: string): Promise<boolean> {
-    return this.deleteRequest(`/deliverables/${id}`);
+    return this.deleteRequest(`/deliverables/${encodeURIComponent(id)}`);
   }
 
   // Iterations
@@ -582,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',
@@ -591,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)
     });
@@ -599,17 +731,24 @@ export class CriticalPathClient {
   }
 
   async deleteIteration(id: string): Promise<boolean> {
-    return this.deleteRequest(`/iterations/${id}`);
+    return this.deleteRequest(`/iterations/${encodeURIComponent(id)}`);
   }
 
   // Activity Stream
+  /** The whole activity feed (newest first), following pagination. Prefer `queryActivities` for feeds. */
   async getActivities(filter?: { projectId?: string; taskId?: string }): Promise<Activity[]> {
+    return this.collectPages((cursor) => this.queryActivities({ ...filter, cursor, limit: 500 }));
+  }
+
+  /** One page of the activity feed, newest first. */
+  async queryActivities(query: ActivityQuery = {}): Promise<Page<Activity>> {
     const params = new URLSearchParams();
-    if (filter?.projectId) params.set('projectId', filter.projectId);
-    if (filter?.taskId) params.set('taskId', filter.taskId);
-    const query = params.toString() ? `?${params.toString()}` : '';
-    const res = await this.request<{ activities: Activity[] }>(`/activities${query}`);
-    return res.activities;
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && key !== 'projectIds') params.set(key, String(value));
+    }
+    const qs = params.size ? `?${params}` : '';
+    const res = await this.request<{ activities: Activity[]; nextCursor?: string }>(`/activities${qs}`);
+    return { items: res.activities, nextCursor: res.nextCursor };
   }
 
   // Comments