encarapi 1.0.0 → 1.1.1

package/README.md

@@ -1,19 +1,19 @@
 # EnCarAPI: Node.js client for Korean and Chinese used car data
 
-Official **Node.js / TypeScript client** for [EnCarAPI](https://encarapi.com), the REST
+Official **Node.js / TypeScript client** for [EnCarAPI](https://encarapi.com/?utm_source=readme&utm_medium=encarapi-node), 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)
+- **China:** Dongchedi and Che168 in English via [ChinaCarAPI](https://chinacarapi.com/?utm_source=readme&utm_medium=encarapi-node)
   (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)**.
+> **[encarapi.com](https://encarapi.com/?utm_source=readme&utm_medium=encarapi-node)**.
 
 ## Install
 
@@ -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 |
 
@@ -117,10 +128,10 @@ try {
 
 ## Links
 
-- Website and pricing: https://encarapi.com
-- Documentation: https://encarapi.com/documentation
+- Website and pricing: [encarapi.com](https://encarapi.com/?utm_source=readme&utm_medium=encarapi-node)
+- Documentation: [encarapi.com/documentation](https://encarapi.com/documentation?utm_source=readme&utm_medium=encarapi-node)
 - OpenAPI reference: https://api.encarapi.com/reference
-- China data: https://chinacarapi.com
+- China data: [chinacarapi.com](https://chinacarapi.com/?utm_source=readme&utm_medium=encarapi-node)
 - Python client: https://github.com/ThatMojo/encarapi-python
 
 EnCarAPI is an independent service and not affiliated with Encar, KB Chachacha, K Car,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "encarapi",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "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",
@@ -36,7 +36,7 @@
     "car export",
     "vehicle data api"
   ],
-  "homepage": "https://encarapi.com",
+  "homepage": "https://encarapi.com/?utm_source=npm&utm_medium=encarapi-node",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ThatMojo/encarapi-node.git"

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.
@@ -13,7 +16,7 @@ class ChinaClient {
     this.http = new HttpClient({
       apiKey,
       baseUrl: options.baseUrl || "https://api.chinacarapi.com",
-      signupUrl: "https://chinacarapi.com",
+      signupUrl: "https://chinacarapi.com/?utm_source=sdk&utm_medium=encarapi-node&utm_content=error#pricing",
       product: "ChinaCarAPI",
       fetchImpl: options.fetch,
     });
@@ -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>;

package/src/index.js

@@ -23,7 +23,7 @@ class EnCarAPI {
     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"
+          "(Korea) / CHINACARAPI_KEY (China). Get a key at https://encarapi.com/?utm_source=sdk&utm_medium=encarapi-node&utm_content=error"
       );
     }
     this._apiKey = apiKey;
@@ -35,7 +35,7 @@ class EnCarAPI {
   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");
+        throw new EnCarAPIError("An EnCarAPI key is required for Korean data. Get one at https://encarapi.com/?utm_source=sdk&utm_medium=encarapi-node&utm_content=error");
       }
       this._korea = new KoreaClient(this._apiKey, { baseUrl: this._options.baseUrl, fetch: this._options.fetch });
     }
@@ -68,7 +68,7 @@ class ChinaCarAPI extends ChinaClient {
     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"
+          "Get a key at https://chinacarapi.com/?utm_source=sdk&utm_medium=encarapi-node&utm_content=error"
       );
     }
     super(apiKey, options);

package/src/korea.js

@@ -15,7 +15,7 @@ class KoreaClient {
     this.http = new HttpClient({
       apiKey,
       baseUrl: options.baseUrl || "https://api.encarapi.com",
-      signupUrl: "https://encarapi.com",
+      signupUrl: "https://encarapi.com/?utm_source=sdk&utm_medium=encarapi-node&utm_content=error#pricing",
       product: "EnCarAPI",
       fetchImpl: options.fetch,
     });