Focura API Reference

{
  "sub"  : "cm_user_abc123",       // User cuid
  "email": "you@example.com",
  "role" : "USER",                  // USER | ADMIN | SUPER_ADMIN
  "iat"  : 1714480000,              // Issued at (Unix timestamp)
  "exp"  : 1714480900,              // Expires at (iat + 900s = 15 min)
  "jti"  : "unique-jwt-id"         // JWT ID — tracked in Redis for revocation
}

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit    : 3
X-RateLimit-Remaining: 0
X-RateLimit-Reset    : 1714483600000
Retry-After          : 3600

{
  "success"   : false,
  "error"     : "TOO_MANY_REQUESTS",
  "message"   : "You have sent too many messages. Please try again in 60 minutes.",
  "retryAfter": 1714483600000,
  "remaining" : 0
}

// Raw SSE stream from the server:

event: notification
data: {
  "id"       : "cm_notif_abc123",
  "type"     : "TASK_ASSIGNED",
  "title"    : "Task assigned to you",
  "message"  : "Raihan assigned 'Implement dark mode' to you",
  "read"     : false,
  "actionUrl": "/workspace/cm_ws_xyz/tasks/cm_task_abc",
  "createdAt": "2026-04-30T14:22:00.000Z",
  "sender"   : {
    "id"   : "cm_user_raihan",
    "name" : "Mohammad Raihan",
    "image": "https://res.cloudinary.com/..."
  }
}

// hooks/useNotifications.ts
import { useEffect, useCallback } from 'react';
import { useQueryClient }         from '@tanstack/react-query';

const API = process.env.NEXT_PUBLIC_API_URL ?? '';

export function useNotifications() {
  const queryClient = useQueryClient();

  const handleEvent = useCallback((event: MessageEvent) => {
    const notification = JSON.parse(event.data);

    // 1. Optimistically add to local notification list
    queryClient.setQueryData(['notifications'], (old: any) => ({
      ...old,
      data: {
        ...old?.data,
        notifications: [notification, ...(old?.data?.notifications ?? [])],
      },
    }));

    // 2. Invalidate relevant queries based on notification type
    if (['TASK_ASSIGNED', 'TASK_COMPLETED'].includes(notification.type)) {
      queryClient.invalidateQueries({ queryKey: ['tasks'] });
    }
    if (notification.type === 'MEMBER_JOINED') {
      queryClient.invalidateQueries({ queryKey: ['workspace-members'] });
    }
  }, [queryClient]);

  useEffect(() => {
    const es = new EventSource(`${API}/api/notifications/stream`, {
      withCredentials: true,   // sends HTTP-only auth cookie
    });

    es.addEventListener('notification', handleEvent);

    es.onerror = () => {
      // Browser auto-reconnects with exponential backoff
      console.warn('SSE connection error — reconnecting…');
    };

    return () => {
      es.removeEventListener('notification', handleEvent);
      es.close();
    };
  }, [handleEvent]);
}

// All error responses follow this shape:
{
  "success": false,
  "error"  : "ERROR_CODE",       // Machine-readable constant (snake_case uppercase)
  "message": "Human explanation" // User-facing message — safe to display
}

// 422 Validation errors additionally include:
{
  "success": false,
  "error"  : "VALIDATION_ERROR",
  "message": "Please fix the errors below.",
  "errors" : {
    "email"   : ["Please enter a valid email address"],
    "password": ["Min 8 characters"],
    "name"    : ["Name must be at least 2 characters"]
  }
}

// 429 Rate limit errors additionally include:
{
  "success"   : false,
  "error"     : "TOO_MANY_REQUESTS",
  "message"   : "You have sent too many messages. Please try again in 60 minutes.",
  "retryAfter": 1714483600000,   // Unix ms — when the window resets
  "remaining" : 0
}