repost-client 0.1.0__tar.gz

repost_client-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+dist/
+.pytest_cache/

repost_client-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: repost-client
+Version: 0.1.0
+Summary: Repost webhook client runtime — typed senders generated from your .repost schema
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27

repost_client-0.1.0/fixture/repost_sdk/__init__.py

@@ -0,0 +1,20 @@
+# Generated by Repost from your `.repost` schema — do not edit.
+# Regenerate with `repost generate`.
+
+from __future__ import annotations
+
+from .client import RepostClient
+from .models import (
+    Author,
+    Book,
+    Currency,
+    DeletedBook,
+)
+
+__all__ = [
+    "Author",
+    "Book",
+    "Currency",
+    "DeletedBook",
+    "RepostClient",
+]

repost_client-0.1.0/fixture/repost_sdk/client.py

@@ -0,0 +1,54 @@
+# Generated by Repost from your `.repost` schema — do not edit.
+# Regenerate with `repost generate`.
+
+from __future__ import annotations
+
+from repost_client import (
+    ClientOptions,
+    SendResult,
+    assert_descriptor_version,
+    send,
+)
+
+from .descriptors import SCHEMA
+from .models import Book, DeletedBook
+
+
+class BookWebhooks:
+    """Sends the "book" group's events."""
+
+    def __init__(self, options: ClientOptions) -> None:
+        self._options = options
+
+    def created(self, *, customer_id: str, data: Book, idempotency_key: str | None = None) -> SendResult:
+        """A book was created"""
+        return send(self._options, SCHEMA, "book", "created", customer_id=customer_id, data=data, idempotency_key=idempotency_key)
+
+    def updated(self, *, customer_id: str, data: Book, idempotency_key: str | None = None) -> SendResult:
+        """Sends a "book.updated" event."""
+        return send(self._options, SCHEMA, "book", "updated", customer_id=customer_id, data=data, idempotency_key=idempotency_key)
+
+    def deleted(self, *, customer_id: str, data: DeletedBook, idempotency_key: str | None = None) -> SendResult:
+        """Sends a "book.deleted" event."""
+        return send(self._options, SCHEMA, "book", "deleted", customer_id=customer_id, data=data, idempotency_key=idempotency_key)
+
+
+class Webhooks:
+    """The catalog method tree: one attribute per catalog with at least
+    one bound member."""
+
+    def __init__(self, options: ClientOptions) -> None:
+        self.book = BookWebhooks(options)
+
+
+class RepostClient:
+    """The Repost client generated from your schema. The typed send
+    methods live under ``.webhooks``."""
+
+    def __init__(self, options: ClientOptions | None = None) -> None:
+        # The descriptor-format handshake with the runtime package runs
+        # here, so a version mismatch fails at construction — never
+        # silently at send time.
+        assert_descriptor_version(2)
+        self._options = options if options is not None else ClientOptions()
+        self.webhooks = Webhooks(self._options)

repost_client-0.1.0/fixture/repost_sdk/descriptors.py

@@ -0,0 +1,55 @@
+# Generated by Repost from your `.repost` schema — do not edit.
+# Regenerate with `repost generate`.
+
+from __future__ import annotations
+
+from repost_client import (
+    EventDescriptor,
+    FieldDescriptor,
+    ModelDescriptor,
+    SchemaDescriptor,
+)
+
+# SCHEMA is the complete descriptor set handed to the runtime on every
+# send: the per-model serialization descriptors (field order, `@map` wire
+# names, `@default` injection specs), the catalog method tree, and the
+# descriptor-format version this package was emitted for (verified by the
+# `RepostClient` construction-time handshake).
+SCHEMA = SchemaDescriptor(
+    descriptor_format_version=2,
+    enums={
+        "Currency": {
+            "USD": "USD",
+            "EUR": "EUR",
+        },
+    },
+    models={
+        "Author": ModelDescriptor(
+            fields=(
+                FieldDescriptor(schema_name="name", wire_name="name", scalar_kind="string", required_in_input=True, nullable_in_input=False, list=False, default=None),
+                FieldDescriptor(schema_name="email", wire_name="email", scalar_kind="string", required_in_input=False, nullable_in_input=True, list=False, default=None),
+            )
+        ),
+        "Book": ModelDescriptor(
+            fields=(
+                FieldDescriptor(schema_name="title", wire_name="title", scalar_kind="string", required_in_input=True, nullable_in_input=False, list=False, default=None),
+                FieldDescriptor(schema_name="authors", wire_name="authors", scalar_kind="model", descriptor_id="Author", required_in_input=True, nullable_in_input=False, list=True, default=None),
+                FieldDescriptor(schema_name="price", wire_name="price", scalar_kind="float64", required_in_input=True, nullable_in_input=False, list=False, default=None),
+                FieldDescriptor(schema_name="currency", wire_name="currency", scalar_kind="enum", descriptor_id="Currency", required_in_input=True, nullable_in_input=False, list=False, default=None),
+                FieldDescriptor(schema_name="subtitle", wire_name="subtitle", scalar_kind="string", required_in_input=False, nullable_in_input=True, list=False, default=None),
+            )
+        ),
+        "DeletedBook": ModelDescriptor(
+            fields=(
+                FieldDescriptor(schema_name="id", wire_name="id", scalar_kind="string", required_in_input=True, nullable_in_input=False, list=False, default=None),
+            )
+        ),
+    },
+    webhooks={
+        "book": {
+            "created": EventDescriptor(type="book.created", model="Book"),
+            "updated": EventDescriptor(type="book.updated", model="Book"),
+            "deleted": EventDescriptor(type="book.deleted", model="DeletedBook"),
+        },
+    },
+)

