copilot-spend 0.1.0__py3-none-any.whl

copilot_spend/__init__.py

@@ -0,0 +1 @@
+"""copilot-spend: a one-shot CLI for current-period GitHub Copilot spend."""

copilot_spend/__main__.py

@@ -0,0 +1,4 @@
+from copilot_spend.cli import _entrypoint
+
+if __name__ == "__main__":
+    _entrypoint()

copilot_spend/api.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import json
+import socket
+import ssl
+import urllib.error
+import urllib.request
+from importlib.metadata import PackageNotFoundError, version
+
+from copilot_spend.auth import Auth
+from copilot_spend.paths import scrub
+from copilot_spend.quota import NoSubscriptionError
+
+
+class APIError(Exception):
+    pass
+
+
+def _package_version() -> str:
+    try:
+        return version("copilot-spend")
+    except PackageNotFoundError:
+        return "dev"
+
+
+def _build_url(host: str) -> str:
+    if host == "github.com":
+        return "https://api.github.com/copilot_internal/user"
+    return f"https://{host}/api/v3/copilot_internal/user"
+
+
+def _body_excerpt(raw: bytes, limit: int = 500) -> str:
+    try:
+        text = raw.decode("utf-8", errors="replace")
+    except Exception:
+        text = "<unreadable response body>"
+    text = text.strip()
+    if len(text) > limit:
+        text = text[:limit] + "…"
+    return text
+
+
+def _reauth_message(source: str) -> str:
+    if source == "native":
+        return (
+            "Token rejected by GitHub Copilot. "
+            "Run `copilot-spend login` to re-authenticate."
+        )
+    return (
+        "Token rejected by GitHub Copilot — opencode token may be expired. "
+        "Run `opencode login` to refresh."
+    )
+
+
+def fetch_quota(auth: Auth, *, timeout: float = 10.0) -> dict:
+    # `/copilot_internal/user` accepts the OAuth/GitHub-App user token
+    # directly as Bearer for both `ghu_` (native) and `gho_` (opencode).
+    # No session-token exchange — that token (`/copilot_internal/v2/token`)
+    # is for the Copilot Chat proxy at api.githubcopilot.com, not this endpoint.
+    url = _build_url(auth.host)
+    request = urllib.request.Request(
+        url,
+        headers={
+            "Authorization": f"Bearer {auth.token}",
+            "User-Agent": f"copilot-spend/{_package_version()}",
+            "Accept": "application/json",
+        },
+        method="GET",
+    )
+
+    context = ssl.create_default_context()
+
+    try:
+        with urllib.request.urlopen(request, timeout=timeout, context=context) as response:
+            raw = response.read()
+    except urllib.error.HTTPError as exc:
+        status = exc.code
+        if status in (401, 403):
+            raise APIError(_reauth_message(auth.source)) from None
+        if status == 404:
+            raise NoSubscriptionError(
+                "No Copilot quota on this account."
+            ) from None
+        try:
+            body = scrub(_body_excerpt(exc.read()), auth.token)
+        except Exception:
+            body = "<no response body>"
+        if 500 <= status < 600:
+            raise APIError(
+                f"GitHub Copilot API returned {status} at {url} — try again shortly."
+            ) from None
+        raise APIError(
+            f"GitHub Copilot API returned {status} at {url}: {body}"
+        ) from None
+    except TimeoutError:
+        raise APIError(
+            f"Request to {auth.host} timed out after {timeout}s."
+        ) from None
+    except socket.timeout:
+        raise APIError(
+            f"Request to {auth.host} timed out after {timeout}s."
+        ) from None
+    except urllib.error.URLError as exc:
+        underlying = getattr(exc, "reason", exc)
+        raise APIError(
+            f"Could not reach {auth.host}: {underlying}"
+        ) from None
+
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise APIError(
+            f"GitHub Copilot API at {url} returned a non-JSON response: {exc}"
+        ) from None

