transcodely 0.3.7__py3-none-any.whl → 0.3.9__py3-none-any.whl

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/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/resources/billing.py

@@ -1,4 +1,4 @@
-"""Billing resource — an organization's invoices, read-only."""
+"""Billing resource — an organization's invoices, budget and outstanding balance."""
 
 from __future__ import annotations
 
@@ -25,10 +25,13 @@ class Billing:
         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.
+    to create, edit, or delete one — a statement records what happened. The one
+    exception is :meth:`settle_outstanding_balance`, which closes the period
+    early and produces an ordinary statement for what is owed so far.
 
     Monetary amounts are integer minor units (cents) of the invoice currency:
-    ``total_cents == 1250`` in EUR is 12.50 EUR.
+    ``total_cents == 1250`` in EUR is 12.50 EUR. The budget is the exception —
+    it is stated in whole EUR as a float, matching how a customer types it.
     """
 
     def __init__(self, transport: Transport) -> None:
@@ -113,6 +116,131 @@ class Billing:
             opts,
         ).profile
 
+    def retrieve_budget(self, opts: CallOptions | None = None) -> billing_pb2.Budget:
+        """Retrieve the organization's monthly budget and the spend against it.
+
+        A budget is the organization's own telemetry and it NEVER enforces
+        anything: crossing 100% sends an email and changes nothing else. The
+        hard cap is the per-app spend limit
+        (:meth:`~transcodely.resources.apps.Apps.set_spend_limit`), which does
+        refuse new jobs. Limits block; budgets notify.
+
+        Always returns a budget: an organization that has never set one gets
+        ``amount_eur`` absent with ``spent_eur`` still populated, so the current
+        period's spend can be shown before a budget exists.
+        """
+        req = billing_pb2.GetBudgetRequest()
+        return self._t.unary(
+            _SERVICE,
+            "GetBudget",
+            req,
+            billing_pb2.GetBudgetResponse(),
+            opts,
+        ).budget
+
+    def update_budget(
+        self,
+        amount_eur: float | None = None,
+        opts: CallOptions | None = None,
+    ) -> billing_pb2.Budget:
+        """Set or clear the organization's monthly budget.
+
+        Pass ``amount_eur`` (must be > 0) to set the budget, or leave it
+        ``None`` to clear it and stop the alert emails. :meth:`set_budget` and
+        :meth:`clear_budget` are the ergonomic shorthands.
+
+        Moving the amount never re-arms an alert step already sent this period —
+        read ``notified_steps`` on the returned budget to see which have fired.
+        """
+        req = billing_pb2.UpdateBudgetRequest()
+        if amount_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 budget".
+            req.amount_eur = amount_eur
+        return self._t.unary(
+            _SERVICE,
+            "UpdateBudget",
+            req,
+            billing_pb2.UpdateBudgetResponse(),
+            opts,
+        ).budget
+
+    def set_budget(self, amount_eur: float, opts: CallOptions | None = None) -> billing_pb2.Budget:
+        """Set the organization's monthly budget in EUR (must be > 0).
+
+        Alert emails go out as spend crosses each step in ``alert_steps`` (50%,
+        80% and 100% today). Nothing is restricted at any of them.
+        """
+        return self.update_budget(amount_eur, opts)
+
+    def clear_budget(self, opts: CallOptions | None = None) -> billing_pb2.Budget:
+        """Clear the monthly budget, turning the alert emails off (the default)."""
+        return self.update_budget(None, opts)
+
+    def retrieve_outstanding_balance(
+        self, opts: CallOptions | None = None
+    ) -> billing_pb2.OutstandingBalance:
+        """Retrieve the unsettled balance and the threshold it is measured against.
+
+        Usage that has been accrued and not yet captured onto a statement,
+        across every app in the organization. It is a different number from
+        :meth:`retrieve_upcoming` (which is what the *current period* accrued,
+        while this also carries anything an earlier period left uncaptured) and
+        from ``Budget.spent_eur`` (which keeps counting after an invoice is
+        issued, while this drops to zero when one is).
+
+        Reminder emails go out at 80%, 100%, 125%, 150% and 175% of
+        ``threshold_cents`` and restrict nothing. Only at ``hard_stop_cents`` —
+        twice the threshold — are new jobs refused, with error code
+        ``outstanding_balance_exceeded``; work already queued or running still
+        finishes and videos keep playing. ``blocked`` reads the same numbers the
+        admission gate reads.
+
+        Always returns a balance: an organization that owes nothing gets one
+        with ``outstanding_cents`` 0 and its threshold still populated.
+        """
+        req = billing_pb2.GetOutstandingBalanceRequest()
+        return self._t.unary(
+            _SERVICE,
+            "GetOutstandingBalance",
+            req,
+            billing_pb2.GetOutstandingBalanceResponse(),
+            opts,
+        ).balance
+
+    def settle_outstanding_balance(
+        self, opts: CallOptions | None = None
+    ) -> billing_pb2.SettleOutstandingBalanceResponse:
+        """Pay the outstanding balance now, without waiting for the period to end.
+
+        Closes the current period at this instant and produces a real statement
+        for everything owed, which the payment provider then charges. On success
+        the balance is zero, any admission block is lifted immediately, and the
+        trust tier re-evaluates once the statement is paid.
+
+        Takes no amount on purpose: the figure is whatever the ledger says at
+        the instant the settlement runs, so a stale page cannot pay less than is
+        owed and leave the difference looking settled.
+
+        Returns both the :class:`~transcodely.types.Settlement` and the balance
+        as it now stands, so a caller that just paid can render the new state
+        without a second request.
+
+        Raises :class:`~transcodely.errors.PreconditionError` with code
+        ``settlement_unavailable`` when the deployment has mid-cycle settlement
+        switched off — check ``settlement_available`` on the balance before
+        offering a "pay now" action — and ``nothing_outstanding`` when there is
+        nothing to pay.
+        """
+        req = billing_pb2.SettleOutstandingBalanceRequest()
+        return self._t.unary(
+            _SERVICE,
+            "SettleOutstandingBalance",
+            req,
+            billing_pb2.SettleOutstandingBalanceResponse(),
+            opts,
+        )
+
     def create_portal_session(
         self, opts: CallOptions | None = None
     ) -> billing_pb2.BillingPortalSession:

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/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

transcodely/resources/webhook_endpoints.py

@@ -126,12 +126,22 @@ class WebhookEndpoints:
     def list(
         self,
         *,
-        app_id: str,
+        app_id: str | None = None,
         limit: int | None = None,
         opts: CallOptions | None = None,
     ) -> Page[webhook_pb2.WebhookEndpoint]:
+        """List webhook endpoints, 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 endpoints of
+        every app in the organization.
+        """
+
         def fetch(cursor: str | None) -> PageContents[webhook_pb2.WebhookEndpoint]:
-            req = webhook_pb2.ListWebhookEndpointsRequest(app_id=app_id)
+            req = webhook_pb2.ListWebhookEndpointsRequest()
+            if app_id is not None:
+                req.app_id = app_id
             pagination = common_pb2.PaginationRequest()
             if limit is not None:
                 pagination.limit = limit