@gojinko/api-client

Typed API client for the Jinko BFF. 6 methods matching MCP tools 1:1.

Install

npm install @gojinko/api-client

Quick Start

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

// Uses credentials from ~/.jinko/config.yaml or JINKO_API_KEY env
const client = await createJinkoClient();

// Or pass an API key directly
const client = await createJinkoClient({ apiKey: 'jnk_...' });

Authentication

The client resolves credentials automatically in this order:

1. apiKey option passed to createJinkoClient()
2. JINKO_API_KEY environment variable
3. ~/.jinko/config.yaml — API key or OAuth tokens

OAuth tokens are set up via the CLI (jinko auth login) and refreshed automatically when they expire.

Config file

# ~/.jinko/config.yaml

# API key auth
api_key: jnk_your_key

# OR OAuth auth (managed by `jinko auth login`, don't edit manually)
oauth:
  access_token: eyJhbGci...
  refresh_token: re_abc...
  expires_at: 1711036800000

6 Tools

| Method | MCP Tool | Mode | BFF Endpoint | |--------|----------|------|--------------| | client.findFlight() | find_flight | Cached | POST /flights/search | | client.findDestination() | find_destination | Cached | POST /flights/destination-search | | client.flightCalendar() | flight_calendar | Cached | POST /flights/search | | client.flightSearch() | flight_search | Live | POST /flights/shop | | client.trip() | trip | Live | POST /trips | | client.book() | book | Live | POST /trips/checkout |

Usage

find_flight — Cached search

const flights = await client.findFlight({
  passengers: { adt: 1 },
  filters: {
    locations: { origins: ['PAR'], destinations: ['NYC'] },
    dates: { departure_dates: ['2026-06-15'] },
    trip_type: 'oneway',
  },
  sort: 'lowest',
  limit: 10,
});
// → itineraries with offer_token

find_destination — Discover destinations

const destinations = await client.findDestination({
  passengers: { adt: 1 },
  filters: {
    locations: { origins: ['PAR'] },
    trip_type: 'oneway',
  },
  limit: 20,
});

flight_calendar — Price calendar

const calendar = await client.flightCalendar({
  passengers: { adt: 1 },
  filters: {
    locations: { origins: ['PAR'], destinations: ['NYC'] },
    dates: { departure_date_ranges: [{ start: '2026-06-01', end: '2026-06-30' }] },
    trip_type: 'oneway',
  },
  sort: 'lowest',
});

flight_search — Live search / price-check

// Search mode
const results = await client.flightSearch({
  origin: 'PAR',
  destination: 'NYC',
  departure_date: '2026-06-15',
  trip_type: 'oneway',
  passengers: { adults: 1 },
});

// Price-check mode (returns trip_item_token)
const fares = await client.flightSearch({
  offer_token: 'tok_abc123',
  passengers: { adults: 1 },
});

trip — Create trip, add flight, set travelers

const trip = await client.trip({
  add_item: { trip_item_token: 'tok_xyz' },
  upsert_travelers: {
    travelers: [{
      first_name: 'John',
      last_name: 'Doe',
      date_of_birth: '1990-01-15',
      gender: 'MALE',
      passenger_type: 'ADULT',
    }],
    contact: { email: '[email protected]', phone: '+33612345678' },
  },
});
// → { trip_id, status, items, travelers, actions_performed }

book — Checkout

const checkout = await client.book({ trip_id: '42' });
// → { checkout_url, session_id, status }

Token Flow

findFlight / findDestination / flightCalendar → offer_token     (cached)
flightSearch (with offer_token)               → trip_item_token  (live)
trip (with trip_item_token + travelers)       → trip_id
book (with trip_id)                           → checkout_url

Error Handling

import { createJinkoClient, ApiError, AuthError } from '@gojinko/api-client';

try {
  const client = await createJinkoClient();
} catch (error) {
  if (error instanceof AuthError) {
    // No credentials configured — run `jinko auth login`
  }
  if (error instanceof ApiError) {
    console.error(error.code, error.message, error.statusCode);
  }
}

Types

import type {
  FlightFindRequest,
  FlightDestinationSearchRequest,
  FlightSearchRequest,
  FlightSearchLiveRequest,
  FlightSearchPriceCheckRequest,
  TripRequest,
  CheckoutRequest,
  Traveler,
  Contact,
} from '@gojinko/api-client';

Raw Client

The underlying openapi-fetch client is still accessible:

const response = await client.raw.POST('/api/v1/devplatform/flights/shop' as never, {
  body: { ... },
} as never);