caveman/tests/caveman-compress/mixed-with-code.md

API Integration Guide

Authentication

All API requests include valid JWT in Authorization header. Get token from login endpoint using credentials. If expired, use refresh token to get new access token, retry request.

Auth example:

const login = async (email: string, password: string) => {
  const response = await fetch('/api/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password }),
  });
  const { accessToken, refreshToken } = await response.json();
  return { accessToken, refreshToken };
};

Access token expires in 15 min. On 401 → refresh token.

const refreshAccessToken = async (refreshToken: string) => {
  const response = await fetch('/api/auth/refresh', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ refreshToken }),
  });
  if (!response.ok) throw new Error('Refresh failed');
  const { accessToken } = await response.json();
  return accessToken;
};

Creating Tasks

Create task → POST /api/v2/tasks.

Required: projectId, title Optional: others use defaults

priority: 1 (low) → 5 (high), default 3

interface CreateTaskPayload {
  projectId: string;
  title: string;
  description?: string;
  assigneeId?: string;
  priority?: 1 | 2 | 3 | 4 | 5;
  dueDate?: string; // ISO 8601 format
  labels?: string[];
}

const createTask = async (payload: CreateTaskPayload, token: string) => {
  const response = await fetch('/api/v2/tasks', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
    },
    body: JSON.stringify(payload),
  });
  return response.json();
};

Response includes: id, createdAt, status (default "todo").

Error Handling

All errors return:

• code — machine-readable
• message — human-readable
• details — optional extra info

Common errors:

• AUTH_TOKEN_EXPIRED — refresh + retry
• AUTH_TOKEN_INVALID — login again
• VALIDATION_ERROR — check details
• NOT_FOUND — resource missing / no access
• RATE_LIMIT_EXCEEDED — wait (Retry-After)

Pattern:

class ApiError extends Error {
  constructor(
    public code: string,
    public status: number,
    message: string,
    public details?: Record<string, string[]>
  ) {
    super(message);
  }
}

const apiClient = async (url: string, options: RequestInit = {}) => {
  const response = await fetch(url, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new ApiError(error.code, response.status, error.message, error.details);
  }

  return response.json();
};

Pagination

All list endpoints use cursor-based pagination. Better than offset for consistency with concurrent changes.

Response includes cursor. Pass as query param for next page.

Defaults:

• page size: 50
• max: 100 (limit)

Fetch all tasks:

const fetchAllTasks = async (projectId: string, token: string) => {
  let cursor: string | undefined;
  const allTasks = [];

  do {
    const params = new URLSearchParams({ limit: '50' });
    if (cursor) params.set('cursor', cursor);

    const response = await apiClient(
      `/api/v2/projects/${projectId}/tasks?${params}`,
      { headers: { Authorization: `Bearer ${token}` } }
    );

    allTasks.push(...response.data);
    cursor = response.cursor;
  } while (cursor);

  return allTasks;
};

Rate Limiting

Limits:

• Authenticated: 100 req/min
• Unauthenticated: 20 req/min

On exceed → 429 + Retry-After.

Client strategy:

• Use exponential backoff
• Start with Retry-After
• Double each retry
• Max wait: 60s

Prevents thundering herd.

Webhooks

Supports outgoing webhooks for events:

• task created, updated, deleted, assigned, status change

Configured in project settings. Sends POST with event payload.

Security:

• Header: X-Taskflow-Signature
• HMAC-SHA256 of body using webhook secret
• Always verify before processing

import crypto from 'crypto';

const verifyWebhookSignature = (
  payload: string,
  signature: string,
  secret: string
): boolean => {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
};