encarapi 1.1.0 → 1.2.0

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
 
@@ -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`)
@@ -128,10 +130,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.1.0",
+  "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",
@@ -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

@@ -16,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,
     });

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/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,
     });
@@ -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 -------------------------------------------------------------