copilot-spend 0.1.0__tar.gz

copilot_spend-0.1.0/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Project-internal planning docs (brainstorms, plans) — never ship to PyPI or git
+docs/

copilot_spend-0.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-17
+
+### Added
+
+- `copilot-spend` bare command: reads the current-period Copilot quota and
+  prints used PRUs, included allowance, billable overage (at $0.04/PRU), and
+  the period reset date.
+- `copilot-spend login` subcommand: GitHub OAuth device flow against the
+  well-known VS Code Copilot GitHub App client ID, with re-auth detection,
+  `slow_down` handling, defensive timeout, SSRF host validation, and
+  post-login verification against `/copilot_internal/user` before any token
+  is persisted.
+- `copilot-spend logout` subcommand: removes stored credentials
+  idempotently and cleans up any legacy `session.json` from earlier builds.
+- Multi-source auth resolution: prefers the native
+  `~/.config/copilot-spend/auth.json`, falls back to an existing
+  `~/.local/share/opencode/auth.json` so users already authenticated to
+  opencode work without re-running login.
+- GitHub Enterprise host support: device flow and quota fetch both target
+  `https://<ghe-host>/api/v3/...` when an enterprise host is configured.
+- Single-hop bearer path: the `ghu_` or `gho_` user token is sent directly
+  as `Bearer` to `/copilot_internal/user` — no separate session-token
+  exchange, no `session.json` cache.
+- Hardened on-disk secrets: `auth.json` written atomically with `0o600`
+  inside a `0o700` config directory; refuses to use a config directory
+  owned by a different uid or group/world writable.
+- Token redaction in all user-facing error paths, including post-login
+  verification failures.
+- Documented exit codes (`0` success, `1` unexpected, `2` auth, `3` API,
+  `4` no Copilot quota).
+- Mermaid flowchart in the README covering the full login, logout, and
+  bare-invocation flows.
+
+[Unreleased]: https://github.com/nkootstra/copilot-spend/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/nkootstra/copilot-spend/releases/tag/v0.1.0

copilot_spend-0.1.0/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.

copilot_spend-0.1.0/PKG-INFO

@@ -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
+```