posthog-foss: Skill for Claude Code

Adopting generated API types

Overview

PostHog generates TypeScript API client functions and types from Django serializers via the OpenAPI pipeline:

Django serializer → drf-spectacular → OpenAPI JSON → Orval → TypeScript (api.ts + api.schemas.ts + api.zod.ts)

Generated files live in:

• Core: frontend/src/generated/core/api.ts, api.schemas.ts, and api.zod.ts
• Products: products/<product>/frontend/generated/api.ts, api.schemas.ts, and api.zod.ts

Generated types use the Api suffix (DashboardApi, SurveyApi). Handwritten types never do.

This skill guides replacing manual API calls and handwritten types with generated equivalents.

The three manual patterns to migrate

The legacy frontend/src/lib/api.ts (~6000 lines) has three layers, all migration targets:

1. High-level object API (most common)

Domain-specific convenience methods on the api object:

api.surveys.get(id)
api.surveys.create(data)
api.dashboards.list()
api.cohorts.update(id, data)
api.actions.create(data)

These are the most widely used pattern — every entity has its own namespace with CRUD plus custom methods (e.g., api.surveys.getResponsesCount(), api.dashboards.streamTiles()).

2. Raw HTTP methods with manual URLs

api.get<SomeType>(`api/projects/${id}/surveys/`)
api.create<SomeType>(`api/projects/${id}/surveys/`, data)
api.update<SomeType>(url, data)
api.put<SomeType>(url, data)
api.delete(url)

3. ApiRequest builder (fluent URL construction)

const url = new ApiRequest().surveys().assembleFullUrl()
const response = await api.get(url)

// or directly:
await new ApiRequest().survey(surveyId).withAction('summarize_responses').create({ data })

All three patterns should be replaced with generated functions where available.

When to use

• Touching a file that calls api.<entity>.<method>() (e.g., api.surveys.get())
• Touching a file that calls api.get<T>(...), api.create<T>(...), etc.
• Touching a file that uses new ApiRequest() to build URLs
• Touching a file that imports handwritten interfaces from ~/types for API response shapes
• Cleaning up frontend code after backend serializer improvements