outnoise 1.0.0__tar.gz

outnoise-1.0.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: outnoise
+Version: 1.0.0
+Summary: Official Python SDK for the Outnoise Developer
+Keywords: outnoise,sdk,api,social
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1.0,>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# outnoise-sdk
+
+Official Python SDK for the **Outnoise Developer Platform** (formerly Chat X).
+
+```python
+from outnoise import Outnoise
+
+client = Outnoise(api_key="YOUR_BOT_TOKEN")
+print(client.users.me().username)
+client.posts.create(content="Hello from Outnoise SDK!")
+```
+
+- Package name: `outnoise-sdk` · import name: `outnoise`
+- Python 3.8+ · built on [httpx](https://www.python-httpx.org/) · synchronous **and** asynchronous clients
+- Typed exceptions, automatic pagination, automatic rate-limit handling, mocked-HTTP test suite
+
+---
+
+## Installation
+
+```bash
+pip install outnoise-sdk
+```
+
+> The package is not published yet. Until it is, install it from this folder (see [Local development](#local-development)).
+
+## Getting started
+
+1. On Outnoise open the Developer Portal (`/developers`) and **create an application**.
+2. In **Permissions** enable the scopes your code needs (for example `identify`, `posts.read`, `posts.write`).
+3. Either create a **bot** (Bot tab → copy the bot token) or use **OAuth2** (OAuth2 tab → Client ID/Secret, add a redirect URL).
+4. Install the SDK and make a request:
+
+```python
+import os
+from outnoise import Outnoise
+
+client = Outnoise(api_key=os.environ["OUTNOISE_API_KEY"])      # never hard-code credentials
+
+me = client.users.me()                         # scope: identify
+posts = client.posts.list(limit=10)            # scope: posts.read
+post = client.posts.create(content="Hello from Outnoise SDK!")   # scope: posts.write
+groups = client.groups.list(limit=10)          # scope: groups.read
+analytics = client.analytics.overview()        # scope: analytics.read
+```
+
+Responses are dictionaries that also allow attribute access: `me.username` and `me["username"]` both work.
+
+## Authentication
+
+| You pass | Sent as | Acts as | Scopes |
+|---|---|---|---|
+| `api_key="…"` (bot token) | `Authorization: Bot …` | your application's bot account | every scope enabled for the application |
+| `access_token="…"` (OAuth2) | `Authorization: Bearer …` | the user who authorized your app | the scopes that user approved |
+
+```python
+bot  = Outnoise(api_key="onbt_…")
+user = Outnoise(access_token="onat_…")
+```
+
+Pass **either** one, not both. Both can also come from the environment:
+
+| Variable | Meaning |
+|---|---|
+| `OUTNOISE_API_KEY` | bot token |
+| `OUTNOISE_ACCESS_TOKEN` | OAuth2 access token |
+| `OUTNOISE_BASE_URL` | API address, e.g. `http://127.0.0.1:8000/api/v1` |
+
+```python
+client = Outnoise()          # reads OUTNOISE_API_KEY / OUTNOISE_ACCESS_TOKEN / OUTNOISE_BASE_URL
+```
+
+### Getting an OAuth2 access token
+
+Send the user to `https://<your-outnoise-host>/oauth2/authorize?client_id=APP_ID&response_type=code&redirect_uri=…&scope=identify%20posts.read&state=…`,
+then exchange the returned `code` **on your server** (the client secret must never reach a browser):
+
+```python
+import httpx
+
+tokens = httpx.post("https://<your-outnoise-host>/oauth2/token", data={
+    "grant_type": "authorization_code", "code": code, "redirect_uri": "https://example.com/callback",
+    "client_id": APP_ID, "client_secret": CLIENT_SECRET,
+}).json()
+
+client = Outnoise(access_token=tokens["access_token"])
+```
+
+Access tokens expire after 1 hour; renew with `grant_type=refresh_token`. Full details: `/developers/documentation/authentication`.
+
+## Available resources
+
+| Resource | Methods | Scope |
+|---|---|---|
+| `client.applications` | `me()` | – |
+| `client.users` | `me()`, `get(username)` | `identify`, `profile.read` |
+| `client.posts` | `list(limit, offset, author)`, `iter(...)`, `get(id)`, `create(content, visibility, images, feeling)` | `posts.read`, `posts.write` |
+| `client.groups` | `list(limit, offset, mine)`, `iter(...)`, `get(id)` | `groups.read` |
+| `client.events` | `list(limit, offset, include_past)`, `iter(...)` | `events.read` |
+| `client.messages` | `list(user, limit, offset)`, `iter(user)`, `send(recipient, content)` | `messages.read`, `messages.write` |
+| `client.analytics` | `overview(days=28)` | `analytics.read` |
+
+Notes: `visibility` is `public`, `followers`, `unlisted` or `private`. Bots may only direct-message users who authorized the application or messaged the bot first. Methods raise `ValueError` for bad arguments before any request is made.
+
+## Pagination
+
+List methods return a `Page` (a normal list with paging info):
+
+```python
+page = client.posts.list(limit=10)
+print(len(page), page.has_more, page.next_offset)
+page2 = client.posts.list(limit=10, offset=page.next_offset)
+```
+
+or iterate over everything — pages are fetched lazily:
+
+```python
+for post in client.posts.iter(author="alice", page_size=50, max_items=200):
+    print(post.content)
+```
+
+## Error handling
+
+```python
+from outnoise import (Outnoise, OutnoiseError, AuthenticationError, MissingScopeError, NotFoundError,
+                      RateLimitError, APIConnectionError)
+
+try:
+    client.posts.create(content="hi")
+except MissingScopeError as e:
+    print("Enable these scopes:", e.required_scopes)
+except AuthenticationError:
+    print("Bad, expired or revoked credentials")
+except RateLimitError as e:
+    print("Slow down, retry in", e.retry_after, "seconds")
+except NotFoundError:
+    ...
+except APIConnectionError:
+    print("Could not reach Outnoise")
+except OutnoiseError as e:      # catches everything from this package
+    print(e)                    # e.g. "[400 content_too_long] Content too long (max 2500 characters)."
+```
+
+| Exception | When |
+|---|---|
+| `ConfigurationError` | missing/conflicting credentials, bad `base_url` |
+| `APIConnectionError` / `APITimeoutError` | network failure / timeout |
+| `InvalidRequestError` (400) | the API rejected the request |
+| `AuthenticationError` (401) | invalid, expired or revoked token |
+| `PermissionDeniedError` (403), `MissingScopeError` | not allowed / missing scope |
+| `NotFoundError` (404) | unknown or invisible resource |
+| `RateLimitError` (429) | rate limit exceeded (`.retry_after`) |
+| `ServerError` (5xx) | server problem |
+
+Every API error has `.status_code`, `.code`, `.message`, `.body` and `.headers`.
+
+### Rate limits and retries
+
+The API limits each token (reads 120/min, writes 30/min, messages 20/min). The SDK automatically:
+
+- retries `429` responses after the `Retry-After` delay (also for `POST`, because a rate-limited request was not processed);
+- retries `GET` requests on connection errors, timeouts and 502/503/504 with exponential backoff.
+
+Control it with `Outnoise(max_retries=2, max_retry_wait=30)`; `max_retries=0` turns retrying off. If the server asks for a longer wait than `max_retry_wait`, `RateLimitError` is raised immediately.
+
+## Async usage
+
+```python
+import asyncio
+from outnoise import AsyncOutnoise
+
+async def main():
+    async with AsyncOutnoise(api_key="YOUR_BOT_TOKEN") as client:
+        me = await client.users.me()
+        post = await client.posts.create(content="Hello from async!")
+        async for p in client.posts.iter(max_items=100):
+            print(p.content)
+
+asyncio.run(main())
+```
+
+`AsyncOutnoise` has the same resources and options; every call is awaited and `iter()` is used with `async for`.
+
+## Configuration
+
+```python
+client = Outnoise(
+    api_key="…",
+    base_url="http://127.0.0.1:8000/api/v1",   # custom API address (local testing, staging)
+    timeout=30,                                # seconds
+    max_retries=2,
+)
+```
+
+The built-in default address is the beta deployment (`https://beta-chatx.hostmybotprojects.net/api/v1`). Change `DEFAULT_BASE_URL` in `src/outnoise/_base.py`, or pass `base_url` / `OUTNOISE_BASE_URL`, when you use another host. You can also hand over your own `httpx.Client` / `httpx.AsyncClient` with `http_client=` (proxies, custom transports).
+
+## Local development
+
+Install in editable mode — no PyPI needed:
+
+```bash
+cd outnoise-sdk
+python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+Test it against your local Outnoise backend (use a **test** account/application, never production credentials):
+
+```python
+from outnoise import Outnoise
+client = Outnoise(api_key="TEST_KEY", base_url="http://127.0.0.1:8000/api/v1")
+print(client.users.me())
+```
+
+(`python app.py` in the Outnoise project serves on port 3002 by default, so the local URL is usually `http://127.0.0.1:3002/api/v1`.)
+
+## Testing
+
+```bash
+pytest
+```
+
+The suite uses `httpx.MockTransport`, so it needs **no network and no credentials**. It covers authentication, request building, invalid credentials, API errors, pagination, rate limits, custom base URLs, every resource method and the async client.
+`tests/test_live_backend.py` is an optional integration test that is skipped unless `OUTNOISE_TEST_BASE_URL` and `OUTNOISE_TEST_API_KEY` point at a local test backend.
+
+## Security
+
+- Keep bot tokens and client secrets in environment variables or a secrets manager — never in source control, browsers or mobile apps.
+- Resetting a token or secret in the Developer Portal invalidates the old one immediately.
+- Credentials are never included in exception messages or `repr()` output.

outnoise-1.0.0/README.md

@@ -0,0 +1,230 @@
+# outnoise-sdk
+
+Official Python SDK for the **Outnoise Developer Platform** (formerly Chat X).
+
+```python
+from outnoise import Outnoise
+
+client = Outnoise(api_key="YOUR_BOT_TOKEN")
+print(client.users.me().username)
+client.posts.create(content="Hello from Outnoise SDK!")
+```
+
+- Package name: `outnoise-sdk` · import name: `outnoise`
+- Python 3.8+ · built on [httpx](https://www.python-httpx.org/) · synchronous **and** asynchronous clients
+- Typed exceptions, automatic pagination, automatic rate-limit handling, mocked-HTTP test suite
+
+---
+
+## Installation
+
+```bash
+pip install outnoise-sdk
+```
+
+> The package is not published yet. Until it is, install it from this folder (see [Local development](#local-development)).
+
+## Getting started
+
+1. On Outnoise open the Developer Portal (`/developers`) and **create an application**.
+2. In **Permissions** enable the scopes your code needs (for example `identify`, `posts.read`, `posts.write`).
+3. Either create a **bot** (Bot tab → copy the bot token) or use **OAuth2** (OAuth2 tab → Client ID/Secret, add a redirect URL).
+4. Install the SDK and make a request:
+
+```python
+import os
+from outnoise import Outnoise
+
+client = Outnoise(api_key=os.environ["OUTNOISE_API_KEY"])      # never hard-code credentials
+
+me = client.users.me()                         # scope: identify
+posts = client.posts.list(limit=10)            # scope: posts.read
+post = client.posts.create(content="Hello from Outnoise SDK!")   # scope: posts.write
+groups = client.groups.list(limit=10)          # scope: groups.read
+analytics = client.analytics.overview()        # scope: analytics.read
+```
+
+Responses are dictionaries that also allow attribute access: `me.username` and `me["username"]` both work.
+
+## Authentication
+
+| You pass | Sent as | Acts as | Scopes |
+|---|---|---|---|
+| `api_key="…"` (bot token) | `Authorization: Bot …` | your application's bot account | every scope enabled for the application |
+| `access_token="…"` (OAuth2) | `Authorization: Bearer …` | the user who authorized your app | the scopes that user approved |
+
+```python
+bot  = Outnoise(api_key="onbt_…")
+user = Outnoise(access_token="onat_…")
+```
+
+Pass **either** one, not both. Both can also come from the environment:
+
+| Variable | Meaning |
+|---|---|
+| `OUTNOISE_API_KEY` | bot token |
+| `OUTNOISE_ACCESS_TOKEN` | OAuth2 access token |
+| `OUTNOISE_BASE_URL` | API address, e.g. `http://127.0.0.1:8000/api/v1` |
+
+```python
+client = Outnoise()          # reads OUTNOISE_API_KEY / OUTNOISE_ACCESS_TOKEN / OUTNOISE_BASE_URL
+```
+
+### Getting an OAuth2 access token
+
+Send the user to `https://<your-outnoise-host>/oauth2/authorize?client_id=APP_ID&response_type=code&redirect_uri=…&scope=identify%20posts.read&state=…`,
+then exchange the returned `code` **on your server** (the client secret must never reach a browser):
+
+```python
+import httpx
+
+tokens = httpx.post("https://<your-outnoise-host>/oauth2/token", data={
+    "grant_type": "authorization_code", "code": code, "redirect_uri": "https://example.com/callback",
+    "client_id": APP_ID, "client_secret": CLIENT_SECRET,
+}).json()
+
+client = Outnoise(access_token=tokens["access_token"])
+```
+
+Access tokens expire after 1 hour; renew with `grant_type=refresh_token`. Full details: `/developers/documentation/authentication`.
+
+## Available resources
+
+| Resource | Methods | Scope |
+|---|---|---|
+| `client.applications` | `me()` | – |
+| `client.users` | `me()`, `get(username)` | `identify`, `profile.read` |
+| `client.posts` | `list(limit, offset, author)`, `iter(...)`, `get(id)`, `create(content, visibility, images, feeling)` | `posts.read`, `posts.write` |
+| `client.groups` | `list(limit, offset, mine)`, `iter(...)`, `get(id)` | `groups.read` |
+| `client.events` | `list(limit, offset, include_past)`, `iter(...)` | `events.read` |
+| `client.messages` | `list(user, limit, offset)`, `iter(user)`, `send(recipient, content)` | `messages.read`, `messages.write` |
+| `client.analytics` | `overview(days=28)` | `analytics.read` |
+
+Notes: `visibility` is `public`, `followers`, `unlisted` or `private`. Bots may only direct-message users who authorized the application or messaged the bot first. Methods raise `ValueError` for bad arguments before any request is made.
+
+## Pagination
+
+List methods return a `Page` (a normal list with paging info):
+
+```python
+page = client.posts.list(limit=10)
+print(len(page), page.has_more, page.next_offset)
+page2 = client.posts.list(limit=10, offset=page.next_offset)
+```
+
+or iterate over everything — pages are fetched lazily:
+
+```python
+for post in client.posts.iter(author="alice", page_size=50, max_items=200):
+    print(post.content)
+```
+
+## Error handling
+
+```python
+from outnoise import (Outnoise, OutnoiseError, AuthenticationError, MissingScopeError, NotFoundError,
+                      RateLimitError, APIConnectionError)
+
+try:
+    client.posts.create(content="hi")
+except MissingScopeError as e:
+    print("Enable these scopes:", e.required_scopes)
+except AuthenticationError:
+    print("Bad, expired or revoked credentials")
+except RateLimitError as e:
+    print("Slow down, retry in", e.retry_after, "seconds")
+except NotFoundError:
+    ...
+except APIConnectionError:
+    print("Could not reach Outnoise")
+except OutnoiseError as e:      # catches everything from this package
+    print(e)                    # e.g. "[400 content_too_long] Content too long (max 2500 characters)."
+```
+
+| Exception | When |
+|---|---|
+| `ConfigurationError` | missing/conflicting credentials, bad `base_url` |
+| `APIConnectionError` / `APITimeoutError` | network failure / timeout |
+| `InvalidRequestError` (400) | the API rejected the request |
+| `AuthenticationError` (401) | invalid, expired or revoked token |
+| `PermissionDeniedError` (403), `MissingScopeError` | not allowed / missing scope |
+| `NotFoundError` (404) | unknown or invisible resource |
+| `RateLimitError` (429) | rate limit exceeded (`.retry_after`) |
+| `ServerError` (5xx) | server problem |
+
+Every API error has `.status_code`, `.code`, `.message`, `.body` and `.headers`.
+
+### Rate limits and retries
+
+The API limits each token (reads 120/min, writes 30/min, messages 20/min). The SDK automatically:
+
+- retries `429` responses after the `Retry-After` delay (also for `POST`, because a rate-limited request was not processed);
+- retries `GET` requests on connection errors, timeouts and 502/503/504 with exponential backoff.
+
+Control it with `Outnoise(max_retries=2, max_retry_wait=30)`; `max_retries=0` turns retrying off. If the server asks for a longer wait than `max_retry_wait`, `RateLimitError` is raised immediately.
+
+## Async usage
+
+```python
+import asyncio
+from outnoise import AsyncOutnoise
+
+async def main():
+    async with AsyncOutnoise(api_key="YOUR_BOT_TOKEN") as client:
+        me = await client.users.me()
+        post = await client.posts.create(content="Hello from async!")
+        async for p in client.posts.iter(max_items=100):
+            print(p.content)
+
+asyncio.run(main())
+```
+
+`AsyncOutnoise` has the same resources and options; every call is awaited and `iter()` is used with `async for`.
+
+## Configuration
+
+```python
+client = Outnoise(
+    api_key="…",
+    base_url="http://127.0.0.1:8000/api/v1",   # custom API address (local testing, staging)
+    timeout=30,                                # seconds
+    max_retries=2,
+)
+```
+
+The built-in default address is the beta deployment (`https://beta-chatx.hostmybotprojects.net/api/v1`). Change `DEFAULT_BASE_URL` in `src/outnoise/_base.py`, or pass `base_url` / `OUTNOISE_BASE_URL`, when you use another host. You can also hand over your own `httpx.Client` / `httpx.AsyncClient` with `http_client=` (proxies, custom transports).
+
+## Local development
+
+Install in editable mode — no PyPI needed:
+
+```bash
+cd outnoise-sdk
+python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+Test it against your local Outnoise backend (use a **test** account/application, never production credentials):
+
+```python
+from outnoise import Outnoise
+client = Outnoise(api_key="TEST_KEY", base_url="http://127.0.0.1:8000/api/v1")
+print(client.users.me())
+```
+
+(`python app.py` in the Outnoise project serves on port 3002 by default, so the local URL is usually `http://127.0.0.1:3002/api/v1`.)
+
+## Testing
+
+```bash
+pytest
+```
+
+The suite uses `httpx.MockTransport`, so it needs **no network and no credentials**. It covers authentication, request building, invalid credentials, API errors, pagination, rate limits, custom base URLs, every resource method and the async client.
+`tests/test_live_backend.py` is an optional integration test that is skipped unless `OUTNOISE_TEST_BASE_URL` and `OUTNOISE_TEST_API_KEY` point at a local test backend.
+
+## Security
+
+- Keep bot tokens and client secrets in environment variables or a secrets manager — never in source control, browsers or mobile apps.
+- Resetting a token or secret in the Developer Portal invalidates the old one immediately.
+- Credentials are never included in exception messages or `repr()` output.

outnoise-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "outnoise"
+version = "1.0.0"
+description = "Official Python SDK for the Outnoise Developer"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = ["httpx>=0.24,<1.0"]
+keywords = ["outnoise", "sdk", "api", "social"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+outnoise = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]

outnoise-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

outnoise-1.0.0/src/outnoise/__init__.py

@@ -0,0 +1,15 @@
+"""Official Python SDK for the Outnoise Developer Platform."""
+from ._version import __version__
+from .async_client import AsyncOutnoise
+from .client import Outnoise
+from .exceptions import (APIConnectionError, APIStatusError, APITimeoutError, AuthenticationError,
+                         ConfigurationError, InvalidRequestError, MissingScopeError, NotFoundError,
+                         OutnoiseError, PermissionDeniedError, RateLimitError, ServerError)
+from .models import AttrDict, Page
+
+__all__ = [
+    "Outnoise", "AsyncOutnoise", "Page", "AttrDict", "__version__",
+    "OutnoiseError", "ConfigurationError", "APIConnectionError", "APITimeoutError", "APIStatusError",
+    "InvalidRequestError", "AuthenticationError", "PermissionDeniedError", "MissingScopeError",
+    "NotFoundError", "RateLimitError", "ServerError",
+]

outnoise-1.0.0/src/outnoise/_base.py

@@ -0,0 +1,126 @@
+"""Configuration, request building and response handling shared by the sync and async clients."""
+import json
+import os
+import random
+import time  # noqa: F401  (patched in tests)
+from typing import Any, Dict, Optional, Tuple
+
+import httpx
+
+from ._version import __version__
+from .exceptions import APIStatusError, ConfigurationError, OutnoiseError, error_for_status
+from .models import Page, wrap
+
+# The beta deployment. Override with base_url=... or OUTNOISE_BASE_URL once you use another host.
+DEFAULT_BASE_URL = "https://beta-chatx.hostmybotprojects.net/api/v1"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+MAX_RETRY_WAIT = 30.0           # never sleep longer than this for a single retry
+_RETRY_STATUS = (502, 503, 504)  # transient server errors; retried for GET only
+
+
+class ClientConfig:
+    def __init__(self, api_key, access_token, base_url, timeout, max_retries, max_retry_wait):
+        api_key = api_key or os.environ.get("OUTNOISE_API_KEY") or None
+        access_token = access_token or os.environ.get("OUTNOISE_ACCESS_TOKEN") or None
+        if api_key and access_token:
+            raise ConfigurationError("Pass either api_key (bot token) or access_token (OAuth2), not both.")
+        if not api_key and not access_token:
+            raise ConfigurationError(
+                "No credentials. Pass api_key=... (bot token) or access_token=... (OAuth2), "
+                "or set OUTNOISE_API_KEY / OUTNOISE_ACCESS_TOKEN.")
+        base_url = (base_url or os.environ.get("OUTNOISE_BASE_URL") or DEFAULT_BASE_URL).strip().rstrip("/")
+        if not base_url.startswith(("http://", "https://")):
+            raise ConfigurationError(f"base_url must start with http:// or https:// (got {base_url!r}).")
+        if timeout is not None and timeout <= 0:
+            raise ConfigurationError("timeout must be positive.")
+        if max_retries < 0:
+            raise ConfigurationError("max_retries must be 0 or greater.")
+        self.base_url = base_url
+        self.timeout = DEFAULT_TIMEOUT if timeout is None else timeout
+        self.max_retries = max_retries
+        self.max_retry_wait = max_retry_wait
+        self.headers = {
+            "Authorization": ("Bot " + api_key) if api_key else ("Bearer " + access_token),
+            "Accept": "application/json",
+            "User-Agent": f"outnoise-python/{__version__}",
+        }
+
+    def __repr__(self):  # never print credentials
+        return f"<ClientConfig base_url={self.base_url!r}>"
+
+
+def clean_params(params: Optional[Dict[str, Any]]) -> Dict[str, str]:
+    out = {}
+    for k, v in (params or {}).items():
+        if v is None:
+            continue
+        out[k] = ("1" if v else "0") if isinstance(v, bool) else str(v)
+    return out
+
+
+def retry_delay(attempt: int, retry_after: Optional[float], max_wait: float) -> Optional[float]:
+    """Seconds to wait before retry number `attempt` (0-based), or None if we should give up."""
+    if retry_after is not None:
+        return None if retry_after > max_wait else max(0.0, retry_after)
+    return min(max_wait, 0.5 * (2 ** attempt)) * (0.75 + random.random() / 2)
+
+
+def parse_retry_after(headers) -> Optional[float]:
+    raw = headers.get("Retry-After") if headers is not None else None
+    try:
+        return float(raw) if raw is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def build_error(resp: "httpx.Response") -> APIStatusError:
+    body: Any = None
+    try:
+        body = resp.json()
+    except ValueError:
+        pass
+    message, code = None, None
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, dict):                     # tolerate {"error": {"message": ...}}
+            message, code = err.get("message"), err.get("code")
+        else:
+            message = err if isinstance(err, str) else body.get("message")
+            code = body.get("code")
+        if not code and isinstance(err, str) and body.get("error_description"):   # OAuth2 style
+            code, message = err, body["error_description"]
+    if not message:
+        snippet = (resp.text or "").strip().replace("\n", " ")[:200]
+        message = snippet or f"HTTP {resp.status_code}"
+    return error_for_status(resp.status_code, message, code, body, resp.headers, parse_retry_after(resp.headers))
+
+
+def parse_success(resp: "httpx.Response") -> Any:
+    try:
+        body = resp.json()
+    except ValueError:
+        raise OutnoiseError(f"The API returned a non-JSON response (HTTP {resp.status_code}).") from None
+    if not isinstance(body, dict) or "data" not in body:
+        raise OutnoiseError("Unexpected API response shape (missing 'data').")
+    data = wrap(body["data"])
+    if isinstance(body.get("paging"), dict) and isinstance(data, list):
+        return Page(data, body["paging"])
+    return data
+
+
+def request_kwargs(method: str, path: str, params, json_body) -> Tuple[str, Dict[str, Any]]:
+    kw: Dict[str, Any] = {}
+    q = clean_params(params)
+    if q:
+        kw["params"] = q
+    if json_body is not None:
+        kw["json"] = json_body
+    return method.upper(), kw
+
+
+def validate_page_args(limit: int, offset: int):
+    if not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= 50:
+        raise ValueError("limit must be an integer between 1 and 50.")
+    if not isinstance(offset, int) or isinstance(offset, bool) or offset < 0:
+        raise ValueError("offset must be an integer of 0 or greater.")

outnoise-1.0.0/src/outnoise/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"