🐕 Corgi VIN Decoder

Corgi is a blazing-fast, fully offline VIN decoder built with TypeScript. Powered by an optimized VPIC database, it delivers comprehensive vehicle information with zero network dependencies and lightning-fast performance across Node.js, browsers, and Cloudflare Workers.

⚡ Performance First

• Fully Offline: No API calls, no network dependencies, no rate limits
• Lightning Fast: Optimized SQLite database with pattern-based decoding
• Tiny Footprint: ~20MB compressed bundle with complete NHTSA dataset
• Zero Dependencies: Self-contained with automatic database management
• Universal: Works everywhere - Node.js, browsers, and edge computing

🚀 Quick Start

npm install @cardog/corgi

import { createDecoder } from "@cardog/corgi";

// One-line VIN decoding - database auto-managed
const decoder = await createDecoder();
const result = await decoder.decode("KM8K2CAB4PU001140");

console.log(result.components.vehicle);
// {
//   make: 'Hyundai',
//   model: 'Kona',
//   year: 2023,
//   series: 'SE',
//   bodyStyle: 'SUV',
//   driveType: '4WD/4-Wheel Drive/4x4',
//   fuelType: 'Gasoline',
//   doors: '5'
// }

await decoder.close();

📋 What You Get

Corgi extracts comprehensive vehicle information from any VIN:

• Vehicle Details: Make, model, year, series, trim, body style
• Technical Specs: Engine details, drivetrain, fuel type, doors
• Manufacturing: Plant location, manufacturer, production details
• Quality Metrics: Confidence scores and validation results
• Standards Compliance: Full NHTSA VPIC dataset integration

🏗️ Platform Support

Node.js

import { createDecoder } from "@cardog/corgi";

// Automatic database management - downloads and caches on first run
const decoder = await createDecoder();
const result = await decoder.decode("1HGCM82633A123456");

// Or provide your own database path
const customDecoder = await createDecoder({
  databasePath: "/path/to/vpic.lite.db",
});

Browser

// Host the database file and provide the URL
const browserDecoder = await createDecoder({
  databasePath: "https://cdn.example.com/vpic.lite.db.gz",
  runtime: "browser",
});

Cloudflare Workers

import { createDecoder, initD1Adapter } from "@cardog/corgi";

// Initialize D1 adapter with your binding
initD1Adapter(env.D1_DATABASE);

// Create decoder
const decoder = await createDecoder({
  databasePath: "D1",
  runtime: "cloudflare",
});

⚙️ Configuration

Advanced Options

const decoder = await createDecoder({
  databasePath: "./custom/db/path.db", // Custom database location
  forceFresh: true, // Force fresh database setup
  defaultOptions: {
    includePatternDetails: true, // Pattern matching details
    includeRawData: false, // Raw database records
    confidenceThreshold: 0.8, // Confidence threshold (0-1)
    includeDiagnostics: true, // Performance metrics
  },
});

// Override options per decode
const result = await decoder.decode("VIN12345678901234", {
  modelYear: 2024, // Override detected year
  includePatternDetails: true, // Include pattern analysis
});

Quick Decode Helper

import { quickDecode } from "@cardog/corgi";

// One-line decoding with shared instance
const result = await quickDecode("1HGCM82633A123456");

📊 Response Structure

interface DecodeResult {
  vin: string; // Input VIN
  valid: boolean; // Overall validation status

  components: {
    vehicle?: {
      // Core vehicle information
      make: string; // e.g., "Honda", "Toyota"
      model: string; // e.g., "Civic", "Camry"
      year: number; // Model year
      series?: string; // Trim/series level
      bodyStyle?: string; // "Sedan", "SUV", "Pickup"
      driveType?: string; // "FWD", "AWD", "4WD"
      fuelType?: string; // "Gasoline", "Electric"
      doors?: string; // Number of doors
    };

    wmi?: {
      // World Manufacturer Identifier
      manufacturer: string; // Official manufacturer name
      make: string; // Brand name
      country: string; // Country of origin
      region: string; // Geographic region
    };

    plant?: {
      // Manufacturing details
      country: string; // Production country
      city?: string; // Production city
      code: string; // Plant code
    };

    engine?: {
      // Engine specifications
      model?: string; // Engine model/code
      cylinders?: string; // Cylinder count
      displacement?: string; // Engine displacement
      fuel?: string; // Fuel type
    };

    modelYear?: {
      // Year detection details
      year: number; // Detected year
      source: string; // Detection method
      confidence: number; // Confidence score
    };

    checkDigit?: {
      // VIN validation
      isValid: boolean; // Check digit validity
      expected?: string; // Expected value
      actual: string; // Actual value
    };
  };

