shipzil 0.1.0__tar.gz

shipzil-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,84 @@
+name: Bug report
+description: Something behaves differently from the documented contract.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please do not include live credentials, real customer addresses or real
+        label data. Sanitize provider payloads the way `tests/fixtures/README.md`
+        describes.
+
+        For a security issue, use a
+        [private advisory](https://github.com/sameerkumar18/shipzil/security/advisories/new)
+        instead.
+
+  - type: input
+    id: version
+    attributes:
+      label: shipzil version or commit
+      placeholder: "0.1.0, or the commit SHA from your lockfile"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: provider
+    attributes:
+      label: Provider
+      options:
+        - shippo
+        - easyship
+        - shipstation_v1
+        - shipstation_v2
+        - more than one
+        - not provider specific
+    validations:
+      required: true
+
+  - type: dropdown
+    id: operation
+    attributes:
+      label: Operation
+      options:
+        - rating
+        - purchase
+        - void or refund
+        - filtering or service keys
+        - customs or international
+        - other
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected, and where that is documented
+      description: Link the docs page or quote the contract, so we can tell a bug from a missing feature.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: What happened
+      description: Include `quote.explain()` output where relevant, and the exception type and message.
+      render: text
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction
+      description: The smallest snippet that shows it. Replace credentials with placeholders.
+      render: python
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12.4"
+    validations:
+      required: true

shipzil-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Documentation
+    url: https://sameerkumar18.github.io/shipzil/
+    about: Concepts, provider support, errors and the API reference.
+  - name: Security issue
+    url: https://github.com/sameerkumar18/shipzil/security/advisories/new
+    about: Report credential handling, duplicate purchase or declaration issues privately.

shipzil-0.1.0/.github/ISSUE_TEMPLATE/provider_support.yml

@@ -0,0 +1,50 @@
+name: Provider support
+description: Add a provider, or report a gap in an existing adapter.
+labels: [provider]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Adapter changes need evidence from the provider's current schema, not its
+        prose documentation. See CONTRIBUTING.md.
+
+  - type: input
+    id: provider
+    attributes:
+      label: Provider
+      placeholder: "Sendcloud, or shipstation_v2"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Request
+      options:
+        - a new provider adapter
+        - a field or operation an existing adapter does not send
+        - a provider behaviour shipzil reports incorrectly
+    validations:
+      required: true
+
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Schema evidence
+      description: |
+        Link the provider's schema or model page for the fields involved, and quote
+        the relevant part. A prose example is not enough; field nesting and
+        required values have to come from the schema.
+    validations:
+      required: true
+
+  - type: textarea
+    id: semantics
+    attributes:
+      label: Semantics that differ from the current adapters
+      description: |
+        Especially: is a customs value per unit or a line total, is multi-parcel
+        rating native, how is duty liability expressed, and is there a no-charge
+        test path for purchases.
+    validations:
+      required: false

shipzil-0.1.0/.github/dependabot.yml

@@ -0,0 +1,37 @@
+version: 2
+
+updates:
+  # Python: runtime has no dependencies, so this tracks the dev toolchain only.
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 3
+    commit-message:
+      prefix: "deps"
+
+  - package-ecosystem: npm
+    directory: /docs-site
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 3
+    commit-message:
+      prefix: "deps(docs)"
+    groups:
+      fumadocs:
+        patterns:
+          - "fumadocs*"
+      next:
+        patterns:
+          - "next"
+          - "react"
+          - "react-dom"
+          - "@types/react*"
+
+  # setup-uv has no moving major tag, so a pinned version needs updating here.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    commit-message:
+      prefix: "ci"

shipzil-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,29 @@
+## What changes
+
+<!-- The behaviour a caller can observe, not the diff. -->
+
+## Evidence
+
+<!-- For a provider change: link the provider's current schema or model page for
+     every field involved. A prose example is not sufficient. -->
+
+- [ ] Request fields verified against the provider's current schema
+- [ ] Payload test proves the value reaches the outgoing request
+- [ ] Parser test uses a sanitized provider response, or the constructed case is
+      marked synthetic
+- [ ] Regression test checked by restoring the bug and watching it fail
+
+## Safety
+
+- [ ] `retries=0` on anything that spends money
+- [ ] No fabricated dimensions, contents, customs values or company names
+- [ ] `Quote.excluded` explains anything shipzil removed
+- [ ] Docs updated where behaviour changed
+
+## Verification
+
+```
+make check
+make check-compat
+make test-live     # state which live tests ran, and against which provider
+```

shipzil-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "shipzil/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/ci.yml"
+  pull_request:
+    paths:
+      - "shipzil/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # setup-uv publishes no moving major tag, so this is pinned exactly.
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          enable-cache: true
+      - run: uv sync --python 3.14
+      - run: uv run ruff check shipzil tests
+      - run: uv run mypy shipzil
+      - run: uv run pytest -m "not live"
+
+  compatibility:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # setup-uv publishes no moving major tag, so this is pinned exactly.
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          enable-cache: true
+      - run: uv run --python ${{ matrix.python-version }} --isolated --with pytest pytest -m "not live"

shipzil-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,67 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs-site/**"
+      - "shipzil/**"
+      - "AGENTS.md"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs-site/**"
+      - "shipzil/**"
+      - "AGENTS.md"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # Always build, on every branch and PR. Type generation, static generation and
+  # the agent-output checks all run before anything can be deployed.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs-site/package-lock.json
+      # setup-uv publishes no moving major tag, so this is pinned exactly.
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          enable-cache: true
+      - run: npm ci
+        working-directory: docs-site
+      - run: npm run types:check
+        working-directory: docs-site
+      - run: npm run build
+        working-directory: docs-site
+      - run: npm run check:agent
+        working-directory: docs-site
+      - uses: actions/upload-pages-artifact@v5
+        if: github.ref == 'refs/heads/main'
+        with:
+          path: docs-site/out
+
+  # Deploy only from main, and only once Pages is actually enabled. Pages on a
+  # private repository needs a paid plan, and deploy-pages returns 404 until the
+  # source is set to "GitHub Actions", which would fail every push.
+  # Enable with: gh variable set PAGES_ENABLED --body true
+  deploy:
+    if: github.ref == 'refs/heads/main' && vars.PAGES_ENABLED == 'true'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - id: deploy
+        uses: actions/deploy-pages@v5

shipzil-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,78 @@
+name: release
+
+# Publishes to PyPI when a version tag is pushed.
+#
+# Uses PyPI Trusted Publishing (OIDC), so there is no API token in this repository.
+# One-time setup on PyPI: add a trusted publisher for this repo with workflow
+# name "release" and environment "pypi".
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # Never publish something that does not pass its own suite.
+  verify:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.10", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      # setup-uv publishes no moving major tag, so this is pinned exactly.
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          enable-cache: true
+      - run: uv run --python ${{ matrix.python-version }} --isolated --with pytest pytest -m "not live"
+
+  build:
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # setup-uv publishes no moving major tag, so this is pinned exactly.
+      - uses: astral-sh/setup-uv@v10.1.0
+
+      - name: Fail if the tag does not match the package version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(uv run python -c 'import shipzil; print(shipzil.__version__)')"
+          echo "tag=$tag package=$pkg"
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::tag $tag does not match shipzil.__version__ $pkg"
+            exit 1
+          fi
+        if: github.event_name == 'push'
+
+      - run: uv build
+
+      - name: Check the wheel ships what it must
+        run: |
+          uv run --with twine twine check dist/*
+          python -m zipfile -l dist/*.whl > contents.txt
+          for required in shipzil/gateway.py shipzil/services.py shipzil/py.typed; do
+            grep -q "$required" contents.txt || {
+              echo "::error::wheel is missing $required"; exit 1; }
+          done
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write        # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

shipzil-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.probe/
+
+# Scraped provider API docs. Reference only, never committed.
+.apidocs/
+
+# Fumadocs build and install output, never committed.
+docs-site/node_modules/
+docs-site/.next/
+docs-site/out/
+
+# Local build playbook — tricks, scrape recipes, credential inventory, open
+# operational state. Deliberately never pushed. Must not move into the docs app.
+NOTES.local.md
+*.local.md

shipzil-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

shipzil-0.1.0/AGENTS.md

@@ -0,0 +1,85 @@
+# Agent guide
+
+This repository is the Python shipping Gateway, not the separate Shipzil status
+page repository.
+
+## Current scope
+
+Supported provider adapters:
+
+- `shippo`
+- `easyship`
+- `shipstation_v1`
+- `shipstation_v2`
+
+`Gateway` sits above the existing single-provider `Client`:
+
+- no provider preference means query all configured sources
+- an explicit `fallback=(...)` is caller-authored policy
+- provider, carrier and exact `ServiceKey` filters intersect
+- source failures remain in `GatewayQuote.sources`
+- every Gateway rate carries its configured `source`
+- buying and voiding use that exact source
+
+Do not add health-aware routing, cheapest-rate selection, service equivalence,
+manifest generation or automatic purchase fallback. Those are not Gateway MVP
+features.
+
+## Code map
+
+| Area | File | Role |
+|---|---|---|
+| internal source client | `shipzil/_client.py` | rate, buy, void for one adapter |
+| Gateway | `shipzil/gateway.py` | multi-source aggregation and explicit filters |
+| service map | `shipzil/services.py` | `ServiceKey`, `ServiceInfo`, `ServiceMap` |
+| provider contract | `shipzil/providers/base.py` | adapter capabilities and fidelity gaps |
+| provider adapters | `shipzil/providers/` | provider-specific requests/parsers |
+| provider errors | `shipzil/normalize.py` | prose/code to `ExclusionCode` |
+| live-shaped fixtures | `tests/fixtures/` | scrubbed provider responses |
+| provider source guide | `docs-site/content/docs/provider-sources.md` | authoritative documentation URLs and verification rules |
+
+## Invariants
+
+- `Item.value` and `Item.weight` are per unit.
+- Provider machine keys go into `ServiceKey.service`; display names stay on
+  `Rate.service`.
+- `ServiceKey` is provider-namespaced. Do not infer that two providers' keys are
+  equivalent.
+- `Rate.source` is the configured account/source that produced the rate. Never
+  purchase through another source.
+- `Quote.excluded` retains provider-reported and local exclusions. It cannot explain
+  services the provider silently omitted.
+- Purchases are never retried automatically.
+- A fan-out rate is an estimate, not one provider-native multi-parcel quote, and
+  cannot be bought as one label.
+- Do not add a provider capability to `hazmat_fields` unless the adapter emits
+  that field on the wire.
+
+## Verification
+
+```bash
+make check
+make check-compat
+make docs-build
+make test-live
+```
+
+`make test-live` loads the ignored `.env`. Live calls can buy test labels or
+consume sandbox quota; inspect the marker and provider before running them.
+
+When changing a provider parser, use a sanitized provider response plus a
+payload-level test. A constructed fixture is appropriate for an edge case absent
+from the captured response.
+
+## Provider documentation
+
+Read `docs-site/content/docs/provider-sources.md` before changing provider
+behavior. Verify claims against the provider's current schema or documentation and
+then add a captured-response or payload-level test. Never commit `.env`, raw
+credentials or unsanitized provider payloads.
+
+## Style
+
+Keep the public API small and Pythonic. Prefer a dataclass, tuple, mapping or
+keyword argument over a hierarchy of policy/configuration classes. Use
+`dataclasses.replace` when copying a model so new fields cannot silently vanish.

shipzil-0.1.0/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+## 0.1.0 - 2026-09-19
+
+First published release. Alpha: the interface may change before 1.0.
+
+### Added
+
+- Multi-source `Gateway` with direct credential configuration.
+- Concurrent source rating and concurrent per-parcel FANOUT.
+- Source provenance on rates and labels.
+- Provider, carrier and exact-service filtering.
+- `GatewayQuote` sequence operations, diagnostics, messages, `cheapest` and
+  `fastest`.
+- Structured exclusions for locally filtered and unaddressable rates.
+- Replaceable HTTP `Transport` protocol.
+- Fumadocs site, generated Python reference and agent-readable Markdown routes.
+- CI checks for Python 3.10 through 3.14 and a trusted-publishing release workflow.
+
+### Changed
+
+- `get_rates(sources=...)` selects configured source names; `providers=` now selects
+  adapter types only. The single overloaded argument matched either, which hid a
+  caller's typo as an empty result. An unknown name in either raises
+  `ConfigurationError`.
+- `max_spend` accepts `max_spend_currency`. A rate with no currency, or one in a
+  different currency, is refused rather than compared, because shipzil does not
+  convert money.
+- Removed `Label.parcel_labels` and `TrackingLeg.piece`. No adapter populated
+  either, and a documented field that is always empty is a promise the library does
+  not keep.
+
+- Minimum Python version is 3.10.
+- `Gateway` is the caller entry point; the single-source client is internal.
+- `Rate` and `Label` constructors are keyword-only.
+- `Capabilities` is a frozen dataclass.
+- `SourceResult` exposes rates, exclusions and messages directly.
+- `cheapest` returns `None` for mixed or unknown currencies.
+- Cross-border rating stops before a provider call when any item lacks weight or
+  value.
+- Easyship requires explicit items and values; it no longer creates placeholder
+  merchandise or a default customs value.
+- ShipStation v1 label bytes are available in `Label.label_data`.
+- Purchase-path `ProviderError` becomes `AmbiguousPurchaseError`.
+
+### Fixed
+
+- A rate list shortened by a transient carrier failure is now reported. Measured
+  against a Shippo test account on a US domestic lane, a rating call returns 11
+  rates normally and 3 when UPS answers "Hard: Too Many Requests". The reason was
+  present in the response messages and already classifiable, but no exclusion was
+  produced because the list was not empty, so a caller could lose 8 of 11 options
+  with no signal. Structural account and lane messages are still not promoted;
+  they are permanent and would be noise on every quote.
+
+- Carrier family filters now match variants such as DHL Express and DHL eCommerce
+  without matching unrelated carriers.
+- Rates removed by shipzil filters return an exclusion instead of disappearing.
+- Provider warning messages survive Gateway aggregation.
+- Provider counts, customs value basis and idempotency documentation were reconciled
+  with current source and provider schemas.
+
+### Verified
+
+- Live rating now covers all four adapters. Easyship runs against its sandbox host;
+  ShipStation v1 rating is read-only and confirmed live that it returns no currency
+  and no delivery estimate.
+- Partial-shortfall reporting was checked in every adapter rather than assumed:
+  ShipStation v2 and v1 already reported failures alongside returned rates, and
+  Easyship's response carries no failure field to report.
+
+- Offline tests cover all four adapters with sanitized responses and payload
+  assertions.
+- Live rating covers Shippo and ShipStation v2, including a two-source Gateway
+  call with provenance checks.
+- Shippo test purchase and refund are exercised with a `shippo_test_` token.
+- ShipStation v2 purchase and void remain unverified live.