truagents 0.0.0.dev0__tar.gz

truagents-0.0.0.dev0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+.tox/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Editors / IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS junk
+.DS_Store
+Thumbs.db
+
+# Secrets / credentials (never commit)
+.env
+.env.*
+credentials*
+*.pem
+*.key
+*.p12
+*.pfx

truagents-0.0.0.dev0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: truagents
+Version: 0.0.0.dev0
+Summary: Official Python SDK for the TruAgents Unsubscribe API.
+Project-URL: Homepage, https://github.com/ablt-ai/truagents-sdk
+Project-URL: Documentation, https://docs.truagents.com/sdks/python
+Project-URL: Source, https://github.com/ablt-ai/truagents-sdk
+Project-URL: Issues, https://github.com/ablt-ai/truagents-sdk/issues
+Author: ablt-ai
+License: Apache-2.0
+Keywords: oauth,sdk,truagents,unsubscribe
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: attrs>=25.0
+Requires-Dist: httpx>=0.28
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.400; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Requires-Dist: ruff==0.15.18; extra == 'dev'
+Requires-Dist: time-machine>=2.16; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# truagents — Python SDK for the TruAgents Unsubscribe API
+
+[![PyPI version](https://img.shields.io/pypi/v/truagents.svg)](https://pypi.org/project/truagents/)
+[![Python versions](https://img.shields.io/pypi/pyversions/truagents.svg)](https://pypi.org/project/truagents/)
+[![CI](https://github.com/ablt-ai/truagents-sdk/actions/workflows/contract-python.yml/badge.svg)](https://github.com/ablt-ai/truagents-sdk/actions/workflows/contract-python.yml)
+
+Official Python SDK for the [TruAgents Unsubscribe API](https://docs.truagents.com).
+Handles OAuth token acquisition and refresh, retries, rate limiting, and
+observability so you can focus on the business logic.
+
+## Install
+
+```bash
+pip install truagents
+```
+
+Requires Python `>= 3.11`.
+
+## Quickstart (sync)
+
+```python
+from truagents import Client
+
+with Client(client_id="...", client_secret="...") as client:
+    resp = client.list_email_unsubscribes()
+    for record in resp.data:
+        print(record.email, record.unsubscribed)
+```
+
+## Quickstart (async)
+
+```python
+import asyncio
+
+from truagents import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient(client_id="...", client_secret="...") as client:
+        resp = await client.list_email_unsubscribes()
+        for record in resp.data:
+            print(record.email, record.unsubscribed)
+
+
+asyncio.run(main())
+```
+
+## Authentication
+
+`TokenManager` (owned by the client) mints an access token via
+`client_credentials` on the first request and refreshes it via `refresh_token`
+`refresh_threshold_seconds` before the server-side expiry (default: 60s).
+Concurrent callers are de-duplicated: a thundering herd of sync threads or
+async coroutines results in a single `/oauth/token` round-trip.
+
+If the cached refresh token is rejected with `invalid_grant` (RFC 6749 §5.2
+family revoke), the manager transparently drops it and re-mints via
+`client_credentials`. Partners never see the intermediate `InvalidGrant`.
+
+**A mid-flight `TokenExpired` (HTTP 401) on an API endpoint is NOT
+auto-remedied.** It signals that your credentials were revoked externally and
+you need to investigate. This is a deliberate design decision — silently
+re-minting on 401 would mask real revocations.
+
+## Retries + rate limiting
+
+Every request goes through a shared `RetryPolicy`:
+
+| Failure                          | Retry?                                    |
+|----------------------------------|-------------------------------------------|
+| `NetworkError`                   | Yes — up to `max_attempts` with exp. back-off |
+| `ServerError` (5xx)              | Yes — up to `max_attempts` with exp. back-off |
+| `RateLimited` (HTTP 429)         | Yes — honours `Retry-After` (capped at 60s) |
+| `InvalidRequest` (HTTP 400)      | No                                        |
+| `NotFound` (HTTP 404)            | No                                        |
+| `TokenExpired` (HTTP 401)        | No                                        |
+
+Override defaults by constructing your own `RetryPolicy`:
+
+```python
+from truagents import Client, RetryPolicy
+
+policy = RetryPolicy(max_attempts=5, base_delay=0.1, retry_after_cap=30.0)
+client = Client(client_id="...", client_secret="...", retry=policy)
+```
+
+## Observability hooks
+
+`Hooks` fire around every HTTP call (token endpoint and API endpoint alike).
+Broken hooks never break an SDK call — they are logged and swallowed.
+
+```python
+from truagents import Client, Hooks, Request, Response
+
+
+def log_request(req: Request) -> None:
+    print(f"-> {req.method} {req.url}")
+
+
+def log_response(resp: Response, elapsed_ms: float) -> None:
+    print(f"<- {resp.status_code} ({elapsed_ms:.0f}ms)")
+
+
+hooks = Hooks(on_request=log_request, on_response=log_response)
+client = Client(client_id="...", client_secret="...", hooks=hooks)
+```
+
+## Error handling
+
+All SDK exceptions inherit from `truagents.errors.TruAgentsError`.
+
+| Exception            | Raised when                                        |
+|----------------------|----------------------------------------------------|
+| `AuthError`          | Base of OAuth token endpoint failures.             |
+| `InvalidClient`      | Token endpoint returned 401 (bad client_id/secret). |
+| `InvalidGrant`       | Token endpoint returned 400 `invalid_grant`. Almost always caught + recovered internally. |
+| `TokenExpired`       | API endpoint returned 401 (external revocation).    |
+| `APIError`           | Base of API endpoint failures.                     |
+| `InvalidRequest`     | API endpoint returned 400.                         |
+| `NotFound`           | API endpoint returned 404.                         |
+| `RateLimited`        | API endpoint returned 429. Carries `retry_after`.  |
+| `ServerError`        | API endpoint returned 5xx.                         |
+| `NetworkError`       | Transport failure (DNS, connection reset, timeout). Wraps the underlying `httpx` exception. |
+
+Every subclass carries a `code` class variable (e.g. `"INVALID_CLIENT"`) so
+you can log it without importing the class.
+
+## Version stability
+
+The SDK is at `0.x`. Minor bumps may introduce breaking changes. See
+[`docs/versioning.md`](../../docs/versioning.md) at the repository root for
+the full policy and the `1.0.0` promotion criteria.
+
+## Links
+
+- Homepage: <https://github.com/ablt-ai/truagents-sdk>
+- Docs: <https://docs.truagents.com>
+- Issues: <https://github.com/ablt-ai/truagents-sdk/issues>
+- License: Apache 2.0 (see [`LICENSE`](../../LICENSE))

truagents-0.0.0.dev0/README.md

@@ -0,0 +1,139 @@
+# truagents — Python SDK for the TruAgents Unsubscribe API
+
+[![PyPI version](https://img.shields.io/pypi/v/truagents.svg)](https://pypi.org/project/truagents/)
+[![Python versions](https://img.shields.io/pypi/pyversions/truagents.svg)](https://pypi.org/project/truagents/)
+[![CI](https://github.com/ablt-ai/truagents-sdk/actions/workflows/contract-python.yml/badge.svg)](https://github.com/ablt-ai/truagents-sdk/actions/workflows/contract-python.yml)
+
+Official Python SDK for the [TruAgents Unsubscribe API](https://docs.truagents.com).
+Handles OAuth token acquisition and refresh, retries, rate limiting, and
+observability so you can focus on the business logic.
+
+## Install
+
+```bash
+pip install truagents
+```
+
+Requires Python `>= 3.11`.
+
+## Quickstart (sync)
+
+```python
+from truagents import Client
+
+with Client(client_id="...", client_secret="...") as client:
+    resp = client.list_email_unsubscribes()
+    for record in resp.data:
+        print(record.email, record.unsubscribed)
+```
+
+## Quickstart (async)
+
+```python
+import asyncio
+
+from truagents import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient(client_id="...", client_secret="...") as client:
+        resp = await client.list_email_unsubscribes()
+        for record in resp.data:
+            print(record.email, record.unsubscribed)
+
+
+asyncio.run(main())
+```
+
+## Authentication
+
+`TokenManager` (owned by the client) mints an access token via
+`client_credentials` on the first request and refreshes it via `refresh_token`
+`refresh_threshold_seconds` before the server-side expiry (default: 60s).
+Concurrent callers are de-duplicated: a thundering herd of sync threads or
+async coroutines results in a single `/oauth/token` round-trip.
+
+If the cached refresh token is rejected with `invalid_grant` (RFC 6749 §5.2
+family revoke), the manager transparently drops it and re-mints via
+`client_credentials`. Partners never see the intermediate `InvalidGrant`.
+
+**A mid-flight `TokenExpired` (HTTP 401) on an API endpoint is NOT
+auto-remedied.** It signals that your credentials were revoked externally and
+you need to investigate. This is a deliberate design decision — silently
+re-minting on 401 would mask real revocations.
+
+## Retries + rate limiting
+
+Every request goes through a shared `RetryPolicy`:
+
+| Failure                          | Retry?                                    |
+|----------------------------------|-------------------------------------------|
+| `NetworkError`                   | Yes — up to `max_attempts` with exp. back-off |
+| `ServerError` (5xx)              | Yes — up to `max_attempts` with exp. back-off |
+| `RateLimited` (HTTP 429)         | Yes — honours `Retry-After` (capped at 60s) |
+| `InvalidRequest` (HTTP 400)      | No                                        |
+| `NotFound` (HTTP 404)            | No                                        |
+| `TokenExpired` (HTTP 401)        | No                                        |
+
+Override defaults by constructing your own `RetryPolicy`:
+
+```python
+from truagents import Client, RetryPolicy
+
+policy = RetryPolicy(max_attempts=5, base_delay=0.1, retry_after_cap=30.0)
+client = Client(client_id="...", client_secret="...", retry=policy)
+```
+
+## Observability hooks
+
+`Hooks` fire around every HTTP call (token endpoint and API endpoint alike).
+Broken hooks never break an SDK call — they are logged and swallowed.
+
+```python
+from truagents import Client, Hooks, Request, Response
+
+
+def log_request(req: Request) -> None:
+    print(f"-> {req.method} {req.url}")
+
+
+def log_response(resp: Response, elapsed_ms: float) -> None:
+    print(f"<- {resp.status_code} ({elapsed_ms:.0f}ms)")
+
+
+hooks = Hooks(on_request=log_request, on_response=log_response)
+client = Client(client_id="...", client_secret="...", hooks=hooks)
+```
+
+## Error handling
+
+All SDK exceptions inherit from `truagents.errors.TruAgentsError`.
+
+| Exception            | Raised when                                        |
+|----------------------|----------------------------------------------------|
+| `AuthError`          | Base of OAuth token endpoint failures.             |
+| `InvalidClient`      | Token endpoint returned 401 (bad client_id/secret). |
+| `InvalidGrant`       | Token endpoint returned 400 `invalid_grant`. Almost always caught + recovered internally. |
+| `TokenExpired`       | API endpoint returned 401 (external revocation).    |
+| `APIError`           | Base of API endpoint failures.                     |
+| `InvalidRequest`     | API endpoint returned 400.                         |
+| `NotFound`           | API endpoint returned 404.                         |
+| `RateLimited`        | API endpoint returned 429. Carries `retry_after`.  |
+| `ServerError`        | API endpoint returned 5xx.                         |
+| `NetworkError`       | Transport failure (DNS, connection reset, timeout). Wraps the underlying `httpx` exception. |
+
+Every subclass carries a `code` class variable (e.g. `"INVALID_CLIENT"`) so
+you can log it without importing the class.
+
+## Version stability
+
+The SDK is at `0.x`. Minor bumps may introduce breaking changes. See
+[`docs/versioning.md`](../../docs/versioning.md) at the repository root for
+the full policy and the `1.0.0` promotion criteria.
+
+## Links
+
+- Homepage: <https://github.com/ablt-ai/truagents-sdk>
+- Docs: <https://docs.truagents.com>
+- Issues: <https://github.com/ablt-ai/truagents-sdk/issues>
+- License: Apache 2.0 (see [`LICENSE`](../../LICENSE))

truagents-0.0.0.dev0/examples/oauth_flow.py

@@ -0,0 +1,73 @@
+"""Runnable positive-flow demo of the TruAgents Python SDK.
+
+Steps:
+  1. Read CLIENT_ID / CLIENT_SECRET / BASE_URL from env.
+  2. Mint an access token via `client_credentials` (via TokenManager).
+  3. GET /api/v1/unsubscribe/email with the fresh token.
+  4. Force a rotation by expiring the cache and re-fetching the token.
+  5. GET /api/v1/unsubscribe/email with the rotated token.
+
+Exit codes:
+  0 — every step OK.
+  1 — unexpected outcome.
+  2 — env missing.
+
+Usage:
+  export CLIENT_ID=...
+  export CLIENT_SECRET=...
+  python examples/oauth_flow.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from truagents import Client, errors
+
+DEFAULT_BASE_URL = "https://api.dev-truagents.com"
+
+
+def read_env() -> tuple[str, str, str]:
+    client_id = os.environ.get("CLIENT_ID")
+    client_secret = os.environ.get("CLIENT_SECRET")
+    base_url = os.environ.get("BASE_URL", DEFAULT_BASE_URL)
+    if not client_id or not client_secret:
+        print("Missing CLIENT_ID / CLIENT_SECRET", file=sys.stderr)
+        sys.exit(2)
+    return client_id, client_secret, base_url
+
+
+def _prefix(value: str) -> str:
+    return f"{value[:12]}..." if value else "<none>"
+
+
+def main() -> int:
+    client_id, client_secret, base_url = read_env()
+    print(f"Step 1: env resolved — CLIENT_ID={_prefix(client_id)} BASE_URL={base_url}")
+
+    with Client(client_id=client_id, client_secret=client_secret, base_url=base_url) as client:
+        try:
+            step2_token = client._token_manager.get_access_token()
+            print(f"Step 2: mint OK — access_token={_prefix(step2_token)}")
+
+            step3 = client.list_email_unsubscribes()
+            print(f"Step 3: GET /api/v1/unsubscribe/email OK — items_count={len(step3.data)}")
+
+            # test/demo escape hatch — not part of public SDK API; do not copy into production
+            client._token_manager._expire_now()
+            step4_token = client._token_manager.get_access_token()
+            print(f"Step 4: refresh rotation OK — new_token={_prefix(step4_token)}")
+
+            step5 = client.list_email_unsubscribes()
+            print(f"Step 5: GET with rotated token OK — items_count={len(step5.data)}")
+        except errors.TruAgentsError as err:
+            print(f"Unexpected error: {err.code} {err}", file=sys.stderr)
+            return 1
+
+    print("All 5 positive-flow steps completed as expected.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

truagents-0.0.0.dev0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "truagents"
+dynamic = ["version"]
+description = "Official Python SDK for the TruAgents Unsubscribe API."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.11"
+authors = [{ name = "ablt-ai" }]
+keywords = ["truagents", "unsubscribe", "sdk", "oauth"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.28",
+  "attrs>=25.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.24",
+  "pytest-timeout>=2.3",
+  "respx>=0.22",
+  "time-machine>=2.16",
+  "ruff==0.15.18",
+  "pyright>=1.1.400",
+]
+
+[project.urls]
+Homepage = "https://github.com/ablt-ai/truagents-sdk"
+Documentation = "https://docs.truagents.com/sdks/python"
+Source = "https://github.com/ablt-ai/truagents-sdk"
+Issues = "https://github.com/ablt-ai/truagents-sdk/issues"
+
+[tool.hatch.version]
+path = "src/truagents/__version__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/truagents"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+extend-exclude = ["src/truagents/generated"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "B", "UP"]
+
+[tool.pyright]
+include = ["src/truagents"]
+exclude = ["tests/**", "src/truagents/generated"]
+pythonVersion = "3.12"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+timeout = 300
+testpaths = ["tests"]
+addopts = "-vvv -rsfEx --tb=short"

truagents-0.0.0.dev0/src/truagents/__init__.py

@@ -0,0 +1,18 @@
+from truagents import errors
+from truagents.__version__ import __version__
+from truagents.auth import TokenManager
+from truagents.client import AsyncClient, Client
+from truagents.observability import Hooks, Request, Response
+from truagents.retry import RetryPolicy
+
+__all__ = [
+    "AsyncClient",
+    "Client",
+    "Hooks",
+    "Request",
+    "Response",
+    "RetryPolicy",
+    "TokenManager",
+    "__version__",
+    "errors",
+]

truagents-0.0.0.dev0/src/truagents/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.0.0.dev0"