repost_client-0.1.0/fixture/repost_sdk/models.py

@@ -0,0 +1,52 @@
+# Generated by Repost from your `.repost` schema — do not edit.
+# Regenerate with `repost generate`.
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from typing import ClassVar
+
+from repost_client import UNSET, UnsetType
+
+
+class Currency(str, enum.Enum):
+    USD = "USD"
+    EUR = "EUR"
+
+
+@dataclass(kw_only=True)
+class Author:
+    __repost_fields__: ClassVar[dict[str, str]] = {
+        "name": "name",
+        "email": "email",
+    }
+
+    name: str
+    email: str | None | UnsetType = UNSET
+
+
+@dataclass(kw_only=True)
+class Book:
+    __repost_fields__: ClassVar[dict[str, str]] = {
+        "title": "title",
+        "authors": "authors",
+        "price": "price",
+        "currency": "currency",
+        "subtitle": "subtitle",
+    }
+
+    title: str
+    authors: list[Author]
+    price: float
+    currency: Currency
+    subtitle: str | None | UnsetType = UNSET
+
+
+@dataclass(kw_only=True)
+class DeletedBook:
+    __repost_fields__: ClassVar[dict[str, str]] = {
+        "id": "id",
+    }
+
+    id: str

repost_client-0.1.0/fixture/repost_sdk/schema.repost

@@ -0,0 +1,52 @@
+// --- canonical.repost
+generator sdk {
+  language = "python"
+  output   = "../generated/python"
+}
+
+enum Currency {
+  USD
+  EUR
+}
+
+type Book {
+  /// A book was created
+  created
+  updated
+  deleted
+}
+
+model Author {
+  name  String
+  email String?
+}
+
+model Book {
+  title    String
+  authors  Author[]
+  price    Float
+  currency Currency
+  subtitle String?
+}
+
+model DeletedBook {
+  id String
+}
+
+event BookCreated {
+  type      @type(Book.created)
+  data      Book
+  timestamp DateTime
+}
+
+event BookUpdated {
+  type      @type(Book.updated)
+  data      Book
+  timestamp DateTime
+}
+
+event BookDeleted {
+  type      @type(Book.deleted)
+  data      DeletedBook
+  timestamp DateTime
+}

repost_client-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "repost-client"
+version = "0.1.0"
+description = "Repost webhook client runtime — typed senders generated from your .repost schema"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/repost_client"]
+
+[tool.pyright]
+include = ["src", "tests", "fixture"]
+extraPaths = ["fixture"]
+typeCheckingMode = "strict"
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

repost_client-0.1.0/src/repost_client/__init__.py

@@ -0,0 +1,57 @@
+"""Repost webhook client runtime — typed senders generated from your
+``.repost`` schema.
+
+Generated clients are data + types only; every behavior (serialization,
+envelopes, retries, idempotency) lives here, pinned by
+``sdk/conformance/CONTRACT.md`` and the ``sdk/conformance`` vectors.
+"""
+
+from __future__ import annotations
+
+from ._sentinel import UNSET, UnsetType
+from ._types import (
+    DefaultSpec,
+    EventDescriptor,
+    FieldDescriptor,
+    Generators,
+    ModelDescriptor,
+    SchemaDescriptor,
+    SendResult,
+)
+from .errors import DescriptorVersionError
+from .serialize import serialize_model
+from .transport import (
+    Envelope,
+    HTTPTransportOptions,
+    PublishError,
+    SendRequest,
+    Transport,
+    http_transport,
+)
+from .version import DESCRIPTOR_FORMAT_VERSION, assert_descriptor_version
+from .webhooks import ClientOptions, StubTransport, send
+
+__all__ = [
+    "DESCRIPTOR_FORMAT_VERSION",
+    "UNSET",
+    "ClientOptions",
+    "DefaultSpec",
+    "DescriptorVersionError",
+    "Envelope",
+    "EventDescriptor",
+    "FieldDescriptor",
+    "Generators",
+    "HTTPTransportOptions",
+    "ModelDescriptor",
+    "PublishError",
+    "SchemaDescriptor",
+    "SendRequest",
+    "SendResult",
+    "StubTransport",
+    "Transport",
+    "UnsetType",
+    "assert_descriptor_version",
+    "http_transport",
+    "send",
+    "serialize_model",
+]

