encarapi 1.1.1 → 1.3.0

package/README.md

@@ -82,7 +82,18 @@ saveCursor(client.china.lastCursor);
 |---|---|---|
 | `catalog(params)` | `GET /api/catalog` | Search & list. `source`: `encar` (default), `kbc`, `kcar`, `all` |
 | `iterateCatalog(params)` | `GET /api/catalog` | Async iterator over all pages |
+| `iterateCatalogById(params)` | `GET /api/catalog?sort=id` | Complete, stable traversal (keyset cursor, nothing repeated or skipped) |
 | `leasing(params)` | `GET /api/catalog/leasing` | Lease takeovers and rentals |
+| `iterateLeasingById(params)` | `GET /api/catalog/leasing?sort=id` | Complete, stable traversal of lease/rental listings |
+| `vehicleByVin(vin)` | `GET /api/vehicle/by-vin/{vin}` | All listings of one VIN incl. removed ones (Business/Scale) |
+| `trucks(params)` | `GET /api/catalog/trucks` | Trucks, buses and special vehicles (Business/Scale) |
+| `truckEnums()` | `GET /api/catalog/trucks/enums` | Truck filter values with counts |
+| `trucksCsv()` | `GET /api/catalog/trucks/export` | Full truck inventory CSV (Business/Scale) |
+| `iterateTrucksById(params)` | `GET /api/catalog/trucks?sort=id` | Complete, stable traversal of the truck catalog |
+| `equipment(params)` | `GET /api/catalog/equipment` | Used excavators (Business/Scale) |
+| `equipmentEnums()` | `GET /api/catalog/equipment/enums` | Equipment filter values with counts |
+| `equipmentCsv()` | `GET /api/catalog/equipment/export` | Full equipment inventory CSV (Business/Scale) |
+| `iterateEquipmentById(params)` | `GET /api/catalog/equipment?sort=id` | Complete, stable traversal of the equipment catalog |
 | `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 |
@@ -94,7 +105,7 @@ saveCursor(client.china.lastCursor);
 | `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) |
+| `exportCsv(params)` | `GET /api/catalog/export` | Full catalog CSV (Business/Scale); `{ sell_type: "lease,rental" }` for lease/rental |
 | `makesCsv()` / `modelsCsv()` / `badgesCsv()` | `GET /api/taxonomy/*.csv` | Reference data |
 
 ## China API (`client.china`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "encarapi",
-  "version": "1.1.1",
+  "version": "1.3.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",

package/src/index.d.ts

