{"id":30103952,"url":"https://github.com/cardog-ai/corgi","last_synced_at":"2026-03-12T06:07:07.934Z","repository":{"id":295877443,"uuid":"991575617","full_name":"cardog-ai/corgi","owner":"cardog-ai","description":"A TypeScript library for decoding and validating Vehicle Identification Numbers (VINs) using a customized VPIC database.","archived":false,"fork":false,"pushed_at":"2026-03-05T23:47:16.000Z","size":1190,"stargazers_count":212,"open_issues_count":3,"forks_count":25,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-03-06T03:34:14.400Z","etag":null,"topics":["automotive","cloudflare-workers","offline","offline-first","sqlite","typescript","vin-decoder"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cardog-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":["https://cardog.app"]}},"created_at":"2025-05-27T20:48:04.000Z","updated_at":"2026-02-27T17:52:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"977c2314-cc2b-4d36-a5f6-da8eb49f2bdd","html_url":"https://github.com/cardog-ai/corgi","commit_stats":null,"previous_names":["cardog-ai/corgi"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/cardog-ai/corgi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardog-ai%2Fcorgi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardog-ai%2Fcorgi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardog-ai%2Fcorgi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardog-ai%2Fcorgi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cardog-ai","download_url":"https://codeload.github.com/cardog-ai/corgi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardog-ai%2Fcorgi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30415041,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T00:40:14.898Z","status":"online","status_checked_at":"2026-03-12T02:00:07.260Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automotive","cloudflare-workers","offline","offline-first","sqlite","typescript","vin-decoder"],"created_at":"2025-08-09T22:02:55.542Z","updated_at":"2026-03-12T06:07:07.927Z","avatar_url":"https://github.com/cardog-ai.png","language":"TypeScript","funding_links":["https://cardog.app"],"categories":["TypeScript","Built with TypeScript","Applications"],"sub_categories":["Libraries","Desktop"],"readme":"# Corgi VIN Decoder\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./cardog-icon.png\" alt=\"Cardog\" width=\"120\" height=\"120\" style=\"border-radius: 24px;\"\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"./corgi.png\" alt=\"Corgi - Fast VIN Decoder\" width=\"120\" height=\"120\"\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cstrong\u003eFast, offline VIN decoding for Node.js, browsers, and Cloudflare Workers.\u003c/strong\u003e\u003cbr\u003e\n  Powered by the NHTSA VPIC database.\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![npm version](https://badge.fury.io/js/%40cardog%2Fcorgi.svg)](https://www.npmjs.com/package/@cardog/corgi)\n[![Downloads](https://img.shields.io/npm/dm/@cardog/corgi.svg)](https://www.npmjs.com/package/@cardog/corgi)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n[![License: ISC](https://img.shields.io/badge/License-ISC-yellow.svg)](https://opensource.org/licenses/ISC)\n[![Cardog API](https://img.shields.io/badge/Cardog-API-orange.svg)](https://docs.cardog.app)\n\n\u003c/div\u003e\n\n\u003e **Need more than basic VIN decoding?** Check out the [Cardog API](https://docs.cardog.app) for comprehensive vehicle data including market values, safety recalls, ownership costs, and more.\n\n## Installation\n\n```bash\nnpm install @cardog/corgi\n```\n\n## Quick Start\n\n```typescript\nimport { createDecoder } from \"@cardog/corgi\";\n\nconst decoder = await createDecoder();\nconst result = await decoder.decode(\"KM8K2CAB4PU001140\");\n\nconsole.log(result.components.vehicle);\n// { make: 'Hyundai', model: 'Kona', year: 2023, ... }\n\nawait decoder.close();\n```\n\n## Platform Support\n\n### Node.js\n\n```typescript\nimport { createDecoder } from \"@cardog/corgi\";\n\nconst decoder = await createDecoder();\nconst result = await decoder.decode(\"1HGCM82633A123456\");\n\n// Custom database path\nconst decoder = await createDecoder({\n  databasePath: \"/path/to/vpic.lite.db\",\n});\n```\n\n### Browser\n\n```typescript\nimport { createDecoder } from \"@cardog/corgi/browser\";\n\nconst decoder = await createDecoder({\n  databasePath: \"https://corgi.cardog.io/vpic.lite.db.gz\",\n  runtime: \"browser\",\n});\n```\n\n### Cloudflare Workers (D1)\n\n```typescript\nimport { createDecoder, initD1Adapter } from \"@cardog/corgi\";\n\ninitD1Adapter(env.D1_DATABASE);\n\nconst decoder = await createDecoder({\n  databasePath: \"D1\",\n  runtime: \"cloudflare\",\n});\n```\n\n## Configuration\n\n```typescript\nconst decoder = await createDecoder({\n  databasePath: \"./custom/path.db\",\n  forceFresh: true,\n  defaultOptions: {\n    includePatternDetails: true,\n    includeRawData: false,\n    confidenceThreshold: 0.8,\n    includeDiagnostics: true,\n  },\n});\n\n// Per-decode options\nconst result = await decoder.decode(\"VIN12345678901234\", {\n  modelYear: 2024,\n  includePatternDetails: true,\n});\n```\n\n## Response Structure\n\n```typescript\ninterface DecodeResult {\n  vin: string;\n  valid: boolean;\n\n  components: {\n    vehicle?: {\n      make: string;\n      model: string;\n      year: number;\n      series?: string;\n      bodyStyle?: string;\n      driveType?: string;\n      fuelType?: string;\n      doors?: string;\n    };\n    wmi?: {\n      manufacturer: string;\n      make: string;\n      country: string;\n      region: string;\n    };\n    plant?: {\n      country: string;\n      city?: string;\n      code: string;\n    };\n    engine?: {\n      model?: string;\n      cylinders?: string;\n      displacement?: string;\n      fuel?: string;\n    };\n    modelYear?: {\n      year: number;\n      source: string;\n      confidence: number;\n    };\n    checkDigit?: {\n      isValid: boolean;\n      expected?: string;\n      actual: string;\n    };\n  };\n\n  errors: DecodeError[];\n  metadata?: DiagnosticInfo;\n  patterns?: PatternMatch[];\n}\n```\n\n## Error Handling\n\n```typescript\nimport { ErrorCode } from \"@cardog/corgi\";\n\nconst result = await decoder.decode(\"INVALID_VIN\");\n\nif (!result.valid) {\n  result.errors.forEach((error) =\u003e {\n    switch (error.code) {\n      case ErrorCode.INVALID_CHECK_DIGIT:\n      case ErrorCode.INVALID_LENGTH:\n      case ErrorCode.WMI_NOT_FOUND:\n        console.log(error.message);\n    }\n  });\n}\n```\n\n## CLI\n\n```bash\nnpx @cardog/corgi decode 1HGCM82633A123456\nnpx @cardog/corgi decode 1HGCM82633A123456 --patterns --format json\nnpx @cardog/corgi --help\n```\n\n---\n\n## Architecture\n\n### VIN Structure\n\nA Vehicle Identification Number (VIN) is a 17-character identifier assigned to every vehicle manufactured for road use. The structure is defined by ISO 3779 and follows this format:\n\n```\nPosition:  1-3    4-8      9       10      11      12-17\n           WMI    VDS      Check   Year    Plant   VIS\n           │      │        │       │       │       │\n           │      │        │       │       │       └─ Sequential production number\n           │      │        │       │       └───────── Assembly plant code\n           │      │        │       └─────────────── Model year (A-Y, 1-9, excluding I,O,Q,U,Z,0)\n           │      │        └─────────────────────── Check digit (0-9, X)\n           │      └──────────────────────────────── Vehicle attributes (model, body, engine, etc.)\n           └─────────────────────────────────────── World Manufacturer Identifier\n```\n\n**WMI (Positions 1-3)**: Identifies the manufacturer. First character indicates country/region, second indicates manufacturer, third indicates vehicle type or manufacturing division.\n\n**VDS (Positions 4-8)**: Vehicle Descriptor Section. Manufacturer-defined attributes including model, body style, engine type, and restraint system.\n\n**Check Digit (Position 9)**: Validates VIN integrity using a weighted algorithm. Required for all vehicles sold in North America.\n\n**Model Year (Position 10)**: Encodes the model year. Uses letters A-Y (excluding I, O, Q, U, Z) and digits 1-9 in a 30-year cycle.\n\n**Plant Code (Position 11)**: Identifies the assembly plant. Manufacturer-specific encoding.\n\n**VIS (Positions 12-17)**: Vehicle Identifier Section. Sequential production number unique within the model year and plant.\n\n### Check Digit Algorithm\n\nThe check digit (position 9) is calculated by:\n\n1. Assigning each character a value (A=1, B=2, ..., N=5, P=7, ..., 0-9 = face value)\n2. Multiplying each position by a weight: `[8,7,6,5,4,3,2,10,0,9,8,7,6,5,4,3,2]`\n3. Summing all products and taking modulo 11\n4. Result 10 = 'X', otherwise the digit itself\n\n### Model Year Decoding\n\nPer 49 CFR 565.15, model year codes cycle every 30 years:\n\n| Code | Years |\n|------|-------|\n| A | 1980, 2010 |\n| B | 1981, 2011 |\n| ... | ... |\n| X | 1999, 2029 |\n| Y | 2000, 2030 |\n| 1 | 2001, 2031 |\n| ... | ... |\n| 9 | 2009, 2039 |\n\nCharacters I, O, Q are excluded from all VIN positions. U, Z, and 0 are additionally excluded from position 10.\n\n---\n\n## Database\n\n### VPIC Lite\n\nCorgi uses an optimized subset of the NHTSA vPIC (Vehicle Product Information Catalog) database. The database is compressed and bundled with the package for offline operation.\n\n**Specifications:**\n- Source: NHTSA VPIC\n- Format: SQLite (optimized)\n- Compressed: ~20MB (gzip)\n- Uncompressed: ~40MB\n- Updates: Monthly via automated pipeline\n\n### Hosted Database\n\nCardog maintains a public CDN with the latest VPIC database builds:\n\n**Base URL:** `https://corgi.cardog.io`\n\n| File | Description |\n|------|-------------|\n| `vpic.lite.db.gz` | Database (gzip) |\n| `vpic.lite.db.bz2` | Database (bzip2) |\n| `vpic.lite.db.xz` | Database (xz) |\n| `vpic.lite.db.zst` | Database (zstd) |\n| `vpic.lite.json` | Metadata (version, checksums, record counts) |\n| `vpic.lite.sha256` | SHA256 checksums |\n\nDated archives are also available: `vpic_lite_YYYYMMDD.db.gz`\n\n### Local Cache\n\n- **Node.js**: `~/.corgi-cache/vpic.lite.db`\n- **Browser**: Loaded from provided URL\n- **Cloudflare**: Managed by D1\n\n```typescript\nimport { getDatabasePath } from \"@cardog/corgi\";\n\nconst dbPath = await getDatabasePath();\nconst decoder = await createDecoder({ forceFresh: true }); // Force refresh\n```\n\n---\n\n## Exports\n\n```typescript\n// Core\nimport { createDecoder, quickDecode, getDatabasePath } from \"@cardog/corgi\";\n\n// Types\nimport type { DecodeResult, DecodeOptions, DecoderConfig } from \"@cardog/corgi\";\n\n// Enums\nimport { ErrorCode, ErrorCategory, BodyStyle } from \"@cardog/corgi\";\n\n// Adapters\nimport { initD1Adapter } from \"@cardog/corgi/d1-adapter\";\nimport { createDecoder } from \"@cardog/corgi/browser\";\n```\n\n---\n\n## Cardog API\n\n**Corgi provides fast, offline VIN decoding** - but if you need comprehensive vehicle intelligence, the [Cardog API](https://docs.cardog.app) offers much more:\n\n- **Enriched VIN Decoding** - Corgi decoding plus detailed variant data, specs, and features\n- **Market Analysis** - Pricing insights, market trends, and comparable vehicle listings\n- **Safety Recalls** - NHTSA and Transport Canada recall data searchable by VIN or make/model\n- **Vehicle Listings** - Search active listings with filters for make, model, price, location\n- **EV Data** - Charging stations, efficiency ratings, and range estimates\n\n```bash\n# Decode a VIN with full vehicle data\ncurl \"https://api.cardog.io/v1/vin/1HGCM82633A123456\" \\\n  -H \"x-api-key: your-api-key\"\n```\n\n[Get started at docs.cardog.app](https://docs.cardog.app)\n\n---\n\n## License\n\nISC License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcardog-ai%2Fcorgi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcardog-ai%2Fcorgi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcardog-ai%2Fcorgi/lists"}