TypeScript SDK Template (OpenAPI First)

Template para criar SDKs Node.js/TypeScript para qualquer API OpenAPI.

Como usar como template no GitHub

1. Clique em Use this template neste repositório.
2. Crie o novo repositório do SDK (ex.: payments-sdk).
3. Clone e personalize os metadados do package.json:

• name
• repository.url
• bugs.url
• homepage
• publishConfig.access (public/restricted)

4. Substitua openapi.json pela spec real do projeto.
5. Rode npm run generate && npm run postgenerate.
6. Rode npm run ci.

Padrão adotado

• OpenAPI-first (openapi.json) como fonte de verdade.
• SDK gerado automaticamente em src/generated com openapi-typescript-codegen.
• Camada manual em src/client para auth, timeout, retry e erros tipados.
• Governança de contrato com Redocly + validação de operationId.

Scripts

npm run lint:spec             # Lint OpenAPI
npm run check:operation-ids   # Verifica operationId único
npm run fix:operation-ids     # Corrige operationId duplicado no openapi.json
npm run generate              # Gera SDK em src/generated
npm run postgenerate          # Pós-processamento da geração
npm run build                 # Build ESM/CJS + d.ts
npm run test                  # Testes
npm run ci                    # Pipeline completo

Exemplo de uso

import { ApiClient, HealthService } from "@wocody/runaholic-sdk";

const client = new ApiClient({
  baseUrl: process.env.API_BASE_URL!,
  token: () => process.env.API_TOKEN!,
  headers: {
    "x-app": "my-project",
  },
});

await client.configure();
const health = client.use(HealthService);
const status = await health.getHealth();

Next.js (App Router)

import { withNextHints } from "@wocody/runaholic-sdk/next";

const init = withNextHints({}, { revalidate: 60, tags: ["health"] });

CI/CD

• .github/workflows/ci.yml: valida contrato, gera SDK, build e testes.
• .github/workflows/release.yml: publish automatizado com semantic-release.

Quando a API mudar

1. Atualize openapi.json.
2. Rode npm run fix:operation-ids (se necessário).
3. Rode npm run generate && npm run postgenerate.
4. Commit das mudanças geradas.