cardog 0.1.0__tar.gz

cardog-0.1.0/.gitignore

@@ -0,0 +1,86 @@
+# env files in any directory
+.env*
+.env.local
+.env.example
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Override global gitignore - allow TypeScript env modules
+!src/env/
+!apps/*/src/env/
+
+# Override global gitignore - allow parts directories in services
+!src/services/parts/
+!apps/*/src/services/parts/
+
+packages/assets
+
+# wrangler
+.wrangler
+
+candog
+tab
+
+# misc
+.DS_Store
+*.pem
+*.db
+*.db.br
+*.db.gz
+
+# Playwright
+playwright-report
+
+# Test results
+test-results
+
+# python
+__pycache__
+.venv
+
+# next
+next-env.d.ts
+
+# node_modules
+node_modules
+
+# dist
+dist/
+
+# test.3d.vin
+test.3d.vin
+
+# Ignore packages/vPIC-download for now
+packages/vpic-pipeline
+
+# Submodules
+@cardog-icons/
+
+
+# foxfuck folder
+foxfuck
+
+# vehicle-media folder
+vehicle-media
+
+# brochure folder
+brochure
+
+# turbo 
+.turbo
+
+# vercel
+.vercel
+
+# cursor
+.cursor
+
+# sandbox directory
+sandbox
+
+# Any claude folders 
+.claude
+
+
+docs

