Hooks Reference¶

Custom React hooks organized by domain.

Authentication¶

useAuth¶

hooks/use-auth.ts

Central auth state management.

const { 
  session,           // Session data
  user,              // User object
  token,             // JWT for API calls
  activeOrganization,// Current org
  isLoading 
} = useAuth();

Features: - Provides JWT token from BetterAuth - Syncs active organization with URL slug - Caches token for 10 minutes

useRole¶

hooks/use-role.ts

RBAC access from RoleProvider context.

const { 
  role,      // "owner" | "admin" | "member"
  isAdmin,   // role === "admin" || role === "owner"
  isManager, // role === "owner"
  isBasic    // role === "member"
} = useRole();

useTeam¶

hooks/use-team.ts

Team state management.

const { 
  teams,          // Team[] - All org teams
  activeTeam,     // Current team
  isLoading 
} = useTeam();

Features: - Syncs active team with URL parameter - Fetches teams for active organization

Sessions¶

useSessions¶

hooks/sessions/use-sessions.ts

List and create sessions.

const { 
  sessions,        // Session[]
  isLoading,
  createSession    // (data: CreateSessionData) => Promise<Session>
} = useSessions(organizationSlug);

useSession¶

hooks/sessions/use-session.ts

Single session with full operations.

const {
  session,         // Session
  logs,            // Log[]
  clips,           // Clip[]
  timeline,        // TimelineItem[]
  isLoading,
  startSession,    // () => Promise<void>
  endSession,      // () => Promise<void>
  deleteSession,   // () => Promise<void>
  createLog,       // (data) => Promise<Log>
  createClip       // (data) => Promise<Clip>
} = useSession(organizationSlug, sessionId);

useSessionForm¶

hooks/sessions/use-session-form.ts

Single form template management.

const {
  form,            // SessionForm
  isLoading,
  updateForm,      // (data) => Promise<void>
  deleteForm       // () => Promise<void>
} = useSessionForm(organizationSlug, formId);

useOrganizationSessionForms¶

hooks/sessions/use-organization-session-forms.ts

Form template collection.

const {
  forms,           // SessionForm[]
  isLoading,
  createForm       // (data) => Promise<SessionForm>
} = useOrganizationSessionForms(organizationSlug);

useSessionLog¶

hooks/sessions/use-session-log.ts

Single log entry.

const { 
  log,             // Log
  isLoading 
} = useSessionLog(organizationSlug, sessionId, logId);

useSessionClip¶

hooks/sessions/use-session-clip.ts

Single clip with video URL.

const { 
  clip,            // Clip
  videoUrl,        // string
  isLoading 
} = useSessionClip(organizationSlug, sessionId, clipId);

Embeddings¶

useEmbeddings¶

hooks/embeddings/use-embeddings.ts

List and upload embeddings.

const {
  embeddings,      // Embedding[]
  total,           // number
  isLoading,
  uploadFiles      // (files: File[]) => Promise<void>
} = useEmbeddings(organizationSlug, { params });

Params: - limit - Max results (default: 100)

useEmbedding¶

hooks/embeddings/use-embedding.ts

Single embedding with media.

const {
  embedding,       // Embedding
  mediaUrl,        // string (blob URL)
  isLoading,
  isPolling,       // Processing in progress
  deleteEmbedding  // () => Promise<void>
} = useEmbedding(organizationSlug, embeddingId);

Features: - Polls every 5s while processing - Fetches media blob for preview

useSearchEmbeddings¶

hooks/embeddings/use-search-embedding.ts

Search embeddings.

const { 
  embeddings,      // Embedding[]
  isLoading 
} = useSearchEmbeddings(organizationSlug, {
  searchQuery,     // Text search
  filename,        // Filename match
  contentType,     // Filter by type
  footballRelated, // Sports relevance filter
  limit
});

Chat¶

useChat¶

hooks/use-chat.ts

Complete chat functionality.