repost_client-0.1.0/src/repost_client/_cuid2.py

@@ -0,0 +1,25 @@
+"""Vendored cuid2-shaped id generator.
+
+Generates ids matching the documented cuid2 *shape* — 24 characters, a
+lowercase letter first, the rest lowercase base36 — from :mod:`secrets`
+entropy. Shape only, not the reference algorithm's session counters and
+fingerprints; vendored so the runtime carries zero id-generation
+dependencies (SDK distribution decision §3).
+"""
+
+from __future__ import annotations
+
+import secrets
+
+LENGTH = 24
+"""The number of characters in a generated id."""
+
+_LETTERS = "abcdefghijklmnopqrstuvwxyz"
+_BASE36 = "0123456789abcdefghijklmnopqrstuvwxyz"
+
+
+def cuid() -> str:
+    """Return a cuid2-shaped id: 24 chars, lowercase letter first, base36."""
+    first = secrets.choice(_LETTERS)
+    rest = "".join(secrets.choice(_BASE36) for _ in range(LENGTH - 1))
+    return first + rest

repost_client-0.1.0/src/repost_client/_generators.py

@@ -0,0 +1,59 @@
+"""Default clock and id generators, plus the resolution helper that merges
+a user :class:`~repost_client.Generators` over them."""
+
+from __future__ import annotations
+
+import uuid as _uuid
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from . import _cuid2
+from ._types import Generators
+
+
+def format_timestamp(value: datetime) -> str:
+    """Format a datetime as the contract's timestamp canon.
+
+    ``YYYY-MM-DDTHH:MM:SS.mmmZ`` — millisecond precision, ``Z`` suffix, in
+    UTC (the JS ``toISOString()`` shape). Aware datetimes are converted to
+    UTC; naive datetimes are assumed UTC.
+    """
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    value = value.astimezone(timezone.utc)
+    return value.strftime("%Y-%m-%dT%H:%M:%S.") + f"{value.microsecond // 1000:03d}Z"
+
+
+def default_now() -> str:
+    """The default clock: the current UTC time in the timestamp canon."""
+    return format_timestamp(datetime.now(timezone.utc))
+
+
+def default_uuid() -> str:
+    """The default UUID source: a random UUIDv4."""
+    return str(_uuid.uuid4())
+
+
+def default_cuid() -> str:
+    """The default cuid source: the vendored cuid2-shape generator."""
+    return _cuid2.cuid()
+
+
+@dataclass(frozen=True)
+class ResolvedGenerators:
+    """A :class:`~repost_client.Generators` with every seam filled in."""
+
+    now: Callable[[], str]
+    uuid: Callable[[], str]
+    cuid: Callable[[], str]
+
+
+def resolve_generators(generators: Generators | None) -> ResolvedGenerators:
+    """Merge a user ``Generators`` over the defaults (``None`` = default)."""
+    g = generators or Generators()
+    return ResolvedGenerators(
+        now=g.now or default_now,
+        uuid=g.uuid or default_uuid,
+        cuid=g.cuid or default_cuid,
+    )

repost_client-0.1.0/src/repost_client/_sentinel.py

