@autoapicom/client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AUTO-API.COM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# auto-api-client-typescript
+
+[![npm version](https://img.shields.io/npm/v/@auto-api/client)](https://npmjs.com/package/@auto-api/client)
+[![Node version](https://img.shields.io/node/v/@auto-api/client)](https://npmjs.com/package/@auto-api/client)
+[![License](https://img.shields.io/npm/l/@auto-api/client)](LICENSE)
+
+TypeScript client for the [auto-api.com](https://auto-api.com) car listings API. Zero dependencies — uses the built-in `fetch`.
+
+Search and filter offers across 8 marketplaces (encar, mobile.de, autoscout24, che168, dongchedi, guazi, dubicars, dubizzle), track price changes, pull individual listings by ID or URL.
+
+## Installation
+
+```bash
+npm install @auto-api/client
+```
+
+## Usage
+
+```typescript
+import { Client } from '@auto-api/client';
+
+const client = new Client('your-api-key');
+```
+
+### Get filters
+
+```typescript
+const filters = await client.getFilters('encar');
+```
+
+### Search offers
+
+```typescript
+const offers = await client.getOffers('mobilede', {
+    page: 1,
+    brand: 'BMW',
+    year_from: 2020,
+});
+
+// Pagination
+console.log(offers.meta.page);
+console.log(offers.meta.next_page);
+```
+
+### Get single offer
+
+```typescript
+const offer = await client.getOffer('encar', '40427050');
+```
+
+### Track changes
+
+```typescript
+const changeId = await client.getChangeId('encar', '2025-01-15');
+const changes = await client.getChanges('encar', changeId);
+
+// Next batch
+const nextBatch = await client.getChanges('encar', changes.meta.next_change_id);
+```
+
+### Get offer by URL
+
+```typescript
+const info = await client.getOfferByUrl('https://encar.com/dc/dc_cardetailview.do?carid=40427050');
+```
+
+### Error handling
+
+```typescript
+import { Client, AuthError, ApiError } from '@auto-api/client';
+
+try {
+    const offers = await client.getOffers('encar', { page: 1 });
+} catch (e) {
+    if (e instanceof AuthError) {
+        // 401/403 — invalid API key
+    } else if (e instanceof ApiError) {
+        console.log(e.statusCode);
+        console.log(e.message);
+    }
+}
+```
+
+## Supported sources
+
+| Source | Platform | Region |
+|--------|----------|--------|
+| `encar` | [encar.com](https://encar.com) | South Korea |
+| `mobilede` | [mobile.de](https://mobile.de) | Germany |
+| `autoscout24` | [autoscout24.com](https://autoscout24.com) | Europe |
+| `che168` | [che168.com](https://che168.com) | China |
+| `dongchedi` | [dongchedi.com](https://dongchedi.com) | China |
+| `guazi` | [guazi.com](https://guazi.com) | China |
+| `dubicars` | [dubicars.com](https://dubicars.com) | UAE |
+| `dubizzle` | [dubizzle.com](https://dubizzle.com) | UAE |
+
+## Other languages
+
+| Language | Package |
+|----------|---------|
+| PHP | [auto-api/client](https://github.com/autoapicom/auto-api-php) |
+| Python | [auto-api-client](https://github.com/autoapicom/auto-api-python) |
+| Go | [auto-api-go](https://github.com/autoapicom/auto-api-go) |
+| C# | [AutoApi.Client](https://github.com/autoapicom/auto-api-dotnet) |
+| Java | [auto-api-client](https://github.com/autoapicom/auto-api-java) |
+| Ruby | [auto-api-client](https://github.com/autoapicom/auto-api-ruby) |
+| Rust | [auto-api-client](https://github.com/autoapicom/auto-api-rust) |
+
+## Documentation
+
+[auto-api.com](https://auto-api.com)

package/dist/client.d.ts

@@ -0,0 +1,39 @@
+export declare class Client {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly apiVersion;
+    private readonly timeout;
+    constructor(apiKey: string, baseUrl?: string, apiVersion?: string);
+    /**
+     * Available filters for a source (brands, models, body types, etc.)
+     */
+    getFilters(source: string): Promise<Record<string, unknown>>;
+    /**
+     * List of offers with pagination and filters.
+     *
+     * Params: page (required), brand, model, configuration, complectation,
+     * transmission, color, body_type, engine_type, year_from, year_to,
+     * mileage_from, mileage_to, price_from, price_to
+     */
+    getOffers(source: string, params?: Record<string, string | number>): Promise<Record<string, unknown>>;
+    /**
+     * Single offer by inner_id.
+     */
+    getOffer(source: string, innerId: string): Promise<Record<string, unknown>>;
+    /**
+     * Get change_id by date (format: yyyy-mm-dd).
+     */
+    getChangeId(source: string, date: string): Promise<number>;
+    /**
+     * Changes feed (added/changed/removed) starting from change_id.
+     */
+    getChanges(source: string, changeId: number): Promise<Record<string, unknown>>;
+    /**
+     * Get offer data by its URL on the marketplace.
+     */
+    getOfferByUrl(url: string): Promise<Record<string, unknown>>;
+    private get;
+    private post;
+    private decode;
+    private handleError;
+}

package/dist/client.js

@@ -0,0 +1,112 @@
+import { ApiError, AuthError } from './errors.js';
+export class Client {
+    apiKey;
+    baseUrl;
+    apiVersion;
+    timeout;
+    constructor(apiKey, baseUrl = 'https://auto-api.com', apiVersion = 'v2') {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+        this.apiVersion = apiVersion;
+        this.timeout = 30000;
+    }
+    /**
+     * Available filters for a source (brands, models, body types, etc.)
+     */
+    async getFilters(source) {
+        return this.get(`api/${this.apiVersion}/${source}/filters`);
+    }
+    /**
+     * List of offers with pagination and filters.
+     *
+     * Params: page (required), brand, model, configuration, complectation,
+     * transmission, color, body_type, engine_type, year_from, year_to,
+     * mileage_from, mileage_to, price_from, price_to
+     */
+    async getOffers(source, params = {}) {
+        return this.get(`api/${this.apiVersion}/${source}/offers`, params);
+    }
+    /**
+     * Single offer by inner_id.
+     */
+    async getOffer(source, innerId) {
+        return this.get(`api/${this.apiVersion}/${source}/offer`, { inner_id: innerId });
+    }
+    /**
+     * Get change_id by date (format: yyyy-mm-dd).
+     */
+    async getChangeId(source, date) {
+        const response = await this.get(`api/${this.apiVersion}/${source}/change_id`, { date });
+        return response.change_id;
+    }
+    /**
+     * Changes feed (added/changed/removed) starting from change_id.
+     */
+    async getChanges(source, changeId) {
+        return this.get(`api/${this.apiVersion}/${source}/changes`, { change_id: changeId });
+    }
+    /**
+     * Get offer data by its URL on the marketplace.
+     */
+    async getOfferByUrl(url) {
+        return this.post('api/v1/offer/info', { url });
+    }
+    async get(endpoint, params = {}) {
+        const query = new URLSearchParams();
+        query.set('api_key', this.apiKey);
+        for (const [key, value] of Object.entries(params)) {
+            query.set(key, String(value));
+        }
+        const url = `${this.baseUrl}/${endpoint}?${query.toString()}`;
+        const response = await fetch(url, {
+            method: 'GET',
+            signal: AbortSignal.timeout(this.timeout),
+        });
+        if (!response.ok) {
+            await this.handleError(response);
+        }
+        return this.decode(response);
+    }
+    async post(endpoint, data) {
+        const url = `${this.baseUrl}/${endpoint}`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+            },
+            body: JSON.stringify(data),
+            signal: AbortSignal.timeout(this.timeout),
+        });
+        if (!response.ok) {
+            await this.handleError(response);
+        }
+        return this.decode(response);
+    }
+    async decode(response) {
+        const text = await response.text();
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new ApiError(`Invalid JSON response: ${text.slice(0, 200)}`, response.status);
+        }
+    }
+    async handleError(response) {
+        let body;
+        let message = `API error: ${response.status} ${response.statusText}`;
+        try {
+            body = await response.json();
+            if (body && typeof body === 'object' && 'message' in body) {
+                message = body.message;
+            }
+        }
+        catch {
+            // Response body is not JSON
+        }
+        if (response.status === 401 || response.status === 403) {
+            throw new AuthError(message, response.status);
+        }
+        throw new ApiError(message, response.status, body);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+export declare class ApiError extends Error {
+    readonly statusCode: number;
+    readonly responseBody: unknown;
+    constructor(message: string, statusCode: number, responseBody?: unknown);
+}
+export declare class AuthError extends ApiError {
+    constructor(message?: string, statusCode?: number);
+}

package/dist/errors.js

@@ -0,0 +1,16 @@
+export class ApiError extends Error {
+    statusCode;
+    responseBody;
+    constructor(message, statusCode, responseBody) {
+        super(message);
+        this.name = 'ApiError';
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+    }
+}
+export class AuthError extends ApiError {
+    constructor(message = 'Invalid or missing API key', statusCode = 401) {
+        super(message, statusCode);
+        this.name = 'AuthError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Client } from './client.js';
+export { ApiError, AuthError } from './errors.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Client } from './client.js';
+export { ApiError, AuthError } from './errors.js';

package/package.json

@@ -0,0 +1,53 @@
+{
+    "name": "@autoapicom/client",
+    "version": "1.0.0",
+    "description": "Auto-api.com client for Node.js — fetch car listings from encar, mobile.de, autoscout24 and 5 other sources",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "tsc"
+    },
+    "keywords": [
+        "auto-api",
+        "api-client",
+        "car-listings",
+        "encar",
+        "mobile-de",
+        "autoscout24",
+        "typescript-api-client",
+        "car-auction",
+        "scraper",
+        "encar api",
+        "mobile.de api",
+        "autoscout24 api",
+        "che168 api",
+        "dongchedi api",
+        "guazi api",
+        "dubicars api",
+        "dubizzle api"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/autoapicom/auto-api-node.git"
+    },
+    "homepage": "https://auto-api.com",
+    "author": "AUTO-API.COM <access@auto-api.com>",
+    "license": "MIT",
+    "devDependencies": {
+        "typescript": "^5.0.0"
+    }
+}