copilot_spend/auth.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import ipaddress
+import json
+import os
+import re
+import stat
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+AUTH_PATH = Path.home() / ".local/share/opencode/auth.json"
+
+# RFC 1123 hostname: dot-separated labels, each 1-63 chars of [A-Za-z0-9-],
+# not starting or ending with a hyphen. Total length ≤ 253.
+_HOSTNAME_LABEL = r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?"
+_HOSTNAME_RE = re.compile(rf"^{_HOSTNAME_LABEL}(?:\.{_HOSTNAME_LABEL})*$")
+
+
+class AuthError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class Auth:
+    token: str
+    host: str
+    source: Literal["native", "opencode"] = "opencode"
+
+    def __repr__(self) -> str:
+        return f"Auth(token=<redacted>, host={self.host!r}, source={self.source!r})"
+
+
+def _is_private_ip_literal(host: str) -> bool:
+    try:
+        addr = ipaddress.ip_address(host)
+    except ValueError:
+        return False
+    return (
+        addr.is_private
+        or addr.is_loopback
+        or addr.is_link_local
+        or addr.is_reserved
+        or addr.is_multicast
+        or addr.is_unspecified
+    )
+
+
+def is_valid_host(host: str) -> bool:
+    if not host or len(host) > 253:
+        return False
+    if _is_private_ip_literal(host):
+        return False
+    return bool(_HOSTNAME_RE.match(host))
+
+
+def normalize_host(raw: str) -> str:
+    host = raw.strip()
+    for prefix in ("https://", "http://"):
+        if host.startswith(prefix):
+            host = host[len(prefix):]
+            break
+    return host.rstrip("/").strip()
+
+
+# Backwards-compat aliases retained for module-internal use.
+_is_valid_host = is_valid_host
+_normalize_host = normalize_host
+
+
+def _warn_if_permissive(path: Path) -> None:
+    if os.name != "posix":
+        return
+    try:
+        mode = path.stat().st_mode
+    except OSError:
+        return
+    permissive_bits = mode & (stat.S_IRWXG | stat.S_IRWXO)
+    if permissive_bits:
+        owner_octal = stat.S_IMODE(mode)
+        print(
+            f"warning: {path} permissions are {oct(owner_octal)} — "
+            "the file holds a long-lived Copilot token; consider `chmod 600`.",
+            file=sys.stderr,
+        )
+
+
+def _read_opencode(path: Path) -> Auth | None:
+    if not path.exists():
+        return None
+
+    _warn_if_permissive(path)
+
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise AuthError(f"opencode auth file is malformed JSON at {path}: {exc.msg}") from None
+
+    if not isinstance(data, dict):
+        raise AuthError(f"opencode auth file at {path} is not a JSON object.")
+
+    entry = data.get("github-copilot") or {}
+    if not isinstance(entry, dict):
+        raise AuthError(
+            f"opencode auth file at {path} has a malformed github-copilot entry."
+        )
+
+    token = entry.get("access")
+    if not token or not isinstance(token, str):
+        raise AuthError(
+            f"No GitHub Copilot token in {path}. Run `opencode login` first."
+        )
+
+    enterprise_raw = entry.get("enterpriseUrl")
+    if enterprise_raw is None:
+        enterprise_raw = ""
+    if not isinstance(enterprise_raw, str):
+        raise AuthError(
+            f"opencode auth file at {path} has a non-string enterpriseUrl field."
+        )
+
+    enterprise = normalize_host(enterprise_raw)
+    if not enterprise:
+        host = "github.com"
+    else:
+        if not is_valid_host(enterprise):
+            raise AuthError(
+                f"enterpriseUrl in {path} is not a valid hostname: {enterprise_raw!r}. "
+                "Expected a bare hostname like `ghe.example.com`."
+            )
+        host = enterprise
+
+    return Auth(token=token, host=host, source="opencode")
+
+
+def _read_native(path: Path) -> Auth | None:
+    if not path.exists():
+        return None
+
+    _warn_if_permissive(path)
+
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise AuthError(
+            f"copilot-spend auth file is malformed JSON at {path}: {exc.msg}. "
+            "Run `copilot-spend login` to recreate it."
+        ) from None
+
+    if not isinstance(data, dict):
+        raise AuthError(f"copilot-spend auth file at {path} is not a JSON object.")
+
+    entry = data.get("github-copilot") or {}
+    if not isinstance(entry, dict):
+        raise AuthError(
+            f"copilot-spend auth file at {path} has a malformed github-copilot entry."
+        )
+
+    token = entry.get("token")
+    if not token or not isinstance(token, str):
+        raise AuthError(
+            f"No GitHub Copilot token in {path}. Run `copilot-spend login`."
+        )
+
+    host_raw = entry.get("host", "")
+    if not isinstance(host_raw, str):
+        raise AuthError(
+            f"copilot-spend auth file at {path} has a non-string host field."
+        )
+
+    host = normalize_host(host_raw) or "github.com"
+    if host != "github.com" and not is_valid_host(host):
+        raise AuthError(
+            f"host in {path} is not a valid hostname: {host_raw!r}."
+        )
+
+    return Auth(token=token, host=host, source="native")
+
+
+def resolve_auth(
+    *,
+    native_path: Path | None = None,
+    opencode_path: Path = AUTH_PATH,
+) -> Auth:
+    if native_path is None:
+        # Defer the import to call time so test monkeypatching of
+        # COPILOT_SPEND_CONFIG_DIR is honored.
+        from . import paths as _paths
+        native_path = _paths.auth_path()
+
+    native = _read_native(native_path)
+    if native is not None:
+        return native
+
+    opencode = _read_opencode(opencode_path)
+    if opencode is not None:
+        return opencode
+
+    raise AuthError(
+        "No credentials found. Run `copilot-spend login` to authenticate, "
+        "or install opencode and run `opencode login`."
+    )

