encarapi 1.0.0 → 1.1.0

package/README.md

@@ -66,6 +66,16 @@ for await (const change of client.korea.iterateChanges({ cursor: savedCursor ??
 saveCursor(client.korea.lastCursor);
 ```
 
+The China API works the same way (`client.china`); its events are
+`{ id, source, vehicleId, type: "new" | "price" | "removed" | "relisted", oldPrice, newPrice, at }`:
+
+```js
+for await (const change of client.china.iterateChanges({ cursor: savedCursor ?? 0 })) {
+  // change.type: "new" | "price" | "removed" | "relisted"
+}
+saveCursor(client.china.lastCursor);
+```
+
 ## Korea API (`client.korea`)
 
 | Method | Endpoint | Notes |
@@ -92,10 +102,11 @@ saveCursor(client.korea.lastCursor);
 | Method | Endpoint | Notes |
 |---|---|---|
 | `catalog(params)` | `GET /api/catalog` | `make`, `price_min/max` (CNY), `export_ready`, `sort`, ... |
+| `iterateCatalog(params)` | `GET /api/catalog` | Async iterator over all pages (up to the 10,000-result depth limit) |
 | `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 |
+| `changes(params)` / `iterateChanges(params)` | `GET /api/catalog/changes` | Change feed (Business/Scale) |
 | `exportCsv()` | `GET /api/catalog/export` | Full catalog CSV |
 | `enums()` / `models(make)` | `GET /api/enums`, `/api/models` | Filter values, models per make |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "encarapi",
-  "version": "1.0.0",
+  "version": "1.1.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/china.js

@@ -4,6 +4,9 @@ const { HttpClient } = require("./http");
 
 const enc = encodeURIComponent;
 
+// /api/catalog serves at most this many results per query (page * limit).
+const CATALOG_DEPTH = 10000;
+
 /**
  * Chinese used-car data (Dongchedi and Che168) in English. Works with a
  * ChinaCarAPI key or an EnCarAPI key that has the China add-on.
@@ -22,6 +25,21 @@ class ChinaClient {
   /** 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 }); }
 
+  /**
+   * Async iterator over all catalog pages: for await (const car of china.iterateCatalog({...})) {}
+   * Stops at the API's 10,000-result depth limit; for the whole catalog use
+   * exportCsv() plus iterateChanges().
+   */
+  async *iterateCatalog(params = {}) {
+    const limit = Math.min(params.limit || 100, 100);
+    for (let page = params.page || 1; ; page++) {
+      const res = await this.catalog({ ...params, limit, page });
+      const items = res.results || [];
+      for (const item of items) yield item;
+      if (items.length < limit || (page + 1) * limit > CATALOG_DEPTH) return;
+    }
+  }
+
   /** 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 }); }
 
@@ -37,6 +55,23 @@ class ChinaClient {
   /** Change feed: { since } once, then { cursor: nextCursor } (Business/Scale). */
   changes(params) { return this.http.request("GET", "/api/catalog/changes", { params }); }
 
+  /**
+   * Follows the change feed until it is drained and yields every event once:
+   * { id, source, vehicleId, type: "new" | "price" | "removed" | "relisted", oldPrice, newPrice, at }.
+   * Pass { since } (right after an export) or { cursor } to start; after the loop,
+   * `china.lastCursor` holds the cursor to resume from next time.
+   */
+  async *iterateChanges(params = {}) {
+    let query = { ...params };
+    for (;;) {
+      const res = await this.changes(query);
+      for (const item of res.changes || []) yield item;
+      if (res.nextCursor !== undefined) this.lastCursor = res.nextCursor;
+      if (!res.hasMore || res.nextCursor === undefined) return;
+      query = { ...params, since: undefined, cursor: res.nextCursor };
+    }
+  }
+
   /** Full catalog as CSV text (Business/Scale). */
   exportCsv(params) { return this.http.request("GET", "/api/catalog/export", { params, text: true }); }
 

package/src/index.d.ts

@@ -169,16 +169,45 @@ export interface ChinaCatalogResponse {
   results: Json[];
 }
 
+export interface ChinaChangesParams {
+  /** ISO timestamp for the first call. */
+  since?: string;
+  /** nextCursor from the previous call. */
+  cursor?: number;
+  source?: "dongchedi" | "che168" | (string & {});
+  limit?: number;
+}
+
+export interface ChinaChange extends Json {
+  id: number;
+  source: string;
+  vehicleId: string;
+  type: "new" | "price" | "removed" | "relisted";
+  at: string;
+}
+
+export interface ChinaChangesResponse {
+  cursor: number;
+  nextCursor: number;
+  hasMore: boolean;
+  changes: ChinaChange[];
+}
+
 /** Chinese used-car data: Dongchedi and Che168. */
 export class ChinaClient {
   constructor(apiKey: string, options?: Pick<ClientOptions, "fetch"> & { baseUrl?: string });
+  /** Cursor to resume from after iterateChanges() finished. */
+  lastCursor?: number;
   catalog(params?: ChinaCatalogParams): Promise<ChinaCatalogResponse>;
-  vehicle(id: string, params?: { lang?: "en" | "zh" }): Promise<Json>;
-  inspection(id: string, params?: { lang?: "en" | "zh" }): Promise<Json>;
+  /** All pages up to the API's 10,000-result depth limit. */
+  iterateCatalog(params?: ChinaCatalogParams): AsyncGenerator<Json, void, unknown>;
+  vehicle(id: string, params?: { source?: "dongchedi" | "che168"; lang?: "en" | "zh" }): Promise<Json>;
+  inspection(id: string, params?: { source?: "dongchedi" | "che168"; 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>;
+  changes(params: ChinaChangesParams): Promise<ChinaChangesResponse>;
+  iterateChanges(params: ChinaChangesParams): AsyncGenerator<ChinaChange, void, unknown>;
   exportCsv(params?: Json): Promise<string>;
   enums(params?: Json): Promise<Json>;
   models(make: string | number): Promise<Json>;