@gojinko/plugin 0.4.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "jinko",
+  "description": "Search flights, book trips, and manage bookings with the Jinko Travel API. Connects to the Jinko MCP server for live flight pricing, trip management, and payment.",
+  "version": "0.4.0",
+  "author": {
+    "name": "Jinko",
+    "url": "https://gojinko.com"
+  },
+  "homepage": "https://builders.gojinko.com",
+  "repository": "https://github.com/gojinko/jinko-dev-tools",
+  "license": "MIT",
+  "keywords": ["travel", "flights", "booking", "mcp"]
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,30 @@
+{
+  "name": "jinko",
+  "description": "Search flights, book trips, and manage bookings with the Jinko Travel API. Connects to the Jinko MCP server for live flight pricing, trip management, and payment.",
+  "version": "0.4.0",
+  "author": {
+    "name": "Jinko",
+    "url": "https://gojinko.com"
+  },
+  "homepage": "https://builders.gojinko.com",
+  "repository": "https://github.com/gojinko/jinko-dev-tools",
+  "license": "MIT",
+  "keywords": ["travel", "flights", "booking", "mcp"],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Jinko Travel",
+    "shortDescription": "Flight search, booking, and trip management",
+    "longDescription": "Search flights, compare prices, book trips with ancillaries, and manage refunds using the Jinko Travel API. Supports live pricing from multiple airlines via Sabre and TravelFusion.",
+    "developerName": "Jinko",
+    "category": "Productivity",
+    "capabilities": ["Interactive", "Write"],
+    "websiteURL": "https://gojinko.com",
+    "defaultPrompt": [
+      "Find the cheapest flights from Paris to New York next month",
+      "Book a round-trip flight from London to Tokyo",
+      "Check my API usage and remaining quota"
+    ],
+    "brandColor": "#2563EB"
+  }
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "jinko": {
+      "url": "https://mcp.builders.gojinko.com/mcp",
+      "bearer_token_env_var": "JINKO_API_KEY"
+    }
+  }
+}

package/README.md

