zklighter-perps-ts

Auto-generated TypeScript SDK for the Lighter Perps API, published to npm as zklighter-perps.

The SDK source (index.ts, runtime.ts, apis/, models/) is generated by the OpenAPI Generator from the backend's OpenAPI spec. Do not edit the generated files by hand — they are overwritten on every regeneration. The package ships raw .ts ("main": "index.ts"), so consumers compile it themselves.

Generation pipeline (CircleCI)

Defined in .circleci/config.yml. The update_ts_sdk workflow (manually triggered) runs three jobs in sequence:

1. update_openapi — clones zklighter-perps, runs goctl-swagger to emit the raw openapi.json, and persists it. This job no longer transforms the spec; it only generates and persists it.
2. openapi_postprocess — runs .circleci/openapi_postprocess.py, the single source of truth for all spec fixups (see below).
3. update_ts_sdk — runs the OpenAPI Generator on the post-processed spec, bumps the package version, and opens a PR.

The update_npm_package workflow runs on main:

• typecheck — npm install && npm run typecheck (tsc --noEmit using tsconfig.json). Runs on every branch, including the timestamped branches opened by update_ts_sdk, so a regenerated SDK that would fail to compile in a consumer (e.g. perps-fe) is caught on its PR.
• update_npm_package — publishes to npm (requires typecheck to pass).

OpenAPI post-processing

The spec emitted by goctl-swagger has quirks that either break the OpenAPI Generator or produce an awkward SDK, so we post-process it before generation. All of this lives in one place — .circleci/openapi_postprocess.py. (Historically some of these fixes were inline jq/sed commands in the update_openapi job; they have been consolidated into the script so the logic is in a single, testable file.)

Why each transform exists:

1. Drop internal endpoints/definitions (/api/v1/feedback, /api/v1/ws_status, /stream, /api/v1/permission, ReqSendFeedback) — not part of the public SDK surface.
2. Strip empty-string keys — the generator emits "" keys the OpenAPI Generator cannot process.
3. Mirror summary into description — preserves the original human-readable text as the generated doc comment before summary is overwritten in step 8.
4. Seed summary from operationId — normalizes naming before step 8.
5. Add a documented 400 response referencing ResultCode to every operation, so the SDK models the standard error shape.
6. Model the types parameter as a byte array (array of uint8) instead of the non-standard scalar the spec declares.
7. Remove placeholder "-" enum/array values that aren't real values.
8. Derive stable, path-based operationId/summary (e.g. /api/v1/account → account) so generated method names are predictable.
9. Inline non-standard int16/map $refs (int16, mapint16string, mapstringfloat64) — these are not standard OpenAPI and make the generator emit broken model references.
10. Move array-level enum into items — correct placement for array schemas.
11. Make the transfer/history type param an array of enum strings.
12. Trim over-eager required fields — the backend marks fields required that are actually optional in responses; we relax them so deserialization doesn't reject valid payloads.

Local development

npm install        # installs TypeScript (the only dependency)
npm run typecheck  # same check CI runs: tsc --noEmit

To test the post-processing script against a spec locally, place an openapi.json next to the script and run python3 openapi_postprocess.py (it reads/writes ./openapi.json).