sendstack 0.1.1__tar.gz → 0.1.3__tar.gz

{sendstack-0.1.1/src/sendstack.egg-info → sendstack-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sendstack
-Version: 0.1.1
+Version: 0.1.3
 Summary: Sync and async Python SDK for the SendStack email SaaS API.
 Author: Noria Labs
 License-Expression: MIT
@@ -123,11 +123,13 @@ decoded payload; on `AsyncSendstack` the same call returns a coroutine you
 
 ### Base URL
 
-The SDK defaults to `https://mailer.norialabs.com`, matching the current live
-API. Override it when you move to the SendStack domain:
+The SDK defaults to `https://sendstack.norialabs.com/api/v1` (the versioned API
+base). Override `base_url` to point at another environment — include the
+`/api/v1` version segment, since resource paths (e.g. `/emails`) are sent
+relative to whatever base you provide:
 
 ```python
-client = Sendstack(token, base_url="https://sendstack.norialabs.com")
+client = Sendstack(token, base_url="https://staging.norialabs.com/api/v1")
 ```
 
 ## Docs Split
@@ -139,7 +141,7 @@ The SaaS docs remain the canonical source for product/API behavior: account
 setup, API tokens, domain verification, DNS records, webhook event catalogs,
 deliverability concepts, provider behavior, dashboard workflows, and the raw
 HTTP API reference. Current live SaaS docs are at
-`https://mailer.norialabs.com/api/docs`.
+`https://sendstack.norialabs.com/api/docs`.
 
 ## Auth
 
@@ -162,7 +164,7 @@ request (sync or async callables both work):
 from sendstack import BearerAuthStrategy, Sendstack
 
 client = Sendstack(
-    base_url="https://mailer.norialabs.com",
+    base_url="https://sendstack.norialabs.com/api/v1",
     auth=BearerAuthStrategy(token=lambda context: get_fresh_token()),
 )
 ```
@@ -293,6 +295,45 @@ client.emails.send(
 )
 ```
 
+### Reading from files
+
+The API accepts strings (`html`/`text`) and base64 (`attachments`). These
+stdlib-only helpers do the read-and-encode step so you don't repeat it:
+
+```python
+from sendstack import (
+    Sendstack,
+    html_from_file,
+    text_from_file,
+    attachment_from_file,
+    attachment_from_bytes,
+)
+
+client.emails.send(
+    {
+        "from": "billing@example.com",
+        "to": "customer@example.com",
+        "subject": "Your invoice",
+        "html": html_from_file("templates/invoice.html"),
+        "text": text_from_file("templates/invoice.txt"),
+        "attachments": [
+            # From a path: filename defaults to the basename, content is base64-encoded.
+            attachment_from_file("invoices/2026-06.pdf", content_type="application/pdf"),
+            # From in-memory bytes (e.g. a generated PDF): filename is required.
+            attachment_from_bytes(generated_pdf, filename="summary.pdf", content_type="application/pdf"),
+        ],
+    }
+)
+```
+
+- `html_from_file(path, *, encoding="utf-8")` / `text_from_file(...)` — read a text
+  file into a string.
+- `attachment_from_file(path, *, filename=None, content_type=None, inline=None, content_id=None)`
+  — read a file into a base64 attachment `dict`. `filename` defaults to the basename.
+  `path` accepts a `str` or any `os.PathLike`.
+- `attachment_from_bytes(data, *, filename, content_type=None, inline=None, content_id=None)`
+  — encode in-memory `bytes`; `filename` is required.
+
 ## Domains
 
 ```python
@@ -510,6 +551,11 @@ Clients and errors:
 - `SendstackError`
 - `DEFAULT_BASE_URL`
 
+Filesystem helpers:
+
+- `html_from_file`, `text_from_file`
+- `attachment_from_file`, `attachment_from_bytes`
+
 Auth, options, and machinery:
 
 - `BearerAuthStrategy`, `HeadersAuthStrategy`, `SendstackAuthStrategy`

{sendstack-0.1.1 → sendstack-0.1.3}/README.md

@@ -96,11 +96,13 @@ decoded payload; on `AsyncSendstack` the same call returns a coroutine you
 
 ### Base URL
 
-The SDK defaults to `https://mailer.norialabs.com`, matching the current live
-API. Override it when you move to the SendStack domain:
+The SDK defaults to `https://sendstack.norialabs.com/api/v1` (the versioned API
+base). Override `base_url` to point at another environment — include the
+`/api/v1` version segment, since resource paths (e.g. `/emails`) are sent
+relative to whatever base you provide:
 
 ```python
-client = Sendstack(token, base_url="https://sendstack.norialabs.com")
+client = Sendstack(token, base_url="https://staging.norialabs.com/api/v1")
 ```
 
 ## Docs Split
@@ -112,7 +114,7 @@ The SaaS docs remain the canonical source for product/API behavior: account
 setup, API tokens, domain verification, DNS records, webhook event catalogs,
 deliverability concepts, provider behavior, dashboard workflows, and the raw
 HTTP API reference. Current live SaaS docs are at
-`https://mailer.norialabs.com/api/docs`.
+`https://sendstack.norialabs.com/api/docs`.
 
 ## Auth
 
@@ -135,7 +137,7 @@ request (sync or async callables both work):
 from sendstack import BearerAuthStrategy, Sendstack
 
 client = Sendstack(
-    base_url="https://mailer.norialabs.com",
+    base_url="https://sendstack.norialabs.com/api/v1",
     auth=BearerAuthStrategy(token=lambda context: get_fresh_token()),
 )
 ```
@@ -266,6 +268,45 @@ client.emails.send(
 )
 ```
 
+### Reading from files
+
+The API accepts strings (`html`/`text`) and base64 (`attachments`). These
+stdlib-only helpers do the read-and-encode step so you don't repeat it:
+
+```python
+from sendstack import (
+    Sendstack,
+    html_from_file,
+    text_from_file,
+    attachment_from_file,
+    attachment_from_bytes,
+)
+
+client.emails.send(
+    {
+        "from": "billing@example.com",
+        "to": "customer@example.com",
+        "subject": "Your invoice",
+        "html": html_from_file("templates/invoice.html"),
+        "text": text_from_file("templates/invoice.txt"),
+        "attachments": [
+            # From a path: filename defaults to the basename, content is base64-encoded.
+            attachment_from_file("invoices/2026-06.pdf", content_type="application/pdf"),
+            # From in-memory bytes (e.g. a generated PDF): filename is required.
+            attachment_from_bytes(generated_pdf, filename="summary.pdf", content_type="application/pdf"),
+        ],
+    }
+)
+```
+
+- `html_from_file(path, *, encoding="utf-8")` / `text_from_file(...)` — read a text
+  file into a string.
+- `attachment_from_file(path, *, filename=None, content_type=None, inline=None, content_id=None)`
+  — read a file into a base64 attachment `dict`. `filename` defaults to the basename.
+  `path` accepts a `str` or any `os.PathLike`.
+- `attachment_from_bytes(data, *, filename, content_type=None, inline=None, content_id=None)`
+  — encode in-memory `bytes`; `filename` is required.
+
 ## Domains
 
 ```python
@@ -483,6 +524,11 @@ Clients and errors:
 - `SendstackError`
 - `DEFAULT_BASE_URL`
 
+Filesystem helpers:
+
+- `html_from_file`, `text_from_file`
+- `attachment_from_file`, `attachment_from_bytes`
+
 Auth, options, and machinery:
 
 - `BearerAuthStrategy`, `HeadersAuthStrategy`, `SendstackAuthStrategy`

{sendstack-0.1.1 → sendstack-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sendstack"
-version = "0.1.1"
+version = "0.1.3"
 description = "Sync and async Python SDK for the SendStack email SaaS API."
 readme = "README.md"
 requires-python = ">=3.11"

{sendstack-0.1.1 → sendstack-0.1.3}/src/sendstack/__init__.py

@@ -20,6 +20,12 @@ from .errors import (
     is_success_envelope,
     to_sendstack_error,
 )
+from .files import (
+    attachment_from_bytes,
+    attachment_from_file,
+    html_from_file,
+    text_from_file,
+)
 from .types import (
     DEFAULT_BASE_URL,
     BearerAuthStrategy,
@@ -77,6 +83,11 @@ __all__ = [
     "is_error_envelope",
     "is_success_envelope",
     "to_sendstack_error",
+    # Filesystem helpers
+    "html_from_file",
+    "text_from_file",
+    "attachment_from_file",
+    "attachment_from_bytes",
     # Auth
     "BearerAuthStrategy",
     "HeadersAuthStrategy",

sendstack-0.1.3/src/sendstack/files.py

@@ -0,0 +1,83 @@
+"""Filesystem conveniences for building email payloads from local files.
+
+The SendStack API accepts strings (``html``/``text``) and base64 (``attachments``).
+These helpers do the read-and-encode step so callers don't repeat it. They use
+only the standard library, so they add no dependencies.
+
+The returned attachment ``dict`` uses the snake_case wire field names, so it can
+be dropped straight into ``emails.send({"attachments": [...]})``.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+from pathlib import Path
+from typing import Any
+
+PathLike = str | os.PathLike[str]
+
+__all__ = [
+    "html_from_file",
+    "text_from_file",
+    "attachment_from_file",
+    "attachment_from_bytes",
+]
+
+
+def html_from_file(path: PathLike, *, encoding: str = "utf-8") -> str:
+    """Read a text file (e.g. an HTML template) into a string for ``html``."""
+    return Path(path).read_text(encoding=encoding)
+
+
+def text_from_file(path: PathLike, *, encoding: str = "utf-8") -> str:
+    """Read a text file (e.g. a ``.txt`` body) into a string for ``text``."""
+    return Path(path).read_text(encoding=encoding)
+
+
+def attachment_from_file(
+    path: PathLike,
+    *,
+    filename: str | None = None,
+    content_type: str | None = None,
+    inline: bool | None = None,
+    content_id: str | None = None,
+) -> dict[str, Any]:
+    """Read a file from disk into a base64 attachment dict.
+
+    ``filename`` defaults to the file's basename. The result is ready to drop
+    into ``emails.send({"attachments": [...]})``.
+    """
+    data = Path(path).read_bytes()
+    return attachment_from_bytes(
+        data,
+        filename=filename if filename is not None else Path(os.fspath(path)).name,
+        content_type=content_type,
+        inline=inline,
+        content_id=content_id,
+    )
+
+
+def attachment_from_bytes(
+    data: bytes,
+    *,
+    filename: str,
+    content_type: str | None = None,
+    inline: bool | None = None,
+    content_id: str | None = None,
+) -> dict[str, Any]:
+    """Encode in-memory bytes (e.g. a generated PDF) into a base64 attachment dict.
+
+    ``filename`` is required since there is no path to derive one from.
+    """
+    attachment: dict[str, Any] = {
+        "filename": filename,
+        "content_base64": base64.b64encode(data).decode("ascii"),
+    }
+    if content_type is not None:
+        attachment["content_type"] = content_type
+    if inline is not None:
+        attachment["inline"] = inline
+    if content_id is not None:
+        attachment["content_id"] = content_id
+    return attachment

{sendstack-0.1.1 → sendstack-0.1.3}/src/sendstack/types.py

@@ -20,8 +20,10 @@ from typing import Any, Literal, NotRequired, TypeAlias, TypedDict
 
 import httpx
 
-# The live API host. Override via ``base_url`` when SendStack moves domains.
-DEFAULT_BASE_URL = "https://mailer.norialabs.com"
+# The versioned API base. Override via ``base_url`` for other environments;
+# include the /api/v1 segment, since resource paths (e.g. /emails) are sent
+# relative to whatever base is configured.
+DEFAULT_BASE_URL = "https://sendstack.norialabs.com/api/v1"
 
 # Sentinel distinguishing "no body" from an explicit ``None`` body.
 UNSET: Any = object()

{sendstack-0.1.1 → sendstack-0.1.3/src/sendstack.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sendstack
-Version: 0.1.1
+Version: 0.1.3
 Summary: Sync and async Python SDK for the SendStack email SaaS API.
 Author: Noria Labs
 License-Expression: MIT
@@ -123,11 +123,13 @@ decoded payload; on `AsyncSendstack` the same call returns a coroutine you
 
 ### Base URL
 
-The SDK defaults to `https://mailer.norialabs.com`, matching the current live
-API. Override it when you move to the SendStack domain:
+The SDK defaults to `https://sendstack.norialabs.com/api/v1` (the versioned API
+base). Override `base_url` to point at another environment — include the
+`/api/v1` version segment, since resource paths (e.g. `/emails`) are sent
+relative to whatever base you provide:
 
 ```python
-client = Sendstack(token, base_url="https://sendstack.norialabs.com")
+client = Sendstack(token, base_url="https://staging.norialabs.com/api/v1")
 ```
 
 ## Docs Split
@@ -139,7 +141,7 @@ The SaaS docs remain the canonical source for product/API behavior: account
 setup, API tokens, domain verification, DNS records, webhook event catalogs,
 deliverability concepts, provider behavior, dashboard workflows, and the raw
 HTTP API reference. Current live SaaS docs are at
-`https://mailer.norialabs.com/api/docs`.
+`https://sendstack.norialabs.com/api/docs`.
 
 ## Auth
 
@@ -162,7 +164,7 @@ request (sync or async callables both work):
 from sendstack import BearerAuthStrategy, Sendstack
 
 client = Sendstack(
-    base_url="https://mailer.norialabs.com",
+    base_url="https://sendstack.norialabs.com/api/v1",
     auth=BearerAuthStrategy(token=lambda context: get_fresh_token()),
 )
 ```
@@ -293,6 +295,45 @@ client.emails.send(
 )
 ```
 
+### Reading from files
+
+The API accepts strings (`html`/`text`) and base64 (`attachments`). These
+stdlib-only helpers do the read-and-encode step so you don't repeat it:
+
+```python
+from sendstack import (
+    Sendstack,
+    html_from_file,
+    text_from_file,
+    attachment_from_file,
+    attachment_from_bytes,
+)
+
+client.emails.send(
+    {
+        "from": "billing@example.com",
+        "to": "customer@example.com",
+        "subject": "Your invoice",
+        "html": html_from_file("templates/invoice.html"),
+        "text": text_from_file("templates/invoice.txt"),
+        "attachments": [
+            # From a path: filename defaults to the basename, content is base64-encoded.
+            attachment_from_file("invoices/2026-06.pdf", content_type="application/pdf"),
+            # From in-memory bytes (e.g. a generated PDF): filename is required.
+            attachment_from_bytes(generated_pdf, filename="summary.pdf", content_type="application/pdf"),
+        ],
+    }
+)
+```
+
+- `html_from_file(path, *, encoding="utf-8")` / `text_from_file(...)` — read a text
+  file into a string.
+- `attachment_from_file(path, *, filename=None, content_type=None, inline=None, content_id=None)`
+  — read a file into a base64 attachment `dict`. `filename` defaults to the basename.
+  `path` accepts a `str` or any `os.PathLike`.
+- `attachment_from_bytes(data, *, filename, content_type=None, inline=None, content_id=None)`
+  — encode in-memory `bytes`; `filename` is required.
+
 ## Domains
 
 ```python
@@ -510,6 +551,11 @@ Clients and errors:
 - `SendstackError`
 - `DEFAULT_BASE_URL`
 
+Filesystem helpers:
+
+- `html_from_file`, `text_from_file`
+- `attachment_from_file`, `attachment_from_bytes`
+
 Auth, options, and machinery:
 
 - `BearerAuthStrategy`, `HeadersAuthStrategy`, `SendstackAuthStrategy`

{sendstack-0.1.1 → sendstack-0.1.3}/src/sendstack.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 src/sendstack/__init__.py
 src/sendstack/client.py
 src/sendstack/errors.py
+src/sendstack/files.py
 src/sendstack/py.typed
 src/sendstack/types.py
 src/sendstack/utils.py
@@ -14,4 +15,5 @@ src/sendstack.egg-info/requires.txt
 src/sendstack.egg-info/top_level.txt
 tests/test_conformance.py
 tests/test_distribution_identity.py
+tests/test_files.py
 tests/test_sendstack.py

sendstack-0.1.3/tests/test_files.py

@@ -0,0 +1,86 @@
+"""Tests for the filesystem convenience helpers."""
+
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+
+from sendstack import (
+    attachment_from_bytes,
+    attachment_from_file,
+    html_from_file,
+    text_from_file,
+)
+
+
+def test_html_from_file_reads_utf8(tmp_path: Path) -> None:
+    path = tmp_path / "welcome.html"
+    path.write_text("<p>Hëllo</p>", encoding="utf-8")
+
+    assert html_from_file(path) == "<p>Hëllo</p>"
+
+
+def test_text_from_file_reads_utf8_and_honors_encoding(tmp_path: Path) -> None:
+    path = tmp_path / "welcome.txt"
+    path.write_text("Héllo", encoding="latin-1")
+
+    assert text_from_file(path, encoding="latin-1") == "Héllo"
+
+
+def test_attachment_from_file_defaults_filename_to_basename(tmp_path: Path) -> None:
+    path = tmp_path / "invoice.pdf"
+    payload = b"%PDF-1.4 fake"
+    path.write_bytes(payload)
+
+    assert attachment_from_file(path) == {
+        "filename": "invoice.pdf",
+        "content_base64": base64.b64encode(payload).decode("ascii"),
+    }
+
+
+def test_attachment_from_file_accepts_str_path_and_overrides(tmp_path: Path) -> None:
+    path = tmp_path / "logo.png"
+    payload = bytes([0x89, 0x50, 0x4E, 0x47])
+    path.write_bytes(payload)
+
+    # Pass the path as a str to exercise the os.fspath branch.
+    assert attachment_from_file(
+        str(path),
+        filename="brand-logo.png",
+        content_type="image/png",
+        inline=True,
+        content_id="logo",
+    ) == {
+        "filename": "brand-logo.png",
+        "content_base64": base64.b64encode(payload).decode("ascii"),
+        "content_type": "image/png",
+        "inline": True,
+        "content_id": "logo",
+    }
+
+
+def test_attachment_from_bytes_minimal() -> None:
+    data = b"generated bytes"
+
+    assert attachment_from_bytes(data, filename="report.bin") == {
+        "filename": "report.bin",
+        "content_base64": base64.b64encode(data).decode("ascii"),
+    }
+
+
+def test_attachment_from_bytes_with_all_metadata() -> None:
+    data = bytes([1, 2, 3, 4])
+
+    assert attachment_from_bytes(
+        data,
+        filename="raw.dat",
+        content_type="application/octet-stream",
+        inline=False,
+        content_id="raw",
+    ) == {
+        "filename": "raw.dat",
+        "content_base64": base64.b64encode(data).decode("ascii"),
+        "content_type": "application/octet-stream",
+        "inline": False,
+        "content_id": "raw",
+    }

{sendstack-0.1.1 → sendstack-0.1.3}/tests/test_sendstack.py

@@ -131,7 +131,7 @@ def test_send_email_aliases_and_unwraps():
 
     assert result == {"id": "m_1", "status": "queued"}
     request = calls[0]
-    assert str(request.url) == "https://mailer.norialabs.com/emails"
+    assert str(request.url) == "https://sendstack.norialabs.com/api/v1/emails"
     assert request.method == "POST"
     assert request.headers["authorization"] == "Bearer tok"
     assert request.headers["accept"] == "application/json"
@@ -192,10 +192,10 @@ def test_emails_get_events_cancel_requeue():
         assert client.emails.requeue("m1")["status"] == "queued"
     finally:
         http.close()
-    assert calls[0].url.path == "/emails/m 1"  # decoded back by httpx (sent percent-encoded)
-    assert calls[1].url.path == "/emails/m1/events"
-    assert calls[2].method == "POST" and calls[2].url.path == "/emails/m1/cancel"
-    assert calls[3].url.path == "/emails/m1/requeue"
+    assert calls[0].url.path == "/api/v1/emails/m 1"  # decoded back by httpx (sent percent-encoded)
+    assert calls[1].url.path == "/api/v1/emails/m1/events"
+    assert calls[2].method == "POST" and calls[2].url.path == "/api/v1/emails/m1/cancel"
+    assert calls[3].url.path == "/api/v1/emails/m1/requeue"
 
 
 # --------------------------------------------------------------------------- #
@@ -224,8 +224,8 @@ def test_domains_resource():
         "provider_id": "p1",
         "custom_return_path": "bounce",
     }
-    assert calls[1].method == "GET" and calls[1].url.path == "/domains"
-    assert calls[3].url.path == "/domains/d1/verify"
+    assert calls[1].method == "GET" and calls[1].url.path == "/api/v1/domains"
+    assert calls[3].url.path == "/api/v1/domains/d1/verify"
 
 
 def test_templates_resource_including_delete_returns_none():
@@ -247,7 +247,7 @@ def test_templates_resource_including_delete_returns_none():
     finally:
         http.close()
     assert removed is None
-    assert calls[3].method == "PATCH" and calls[3].url.path == "/templates/t1"
+    assert calls[3].method == "PATCH" and calls[3].url.path == "/api/v1/templates/t1"
     assert calls[4].method == "DELETE"
 
 
@@ -268,8 +268,8 @@ def test_webhooks_resource_event_types_alias():
     finally:
         http.close()
     assert json.loads(calls[0].content) == {"url": "https://e.com", "event_types": ["email.sent"]}
-    assert calls[0].url.path == "/webhook-endpoints"
-    assert calls[3].method == "DELETE" and calls[3].url.path == "/webhook-endpoints/wh"
+    assert calls[0].url.path == "/api/v1/webhook-endpoints"
+    assert calls[3].method == "DELETE" and calls[3].url.path == "/api/v1/webhook-endpoints/wh"
 
 
 def test_webhook_events_retry_alias_attribute():
@@ -280,7 +280,7 @@ def test_webhook_events_retry_alias_attribute():
     finally:
         http.close()
     assert result["webhook_status"] == "queued"
-    assert calls[0].method == "POST" and calls[0].url.path == "/events/ev_1/retry"
+    assert calls[0].method == "POST" and calls[0].url.path == "/api/v1/events/ev_1/retry"
 
 
 def test_suppressions_resource():
@@ -297,8 +297,8 @@ def test_suppressions_resource():
         client.suppressions.remove("bad@x.com")
     finally:
         http.close()
-    assert calls[0].url.path == "/suppressions"
-    assert calls[2].method == "DELETE" and calls[2].url.path == "/suppressions/bad@x.com"
+    assert calls[0].url.path == "/api/v1/suppressions"
+    assert calls[2].method == "DELETE" and calls[2].url.path == "/api/v1/suppressions/bad@x.com"
 
 
 def test_attachments_upload_alias():
@@ -646,7 +646,7 @@ def test_close_owns_vs_injected_and_context_manager():
 def test_default_base_url_when_unspecified():
     client = Sendstack("tok")
     try:
-        assert client.base_url == "https://mailer.norialabs.com"
+        assert client.base_url == "https://sendstack.norialabs.com/api/v1"
     finally:
         client.close()