fleet-costs-sdk 0.4.0__tar.gz

fleet_costs_sdk-0.4.0/.gitignore

@@ -0,0 +1,9 @@
+# Python build artifacts
+dist/
+build/
+*.egg-info/
+*.pyc
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

fleet_costs_sdk-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lodewijk Wensveen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fleet_costs_sdk-0.4.0/PKG-INFO

@@ -0,0 +1,335 @@
+Metadata-Version: 2.5
+Name: fleet-costs-sdk
+Version: 0.4.0
+Summary: Official Python SDK for the Fleet Costs landed-cost / duty / VAT / freight pricing API.
+Project-URL: Homepage, https://getfleet.dev
+Project-URL: Documentation, https://docs.getfleet.dev/guides/python-sdk
+Project-URL: API reference, https://docs.getfleet.dev
+Project-URL: Support, https://getfleet.dev/contact
+Author-email: Fleet <support@getfleet.dev>
+Maintainer-email: Fleet <support@getfleet.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cross-border,customs,duty,fleet,hs-code,hts,import,landed-cost,sdk,vat
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fleet-costs-sdk
+
+Official Python SDK for the [Fleet Costs](https://getfleet.dev) landed-cost /
+duty / VAT / freight pricing API.
+
+```bash
+pip install fleet-costs-sdk
+```
+
+```python
+from fleet import FleetClient
+
+client = FleetClient(
+    base_url="https://api.getfleet.dev",
+    api_key="ck_live_...",
+)
+
+quote = client.create_quote({
+    "origin": "US",
+    "dest": "DE",
+    "itemValue": {"amount": 100, "currency": "USD"},
+    "dimsCm": {"l": 20, "w": 15, "h": 5},
+    "weightKg": 0.5,
+    "categoryKey": "electronics.smartphone",
+    "mode": "air",
+    "hs6": "851712",  # optional: supply a 6-, 8- or 10-digit commodity code
+})
+
+print(quote["total"])
+```
+
+## Features
+
+- Synchronous client built on [httpx](https://www.python-httpx.org/).
+- Automatic retries on transient failures (429, 500, 502, 503, 504) with
+  exponential backoff.
+- Idempotency key support on mutating endpoints — safe to retry writes.
+- Context manager support (`with FleetClient(...) as client: ...`).
+- Typed method surface covering quotes, classify, manifests, and lookups.
+
+## Documentation
+
+- API reference: https://docs.getfleet.dev
+- Python SDK guide: https://docs.getfleet.dev/guides/python-sdk
+- Support: https://getfleet.dev/contact or support@getfleet.dev
+
+## License
+
+MIT — see the `LICENSE` file included in this package.
+
+## Collection assessment
+
+Quote methods preserve the API's `assessment` dictionary. Before collecting import charges,
+require `quote["assessment"]["collection"]["eligible"] is True`. Its `outcome` is
+`complete`, `estimated`, or `refused`; display the `reasons` and their `message` and `action`
+alongside any estimate. A maximum or confidence score is not collection permission.
+Category-only quotes remain estimates. Missing assessment on an older saved response requires
+a fresh quote with a new idempotency key before collection.
+
+## Retry and recovery keys
+
+Mutating methods return a `FleetResponse`: the usual response dictionary, plus an
+`idempotency_key` attribute containing the key actually sent. The attribute is SDK
+metadata and is not added to the API JSON fields.
+
+```python
+import httpx
+from fleet import FleetAPIError
+
+try:
+    quote = client.create_quote(body)
+    recovery_key = quote.idempotency_key
+except FleetAPIError as error:
+    recovery_key = error.idempotency_key
+    server_code = error.code
+except httpx.RequestError as error:
+    recovery_key = error.idempotency_key
+except ValueError as error:
+    recovery_key = error.idempotency_key
+```
+
+For a timed-out quote, use `client.get_quote_by_key(recovery_key)` to retrieve a
+result that may have completed server-side. A missing result is not evidence that
+it is safe to create the same order under another key.
+
+The SDK keeps the same key on network errors, ordinary transient HTTP failures,
+and `409 IDEMPOTENCY_KEY_PROCESSING`. It generates a replacement only after
+`409 IDEMPOTENCY_KEY_FAILED` explicitly confirms rollback, and only when the SDK
+created the key. A caller's `idempotency_key` is never replaced. Unrelated conflicts
+are not retried. Retries share the configured `max_retries` budget; HTTP and
+transport failures expose the final attempted key even when that budget is zero.
+Invalid JSON and HTTPX response-decoding failures also retain the key on the
+original exception; non-transport decoding failures are not retried.
+
+`create_quote` and `create_quote_batch` require decoded JSON success responses to
+be objects. JSON `null`, arrays and scalars raise `ValueError` with the final
+`idempotency_key`, without retrying the write. This checks only the top-level
+shape: empty objects and nested nullable fields are retained unchanged. Invalid
+JSON still raises its original parsing exception with the final recovery key.
+
+## Complete consignments and batch quotes
+
+Use `client.create_quote_batch(items)` for 1–50 quote inputs. All items are sent in
+one request, in their original order, including non-adjacent members of a declared
+consignment. Supply the complete membership and the canonical declaration facts;
+the SDK does not invent grouping, split oversized batches, or change delivery and
+freight inputs. An explicit zero `deliveryCharge` is different from an omitted value.
+
+`insurance` is the premium actually paid and not already in `itemValue`. It is handled as
+freight is: part of `components.CIF` and `total` everywhere, and of the duty base only
+where duty is valued CIF (not the US). For a CN destination, omit it when no insurance
+was paid and the API applies the
+customs presumption of 3 per mille of goods plus freight (`cn_insurance_presumed`); send
+`{"amount": 0, ...}` when the insurance is already included in `itemValue`. In the
+response, `insurance` is the declared premium inside `components.CIF` and `total`, and
+`presumedInsurance` is the CN presumption: duty and VAT are computed on it, but it is not
+part of `components.CIF` or `total`, since nobody pays it. The SDK sends whichever of the
+three states you give it unchanged.
+
+Inspect `results`, `succeeded` and `failed`: an HTTP success may contain per-item
+errors or estimates, and `status == "ok"` does not grant collection permission.
+Assessments and allocation details are retained unchanged.
+
+The batch response exposes `result.idempotency_key`. To recover a timed-out batch,
+repeat `create_quote_batch` with the **identical full items** and that final key.
+`get_quote_by_key` reads single quotes and cannot replay a batch key.
+
+## Dispatch and customs status
+
+Quote inputs are dictionaries. Single and batch methods preserve the canonical
+`declaration.movement` object without adding defaults or validating customs facts:
+
+```python
+body = {
+    "origin": "CN",  # country of manufacture
+    "dispatchCountry": "DE",  # actual ship-from country
+    "dest": "FR",
+    "itemValue": {"amount": 200, "currency": "EUR"},
+    "dimsCm": {"l": 10, "w": 10, "h": 10},
+    "weightKg": 2,
+    "categoryKey": "apparel.tshirt",
+    "hs6": "610910",
+    "mode": "air",
+    "freight": {"amount": 25, "currency": "EUR"},
+    "deliveryCharge": {"amount": 0, "currency": "EUR"},
+    "declaration": {"movement": {"customsStatus": "free_circulation"}},
+}
+quote = client.create_quote(body)
+```
+
+The status describes the goods **at this sale in the dispatch customs territory**.
+`free_circulation` means qualifying goods are already in free circulation before
+the sale, with no release/entry lodged to fulfil this order. Use
+`not_in_free_circulation` when a customs debt or conditional procedure remains,
+including bonded stock that will be released to fulfil this order. This is the
+merchant's assertion from their records; Fleet does not verify release evidence.
+Do not derive it from manufacture, warehouse country, IOSS registration or an unset
+Boolean. Supply actual `dispatchCountry` with a known status; omit `movement` when
+unknown. An empty movement object or a made-up status is not an unknown value.
+
+Movement is per line: items sharing a complete consignment may have different
+statuses. Preserve those facts; do not split a consignment to change its treatment.
+On a no-border lane, a required release produces `customs_release_not_modelled`
+and a refused assessment with a null maximum. Other qualifications remain
+independent, including `vat_buyer_status_unresolved`. Neither declared free
+circulation nor a successful batch item establishes collection permission, buyer
+VAT entitlement, seller registration or the correct remittance jurisdiction.
+
+`explainability.duty.customsStatusSource` records `request` for a merchant declaration
+and `assumed` for an inferred status on applicable no-border quotes. It is absent
+on border quotes and can be absent on historical records, including records with
+no `explainability` block. Preserve that absence; never fill it with `assumed` or
+interpret `request` as verified. The response dictionary retains complete reasons,
+warnings, missing components and nullable ceilings alongside this provenance.
+
+## Distance-sales attestation
+
+A seller established in an EU member state, with no OSS registration, can attest
+that it is under that state's distance-selling threshold (EUR 10,000 in the euro
+area, the national figure elsewhere). State the total in the threshold's currency;
+`client.get_distance_sales_threshold("PL")` says which. Quotes whose
+request declares `dispatchCountry` equal to the attested state can then price
+consumer sales at the dispatch state's rate:
+
+```python
+profile = client.set_distance_sales_attestation({
+    "statementVersion": 1,
+    "establishmentCountry": "NL",
+    "sellsOnOwnAccount": True,
+    "establishedOnlyThere": True,
+    "dispatchesOnlyFromThere": True,
+    "noDestinationTaxationOption": True,
+    "noSmallEnterpriseExemption": True,
+    "priorYearWithinThreshold": True,
+    "currentYearTotal": {"amount": 4200, "currency": "EUR"},
+    "currentYearTotalAsOf": "2026-09-20",
+    "exclusionsAcknowledged": True,
+})
+profile["distanceSalesAttestation"]["inEffect"]
+
+# As soon as the current-year total passes the threshold:
+client.withdraw_distance_sales_attestation()
+```
+
+Every statement is a literal `True`: send the attestation only if the seller can
+affirm each one. It needs a live key with `self:write`; Test-mode keys are refused,
+and the API does not check who holds the key.
+
+`explainability.vat.supplyVatSchemeSource` names what decided where a consumer sale is taxed (`oss_registration`,
+`destination_registration`, `declared_destination`, `attestation` or `assumed`) on a cross-border intra-EU supply
+priced OSS or domestic. `declared_destination` means the seller states destination taxation with no OSS or
+destination VAT registration on file; such an OSS-priced quote cannot be collected.
+It is absent on reverse charge, domestic movements, imports and older saved quotes.
+`explainability.vat.thresholdAttestation` is present only where the engine consulted an attestation on file (no OSS
+registration, a domestic-scheme price): `applied`, or `not_applied` with a `reason`.
+Preserve both absences; do not fill them in.
+
+## Buyer VAT numbers
+
+Send the buyer's VAT number, country prefix included, as
+`declaration.buyer.vatNumber`, and `declaration.buyer.taxStatus:
+"vat_registered_business"` only where your checkout captured it. Never derive the
+status from the presence of a number.
+
+Where an EU number could decide an intra-EU supply, Fleet checks it against VIES and
+reports the result in `explainability.vat.buyerVatCheck`: `status` (`valid`, `invalid`, `unavailable`, or
+`not_checked` with a `reason`), `numberCountry`, `requesterCountry`, `checkedAt` and
+`requestIdentifier`, the VIES consultation number to keep with the invoice. The
+number itself is never echoed.
+
+A check needs your VAT registration for the dispatch state recorded in Fleet as the
+requester. Without it the result is `not_checked` with reason
+`no_requester_registration`, test keys included. Live keys in production are not
+checked until the switch-on (#2369). Test keys get a simulator that sends nothing
+anywhere: national part `100` is valid and `200` invalid. GB numbers are not checked
+yet.
+
+What the result changes depends on the lane, so read each quote's warnings rather than
+these notes:
+
+- **A number from another member state** (an exempt supply). A `valid` number beside
+  `vat_registered_business` replaces `vat_reverse_charge_conditional` with the
+  information code `vat_intra_eu_exemption_number_verified`, and the quote can
+  complete. VIES confirms a registration, not who is buying, so a valid number without
+  that status does not. VAT confidence stays capped at `estimated` and
+  `guaranteedMax` keeps its reserve either way, because the exemption also rests on
+  your own recapitulative statement. `unavailable` and `not_checked` leave the quote
+  as it would be without a check.
+- **A number from the dispatch state** never makes the supply exempt. A valid one
+  beside `vat_registered_business` prices dispatch-state VAT and discloses it with
+  `vat_reverse_charge_not_available`.
+- **An `invalid` number**, from either, is priced as absent. It blocks collection with
+  `vat_buyer_vat_number_invalid` only where that could change the rate; where it
+  cannot, such as equal rates or an applied distance-sales attestation, the quote
+  discloses it with `vat_reverse_charge_not_available`.
+
+On a GB business import of GBP 135 or less, a GB number gives a conditional zero
+(`vat_reverse_charge_conditional`) with no `guaranteedMax`. Rows from `export_quotes` carry the same `buyerVatCheck`, so
+the consultation number stays linked to its quote.
+
+For the separate [organization data export](https://docs.getfleet.dev/api/data-retention),
+use `GET /v1/data-retention/export` with `self:read` scope as an organization owner or admin.
+Retained consultation records appear in `data.viesConsultations`, newest first, up to 10,000.
+`completeness.viesConsultationsIncluded` gives the returned count;
+`completeness.viesConsultationsTruncated` says whether more records exist.
+These records are separate from per-quote `buyerVatCheck`. This organization export excludes
+single-quote history, manifest quotes and manifest documents; it is not a complete quote-history export.
+
+### Great Britain and Northern Ireland
+
+For quote and manifest requests with destination `GB` (or `UK`), explicitly send
+`gbDeliveryTerritory: "great_britain"` or `"northern_ireland"` for the actual delivery.
+No SDK supplies a default. Omission returns HTTP 422
+`GB_DELIVERY_TERRITORY_REQUIRED`; Northern Ireland returns HTTP 422
+`TERRITORY_NOT_SUPPORTED`. Do not derive Great Britain from the country code alone.
+
+## Gateway headers
+
+Use the public `extra_headers` option when your chosen API gateway requires
+additional headers. For example, a Cloudflare Access protected origin can use:
+
+```python
+import os
+from fleet import FleetClient
+
+with FleetClient(
+    base_url=os.environ["FLEET_API_URL"],
+    api_key=os.environ["FLEET_API_KEY"],
+    extra_headers={
+        "CF-Access-Client-Id": os.environ["CF_ACCESS_CLIENT_ID"],
+        "CF-Access-Client-Secret": os.environ["CF_ACCESS_CLIENT_SECRET"],
+    },
+) as client:
+    quote = client.create_quote(body)
+```
+
+The mapping is copied at construction. Header names are case-insensitive;
+invalid/duplicate names, non-ASCII/control-character values and SDK-controlled
+authentication, idempotency, host, framing and hop-by-hop headers raise `ValueError`.
+Keep the API key in `api_key` and operation keys in `idempotency_key`.
+Redirects are not followed, so gateway credentials are not forwarded to a
+redirect destination. Use a trusted HTTPS origin for real credentials.

fleet_costs_sdk-0.4.0/README.md

@@ -0,0 +1,302 @@
+# fleet-costs-sdk
+
+Official Python SDK for the [Fleet Costs](https://getfleet.dev) landed-cost /
+duty / VAT / freight pricing API.
+
+```bash
+pip install fleet-costs-sdk
+```
+
+```python
+from fleet import FleetClient
+
+client = FleetClient(
+    base_url="https://api.getfleet.dev",
+    api_key="ck_live_...",
+)
+
+quote = client.create_quote({
+    "origin": "US",
+    "dest": "DE",
+    "itemValue": {"amount": 100, "currency": "USD"},
+    "dimsCm": {"l": 20, "w": 15, "h": 5},
+    "weightKg": 0.5,
+    "categoryKey": "electronics.smartphone",
+    "mode": "air",
+    "hs6": "851712",  # optional: supply a 6-, 8- or 10-digit commodity code
+})
+
+print(quote["total"])
+```
+
+## Features
+
+- Synchronous client built on [httpx](https://www.python-httpx.org/).
+- Automatic retries on transient failures (429, 500, 502, 503, 504) with
+  exponential backoff.
+- Idempotency key support on mutating endpoints — safe to retry writes.
+- Context manager support (`with FleetClient(...) as client: ...`).
+- Typed method surface covering quotes, classify, manifests, and lookups.
+
+## Documentation
+
+- API reference: https://docs.getfleet.dev
+- Python SDK guide: https://docs.getfleet.dev/guides/python-sdk
+- Support: https://getfleet.dev/contact or support@getfleet.dev
+
+## License
+
+MIT — see the `LICENSE` file included in this package.
+
+## Collection assessment
+
+Quote methods preserve the API's `assessment` dictionary. Before collecting import charges,
+require `quote["assessment"]["collection"]["eligible"] is True`. Its `outcome` is
+`complete`, `estimated`, or `refused`; display the `reasons` and their `message` and `action`
+alongside any estimate. A maximum or confidence score is not collection permission.
+Category-only quotes remain estimates. Missing assessment on an older saved response requires
+a fresh quote with a new idempotency key before collection.
+
+## Retry and recovery keys
+
+Mutating methods return a `FleetResponse`: the usual response dictionary, plus an
+`idempotency_key` attribute containing the key actually sent. The attribute is SDK
+metadata and is not added to the API JSON fields.
+
+```python
+import httpx
+from fleet import FleetAPIError
+
+try:
+    quote = client.create_quote(body)
+    recovery_key = quote.idempotency_key
+except FleetAPIError as error:
+    recovery_key = error.idempotency_key
+    server_code = error.code
+except httpx.RequestError as error:
+    recovery_key = error.idempotency_key
+except ValueError as error:
+    recovery_key = error.idempotency_key
+```
+
+For a timed-out quote, use `client.get_quote_by_key(recovery_key)` to retrieve a
+result that may have completed server-side. A missing result is not evidence that
+it is safe to create the same order under another key.
+
+The SDK keeps the same key on network errors, ordinary transient HTTP failures,
+and `409 IDEMPOTENCY_KEY_PROCESSING`. It generates a replacement only after
+`409 IDEMPOTENCY_KEY_FAILED` explicitly confirms rollback, and only when the SDK
+created the key. A caller's `idempotency_key` is never replaced. Unrelated conflicts
+are not retried. Retries share the configured `max_retries` budget; HTTP and
+transport failures expose the final attempted key even when that budget is zero.
+Invalid JSON and HTTPX response-decoding failures also retain the key on the
+original exception; non-transport decoding failures are not retried.
+
+`create_quote` and `create_quote_batch` require decoded JSON success responses to
+be objects. JSON `null`, arrays and scalars raise `ValueError` with the final
+`idempotency_key`, without retrying the write. This checks only the top-level
+shape: empty objects and nested nullable fields are retained unchanged. Invalid
+JSON still raises its original parsing exception with the final recovery key.
+
+## Complete consignments and batch quotes
+
+Use `client.create_quote_batch(items)` for 1–50 quote inputs. All items are sent in
+one request, in their original order, including non-adjacent members of a declared
+consignment. Supply the complete membership and the canonical declaration facts;
+the SDK does not invent grouping, split oversized batches, or change delivery and
+freight inputs. An explicit zero `deliveryCharge` is different from an omitted value.
+
+`insurance` is the premium actually paid and not already in `itemValue`. It is handled as
+freight is: part of `components.CIF` and `total` everywhere, and of the duty base only
+where duty is valued CIF (not the US). For a CN destination, omit it when no insurance
+was paid and the API applies the
+customs presumption of 3 per mille of goods plus freight (`cn_insurance_presumed`); send
+`{"amount": 0, ...}` when the insurance is already included in `itemValue`. In the
+response, `insurance` is the declared premium inside `components.CIF` and `total`, and
+`presumedInsurance` is the CN presumption: duty and VAT are computed on it, but it is not
+part of `components.CIF` or `total`, since nobody pays it. The SDK sends whichever of the
+three states you give it unchanged.
+
+Inspect `results`, `succeeded` and `failed`: an HTTP success may contain per-item
+errors or estimates, and `status == "ok"` does not grant collection permission.
+Assessments and allocation details are retained unchanged.
+
+The batch response exposes `result.idempotency_key`. To recover a timed-out batch,
+repeat `create_quote_batch` with the **identical full items** and that final key.
+`get_quote_by_key` reads single quotes and cannot replay a batch key.
+
+## Dispatch and customs status
+
+Quote inputs are dictionaries. Single and batch methods preserve the canonical
+`declaration.movement` object without adding defaults or validating customs facts:
+
+```python
+body = {
+    "origin": "CN",  # country of manufacture
+    "dispatchCountry": "DE",  # actual ship-from country
+    "dest": "FR",
+    "itemValue": {"amount": 200, "currency": "EUR"},
+    "dimsCm": {"l": 10, "w": 10, "h": 10},
+    "weightKg": 2,
+    "categoryKey": "apparel.tshirt",
+    "hs6": "610910",
+    "mode": "air",
+    "freight": {"amount": 25, "currency": "EUR"},
+    "deliveryCharge": {"amount": 0, "currency": "EUR"},
+    "declaration": {"movement": {"customsStatus": "free_circulation"}},
+}
+quote = client.create_quote(body)
+```
+
+The status describes the goods **at this sale in the dispatch customs territory**.
+`free_circulation` means qualifying goods are already in free circulation before
+the sale, with no release/entry lodged to fulfil this order. Use
+`not_in_free_circulation` when a customs debt or conditional procedure remains,
+including bonded stock that will be released to fulfil this order. This is the
+merchant's assertion from their records; Fleet does not verify release evidence.
+Do not derive it from manufacture, warehouse country, IOSS registration or an unset
+Boolean. Supply actual `dispatchCountry` with a known status; omit `movement` when
+unknown. An empty movement object or a made-up status is not an unknown value.
+
+Movement is per line: items sharing a complete consignment may have different
+statuses. Preserve those facts; do not split a consignment to change its treatment.
+On a no-border lane, a required release produces `customs_release_not_modelled`
+and a refused assessment with a null maximum. Other qualifications remain
+independent, including `vat_buyer_status_unresolved`. Neither declared free
+circulation nor a successful batch item establishes collection permission, buyer
+VAT entitlement, seller registration or the correct remittance jurisdiction.
+
+`explainability.duty.customsStatusSource` records `request` for a merchant declaration
+and `assumed` for an inferred status on applicable no-border quotes. It is absent
+on border quotes and can be absent on historical records, including records with
+no `explainability` block. Preserve that absence; never fill it with `assumed` or
+interpret `request` as verified. The response dictionary retains complete reasons,
+warnings, missing components and nullable ceilings alongside this provenance.
+
+## Distance-sales attestation
+
+A seller established in an EU member state, with no OSS registration, can attest
+that it is under that state's distance-selling threshold (EUR 10,000 in the euro
+area, the national figure elsewhere). State the total in the threshold's currency;
+`client.get_distance_sales_threshold("PL")` says which. Quotes whose
+request declares `dispatchCountry` equal to the attested state can then price
+consumer sales at the dispatch state's rate:
+
+```python
+profile = client.set_distance_sales_attestation({
+    "statementVersion": 1,
+    "establishmentCountry": "NL",
+    "sellsOnOwnAccount": True,
+    "establishedOnlyThere": True,
+    "dispatchesOnlyFromThere": True,
+    "noDestinationTaxationOption": True,
+    "noSmallEnterpriseExemption": True,
+    "priorYearWithinThreshold": True,
+    "currentYearTotal": {"amount": 4200, "currency": "EUR"},
+    "currentYearTotalAsOf": "2026-09-20",
+    "exclusionsAcknowledged": True,
+})
+profile["distanceSalesAttestation"]["inEffect"]
+
+# As soon as the current-year total passes the threshold:
+client.withdraw_distance_sales_attestation()
+```
+
+Every statement is a literal `True`: send the attestation only if the seller can
+affirm each one. It needs a live key with `self:write`; Test-mode keys are refused,
+and the API does not check who holds the key.
+
+`explainability.vat.supplyVatSchemeSource` names what decided where a consumer sale is taxed (`oss_registration`,
+`destination_registration`, `declared_destination`, `attestation` or `assumed`) on a cross-border intra-EU supply
+priced OSS or domestic. `declared_destination` means the seller states destination taxation with no OSS or
+destination VAT registration on file; such an OSS-priced quote cannot be collected.
+It is absent on reverse charge, domestic movements, imports and older saved quotes.
+`explainability.vat.thresholdAttestation` is present only where the engine consulted an attestation on file (no OSS
+registration, a domestic-scheme price): `applied`, or `not_applied` with a `reason`.
+Preserve both absences; do not fill them in.
+
+## Buyer VAT numbers
+
+Send the buyer's VAT number, country prefix included, as
+`declaration.buyer.vatNumber`, and `declaration.buyer.taxStatus:
+"vat_registered_business"` only where your checkout captured it. Never derive the
+status from the presence of a number.
+
+Where an EU number could decide an intra-EU supply, Fleet checks it against VIES and
+reports the result in `explainability.vat.buyerVatCheck`: `status` (`valid`, `invalid`, `unavailable`, or
+`not_checked` with a `reason`), `numberCountry`, `requesterCountry`, `checkedAt` and
+`requestIdentifier`, the VIES consultation number to keep with the invoice. The
+number itself is never echoed.
+
+A check needs your VAT registration for the dispatch state recorded in Fleet as the
+requester. Without it the result is `not_checked` with reason
+`no_requester_registration`, test keys included. Live keys in production are not
+checked until the switch-on (#2369). Test keys get a simulator that sends nothing
+anywhere: national part `100` is valid and `200` invalid. GB numbers are not checked
+yet.
+
+What the result changes depends on the lane, so read each quote's warnings rather than
+these notes:
+
+- **A number from another member state** (an exempt supply). A `valid` number beside
+  `vat_registered_business` replaces `vat_reverse_charge_conditional` with the
+  information code `vat_intra_eu_exemption_number_verified`, and the quote can
+  complete. VIES confirms a registration, not who is buying, so a valid number without
+  that status does not. VAT confidence stays capped at `estimated` and
+  `guaranteedMax` keeps its reserve either way, because the exemption also rests on
+  your own recapitulative statement. `unavailable` and `not_checked` leave the quote
+  as it would be without a check.
+- **A number from the dispatch state** never makes the supply exempt. A valid one
+  beside `vat_registered_business` prices dispatch-state VAT and discloses it with
+  `vat_reverse_charge_not_available`.
+- **An `invalid` number**, from either, is priced as absent. It blocks collection with
+  `vat_buyer_vat_number_invalid` only where that could change the rate; where it
+  cannot, such as equal rates or an applied distance-sales attestation, the quote
+  discloses it with `vat_reverse_charge_not_available`.
+
+On a GB business import of GBP 135 or less, a GB number gives a conditional zero
+(`vat_reverse_charge_conditional`) with no `guaranteedMax`. Rows from `export_quotes` carry the same `buyerVatCheck`, so
+the consultation number stays linked to its quote.
+
+For the separate [organization data export](https://docs.getfleet.dev/api/data-retention),
+use `GET /v1/data-retention/export` with `self:read` scope as an organization owner or admin.
+Retained consultation records appear in `data.viesConsultations`, newest first, up to 10,000.
+`completeness.viesConsultationsIncluded` gives the returned count;
+`completeness.viesConsultationsTruncated` says whether more records exist.
+These records are separate from per-quote `buyerVatCheck`. This organization export excludes
+single-quote history, manifest quotes and manifest documents; it is not a complete quote-history export.
+
+### Great Britain and Northern Ireland
+
+For quote and manifest requests with destination `GB` (or `UK`), explicitly send
+`gbDeliveryTerritory: "great_britain"` or `"northern_ireland"` for the actual delivery.
+No SDK supplies a default. Omission returns HTTP 422
+`GB_DELIVERY_TERRITORY_REQUIRED`; Northern Ireland returns HTTP 422
+`TERRITORY_NOT_SUPPORTED`. Do not derive Great Britain from the country code alone.
+
+## Gateway headers
+
+Use the public `extra_headers` option when your chosen API gateway requires
+additional headers. For example, a Cloudflare Access protected origin can use:
+
+```python
+import os
+from fleet import FleetClient
+
+with FleetClient(
+    base_url=os.environ["FLEET_API_URL"],
+    api_key=os.environ["FLEET_API_KEY"],
+    extra_headers={
+        "CF-Access-Client-Id": os.environ["CF_ACCESS_CLIENT_ID"],
+        "CF-Access-Client-Secret": os.environ["CF_ACCESS_CLIENT_SECRET"],
+    },
+) as client:
+    quote = client.create_quote(body)
+```
+
+The mapping is copied at construction. Header names are case-insensitive;
+invalid/duplicate names, non-ASCII/control-character values and SDK-controlled
+authentication, idempotency, host, framing and hop-by-hop headers raise `ValueError`.
+Keep the API key in `api_key` and operation keys in `idempotency_key`.
+Redirects are not followed, so gateway credentials are not forwarded to a
+redirect destination. Use a trusted HTTPS origin for real credentials.

fleet_costs_sdk-0.4.0/fleet/__init__.py

@@ -0,0 +1,6 @@
+"""Fleet Python SDK — landed-cost API client."""
+
+from .client import FleetAPIError, FleetClient, FleetResponse
+
+__all__ = ["FleetAPIError", "FleetClient", "FleetResponse"]
+__version__ = "0.4.0"

fleet_costs_sdk-0.4.0/fleet/client.py

@@ -0,0 +1,559 @@
+"""Fleet API client with retry logic and idempotency support."""
+
+from __future__ import annotations
+
+import random
+import re
+import secrets
+import time
+from base64 import urlsafe_b64encode
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any
+from collections.abc import Mapping
+from urllib.parse import quote
+
+import httpx
+
+# Maximum backoff/Retry-After wait, in seconds.
+_MAX_DELAY = 30.0
+
+# Authentication, recovery and HTTP framing belong to the SDK/HTTP client.
+# Reject aliases case-insensitively so additional gateway headers cannot silently
+# replace a bearer key or turn one logical retry into a different operation.
+_RESERVED_HEADERS = frozenset({
+    "authorization", "x-api-key", "idempotency-key", "host", "content-type",
+    "content-length", "transfer-encoding", "connection", "keep-alive",
+    "proxy-authenticate", "proxy-authorization", "te", "trailer", "upgrade",
+})
+
+
+def _extra_headers(headers: Mapping[str, str] | None) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for name, value in (headers or {}).items():
+        if (not isinstance(name, str) or not re.fullmatch(r"[!#$%&'*+.^_`|~0-9A-Za-z-]+", name)
+                or name.lower() in _RESERVED_HEADERS):
+            raise ValueError("extra_headers contains an invalid or SDK-controlled header name")
+        # Constant diagnostics deliberately exclude potentially secret values.
+        if (not isinstance(value, str) or value != value.strip()
+                or any(ord(c) < 32 or ord(c) > 126 for c in value)):
+            raise ValueError("extra_headers contains an invalid header value")
+        if name.lower() in result:
+            raise ValueError("extra_headers contains duplicate header names")
+        result[name.lower()] = value
+    return result
+
+
+def _encode_path_segment(segment: str) -> str:
+    """Percent-encode a user-supplied value for use as a single URL path segment.
+
+    Reserved-character escaping matches the Go SDK's ``encodePathSegment``:
+    every non-unreserved byte is percent-encoded. It is slightly stricter than
+    the TS SDK's ``encodeURIComponent``,
+    which leaves ``! * ' ( )`` bare — both decode identically server-side: without this, a key containing ``/`` adds path
+    segments, ``?`` truncates into a query string, ``#`` into a fragment, and a
+    bare ``%`` produces an invalid percent-sequence.
+    """
+    if not isinstance(segment, str):
+        raise TypeError(f"path segment must be a str, got {type(segment).__name__}")
+    # quote() always leaves dots unescaped, even with safe="". HTTPX removes
+    # literal dot segments while merging the base URL, losing valid recovery
+    # keys "." and ".." before sending the request (#2784).
+    if segment in (".", ".."):
+        return "%2E" * len(segment)
+    return quote(segment, safe="")
+
+
+def _gen_idem_key() -> str:
+    """Generate a unique idempotency key prefixed with ``ck_idem_``."""
+    raw = secrets.token_bytes(16)
+    b64 = urlsafe_b64encode(raw).rstrip(b"=").decode()
+    return f"ck_idem_{b64}"
+
+
+def _backoff_delay(attempt: int, *, initial: float = 0.5, maximum: float = _MAX_DELAY) -> float:
+    """Exponential backoff with full jitter, in seconds.
+
+    ``delay = uniform(0, min(maximum, initial * 2**attempt))``
+    """
+    ceiling = min(maximum, initial * (2**attempt))
+    return random.uniform(0.0, ceiling)
+
+
+def _parse_retry_after(resp: httpx.Response) -> float | None:
+    """Parse a ``Retry-After`` header into seconds.
+
+    Accepts both the numeric-seconds and HTTP-date forms. Returns ``None`` when
+    the header is absent or unparseable.
+    """
+    header = resp.headers.get("retry-after")
+    if not header:
+        return None
+
+    # Numeric seconds.
+    try:
+        secs = float(header)
+        if secs >= 0:
+            return secs
+    except ValueError:
+        pass
+
+    # HTTP-date.
+    try:
+        when = parsedate_to_datetime(header)
+    except (TypeError, ValueError):
+        return None
+    # A "-0000" offset yields a naive datetime; normalise to UTC so the
+    # subtraction below never mixes aware and naive datetimes.
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+    delta = (when - datetime.now(timezone.utc)).total_seconds()
+    return max(0.0, delta)
+
+
+class FleetResponse(dict[str, Any]):
+    """API response fields with SDK recovery metadata outside the JSON payload."""
+
+    def __init__(self, data: dict[str, Any], idempotency_key: str) -> None:
+        super().__init__(data)
+        self.idempotency_key = idempotency_key
+
+
+class FleetAPIError(httpx.HTTPStatusError):
+    """HTTP failure with the server code and the key actually sent."""
+
+    def __init__(
+        self, error: httpx.HTTPStatusError, code: str | None, idempotency_key: str | None
+    ) -> None:
+        super().__init__(str(error), request=error.request, response=error.response)
+        self.code = code
+        self.idempotency_key = idempotency_key
+
+
+class FleetClient:
+    """Synchronous client for the Fleet API.
+
+    Args:
+        base_url: API base URL (e.g. ``https://api.getfleet.dev``).
+        api_key: Bearer API key.
+        max_retries: Maximum retry attempts for transient failures (default 3).
+        timeout: Request timeout in seconds (default 30).
+        extra_headers: Optional gateway headers, copied at construction. SDK
+            authentication, idempotency and HTTP framing headers are reserved.
+    """
+
+    RETRYABLE_STATUSES = {429, 500, 502, 503, 504}
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        max_retries: int = 3,
+        timeout: float = 30,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.max_retries = max_retries
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers={**_extra_headers(extra_headers), "Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+            follow_redirects=False,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> FleetClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Internal HTTP helper with retry
+    # ------------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        idempotency_key: str | None = None,
+        idempotency_generated: bool = False,
+        require_json_object: bool = False,
+    ) -> Any:
+        last_err: Exception | None = None
+        # Delay to wait before the *next* attempt: Retry-After when the server
+        # sent it, otherwise exponential backoff with jitter. Computing it once
+        # per retry decision means we never stack a Retry-After wait on top of a
+        # generic backoff wait.
+        next_delay = 0.0
+        for attempt in range(self.max_retries + 1):
+            if attempt > 0:
+                time.sleep(next_delay)
+            try:
+                attempt_headers = dict(headers or {})
+                if idempotency_key is not None:
+                    attempt_headers["Idempotency-Key"] = idempotency_key
+                resp = self._client.request(
+                    method, path, json=json, params=params, headers=attempt_headers
+                )
+            except httpx.TransportError as exc:
+                last_err = exc
+                if attempt < self.max_retries:
+                    next_delay = _backoff_delay(attempt)
+                    continue
+                # Preserve httpx's concrete timeout/network exception type.
+                exc.idempotency_key = idempotency_key
+                raise
+            except httpx.RequestError as exc:
+                # HTTPX may fail while decoding a response after the server
+                # committed the operation (for example corrupt gzip). Preserve
+                # recovery without retrying non-transport request errors.
+                exc.idempotency_key = idempotency_key
+                raise
+
+            code = None
+            if not resp.is_success:
+                try:
+                    payload = resp.json()
+                except ValueError:
+                    payload = None
+                error = payload.get("error") if isinstance(payload, dict) else None
+                if isinstance(error, dict) and isinstance(error.get("code"), str):
+                    code = error["code"]
+
+            if resp.status_code == 409 and attempt < self.max_retries:
+                # Only explicit rollback permits a new SDK-owned key. A plain
+                # 500 may hide committed work; PROCESSING must replay that work.
+                if code == "IDEMPOTENCY_KEY_FAILED" and idempotency_generated and idempotency_key:
+                    idempotency_key = _gen_idem_key()
+                    next_delay = _backoff_delay(attempt)
+                    continue
+                if code == "IDEMPOTENCY_KEY_PROCESSING" and idempotency_key:
+                    next_delay = _backoff_delay(attempt)
+                    continue
+
+            if (
+                resp.status_code != 409
+                and resp.status_code in self.RETRYABLE_STATUSES
+                and attempt < self.max_retries
+            ):
+                last_err = httpx.HTTPStatusError(
+                    f"{resp.status_code}", request=resp.request, response=resp
+                )
+                retry_after = _parse_retry_after(resp)
+                next_delay = (
+                    min(_MAX_DELAY, retry_after)
+                    if retry_after is not None
+                    else _backoff_delay(attempt)
+                )
+                continue
+
+            try:
+                resp.raise_for_status()
+            except httpx.HTTPStatusError as exc:
+                raise FleetAPIError(exc, code, idempotency_key) from exc
+
+            ct = resp.headers.get("content-type", "")
+            if "application/json" in ct:
+                try:
+                    data = resp.json()
+                except ValueError as exc:
+                    exc.idempotency_key = idempotency_key
+                    raise
+                if require_json_object and not isinstance(data, dict):
+                    # A successful write may already have committed. Report the
+                    # final attempted key, including FAILED replacement (#2769),
+                    # without replaying the write or validating nested fields.
+                    exc = ValueError("Expected a JSON object for quote creation response")
+                    exc.idempotency_key = idempotency_key
+                    raise exc
+                if isinstance(data, dict) and idempotency_key is not None:
+                    return FleetResponse(data, idempotency_key)
+                return data
+            return resp.text
+
+        raise last_err or RuntimeError("request failed")
+
+    # ------------------------------------------------------------------
+    # Quotes
+    # ------------------------------------------------------------------
+
+    def create_quote(self, body: dict[str, Any], *, idempotency_key: str | None = None) -> FleetResponse:
+        """Create a quote; ``result.idempotency_key`` is its recovery key.
+
+        ``body["expectedCustomsEntryDate"]`` optionally selects the UTC calendar
+        day customs is expected to accept the declaration (``YYYY-MM-DD``).
+        Omission uses today. This does not predict FX or certify clearance;
+        inspect the returned assessment before collection.
+
+        For GB/UK, supply ``gbDeliveryTerritory`` as ``great_britain`` or
+        ``northern_ireland``. Missing territory and Northern Ireland return
+        named 422 errors; the SDK never defaults this delivery fact.
+        """
+        idem = idempotency_key if idempotency_key is not None else _gen_idem_key()
+        return self._request(
+            "POST", "/v1/quotes", json=body, idempotency_key=idem,
+            idempotency_generated=idempotency_key is None,
+            require_json_object=True,
+        )
+
+    def get_quote_by_key(self, key: str) -> dict:
+        """Retrieve a quote by its idempotency key."""
+        return self._request("GET", f"/v1/quotes/by-key/{_encode_path_segment(key)}")
+
+    def create_quote_batch(
+        self, items: list[dict[str, Any]], *, idempotency_key: str | None = None
+    ) -> FleetResponse:
+        """Quote 1–50 items without splitting or changing declared consignments.
+
+        HTTP 200 can contain per-item errors. Inspect each result and assessment.
+        Recover a batch by repeating this identical POST with its final key;
+        ``get_quote_by_key`` is for single quotes, not batch replay.
+        """
+        idem = idempotency_key if idempotency_key is not None else _gen_idem_key()
+        return self._request(
+            "POST", "/v1/quotes/batch", json={"items": items}, idempotency_key=idem,
+            idempotency_generated=idempotency_key is None,
+            require_json_object=True,
+        )
+
+    def export_quotes(self, **params: Any) -> dict:
+        """Export quote history with optional filters."""
+        return self._request("GET", "/v1/quotes/export", params=params)
+
+    def get_quote_stats(self) -> dict:
+        """Get quote count statistics."""
+        return self._request("GET", "/v1/quotes/stats")
+
+    # ------------------------------------------------------------------
+    # Classification
+    # ------------------------------------------------------------------
+
+    def classify(self, body: dict[str, Any], *, idempotency_key: str | None = None) -> FleetResponse:
+        """Classify a product and predict its HS6 code."""
+        idem = idempotency_key if idempotency_key is not None else _gen_idem_key()
+        return self._request(
+            "POST", "/v1/classify", json=body, idempotency_key=idem,
+            idempotency_generated=idempotency_key is None,
+        )
+
+    def classify_batch(
+        self, items: list[dict[str, Any]], *, idempotency_key: str | None = None
+    ) -> FleetResponse:
+        """Classify multiple products in a single request.
+
+        An idempotency key is attached (auto-generated unless
+        ``idempotency_key`` is supplied) and forwarded verbatim, but
+        ``POST /v1/classify/batch`` implements no dedup guard today, so a
+        retried batch is classified again rather than replayed (#1306). That
+        costs nothing: classification is a pure computation over the request
+        body, and the metered unit is quotes — this route writes no meter
+        event, so a duplicate batch is not billed. The header is still sent so
+        a caller-supplied key reaches the API and so nothing here changes if
+        the route later gains a guard.
+
+        The wording this replaces said the key kept "a retry from classifying —
+        and billing — the batch twice", which was wrong on both halves.
+        """
+        idem = idempotency_key if idempotency_key is not None else _gen_idem_key()
+        return self._request(
+            "POST", "/v1/classify/batch", json={"items": items}, idempotency_key=idem,
+            idempotency_generated=idempotency_key is None,
+        )
+
+    # ------------------------------------------------------------------
+    # Manifests
+    # ------------------------------------------------------------------
+
+    def create_manifest(self, body: dict[str, Any], *, idempotency_key: str | None = None) -> FleetResponse:
+        """Create a new manifest."""
+        idem = idempotency_key if idempotency_key is not None else _gen_idem_key()
+        return self._request(
+            "POST", "/v1/manifests", json=body, idempotency_key=idem,
+            idempotency_generated=idempotency_key is None,
+        )
+
+    def list_manifests(self, **params: Any) -> dict:
+        """List manifests with optional pagination."""
+        return self._request("GET", "/v1/manifests", params=params)
+
+    def get_manifest(self, manifest_id: str) -> dict:
+        """Get a manifest by ID."""
+        return self._request("GET", f"/v1/manifests/{_encode_path_segment(manifest_id)}")
+
+    def compute_manifest(
+        self,
+        manifest_id: str,
+        allocation: str | None = None,
+        *,
+        dry_run: bool = False,
+        idempotency_key: str | None = None,
+    ) -> FleetResponse:
+        """Compute landed costs for a manifest.
+
+        When ``allocation`` is None it is omitted from the request so the API
+        applies its mode-aware default (chargeable-kg for air manifests,
+        volumetric m³ for sea). The old ``"chargeable"`` default here forced
+        every sea manifest onto the "chargeable" basis, which on sea degenerates
+        to plain actual-weight allocation (#1499).
+        """
+        idem = idempotency_key if idempotency_key is not None else _gen_idem_key()
+        body: dict = {"dryRun": dry_run}
+        if allocation is not None:
+            body["allocation"] = allocation
+        return self._request(
+            "POST",
+            f"/v1/manifests/{_encode_path_segment(manifest_id)}/compute",
+            json=body,
+            idempotency_key=idem,
+            idempotency_generated=idempotency_key is None,
+        )
+
+    def compute_manifest_async(
+        self,
+        manifest_id: str,
+        allocation: str | None = None,
+        *,
+        dry_run: bool = False,
+        idempotency_key: str | None = None,
+    ) -> FleetResponse:
+        """Enqueue an async compute job.
+
+        ``allocation`` semantics match :meth:`compute_manifest` — None omits
+        the field so the API resolves the mode-aware default (#1499).
+        """
+        idem = idempotency_key if idempotency_key is not None else _gen_idem_key()
+        body: dict = {"dryRun": dry_run}
+        if allocation is not None:
+            body["allocation"] = allocation
+        return self._request(
+            "POST",
+            f"/v1/manifests/{_encode_path_segment(manifest_id)}/compute-async",
+            json=body,
+            idempotency_key=idem,
+            idempotency_generated=idempotency_key is None,
+        )
+
+    def get_compute_job_status(self, manifest_id: str, job_id: str) -> dict:
+        """Poll the status of an async compute job."""
+        return self._request(
+            "GET",
+            f"/v1/manifests/{_encode_path_segment(manifest_id)}"
+            f"/compute-async/{_encode_path_segment(job_id)}",
+        )
+
+    def get_manifest_quotes(self, manifest_id: str) -> dict:
+        """Get the latest computed quotes for a manifest."""
+        return self._request("GET", f"/v1/manifests/{_encode_path_segment(manifest_id)}/quotes")
+
+    def get_customs_declaration(self, manifest_id: str, *, fmt: str = "json") -> Any:
+        """Export a customs declaration (JSON or CSV)."""
+        return self._request(
+            "GET",
+            f"/v1/manifests/{_encode_path_segment(manifest_id)}/customs-declaration",
+            params={"format": fmt},
+        )
+
+    def delete_manifest(self, manifest_id: str) -> dict:
+        """Delete a manifest."""
+        return self._request("DELETE", f"/v1/manifests/{_encode_path_segment(manifest_id)}")
+
+    # ------------------------------------------------------------------
+    # Reference data lookups
+    # ------------------------------------------------------------------
+
+    def lookup_duty_rate(self, **params: Any) -> dict:
+        """Look up the duty rate for a destination and HS6 code."""
+        return self._request("GET", "/v1/duty-rates/lookup", params=params)
+
+    def lookup_vat(self, **params: Any) -> dict:
+        """Look up VAT rate for a destination."""
+        return self._request("GET", "/v1/vat/lookup", params=params)
+
+    def lookup_surcharges(self, **params: Any) -> dict:
+        """Look up applicable surcharges."""
+        return self._request("GET", "/v1/surcharges/lookup", params=params)
+
+    def convert_currency(
+        self, amount: float, from_ccy: str, to_ccy: str, *, on: str | None = None
+    ) -> dict:
+        """Convert between currencies.
+
+        Pass ``on="YYYY-MM-DD"`` to convert at a historical FX rate (matching a
+        quote computed on a prior date); omit it for the latest rate.
+        """
+        params: dict[str, Any] = {"amount": amount, "from": from_ccy, "to": to_ccy}
+        if on is not None:
+            params["on"] = on
+        return self._request("GET", "/v1/fx/convert", params=params)
+
+    # ------------------------------------------------------------------
+    # Merchant profile
+    # ------------------------------------------------------------------
+
+    def set_distance_sales_attestation(self, body: dict[str, Any]) -> dict:
+        """Record the seller's distance-sales attestation (#2081).
+
+        The seller states it is established in one member state, dispatches
+        only from there, and is under that state's distance-selling threshold
+        (EUR 10,000 in the euro area, the national figure elsewhere, #2360).
+        Every statement in ``body`` is a literal ``True``, and the server
+        refuses unknown keys: send the fields exactly as the API documents
+        them (``statementVersion``, ``establishmentCountry``, the seven
+        statements, ``currentYearTotal`` as ``{"amount", "currency"}`` in the
+        threshold's currency, and ``currentYearTotalAsOf``).
+        :meth:`get_distance_sales_threshold` says which currency applies; send
+        its ``amount`` and ``currency`` as ``reviewedThreshold`` and the API
+        refuses the attestation with 409 if the threshold changed since.
+
+        Quotes whose request declares ``dispatchCountry`` equal to
+        ``establishmentCountry`` can then price consumer sales at the dispatch
+        state's rate. Where the engine consulted the attestation, the quote's
+        ``explainability.vat.thresholdAttestation`` says whether it was priced on
+        it. Returns the merchant profile, whose
+        ``distanceSalesAttestation`` shows the attestation on file, ``inEffect``
+        and ``expiresAt``.
+
+        Needs a live key with ``self:write``; the API refuses Test-mode keys.
+        It does not check who holds the key: its owner/admin check applies only
+        to dashboard sessions. The server stamps the year and
+        ``attestedAt``, and the route takes no Idempotency-Key: a retry after a
+        lost response re-affirms the same statements with a later
+        ``attestedAt`` and a second audit entry.
+        """
+        return self._request(
+            "PUT", "/v1/merchant-profiles/distance-sales-attestation", json=body
+        )
+
+    def get_distance_sales_threshold(self, country: str) -> dict:
+        """The distance-selling threshold an attestation is held to (#2360).
+
+        Returns ``country``, ``amount``, ``currency``, ``basis``,
+        ``legalCitation`` and ``effectiveFrom`` for a seller established in
+        ``country`` today: state ``currentYearTotal`` in that ``currency`` and
+        no higher than ``amount``. Raises on a 404 while Fleet has no
+        threshold for the state, and the attestation is then refused. Needs a
+        key with ``self:read``.
+        """
+        return self._request(
+            "GET",
+            "/v1/merchant-profiles/distance-sales-threshold",
+            params={"country": country},
+        )
+
+    def withdraw_distance_sales_attestation(self) -> dict:
+        """Withdraw the distance-sales attestation.
+
+        Withdraw it as soon as the current-year total passes the threshold.
+        Idempotent: with nothing on file it still returns the merchant profile.
+        Same key requirements as :meth:`set_distance_sales_attestation`.
+        """
+        return self._request("DELETE", "/v1/merchant-profiles/distance-sales-attestation")

fleet_costs_sdk-0.4.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+# PyPI distribution name. The bare `fleet` name is already taken
+# on PyPI, so we publish under `fleet-costs-sdk`. Consumers still
+# `import fleet` because the top-level package directory stays `fleet/`.
+name = "fleet-costs-sdk"
+version = "0.4.0"
+description = "Official Python SDK for the Fleet Costs landed-cost / duty / VAT / freight pricing API."
+readme = "README.md"
+# Keep the consumer floor and classifiers aligned with python-sdk-ci.yml,
+# which now tests Python 3.10 through 3.13, including transport/recovery (#1602).
+# Re-check the 3.10 floor when its upstream security support ends in October 2026.
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Fleet", email = "support@getfleet.dev" },
+]
+maintainers = [
+    { name = "Fleet", email = "support@getfleet.dev" },
+]
+keywords = [
+    "fleet",
+    "landed-cost",
+    "duty",
+    "vat",
+    "hts",
+    "hs-code",
+    "customs",
+    "import",
+    "cross-border",
+    "sdk",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    # Keep this list in step with `requires-python` above; 3.9 was dropped with
+    # the floor when it went EOL.
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.25"]
+
+# Public pages only. The SDK is built in a private repository, so a
+# Repository or Issues link would 404 for every customer on the PyPI page
+# (#2335; the npm and Go packages were fixed the same way).
+[project.urls]
+Homepage = "https://getfleet.dev"
+Documentation = "https://docs.getfleet.dev/guides/python-sdk"
+"API reference" = "https://docs.getfleet.dev"
+Support = "https://getfleet.dev/contact"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "respx>=0.21"]
+
+[tool.hatch.build.targets.wheel]
+# Only ship the `fleet/` package — skip tests/, pyproject.toml, etc.
+packages = ["fleet"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/fleet",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]