transcodely 0.3.1__tar.gz → 0.3.2__tar.gz

{transcodely-0.3.1 → transcodely-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: transcodely
-Version: 0.3.1
+Version: 0.3.2
 Summary: Official Python SDK for the Transcodely video transcoding API
 Project-URL: Homepage, https://transcodely.com
 Project-URL: Documentation, https://transcodely.com/docs
@@ -30,7 +30,7 @@ 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'
+Requires-Dist: ruff<0.16,>=0.5; extra == 'dev'
 Provides-Extra: fast
 Requires-Dist: orjson>=3.10; extra == 'fast'
 Description-Content-Type: text/markdown
@@ -52,6 +52,7 @@ 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",
+        managed=True,  # write outputs to Transcodely-managed storage
         outputs=[{
             "type": "hls",
             "video": [
@@ -59,6 +60,10 @@ with Transcodely(api_key=os.environ["TRANSCODELY_API_KEY"]) as client:
                 {"codec": "h264", "resolution": "720p"},
             ],
         }],
+        # Optional: encode only a sub-range of the input. Applies job-wide and
+        # reduces cost (billing keys off the produced output duration). Omit
+        # "end_seconds" (or leave 0) to encode through to the end of the input.
+        clip={"start_seconds": 2, "end_seconds": 7},
     )
     print(job.id)  # "job_a1b2c3d4e5f6"
 
@@ -70,6 +75,35 @@ with Transcodely(api_key=os.environ["TRANSCODELY_API_KEY"]) as client:
 
 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.
 
+## AI captions
+
+Add auto-generated captions to any output with a `generate` subtitle track. Leave `language` empty (or set `"auto"`) to auto-detect the spoken language, or pass an ISO 639-2 code to force one. A per-job fee is metered by source minute and surfaced on `job.fees`; produced captions appear on `job.subtitle_results` with `auto_generated=True`.
+
+```python
+# Generate captions while transcoding a new source.
+client.jobs.create(
+    input_url="https://example.com/source.mp4",
+    managed=True,
+    outputs=[{
+        "type": "hls",
+        "video": [{"codec": "h264", "resolution": "1080p"}],
+        "subtitle_tracks": [{"operation": "generate", "language": "auto"}],
+    }],
+)
+
+# Retro-caption a video you've already hosted: reference it by input_video_id and
+# request a single captions-only output (no video encode).
+job = client.jobs.create(
+    input_video_id="vid_a1b2c3d4e5f6g7",
+    outputs=[{"subtitle_tracks": [{"operation": "generate"}]}],
+)
+
+for result in job.subtitle_results:
+    print(result.language, result.auto_generated, result.url)
+for fee in job.fees:
+    print(fee.fee_type, fee.amount, fee.currency)  # "captions" 0.51 "eur"
+```
+
 ## Authentication
 
 ```python
@@ -82,7 +116,7 @@ API keys are opaque `ak_`-prefixed secrets — pass the full value shown once at
 
 ```python
 client.jobs            # create / get / list / cancel / confirm / watch
-client.videos          # upload helpers, multipart, get / list / update / delete / watch
+client.videos          # upload helpers, multipart, create_from_url, get / list / update / delete / watch, get_stats / list_top_videos
 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