const {
  // Queries
  chats,           // Chat[]
  pinnedChats,     // Chat[]
  chat,            // Chat (when chatId provided)
  messages,        // Message[]

  // States
  isLoadingChats,
  isLoadingChat,
  isSending,

  // Mutations
  createChat,      // (text: string) => Promise<Chat>
  sendMessage,     // (prompt: string) => Promise<void>
  pinChat,         // () => Promise<void>
  archiveChat,     // () => Promise<void>
  updateTitle,     // (title: string) => Promise<void>
  deleteChat       // () => Promise<void>
} = useChat(organizationSlug, chatId?);

Features: - SSE streaming for messages - Optimistic updates - Debounced UI updates during streaming

Training¶

useTrainings¶

hooks/trainings/use-trainings.ts

List and create training jobs.

const {
  jobs,            // TrainingJob[]
  isLoading,
  createJob        // (data: StartTrainingRequest) => Promise<StartTrainingResponse>
} = useTrainings(organizationSlug);

useTraining¶

hooks/trainings/use-training.ts

Single job management.

const {
  job,             // TrainingJob
  status,          // TrainingStatus
  isLoading,
  isPolling,       // Job still running
  cancelJob,       // () => Promise<void>
  rollbackJob      // () => Promise<void>
} = useTraining(organizationSlug, jobId);

Features: - Polls status every 5s while running

Devices & Cameras¶

useDevices¶

hooks/use-devices.ts

Admin device management.

const {
  devices,         // Device[]
  isLoading,
  registerDevice,  // (data) => Promise<Device>
  updateDevice,    // (id, data) => Promise<void>
  deleteDevice     // (id) => Promise<void>
} = useDevices();

useCameraStream¶

hooks/use-camera-stream.ts

Camera streaming and detection.

const {
  // Camera data
  cameras,           // Camera[]
  connectedCameras,  // Camera[]
  activeCamera,      // Camera
  activeCameras,     // Camera[]

  // Detection
  detectionStatus,   // { enabled: boolean }

  // Streaming state
  selectedCameraId,  // string
  isStreaming,       // boolean
  frameData,         // FrameData

  // Actions
  handleCameraChange,    // (cameraId) => void
  startStreaming,        // (cameraId) => void
  stopStreaming,         // () => void
  handleCreateClip,      // (data) => Promise<Clip>
  handleEnableDetection, // () => Promise<void>
  handleDisableDetection // () => Promise<void>
} = useCameraStream({
  organizationId,
  sessionId,
  serverHostURL
});

UI Utilities¶

useTutorialProgress¶

hooks/use-tutorial-progress.ts

Tutorial step tracking with localStorage.

const {
  progress,        // Record<string, boolean>
  completeStep,    // (stepId: string) => void
  resetProgress,   // () => void
  isStepCompleted  // (stepId: string) => boolean
} = useTutorialProgress(pageId, stepIds);

Features: - Persists to localStorage - Syncs across tabs via storage events

useMobile¶

hooks/use-mobile.ts

Mobile viewport detection.

const isMobile = useMobile();

Hook Patterns¶

Query Keys¶

All hooks use namespaced query keys:

// Pattern
["resource", organizationSlug, ...identifiers]

// Examples
["sessions", "my-org"]
["session", "my-org", "session-123"]
["session-logs", "my-org", "session-123"]

Enabled Conditions¶

Queries only run when dependencies are ready:

const { data } = useQuery({
  queryKey: ["sessions", orgSlug],
  queryFn: fetchSessions,
  enabled: Boolean(token && orgSlug && user)
});

Mutations with Feedback¶

const createMutation = useMutation({
  mutationFn: createResource,
  onSuccess: () => {
    toast.success("Created successfully");
    queryClient.invalidateQueries(["resources"]);
  },
  onError: (error) => {
    toast.error("Failed to create");
    console.error(error);
  }
});

Polling¶

const { data } = useQuery({
  queryKey: ["job", jobId],
  queryFn: fetchJob,
  refetchInterval: (data) => 
    isTerminalStatus(data?.status) ? false : 5000
});