encarapi 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 EnCarAPI (encarapi.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Note: This MIT license covers the client library only. Access to the EnCarAPI
+service and its data requires a valid API key and is subject to the terms at
+https://encarapi.com.

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# EnCarAPI: Node.js client for Korean and Chinese used car data
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official **Node.js / TypeScript client** for [EnCarAPI](https://encarapi.com), the REST
+**Encar API** and **Korean Car API**. One package for:
+
+- **Korea:** Encar.com, KB Chachacha (`source: "kbc"`) and K Car (`source: "kcar"`), with
+  photos, specs, options, inspection reports, accident and ownership records, condition
+  reports, price history, a change feed and full catalog export.
+- **China:** Dongchedi and Che168 in English via [ChinaCarAPI](https://chinacarapi.com)
+  (separate key or the China add-on for EnCarAPI keys).
+
+Built for car exporters, dealers and marketplaces that need reliable used car data without
+scraping, proxies or geo-blocks.
+
+> **An API key is required.** The data is a paid service. Get a key (5-day trial) at
+> **[encarapi.com](https://encarapi.com)**.
+
+## Install
+
+```bash
+npm install encarapi
+```
+
+Requires Node.js 18+ (uses the global `fetch`). No dependencies. TypeScript types included.
+
+## Quick start
+
+```js
+const { EnCarAPI } = require("encarapi");
+
+const client = new EnCarAPI("YOUR_API_KEY"); // or set ENCARAPI_KEY
+
+// Search Korean listings with flat English filters
+const cars = await client.korea.catalog({
+  manufacturer: "Hyundai",
+  max_mileage: 60000,
+  frame_clean: true,   // accident-free chassis only
+  lang: "en",
+  count: true,
+});
+console.log(cars.Count, cars.SearchResults[0]);
+
+// Full detail, inspection report and insurance record for one car
+const detail = await client.korea.vehicle("12345678");
+const inspection = await client.korea.inspection("12345678");
+const record = await client.korea.record("12345678");
+
+// KB Chachacha and K Car listings, or all three marketplaces deduplicated
+const kbc = await client.korea.catalog({ source: "kbc", limit: 20 });
+const all = await client.korea.catalog({ source: "all", count: true });
+
+// Chinese listings (Dongchedi + Che168)
+const byd = await client.china.catalog({ make: "BYD", export_ready: true, limit: 25 });
+```
+
+## Keep a local copy in sync (Business / Scale)
+
+```js
+// 1) Baseline: full catalog as CSV
+const csv = await client.korea.exportCsv();
+
+// 2) Then follow the change feed; every event arrives exactly once
+for await (const change of client.korea.iterateChanges({ cursor: savedCursor ?? 0 })) {
+  // change.type: "added" | "updated" | "reappeared" | "removed"
+}
+saveCursor(client.korea.lastCursor);
+```
+
+## Korea API (`client.korea`)
+
+| Method | Endpoint | Notes |
+|---|---|---|
+| `catalog(params)` | `GET /api/catalog` | Search & list. `source`: `encar` (default), `kbc`, `kcar`, `all` |
+| `iterateCatalog(params)` | `GET /api/catalog` | Async iterator over all pages |
+| `leasing(params)` | `GET /api/catalog/leasing` | Lease takeovers and rentals |
+| `nav(params)` | `GET /api/nav` | Filter facets with counts |
+| `enums(params)` | `GET /api/enums` | Valid values for the flat filters |
+| `modelSearch(search, params)` | `GET /api/model-search` | Model autocomplete |
+| `vehicle(id)` | `GET /api/vehicle/:id` | Ids: Encar id, `kbc:<id>`, `kcar:<id>` |
+| `inspection(id)` | `GET /api/inspection/:id` | Official inspection report |
+| `record(id)` | `GET /api/record/:id` | Accident & ownership record |
+| `refresh(id)` | `POST /api/vehicle/:id/refresh` | On-demand refresh (daily quota) |
+| `priceCheck(id)` | `GET /api/price-check/:id` | Market estimate (beta, Scale) |
+| `bulkVehicles(ids)` / `bulkInspections(ids)` / `bulkRecords(ids)` | `POST /api/.../bulk` | Up to 500 ids (Business/Scale) |
+| `inspectionVersions(id)` / `recordVersions(id)` | `GET /api/.../versions` | Report history (Business/Scale) |
+| `changes(params)` / `iterateChanges(params)` | `GET /api/catalog/changes` | Incremental sync (Business/Scale) |
+| `exportCsv()` | `GET /api/catalog/export` | Full catalog CSV (Business/Scale) |
+| `makesCsv()` / `modelsCsv()` / `badgesCsv()` | `GET /api/taxonomy/*.csv` | Reference data |
+
+## China API (`client.china`)
+
+| Method | Endpoint | Notes |
+|---|---|---|
+| `catalog(params)` | `GET /api/catalog` | `make`, `price_min/max` (CNY), `export_ready`, `sort`, ... |
+| `vehicle(id)` | `GET /api/vehicle/:id` | Price history, photos, seller, export status |
+| `inspection(id)` | `GET /api/inspection/:id` | Accident, flood and fire checks, EV battery data |
+| `bulkVehicles(ids)` | `POST /api/vehicle/bulk` | Up to 500 ids |
+| `changes(params)` | `GET /api/catalog/changes` | Change feed |
+| `exportCsv()` | `GET /api/catalog/export` | Full catalog CSV |
+| `enums()` / `models(make)` | `GET /api/enums`, `/api/models` | Filter values, models per make |
+
+China only? `const { ChinaCarAPI } = require("encarapi")` (also available as the
+[`chinacarapi`](https://www.npmjs.com/package/chinacarapi) package).
+
+## Errors
+
+Every failed request throws `EnCarAPIError` with `status` and the raw `body`. A `403` on a
+plan-gated endpoint includes an upgrade hint from the API.
+
+```js
+try {
+  await client.korea.changes({ cursor: 0 });
+} catch (e) {
+  if (e.status === 403) console.log("Plan does not include this endpoint:", e.body);
+}
+```
+
+## Links
+
+- Website and pricing: https://encarapi.com
+- Documentation: https://encarapi.com/documentation
+- OpenAPI reference: https://api.encarapi.com/reference
+- China data: https://chinacarapi.com
+- Python client: https://github.com/ThatMojo/encarapi-python
+
+EnCarAPI is an independent service and not affiliated with Encar, KB Chachacha, K Car,
+Dongchedi or Che168.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "encarapi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Official Node.js client for EnCarAPI: Korean used car data (Encar, KB Chachacha, K Car) and Chinese used car data (Dongchedi, Che168) in one REST API.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node test/smoke.js",
+    "test:live": "node test/smoke.js --live"
+  },
+  "keywords": [
+    "encar",
+    "encar api",
+    "encar.com",
+    "kbchacha",
+    "kb chachacha",
+    "kcar",
+    "k car",
+    "korean car api",
+    "korea car api",
+    "korean used car data",
+    "china car api",
+    "chinese used car data",
+    "che168",
+    "dongchedi",
+    "car export",
+    "vehicle data api"
+  ],
+  "homepage": "https://encarapi.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThatMojo/encarapi-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ThatMojo/encarapi-node/issues"
+  },
+  "author": "EnCarAPI (https://encarapi.com)",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/china.js

@@ -0,0 +1,50 @@
+"use strict";
+
+const { HttpClient } = require("./http");
+
+const enc = encodeURIComponent;
+
+/**
+ * Chinese used-car data (Dongchedi and Che168) in English. Works with a
+ * ChinaCarAPI key or an EnCarAPI key that has the China add-on.
+ */
+class ChinaClient {
+  constructor(apiKey, options = {}) {
+    this.http = new HttpClient({
+      apiKey,
+      baseUrl: options.baseUrl || "https://api.chinacarapi.com",
+      signupUrl: "https://chinacarapi.com",
+      product: "ChinaCarAPI",
+      fetchImpl: options.fetch,
+    });
+  }
+
+  /** Search listings. Filters: source, make, model, year_min/max, price_min/max (CNY), mileage_max, city, fuel, has_report, export_ready, sort, page, limit, lang. */
+  catalog(params) { return this.http.request("GET", "/api/catalog", { params }); }
+
+  /** Full record for one car: price history, photos, seller, export status, alsoListedOn. */
+  vehicle(id, params) { return this.http.request("GET", `/api/vehicle/${enc(id)}`, { params }); }
+
+  /** Inspection report: accident, flood and fire checks, battery data for EVs. */
+  inspection(id, params) { return this.http.request("GET", `/api/inspection/${enc(id)}`, { params }); }
+
+  /** Up to 500 full records in one call (Business/Scale). */
+  bulkVehicles(ids, params) { return this.http.request("POST", "/api/vehicle/bulk", { params, body: { ids } }); }
+
+  /** Alias of bulkVehicles (name used by the standalone chinacarapi 0.x client). */
+  bulk(ids, params) { return this.bulkVehicles(ids, params); }
+
+  /** Change feed: { since } once, then { cursor: nextCursor } (Business/Scale). */
+  changes(params) { return this.http.request("GET", "/api/catalog/changes", { params }); }
+
+  /** Full catalog as CSV text (Business/Scale). */
+  exportCsv(params) { return this.http.request("GET", "/api/catalog/export", { params, text: true }); }
+
+  /** Filter values with counts: makes, fuels, cities, sources, sorts. */
+  enums(params) { return this.http.request("GET", "/api/enums", { params }); }
+
+  /** Models of one make (id or English name) with counts. */
+  models(make) { return this.http.request("GET", "/api/models", { params: { make } }); }
+}
+
+module.exports = { ChinaClient };

package/src/http.js

@@ -0,0 +1,65 @@
+"use strict";
+
+class EnCarAPIError extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.name = "EnCarAPIError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/**
+ * Minimal fetch wrapper shared by the Korea and China clients. Sends the API key
+ * as `x-api-key`, drops undefined/null params, and turns 401/403 into an error
+ * that carries the server message (which includes upgrade hints for plan-gated
+ * endpoints) plus a link to the signup page.
+ */
+class HttpClient {
+  constructor({ apiKey, baseUrl, signupUrl, product, fetchImpl }) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.signupUrl = signupUrl;
+    this.product = product;
+    this.fetch = fetchImpl || (typeof fetch === "function" ? fetch.bind(globalThis) : null);
+    if (!this.fetch) {
+      throw new EnCarAPIError("Global fetch is not available: Node.js 18+ is required (or pass options.fetch).");
+    }
+  }
+
+  async request(method, path, { params, body, text } = {}) {
+    const url = new URL(this.baseUrl + path);
+    for (const [k, v] of Object.entries(params || {})) {
+      if (v === undefined || v === null) continue;
+      url.searchParams.set(k, Array.isArray(v) ? v.join(",") : String(v));
+    }
+    const res = await this.fetch(url, {
+      method,
+      headers: {
+        "x-api-key": this.apiKey,
+        Accept: text ? "text/csv" : "application/json",
+        ...(body ? { "Content-Type": "application/json" } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const raw = await res.text();
+    if (res.status === 401 || res.status === 403) {
+      throw new EnCarAPIError(
+        `${this.product} rejected the request (${res.status}). Check your key or plan at ${this.signupUrl}. Body: ${raw.slice(0, 300)}`,
+        res.status,
+        raw
+      );
+    }
+    if (!res.ok) {
+      throw new EnCarAPIError(`${this.product} error ${res.status}: ${raw.slice(0, 300)}`, res.status, raw);
+    }
+    if (text) return raw;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  }
+}
+
+module.exports = { HttpClient, EnCarAPIError };

package/src/index.d.ts

@@ -0,0 +1,203 @@
+export interface ClientOptions {
+  /** Override the Korea API base URL (default https://api.encarapi.com). */
+  baseUrl?: string;
+  /** Override the China API base URL (default https://api.chinacarapi.com). */
+  chinaBaseUrl?: string;
+  /** Separate key for China data. Defaults to CHINACARAPI_KEY, then the main key. */
+  chinaKey?: string;
+  /** Custom fetch implementation (defaults to global fetch, Node.js 18+). */
+  fetch?: typeof fetch;
+}
+
+export class EnCarAPIError extends Error {
+  /** HTTP status code, if the error came from an API response. */
+  status?: number;
+  /** Raw response body, if any. */
+  body?: string;
+}
+export { EnCarAPIError as ChinaCarAPIError };
+
+type Bool = boolean | "true" | "false";
+type Json = Record<string, any>;
+
+/** Korean data source. Encar is the default; "all" is the deduplicated union. */
+export type KoreaSource = "encar" | "kbc" | "kcar" | "all" | (string & {});
+
+/** Flat English filters for /api/catalog, /api/nav and /api/catalog/leasing. Values from korea.enums() / korea.nav(). */
+export interface KoreaCatalogParams {
+  source?: KoreaSource;
+  manufacturer?: string;
+  model_group?: string;
+  model?: string;
+  badge_group?: string;
+  badge?: string;
+  model_search?: string;
+  fuel?: "gasoline" | "diesel" | "hybrid" | "diesel-hybrid" | "lpg-hybrid" | "gasoline-lpg" | "cng" | "electric" | "lpg" | "hydrogen" | "other";
+  transmission?: "automatic" | "manual" | "cvt" | "semi-automatic" | "other";
+  drivetrain?: string;
+  color?: string;
+  seat_color?: string;
+  category?: "suv" | "rv" | "large" | "midsize" | "compact" | "small" | "kei" | "van" | "light-van" | "truck" | "sports" | "other";
+  seats?: string | number;
+  min_seats?: number;
+  max_seats?: number;
+  /** Equipment codes; the car must have all of them. */
+  options?: string | string[];
+  /** Price in 만원 (1 = 10,000 KRW). */
+  min_price?: number;
+  max_price?: number;
+  min_year?: number;
+  max_year?: number;
+  min_mileage?: number;
+  max_mileage?: number;
+  min_ps?: number;
+  max_ps?: number;
+  max_owners?: number;
+  frame_clean?: Bool;
+  no_damage_cost?: Bool;
+  max_damage_eur?: number;
+  no_repairs?: Bool;
+  has_record?: Bool;
+  has_inspection?: Bool;
+  has_photos?: Bool;
+  usage_change?: string;
+  no_usage_change?: Bool;
+  exclude_prices?: string;
+  exclude_duplicates?: Bool;
+  min_first_seen?: string;
+  /** Raw Encar q-grammar (alternative to the flat filters). */
+  q?: string;
+  lang?: "en";
+  sort?: "newest" | "price_asc" | "price_desc" | "mileage_asc" | "mileage_desc" | "year_desc" | "year_asc";
+  page?: number;
+  limit?: number;
+  count?: Bool;
+}
+
+export interface KoreaCatalogResponse {
+  Count?: number;
+  SearchResults: Json[];
+  [key: string]: any;
+}
+
+export interface KoreaChangesParams {
+  cursor?: number;
+  since?: string;
+  source?: KoreaSource;
+  sell_type?: string;
+  limit?: number;
+  lang?: "en";
+}
+
+export interface KoreaChangesResponse {
+  nextCursor?: number;
+  hasMore?: boolean;
+  truncated?: boolean;
+  added?: Json[];
+  updated?: Json[];
+  reappeared?: Json[];
+  removed?: Json[];
+  [key: string]: any;
+}
+
+export interface KoreaChange extends Json {
+  type: "added" | "updated" | "reappeared" | "removed";
+}
+
+/** Korean used-car data: Encar, KB Chachacha ("kbc") and K Car ("kcar"). */
+export class KoreaClient {
+  constructor(apiKey: string, options?: Pick<ClientOptions, "baseUrl" | "fetch">);
+  /** Cursor to resume from after iterateChanges() finished. */
+  lastCursor?: number;
+  catalog(params?: KoreaCatalogParams): Promise<KoreaCatalogResponse>;
+  leasing(params?: KoreaCatalogParams): Promise<KoreaCatalogResponse>;
+  nav(params?: KoreaCatalogParams): Promise<Json>;
+  enums(params?: { source?: KoreaSource }): Promise<Json>;
+  modelSearch(search: string, params?: { limit?: number; source?: KoreaSource; exclude_duplicates?: Bool; has_photos?: Bool; exclude_prices?: string; min_price?: number }): Promise<Json>;
+  iterateCatalog(params?: KoreaCatalogParams): AsyncGenerator<Json, void, unknown>;
+  /** Ids: Encar id, "kbc:<id>" or "kcar:<id>". */
+  vehicle(id: string, params?: { lang?: "en" }): Promise<Json>;
+  inspection(id: string): Promise<Json>;
+  record(id: string): Promise<Json>;
+  refresh(id: string): Promise<Json>;
+  /** Beta, Scale plan. */
+  priceCheck(id: string): Promise<Json>;
+  inspectionVersions(id: string): Promise<Json>;
+  recordVersions(id: string): Promise<Json>;
+  bulkVehicles(ids: string[]): Promise<Json>;
+  bulkInspections(ids: string[]): Promise<Json>;
+  bulkRecords(ids: string[]): Promise<Json>;
+  changes(params: KoreaChangesParams): Promise<KoreaChangesResponse>;
+  iterateChanges(params: KoreaChangesParams): AsyncGenerator<KoreaChange, void, unknown>;
+  /** CSV text. */
+  exportCsv(params?: { source?: KoreaSource }): Promise<string>;
+  makesCsv(params?: { source?: KoreaSource }): Promise<string>;
+  modelsCsv(params?: { source?: KoreaSource }): Promise<string>;
+  badgesCsv(params?: { source?: KoreaSource }): Promise<string>;
+}
+
+export interface ChinaCatalogParams {
+  source?: "dongchedi" | "che168" | (string & {});
+  duplicates?: "include" | (string & {});
+  make?: string;
+  model?: string;
+  year_min?: number;
+  year_max?: number;
+  reg_year_min?: number;
+  reg_year_max?: number;
+  /** Price in CNY. */
+  price_min?: number;
+  price_max?: number;
+  mileage_max?: number;
+  city?: string;
+  fuel?: string;
+  has_report?: Bool;
+  export_ready?: Bool;
+  updated_since?: string;
+  sort?: "newest" | "price_asc" | "price_desc" | "mileage_asc" | "year_desc";
+  page?: number;
+  limit?: number;
+  /** "zh" = original Chinese values. */
+  lang?: "en" | "zh";
+}
+
+export interface ChinaCatalogResponse {
+  total: number;
+  page: number;
+  limit: number;
+  sort?: string;
+  results: Json[];
+}
+
+/** Chinese used-car data: Dongchedi and Che168. */
+export class ChinaClient {
+  constructor(apiKey: string, options?: Pick<ClientOptions, "fetch"> & { baseUrl?: string });
+  catalog(params?: ChinaCatalogParams): Promise<ChinaCatalogResponse>;
+  vehicle(id: string, params?: { lang?: "en" | "zh" }): Promise<Json>;
+  inspection(id: string, params?: { lang?: "en" | "zh" }): Promise<Json>;
+  bulkVehicles(ids: string[], params?: { lang?: "en" | "zh" }): Promise<Json>;
+  /** Alias of bulkVehicles. */
+  bulk(ids: string[], params?: { lang?: "en" | "zh" }): Promise<Json>;
+  changes(params: { since?: string; cursor?: number; source?: string; limit?: number }): Promise<Json>;
+  exportCsv(params?: Json): Promise<string>;
+  enums(params?: Json): Promise<Json>;
+  models(make: string | number): Promise<Json>;
+}
+
+/** One client for both markets. */
+export class EnCarAPI {
+  constructor(apiKey?: string, options?: ClientOptions);
+  readonly korea: KoreaClient;
+  readonly china: ChinaClient;
+  /** Shortcut for korea.catalog (0.x compatible). */
+  catalog(params?: KoreaCatalogParams): Promise<KoreaCatalogResponse>;
+  /** Shortcut for korea.nav (0.x compatible). */
+  nav(params?: KoreaCatalogParams): Promise<Json>;
+  /** Shortcut for korea.vehicle (0.x compatible). */
+  vehicle(id: string, params?: { lang?: "en" }): Promise<Json>;
+}
+
+/** China-only client (also published as the `chinacarapi` package). */
+export class ChinaCarAPI extends ChinaClient {
+  constructor(apiKey?: string, options?: Pick<ClientOptions, "fetch"> & { baseUrl?: string });
+}

package/src/index.js

@@ -0,0 +1,85 @@
+"use strict";
+
+const { EnCarAPIError } = require("./http");
+const { KoreaClient } = require("./korea");
+const { ChinaClient } = require("./china");
+
+/**
+ * Official Node.js client for EnCarAPI: Korean used-car data (Encar, KB Chachacha,
+ * K Car) and Chinese used-car data (Dongchedi, Che168) through one package.
+ *
+ * An API key is REQUIRED. Get one at https://encarapi.com (Korea) or
+ * https://chinacarapi.com (China). EnCarAPI keys with the China add-on work for both.
+ *
+ *   const { EnCarAPI } = require("encarapi");
+ *   const client = new EnCarAPI(process.env.ENCARAPI_KEY);
+ *   const kr = await client.korea.catalog({ manufacturer: "Hyundai", lang: "en", count: true });
+ *   const cn = await client.china.catalog({ make: "BYD", limit: 25 });
+ */
+class EnCarAPI {
+  constructor(apiKey, options = {}) {
+    apiKey = apiKey || process.env.ENCARAPI_KEY;
+    const chinaKey = options.chinaKey || process.env.CHINACARAPI_KEY || apiKey;
+    if (!apiKey && !chinaKey) {
+      throw new EnCarAPIError(
+        "An API key is required. Pass new EnCarAPI('YOUR_KEY') or set ENCARAPI_KEY " +
+          "(Korea) / CHINACARAPI_KEY (China). Get a key at https://encarapi.com"
+      );
+    }
+    this._apiKey = apiKey;
+    this._chinaKey = chinaKey;
+    this._options = options;
+  }
+
+  /** Korean data: Encar (default), KB Chachacha (source "kbc"), K Car (source "kcar"). */
+  get korea() {
+    if (!this._korea) {
+      if (!this._apiKey) {
+        throw new EnCarAPIError("An EnCarAPI key is required for Korean data. Get one at https://encarapi.com");
+      }
+      this._korea = new KoreaClient(this._apiKey, { baseUrl: this._options.baseUrl, fetch: this._options.fetch });
+    }
+    return this._korea;
+  }
+
+  /** Chinese data: Dongchedi and Che168 (ChinaCarAPI key or EnCarAPI key with the China add-on). */
+  get china() {
+    if (!this._china) {
+      this._china = new ChinaClient(this._chinaKey, { baseUrl: this._options.chinaBaseUrl, fetch: this._options.fetch });
+    }
+    return this._china;
+  }
+
+  // Backwards compatible shortcuts from 0.x (Korean catalog).
+  catalog(params) { return this.korea.catalog(params); }
+  nav(params) { return this.korea.nav(params); }
+  vehicle(id, params) { return this.korea.vehicle(id, params); }
+}
+
+/**
+ * China-only entry point (also published as the `chinacarapi` package).
+ *
+ *   const { ChinaCarAPI } = require("encarapi");
+ *   const client = new ChinaCarAPI(process.env.CHINACARAPI_KEY);
+ */
+class ChinaCarAPI extends ChinaClient {
+  constructor(apiKey, options = {}) {
+    apiKey = apiKey || process.env.CHINACARAPI_KEY;
+    if (!apiKey) {
+      throw new EnCarAPIError(
+        "A ChinaCarAPI key is required. Pass new ChinaCarAPI('YOUR_KEY') or set CHINACARAPI_KEY. " +
+          "Get a key at https://chinacarapi.com"
+      );
+    }
+    super(apiKey, options);
+  }
+}
+
+module.exports = {
+  EnCarAPI,
+  ChinaCarAPI,
+  KoreaClient,
+  ChinaClient,
+  EnCarAPIError,
+  ChinaCarAPIError: EnCarAPIError,
+};

package/src/korea.js

@@ -0,0 +1,123 @@
+"use strict";
+
+const { HttpClient } = require("./http");
+
+const enc = encodeURIComponent;
+
+/**
+ * Korean used-car data: Encar plus KB Chachacha (`source: "kbc"`) and K Car
+ * (`source: "kcar"`). Encar is the default source; pass `source: "all"` for the
+ * deduplicated union. Endpoints marked Business/Scale return 403 with an upgrade
+ * hint on smaller plans.
+ */
+class KoreaClient {
+  constructor(apiKey, options = {}) {
+    this.http = new HttpClient({
+      apiKey,
+      baseUrl: options.baseUrl || "https://api.encarapi.com",
+      signupUrl: "https://encarapi.com",
+      product: "EnCarAPI",
+      fetchImpl: options.fetch,
+    });
+  }
+
+  // -- search ----------------------------------------------------------------
+
+  /** Search & list vehicles. Flat English filters, e.g. { manufacturer: "BMW", max_mileage: 50000, lang: "en" }. */
+  catalog(params) { return this.http.request("GET", "/api/catalog", { params }); }
+
+  /** Lease-takeover and rental listings (same filters as catalog). */
+  leasing(params) { return this.http.request("GET", "/api/catalog/leasing", { params }); }
+
+  /** Filter facets with counts (the navigation tree). */
+  nav(params) { return this.http.request("GET", "/api/nav", { params }); }
+
+  /** Valid filter values for the flat parameters. */
+  enums(params) { return this.http.request("GET", "/api/enums", { params }); }
+
+  /** Model autocomplete across brands. */
+  modelSearch(search, params) { return this.http.request("GET", "/api/model-search", { params: { ...params, search } }); }
+
+  /** Async iterator over all catalog pages: for await (const car of korea.iterateCatalog({...})) {} */
+  async *iterateCatalog(params = {}) {
+    const limit = params.limit || 100;
+    for (let page = params.page || 1; ; page++) {
+      const res = await this.catalog({ ...params, limit, page });
+      const items = res.SearchResults || [];
+      for (const item of items) yield item;
+      if (items.length < limit) return;
+    }
+  }
+
+  // -- one vehicle -------------------------------------------------------------
+
+  /** Full vehicle detail. Ids: Encar id, "kbc:<id>" or "kcar:<id>". */
+  vehicle(id, params) { return this.http.request("GET", `/api/vehicle/${enc(id)}`, { params }); }
+
+  /** Official inspection report (성능점검). */
+  inspection(id) { return this.http.request("GET", `/api/inspection/${enc(id)}`); }
+
+  /** Insurance accident & ownership record. */
+  record(id) { return this.http.request("GET", `/api/record/${enc(id)}`); }
+
+  /** Ask for a fresh copy of one listing (daily quota per plan). */
+  refresh(id) { return this.http.request("POST", `/api/vehicle/${enc(id)}/refresh`); }
+
+  /** Price check (beta, Scale): below / in line with / above the market. */
+  priceCheck(id) { return this.http.request("GET", `/api/price-check/${enc(id)}`); }
+
+  /** Inspection report versions (Business/Scale). */
+  inspectionVersions(id) { return this.http.request("GET", `/api/inspection/${enc(id)}/versions`); }
+
+  /** Insurance record versions (Business/Scale). */
+  recordVersions(id) { return this.http.request("GET", `/api/record/${enc(id)}/versions`); }
+
+  // -- bulk & sync (Business/Scale) ---------------------------------------------
+
+  /** Up to 500 vehicle details in one call. */
+  bulkVehicles(ids) { return this.http.request("POST", "/api/vehicle/bulk", { body: { ids } }); }
+
+  /** Up to 500 inspection reports in one call. */
+  bulkInspections(ids) { return this.http.request("POST", "/api/inspection/bulk", { body: { ids } }); }
+
+  /** Up to 500 insurance records in one call. */
+  bulkRecords(ids) { return this.http.request("POST", "/api/record/bulk", { body: { ids } }); }
+
+  /** Incremental change feed: { cursor } from the previous call, or { since } right after an export. */
+  changes(params) { return this.http.request("GET", "/api/catalog/changes", { params }); }
+
+  /**
+   * Follows the change feed until it is drained and yields every change once as
+   * { type: "added" | "updated" | "reappeared" | "removed", ...item }. Pass
+   * { since } (right after an export) or { cursor } to start; after the loop,
+   * `korea.lastCursor` holds the cursor to resume from next time.
+   */
+  async *iterateChanges(params = {}) {
+    let query = { ...params };
+    for (;;) {
+      const res = await this.changes(query);
+      for (const type of ["added", "updated", "reappeared", "removed"]) {
+        for (const item of res[type] || []) yield { type, ...item };
+      }
+      if (res.nextCursor !== undefined) this.lastCursor = res.nextCursor;
+      if (!(res.hasMore || res.truncated) || res.nextCursor === undefined) return;
+      query = { ...params, since: undefined, cursor: res.nextCursor };
+    }
+  }
+
+  /** Full catalog as CSV text. */
+  exportCsv(params) { return this.http.request("GET", "/api/catalog/export", { params, text: true }); }
+
+  // -- reference data -------------------------------------------------------------
+
+  /** All makes as CSV. */
+  makesCsv(params) { return this.http.request("GET", "/api/taxonomy/makes.csv", { params, text: true }); }
+
+  /** All models as CSV. */
+  modelsCsv(params) { return this.http.request("GET", "/api/taxonomy/models.csv", { params, text: true }); }
+
+  /** All badges (trims) as CSV. */
+  badgesCsv(params) { return this.http.request("GET", "/api/taxonomy/badges.csv", { params, text: true }); }
+}
+
+module.exports = { KoreaClient };