:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
/**
* OpenAPI schema preprocessing to fix known Orval code generation issues.
*
* Four patterns are handled before handing schemas to Orval:
*
* 1. Named schemas that should be inlined (SCHEMAS_TO_INLINE)
* Each entry maps a component name to the inline schema that replaces every
* $ref to it. Two cases use this today:
* - TimezoneEnum has 596 IANA identifiers like "Africa/Abidjan" that
* PascalCase to "AfricaAbidjan", losing the path separator. We replace
* refs with { type: 'string' }.
* - NullEnum is drf-spectacular's named ref for a `{type: 'null'}` schema
* emitted alongside every nullable enum. The component is structural
* noise — it produces a `NullEnumApi = null` type alias that just
* forwards to `null`. We replace refs with { type: 'null'} so consumers
* see `Role | "" | null` directly.
*
* 2. Inline ordering enums with colliding keys (stripCollidingInlineEnums)
* DRF ordering params include both "created_at" and "-created_at", which
* both PascalCase to "CreatedAt" — producing an object with duplicate keys
* where the second silently overwrites the first. We detect this pattern
* (any enum with both "x" and "-x" values) and drop the enum constraint
* so orval emits string[] instead.
*
* 3. Integer bounds exceeding JS safe-integer range (clampIntegerBounds)
* drf-spectacular emits i64 bounds (±9223372036854775807) for BigAutoField
* primary keys. JSON.parse silently rounds 2^63-1 up to 2^63 (losing
* precision), and downstream consumers — including Anthropic's tool-schema
* validator, which parses bounds as i64 — then reject the overflowed value.
* We clamp any integer schema's min/max/exclusiveMin/exclusiveMax to int32
* range, which is far more than enough for every PostHog identifier.
*
* 4. `default: null` on null-permitting schemas (stripNullDefaults)
* Pydantic emits `default: null` for every `Optional[...] = None` field.
* Orval mirrors that into `.default(null)`, which makes Zod fill the field
* with `null` whenever the caller omits it (`safeParse` applies defaults).
* For request schemas that turns "field not sent" into "field sent as null",
* which the backend then rejects (`extra="forbid"`) or silently overwrites.
* Removing the null default lets Orval emit a plain `.nullable()` instead,
* so an omitted field stays omitted while an explicit `null` still parses.
*/
export const INT32_MIN = -2147483648
export const INT32_MAX = 2147483647
const INTEGER_BOUND_KEYS = ['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum']
/**
* Component names whose $refs get replaced inline, mapped to the substitute schema.
* The component itself is also removed from `components.schemas` after substitution.
*/
export const SCHEMAS_TO_INLINE = new Map([
['TimezoneEnum', { type: 'string' }],
['NullEnum', { type: 'null' }],
])
/**
* Replace $refs to SCHEMAS_TO_INLINE entries with their substitute schema in-place.
*/
export function inlineSchemaRefs(obj) {
if (!obj || typeof obj !== 'object') {
return obj
}
if (obj.$ref) {
const name = obj.$ref.replace('#/components/schemas/', '')
const substitute = SCHEMAS_TO_INLINE.get(name)
if (substitute) {
return { ...substitute }
}
}
for (const [key, value] of Object.entries(obj)) {
obj[key] = inlineSchemaRefs(value)
}
return obj
}
/**
* Remove enum arrays where both "x" and "-x" appear (colliding PascalCase keys).
* Applied in-place recursively.
*/
export function stripCollidingInlineEnums(obj) {
if (!obj || typeof obj !== 'object') {
return
}
if (Array.isArray(obj)) {
obj.forEach(stripCollidingInlineEnums)
return
}
if (obj.type === 'string' && Array.isArray(obj.enum)) {
const positives = new Set(obj.enum.filter((v) => !v.startsWith('-')))
if (obj.enum.some((v) => v.startsWith('-') && positives.has(v.slice(1)))) {
delete obj.enum
}
}
for (const value of Object.values(obj)) {
stripCollidingInlineEnums(value)
}
}
/**
* Clamp integer bounds that exceed int32 range.
*
* Applied in-place to any object shaped like `{ type: 'integer', ... }`, where
* "integer" is either the literal type or present in a `type` array. Bounds
* outside ±2^31-1 are rewritten to the nearest int32 limit; values already
* within range are left untouched.
*/
export function clampIntegerBounds(obj) {
if (!obj || typeof obj !== 'object') {
return
}
if (Array.isArray(obj)) {
obj.forEach(clampIntegerBounds)
return
}
const type = obj.type
const isInteger = type === 'integer' || (Array.isArray(type) && type.includes('integer'))
if (isInteger) {
for (const key of INTEGER_BOUND_KEYS) {
const value = obj[key]
if (typeof value !== 'number') {
continue
}
if (value > INT32_MAX) {
obj[key] = INT32_MAX
} else if (value < INT32_MIN) {
obj[key] = INT32_MIN
}
}
}
for (const value of Object.values(obj)) {
clampIntegerBounds(value)
}
}
/**
* Returns true when the schema accepts `null` — covers every shape Pydantic
* and drf-spectacular emit:
* - `nullable: true` (OpenAPI 3.0)
* - `type: 'null'` (OpenAPI 3.1 / JSON Schema)
* - `type: ['string', 'null']` (OpenAPI 3.1 type-array form)
* - `anyOf` / `oneOf` with a null variant (OpenAPI 3.1 union form)
* - Untyped `typing.Any` — Pydantic emits a bare `{}` (no type, no $ref, no
* variants, no enum, no properties) which accepts every value including null.
*
* A schema with `allOf` is treated as constrained (intersection of refs), so
* `{ allOf: [{ $ref: '...' }], default: null }` does NOT match — fall back to
* the explicit nullable keys above when the constituent permits null.
*/
export function schemaAllowsNull(schema) {
if (!schema || typeof schema !== 'object') {
return false
}
if (schema.nullable === true || schema.type === 'null') {
return true
}
if (Array.isArray(schema.type) && schema.type.includes('null')) {
return true
}
for (const key of ['anyOf', 'oneOf']) {
const variants = schema[key]
if (Array.isArray(variants) && variants.some(schemaAllowsNull)) {
return true
}
}
const constrained = ['type', 'allOf', 'anyOf', 'oneOf', '$ref', 'enum', 'const', 'properties']
if (constrained.every((key) => !(key in schema))) {
return true
}
return false
}
/**
* Strip `default: null` from any schema that already permits null. See the
* file-level doc for why this matters. Mutates in place.
*/
export function stripNullDefaults(obj) {
if (!obj || typeof obj !== 'object') {
return
}
if (Array.isArray(obj)) {
for (const item of obj) {
stripNullDefaults(item)
}
return
}
if ('default' in obj && obj.default === null && schemaAllowsNull(obj)) {
delete obj.default
}
for (const value of Object.values(obj)) {
stripNullDefaults(value)
}
}
/**
* Run standard preprocessing on a full OpenAPI schema.
* Mutates the schema in place, also returns it for convenience.
*/
export function preprocessSchema(schema) {
inlineSchemaRefs(schema)
for (const name of SCHEMAS_TO_INLINE.keys()) {
delete schema.components?.schemas?.[name]
}
stripCollidingInlineEnums(schema)
clampIntegerBounds(schema)
stripNullDefaults(schema)
return schema
}