@cardog/api 0.1.1

package/README.md

@@ -0,0 +1,327 @@
+# @cardog/api
+
+<div align="center">
+  <img src="./cardog-icon.png" alt="Cardog" width="120" height="120" style="border-radius: 24px;">
+</div>
+
+<div align="center">
+  <strong>Official TypeScript client for the Cardog API</strong><br>
+  Vehicle data, market analysis, VIN decoding, and more.
+</div>
+
+<br>
+
+<div align="center">
+
+[![npm version](https://badge.fury.io/js/%40cardog%2Fapi.svg)](https://www.npmjs.com/package/@cardog/api)
+[![Downloads](https://img.shields.io/npm/dm/@cardog/api.svg)](https://www.npmjs.com/package/@cardog/api)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+<div align="center">
+
+[Documentation](https://docs.cardog.app) · [Get API Key](https://cardog.app) · [Pricing](https://cardog.app/pricing)
+
+</div>
+
+---
+
+## Installation
+
+```bash
+npm install @cardog/api
+# or
+pnpm add @cardog/api
+# or
+yarn add @cardog/api
+```
+
+For React hooks, also install:
+
+```bash
+npm install @tanstack/react-query
+```
+
+## Quick Start
+
+```typescript
+import { CardogClient } from "@cardog/api";
+
+const client = new CardogClient({
+  apiKey: "your-api-key", // Get one at https://cardog.app
+});
+
+// Decode a VIN
+const vehicle = await client.vin.decode("1HGCM82633A123456");
+console.log(vehicle.make, vehicle.model, vehicle.year);
+// Honda Accord 2003
+
+// Get market analysis
+const market = await client.market.overview("Toyota", "Camry", 2022);
+console.log(market.medianPrice, market.totalListings);
+
+// Search listings
+const listings = await client.listings.search({
+  makes: ["Toyota"],
+  year: { min: 2020, max: 2024 },
+  price: { max: 50000 },
+});
+```
+
+## React Hooks
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { CardogClient } from "@cardog/api";
+import { createHooks } from "@cardog/api/react";
+
+const queryClient = new QueryClient();
+const client = new CardogClient({ apiKey: "your-api-key" });
+const { useVinDecode, useMarketOverview, useListingsSearch } = createHooks(client);
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <VehicleLookup />
+    </QueryClientProvider>
+  );
+}
+
+function VehicleLookup() {
+  const { data, isLoading, error } = useVinDecode("1HGCM82633A123456");
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      {data?.make} {data?.model} ({data?.year})
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### VIN Decoding
+
+```typescript
+// Decode a VIN
+const vehicle = await client.vin.decode("1HGCM82633A123456");
+
+// Decode from image (base64)
+const result = await client.vin.image(base64Image);
+```
+
+### Market Analysis
+
+```typescript
+// Market overview for a specific vehicle
+const overview = await client.market.overview("Toyota", "Camry", 2022);
+
+// Price distribution
+const pricing = await client.market.pricing("Honda", "Civic", 2021);
+
+// Geographic breakdown
+const geography = await client.market.geography("Ford", "F-150", 2023);
+
+// Market trends over time
+const trends = await client.market.trends("Tesla", "Model 3", 2022, "month");
+
+// Listing market position
+const position = await client.market.position("listing-id");
+
+// Overall market pulse
+const pulse = await client.market.pulse({
+  priceRangeMin: 20000,
+  priceRangeMax: 50000,
+});
+```
+
+### Vehicle Listings
+
+```typescript
+// Search listings with filters
+const results = await client.listings.search({
+  makes: ["Toyota", "Honda"],
+  models: { Toyota: ["Camry", "Corolla"] },
+  year: { min: 2020, max: 2024 },
+  price: { min: 15000, max: 40000 },
+  odometer: { max: 50000 },
+  bodyStyles: ["Sedan", "SUV"],
+  fuelTypes: ["Gasoline", "Hybrid"],
+});
+
+// Get listing count
+const count = await client.listings.count({ makes: ["BMW"] });
+
+// Get facets for filtering UI
+const facets = await client.listings.facets({ makes: ["Mercedes-Benz"] });
+
+// Get specific listing
+const listing = await client.listings.getById("listing-id");
+```
+
+### Safety Recalls
+
+```typescript
+// Search recalls
+const recalls = await client.recalls.search({
+  country: "us", // or "ca" for Canada
+  makes: ["Toyota"],
+  models: ["RAV4"],
+  year: { min: 2019, max: 2023 },
+});
+```
+
+### Research & Specs
+
+```typescript
+// Get vehicle lineup for a make
+const lineup = await client.research.lineup("Toyota");
+
+// Get model year details
+const modelYear = await client.research.modelYear("Toyota", "Camry", 2023);
+
+// Get vehicle images
+const images = await client.research.images("Toyota", "Camry", 2023);
+
+// Get available colors
+const colors = await client.research.colors("Honda", "Civic", 2024);
+```
+
+### Fuel & Charging
+
+```typescript
+// Find gas stations
+const gasStations = await client.fuel.search({
+  lat: 43.6532,
+  lng: -79.3832,
+  radius: 10,
+  fuelType: "REGULAR",
+});
+
+// Find EV charging stations
+const chargers = await client.charging.search({
+  lat: 43.6532,
+  lng: -79.3832,
+  radius: 25,
+  minPower: 50, // kW
+});
+```
+
+### Locations
+
+```typescript
+// Search dealer/seller locations
+const dealers = await client.locations.search({
+  lat: 43.6532,
+  lng: -79.3832,
+  radius: 50,
+});
+
+// Get seller details
+const seller = await client.locations.getById("seller-id");
+```
+
+### EPA Efficiency
+
+```typescript
+// Search EPA fuel economy data
+const efficiency = await client.efficiency.search({
+  make: "Toyota",
+  model: "Prius",
+  year: 2023,
+});
+```
+
+### NHTSA Complaints
+
+```typescript
+// Search vehicle complaints
+const complaints = await client.complaints.search({
+  make: "Ford",
+  model: "Explorer",
+  year: { min: 2020, max: 2023 },
+});
+```
+
+## Error Handling
+
+```typescript
+import { CardogClient, APIError } from "@cardog/api";
+
+try {
+  const data = await client.vin.decode("INVALID");
+} catch (error) {
+  if (error instanceof APIError) {
+    console.log(error.status);  // HTTP status code
+    console.log(error.code);    // Error code (e.g., "INVALID_VIN")
+    console.log(error.message); // Human-readable message
+    console.log(error.data);    // Additional error details
+  }
+}
+```
+
+## Query Keys
+
+For manual React Query integration:
+
+```typescript
+import { queryKeys } from "@cardog/api";
+
+// Use in custom queries
+const { data } = useQuery({
+  queryKey: queryKeys.vin.decode("1HGCM82633A123456"),
+  queryFn: () => client.vin.decode("1HGCM82633A123456"),
+});
+
+// Available key factories
+queryKeys.vin.decode(vin)
+queryKeys.market.overview(make, model, year)
+queryKeys.listings.search(params)
+queryKeys.recalls.search(params)
+// ... and more
+```
+
+## Configuration
+
+```typescript
+const client = new CardogClient({
+  apiKey: "your-api-key",
+  baseUrl: "https://api.cardog.io", // Default
+});
+
+// Update config at runtime
+client.setConfig({
+  apiKey: "new-api-key",
+});
+```
+
+## Pricing
+
+| Plan | Requests/mo | Price | Best For |
+|------|-------------|-------|----------|
+| **Free** | 100 | $0 | Testing & development |
+| **Pro** | 10,000 | $29/mo | Small apps & side projects |
+| **Business** | 100,000 | $199/mo | Production applications |
+| **Enterprise** | Unlimited | Custom | High-volume integrations |
+
+All plans include access to all API endpoints. [View full pricing →](https://cardog.app/pricing)
+
+## Links
+
+- [API Documentation](https://docs.cardog.app)
+- [Get API Key](https://cardog.app)
+- [Pricing](https://cardog.app/pricing)
+- [GitHub Issues](https://github.com/cardog-ai/cardog-api/issues)
+
+## Related Packages
+
+- [`@cardog/corgi`](https://www.npmjs.com/package/@cardog/corgi) - Offline VIN decoder (no API key needed)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.