transcodely 0.3.6__tar.gz → 0.3.8__tar.gz

{transcodely-0.3.6 → transcodely-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: transcodely
-Version: 0.3.6
+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
@@ -122,6 +122,9 @@ client.origins         # create / get / list / update / validate / archive
 client.apps            # create / get / list / update / archive / enable_hosting
 client.api_keys        # create / get / list / revoke
 client.organizations   # create / get / list / update / check_slug
+client.billing         # list_invoices / retrieve / retrieve_upcoming / retrieve_profile / create_portal_session
+                       #   + retrieve_budget / set_budget / clear_budget
+                       #   + retrieve_outstanding_balance / settle_outstanding_balance
 client.memberships     # list / get / update_role / remove
 client.users           # get_me / get / list / update_me
 client.health          # check
@@ -266,6 +269,54 @@ r2 = {
 
 Provide either `account_id` or `endpoint`, never both. `jurisdiction` only applies when `account_id` is set.
 
+## Billing
+
+Billing settles a whole organization, so `client.billing` needs a dashboard session token for an
+organization **owner** plus the organization it is for — an API key is scoped to one app and is
+rejected outright:
+
+```python
+client = Transcodely("tk_session_token", organization_id="org_f6g7h8i9j0")
+
+client.billing.retrieve_upcoming()  # what the current period has accrued
+client.billing.list_invoices(limit=12)
+```
+
+Three numbers live here and they are not interchangeable:
+
+| Call | What it answers | Enforces? |
+|---|---|---|
+| `billing.retrieve_upcoming()` | What the **current period** has accrued | No |
+| `billing.retrieve_budget()` | Spend against the org's own monthly budget | No — emails only |
+| `billing.retrieve_outstanding_balance()` | What is **unsettled**, incl. earlier periods | Yes, at the hard stop |
+| `apps.set_spend_limit(app_id, eur)` | One app's monthly cap | Yes, at 100% |
+
+Budgets notify; limits block:
+
+```python
+client.billing.set_budget(500.0)  # emails at 50% / 80% / 100%, restricts nothing
+client.billing.clear_budget()  # turns the alerts off
+```
+
+The outstanding balance is the platform's own exposure control. 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 code `outstanding_balance_exceeded` — queued
+and running work still finishes and videos keep playing. Paying lifts the block on the next
+request:
+
+```python
+balance = client.billing.retrieve_outstanding_balance()
+if balance.blocked and balance.settlement_available:
+    result = client.billing.settle_outstanding_balance()
+    print(result.settlement.invoice_id, result.balance.outstanding_cents)  # → 0
+```
+
+Check `settlement_available` before offering a "pay now" action: settlement raises
+`PreconditionError` with code `settlement_unavailable` where the rail is switched off, and
+`nothing_outstanding` when there is nothing to pay. Job creates refused for money reasons carry
+`billing_past_due` (a statement is unpaid) or `outstanding_balance_exceeded` (too much unbilled
+usage) — neither clears by retrying, so back-off is the wrong response to both.
+
 ## Errors
 
 All exceptions inherit from `TranscodelyError`:

{transcodely-0.3.6 → transcodely-0.3.8}/README.md

@@ -85,6 +85,9 @@ client.origins         # create / get / list / update / validate / archive
 client.apps            # create / get / list / update / archive / enable_hosting
 client.api_keys        # create / get / list / revoke
 client.organizations   # create / get / list / update / check_slug
+client.billing         # list_invoices / retrieve / retrieve_upcoming / retrieve_profile / create_portal_session
+                       #   + retrieve_budget / set_budget / clear_budget
+                       #   + retrieve_outstanding_balance / settle_outstanding_balance
 client.memberships     # list / get / update_role / remove
 client.users           # get_me / get / list / update_me
 client.health          # check
@@ -229,6 +232,54 @@ r2 = {
 
 Provide either `account_id` or `endpoint`, never both. `jurisdiction` only applies when `account_id` is set.
 
+## Billing
+
+Billing settles a whole organization, so `client.billing` needs a dashboard session token for an
+organization **owner** plus the organization it is for — an API key is scoped to one app and is
+rejected outright:
+
+```python
+client = Transcodely("tk_session_token", organization_id="org_f6g7h8i9j0")
+
+client.billing.retrieve_upcoming()  # what the current period has accrued
+client.billing.list_invoices(limit=12)
+```
+
+Three numbers live here and they are not interchangeable:
+
+| Call | What it answers | Enforces? |
+|---|---|---|
+| `billing.retrieve_upcoming()` | What the **current period** has accrued | No |
+| `billing.retrieve_budget()` | Spend against the org's own monthly budget | No — emails only |
+| `billing.retrieve_outstanding_balance()` | What is **unsettled**, incl. earlier periods | Yes, at the hard stop |
+| `apps.set_spend_limit(app_id, eur)` | One app's monthly cap | Yes, at 100% |
+
+Budgets notify; limits block:
+
+```python
+client.billing.set_budget(500.0)  # emails at 50% / 80% / 100%, restricts nothing
+client.billing.clear_budget()  # turns the alerts off
+```
+
+The outstanding balance is the platform's own exposure control. 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 code `outstanding_balance_exceeded` — queued
+and running work still finishes and videos keep playing. Paying lifts the block on the next
+request:
+
+```python
+balance = client.billing.retrieve_outstanding_balance()
+if balance.blocked and balance.settlement_available:
+    result = client.billing.settle_outstanding_balance()
+    print(result.settlement.invoice_id, result.balance.outstanding_cents)  # → 0
+```
+
+Check `settlement_available` before offering a "pay now" action: settlement raises
+`PreconditionError` with code `settlement_unavailable` where the rail is switched off, and
+`nothing_outstanding` when there is nothing to pay. Job creates refused for money reasons carry
+`billing_past_due` (a statement is unpaid) or `outstanding_balance_exceeded` (too much unbilled
+usage) — neither clears by retrying, so back-off is the wrong response to both.
+
 ## Errors
 
 All exceptions inherit from `TranscodelyError`:

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "transcodely"
-version = "0.3.6"
+version = "0.3.8"
 description = "Official Python SDK for the Transcodely video transcoding API"
 readme = "README.md"
 license = "MIT"

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

@@ -55,6 +55,10 @@ from .types import (
     App,
     AudioTrackConfig,
     AutoABRConfig,
+    BillingPaymentMethod,
+    BillingPortalSession,
+    BillingProfile,
+    BillingStanding,
     ChapterPoint,
     ChapterResult,
     ClipConfig,
@@ -77,6 +81,7 @@ from .types import (
     OutputFormat,
     OutputSpec,
     OutputStatus,
+    PaymentMethodState,
     Preset,
     PresetVariant,
     Resolution,
@@ -127,6 +132,10 @@ __all__ = [
     "AudioTrackConfig",
     "AuthenticationError",
     "AutoABRConfig",
+    "BillingPaymentMethod",
+    "BillingPortalSession",
+    "BillingProfile",
+    "BillingStanding",
     "ChapterPoint",
     "ChapterResult",
     "ClipConfig",
@@ -158,6 +167,7 @@ __all__ = [
     "OutputStatus",
     "Page",
     "PageContents",
+    "PaymentMethodState",
     "PermissionError",
     "PreconditionError",
     "Preset",

transcodely-0.3.8/src/transcodely/resources/billing.py

@@ -0,0 +1,266 @@
+"""Billing resource — an organization's invoices, budget and outstanding balance."""
+
+from __future__ import annotations
+
+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. 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. 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:
+        self._t = transport
+
+    def list_invoices(
+        self,
+        *,
+        limit: int | None = None,
+        opts: CallOptions | None = 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: str | None) -> 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: CallOptions | None = 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: CallOptions | None = 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
+
+    def retrieve_profile(self, opts: CallOptions | None = None) -> billing_pb2.BillingProfile:
+        """Retrieve the organization's payment standing.
+
+        Reports whether the payment provider holds a chargeable method, and
+        whatever it will say about that method for display. Read-only and
+        side-effect free — it never creates provider resources. An organization
+        that has never touched billing reports ``PAYMENT_METHOD_STATE_NONE``
+        and no payment methods.
+
+        ``payment_method_state`` is the only reliable signal. A method's
+        ``brand`` and ``last4`` are frequently absent even for a working card,
+        because the provider does not always expose card metadata; render such
+        a method as "Card on file" rather than treating the missing digits as
+        an error.
+        """
+        req = billing_pb2.GetBillingProfileRequest()
+        return self._t.unary(
+            _SERVICE,
+            "GetBillingProfile",
+            req,
+            billing_pb2.GetBillingProfileResponse(),
+            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:
+        """Create a session for the payment provider's hosted billing portal.
+
+        The portal is where a payment method is added or replaced and where
+        receipts live — card details never touch this SDK.
+
+        The first call for an organization also links it to the payment
+        provider, so the returned portal is already attached to this
+        organization's billing account. Safe to call repeatedly.
+
+        The session is single-use and expires; request a fresh one per visit
+        rather than storing the URL.
+        """
+        req = billing_pb2.CreateBillingPortalSessionRequest()
+        return self._t.unary(
+            _SERVICE,
+            "CreateBillingPortalSession",
+            req,
+            billing_pb2.CreateBillingPortalSessionResponse(),
+            opts,
+        ).session

{transcodely-0.3.6 → transcodely-0.3.8}/src/transcodely/types.py

@@ -61,9 +61,34 @@ from transcodely.v1.app_pb2 import (
 # token for an organization owner plus ``organization_id`` — an API key is
 # scoped to one app, while an invoice settles a whole organization, so API keys
 # are rejected.
+#
+# ``BillingProfile`` reports whether the payment provider holds a chargeable
+# method; a portal session is the only place a card is added or replaced, so
+# card details never reach this SDK. Branch on ``PaymentMethodState``, not on
+# the card fields — ``brand`` and ``last4`` are frequently absent even for a
+# working card.
+#
+# ``Budget`` and ``OutstandingBalance`` are three different numbers away from
+# each other and from an invoice: a budget notifies and never enforces, an
+# upcoming invoice is what the CURRENT PERIOD has accrued, and an outstanding
+# balance is what is UNSETTLED — the one that decides whether new jobs are
+# admitted.
 from transcodely.v1.billing_pb2 import (
+    BillingPaymentMethod,
+    BillingPortalSession,
+    BillingProfile,
+    Budget,
+    CreateBillingPortalSessionRequest,
+    CreateBillingPortalSessionResponse,
+    ExposureThresholdSource,
+    GetBillingProfileRequest,
+    GetBillingProfileResponse,
+    GetBudgetRequest,
+    GetBudgetResponse,
     GetInvoiceRequest,
     GetInvoiceResponse,
+    GetOutstandingBalanceRequest,
+    GetOutstandingBalanceResponse,
     GetUpcomingInvoiceRequest,
     GetUpcomingInvoiceResponse,
     Invoice,
@@ -72,13 +97,36 @@ from transcodely.v1.billing_pb2 import (
     InvoiceStatus,
     ListInvoicesRequest,
     ListInvoicesResponse,
+    OutstandingBalance,
+    PaymentMethodState,
+    Settlement,
+    SettleOutstandingBalanceRequest,
+    SettleOutstandingBalanceResponse,
+    TrustTier,
+    UpdateBudgetRequest,
+    UpdateBudgetResponse,
 )
 from transcodely.v1.codec_av1_pb2 import AV1Options
 from transcodely.v1.codec_h264_pb2 import H264Options
 from transcodely.v1.codec_h265_pb2 import H265Options
 from transcodely.v1.codec_vp9_pb2 import VP9Options
+
+# ``BillingStanding`` is ``BillingProfile.standing`` — derived from the
+# organization's billing facts rather than assigned, so there is nothing to set.
+# ``FREE`` and ``DELINQUENT`` both resolve usage limits to the free tier's, but
+# ``DELINQUENT`` still bills; neither is a suspension. An organization exempt
+# from the payment-method requirement always reports ``ACTIVE``.
+#
+# ``BillingTreatment`` is ``Organization.billing_treatment`` — orthogonal to
+# standing, and assigned rather than derived: standing is a fact about payment
+# health, treatment is the decision about whether automation may act on it. It
+# is populated on admin reads only. ``DunningStage`` belongs to the same wave
+# but reaches no message this SDK can receive, so it stays unexported; reach it
+# at ``transcodely.v1.common_pb2.DunningStage`` if you are decoding admin JSON.
 from transcodely.v1.common_pb2 import (
     AudioCodec,
+    BillingStanding,
+    BillingTreatment,
     BitrateMode,
     Container,
     ContentType,
@@ -388,7 +436,13 @@ __all__ = [
     "AutoABRConfig",
     "AutoProfileDefaults",
     "BYOKConfig",
+    "BillingPaymentMethod",
+    "BillingPortalSession",
+    "BillingProfile",
+    "BillingStanding",
+    "BillingTreatment",
     "BitrateMode",
+    "Budget",
     "BurnInStyle",
     "CancelJobRequest",
     "CancelJobResponse",
@@ -414,6 +468,8 @@ __all__ = [
     "CreateAPIKeyResponse",
     "CreateAppRequest",
     "CreateAppResponse",
+    "CreateBillingPortalSessionRequest",
+    "CreateBillingPortalSessionResponse",
     "CreateFromUrlRequest",
     "CreateFromUrlResponse",
     "CreateJobRequest",
@@ -450,6 +506,7 @@ __all__ = [
     "EventRequest",
     "EventType",
     "ExecutionTiming",
+    "ExposureThresholdSource",
     "GOPAlignmentMode",
     "GcsCredentials",
     "GcsOriginConfig",
@@ -457,6 +514,10 @@ __all__ = [
     "GetAPIKeyResponse",
     "GetAppRequest",
     "GetAppResponse",
+    "GetBillingProfileRequest",
+    "GetBillingProfileResponse",
+    "GetBudgetRequest",
+    "GetBudgetResponse",
     "GetEndpointHealthRequest",
     "GetEndpointHealthResponse",
     "GetInvoiceRequest",
@@ -471,6 +532,8 @@ __all__ = [
     "GetOrganizationResponse",
     "GetOriginRequest",
     "GetOriginResponse",
+    "GetOutstandingBalanceRequest",
+    "GetOutstandingBalanceResponse",
     "GetPresetBySlugRequest",
     "GetPresetBySlugResponse",
     "GetPresetRequest",
@@ -557,8 +620,10 @@ __all__ = [
     "OutputSpec",
     "OutputStatus",
     "OutputVariantResult",
+    "OutstandingBalance",
     "PaginationRequest",
     "PaginationResponse",
+    "PaymentMethodState",
     "Preset",
     "PresetVariant",
     "PricingSnapshot",
@@ -581,6 +646,9 @@ __all__ = [
     "SegmentConfig",
     "SendTestWebhookRequest",
     "SendTestWebhookResponse",
+    "SettleOutstandingBalanceRequest",
+    "SettleOutstandingBalanceResponse",
+    "Settlement",
     "StreamingConfig",
     "SubtitleFormat",
     "SubtitleOperation",
@@ -593,8 +661,11 @@ __all__ = [
     "ThumbnailSpec",
     "ToneMapping",
     "TopVideo",
+    "TrustTier",
     "UpdateAppRequest",
     "UpdateAppResponse",
+    "UpdateBudgetRequest",
+    "UpdateBudgetResponse",
     "UpdateHostingConfigRequest",
     "UpdateHostingConfigResponse",
     "UpdateMeRequest",