@@ -0,0 +1,60 @@
+# Jinko Travel Plugin
+
+Plugin for **Claude Code** and **OpenAI Codex** that enables flight search, trip booking, and booking management via the Jinko Travel API.
+
+## What's included
+
+- **4 skills**: search-flights, book-trip, manage-booking, account
+- **MCP server config**: connects to `mcp.builders.gojinko.com`
+- **Dual-platform support**: works with both Claude Code and Codex CLI
+
+## Setup
+
+### 1. Get an API key
+
+Sign up at [builders.gojinko.com](https://builders.gojinko.com) and create an API key from the dashboard.
+
+### 2. Set your API key
+
+```bash
+export JINKO_API_KEY=jnk_your_key_here
+```
+
+Or add it to your shell profile (`~/.zshrc`, `~/.bashrc`).
+
+### 3. Install the plugin
+
+**Claude Code:**
+```bash
+claude plugin install @gojinko/plugin
+```
+
+**Codex CLI:**
+```bash
+codex plugin install @gojinko/plugin
+```
+
+## Available skills
+
+| Skill | Description | Example prompt |
+|-------|-------------|---------------|
+| `jinko:search-flights` | Find flights, explore destinations, compare prices | "Find flights from Paris to Tokyo in June" |
+| `jinko:book-trip` | Book a flight with travelers and payment | "Book the cheapest flight and pay" |
+| `jinko:manage-booking` | Check refund eligibility and process refunds | "Can I get a refund on booking ORD-123?" |
+| `jinko:account` | Manage API keys and check usage | "How many API calls do I have left?" |
+
+## Authentication
+
+The plugin supports two auth methods:
+
+- **API Key**: Set `JINKO_API_KEY` environment variable with your `jnk_*` key
+- **OAuth**: If no API key is set, Codex will auto-discover OAuth and prompt you to sign in via browser
+
+## MCP server
+
+The plugin connects to the Jinko MCP server at:
+```
+https://mcp.builders.gojinko.com/mcp
+```
+
+This is the same server used by the Jinko CLI (`@gojinko/cli`) and SDK (`@gojinko/api-client`).

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@gojinko/plugin",
+  "version": "0.4.0",
+  "description": "Jinko Travel plugin for Claude Code and OpenAI Codex — flight search, booking, and trip management via MCP",
+  "private": false,
+  "license": "MIT",
+  "author": "Jinko <dev@gojinko.com>",
+  "homepage": "https://builders.gojinko.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gojinko/jinko-dev-tools",
+    "directory": "packages/plugin"
+  },
+  "files": [
+    ".claude-plugin/",
+    ".codex-plugin/",
+    "skills/",
+    ".mcp.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/account/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: account
+description: Manage your Jinko developer account — register, create and revoke API keys, check usage quotas. Use when the user asks about their API key, usage limits, or account setup.
+---
+
+# Developer Account
+
+Manage your Jinko developer platform account using the `dev_account` MCP tool.
+
+## Actions
+
+### Register — create a new account
+
+```json
+{
+  "action": "register",
+  "email": "dev@example.com",
+  "name": "Jane Developer"
+}
+```
+
+New accounts start in `pending` status until approved. `email` is required, `name` is optional.
+
+### List API keys
+
+```json
+{
+  "action": "list_keys"
+}
+```
+
+Returns all keys with `id`, `name`, `prefix`, `status`, `key_type`, and `rate_limit`. Full key values are never shown after creation.
+
+### Create a new API key
+
+```json
+{
+  "action": "create_key",
+  "key_name": "my-project-key"
+}
+```
+
+**The full API key is only shown once in the response.** Tell the user to save it immediately — it cannot be retrieved later. Keys use the `jnk_` prefix.
+
+### Revoke an API key
+
+```json
+{
+  "action": "delete_key",
+  "key_id": 42
+}
+```
+
+`key_id` is the numeric ID from `list_keys`. This is irreversible — confirm with the user before proceeding.
+
+### Check usage
+
+```json
+{
+  "action": "usage"
+}
+```
+
+Returns `used`, `limit`, `remaining`, and `resets_at` for the current billing period.
+
+## Getting started
+
+If the user doesn't have a Jinko account yet, guide them through:
+
+1. `register` with their email
+2. Wait for account approval (or direct them to [builders.gojinko.com](https://builders.gojinko.com))
+3. `create_key` to get an API key
+4. Set `JINKO_API_KEY=jnk_...` in their environment

package/skills/book-trip/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: book-trip
+description: Book a flight trip end-to-end — live pricing, traveler details, ancillaries, and payment via the Jinko Travel API. Use when the user wants to book, price-check, or pay for a flight.
+---
+
+# Book a Trip
+
+Complete booking flow using Jinko MCP tools. Each step depends on the previous — do not skip steps.
+
+## Booking Flow
+
+```
+flight_search → trip (add_item) → trip (upsert_travelers) → trip (select_ancillaries) → book (quote) → book (fulfillment) → book (confirm_payment)
+```
+
+## Step 1: Get live pricing — `flight_search`
+
+Two modes (use exactly one):
+
+**Direct search** (user has route + dates):
+```json
+{
+  "search": {
+    "origin": "PAR",
+    "destination": "NYC",
+    "departure_date": "2026-06-15",
+    "return_date": "2026-06-22",
+    "cabin_class": "economy",
+    "direct_only": false
+  },
+  "passengers": { "adults": 1, "children": 0, "infants": 0 }
+}
+```
+
+**Price-check** (user has an `offer_token` from search-flights):
+```json
+{
+  "price_check": {
+    "offer_token": "es-abc123..."
+  }
+}
+```
+
+**Response:** Flights with fare options. Each fare includes a `trip_item_token`. If status is `"flight_unavailable"`, show alternatives — do NOT proceed to booking.
+
+**Rules:**
+- Origin and destination must differ
+- Departure date must be in the future
+- Infants cannot exceed adults
+- Total passengers max 9
+
+## Step 2: Create trip — `trip` with `add_item`
+
+```json
+{
+  "add_item": {
+    "trip_item_token": "<from flight_search fare>"
+  }
+}
+```
+
+Returns `trip_id`. Save it for all subsequent steps.
+
+## Step 3: Set travelers — `trip` with `upsert_travelers`
+
+**Never fabricate traveler data. Always ask the user for real passenger details.**
+
+```json
+{
+  "trip_id": "<from step 2>",
+  "upsert_travelers": {
+    "travelers": [
+      {
+        "first_name": "John",
+        "last_name": "Doe",
+        "date_of_birth": "1990-01-15",
+        "gender": "MALE",
+        "passenger_type": "ADULT"
+      }
+    ],
+    "contact": {
+      "email": "john@example.com",
+      "phone": "+33612345678"
+    }
+  }
+}
+```
+
+**Traveler fields:**
+- `first_name`, `last_name`: as on travel document (required)
+- `date_of_birth`: YYYY-MM-DD (required)
+- `gender`: `"MALE"` or `"FEMALE"` (required)
+- `passenger_type`: `"ADULT"` (12+), `"CHILD"` (2-11), `"INFANT"` (under 2) (required)
+- `nationality`, `passport_number`, `passport_expiry`, `passport_country`: optional
+
+**Contact:** `email` is required, `phone` is optional.
+
+## Step 4 (optional): Add ancillaries — `trip` with `select_ancillaries`
+
+Check the trip response from step 3 for `available_ancillaries` on each trip item. If available, offer them to the user.
+
+```json
+{
+  "trip_id": "<trip_id>",
+  "select_ancillaries": {
+    "item_id": "<trip item id>",
+    "selections": [
+      {
+        "offer_id": "<ancillary offer_id>",
+        "category": "BAGGAGE",
+        "quantity": 1
+      }
+    ]
+  }
+}
+```
+
+Categories: `BAGGAGE`, `SEAT`, `MEAL`, etc.
+
+## Step 5: Quote — `book` with `quote`
+
+```json
+{
+  "quote": {
+    "trip_id": "<trip_id>"
+  }
+}
+```
+
+Returns final pricing with all items and ancillaries. Trip must have items and travelers set.
+
+## Step 6: Pay — `book` with `fulfillment`
+
+```json
+{
+  "fulfillment": {
+    "trip_id": "<trip_id>"
+  }
+}
+```
+
+Returns `checkout_url` and `session_id`. The user completes payment in their browser at the checkout URL.
+
+## Step 7: Confirm — `book` with `confirm_payment`
+
+After the user completes payment:
+
+```json
+{
+  "confirm_payment": {
+    "trip_id": "<trip_id>",
+    "checkout_session_id": "cs_xxx"
+  }
+}
+```
+
+Or with payment intent:
+```json
+{
+  "confirm_payment": {
+    "trip_id": "<trip_id>",
+    "payment_intent_id": "pi_xxx"
+  }
+}
+```
+
+Returns booking confirmation with `booking_reference`.
+
+## Important rules
+
+- **Never skip steps** — each depends on the previous
+- **Never fabricate traveler data** — always ask the user
+- **If flight_search returns "flight_unavailable"** — do NOT proceed, show alternatives
+- **Sessions expire** — if you get a 404, start over
+- **Rate limit**: 1000 requests/30 days per API key

package/skills/manage-booking/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: manage-booking
+description: Check refund eligibility and process refunds for booked flights via the Jinko Travel API. Use when the user asks about refunds, cancellations, or booking modifications.
+---
+
+# Manage Booking
+
+Post-booking operations using the Jinko `refund_flight` MCP tool.
+
+## Refund Flow
+
+Always check eligibility first, then confirm with the user before committing.
+
+### Step 1: Check eligibility — `refund_flight` with `action: "check"`
+
+```json
+{
+  "action": "check",
+  "booking_reference": "ORD-123456",
+  "pnr": "ABC123"
+}
+```
+
+**Response includes:**
+- `is_refundable`: whether a refund is possible
+- `refund_amount`: estimated refund value and currency
+- `penalty_amount`: cancellation fee if applicable
+- `total_paid`: original payment amount
+- `processing_type`: how the refund will be processed
+
+**Present the refund details clearly to the user** — show what they paid, what they'd get back, and any penalty. Ask for explicit confirmation before proceeding.
+
+### Step 2: Process refund — `refund_flight` with `action: "commit"`
+
+Only after the user confirms:
+
+```json
+{
+  "action": "commit",
+  "booking_reference": "ORD-123456",
+  "pnr": "ABC123",
+  "reason": "schedule change"
+}
+```
+
+**Params:**
+- `booking_reference`: the order ID (required)
+- `pnr`: Passenger Name Record (optional but recommended)
+- `reason`: why the user wants a refund (only for commit)
+
+## Important rules
+
+- **Always check before committing** — never skip the eligibility check
+- **Get user confirmation** — show refund amount and penalty before processing
+- **Non-refundable bookings** — if `is_refundable` is false, inform the user and do not attempt commit

package/skills/search-flights/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: search-flights
+description: Search for flights, explore destinations, and compare prices across dates using the Jinko Travel API. Use when the user wants to find flights, discover where they can fly, or compare prices.
+---
+
+# Flight Search
+
+You have access to three Jinko MCP tools for flight discovery. Pick the right one based on what the user knows:
+
+## Tool Selection
+
+| User knows | Tool to use |
+|-----------|-------------|
+| Nothing — wants inspiration | `find_destination` |
+| Route but flexible on dates | `flight_calendar` |
+| Route + dates | `find_flight` |
+
+## find_destination
+
+Discover destinations from origin airports. Returns destinations sorted by cheapest flight.
+
+**Required params:**
+- `origins`: array of IATA codes (include all nearby airports, e.g. `["JFK", "LGA", "EWR"]` for NYC)
+- `trip_type`: `"oneway"` or `"roundtrip"`
+
+**Optional params:**
+- `destinations`: filter to specific destinations
+- `departure_dates` or `departure_date_ranges`: when to depart
+- `return_dates` or `return_date_ranges`: when to return (roundtrip)
+- `stay_days` or `stay_days_range`: trip duration
+- `direct_only`: nonstop flights only
+- `cabin_class`: `"economy"`, `"premium_economy"`, `"business"`, `"first"`
+- `max_price`: maximum price per person
+- `currency`: ISO 4217 code (default `"USD"`)
+
+**Response:** List of destinations with `destination_code`, `destination_name`, `min_price`, `total_offers`, and `cheapest_offer_token`.
+
+## flight_calendar
+
+Show cheapest prices across a date range for a specific route. Great for "what's the cheapest day to fly?"
+
+**Required params:**
+- `origin`: IATA code (e.g. `"PAR"`)
+- `destination`: IATA code (e.g. `"NYC"`)
+- `trip_type`: `"oneway"` or `"roundtrip"`
+- `departure_date_start`: start of range (YYYY-MM-DD)
+- `departure_date_end`: end of range (YYYY-MM-DD)
+
+**Optional params:**
+- `return_date_start`, `return_date_end`: return range (roundtrip)
+- `stay_days`: exact stay duration
+- `direct_only`, `cabin_class`, `currency`
+
+**Response:** List of dates with `price`, `offer_token`, `airline`, `stops`. Includes `cheapest` entry.
+
+## find_flight
+
+Search cached flights by route and dates. Fast results with offer tokens.
+
+**Required params:**
+- `origin`: IATA code (e.g. `"CDG"`)
+- `destination`: IATA code (e.g. `"JFK"`)
+- `trip_type`: `"oneway"` or `"roundtrip"`
+
+**Optional params:**
+- `departure_dates` or `departure_date_ranges`: when to depart
+- `return_dates` or `return_date_ranges`: when to return (roundtrip)
+- `stay_days` or `stay_days_range`: trip duration
+- `direct_only`, `cabin_class`, `max_price`, `sort_by`, `currency`
+
+**Response:** Flights with `offer_token`, `airline`, `price`, `departure`, `arrival`, `duration_minutes`, `stops`.
+
+## Important notes
+
+- **Airport codes**: Use 3-letter IATA codes (PAR, NYC, JFK, CDG)
+- **Dates**: YYYY-MM-DD format
+- **Cached vs Live**: These tools use cached data (fast). For live pricing, use the `book-trip` skill's `flight_search` tool
+- **offer_token**: Every result includes an `offer_token` — save it for live pricing via `flight_search`
+- All three tools support `format: "json"` for structured output or `format: "text"` for readable summaries