Skip to main content
@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

npm install @gojinko/api-client
Works with Node.js ≥ 20. ESM-only.
@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

import { createJinkoClient } from '@gojinko/api-client'

const client = await createJinkoClient({ apiKey: 'jnk_...' })

const { results } = await client.flightCalendar({
  origin: 'JFK',
  destination: 'CDG',
  departure_date: '2026-06-15',
})

Authentication

createJinkoClient() resolves auth in this order:
1

Explicit apiKey option

createJinkoClient({ apiKey: 'jnk_...' })
2

JINKO_API_KEY env var

export JINKO_API_KEY=jnk_...
createJinkoClient() // picks up env
3

~/.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.
If none of those yield credentials, createJinkoClient() throws AuthError.

OAuth tokens

If your config has OAuth tokens (from jinko 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)

Pass environment to target the sandbox (isolated data, separate API keys) before going to production:
const client = await createJinkoClient({
  environment: 'sandbox',
  apiKey: 'jnk_your_sandbox_key',
})
environmentBase URL
'prod' (default)https://api.gojinko.com
'sandbox'https://api.sandbox.gojinko.com
Resolution precedence: the environment option → JINKO_ENV → the active environment in ~/.jinko/config.yaml (shared with the CLIjinko 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

interface JinkoClient extends JinkoTools {
  readonly raw: JinkoRawClient    // openapi-fetch client for escape-hatch requests
  readonly auth: ResolvedAuth     // method + token info
  // ...plus every method in JinkoTools (see Method reference)
}
  • client.raw, the underlying openapi-fetch client, 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 from ApiError:
import { ApiError, AuthError, ValidationError } from '@gojinko/api-client'

try {
  await client.flightCalendar({ /* ... */ })
} catch (err) {
  if (err instanceof AuthError) {
    // 401, bad or missing credentials
  } else if (err instanceof ValidationError) {
    // 400, malformed request
  } else if (err instanceof ApiError) {
    // other HTTP errors, err.statusCode is set
  }
}
See Errors & troubleshooting for a full status code reference.

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 logs
  • X-User-ID, only set on OAuth, from the JWT sub claim
When reporting a problem, grab the 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 methodPurpose
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.rawEscape hatch, typed openapi-fetch client for anything not yet wrapped
Click through any API endpoint for request / response schemas + runnable SDK + CLI + curl examples.

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.