transcodely 0.3.0__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/_helpers.py

@@ -2,12 +2,13 @@
 
 from __future__ import annotations
 
-from typing import Any, Mapping, Optional
+from typing import Any, Mapping, Optional, Union
 
 from google.protobuf import json_format
+from google.protobuf.descriptor import EnumDescriptor
 from google.protobuf.message import Message
 
-from .._codec.json_codec import transform_enums_in_dict
+from .._codec.json_codec import expand_enum_value, simplify_enum_value, transform_enums_in_dict
 
 
 def fill_from_dict(msg: Message, data: Mapping[str, Any]) -> Message:
@@ -22,8 +23,44 @@ def fill_from_dict(msg: Message, data: Mapping[str, Any]) -> Message:
     return msg
 
 
-def assign_pagination(req_pagination: Any, *, limit: Optional[int], cursor: Optional[str]) -> None:
+def resolve_enum(value: Union[int, str], enum_desc: EnumDescriptor) -> int:
+    """Resolve an enum value from either the raw proto int or a string.
+
+    Strings may be the simplified lowercase wire form (``"standard"``,
+    ``"processing"``) or the canonical proto name (``"JOB_PRIORITY_STANDARD"``) —
+    both resolve to the same int via the codec's inbound ``expand`` rule. Ints
+    pass through unchanged (proto3 enums are open, so an unknown int is the
+    caller's responsibility). Used for scalar enum kwargs that are set on a
+    request directly rather than through :func:`fill_from_dict`.
+    """
+    if isinstance(value, bool):  # bool is an int subclass — reject it explicitly.
+        raise TypeError(f"{enum_desc.name} value must be an int or str, got bool: {value!r}")
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        name = expand_enum_value(value, enum_desc)
+        entry = enum_desc.values_by_name.get(name)
+        if entry is None:
+            allowed = ", ".join(
+                simplify_enum_value(v.name, enum_desc) for v in enum_desc.values if v.number != 0
+            )
+            raise ValueError(
+                f"unknown {enum_desc.name} value {value!r}; expected one of: {allowed}"
+            )
+        return int(entry.number)
+    raise TypeError(f"{enum_desc.name} value must be an int or str, got {type(value).__name__}")
+
+
+def assign_pagination(
+    req_pagination: Any,
+    *,
+    limit: Optional[int] = None,
+    cursor: Optional[str] = None,
+    offset: Optional[int] = None,
+) -> None:
     if limit is not None:
         req_pagination.limit = limit
     if cursor is not None:
         req_pagination.cursor = cursor
+    if offset is not None:
+        req_pagination.offset = offset

transcodely/resources/apps.py

@@ -31,11 +31,23 @@ class Apps:
     def list(
         self,
         *,
+        org_id: Optional[str] = None,
         limit: Optional[int] = None,
+        include_archived: Optional[bool] = None,
         opts: Optional[CallOptions] = None,
     ) -> Page[app_pb2.App]:
+        """List apps in an organization.
+
+        ``org_id`` (the parent organization, e.g. ``"org_a1b2c3d4e5"``) is required
+        by the API. Pass ``include_archived=True`` to include archived apps.
+        """
+
         def fetch(cursor: Optional[str]) -> PageContents[app_pb2.App]:
             req = app_pb2.ListAppsRequest()
+            if org_id is not None:
+                req.org_id = org_id
+            if include_archived is not None:
+                req.include_archived = include_archived
             assign_pagination(req.pagination, limit=limit, cursor=cursor)
             res = self._t.unary(_SERVICE, "List", req, app_pb2.ListAppsResponse(), opts)
             return PageContents(
@@ -57,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,12 +2,13 @@
 
 from __future__ import annotations
 
-from typing import Any, Generator, Mapping, Optional
+from typing import Any, Generator, Mapping, Optional, Union, cast
 
 from .._transport.transport import CallOptions, Transport
 from ..pagination import Page, PageContents
 from ..streaming import watch
 from ..v1 import job_pb2
+from ._helpers import assign_pagination, fill_from_dict, resolve_enum
 
 _SERVICE = "transcodely.v1.JobService"
 
@@ -21,35 +22,80 @@ class Jobs:
         input_url: Optional[str] = None,
         outputs: Optional[list[Mapping[str, Any]]] = None,
         *,
-        idempotency_key: Optional[str] = None,
+        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,
-        priority: Optional[int] = 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,
     ) -> job_pb2.Job:
