@cardog/api

Cardog API Client

Official TypeScript client for the Cardog API.

Features

• 🔒 Type-safe API calls with runtime validation
• 🎯 First-class TanStack Query (React Query) support
• 📦 Tree-shakeable ESM package
• 🔍 Autocomplete for all API methods
• 🚀 Built-in error handling
• ♾️ Infinite scrolling support for listings

Installation

npm install @cardog/api
# or
yarn add @cardog/api
# or
pnpm add @cardog/api

For React support with TanStack Query:

npm install @cardog/api @tanstack/react-query

Basic Usage

import { CardogClient } from "@cardog/api";

const client = new CardogClient({
  apiKey: "your-api-key",
});

// Get an api key from https://platform.cardog.ai

// Search listings
const listings = await client.listings.search({
  filters: {
    makes: ["Toyota"],
    year: { min: 2020 },
    price: { max: 50000 },
  },
  pagination: { page: 1, limit: 25 },
  sort: { field: "price", direction: "asc" },
});

// Get a specific listing
const listing = await client.listings.getById("listing-123");

// Decode a VIN
const vehicleInfo = await client.vin.decode("1HGCM82633A123456");

// Get market pricing
const pricing = await client.market.getPricing({
  make: "Honda",
  model: "Civic",
  year: 2023,
});

React Integration

Basic Setup

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { CRDGClient } from '@crdg/client';
import { createHooks } from '@crdg/client/react';

const queryClient = new QueryClient();
const client = new CRDGClient({
  apiKey: 'your-api-key',
});

// Create hooks
const hooks = createHooks(client);

// Use in your app
export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <ListingsSearch />
    </QueryClientProvider>
  );
}

Listings Search Example

import { ListingsSearchParams } from '@crdg/client';

function ListingsSearch() {
  // Basic search with pagination
  const { data, isLoading } = hooks.useListingsSearch({
    filters: {
      makes: ['Toyota'],
      year: { min: 2020 },
    },
    pagination: { page: 1, limit: 25 },
    sort: { field: 'price', direction: 'asc' },
  });

  // Or use infinite scrolling
  const {
    data: infiniteData,
    fetchNextPage,
    hasNextPage,
    isFetchingNextPage,
  } = hooks.useInfiniteListingsSearch({
    filters: {
      makes: ['Toyota'],
      year: { min: 2020 },
    },
    sort: { field: 'price', direction: 'asc' },
  });

  return (
    <div>
      {/* Render your listings */}
      {infiniteData?.pages.map(page =>
        page.items.map(listing => (
          <ListingCard key={listing.id} listing={listing} />
        ))
      )}

      {hasNextPage && (
        <button
          onClick={() => fetchNextPage()}
          disabled={isFetchingNextPage}
        >
          Load More
        </button>
      )}
    </div>
  );
}

// Individual listing
function ListingDetail({ id }: { id: string }) {
  const { data: listing, isLoading } = hooks.useListingById(id);

  if (isLoading) return <div>Loading...</div>;
  if (!listing) return <div>Not found</div>;

  return (
    <div>
      <h1>{listing.year} {listing.make} {listing.model}</h1>
      <p>Price: ${listing.price}</p>
      {/* ... */}
    </div>
  );
}

Advanced Usage with Type Helpers

import { createHooks, InferQueryResult, RouteParams } from '@crdg/client/react';

// Infer response types
type ListingType = InferQueryResult<typeof client.listings.getById>;
type SearchResponse = InferQueryResult<typeof client.listings.search>;

// Infer parameter types
type SearchParams = RouteParams<typeof client.listings.search>;

// Use with custom options
function ListingsGrid({ params }: { params: SearchParams }) {
  const { data } = hooks.useListingsSearch(params, {
    staleTime: 5 * 60 * 1000, // 5 minutes
    cacheTime: 30 * 60 * 1000, // 30 minutes
  });

  return <div>{/* Render your grid */}</div>;
}

Creating Custom Hooks

import { queryKeys, createQueryKeyFactory } from "@crdg/client/react";

// Create type-safe query keys for your custom endpoints
const customKeys = createQueryKeyFactory("custom");

function useCustomQuery(id: string) {
  return useQuery({
    queryKey: customKeys.detail(id),
    queryFn: () => client.custom.getDetails(id),
  });
}

Extending the Client

You can extend the client with custom methods:

import { CRDGClient, BaseClient } from "@crdg/client";

// Create custom API class
class CustomAPI extends BaseClient {
  async customMethod() {
    return this.get("/custom/endpoint");
  }
}

// Extend the main client
class ExtendedClient extends CRDGClient {
  public custom: CustomAPI;

  constructor(config) {
    super(config);
    this.custom = new CustomAPI(config);
  }
}

Error Handling

The client includes built-in error handling with typed errors:

try {
  const data = await client.listings.search({
    filters: {
      makes: ["Invalid Make"],
    },
  });
} catch (error) {
  if (error instanceof APIError) {
    console.log(error.status); // HTTP status code
    console.log(error.code); // Error code from API
    console.log(error.data); // Additional error data
  }
}

TypeScript Support

The client is written in TypeScript and includes full type definitions. All API responses are validated at runtime using Zod schemas.

Available Types

import type {
  // Listings types
  ListingsSearchParams,
  ListingsResponse,
  Listing,
  ListingsPagination,
  ListingsSort,
  ListingsFilters,
  Location,

  // Other types
  VinDecodeResponse,
  MarketPricingResponse,
} from "@crdg/client";