  errors: DecodeError[]; // Validation errors
  metadata?: DiagnosticInfo; // Performance metrics
  patterns?: PatternMatch[]; // Pattern details (optional)
}

🚨 Error Handling

import { ErrorCode, ErrorCategory } from "@cardog/corgi";

const result = await decoder.decode("INVALID_VIN");

if (!result.valid) {
  result.errors.forEach((error) => {
    console.log(`${error.category}: ${error.message}`);

    // Handle specific error types
    switch (error.code) {
      case ErrorCode.INVALID_CHECK_DIGIT:
        console.log(`Expected: ${error.expected}, Got: ${error.actual}`);
        break;
      case ErrorCode.INVALID_LENGTH:
        console.log("VIN must be exactly 17 characters");
        break;
      case ErrorCode.WMI_NOT_FOUND:
        console.log("Unknown manufacturer code");
        break;
    }
  });
}

🖥️ Command Line Interface

# Quick VIN decode
npx @cardog/corgi decode 1HGCM82633A123456

# With options
npx @cardog/corgi decode 1HGCM82633A123456 \
  --patterns \
  --year 2022 \
  --format json

# Custom database
npx @cardog/corgi decode 1HGCM82633A123456 \
  --database ./custom/vpic.lite.db

# Help
npx @cardog/corgi --help

💾 Database & Caching

Automatic Database Management

Corgi uses an intelligent caching system to provide optimal performance:

// First run: Downloads, decompresses, and caches database
const decoder = await createDecoder();

// Subsequent runs: Uses cached database for instant startup
const decoder2 = await createDecoder();

// Force fresh download and cache refresh
const freshDecoder = await createDecoder({ forceFresh: true });

Cache Storage Locations

• Node.js: ~/.corgi-cache/vpic.lite.db (User home directory)
• Browser: Database loaded from your provided URL
• Cloudflare: Managed by D1 database service

Database Details

• Source: Official NHTSA VPIC dataset (updated automatically)
• Compressed Size: ~20MB (vpic.lite.db.gz)
• Uncompressed Size: ~40MB (vpic.lite.db)
• Update Frequency: Monthly via automated pipeline
• Coverage: Complete VIN database with optimized queries

Cache Management

import { getDatabasePath } from "@cardog/corgi";

// Get current cached database path
const dbPath = await getDatabasePath();
console.log(`Database cached at: ${dbPath}`);

// Force cache refresh (useful after package updates)
const decoder = await createDecoder({ forceFresh: true });

🔬 Advanced Features

Pattern-Based Decoding

const result = await decoder.decode("VIN12345678901234", {
  includePatternDetails: true,
  confidenceThreshold: 0.8,
});

// Analyze individual pattern matches
result.patterns?.forEach((pattern) => {
  console.log(`${pattern.element}: ${pattern.value} (${pattern.confidence})`);
});

// Overall decode confidence
console.log(`Confidence: ${result.metadata?.confidence}`);

Body Style Normalization

import { BodyStyle } from "@cardog/corgi";

// Automatic normalization to standard values
console.log(BodyStyle.SUV); // "SUV"
console.log(BodyStyle.SEDAN); // "Sedan"
console.log(BodyStyle.PICKUP); // "Pickup"

// Raw values like "Sport Utility Vehicle (SUV)/Multi-Purpose Vehicle (MPV)"
// become clean "SUV"

Performance Diagnostics

const result = await decoder.decode("VIN12345678901234", {
  includeDiagnostics: true,
});

console.log(`Processing time: ${result.metadata?.processingTime}ms`);
console.log(`Schema version: ${result.metadata?.schemaVersion}`);

🤝 Contributing

We welcome contributions from the automotive and developer communities! Corgi is built to be the fastest, most reliable VIN decoder available.

Quick Start

git clone https://github.com/cardog-ai/corgi.git
cd corgi
pnpm install
pnpm approve-builds
pnpm test

Development Workflow

• Issues: Report bugs or request features via GitHub Issues
• Pull Requests: Fork, create a feature branch, and submit a PR
• Testing: All changes must include tests and pass existing test suite
• Standards: Follow existing TypeScript patterns and conventions

Database Updates

The VPIC database is automatically maintained via CI/CD pipelines. Manual database updates are rarely needed, but documentation is available for contributors.

Community Guidelines

• Be respectful and inclusive
• Follow semantic versioning for changes
• Write clear commit messages
• Add tests for new functionality

Made with ❤️ by the automotive community

📄 License

ISC License - see LICENSE for details.