fix: resolve all 610 ESLint errors across the codebase

app/api/accounts/[id]/route.ts

@@ -23,7 +23,8 @@ export async function OPTIONS() {
  * - id (required): The unique identifier of the account (UUID)
  *
  * @param request - The request object
- * @param params - Route params containing the account ID
+ * @param root1 - Destructured route context
+ * @param root1.params - Promise resolving to route params containing the account ID
  * @returns A NextResponse with account data
  */
 export async function GET(request: NextRequest, { params }: { params: Promise<{ id: string }> }) {

app/api/admins/coding/pr/route.ts

@@ -10,13 +10,18 @@ import { getPrStatusHandler } from "@/lib/admins/pr/getPrStatusHandler";
  * Uses the GitHub REST API to check each PR's state.
  * Requires admin authentication.
  *
- * @param request
+ * @param request - The incoming request with pull_requests query params
+ * @returns A NextResponse with the PR status for each provided URL
  */
 export async function GET(request: NextRequest): Promise<NextResponse> {
   return getPrStatusHandler(request);
 }
 
-/** CORS preflight handler. */
+/**
+ * CORS preflight handler.
+ *
+ * @returns A NextResponse with CORS headers allowing cross-origin access
+ */
 export async function OPTIONS(): Promise<NextResponse> {
   return new NextResponse(null, { status: 204, headers: getCorsHeaders() });
 }

app/api/admins/coding/slack/route.ts

@@ -9,12 +9,19 @@ import { getSlackTagsHandler } from "@/lib/admins/slack/getSlackTagsHandler";
  * Pulls directly from the Slack API as the source of truth.
  * Supports period filtering: all (default), daily, weekly, monthly.
  * Requires admin authentication.
+ *
+ * @param request - The incoming request with optional period query param
+ * @returns A NextResponse with Slack tagging analytics data
  */
 export async function GET(request: NextRequest): Promise<NextResponse> {
   return getSlackTagsHandler(request);
 }
 
-/** CORS preflight handler. */
+/**
+ * CORS preflight handler.
+ *
+ * @returns A NextResponse with CORS headers allowing cross-origin access
+ */
 export async function OPTIONS(): Promise<NextResponse> {
   return new NextResponse(null, { status: 204, headers: getCorsHeaders() });
 }

app/api/admins/content/slack/route.ts

@@ -10,13 +10,18 @@ import { getContentSlackTagsHandler } from "@/lib/admins/content/getContentSlack
  * Supports period filtering: all (default), daily, weekly, monthly.
  * Requires admin authentication.
  *
- * @param request
+ * @param request - The incoming request with optional period query param
+ * @returns A NextResponse with Slack tagging analytics data
  */
 export async function GET(request: NextRequest): Promise<NextResponse> {
   return getContentSlackTagsHandler(request);
 }
 
-/** CORS preflight handler. */
+/**
+ * CORS preflight handler.
+ *
+ * @returns A NextResponse with CORS headers allowing cross-origin access
+ */
 export async function OPTIONS(): Promise<NextResponse> {
   return new NextResponse(null, { status: 204, headers: getCorsHeaders() });
 }

app/api/admins/privy/route.ts

@@ -8,11 +8,19 @@ import { getPrivyLoginsHandler } from "@/lib/admins/privy/getPrivyLoginsHandler"
  * Returns Privy login statistics for the requested time period.
  * Supports daily (last 24h), weekly (last 7 days), and monthly (last 30 days) periods.
  * Requires admin authentication.
+ *
+ * @param request - The incoming request with optional period query param
+ * @returns A NextResponse with Privy login statistics
  */
 export async function GET(request: NextRequest): Promise<NextResponse> {
   return getPrivyLoginsHandler(request);
 }
 
+/**
+ * CORS preflight handler.
+ *
+ * @returns A NextResponse with CORS headers allowing cross-origin access
+ */
 export async function OPTIONS(): Promise<NextResponse> {
   return new NextResponse(null, { status: 204, headers: getCorsHeaders() });
 }

app/api/coding-agent/callback/route.ts

@@ -9,6 +9,7 @@ import { handleCodingAgentCallback } from "@/lib/coding-agent/handleCodingAgentC
  * Receives task results and posts them back to the Slack thread.
  *
  * @param request - The incoming callback request
+ * @returns A NextResponse indicating success or failure of the callback processing
  */
 export async function POST(request: NextRequest) {
   await codingAgentBot.initialize();

app/api/coding-agent/github/route.ts

@@ -8,6 +8,7 @@ import { handleGitHubWebhook } from "@/lib/coding-agent/handleGitHubWebhook";
  * Receives issue_comment events and triggers update-pr when the bot is mentioned.
  *
  * @param request - The incoming GitHub webhook request
+ * @returns A NextResponse indicating whether the webhook was processed
  */
 export async function POST(request: NextRequest) {
   return handleGitHubWebhook(request);

app/api/connectors/route.ts

@@ -7,6 +7,8 @@ import { disconnectConnectorHandler } from "@/lib/composio/connectors/disconnect
 
 /**
  * OPTIONS handler for CORS preflight requests.
+ *
+ * @returns A NextResponse with CORS headers allowing cross-origin access
  */
 export async function OPTIONS() {
   return new NextResponse(null, {
@@ -25,7 +27,7 @@ export async function OPTIONS() {
  *
  * Authentication: x-api-key OR Authorization Bearer token required.
  *
- * @param request
+ * @param request - The incoming request with optional account_id query param
  * @returns List of connectors with connection status
  */
 export async function GET(request: NextRequest) {
@@ -44,7 +46,7 @@ export async function GET(request: NextRequest) {
  * - callback_url: Optional custom callback URL after OAuth
  * - account_id: Optional account ID for account-specific connections
  *
- * @param request
+ * @param request - The incoming request with connector slug and optional callback_url in the body
  * @returns The redirect URL for OAuth authorization
  */
 export async function POST(request: NextRequest) {
@@ -62,7 +64,8 @@ export async function POST(request: NextRequest) {
  *
  * Authentication: x-api-key OR Authorization Bearer token required.
  *
- * @param request
+ * @param request - The incoming request with connected_account_id in the body
+ * @returns A NextResponse confirming the connector was disconnected
  */
 export async function DELETE(request: NextRequest) {
   return disconnectConnectorHandler(request);

app/api/songs/analyze/presets/route.ts

@@ -28,6 +28,7 @@ export async function OPTIONS() {
  * - status: "success"
  * - presets: Array of { name, label, description, requiresAudio, responseFormat }
  *
+ * @param request - The incoming request with authentication headers
  * @returns A NextResponse with the list of available presets
  */
 export async function GET(request: NextRequest): Promise<NextResponse> {

app/api/transcribe/route.ts

@@ -2,6 +2,15 @@ import { NextRequest, NextResponse } from "next/server";
 import { processAudioTranscription } from "@/lib/transcribe/processAudioTranscription";
 import { formatTranscriptionError } from "@/lib/transcribe/types";
 
+/**
+ * POST /api/transcribe
+ *
+ * Fetches an audio file from the provided URL, transcribes it using OpenAI Whisper,
+ * and saves both the audio and transcript as file records linked to the artist account.
+ *
+ * @param req - The incoming request containing audio_url, account_id, artist_account_id, title, and include_timestamps
+ * @returns A NextResponse with the created audio file record, transcript file record, and transcription text
+ */
 export async function POST(req: NextRequest) {
   try {
     const body = await req.json();

lib/accounts/validateOverrideAccountId.ts

@@ -18,11 +18,9 @@ export type ValidateOverrideAccountIdResult = {
  * Used when an org API key wants to create resources on behalf of another account.
  * Checks that the API key belongs to an org with access to the target account.
  *
- * @param params.apiKey - The x-api-key header value
- * @param params.targetAccountId - The accountId to override to
- * @param root0
- * @param root0.apiKey
- * @param root0.targetAccountId
+ * @param root0 - The validation parameters
+ * @param root0.apiKey - The x-api-key header value
+ * @param root0.targetAccountId - The accountId to override to
  * @returns The validated accountId or a NextResponse error
  */
 export async function validateOverrideAccountId({

lib/admins/content/__tests__/getContentSlackTagsHandler.test.ts

@@ -40,8 +40,10 @@ const mockTags = [
 ];
 
 /**
+ * Creates a mock NextRequest for the content Slack tags endpoint with the given period.
  *
- * @param period
+ * @param period - The time period query parameter (e.g., "all", "daily", "weekly", "monthly").
+ * @returns A NextRequest instance targeting the content Slack tags endpoint.
  */
 function makeRequest(period = "all") {
   return new NextRequest(`https://example.com/api/admins/content/slack?period=${period}`);

lib/admins/content/extractVideoLinks.ts

@@ -6,9 +6,10 @@ const VIDEO_URL_PATTERN = /https?:\/\/[^\s>|]+/g;
  * Extracts video/media URLs from a Slack bot reply message's text, attachments, and blocks.
  * Filters for common video hosting patterns.
  *
- * @param text
- * @param attachments
- * @param blocks
+ * @param text - The plain text body of the Slack message to scan for URLs.
+ * @param attachments - Optional Slack message attachments whose action button URLs are also scanned.
+ * @param blocks - Optional Slack Block Kit blocks whose element URLs are also scanned.
+ * @returns A deduplicated array of video/media URLs found across all message surfaces.
  */
 export function extractVideoLinks(
   text: string,

lib/admins/content/fetchThreadVideoLinks.ts

@@ -20,9 +20,10 @@ interface ConversationsRepliesResponse {
  * Fetches bot replies in a Slack thread and returns any video/media URLs found.
  * Extracts URLs from message text, attachment action buttons, and Block Kit blocks.
  *
- * @param token
- * @param channel
- * @param threadTs
+ * @param token - Slack bot token used to authenticate the conversations.replies API call.
+ * @param channel - Slack channel ID containing the thread.
+ * @param threadTs - Timestamp of the parent message that identifies the thread.
+ * @returns A deduplicated array of video/media URLs posted by bots in the thread.
  */
 export async function fetchThreadVideoLinks(
   token: string,

lib/admins/emails/__tests__/validateGetAdminEmailsQuery.test.ts

@@ -12,6 +12,12 @@ vi.mock("@/lib/admins/validateAdminAuth", () => ({
   validateAdminAuth: vi.fn(),
 }));
 
+/**
+ * Creates a minimal mock NextRequest from a URL string for use in unit tests.
+ *
+ * @param url - The full URL string to construct the mock request from.
+ * @returns A mock NextRequest with url and nextUrl populated.
+ */
 function createMockRequest(url: string): NextRequest {
   return {
     url,

lib/admins/pr/__tests__/getPrMergedStatusHandler.test.ts

@@ -19,6 +19,12 @@ vi.mock("@/lib/github/fetchGithubPrStatus", () => ({
 const PR_URL_1 = "https://github.com/recoupable/api/pull/42";
 const PR_URL_2 = "https://github.com/recoupable/chat/pull/100";
 
+/**
+ * Creates a NextRequest targeting the PR status endpoint with the given PR URLs as query params.
+ *
+ * @param urls - Array of GitHub pull request URLs to include as pull_requests query parameters.
+ * @returns A NextRequest with all provided URLs appended as repeated pull_requests params.
+ */
 function makeRequest(urls: string[] = [PR_URL_1]) {
   const params = new URLSearchParams();
   urls.forEach(url => params.append("pull_requests", url));

lib/admins/pr/getPrStatusHandler.ts

@@ -10,6 +10,9 @@ import { fetchGithubPrStatus } from "@/lib/github/fetchGithubPrStatus";
  * Uses the GitHub REST API to check each PR's state.
  *
  * Requires admin authentication.
+ *
+ * @param request - The incoming Next.js request containing pull_requests query parameters.
+ * @returns A NextResponse with each PR URL mapped to its current status, or an error response.
  */
 export async function getPrStatusHandler(request: NextRequest): Promise<NextResponse> {
   try {

lib/admins/privy/__tests__/getPrivyLoginsHandler.test.ts

@@ -49,8 +49,10 @@ const mockLogins = [
 ];
 
 /**
+ * Creates a NextRequest targeting the Privy logins endpoint with the given period query param.
  *
- * @param period
+ * @param period - The time period to filter logins by (e.g., "daily", "weekly", "monthly", "all").
+ * @returns A NextRequest instance for the Privy logins admin endpoint.
  */
 function makeRequest(period = "daily") {
   return new NextRequest(`https://example.com/api/admins/privy?period=${period}`);

lib/admins/privy/__tests__/validateGetPrivyLoginsQuery.test.ts

@@ -15,8 +15,10 @@ vi.mock("@/lib/admins/validateAdminAuth", () => ({
 const mockAuth = { accountId: "test-account", orgId: null, authToken: "token" };
 
 /**
+ * Creates a NextRequest targeting the Privy logins query endpoint, optionally with a period param.
  *
- * @param period
+ * @param period - Optional time period value to include as a query parameter.
+ * @returns A NextRequest for the Privy logins admin endpoint with or without a period filter.
  */
 function makeRequest(period?: string) {
   const url = period

lib/admins/privy/countNewAccounts.ts

@@ -5,6 +5,10 @@ import { getCutoffMs } from "./getCutoffMs";
 
 /**
  * Counts how many users in the list were created within the cutoff period.
+ *
+ * @param users - Array of Privy user objects to evaluate.
+ * @param period - The time window to check against (e.g., "daily", "weekly", "monthly", or "all").
+ * @returns The number of users whose created_at timestamp falls within the given period.
  */
 export function countNewAccounts(users: User[], period: PrivyLoginsPeriod): number {
   const cutoffMs = getCutoffMs(period);

lib/admins/privy/fetchPrivyLogins.ts

@@ -20,6 +20,14 @@ export type FetchPrivyLoginsResult = {
   totalPrivyUsers: number;
 };
 
+/**
+ * Fetches Privy users active or created within the given period via the Privy Management API.
+ * Paginates through all users and collects those whose created_at or latest_verified_at
+ * falls within the time window determined by the period.
+ *
+ * @param period - The time window to filter users by ("daily", "weekly", "monthly", or "all").
+ * @returns An object containing the matching users sorted by created_at descending and the total Privy user count.
+ */
 export async function fetchPrivyLogins(period: PrivyLoginsPeriod): Promise<FetchPrivyLoginsResult> {
   const isAll = period === "all";
   const cutoffMs = getCutoffMs(period);

lib/admins/privy/getCutoffMs.ts

@@ -5,6 +5,9 @@ import { PERIOD_DAYS } from "./periodDays";
  * Returns the cutoff timestamp in milliseconds for a given period.
  * Uses midnight UTC calendar day boundaries to match Privy dashboard behavior.
  * Returns 0 for "all" (no cutoff).
+ *
+ * @param period - The time window ("daily", "weekly", "monthly", or "all") to compute a cutoff for.
+ * @returns Milliseconds timestamp representing the start of the period, or 0 for "all".
  */
 export function getCutoffMs(period: PrivyLoginsPeriod): number {
   if (period === "all") return 0;

lib/admins/privy/getLatestVerifiedAt.ts

@@ -4,6 +4,9 @@ import type { User } from "@privy-io/node";
 /**
  * Returns the most recent latest_verified_at (in ms) across all linked_accounts for a Privy user.
  * Returns null if no linked account has a latest_verified_at.
+ *
+ * @param user - The Privy user object whose linked accounts are inspected.
+ * @returns The most recent verified-at timestamp in milliseconds, or null if none exists.
  */
 export function getLatestVerifiedAt(user: User): number | null {
   const linkedAccounts = user.linked_accounts;

lib/admins/privy/toMs.ts

@@ -1,6 +1,9 @@
 /**
  * Normalizes a Privy timestamp to milliseconds.
  * Privy docs say milliseconds but examples show seconds (10 digits).
+ *
+ * @param timestamp - A Privy timestamp that may be in either seconds or milliseconds.
+ * @returns The timestamp normalized to milliseconds.
  */
 export function toMs(timestamp: number): number {
   return timestamp > 1e12 ? timestamp : timestamp * 1000;

lib/admins/slack/__tests__/createSlackTagsHandler.test.ts

@@ -18,8 +18,10 @@ const handler = createSlackTagsHandler({
 });
 
 /**
+ * Creates a NextRequest targeting the coding Slack tags endpoint with the given period query param.
  *
- * @param period
+ * @param period - The time period to filter tags by (e.g., "all", "daily", "weekly", "monthly").
+ * @returns A NextRequest instance for the coding Slack tags admin endpoint.
  */
 function makeRequest(period = "all") {
   return new NextRequest(`https://example.com/api/admins/coding/slack?period=${period}`);

lib/admins/slack/__tests__/getSlackTagsHandler.test.ts

@@ -40,8 +40,10 @@ const mockTags = [
 ];
 
 /**
+ * Creates a NextRequest targeting the Slack tags endpoint with the given period query param.
  *
- * @param period
+ * @param period - The time period to filter tags by (e.g., "all", "daily", "weekly", "monthly").
+ * @returns A NextRequest instance for the Slack tags admin endpoint.
  */
 function makeRequest(period = "all") {
   return new NextRequest(`https://example.com/api/admins/coding/slack?period=${period}`);

lib/admins/slack/__tests__/validateGetSlackTagsQuery.test.ts

@@ -14,8 +14,10 @@ vi.mock("@/lib/admins/validateAdminAuth", () => ({
 const mockAuth = { accountId: "test-account", orgId: null, authToken: "token" };
 
 /**
+ * Creates a NextRequest targeting the Slack tags query endpoint, optionally with a period param.
  *
- * @param period
+ * @param period - Optional time period value to include as a query parameter.
+ * @returns A NextRequest for the coding Slack tags admin endpoint with or without a period filter.
  */
 function makeRequest(period?: string) {
   const url = period

lib/admins/slack/createSlackTagsHandler.ts

@@ -15,7 +15,10 @@ interface SlackTagsHandlerConfig {
  * Factory that creates a handler for admin slack tags endpoints.
  * Parameterized by validation, fetching, and response field naming.
  *
- * @param config
+ * @param config - Configuration object specifying the validate function, fetchMentions function,
+ *   and the response field names used to expose per-tag response counts and totals.
+ * @returns An async request handler function that validates the request, fetches mentions,
+ *   and returns aggregated tag statistics as a JSON response.
  */
 export function createSlackTagsHandler(
   config: SlackTagsHandlerConfig,