copilot_spend/cli.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime, timezone
+from importlib.metadata import PackageNotFoundError, version
+
+from copilot_spend.api import APIError, fetch_quota
+from copilot_spend.auth import AuthError, resolve_auth
+from copilot_spend.output import render
+from copilot_spend.paths import scrub
+from copilot_spend.quota import NoSubscriptionError, parse_quota
+
+
+def _package_version() -> str:
+    try:
+        return version("copilot-spend")
+    except PackageNotFoundError:
+        return "dev"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="copilot-spend",
+        description="Print your current-period GitHub Copilot spend and reset date.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"copilot-spend {_package_version()}",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+    subparsers.add_parser(
+        "login",
+        help="Authenticate via GitHub OAuth device flow (github.com or GHE).",
+    )
+    subparsers.add_parser(
+        "logout",
+        help="Remove copilot-spend's stored credentials.",
+    )
+    return parser
+
+
+def _run_show_quota() -> int:
+    auth = None
+    try:
+        auth = resolve_auth()
+    except AuthError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+    try:
+        payload = fetch_quota(auth)
+    except NoSubscriptionError as exc:
+        print(f"no Copilot quota on this account: {exc}", file=sys.stderr)
+        return 4
+    except APIError as exc:
+        print(scrub(str(exc), auth.token if auth else None), file=sys.stderr)
+        return 3
+
+    try:
+        spend = parse_quota(payload)
+    except NoSubscriptionError as exc:
+        print(f"no Copilot quota on this account: {exc}", file=sys.stderr)
+        return 4
+
+    try:
+        print(render(spend, now=datetime.now(timezone.utc)))
+    except Exception as exc:
+        print(
+            scrub(f"unexpected error rendering output: {exc}", auth.token if auth else None),
+            file=sys.stderr,
+        )
+        return 1
+
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "login":
+        from copilot_spend.login import run_login
+        return run_login()
+    if args.command == "logout":
+        from copilot_spend.login import run_logout
+        return run_logout()
+
+    return _run_show_quota()
+
+
+def _entrypoint() -> None:
+    try:
+        sys.exit(main())
+    except SystemExit:
+        raise
+    except Exception as exc:
+        print(f"unexpected error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    _entrypoint()

copilot_spend/login.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+import json
+import socket
+import ssl
+import sys
+import time
+import urllib.error
+import urllib.request
+
+from . import api, paths
+from .auth import Auth, AuthError, is_valid_host, normalize_host
+from .quota import NoSubscriptionError
+
+CLIENT_ID = "Iv1.b507a08c87ecfe98"
+OAUTH_SCOPE = "read:user"
+POLL_MAX_WAIT_S = 900
+
+
+def _device_url(host: str) -> str:
+    if host == "github.com":
+        return "https://github.com/login/device/code"
+    return f"https://{host}/login/device/code"
+
+
+def _access_token_url(host: str) -> str:
+    if host == "github.com":
+        return "https://github.com/login/oauth/access_token"
+    return f"https://{host}/login/oauth/access_token"
+
+
+def _post_json(url: str, body: dict, *, timeout: float = 10.0) -> dict:
+    request = urllib.request.Request(
+        url,
+        data=json.dumps(body).encode("utf-8"),
+        headers={
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+    context = ssl.create_default_context()
+    with urllib.request.urlopen(request, timeout=timeout, context=context) as response:
+        raw = response.read()
+    return json.loads(raw.decode("utf-8"))
+
+
+def _prompt_host(stdin=None, stderr=None) -> str:
+    stdin = stdin or sys.stdin
+    stderr = stderr or sys.stderr
+    print("Where do you authenticate?", file=stderr)
+    print("  1) github.com", file=stderr)
+    print("  2) GitHub Enterprise", file=stderr)
+    print("Choose 1 or 2 [1]: ", end="", file=stderr, flush=True)
+    choice = stdin.readline().strip() or "1"
+
+    if choice == "1":
+        return "github.com"
+    if choice != "2":
+        raise AuthError(f"Unrecognized choice: {choice!r}. Expected 1 or 2.")
+
+    print("GHE host (e.g. ghe.example.com): ", end="", file=stderr, flush=True)
+    raw = stdin.readline().strip()
+    host = normalize_host(raw)
+    if not is_valid_host(host):
+        raise AuthError(
+            f"Not a valid hostname: {raw!r}. Expected a bare hostname like `ghe.example.com`."
+        )
+    return host
+
+
+def _request_device_code(host: str) -> dict:
+    url = _device_url(host)
+    try:
+        payload = _post_json(url, {"client_id": CLIENT_ID, "scope": OAUTH_SCOPE})
+    except urllib.error.HTTPError as exc:
+        raise AuthError(
+            f"GitHub returned {exc.code} from {url}. Check the host and try again."
+        ) from None
+    except (TimeoutError, socket.timeout):
+        raise AuthError(f"Timed out reaching {host} for device-code request.") from None
+    except urllib.error.URLError as exc:
+        underlying = getattr(exc, "reason", exc)
+        raise AuthError(f"Could not reach '{host}': {underlying}.") from None
+
+    if not isinstance(payload, dict):
+        raise AuthError(f"Unexpected response from {url}: not a JSON object.")
+    error = payload.get("error")
+    if error:
+        description = payload.get("error_description", error)
+        raise AuthError(
+            f"GitHub rejected the device-code request ({error}): {description}."
+        )
+
+    required = ("device_code", "user_code", "verification_uri", "interval")
+    if not all(payload.get(k) for k in required):
+        raise AuthError(
+            f"Device-code response from {url} is missing required fields."
+        )
+    return payload
+
+
+def _poll_for_token(
+    host: str,
+    device_code: str,
+    interval: int,
+    *,
+    now=time.monotonic,
+    sleep=time.sleep,
+    max_wait: int = POLL_MAX_WAIT_S,
+) -> str:
+    url = _access_token_url(host)
+    body = {
+        "client_id": CLIENT_ID,
+        "device_code": device_code,
+        "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+    }
+    started = now()
+    current_interval = max(int(interval), 1)
+
+    while True:
+        if now() - started > max_wait:
+            raise AuthError("Login timed out. Run `copilot-spend login` again.")
+
+        sleep(current_interval)
+
+        try:
+            payload = _post_json(url, body)
+        except urllib.error.HTTPError as exc:
+            raise AuthError(
+                f"GitHub returned {exc.code} during token polling. Run `copilot-spend login` again."
+            ) from None
+        except (TimeoutError, socket.timeout):
+            # Transient — keep polling within the time budget.
+            continue
+        except urllib.error.URLError as exc:
+            underlying = getattr(exc, "reason", exc)
+            raise AuthError(f"Could not reach '{host}': {underlying}.") from None
+
+        if not isinstance(payload, dict):
+            raise AuthError("Unexpected non-object response from token endpoint.")
+
+        token = payload.get("access_token")
+        if token:
+            if not isinstance(token, str):
+                raise AuthError("GitHub returned a non-string access_token.")
+            return token
+
+        err = payload.get("error")
+        if err == "authorization_pending":
+            continue
+        if err == "slow_down":
+            current_interval += 5
+            continue
+        if err == "expired_token":
+            raise AuthError("Login timed out. Run `copilot-spend login` again.")
+        if err == "access_denied":
+            raise AuthError("Authorization denied. Run `copilot-spend login` again to retry.")
+        if err == "unauthorized_client":
+            raise AuthError(
+                "GitHub rejected the OAuth app (unauthorized_client). "
+                "The bundled CLIENT_ID may not be allowed on this host. "
+                "See README 'Switch to your own GitHub App'."
+            )
+        if err:
+            description = payload.get("error_description", err)
+            raise AuthError(f"GitHub returned an error during polling ({err}): {description}.")
+
+        raise AuthError("Token response missing both access_token and error.")
+
+
+def run_login(
+    *,
+    stdin=None,
+    stdout=None,
+    stderr=None,
+    sleep=time.sleep,
+    now=time.monotonic,
+) -> int:
+    stdin = stdin or sys.stdin
+    stdout = stdout or sys.stdout
+    stderr = stderr or sys.stderr
+    try:
+        host = _prompt_host(stdin=stdin, stderr=stderr)
+        device = _request_device_code(host)
+    except AuthError as exc:
+        print(f"error: {exc}", file=stderr)
+        return 2
+
+    print(
+        f"Visit {device['verification_uri']} and enter the code: {device['user_code']}",
+        file=stdout,
+    )
+    print("Waiting for authorization...", file=stderr)
+
+    try:
+        token = _poll_for_token(
+            host,
+            device["device_code"],
+            int(device.get("interval", 5)),
+            now=now,
+            sleep=sleep,
+        )
+    except KeyboardInterrupt:
+        print("Login cancelled.", file=stderr)
+        return 2
+    except AuthError as exc:
+        print(f"error: {exc}", file=stderr)
+        return 2
+
+    if not token.startswith("ghu_"):
+        print(
+            "error: GitHub returned a non-GitHub-App token (expected `ghu_…` prefix). "
+            "The bundled CLIENT_ID is misconfigured — see README 'Switch to your own GitHub App'.",
+            file=stderr,
+        )
+        return 2
+
+    auth = Auth(token=token, host=host, source="native")
+
+    try:
+        api.fetch_quota(auth)
+    except NoSubscriptionError:
+        print(
+            "error: post-login verification failed: this account has no Copilot quota.",
+            file=stderr,
+        )
+        return 2
+    except api.APIError as exc:
+        scrubbed = paths.scrub(str(exc), token)
+        print(f"error: post-login verification failed: {scrubbed}", file=stderr)
+        return 2
+
+    target = paths.auth_path()
+    if target.exists():
+        print(
+            "Re-authenticating — previous credentials will be replaced.",
+            file=stderr,
+        )
+
+    try:
+        paths.write_secret_file(
+            target,
+            {"github-copilot": {"token": token, "host": host}},
+        )
+    except AuthError as exc:
+        print(f"error: could not write credentials: {exc}", file=stderr)
+        return 2
+    except OSError as exc:
+        print(f"error: could not write credentials: {exc}", file=stderr)
+        return 2
+
+    # Clean up any stale session.json from versions that cached a session token.
+    paths.delete_secret_file(paths.config_dir() / "session.json")
+
+    print(f"Logged in to GitHub Copilot via {host}.", file=stdout)
+    return 0
+
+
+def run_logout(*, stdout=None) -> int:
+    stdout = stdout or sys.stdout
+    paths.delete_secret_file(paths.auth_path())
+    # Legacy cleanup: pre-session-removal versions cached a session token here.
+    paths.delete_secret_file(paths.config_dir() / "session.json")
+    print("Logged out of copilot-spend.", file=stdout)
+    return 0

copilot_spend/output.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from copilot_spend.quota import Spend
+
+
+def _format_dollars(amount: float) -> str:
+    if amount < 0:
+        return f"-${abs(amount):.2f}"
+    return f"${amount:.2f}"
+
+
+def _format_reset(reset: datetime | None, now: datetime) -> str:
+    if reset is None:
+        return "next reset: unknown"
+
+    absolute = reset.strftime("%b %d, %Y")
+    delta_days = (reset.date() - now.date()).days
+
+    if delta_days == 0:
+        relative = "today"
+    elif delta_days == 1:
+        relative = "tomorrow"
+    elif delta_days > 1:
+        relative = f"in {delta_days} days"
+    elif delta_days == -1:
+        relative = "yesterday (overdue)"
+    else:
+        relative = f"overdue by {abs(delta_days)} days"
+
+    return f"{absolute} ({relative})"
+
+
+def render(spend: Spend, *, now: datetime) -> str:
+    plan_label = f" ({spend.plan})" if spend.plan else ""
+    login_label = spend.login or "<unknown account>"
+
+    lines = [
+        f"GitHub Copilot - {login_label}{plan_label}",
+        f"  Used:      {spend.consumed} PRUs",
+        f"  Allowance: {_format_dollars(spend.dollars_entitlement)}  ({spend.entitlement} PRUs included)",
+    ]
+
+    if spend.billable_prus > 0:
+        lines.append(
+            f"  Billable:  {_format_dollars(spend.dollars_owed)}"
+            f"  ({spend.billable_prus} PRUs over allowance at $0.04/PRU)"
+        )
+    else:
+        lines.append(
+            f"  Remaining: {_format_dollars(spend.dollars_free_remaining)}"
+            f"  ({spend.free_remaining_prus} PRUs of free allowance left)"
+        )
+
+    lines.append(f"  Resets:    {_format_reset(spend.reset, now)}")
+    return "\n".join(lines)

copilot_spend/paths.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import json
+import os
+import stat
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from .auth import AuthError
+
+
+def config_dir() -> Path:
+    override = os.environ.get("COPILOT_SPEND_CONFIG_DIR")
+    if override:
+        return Path(override)
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        return Path(xdg) / "copilot-spend"
+    return Path.home() / ".config" / "copilot-spend"
+
+
+def auth_path() -> Path:
+    return config_dir() / "auth.json"
+
+
+def assert_safe_parent(parent: Path) -> None:
+    if os.name != "posix":
+        return
+    if not parent.exists():
+        return
+    try:
+        info = parent.stat()
+    except OSError as exc:
+        raise AuthError(f"Cannot stat config directory {parent}: {exc}") from None
+    if info.st_uid != os.getuid():
+        raise AuthError(
+            f"Refusing to use config directory {parent}: owned by uid "
+            f"{info.st_uid}, expected {os.getuid()}. "
+            "Set COPILOT_SPEND_CONFIG_DIR or XDG_CONFIG_HOME to a directory "
+            "you own."
+        )
+    if info.st_mode & (stat.S_IWGRP | stat.S_IWOTH):
+        raise AuthError(
+            f"Refusing to use config directory {parent}: mode "
+            f"{oct(stat.S_IMODE(info.st_mode))} grants group or world write. "
+            f"Run `chmod 700 {parent}`."
+        )
+
+
+def write_secret_file(path: Path, payload: dict[str, Any]) -> None:
+    parent = path.parent
+    assert_safe_parent(parent)
+    parent.mkdir(parents=True, exist_ok=True)
+    if os.name == "posix":
+        os.chmod(parent, 0o700)
+
+    fd, tmp_str = tempfile.mkstemp(dir=parent, prefix=".tmp-", suffix=".json")
+    tmp_path = Path(tmp_str)
+    try:
+        if os.name == "posix":
+            os.chmod(fd, 0o600)
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(json.dumps(payload, indent=2).encode("utf-8"))
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp_path, path)
+    except BaseException:
+        tmp_path.unlink(missing_ok=True)
+        raise
+
+
+def delete_secret_file(path: Path) -> None:
+    path.unlink(missing_ok=True)
+
+
+def scrub(text: str, *tokens: str | None) -> str:
+    for token in tokens:
+        if token and token in text:
+            text = text.replace(token, "<redacted-token>")
+    return text

copilot_spend/quota.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+# Published GitHub Copilot premium request unit price as of 2026-05.
+# Update this constant if GitHub changes the rate.
+PRU_PRICE_USD = 0.04
+
+# Plausible field names for the next-reset timestamp. Searched at the payload
+# top level first, then inside `quota_snapshots.premium_interactions`. The
+# endpoint is undocumented; live observation (2026-05) shows `quota_reset_date`
+# at the top level with a date-only string. The other names are defensive
+# fallbacks in case GitHub renames or relocates the field.
+RESET_FIELD_CANDIDATES: tuple[str, ...] = (
+    "quota_reset_date",
+    "next_reset",
+    "reset_date",
+    "resets_at",
+    "reset",
+    "next_reset_date",
+)
+
+# Nested paths inside `premium_interactions` to search when no flat candidate
+# matches. Each path is a tuple of keys to walk.
+RESET_NESTED_PATHS: tuple[tuple[str, ...], ...] = (
+    ("reset", "date"),
+    ("reset", "at"),
+    ("next", "reset"),
+)
+
+
+class NoSubscriptionError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class Spend:
+    login: str
+    plan: str
+    entitlement: int               # included free PRUs per period
+    consumed: int                  # total PRUs used this period (>= 0)
+    billable_prus: int             # max(0, consumed - entitlement)
+    free_remaining_prus: int       # max(0, entitlement - consumed)
+    dollars_owed: float            # billable_prus * PRU_PRICE_USD
+    dollars_entitlement: float     # entitlement * PRU_PRICE_USD (reference)
+    dollars_free_remaining: float  # free_remaining_prus * PRU_PRICE_USD
+    reset: datetime | None
+
+
+def _parse_iso(value: Any) -> datetime | None:
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    # Date-only strings (e.g. "2026-06-01") parse to naive datetimes; attach
+    # UTC so downstream comparisons and formatting are consistent.
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed
+
+
+def _extract_reset(payload: dict, pi: dict) -> datetime | None:
+    for source in (payload, pi):
+        for name in RESET_FIELD_CANDIDATES:
+            if name in source:
+                parsed = _parse_iso(source[name])
+                if parsed is not None:
+                    return parsed
+    for path in RESET_NESTED_PATHS:
+        cursor: Any = pi
+        for key in path:
+            if isinstance(cursor, dict) and key in cursor:
+                cursor = cursor[key]
+            else:
+                cursor = None
+                break
+        parsed = _parse_iso(cursor)
+        if parsed is not None:
+            return parsed
+    return None
+
+
+def parse_quota(payload: dict) -> Spend:
+    plan = payload.get("copilot_plan") or ""
+    snapshots = payload.get("quota_snapshots") or {}
+    pi = snapshots.get("premium_interactions") if isinstance(snapshots, dict) else None
+
+    # Origin R7: missing copilot_plan OR missing premium_interactions → no subscription.
+    if not plan or not isinstance(pi, dict):
+        raise NoSubscriptionError("No Copilot quota on this account.")
+
+    try:
+        entitlement = int(pi["entitlement"])
+        remaining = int(pi["remaining"])
+    except (KeyError, TypeError, ValueError) as exc:
+        raise NoSubscriptionError(
+            f"premium_interactions missing entitlement/remaining: {exc}"
+        ) from None
+
+    # API semantics observed against a business-plan account:
+    #   `remaining` counts down from 0 as you consume PRUs (so the value is
+    #   ≤ 0 in steady state on this plan class). `entitlement` is the free
+    #   credit per period — the first N PRUs are not billable.
+    # Defensive: if `remaining` is positive (unobserved case, possibly other
+    # plan classes), treat it as zero consumption rather than guessing.
+    consumed = max(0, -remaining)
+    billable_prus = max(0, consumed - entitlement)
+    free_remaining_prus = max(0, entitlement - consumed)
+
+    dollars_owed = round(billable_prus * PRU_PRICE_USD, 2)
+    dollars_entitlement = round(entitlement * PRU_PRICE_USD, 2)
+    dollars_free_remaining = round(free_remaining_prus * PRU_PRICE_USD, 2)
+
+    reset = _extract_reset(payload, pi)
+
+    login = payload.get("login") or ""
+    if not isinstance(login, str):
+        login = ""
+    if not isinstance(plan, str):
+        plan = ""
+
+    return Spend(
+        login=login,
+        plan=plan,
+        entitlement=entitlement,
+        consumed=consumed,
+        billable_prus=billable_prus,
+        free_remaining_prus=free_remaining_prus,
+        dollars_owed=dollars_owed,
+        dollars_entitlement=dollars_entitlement,
+        dollars_free_remaining=dollars_free_remaining,
+        reset=reset,
+    )
+
+
+__all__ = [
+    "PRU_PRICE_USD",
+    "RESET_FIELD_CANDIDATES",
+    "RESET_NESTED_PATHS",
+    "NoSubscriptionError",
+    "Spend",
+    "parse_quota",
+]

copilot_spend-0.1.0.dist-info/METADATA

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: copilot-spend
+Version: 0.1.0
+Summary: Print your current-period GitHub Copilot spend and reset date.
+Project-URL: Homepage, https://github.com/nkootstra/copilot-spend
+Project-URL: Source, https://github.com/nkootstra/copilot-spend
+Project-URL: Issues, https://github.com/nkootstra/copilot-spend/issues
+Project-URL: Changelog, https://github.com/nkootstra/copilot-spend/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/nkootstra/copilot-spend#readme
+Author-email: Niels Kootstra <niels.kootstra@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Niels
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cli,copilot,github,quota,spend
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# copilot-spend
+
+Find out what your Copilot habit actually costs.
+
+A small Python CLI that reads your GitHub Copilot quota and prints
+your current-period spend in dollars and PRUs, plus when the period resets.
+Works against both `github.com` and GitHub Enterprise hosts.
+
+## How it works
+
+```mermaid
+flowchart TD
+    Start([copilot-spend ...]) --> Cmd{subcommand?}
+
+    Cmd -- login --> Host[prompt: github.com or GHE host]
+    Host --> DeviceCode[POST /login/device/code]
+    DeviceCode --> ShowCode[show user code + verification URL]
+    ShowCode --> Poll[poll /login/oauth/access_token]
+    Poll -- access_denied / expired --> LoginFail[/exit 2: login failed/]
+    Poll -- ghu_ token --> Verify[verify token works<br/>GET /copilot_internal/user]
+    Verify -- fail --> LoginFail
+    Verify -- ok --> WriteAuth[write auth.json 0o600]
+    WriteAuth --> LoginDone[/exit 0/]
+
+    Cmd -- logout --> DeleteFiles[delete auth.json]
+    DeleteFiles --> LogoutDone[/exit 0/]
+
+    Cmd -- bare --> Native{native<br/>~/.config/copilot-spend/auth.json?}
+    Native -- yes --> NativeBearer[bearer = ghu_ token]
+    Native -- no --> Opencode{opencode<br/>~/.local/share/opencode/auth.json?}
+    Opencode -- yes --> OpencodeBearer[bearer = gho_ token]
+    Opencode -- no --> NoCreds[/exit 2: run copilot-spend login/]
+    NativeBearer --> Quota[GET /copilot_internal/user with Bearer]
+    OpencodeBearer --> Quota
+    Quota -- 200 --> Print[/print spend + reset date<br/>exit 0/]
+    Quota -- 401 / 403 --> AuthErr[/exit 2: re-authenticate/]
+    Quota -- 404 --> NoSub[/exit 4: no Copilot quota/]
+    Quota -- 5xx / timeout --> ApiErr[/exit 3: API error/]
+```
+
+The bare `copilot-spend` invocation, expanded as numbered steps:
+
+1. Resolves a GitHub Copilot token from the first source that exists, in
+   this order:
+   1. Native: `~/.config/copilot-spend/auth.json`, created by running
+      `copilot-spend login`.
+   2. Opencode fallback: `~/.local/share/opencode/auth.json` (keys
+      `github-copilot.access` and `github-copilot.enterpriseUrl`), if
+      opencode is installed.
+2. Uses the resolved token directly as the `Bearer` for the next step.
+   Both source kinds work the same way: native gives a `ghu_…` GitHub App
+   user-to-server token, opencode gives a `gho_…` OAuth App token, and
+   `/copilot_internal/user` accepts either one directly.
+3. Calls `GET /api/v3/copilot_internal/user` on your GHE host, or
+   `GET https://api.github.com/copilot_internal/user` if no enterprise
+   host is configured.
+4. Computes the billable overage:
+   `billable_PRUs = max(0, consumed - entitlement)`, then
+   `dollars_owed = billable_PRUs × $0.04`.
+   The first `entitlement` PRUs each period are included with your plan
+   and cost nothing.
+5. Prints a plain-text summary on stdout.
+
+No background daemon. No history. No session-token cache. One HTTP
+request per run.
+
+## Requirements
+
+- Python 3.10 or newer
+- macOS or Linux
+- A GitHub Copilot token, obtained by either:
+  - running `copilot-spend login`, or
+  - having opencode installed and authenticated already
+
+## Install
+
+```sh
+# Option A: pipx (persistent, isolated)
+pipx install copilot-spend
+
+# Option B: pip (into your active environment or --user)
+pip install copilot-spend
+
+# Option C: uv tool (persistent, isolated)
+uv tool install copilot-spend
+
+# Option D: one-off run, no install
+uvx copilot-spend
+pipx run copilot-spend
+```
+
+### Install from source
+
+```sh
+git clone https://github.com/nkootstra/copilot-spend.git
+cd copilot-spend
+
+pipx install .
+# or:
+uv tool install --from . copilot-spend
+# or one-off:
+uvx --from . copilot-spend
+```
+
+## Usage
+
+```sh
+copilot-spend          # print current-period quota
+copilot-spend login    # authenticate via GitHub OAuth device flow
+copilot-spend logout   # remove copilot-spend's stored credentials
+```
+
+`copilot-spend login` prompts for github.com or a GHE host, shows a
+device code with a URL to visit, then polls until you complete the
+flow in your browser. The new token is verified against
+`/copilot_internal/user` before anything gets persisted. Credentials
+land in `~/.config/copilot-spend/auth.json` (mode `0o600`). If you
+already have opencode authenticated, the bare `copilot-spend` command
+continues to work without login.
+
+Example output (under your allowance):
+
+```
+GitHub Copilot - your-login (business)
+  Used:      221 PRUs
+  Allowance: $12.00  (300 PRUs included)
+  Remaining: $3.16  (79 PRUs of free allowance left)
+  Resets:    May 31, 2026 (in 15 days)
+```
+
+Example output (over your allowance — billable overage):
+
+```
+GitHub Copilot - your-login (business)
+  Used:      4073 PRUs
+  Allowance: $12.00  (300 PRUs included)
+  Billable:  $150.92  (3773 PRUs over allowance at $0.04/PRU)
+  Resets:    Jun 01, 2026 (in 16 days)
+```
+
+Flags: `--help`, `--version`. Subcommands: `login`, `logout`.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Unexpected error |
+| 2 | Auth error (missing/invalid `auth.json` or token) |
+| 3 | API error (network, timeout, 4xx/5xx) |
+| 4 | No Copilot quota on the account |
+
+## Switch to your own GitHub App
+
+`copilot-spend login` runs the GitHub OAuth device flow against
+Microsoft's well-known VS Code Copilot GitHub App
+(`Iv1.b507a08c87ecfe98`). This is the same client ID used by every
+working third-party Copilot tool — copilot.vim, avante.nvim, LiteLLM,
+and others — because GitHub's session-token exchange endpoint
+(`/copilot_internal/v2/token`) only accepts tokens issued by a GitHub
+App, not by an OAuth App.
+
+The trade-off: the GitHub consent screen during login says "GitHub for
+VS Code" rather than "copilot-spend", and you depend on Microsoft not
+rotating that app. To remove both, register your own GitHub App and
+swap the constant:
+
+1. Visit https://github.com/settings/apps and click **New GitHub App**.
+   This must be a *GitHub App*, not an *OAuth App* — OAuth Apps issue
+   `gho_…` tokens that the Copilot exchange endpoint rejects with 404.
+2. Set Homepage URL and Callback URL to anything (the device flow does
+   not use them).
+3. Enable **Device flow** under "Identifying and authorizing users".
+4. Account permissions: none required beyond user identification.
+   The `read:user` OAuth scope is enough.
+5. Note the resulting **Client ID** (starts with `Iv23` or `Iv1.`).
+6. Replace the `CLIENT_ID` constant in
+   `src/copilot_spend/login.py` with your new client ID.
+7. Rebuild/reinstall (`pipx install --force .` or
+   `uv tool install --force --from . copilot-spend`).
+
+After the swap, the consent screen shows your app's name and your
+copilot-spend install no longer breaks if Microsoft rotates
+`Iv1.b507a08c87ecfe98`.
+
+## Caveats
+
+- The PRU price is hardcoded at $0.04 (correct as of 2026-05). Update the
+  constant in `src/copilot_spend/quota.py` if GitHub changes it.
+- v1 ships with VS Code's GitHub App ID `Iv1.b507a08c87ecfe98` for the
+  device flow. See "Switch to your own GitHub App" above to remove the
+  dependency.
+- The billing model assumed: the first `entitlement` PRUs each period are
+  included with your plan, and anything beyond that is billable at $0.04
+  per PRU. This matches observed behavior on a business plan. Org-level
+  caps or contracts may change what you actually pay — treat the
+  `Billable` figure as a personal estimate, not an invoice.
+- The reset-date field name in the Copilot API response is best-effort:
+  `copilot-spend` tries the field names observed on a real response, plus
+  a few defensive fallbacks, and prints `next reset: unknown` if none
+  match. Adjust `RESET_FIELD_CANDIDATES` in `quota.py` if your response
+  uses a different name.
+- The `/copilot_internal/user` endpoint is not a public, documented API.
+  GitHub may change its shape at any time.
+
+## Development
+
+```sh
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```

copilot_spend-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+copilot_spend/__init__.py,sha256=mOUnkKLmpJwiljM2PF7UB0ifT-94wKv8Bo_NGBBIgt8,77
+copilot_spend/__main__.py,sha256=aI19Q7QEFhIHNZatXr3Xkrwj1-p5nQ--LVEb48dIvzI,88
+copilot_spend/api.py,sha256=TpaEISTOw5ZX4lZVJZgaf9l2-CuXTWQL8tVy73-7ilk,3587
+copilot_spend/auth.py,sha256=cTz98IDi_1HnZxQt3e4EL0vjCx4FZjYeaK330zhju1s,5819
+copilot_spend/cli.py,sha256=0tAkQJS43b1m2x0-3OHR68Qw0UEzLcaDtVxdDa4x9-M,2758
+copilot_spend/login.py,sha256=cp7dxdP4dw0b4yP05rvPy0P2UUdz936gSa62E2jFMOg,8678
+copilot_spend/output.py,sha256=jzj1TWxfjwcQkCPd-O5ULjVlZPFp9jdPjl4XFIs-SfY,1693
+copilot_spend/paths.py,sha256=3SrN3QV-5ybCGh4oKvbR2mu5oS0MwN1yxdk-mgAAhhc,2340
+copilot_spend/quota.py,sha256=tVnUdoPQRVa7D0-xmTB0qZI3k5kFNkfmHCeHv96UdDc,5023
+copilot_spend-0.1.0.dist-info/METADATA,sha256=lgtmVNaC5xo5PFu-0GL8i0VGF2uvZzS8t6hThcqffPU,10371
+copilot_spend-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+copilot_spend-0.1.0.dist-info/entry_points.txt,sha256=HGni_718xl1N0OzIN8Nq7KOJtghb1GDUXhgP8ENwwGM,64
+copilot_spend-0.1.0.dist-info/licenses/LICENSE,sha256=OIDefE7LMks4ClJdo8FZ4rJNaaoNksNHKYDfpLjump8,1062
+copilot_spend-0.1.0.dist-info/RECORD,,

copilot_spend-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

copilot_spend-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+copilot-spend = copilot_spend.cli:_entrypoint

copilot_spend-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niels
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.