@@ -65,10 +65,69 @@ export interface KoreaCatalogParams {
   exclude_prices?: string;
   exclude_duplicates?: Bool;
   min_first_seen?: string;
+  /** Region codes, comma = OR (seoul, gyeonggi, busan, ...). Encar listings only for now. */
+  region?: string;
+  /** Cities, comma = OR: value from korea.enums().city (e.g. "suwon"), English or Korean name. Encar only. */
+  city?: string;
+  /** Keyset cursor for sort "id": nextAfter of the previous response. */
+  after?: 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";
+  /** "id" = stable listing-id order; page with `after` (see iterateCatalogById). */
+  sort?: "newest" | "price_asc" | "price_desc" | "mileage_asc" | "mileage_desc" | "year_desc" | "year_asc" | "id";
+  page?: number;
+  limit?: number;
+  count?: Bool;
+}
+
+/** Filters for /api/catalog/trucks. Values from korea.truckEnums(). */
+export interface KoreaTruckParams {
+  form?: "cargo" | "wing_body" | "bus" | "dump_construction" | "crane" | "tank" | "camper" | "waste_transport" | "live_fish" | "tow_transport" | "tractor" | "trailer" | (string & {});
+  manufacturer?: string;
+  /** Substring of the Korean model name, e.g. "포터". */
+  model?: string;
+  min_tons?: number;
+  max_tons?: number;
+  use?: "private" | "commercial" | "other";
+  fuel?: string;
+  transmission?: string;
+  color?: string;
+  min_price?: number;
+  max_price?: number;
+  min_year?: number;
+  max_year?: number;
+  min_mileage?: number;
+  max_mileage?: number;
+  region?: string;
+  sort?: "newest" | "price_asc" | "price_desc" | "mileage_asc" | "mileage_desc" | "year_desc" | "year_asc" | "id";
+  after?: string;
+  page?: number;
+  limit?: number;
+  count?: Bool;
+  lang?: "en";
+}
+
+/** Filters for /api/catalog/equipment. Values from korea.equipmentEnums(). */
+export interface KoreaEquipmentParams {
+  maker?: string;
+  model?: string;
+  sub_type?: "crawler" | "wheel" | (string & {});
+  /** e.g. "EXC_CR_LE_6_5" (02 class crawler). */
+  weight_class?: string;
+  min_year?: number;
+  max_year?: number;
+  min_hours?: number;
+  max_hours?: number;
+  /** Price in 만원 (10,000 KRW). */
+  min_price?: number;
+  max_price?: number;
+  has_price?: Bool;
+  /** "sell" (default), "buy", "rent", a comma list or "all". */
+  deal_type?: string;
+  region?: string;
+  sort?: "newest" | "price_asc" | "price_desc" | "hours_asc" | "year_desc" | "year_asc" | "id";
+  after?: string;
   page?: number;
   limit?: number;
   count?: Bool;
@@ -77,6 +136,10 @@ export interface KoreaCatalogParams {
 export interface KoreaCatalogResponse {
   Count?: number;
   SearchResults: Json[];
+  /** Only with sort "id": pass as `after` for the next page; null on the last page. */
+  nextAfter?: string | null;
+  /** Only with sort "id": true while more pages follow. */
+  hasMore?: boolean;
   [key: string]: any;
 }
 
@@ -115,6 +178,28 @@ export class KoreaClient {
   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>;
+  /** Complete, stable traversal (sort=id + after): nothing repeated or skipped while the catalog changes. */
+  iterateCatalogById(params?: KoreaCatalogParams): AsyncGenerator<Json, void, unknown>;
+  /** iterateCatalogById() for lease-takeover and rental listings. */
+  iterateLeasingById(params?: KoreaCatalogParams): AsyncGenerator<Json, void, unknown>;
+  /** Encar trucks, buses and special vehicles (Business/Scale). */
+  trucks(params?: KoreaTruckParams): Promise<KoreaCatalogResponse>;
+  /** Every Encar / K Car listing of one VIN, active and removed (Business/Scale). */
+  vehicleByVin(vin: string): Promise<Json>;
+  /** Valid truck filter values with counts. */
+  truckEnums(): Promise<Json>;
+  /** Full truck inventory as CSV text (Business/Scale). */
+  trucksCsv(params?: { compress?: Bool }): Promise<string>;
+  /** Complete, stable traversal of the truck catalog (sort=id + after). */
+  iterateTrucksById(params?: KoreaTruckParams): AsyncGenerator<Json, void, unknown>;
+  /** Used excavators from 굴삭기나라 (Business/Scale). */
+  equipment(params?: KoreaEquipmentParams): Promise<KoreaCatalogResponse>;
+  /** Valid equipment filter values with counts. */
+  equipmentEnums(): Promise<Json>;
+  /** Full equipment inventory as CSV text (Business/Scale). */
+  equipmentCsv(params?: { compress?: Bool }): Promise<string>;
+  /** Complete, stable traversal of the equipment catalog (sort=id + after). */
+  iterateEquipmentById(params?: KoreaEquipmentParams): 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>;
@@ -130,7 +215,8 @@ export class KoreaClient {
   changes(params: KoreaChangesParams): Promise<KoreaChangesResponse>;
   iterateChanges(params: KoreaChangesParams): AsyncGenerator<KoreaChange, void, unknown>;
   /** CSV text. */
-  exportCsv(params?: { source?: KoreaSource }): Promise<string>;
+  /** sell_type: "sale" (default), "lease", "rental", a comma list or "all". */
+  exportCsv(params?: { source?: KoreaSource; sell_type?: string }): Promise<string>;
   makesCsv(params?: { source?: KoreaSource }): Promise<string>;
   modelsCsv(params?: { source?: KoreaSource }): Promise<string>;
   badgesCsv(params?: { source?: KoreaSource }): Promise<string>;

package/src/korea.js

@@ -49,11 +49,72 @@ class KoreaClient {
     }
   }
 
+  /**
+   * Complete, stable traversal via sort=id + after (keyset cursor): rows never
+   * shift between pages while the catalog changes, so nothing is repeated or
+   * skipped. Yields every matching listing once, in listing-id order.
+   * for await (const car of korea.iterateCatalogById({ manufacturer: "BMW" })) {}
+   */
+  async *iterateCatalogById(params = {}) {
+    yield* this._iterateById("/api/catalog", params);
+  }
+
+  /** Same as iterateCatalogById() for lease-takeover and rental listings. */
+  async *iterateLeasingById(params = {}) {
+    yield* this._iterateById("/api/catalog/leasing", params);
+  }
+
+  // -- trucks, buses, special vehicles (Business/Scale) ----------------------
+
+  /** Encar trucks & buses: { form: "cargo", max_tons: 1, lang: "en" }. Values from truckEnums(). */
+  trucks(params) { return this.http.request("GET", "/api/catalog/trucks", { params }); }
+
+  /** Valid truck filter values with counts (form, use, fuel, transmission, color, manufacturer, capacity_tons, region). */
+  truckEnums() { return this.http.request("GET", "/api/catalog/trucks/enums"); }
+
+  /** Full truck inventory as CSV text (Business/Scale). */
+  trucksCsv(params) { return this.http.request("GET", "/api/catalog/trucks/export", { params, text: true }); }
+
+  /** Complete, stable traversal of the truck catalog (sort=id + after). */
+  async *iterateTrucksById(params = {}) {
+    yield* this._iterateById("/api/catalog/trucks", params);
+  }
+
+  // -- construction equipment / excavators (Business/Scale) -----------------
+
+  /** Used excavators from 굴삭기나라: { sub_type: "crawler", max_hours: 5000 }. Values from equipmentEnums(). */
+  equipment(params) { return this.http.request("GET", "/api/catalog/equipment", { params }); }
+
+  /** Valid equipment filter values with counts (maker, sub_type, weight_class, deal_type, region). */
+  equipmentEnums() { return this.http.request("GET", "/api/catalog/equipment/enums"); }
+
+  /** Full equipment inventory as CSV text (Business/Scale). */
+  equipmentCsv(params) { return this.http.request("GET", "/api/catalog/equipment/export", { params, text: true }); }
+
+  /** Complete, stable traversal of the equipment catalog (sort=id + after). */
+  async *iterateEquipmentById(params = {}) {
+    yield* this._iterateById("/api/catalog/equipment", params);
+  }
+
+  async *_iterateById(path, params) {
+    const { page, ...rest } = params;
+    let query = { ...rest, sort: "id", limit: params.limit || 1000 };
+    for (;;) {
+      const res = await this.http.request("GET", path, { params: query });
+      for (const item of res.SearchResults || []) yield item;
+      if (!res.hasMore || !res.nextAfter) return;
+      query = { ...query, after: res.nextAfter };
+    }
+  }
+
   // -- 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 }); }
 
+  /** Every Encar / K Car listing of one VIN, active and removed (Business/Scale). */
+  vehicleByVin(vin) { return this.http.request("GET", `/api/vehicle/by-vin/${enc(vin)}`); }
+
   /** Official inspection report (성능점검). */
   inspection(id) { return this.http.request("GET", `/api/inspection/${enc(id)}`); }
 
@@ -105,7 +166,10 @@ class KoreaClient {
     }
   }
 
-  /** Full catalog as CSV text. */
+  /**
+   * Full catalog as CSV text. { sell_type: "lease,rental" } for the lease/rental
+   * inventory, { source: "kbc" } etc. for other marketplaces.
+   */
   exportCsv(params) { return this.http.request("GET", "/api/catalog/export", { params, text: true }); }
 
   // -- reference data -------------------------------------------------------------