@meterapp/car-image-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meter
+
+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,141 @@
+# @meterapp/car-image-sdk
+
+TypeScript SDK for the **Car Image API** by Meter — studio-quality, transparent-background renders of any vehicle in the open [`@meterapp/vehicle-db`](https://github.com/MeterApp/vehicle-db) catalog (1,145 makes, 14,841 models, model years 1990–2026).
+
+- Zero runtime dependencies. Works in Node 20+, Vercel/Cloudflare edge runtimes, Deno, Bun and browsers.
+- Typed parameters and responses for every endpoint.
+- `CarImageError` carries `status`, `title`, `detail`, `requestId` and the raw RFC 9457 problem.
+- Automatic retries with full jitter on `429`/`503` (honoring `Retry-After`); never retries `402`.
+- Shared MCP tool definitions (`@meterapp/car-image-sdk/mcp`) used by both the stdio and the remote MCP servers.
+
+```bash
+npm install @meterapp/car-image-sdk
+```
+
+## Pricing in one line
+
+Every delivered image costs **1 credit** whether it comes from cache or is freshly generated. **$1 = 1,000 credits**, every account starts with **100 free credits**, there is no subscription. Signed delivery URLs cost 1 credit when created; loading them is free.
+
+Get a key at <https://car-imgs.vercel.app/dashboard> or run `npx @meterapp/car-image login`.
+
+## Quickstart (Node)
+
+```ts
+import { CarImageClient } from "@meterapp/car-image-sdk";
+import { writeFile } from "node:fs/promises";
+
+const client = new CarImageClient({ apiKey: process.env.CAR_IMAGE_API_KEY });
+
+const image = await client.getImage({
+  make: "Porsche",
+  model: "911",
+  year: 2024,
+  view: "front-3-4", // front | front-3-4 | side | side-right | rear | rear-3-4
+  color: "red",      // 15 presets: white black gray silver blue red green brown beige tan orange yellow gold burgundy purple
+  size: "medium",    // thumb=256 small=512 medium=768 large=1024 (or width/height up to 1024)
+  format: "png",     // png | webp | jpg
+});
+
+await writeFile("porsche-911.png", image.bytes);
+console.log(image.source, image.creditsCharged, image.creditsRemaining, image.requestId);
+```
+
+`apiKey` and `baseUrl` fall back to `CAR_IMAGE_API_KEY` / `CAR_IMAGE_API_URL` when running on a server.
+
+## Next.js route handler
+
+Keep the key on the server; hand the browser signed URLs.
+
+```ts
+// app/api/car-image/route.ts
+import { CarImageClient, CarImageError } from "@meterapp/car-image-sdk";
+
+const client = new CarImageClient({ apiKey: process.env.CAR_IMAGE_API_KEY });
+
+export async function POST(request: Request) {
+  const { make, model, year } = await request.json();
+  try {
+    const { data } = await client.createImageUrls([{ make, model, year, view: "side" }], {
+      ttlSeconds: 24 * 60 * 60, // 1 minute to 7 days
+      maxUses: 0,               // 0 = unlimited redemptions until expiry
+    });
+    return Response.json({ url: data[0].url, expiresAt: data[0].expires_at });
+  } catch (error) {
+    if (error instanceof CarImageError) {
+      return Response.json({ error: error.detail, requestId: error.requestId }, { status: error.status });
+    }
+    throw error;
+  }
+}
+```
+
+## Browser
+
+Never ship the API key to a browser. Create signed URLs server-side (above) and use them like any image:
+
+```html
+<img src="https://car-imgs.vercel.app/api/v1/delivery/…" alt="2024 Porsche 911, side view" />
+```
+
+The SDK itself is browser-safe (no Node APIs), which is useful for public endpoints such as `options()`, `vehicles()` and `searchVehicles()` that need no key.
+
+## Everything else
+
+```ts
+await client.getImageUrl(params);                       // 1 credit, returns a signed URL instead of bytes
+await client.options();                                 // views, colors, sizes, formats, pricing, catalog coverage
+await client.resolve("red 2024 porsche 911 side view"); // free text -> { make, model, year, view, color } + candidates
+await client.vehicles();                                // years
+await client.vehicles({ year: 2024 });                  // makes for a year
+await client.vehicles({ year: 2024, makeId: 7 });       // models for a year + make
+await client.searchVehicles("porshe 911", { limit: 5 }); // fuzzy catalog search
+await client.feedback({ requestId, verdict: "good" });  // or { make, model, year, rating: 4, reason }
+await client.account();                                 // credits, auto-reload, usage_30d, key scopes
+await client.createCheckout(5000);                      // hosted Stripe Checkout URL (scope billing:write)
+await client.billingPortal();                           // Stripe Customer Portal URL
+await client.health();                                  // { status: "ok" | "degraded", checks }
+await client.openapi();                                 // the OpenAPI 3.1 document
+await client.fetch("/api/v1/account");                  // authenticated raw fetch (same-origin only)
+```
+
+## Error handling
+
+All failures throw `CarImageError`:
+
+```ts
+import { CarImageError } from "@meterapp/car-image-sdk";
+
+try {
+  await client.getImage({ make: "Porsche", model: "911", year: 2024 });
+} catch (error) {
+  if (error instanceof CarImageError) {
+    error.status;           // 400 | 401 | 402 | 404 | 429 | 502 | 0 (network)
+    error.title;            // "Insufficient credits"
+    error.detail;           // "This request needs 1 credit; balance is 0"
+    error.requestId;        // "0d1e…" — quote this when contacting support
+    error.problem;          // the raw application/problem+json body (402 includes balance, required_credits)
+    error.retryAfterSeconds; // set on 429
+    if (error.isInsufficientCredits) {
+      // Send a human to https://car-imgs.vercel.app/billing — never buy credits automatically.
+    }
+  }
+}
+```
+
+Retries: `429` and `503` are retried up to `maxRetries` (default 2) with full-jitter exponential backoff, honoring `Retry-After`. Network failures are retried for `GET` only, so a `POST` is never duplicated. Configure with `new CarImageClient({ maxRetries, retryBaseDelayMs, maxRetryDelayMs, timeoutMs })` or per call via `{ retries }`.
+
+## MCP tool definitions
+
+`@meterapp/car-image-sdk/mcp` exports the tool names, zod input schemas, descriptions, annotations and the server instructions shared by the `car-image mcp` stdio server and the remote server at `https://car-imgs.vercel.app/api/mcp`. It needs `zod` (an optional peer dependency); the main entry point does not.
+
+```ts
+import { MCP_TOOLS, MCP_INSTRUCTIONS, formatApiReference } from "@meterapp/car-image-sdk/mcp";
+```
+
+## Types
+
+`View`, `Color`, `Size`, `Format`, `ImageParams`, `ImageResult`, `CreateImageUrlsResponse`, `OptionsResponse`, `ResolveResponse`, `VehicleSearchResponse`, `AccountResponse`, … plus the constant arrays `VIEWS`, `COLORS`, `SIZES`, `FORMATS`.
+
+## License
+
+MIT © Meter

package/dist/client.d.ts

@@ -0,0 +1,113 @@
+import { type AccountResponse, type CheckoutResponse, type CreateImageUrlsOptions, type CreateImageUrlsResponse, type DeviceCodeResponse, type DeviceTokenResult, type FeedbackInput, type FeedbackResponse, type FetchLike, type HealthResponse, type ImageParams, type ImageResult, type ImageUrlResponse, type OpenApiDocument, type OptionsResponse, type PortalResponse, type ResolveResponse, type TelemetryEvent, type VehicleMakesResponse, type VehicleModelsResponse, type VehicleSearchResponse, type VehicleYearsResponse } from "./types.js";
+export interface CarImageClientOptions {
+    /** `cimg_…` key. Falls back to `process.env.CAR_IMAGE_API_KEY` when running on a server. */
+    apiKey?: string;
+    /** API origin; defaults to `process.env.CAR_IMAGE_API_URL` or https://car-imgs.vercel.app. */
+    baseUrl?: string;
+    /** Custom fetch (tests, polyfills, instrumentation). Defaults to `globalThis.fetch`. */
+    fetch?: FetchLike;
+    /** Sent as `User-Agent` (ignored by browsers). Defaults to `car-image-sdk/<version>`. */
+    userAgent?: string;
+    /** Retries on 429/503 (and network failures for GET). Default 2; 0 disables. */
+    maxRetries?: number;
+    /** Base for exponential backoff with full jitter. Default 500 ms. */
+    retryBaseDelayMs?: number;
+    /** Upper bound for any single wait, including `Retry-After`. Default 30 000 ms. */
+    maxRetryDelayMs?: number;
+    /** Per-attempt timeout. Unset by default. */
+    timeoutMs?: number;
+    /** Sleep implementation; injectable for tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface RequestOptions {
+    signal?: AbortSignal;
+    /** Overrides the client-wide `maxRetries` for this call. */
+    retries?: number;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
+/**
+ * Client for the Car Image API. Safe for Node 20+, edge runtimes and browsers
+ * (in browsers, prefer signed delivery URLs created server-side so the API key
+ * never ships to the client).
+ */
+export declare class CarImageClient {
+    readonly baseUrl: string;
+    readonly userAgent: string;
+    readonly maxRetries: number;
+    readonly retryBaseDelayMs: number;
+    readonly maxRetryDelayMs: number;
+    readonly timeoutMs: number | undefined;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly sleep;
+    constructor(options?: CarImageClientOptions);
+    /** Whether a key is configured; the key itself is never exposed. */
+    get hasApiKey(): boolean;
+    /** Display form such as `cimg_A1b2…9zY`; never logs the full key. */
+    maskedApiKey(): string | null;
+    /** Keeps the key out of `JSON.stringify(client)`, logs and error reports. */
+    toJSON(): Record<string, unknown>;
+    /** GET /api/v1/images/car — 1 credit; returns the bytes plus billing headers. */
+    getImage(params: ImageParams, options?: RequestOptions): Promise<ImageResult>;
+    /** GET /api/v1/images/car with `Accept: application/json` — 1 credit; returns a signed URL. */
+    getImageUrl(params: ImageParams, options?: RequestOptions): Promise<ImageUrlResponse>;
+    /**
+     * POST /api/v1/image-urls — 1 credit per URL, charged at creation. Up to 50
+     * images per call. Redemptions are free within the TTL.
+     */
+    createImageUrls(images: ImageParams | ImageParams[], options?: CreateImageUrlsOptions & RequestOptions): Promise<CreateImageUrlsResponse>;
+    /** GET /api/v1/images/options — public; views, colors, sizes, formats, pricing, catalog. */
+    options(options?: RequestOptions): Promise<OptionsResponse>;
+    /** POST /api/v1/images/resolve — free; turns "red 2024 porsche 911 side view" into parameters. */
+    resolve(query: string, options?: RequestOptions): Promise<ResolveResponse>;
+    /** GET /api/v1/vehicles — public. No filter: years; `year`: makes; `year`+`makeId`: models. */
+    vehicles(filter?: Record<string, never>, options?: RequestOptions): Promise<VehicleYearsResponse>;
+    vehicles(filter: {
+        year: number;
+    }, options?: RequestOptions): Promise<VehicleMakesResponse>;
+    vehicles(filter: {
+        year: number;
+        makeId: number;
+    }, options?: RequestOptions): Promise<VehicleModelsResponse>;
+    /** GET /api/v1/vehicles?q= — public fuzzy search across makes and models. */
+    searchVehicles(query: string, options?: {
+        limit?: number;
+        year?: number;
+    } & RequestOptions): Promise<VehicleSearchResponse>;
+    /** POST /api/v1/feedback — free; rate a delivered image by request id or by vehicle. */
+    feedback(input: FeedbackInput, options?: RequestOptions): Promise<FeedbackResponse>;
+    /** GET /api/v1/account — credits, auto-reload, 30-day usage, key scopes. */
+    account(options?: RequestOptions): Promise<AccountResponse>;
+    /** POST /api/v1/billing/checkout — hosted Stripe Checkout URL (scope billing:write). */
+    createCheckout(credits: number, options?: RequestOptions): Promise<CheckoutResponse>;
+    /** POST /api/v1/billing/portal — Stripe Customer Portal URL (scope billing:write). */
+    billingPortal(options?: RequestOptions): Promise<PortalResponse>;
+    /** GET /api/health — public. */
+    health(options?: RequestOptions): Promise<HealthResponse>;
+    /** GET /openapi.json — public machine-readable contract. */
+    openapi(options?: RequestOptions): Promise<OpenApiDocument>;
+    /** POST /api/auth/device/code — start browser-assisted login (public). */
+    startDeviceLogin(input?: {
+        clientName?: string;
+    }, options?: RequestOptions): Promise<DeviceCodeResponse>;
+    /** POST /api/auth/device/token — one poll; returns pending/expired/approved without throwing. */
+    pollDeviceLogin(deviceCode: string, options?: RequestOptions): Promise<DeviceTokenResult>;
+    /** POST /api/v1/events — anonymous telemetry; public, never retried. */
+    trackEvents(events: TelemetryEvent[], options?: RequestOptions): Promise<void>;
+    /**
+     * Authenticated raw fetch for anything not covered above. No retries, no
+     * throwing on HTTP errors. The `Authorization` header is only attached when
+     * the target shares the client's origin, so a foreign URL never sees the key.
+     */
+    fetch(pathOrUrl: string, init?: RequestInit): Promise<Response>;
+    private url;
+    private sameOrigin;
+    private json;
+    private signalFor;
+    /** Sends and throws `CarImageError` on any non-2xx response. */
+    private send;
+    /** Sends with retries but returns the final response, whatever its status. */
+    private rawSend;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}