@@ -96,6 +130,55 @@ client.events          # retrieve / list / resend
 client.webhooks        # construct_event / verify_signature (signature-verification helpers)
 ```
 
+## Videos
+
+### One-call ingest from a URL
+
+`create_from_url` skips the upload dance entirely: give it a publicly-reachable
+`http(s)` URL and the worker fetches it at transcode time. Requires an app with
+managed hosting enabled (`client.apps.enable_hosting(...)`).
+
+```python
+video = client.videos.create_from_url(
+    app_id="app_default000",
+    url="https://example.com/source.mp4",
+    title="Product demo",
+)
+print(video.id, video.status)  # "processing" — no upload step
+
+for event in client.videos.watch(video.id):
+    if event.video.status == "ready":
+        print(event.video.playback_url, event.video.embed_url)
+        break
+```
+
+No `video.uploaded` event fires for URL ingest (no bytes are uploaded to the
+API) — subscribe to `video.ready` / `video.failed` instead to know when it's
+playable.
+
+### Playback analytics
+
+`get_stats` returns a single video's playback stats — plays, watch time, and
+unique viewers — aggregated per UTC day, plus range totals. `list_top_videos`
+ranks an app's videos by plays over a date range. Both accept optional
+`start_date` / `end_date` (`YYYY-MM-DD`, inclusive); stats are best-effort and
+roll up hourly, so recent activity can lag by up to an hour.
+
+```python
+stats = client.videos.get_stats(
+    video_id="vid_abc123def456",
+    start_date="2026-07-01",
+    end_date="2026-07-16",
+)
+for day in stats.daily:
+    print(day.date, day.plays, day.watch_seconds, day.unique_viewers)
+print("range totals:", stats.totals.plays, stats.totals.watch_seconds)
+
+top = client.videos.list_top_videos(app_id="app_default000", limit=10)
+for video in top.items:
+    print(video.video_id, video.title, video.plays, video.watch_seconds)
+```
+
 ## 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.
@@ -314,7 +397,7 @@ for event in client.events.list(app_id="app_123").auto_paging_iter():
 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`.
+The 17 event types are `job.created`, `job.succeeded`, `job.failed`, `job.canceled`, `job.progress`, `output.created`, `output.ready`, `output.failed`, `output.progress`, `video.uploaded`, `video.ready`, `video.failed`, `video.deleted`, `app.created`, `app.updated`, `app.spend_limit_warning`, and `app.spend_limit_exceeded`. 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`. The two `app.spend_limit_*` events also carry a plain `dict` (`app_id`, `period_start`, `period_end`, `limit_eur`, `spent_eur`, `threshold_pct`, `currency`), not a resource snapshot.
 
 ## Configuration
 

{transcodely-0.3.1 → transcodely-0.3.2}/README.md

@@ -15,6 +15,7 @@ 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",
+        managed=True,  # write outputs to Transcodely-managed storage
         outputs=[{
             "type": "hls",
             "video": [
@@ -22,6 +23,10 @@ with Transcodely(api_key=os.environ["TRANSCODELY_API_KEY"]) as client:
                 {"codec": "h264", "resolution": "720p"},
             ],
         }],
+        # Optional: encode only a sub-range of the input. Applies job-wide and
+        # reduces cost (billing keys off the produced output duration). Omit
+        # "end_seconds" (or leave 0) to encode through to the end of the input.
+        clip={"start_seconds": 2, "end_seconds": 7},
     )
     print(job.id)  # "job_a1b2c3d4e5f6"
 
@@ -33,6 +38,35 @@ with Transcodely(api_key=os.environ["TRANSCODELY_API_KEY"]) as client:
 
 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.
 
+## AI captions
+
+Add auto-generated captions to any output with a `generate` subtitle track. Leave `language` empty (or set `"auto"`) to auto-detect the spoken language, or pass an ISO 639-2 code to force one. A per-job fee is metered by source minute and surfaced on `job.fees`; produced captions appear on `job.subtitle_results` with `auto_generated=True`.
+
+```python
+# Generate captions while transcoding a new source.
+client.jobs.create(
+    input_url="https://example.com/source.mp4",
+    managed=True,
+    outputs=[{
+        "type": "hls",
+        "video": [{"codec": "h264", "resolution": "1080p"}],
+        "subtitle_tracks": [{"operation": "generate", "language": "auto"}],
+    }],
+)
+
+# Retro-caption a video you've already hosted: reference it by input_video_id and
+# request a single captions-only output (no video encode).
+job = client.jobs.create(
+    input_video_id="vid_a1b2c3d4e5f6g7",
+    outputs=[{"subtitle_tracks": [{"operation": "generate"}]}],
+)
+
+for result in job.subtitle_results:
+    print(result.language, result.auto_generated, result.url)
+for fee in job.fees:
+    print(fee.fee_type, fee.amount, fee.currency)  # "captions" 0.51 "eur"
+```
+
 ## Authentication
 
 ```python