@@ -0,0 +1,35 @@
+"""The ``UNSET`` sentinel: Python's tri-state for optional fields.
+
+An attribute equal to :data:`UNSET` is *absent* (omitted from the wire, or
+replaced by the field's ``@default``); ``None`` is an explicit JSON ``null``
+(contract §2.3 — explicit null is not absence).
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+
+class UnsetType:
+    """The type of the :data:`UNSET` sentinel (a falsy singleton).
+
+    Generated dataclasses annotate optional fields as
+    ``T | None | UnsetType`` with ``UNSET`` as the default.
+    """
+
+    _instance: UnsetType | None = None
+
+    def __new__(cls) -> UnsetType:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+UNSET: Final[UnsetType] = UnsetType()
+"""Marks an attribute as *not provided* — omit it (or inject its default)."""

repost_client-0.1.0/src/repost_client/_types.py

@@ -0,0 +1,117 @@
+"""Descriptor and result types shared across the runtime (contract §1).
+
+Generated clients embed these descriptors as plain data; the runtime reads
+them to serialize, envelope, and send. All descriptor dataclasses are frozen
+— they are immutable schema facts, not builders.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+def _empty_enum_descriptors() -> dict[str, dict[str, str]]:
+    return {}
+
+
+@dataclass(frozen=True)
+class DefaultSpec:
+    """An ``@default`` injection spec, applied when a field is absent.
+
+    ``kind`` is one of ``"literal"`` (inject ``value`` verbatim), ``"now"``
+    (ISO-8601 timestamp from the clock), ``"uuid"``, or ``"cuid"`` (from the
+    id generators).
+    """
+
+    kind: str
+    value: object = None
+
+
+@dataclass(frozen=True)
+class FieldDescriptor:
+    """One field's serialization descriptor. Field order is wire key order.
+
+    ``name`` is the DSL identifier (the SDK-input property); ``wire`` is the
+    ``@map``'d wire name when it differs; ``list`` marks list arity (elements
+    serialized one by one); ``model`` names a nested payload model to recurse
+    into; ``enum`` maps member name → wire value; ``default`` is the
+    ``@default`` injection when the field is absent from the input.
+    """
+
+    schema_name: str | None = None
+    wire_name: str | None = None
+    scalar_kind: Literal["string", "boolean", "int64", "float64", "datetime", "json", "enum", "model"] | str | None = None
+    descriptor_id: str | None = None
+    required_in_input: bool = False
+    nullable_in_input: bool = True
+    list: bool = False
+    default: DefaultSpec | None = None
+
+    # Immutable descriptor-format-1 compatibility fields. Generated v2 code
+    # never sets them; the frozen v1 vector runner still does.
+    name: str | None = None
+    wire: str | None = None
+    model: str | None = None
+    enum: dict[str, str] | None = None
+
+
+@dataclass(frozen=True)
+class ModelDescriptor:
+    """A payload model's serialization descriptor: its fields, in
+    declaration order."""
+
+    fields: tuple[FieldDescriptor, ...]
+
+
+@dataclass(frozen=True)
+class EventDescriptor:
+    """One catalog member's binding: wire event ``type`` (e.g.
+    ``"book.created"``) plus the payload ``model``'s key in the model map."""
+
+    type: str
+    model: str
+
+
+@dataclass(frozen=True)
+class SchemaDescriptor:
+    """Everything the runtime needs from a generated client.
+
+    ``descriptor_format_version`` is the version the client was emitted for
+    — generated code asserts it against the runtime at construction via
+    :func:`repost_client.assert_descriptor_version`. ``webhooks`` is
+    ``camelCase(Catalog) → member → event binding``.
+    """
+
+    descriptor_format_version: int
+    models: dict[str, ModelDescriptor]
+    webhooks: dict[str, dict[str, EventDescriptor]]
+    enums: dict[str, dict[str, str]] = field(default_factory=_empty_enum_descriptors)
+
+
+@dataclass(frozen=True)
+class SendResult:
+    """The result of a webhook send, as returned by Repost's publish API
+    (202): the assigned message id (``msg_…``), the wire event type, the
+    receiving tenant, and the envelope's ISO-8601 timestamp."""
+
+    id: str
+    type: str
+    customer_id: str
+    timestamp: str
+
+
+@dataclass
+class Generators:
+    """Injectable clock and id sources (the deterministic-test seam).
+
+    Used by the envelope timestamp and ``@default(now()/uuid()/cuid())``
+    injection. ``None`` fields fall back to the real implementations —
+    override them for deterministic tests (the conformance suite's
+    requirement: every runtime exposes these seams).
+    """
+
+    now: Callable[[], str] | None = None
+    uuid: Callable[[], str] | None = None
+    cuid: Callable[[], str] | None = None

repost_client-0.1.0/src/repost_client/errors.py

@@ -0,0 +1,12 @@
+"""Runtime error types (the transport's ``PublishError`` lives in
+:mod:`repost_client.transport`)."""
+
+from __future__ import annotations
+
+
+class DescriptorVersionError(Exception):
+    """A generated client's descriptor format does not match this runtime.
+
+    Raised by :func:`repost_client.assert_descriptor_version` at client
+    construction — never silently at send time.
+    """