TypeScript SDK

@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:

Explicit apiKey option

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

JINKO_API_KEY env var

export JINKO_API_KEY=jnk_...

createJinkoClient() // picks up env

~/.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',
})

`environment`	Base 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 CLI via 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

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 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.checkout(tripId)`	Schedule checkout, get Stripe URL + `agent_spt_params`
`client.submitAgentPayment(tripId, token)`	Agentic pay: redeem a Shared Payment Token to authorize the booking
`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.destination(req)` / `market(req)` / `audience(req)`	Travel demand rankings by share: top destinations, source markets, traveler audiences
`client.destinationTrend(req)` / `marketTrend(req)` / `audienceTrend(req)` / `trend(req)`	Travel demand time series: destination, market, and audience trends, plus explicit origin and destination pairs (`trend`)
`client.raw`	Escape 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.

Getting started

Guides

Authentication

Connect

Concepts

Install

Quick start

Authentication

OAuth tokens

Environments (prod / sandbox)

The returned client

Error handling

Observability

Method reference

Next steps

Booking guide

API reference

Authentication

Errors

​Install

​Quick start

​Authentication

​OAuth tokens

​Environments (prod / sandbox)

​The returned client

​Error handling

​Observability

​Method reference

​Next steps

Booking guide

API reference

Authentication

Errors

Install

Quick start

Authentication

OAuth tokens

Environments (prod / sandbox)

The returned client

Error handling

Observability

Method reference

Next steps