trigv 1.0.0__tar.gz

trigv-1.0.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+.env
+*.egg

trigv-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trigv
+
+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.

trigv-1.0.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: trigv
+Version: 1.0.0
+Summary: Official Trigv SDK for Python — send notification events to your workspace
+Project-URL: Homepage, https://trigv.com
+Project-URL: Repository, https://github.com/Trigv/trigv-python
+Project-URL: Documentation, https://github.com/Trigv/trigv-python#readme
+Author: Trigv
+License-Expression: MIT
+License-File: LICENSE
+Keywords: notifications,push,sdk,trigv
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Trigv Python SDK
+
+Official Python client for the [Trigv](https://trigv.com) workspace ingest API. Send push notification events from scripts, cron jobs, CI pipelines, and backend services.
+
+## Installation
+
+```bash
+pip install trigv
+```
+
+Requires Python 3.10 or newer. No runtime dependencies beyond the standard library.
+
+## Quick start
+
+```python
+from trigv import Trigv
+
+trigv = Trigv()
+
+result = trigv.send_event(
+    {
+        "channel": "general",
+        "title": "Hello from Python",
+    }
+)
+
+print(result.event.public_id)
+```
+
+## Authentication
+
+Create a workspace ingest API key in the Trigv dashboard. Keys look like `trgv_a1b2c3d4_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`.
+
+Pass the key when constructing the client, or set the `TRIGV_API_KEY` environment variable:
+
+```python
+from trigv import Trigv
+
+trigv = Trigv(api_key="trgv_your_api_key")
+```
+
+Never commit API keys to source control. The SDK does not include your key in error messages or logs.
+
+## Sending an event
+
+```python
+result = trigv.send_event(
+    {
+        "channel": "deploys",
+        "title": "Production deploy complete",
+        "description": "Build #42 succeeded in 38s (commit abc1234)",
+        "level": "success",
+        "event_type": "deploy.completed",
+    }
+)
+
+print(result.event.public_id, result.event.status)
+```
+
+`send_event()` returns a `SendEventResult` with:
+
+- `event` — server metadata (`public_id`, `status`, `target_device_count`, etc.)
+- `duplicate` — `True` when the same `idempotency_key` was already accepted (HTTP 200)
+
+Title, description, and image URL are delivered to devices but are **not** stored server-side.
+
+## Event options
+
+| Field | Required | Description |
+|-------|:--------:|-------------|
+| `channel` | Yes | Channel slug (e.g. `general`, `deploys`) |
+| `title` | Yes | Notification title |
+| `description` | No | Body text (max 1000 characters) |
+| `image_url` | No | HTTPS image URL (max 2048 characters) |
+| `url` | No | Destination URL for the notification (max 2048 characters; not stored server-side) |
+| `level` | No | `info`, `success`, `warning`, or `error` (default: `info`) |
+| `delivery_urgency` | No | `standard` or `time_sensitive` (default: `standard`) |
+| `event_type` | No | Free-form label (e.g. `deploy.completed`) |
+| `idempotency_key` | No | Dedup key per workspace (max 190 characters) |
+
+Prohibited fields: `api_key` (use the `Authorization` header), `icon`.
+
+## Levels
+
+| Level | Use case |
+|-------|----------|
+| `info` | General updates (default) |
+| `success` | Completed jobs, successful deploys |
+| `warning` | Degraded service, retries |
+| `error` | Failures requiring attention |
+
+## Delivery urgency
+
+| Value | Behaviour |
+|-------|-----------|
+| `standard` | Normal delivery (default) |
+| `time_sensitive` | iOS time-sensitive interruption level |
+
+## Idempotency
+
+Set `idempotency_key` to safely retry delivery without creating duplicate events or billing twice:
+
+```python
+result = trigv.send_event(
+    {
+        "channel": "deploys",
+        "title": "Production deploy complete",
+        "idempotency_key": "deploy-prod-42",
+    }
+)
+
+if result.duplicate:
+    print("Already sent:", result.event.public_id)
+```
+
+- First request with a key → HTTP 202, `duplicate=False`, usage billed
+- Retry with the same key → HTTP 200, `duplicate=True`, no additional usage
+
+Without an `idempotency_key`, the SDK does not auto-retry `send_event()` on ambiguous failures.
+
+## Error handling
+
+```python
+from trigv import (
+    AuthenticationError,
+    AuthorizationError,
+    NotFoundError,
+    RateLimitError,
+    Trigv,
+    ValidationError,
+)
+
+trigv = Trigv()
+
+try:
+    trigv.send_event({"channel": "general", "title": "Hello"})
+except ValidationError as exc:
+    print(exc.errors)
+except AuthenticationError:
+    print("Check your API key")
+except NotFoundError:
+    print("Channel does not exist")
+except RateLimitError as exc:
+    if exc.retryable:
+        print("Per-minute limit — retry shortly")
+    else:
+        print("Monthly workspace cap reached")
+```
+
+| Exception | When |
+|-----------|------|
+| `ValidationError` | Client-side validation or HTTP 422 |
+| `AuthenticationError` | HTTP 401 |
+| `AuthorizationError` | HTTP 403 |
+| `NotFoundError` | HTTP 404 (e.g. unknown channel) |
+| `RateLimitError` | HTTP 429 (`retryable` distinguishes burst vs monthly cap) |
+| `ApiError` | Other HTTP errors |
+| `NetworkError` | Connection failure |
+| `TimeoutError` | Request timeout |
+
+## Configuration
+
+```python
+trigv = Trigv(
+    api_key="trgv_your_api_key",
+    base_url="https://api.trigv.com/api",  # default
+    timeout=30.0,                          # seconds
+    max_retries=2,                         # retryable errors only
+)
+```
+
+For local development with [Laravel Herd](https://herd.laravel.com):
+
+```python
+trigv = Trigv(base_url="http://trigv-platform.test/api")
+```
+
+### Verify connection
+
+Check that your API key is valid without sending an event or consuming usage:
+
+```python
+connection = trigv.verify_connection()
+print(connection.workspace.name)
+print(connection.api_key.prefix)
+```
+
+## Examples
+
+See the [`examples/`](examples/) directory:
+
+- [`basic.py`](examples/basic.py) — minimal event
+- [`deploy-completed.py`](examples/deploy-completed.py) — canonical deploy notification
+- [`cron-failed.py`](examples/cron-failed.py) — scheduled job failure
+- [`idempotency.py`](examples/idempotency.py) — safe retries with idempotency keys
+
+## Development
+
+```bash
+git clone https://github.com/Trigv/trigv-python.git
+cd trigv-python
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Or with PEP 735 dependency groups:
+
+```bash
+pip install pytest ruff black hatchling
+pip install -e .
+```
+
+## Testing
+
+```bash
+pytest
+ruff check src tests examples
+black --check src tests examples
+```
+
+Tests use a mocked HTTP transport — no live API key required.
+
+## Contributing
+
+Contributions are welcome. Please open an issue or pull request on [GitHub](https://github.com/Trigv/trigv-python).
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).

trigv-1.0.0/README.md

@@ -0,0 +1,230 @@
+# Trigv Python SDK
+
+Official Python client for the [Trigv](https://trigv.com) workspace ingest API. Send push notification events from scripts, cron jobs, CI pipelines, and backend services.
+
+## Installation
+
+```bash
+pip install trigv
+```
+
+Requires Python 3.10 or newer. No runtime dependencies beyond the standard library.
+
+## Quick start
+
+```python
+from trigv import Trigv
+
+trigv = Trigv()
+
+result = trigv.send_event(
+    {
+        "channel": "general",
+        "title": "Hello from Python",
+    }
+)
+
+print(result.event.public_id)
+```
+
+## Authentication
+
+Create a workspace ingest API key in the Trigv dashboard. Keys look like `trgv_a1b2c3d4_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`.
+
+Pass the key when constructing the client, or set the `TRIGV_API_KEY` environment variable:
+
+```python
+from trigv import Trigv
+
+trigv = Trigv(api_key="trgv_your_api_key")
+```
+
+Never commit API keys to source control. The SDK does not include your key in error messages or logs.
+
+## Sending an event
+
+```python
+result = trigv.send_event(
+    {
+        "channel": "deploys",
+        "title": "Production deploy complete",
+        "description": "Build #42 succeeded in 38s (commit abc1234)",
+        "level": "success",
+        "event_type": "deploy.completed",
+    }
+)
+
+print(result.event.public_id, result.event.status)
+```
+
+`send_event()` returns a `SendEventResult` with:
+
+- `event` — server metadata (`public_id`, `status`, `target_device_count`, etc.)
+- `duplicate` — `True` when the same `idempotency_key` was already accepted (HTTP 200)
+
+Title, description, and image URL are delivered to devices but are **not** stored server-side.
+
+## Event options
+
+| Field | Required | Description |
+|-------|:--------:|-------------|
+| `channel` | Yes | Channel slug (e.g. `general`, `deploys`) |
+| `title` | Yes | Notification title |
+| `description` | No | Body text (max 1000 characters) |
+| `image_url` | No | HTTPS image URL (max 2048 characters) |
+| `url` | No | Destination URL for the notification (max 2048 characters; not stored server-side) |
+| `level` | No | `info`, `success`, `warning`, or `error` (default: `info`) |
+| `delivery_urgency` | No | `standard` or `time_sensitive` (default: `standard`) |
+| `event_type` | No | Free-form label (e.g. `deploy.completed`) |
+| `idempotency_key` | No | Dedup key per workspace (max 190 characters) |
+
+Prohibited fields: `api_key` (use the `Authorization` header), `icon`.
+
+## Levels
+
+| Level | Use case |
+|-------|----------|
+| `info` | General updates (default) |
+| `success` | Completed jobs, successful deploys |
+| `warning` | Degraded service, retries |
+| `error` | Failures requiring attention |
+
+## Delivery urgency
+
+| Value | Behaviour |
+|-------|-----------|
+| `standard` | Normal delivery (default) |
+| `time_sensitive` | iOS time-sensitive interruption level |
+
+## Idempotency
+
+Set `idempotency_key` to safely retry delivery without creating duplicate events or billing twice:
+
+```python
+result = trigv.send_event(
+    {
+        "channel": "deploys",
+        "title": "Production deploy complete",
+        "idempotency_key": "deploy-prod-42",
+    }
+)
+
+if result.duplicate:
+    print("Already sent:", result.event.public_id)
+```
+
+- First request with a key → HTTP 202, `duplicate=False`, usage billed
+- Retry with the same key → HTTP 200, `duplicate=True`, no additional usage
+
+Without an `idempotency_key`, the SDK does not auto-retry `send_event()` on ambiguous failures.
+
+## Error handling
+
+```python
+from trigv import (
+    AuthenticationError,
+    AuthorizationError,
+    NotFoundError,
+    RateLimitError,
+    Trigv,
+    ValidationError,
+)
+
+trigv = Trigv()
+
+try:
+    trigv.send_event({"channel": "general", "title": "Hello"})
+except ValidationError as exc:
+    print(exc.errors)
+except AuthenticationError:
+    print("Check your API key")
+except NotFoundError:
+    print("Channel does not exist")
+except RateLimitError as exc:
+    if exc.retryable:
+        print("Per-minute limit — retry shortly")
+    else:
+        print("Monthly workspace cap reached")
+```
+
+| Exception | When |
+|-----------|------|
+| `ValidationError` | Client-side validation or HTTP 422 |
+| `AuthenticationError` | HTTP 401 |
+| `AuthorizationError` | HTTP 403 |
+| `NotFoundError` | HTTP 404 (e.g. unknown channel) |
+| `RateLimitError` | HTTP 429 (`retryable` distinguishes burst vs monthly cap) |
+| `ApiError` | Other HTTP errors |
+| `NetworkError` | Connection failure |
+| `TimeoutError` | Request timeout |
+
+## Configuration
+
+```python
+trigv = Trigv(
+    api_key="trgv_your_api_key",
+    base_url="https://api.trigv.com/api",  # default
+    timeout=30.0,                          # seconds
+    max_retries=2,                         # retryable errors only
+)
+```
+
+For local development with [Laravel Herd](https://herd.laravel.com):
+
+```python
+trigv = Trigv(base_url="http://trigv-platform.test/api")
+```
+
+### Verify connection
+
+Check that your API key is valid without sending an event or consuming usage:
+
+```python
+connection = trigv.verify_connection()
+print(connection.workspace.name)
+print(connection.api_key.prefix)
+```
+
+## Examples
+
+See the [`examples/`](examples/) directory:
+
+- [`basic.py`](examples/basic.py) — minimal event
+- [`deploy-completed.py`](examples/deploy-completed.py) — canonical deploy notification
+- [`cron-failed.py`](examples/cron-failed.py) — scheduled job failure
+- [`idempotency.py`](examples/idempotency.py) — safe retries with idempotency keys
+
+## Development
+
+```bash
+git clone https://github.com/Trigv/trigv-python.git
+cd trigv-python
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Or with PEP 735 dependency groups:
+
+```bash
+pip install pytest ruff black hatchling
+pip install -e .
+```
+
+## Testing
+
+```bash
+pytest
+ruff check src tests examples
+black --check src tests examples
+```
+
+Tests use a mocked HTTP transport — no live API key required.
+
+## Contributing
+
+Contributions are welcome. Please open an issue or pull request on [GitHub](https://github.com/Trigv/trigv-python).
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).

trigv-1.0.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "trigv"
+version = "1.0.0"
+description = "Official Trigv SDK for Python — send notification events to your workspace"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Trigv" }]
+keywords = ["trigv", "notifications", "push", "sdk"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://trigv.com"
+Repository = "https://github.com/Trigv/trigv-python"
+Documentation = "https://github.com/Trigv/trigv-python#readme"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/trigv"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/trigv", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests", "examples"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.black]
+line-length = 100
+target-version = ["py310", "py311", "py312"]
+
+[project.optional-dependencies]
+dev = ["black>=24.0", "pytest>=8.0", "ruff>=0.8"]
+
+[dependency-groups]
+dev = [
+    "black>=24.0",
+    "pytest>=8.0",
+    "ruff>=0.8",
+]

trigv-1.0.0/src/trigv/__init__.py

@@ -0,0 +1,57 @@
+"""Official Trigv SDK for Python."""
+
+from trigv.client import Trigv
+from trigv.constants import (
+    DEFAULT_BASE_URL,
+    DELIVERY_URGENCIES,
+    LEVELS,
+    VERSION,
+)
+from trigv.errors import (
+    ApiError,
+    AuthenticationError,
+    AuthorizationError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    TimeoutError,
+    TrigvError,
+    ValidationError,
+)
+from trigv.types import (
+    ConnectionApiKey,
+    ConnectionResult,
+    ConnectionWorkspace,
+    DeliveryUrgency,
+    Event,
+    NotificationLevel,
+    SendEventParams,
+    SendEventResult,
+)
+
+__all__ = [
+    "ApiError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "ConnectionApiKey",
+    "ConnectionResult",
+    "ConnectionWorkspace",
+    "DEFAULT_BASE_URL",
+    "DELIVERY_URGENCIES",
+    "DeliveryUrgency",
+    "Event",
+    "LEVELS",
+    "NetworkError",
+    "NotFoundError",
+    "NotificationLevel",
+    "RateLimitError",
+    "SendEventParams",
+    "SendEventResult",
+    "TimeoutError",
+    "Trigv",
+    "TrigvError",
+    "ValidationError",
+    "VERSION",
+]
+
+__version__ = VERSION

trigv-1.0.0/src/trigv/client.py

@@ -0,0 +1,298 @@
+"""HTTP client for the Trigv ingest API."""
+
+from __future__ import annotations
+
+import builtins
+import json
+import os
+import random
+import socket
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable, Mapping
+from typing import Any, TypeVar
+
+from trigv.constants import DEFAULT_BASE_URL, DEFAULT_TIMEOUT_SECONDS, MAX_RETRIES, VERSION
+from trigv.errors import (
+    ApiError,
+    AuthenticationError,
+    AuthorizationError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    TrigvError,
+    ValidationError,
+    is_monthly_limit_message,
+)
+from trigv.errors import (
+    TimeoutError as TrigvTimeoutError,
+)
+from trigv.types import (
+    ConnectionApiKey,
+    ConnectionResult,
+    ConnectionWorkspace,
+    Event,
+    HttpResponse,
+    SendEventParams,
+    SendEventResult,
+)
+from trigv.validation import validate_send_event_params
+
+T = TypeVar("T")
+
+HttpTransport = Callable[[str, str, dict[str, str], bytes | None, float], HttpResponse]
+
+_RETRYABLE_STATUSES = {429, 502, 503, 504}
+
+
+def _parse_json(text: str) -> dict[str, Any] | None:
+    if not text:
+        return None
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError:
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def _error_from_response(
+    status: int,
+    body: dict[str, Any] | None,
+    headers: dict[str, str] | None = None,
+) -> None:
+    message = str(body.get("message")) if body and body.get("message") is not None else None
+    if not message:
+        message = f"Trigv API returned HTTP {status}"
+
+    if status == 401:
+        raise AuthenticationError(message)
+    if status == 403:
+        raise AuthorizationError(message)
+    if status == 404:
+        raise NotFoundError(message)
+    if status == 422:
+        errors = body.get("errors") if body else None
+        if not isinstance(errors, dict):
+            errors = {}
+        normalized: dict[str, list[str]] = {}
+        for field, messages in errors.items():
+            if isinstance(messages, list):
+                normalized[str(field)] = [str(item) for item in messages]
+            else:
+                normalized[str(field)] = [str(messages)]
+        raise ValidationError(message, normalized)
+    if status == 429:
+        from trigv.retry import parse_retry_after_header
+
+        retry_after = None
+        if headers is not None:
+            retry_after = parse_retry_after_header(headers.get("retry-after"))
+        raise RateLimitError(message, not is_monthly_limit_message(message), retry_after)
+    raise ApiError(message, status, body)
+
+
+def _is_retryable_status(status: int) -> bool:
+    return status in _RETRYABLE_STATUSES
+
+
+def _jitter(max_ms: int) -> float:
+    return random.randint(0, max_ms) / 1000.0
+
+
+def _default_transport(
+    method: str,
+    url: str,
+    headers: dict[str, str],
+    body: bytes | None,
+    timeout: float,
+) -> HttpResponse:
+    request = urllib.request.Request(url=url, data=body, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            response_body = response.read().decode("utf-8")
+            response_headers = {key.lower(): value for key, value in response.headers.items()}
+            return HttpResponse(
+                status=response.status,
+                body=response_body,
+                headers=response_headers,
+            )
+    except urllib.error.HTTPError as exc:
+        response_body = exc.read().decode("utf-8", errors="replace")
+        response_headers = {key.lower(): value for key, value in exc.headers.items()}
+        return HttpResponse(status=exc.code, body=response_body, headers=response_headers)
+    except (builtins.TimeoutError, socket.timeout) as exc:  # noqa: UP041
+        raise TrigvTimeoutError() from exc
+    except urllib.error.URLError as exc:
+        if isinstance(exc.reason, (builtins.TimeoutError, socket.timeout)):  # noqa: UP041
+            raise TrigvTimeoutError() from exc
+        message = str(exc.reason) if exc.reason else "Network request failed"
+        raise NetworkError(message, exc) from exc
+
+
+class Trigv:
+    """Trigv workspace ingest client."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        transport: HttpTransport | None = None,
+    ) -> None:
+        resolved_key = api_key if api_key is not None else os.environ.get("TRIGV_API_KEY")
+        if not resolved_key or not resolved_key.strip():
+            raise ValidationError("api_key is required (or set TRIGV_API_KEY)")
+
+        if max_retries is not None and max_retries < 0:
+            raise ValidationError(
+                "max_retries must be zero or greater",
+                {"max_retries": ["max_retries must be zero or greater"]},
+            )
+
+        if timeout is not None and timeout <= 0:
+            raise ValidationError(
+                "timeout must be greater than zero",
+                {"timeout": ["timeout must be greater than zero"]},
+            )
+
+        self._api_key = resolved_key.strip()
+        self._base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout if timeout is not None else DEFAULT_TIMEOUT_SECONDS
+        self._max_retries = max_retries if max_retries is not None else MAX_RETRIES
+        self._transport = transport or _default_transport
+
+    @property
+    def user_agent(self) -> str:
+        return f"trigv-python/{VERSION}"
+
+    def send_event(self, params: SendEventParams | Mapping[str, object]) -> SendEventResult:
+        body = validate_send_event_params(params)
+        has_idempotency = bool(body.get("idempotency_key"))
+
+        def parse_success(status: int, parsed: dict[str, Any] | None) -> SendEventResult:
+            if status in (200, 202) and parsed and isinstance(parsed.get("event"), dict):
+                return SendEventResult(
+                    event=Event.from_dict(parsed["event"]),
+                    duplicate=status == 200,
+                )
+            _error_from_response(status, parsed)
+            raise AssertionError("unreachable")
+
+        return self._request_with_retry(
+            method="POST",
+            path="/v1/events",
+            body=body,
+            allow_retry=has_idempotency,
+            parse_success=parse_success,
+        )
+
+    def verify_connection(self) -> ConnectionResult:
+        def parse_success(status: int, parsed: dict[str, Any] | None) -> ConnectionResult:
+            if (
+                status == 200
+                and parsed
+                and isinstance(parsed.get("workspace"), dict)
+                and isinstance(parsed.get("api_key"), dict)
+            ):
+                return ConnectionResult(
+                    workspace=ConnectionWorkspace.from_dict(parsed["workspace"]),
+                    api_key=ConnectionApiKey.from_dict(parsed["api_key"]),
+                )
+            _error_from_response(status, parsed)
+            raise AssertionError("unreachable")
+
+        return self._request_with_retry(
+            method="GET",
+            path="/v1/connection",
+            body=None,
+            allow_retry=True,
+            parse_success=parse_success,
+        )
+
+    def _request_with_retry(
+        self,
+        *,
+        method: str,
+        path: str,
+        body: dict[str, str] | None,
+        allow_retry: bool,
+        parse_success: Callable[[int, dict[str, Any] | None], T],
+    ) -> T:
+        last_error: BaseException | None = None
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                return self._request_once(
+                    method=method,
+                    path=path,
+                    body=body,
+                    parse_success=parse_success,
+                )
+            except TrigvError as error:
+                last_error = error
+
+                if not allow_retry or attempt >= self._max_retries:
+                    raise
+
+                if isinstance(
+                    error,
+                    (ValidationError, AuthenticationError, AuthorizationError, NotFoundError),
+                ):
+                    raise
+
+                if isinstance(error, RateLimitError) and not error.retryable:
+                    raise
+
+                if isinstance(error, ApiError) and not _is_retryable_status(error.status_code):
+                    raise
+
+                if not isinstance(
+                    error,
+                    (NetworkError, TrigvTimeoutError, RateLimitError, ApiError),
+                ):
+                    raise
+
+                backoff = 0.5 * (2**attempt) + _jitter(250)
+                if isinstance(error, RateLimitError) and error.retry_after_seconds is not None:
+                    backoff = error.retry_after_seconds
+                time.sleep(min(backoff, self._timeout))
+
+        assert last_error is not None
+        raise last_error
+
+    def _request_once(
+        self,
+        *,
+        method: str,
+        path: str,
+        body: dict[str, str] | None,
+        parse_success: Callable[[int, dict[str, Any] | None], T],
+    ) -> T:
+        url = f"{self._base_url}{path}"
+        headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": self.user_agent,
+        }
+        payload = json.dumps(body).encode("utf-8") if body is not None else None
+
+        try:
+            response = self._transport(method, url, headers, payload, self._timeout)
+        except TrigvTimeoutError:
+            raise
+        except NetworkError:
+            raise
+        except Exception as exc:
+            raise NetworkError(str(exc), exc) from exc
+
+        parsed = _parse_json(response.body)
+
+        if 200 <= response.status < 300:
+            return parse_success(response.status, parsed)
+
+        _error_from_response(response.status, parsed, response.headers)
+        raise AssertionError("unreachable")

trigv-1.0.0/src/trigv/constants.py

@@ -0,0 +1,25 @@
+"""Shared constants for the Trigv Python SDK."""
+
+VERSION = "1.0.0"
+
+DEFAULT_BASE_URL = "https://api.trigv.com/api"
+
+DEFAULT_TIMEOUT_SECONDS = 30.0
+
+MAX_RETRIES = 2
+
+LEVELS = ("info", "success", "warning", "error")
+
+DELIVERY_URGENCIES = ("standard", "time_sensitive")
+
+FIELD_MAX_LENGTHS = {
+    "channel": 120,
+    "title": 255,
+    "description": 1000,
+    "image_url": 2048,
+    "url": 2048,
+    "event_type": 120,
+    "idempotency_key": 190,
+}
+
+PROHIBITED_FIELDS = ("api_key", "icon")

trigv-1.0.0/src/trigv/errors.py

@@ -0,0 +1,87 @@
+"""Exception types for the Trigv Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class TrigvError(Exception):
+    """Base exception for all Trigv SDK errors."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class ValidationError(TrigvError):
+    """Client-side or HTTP 422 validation failure."""
+
+    def __init__(self, message: str, errors: dict[str, list[str]] | None = None) -> None:
+        super().__init__(message)
+        self.errors: dict[str, list[str]] = errors or {}
+
+
+class AuthenticationError(TrigvError):
+    """HTTP 401 — invalid or missing API key."""
+
+    status_code = 401
+
+
+class AuthorizationError(TrigvError):
+    """HTTP 403 — revoked, expired, or insufficient scope."""
+
+    status_code = 403
+
+
+class NotFoundError(TrigvError):
+    """HTTP 404 — channel or resource not found."""
+
+    status_code = 404
+
+
+class RateLimitError(TrigvError):
+    """HTTP 429 — per-minute burst or monthly workspace cap."""
+
+    status_code = 429
+
+    def __init__(
+        self,
+        message: str,
+        retryable: bool = True,
+        retry_after_seconds: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.retryable = retryable
+        self.retry_after_seconds = retry_after_seconds
+
+
+class ApiError(TrigvError):
+    """Other HTTP 4xx/5xx responses."""
+
+    def __init__(self, message: str, status_code: int, body: Any = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+class NetworkError(TrigvError):
+    """DNS, connection reset, or other transport failure."""
+
+    def __init__(self, message: str, cause: BaseException | None = None) -> None:
+        super().__init__(message)
+        self.cause = cause
+
+
+class TimeoutError(TrigvError):
+    """Request exceeded the configured timeout."""
+
+    def __init__(self, message: str = "Request timed out") -> None:
+        super().__init__(message)
+
+
+def is_monthly_limit_message(message: str) -> bool:
+    """Return True when a 429 message indicates the monthly workspace cap."""
+    return "Monthly event limit" in message

trigv-1.0.0/src/trigv/retry.py

@@ -0,0 +1,33 @@
+"""Retry helpers for Trigv HTTP clients."""
+
+from __future__ import annotations
+
+import time
+from datetime import timezone
+from email.utils import parsedate_to_datetime
+
+
+def parse_retry_after_header(value: str | None, now: float | None = None) -> float | None:
+    """Parse Retry-After (integer seconds or HTTP-date). Returns wait seconds when valid."""
+    if not value or not value.strip():
+        return None
+
+    trimmed = value.strip()
+
+    if trimmed.isdigit():
+        seconds = int(trimmed)
+        if seconds < 0:
+            return None
+        return float(seconds)
+
+    try:
+        retry_at = parsedate_to_datetime(trimmed)
+        if retry_at.tzinfo is None:
+            retry_at = retry_at.replace(tzinfo=timezone.utc)
+        current = time.time() if now is None else now
+        wait = retry_at.timestamp() - current
+        if wait < 0:
+            return None
+        return wait
+    except (TypeError, ValueError, OverflowError):
+        return None

trigv-1.0.0/src/trigv/types.py

@@ -0,0 +1,96 @@
+"""Type definitions for the Trigv Python SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, TypedDict
+
+NotificationLevel = Literal["info", "success", "warning", "error"]
+DeliveryUrgency = Literal["standard", "time_sensitive"]
+
+
+class SendEventParams(TypedDict, total=False):
+    """Parameters for :meth:`Trigv.send_event`."""
+
+    channel: str
+    title: str
+    description: str
+    image_url: str
+    url: str
+    level: NotificationLevel
+    delivery_urgency: DeliveryUrgency
+    event_type: str
+    idempotency_key: str
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    """Event metadata returned by the ingest API."""
+
+    public_id: str
+    event_uuid: str
+    status: str
+    level: str
+    event_type: str | None
+    target_device_count: int
+    received_at: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> Event:
+        return cls(
+            public_id=str(data["public_id"]),
+            event_uuid=str(data["event_uuid"]),
+            status=str(data["status"]),
+            level=str(data["level"]),
+            event_type=data.get("event_type") if data.get("event_type") is not None else None,
+            target_device_count=int(data["target_device_count"]),  # type: ignore[arg-type]
+            received_at=str(data["received_at"]),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class SendEventResult:
+    """Result of a successful event ingest."""
+
+    event: Event
+    duplicate: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectionWorkspace:
+    public_id: str
+    name: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> ConnectionWorkspace:
+        return cls(public_id=str(data["public_id"]), name=str(data["name"]))
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectionApiKey:
+    public_id: str
+    name: str
+    prefix: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> ConnectionApiKey:
+        return cls(
+            public_id=str(data["public_id"]),
+            name=str(data["name"]),
+            prefix=str(data["prefix"]),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectionResult:
+    workspace: ConnectionWorkspace
+    api_key: ConnectionApiKey
+
+
+@dataclass(frozen=True, slots=True)
+class HttpResponse:
+    """HTTP response returned by the transport layer."""
+
+    status: int
+    body: str
+    headers: dict[str, str]

trigv-1.0.0/src/trigv/validation.py

@@ -0,0 +1,99 @@
+"""Client-side validation for event parameters."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from trigv.constants import (
+    DELIVERY_URGENCIES,
+    FIELD_MAX_LENGTHS,
+    LEVELS,
+    PROHIBITED_FIELDS,
+)
+from trigv.errors import ValidationError
+from trigv.types import SendEventParams
+
+
+def _trim(value: str | None) -> str | None:
+    if value is None:
+        return None
+    trimmed = value.strip()
+    return trimmed if trimmed else None
+
+
+def _assert_max_length(field: str, value: str, maximum: int) -> None:
+    if len(value) > maximum:
+        message = f"{field} must be at most {maximum} characters"
+        raise ValidationError(message, {field: [message]})
+
+
+def _assert_enum(field: str, value: str, allowed: tuple[str, ...]) -> None:
+    if value not in allowed:
+        message = f"{field} must be one of: {', '.join(allowed)}"
+        raise ValidationError(message, {field: [message]})
+
+
+def validate_send_event_params(params: SendEventParams | Mapping[str, object]) -> dict[str, str]:
+    """Validate and normalize send-event parameters for the JSON request body."""
+    raw = dict(params)
+
+    for prohibited in PROHIBITED_FIELDS:
+        if prohibited in raw:
+            raise ValidationError(
+                f'Field "{prohibited}" is not allowed',
+                {prohibited: [f"The {prohibited} field is prohibited"]},
+            )
+
+    channel = _trim(str(raw.get("channel", "")) if raw.get("channel") is not None else None)
+    title = _trim(str(raw.get("title", "")) if raw.get("title") is not None else None)
+
+    if not channel:
+        raise ValidationError("channel is required", {"channel": ["channel is required"]})
+    if not title:
+        raise ValidationError("title is required", {"title": ["title is required"]})
+
+    _assert_max_length("channel", channel, FIELD_MAX_LENGTHS["channel"])
+    _assert_max_length("title", title, FIELD_MAX_LENGTHS["title"])
+
+    body: dict[str, str] = {"channel": channel, "title": title}
+
+    description = _trim(str(raw["description"]) if raw.get("description") is not None else None)
+    if description is not None:
+        _assert_max_length("description", description, FIELD_MAX_LENGTHS["description"])
+        body["description"] = description
+
+    image_url = _trim(str(raw["image_url"]) if raw.get("image_url") is not None else None)
+    if image_url is not None:
+        _assert_max_length("image_url", image_url, FIELD_MAX_LENGTHS["image_url"])
+        body["image_url"] = image_url
+
+    url = _trim(str(raw["url"]) if raw.get("url") is not None else None)
+    if url is not None:
+        _assert_max_length("url", url, FIELD_MAX_LENGTHS["url"])
+        body["url"] = url
+
+    level = _trim(str(raw["level"]) if raw.get("level") is not None else None)
+    if level is not None:
+        _assert_enum("level", level, LEVELS)
+        body["level"] = level
+
+    delivery_urgency = _trim(
+        str(raw["delivery_urgency"]) if raw.get("delivery_urgency") is not None else None
+    )
+    if delivery_urgency is not None:
+        _assert_enum("delivery_urgency", delivery_urgency, DELIVERY_URGENCIES)
+        body["delivery_urgency"] = delivery_urgency
+
+    event_type = _trim(str(raw["event_type"]) if raw.get("event_type") is not None else None)
+    if event_type is not None:
+        _assert_max_length("event_type", event_type, FIELD_MAX_LENGTHS["event_type"])
+        body["event_type"] = event_type
+
+    idempotency_key = _trim(
+        str(raw["idempotency_key"]) if raw.get("idempotency_key") is not None else None
+    )
+    if idempotency_key is not None:
+        _assert_max_length("idempotency_key", idempotency_key, FIELD_MAX_LENGTHS["idempotency_key"])
+        body["idempotency_key"] = idempotency_key
+
+    return body