cardog 2.1.0__tar.gz → 2.2.0__tar.gz

{cardog-2.1.0 → cardog-2.2.0}/CHANGELOG.md

@@ -8,6 +8,36 @@ pre-release it tracks. 3.0.0, published to PyPI on 2026-09-28, broke that
 rule and is yanked: `pip install cardog` no longer resolves to it, and a
 pin on `==3.0.0` still installs. Everything it carried is in 2.1.0.
 
+## [2.2.0] - 2026-09-30
+
+Tracks API 2.0.0-rc.6. The SDK ergonomics batch (CRDG-3286). Nothing on the
+wire changes; nothing existing stops working.
+
+### Added
+
+- `client.last_credits`: the `X-Credits-*` headers of the last metered
+  response, parsed into a `Credits` (`rate`, `remaining`, `allowance`,
+  `reset`, `source`), on both `Cardog` and `AsyncCardog`. Errors included: a
+  402 states the budget too. `None` until a metered response arrives, and an
+  unmetered response (pricing, a signed link) leaves the last set alone. The
+  credits contract says the price of your next call is in the headers of your
+  last one; budget-aware callers no longer drop to raw httpx for it.
+- `APIError.message` (and so `CardogAPIError.message`): the API's message on
+  its own. `str(err)` is unchanged, `[status] (code) message`, so
+  `f"{err.code}: {err.message}"` prints the code once.
+- The sibling names the TypeScript client uses, on the same groups:
+  `client.v2.entities.get_by_ref`, `client.v2.instruments.get_by_ref`,
+  `client.v2.quotes.get_by_ref`, `client.v2.recalls.get_by_ref` and
+  `client.v2.vin.get_by_vin` (for `getByRef` / `getByVin`). The former `get`
+  on each group stays callable as an alias.
+
+### Changed
+
+- The documented example VIN is `5YJSA1E28MF420053` everywhere (README,
+  docstrings, tests). The previous `5YJSA1E26MF420053` fails the check digit
+  at position 9; the decoder tolerated it, but an integrator validating check
+  digits first rejected our own example.
+
 ## [2.1.0] - 2026-09-30
 
 Tracks API 2.0.0-rc.6. Carries what 3.0.0 (yanked) and the unpublished

