fcloud-sdk 0.3.0__tar.gz → 0.3.1__tar.gz

{fcloud_sdk-0.3.0 → fcloud_sdk-0.3.1}/CHANGELOG.md

@@ -6,6 +6,50 @@ versions follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-09-22
+
+### Fixed
+- `fcloud credits buy` no longer turns auto-refill on by default. It used to
+  consent on behalf of anyone who had never consented before, so buying less
+  than the auto-refill threshold enrolled the account and then charged the
+  saved card for the full top-up seconds later — `buy 10` against the default
+  $25 threshold cost $110. Consent is now opt-in via `--autorefill`, and
+  `--autorefill` also turns the setting back on for an account that had it
+  off, which consent alone cannot do. `--no-autorefill` is still accepted and
+  is now the default; passing both is an error.
+- Before a purchase that will trigger a top-up, the CLI now says so and names
+  the amount. What triggers one is the balance a purchase *leaves behind*,
+  not its size, and the refill is sized to clear the threshold — so $10
+  against a $200 threshold charges the card a further $195, not the $50 the
+  setting says. Both numbers are worked out and printed before anything is
+  charged, including under `--yes`, and including for an account that was
+  already armed.
+- `fcloud credits` no longer claims auto-refill "turns on with your first
+  purchase". It turns on with a purchase made with `--autorefill`, and the
+  status line now says so and names that command.
+- `fcloud credits buy` no longer sends buyers to a dead address after paying.
+  The return URL was built from a domain baked in at release time, which
+  outlived its DNS record: the charge succeeded and the browser landed on a
+  404. The CLI now names no return address and the dispatcher supplies one
+  from its own allowlist, which redeploys with the web app instead of going
+  stale in a published wheel. Setting `FCLOUD_WEB_URL` returns you to
+  `/dashboard`, the page that reads the result, rather than to
+  `/dashboard/billing`, which ignores it.
+
+### Changed
+- `resolve_web_url()` returns `None` when no web URL is configured, and
+  `DEFAULT_WEB_URL` is gone. `Client.start_credit_checkout()` takes
+  `success_url` and `cancel_url` as optional and omits them from the request
+  when unset. Set `FCLOUD_WEB_URL` only to override where a buyer is returned
+  to. **Needs a dispatcher carrying the matching server change**; against an
+  older one, set `FCLOUD_WEB_URL` or buy from the dashboard.
+
+### Added
+- `fcloud.billing_types.predicted_topup_micros()` — what auto-refill would
+  charge once a given purchase has posted. Mirrors the dispatcher's own
+  `topUpAmount` and daily-cap clamp so a confirmation can name the second
+  charge before the card is saved.
+
 ## [0.3.0] - 2026-09-16
 
 ### Fixed