-        """Create a new transcoding job. Auto-fills ``idempotency_key`` if omitted."""
+        """Create a new transcoding job.
+
+        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 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}"``). 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:
-            req = job_pb2.CreateJobRequest()
+            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:
-                req.input_url = input_url
+                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:
-                from google.protobuf import json_format
-
-                from .._codec.json_codec import transform_enums_in_dict
-
-                # Outputs are nested messages — round-trip through JSON so callers can
-                # pass plain dicts with simplified-enum strings.
-                payload = {"outputs": list(outputs)}
-                transform_enums_in_dict(payload, req.DESCRIPTOR, mode="expand")
-                json_format.ParseDict(payload, req, ignore_unknown_fields=True)
-            if webhook_url is not None:
-                req.webhook_url = webhook_url
+                payload["outputs"] = list(outputs)
             if priority is not None:
-                req.priority = priority
+                payload["priority"] = priority
+            if delayed_start is not None:
+                payload["delayed_start"] = delayed_start
+            if webhook_url is not None:
+                payload["webhook_url"] = webhook_url
             if metadata:
-                for k, v in metadata.items():
-                    req.metadata[k] = v
+                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:
@@ -66,22 +112,38 @@ class Jobs:
     def list(
         self,
         *,
-        status: Optional[int] = None,
+        status: Optional[Union[int, str]] = None,
         limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        pagination: Optional[Mapping[str, Any]] = None,
         opts: Optional[CallOptions] = None,
     ) -> Page[job_pb2.Job]:
-        from ..v1 import common_pb2
+        """List jobs, optionally filtered by ``status``.
+
+        ``status`` accepts the simplified lowercase string (``"processing"``) or the
+        raw ``JobStatus`` int. Pagination may be given as ``limit`` / ``offset``
+        keyword args or as a ``pagination={"limit": ..., "offset": ..., "cursor": ...}``
+        mapping; explicit keyword args take precedence over the mapping.
+        """
+        status_value = (
+            resolve_enum(status, job_pb2.JobStatus.DESCRIPTOR) if status is not None else None
+        )
+        pag = dict(pagination) if pagination else {}
+        eff_limit = limit if limit is not None else pag.get("limit")
+        eff_offset = offset if offset is not None else pag.get("offset")
+        start_cursor = pag.get("cursor")
 
         def fetch(cursor: Optional[str]) -> PageContents[job_pb2.Job]:
             req = job_pb2.ListJobsRequest()
-            if status is not None:
-                req.status = status
-            pagination = common_pb2.PaginationRequest()
-            if limit is not None:
-                pagination.limit = limit
-            if cursor is not None:
-                pagination.cursor = cursor
-            req.pagination.CopyFrom(pagination)
+            if status_value is not None:
+                # 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,
+                cursor=cursor if cursor is not None else start_cursor,
+                offset=eff_offset,
+            )
             res = self._t.unary(_SERVICE, "List", req, job_pb2.ListJobsResponse(), opts)
             return PageContents(
                 items=list(res.jobs),

transcodely/resources/memberships.py

@@ -2,12 +2,12 @@
 
 from __future__ import annotations
 
-from typing import Any, Optional
+from typing import Any, Optional, Union, cast
 
 from .._transport.transport import CallOptions, Transport
 from ..pagination import Page, PageContents
 from ..v1 import membership_pb2
-from ._helpers import assign_pagination, fill_from_dict
+from ._helpers import assign_pagination, fill_from_dict, resolve_enum
 
 _SERVICE = "transcodely.v1.MembershipService"
 
@@ -19,11 +19,26 @@ class Memberships:
     def list(
         self,
         *,
+        status: Optional[Union[int, str]] = None,
         limit: Optional[int] = None,
         opts: Optional[CallOptions] = None,
     ) -> Page[membership_pb2.MembershipWithUser]:
+        """List memberships, optionally filtered by ``status``.
+
+        ``status`` accepts the simplified lowercase string (``"active"``,
+        ``"invited"``, ``"suspended"``) or the raw ``MembershipStatus`` int.
+        """
+        status_value = (
+            resolve_enum(status, membership_pb2.MembershipStatus.DESCRIPTOR)
+            if status is not None
+            else None
+        )
+
         def fetch(cursor: Optional[str]) -> PageContents[membership_pb2.MembershipWithUser]:
             req = membership_pb2.ListMembershipsRequest()
+            if status_value is not None:
+                # 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,12 +2,12 @@
 
 from __future__ import annotations
 
-from typing import Any, Optional
+from typing import Any, Optional, Union, cast
 
 from .._transport.transport import CallOptions, Transport
 from ..pagination import Page, PageContents
 from ..v1 import user_pb2
-from ._helpers import assign_pagination, fill_from_dict
+from ._helpers import assign_pagination, fill_from_dict, resolve_enum
 
 _SERVICE = "transcodely.v1.UserService"
 
@@ -32,11 +32,24 @@ class Users:
     def list(
         self,
         *,
+        status: Optional[Union[int, str]] = None,
         limit: Optional[int] = None,
         opts: Optional[CallOptions] = None,
     ) -> Page[user_pb2.User]:
+        """List users, optionally filtered by ``status``.
+
+        ``status`` accepts the simplified lowercase string (``"active"``,
+        ``"suspended"``, ``"deleted"``) or the raw ``UserStatus`` int.
+        """
+        status_value = (
+            resolve_enum(status, user_pb2.UserStatus.DESCRIPTOR) if status is not None else None
+        )
+
         def fetch(cursor: Optional[str]) -> PageContents[user_pb2.User]:
             req = user_pb2.ListUsersRequest()
+            if status_value is not None:
+                # 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())