@gojinko/api-client is the typed Node.js SDK for the Jinko Public API. It wraps every public endpoint with full TypeScript types, handles authentication (API key or OAuth), and auto-refreshes OAuth tokens when they expire.
Install
@gojinko/api-client 2.0 targets the canonical jinko-api /v1 surface. Upgrading is opt-in — the existing 1.x line keeps working unchanged against the legacy routes, which stay served during the transition. Move to 2.0 when you’re ready; there’s no forced cutover.Quick start
Authentication
createJinkoClient() resolves auth in this order:
~/.jinko/config.yaml (CLI-shared)
The same config file the CLI uses. Run
jinko auth login to populate it; your scripts pick it up automatically.createJinkoClient() throws AuthError.
OAuth tokens
If your config has OAuth tokens (fromjinko auth login without --key), the SDK checks expiry before each request and calls the auth refresh endpoint transparently. Refreshed tokens are written back to ~/.jinko/config.yaml so long-running scripts don’t lose session.
You cannot paste an OAuth token directly into
apiKey, different issuers. Use an API key (jnk_...) for programmatic access when you don’t want to maintain OAuth state.Environments (prod / sandbox)
Passenvironment to target the sandbox (isolated data, separate API keys) before going to production:
environment | Base URL |
|---|---|
'prod' (default) | https://api.gojinko.com |
'sandbox' | https://api.sandbox.gojinko.com |
environment option → JINKO_ENV → the active environment in ~/.jinko/config.yaml (shared with the CLI — jinko config set environment sandbox) → prod. An explicit baseUrl or the JINKO_API_BASE env var still overrides the mapping (for dev/staging).
The returned client
client.raw, the underlyingopenapi-fetchclient, typed against the full OpenAPI spec. Use this when you need an endpoint not yet exposed via a convenience method.client.auth, resolved credentials (method:'api_key' | 'oauth', plus token info).
Error handling
All errors derive fromApiError:
Observability
Every request the SDK emits carries:X-Session-ID, stable per process/CLI session (from~/.jinko/session.yaml)X-Request-ID, fresh UUID per request, useful for correlating a failure with Datadog logsX-User-ID, only set on OAuth, from the JWTsubclaim
X-Request-ID from your SDK logs and we can trace it server-side.
Method reference
The SDK mirrors the API reference 1:1, each method maps to an endpoint. Each endpoint’s reference page includes a TypeScript (SDK) tab alongside the CLI + curl samples, so the reference doubles as your SDK docs. Quick map:| SDK method | Purpose |
|---|---|
client.findDestination(req) | Discover destinations from origin airports |
client.flightCalendar(req) | Cached price calendar by route + flexible dates (canonical discovery method) |
client.flightSearch(req) | Live pricing: search OR price-check an offer |
client.hotelSearch(req) | Live hotel inventory + rates |
client.trip(req) | Create / update trip, items, travelers, ancillaries |
client.selectAncillaries(req) | Pre-select bags / seats / meals |
client.getTrip(tripId) | Inspect trip / quote / fulfillment / bookings |
client.book(tripId) | Schedule checkout, get Stripe URL |
client.getBooking(req) | Guest lookup by booking_ref + last_name |
client.refundCheck(req) / refundCommit(req) / refundStatus(req) | Refund flow |
client.exchangeShop(req) / exchangePrice(req) / exchangeCommit(req) / exchangeStatus(req) | Exchange flow |
client.raw | Escape hatch, typed openapi-fetch client for anything not yet wrapped |
Next steps
Booking guide
End-to-end booking flow in TypeScript, CLI, and MCP.
API reference
Per-endpoint docs with SDK / CLI / curl samples.
Authentication
API keys, OAuth flows, and when to use each.
Errors
Status codes, error envelope, and debugging.
