meterbase 0.5.0__tar.gz → 0.6.0__tar.gz

{meterbase-0.5.0 → meterbase-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterbase
-Version: 0.5.0
+Version: 0.6.0
 Summary: Python SDK for the Meterbase engine
 Project-URL: Homepage, https://meterbase.tech
 Project-URL: Documentation, https://meterbase.tech/docs
@@ -756,14 +756,14 @@ Once the workspace has connected Stripe or Dodo Payments under **Payments** in
 the dashboard, and bound its plans and packs to Stripe prices or Dodo products,
 Meterbase sells them: it opens the checkout, receives the provider's webhooks,
 and moves the customer's plan or grants the pack. There is no webhook handler of
-yours in between. These calls go to the service at
-`https://service.meterbase.tech` rather than the engine, with the same API key;
+yours in between. These calls go to the billing service at
+`https://billing.meterbase.tech` rather than the engine, with the same API key;
 see [Options](#options). There each API key has three limits, whichever
-customers the calls are for: `billing.checkout` and `billing.state` have 30
-requests per 10 s each, and `purchases` has 120 per 10 s. All calls from one IP
-address share 300 per 10 s on top. A 429 there raises `RateLimitError` with
-`retry_after`, once the retries a `GET` or a keyed checkout gets have run out;
-`purchases.wait` keeps waiting instead.
+customers the calls are for: `billing.checkout`, `change`, `cancel`, `keep` and
+`portal` share 30 requests per 10 s, `billing.state` has 30 per 10 s of its own,
+and `purchases` has 120 per 10 s. All calls from one IP address share 300 per
+10 s on top. A 429 there raises `RateLimitError` with `retry_after`, once the
+call's retries have run out; `purchases.wait` keeps waiting instead.
 
 A Dodo Payments subscription made outside Meterbase's checkout, from a buy link
 or your own server, is held until you link it to its customer once under
@@ -802,31 +802,16 @@ A plan's checkout opens a new subscription, so it is for a customer without a
 paying one. For a customer whose subscription pays and is not cancelling
 (`billing.status` is `active`, `trialing` or `past_due` in their
 [state](#a-customers-billing), and `cancel_at_period_end` is false), it raises
-`ConflictError` with `code == "already_subscribed"`. There is no plan-change
-call yet: a customer who already pays changes plan or interval in the provider's
-customer portal, so link there for their `upgrade`, `downgrade` and
-`switch_interval` offers. A customer whose subscription is cancelling can check
-out a new one, which takes over when the old one ends; its purchase reads `held`
-until then.
-
-Set the portal up once per mode, on the provider's side, and give it only the
-prices or products you bound: a subscription moved onto any other is held for
-review under **Payments**.
-
-- **Stripe:** under Settings → Billing → Customer portal, turn on **Switch
-  plan**, add the bound products and prices, and save. Then **Activate link**,
-  and link to the login link it gives (`https://billing.stripe.com/p/login/…`),
-  where the customer signs in with the email they paid with. In test mode,
-  open a customer's portal from their page in the Stripe Dashboard.
-- **Dodo Payments:** put the bound subscription products in one Product
-  Collection, since the portal changes plans only within one, and turn on
-  **Allow Subscription Updates** under Settings → Subscriptions. Link to
-  `https://customer.dodopayments.com/login/{business_id}`, where the customer
-  asks for a sign-in link by the email they paid with. Test mode sends no
-  sign-in emails, so there your server makes a session with your Dodo key:
-  `POST /customers/{customer_id}/customer-portal/session`, with the
-  `customer.customer_id` of `GET /subscriptions/{id}`, for the
-  `billing.subscription_id` in their [state](#a-customers-billing).
+`ConflictError` with `code == "already_subscribed"`: move them with
+[`billing.change`](#change-cancel-keep-portal) instead, as their plan offers'
+`via == "change"` says. A customer whose subscription is cancelling can check
+out a new one, which takes over when the old one ends, its purchase reading
+`held` until then. That is a second subscription, charged from the start, so
+`keep` and then `change` is the way to move them.
+
+A plan changed in the provider's own portal or dashboard still reaches the
+ledger through the provider's event, as long as it moves onto a bound price: a
+subscription moved onto any other is held for review under **Payments**.
 
 A checkout is never retried unless it is given an `idempotency_key`, 1 to 200
 printable ASCII characters with no spaces. Until the session expires, a repeat
@@ -891,7 +876,7 @@ state.plan  # BillingPlan(key="pro", name="Pro"), or None
 if state.billing and state.billing.status == "past_due":
     print("Payment failing, next retry:", state.billing.next_retry_at)  # None on Dodo
 for offer in state.offers:
-    print(offer.action, offer.plan or offer.pack, offer.price.unit_amount)
+    print(offer.action, offer.via, offer.plan or offer.pack, offer.price.unit_amount)
 ```
 
 One read for a pricing or account page: the plan and its `period`, a change
@@ -906,30 +891,44 @@ what to buy before they buy. A customer that was deleted raises `NotFoundError`
 `billing.status` reads the same on both providers, with a cancelled or expired
 subscription `ended`. Dodo Payments has no `trialing`, since a trial reads
 `active`, and its `on_hold` reads as `unpaid`; `next_retry_at` and `lookup_key`
-are always `None` there.
+are always `None` there. `billing.scheduled_change` is a plan change the
+provider has scheduled, with `plan` `None` when the scheduled price is not
+bound. `pending_change` is the ledger's: while the ledger's period does not end
+with the provider's, it stays `None`, and only `scheduled_change` shows the
+change.
 
 An offer's `action` is `current`, `switch_interval` for the same plan billed
 over another interval, `upgrade` or `downgrade` by price per month against the
-current plan, or `purchase` for a pack. A plan offer is sold to a customer
-without a paying subscription with `checkout(..., plan=offer.plan,
-price=offer.price.id)`, and a pack offer with `pack=offer.pack`. New actions can
-be added; treat one you do not know as unavailable. `price.unit_amount` is the
-price as listed, in the currency's minor unit, cents for USD. Dodo Payments adds
-tax at checkout, by the buyer's location, unless the product's price is tax
-inclusive, so a Dodo Payments buyer can pay more than the offer shows.
-
-A pack offer's `grant` is what one pack gives: `amount` on the meter whose key
-is `meter`, twice that for `quantity=2`, expiring `expires_days` after the
-payment, or never when that is `None`. A plan offer's `grant` is `None`. Choose
-a pack by its grant rather than by name, telling two packs on one meter apart
-by `amount`: Dodo Payments has no lookup keys, and its product ids differ
-between test and live mode.
+current plan, or `purchase` for a pack. `via` names the call that buys it:
+`change` for a plan offer while the customer's subscription pays, cancelling
+included, `checkout` otherwise (a Dodo Payments subscription that ends by its
+term too), and `None` for `current`. A plan offer is sold
+with `plan=offer.plan, price=offer.price.id`, and a pack offer with
+`pack=offer.pack`. New actions can be added; treat one you do not know as
+unavailable. `price.unit_amount` is the price as listed, in the currency's minor
+unit, cents for USD. Dodo Payments adds tax at checkout, by the buyer's
+location, unless the product's price is tax inclusive, so a Dodo Payments buyer
+can pay more than the offer shows.
+
+A pack offer's `grants` is what one pack gives, one entry per meter: `amount`
+on the meter whose key is `meter`, twice that for `quantity=2`, expiring
+`expires_days` after the payment, or never when that is `None`. A plan offer's
+`grants` is empty. Choose a pack by its grants rather than by name, telling two
+packs on one meter apart by `amount`: Dodo Payments has no lookup keys, and its
+product ids differ between test and live mode.
+
+A pack can grant up to five meters at once, such as 500,000 `ai_tokens` and 50
+`credits` for one price, each with its own expiry. A payment grants every meter
+in the pack, and a refund takes back the refunded share of each. `grant` is the
+first entry of `grants`, `None` on a plan offer, and is deprecated: it shows
+one meter of a pack that may grant several.
 
 ```python
 top_up = next(
-    (o for o in state.offers if o.grant and o.grant.meter == "ai_tokens"), None
+    (o for o in state.offers if [g.meter for g in o.grants] == ["ai_tokens"]),
+    None,
 )
-# top_up.grant == {"meter": "ai_tokens", "amount": 200_000, "expires_days": 90}
+# top_up.grants == [{"meter": "ai_tokens", "amount": 200_000, "expires_days": 90}]
 
 if top_up and top_up.pack:
     session = meterbase.billing.checkout(
@@ -939,23 +938,139 @@ if top_up and top_up.pack:
     )
 ```
 
+On Stripe, a plan can bill usage past a soft cap (`allow_overage`): Meterbase
+adds it as a line to the customer's next renewal invoice. An allowance's
+`overage_used` is the usage past `amount` this period, `None` under `no_cap`,
+and `overage_price` the price per unit it is billed at, `None` when none is
+bound. A plan offer's `overage` lists that plan's overage prices by meter, so a
+pricing page can show them before a purchase. Dodo Payments bills no overage
+from Meterbase yet, so there both are `None` and `[]`. An overage price is often
+below one minor unit, so read its `unit_amount_decimal`, the amount in minor
+units as a decimal string: $2 per million tokens is `"0.0002"`, and its
+`unit_amount` is `None`.
+
+### Change, cancel, keep, portal
+
+For a customer whose subscription pays, `billing.change` moves it to another
+plan, or to the same plan at another interval, on the provider. Meterbase then
+brings the ledger along at once, before the provider's own event arrives.
+
+```python
+change = meterbase.billing.change(
+    "acct_1",
+    plan="scale",  # the plan's key
+    # price="scale_yearly", a plan offer's price.id or price.lookup_key
+    # when="now" or "period_end"
+)
+
+if change.outcome == "declined":
+    ...  # the charge was refused and nothing changed; change.declined says why
+```
+
+Without `price`, the plan's price at the subscription's current interval is
+used, else its first bound price. `action` is what the plan offer shows, and
+sets when the change happens unless `when` says otherwise:
+
+| `action`          | `when` by default                                             |
+| ----------------- | ------------------------------------------------------------- |
+| `upgrade`         | `"now"`, charging the difference at once                      |
+| `downgrade`       | `"period_end"`                                                |
+| `switch_interval` | `"now"` to a longer interval, `"period_end"` to a shorter one |
+
+| `outcome`   | Means                                                                                                      |
+| ----------- | ---------------------------------------------------------------------------------------------------------- |
+| `changed`   | the subscription is on the new price now                                                                   |
+| `scheduled` | the change happens at `effective_at`, the period end                                                       |
+| `pending`   | Dodo Payments took the change and is still charging for it; the plan moves once the payment succeeds       |
+| `declined`  | Stripe refused the charge, and nothing changed: `declined` is `card_declined` or `authentication_required` |
+| `unchanged` | the subscription is already on that price                                                                  |
+| `preview`   | `preview=True`: what the change would do, with nothing written                                             |
+
+`due_now` is what the provider takes now, in minor units; a negative amount is a
+credit to the customer's balance on Stripe. It is `None` for a change at the
+period end, and on Dodo Payments after a real change, which Dodo answers with no
+amount; a preview has it on both. An upgrade is charged off session to the saved
+payment method, so a card that asks for 3D Secure answers `declined` with
+`authentication_required`. `ledger_updated` is true when `billing.state` already
+shows the result; after `changed` or `scheduled`, a false means the provider's
+event brings it there.
+
+`change`, `cancel`, `keep` and `portal` are safe to repeat, so the SDK retries
+them as it does a `GET`. A change already made answers `unchanged`, or
+`scheduled` for the same change at the period end, and nothing is charged twice.
+
+`billing.cancel` ends the subscription at the period end, `effective_at`, and
+never at once. Until then the customer keeps their plan, and then moves to the
+fallback plan set under **Payments**; without one, that event waits there for
+review. A cancel already set answers `unchanged`. Usage past a soft cap in this
+last period is recorded, not invoiced, so use a hard cap where that matters.
+
+`billing.keep` drops a scheduled plan change or cancel, on the provider and then
+in the ledger, and answers `unchanged` when nothing was scheduled. While either
+is scheduled (`billing.scheduled_change`, or `cancel_at_period_end`), `change`
+and `cancel` raise `ConflictError` with `code == "change_scheduled"` rather than
+replace it, so a cancelling customer who wants another plan takes two calls:
+
+```python
+meterbase.billing.keep("acct_1")
+meterbase.billing.change("acct_1", plan="scale")
+```
+
+On Dodo Payments, an upgrade answers `pending` while its charge runs: read
+`billing.state` afterwards to see whether the plan moved, since a failed charge
+leaves it as it was and nothing records the attempt. Another change meanwhile
+raises `ConflictError` with `code == "change_pending"`. `cancel_at_period_end`
+is also true there for a subscription that ends by its own term, which `keep`
+cannot clear: `change` raises `ConflictError` with `code == "ends_by_term"`, and
+`cancel` answers `unchanged`. Start a new subscription with `checkout`; it takes
+over when this one ends.
+
+`billing.portal` makes a session in the provider's customer portal, where the
+customer updates their payment method, reads invoices and cancels:
+
+```python
+portal = meterbase.billing.portal(
+    "acct_1", return_url="https://app.example.com/account"
+)
+redirect(portal.url)  # now
+```
+
+`return_url` is required: https, or http on localhost. On Stripe the session
+uses a portal setup named Meterbase, which Meterbase adds to the account once:
+payment methods, invoices, billing details, and cancelling at the period end,
+with switching plans left to `change`. A Stripe session expires 5 minutes after
+it is made, and once opened an hour after its last use, so make one when the
+customer asks and redirect at once. A cancel in the Stripe portal may fail
+while a change is scheduled; call `keep`, then `billing.cancel`. On Dodo
+Payments the portal is set up in Dodo, and a session lasts 24 hours. A customer
+who has not paid through the provider yet has no portal, and raises
+`ConflictError` with `code == "no_provider_customer"`.
+
 ### Billing errors
 
-| `code`                   | Raises                           | Calls               | When                                                                     |
-| ------------------------ | -------------------------------- | ------------------- | ------------------------------------------------------------------------ |
-| `unauthenticated`        | `AuthenticationError`, 401       | all                 | unknown, revoked or malformed key                                        |
-| `payments_not_connected` | `ConflictError`, 409             | all                 | the workspace has no payment provider connected                          |
-| `already_subscribed`     | `ConflictError`, 409             | `checkout`          | a plan checkout for a customer who already pays                          |
-| `customer_deleted`       | `ConflictError`, 409             | `checkout`          | the customer was deleted                                                 |
-| `idempotency_key_reused` | `IdempotencyKeyReusedError`, 409 | `checkout`          | the `idempotency_key` was used for a different checkout                  |
-| `customer_not_found`     | `NotFoundError`, 404             | `state`             | the customer was deleted                                                 |
-| `purchase_not_found`     | `NotFoundError`, 404             | `purchases`         | no checkout has that session id; `wait` reads it as waiting              |
-| `price_not_bound`        | `InvalidRequestError`, 422       | `checkout`          | the plan or pack has nothing bound, or `price` is not bound to the plan  |
-| `invalid_request`        | `InvalidRequestError`, 422       | `checkout`, `state` | a field failed validation; the message names it                          |
-| `rate_limited`           | `RateLimitError`, 429            | all                 | past a [limit](#billing), with `retry_after`; `wait` keeps waiting       |
-| `provider_error`         | `ServerError`, 502               | all                 | the provider refused or failed; the message says which                   |
-| `unavailable`            | `ServerError`, 503               | all                 | the connected key could not be opened: disconnect, then connect it again |
-| `engine_unavailable`     | `ServerError`, 503               | all                 | Meterbase could not be reached                                           |
+| `code`                   | Raises                           | Calls                                            | When                                                                                           |
+| ------------------------ | -------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| `unauthenticated`        | `AuthenticationError`, 401       | all                                              | unknown, revoked or malformed key                                                              |
+| `payments_not_connected` | `ConflictError`, 409             | all                                              | the workspace has no payment provider connected                                                |
+| `payments_not_live`      | `ConflictError`, 409             | `checkout`, `change`, `cancel`, `keep`, `portal` | a live workspace that has not finished Go live in the dashboard, or that Meterbase has closed  |
+| `already_subscribed`     | `ConflictError`, 409             | `checkout`                                       | a plan checkout for a customer who already pays: use `change`                                  |
+| `customer_deleted`       | `ConflictError`, 409             | `checkout`                                       | the customer was deleted                                                                       |
+| `idempotency_key_reused` | `IdempotencyKeyReusedError`, 409 | `checkout`                                       | the `idempotency_key` was used for a different checkout                                        |
+| `not_subscribed`         | `ConflictError`, 409             | `change`, `cancel`, `keep`                       | the customer has no active subscription through the provider, or its price is bound to no plan |
+| `payment_failing`        | `ConflictError`, 409             | `change`, `cancel`                               | the last payment failed: send the customer to `portal` to update their card, then try again    |
+| `change_scheduled`       | `ConflictError`, 409             | `change`, `cancel`                               | a plan change or a cancel is already scheduled: call `keep` first                              |
+| `change_pending`         | `ConflictError`, 409             | `change`                                         | Dodo Payments: a plan change is waiting for its payment; read `state`, then try again          |
+| `ends_by_term`           | `ConflictError`, 409             | `change`                                         | Dodo Payments: the subscription ends by its term; start a new one with `checkout`              |
+| `customer_busy`          | `ConflictError`, 409             | `change`, `cancel`, `keep`                       | another change for the customer is running; try again in a moment                              |
+| `no_provider_customer`   | `ConflictError`, 409             | `portal`                                         | the customer has not paid through the provider yet                                             |
+| `customer_not_found`     | `NotFoundError`, 404             | all but `checkout` and `purchases`               | the customer was deleted                                                                       |
+| `purchase_not_found`     | `NotFoundError`, 404             | `purchases`                                      | no checkout has that session id; `wait` reads it as waiting                                    |
+| `price_not_bound`        | `InvalidRequestError`, 422       | `checkout`, `change`                             | the plan or pack has nothing bound, or `price` is not bound to the plan                        |
+| `invalid_request`        | `InvalidRequestError`, 422       | all but `purchases`                              | a field failed validation; the message names it                                                |
+| `rate_limited`           | `RateLimitError`, 429            | all                                              | past a [limit](#billing), with `retry_after`; `wait` keeps waiting                             |
+| `provider_error`         | `ServerError`, 502               | all                                              | the provider refused or failed; the message says which                                         |
+| `unavailable`            | `ServerError`, 503               | all                                              | the connected key could not be opened: disconnect, then connect it again                       |
+| `engine_unavailable`     | `ServerError`, 503               | all                                              | Meterbase could not be reached                                                                 |
 
 ## Webhooks
 
@@ -1133,7 +1248,7 @@ except RateLimitError as error:
 | `InvalidIdempotencyKeyError`             | 422 — an `InvalidRequestError`: the key was not a UUIDv7                                                                                  |
 | `TooLateError`                           | 422 — an `InvalidRequestError`: the key is over an hour from the engine's clock, which it carries on `server_time`. Nothing was recorded |
 | `ReservationMismatchError`               | 422 — an `InvalidRequestError`: the reservation was made for a different customer or meter                                                |
-| `RateLimitError`                         | 429 — `check` or `reserve` past the workspace's fair-use rate, `code == "rate_limited"`, with `retry_after` in seconds. `reserve` retries it for you; `check` raises at once, so fail open or closed. Also a billing call past its [per-key limit](#billing), once a `GET` or a keyed checkout has retried it; `purchases.wait` keeps waiting |
+| `RateLimitError`                         | 429 — `check` or `reserve` past the workspace's fair-use rate, `code == "rate_limited"`, with `retry_after` in seconds. `reserve` retries it for you; `check` raises at once, so fail open or closed. Also a billing call past its [per-key limit](#billing), once the call's retries have run out; `purchases.wait` keeps waiting |
 | `ServerError`                            | 5xx                                                                                                                                       |
 | `APIConnectionError` / `APITimeoutError` | the request never got an answer                                                                                                           |
 | `WebhookVerificationError`               | `verify_webhook`: not a delivery Meterbase signed in the last five minutes                                                                |
@@ -1153,7 +1268,7 @@ SDK would raise for a response, for realistic errors in your own tests.
 Meterbase(
     api_key="mb_sk_live_…",
     base_url="https://api.meterbase.tech",
-    billing_base_url="https://service.meterbase.tech",  # billing and purchases
+    billing_base_url="https://billing.meterbase.tech",  # billing and purchases
     timeout=10.0,  # seconds, per attempt, on every call; unset, 35, and 3 for check
     max_retries=2,
     http_client=httpx.Client(proxy="http://localhost:8030"),  # yours to close
@@ -1168,7 +1283,7 @@ there — failing open or failing closed — rather than leaving the user waitin
 out the 35 s the writes get. Pass an `http_client` for proxies,
 limits or a transport of your own: an `httpx.Client` for `Meterbase`, an
 `httpx.AsyncClient` for `AsyncMeterbase`. `billing` and `purchases` go to
-`billing_base_url`, `https://service.meterbase.tech` unless set, and every other
+`billing_base_url`, `https://billing.meterbase.tech` unless set, and every other
 call to `base_url`, over the same connections.
 
 For other settings on some calls, derive a client with them. It shares the
@@ -1188,15 +1303,18 @@ cancelled `track` cannot record usage twice. A sync call cannot be cancelled;
 bound it with `timeout` and `max_retries` instead.
 
 **Retries** apply to `GET`, `DELETE`, `track`, `reserve`, `customers.ensure`,
-and a grant, plan change or `billing.checkout` given an `idempotency_key`, on
-connection failures, timeouts, 408, 429 and 5xx, with exponential backoff and
-full jitter. `Retry-After` is honoured when Meterbase sends it, up to eight
-seconds. Every other `POST` and `PATCH` is never replayed, because a retried
-create could produce a second row. An `ensure` can be, because running it twice
-changes nothing: one whose first attempt landed answers `created` false. So can
-a keyed grant or plan change, which the engine answers with what the first
-attempt wrote: one whose first attempt landed answers `replayed` true. A keyed
-checkout is answered by Meterbase with the session its first attempt opened.
+`billing.change`, `cancel`, `keep` and `portal`, and a grant, plan change or
+`billing.checkout` given an `idempotency_key`, on connection failures, timeouts,
+408, 429 and 5xx, with exponential backoff and full jitter. `Retry-After` is
+honoured when Meterbase sends it, up to eight seconds. Every other `POST` and
+`PATCH` is never replayed, because a retried create could produce a second row.
+An `ensure` can be, because running it twice changes nothing: one whose first
+attempt landed answers `created` false. So can a keyed grant or plan change,
+which the engine answers with what the first attempt wrote: one whose first
+attempt landed answers `replayed` true. A keyed checkout is answered by
+Meterbase with the session its first attempt opened. So is a `billing.change`,
+which Meterbase checks against the subscription itself: one whose first attempt
+landed answers `unchanged`, or `scheduled` at the period end.
 
 `track` and `reserve` are the exception because they carry an idempotency key,
 and because the SDK fixes that key **before** the retry loop starts: every
@@ -1225,11 +1343,19 @@ Pre-1.0, the minor version is where breaking changes land — deliberately, so a
 change that will not run against your code cannot arrive as a patch. The SDK
 follows the engine's API, as the TypeScript SDK (`mbase-sdk`) does.
 
+**0.6.0** adds `billing.change`, `billing.cancel`, `billing.keep` and
+`billing.portal`, and `billing_base_url` now defaults to
+`https://billing.meterbase.tech`. The old host still answers, so nothing in it
+breaks code written for 0.5.
+
+**0.5.1** adds `grants` to a billing offer: every meter a pack grants. `grant`,
+the first of them, stays and is deprecated.
+
 **0.5.0** adds `billing` and `purchases`, for a workspace that sells through
 Stripe or Dodo Payments: `billing.checkout`, `billing.state`,
 `purchases.retrieve` and `purchases.wait`, with the `billing_base_url` option.
-They go to the service at `https://service.meterbase.tech` rather than the
-engine. Nothing in it breaks code written for 0.4.0.
+They go to the Meterbase service rather than the engine. Nothing in it breaks
+code written for 0.4.0.
 
 **0.4.0** pages the customer list, and adds `customers.list_all` and the
 `limit`, `starting_after`, `plan` and `has_plan` parameters. One change can break