cardog-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: cardog
+Version: 0.1.0
+Summary: Official Python SDK for the Cardog API
+Project-URL: Homepage, https://cardog.app
+Project-URL: Documentation, https://docs.cardog.app
+Project-URL: Repository, https://github.com/cardog-ai/cardog-python
+Author-email: Cardog <hello@cardog.app>
+License-Expression: MIT
+Keywords: api,automotive,cardog,sdk,vehicle,vin
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Cardog Python SDK
+
+Official Python SDK for the [Cardog API](https://docs.cardog.app) — automotive intelligence, VIN decoding, market analytics, and more.
+
+## Installation
+
+```bash
+pip install cardog
+```
+
+## Quick Start
+
+```python
+from cardog import Cardog
+
+client = Cardog(api_key="your-api-key")
+
+# Decode a VIN
+vehicle = client.vin.decode("1HGCM82633A123456")
+print(vehicle.components.vehicle.make)  # "Honda"
+
+# Search listings
+results = client.listings.search(
+    makes=["Toyota"],
+    year_min=2020,
+    price_max=30000,
+)
+for listing in results.listings:
+    print(f"{listing.year} {listing.make} {listing.model} - ${listing.price}")
+
+# Market overview
+overview = client.market.overview("Honda", "Civic", 2022)
+print(f"Median price: ${overview.median_price}")
+
+# Recalls
+recalls = client.recalls.search("us", makes=["Tesla"])
+print(f"Found {recalls.meta.count} recalls")
+
+# EV charging stations
+stations = client.charging.search(lat=43.65, lng=-79.38, radius=10)
+for station in stations.stations:
+    print(f"{station.name} - {station.network}")
+
+# Fuel prices
+fuel = client.fuel.get("regular", lat=43.65, lng=-79.38)
+print(f"Current price: {fuel.current} {fuel.unit}")
+```
+
+## Async Support
+
+```python
+import asyncio
+from cardog import AsyncCardog
+
+async def main():
+    client = AsyncCardog(api_key="your-api-key")
+
+    vehicle = await client.vin.decode("1HGCM82633A123456")
+    listings = await client.listings.search(makes=["Toyota"])
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+## Available Resources
+
+| Resource | Description |
+|----------|-------------|
+| `client.vin` | VIN decoding (single, batch, image) |
+| `client.listings` | Vehicle listing search, count, facets |
+| `client.market` | Market analytics, pricing, trends, geography |
+| `client.recalls` | US & Canadian vehicle recalls |
+| `client.charging` | EV charging station search |
+| `client.fuel` | Fuel prices and gas station search |
+| `client.research` | Vehicle variants, specs, images |
+| `client.locations` | Dealer/seller search |
+| `client.safety` | NHTSA safety ratings |
+| `client.efficiency` | EPA fuel economy data |
+| `client.complaints` | NHTSA complaints |
+| `client.history` | Vehicle history reports |
+
+## Configuration
+
+```python
+client = Cardog(
+    api_key="your-api-key",
+    base_url="https://api.cardog.io/v1",  # default
+    timeout=30.0,                          # seconds
+    max_retries=2,                         # retry on 429/5xx
+)
+```
+
+## Error Handling
+
+```python
+from cardog import Cardog, NotFoundError, RateLimitError, AuthenticationError
+
+client = Cardog(api_key="your-api-key")
+
+try:
+    vehicle = client.vin.decode("INVALID")
+except NotFoundError:
+    print("VIN not found")
+except RateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after}s")
+except AuthenticationError:
+    print("Invalid API key")
+```
+
+## Type Safety
+
+All responses are Pydantic models with full type hints. Your IDE will provide autocomplete for every field.
+
+```python
+result = client.market.overview("Toyota", "Camry", 2023)
+# IDE knows result.avg_price is float, result.total_listings is int, etc.
+```
+
+## License
+
+MIT

cardog-0.1.0/README.md

@@ -0,0 +1,122 @@
+# Cardog Python SDK
+
+Official Python SDK for the [Cardog API](https://docs.cardog.app) — automotive intelligence, VIN decoding, market analytics, and more.
+
+## Installation
+
+```bash
+pip install cardog
+```
+
+## Quick Start
+
+```python
+from cardog import Cardog
+
+client = Cardog(api_key="your-api-key")
+
+# Decode a VIN
+vehicle = client.vin.decode("1HGCM82633A123456")
+print(vehicle.components.vehicle.make)  # "Honda"
+
+# Search listings
+results = client.listings.search(
+    makes=["Toyota"],
+    year_min=2020,
+    price_max=30000,
+)
+for listing in results.listings:
+    print(f"{listing.year} {listing.make} {listing.model} - ${listing.price}")
+
+# Market overview
+overview = client.market.overview("Honda", "Civic", 2022)
+print(f"Median price: ${overview.median_price}")
+
+# Recalls
+recalls = client.recalls.search("us", makes=["Tesla"])
+print(f"Found {recalls.meta.count} recalls")
+
+# EV charging stations
+stations = client.charging.search(lat=43.65, lng=-79.38, radius=10)
+for station in stations.stations:
+    print(f"{station.name} - {station.network}")
+
+# Fuel prices
+fuel = client.fuel.get("regular", lat=43.65, lng=-79.38)
+print(f"Current price: {fuel.current} {fuel.unit}")
+```
+
+## Async Support
+
+```python
+import asyncio
+from cardog import AsyncCardog
+
+async def main():
+    client = AsyncCardog(api_key="your-api-key")
+
+    vehicle = await client.vin.decode("1HGCM82633A123456")
+    listings = await client.listings.search(makes=["Toyota"])
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+## Available Resources
+
+| Resource | Description |
+|----------|-------------|
+| `client.vin` | VIN decoding (single, batch, image) |
+| `client.listings` | Vehicle listing search, count, facets |
+| `client.market` | Market analytics, pricing, trends, geography |
+| `client.recalls` | US & Canadian vehicle recalls |
+| `client.charging` | EV charging station search |
+| `client.fuel` | Fuel prices and gas station search |
+| `client.research` | Vehicle variants, specs, images |
+| `client.locations` | Dealer/seller search |
+| `client.safety` | NHTSA safety ratings |
+| `client.efficiency` | EPA fuel economy data |
+| `client.complaints` | NHTSA complaints |
+| `client.history` | Vehicle history reports |
+
+## Configuration
+
+```python
+client = Cardog(
+    api_key="your-api-key",
+    base_url="https://api.cardog.io/v1",  # default
+    timeout=30.0,                          # seconds
+    max_retries=2,                         # retry on 429/5xx
+)
+```
+
+## Error Handling
+
+```python
+from cardog import Cardog, NotFoundError, RateLimitError, AuthenticationError
+
+client = Cardog(api_key="your-api-key")
+
+try:
+    vehicle = client.vin.decode("INVALID")
+except NotFoundError:
+    print("VIN not found")
+except RateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after}s")
+except AuthenticationError:
+    print("Invalid API key")
+```
+
+## Type Safety
+
+All responses are Pydantic models with full type hints. Your IDE will provide autocomplete for every field.
+
+```python
+result = client.market.overview("Toyota", "Camry", 2023)
+# IDE knows result.avg_price is float, result.total_listings is int, etc.
+```
+
+## License
+
+MIT

