: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
#!/usr/bin/env tsx
import { execSync } from "node:child_process";
import * as fs from "node:fs";
import * as path from "node:path";
import { fileURLToPath } from "node:url";
// Anchor to the package root so the relative paths below (and the pnpm binary lookup)
// resolve the same way no matter which directory the script is invoked from.
process.chdir(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
const REPO_ROOT = path.resolve(process.cwd(), "../../../..");
// The schema `hogli build:openapi-schema` writes, which every other generator in the repo
// reads. Reading it here rather than fetching a running instance keeps this client pinned to
// the checkout, so a stale regeneration is a diff rather than a silent mismatch.
const OPENAPI_PATH = path.resolve(REPO_ROOT, "frontend/tmp/openapi.json");
const TEMP_SCHEMA_PATH = "temp-openapi.json";
const OUTPUT_PATH = "src/generated.ts";
// Only the endpoints the desktop calls through the typed client are generated. The full
// schema documents thousands of routes, and every backend change to any of them would
// otherwise churn generated.ts; an allowlist keeps a regen to the routes we actually use.
const ALLOWLIST_PATH = "endpoint-allowlist.json";
function readSchema() {
console.log(`Reading OpenAPI schema from ${OPENAPI_PATH}...`);
if (!fs.existsSync(OPENAPI_PATH)) {
console.error(
`OpenAPI schema not found at ${OPENAPI_PATH}. Run \`hogli build:openapi-schema\` first.`,
);
return false;
}
try {
const schema = JSON.parse(fs.readFileSync(OPENAPI_PATH, "utf-8"));
filterEndpoints(schema);
fs.writeFileSync(TEMP_SCHEMA_PATH, JSON.stringify(schema), "utf-8");
console.log(`✓ Schema saved to ${TEMP_SCHEMA_PATH}`);
return true;
} catch (error) {
console.error("Error reading schema:", error);
return false;
}
}
interface Allowlist {
paths: string[];
schemas: string[];
}
function readAllowlist(): Allowlist {
const allowlist = JSON.parse(fs.readFileSync(ALLOWLIST_PATH, "utf-8")) as {
paths?: unknown;
schemas?: unknown;
};
const isStringList = (value: unknown): value is string[] =>
Array.isArray(value) && value.every((item) => typeof item === "string");
if (!isStringList(allowlist.paths) || !isStringList(allowlist.schemas)) {
throw new Error(
`${ALLOWLIST_PATH} must contain "paths" and "schemas" arrays of strings`,
);
}
return { paths: allowlist.paths, schemas: allowlist.schemas };
}
type Components = Record<string, Record<string, unknown>>;
const REF_PREFIX = "#/components/";
/** Every `$ref` reachable from `value`, as [componentKind, name] pairs. */
function collectRefs(value: unknown, into: Set<string>): void {
if (Array.isArray(value)) {
for (const item of value) collectRefs(item, into);
return;
}
if (!value || typeof value !== "object") return;
for (const [key, child] of Object.entries(value)) {
if (
key === "$ref" &&
typeof child === "string" &&
child.startsWith(REF_PREFIX)
) {
into.add(child.slice(REF_PREFIX.length));
} else {
collectRefs(child, into);
}
}
}
/**
* Keeps only the component schemas reachable from the kept paths and the
* allowlisted schema names, following `$ref`s transitively (through other
* component kinds too, since a shared parameter can reference a schema).
*/
function pruneSchemas(
schema: { paths?: Record<string, unknown>; components?: Components },
seeds: string[],
) {
const components = schema.components;
if (!components?.schemas) return;
const missing = seeds.filter((name) => !(name in components.schemas));
if (missing.length > 0) {
throw new Error(
`Allowlisted schemas missing from the schema (remove them from ${ALLOWLIST_PATH} or fix the name):\n ${missing.join("\n ")}`,
);
}
const pending = new Set<string>(seeds.map((name) => `schemas/${name}`));
collectRefs(schema.paths, pending);
const kept = new Set<string>();
while (pending.size > 0) {
const [ref] = pending;
pending.delete(ref);
if (kept.has(ref)) continue;
kept.add(ref);
const [kind, ...rest] = ref.split("/");
const definition = components[kind]?.[rest.join("/")];
const refs = new Set<string>();
collectRefs(definition, refs);
for (const next of refs) if (!kept.has(next)) pending.add(next);
}
const total = Object.keys(components.schemas).length;
components.schemas = Object.fromEntries(
Object.entries(components.schemas).filter(([name]) =>
kept.has(`schemas/${name}`),
),
);
console.log(
`✓ Kept ${Object.keys(components.schemas).length} component schemas of ${total} in the schema`,
);
}
function filterEndpoints(schema: {
paths?: Record<string, unknown>;
components?: Components;
}) {
if (!schema.paths) return;
const allowlist = readAllowlist();
const totalInSchema = Object.keys(schema.paths).length;
const filteredPaths: Record<string, unknown> = {};
const missing: string[] = [];
for (const path of allowlist.paths) {
const pathItem = schema.paths[path];
if (pathItem === undefined) {
missing.push(path);
continue;
}
filteredPaths[path] = pathItem;
}
// A path that left the schema means a route was removed or renamed upstream. Failing
// here names it, instead of a typecheck error at whichever call site used it.
if (missing.length > 0) {
throw new Error(
`Allowlisted endpoints missing from the schema (remove them from ${ALLOWLIST_PATH} or fix the path):\n ${missing.join("\n ")}`,
);
}
schema.paths = filteredPaths;
console.log(
`✓ Kept ${Object.keys(filteredPaths).length} allowlisted endpoints of ${totalInSchema} in the schema`,
);
pruneSchemas(schema, allowlist.schemas);
}
function generateClient() {
console.log("Generating TypeScript client...");
try {
execSync(`pnpm typed-openapi ${TEMP_SCHEMA_PATH} --output ${OUTPUT_PATH}`, {
stdio: "inherit",
});
console.log(`✓ Client generated at ${OUTPUT_PATH}`);
return true;
} catch (error) {
console.error("Error generating client:", error);
return false;
}
}
// typed-openapi emits long single-line types. Formatting the output makes a regen diff show
// the types that changed instead of rewrapping the whole file, and matches how the
// checked-in file has always been formatted. Biome skips this file, so prettier does it.
function formatClient() {
console.log("Formatting generated client...");
try {
execSync(`pnpm prettier --write ${OUTPUT_PATH} --log-level warn`, {
stdio: "inherit",
});
console.log("✓ Client formatted");
return true;
} catch (error) {
console.error("Error formatting client:", error);
return false;
}
}
function cleanup() {
try {
if (fs.existsSync(TEMP_SCHEMA_PATH)) {
fs.unlinkSync(TEMP_SCHEMA_PATH);
console.log("✓ Cleaned up temporary schema file");
}
} catch (error) {
console.error("Warning: Could not clean up temporary file:", error);
}
}
async function main() {
console.log("Starting OpenAPI client update...\n");
const schemaRead = readSchema();
if (!schemaRead) {
process.exit(1);
}
const clientGenerated = generateClient() && formatClient();
cleanup();
if (!clientGenerated) {
process.exit(1);
}
console.log("\n✅ OpenAPI client successfully updated!");
}
main().catch((error) => {
console.error("Unexpected error:", error);
process.exit(1);
});