The official client is a hand-maintained TypeScript SDK with an enum-translation layer

Context

JavaScript/TypeScript integrators — merchant dashboards, partner apps, internal tools — need a supported way to call the commerce API. Two forks: generate the SDK from an API description (codegen) or hand-maintain it; and how to present API fields that are exposed as magic integers (statuses, kinds) which are unfriendly and error-prone for consumers.

Decision

Ship an official, hand-maintained TypeScript SDK (@inkress/admin-sdk) with a client-side enum-translation layer.

• Hand-written, spec-seeded. The SDK is authored by hand, using the OpenAPI description as a seed/reference, not a codegen source, and organized into resource modules. It is versioned and published to npm (currently v1.1.52).
• Enum translation at the edge. A data-mapping layer converts the API's magic integers to and from human-readable strings (e.g. order status), so SDK consumers work with meaningful values instead of raw codes.

Consequences

• Positive: a curated, ergonomic, typed client that can smooth over API rough edges (the integer enums) rather than mechanically mirroring them; it is the single supported integration surface.
• Neutral / to revisit: hand-maintenance means the SDK can drift from the API when an endpoint or field changes and the SDK is not updated in lockstep — there is no codegen forcing sync; and the enum-translation map must track the API's integer meanings or it will mistranslate.

Alternatives considered

• Full codegen from OpenAPI: not adopted — it mirrors the API's rough edges (magic integers, weak ergonomics) and produces mechanical code; hand-maintenance trades automated sync for a better developer experience and the freedom to translate enums.
• No official SDK (integrators call REST directly): rejected — every integrator would re-derive the enum meanings and request shapes; an official SDK centralizes that knowledge and is the supported path.