cardog-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cardog"
+version = "0.1.0"
+description = "Official Python SDK for the Cardog API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Cardog", email = "hello@cardog.app" }]
+keywords = ["cardog", "automotive", "vin", "vehicle", "api", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://cardog.app"
+Documentation = "https://docs.cardog.app"
+Repository = "https://github.com/cardog-ai/cardog-python"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-httpx>=0.30",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cardog"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "contract: marks tests that hit the live API (requires CARDOG_API_KEY)",
+]

cardog-0.1.0/src/cardog/__init__.py

@@ -0,0 +1,57 @@
+"""Cardog - Official Python SDK for the Cardog API.
+
+Usage::
+
+    from cardog import Cardog
+
+    client = Cardog(api_key="your-api-key")
+
+    # Decode a VIN
+    vehicle = client.vin.decode("1HGCM82633A123456")
+
+    # Search listings
+    results = client.listings.search(makes=["Toyota"], year_min=2020, price_max=30000)
+
+    # Market analysis
+    overview = client.market.overview("Honda", "Civic", 2022)
+
+For async usage::
+
+    from cardog import AsyncCardog
+
+    client = AsyncCardog(api_key="your-api-key")
+    vehicle = await client.vin.decode("1HGCM82633A123456")
+"""
+
+from cardog._async_client import AsyncCardog
+from cardog._client import Cardog
+from cardog._constants import DEFAULT_BASE_URL
+from cardog._exceptions import (
+    APIError,
+    AuthenticationError,
+    CardogError,
+    ConnectionError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Cardog",
+    "AsyncCardog",
+    "DEFAULT_BASE_URL",
+    # Exceptions
+    "CardogError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "ConnectionError",
+    "TimeoutError",
+]

cardog-0.1.0/src/cardog/_async_client.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from cardog._base_client import AsyncAPIClient
+from cardog._constants import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT
+from cardog.resources import (
+    AsyncChargingResource,
+    AsyncComplaintsResource,
+    AsyncEfficiencyResource,
+    AsyncFuelResource,
+    AsyncHistoryResource,
+    AsyncListingsResource,
+    AsyncLocationsResource,
+    AsyncMarketResource,
+    AsyncRecallsResource,
+    AsyncResearchResource,
+    AsyncSafetyResource,
+    AsyncVinResource,
+)
+
+
+class AsyncCardog(AsyncAPIClient):
+    """Asynchronous Cardog API client.
+
+    Usage::
+
+        import asyncio
+        from cardog import AsyncCardog
+
+        async def main():
+            client = AsyncCardog(api_key="your-api-key")
+
+            # Decode a VIN
+            vehicle = await client.vin.decode("1HGCM82633A123456")
+
+            # Search listings
+            listings = await client.listings.search(makes=["Toyota"], year_min=2020)
+
+            await client.close()
+
+        asyncio.run(main())
+
+    Args:
+        api_key: Your Cardog API key.
+        base_url: API base URL (default: https://api.cardog.io/v1).
+        timeout: Request timeout in seconds (default: 30).
+        max_retries: Max retry attempts for failed requests (default: 2).
+    """
+
+    vin: AsyncVinResource
+    listings: AsyncListingsResource
+    market: AsyncMarketResource
+    recalls: AsyncRecallsResource
+    charging: AsyncChargingResource
+    fuel: AsyncFuelResource
+    research: AsyncResearchResource
+    locations: AsyncLocationsResource
+    safety: AsyncSafetyResource
+    efficiency: AsyncEfficiencyResource
+    complaints: AsyncComplaintsResource
+    history: AsyncHistoryResource
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        super().__init__(api_key, base_url=base_url, timeout=timeout, max_retries=max_retries)
+
+        self.vin = AsyncVinResource(self)
+        self.listings = AsyncListingsResource(self)
+        self.market = AsyncMarketResource(self)
+        self.recalls = AsyncRecallsResource(self)
+        self.charging = AsyncChargingResource(self)
+        self.fuel = AsyncFuelResource(self)
+        self.research = AsyncResearchResource(self)
+        self.locations = AsyncLocationsResource(self)
+        self.safety = AsyncSafetyResource(self)
+        self.efficiency = AsyncEfficiencyResource(self)
+        self.complaints = AsyncComplaintsResource(self)
+        self.history = AsyncHistoryResource(self)