@yoast/ai-insights-client 1.4.101 → 1.4.103

package/README.md

@@ -165,7 +165,57 @@ For testing purposes, the application includes a dev mode that allows manual tok
 
 When enabled, a "Dev mode token" section appears in the sidebar that provides a textarea for entering authentication tokens. Tokens are auto-saved after a 1-second debounce (there is no save button). This is useful for preview environments and testing scenarios.
 
-For more details, see [docs/dev-mode.md](./docs/dev-mode.md).
+## API Integration with Orval
+
+This project uses [Orval](https://orval.dev/) to automatically generate type-safe API client code from our OpenAPI specification. This eliminates the need to manually write fetch or Axios calls and ensures our frontend stays in sync with backend API changes.
+
+### How Orval Works
+
+Orval takes an OpenAPI specification file and converts it into TypeScript functions that can be consumed directly to perform API actions. The generated code includes:
+
+- Typed Axios request functions
+- TanStack Query hooks for data fetching
+- TypeScript interfaces for request/response types
+- Automatic error handling
+
+### Generated Code Location
+
+The Orval output is generated into `/src/api/generated/`. While generated code typically wouldn't be committed to Git (like `node_modules`), we've chosen to commit these files to enable:
+
+- Easy comparison of API changes during code review
+- Tracking of API evolution over time
+- Immediate availability for developers without requiring local generation
+
+### Development Workflow
+
+#### Updating API Code
+
+To pull the latest API changes from the backend:
+
+```bash
+# Pull from local development server (localhost:8000)
+yarn orval:dev
+
+# Pull from production/staging API
+yarn orval:prod
+```
+
+Configuration can be found in `orval.config.ts`.
+
+#### Code Review Guidelines
+
+When reviewing changes in `/src/api/generated/`:
+
+- Focus on high-level review to ensure new endpoints and schema changes are properly reflected
+- Verify the changes align with the corresponding `ai-insights-api` branch
+- Don't modify generated files directly - changes should come from API updates
+- TypeScript compilation will catch most incompatibility issues
+
+#### Best Practices
+
+1. **Always regenerate before merging**: Run `yarn orval:dev` after the API branch merges to main to capture all changes
+2. **Coordinate with backend**: Ensure the API branch is up-to-date when generating frontend code
+3. **Review systematically**: Check that new endpoints, modified schemas, and removed endpoints are properly reflected
 
 ## TypeScript Support