heyapi-handson

PoC de un SDK TypeScript autogenerado desde un OpenAPI spec usando @hey-api/openapi-ts.

Spec de prueba: https://earn.turtle.xyz/v1/docs/openapi.json (Turtle Earn API).

Qué hace

• Genera tipos + cliente runtime + funciones tipadas por endpoint desde el OpenAPI
• Empaqueta un wrapper mínimo createTurtleClient({ apiKey, baseUrl }) para DX limpia
• GitHub Action que re-genera el SDK en cada cambio del spec y abre PR

Scripts

pnpm install           # instalar deps
pnpm codegen           # regenerar src/client-v1/ y src/client-v2/ desde el OpenAPI
pnpm typecheck         # validar tipos
pnpm example           # correr examples/basic.ts (smoke test v1 + v2)
pnpm example:zod       # correr examples/with-zod.ts (validación runtime con zod)

examples/with-tanstack.tsx no se corre acá (necesita React) — está como snippet documentado de cómo se usaría el plugin TanStack Query.

Uso

import { createTurtleV1Client, createTurtleV2Client, v1, v2 } from './src';

const apiV1 = createTurtleV1Client({ apiKey, baseUrl: 'https://earn.turtle.xyz' });
const opps = await apiV1.getOpportunities();

const apiV2 = createTurtleV2Client({ apiKey, baseUrl: 'https://earn.turtle.xyz' });
const chains = await apiV2.handlersV2GetChainsHandler();

// Tipos por versión:
const opp: v1.Opportunity = /* ... */;

Múltiples specs / múltiples APIs

openapi-ts.config.ts exporta un array de configs: cada entry es un codegen independiente con su propio input, output y filtros.

• Mismo API, distinta versión: dos entries con el mismo input y filtros parser.filters.operations.include por path (regex ^[A-Z]+ \/v1\/).
• Otra API entera: un entry más con otro input, output: './src/client-otra' y su propio wrapper createOtraClient.ts. Mismo patrón.

Workflow de sync

.github/workflows/sync-sdk.yml corre:

• Manualmente (workflow_dispatch)
• Cada día a las 06:00 UTC (cron, fallback)
• En repository_dispatch con event openapi-spec-updated (disparado por openapi-trigger-faker cuando muta openapi.json en main)

Si detecta cambios en el spec, abre un PR con src/client-v1/ o src/client-v2/ regenerado.

Stack y decisiones

• @hey-api/openapi-ts con plugins client-fetch + sdk (flat) + typescript
• Tree-shakeable: cada endpoint es una función exportada
• v1 expone wrapper parametrizable createTurtleV1Client({ apiKey, baseUrl })
• v2 expone funciones pre-configuradas via runtimeConfigPath (lee env)

Features del codegen aplicadas

| Feature | Dónde se ve | |---|---| | Array de configs | openapi-ts.config.ts exporta defineConfig([v1, v2, ...]) | | Filtros por path | parser.filters.operations.include separa v1 y v2 de la misma spec | | Naming custom | sdk.operations.methodName.name strip handlersV\d+ / Handler$ | | Enums como objetos JS | typescript.enums: 'javascript' (evita footgun de TS enums) | | Runtime config | client-fetch.runtimeConfigPath apunta a hey-api.runtime.ts (solo v2) | | Split por tag | parser.hooks.symbols.getFilePath parte el SDK en sdk/<tag>.gen.ts (solo v1) | | Zod schemas | plugin zod genera zod.gen.ts con un schema por cada tipo. safeParse(response) detecta drift backend/spec | | TanStack Query | plugin @tanstack/react-query genera <op>Options/QueryKey/Mutation para useQuery/useMutation |

Pendientes para producción

• [ ] tsup + package.json#exports para builds ESM+CJS
• [ ] changesets para versionado semver
• [ ] oasdiff para detectar breaking changes en el PR
• [ ] npm publish automático
• [ ] repository_dispatch desde el repo del API