chore: adds jsdoc comments

honeycomb/src/services/api.ts

@@ -1,6 +1,13 @@
-// In the honeycomb monorepo, hive handles all endpoints (auth, user, IAM, and agent control)
+/**
+ * API Client Service
+ *
+ * Generic HTTP client for all hive endpoints (auth, user, IAM, and agent control).
+ * Handles authentication tokens from localStorage and standard CRUD operations.
+ */
+
 const API_URL = import.meta.env.VITE_API_URL || ''
 
+
 export class ApiError extends Error {
   constructor(
     public status: number,
@@ -37,6 +44,13 @@ class ApiClient {
     return headers
   }
 
+  /**
+   * Performs a GET request to the specified endpoint.
+   * @template T - Expected response type
+   * @param endpoint - API endpoint path (e.g., '/user/profile')
+   * @returns Promise resolving to the parsed JSON response
+   * @throws {ApiError} When the response status is not ok (non-2xx)
+   */
   async get<T>(endpoint: string): Promise<T> {
     const response = await fetch(`${this.baseUrl}${endpoint}`, {
       method: 'GET',
@@ -50,6 +64,14 @@ class ApiClient {
     return response.json()
   }
 
+  /**
+   * Performs a POST request to the specified endpoint.
+   * @template T - Expected response type
+   * @param endpoint - API endpoint path
+   * @param data - Optional request body (will be JSON stringified)
+   * @returns Promise resolving to the parsed JSON response
+   * @throws {ApiError} When the response status is not ok (non-2xx)
+   */
   async post<T>(endpoint: string, data?: unknown): Promise<T> {
     const response = await fetch(`${this.baseUrl}${endpoint}`, {
       method: 'POST',
@@ -64,6 +86,14 @@ class ApiClient {
     return response.json()
   }
 
+  /**
+   * Performs a PUT request to the specified endpoint.
+   * @template T - Expected response type
+   * @param endpoint - API endpoint path
+   * @param data - Request body (will be JSON stringified)
+   * @returns Promise resolving to the parsed JSON response
+   * @throws {ApiError} When the response status is not ok (non-2xx)
+   */
   async put<T>(endpoint: string, data: unknown): Promise<T> {
     const response = await fetch(`${this.baseUrl}${endpoint}`, {
       method: 'PUT',
@@ -78,6 +108,13 @@ class ApiClient {
     return response.json()
   }
 
+  /**
+   * Performs a DELETE request to the specified endpoint.
+   * @template T - Expected response type
+   * @param endpoint - API endpoint path
+   * @returns Promise resolving to the parsed JSON response
+   * @throws {ApiError} When the response status is not ok (non-2xx)
+   */
   async delete<T>(endpoint: string): Promise<T> {
     const response = await fetch(`${this.baseUrl}${endpoint}`, {
       method: 'DELETE',
@@ -92,9 +129,11 @@ class ApiClient {
   }
 }
 
-// Main API client for all hive endpoints
+/** Main API client instance for all hive endpoints. */
 export const apiClient = new ApiClient(API_URL)
 
-// Aliases for compatibility with existing code
+/** @deprecated Use apiClient instead. Alias for backward compatibility. */
 export const serverClient = apiClient
+
+/** @deprecated Use apiClient instead. Alias for backward compatibility. */
 export const hiveClient = apiClient

honeycomb/src/services/authApi.ts

@@ -1,3 +1,7 @@
+/**
+ * Authentication API Service
+ */
+
 import { serverClient } from './api'
 import type {
   LoginCredentials,
@@ -7,11 +11,50 @@ import type {
   RegisterResponse,
 } from '@/types/auth'
 
+/**
+ * Authenticates a user with email and password.
+ * 
+ * @param credentials - User login credentials
+ * @returns Promise resolving to login response with token and mustResetPassword
+ * @throws {ApiError} When credentials are invalid (401) or other server errors
+ * 
+ * @example
+ * submitLogin({
+ *   email: "john.doe@example.com",
+ *   password: "StrongPass123",
+ *   grantToken: "optional-grant-token"
+ * })
+ */
 export const submitLogin = (credentials: LoginCredentials): Promise<LoginResponse> =>
   serverClient.post<LoginResponse>('/user/login-v2', credentials)
 
+/**
+ * Retrieves organization information by its URL path.
+ * Used during login to display organization branding and validate org existence.
+ * @param orgPath - Organization's URL path identifier (e.g., 'acme-corp')
+ * @returns Promise resolving to organization info
+ * @throws {ApiError} When organization is not found (404)
+ * 
+ * @example
+ * getOrgInfoByPath('acme-corp')
+ */
 export const getOrgInfoByPath = (orgPath: string): Promise<{ data: OrgInfo }> =>
   serverClient.get<{ data: OrgInfo }>(`/iam/org/info/${orgPath}`)
 
+/**
+ * Registers a new user account.
+ * 
+ * @param credentials User registration payload
+ * @returns {Promise<RegisterResponse>} Registration response
+ * @throws {ApiError} When email is already taken (409) or validation fails (400)
+ * 
+ * @example
+ * submitRegister({
+ *   email: "john.doe@example.com",
+ *   password: "StrongPass123",
+ *   firstname: "John",
+ *   lastname: "Doe"
+ * })
+ */
 export const submitRegister = (credentials: RegisterCredentials): Promise<RegisterResponse> =>
   serverClient.post<RegisterResponse>('/user/register', credentials)

honeycomb/src/services/orgApi.ts

@@ -1,3 +1,7 @@
+/**
+ * Organization API Service
+ */
+
 import { serverClient } from './api'
 import type {
   Organization,
@@ -6,20 +10,64 @@ import type {
   UpdateOrgNamePayload,
 } from '@/types/user'
 
-// Organization Management
+/** Organization Management */
+
+/**
+ * Retrieves the current team/organization context for the authenticated user.
+ * @returns Promise resolving to current team details
+ * @throws {ApiError} When not authenticated (401)
+ * 
+ * @example
+ * getCurrentTeam()
+ */
 export const getCurrentTeam = () =>
   serverClient.get<OrganizationResponse>('/iam/get-current-team')
 
+/**
+ * Updates the organization's logo image.
+ * @param payload - update payload containing orgId and new logo image (base64 string)
+ * @returns Promise resolving to success message
+ * @throws {ApiError} When image format is invalid (400) or no admin access (403)
+ * 
+ * @example
+ * setOrganizationLogo({ orgId: 1, orgLogo: 'base64-encoded-image' })
+ */
 export const setOrganizationLogo = (payload: UpdateOrgLogoPayload) =>
   serverClient.post<{ message: string }>('/iam/set-organization-logo', payload)
 
+/**
+ * Renames the organization.
+ * @param payload - update payload containing orgId and new name
+ * @returns Promise resolving to success message
+ * @throws {ApiError} When name is invalid (400) or no admin access (403)
+ * 
+ * @example
+ * updateOrgName({ name: 'New Organization Name', orgId: 1 })
+ */
 export const updateOrgName = (payload: UpdateOrgNamePayload) =>
   serverClient.post<{ message: string }>('/iam/org/rename', payload)
 
-// Fetch all organizations user belongs to
+/**
+ * Retrieves all organizations the current user belongs to.
+ * Used to populate the organization switcher.
+ * @returns Promise resolving to array of organization details including orgName, orgId, teamId, and teamName
+ * @throws {ApiError} When not authenticated (401)
+ * 
+ * @example
+ * await getOrganizations()
+ */
 export const getOrganizations = () =>
   serverClient.get<Organization[]>('/iam/get-user-organizations')
 
-// Switch to a different organization
+/**
+ * Switches the user's current team/organization context.
+ * Returns a new auth token scoped to the selected team.
+ * @param payload - Object containing the teamId to switch to
+ * @returns Promise resolving to new authentication token for the selected team
+ * @throws {ApiError} When team not found (404) or no access (403)
+ * 
+ * @example
+ * await setCurrentTeam({ teamId: 1 })
+ */
 export const setCurrentTeam = (payload: { teamId: number }) =>
   serverClient.post<{ data: { token: string } }>('/iam/set-current-team', payload)

honeycomb/src/services/userApi.ts

@@ -1,3 +1,7 @@
+/**
+ * User API Service
+ */
+
 import { serverClient } from './api'
 import type {
   UserProfileResponse,
@@ -9,29 +13,86 @@ import type {
   TeamRoleResponse,
 } from '@/types/user'
 
-// 5 years in seconds (5 * 365 * 24 * 60 * 60) - default TTL for API tokens.
+/** Default TTL for API tokens: 5 years in seconds (5 * 365 * 24 * 60 * 60). */
 const DEFAULT_API_TOKEN_TTL_SECONDS = 157680000
 
-// Profile Management
+/** Profile Management */
+
+/**
+ * Retrieves the current user's profile information.
+ * @returns Promise resolving to user profile data including firstname, lastname, email and other user details.
+ * @throws {ApiError} When not authenticated (401)
+ * 
+ * @example
+ * getUserProfile()
+ */
 export const getUserProfile = () =>
   serverClient.get<UserProfileResponse>('/user/profile')
 
+/**
+ * Updates the current user's profile information.
+ * @param data - Profile fields to update (firstname, lastname, email, etc.)
+ * @returns Promise resolving to success message
+ * @throws {ApiError} When validation fails (400) or not authenticated (401)
+ * 
+ * @example
+ * updateUserProfile({ firstname: 'John', lastname: 'Doe', email: 'john.doe@example.com' })
+ */
 export const updateUserProfile = (data: UpdateProfilePayload) =>
   serverClient.put<{ message: string }>('/user/profile', data)
 
+/**
+ * Updates the current user's avatar image.
+ * @param data - Avatar data including base64-encoded image
+ * @returns Promise resolving to the new avatar URL
+ * @throws {ApiError} When image format is invalid (400)
+ * 
+ * @example
+ * updateUserAvatar({ userAvatar: 'base64-encoded-image' })
+ */
 export const updateUserAvatar = (data: UpdateAvatarPayload) =>
   serverClient.post<{ data: string }>('/user/set-user-avatar', data)
 
-// API Tokens (Developer Tools)
+/** API Tokens (Developer Tools) */
+
+/**
+ * Retrieves all API tokens for the current user.
+ * @returns Promise resolving to list of API tokens with metadata
+ * @throws {ApiError} When not authenticated (401)
+ * 
+ * @example
+ * getAPITokens()
+ */
 export const getAPITokens = () =>
   serverClient.get<APITokensResponse>('/user/get-dev-tokens')
 
+/**
+ * Creates a new API token for developer tools access.
+ * @param label - Display name for the token (e.g., 'Production API Key')
+ * @param ttl - Time-to-live in seconds (default: 5 years)
+ * @returns Promise resolving to the created token (only shown once)
+ * @throws {ApiError} When not authenticated (401)
+ * 
+ * @example
+ * createAPIToken('Production API Key')
+ */
 export const createAPIToken = (label: string, ttl: number = DEFAULT_API_TOKEN_TTL_SECONDS) =>
   serverClient.post<APITokenResponse>('/user/generate-dev-token', {
     label,
     ttl,
   } as CreateAPITokenPayload)
 
-// Team/Role (needed for org initialization)
+/** Team/Role */
+
+/**
+ * Retrieves the user's role information for a specific team.
+ * Used during organization initialization to verify permissions.
+ * @param teamId - Team ID to get role for
+ * @returns Promise resolving to team role information
+ * @throws {ApiError} When team not found (404) or no access (403)
+ * 
+ * @example
+ * getTeamRoleId('123')
+ */
 export const getTeamRoleId = (teamId: string) =>
   serverClient.get<TeamRoleResponse>(`/iam/team/get-team-role-by-id/${teamId}`)