transcodely 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

transcodely/__init__.py

@@ -68,11 +68,18 @@ from .types import (
     App,
     AudioTrackConfig,
     AutoABRConfig,
+    ChapterPoint,
+    ChapterResult,
+    ClipConfig,
     ContentAwareConfig,
     DASHConfig,
     DRMConfig,
     HDRConfig,
     HLSConfig,
+    Invoice,
+    InvoiceLineItem,
+    InvoiceLineType,
+    InvoiceStatus,
     Job,
     JobOutput,
     JobPriority,
@@ -87,6 +94,7 @@ from .types import (
     PresetVariant,
     Resolution,
     StreamingConfig,
+    SubtitleResult,
     SubtitleTrack,
     ThumbnailResult,
     ThumbnailSpec,
@@ -95,10 +103,12 @@ from .types import (
     Video,
     VideoCodec,
     VideoRendition,
+    VideoTextTrack,
     VideoVariant,
     WatchEventType,
     WatchJobResponse,
     WatchVideoResponse,
+    WatermarkConfig,
     WebhookDelivery,
     WebhookEndpoint,
 )
@@ -112,6 +122,9 @@ __all__ = [
     "AudioTrackConfig",
     "AuthenticationError",
     "AutoABRConfig",
+    "ChapterPoint",
+    "ChapterResult",
+    "ClipConfig",
     "ConflictError",
     "construct_event",
     "ContentAwareConfig",
@@ -127,6 +140,10 @@ __all__ = [
     "HDRConfig",
     "HLSConfig",
     "InvalidRequestError",
+    "Invoice",
+    "InvoiceLineItem",
+    "InvoiceLineType",
+    "InvoiceStatus",
     "Job",
     "JobOutput",
     "JobPriority",
@@ -149,6 +166,7 @@ __all__ = [
     "SDK_VERSION",
     "SIGNATURE_HEADER",
     "StreamingConfig",
+    "SubtitleResult",
     "SubtitleTrack",
     "ThumbnailResult",
     "ThumbnailSpec",
@@ -160,10 +178,12 @@ __all__ = [
     "Video",
     "VideoCodec",
     "VideoRendition",
+    "VideoTextTrack",
     "VideoVariant",
     "WatchEventType",
     "WatchJobResponse",
     "WatchVideoResponse",
+    "WatermarkConfig",
     "WebhookDelivery",
     "WebhookEndpoint",
     "WebhookError",

transcodely/_transport/transport.py

@@ -71,6 +71,7 @@ class Transport:
         self,
         api_key: str,
         *,
+        organization_id: Optional[str] = None,
         base_url: Optional[str] = None,
         timeout: float = 30.0,
         max_retries: int = 3,
@@ -82,6 +83,7 @@ class Transport:
         if not api_key:
             raise ValueError("Transcodely: api_key is required")
         self.api_key = api_key
+        self.organization_id = organization_id
         self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
         self.timeout = timeout
         self.max_retries = max_retries
@@ -218,6 +220,8 @@ class Transport:
             "transcodely-version": opts.api_version or self.api_version,
             "accept": content_type,
         }
+        if self.organization_id:
+            headers["x-organization-id"] = self.organization_id
         if idempotency_key:
             headers["idempotency-key"] = idempotency_key
         headers.update(self.default_headers)

transcodely/client.py

@@ -9,6 +9,7 @@ import httpx
 from ._transport.transport import LogEvent, Transport
 from .resources.api_keys import ApiKeys
 from .resources.apps import Apps
+from .resources.billing import Billing
 from .resources.events import Events
 from .resources.health import Health
 from .resources.jobs import Jobs
@@ -37,6 +38,7 @@ class Transcodely:
         self,
         api_key: str,
         *,
+        organization_id: Optional[str] = None,
         base_url: Optional[str] = None,
         timeout: float = 30.0,
         max_retries: int = 3,
@@ -47,6 +49,7 @@ class Transcodely:
     ) -> None:
         self._transport = Transport(
             api_key,
+            organization_id=organization_id,
             base_url=base_url,
             timeout=timeout,
             max_retries=max_retries,
@@ -67,6 +70,7 @@ class Transcodely:
         self._health: Optional[Health] = None
         self._webhook_endpoints: Optional[WebhookEndpoints] = None
         self._events: Optional[Events] = None
+        self._billing: Optional[Billing] = None
 
     def close(self) -> None:
         self._transport.close()
@@ -154,6 +158,18 @@ class Transcodely:
             self._events = Events(self._transport)
         return self._events
 
+    @property
+    def billing(self) -> Billing:
+        """The organization's invoices.
+
+        Needs a dashboard session token for an organization owner plus
+        ``organization_id`` on the client; API keys are rejected. See
+        :class:`~transcodely.resources.billing.Billing`.
+        """
+        if self._billing is None:
+            self._billing = Billing(self._transport)
+        return self._billing
+
     @property
     def webhooks(self) -> type[Webhooks]:
         """Stripe-style facade: ``client.webhooks.construct_event(body, sig, secret)``."""

transcodely/resources/apps.py

@@ -69,3 +69,50 @@ class Apps:
         return self._t.unary(
             _SERVICE, "UpdateHostingConfig", req, app_pb2.UpdateHostingConfigResponse()
         )
+
+    def update_spend_limit(
+        self,
+        app_id: str,
+        monthly_spend_limit_eur: Optional[float] = None,
+        opts: Optional[CallOptions] = None,
+    ) -> app_pb2.App:
+        """Set or clear an app's monthly transcoding spend cap.
+
+        Pass ``monthly_spend_limit_eur`` (must be > 0) to set the cap, or leave it
+        ``None`` to clear the cap and return the app to unlimited. ``set_spend_limit``
+        and ``clear_spend_limit`` are the ergonomic shorthands.
+        """
+        req = app_pb2.UpdateSpendLimitRequest(app_id=app_id)
+        if monthly_spend_limit_eur is not None:
+            # Setting the optional field marks presence; leaving it unset omits it
+            # from the request, which the server reads as "clear the cap".
+            req.monthly_spend_limit_eur = monthly_spend_limit_eur
+        return self._t.unary(
+            _SERVICE, "UpdateSpendLimit", req, app_pb2.UpdateSpendLimitResponse(), opts
+        ).app
+
+    def set_spend_limit(
+        self, app_id: str, monthly_spend_limit_eur: float, opts: Optional[CallOptions] = None
+    ) -> app_pb2.App:
+        """Set the app's monthly transcoding spend cap in EUR (must be > 0).
+
+        Once recorded spend for the current billing period reaches the cap, new
+        jobs are rejected with the ``limit_exceeded`` error code; in-flight jobs
+        are never stopped. Use :meth:`clear_spend_limit` to return to unlimited.
+        """
+        return self.update_spend_limit(app_id, monthly_spend_limit_eur, opts)
+
+    def clear_spend_limit(self, app_id: str, opts: Optional[CallOptions] = None) -> app_pb2.App:
+        """Clear the app's monthly spend cap, returning it to unlimited (the default)."""
+        return self.update_spend_limit(app_id, None, opts)
+
+    def get_spend(
+        self, app_id: str, opts: Optional[CallOptions] = None
+    ) -> app_pb2.GetSpendResponse:
+        """Get the app's current-period transcoding spend against its limit.
+
+        Returns the billing-period bounds, EUR spent so far, the cap (if set), and
+        whether the 80% warning and 100% breach events have fired this period.
+        """
+        req = app_pb2.GetSpendRequest(app_id=app_id)
+        return self._t.unary(_SERVICE, "GetSpend", req, app_pb2.GetSpendResponse(), opts)

transcodely/resources/billing.py

@@ -0,0 +1,92 @@
+"""Billing resource — an organization's invoices, read-only."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .._transport.transport import CallOptions, Transport
+from ..pagination import Page, PageContents
+from ..v1 import billing_pb2
+from ._helpers import assign_pagination
+
+_SERVICE = "transcodely.v1.BillingService"
+
+
+class Billing:
+    """An organization's billing statements.
+
+    Unlike every other resource, billing settles a whole organization rather
+    than a single app, so it is **not** available to API-key callers: a key is
+    scoped to one app, and there is no app-scoped subset of an invoice worth
+    serving. An API key gets a :class:`~transcodely.errors.PermissionError`.
+
+    Reading invoices needs a dashboard session token for an organization
+    **owner**, plus the organization the request is for::
+
+        client = Transcodely(session_token, organization_id="org_f6g7h8i9j0")
+        upcoming = client.billing.retrieve_upcoming()
+
+    Invoices are generated automatically when a period closes. There is no API
+    to create, edit, or delete one — a statement records what happened.
+
+    Monetary amounts are integer minor units (cents) of the invoice currency:
+    ``total_cents == 1250`` in EUR is 12.50 EUR.
+    """
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def list_invoices(
+        self,
+        *,
+        limit: Optional[int] = None,
+        opts: Optional[CallOptions] = None,
+    ) -> Page[billing_pb2.Invoice]:
+        """Page through finalized invoices, newest period first.
+
+        Line items are omitted here — use :meth:`retrieve` for one invoice's
+        breakdown. A statement still being generated for a just-ended period is
+        never returned; for the period currently accruing use
+        :meth:`retrieve_upcoming`.
+        """
+
+        def fetch(cursor: Optional[str]) -> PageContents[billing_pb2.Invoice]:
+            req = billing_pb2.ListInvoicesRequest()
+            assign_pagination(req.pagination, limit=limit, cursor=cursor)
+            res = self._t.unary(
+                _SERVICE, "ListInvoices", req, billing_pb2.ListInvoicesResponse(), opts
+            )
+            return PageContents(
+                items=list(res.invoices),
+                next_cursor=res.pagination.next_cursor or None,
+            )
+
+        return Page(fetch)
+
+    def retrieve(self, invoice_id: str, opts: Optional[CallOptions] = None) -> billing_pb2.Invoice:
+        """Retrieve one invoice by ID (``inv_*``), including its line items."""
+        req = billing_pb2.GetInvoiceRequest(id=invoice_id)
+        return self._t.unary(
+            _SERVICE,
+            "GetInvoice",
+            req,
+            billing_pb2.GetInvoiceResponse(),
+            opts,
+        ).invoice
+
+    def retrieve_upcoming(self, opts: Optional[CallOptions] = None) -> billing_pb2.Invoice:
+        """Retrieve the statement for the period currently accruing.
+
+        Computed live from settled jobs rather than stored, so its ``id`` is
+        empty, its status is ``draft``, and its totals move as jobs finish. Jobs
+        still running are not included at any price — a job is billed only once
+        it settles.
+        """
+        req = billing_pb2.GetUpcomingInvoiceRequest()
+        return self._t.unary(
+            _SERVICE,
+            "GetUpcomingInvoice",
+            req,
+            billing_pb2.GetUpcomingInvoiceResponse(),
+            opts,
+        ).invoice

transcodely/resources/jobs.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any, Generator, Mapping, Optional, Union
+from typing import Any, Generator, Mapping, Optional, Union, cast
 
 from .._transport.transport import CallOptions, Transport
 from ..pagination import Page, PageContents
@@ -24,12 +24,15 @@ class Jobs:
         *,
         output_origin_id: Optional[str] = None,
         output_path_template: Optional[str] = None,
+        managed: Optional[bool] = None,
         input_origin_id: Optional[str] = None,
         input_path: Optional[str] = None,
+        input_video_id: Optional[str] = None,
         priority: Optional[Union[int, str]] = None,
         delayed_start: Optional[bool] = None,
         webhook_url: Optional[str] = None,
         metadata: Optional[Mapping[str, str]] = None,
+        clip: Optional[Union[job_pb2.ClipConfig, Mapping[str, Any]]] = None,
         idempotency_key: Optional[str] = None,
         request: Optional[job_pb2.CreateJobRequest] = None,
         opts: Optional[CallOptions] = None,
@@ -39,25 +42,46 @@ class Jobs:
         Keyword arguments mirror the API's snake_case fields. Enum-valued fields —
         ``priority`` here, plus any enum inside ``outputs`` dicts — accept either the
         simplified lowercase string (``"standard"``, ``"h264"``) or the raw proto int.
-        Provide inputs via ``input_url`` (direct URL) OR ``input_origin_id`` +
-        ``input_path`` (origin mode); the server rejects both. Pass a fully-built
-        ``request=`` to bypass the convenience kwargs entirely. ``idempotency_key`` is
+        Provide inputs via exactly one of: ``input_url`` (direct URL),
+        ``input_origin_id`` + ``input_path`` (origin mode), or ``input_video_id``
+        (a hosted ``vid_`` video, e.g. to retro-caption it); the server rejects
+        more than one. Pass a fully-built ``request=`` to bypass the convenience
+        kwargs entirely. ``idempotency_key`` is
         auto-filled with a uuid4 when omitted. ``output_path_template`` overrides where
         rendered outputs are written within the output origin (e.g.
-        ``"videos/{job_id}/{output}"``).
+        ``"videos/{job_id}/{output}"``). Set ``managed=True`` to write outputs to
+        Transcodely-managed hosting storage and create a video record; managed apps do
+        not require an ``output_origin_id``.
+
+        ``clip`` trims the input to a sub-range before encoding — pass a
+        :class:`~transcodely.types.ClipConfig` or a plain dict like
+        ``{"start_seconds": 2, "end_seconds": 7}``. It applies job-wide (every output
+        and thumbnails/sprites are computed within the range) and reduces cost, since
+        billing keys off the produced output duration. Omit ``end_seconds`` (or leave it
+        ``0``) to encode through to the end of the input; a range outside the probed
+        input duration fails the job at probe time with ``input_clip_out_of_range``.
         """
         if request is None:
             payload: dict[str, Any] = {}
+            clip_msg: Optional[job_pb2.ClipConfig] = None
+            if isinstance(clip, job_pb2.ClipConfig):
+                clip_msg = clip
+            elif clip is not None:
+                payload["clip"] = dict(clip)
             if input_url is not None:
                 payload["input_url"] = input_url
             if input_origin_id is not None:
                 payload["input_origin_id"] = input_origin_id
             if input_path is not None:
                 payload["input_path"] = input_path
+            if input_video_id is not None:
+                payload["input_video_id"] = input_video_id
             if output_origin_id is not None:
                 payload["output_origin_id"] = output_origin_id
             if output_path_template is not None:
                 payload["output_path_template"] = output_path_template
+            if managed is not None:
+                payload["managed"] = managed
             if outputs:
                 payload["outputs"] = list(outputs)
             if priority is not None:
@@ -70,6 +94,8 @@ class Jobs:
                 payload["metadata"] = dict(metadata)
             req = job_pb2.CreateJobRequest()
             fill_from_dict(req, payload)
+            if clip_msg is not None:
+                req.clip.CopyFrom(clip_msg)
         else:
             req = request
         if not req.idempotency_key:
@@ -110,7 +136,8 @@ class Jobs:
         def fetch(cursor: Optional[str]) -> PageContents[job_pb2.Job]:
             req = job_pb2.ListJobsRequest()
             if status_value is not None:
-                req.status = status_value
+                # resolve_enum returns a plain int; the field is typed as the enum.
+                req.status = cast("job_pb2.JobStatus", status_value)
             assign_pagination(
                 req.pagination,
                 limit=eff_limit,

transcodely/resources/memberships.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any, Optional, Union
+from typing import Any, Optional, Union, cast
 
 from .._transport.transport import CallOptions, Transport
 from ..pagination import Page, PageContents
@@ -37,7 +37,8 @@ class Memberships:
         def fetch(cursor: Optional[str]) -> PageContents[membership_pb2.MembershipWithUser]:
             req = membership_pb2.ListMembershipsRequest()
             if status_value is not None:
-                req.status = status_value
+                # resolve_enum returns a plain int; the field is typed as the enum.
+                req.status = cast("membership_pb2.MembershipStatus", status_value)
             assign_pagination(req.pagination, limit=limit, cursor=cursor)
             res = self._t.unary(
                 _SERVICE, "List", req, membership_pb2.ListMembershipsResponse(), opts

transcodely/resources/users.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any, Optional, Union
+from typing import Any, Optional, Union, cast
 
 from .._transport.transport import CallOptions, Transport
 from ..pagination import Page, PageContents
@@ -48,7 +48,8 @@ class Users:
         def fetch(cursor: Optional[str]) -> PageContents[user_pb2.User]:
             req = user_pb2.ListUsersRequest()
             if status_value is not None:
-                req.status = status_value
+                # resolve_enum returns a plain int; the field is typed as the enum.
+                req.status = cast("user_pb2.UserStatus", status_value)
             assign_pagination(req.pagination, limit=limit, cursor=cursor)
             res = self._t.unary(_SERVICE, "List", req, user_pb2.ListUsersResponse(), opts)
             return PageContents(

transcodely/resources/videos.py

@@ -25,6 +25,20 @@ class Videos:
         req = fill_from_dict(video_pb2.CompleteUploadRequest(), kwargs)
         return self._t.unary(_SERVICE, "CompleteUpload", req, video_pb2.CompleteUploadResponse())
 
+    def create_from_url(self, **kwargs: Any) -> video_pb2.Video:
+        """One-call video ingest from a publicly-reachable http(s) URL.
+
+        No upload step: the API records the video in "processing" and hands
+        the URL to the transcoding pipeline. Returns the ``Video`` directly
+        (``CreateFromUrlResponse`` carries nothing else) — playback/embed
+        URLs populate once it reaches "ready" (watch it or subscribe to
+        ``video.ready``).
+        """
+        req = fill_from_dict(video_pb2.CreateFromUrlRequest(), kwargs)
+        return self._t.unary(
+            _SERVICE, "CreateFromUrl", req, video_pb2.CreateFromUrlResponse()
+        ).video
+
     def create_multipart_upload(self, **kwargs: Any) -> video_pb2.CreateMultipartUploadResponse:
         req = fill_from_dict(video_pb2.CreateMultipartUploadRequest(), kwargs)
         return self._t.unary(
@@ -112,3 +126,28 @@ class Videos:
     def get_usage(self, **kwargs: Any) -> video_pb2.GetUsageResponse:
         req = fill_from_dict(video_pb2.GetUsageRequest(), kwargs)
         return self._t.unary(_SERVICE, "GetUsage", req, video_pb2.GetUsageResponse())
+
+    def get_stats(self, **kwargs: Any) -> video_pb2.GetStatsResponse:
+        """Playback analytics for a single video: plays, watch time, and unique
+        viewers per UTC day, plus range totals.
+
+        Pass ``video_id`` (required) and optional ``start_date`` / ``end_date``
+        (inclusive, ``YYYY-MM-DD``). Returns the full ``GetStatsResponse`` —
+        ``.daily`` holds per-day rows (oldest first, activity-only, no zero-fill)
+        and ``.totals`` the range aggregate. Stats are best-effort and roll up
+        hourly, so recent activity can lag by up to an hour.
+        """
+        req = fill_from_dict(video_pb2.GetStatsRequest(), kwargs)
+        return self._t.unary(_SERVICE, "GetStats", req, video_pb2.GetStatsResponse())
+
+    def list_top_videos(self, **kwargs: Any) -> video_pb2.ListTopVideosResponse:
+        """An app's top videos ranked by plays over a date range.
+
+        Optional kwargs: ``app_id`` (API-key callers may omit it — their key's
+        app is used), ``start_date`` / ``end_date`` (inclusive, ``YYYY-MM-DD``),
+        and ``limit`` (1-100, default 10). Returns the full
+        ``ListTopVideosResponse`` — ``.items`` is the ranked list of
+        ``TopVideo`` rows (by plays, then watch time, descending).
+        """
+        req = fill_from_dict(video_pb2.ListTopVideosRequest(), kwargs)
+        return self._t.unary(_SERVICE, "ListTopVideos", req, video_pb2.ListTopVideosResponse())