transcodely 0.2.0__py3-none-any.whl

transcodely/webhooks/construct_event.py

@@ -0,0 +1,111 @@
+"""Verify a signed webhook delivery and decode it into a typed :class:`Event`.
+
+Python port of the TypeScript SDK's ``webhooks/construct-event.ts``.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any, Callable, Mapping, Optional, Union
+
+from ..errors import WebhookPayloadError
+from .signature import DEFAULT_TOLERANCE_SECONDS, verify_signature
+from .types import Event, EventRequest, decoder_for_type
+
+
+def construct_event(
+    raw_body: Union[str, bytes],
+    sig_header: str,
+    secret: Union[str, list[str]],
+    *,
+    tolerance: int = DEFAULT_TOLERANCE_SECONDS,
+    now: Optional[Callable[[], int]] = None,
+) -> Event:
+    """Verify a signed webhook delivery and return the typed :class:`Event`.
+
+    ``secret`` may be a single signing secret or a list of secrets — pass
+    ``[previous, current]`` during a secret rotation's overlap window.
+
+    :raises WebhookSignatureError: the signature is missing/malformed or doesn't match.
+    :raises WebhookTimestampError: the timestamp is outside the tolerance window.
+    :raises WebhookPayloadError: the body isn't valid JSON or the envelope shape is wrong.
+    """
+    body_bytes = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+
+    verify_signature(body_bytes, sig_header, secret, tolerance=tolerance, now=now)
+
+    try:
+        parsed = json.loads(body_bytes.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError) as cause:
+        raise WebhookPayloadError("Webhook body is not valid JSON") from cause
+
+    return _build_event(parsed)
+
+
+def _require_string(obj: Mapping[str, Any], key: str) -> str:
+    v = obj.get(key)
+    if not isinstance(v, str) or len(v) == 0:
+        raise WebhookPayloadError(f"Webhook envelope is missing required string field `{key}`")
+    return v
+
+
+def _require_number(obj: Mapping[str, Any], key: str) -> int:
+    v = obj.get(key)
+    # bool is a subclass of int in Python — reject it explicitly so a JSON
+    # `true` doesn't sail through as the number 1 (matches the TS typeof check).
+    if isinstance(v, bool) or not isinstance(v, (int, float)) or not math.isfinite(v):
+        raise WebhookPayloadError(f"Webhook envelope field `{key}` must be a number")
+    return int(v)
+
+
+def _build_event(parsed: Any) -> Event:
+    if not isinstance(parsed, dict):
+        raise WebhookPayloadError("Webhook body must be a JSON object")
+
+    id_ = _require_string(parsed, "id")
+    if parsed.get("object") != "event":
+        raise WebhookPayloadError('Webhook envelope `object` must be "event"')
+    api_version = _require_string(parsed, "api_version")
+    created = _require_string(parsed, "created")
+    type_ = _require_string(parsed, "type")
+    pending_webhooks = _require_number(parsed, "pending_webhooks")
+
+    data_raw = parsed.get("data")
+    if not isinstance(data_raw, dict):
+        raise WebhookPayloadError("Webhook envelope field `data` must be a JSON object")
+
+    request_raw = parsed.get("request")
+    if not isinstance(request_raw, dict):
+        raise WebhookPayloadError("Webhook envelope field `request` must be a JSON object")
+    # `request.id` is null for events emitted outside a request scope — every
+    # worker-callback event (job.succeeded/failed/canceled/progress, output.*,
+    # video.uploaded) and every SendTestWebhook delivery. Accept null or a
+    # non-empty string; reject "" and non-strings (mirrors the JS SDK).
+    request_id = request_raw.get("id")
+    if request_id is not None and (not isinstance(request_id, str) or request_id == ""):
+        raise WebhookPayloadError(
+            "Webhook envelope field `request.id` must be a non-empty string or null"
+        )
+    idempotency_key = request_raw.get("idempotency_key")
+    if idempotency_key is not None and not isinstance(idempotency_key, str):
+        raise WebhookPayloadError(
+            "Webhook envelope field `request.idempotency_key` must be a string or null"
+        )
+
+    decode = decoder_for_type(type_)
+    data: Any = decode(data_raw) if decode else data_raw
+
+    return Event(
+        id=id_,
+        object="event",
+        api_version=api_version,
+        created=created,
+        type=type_,
+        data=data,
+        pending_webhooks=pending_webhooks,
+        request=EventRequest(id=request_id, idempotency_key=idempotency_key),
+    )
+
+
+__all__ = ["construct_event"]

transcodely/webhooks/signature.py

@@ -0,0 +1,110 @@
+"""Webhook signature verification.
+
+Python port of the TypeScript SDK's ``webhooks/signature.ts``. The signing
+math is identical across all Transcodely SDKs: HMAC-SHA-256 over
+``"<unix-timestamp>.<raw-body-bytes>"``, hex-encoded, carried in the
+``Transcodely-Signature`` header as ``t=<ts>,v1=<hex>``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from typing import Callable, Optional, Union
+
+from ..errors import WebhookSignatureError, WebhookTimestampError
+
+#: Default signature tolerance window in seconds (Stripe parity).
+DEFAULT_TOLERANCE_SECONDS = 300
+
+#: HTTP header name carrying the signature (lower-cased for case-insensitive lookup).
+SIGNATURE_HEADER = "transcodely-signature"
+
+#: HTTP header name carrying the event ID (``evt_*``). Useful as an idempotency
+#: key for handlers that dedupe redeliveries — the same event ID rides every
+#: retry of a given event.
+EVENT_ID_HEADER = "webhook-id"
+
+
+def _parse_header(header: str) -> tuple[int, list[str]]:
+    """Parse the ``Transcodely-Signature`` header.
+
+    The header is a comma-separated list of ``key=value`` pairs. ``t`` is the
+    unix timestamp (seconds); each ``v1`` entry is a hex-encoded
+    HMAC-SHA-256. Unknown keys are ignored so future scheme versions don't
+    break older receivers.
+    """
+    timestamp: Optional[int] = None
+    signatures: list[str] = []
+    for part in header.split(","):
+        eq = part.find("=")
+        if eq < 0:
+            continue
+        key = part[:eq].strip()
+        value = part[eq + 1 :].strip()
+        if key == "t":
+            try:
+                timestamp = int(value)
+            except ValueError:
+                # Divergence from the JS SDK (which parses with Number() and an
+                # isInteger check, so it would accept "123.0"/"1e3"): int() is
+                # stricter and rejects those. Harmless — the API always emits a
+                # plain integer timestamp.
+                continue
+        elif key == "v1":
+            signatures.append(value)
+    if timestamp is None:
+        raise WebhookSignatureError("Signature header is missing the timestamp (t=) component")
+    if not signatures:
+        raise WebhookSignatureError("Signature header has no v1 entries")
+    return timestamp, signatures
+
+
+def verify_signature(
+    raw_body: Union[str, bytes],
+    sig_header: str,
+    secret: Union[str, list[str]],
+    *,
+    tolerance: int = DEFAULT_TOLERANCE_SECONDS,
+    now: Optional[Callable[[], int]] = None,
+) -> None:
+    """Verify a webhook signature. Raises on failure; returns ``None`` on success.
+
+    Multiple secrets are accepted so a customer rotating their signing secret
+    can pass ``[previous, current]`` during the overlap window without dropping
+    legitimate deliveries signed under either key.
+
+    :raises WebhookSignatureError: the header is malformed or no signature matched.
+    :raises WebhookTimestampError: the timestamp is outside ``tolerance`` seconds.
+    """
+    timestamp, signatures = _parse_header(sig_header)
+
+    now_fn: Callable[[], int] = now or (lambda: int(time.time()))
+    if abs(now_fn() - timestamp) > tolerance:
+        raise WebhookTimestampError(
+            f"Signature timestamp is outside the tolerance window ({tolerance}s)"
+        )
+
+    secrets = [secret] if isinstance(secret, str) else secret
+    body_bytes = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+    payload = f"{timestamp}.".encode("utf-8") + body_bytes
+
+    for s in secrets:
+        expected = hmac.new(s.encode("utf-8"), payload, hashlib.sha256).hexdigest()
+        for candidate in signatures:
+            # `expected` is lowercase hex (hexdigest); normalize the candidate so
+            # an upper/mixed-case hex digest still matches — the JS SDK compares
+            # decoded bytes, which is inherently case-insensitive.
+            if hmac.compare_digest(expected, candidate.lower()):
+                return
+
+    raise WebhookSignatureError("No signatures matched the expected value")
+
+
+__all__ = [
+    "DEFAULT_TOLERANCE_SECONDS",
+    "EVENT_ID_HEADER",
+    "SIGNATURE_HEADER",
+    "verify_signature",
+]