@@ -45,7 +79,7 @@ API keys are opaque `ak_`-prefixed secrets — pass the full value shown once at
 
 ```python
 client.jobs            # create / get / list / cancel / confirm / watch
-client.videos          # upload helpers, multipart, get / list / update / delete / watch
+client.videos          # upload helpers, multipart, create_from_url, get / list / update / delete / watch, get_stats / list_top_videos
 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
@@ -59,6 +93,55 @@ client.events          # retrieve / list / resend
 client.webhooks        # construct_event / verify_signature (signature-verification helpers)
 ```
 
+## Videos
+
+### One-call ingest from a URL
+
+`create_from_url` skips the upload dance entirely: give it a publicly-reachable
+`http(s)` URL and the worker fetches it at transcode time. Requires an app with
+managed hosting enabled (`client.apps.enable_hosting(...)`).
+
+```python
+video = client.videos.create_from_url(
+    app_id="app_default000",
+    url="https://example.com/source.mp4",
+    title="Product demo",
+)
+print(video.id, video.status)  # "processing" — no upload step
+
+for event in client.videos.watch(video.id):
+    if event.video.status == "ready":
+        print(event.video.playback_url, event.video.embed_url)
+        break
+```
+
+No `video.uploaded` event fires for URL ingest (no bytes are uploaded to the
+API) — subscribe to `video.ready` / `video.failed` instead to know when it's
+playable.
+
+### Playback analytics
+
+`get_stats` returns a single video's playback stats — plays, watch time, and
+unique viewers — aggregated per UTC day, plus range totals. `list_top_videos`
+ranks an app's videos by plays over a date range. Both accept optional
+`start_date` / `end_date` (`YYYY-MM-DD`, inclusive); stats are best-effort and
+roll up hourly, so recent activity can lag by up to an hour.
+
+```python
+stats = client.videos.get_stats(
+    video_id="vid_abc123def456",
+    start_date="2026-07-01",
+    end_date="2026-07-16",
+)
+for day in stats.daily:
+    print(day.date, day.plays, day.watch_seconds, day.unique_viewers)
+print("range totals:", stats.totals.plays, stats.totals.watch_seconds)
+
+top = client.videos.list_top_videos(app_id="app_default000", limit=10)
+for video in top.items:
+    print(video.video_id, video.title, video.plays, video.watch_seconds)
+```
+
 ## 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.
@@ -277,7 +360,7 @@ for event in client.events.list(app_id="app_123").auto_paging_iter():
 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`.
+The 17 event types are `job.created`, `job.succeeded`, `job.failed`, `job.canceled`, `job.progress`, `output.created`, `output.ready`, `output.failed`, `output.progress`, `video.uploaded`, `video.ready`, `video.failed`, `video.deleted`, `app.created`, `app.updated`, `app.spend_limit_warning`, and `app.spend_limit_exceeded`. 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`. The two `app.spend_limit_*` events also carry a plain `dict` (`app_id`, `period_start`, `period_end`, `limit_eur`, `spent_eur`, `threshold_pct`, `currency`), not a resource snapshot.
 
 ## Configuration
 

{transcodely-0.3.1 → transcodely-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "transcodely"
-version = "0.3.1"
+version = "0.3.2"
 description = "Official Python SDK for the Transcodely video transcoding API"
 readme = "README.md"
 license = "MIT"
@@ -37,7 +37,12 @@ fast = ["orjson>=3.10"]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
-    "ruff>=0.5",
+    # Upper bound is deliberate: ruff 0.16 promoted UP007/UP045 (and others) into
+    # its default rule set, which flags the Optional[...]/Union[...] style used
+    # throughout this repo — 257 findings on an untouched master. Adopting the
+    # new rules is a mechanical `ruff check --fix` sweep that belongs in its own
+    # PR, not in whatever change happens to run CI first after a ruff release.
+    "ruff>=0.5,<0.16",
     "mypy>=1.10",
 ]
 

{transcodely-0.3.1 → transcodely-0.3.2}/src/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-0.3.1 → transcodely-0.3.2}/src/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-0.3.1 → transcodely-0.3.2}/src/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-0.3.1 → transcodely-0.3.2}/src/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-0.3.2/src/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