feat(#194): Fix workspace ID transmission mismatch between API and client

- Update WorkspaceGuard to support query string as fallback (backward compatibility)
- Priority order: Header > Param > Body > Query
- Update web client to send workspace ID via X-Workspace-Id header (recommended)
- Extend apiRequest helpers to accept workspace ID option
- Update fetchTasks to use header instead of query parameter
- Add comprehensive tests for all workspace ID transmission methods
- Tests passing: API 11 tests, Web 6 new tests (total 494)

This ensures consistent workspace ID handling with proper multi-tenant isolation
while maintaining backward compatibility with existing query string approaches.

Fixes #194

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

apps/web/src/lib/api/client.test.ts

@@ -100,6 +100,26 @@ describe("API Client", (): void => {
       );
       expect(result).toEqual(mockData);
     });
+
+    it("should include workspace ID in header when provided", async (): Promise<void> => {
+      const mockData = { id: "1" };
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(mockData),
+      });
+
+      await apiGet<typeof mockData>("/test", "workspace-123");
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        "http://localhost:3001/test",
+        expect.objectContaining({
+          method: "GET",
+          headers: expect.objectContaining({
+            "X-Workspace-Id": "workspace-123",
+          }),
+        })
+      );
+    });
   });
 
   describe("apiPost", (): void => {
@@ -143,6 +163,26 @@ describe("API Client", (): void => {
       const callArgs = mockFetch.mock.calls[0]![1] as RequestInit;
       expect(callArgs.body).toBeUndefined();
     });
+
+    it("should include workspace ID in header when provided", async (): Promise<void> => {
+      const postData = { name: "New Item" };
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({}),
+      });
+
+      await apiPost("/test", postData, "workspace-456");
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        "http://localhost:3001/test",
+        expect.objectContaining({
+          method: "POST",
+          headers: expect.objectContaining({
+            "X-Workspace-Id": "workspace-456",
+          }),
+        })
+      );
+    });
   });
 
   describe("apiPatch", (): void => {

apps/web/src/lib/api/client.ts

@@ -3,7 +3,7 @@
  * Handles authenticated requests to the backend API
  */
 
-/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-misused-spread */
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
 
 const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
 
@@ -22,18 +22,35 @@ export interface ApiResponse<T> {
   };
 }
 
+/**
+ * Options for API requests with workspace context
+ */
+export interface ApiRequestOptions extends RequestInit {
+  workspaceId?: string;
+}
+
 /**
  * Make an authenticated API request
  */
-export async function apiRequest<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
+export async function apiRequest<T>(endpoint: string, options: ApiRequestOptions = {}): Promise<T> {
   const url = `${API_BASE_URL}${endpoint}`;
+  const { workspaceId, ...fetchOptions } = options;
+
+  // Build headers with workspace ID if provided
+  const baseHeaders = (fetchOptions.headers as Record<string, string> | undefined) ?? {};
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...baseHeaders,
+  };
+
+  // Add workspace ID header if provided (recommended over query string)
+  if (workspaceId) {
+    headers["X-Workspace-Id"] = workspaceId;
+  }
 
   const response = await fetch(url, {
-    ...options,
-    headers: {
-      "Content-Type": "application/json",
-      ...(options.headers ?? {}),
-    },
+    ...fetchOptions,
+    headers,
     credentials: "include", // Include cookies for session
   });
 
@@ -54,15 +71,23 @@ export async function apiRequest<T>(endpoint: string, options: RequestInit = {})
 /**
  * GET request helper
  */
-export async function apiGet<T>(endpoint: string): Promise<T> {
-  return apiRequest<T>(endpoint, { method: "GET" });
+export async function apiGet<T>(endpoint: string, workspaceId?: string): Promise<T> {
+  const options: ApiRequestOptions = { method: "GET" };
+  if (workspaceId !== undefined) {
+    options.workspaceId = workspaceId;
+  }
+  return apiRequest<T>(endpoint, options);
 }
 
 /**
  * POST request helper
  */
-export async function apiPost<T>(endpoint: string, data?: unknown): Promise<T> {
-  const options: RequestInit = {
+export async function apiPost<T>(
+  endpoint: string,
+  data?: unknown,
+  workspaceId?: string
+): Promise<T> {
+  const options: ApiRequestOptions = {
     method: "POST",
   };
 
@@ -70,22 +95,40 @@ export async function apiPost<T>(endpoint: string, data?: unknown): Promise<T> {
     options.body = JSON.stringify(data);
   }
 
+  if (workspaceId !== undefined) {
+    options.workspaceId = workspaceId;
+  }
+
   return apiRequest<T>(endpoint, options);
 }
 
 /**
  * PATCH request helper
  */
-export async function apiPatch<T>(endpoint: string, data: unknown): Promise<T> {
-  return apiRequest<T>(endpoint, {
+export async function apiPatch<T>(
+  endpoint: string,
+  data: unknown,
+  workspaceId?: string
+): Promise<T> {
+  const options: ApiRequestOptions = {
     method: "PATCH",
     body: JSON.stringify(data),
-  });
+  };
+
+  if (workspaceId !== undefined) {
+    options.workspaceId = workspaceId;
+  }
+
+  return apiRequest<T>(endpoint, options);
 }
 
 /**
  * DELETE request helper
  */
-export async function apiDelete<T>(endpoint: string): Promise<T> {
-  return apiRequest<T>(endpoint, { method: "DELETE" });
+export async function apiDelete<T>(endpoint: string, workspaceId?: string): Promise<T> {
+  const options: ApiRequestOptions = { method: "DELETE" };
+  if (workspaceId !== undefined) {
+    options.workspaceId = workspaceId;
+  }
+  return apiRequest<T>(endpoint, options);
 }

apps/web/src/lib/api/tasks.test.ts

@@ -59,7 +59,7 @@ describe("Task API Client", (): void => {
 
     const result = await fetchTasks();
 
-    expect(apiGet).toHaveBeenCalledWith("/api/tasks");
+    expect(apiGet).toHaveBeenCalledWith("/api/tasks", undefined);
     expect(result).toEqual(mockTasks);
   });
 
@@ -75,7 +75,7 @@ describe("Task API Client", (): void => {
 
     await fetchTasks({ status: TaskStatus.IN_PROGRESS });
 
-    expect(apiGet).toHaveBeenCalledWith("/api/tasks?status=IN_PROGRESS");
+    expect(apiGet).toHaveBeenCalledWith("/api/tasks?status=IN_PROGRESS", undefined);
   });
 
   it("should fetch tasks with multiple filters", async (): Promise<void> => {
@@ -84,7 +84,30 @@ describe("Task API Client", (): void => {
 
     await fetchTasks({ status: TaskStatus.IN_PROGRESS, priority: TaskPriority.HIGH });
 
-    expect(apiGet).toHaveBeenCalledWith("/api/tasks?status=IN_PROGRESS&priority=HIGH");
+    expect(apiGet).toHaveBeenCalledWith("/api/tasks?status=IN_PROGRESS&priority=HIGH", undefined);
+  });
+
+  it("should fetch tasks with workspace ID", async (): Promise<void> => {
+    const mockTasks: Task[] = [];
+    vi.mocked(apiGet).mockResolvedValueOnce({ data: mockTasks });
+
+    await fetchTasks({ workspaceId: "workspace-123" });
+
+    // WorkspaceId should be sent via header (second param), not query string
+    expect(apiGet).toHaveBeenCalledWith("/api/tasks", "workspace-123");
+  });
+
+  it("should fetch tasks with filters and workspace ID", async (): Promise<void> => {
+    const mockTasks: Task[] = [];
+    vi.mocked(apiGet).mockResolvedValueOnce({ data: mockTasks });
+
+    await fetchTasks({
+      status: TaskStatus.IN_PROGRESS,
+      workspaceId: "workspace-456",
+    });
+
+    // Status in query, workspace in header
+    expect(apiGet).toHaveBeenCalledWith("/api/tasks?status=IN_PROGRESS", "workspace-456");
   });
 
   describe("error handling", (): void => {
@@ -138,7 +161,7 @@ describe("Task API Client", (): void => {
       await fetchTasks({ invalidFilter: "value" } as any);
 
       // Function should ignore invalid filters and call without query params
-      expect(apiGet).toHaveBeenCalledWith("/api/tasks");
+      expect(apiGet).toHaveBeenCalledWith("/api/tasks", undefined);
     });
 
     it("should handle empty response data", async (): Promise<void> => {

apps/web/src/lib/api/tasks.ts

@@ -19,20 +19,19 @@ export interface TaskFilters {
 export async function fetchTasks(filters?: TaskFilters): Promise<Task[]> {
   const params = new URLSearchParams();
 
+  // Add filter parameters (not workspace ID - that goes in header)
   if (filters?.status) {
     params.append("status", filters.status);
   }
   if (filters?.priority) {
     params.append("priority", filters.priority);
   }
-  if (filters?.workspaceId) {
-    params.append("workspaceId", filters.workspaceId);
-  }
 
   const queryString = params.toString();
   const endpoint = queryString ? `/api/tasks?${queryString}` : "/api/tasks";
 
-  const response = await apiGet<ApiResponse<Task[]>>(endpoint);
+  // Pass workspaceId via header (X-Workspace-Id) instead of query string
+  const response = await apiGet<ApiResponse<Task[]>>(endpoint, filters?.workspaceId);
   return response.data;
 }