transcodely/webhooks/types.py

@@ -0,0 +1,115 @@
+"""Public types for the webhook surface.
+
+Python port of the TypeScript SDK's ``webhooks/types.ts`` — the customer-facing
+:class:`Event` shape plus the resource-decoder table shared between the verify
+helper (:func:`transcodely.construct_event`) and the ``client.events`` resource
+bridge. Both paths converge on the same :class:`Event`, so a ``job.succeeded``
+handler behaves identically whether the event arrived over an HTTP delivery or
+was pulled from :meth:`Events.retrieve`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Literal, Mapping, Optional
+
+from google.protobuf.message import Message
+
+from ..resources._helpers import fill_from_dict
+from ..v1 import app_pb2, job_pb2, video_pb2
+
+#: The 13 canonical event types the webhook system can emit, mirroring the API's
+#: ``domain.WebhookEventTypes()``. The ``"*"`` wildcard is intentionally absent —
+#: it is a subscription value only, never the ``type`` of an emitted event. Used
+#: for annotations and documentation; the ``Event.type`` field is a plain ``str``
+#: so an older SDK still parses a ``type`` the API has since added (forward
+#: compatibility).
+EventType = Literal[
+    "job.created",
+    "job.succeeded",
+    "job.failed",
+    "job.canceled",
+    "job.progress",
+    "output.created",
+    "output.ready",
+    "output.failed",
+    "output.progress",
+    "video.uploaded",
+    "video.deleted",
+    "app.created",
+    "app.updated",
+]
+
+
+@dataclass(frozen=True)
+class EventRequest:
+    """The originating API request that triggered an event, if known."""
+
+    #: Request ID (``req_*``), or ``None`` for events emitted outside a request
+    #: scope (worker-callback events like ``job.succeeded`` and every test send).
+    id: Optional[str]
+    #: Idempotency key the original request carried, or ``None``.
+    idempotency_key: Optional[str]
+
+
+@dataclass(frozen=True, kw_only=True)
+class Event:
+    """A webhook event, unified across the HTTP delivery envelope and the API.
+
+    ``data`` carries the decoded resource snapshot — a :class:`~transcodely.Job`,
+    :class:`~transcodely.JobOutput`, :class:`~transcodely.Video`, or
+    :class:`~transcodely.App` for a known ``type``, or the raw ``dict`` for an
+    unrecognized one (forward compatibility).
+    """
+
+    #: Event ID (``evt_*``).
+    id: str
+    #: Resource discriminator. Always ``"event"``.
+    object: str = "event"
+    #: API version at emit time (e.g. ``"2026-05-23"``). Frozen for the event's life.
+    api_version: str
+    #: RFC 3339 UTC timestamp of when the event was created.
+    created: str
+    #: Event type, e.g. ``"job.succeeded"``. See :data:`EventType`.
+    type: str
+    #: The decoded resource snapshot (a proto message, or ``dict`` for unknown types).
+    data: Any
+    #: Delivery attempts still pending across all subscribed endpoints.
+    pending_webhooks: int
+    #: The originating API request.
+    request: EventRequest
+
+
+#: Alias matching the TypeScript SDK's ``WebhookEvent`` name.
+WebhookEvent = Event
+
+Decoder = Callable[[Mapping[str, Any]], Message]
+
+#: Event-type prefix → resource decoder. Shared by ``construct_event`` (verify
+#: path; ``data`` arrives pre-parsed) and the ``events`` resource bridge (API
+#: path; ``data`` arrives as a JSON string on the proto ``Event``). ``output.``
+#: is listed first to make the intent explicit; the prefixes are disjoint.
+RESOURCE_DECODERS: list[tuple[str, Decoder]] = [
+    ("output.", lambda d: fill_from_dict(job_pb2.JobOutput(), d)),
+    ("job.", lambda d: fill_from_dict(job_pb2.Job(), d)),
+    ("video.", lambda d: fill_from_dict(video_pb2.Video(), d)),
+    ("app.", lambda d: fill_from_dict(app_pb2.App(), d)),
+]
+
+
+def decoder_for_type(type: str) -> Optional[Decoder]:
+    """Return a resource decoder for ``type``, or ``None`` if the type is unknown."""
+    for prefix, decode in RESOURCE_DECODERS:
+        if type.startswith(prefix):
+            return decode
+    return None
+
+
+__all__ = [
+    "Event",
+    "EventRequest",
+    "EventType",
+    "RESOURCE_DECODERS",
+    "WebhookEvent",
+    "decoder_for_type",
+]

transcodely-0.2.0.dist-info/METADATA

@@ -0,0 +1,349 @@
+Metadata-Version: 2.4
+Name: transcodely
+Version: 0.2.0
+Summary: Official Python SDK for the Transcodely video transcoding API
+Project-URL: Homepage, https://transcodely.com
+Project-URL: Documentation, https://transcodely.com/docs
+Project-URL: Repository, https://github.com/transcodely/transcodely-python
+Project-URL: Issues, https://github.com/transcodely/transcodely-python/issues
+Author: Transcodely
+License-Expression: MIT
+License-File: LICENSE
+Keywords: connect-rpc,dash,encoding,hls,streaming,transcodely,transcoding,video
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Multimedia :: Video :: Conversion
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: protobuf>=5.0
+Requires-Dist: typing-extensions>=4.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: fast
+Requires-Dist: orjson>=3.10; extra == 'fast'
+Description-Content-Type: text/markdown
+
+# transcodely
+
+Official Python SDK for the [Transcodely](https://transcodely.com) video transcoding API.
+
+```bash
+pip install transcodely
+```
+
+## Quick start
+
+```python
+import os
+from transcodely import Transcodely
+
+with Transcodely(api_key=os.environ["TRANSCODELY_API_KEY"]) as client:
+    job = client.jobs.create(
+        input_url="https://example.com/source.mp4",
+        outputs=[{
+            "type": "hls",
+            "video": [
+                {"codec": "h264", "resolution": "1080p"},
+                {"codec": "h264", "resolution": "720p"},
+            ],
+        }],
+    )
+    print(job.id)  # "job_a1b2c3d4e5f6"
+
+    for event in client.jobs.watch(job.id):
+        print(event.job.status, event.job.progress)
+        if event.job.status == 4:  # JOB_STATUS_COMPLETED
+            break
+```
+
+The simplified-string form (`"hls"`, `"h264"`, `"1080p"`) is what the API actually emits over the wire — the SDK round-trips it transparently to and from the proto enum integers.
+
+## Authentication
+
+```python
+client = Transcodely(api_key=os.environ["TRANSCODELY_API_KEY"])
+```
+
+API keys are opaque `ak_`-prefixed secrets — pass the full value shown once at creation time.
+
+## Resources
+
+```python
+client.jobs            # create / get / list / cancel / confirm / watch
+client.videos          # upload helpers, multipart, get / list / update / delete / watch
+client.presets         # create / get / get_by_slug / list / update / duplicate / archive
+client.origins         # create / get / list / update / validate / archive
+client.apps            # create / get / list / update / archive / enable_hosting
+client.api_keys        # create / get / list / revoke
+client.organizations   # create / get / list / update / check_slug
+client.memberships     # list / get / update_role / remove
+client.users           # get_me / get / list / update_me
+client.health          # check
+client.webhook_endpoints  # create / retrieve / update / delete / list / rotate_secret / send_test / list_deliveries / get_health
+client.events          # retrieve / list / resend
+client.webhooks        # construct_event / verify_signature (signature-verification helpers)
+```
+
+## Origins
+
+An origin tells Transcodely where to read source media from and where to write outputs. Every origin belongs to a single provider; pass exactly one provider-config field (`s3`, `gcs`, `http`, or `r2`) on create.
+
+### Create an S3 origin
+
+```python
+origin = client.origins.create(
+    name="Production S3",
+    permissions=["read", "write"],
+    s3={
+        "bucket": "my-bucket",
+        "region": "us-east-1",
+        "credentials": {
+            "access_key_id": os.environ["S3_ACCESS_KEY"],
+            "secret_access_key": os.environ["S3_SECRET_KEY"],
+        },
+        # "endpoint": "https://s3.custom.example.com",  # for MinIO, Wasabi, etc.
+    },
+)
+```
+
+### Create a GCS origin
+
+```python
+origin = client.origins.create(
+    name="Production GCS",
+    permissions=["read", "write"],
+    gcs={
+        "bucket": "my-gcs-bucket",
+        "credentials": {
+            "service_account_json": os.environ["GCS_SERVICE_ACCOUNT_JSON"],
+        },
+    },
+)
+```
+
+### Create an HTTP origin
+
+```python
+origin = client.origins.create(
+    name="Public CDN",
+    permissions=["read"],  # HTTP origins are read-only
+    http={
+        "base_url": "https://media.example.com",
+        "credentials": {
+            "headers": {"Authorization": f"Bearer {os.environ['MEDIA_TOKEN']}"},
+        },
+    },
+)
+```
+
+### Create an R2 origin
+
+R2 supports two forms. With `account_id` (32-char hex) the endpoint is derived for you, optionally with a data-residency jurisdiction:
+
+```python
+origin = client.origins.create(
+    name="Production R2",
+    permissions=["read", "write"],
+    r2={
+        "bucket": "media",
+        "account_id": os.environ["R2_ACCOUNT_ID"],
+        "jurisdiction": "default",  # or "eu", "fedramp"
+        "credentials": {
+            "access_key_id": os.environ["R2_ACCESS_KEY"],
+            "secret_access_key": os.environ["R2_SECRET_KEY"],
+        },
+    },
+)
+```
+
+Or, with an explicit `endpoint` (custom domain bound to a bucket, or a jurisdiction not yet enumerated):
+
+```python
+r2 = {
+    "bucket": "media",
+    "endpoint": "https://media.example.com",
+    "credentials": {
+        "access_key_id": os.environ["R2_ACCESS_KEY"],
+        "secret_access_key": os.environ["R2_SECRET_KEY"],
+    },
+}
+```
+
+Provide either `account_id` or `endpoint`, never both. `jurisdiction` only applies when `account_id` is set.
+
+## Errors
+
+All exceptions inherit from `TranscodelyError`:
+
+```python
+from transcodely import (
+    Transcodely,
+    TranscodelyError,
+    InvalidRequestError,
+    NotFoundError,
+    RateLimitError,
+)
+
+try:
+    client.jobs.create(input_url=..., outputs=[...])
+except InvalidRequestError as err:
+    for v in err.errors:
+        print(f"{v.field}: {v.description}")
+except RateLimitError as err:
+    time.sleep((err.retry_after_ms or 1000) / 1000)
+except TranscodelyError as err:
+    print(f"[{err.request_id}] {err.code}: {err}")
+```
+
+| Class | Status | When |
+|---|---|---|
+| `APIConnectionError` | — | Network / DNS / TLS failure |
+| `APIError` | 5xx | Server-side error |
+| `AuthenticationError` | 401 | Bad / missing / revoked key |
+| `PermissionError` | 403 | Authenticated but forbidden |
+| `NotFoundError` | 404 | Resource doesn't exist |
+| `ConflictError` | 409 | Idempotency conflict, slug taken |
+| `RateLimitError` | 429 | Carries `retry_after_ms` |
+| `InvalidRequestError` | 400 | Carries `errors: list[FieldViolation]` |
+| `PreconditionError` | 412 | Wrong state (e.g. job not cancelable) |
+
+Every error carries `request_id`, `code`, `http_status`, and `raw` for debugging.
+
+Webhook verification raises `WebhookError` (or a subclass) — see [Webhooks](#webhooks).
+
+## Pagination
+
+```python
+# One page
+page = client.jobs.list(limit=50)
+print(page.items, page.next_cursor)
+
+# All items, automatically across pages
+for job in client.jobs.list(limit=50).auto_paging_iter():
+    print(job.id)
+```
+
+## Idempotency
+
+`jobs.create` accepts `idempotency_key`. If you don't pass one, the SDK generates a UUID v4 so retries are safe by default. For cross-process safety, pass your own:
+
+```python
+client.jobs.create(
+    input_url="...",
+    outputs=[...],
+    idempotency_key="create-job-for-asset-12345",
+)
+```
+
+For all other write methods, the SDK ships an `Idempotency-Key` HTTP header automatically.
+
+## Streaming watch
+
+```python
+for event in client.jobs.watch(job.id):
+    print(event.event, event.job.status, event.job.progress)
+```
+
+The SDK auto-reconnects on transient network failures — Watch is read-only and re-emits a SNAPSHOT on every reconnect. HEARTBEAT events are filtered by default.
+
+## Webhooks
+
+Verify a signed delivery and get back a typed `Event`. Pass the **raw** request body (bytes or str — do not re-serialize) and the `Transcodely-Signature` header:
+
+```python
+from transcodely import construct_event, WebhookSignatureError
+
+try:
+    event = construct_event(
+        request.body,                       # raw bytes/str, exactly as received
+        request.headers["transcodely-signature"],
+        "whsec_...",                        # your endpoint's signing secret
+    )
+except WebhookSignatureError:
+    return Response(status_code=400)
+
+# `event.data` is the decoded resource (a Job, JobOutput, Video, or App).
+if event.type == "job.succeeded":
+    print("job done:", event.data.id)
+elif event.type == "video.uploaded":
+    print("new video:", event.data.id)
+```
+
+`construct_event` also accepts a **list** of secrets so deliveries keep verifying during a secret rotation's overlap window:
+
+```python
+event = construct_event(body, sig_header, ["whsec_previous", "whsec_current"])
+```
+
+Tuning and errors:
+
+- `tolerance` (default `300` seconds) bounds clock skew / replay; widen or narrow it per call.
+- `WebhookSignatureError` — header malformed or no signature matched.
+- `WebhookTimestampError` — timestamp outside the tolerance window.
+- `WebhookPayloadError` — body isn't valid JSON or doesn't match the event envelope.
+
+All three inherit from `WebhookError`. `client.webhooks.construct_event(...)` is an alias for the module-level function.
+
+Manage endpoints and replay events via the API:
+
+```python
+endpoint = client.webhook_endpoints.create(
+    app_id="app_123",
+    url="https://example.com/hooks/transcodely",
+    enabled_events=["job.succeeded", "job.failed"],   # or ["*"] for all
+)
+print(endpoint.secret)   # shown only on create + rotate_secret — store it now
+
+# The same typed Event, fetched from the API instead of an HTTP delivery:
+event = client.events.retrieve("evt_123")
+for event in client.events.list(app_id="app_123").auto_paging_iter():
+    print(event.type, event.id)
+
+client.events.resend("evt_123")   # re-queue delivery to all subscribed endpoints
+```
+
+The 13 event types are `job.created`, `job.succeeded`, `job.failed`, `job.canceled`, `job.progress`, `output.created`, `output.ready`, `output.failed`, `output.progress`, `video.uploaded`, `video.deleted`, `app.created`, and `app.updated`. Subscribe to `"*"` to receive all of them (including ones added later). An unrecognized future type still verifies; its `event.data` is left as a plain `dict`.
+
+## Configuration
+
+```python
+Transcodely(
+    api_key,                    # required
+    base_url=None,              # default: https://api.transcodely.com
+    timeout=30.0,               # seconds
+    max_retries=3,
+    api_version=None,           # override the pinned API version
+    default_headers=None,       # dict, sent on every request
+    http_client=None,           # custom httpx.Client
+    logger=None,                # callable(LogEvent)
+)
+```
+
+## Request IDs
+
+```python
+client.jobs.get("job_x")
+print(client.last_request_id)  # "req_*"
+```
+
+Errors also carry the request ID via `err.request_id` for log correlation.
+
+## Versioning
+
+The SDK follows semver, starting at `0.1.0`. Breaking changes are allowed on minor bumps until `1.0.0`. Each release pins a specific calendar-versioned API (`Transcodely.API_VERSION`) and sends `Transcodely-Version` on every request.
+
+## License
+
+[MIT](LICENSE).