TypeScript SDK

@gojinko/api-client is the typed Node.js SDK for the Jinko Public API. It provides typed convenience methods for travel operations and a raw client for additional endpoints. Use an API key for new integrations; existing OAuth configuration is also supported.

Install

npm install @gojinko/api-client

Works with Node.js ≥ 20. ESM-only.

Quick start

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

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

const { itineraries } = await client.flightCalendar({
  origins: ['JFK'],
  destinations: ['CDG'],
  origin_type: 'airport',
  destination_type: 'airport',
  trip_type: 'oneway',
  departure_dates: ['2027-06-15'],
})

Authentication

createJinkoClient() resolves auth in this order:

Explicit apiKey option

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

JINKO_API_KEY env var

export JINKO_API_KEY=jnk_t_...

createJinkoClient() // picks up env

~/.jinko/config.yaml (CLI-shared)

The same config file the CLI uses. Run jinko auth login --key jnk_t_... to populate it; your scripts pick it up automatically.

If none of those yield credentials, createJinkoClient() throws AuthError.

Existing OAuth tokens

CLI OAuth login is deprecated. Use an API key for new CLI and SDK setups. If your config already has OAuth tokens, 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_t_...) for programmatic access when you don’t want to maintain OAuth state.

Environments

Pass environment to target the sandbox (isolated data, separate API keys) before going to production:

const client = await createJinkoClient({
  environment: 'sandbox',
  apiKey: 'jnk_sandbox_t_your_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. For a custom endpoint (such as dev/staging), set JINKO_API_BASE and use a key for that endpoint. This env var overrides the base URL even when you pass environment explicitly. Unset JINKO_API_BASE to use the environment URLs above. Sandbox flight tests: use Jinko Airline (ZZ). It is a fake airline that exists only in sandbox: search with include_carriers: ["ZZ"] on a route such as JFK–LHR from tomorrow onwards, and book flight ZZ101 for the normal flow. Every other flight number triggers one documented behaviour, such as a price change, a sold-out booking or a failed ticket, so you can test failure paths on demand. See Testing in sandbox.

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

HTTP failures throw ApiError; inspect statusCode to distinguish them. AuthError reports missing credentials during client setup, not an HTTP 401 response.

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

try {
  await client.flightCalendar({ /* ... */ })
} catch (err) {
  if (err instanceof ApiError) {
    if (err.statusCode === 401) {
      // The server rejected the credentials.
    } else if (err.statusCode === 422) {
      // Inspect err.code and err.details for validation failures.
    } else {
      // Handle other HTTP failures by statusCode and code.
    }
  }
}

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; include it when you report a failure to Jinko
X-User-ID, only set on OAuth, from the JWT sub claim

The SDK sends X-Request-ID but does not log it automatically. After creating client, add this middleware before making requests to record the ID in your application logs:

client.raw.use({
  onRequest({ request }) {
    console.info('Jinko request ID:', request.headers.get('X-Request-ID'))
  },
})

Include the request ID when reporting a problem so we can trace it server-side. Log only the ID, not the full request headers or body.

Method reference

Convenience methods map to REST endpoints. Use the API reference for request and response schemas, and the booking guides for SDK examples. Endpoints without a convenience method are available through client.raw. 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.carSearch(req)`	Live rental car offers; see the car guide
`client.trip(req)`	Create / update trip, items, travelers, ancillaries
`client.getAncillaries(tripId)`	List available ancillaries without a checkout URL
`client.selectAncillaries(req)`	Pre-select bags / seats / meals
`client.getTrip(tripId)`	Inspect trip / quote / fulfillment / bookings
`client.checkout(tripId)`	Price the trip and wait for the quote: returns `quote_id`, the Jinko checkout page (`checkout_url`) and `agent_spt_params`
`client.submitPayment({ tripId, quoteId, payment }, { idempotencyKey })`	Agentic pay: submit a Shared Payment Token against the `quote_id` the traveler approved, with an idempotency key for retries
`client.submitAgentPayment(tripId, token)`	Deprecated: the older form, which pays the trip’s latest valid quote
`client.getBooking(req)`	Guest lookup by booking_ref + last_name
`client.hotelCancelPreview(req)` / `hotelCancelCommit(req)` / `hotelCancelStatus(req)`	Preview, commit and follow a hotel cancellation
`client.hotelCancelBooking(req)`	Deprecated: one-step hotel cancellation
`client.carCancelPreview(req)` / `carCancelCommit(req)`	Preview and commit a car cancellation; see the car guide
`client.flightRefundPreview(req)` / `flightRefundCommit(req)` / `flightRefundStatus(req)`	Preview, commit and follow a flight refund
`client.refundCheck(req)` / `refundCommit(req)` / `refundStatus(req)`	Deprecated: the older refund flow
`client.exchangeShop(req)` / `exchangePrice(req)` / `exchangeCommit(req)` / `exchangeStatus(req)`	Exchange flow
`client.demandDestination(req)` / `demandMarket(req)` / `demandAudience(req)`	Travel demand rankings by share: top destinations, source markets, traveler audiences
`client.demandDestinationTrend(req)` / `demandMarketTrend(req)` / `demandAudienceTrend(req)` / `demandTrend(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 and response schemas. See the booking guides for SDK and CLI examples.

Next steps

Booking guide

End-to-end booking flow in TypeScript, CLI, and MCP.

API reference

Per-endpoint request and response schemas.

Authentication

API keys, OAuth flows, and when to use each.

Errors

Status codes, error envelope, and debugging.

Getting started

Guides

Marketing claim

Authentication

Connect

Developer Platform

Concepts

Install

Quick start

Authentication

Existing OAuth tokens

Environments

The returned client

Error handling

Observability

Method reference

Next steps

Booking guide

API reference

Authentication

Errors

​Install

​Quick start

​Authentication

​Existing OAuth tokens

​Environments

​The returned client

​Error handling

​Observability

​Method reference

​Next steps

Booking guide

API reference

Authentication

Errors

Install

Quick start

Authentication

Existing OAuth tokens

Environments

The returned client

Error handling

Observability

Method reference

Next steps