commoncompute 0.3.1__tar.gz → 0.4.0__tar.gz

{commoncompute-0.3.1 → commoncompute-0.4.0}/.gitignore

@@ -37,3 +37,6 @@ apps/web/.playwright/
 # Local scratch — never tracked (internal notes, draft reviews)
 tmp/
 .venv
+
+# Device reliability reset snapshots (rollback data, never tracked)
+scripts/.reliability-snapshots/

{commoncompute-0.3.1 → commoncompute-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commoncompute
-Version: 0.3.1
+Version: 0.4.0
 Summary: Official Python SDK for Common Compute — the batch AI bill you shouldn't be paying.
 Project-URL: Homepage, https://commoncompute.ai
 Project-URL: Documentation, https://commoncompute.ai/docs

{commoncompute-0.3.1 → commoncompute-0.4.0}/commoncompute/__init__.py

@@ -30,7 +30,7 @@ in the catalog — the API declines them with `workload_not_available`
 # `commoncompute.__version__` at import time for the User-Agent header,
 # and the previous ordering (`__version__` defined at the bottom) made
 # every clean install of the SDK fail with a circular ImportError.
-__version__ = "0.3.1"
+__version__ = "0.4.0"
 
 from .client import Client, AsyncClient
 from .errors import (
@@ -51,6 +51,7 @@ from .errors import (
 )
 from .models import Job, Quote, Receipt, TaskResult, AccountTier, SpendSummary
 from .connect import connect, login
+from .billing import add_card
 from . import aws_batch  # noqa: E402  (intentional re-export)
 
 __all__ = [
@@ -58,6 +59,7 @@ __all__ = [
     "AsyncClient",
     "connect",
     "login",
+    "add_card",
     "CommonComputeError",
     "AuthenticationError",
     "PermissionDeniedError",

{commoncompute-0.3.1 → commoncompute-0.4.0}/commoncompute/_async_client.py

@@ -297,6 +297,21 @@ class _BillingAsync:
     async def balance(self) -> dict[str, Any]:
         return await self._t.request("GET", "/v1/billing/balance")
 
+    async def credits(self) -> dict[str, Any]:
+        """Prepaid credit balance, held amounts, and auto-reload settings —
+        ``GET /v1/billing/credits``. Mirrors ``Client.billing.credits()``."""
+        return await self._t.request("GET", "/v1/billing/credits")
+
+    async def buy_credits(self, *, amount_cents: int, idempotency_key: str | None = None) -> dict[str, Any]:
+        """Charge the saved card for credits. Mirrors ``Client.billing.buy_credits()``
+        — needs an API key carrying the ``billing`` scope."""
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return await self._t.request(
+            "POST", "/v1/billing/credits",
+            json_body={"amount_cents": amount_cents},
+            headers=headers,
+        )
+
     async def history(self, *, limit: int = 50) -> list[dict[str, Any]]:
         return (await self._t.request("GET", "/v1/billing/history", params={"limit": limit})).get("entries", [])
 

commoncompute-0.4.0/commoncompute/billing.py

@@ -0,0 +1,124 @@
+"""Attach a payment card from a script or notebook.
+
+``commoncompute.add_card()`` opens the dashboard billing page, waits for the
+card to actually land server-side, and returns the resulting payment-method
+summary::
+
+    import commoncompute as cc
+    cc.connect()      # one-time: get a key
+    cc.add_card()     # one-time: attach a card
+    cc.Client().submit(...)
+
+WHY THE BROWSER. The card number has to reach Stripe directly. Accepting it
+here would put the number in this process's memory, its traceback frames, and
+whatever notebook checkpoint happens to capture the cell — and would drag the
+user's machine into PCI scope for no benefit at all. So this function never
+sees a card; it opens the page where Stripe's own iframe collects one.
+
+WHY IT POLLS. The card is saved by the ``setup_intent.succeeded`` webhook, not
+by the browser form submitting. Returning as soon as the browser opens would
+report success for a card that may never arrive. Polling the read-only summary
+means a returned value is the server agreeing the card exists.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import webbrowser
+from typing import Any, Callable, Optional
+
+from .errors import CommonComputeError
+
+DEFAULT_BASE_URL = "https://api.commoncompute.ai"
+POLL_INTERVAL_S = 3.0
+
+
+def dashboard_url_for(api_base: str, path: str = "/app/billing") -> str:
+    """Map an API base URL to the matching dashboard URL.
+
+    `api.` is stripped because that is the only difference between the two
+    hostnames in every environment we run, so a staging key opens the staging
+    dashboard rather than production's. CC_DASHBOARD_URL overrides outright,
+    for local dev where the two aren't related by prefix at all.
+    """
+    override = os.environ.get("CC_DASHBOARD_URL")
+    if override:
+        return f"{override.rstrip('/')}{path}"
+    return f"{api_base.rstrip('/').replace('://api.', '://', 1)}{path}"
+
+
+def add_card(
+    *,
+    client: Any = None,
+    open_browser: bool = True,
+    timeout: float = 600.0,
+    quiet: bool = False,
+    _sleep: Callable[[float], None] = time.sleep,
+) -> dict[str, Any]:
+    """Attach a payment card to the account this machine is logged in as.
+
+    Opens the browser to the dashboard billing page (or prints the URL when
+    ``open_browser=False``), then blocks until the saved card appears.
+
+    Returns the payment-method summary — ``{"has_card": True, "brand": ...,
+    "last4": ...}``. Returns immediately if a card is already on file, or if
+    the account is billing-exempt and doesn't need one.
+
+    Raises :class:`CommonComputeError` if no card appears before ``timeout``.
+    """
+    from .client import Client  # local import: avoids a cycle at module load
+
+    c = client or Client()
+
+    def say(msg: str) -> None:
+        if not quiet:
+            print(msg)
+
+    summary = c.billing.balance()
+    if summary.get("has_card"):
+        say(f"Card already on file — {describe_card(summary)}")
+        return summary
+    if summary.get("billing_exempt"):
+        say("This account is billing-exempt — no card needed.")
+        return summary
+
+    url = dashboard_url_for(c._transport._base_url)
+    say("Add your card in the browser — it goes straight to Stripe, not through this process.")
+    say(f"  Open: {url}")
+    if open_browser:
+        try:
+            webbrowser.open(url)
+        except Exception:
+            pass  # headless; the printed URL is the fallback
+
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        _sleep(POLL_INTERVAL_S)
+        try:
+            summary = c.billing.balance()
+        except Exception:
+            continue  # transient — the user is mid-flow; keep waiting
+        if summary.get("has_card"):
+            say(f"✓ Card saved — {describe_card(summary)}")
+            return summary
+
+    raise CommonComputeError(
+        f"No card appeared within {timeout:.0f}s. If you did add one, it may still be "
+        "processing — check client.billing.balance()."
+    )
+
+
+def describe_card(summary: dict[str, Any]) -> str:
+    """Human label for a payment-method summary.
+
+    Distinguishes "no card" from "card whose details Stripe couldn't be asked
+    for" — the API degrades to has_card without brand/last4 when Stripe is
+    unreachable, and calling that "none" would contradict the submit gate.
+    """
+    if summary.get("last4"):
+        brand = (summary.get("brand") or "card").capitalize()
+        return f"{brand} ••••{summary['last4']}"
+    if summary.get("has_card"):
+        return "on file (details unavailable)"
+    return "none"

{commoncompute-0.3.1 → commoncompute-0.4.0}/commoncompute/cli.py

@@ -56,10 +56,14 @@ jobs_app = typer.Typer(no_args_is_help=True, help="Inspect and submit jobs.")
 keys_app = typer.Typer(no_args_is_help=True, help="Manage API keys.")
 receipts_app = typer.Typer(no_args_is_help=True, help="List, get, and export job receipts.")
 config_app = typer.Typer(no_args_is_help=True, help="Local CLI/SDK configuration (base_url, org, credentials).")
+billing_app = typer.Typer(no_args_is_help=True, help="Payment method and credit balance.")
+credits_app = typer.Typer(no_args_is_help=True, help="Buy and inspect prepaid credits.")
 app.add_typer(jobs_app, name="jobs")
 app.add_typer(keys_app, name="keys")
 app.add_typer(receipts_app, name="receipts")
 app.add_typer(config_app, name="config")
+app.add_typer(billing_app, name="billing")
+app.add_typer(credits_app, name="credits")
 
 console = Console()
 err_console = Console(stderr=True, style="red")
@@ -112,6 +116,39 @@ def _fmt_usd(cents: int) -> str:
     return f"${cents / 100:,.2f}"
 
 
+def _stdin_is_tty() -> bool:
+    """Is there a human who can answer a prompt?
+
+    Its own function so a test can drive both branches — CliRunner replaces
+    sys.stdin, so patching sys.stdin.isatty directly doesn't reach the code
+    under test, and the untested branch here is the one that charges a card.
+    """
+    try:
+        return sys.stdin.isatty()
+    except Exception:
+        return False  # detached stdin — treat as non-interactive
+
+
+def _dashboard_url(client: Client, path: str) -> str:
+    """Map the API base URL to the matching dashboard URL.
+
+    The card itself is entered in a browser, never here — Stripe must receive
+    the number directly, and routing it through this process would drag the
+    user's machine into PCI scope for no benefit. So the CLI's job is to open
+    the right page and then watch for the result.
+
+    Derived from the transport's base_url rather than hardcoded so `config set
+    base_url` and CC_BASE_URL keep pointing at the matching dashboard: staging
+    API → staging dashboard. `api.` is stripped because that is the only
+    difference between the two hostnames in every environment we run.
+    """
+    override = os.environ.get("CC_DASHBOARD_URL")
+    base = (override or client._transport._base_url).rstrip("/")
+    if not override:
+        base = base.replace("://api.", "://", 1)
+    return f"{base}{path}"
+
+
 def _print_err(e: Exception) -> None:
     err_console.print(f"[bold red]Error:[/bold red] {e}")
 
@@ -267,6 +304,174 @@ def balance(as_json: bool = typer.Option(False, "--json", help="Raw JSON output.
     console.print(table)
 
 
+# ─── billing ────────────────────────────────────────────────────────────
+#
+# The card number never passes through this process. `billing add-card` opens
+# the dashboard, where Stripe's own iframe collects it, and then polls a
+# read-only endpoint until the saved card shows up. That split is why these
+# commands need no new API surface and no new permission: GET
+# /v1/billing/balance and /v1/billing/credits already accept an API key
+# (`requireAuth`), while everything that *mutates* billing stays JWT-only and
+# happens in the browser session.
+
+@billing_app.command("status")
+def billing_status(as_json: bool = typer.Option(False, "--json", help="Raw JSON output.")) -> None:
+    """Show the saved card and credit balance."""
+    c = _client()
+    try:
+        card = c.balance()
+        credits = c.billing.credits()
+    except Exception as e:
+        _print_err(e); raise typer.Exit(1)
+    if _emit({**credits, "payment_method": card}, as_json):
+        return
+
+    table = Table(show_header=False, box=None)
+    table.add_row("Payment method", _describe_card(card))
+    table.add_row("Credits", _fmt_usd(credits.get("balance_cents", 0)))
+    held = credits.get("held_cents")
+    if held:
+        table.add_row("Held for running jobs", _fmt_usd(held))
+    if credits.get("auto_reload_enabled"):
+        table.add_row("Auto-reload", f"on — {_fmt_usd(credits.get('auto_reload_amount_cents', 0))}")
+    console.print(table)
+
+    if card.get("billing_exempt"):
+        console.print("\n[dim]This account is billing-exempt — jobs run without a card.[/dim]")
+    elif not card.get("has_card"):
+        console.print("\nNo card yet. Run [bold]commoncompute billing add-card[/bold].")
+
+
+def _describe_card(card: dict) -> str:
+    if card.get("last4"):
+        brand = (card.get("brand") or "card").capitalize()
+        return f"{brand} ••••{card['last4']}"
+    if card.get("has_card"):
+        # Stripe was unreachable when the summary was built; the submit gate
+        # still works, so report the card rather than implying there isn't one.
+        return "on file (details unavailable)"
+    return "none"
+
+
+@billing_app.command("add-card")
+def billing_add_card(
+    no_browser: bool = typer.Option(False, "--no-browser", help="Print the URL instead of opening it."),
+    timeout: float = typer.Option(600.0, "--timeout", help="Seconds to wait for the card to appear."),
+) -> None:
+    """Add a payment card (opens the browser; the card is entered on Stripe's form)."""
+    c = _client()
+    try:
+        card = c.balance()
+    except Exception as e:
+        _print_err(e); raise typer.Exit(1)
+
+    if card.get("has_card"):
+        console.print(f"[green]✓[/green] Card already on file — {_describe_card(card)}")
+        console.print("[dim]Replace it from the dashboard billing page.[/dim]")
+        return
+    if card.get("billing_exempt"):
+        console.print("This account is billing-exempt — no card needed to submit jobs.")
+        return
+
+    url = _dashboard_url(c, "/app/billing")
+    console.print("Add your card in the browser — it goes straight to Stripe, not through this CLI.")
+    console.print(f"  Open: [bold]{url}[/bold]\n")
+    if not no_browser:
+        try:
+            webbrowser.open(url)
+        except Exception:
+            pass  # headless box; the printed URL is the fallback
+
+    # Poll the read-only summary. The webhook (setup_intent.succeeded) is what
+    # actually saves the card, so success here means the card really landed
+    # server-side — not merely that the browser form looked happy.
+    deadline = time.time() + timeout
+    try:
+        with console.status("Waiting for the card…"):
+            while time.time() < deadline:
+                time.sleep(3)
+                try:
+                    card = c.balance()
+                except Exception:
+                    continue  # transient; keep waiting until the deadline
+                if card.get("has_card"):
+                    console.print(f"[green]✓[/green] Card saved — {_describe_card(card)}")
+                    console.print("Next: [bold]commoncompute billing status[/bold]")
+                    return
+    except KeyboardInterrupt:
+        console.print("\nStopped waiting. The card is saved if you finished in the browser;")
+        console.print("check with [bold]commoncompute billing status[/bold].")
+        raise typer.Exit(1)
+
+    err_console.print(
+        f"Timed out after {timeout:.0f}s without seeing a card.\n"
+        "If you did add one, check `commoncompute billing status` — the webhook may still be in flight."
+    )
+    raise typer.Exit(1)
+
+
+@credits_app.command("buy")
+def credits_buy(
+    amount: float = typer.Argument(..., help="Dollars of credit to buy, e.g. 20."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+    as_json: bool = typer.Option(False, "--json", help="Raw JSON output."),
+) -> None:
+    """Charge your saved card for credits.
+
+    Needs a key with the `billing` scope — tick "Also let it buy credits" when
+    you run `commoncompute login`. Without it you'll get a clear 403.
+    """
+    c = _client()
+    amount_cents = int(round(amount * 100))
+
+    # Confirm before charging. This is the one CLI command that moves money, so
+    # a mistyped argument is a real charge rather than a failed request.
+    #
+    # When there's no tty we REFUSE rather than assuming consent. Skipping the
+    # prompt because nobody can answer it turns "couldn't ask" into "went
+    # ahead" — a cron job or a stray script would charge the card silently. A
+    # caller that means it passes --yes.
+    if not yes:
+        if _stdin_is_tty():
+            typer.confirm(f"Charge your saved card {_fmt_usd(amount_cents)}?", abort=True)
+        else:
+            err_console.print(
+                f"Refusing to charge {_fmt_usd(amount_cents)} without confirmation.\n"
+                "This isn't an interactive shell, so there's nobody to ask — "
+                "pass [bold]--yes[/bold] if you meant it."
+            )
+            raise typer.Exit(2)
+
+    try:
+        res = c.billing.buy_credits(amount_cents=amount_cents)
+    except Exception as e:
+        _print_err(e)
+        # The API distinguishes these; each needs a different action from the
+        # user, so don't flatten them into "purchase failed".
+        text = str(e)
+        if "insufficient_scope" in text or "billing\" scope" in text:
+            err_console.print(
+                "\nThis key can't buy credits. Re-run [bold]commoncompute login[/bold] and tick\n"
+                '"Also let it buy credits" on the approval page, or buy from the dashboard.'
+            )
+        elif "no_payment_method" in text:
+            err_console.print("\nNo card on file. Run [bold]commoncompute billing add-card[/bold] first.")
+        raise typer.Exit(1)
+
+    if _emit(res, as_json):
+        return
+    console.print(
+        f"[green]✓[/green] Added {_fmt_usd(res.get('purchased_cents', amount_cents))} — "
+        f"balance {_fmt_usd(res.get('available_cents', 0))}"
+    )
+
+
+@credits_app.command("status")
+def credits_status(as_json: bool = typer.Option(False, "--json", help="Raw JSON output.")) -> None:
+    """Show the credit balance (alias of `billing status`)."""
+    billing_status(as_json=as_json)
+
+
 @app.command()
 def usage(
     start: Optional[str] = typer.Option(None, "--start", help="Window start, YYYY-MM-DD (default: 30 days ago)."),

{commoncompute-0.3.1 → commoncompute-0.4.0}/commoncompute/client.py

@@ -298,6 +298,32 @@ class _BillingSync:
     def balance(self) -> dict[str, Any]:
         return self._t.request("GET", "/v1/billing/balance")
 
+    def credits(self) -> dict[str, Any]:
+        """Prepaid credit balance, what's held against in-flight jobs, and
+        auto-reload settings — ``GET /v1/billing/credits``.
+
+        Read-only, so an API key is enough. Buying credits is a separate,
+        JWT-only operation done from the dashboard.
+        """
+        return self._t.request("GET", "/v1/billing/credits")
+
+    def buy_credits(self, *, amount_cents: int, idempotency_key: str | None = None) -> dict[str, Any]:
+        """Charge the saved card for credits — ``POST /v1/billing/credits``.
+
+        Needs an API key carrying the ``billing`` scope, which is granted only
+        by ticking "Also let it buy credits" during ``commoncompute login``.
+        A stock key raises with ``insufficient_scope``.
+
+        Pass ``idempotency_key`` to make a retry safe: the same key never
+        charges twice.
+        """
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._t.request(
+            "POST", "/v1/billing/credits",
+            json_body={"amount_cents": amount_cents},
+            headers=headers,
+        )
+
     def history(self, *, limit: int = 50) -> list[dict[str, Any]]:
         return self._t.request("GET", "/v1/billing/history", params={"limit": limit}).get("entries", [])