usps-v3 1.0.0__tar.gz

usps_v3-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: python -m twine upload dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}

usps_v3-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v --tb=short
+
+      - name: Lint
+        if: matrix.python-version == '3.12'
+        run: ruff check src/ tests/

usps_v3-1.0.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+env/
+*.env
+.DS_Store
+*.pem
+*.key
+tokens.json

usps_v3-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Lambert / Revasser LLC
+
+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.

usps_v3-1.0.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: usps-v3
+Version: 1.0.0
+Summary: Python SDK for USPS Web Tools v3 REST API — OAuth 2.0, address validation, tracking, labels, prices
+Project-URL: Homepage, https://revaddress.com
+Project-URL: Documentation, https://revaddress.com/docs
+Project-URL: Repository, https://github.com/revereveal/usps-v3
+Project-URL: Issues, https://github.com/revereveal/usps-v3/issues
+Author-email: James Lambert <james@revasser.nyc>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: address-validation,api,labels,postal,shipping,tracking,usps
+Classifier: Development Status :: 5 - Production/Stable
+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 :: Office/Business :: Financial :: Point-Of-Sale
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-httpx>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# usps-v3
+
+Python SDK for the **USPS Web Tools v3 REST API** — the replacement for the retired XML-based Web Tools.
+
+Direct USPS integration. OAuth 2.0. No middleman. No per-label fees.
+
+## Install
+
+```bash
+pip install usps-v3
+```
+
+## Quick Start
+
+```python
+from usps_v3 import Client
+
+# Credentials from USPS Business Customer Gateway
+client = Client(client_id="your-id", client_secret="your-secret")
+# Or set USPS_CLIENT_ID and USPS_CLIENT_SECRET environment variables:
+# client = Client()
+
+# Validate an address (FREE)
+result = client.addresses.validate(
+    street_address="1600 Pennsylvania Ave NW",
+    city="Washington",
+    state="DC",
+    zip_code="20500",
+)
+print(result["address"]["ZIPPlus4"])  # "0005"
+
+# Track a package (FREE)
+info = client.tracking.track("9400111899223033005282")
+print(info["statusCategory"])  # "Delivered"
+
+# Get delivery time estimates (FREE)
+standards = client.standards.estimates("10001", "90210")
+
+# Find drop-off locations (FREE)
+locations = client.locations.dropoff("20500", mail_class="PRIORITY_MAIL")
+
+# Get rate quotes
+rates = client.prices.domestic("10001", "90210", weight=2.5)
+print(rates["rates"]["rateOptions"][0]["totalPrice"])
+
+# International rates
+intl = client.prices.international("10001", "CA", weight=3.0)
+
+# Create shipping labels (requires USPS enrollment + COP claims)
+label = client.labels.create(
+    from_address={"streetAddress": "123 Sender St", "city": "New York", "state": "NY", "ZIPCode": "10001"},
+    to_address={"streetAddress": "456 Recipient Ave", "city": "LA", "state": "CA", "ZIPCode": "90001"},
+    mail_class="PRIORITY_MAIL",
+    weight=2.0,
+)
+print(label["trackingNumber"])
+
+# Void a label
+client.labels.void("9400111899223033005282")
+```
+
+## Features
+
+| Feature | Endpoint | Auth Required |
+|---------|----------|--------------|
+| Address Validation | `addresses.validate()` | OAuth only |
+| City/State Lookup | `addresses.city_state()` | OAuth only |
+| Package Tracking | `tracking.track()` | OAuth only |
+| Service Standards | `standards.estimates()` | OAuth only |
+| Drop-off Locations | `locations.dropoff()` | OAuth only |
+| Domestic Prices | `prices.domestic()` | OAuth only |
+| International Prices | `prices.international()` | OAuth only |
+| Label Creation | `labels.create()` | OAuth + Payment Auth |
+| Label Void | `labels.void()` | OAuth only |
+
+## Authentication
+
+The SDK handles OAuth 2.0 token lifecycle automatically:
+
+- **Token caching**: Tokens are cached in memory and on disk (`~/.usps-v3/tokens.json`)
+- **Auto-refresh**: Tokens refresh automatically 30 minutes before expiry
+- **Thread-safe**: Safe for concurrent use across threads
+
+### Getting Credentials
+
+1. Register at [USPS Business Customer Gateway](https://gateway.usps.com)
+2. Create an application in the API developer portal
+3. Note your `client_id` and `client_secret`
+
+For label creation, you also need:
+- **CRID** (Customer Registration ID)
+- **MIDs** (Mailer IDs — master + label owner)
+- **EPA** (Enterprise Payment Account)
+- **COP claims linking** at [cop.usps.com](https://cop.usps.com)
+
+```python
+client = Client(
+    client_id="...",
+    client_secret="...",
+    crid="56982563",
+    master_mid="904128936",
+    label_mid="904128937",
+    epa_account="1000405525",
+)
+```
+
+## Error Handling
+
+```python
+from usps_v3 import Client, AuthError, ValidationError, RateLimitError, APIError
+
+try:
+    result = client.addresses.validate(street_address="123 Main St")
+except ValidationError as e:
+    print(f"Bad input: {e} (field: {e.field})")
+except RateLimitError as e:
+    print(f"Rate limited — retry after {e.retry_after}s")
+except AuthError as e:
+    print(f"Auth failed: {e}")
+except APIError as e:
+    print(f"USPS error ({e.status_code}): {e}")
+```
+
+## USPS Rate Limits
+
+The v3 API defaults to **60 requests/hour** (down from unlimited in Web Tools). The SDK does not enforce this limit — USPS returns 429 when exceeded.
+
+To request a higher limit, contact USPS at [emailus.usps.com](https://emailus.usps.com).
+
+## Migration from Web Tools
+
+If you're migrating from the retired USPS Web Tools XML API:
+
+| Web Tools (XML) | v3 SDK (Python) |
+|-----------------|-----------------|
+| `<AddressValidateRequest>` | `client.addresses.validate(...)` |
+| `<CityStateLookupRequest>` | `client.addresses.city_state(...)` |
+| `<TrackFieldRequest>` | `client.tracking.track(...)` |
+| `<RateV4Request>` | `client.prices.domestic(...)` |
+| User ID auth | OAuth 2.0 (automatic) |
+| XML response parsing | Python dicts (automatic) |
+| Unlimited requests | 60/hr default (request increase) |
+
+## Development
+
+```bash
+git clone https://github.com/revereveal/usps-v3.git
+cd usps-v3
+pip install -e ".[dev]"
+pytest -v
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Built by [RevAddress](https://revaddress.com) — direct USPS API integration for developers.

usps_v3-1.0.0/README.md

@@ -0,0 +1,157 @@
+# usps-v3
+
+Python SDK for the **USPS Web Tools v3 REST API** — the replacement for the retired XML-based Web Tools.
+
+Direct USPS integration. OAuth 2.0. No middleman. No per-label fees.
+
+## Install
+
+```bash
+pip install usps-v3
+```
+
+## Quick Start
+
+```python
+from usps_v3 import Client
+
+# Credentials from USPS Business Customer Gateway
+client = Client(client_id="your-id", client_secret="your-secret")
+# Or set USPS_CLIENT_ID and USPS_CLIENT_SECRET environment variables:
+# client = Client()
+
+# Validate an address (FREE)
+result = client.addresses.validate(
+    street_address="1600 Pennsylvania Ave NW",
+    city="Washington",
+    state="DC",
+    zip_code="20500",
+)
+print(result["address"]["ZIPPlus4"])  # "0005"
+
+# Track a package (FREE)
+info = client.tracking.track("9400111899223033005282")
+print(info["statusCategory"])  # "Delivered"
+
+# Get delivery time estimates (FREE)
+standards = client.standards.estimates("10001", "90210")
+
+# Find drop-off locations (FREE)
+locations = client.locations.dropoff("20500", mail_class="PRIORITY_MAIL")
+
+# Get rate quotes
+rates = client.prices.domestic("10001", "90210", weight=2.5)
+print(rates["rates"]["rateOptions"][0]["totalPrice"])
+
+# International rates
+intl = client.prices.international("10001", "CA", weight=3.0)
+
+# Create shipping labels (requires USPS enrollment + COP claims)
+label = client.labels.create(
+    from_address={"streetAddress": "123 Sender St", "city": "New York", "state": "NY", "ZIPCode": "10001"},
+    to_address={"streetAddress": "456 Recipient Ave", "city": "LA", "state": "CA", "ZIPCode": "90001"},
+    mail_class="PRIORITY_MAIL",
+    weight=2.0,
+)
+print(label["trackingNumber"])
+
+# Void a label
+client.labels.void("9400111899223033005282")
+```
+
+## Features
+
+| Feature | Endpoint | Auth Required |
+|---------|----------|--------------|
+| Address Validation | `addresses.validate()` | OAuth only |
+| City/State Lookup | `addresses.city_state()` | OAuth only |
+| Package Tracking | `tracking.track()` | OAuth only |
+| Service Standards | `standards.estimates()` | OAuth only |
+| Drop-off Locations | `locations.dropoff()` | OAuth only |
+| Domestic Prices | `prices.domestic()` | OAuth only |
+| International Prices | `prices.international()` | OAuth only |
+| Label Creation | `labels.create()` | OAuth + Payment Auth |
+| Label Void | `labels.void()` | OAuth only |
+
+## Authentication
+
+The SDK handles OAuth 2.0 token lifecycle automatically:
+
+- **Token caching**: Tokens are cached in memory and on disk (`~/.usps-v3/tokens.json`)
+- **Auto-refresh**: Tokens refresh automatically 30 minutes before expiry
+- **Thread-safe**: Safe for concurrent use across threads
+
+### Getting Credentials
+
+1. Register at [USPS Business Customer Gateway](https://gateway.usps.com)
+2. Create an application in the API developer portal
+3. Note your `client_id` and `client_secret`
+
+For label creation, you also need:
+- **CRID** (Customer Registration ID)
+- **MIDs** (Mailer IDs — master + label owner)
+- **EPA** (Enterprise Payment Account)
+- **COP claims linking** at [cop.usps.com](https://cop.usps.com)
+
+```python
+client = Client(
+    client_id="...",
+    client_secret="...",
+    crid="56982563",
+    master_mid="904128936",
+    label_mid="904128937",
+    epa_account="1000405525",
+)
+```
+
+## Error Handling
+
+```python
+from usps_v3 import Client, AuthError, ValidationError, RateLimitError, APIError
+
+try:
+    result = client.addresses.validate(street_address="123 Main St")
+except ValidationError as e:
+    print(f"Bad input: {e} (field: {e.field})")
+except RateLimitError as e:
+    print(f"Rate limited — retry after {e.retry_after}s")
+except AuthError as e:
+    print(f"Auth failed: {e}")
+except APIError as e:
+    print(f"USPS error ({e.status_code}): {e}")
+```
+
+## USPS Rate Limits
+
+The v3 API defaults to **60 requests/hour** (down from unlimited in Web Tools). The SDK does not enforce this limit — USPS returns 429 when exceeded.
+
+To request a higher limit, contact USPS at [emailus.usps.com](https://emailus.usps.com).
+
+## Migration from Web Tools
+
+If you're migrating from the retired USPS Web Tools XML API:
+
+| Web Tools (XML) | v3 SDK (Python) |
+|-----------------|-----------------|
+| `<AddressValidateRequest>` | `client.addresses.validate(...)` |
+| `<CityStateLookupRequest>` | `client.addresses.city_state(...)` |
+| `<TrackFieldRequest>` | `client.tracking.track(...)` |
+| `<RateV4Request>` | `client.prices.domestic(...)` |
+| User ID auth | OAuth 2.0 (automatic) |
+| XML response parsing | Python dicts (automatic) |
+| Unlimited requests | 60/hr default (request increase) |
+
+## Development
+
+```bash
+git clone https://github.com/revereveal/usps-v3.git
+cd usps-v3
+pip install -e ".[dev]"
+pytest -v
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Built by [RevAddress](https://revaddress.com) — direct USPS API integration for developers.

usps_v3-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "usps-v3"
+version = "1.0.0"
+description = "Python SDK for USPS Web Tools v3 REST API — OAuth 2.0, address validation, tracking, labels, prices"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "James Lambert", email = "james@revasser.nyc" }]
+keywords = ["usps", "shipping", "address-validation", "tracking", "labels", "postal", "api"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "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",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Office/Business :: Financial :: Point-Of-Sale",
+]
+dependencies = ["httpx>=0.24.0"]
+
+[project.urls]
+Homepage = "https://revaddress.com"
+Documentation = "https://revaddress.com/docs"
+Repository = "https://github.com/revereveal/usps-v3"
+Issues = "https://github.com/revereveal/usps-v3/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/usps_v3"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-httpx>=0.21", "respx>=0.20", "ruff>=0.3"]

usps_v3-1.0.0/src/usps_v3/__init__.py

@@ -0,0 +1,25 @@
+"""USPS v3 Python SDK — direct integration with USPS Web Tools v3 REST API.
+
+Usage:
+    from usps_v3 import Client
+
+    client = Client(client_id="...", client_secret="...")
+    result = client.addresses.validate(street_address="1600 Pennsylvania Ave NW", city="Washington", state="DC")
+
+Or with environment variables (USPS_CLIENT_ID, USPS_CLIENT_SECRET):
+    client = Client()
+"""
+
+from .client import Client
+from .exceptions import APIError, AuthError, NetworkError, RateLimitError, USPSError, ValidationError
+
+__version__ = "1.0.0"
+__all__ = [
+    "Client",
+    "USPSError",
+    "AuthError",
+    "ValidationError",
+    "RateLimitError",
+    "APIError",
+    "NetworkError",
+]

usps_v3-1.0.0/src/usps_v3/addresses.py

@@ -0,0 +1,108 @@
+"""Address validation and city/state lookup — USPS Addresses v3.
+
+Free tier: no license required.
+
+USPS endpoints:
+  GET /addresses/v3/address?streetAddress=...&city=...&state=...&ZIPCode=...
+  GET /addresses/v3/city-state?ZIPCode=...
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .auth import TokenManager
+from .exceptions import APIError, NetworkError, RateLimitError, ValidationError
+
+
+class AddressesAPI:
+    """Address validation and ZIP code lookup."""
+
+    def __init__(self, http: httpx.Client, tokens: TokenManager, base_url: str):
+        self._http = http
+        self._tokens = tokens
+        self._base_url = base_url
+
+    def validate(
+        self,
+        street_address: str,
+        *,
+        secondary_address: str | None = None,
+        city: str | None = None,
+        state: str | None = None,
+        zip_code: str | None = None,
+        zip_plus4: str | None = None,
+    ) -> dict[str, Any]:
+        """Validate and standardize a US address.
+
+        Args:
+            street_address: Street address line (required).
+            secondary_address: Apt, Suite, etc.
+            city: City name.
+            state: 2-letter state code.
+            zip_code: 5-digit ZIP code.
+            zip_plus4: 4-digit ZIP+4 extension.
+
+        Returns:
+            Dict with 'address', 'additionalInfo', 'corrections', 'matches' keys.
+            The 'address' dict contains the standardized address fields.
+        """
+        if not street_address:
+            raise ValidationError("street_address is required", field="street_address")
+
+        params: dict[str, str] = {"streetAddress": street_address}
+        if secondary_address:
+            params["secondaryAddress"] = secondary_address
+        if city:
+            params["city"] = city
+        if state:
+            params["state"] = state
+        if zip_code:
+            params["ZIPCode"] = zip_code
+        if zip_plus4:
+            params["ZIPPlus4"] = zip_plus4
+
+        return self._request("GET", "/addresses/v3/address", params=params)
+
+    def city_state(self, zip_code: str) -> dict[str, Any]:
+        """Look up city and state for a ZIP code.
+
+        Args:
+            zip_code: 5-digit ZIP code.
+
+        Returns:
+            Dict with city and state information.
+        """
+        if not zip_code:
+            raise ValidationError("zip_code is required", field="zip_code")
+
+        return self._request("GET", "/addresses/v3/city-state", params={"ZIPCode": zip_code})
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        token = self._tokens.get_oauth_token()
+        headers = {"Authorization": f"Bearer {token}"}
+
+        try:
+            resp = self._http.request(
+                method,
+                f"{self._base_url}{path}",
+                headers=headers,
+                **kwargs,
+            )
+        except httpx.HTTPError as e:
+            raise NetworkError(f"Request failed: {e}") from e
+
+        if resp.status_code == 429:
+            retry_after = resp.headers.get("Retry-After")
+            raise RateLimitError(retry_after=int(retry_after) if retry_after else None)
+
+        if resp.status_code >= 400:
+            raise APIError(
+                f"USPS API error ({resp.status_code}): {resp.text}",
+                status_code=resp.status_code,
+                response_body=resp.text,
+            )
+
+        return resp.json()