beaconbox 0.1.0__tar.gz

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

@@ -0,0 +1,45 @@
+name: CI
+
+# Unit tests only. The live suite is gated on BEACONBOX_LIVE_URL and skips itself here: it needs
+# a running BeaconBox, which is exercised in the private platform repository before a release is
+# cut.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      # The versions pyproject.toml declares support for. 3.10 is the floor and is listed first
+      # because it is the one that breaks: it is where `tomllib` is absent and where a 3.11+ only
+      # syntax would surface.
+      matrix:
+        python: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python }}
+        run: uv python install ${{ matrix.python }}
+
+      - name: Sync deps
+        run: uv sync --all-extras --dev
+
+      - name: Ruff
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Mypy
+        run: uv run mypy
+
+      - name: Pytest
+        run: uv run pytest -q

beaconbox-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,100 @@
+name: Publish to PyPI
+
+# Pushing a tag `vX.Y.Z` to this repository is what publishes a release.
+#
+# The distribution is `beaconbox`; the import name is `beaconbox` too.
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    name: Build + publish
+    runs-on: ubuntu-latest
+    permissions:
+      # PyPI trusted publishing (OIDC). No API token is stored anywhere: PyPI is configured to
+      # trust this workflow, in this repository, and mints a short-lived credential per run.
+      #
+      # For the FIRST release the project does not exist on PyPI yet, so there is nothing to
+      # attach a publisher to — configure a *pending* publisher first at
+      # https://pypi.org/manage/account/publishing/. Its **PyPI project name is the distribution
+      # name, `beaconbox`** — not `beaconbox-python`, which is this repository. Getting that wrong
+      # fails the upload with "invalid-publisher" *after* the tag is public, because PyPI looks
+      # for a publisher for the project being uploaded and finds none.
+      id-token: write
+      # Spelling `permissions` at all drops every default to `none`, so checkout's read has to be
+      # asked for back.
+      contents: read
+
+    # **Deliberately no `environment:`.** An environment is worth adding for a publish job — it is
+    # where a required reviewer would go — but it has to be added on both sides at once: PyPI
+    # matches the publisher on (project, repository, workflow, environment), so naming one here
+    # while the publisher says "(Any)" is a second thing to keep in step for no gain today.
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+
+      # The version is declared once, in `_version.py`, and `pyproject.toml` reads it through
+      # hatchling's `dynamic = ["version"]`. So this reads the module, NOT `project.version` —
+      # that key does not exist in this project and looking it up raises rather than comparing.
+      #
+      # The tag is checked against it because a tag is the only part of a release nobody
+      # validates by running it: the wheel would build and upload happily under a number that
+      # disagrees with what the client reports in its User-Agent.
+      - name: Verify the tag matches the package version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION="$(sed -n 's/^__version__ = "\(.*\)"/\1/p' src/beaconbox/_version.py)"
+          if [ -z "$PKG_VERSION" ]; then
+            echo "::error::could not read __version__ from src/beaconbox/_version.py"
+            exit 1
+          fi
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::tag $TAG_VERSION does not match __version__ $PKG_VERSION"
+            exit 1
+          fi
+          echo "publishing $PKG_VERSION"
+
+      - name: Sync deps
+        run: uv sync --all-extras --dev
+
+      # The gate runs here and not only on the pushing side, because this is the tree that gets
+      # uploaded. A tag can be pushed at any commit by anyone with write access.
+      - name: Test
+        run: uv run pytest -q
+
+      - name: Lint
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Types
+        run: uv run mypy
+
+      - name: Build
+        run: uv build
+
+      # `py.typed` reaching the wheel is the one packaging property that fails silently in a
+      # consumer's project: PEP 561 makes a type checker ignore every annotation in a package
+      # without it, with no error anywhere.
+      - name: Check the artefact
+        run: |
+          python - <<'PY'
+          import glob, sys, zipfile
+
+          wheel = glob.glob("dist/*.whl")[0]
+          names = zipfile.ZipFile(wheel).namelist()
+          if not any(n.endswith("beaconbox/py.typed") for n in names):
+              sys.exit(f"{wheel} ships no py.typed")
+          if any(n.startswith("tests/") for n in names):
+              sys.exit(f"{wheel} ships the test suite")
+          print(f"{wheel}: ok")
+          PY
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

beaconbox-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+
+# A lock file is for an application, not a library. This package is installed *next to* a
+# consumer's own dependencies and resolved against them, so a lock committed here pins nothing
+# for anybody who installs it — and hatchling puts it in the sdist, where it is noise. The PHP
+# SDK gitignores composer.lock for the same reason.
+#
+# `uv run` writes one as a side effect, so this line is what keeps it from being committed by
+# accident rather than on purpose. Tracking lock files for the SDKs would be a deliberate
+# decision for both of them, not one that arrives with a stray command.
+uv.lock

