messagebird-sdk 0.1.0__tar.gz

messagebird_sdk-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

messagebird_sdk-0.1.0/LICENSE

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

messagebird_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: messagebird-sdk
+Version: 0.1.0
+Summary: The official Python SDK for the Bird email platform.
+Project-URL: Homepage, https://github.com/messagebird/bird-sdk-python#readme
+Project-URL: Repository, https://github.com/messagebird/bird-sdk-python.git
+Project-URL: Issues, https://github.com/messagebird/bird-sdk-python/issues
+Author: Bird
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,bird,email,sdk,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Bird Python SDK
+
+The official Python SDK for the [Bird](https://bird.com) email platform.
+
+> **Status:** in development. The PyPI distribution name is `messagebird-sdk`; the import package is `bird`.
+
+Requires Python 3.10+.
+
+## Install
+
+```bash
+pip install messagebird-sdk      # or: uv add messagebird-sdk
+```
+
+> This SDK is generated from Bird's public OpenAPI bundle inside Bird's internal monorepo, which is the single source of truth; this repository tracks tagged releases. Generation runs in the monorepo, so `make generate` won't work from a clone here — see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Quickstart
+
+```python
+from bird import Bird
+
+client = Bird(api_key="bk_eu1_...")  # region inferred from the key prefix
+
+message = client.email.send(
+    from_="hello@acme.com",
+    to=["customer@example.com"],
+    subject="Welcome to Acme",
+    html="<h1>Welcome</h1>",
+)
+print(message.id, message.status)
+```
+
+`api_key` and `base_url` fall back to the `BIRD_API_KEY` / `BIRD_BASE_URL` environment variables, so `Bird()` with no arguments works when they are set. Use the client as a context manager (`with Bird(...) as client:`) to close the underlying HTTP connection pool.
+
+## Email
+
+```python
+# Send
+message = client.email.send(from_="hi@acme.com", to=["c@x.com"], subject="Hi", text="hello")
+
+# Fetch
+message = client.email.get("em_01krd…")
+
+# List — iterating the page auto-paginates across cursors
+for message in client.email.list(status="delivered"):
+    print(message.id, message.status)
+```
+
+### Client-wide email defaults
+
+Defaults fill any unset `send` field; a per-send value always wins.
+
+```python
+client = Bird(
+    api_key="bk_eu1_...",
+    email_defaults={"from_": "noreply@acme.com", "reply_to": ["support@acme.com"]},
+)
+client.email.send(to=["c@x.com"], subject="Receipt", text="…")  # uses noreply@acme.com
+```
+
+## Webhooks
+
+```python
+from bird import Bird, WebhookVerificationError
+
+client = Bird(api_key="bk_eu1_...", webhook_secret="whsec_...")
+
+# In your web handler — pass the RAW request body (bytes) and the request headers
+try:
+    event = client.webhooks.unwrap(request.body, request.headers)
+except WebhookVerificationError:
+    return Response(status=400)
+
+if event.root.type == "email.delivered":
+    print("delivered:", event.root.data.message_id)
+```
+
+> Endpoint management (registering/listing webhook endpoints) is not in this release; it returns once the delivery substrate stabilises.
+
+## Errors
+
+Every failure raises a typed exception rooted at `BirdError`. `APIError` covers anything that goes wrong issuing a request — including transport failures — so a single `except APIError` is enough; `APIStatusError` carries the HTTP `status_code`.
+
+```python
+from bird import APIStatusError, RateLimitError, ValidationError
+
+try:
+    client.email.send(from_="hi@acme.com", to=["c@x.com"], subject="Hi", text="…")
+except RateLimitError as err:
+    retry_in = err.retry_after          # seconds, parsed from Retry-After
+except ValidationError as err:
+    print(err.status_code, err.details) # 422 + per-field detail
+except APIStatusError as err:
+    print(err.status_code, err.code, err.request_id)
+```
+
+Transient failures (timeouts, 429, 5xx) retry automatically with jittered backoff that honors `Retry-After`; a mutation reuses one idempotency key across attempts, so a retried write never double-applies.
+
+## Raw response
+
+Reach the status, headers, and `request_id` alongside the parsed model:
+
+```python
+raw = client.email.with_raw_response.send(from_="hi@acme.com", to=["c@x.com"], subject="Hi", text="…")
+print(raw.status_code, raw.request_id)
+message = raw.parse()
+```
+
+## Async
+
+`AsyncBird` mirrors `Bird` method-for-method — `await` each call and `async for` over a list:
+
+```python
+import asyncio
+from bird import AsyncBird
+
+async def main() -> None:
+    async with AsyncBird(api_key="bk_eu1_...") as client:
+        await client.email.send(from_="hi@acme.com", to=["c@x.com"], subject="Hi", text="hello")
+        async for message in client.email.list(status="delivered"):
+            print(message.id)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+| Option                   | Description                                                                    |
+| ------------------------ | ------------------------------------------------------------------------------ |
+| `api_key`                | API key; falls back to `BIRD_API_KEY`.                                         |
+| `region` / `base_url`    | Region (or explicit base URL); falls back to the key prefix / `BIRD_BASE_URL`. |
+| `timeout`, `max_retries` | Request timeout and retry budget; overridable per call via `options`.          |
+| `webhook_secret`         | Signing secret for `webhooks.unwrap`.                                          |
+| `email_defaults`         | Client-wide `send` defaults.                                                   |
+| `http_client`            | Inject your own `httpx.Client` / `AsyncClient`.                                |
+
+`client.with_options(...)` derives a new client (reusing the connection pool); every method also takes a trailing `options` for per-call `timeout` / `max_retries` / `idempotency_key` / `extra_headers`.
+
+## Escape hatch
+
+Any endpoint outside the typed surface is reachable through the verb methods, with the same auth, retries, and idempotency:
+
+```python
+from bird import EmailMessage
+
+message = client.get("/v1/email/messages/em_01krd…", cast_to=EmailMessage)
+client.post("/v1/some/new/endpoint", body={"key": "value"})
+```
+
+## Design
+
+The wire models are generated from the OpenAPI spec into `bird._generated`; this package is the hand-written idiomatic layer on top.

messagebird_sdk-0.1.0/README.md

@@ -0,0 +1,152 @@
+# Bird Python SDK
+
+The official Python SDK for the [Bird](https://bird.com) email platform.
+
+> **Status:** in development. The PyPI distribution name is `messagebird-sdk`; the import package is `bird`.
+
+Requires Python 3.10+.
+
+## Install
+
+```bash
+pip install messagebird-sdk      # or: uv add messagebird-sdk
+```
+
+> This SDK is generated from Bird's public OpenAPI bundle inside Bird's internal monorepo, which is the single source of truth; this repository tracks tagged releases. Generation runs in the monorepo, so `make generate` won't work from a clone here — see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Quickstart
+
+```python
+from bird import Bird
+
+client = Bird(api_key="bk_eu1_...")  # region inferred from the key prefix
+
+message = client.email.send(
+    from_="hello@acme.com",
+    to=["customer@example.com"],
+    subject="Welcome to Acme",
+    html="<h1>Welcome</h1>",
+)
+print(message.id, message.status)
+```
+
+`api_key` and `base_url` fall back to the `BIRD_API_KEY` / `BIRD_BASE_URL` environment variables, so `Bird()` with no arguments works when they are set. Use the client as a context manager (`with Bird(...) as client:`) to close the underlying HTTP connection pool.
+
+## Email
+
+```python
+# Send
+message = client.email.send(from_="hi@acme.com", to=["c@x.com"], subject="Hi", text="hello")
+
+# Fetch
+message = client.email.get("em_01krd…")
+
+# List — iterating the page auto-paginates across cursors
+for message in client.email.list(status="delivered"):
+    print(message.id, message.status)
+```
+
+### Client-wide email defaults
+
+Defaults fill any unset `send` field; a per-send value always wins.
+
+```python
+client = Bird(
+    api_key="bk_eu1_...",
+    email_defaults={"from_": "noreply@acme.com", "reply_to": ["support@acme.com"]},
+)
+client.email.send(to=["c@x.com"], subject="Receipt", text="…")  # uses noreply@acme.com
+```
+
+## Webhooks
+
+```python
+from bird import Bird, WebhookVerificationError
+
+client = Bird(api_key="bk_eu1_...", webhook_secret="whsec_...")
+
+# In your web handler — pass the RAW request body (bytes) and the request headers
+try:
+    event = client.webhooks.unwrap(request.body, request.headers)
+except WebhookVerificationError:
+    return Response(status=400)
+
+if event.root.type == "email.delivered":
+    print("delivered:", event.root.data.message_id)
+```
+
+> Endpoint management (registering/listing webhook endpoints) is not in this release; it returns once the delivery substrate stabilises.
+
+## Errors
+
+Every failure raises a typed exception rooted at `BirdError`. `APIError` covers anything that goes wrong issuing a request — including transport failures — so a single `except APIError` is enough; `APIStatusError` carries the HTTP `status_code`.
+
+```python
+from bird import APIStatusError, RateLimitError, ValidationError
+
+try:
+    client.email.send(from_="hi@acme.com", to=["c@x.com"], subject="Hi", text="…")
+except RateLimitError as err:
+    retry_in = err.retry_after          # seconds, parsed from Retry-After
+except ValidationError as err:
+    print(err.status_code, err.details) # 422 + per-field detail
+except APIStatusError as err:
+    print(err.status_code, err.code, err.request_id)
+```
+
+Transient failures (timeouts, 429, 5xx) retry automatically with jittered backoff that honors `Retry-After`; a mutation reuses one idempotency key across attempts, so a retried write never double-applies.
+
+## Raw response
+
+Reach the status, headers, and `request_id` alongside the parsed model:
+
+```python
+raw = client.email.with_raw_response.send(from_="hi@acme.com", to=["c@x.com"], subject="Hi", text="…")
+print(raw.status_code, raw.request_id)
+message = raw.parse()
+```
+
+## Async
+
+`AsyncBird` mirrors `Bird` method-for-method — `await` each call and `async for` over a list:
+
+```python
+import asyncio
+from bird import AsyncBird
+
+async def main() -> None:
+    async with AsyncBird(api_key="bk_eu1_...") as client:
+        await client.email.send(from_="hi@acme.com", to=["c@x.com"], subject="Hi", text="hello")
+        async for message in client.email.list(status="delivered"):
+            print(message.id)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+| Option                   | Description                                                                    |
+| ------------------------ | ------------------------------------------------------------------------------ |
+| `api_key`                | API key; falls back to `BIRD_API_KEY`.                                         |
+| `region` / `base_url`    | Region (or explicit base URL); falls back to the key prefix / `BIRD_BASE_URL`. |
+| `timeout`, `max_retries` | Request timeout and retry budget; overridable per call via `options`.          |
+| `webhook_secret`         | Signing secret for `webhooks.unwrap`.                                          |
+| `email_defaults`         | Client-wide `send` defaults.                                                   |
+| `http_client`            | Inject your own `httpx.Client` / `AsyncClient`.                                |
+
+`client.with_options(...)` derives a new client (reusing the connection pool); every method also takes a trailing `options` for per-call `timeout` / `max_retries` / `idempotency_key` / `extra_headers`.
+
+## Escape hatch
+
+Any endpoint outside the typed surface is reachable through the verb methods, with the same auth, retries, and idempotency:
+
+```python
+from bird import EmailMessage
+
+message = client.get("/v1/email/messages/em_01krd…", cast_to=EmailMessage)
+client.post("/v1/some/new/endpoint", body={"key": "value"})
+```
+
+## Design
+
+The wire models are generated from the OpenAPI spec into `bird._generated`; this package is the hand-written idiomatic layer on top.

messagebird_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+# Python SDK for the Bird email platform (ADR-0045).
+# Distribution name is `messagebird-sdk` on PyPI; the import package is `bird`.
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "messagebird-sdk"
+description = "The official Python SDK for the Bird email platform."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Bird" }]
+dynamic = ["version"]
+requires-python = ">=3.10"
+keywords = ["bird", "email", "webhooks", "sdk", "api"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Email",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.0",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/messagebird/bird-sdk-python#readme"
+Repository = "https://github.com/messagebird/bird-sdk-python.git"
+Issues = "https://github.com/messagebird/bird-sdk-python/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "respx>=0.21",
+    "ruff>=0.6",
+    "pyright>=1.1",
+    "pyyaml>=6",
+]
+
+[tool.hatch.version]
+path = "src/bird/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bird"]
+
+# Curate the sdist: ship the package, README, and LICENSE — not the internal agent
+# docs (AGENTS.md / CLAUDE.md), tests, or the generator script.
+[tool.hatch.build.targets.sdist]
+include = ["/src/bird", "/README.md", "/LICENSE"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+extend-exclude = ["src/bird/_generated.py"]  # generated; never hand-edited
+
+[tool.pyright]
+include = ["src", "tests", "examples"]
+ignore = ["src/bird/_generated.py"]  # generated; not held to the hand-written type bar
+pythonVersion = "3.10"

messagebird_sdk-0.1.0/src/bird/__init__.py

@@ -0,0 +1,65 @@
+"""The official Python SDK for the Bird email platform (ADR-0045).
+
+The wire models are generated from the OpenAPI spec into ``bird._generated`` and
+never hand-edited; this package is the hand-written, idiomatic layer on top — a
+synchronous ``Bird`` client and an asynchronous ``AsyncBird`` client, a typed
+exception hierarchy, safe retries, pagination, and webhook verification.
+"""
+
+from __future__ import annotations
+
+from bird._client import AsyncBird, Bird
+from bird._response import APIResponse
+from bird._types import (
+    Attachment,
+    EmailDefaults,
+    EmailListParams,
+    EmailSendParams,
+    RequestOptions,
+)
+from bird._generated import (
+    EmailMessage,
+    WebhookEvent,
+    WebhookEventType,
+)
+from bird._exceptions import (
+    APIConnectionError,
+    APIError,
+    APIStatusError,
+    APITimeoutError,
+    BirdError,
+    ErrorDetail,
+    ErrorType,
+    RateLimitError,
+    ValidationError,
+    WebhookVerificationError,
+)
+from bird.pagination import AsyncPage, SyncPage
+from bird._version import __version__
+
+__all__ = [
+    "Bird",
+    "AsyncBird",
+    "RequestOptions",
+    "EmailDefaults",
+    "Attachment",
+    "EmailSendParams",
+    "EmailListParams",
+    "APIResponse",
+    "SyncPage",
+    "AsyncPage",
+    "EmailMessage",
+    "WebhookEvent",
+    "WebhookEventType",
+    "BirdError",
+    "APIError",
+    "APIStatusError",
+    "RateLimitError",
+    "ValidationError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "WebhookVerificationError",
+    "ErrorDetail",
+    "ErrorType",
+    "__version__",
+]