encarapi 1.1.1 → 1.2.0

package/README.md

@@ -82,7 +82,9 @@ 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 |
 | `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 +96,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.2.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,17 @@ 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;
@@ -77,6 +84,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 +126,10 @@ 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>;
   /** Ids: Encar id, "kbc:<id>" or "kcar:<id>". */
   vehicle(id: string, params?: { lang?: "en" }): Promise<Json>;
   inspection(id: string): Promise<Json>;
@@ -130,7 +145,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,6 +49,32 @@ 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);
+  }
+
+  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>". */
@@ -105,7 +131,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 -------------------------------------------------------------