beaconbox-0.1.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0]
+
+### Added
+
+- `BeaconBox` and `AsyncBeaconBox` clients, with the same 18 operations and identical signatures.
+- Typed models for every response, with `py.typed`. Unknown fields remain available via `.raw`.
+- Cursor pagination via `messages.iterate()`, and `async for` on the async client.
+- Webhook signature verification via `beaconbox.webhooks.verify()`.
+- Automatic `Idempotency-Key` on every write, reused across the SDK's own retries. Override per
+  call with `idempotency_key=`.
+- Retries with exponential backoff and jitter on connection errors, 429 and 5xx. Configure with
+  `RetryPolicy`; `max_retries=0` disables them.
+- `Retry-After` honoured up to `RetryPolicy.max_retry_after` (30s). Beyond it, `RateLimitError` is
+  raised with `retry_after` set rather than retrying.
+- Skipped SMS and WhatsApp channels are reported on the result; they do not raise.
+- Configurable `base_url`, `timeout`, `retry_policy`, `verify`, `max_connections` and
+  `user_agent_suffix`. An `httpx` client can be injected via `http_client=` instead.
+- Opt-in logging on the `beaconbox` logger. Silent by default; the SDK configures nothing.
+- Plain `http` is refused except on localhost.
+- Redirects are not followed.
+- API keys, newly minted keys and webhook endpoint secrets are excluded from `repr()`.
+- Log records carry route templates (`/recipients/{email}/sms`), never interpolated paths.
+
+### Requirements
+
+- Python 3.10+
+- [httpx](https://www.python-httpx.org) `>=0.28.1,<1`
+
+[0.1.0]: https://github.com/beaconbox-eu/beaconbox-python/releases/tag/v0.1.0

beaconbox-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+# Contributing
+
+This repository is a **read-only mirror**. It is published from the BeaconBox monorepo, and
+anything pushed here directly is overwritten by the next release.
+
+Bug reports and feature requests are welcome as issues. For a code change, open an issue first and
+we will apply it upstream with attribution.

beaconbox-0.1.0/LICENSE

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

beaconbox-0.1.0/PKG-INFO

@@ -0,0 +1,336 @@
+Metadata-Version: 2.5
+Name: beaconbox
+Version: 0.1.0
+Summary: Official Python SDK for BeaconBox, order updates your customers actually receive.
+Project-URL: Homepage, https://beaconbox.eu
+Project-URL: Documentation, https://docs.beaconbox.eu
+Project-URL: Source, https://github.com/beaconbox-eu/beaconbox-python
+Project-URL: Issues, https://github.com/beaconbox-eu/beaconbox-python/issues
+Author-email: BeaconBox <sdk@beaconbox.eu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: beaconbox,eu,notifications,sms,transactional,whatsapp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28.1
+Description-Content-Type: text/markdown
+
+# beaconbox
+
+Official Python SDK for [BeaconBox](https://beaconbox.eu), order updates your customers actually
+receive.
+
+```bash
+pip install beaconbox
+```
+
+Python 3.10+. One runtime dependency, [httpx](https://www.python-httpx.org), which is also the
+only HTTP library where the sync and the async client share an API, so this SDK's logic is
+written once rather than twice.
+
+## Push an update
+
+```python
+from beaconbox import BeaconBox
+
+client = BeaconBox()  # reads BEACONBOX_API_KEY
+
+result = client.messages.push(
+    recipient_email="buyer@example.com",
+    subject="Your order has shipped",
+    body="Tracking XY123456789EE. Estimated delivery Thursday.",
+    kind="updateable",
+)
+
+print(result.id)  # 3xg39cvt8a46
+```
+
+The customer gets an email whose link opens their inbox already signed in. No password, no
+account to create.
+
+Re-push the same `subject` with `kind="updateable"` to overwrite it in place, quietly. Add
+`notify=True` to force a nudge on an update, or `obsoletes=[...]` to grey out messages this one
+replaces.
+
+## Async
+
+Same client, same signatures, awaited. Nothing blocks the event loop, including retry backoff.
+
+```python
+from beaconbox import AsyncBeaconBox
+
+async with AsyncBeaconBox() as client:
+    result = await client.messages.push(
+        recipient_email="buyer@example.com",
+        subject="Your order has shipped",
+        body="Tracking XY123456789EE.",
+    )
+
+    async for message in client.messages.iterate(recipient_email="buyer@example.com"):
+        print(message.id, message.delivery.opened)
+```
+
+## Two things to know before anything else
+
+### 1. Read the response, not the status code
+
+A push returns **201 even when the SMS or WhatsApp message was not sent.** The update is already
+in the customer's inbox and the email nudge has gone, so a paid channel that could not send
+reports a reason and the request still succeeded.
+
+```python
+from beaconbox import SkipReason
+
+result = client.messages.push(
+    recipient_email="buyer@example.com",
+    recipient_phone="+37255550134",
+    subject="Your order has shipped",
+    body="Tracking XY123456789EE.",
+    channels=["sms"],
+)
+
+if result.sms and result.sms.skipped_reason == SkipReason.INSUFFICIENT_CREDIT:
+    # Top up, then: client.messages.resend_sms(result.id)
+    ...
+```
+
+**This SDK does not raise on a skip**, deliberately. Treating one as an error is what invites a
+retry, and a retry of a push that already succeeded is a second message to a real person.
+
+### 2. Idempotency is handled for you, and you can do better
+
+Every write carries an `Idempotency-Key`. This SDK generates one per call and **reuses it across
+its own retries**, so a connection that dies with the answer in flight cannot become a duplicate
+email and a duplicate charged SMS.
+
+Pass your own whenever you have a natural key:
+
+```python
+client.messages.push(..., idempotency_key="order-4711-shipped")
+```
+
+Then a retry from *anywhere*, your queue, a cron, a human clicking twice, collapses onto the same
+key rather than only the retries this SDK makes internally.
+
+## Everything else
+
+```python
+from beaconbox import MessagePush
+
+# Delivery status
+client.messages.get("3xg39cvt8a46")
+
+# Every message, following cursors. A generator, so a year of history is not held in memory
+for message in client.messages.iterate(recipient_email="buyer@example.com"):
+    ...
+
+# Take one back: withdrawn for the recipient, any queued nudge called off, no credit spent
+client.messages.retract("3xg39cvt8a46")
+
+# Up to 100 pushes. Always 200: read result.failed, not the status code
+result = client.messages.push_batch(
+    [
+        MessagePush(recipient_email="a@example.com", subject="Shipped", body="..."),
+        MessagePush(recipient_email="b@example.com", subject="Shipped", body="..."),
+    ]
+)
+for item in result.failures:
+    print(item.index, item.error_code)
+
+# Contact details. Reads are masked: a leaked key must not dump a phone book
+client.recipients.set_phone("buyer@example.com", "+37255550134")
+client.recipients.clear_phone("buyer@example.com")
+
+# The prepaid balance. One balance, shared by SMS and WhatsApp
+client.credits.balance()
+
+# Keys and webhook endpoints
+client.keys.create("orders service")
+client.webhook_endpoints.create("https://example.com/hooks")  # empty list means every event
+```
+
+### Pay only for the customers the email did not reach
+
+`escalate_if_unread_after_minutes` holds the paid channel back. The SMS is sent only if the
+recipient still has not opened the message after that long, and if they open it first, nothing is
+sent and nothing is charged.
+
+```python
+client.messages.push(
+    recipient_email="buyer@example.com",
+    recipient_phone="+37255550134",
+    subject="Action needed on your order",
+    body="We could not process your payment.",
+    channels=["sms"],
+    escalate_if_unread_after_minutes=120,
+)
+```
+
+### Erasing a recipient's WhatsApp history
+
+```python
+receipt = client.recipients.erase_whatsapp("buyer@example.com")
+
+# The half only you can finish: erased replies whose words may already be in *your* mailboxes.
+yours = receipt.replies_a_forward_email_may_have_carried
+```
+
+## Verifying webhooks
+
+```python
+import os
+from beaconbox import WebhookVerificationError, WebhookEventType, webhooks
+
+
+@app.post("/hooks/beaconbox")
+async def hook(request):
+    try:
+        event = webhooks.verify(
+            await request.body(),  # the RAW body, byte for byte
+            request.headers["X-BeaconBox-Signature"],
+            os.environ["BEACONBOX_WEBHOOK_SECRET"],
+        )
+    except WebhookVerificationError:
+        return Response(status_code=400)
+
+    if event.type == WebhookEventType.MESSAGE_BOUNCED:
+        ...
+    return {"ok": True}
+```
+
+**Pass the raw body.** Decoding to a dict and re-encoding changes the bytes over key order and
+whitespace, and the signature stops matching, in production, on a payload shaped slightly
+differently from the one you tested with. The helper also checks the timestamp (which is signed,
+so a captured delivery cannot be replayed) and compares in constant time.
+
+Deliveries are **retried**, so the same `event.id` can arrive twice. Deduplicate on it.
+
+## Errors
+
+Everything inherits from `beaconbox.BeaconBoxError`.
+
+| Exception | When |
+| --- | --- |
+| `AuthenticationError` | 401, key missing, malformed or revoked |
+| `PermissionDeniedError` | 403 |
+| `InvalidRequestError` | 422, a malformed field, or a reused idempotency key with a different body |
+| `ResourceMissingError` | 404, no such id. Also what another business's id looks like, deliberately |
+| `ConflictError` | 409, already sent, or an identical request still in flight |
+| `RateLimitError` | 429, after the SDK has already retried |
+| `ServerError` | 5xx, after the SDK has already retried |
+| `APIConnectionError` | no answer at all. **Not** proof the work did not happen |
+| `WebhookVerificationError` | a delivery could not be proven to be ours |
+
+Branch on `error.error_code` (a stable dotted string such as `message.not_found`), not on the
+message text.
+
+## Configuration
+
+```python
+from beaconbox import BeaconBox, RetryPolicy
+
+client = BeaconBox(
+    api_key="bbx_live_...",  # or $BEACONBOX_API_KEY
+    base_url="https://api.beaconbox.eu",  # or $BEACONBOX_BASE_URL
+    timeout=30.0,
+    retry_policy=RetryPolicy(max_retries=2),
+    max_connections=20,
+    user_agent_suffix="acme-orders/2.1",
+)
+```
+
+Reuse one client: it holds a connection pool, and it is safe to share between threads. Close it,
+or use it as a context manager.
+
+Inside a job runner that already retries, pass `RetryPolicy(max_retries=0)` so the two schedules
+do not multiply.
+
+### Backpressure
+
+A connection failure, a 429 and a 5xx are retried; a 4xx is not, because sending the same wrong
+request again asks the same question. Backoff is exponential with full jitter, since the failure
+being absorbed is synchronised across every worker you run.
+
+**A `Retry-After` is honoured in full, not shortened to the backoff cap.** It is the server's own
+answer to when it will be ready, and retrying earlier only earns a second 429. Jitter is added *on
+top* of it rather than sampled from within it — the herd is at its worst here, because every worker
+that hit the same 429 was handed the same number.
+
+If the server asks for longer than `RetryPolicy.max_retry_after` (30s by default), the SDK **stops
+rather than retrying early** and raises `RateLimitError` with `retry_after` set. Blocking for the
+cap and being refused anyway helps nobody; the number is what you need to schedule a real retry.
+
+### Concurrency
+
+`max_connections` is a ceiling, and exceeding it does not look like one: the overflow queues for a
+free connection, and a queue wait that outlives the pool timeout surfaces as `APIConnectionError`
+rather than as anything mentioning a pool. If you fan out more concurrent calls than the ceiling —
+`asyncio.gather` over a few hundred pushes makes that easy — raise it to match.
+
+## Logging
+
+Standard library `logging`, under the `beaconbox` logger, and **silent until you ask**. The SDK
+attaches a `NullHandler` and configures nothing else: no `basicConfig`, no handlers, no level on
+the root logger.
+
+```python
+import logging
+
+logging.getLogger("beaconbox").setLevel(logging.DEBUG)
+```
+
+| Level | What |
+| --- | --- |
+| `DEBUG` | every request and response, with status and elapsed time |
+| `WARNING` | a retry (with reason and backoff), and giving up after the last one |
+
+Nothing is emitted at `INFO` or above in normal operation, so a `WARNING` from this SDK always
+means something went wrong.
+
+Each record carries a `beaconbox` attribute with structured fields (`route`, `attempt`,
+`status_code`, `elapsed_ms`, `idempotency_key`) for a JSON formatter.
+
+**Nothing sensitive is ever logged.** Not the API key or any header, not request or response
+bodies, not the query string, and not the interpolated URL path. A route template is logged
+instead, so `/recipients/buyer@example.com/sms` appears as `/recipients/{email}/sms`. The fields
+are an allow-list rather than a redaction pass, because redaction is a list of things somebody
+remembered to hide and the field added next year is not on it.
+
+### Security defaults you cannot accidentally lose
+
+- **Plain `http` is refused** for anything but localhost, so a misconfigured `base_url` cannot put
+  your API key on the wire in clear.
+- **Redirects are never followed.** httpx would re-send the `Authorization` header to wherever a
+  redirect points.
+- The key is never in a `repr`, and `NewApiKey.__repr__` redacts the minted key.
+- Webhook signatures are compared in constant time, over a signed timestamp.
+
+Need a corporate CA bundle? Pass `verify=` a path or an `ssl.SSLContext`. Need a proxy or custom
+instrumentation? Pass your own `http_client=httpx.Client(...)`, and then you own closing it.
+
+`timeout` and `verify` are **refused** alongside `http_client`, rather than silently ignored: they
+are settings on the client you supplied, and accepting them while doing nothing is how somebody
+discovers during an incident that the timeout they set was never applied.
+
+## Development
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+pytest            # hermetic, no network
+mypy src tests
+ruff check .
+```
+
+The live suite runs against a real BeaconBox. See [`tests/live/README.md`](tests/live/README.md).
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).
+
+BeaconBox is a product of BloomHarbor OÜ, a company registered in Estonia.