clean: Fix React hooks violation in onboarding

[elie222]

User description

This PR fixes a 'Rendered more hooks than during the previous render' error on the clean onboarding route by adding a Suspense boundary and using a unique key for each step.

• Added Suspense with key={step} to isolate step components
• Awaited searchParams earlier to avoid potential hydration issues
• Improved step parsing robustness

---

Generated description

Below is a concise technical summary of the changes proposed in this PR:

graph LR
handleError_("handleError"):::modified
isAiQuotaExceededError_("isAiQuotaExceededError"):::added
ErrorType_("ErrorType"):::modified
isKnownApiError_("isKnownApiError"):::modified
checkCommonErrors_("checkCommonErrors"):::modified
updateUserSettingsNotifications_settings_action_list_("updateUserSettingsNotifications (settings action list)"):::modified
isAnthropicInsufficientBalanceError_("isAnthropicInsufficientBalanceError"):::modified
handleError_ -- "Now detects AI quota errors and notifies with AI_QUOTA_ERROR." --> isAiQuotaExceededError_
handleError_ -- "Uses new ErrorType.AI_QUOTA_ERROR for rate-limit notifications." --> ErrorType_
isKnownApiError_ -- "Treats AI quota RetryError instances as known API errors." --> isAiQuotaExceededError_
checkCommonErrors_ -- "Recognizes AI quota errors and returns standardized 429 response." --> isAiQuotaExceededError_
updateUserSettingsNotifications_settings_action_list_ -- "Includes AI_QUOTA_ERROR in settings notification action list." --> ErrorType_
isKnownApiError_ -- "Continues to detect Anthropic insufficient balance as known error." --> isAnthropicInsufficientBalanceError_
classDef added stroke:#15AA7A
classDef removed stroke:#CD5270
classDef modified stroke:#EDAC4C
linkStyle default stroke:#CBD5E1,font-size:13px

Loading

Resolves a React hooks violation in the clean onboarding flow by introducing a Suspense boundary with a unique key for each step, and refactors AI quota error handling to be more generic across different AI providers.

Topic	Details
Fix Onboarding Hooks	Fixes a React hooks violation in the clean onboarding route by adding a Suspense boundary with a unique key for each step and awaiting searchParams earlier in page.tsx. Modified files (1) apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx Latest Contributors(2) User Commit Date elie222 logger December 18, 2025 mojkakec12345@gmail.com fix-all-comments July 11, 2025
Refine AI Quota Errors	Refactors AI quota error handling by renaming OPENAI_RETRY_ERROR to AI_QUOTA_ERROR and expanding the detection logic for rate limiting across various AI providers. Modified files (4) apps/web/utils/error-messages/index.ts apps/web/utils/error.ts apps/web/utils/llms/index.ts apps/web/utils/actions/settings.ts Latest Contributors(2) User Commit Date elie222 sentry-userid January 04, 2026 eduardoleliss@gmail.com Digest-email-fixes July 07, 2025

This pull request is reviewed by Baz. Review like a pro on (Baz).

Summary by CodeRabbit

Release Notes

• New Features

  • Enhanced detection of AI rate limit and quota exceeded errors with improved accuracy across multiple error indicators.

• Bug Fixes

  • Improved loading experience on the onboarding page with better state management.

• Updates

  • Refined error messaging for rate-limit scenarios with clearer terminology.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
inbox-zero	Ready	Preview	Jan 5, 2026 9:25pm

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR replaces OpenAI-specific retry error handling with a generic AI quota error detection mechanism. Changes span error type definitions, error message mappings, detection logic, and error handling in settings and LLM utilities, alongside minor updates to the onboarding page for Suspense support.

Changes