{cardog-2.1.0 → cardog-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cardog
-Version: 2.1.0
+Version: 2.2.0
 Summary: Python SDK for the Cardog API — Canadian VIN decode, vehicle specs, live listings, market quotes, and Transport Canada + NHTSA recalls.
 Project-URL: Homepage, https://cardog.app
 Project-URL: Documentation, https://cardog.app/docs
@@ -51,9 +51,9 @@ client = Cardog(api_key=os.environ["CARDOG_API_KEY"])
 result = client.v2.entities.resolve("2021 Civic")
 ref = result.best.ref            # "model-year:honda/civic/2021"
 
-identity = client.v2.vin.get("2HGFC2F53MH500001")
+identity = client.v2.vin.get_by_vin("2HGFC2F53MH500001")
 recalls = client.v2.vin.recalls("2HGFC2F53MH500001")
-quote = client.v2.quotes.get(ref)
+quote = client.v2.quotes.get_by_ref(ref)
 ```
 
 Canadian VIN decode coverage is 99.77%. Types and methods are generated from the same OpenAPI contract the API validates against — this SDK and the TypeScript one are siblings, not translations.
@@ -78,7 +78,7 @@ best = resolved.best          # None when nothing clears the confidence floor
 print(best.ref)               # "model:tesla/model-y"
 
 # 2. Dereference a ref: node + parents/children + counts + links
-detail = client.v2.entities.get(best.ref)
+detail = client.v2.entities.get_by_ref(best.ref)
 print(detail.name, detail.counts)
 
 # 3. Query with refs — never fuzzy, never guessed
@@ -99,18 +99,18 @@ for listing in results.listings:
 
 ```python
 # VIN → graph identity card (refs, grains, links)
-identity = client.v2.vin.get("5YJSA1E26MF420053")
+identity = client.v2.vin.get_by_vin("5YJSA1E28MF420053")
 print(identity.make, identity.model, identity.refs.model_year)
 
 # Batch decode (metered per VIN, max 1000) — one bad VIN fails its own row, never the batch
-batch = client.v2.vin.batch(["5YJSA1E26MF420053", "1HGCV1F34LA045661"])
+batch = client.v2.vin.batch(["5YJSA1E28MF420053", "1HGCV1F34LA045661"])
 
 # Recalls affecting a VIN (Transport Canada + NHTSA fused)
-recalls = client.v2.recalls.vin("5YJSA1E26MF420053")
+recalls = client.v2.recalls.vin("5YJSA1E28MF420053")
 
 # VIN → market instrument bridge, quotes, tape
-instrument = client.v2.vin.instrument("5YJSA1E26MF420053")
-quote = client.v2.quotes.get("model-year:toyota/rav4/2021")
+instrument = client.v2.vin.instrument("5YJSA1E28MF420053")
+quote = client.v2.quotes.get_by_ref("model-year:toyota/rav4/2021")
 bars = client.v2.tape.history("model-year:toyota/rav4/2021", window="3m")
 ```
 
@@ -146,7 +146,7 @@ from cardog import AsyncCardog
 
 async def main():
     client = AsyncCardog(api_key="your-api-key")
-    identity = await client.v2.vin.get("5YJSA1E26MF420053")
+    identity = await client.v2.vin.get_by_vin("5YJSA1E28MF420053")
     results = await client.v2.listings.search(filters={"makes": ["make:tesla"]})
     await client.close()
 
@@ -157,18 +157,28 @@ asyncio.run(main())
 
 | Group | Methods |
 |-------|---------|
-| `client.v2.entities` | `browse(domain, ...)` · `resolve(q, ...)` · `get(ref)` |
-| `client.v2.vin` | `get(vin)` · `batch(vins)` · `recalls(vin)` · `listings(vin)` · `instrument(vin)` |
+| `client.v2.entities` | `browse(domain, ...)` · `resolve(q, ...)` · `get_by_ref(ref)` |
+| `client.v2.vin` | `get_by_vin(vin)` · `batch(vins)` · `recalls(vin)` · `listings(vin)` · `instrument(vin)` |
 | `client.v2.specs` | `catalog()` · `sheet(ref, trim=...)` |
 | `client.v2.listings` | `search(...)` · `count(...)` · `facets(...)` · `by_vin(vin)` · `by_id(id)` |
-| `client.v2.instruments` | `search(q=..., limit=...)` · `get(ref, window=...)` |
-| `client.v2.quotes` | `get(ref)` · `get_many(refs)` |
+| `client.v2.instruments` | `search(q=..., limit=...)` · `get_by_ref(ref, window=...)` |
+| `client.v2.quotes` | `get_by_ref(ref)` · `get_many(refs)` |
 | `client.v2.tape` | `live(limit=...)` · `history(ref, window=...)` |
-| `client.v2.recalls` | `vin(vin)` · `entity(ref)` · `feed()` · `stats()` · `get(ref)` |
+| `client.v2.recalls` | `vin(vin)` · `entity(ref)` · `feed()` · `stats()` · `get_by_ref(ref)` |
 | `client.v2.safety` | `ratings(ref)` · `complaints(ref, page=..., limit=...)` |
 | platform meta | `client.v2.pricing()` · `client.v2.openapi()` (both unauthenticated) |
 
-The machine-readable rate card (`pricing()`) plus the `X-Credits-*` response headers let you budget mid-task; `openapi()` returns the same contract this SDK is generated from.
+The machine-readable rate card (`pricing()`) plus the `X-Credits-*` response headers let you budget mid-task; `openapi()` returns the same contract this SDK is generated from. The client keeps the last set of those headers parsed on `client.last_credits`, errors included (a 402 states the budget too):
+
+```python
+client.v2.vin.get_by_vin("5YJSA1E28MF420053")
+credits = client.last_credits  # a Credits, or None before any metered call
+print(credits.rate, credits.remaining, credits.allowance, credits.reset, credits.source)
+# rate: what that call cost · remaining: allowance headroom + pack balance (-1 = custom plan)
+# reset: when the allowance rolls over · source: "allowance" | "pack" | "overage", None when nothing was debited
+```
+
+Errors carry the envelope: `err.code` to branch on, `err.message` on its own, `err.hint` for what to do next. `str(err)` is the log line, `[status] (code) message`.
 
 ## v1 (legacy)
 

{cardog-2.1.0 → cardog-2.2.0}/README.md

@@ -17,9 +17,9 @@ client = Cardog(api_key=os.environ["CARDOG_API_KEY"])
 result = client.v2.entities.resolve("2021 Civic")
 ref = result.best.ref            # "model-year:honda/civic/2021"
 
-identity = client.v2.vin.get("2HGFC2F53MH500001")
+identity = client.v2.vin.get_by_vin("2HGFC2F53MH500001")
 recalls = client.v2.vin.recalls("2HGFC2F53MH500001")
-quote = client.v2.quotes.get(ref)
+quote = client.v2.quotes.get_by_ref(ref)
 ```
 
 Canadian VIN decode coverage is 99.77%. Types and methods are generated from the same OpenAPI contract the API validates against — this SDK and the TypeScript one are siblings, not translations.
@@ -44,7 +44,7 @@ best = resolved.best          # None when nothing clears the confidence floor
 print(best.ref)               # "model:tesla/model-y"
 
 # 2. Dereference a ref: node + parents/children + counts + links
-detail = client.v2.entities.get(best.ref)
+detail = client.v2.entities.get_by_ref(best.ref)
 print(detail.name, detail.counts)
 
 # 3. Query with refs — never fuzzy, never guessed
@@ -65,18 +65,18 @@ for listing in results.listings:
 
 ```python
 # VIN → graph identity card (refs, grains, links)
-identity = client.v2.vin.get("5YJSA1E26MF420053")
+identity = client.v2.vin.get_by_vin("5YJSA1E28MF420053")
 print(identity.make, identity.model, identity.refs.model_year)
 
 # Batch decode (metered per VIN, max 1000) — one bad VIN fails its own row, never the batch
-batch = client.v2.vin.batch(["5YJSA1E26MF420053", "1HGCV1F34LA045661"])
+batch = client.v2.vin.batch(["5YJSA1E28MF420053", "1HGCV1F34LA045661"])
 
 # Recalls affecting a VIN (Transport Canada + NHTSA fused)
-recalls = client.v2.recalls.vin("5YJSA1E26MF420053")
+recalls = client.v2.recalls.vin("5YJSA1E28MF420053")
 
 # VIN → market instrument bridge, quotes, tape
-instrument = client.v2.vin.instrument("5YJSA1E26MF420053")
-quote = client.v2.quotes.get("model-year:toyota/rav4/2021")
+instrument = client.v2.vin.instrument("5YJSA1E28MF420053")
+quote = client.v2.quotes.get_by_ref("model-year:toyota/rav4/2021")
 bars = client.v2.tape.history("model-year:toyota/rav4/2021", window="3m")
 ```
 
@@ -112,7 +112,7 @@ from cardog import AsyncCardog
 
 async def main():
     client = AsyncCardog(api_key="your-api-key")
-    identity = await client.v2.vin.get("5YJSA1E26MF420053")
+    identity = await client.v2.vin.get_by_vin("5YJSA1E28MF420053")
     results = await client.v2.listings.search(filters={"makes": ["make:tesla"]})
     await client.close()
 
@@ -123,18 +123,28 @@ asyncio.run(main())
 
 | Group | Methods |
 |-------|---------|
-| `client.v2.entities` | `browse(domain, ...)` · `resolve(q, ...)` · `get(ref)` |
-| `client.v2.vin` | `get(vin)` · `batch(vins)` · `recalls(vin)` · `listings(vin)` · `instrument(vin)` |
+| `client.v2.entities` | `browse(domain, ...)` · `resolve(q, ...)` · `get_by_ref(ref)` |
+| `client.v2.vin` | `get_by_vin(vin)` · `batch(vins)` · `recalls(vin)` · `listings(vin)` · `instrument(vin)` |
 | `client.v2.specs` | `catalog()` · `sheet(ref, trim=...)` |
 | `client.v2.listings` | `search(...)` · `count(...)` · `facets(...)` · `by_vin(vin)` · `by_id(id)` |
-| `client.v2.instruments` | `search(q=..., limit=...)` · `get(ref, window=...)` |
-| `client.v2.quotes` | `get(ref)` · `get_many(refs)` |
+| `client.v2.instruments` | `search(q=..., limit=...)` · `get_by_ref(ref, window=...)` |
+| `client.v2.quotes` | `get_by_ref(ref)` · `get_many(refs)` |
 | `client.v2.tape` | `live(limit=...)` · `history(ref, window=...)` |
-| `client.v2.recalls` | `vin(vin)` · `entity(ref)` · `feed()` · `stats()` · `get(ref)` |
+| `client.v2.recalls` | `vin(vin)` · `entity(ref)` · `feed()` · `stats()` · `get_by_ref(ref)` |
 | `client.v2.safety` | `ratings(ref)` · `complaints(ref, page=..., limit=...)` |
 | platform meta | `client.v2.pricing()` · `client.v2.openapi()` (both unauthenticated) |
 
-The machine-readable rate card (`pricing()`) plus the `X-Credits-*` response headers let you budget mid-task; `openapi()` returns the same contract this SDK is generated from.
+The machine-readable rate card (`pricing()`) plus the `X-Credits-*` response headers let you budget mid-task; `openapi()` returns the same contract this SDK is generated from. The client keeps the last set of those headers parsed on `client.last_credits`, errors included (a 402 states the budget too):
+
+```python
+client.v2.vin.get_by_vin("5YJSA1E28MF420053")
+credits = client.last_credits  # a Credits, or None before any metered call
+print(credits.rate, credits.remaining, credits.allowance, credits.reset, credits.source)
+# rate: what that call cost · remaining: allowance headroom + pack balance (-1 = custom plan)
+# reset: when the allowance rolls over · source: "allowance" | "pack" | "overage", None when nothing was debited
+```
+
+Errors carry the envelope: `err.code` to branch on, `err.message` on its own, `err.hint` for what to do next. `str(err)` is the log line, `[status] (code) message`.
 
 ## v1 (legacy)