repost-client 0.1.0__py3-none-any.whl

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/_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/_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/_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/_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/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.
+    """

repost_client/serialize.py

@@ -0,0 +1,293 @@
+"""Descriptor-driven serialization (contract §2, pinned byte-for-byte by
+``sdk/conformance/vectors``).
+
+Fields emit in declaration order under their ``@map``'d wire names, absent
+fields with an ``@default`` are injected, absent optional fields are
+omitted, nested models recurse, and enum members serialize to their
+(possibly ``@map``'d) wire values.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable, Mapping
+from datetime import datetime
+from typing import cast
+
+from ._generators import ResolvedGenerators, format_timestamp, resolve_generators
+from ._sentinel import UNSET
+from ._types import DefaultSpec, FieldDescriptor, Generators, ModelDescriptor, SchemaDescriptor
+
+_Getter = Callable[[str], "tuple[object, bool]"]
+
+
+def serialize_model(
+    models: dict[str, ModelDescriptor],
+    model_name: str,
+    data: object,
+    generators: Generators | None = None,
+    enums: dict[str, dict[str, str]] | None = None,
+) -> dict[str, object]:
+    """Serialize a send input into its wire payload, driven by the model
+    descriptors.
+
+    The returned ``dict`` is built in field declaration order (Python dicts
+    preserve insertion order — the wire is an ordered JSON object).
+
+    ``data`` is either a mapping keyed by schema field names (a missing key
+    is *absent*; an explicit ``None`` value is JSON ``null``), or an object
+    carrying ``__repost_fields__`` — a ``dict`` mapping schema field name →
+    attribute name, as generated dataclasses do (an attribute equal to
+    :data:`~repost_client.UNSET` is absent). ``datetime`` values serialize
+    to the contract's timestamp canon; ``(str, Enum)`` members serialize as
+    their string value through the enum wire map.
+
+    ``generators`` overrides the clock and id sources used by
+    ``@default(now()/uuid()/cuid())`` injection (the conformance seam).
+
+    Raises:
+        KeyError: when ``model_name`` has no descriptor in ``models``.
+        TypeError: when ``data`` is neither accepted input form.
+    """
+    enum_descriptors = enums or {}
+    _validate_model_descriptors(models, enum_descriptors)
+    return _serialize_model(models, model_name, data, resolve_generators(generators), enum_descriptors, "$")
+
+
+def _serialize_model(
+    models: dict[str, ModelDescriptor],
+    model_name: str,
+    data: object,
+    generators: ResolvedGenerators,
+    enums: dict[str, dict[str, str]],
+    path: str,
+) -> dict[str, object]:
+    descriptor = models.get(model_name)
+    if descriptor is None:
+        raise KeyError(f"repost-client: no serialization descriptor for model '{model_name}'")
+    get = _input_getter(model_name, data)
+
+    payload: dict[str, object] = {}
+    for field in descriptor.fields:
+        name = field.schema_name if field.schema_name is not None else field.name
+        if name is None:
+            raise ValueError("repost-client: [INVALID_DESCRIPTOR] $: field name is missing")
+        field_path = _append_path(path, name)
+        _validate_descriptor(field, field_path)
+        value, present = get(name)
+        if not present:
+            if field.default is not None:
+                value = _resolve_default(field.default, generators)
+            elif field.schema_name is not None and field.required_in_input:
+                _validation_error("REQUIRED_FIELD", field_path, "required field is absent")
+            else:
+                continue
+        if value is None and field.schema_name is not None and not field.nullable_in_input:
+            _validation_error("NULL_NOT_ALLOWED", field_path, "null is not allowed")
+        wire_name = field.wire_name if field.wire_name is not None else field.wire or name
+        payload[wire_name] = _serialize_value(models, field, value, generators, enums, field_path)
+    return payload
+
+
+def _input_getter(model_name: str, data: object) -> _Getter:
+    """Normalize the two accepted input forms into a presence-aware lookup."""
+    if isinstance(data, Mapping):
+        mapping = cast(Mapping[str, object], data)
+
+        def get_from_mapping(name: str) -> tuple[object, bool]:
+            if name not in mapping:
+                return None, False
+            value = mapping[name]
+            if value is UNSET:
+                return None, False
+            return value, True
+
+        return get_from_mapping
+
+    fields_map = getattr(data, "__repost_fields__", None)
+    if isinstance(fields_map, dict):
+        attributes = cast("dict[str, str]", fields_map)
+
+        def get_from_object(name: str) -> tuple[object, bool]:
+            attribute = attributes.get(name)
+            if attribute is None:
+                return None, False
+            value = getattr(data, attribute, UNSET)
+            if value is UNSET:
+                return None, False
+            return value, True
+
+        return get_from_object
+
+    raise TypeError(
+        f"repost-client: expected a mapping or an object with __repost_fields__ "
+        f"for model '{model_name}', got {_describe(data)}"
+    )
+
+
+def _describe(data: object) -> str:
+    return "null" if data is None else type(data).__name__
+
+
+def _serialize_value(
+    models: dict[str, ModelDescriptor],
+    field: FieldDescriptor,
+    value: object,
+    generators: ResolvedGenerators,
+    enums: dict[str, dict[str, str]],
+    path: str,
+) -> object:
+    """Apply list arity, then per-item model recursion or enum mapping."""
+    if field.list and isinstance(value, (list, tuple)):
+        items = cast("list[object] | tuple[object, ...]", value)
+        serialized: list[object] = []
+        for index, item in enumerate(items):
+            item_path = f"{path}[{index}]"
+            if item is None and field.schema_name is not None:
+                _validation_error("NULL_LIST_ELEMENT", item_path, "null list elements are not allowed")
+            serialized.append(_serialize_item(models, field, item, generators, enums, item_path))
+        return serialized
+    if field.list and field.schema_name is not None and value is not None:
+        _validation_error("TYPE_MISMATCH", path, "expected a list")
+    return _serialize_item(models, field, value, generators, enums, path)
+
+
+def _serialize_item(
+    models: dict[str, ModelDescriptor],
+    field: FieldDescriptor,
+    value: object,
+    generators: ResolvedGenerators,
+    enums: dict[str, dict[str, str]],
+    path: str,
+) -> object:
+    if value is None:
+        return None
+    model = field.descriptor_id if field.scalar_kind == "model" else field.model
+    if model is not None:
+        return _serialize_model(models, model, value, generators, enums, path)
+    enum_values = enums.get(field.descriptor_id or "") if field.scalar_kind == "enum" else field.enum
+    if enum_values is not None:
+        if isinstance(value, str):
+            # Generated enums are `class X(str, Enum)` whose VALUE is the
+            # member name — str subclasses, so the wire map keys match by
+            # string equality. Never `str(value)`: that renders "X.MEMBER".
+            wire = enum_values.get(value)
+            if wire is not None:
+                return wire
+            return str.__str__(value)  # unrecognized member passes through verbatim
+        return value
+    if field.schema_name is not None:
+        _validate_scalar(field.scalar_kind, value, path)
+    if isinstance(value, datetime):
+        # Generated DateTime fields: format to the contract's timestamp
+        # canon in UTC (mirrors the Go runtime's time.Time support).
+        return format_timestamp(value)
+    return value
+
+
+_SCALAR_KINDS = {"string", "boolean", "int64", "float64", "datetime", "json", "enum", "model"}
+
+
+def _validate_descriptor(field: FieldDescriptor, path: str) -> None:
+    if field.schema_name is None:
+        return
+    if field.scalar_kind not in _SCALAR_KINDS:
+        _validation_error("UNKNOWN_SCALAR_KIND", path, f"unknown scalar kind '{field.scalar_kind}'")
+
+
+def _validate_scalar(kind: str | None, value: object, path: str) -> None:
+    if kind in {"float64", "int64"} and isinstance(value, float):
+        import math
+
+        if not math.isfinite(value):
+            _validation_error("NON_FINITE_NUMBER", path, "non-finite numbers are not allowed")
+    if kind == "json":
+        _validate_json(value, path)
+
+
+def _validate_json(value: object, path: str) -> None:
+    _validate_json_at(value, path, set())
+
+
+def _validate_json_at(value: object, path: str, active_ancestors: set[int]) -> None:
+    if isinstance(value, float):
+        import math
+
+        if not math.isfinite(value):
+            _validation_error("NON_FINITE_NUMBER", path, "non-finite numbers are not allowed")
+    if not isinstance(value, (list, tuple, Mapping)):
+        return
+
+    identity = id(cast(object, value))
+    if identity in active_ancestors:
+        _validation_error("INVALID_JSON", path, "cyclic JSON values are not allowed")
+    active_ancestors.add(identity)
+    try:
+        if isinstance(value, (list, tuple)):
+            items = cast("list[object] | tuple[object, ...]", value)
+            for index, item in enumerate(items):
+                _validate_json_at(item, f"{path}[{index}]", active_ancestors)
+        else:
+            mapping = cast("Mapping[object, object]", value)
+            for _, item in sorted(mapping.items(), key=lambda pair: str(pair[0])):
+                _validate_json_at(item, f"{path}[{{*}}]", active_ancestors)
+    finally:
+        active_ancestors.remove(identity)
+
+
+def _validate_model_descriptors(
+    models: dict[str, ModelDescriptor],
+    enums: dict[str, dict[str, str]],
+) -> None:
+    for model_name in sorted(models):
+        model = models[model_name]
+        for index, field in enumerate(model.fields):
+            if field.schema_name is None:
+                continue
+            _validate_descriptor(field, _append_path("$", field.schema_name))
+            if field.scalar_kind not in {"enum", "model"}:
+                continue
+            registry = enums if field.scalar_kind == "enum" else models
+            if field.descriptor_id is None or field.descriptor_id not in registry:
+                reference_path = f"{_append_path('$.models', model_name)}.fields[{index}].descriptorId"
+                _validation_error(
+                    "INVALID_DESCRIPTOR_REFERENCE",
+                    reference_path,
+                    f"{field.scalar_kind} descriptor '{field.descriptor_id or ''}' does not exist",
+                )
+
+
+def validate_schema_descriptor(schema: SchemaDescriptor) -> None:
+    _validate_model_descriptors(schema.models, schema.enums)
+    for group in sorted(schema.webhooks):
+        members = schema.webhooks[group]
+        for member in sorted(members):
+            event = members[member]
+            if event.model not in schema.models:
+                path = f"{_append_path(_append_path('$.webhooks', group), member)}.model"
+                _validation_error(
+                    "INVALID_DESCRIPTOR_REFERENCE",
+                    path,
+                    f"model descriptor '{event.model}' does not exist",
+                )
+
+
+def _append_path(path: str, key: str) -> str:
+    if re.fullmatch(r"[A-Za-z_$][A-Za-z0-9_$]*", key):
+        return f"{path}.{key}"
+    return f"{path}[{json.dumps(key, ensure_ascii=False)}]"
+
+
+def _validation_error(code: str, path: str, message: str) -> None:
+    raise ValueError(f"repost-client: [{code}] {path}: {message}.")
+
+
+def _resolve_default(spec: DefaultSpec, generators: ResolvedGenerators) -> object:
+    if spec.kind == "now":
+        return generators.now()
+    if spec.kind == "uuid":
+        return generators.uuid()
+    if spec.kind == "cuid":
+        return generators.cuid()
+    return spec.value  # "literal"

repost_client/transport.py

@@ -0,0 +1,270 @@
+"""The HTTP transport against Repost's publish API (contract §5), built on
+httpx.
+
+One idempotency key is minted per send and reused across internal retries,
+so retrying is always safe: the server deduplicates. Retryable outcomes are
+transport errors, per-attempt timeouts, 5xx, 429, and 409 (a concurrent
+duplicate still in flight); ``Retry-After`` is honored when it exceeds the
+backoff, capped at 60s.
+
+Sync only for now; the :class:`Transport` protocol is designed so an
+``AsyncTransport`` twin can be added later without changing this surface.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import time
+import uuid as _uuid
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol, cast
+
+import httpx
+
+from ._types import SendResult
+
+DEFAULT_API_URL = "https://api.repost.sh"
+_RETRY_AFTER_CAP_SECONDS = 60.0
+# The publish API's body cap (publish-api handler.go MaxBodyBytes): 1 MiB.
+MAX_PAYLOAD_BYTES = 1 << 20
+
+
+class PublishError(Exception):
+    """A publish rejected or failed by the Repost API.
+
+    ``status`` is the HTTP status of the failing response (``None`` when the
+    failure produced no status — network error, timeout, body cap); ``body``
+    is the parsed JSON error body when one was returned.
+    """
+
+    status: int | None
+    body: object
+
+    def __init__(self, message: str, status: int | None = None, body: object = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+@dataclass
+class Envelope:
+    """The Standard Webhooks envelope the runtime constructs for a send:
+    wire event ``type``, ISO-8601 ``timestamp``, serialized ``data``."""
+
+    type: str
+    timestamp: str
+    data: dict[str, object]
+
+
+@dataclass
+class SendRequest:
+    """Everything a transport needs to deliver one webhook publish.
+
+    ``token`` is the publish API key (sent as the bearer token); ``api_url``
+    is the base URL (``None`` means the transport default);
+    ``customer_id`` is the receiving tenant; ``idempotency_key`` is the
+    caller-owned key (``None`` means the transport mints one per send,
+    deduplicating internal retries only).
+    """
+
+    token: str
+    api_url: str | None
+    customer_id: str
+    idempotency_key: str | None
+    envelope: Envelope
+
+
+class Transport(Protocol):
+    """The seam through which a send reaches Repost. The HTTP transport is
+    the default; :class:`repost_client.StubTransport` serves tests."""
+
+    def send(self, request: SendRequest) -> SendResult:
+        """Deliver one publish and return the API's result."""
+        ...
+
+
+@dataclass
+class HTTPTransportOptions:
+    """Configuration for :func:`http_transport`. Defaults are production
+    values; ``sleep`` and ``rand`` are the deterministic-test seams.
+
+    ``client`` is an injectable :class:`httpx.Client` (e.g. wrapping
+    ``httpx.MockTransport``); ``max_retries`` counts retries after the
+    initial attempt; ``base_delay`` is the backoff base in seconds, doubled
+    per attempt with jitter; ``timeout`` is the per-attempt timeout in
+    seconds (fresh budget each retry); ``rand`` returns jitter in [0, 1).
+    """
+
+    client: httpx.Client | None = None
+    max_retries: int = 3
+    base_delay: float = 0.25
+    timeout: float = 30.0
+    sleep: Callable[[float], None] = time.sleep
+    rand: Callable[[], float] = random.random
+
+
+@dataclass
+class _AttemptFailure:
+    """One failed attempt: the typed error, whether it may be retried, and
+    any Retry-After hint (seconds)."""
+
+    error: PublishError
+    retryable: bool
+    retry_after: float | None = None
+
+
+def http_transport(options: HTTPTransportOptions | None = None) -> Transport:
+    """Build the HTTP transport against Repost's publish API."""
+    return _HTTPTransport(options or HTTPTransportOptions())
+
+
+class _HTTPTransport:
+    """`Transport` implementation over httpx (see the module docstring)."""
+
+    def __init__(self, options: HTTPTransportOptions) -> None:
+        self._client = options.client or httpx.Client()
+        self._max_retries = options.max_retries
+        self._base_delay = options.base_delay
+        self._timeout = options.timeout
+        self._sleep = options.sleep
+        self._rand = options.rand
+
+    def send(self, request: SendRequest) -> SendResult:
+        """Deliver one publish, retrying per the contract's retry table."""
+        base = (request.api_url or DEFAULT_API_URL).rstrip("/")
+        url = base + "/v1/messages"
+
+        body = json.dumps(
+            {
+                "type": request.envelope.type,
+                "customerId": request.customer_id,
+                "timestamp": request.envelope.timestamp,
+                "data": request.envelope.data,
+            },
+            separators=(",", ":"),
+            ensure_ascii=False,
+        ).encode("utf-8")
+
+        # The API rejects oversized bodies with a 413; failing before the
+        # first attempt gives the caller the byte count instead of burned
+        # retries.
+        if len(body) > MAX_PAYLOAD_BYTES:
+            raise PublishError(
+                f"repost-client: publish body is {len(body)} bytes, "
+                f"over the API's 1 MiB ({MAX_PAYLOAD_BYTES}-byte) limit"
+            )
+
+        # ONE idempotency key per send, reused across every retry.
+        idempotency_key = request.idempotency_key or str(_uuid.uuid4())
+
+        last_error = PublishError("repost-client: publish failed before any attempt")
+        retry_after: float | None = None
+        for attempt in range(self._max_retries + 1):
+            if attempt > 0:
+                self._sleep(self._retry_delay(attempt, retry_after))
+            result, failure = self._attempt(url, request.token, idempotency_key, body)
+            if failure is None:
+                assert result is not None
+                return result
+            last_error = failure.error
+            retry_after = failure.retry_after
+            if not failure.retryable:
+                raise last_error
+        raise last_error
+
+    def _attempt(
+        self, url: str, token: str, idempotency_key: str, body: bytes
+    ) -> tuple[SendResult | None, _AttemptFailure | None]:
+        """Perform one HTTP attempt under a fresh per-attempt timeout."""
+        try:
+            response = self._client.request(
+                "POST",
+                url,
+                content=body,
+                headers={
+                    "authorization": f"Bearer {token}",
+                    "content-type": "application/json",
+                    "idempotency-key": idempotency_key,
+                },
+                timeout=self._timeout,
+            )
+        except httpx.TimeoutException:
+            return None, _AttemptFailure(
+                PublishError(f"repost-client: publish attempt timed out after {self._timeout}s"),
+                retryable=True,
+            )
+        except httpx.HTTPError as error:
+            return None, _AttemptFailure(
+                PublishError(f"repost-client: publish request failed: {error}"),
+                retryable=True,
+            )
+
+        if 200 <= response.status_code < 300:
+            return self._decode_success(response)
+
+        parsed: object
+        try:
+            parsed = response.json()
+        except ValueError:
+            parsed = None
+        return None, _AttemptFailure(
+            PublishError(
+                f"repost-client: publish failed with status {response.status_code}",
+                status=response.status_code,
+                body=parsed,
+            ),
+            retryable=response.status_code >= 500 or response.status_code in (429, 409),
+            retry_after=_parse_retry_after(response.headers.get("retry-after")),
+        )
+
+    def _decode_success(
+        self, response: httpx.Response
+    ) -> tuple[SendResult | None, _AttemptFailure | None]:
+        """Parse a 2xx body as ``{id, type, customerId, timestamp}``."""
+        try:
+            parsed = response.json()
+        except ValueError as error:
+            return None, _AttemptFailure(
+                PublishError(f"repost-client: publish request failed: decoding response: {error}"),
+                retryable=True,
+            )
+        if not isinstance(parsed, dict):
+            return None, _AttemptFailure(
+                PublishError(
+                    "repost-client: publish request failed: decoding response: expected a JSON object"
+                ),
+                retryable=True,
+            )
+        fields = cast("dict[str, object]", parsed)
+        return (
+            SendResult(
+                id=str(fields.get("id", "")),
+                type=str(fields.get("type", "")),
+                customer_id=str(fields.get("customerId", "")),
+                timestamp=str(fields.get("timestamp", "")),
+            ),
+            None,
+        )
+
+    def _retry_delay(self, attempt: int, retry_after: float | None) -> float:
+        """The pause before retry ``attempt`` (1-based): exponential backoff
+        with jitter, overridden by a larger Retry-After capped at 60s."""
+        backoff = self._base_delay * (2 ** (attempt - 1)) * (0.5 + 0.5 * self._rand())
+        if retry_after is not None and retry_after > backoff:
+            return min(retry_after, _RETRY_AFTER_CAP_SECONDS)
+        return backoff
+
+
+def _parse_retry_after(header: str | None) -> float | None:
+    """Parse an integer-seconds ``Retry-After`` header value."""
+    if not header:
+        return None
+    try:
+        seconds = float(header)
+    except ValueError:
+        return None
+    if seconds < 0:
+        return None
+    return seconds

repost_client/version.py

@@ -0,0 +1,43 @@
+"""The descriptor-format version handshake (contract §1).
+
+Generated clients declare the version they were emitted for and call
+:func:`assert_descriptor_version` at client construction; a mismatch is
+refused with the concrete fix per direction.
+"""
+
+from __future__ import annotations
+
+from .errors import DescriptorVersionError
+
+DESCRIPTOR_FORMAT_VERSION = 2
+"""The descriptor-format version this runtime implements.
+
+Bumped only on a wire-breaking change to the descriptor contract (see
+``sdk/conformance/CONTRACT.md`` and the conformance-vector freeze policy).
+"""
+
+
+def assert_descriptor_version(declared: int) -> None:
+    """Refuse a generated client whose descriptor format this runtime does
+    not implement.
+
+    Generated code calls this at client construction (never at send time).
+
+    Raises:
+        DescriptorVersionError: when ``declared`` differs from
+            :data:`DESCRIPTOR_FORMAT_VERSION`, naming the fix — upgrade the
+            runtime when the client is newer, regenerate when it is older.
+    """
+    if declared == DESCRIPTOR_FORMAT_VERSION:
+        return
+    if declared > DESCRIPTOR_FORMAT_VERSION:
+        raise DescriptorVersionError(
+            f"repost-client: [UNSUPPORTED_DESCRIPTOR_VERSION] $: the generated client declares descriptor format {declared}, "
+            f"but this runtime implements {DESCRIPTOR_FORMAT_VERSION}. "
+            "Upgrade the repost-client package."
+        )
+    raise DescriptorVersionError(
+        f"repost-client: the generated client declares descriptor format {declared}, "
+        f"but this runtime implements {DESCRIPTOR_FORMAT_VERSION}. "
+        "Re-run `repost schema generate` with the current CLI."
+    )

repost_client/webhooks.py

@@ -0,0 +1,128 @@
+"""The send path a generated client's typed methods call into (contract §4).
+
+Configuration is lazy: auth and base URL are resolved (and enforced) at send
+time, never at construction. Generated clients also check the descriptor
+version at construction, while this public send entry point repeats the full
+version-and-shape handshake before configuration or other side effects.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from ._generators import resolve_generators
+from ._types import Generators, SchemaDescriptor, SendResult
+from .serialize import serialize_model, validate_schema_descriptor
+from .transport import Envelope, HTTPTransportOptions, SendRequest, Transport, http_transport
+from .version import assert_descriptor_version
+
+
+@dataclass
+class ClientOptions:
+    """Options a generated client is constructed with. Nothing is validated
+    until a send.
+
+    ``api_key`` is the environment's publish API key (``None`` means
+    ``REPOST_SEND_API_KEY``, then legacy ``REPOST_TOKEN``, read at send
+    time); ``api_url`` is the API base URL (``None`` means
+    ``REPOST_API_URL``, then the transport default); ``transport`` overrides
+    how sends reach Repost (:class:`StubTransport` for no-network tests);
+    ``generators`` are the injectable clock and id seams.
+    """
+
+    api_key: str | None = None
+    api_url: str | None = None
+    transport: Transport | None = None
+    generators: Generators | None = None
+
+
+# The shared production transport, created on first use so sends without an
+# explicit transport reuse one connection pool.
+_default_transport: Transport | None = None
+
+
+def _get_default_transport() -> Transport:
+    global _default_transport
+    if _default_transport is None:
+        _default_transport = http_transport(HTTPTransportOptions())
+    return _default_transport
+
+
+def send(
+    options: ClientOptions,
+    schema: SchemaDescriptor,
+    group: str,
+    member: str,
+    *,
+    customer_id: str,
+    data: object,
+    idempotency_key: str | None = None,
+) -> SendResult:
+    """Publish one webhook event; generated typed send methods call this.
+
+    Resolves auth lazily (``options.api_key`` → ``REPOST_SEND_API_KEY`` →
+    legacy ``REPOST_TOKEN``) and the base URL (``options.api_url`` →
+    ``REPOST_API_URL``), serializes ``data`` through the model descriptors,
+    builds the Standard Webhooks envelope ``{type, timestamp, data}``, and
+    dispatches through the transport seam.
+
+    Raises:
+        KeyError: for an unknown ``group`` or ``member``.
+        RuntimeError: when no API key is configured.
+    """
+    assert_descriptor_version(schema.descriptor_format_version)
+    validate_schema_descriptor(schema)
+
+    members = schema.webhooks.get(group)
+    if members is None:
+        raise KeyError(f"repost-client: unknown webhook group '{group}'")
+    event = members.get(member)
+    if event is None:
+        raise KeyError(f"repost-client: unknown webhook member '{member}' in group '{group}'")
+
+    # Lazy configuration: first non-empty wins — the api_key option,
+    # REPOST_SEND_API_KEY (the standard .env variable), legacy REPOST_TOKEN.
+    api_key = options.api_key or os.environ.get("REPOST_SEND_API_KEY") or os.environ.get("REPOST_TOKEN")
+    if not api_key:
+        raise RuntimeError(
+            "repost-client: missing API key: set ClientOptions.api_key or the "
+            "REPOST_SEND_API_KEY environment variable (scaffolded into .env by "
+            "`repost schema init`; create a key with your environment in the dashboard)"
+        )
+
+    api_url = options.api_url or os.environ.get("REPOST_API_URL") or None
+
+    resolved = resolve_generators(options.generators)
+    operation_now = resolved.now()
+    operation_generators = Generators(now=lambda: operation_now, uuid=resolved.uuid, cuid=resolved.cuid)
+    envelope = Envelope(
+        type=event.type,
+        timestamp=operation_now,
+        data=serialize_model(schema.models, event.model, data, operation_generators, schema.enums),
+    )
+
+    transport = options.transport or _get_default_transport()
+    return transport.send(
+        SendRequest(
+            token=api_key,
+            api_url=api_url,
+            customer_id=customer_id,
+            idempotency_key=idempotency_key,
+            envelope=envelope,
+        )
+    )
+
+
+class StubTransport:
+    """No-network transport for tests: echoes the envelope identity as a
+    typed :class:`~repost_client.SendResult` with a fixed stub message id."""
+
+    def send(self, request: SendRequest) -> SendResult:
+        """Implement :class:`~repost_client.Transport` without the network."""
+        return SendResult(
+            id="msg_stub",
+            type=request.envelope.type,
+            customer_id=request.customer_id,
+            timestamp=request.envelope.timestamp,
+        )

repost_client-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+repost_client/__init__.py,sha256=wQi8s395uRpMSoz01cwKgCijn7nwfYrKKcxiIULxHZU,1365
+repost_client/_cuid2.py,sha256=9P0uw-C2DCwzAKTfN2NA29cwspliN6pxqutLgvMSFlg,810
+repost_client/_generators.py,sha256=yKKYeAiDQ4ca_F6pbeSDXEia-S-JWqUEJdknNopG1x0,1814
+repost_client/_sentinel.py,sha256=iHKahBjDeEZMYyKTdkvXZM8KdVCA3K3n-IOw3bVFiZM,963
+repost_client/_types.py,sha256=5-Fspw15pZVwq04OIG1G8LG7oMZy9CMGI_nVVMnl4V8,3805
+repost_client/errors.py,sha256=hpgNIU7xQozT9VHb7AZvtIytybeyqNlHiC8yVculy7Y,387
+repost_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+repost_client/serialize.py,sha256=N15W22_R83AdsBDcpJ9RoCQkMpbpaMWu5L1MCpVt7T8,11637
+repost_client/transport.py,sha256=aiBGIPnBVasJs8ODaEF8J6XX_kjiTPcVJ_nyVZSrwKg,9584
+repost_client/version.py,sha256=osefP5ogxEz4S2G1_WUKs9pT_dfC-u9c1XcelOtYjJ0,1695
+repost_client/webhooks.py,sha256=4MUxhvfscejwXNAx98cY_rpu4al7hP7uq6U0PrHIKzg,4819
+repost_client-0.1.0.dist-info/METADATA,sha256=8gcJs1qjpp84JqH1Mxic_xFNjLe2CyOY7GMK5Y6iipk,200
+repost_client-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+repost_client-0.1.0.dist-info/RECORD,,

repost_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any