{fcloud_sdk-0.3.0/src/fcloud_sdk.egg-info → fcloud_sdk-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fcloud-sdk
-Version: 0.3.0
+Version: 0.3.1
 Summary: Python SDK and CLI for the fcloud GPU compute platform
 Author: fcloud
 License-Expression: Apache-2.0

{fcloud_sdk-0.3.0 → fcloud_sdk-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fcloud-sdk"
-version = "0.3.0"
+version = "0.3.1"
 description = "Python SDK and CLI for the fcloud GPU compute platform"
 readme = "README.md"
 license = "Apache-2.0"

{fcloud_sdk-0.3.0 → fcloud_sdk-0.3.1}/src/fcloud/billing_types.py

@@ -41,6 +41,12 @@ NOT_ARMED_REASONS = ("driver_off", "disabled", "not_consented", "no_card")
 PURCHASE_MIN_MICROS = 10_000_000
 PURCHASE_MAX_MICROS = 5_000_000_000
 
+# The smallest refill the scheduler will mint (billing_autorefill.go:29) and
+# the ledger's unit ratio (billing_topup_contract.go:129). Both are inputs to
+# predicted_topup_micros below.
+AUTOREFILL_MIN_AMOUNT_MICROS = 10_000_000
+MICROS_PER_CENT = 10_000
+
 # Ledger paging (billing_ledger_handlers.go).
 LEDGER_PAGE_DEFAULT = 50
 LEDGER_PAGE_MAX = 200
@@ -155,6 +161,57 @@ class CreditBalance:
         )
 
 
+def _whole_cents(micros: int) -> int:
+    """Floor to a whole cent the way the dispatcher does.
+
+    topUpWholeCents is ``micros - micros%microsPerCent`` in Go, whose ``%``
+    truncates toward zero. Python's floors, which differs for negatives, so
+    spell the truncation out rather than inherit the wrong one.
+    """
+    remainder = abs(micros) % MICROS_PER_CENT
+    return micros - remainder if micros >= 0 else micros + remainder
+
+
+def predicted_topup_micros(balance: CreditBalance, purchase_micros: int = 0) -> int:
+    """What auto-refill charges once ``purchase_micros`` has posted, or 0 for nothing.
+
+    Mirrors topUpAmount (billing_topup.go:169) and topUpWithinDailyCap
+    (billing_topup_schedule.go:94) so a confirmation can name the second
+    charge *before* the card is saved. Keep the two in step.
+
+    This is the charge auto-refill would make, not a promise that it will.
+    Two known imprecisions, both erring toward over-statement, which is the
+    safe direction for a consent prompt:
+
+    - ``charged_24h_usd_micros`` is left at zero by the dispatcher unless the
+      account's own three legs already pass (billing_balance_view.go:108-120),
+      so for an account that is not armed yet the daily-cap clamp is skipped
+      and this is an upper bound.
+    - A deployment whose top-up driver is off charges nothing at all. That is
+      deliberately ignored: the driver can be re-armed, and what the prompt
+      describes is a standing order, not this particular hour.
+    """
+    autorefill = balance.autorefill
+    if autorefill.threshold_usd_micros <= 0:
+        return 0
+    # The trigger is the balance this purchase leaves behind, not the size of
+    # the purchase — and it is a strict `<`, so landing exactly on the
+    # threshold does not fire.
+    available = balance.available_usd_micros + purchase_micros
+    if available >= autorefill.threshold_usd_micros:
+        return 0
+    # Enough to clear the threshold when the hole is deeper than the
+    # configured amount, which is how a $100 refill becomes a $195 one.
+    want = max(autorefill.amount_usd_micros,
+               autorefill.threshold_usd_micros - available)
+    want = _whole_cents(min(want, PURCHASE_MAX_MICROS))
+    if autorefill.daily_cap_usd_micros > 0:
+        headroom = autorefill.daily_cap_usd_micros - autorefill.charged_24h_usd_micros
+        if headroom < want:
+            want = _whole_cents(headroom)
+    return want if want >= AUTOREFILL_MIN_AMOUNT_MICROS else 0
+
+
 @dataclass
 class CreditEntry:
     """One signed money movement on the ledger (member-redacted view).

{fcloud_sdk-0.3.0 → fcloud_sdk-0.3.1}/src/fcloud/cli/credits.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import sys
 
+from fcloud.billing_types import CreditBalance, predicted_topup_micros
 from fcloud.cli import output
 from fcloud.cli.common import _extract_flag
 from fcloud.cli.credits_buy import await_purchase, open_checkout, start_checkout
@@ -29,12 +30,19 @@ at zero new work is refused until you top up.
 
   fcloud credits                       # balance, auto-refill, card
   fcloud credits buy 25                # buy $25 via hosted checkout
+  fcloud credits buy 25 --autorefill   # ...and let a saved card top you up
   fcloud credits autorefill on         # let a saved card top you up
   fcloud credits autorefill set --threshold 25 --amount 100
   fcloud credits statement --limit 20  # recent ledger rows
 
 `available` is the number that matters: it is your posted balance minus
-usage that has been metered but not yet billed to the ledger."""
+usage that has been metered but not yet billed to the ledger.
+
+Buying is a one-off: `buy` never turns auto-refill on unless you pass
+`--autorefill`. What triggers a top-up is the balance a purchase leaves
+behind, not its size — buy too little to clear your own threshold and
+auto-refill charges the card again straight away. The confirmation works
+that out and names the amount before anything is charged."""
 
 
 
@@ -71,18 +79,37 @@ def _cmd_balance(args: list[str]) -> None:
 
 def _cmd_buy(args: list[str]) -> None:
     assume_yes, rest = _take_bool(args, "--yes")
+    want_autorefill, rest = _take_bool(rest, "--autorefill")
     no_autorefill, rest = _take_bool(rest, "--no-autorefill")
     if len(rest) != 1:
-        output._fail("Usage: fcloud credits buy <usd> [--yes] [--no-autorefill]",
+        output._fail(
+            "Usage: fcloud credits buy <usd> [--yes] [--autorefill|--no-autorefill]",
+            code="usage", exit_code=2)
+    if want_autorefill and no_autorefill:
+        output._fail("--autorefill and --no-autorefill contradict each other",
                      code="usage", exit_code=2)
     micros = _parse_usd(rest[0])
     client = _client()
     balance = client.credit_balance()
-    consent = not no_autorefill and not balance.autorefill.consented_at
-    if not assume_yes and not _confirm_purchase(micros, consent):
+    # Consent is opt-IN. It used to default on for anyone who had never
+    # consented, which meant `buy 10` enrolled you at the default $25
+    # threshold and a $100 top-up fired seconds later, against a card you
+    # had only just saved. Buying credit and standing an order to buy more
+    # are different decisions; only --autorefill makes the second one.
+    need_consent, need_enable = _autorefill_changes(balance, want_autorefill)
+    # Printed even under --yes: it names a second charge, and consenting to
+    # the purchase in advance is not the same as knowing about that one.
+    notice = _autorefill_notice(micros, balance, want_autorefill)
+    if notice:
+        print(notice)
+    if not assume_yes and not _ask_yes_no(f"Buy {usd(micros)} of credit?"):
         print("Nothing was charged.")
         return
-    start = start_checkout(client, micros, consent)
+    # Before checkout, not after: enabled-but-unconsented is simply not
+    # armed, so a checkout the buyer abandons leaves nothing standing.
+    if need_enable:
+        client.set_autorefill(enabled=True)
+    start = start_checkout(client, micros, need_consent)
     open_checkout(start.url)
     await_purchase(client, start.purchase_id, balance.balance_usd_micros)
 
@@ -195,11 +222,52 @@ def _parse_usd(raw: str, *, flag: str = "") -> int:
     return micros
 
 
-def _confirm_purchase(micros: int, consent: bool) -> bool:
-    line = f"Buy {usd(micros)} of credit?"
-    if consent:
-        line += " Auto-refill will be turned ON."
-    return _ask_yes_no(line)
+def _autorefill_changes(balance: CreditBalance, want: bool) -> tuple[bool, bool]:
+    """What `--autorefill` still has to change: (stamp consent, set enabled).
+
+    Two separate rows, and a purchase only reaches the first: the dispatcher
+    stamps autorefill_consented_at from the Checkout metadata and never
+    writes autorefill_enabled (billing_webhook_purchase.go:225). Consent is
+    not settable any other way, and the enabled flag is not settable by a
+    purchase — so an account that ran `autorefill off` needs a settings
+    write too, or the flag promises an arming that never happens. Hence the
+    pair, rather than one "turn it on" boolean.
+    """
+    return (want and not balance.autorefill.consented_at,
+            want and not balance.autorefill.enabled)
+
+
+def _autorefill_notice(micros: int, balance: CreditBalance, want: bool) -> str:
+    """What this purchase does to auto-refill, and what that will cost.
+
+    The second charge is the one people get wrong. It fires on the balance
+    the purchase leaves behind rather than on the purchase itself, and it is
+    sized to clear the threshold, so it can be several times the configured
+    amount. Say both before the card is saved, not after it is charged.
+    """
+    autorefill = balance.autorefill
+    need_consent, need_enable = _autorefill_changes(balance, want)
+    parts: list[str] = []
+    if need_consent or need_enable:
+        parts.append(
+            f"Auto-refill will be turned ON: {usd(autorefill.amount_usd_micros)} "
+            f"whenever your available balance falls below "
+            f"{usd(autorefill.threshold_usd_micros)}.")
+    elif want:
+        parts.append("Auto-refill is already on; this purchase does not change it.")
+    # Armed once this settles: it already was, or this purchase supplies the
+    # consent and the card that arm it.
+    armed_after = autorefill.armed or need_consent or need_enable
+    topup = predicted_topup_micros(balance, micros) if armed_after else 0
+    if topup:
+        after = balance.available_usd_micros + micros
+        parts.append(
+            f"Your available balance after this purchase is {usd(after)}, which is "
+            f"below {usd(autorefill.threshold_usd_micros)}, so auto-refill will "
+            f"charge your card a further {usd(topup)} within the hour — run "
+            f"`fcloud credits autorefill set --threshold` first if that is not "
+            f"what you want.")
+    return "\n".join(parts)
 
 
 def _ask_yes_no(question: str) -> bool:

{fcloud_sdk-0.3.0 → fcloud_sdk-0.3.1}/src/fcloud/cli/credits_buy.py

@@ -27,12 +27,21 @@ _PURCHASE_POLL_INTERVAL = 3
 
 def start_checkout(client: Client, micros: int, consent: bool):
     """Mint the hosted Checkout session, naming the remedy on refusals."""
+    # No FCLOUD_WEB_URL means we name no return address and the dispatcher
+    # fills one from its allowlist. That is the preferred path: it is the
+    # only copy of the dashboard's address that redeploys with it.
     base = resolve_web_url()
     try:
         return client.start_credit_checkout(
             amount_usd_micros=micros,
-            success_url=f"{base}/dashboard/billing?purchase=success",
-            cancel_url=f"{base}/dashboard/billing?purchase=cancelled",
+            # The same paths the dispatcher would have chosen
+            # (billing_checkout_handlers.go:101-104). /dashboard is the page
+            # that reads ?purchase=; /dashboard/billing does not, so a buyer
+            # sent there watches nothing happen. Stripe substitutes the
+            # session id.
+            success_url=(f"{base}/dashboard?purchase={{CHECKOUT_SESSION_ID}}"
+                         if base else None),
+            cancel_url=f"{base}/dashboard?purchase=cancelled" if base else None,
             autorefill_consent=consent,
         )
     except FcloudError as exc:
@@ -40,12 +49,21 @@ def start_checkout(client: Client, micros: int, consent: bool):
                      code=str(exc) or "checkout_failed")
 
 
-def _checkout_error_message(code: str, base: str) -> str:
+def _checkout_error_message(code: str, base: str | None) -> str:
     """Turn the dispatcher's bare checkout codes into a recovery sentence."""
     if code == "bad_return_url":
+        if base is None:
+            return ("this deployment rejected its own checkout return address "
+                    "— an operator should check FCLOUD_CHECKOUT_RETURN_ORIGINS, "
+                    "or buy credit from the dashboard directly")
         return (f"this deployment does not allow {base} as a checkout return "
-                f"address — set FCLOUD_WEB_URL to your dashboard's origin, "
+                f"address — unset FCLOUD_WEB_URL to let the server choose, "
                 f"or buy credit from the dashboard directly")
+    if code == "return_url_required":
+        return ("this deployment has no checkout return origin configured, so "
+                "it cannot say where to send you after paying — an operator "
+                "should set FCLOUD_CHECKOUT_RETURN_ORIGINS, or set "
+                "FCLOUD_WEB_URL here to name your dashboard yourself")
     if code == "billing_mode_not_prepaid":
         return ("this deployment still bills by invoice, so there is no "
                 "credit to buy yet")

{fcloud_sdk-0.3.0 → fcloud_sdk-0.3.1}/src/fcloud/cli/credits_render.py

@@ -15,7 +15,7 @@ from fcloud.billing_types import AutorefillView, CreditBalance, LedgerPage
 _NOT_ARMED_SENTENCES = {
     "driver_off": "auto-refill is paused platform-wide right now",
     "disabled": "auto-refill is off",
-    "not_consented": "auto-refill turns on with your first purchase",
+    "not_consented": "you have not consented to it yet",
     "no_card": "no card is saved, so nothing can top you up",
 }
 
@@ -82,6 +82,10 @@ def print_autorefill(autorefill: AutorefillView) -> None:
     print(f"Auto-refill: OFF — {reason}")
     if autorefill.not_armed_reason in ("disabled", ""):
         print("  Turn it on: fcloud credits autorefill on")
+    elif autorefill.not_armed_reason == "not_consented":
+        # Consent is stamped by a purchase and by nothing else — no settings
+        # write can grant it — so this is the only remedy there is.
+        print("  Consent with a purchase: fcloud credits buy 25 --autorefill")
     elif autorefill.not_armed_reason == "no_card":
         print("  Add a card with your first purchase: fcloud credits buy 25")
 

{fcloud_sdk-0.3.0 → fcloud_sdk-0.3.1}/src/fcloud/cli_args.py

@@ -336,7 +336,8 @@ SPECS: dict[str, CmdSpec] = {
     # credits <balance|buy|autorefill|statement> — the prepaid wallet; the
     # widest positional shape is `credits autorefill set`.
     "credits": CmdSpec("credits", (
-        Flag(("--yes",), BOOL), Flag(("--no-autorefill",), BOOL),
+        Flag(("--yes",), BOOL), Flag(("--autorefill",), BOOL),
+        Flag(("--no-autorefill",), BOOL),
         Flag(("--threshold",)), Flag(("--amount",)), Flag(("--daily-cap",)),
         Flag(("--limit",)),
     ), tail=POSITIONAL, max_positionals=2),

{fcloud_sdk-0.3.0 → fcloud_sdk-0.3.1}/src/fcloud/client_billing.py

@@ -82,24 +82,31 @@ class ClientBillingMixin:
         self,
         *,
         amount_usd_micros: int,
-        success_url: str,
-        cancel_url: str,
+        success_url: str | None = None,
+        cancel_url: str | None = None,
         autorefill_consent: bool = False,
     ) -> CheckoutStart:
         """Open a hosted Stripe Checkout session for a credit purchase.
 
         Returns the URL to send the buyer to; the credit lands on the
-        ledger when Stripe's webhook settles, not when this returns. The
-        return URLs must be absolute https (http only for localhost) and,
-        where the deployment restricts them, on an allowed origin.
+        ledger when Stripe's webhook settles, not when this returns.
+
+        Leave the return URLs unset to let the dispatcher supply them from
+        its own allowlist — the recommended path, since it cannot point at
+        a dashboard that has moved. Passing them keeps the old behaviour:
+        absolute https (http only for localhost) and, where the deployment
+        restricts them, on an allowed origin.
         """
+        body: dict[str, object] = {
+            "amount_usd_micros": int(amount_usd_micros),
+            "autorefill_consent": bool(autorefill_consent),
+        }
+        # Omitted, not empty: "" is how the server spells "caller named
+        # none", but sending the key at all reads as an attempt to set it.
+        if success_url:
+            body["success_url"] = success_url
+        if cancel_url:
+            body["cancel_url"] = cancel_url
         return CheckoutStart.from_response(self._post(
-            "/v1/billing/checkout",
-            {
-                "amount_usd_micros": int(amount_usd_micros),
-                "autorefill_consent": bool(autorefill_consent),
-                "success_url": success_url,
-                "cancel_url": cancel_url,
-            },
-            timeout=30,
+            "/v1/billing/checkout", body, timeout=30,
         ))

{fcloud_sdk-0.3.0 → fcloud_sdk-0.3.1}/src/fcloud/config.py

@@ -40,12 +40,13 @@ if TYPE_CHECKING:
 
 DEFAULT_URL = "https://fcloud-dispatcher.fly.dev"
 
-# The public web app, used only to build the return URLs a hosted Checkout
-# sends the buyer back to. The dispatcher validates those against its own
-# FCLOUD_CHECKOUT_RETURN_ORIGINS allowlist, so a deployment whose web app
-# lives elsewhere must either set FCLOUD_WEB_URL here or allowlist this one
-# — otherwise `fcloud credits buy` is refused with bad_return_url.
-DEFAULT_WEB_URL = "https://foomcloud.sh"
+# There is deliberately no default web URL. This value only builds the
+# return address a hosted Checkout sends the buyer back to, and a constant
+# compiled into a published wheel cannot follow the web app when it moves:
+# the previous default outlived its DNS record and dropped every CLI buyer
+# on a 404 after their card had already been charged. The dispatcher holds
+# the live answer in FCLOUD_CHECKOUT_RETURN_ORIGINS and fills the URLs in
+# when we send none, so unset means "let the server say", not "guess".
 
 CONFIG_DIR = Path.home() / ".fcloud"
 # ponytail: legacy config dir; drop once users re-run `fcloud set_token`.
@@ -501,8 +502,13 @@ def _has_torch(packages: list[str]) -> bool:
     return any("torch" in p.lower() for p in packages)
 
 
-def resolve_web_url(explicit: str | None = None) -> str:
-    """Return the public web app's base URL (no trailing slash).
+def resolve_web_url(explicit: str | None = None) -> str | None:
+    """Return the configured web app base URL, or None if none is set.
+
+    None is a real answer, not a failure: the dispatcher fills the checkout
+    return URLs from its own allowlist when we send none, which is the only
+    copy of that address that cannot go stale. Override it only to point a
+    buyer at a different dashboard than the deployment's own.
 
     Unlike the dispatcher URL this is not a credential-bearing endpoint, so
     it is resolved from the plain environment without the dotenv/token
@@ -515,4 +521,4 @@ def resolve_web_url(explicit: str | None = None) -> str:
         value = os.environ.get(name, "").strip()
         if value:
             return value.rstrip("/")
-    return DEFAULT_WEB_URL
+    return None

{fcloud_sdk-0.3.0 → fcloud_sdk-0.3.1/src/fcloud_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fcloud-sdk
-Version: 0.3.0
+Version: 0.3.1
 Summary: Python SDK and CLI for the fcloud GPU compute platform
 Author: fcloud
 License-Expression: Apache-2.0

{fcloud_sdk-0.3.0 → fcloud_sdk-0.3.1}/src/fcloud_sdk.egg-info/SOURCES.txt

@@ -85,6 +85,7 @@ src/fcloud_sdk.egg-info/top_level.txt
 src/foom/__init__.py
 tests/conftest.py
 tests/test_autoresearch.py
+tests/test_billing_types.py
 tests/test_checkpoint_option.py
 tests/test_cli_args.py
 tests/test_cli_dispatch.py

fcloud_sdk-0.3.1/tests/test_billing_types.py

@@ -0,0 +1,93 @@
+"""`predicted_topup_micros` against the dispatcher's own arithmetic.
+
+Pure function, so these are unit tests: the point is that the SDK's mirror of
+topUpAmount (billing_topup.go:169) and topUpWithinDailyCap
+(billing_topup_schedule.go:94) stays in step with them. Every case below
+names the server behaviour it pins.
+"""
+
+from __future__ import annotations
+
+from fcloud.billing_types import CreditBalance, predicted_topup_micros
+
+
+def _balance(available: int, **autorefill) -> CreditBalance:
+    """A prepaid balance whose auto-refill rule is armed unless said otherwise."""
+    rule = {
+        "enabled": True, "armed": True,
+        "threshold_usd_micros": 25_000_000,
+        "amount_usd_micros": 100_000_000,
+        "daily_cap_usd_micros": 500_000_000,
+    }
+    rule.update(autorefill)
+    return CreditBalance.from_response({
+        "billing_mode": "prepaid",
+        "balance_usd_micros": available,
+        "available_usd_micros": available,
+        "autorefill": rule,
+    })
+
+
+def test_a_purchase_that_clears_the_threshold_charges_nothing() -> None:
+    assert predicted_topup_micros(_balance(40_000_000), 10_000_000) == 0
+
+
+def test_landing_exactly_on_the_threshold_does_not_fire() -> None:
+    """The dispatcher skips on `available >= threshold`, not `>`."""
+    assert predicted_topup_micros(_balance(15_000_000), 10_000_000) == 0
+
+
+def test_a_cent_below_the_threshold_fires() -> None:
+    assert predicted_topup_micros(_balance(14_990_000), 10_000_000) == 100_000_000
+
+
+def test_the_incident_case_is_seen_from_a_negative_balance() -> None:
+    """-$5 available, buy $25 against a $25 threshold: $20 after, so it fires.
+
+    Comparing the purchase against the threshold instead would call this
+    clear ($25 is not below $25) and say nothing, which is the bug.
+    """
+    assert predicted_topup_micros(_balance(-5_000_000), 25_000_000) == 100_000_000
+
+
+def test_the_charge_grows_to_clear_a_threshold_deeper_than_the_amount() -> None:
+    """max(amount, threshold - available): $200 threshold, $5 left, $50 amount."""
+    balance = _balance(-5_000_000, threshold_usd_micros=200_000_000,
+                       amount_usd_micros=50_000_000)
+    assert predicted_topup_micros(balance, 10_000_000) == 195_000_000
+
+
+def test_the_charge_is_capped_at_one_purchase_ceiling() -> None:
+    balance = _balance(-10_000_000_000, threshold_usd_micros=1_000_000_000,
+                       daily_cap_usd_micros=0)
+    assert predicted_topup_micros(balance, 0) == 5_000_000_000
+
+
+def test_the_charge_is_floored_to_whole_cents() -> None:
+    """A fraction of a cent could never settle, so the dispatcher floors it."""
+    balance = _balance(1_000, threshold_usd_micros=100_001_000,
+                       amount_usd_micros=10_000_000)
+    assert predicted_topup_micros(balance, 0) == 100_000_000
+
+
+def test_daily_cap_headroom_clamps_the_charge() -> None:
+    balance = _balance(0, daily_cap_usd_micros=120_000_000,
+                       charged_24h_usd_micros=60_000_000)
+    assert predicted_topup_micros(balance, 0) == 60_000_000
+
+
+def test_headroom_below_the_minimum_refill_charges_nothing() -> None:
+    balance = _balance(0, daily_cap_usd_micros=105_000_000,
+                       charged_24h_usd_micros=100_000_000)
+    assert predicted_topup_micros(balance, 0) == 0
+
+
+def test_an_exhausted_cap_charges_nothing() -> None:
+    balance = _balance(0, daily_cap_usd_micros=100_000_000,
+                       charged_24h_usd_micros=100_000_000)
+    assert predicted_topup_micros(balance, 0) == 0
+
+
+def test_no_threshold_means_no_prediction() -> None:
+    """An account the dispatcher has never given a rule to."""
+    assert predicted_topup_micros(_balance(0, threshold_usd_micros=0), 0) == 0

{fcloud_sdk-0.3.0 → fcloud_sdk-0.3.1}/tests/test_client_http_contract.py

@@ -31,6 +31,10 @@ class _Resp:
 class _RecordingTransport:
     def __init__(self) -> None:
         self.calls: list[tuple[str, str]] = []
+        # Bodies live alongside `calls` rather than inside it: the tuples
+        # below are asserted on by name in several tests, and widening them
+        # would churn every one.
+        self.bodies: list[tuple[str, dict]] = []
 
     def get(self, url, headers=None, timeout=None) -> _Resp:
         self.calls.append(("GET", url))
@@ -42,6 +46,10 @@ class _RecordingTransport:
 
     def post(self, url, json=None, headers=None, timeout=None) -> _Resp:
         self.calls.append(("POST", url))
+        self.bodies.append((url, json or {}))
+        if "/billing/checkout" in url:
+            return _Resp({"url": "https://checkout.stripe.com/c/pay/cs_1",
+                          "purchase_id": "pur_1"})
         return _Resp({})
 
     def delete(self, url, headers=None, timeout=None) -> _Resp:
@@ -87,3 +95,34 @@ def test_server_state_reads_issue_http(call, want_method, want_url):
     assert not client._direct.method_calls, (  # noqa: SLF001
         f"bridge consulted for server state: {client._direct.method_calls}"
     )
+
+
+def _checkout_body(transport: _RecordingTransport) -> dict:
+    return [b for u, b in transport.bodies if "/billing/checkout" in u][0]
+
+
+def test_checkout_omits_the_return_urls_rather_than_sending_them_empty():
+    """The dispatcher reads an absent URL as "caller named none".
+
+    An empty string is not the same thing — validateReturnURL rejects it
+    outright — so the keys have to be missing from the body, which only a
+    transport-level assertion can see.
+    """
+    client, transport = _real_client()
+    client.start_credit_checkout(amount_usd_micros=25_000_000)
+    body = _checkout_body(transport)
+    assert "success_url" not in body
+    assert "cancel_url" not in body
+    assert body["amount_usd_micros"] == 25_000_000
+
+
+def test_checkout_sends_the_return_urls_when_it_has_them():
+    client, transport = _real_client()
+    client.start_credit_checkout(
+        amount_usd_micros=25_000_000,
+        success_url="https://dash.example/dashboard?purchase=ok",
+        cancel_url="https://dash.example/dashboard?purchase=cancelled",
+    )
+    body = _checkout_body(transport)
+    assert body["success_url"] == "https://dash.example/dashboard?purchase=ok"
+    assert body["cancel_url"] == "https://dash.example/dashboard?purchase=cancelled"