@yoast/ai-insights-client 1.4.101 → 1.4.102
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +51 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -165,7 +165,57 @@ For testing purposes, the application includes a dev mode that allows manual tok
|
|
|
165
165
|
|
|
166
166
|
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.
|
|
167
167
|
|
|
168
|
-
|
|
168
|
+
## API Integration with Orval
|
|
169
|
+
|
|
170
|
+
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.
|
|
171
|
+
|
|
172
|
+
### How Orval Works
|
|
173
|
+
|
|
174
|
+
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:
|
|
175
|
+
|
|
176
|
+
- Typed Axios request functions
|
|
177
|
+
- TanStack Query hooks for data fetching
|
|
178
|
+
- TypeScript interfaces for request/response types
|
|
179
|
+
- Automatic error handling
|
|
180
|
+
|
|
181
|
+
### Generated Code Location
|
|
182
|
+
|
|
183
|
+
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:
|
|
184
|
+
|
|
185
|
+
- Easy comparison of API changes during code review
|
|
186
|
+
- Tracking of API evolution over time
|
|
187
|
+
- Immediate availability for developers without requiring local generation
|
|
188
|
+
|
|
189
|
+
### Development Workflow
|
|
190
|
+
|
|
191
|
+
#### Updating API Code
|
|
192
|
+
|
|
193
|
+
To pull the latest API changes from the backend:
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
# Pull from local development server (localhost:8000)
|
|
197
|
+
yarn orval:dev
|
|
198
|
+
|
|
199
|
+
# Pull from production/staging API
|
|
200
|
+
yarn orval:prod
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Configuration can be found in `orval.config.ts`.
|
|
204
|
+
|
|
205
|
+
#### Code Review Guidelines
|
|
206
|
+
|
|
207
|
+
When reviewing changes in `/src/api/generated/`:
|
|
208
|
+
|
|
209
|
+
- Focus on high-level review to ensure new endpoints and schema changes are properly reflected
|
|
210
|
+
- Verify the changes align with the corresponding `ai-insights-api` branch
|
|
211
|
+
- Don't modify generated files directly - changes should come from API updates
|
|
212
|
+
- TypeScript compilation will catch most incompatibility issues
|
|
213
|
+
|
|
214
|
+
#### Best Practices
|
|
215
|
+
|
|
216
|
+
1. **Always regenerate before merging**: Run `yarn orval:dev` after the API branch merges to main to capture all changes
|
|
217
|
+
2. **Coordinate with backend**: Ensure the API branch is up-to-date when generating frontend code
|
|
218
|
+
3. **Review systematically**: Check that new endpoints, modified schemas, and removed endpoints are properly reflected
|
|
169
219
|
|
|
170
220
|
## TypeScript Support
|
|
171
221
|
|