Cohort / File(s)	Summary
Error Infrastructure apps/web/utils/error-messages/index.ts, apps/web/utils/error.ts	Replaced OPENAI_RETRY_ERROR with AI_QUOTA_ERROR in error type registry and updated UI labels from "API Quota Exceeded" to "AI Rate Limited". Added new isAiQuotaExceededError() function that detects multiple quota/rate-limit phrases ("exceeded your current quota", "rate limit reached", etc.) instead of OpenAI-specific retry detection.
Error Handling in Application Logic apps/web/utils/actions/settings.ts, apps/web/utils/llms/index.ts	Updated error type references and error detection calls from isOpenAIRetryError() to isAiQuotaExceededError() in AI settings updates and LLM error handling paths. Changed error notifications to use AI_QUOTA_ERROR and updated messages to generic AI provider terminology.
UI Component Updates apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx	Added React Suspense boundary with loading fallback keyed to current step. Consolidated single searchParams retrieval at top of component and replaced conditional step parsing with robust Number.parseInt() fallback to CleanStep.INTRO.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• Fallback to Haiku if service unavailable #279: Modifies the same AI error-handling codepaths (apps/web/utils/error.ts and apps/web/utils/llms/index.ts) by adding service-unavailable detection and implementing backup-model retry flow, complementing this PR's shift to generic quota error detection.

Poem

🐰 Hops through the code with glee so bright,
SwapAI errors left and right,
From OpenAI's retry dance so keen,
To quota checks—a fresh, clean scene!
Suspense now wraps the loading way,
A refactor hops to save the day! ✨

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title 'clean: Fix React hooks violation in onboarding' accurately describes the primary change—adding a React Suspense boundary to fix a hooks violation on the clean onboarding route. However, the PR also includes substantial unrelated changes generalizing AI quota error handling across multiple utility files, which are not reflected in the title.	The title should either be updated to reflect all significant changes (e.g., 'clean: Fix React hooks and generalize AI quota error handling') or the unrelated AI quota refactoring should be moved to a separate PR to keep the scope focused.
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b23e08f and d41b173.

📒 Files selected for processing (5)

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx
• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

🧰 Additional context used

📓 Path-based instructions (23)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/data-fetching.mdc)

**/*.{ts,tsx}: For API GET requests to server, use the swr package
Use result?.serverError with toastError from @/components/Toast for error handling in async operations

**/*.{ts,tsx}: Use wrapper functions for Gmail message operations (get, list, batch, etc.) from @/utils/gmail/message.ts instead of direct API calls
Use wrapper functions for Gmail thread operations from @/utils/gmail/thread.ts instead of direct API calls
Use wrapper functions for Gmail label operations from @/utils/gmail/label.ts instead of direct API calls

