transcodely 0.3.8__tar.gz → 0.3.9__tar.gz

transcodely-0.3.8/README.md → transcodely-0.3.9/PKG-INFO

@@ -1,6 +1,45 @@
+Metadata-Version: 2.5
+Name: transcodely
+Version: 0.3.9
+Summary: Official Python SDK for Transcodely — encode video to HLS, DASH and MP4 into your own S3, GCS or R2 bucket, with DRM and signed playback.
+Project-URL: Homepage, https://www.transcodely.com
+Project-URL: Documentation, https://www.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: abr,cmaf,connect-rpc,dash,drm,encoding,fairplay,ffmpeg,hls,r2,s3,signed-urls,streaming,transcodely,transcoding,video,video-hosting,widevine
+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.16; 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.
+Official Python SDK for [Transcodely](https://www.transcodely.com) — encode video into
+HLS, DASH and MP4 and write it to your own S3, GCS or R2 bucket, with DRM, signed
+playback and deterministic output paths. Or let Transcodely host and deliver it.
 
 ```bash
 pip install transcodely
@@ -38,6 +77,49 @@ 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.
 
+## Read the output report
+
+Every completed output carries a report of what the produced file actually
+turned out to be — measured from the encoded file rather than copied from the
+request — plus the verdict of comparing those measurements against what was
+asked for.
+
+```python
+from transcodely.types import OutputReport
+
+done = client.jobs.get(job.id)
+
+for output in done.outputs:
+    if not output.HasField("report"):
+        continue  # not measured — never "nothing wrong"
+
+    report: OutputReport = output.report
+    print(
+        output.id,
+        report.video.codec,
+        f"{report.video.width}x{report.video.height}",
+        f"{report.duration_seconds}s",
+    )
+
+    if not report.verdict.matches_request:
+        for m in report.verdict.mismatches:
+            print(f"  {m.field}: asked for {m.expected}, got {m.actual}")
+```
+
+Check `output.HasField("report")` rather than truthiness: an absent report means
+"not measured", which is not the same as a report that found nothing wrong.
+Branch on `m.field` — it comes from a fixed vocabulary (`video.codec`,
+`video.resolution`, `duration_seconds`, …) — rather than on the values beside
+it. For an ABR ladder the facts describe the highest-resolution rendition, the
+same one the verdict judges; per-rendition detail stays in `variant_results`.
+
+An output encoded with per-title content-aware analysis also carries
+`report.content_aware`: the VMAF target the search aimed at, the score it reached
+on its samples, and the CRF it chose. It describes the SEARCH, not the delivered
+file — `vmaf_achieved` scores short samples taken before the real encode, which
+is never scored itself. Check `report.HasField("content_aware")`; an ordinary
+output has none.
+
 ## 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`.
@@ -82,6 +164,7 @@ client.jobs            # create / get / list / cancel / confirm / 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.ingest_rules    # create / get / list / update / delete / list_events / test / replay_event
 client.apps            # create / get / list / update / archive / enable_hosting
 client.api_keys        # create / get / list / revoke
 client.organizations   # create / get / list / update / check_slug
@@ -232,6 +315,72 @@ r2 = {
 
 Provide either `account_id` or `endpoint`, never both. `jurisdiction` only applies when `account_id` is set.
 
+## Ingest rules
+
+An ingest rule is a standing instruction on one readable origin: *when an object
+matching these filters lands, create this job for it*. Your storage provider
+posts its object-created events to the rule's endpoint, and no server of yours
+is in the path. Amazon S3 via SNS, Google Cloud Storage via a Pub/Sub push
+subscription, Supabase Storage via a database webhook, and a generic shape for
+anything else are all recognised from the payload.
+
+```python
+created = client.ingest_rules.create(
+    origin_id="ori_a1b2c3d4e5f6",
+    name="Watch uploads/",
+    filters={
+        "prefix": "uploads/",
+        "suffixes": [".mp4", ".mov"],
+        "min_bytes": 1024,  # ignore the zero-byte placeholder some clients write first
+    },
+    action={
+        "outputs": [{"preset": "web_1080p_standard"}],
+        "managed": True,  # host and deliver the result; use output_origin_id for your own bucket
+        "priority": "standard",
+    },
+)
+
+print("point your bucket notifications at", created.rule.endpoint_url)
+print("secret (shown once):", created.secret)
+```
+
+`created.secret` is the **only** time the inbound secret is readable — store it
+wherever the event sender will read it from. A later `get` returns just
+`secret_prefix` and `secret_hint`. Lost it? `update` with `rotate_secret=True`
+issues a new one, and the previous one keeps working for 24 hours so the sender
+can be changed without dropping an event.
+
+Every delivery is recorded, whether or not it became a job:
+
+```python
+for event in client.ingest_rules.list_events(rule_id=created.rule.id).auto_paging_iter():
+    print(event.id, event.object_key, event.status, event.reason)
+```
+
+A `skipped` event names why in `reason` — `filter_prefix`, `filter_suffix`,
+`filter_content_type`, `filter_size`, `bucket_mismatch`, `rule_disabled`, or
+`duplicate`. A `failed` one carries the API error code that refused the job,
+such as `limit_exceeded`. Narrow the log to either with the simplified status
+string: `list_events(status="skipped")`.
+
+Deduplication is permanent: an object is identified by (rule, bucket, key,
+etag), so re-sending the event or re-uploading the same bytes produces nothing.
+To give an object another pass — one that arrived while the rule was paused, or
+was refused while the account was over its cap — replay it:
+
+```python
+replayed = client.ingest_rules.replay_event("sev_a1b2c3d4e5f6g7")
+print(replayed.id, "is back in", StorageEventStatus.Name(replayed.status))
+```
+
+Only `skipped` and `failed` events can be replayed. When an `update` switches a
+paused rule back on, the response reports how large that backlog is in
+`events_skipped_while_disabled`.
+
+Before wiring the provider up, dry-run a key against the rule with
+`client.ingest_rules.test(...)`: it reports whether the filters match and, when
+they do, the exact job request the rule would submit. Nothing is stored.
+
 ## Billing
 
 Billing settles a whole organization, so `client.billing` needs a dashboard session token for an

transcodely-0.3.8/PKG-INFO → transcodely-0.3.9/README.md

@@ -1,43 +1,8 @@
-Metadata-Version: 2.5
-Name: transcodely
-Version: 0.3.8
-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.16; 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.
+Official Python SDK for [Transcodely](https://www.transcodely.com) — encode video into
+HLS, DASH and MP4 and write it to your own S3, GCS or R2 bucket, with DRM, signed
+playback and deterministic output paths. Or let Transcodely host and deliver it.
 
 ```bash
 pip install transcodely
@@ -75,6 +40,49 @@ 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.
 
+## Read the output report
+
+Every completed output carries a report of what the produced file actually
+turned out to be — measured from the encoded file rather than copied from the
+request — plus the verdict of comparing those measurements against what was
+asked for.
+
+```python
+from transcodely.types import OutputReport
+
+done = client.jobs.get(job.id)
+
+for output in done.outputs:
+    if not output.HasField("report"):
+        continue  # not measured — never "nothing wrong"
+
+    report: OutputReport = output.report
+    print(
+        output.id,
+        report.video.codec,
+        f"{report.video.width}x{report.video.height}",
+        f"{report.duration_seconds}s",
+    )
+
+    if not report.verdict.matches_request:
+        for m in report.verdict.mismatches:
+            print(f"  {m.field}: asked for {m.expected}, got {m.actual}")
+```
+
+Check `output.HasField("report")` rather than truthiness: an absent report means
+"not measured", which is not the same as a report that found nothing wrong.
+Branch on `m.field` — it comes from a fixed vocabulary (`video.codec`,
+`video.resolution`, `duration_seconds`, …) — rather than on the values beside
+it. For an ABR ladder the facts describe the highest-resolution rendition, the
+same one the verdict judges; per-rendition detail stays in `variant_results`.
+
+An output encoded with per-title content-aware analysis also carries
+`report.content_aware`: the VMAF target the search aimed at, the score it reached
+on its samples, and the CRF it chose. It describes the SEARCH, not the delivered
+file — `vmaf_achieved` scores short samples taken before the real encode, which
+is never scored itself. Check `report.HasField("content_aware")`; an ordinary
+output has none.
+
 ## 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`.
@@ -119,6 +127,7 @@ client.jobs            # create / get / list / cancel / confirm / 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.ingest_rules    # create / get / list / update / delete / list_events / test / replay_event
 client.apps            # create / get / list / update / archive / enable_hosting
 client.api_keys        # create / get / list / revoke
 client.organizations   # create / get / list / update / check_slug
@@ -269,6 +278,72 @@ r2 = {
 
 Provide either `account_id` or `endpoint`, never both. `jurisdiction` only applies when `account_id` is set.
 
+## Ingest rules
+
+An ingest rule is a standing instruction on one readable origin: *when an object
+matching these filters lands, create this job for it*. Your storage provider
+posts its object-created events to the rule's endpoint, and no server of yours
+is in the path. Amazon S3 via SNS, Google Cloud Storage via a Pub/Sub push
+subscription, Supabase Storage via a database webhook, and a generic shape for
+anything else are all recognised from the payload.
+
+```python
+created = client.ingest_rules.create(
+    origin_id="ori_a1b2c3d4e5f6",
+    name="Watch uploads/",
+    filters={
+        "prefix": "uploads/",
+        "suffixes": [".mp4", ".mov"],
+        "min_bytes": 1024,  # ignore the zero-byte placeholder some clients write first
+    },
+    action={
+        "outputs": [{"preset": "web_1080p_standard"}],
+        "managed": True,  # host and deliver the result; use output_origin_id for your own bucket
+        "priority": "standard",
+    },
+)
+
+print("point your bucket notifications at", created.rule.endpoint_url)
+print("secret (shown once):", created.secret)
+```
+
+`created.secret` is the **only** time the inbound secret is readable — store it
+wherever the event sender will read it from. A later `get` returns just
+`secret_prefix` and `secret_hint`. Lost it? `update` with `rotate_secret=True`
+issues a new one, and the previous one keeps working for 24 hours so the sender
+can be changed without dropping an event.
+
+Every delivery is recorded, whether or not it became a job:
+
+```python
+for event in client.ingest_rules.list_events(rule_id=created.rule.id).auto_paging_iter():
+    print(event.id, event.object_key, event.status, event.reason)
+```
+
+A `skipped` event names why in `reason` — `filter_prefix`, `filter_suffix`,
+`filter_content_type`, `filter_size`, `bucket_mismatch`, `rule_disabled`, or
+`duplicate`. A `failed` one carries the API error code that refused the job,
+such as `limit_exceeded`. Narrow the log to either with the simplified status
+string: `list_events(status="skipped")`.
+
+Deduplication is permanent: an object is identified by (rule, bucket, key,
+etag), so re-sending the event or re-uploading the same bytes produces nothing.
+To give an object another pass — one that arrived while the rule was paused, or
+was refused while the account was over its cap — replay it:
+
+```python
+replayed = client.ingest_rules.replay_event("sev_a1b2c3d4e5f6g7")
+print(replayed.id, "is back in", StorageEventStatus.Name(replayed.status))
+```
+
+Only `skipped` and `failed` events can be replayed. When an `update` switches a
+paused rule back on, the response reports how large that backlog is in
+`events_skipped_while_disabled`.
+
+Before wiring the provider up, dry-run a key against the rule with
+`client.ingest_rules.test(...)`: it reports whether the filters match and, when
+they do, the exact job request the rule would submit. Nothing is stored.
+
 ## Billing
 
 Billing settles a whole organization, so `client.billing` needs a dashboard session token for an

{transcodely-0.3.8 → transcodely-0.3.9}/pyproject.toml

@@ -4,14 +4,16 @@ build-backend = "hatchling.build"
 
 [project]
 name = "transcodely"
-version = "0.3.8"
-description = "Official Python SDK for the Transcodely video transcoding API"
+version = "0.3.9"
+description = "Official Python SDK for Transcodely — encode video to HLS, DASH and MP4 into your own S3, GCS or R2 bucket, with DRM and signed playback."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{ name = "Transcodely" }]
 requires-python = ">=3.10"
-keywords = ["transcodely", "video", "transcoding", "encoding", "hls", "dash", "streaming", "connect-rpc"]
+keywords = ["transcodely", "video", "transcoding", "encoding", "hls", "dash", "cmaf",
+            "drm", "widevine", "fairplay", "abr", "ffmpeg", "s3", "r2", "signed-urls",
+            "video-hosting", "streaming", "connect-rpc"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
@@ -42,8 +44,8 @@ dev = [
 ]
 
 [project.urls]
-Homepage = "https://transcodely.com"
-Documentation = "https://transcodely.com/docs"
+Homepage = "https://www.transcodely.com"
+Documentation = "https://www.transcodely.com/docs"
 Repository = "https://github.com/transcodely/transcodely-python"
 Issues = "https://github.com/transcodely/transcodely-python/issues"
 

{transcodely-0.3.8 → transcodely-0.3.9}/src/transcodely/__init__.py

@@ -67,6 +67,7 @@ from .types import (
     DRMConfig,
     HDRConfig,
     HLSConfig,
+    IngestRule,
     Invoice,
     InvoiceLineItem,
     InvoiceLineType,
@@ -85,6 +86,9 @@ from .types import (
     Preset,
     PresetVariant,
     Resolution,
+    StorageEvent,
+    StorageEventSource,
+    StorageEventStatus,
     StreamingConfig,
     SubtitleResult,
     SubtitleTrack,
@@ -149,6 +153,7 @@ __all__ = [
     "FieldViolation",
     "HDRConfig",
     "HLSConfig",
+    "IngestRule",
     "InvalidRequestError",
     "Invoice",
     "InvoiceLineItem",
@@ -174,6 +179,9 @@ __all__ = [
     "PresetVariant",
     "RateLimitError",
     "Resolution",
+    "StorageEvent",
+    "StorageEventSource",
+    "StorageEventStatus",
     "StreamingConfig",
     "SubtitleResult",
     "SubtitleTrack",

{transcodely-0.3.8 → transcodely-0.3.9}/src/transcodely/client.py

@@ -13,6 +13,7 @@ from .resources.apps import Apps
 from .resources.billing import Billing
 from .resources.events import Events
 from .resources.health import Health
+from .resources.ingest_rules import IngestRules
 from .resources.jobs import Jobs
 from .resources.memberships import Memberships
 from .resources.organizations import Organizations
@@ -63,6 +64,7 @@ class Transcodely:
         self._videos: Videos | None = None
         self._presets: Presets | None = None
         self._origins: Origins | None = None
+        self._ingest_rules: IngestRules | None = None
         self._apps: Apps | None = None
         self._api_keys: ApiKeys | None = None
         self._organizations: Organizations | None = None
@@ -111,6 +113,13 @@ class Transcodely:
             self._origins = Origins(self._transport)
         return self._origins
 
+    @property
+    def ingest_rules(self) -> IngestRules:
+        """Ingest rules: watch a bucket, transcode what lands in it."""
+        if self._ingest_rules is None:
+            self._ingest_rules = IngestRules(self._transport)
+        return self._ingest_rules
+
     @property
     def apps(self) -> Apps:
         if self._apps is None:

{transcodely-0.3.8 → transcodely-0.3.9}/src/transcodely/resources/events.py

@@ -52,15 +52,25 @@ class Events:
     def list(
         self,
         *,
-        app_id: str,
+        app_id: str | None = None,
         type: str | None = None,
         created_after: datetime | None = None,
         created_before: datetime | None = None,
         limit: int | None = None,
         opts: CallOptions | None = None,
     ) -> Page[Event]:
+        """List events, newest first.
+
+        ``app_id`` is an optional filter. An API-key caller may omit it and get
+        their key's own app; passing a different app's ID is refused with
+        ``permission_denied``. A portal user who omits it gets the events of
+        every app in the organization.
+        """
+
         def fetch(cursor: str | None) -> PageContents[Event]:
-            req = webhook_pb2.ListEventsRequest(app_id=app_id)
+            req = webhook_pb2.ListEventsRequest()
+            if app_id is not None:
+                req.app_id = app_id
             if type is not None:
                 req.type = type
             if created_after is not None:

transcodely-0.3.9/src/transcodely/resources/ingest_rules.py

@@ -0,0 +1,183 @@
+"""Ingest rule resource — watch a bucket, transcode what lands in it.
+
+An ingest rule is a standing instruction on one readable storage origin: when
+an object matching its filters appears, create the job its action describes.
+Your storage provider posts object-created events to the rule's
+``endpoint_url``, authenticated with the rule's secret, so no server of yours is
+in the path. Amazon S3 via SNS, Google Cloud Storage via a Pub/Sub push
+subscription, Supabase Storage via a database webhook, and a generic shape for
+anything else are all recognised from the payload.
+
+Duplicate deliveries are absorbed: an object is identified by
+(rule, bucket, key, etag) and produces exactly one job.
+
+The inbound endpoint itself is not part of this SDK — your storage provider
+calls it, not you.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from .._transport.transport import CallOptions, Transport
+from ..pagination import Page, PageContents
+from ..v1 import ingest_rule_pb2
+from ._helpers import assign_pagination, fill_from_dict, resolve_enum
+
+_SERVICE = "transcodely.v1.IngestRuleService"
+
+
+class IngestRules:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def create(self, **kwargs: Any) -> ingest_rule_pb2.CreateIngestRuleResponse:
+        """Create a rule on a readable origin.
+
+        The whole response is returned because ``secret`` rides on it: the
+        inbound secret is shown once, here, and cannot be read back. Store it
+        wherever the event sender will read it from.
+        """
+        req = fill_from_dict(ingest_rule_pb2.CreateIngestRuleRequest(), kwargs)
+        return self._t.unary(_SERVICE, "Create", req, ingest_rule_pb2.CreateIngestRuleResponse())
+
+    def get(self, id: str, opts: CallOptions | None = None) -> ingest_rule_pb2.IngestRule:
+        """Fetch a rule by ID (``ing_*``).
+
+        The secret is never returned again — the rule carries only
+        ``secret_prefix`` and ``secret_hint``.
+        """
+        req = ingest_rule_pb2.GetIngestRuleRequest(id=id)
+        return self._t.unary(
+            _SERVICE, "Get", req, ingest_rule_pb2.GetIngestRuleResponse(), opts
+        ).rule
+
+    def list(
+        self,
+        *,
+        origin_id: str | None = None,
+        enabled: bool | None = None,
+        app_id: str | None = None,
+        limit: int | None = None,
+        opts: CallOptions | None = None,
+    ) -> Page[ingest_rule_pb2.IngestRule]:
+        """Rules in scope, newest first."""
+
+        def fetch(cursor: str | None) -> PageContents[ingest_rule_pb2.IngestRule]:
+            req = ingest_rule_pb2.ListIngestRulesRequest()
+            if origin_id is not None:
+                req.origin_id = origin_id
+            if enabled is not None:
+                req.enabled = enabled
+            if app_id is not None:
+                req.app_id = app_id
+            assign_pagination(req.pagination, limit=limit, cursor=cursor)
+            res = self._t.unary(
+                _SERVICE, "List", req, ingest_rule_pb2.ListIngestRulesResponse(), opts
+            )
+            return PageContents(
+                items=list(res.rules), next_cursor=res.pagination.next_cursor or None
+            )
+
+        return Page(fetch)
+
+    def update(self, **kwargs: Any) -> ingest_rule_pb2.UpdateIngestRuleResponse:
+        """Update name, enabled state, filters or action, optionally rotating the secret.
+
+        The update MERGES: it applies only what it carries, down to the
+        individual filters and the individual parts of the action. Narrowing a
+        rule to a new prefix is ``filters={"prefix": "raw/"}`` and nothing else
+        — the suffix, content-type and size filters are untouched.
+
+        Removing something rather than changing it takes the two clear flags.
+        ``clear_filters=True`` empties the filter set before ``filters`` is
+        applied, so on its own it widens the rule to everything in the bucket.
+        ``clear_action=True`` replaces the action outright, and ``action`` must
+        then be complete — at least one output and exactly one destination.
+        That is the only way to drop an action's thumbnails or metadata, since
+        a repeated or map field sent empty reads as "not sent". For the same
+        reason ``managed=False`` does not turn managed storage off; it leaves
+        the destination alone, so send ``output_origin_id`` instead.
+
+        The whole response is returned: a rotation puts the new secret on it
+        (once, and the previous secret keeps working for 24 hours), and
+        switching a paused rule back on reports how many deliveries it declined
+        while off in ``events_skipped_while_disabled``.
+        """
+        req = fill_from_dict(ingest_rule_pb2.UpdateIngestRuleRequest(), kwargs)
+        return self._t.unary(_SERVICE, "Update", req, ingest_rule_pb2.UpdateIngestRuleResponse())
+
+    def delete(self, id: str, opts: CallOptions | None = None) -> ingest_rule_pb2.IngestRule:
+        """Delete a rule; its endpoint stops accepting events immediately.
+
+        The events it already received are kept, and the rule as it stood at
+        deletion is returned.
+        """
+        req = ingest_rule_pb2.DeleteIngestRuleRequest(id=id)
+        return self._t.unary(
+            _SERVICE, "Delete", req, ingest_rule_pb2.DeleteIngestRuleResponse(), opts
+        ).rule
+
+    def list_events(
+        self,
+        *,
+        rule_id: str | None = None,
+        status: int | str | None = None,
+        app_id: str | None = None,
+        limit: int | None = None,
+        opts: CallOptions | None = None,
+    ) -> Page[ingest_rule_pb2.StorageEvent]:
+        """Every delivery received and what came of it, newest first.
+
+        ``status`` accepts the simplified wire string (``"skipped"``) as well as
+        the generated constant.
+        """
+        resolved_status = (
+            None
+            if status is None
+            else resolve_enum(status, ingest_rule_pb2.StorageEventStatus.DESCRIPTOR)
+        )
+
+        def fetch(cursor: str | None) -> PageContents[ingest_rule_pb2.StorageEvent]:
+            req = ingest_rule_pb2.ListIngestEventsRequest()
+            if rule_id is not None:
+                req.rule_id = rule_id
+            if resolved_status is not None:
+                # resolve_enum returns a plain int; the field is typed as the enum.
+                req.status = cast("ingest_rule_pb2.StorageEventStatus", resolved_status)
+            if app_id is not None:
+                req.app_id = app_id
+            assign_pagination(req.pagination, limit=limit, cursor=cursor)
+            res = self._t.unary(
+                _SERVICE, "ListEvents", req, ingest_rule_pb2.ListIngestEventsResponse(), opts
+            )
+            return PageContents(
+                items=list(res.events), next_cursor=res.pagination.next_cursor or None
+            )
+
+        return Page(fetch)
+
+    def test(self, **kwargs: Any) -> ingest_rule_pb2.TestIngestRuleResponse:
+        """Dry-run an object key against a rule. Nothing is stored, no job is created.
+
+        Reports whether the filters match and, when they do, the exact job
+        request the rule would submit. Supply ``etag`` when you want the
+        preview to name the idempotency key a real delivery would carry — the
+        key is derived from it.
+        """
+        req = fill_from_dict(ingest_rule_pb2.TestIngestRuleRequest(), kwargs)
+        return self._t.unary(_SERVICE, "Test", req, ingest_rule_pb2.TestIngestRuleResponse())
+
+    def replay_event(
+        self, event_id: str, opts: CallOptions | None = None
+    ) -> ingest_rule_pb2.StorageEvent:
+        """Re-queue a skipped or refused event (``sev_*``).
+
+        Deduplication is permanent: re-sending the event, or re-uploading the
+        same bytes, is absorbed and produces nothing. The event is reset rather
+        than duplicated, so it keeps its id and its history.
+        """
+        req = ingest_rule_pb2.ReplayIngestEventRequest(event_id=event_id)
+        return self._t.unary(
+            _SERVICE, "ReplayEvent", req, ingest_rule_pb2.ReplayIngestEventResponse(), opts
+        ).event