**/*.{ts,tsx}: For early access feature flags, create hooks using the naming convention use[FeatureName]Enabled that return a boolean from useFeatureFlagEnabled("flag-key")
For A/B test variant flags, create hooks using the naming convention use[FeatureName]Variant that define variant types, use useFeatureFlagVariantKey() with type casting, and provide a default "control" fallback
Use kebab-case for PostHog feature flag keys (e.g., inbox-cleaner, pricing-options-2)
Always define types for A/B test variant flags (e.g., type PricingVariant = "control" | "variant-a" | "variant-b") and provide type safety through type casting

**/*.{ts,tsx}: Don't use primitive type aliases or misleading types
Don't use empty type parameters in type aliases and interfaces
Don't use this and super in static contexts
Don't use any or unknown as type constraints
Don't use the TypeScript directive @ts-ignore
Don't use TypeScript enums
Don't export imported variables
Don't add type annotations to variables, parameters, and class properties that are initialized with literal expressions
Don't use TypeScript namespaces
Don't use non-null assertions with the ! postfix operator
Don't use parameter properties in class constructors
Don't use user-defined types
Use as const instead of literal types and type annotations
Use either T[] or Array<T> consistently
Initialize each enum member value explicitly
Use export type for types
Use `impo...

Files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx
• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

apps/web/app/(app)/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/page-structure.mdc)

apps/web/app/(app)/**/*.{ts,tsx}: Components for the page are either put in page.tsx, or in the apps/web/app/(app)/PAGE_NAME folder
If we're in a deeply nested component we will use swr to fetch via API
If you need to use onClick in a component, that component is a client component and file must start with use client

Files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (.cursor/rules/prisma-enum-imports.mdc)

Always import Prisma enums from @/generated/prisma/enums instead of @/generated/prisma/client to avoid Next.js bundling errors in client components

Import Prisma using the project's centralized utility: import prisma from '@/utils/prisma'

Files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx
• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

apps/web/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/project-structure.mdc)

Import specific lodash functions rather than entire lodash library to minimize bundle size (e.g., import groupBy from 'lodash/groupBy')

apps/web/**/*.{ts,tsx}: Use TypeScript with strict null checks
Do not export types/interfaces that are only used within the same file. Export later if needed

Files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx
• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

**/*.{tsx,ts}

📄 CodeRabbit inference engine (.cursor/rules/ui-components.mdc)

**/*.{tsx,ts}: Use Shadcn UI and Tailwind for components and styling
Use next/image package for images
For API GET requests to server, use the swr package with hooks like useSWR to fetch data
For text inputs, use the Input component with registerProps for form integration and error handling

Files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx
• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

**/*.{tsx,ts,css}

📄 CodeRabbit inference engine (.cursor/rules/ui-components.mdc)

Implement responsive design with Tailwind CSS using a mobile-first approach

Files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx
• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

**/*.tsx

📄 CodeRabbit inference engine (.cursor/rules/ui-components.mdc)

**/*.tsx: Use the LoadingContent component to handle loading states instead of manual loading state management
For text areas, use the Input component with type='text', autosizeTextarea prop set to true, and registerProps for form integration

Files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

**/*.{js,jsx,ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/ultracite.mdc)

**/*.{js,jsx,ts,tsx}: Don't use accessKey attribute on any HTML element
Don't set aria-hidden="true" on focusable elements
Don't add ARIA roles, states, and properties to elements that don't support them
Don't use distracting elements like <marquee> or <blink>
Only use the scope prop on <th> elements
Don't assign non-interactive ARIA roles to interactive HTML elements
Make sure label elements have text content and are associated with an input
Don't assign interactive ARIA roles to non-interactive HTML elements
Don't assign tabIndex to non-interactive HTML elements
Don't use positive integers for tabIndex property
Don't include "image", "picture", or "photo" in img alt prop
Don't use explicit role property that's the same as the implicit/default role
Make static elements with click handlers use a valid role attribute
Always include a title element for SVG elements
Give all elements requiring alt text meaningful information for screen readers
Make sure anchors have content that's accessible to screen readers
Assign tabIndex to non-interactive HTML elements with aria-activedescendant
Include all required ARIA attributes for elements with ARIA roles
Make sure ARIA properties are valid for the element's supported roles
Always include a type attribute for button elements
Make elements with interactive roles and handlers focusable
Give heading elements content that's accessible to screen readers (not hidden with aria-hidden)
Always include a lang attribute on the html element
Always include a title attribute for iframe elements
Accompany onClick with at least one of: onKeyUp, onKeyDown, or onKeyPress
Accompany onMouseOver/onMouseOut with onFocus/onBlur
Include caption tracks for audio and video elements
Use semantic elements instead of role attributes in JSX
Make sure all anchors are valid and navigable
Ensure all ARIA properties (aria-*) are valid
Use valid, non-abstract ARIA roles for elements with ARIA roles
Use valid AR...

Files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx
• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

**/*.{jsx,tsx}

📄 CodeRabbit inference engine (.cursor/rules/ultracite.mdc)

**/*.{jsx,tsx}: Don't use unnecessary fragments
Don't pass children as props
Don't use the return value of React.render
Make sure all dependencies are correctly specified in React hooks
Make sure all React hooks are called from the top level of component functions
Don't forget key props in iterators and collection literals
Don't define React components inside other components
Don't use event handlers on non-interactive elements
Don't assign to React component props
Don't use both children and dangerouslySetInnerHTML props on the same element
Don't use dangerous JSX props
Don't use Array index in keys
Don't insert comments as text nodes
Don't assign JSX properties multiple times
Don't add extra closing tags for components without children
Use <>...</> instead of <Fragment>...</Fragment>
Watch out for possible "wrong" semicolons inside JSX elements
Make sure void (self-closing) elements don't have children
Don't use target="_blank" without rel="noopener"
Don't use <img> elements in Next.js projects
Don't use <head> elements in Next.js projects

Files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

!(pages/_document).{jsx,tsx}

📄 CodeRabbit inference engine (.cursor/rules/ultracite.mdc)

Don't use the next/head module in pages/_document.js on Next.js projects

Files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx
• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

**/*.{js,ts,jsx,tsx}

📄 CodeRabbit inference engine (.cursor/rules/utilities.mdc)

**/*.{js,ts,jsx,tsx}: Use lodash utilities for common operations (arrays, objects, strings)
Import specific lodash functions to minimize bundle size (e.g., import groupBy from 'lodash/groupBy')

Files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx
• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

apps/web/**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (apps/web/CLAUDE.md)

apps/web/**/*.{ts,tsx,js,jsx}: Use @/ path aliases for imports from project root
Prefer self-documenting code over comments; use descriptive variable and function names instead of explaining intent with comments
Add helper functions to the bottom of files, not the top
All imports go at the top of files, no mid-file dynamic imports

Files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx
• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

apps/web/app/**/*.{ts,tsx}

📄 CodeRabbit inference engine (apps/web/CLAUDE.md)

Follow NextJS app router structure with (app) directory

Files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

apps/web/**/*.{tsx,jsx}

📄 CodeRabbit inference engine (apps/web/CLAUDE.md)

apps/web/**/*.{tsx,jsx}: Follow tailwindcss patterns with prettier-plugin-tailwindcss for class sorting
Prefer functional components with hooks in React
Use shadcn/ui components when available
Ensure responsive design with mobile-first approach in components
Follow consistent naming conventions using PascalCase for components
Use LoadingContent component for async data with loading and error states
Use React Hook Form with Zod validation for form handling
Use result?.serverError with toastError and toastSuccess for error handling in forms

Files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

apps/web/**/*.{ts,tsx,js,jsx,json,css}

📄 CodeRabbit inference engine (apps/web/CLAUDE.md)

Format code with Prettier

Files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx
• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

apps/web/utils/actions/*.ts

📄 CodeRabbit inference engine (.cursor/rules/fullstack-workflow.mdc)

apps/web/utils/actions/*.ts: Use next-safe-action with Zod schemas for all server actions (create/update/delete mutations), storing validation schemas in apps/web/utils/actions/*.validation.ts
Server actions should use 'use server' directive and automatically receive authentication context (emailAccountId) from the actionClient

apps/web/utils/actions/*.ts: Create corresponding server action implementation files using the naming convention apps/web/utils/actions/NAME.ts with 'use server' directive
Use 'use server' directive at the top of server action implementation files
Implement all server actions using the next-safe-action library with actionClient, actionClientUser, or adminActionClient for type safety and validation
Use actionClientUser when only authenticated user context (userId) is needed
Use actionClient when both authenticated user context and a specific emailAccountId are needed, with emailAccountId bound when calling from the client
Use adminActionClient for actions restricted to admin users
Add metadata with a meaningful action name using .metadata({ name: "actionName" }) for Sentry instrumentation and monitoring
Use .schema() method with Zod validation schemas from corresponding .validation.ts files in next-safe-action configuration
Access context (userId, emailAccountId, etc.) via the ctx object parameter in the .action() handler
Use revalidatePath or revalidateTag from 'next/cache' within server action handlers when mutations modify data displayed elsewhere

Files:

• apps/web/utils/actions/settings.ts

apps/web/utils/actions/**/*.ts

📄 CodeRabbit inference engine (.cursor/rules/project-structure.mdc)

apps/web/utils/actions/**/*.ts: Server actions must be located in apps/web/utils/actions folder
Server action files must start with use server directive

apps/web/utils/actions/**/*.ts: Use proper error handling with try/catch blocks
Use next-safe-action with Zod schemas for server actions to handle mutations
Use revalidatePath in server actions for cache invalidation after mutations

Files:

• apps/web/utils/actions/settings.ts

**/*.ts

📄 CodeRabbit inference engine (.cursor/rules/security.mdc)

**/*.ts: ALL database queries MUST be scoped to the authenticated user/account by including user/account filtering in WHERE clauses to prevent unauthorized data access
Always validate that resources belong to the authenticated user before performing operations, using ownership checks in WHERE clauses or relationships
Always validate all input parameters for type, format, and length before using them in database queries
Use SafeError for error responses to prevent information disclosure. Generic error messages should not reveal internal IDs, logic, or resource ownership details
Only return necessary fields in API responses using Prisma's select option. Never expose sensitive data such as password hashes, private keys, or system flags
Prevent Insecure Direct Object References (IDOR) by validating resource ownership before operations. All findUnique/findFirst calls MUST include ownership filters
Prevent mass assignment vulnerabilities by explicitly whitelisting allowed fields in update operations instead of accepting all user-provided data
Prevent privilege escalation by never allowing users to modify system fields, ownership fields, or admin-only attributes through user input
All findMany queries MUST be scoped to the user's data by including appropriate WHERE filters to prevent returning data from other users
Use Prisma relationships for access control by leveraging nested where clauses (e.g., emailAccount: { id: emailAccountId }) to validate ownership

Files:

• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

**/{utils,helpers,lib}/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/logging.mdc)

Logger should be passed as a parameter to helper functions instead of creating their own logger instances

Files:

• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

apps/web/utils/actions/**/*.{ts,tsx}

📄 CodeRabbit inference engine (apps/web/CLAUDE.md)

Infer types from Zod schemas using z.infer<typeof schema> instead of duplicating as separate interfaces

Files:

• apps/web/utils/actions/settings.ts

apps/web/**/*.{example,ts,json}

📄 CodeRabbit inference engine (apps/web/CLAUDE.md)

Add environment variables to .env.example, env.ts, and turbo.json

Files:

• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

apps/web/{utils/ai,utils/llms,__tests__}/**/*.ts

📄 CodeRabbit inference engine (.cursor/rules/llm.mdc)

LLM-related code must be organized in specific directories: apps/web/utils/ai/ for main implementations, apps/web/utils/llms/ for core utilities and configurations, and apps/web/__tests__/ for LLM-specific tests

Files:

• apps/web/utils/llms/index.ts

apps/web/utils/llms/{index,model}.ts

📄 CodeRabbit inference engine (.cursor/rules/llm.mdc)

Core LLM functionality must be defined in utils/llms/index.ts, model definitions and configurations in utils/llms/model.ts, and usage tracking in utils/usage.ts

Files:

• apps/web/utils/llms/index.ts

🧠 Learnings (24)

📓 Common learnings

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/ultracite.mdc:0-0
Timestamp: 2025-11-25T14:42:08.869Z
Learning: Applies to **/*.{jsx,tsx} : Make sure all dependencies are correctly specified in React hooks

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/ultracite.mdc:0-0
Timestamp: 2025-11-25T14:42:08.869Z
Learning: Applies to **/*.{jsx,tsx} : Make sure all React hooks are called from the top level of component functions

Learnt from: elie222
Repo: elie222/inbox-zero PR: 485
File: apps/web/app/(landing)/login/page.tsx:41-43
Timestamp: 2025-06-05T09:49:12.168Z
Learning: In Next.js App Router, components that use the `useSearchParams` hook require a Suspense boundary to handle the asynchronous nature of search parameter access. The Suspense wrapper is necessary and should not be removed when a component uses useSearchParams.

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: apps/web/CLAUDE.md:0-0
Timestamp: 2025-12-21T12:21:37.794Z
Learning: Applies to apps/web/**/*.{tsx,jsx} : Prefer functional components with hooks in React

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/llm.mdc:0-0
Timestamp: 2025-11-25T14:38:07.606Z
Learning: Applies to apps/web/utils/ai/**/*.ts : Implement early returns for invalid LLM inputs, use proper error types and logging, implement fallbacks for AI failures, and add retry logic for transient failures using `withRetry`

📚 Learning: 2025-06-05T09:49:12.168Z

Learnt from: elie222
Repo: elie222/inbox-zero PR: 485
File: apps/web/app/(landing)/login/page.tsx:41-43
Timestamp: 2025-06-05T09:49:12.168Z
Learning: In Next.js App Router, components that use the `useSearchParams` hook require a Suspense boundary to handle the asynchronous nature of search parameter access. The Suspense wrapper is necessary and should not be removed when a component uses useSearchParams.

Applied to files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

📚 Learning: 2025-07-08T13:14:07.449Z

Learnt from: elie222
Repo: elie222/inbox-zero PR: 537
File: apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx:30-34
Timestamp: 2025-07-08T13:14:07.449Z
Learning: The clean onboarding page in apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx is intentionally Gmail-specific and should show an error for non-Google email accounts rather than attempting to support multiple providers.

Applied to files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

📚 Learning: 2025-08-10T22:03:30.507Z

Learnt from: elie222
Repo: elie222/inbox-zero PR: 667
File: apps/web/app/(app)/[emailAccountId]/onboarding/page.tsx:18-25
Timestamp: 2025-08-10T22:03:30.507Z
Learning: In Next.js 15, both `params` and `searchParams` passed to page components in the App Router are Promises that need to be awaited. They should be typed as `Promise<{...}>` and accessed using `await` in server components or React's `use()` hook in client components. This is different from Next.js 14 where they were plain objects.

Applied to files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

📚 Learning: 2025-11-25T14:40:15.063Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/ui-components.mdc:0-0
Timestamp: 2025-11-25T14:40:15.063Z
Learning: Applies to **/*.tsx : Use the `LoadingContent` component to handle loading states instead of manual loading state management

Applied to files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

📚 Learning: 2025-11-25T14:37:09.306Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/fullstack-workflow.mdc:0-0
Timestamp: 2025-11-25T14:37:09.306Z
Learning: Applies to apps/web/components/**/*.tsx : Use `LoadingContent` component to consistently handle loading and error states, passing `loading`, `error`, and `children` props

Applied to files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

📚 Learning: 2025-12-21T12:21:37.794Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: apps/web/CLAUDE.md:0-0
Timestamp: 2025-12-21T12:21:37.794Z
Learning: Applies to apps/web/**/*.{tsx,jsx} : Use LoadingContent component for async data with loading and error states

Applied to files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

📚 Learning: 2025-11-25T14:40:13.649Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/ui-components.mdc:0-0
Timestamp: 2025-11-25T14:40:13.649Z
Learning: Applies to **/*.{tsx,ts,jsx,js} : Use the `LoadingContent` component to handle loading states

Applied to files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

📚 Learning: 2025-11-25T14:39:23.326Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/security.mdc:0-0
Timestamp: 2025-11-25T14:39:23.326Z
Learning: Applies to app/api/**/*.ts : Use `withEmailAccount` middleware for operations scoped to a specific email account (reading/writing emails, rules, schedules, etc.) - provides `emailAccountId`, `userId`, and `email` in `request.auth`

Applied to files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

📚 Learning: 2025-11-25T14:39:08.150Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/security-audit.mdc:0-0
Timestamp: 2025-11-25T14:39:08.150Z
Learning: Applies to apps/web/app/api/**/*.{ts,tsx} : All database queries must include user scoping with `emailAccountId` or `userId` filtering in WHERE clauses

Applied to files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

📚 Learning: 2025-11-25T14:39:49.448Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/server-actions.mdc:0-0
Timestamp: 2025-11-25T14:39:49.448Z
Learning: Applies to apps/web/utils/actions/*.ts : Use `actionClient` when both authenticated user context and a specific emailAccountId are needed, with emailAccountId bound when calling from the client

Applied to files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

📚 Learning: 2025-11-25T14:39:27.909Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/security.mdc:0-0
Timestamp: 2025-11-25T14:39:27.909Z
Learning: Applies to **/app/api/**/*.ts : Use `withEmailAccount` middleware for operations scoped to a specific email account, including reading/writing emails, rules, schedules, or any operation using `emailAccountId`

Applied to files:

• apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx

📚 Learning: 2025-11-25T14:38:07.606Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/llm.mdc:0-0
Timestamp: 2025-11-25T14:38:07.606Z
Learning: Applies to apps/web/utils/ai/**/*.ts : Implement early returns for invalid LLM inputs, use proper error types and logging, implement fallbacks for AI failures, and add retry logic for transient failures using `withRetry`

Applied to files:

• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

📚 Learning: 2025-11-25T14:38:07.606Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/llm.mdc:0-0
Timestamp: 2025-11-25T14:38:07.606Z
Learning: Applies to apps/web/utils/ai/**/*.ts : Use TypeScript types for all LLM function parameters and return values, and define clear interfaces for complex input/output structures

Applied to files:

• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

📚 Learning: 2025-11-25T14:38:07.606Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/llm.mdc:0-0
Timestamp: 2025-11-25T14:38:07.606Z
Learning: Applies to apps/web/utils/ai/**/*.ts : Keep related AI functions in the same file or directory, extract common patterns into utility functions, and document complex AI logic with clear comments

Applied to files:

• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

📚 Learning: 2025-11-25T14:39:23.326Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/security.mdc:0-0
Timestamp: 2025-11-25T14:39:23.326Z
Learning: Applies to app/api/**/*.ts : Use `SafeError` for error responses to prevent information disclosure - provide generic messages (e.g., 'Rule not found' not 'Rule {id} does not exist for user {userId}') without revealing internal IDs or ownership details

Applied to files:

• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

📚 Learning: 2025-11-25T14:38:07.606Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/llm.mdc:0-0
Timestamp: 2025-11-25T14:38:07.606Z
Learning: Applies to apps/web/utils/ai/**/*.ts : LLM feature functions must import from `zod` for schema validation, use `createScopedLogger` from `@/utils/logger`, `chatCompletionObject` and `createGenerateObject` from `@/utils/llms`, and import `EmailAccountWithAI` type from `@/utils/llms/types`

Applied to files:

• apps/web/utils/actions/settings.ts
• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

📚 Learning: 2025-11-25T14:39:08.150Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/security-audit.mdc:0-0
Timestamp: 2025-11-25T14:39:08.150Z
Learning: Applies to apps/web/app/api/**/*.{ts,tsx} : Use generic error messages instead of revealing internal details; throw `SafeError` instead of exposing user IDs, resource IDs, or system information

Applied to files:

• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

📚 Learning: 2025-11-25T14:39:27.909Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/security.mdc:0-0
Timestamp: 2025-11-25T14:39:27.909Z
Learning: Applies to **/app/api/**/*.ts : Maintain consistent error response format across all API routes to avoid information disclosure while providing meaningful error feedback

Applied to files:

• apps/web/utils/error-messages/index.ts
• apps/web/utils/error.ts
• apps/web/utils/llms/index.ts

📚 Learning: 2025-12-21T12:21:37.794Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: apps/web/CLAUDE.md:0-0
Timestamp: 2025-12-21T12:21:37.794Z
Learning: Applies to apps/web/utils/actions/**/*.ts : Use proper error handling with try/catch blocks

Applied to files:

• apps/web/utils/error.ts

📚 Learning: 2025-11-25T14:39:27.909Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/security.mdc:0-0
Timestamp: 2025-11-25T14:39:27.909Z
Learning: Applies to **/*.ts : Use SafeError for error responses to prevent information disclosure. Generic error messages should not reveal internal IDs, logic, or resource ownership details

Applied to files:

• apps/web/utils/error.ts

📚 Learning: 2025-11-25T14:38:07.606Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/llm.mdc:0-0
Timestamp: 2025-11-25T14:38:07.606Z
Learning: Applies to apps/web/{utils/ai,utils/llms,__tests__}/**/*.ts : LLM-related code must be organized in specific directories: `apps/web/utils/ai/` for main implementations, `apps/web/utils/llms/` for core utilities and configurations, and `apps/web/__tests__/` for LLM-specific tests

Applied to files:

• apps/web/utils/llms/index.ts

📚 Learning: 2025-11-25T14:38:07.606Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/llm.mdc:0-0
Timestamp: 2025-11-25T14:38:07.606Z
Learning: Applies to apps/web/utils/ai/**/*.ts : Use descriptive scoped loggers for each LLM feature, log inputs and outputs with appropriate log levels, and include relevant context in log messages

Applied to files:

• apps/web/utils/llms/index.ts

📚 Learning: 2025-11-25T14:38:07.606Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/llm.mdc:0-0
Timestamp: 2025-11-25T14:38:07.606Z
Learning: Applies to apps/web/utils/ai/**/*.ts : LLM feature functions must follow a standard structure: accept options with `inputData` and `emailAccount` parameters, implement input validation with early returns, define separate system and user prompts, create a Zod schema for response validation, and use `createGenerateObject` to execute the LLM call

Applied to files:

• apps/web/utils/llms/index.ts

🧬 Code graph analysis (2)

apps/web/utils/actions/settings.ts (1)

apps/web/utils/error-messages/index.ts (1)

• ErrorType (112-119)

apps/web/utils/llms/index.ts (2)

apps/web/utils/error.ts (1)

• isAiQuotaExceededError (134-143)

apps/web/utils/error-messages/index.ts (2)

• addUserErrorMessageWithNotification (157-237)
• ErrorType (112-119)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Baz Reviewer
• GitHub Check: cubic · AI code reviewer
• GitHub Check: test

🔇 Additional comments (6)

apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx (1)

1-1: LGTM! Suspense boundary appropriately addresses the hooks violation.

The changes correctly implement a Suspense boundary to isolate step components and prevent the "Rendered more hooks than during the previous render" error. The key={step} prop forces re-mounting when steps change, which ensures each step component starts with a clean hooks state.

The early await of searchParams at line 31 is correct for Next.js 15, and the step parsing at line 53 safely handles undefined or empty values with a fallback to CleanStep.INTRO.

Based on learnings: In Next.js App Router, components that use async parameters require proper awaiting, and using Suspense boundaries helps handle the asynchronous nature of parameter access.

Also applies to: 31-31, 53-53, 99-108

apps/web/utils/actions/settings.ts (1)

54-64: LGTM! Error type update aligns with the generalized AI quota handling.

The change from OPENAI_RETRY_ERROR to AI_QUOTA_ERROR correctly generalizes the error handling to work with any AI provider, not just OpenAI. This ensures users receive fresh notifications when updating AI settings after encountering quota issues from any provider.

apps/web/utils/llms/index.ts (1)

32-32: LGTM! Quota error handling successfully generalized for all AI providers.

The changes correctly replace OpenAI-specific quota error detection with a generalized approach that works for any AI provider. The updated error message at line 326 now accurately refers to "Your AI provider" instead of "OpenAI provider", and the error type AI_QUOTA_ERROR aligns with the centralized error handling strategy.

Also applies to: 319-329

apps/web/utils/error-messages/index.ts (1)

116-116: LGTM! AI quota error type properly configured.

The new AI_QUOTA_ERROR type is correctly added to both the ErrorType object and the errorTypeConfig map. The user-facing label "AI Rate Limited" is clearer and more accurate than the previous "API Quota Exceeded" terminology.

Also applies to: 140-144

apps/web/utils/error.ts (2)

133-143: LGTM! Generalized quota error detection handles multiple AI providers.

The new isAiQuotaExceededError function uses a comprehensive heuristic approach to detect quota/rate-limit errors from various AI providers by checking for common error message patterns. This effectively replaces the OpenAI-specific detection and covers multiple providers including OpenAI, Anthropic, and others.

The function checks for:

• "exceeded your current quota"
• "quota exceeded"
• "rate limit reached"
• "rate_limit_reached"
• "too many requests"

This broad pattern matching is appropriate for detecting quota issues across different AI provider APIs.

---

187-187: LGTM! Error classification consistently updated.

The integration of isAiQuotaExceededError into isKnownApiError (line 187) and checkCommonErrors (lines 236-243) is correct. The error type and messaging have been properly updated from "OpenAI Quota Exceeded" to "AI Quota Exceeded" to reflect the generalized approach.

Also applies to: 236-243

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Render onboarding step content in CleanPage within a Suspense boundary and switch AI quota error handling to provider-agnostic ErrorType.AI_QUOTA_ERROR across utils

Adds Suspense with a centered loading fallback keyed by step in apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx and replaces OpenAI-specific quota retry detection and messaging with provider-agnostic AI_QUOTA_ERROR in error and LLM utilities.

📍Where to Start

Start with CleanPage in apps/web/app/(app)/[emailAccountId]/clean/onboarding/page.tsx, then review isAiQuotaExceededError in apps/web/utils/error.ts.

---

Macroscope summarized d41b173.

[cubic-dev-ai]

No issues found across 5 files