{"id":50792889,"url":"https://github.com/cryptojones/va-claim-checker","last_synced_at":"2026-06-12T12:02:31.353Z","repository":{"id":299477376,"uuid":"1003182439","full_name":"CryptoJones/VA-Claim-Checker","owner":"CryptoJones","description":"Checks the status of a VA Claim for update","archived":false,"fork":false,"pushed_at":"2026-05-09T12:19:31.000Z","size":123,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T13:26:29.921Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CryptoJones.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-16T18:49:47.000Z","updated_at":"2026-05-09T12:19:28.000Z","dependencies_parsed_at":"2025-06-16T20:02:48.423Z","dependency_job_id":null,"html_url":"https://github.com/CryptoJones/VA-Claim-Checker","commit_stats":null,"previous_names":["cryptojones/va-claim-checker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CryptoJones/VA-Claim-Checker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2FVA-Claim-Checker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2FVA-Claim-Checker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2FVA-Claim-Checker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2FVA-Claim-Checker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CryptoJones","download_url":"https://codeload.github.com/CryptoJones/VA-Claim-Checker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2FVA-Claim-Checker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34243053,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-12T12:01:47.022Z","updated_at":"2026-06-12T12:02:26.402Z","avatar_url":"https://github.com/CryptoJones.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VA Claim Checker\n\nMonitors the status of a VA benefits claim and sends you a notification whenever it moves to a new phase — email, ntfy.sh push, or Pushover.\n\nFor VA API documentation see: https://developer.va.gov/explore/api/benefits-claims\n\n---\n\n## Quick Start\n\n### 1. Install dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n### 2. Run the setup utility\n\n```bash\npython3 init.py\n```\n\nThe setup utility walks you through everything interactively:\n\n- **API mode** — `mock` (no credentials, good for a first run), `real` (your live VA account), or `sandbox` (VA test environment — developers only)\n- **Authentication** — OAuth 2.0 (recommended) or browser cookies (legacy fallback)\n- **Claim ID** — one or multiple\n- **Notifications** — email, ntfy.sh, Pushover, or none\n\nIt writes `config.json` and optionally runs a test check when done.\n\n\u003e **Just want to check your own claim?** Use `real` mode — no API key required. OAuth 2.0 authenticates via your VA.gov account using **login.gov** or **ID.me**. `sandbox` mode is only needed if you are developing or testing against the VA's test environment.\n\n---\n\n## Authentication\n\n### Real mode — VA.gov (no developer account needed)\n\n```bash\npython3 init.py\n```\n\nChoose **real** mode and **OAuth 2.0** when prompted. You will then be asked to select an identity provider:\n\n| Provider | Notes |\n|---|---|\n| **Login.gov** | Government-issued identity, recommended |\n| **ID.me** | Widely used, supports hardware MFA keys |\n\nA browser window opens for you to log in. If your account has MFA enabled (SMS, authenticator app, security key, etc.), complete it in the browser — the tool waits up to 5 minutes. After that, tokens refresh automatically with no further interaction needed.\n\n\u003e **Troubleshooting:** If authentication times out, ensure nothing else is using port 8080 and try again. The tool starts a temporary local server on that port to receive the login callback.\n\n---\n\n### Sandbox mode (developers only)\n\nSandbox mode connects to VA's test environment with synthetic claim data. It requires a developer API key and is not needed to check your real claims.\n\n#### 1. Apply for a sandbox API key\n\n1. Go to https://developer.va.gov/apply and create a free developer account\n2. Click **Request API Access** and select **Benefits Claims**\n3. When prompted for a redirect URI, enter exactly: `http://localhost:8080/callback`\n4. Submit the form — VA will email you a `client_id` and `client_secret` (typically within a few business days)\n\n#### 2. Configure credentials\n\n```bash\ncp config.example.json config.json\n```\n\nEdit `config.json`:\n\n```json\n\"mode\": \"sandbox\",\n\"oauth\": {\n    \"client_id\": \"your_client_id\",\n    \"client_secret\": \"your_client_secret\"\n}\n```\n\nOr use environment variables instead:\n\n```bash\nexport VA_CLIENT_ID=your_client_id\nexport VA_CLIENT_SECRET=your_client_secret\n```\n\n#### 3. Authenticate\n\n```bash\npython3 init.py\n```\n\nChoose **sandbox** mode and **OAuth 2.0** when prompted.\n\n### Browser cookies (legacy)\n\nIf you are waiting for OAuth approval, you can use browser session cookies as a temporary workaround. Note: **cookies expire every 12 hours** and must be manually refreshed.\n\n1. Install the [Cookie Viewer](https://chromewebstore.google.com/detail/cookie-viewer/dedhcncdjkmjpebfohadfeeaopiponca) Chrome extension\n2. Log in at https://www.va.gov/track-claims/your-claims/\n3. Open https://api.va.gov/v0/benefits_claims/ in a new tab\n4. Click Cookie Viewer and paste the values into `config.json` under `\"cookies\"`\n\nRun `python3 init.py` and choose **cookies** to be guided through this.\n\n---\n\n## Usage\n\n```bash\npython3 cli.py status                      # show current claim status\npython3 cli.py check                       # check for changes, notify if any\npython3 cli.py check --claim-id 123 456    # check specific claim IDs\npython3 cli.py claims                      # list all your claims\npython3 cli.py watch                       # poll every 30 minutes (daemon mode)\npython3 cli.py watch --interval 3600       # poll every hour\npython3 cli.py reset                       # clear saved state (re-enables notifications)\npython3 cli.py reset --claim-id 123        # reset a specific claim\npython3 cli.py logout                      # remove stored OAuth tokens\n```\n\n### Scheduling automatic checks\n\nUse `watch` mode to keep the checker running, or add a cron job:\n\n```bash\n# Check every 30 minutes via cron\n*/30 * * * * cd /path/to/VA-Claim-Checker \u0026\u0026 python3 cli.py check\n```\n\n---\n\n## Notifications\n\nConfigure in `config.json` or via the `init.py` setup utility.\n\n| Method | What to set |\n|---|---|\n| Email (SMTP) | `send_email: true`, fill in the `email` block |\n| ntfy.sh | `push.enabled: true`, `push.provider: \"ntfy\"`, set `push.topic` |\n| Pushover | `push.enabled: true`, `push.provider: \"pushover\"`, set `push.app_token` and `push.user_key` |\n\nSensitive values (SMTP password, push tokens) can be kept out of `config.json` by using environment variables:\n\n```bash\nexport VA_SMTP_PASSWORD=your_password\nexport VA_NTFY_TOKEN=your_token\nexport VA_PUSHOVER_APP_TOKEN=your_app_token\nexport VA_PUSHOVER_USER_KEY=your_user_key\n```\n\n---\n\n## Running tests\n\n```bash\npython3 -m pytest tests/ -v\n```\n\n262 tests cover every module:\n\n| File | Tests | What's covered |\n|---|---|---|\n| `test_init.py` | 84 | Setup utility — ask, choose, all 5 steps, main flow, keyboard interrupt |\n| `test_agent.py` | 30 | Config loading, analyze_status, run_check, multi-claim, fetch, list |\n| `test_auth.py` | 36 | TokenStore, resolve_secret, OAuthClient token/refresh/authorize/MFA/timeout/port conflict/idp |\n| `test_va_api_client.py` | 27 | Mock + real mode, legacy + v2 URLs, headers, retry config |\n| `test_cli.py` | 24 | All 6 subcommands, multi-claim flag, watch loop, help output |\n| `test_state.py` | 24 | StateStore get/save/has_changed/diff_summary/reset |\n| `test_notifier.py` | 20 | Mock output, SMTP, ntfy, Pushover, env var overrides |\n| `test_va_response_parser.py` | 18 | normalize() — flat passthrough, v2 response, missing fields, contentions |\n\n---\n\n## Project structure\n\n```\ninit.py               — interactive setup utility (start here)\ncli.py                — command-line interface\nagent.py              — orchestrates check → diff → notify loop\nva_api_client.py      — VA API requests (mock + real), retry logic\nva_response_parser.py — normalizes Lighthouse v2 API response fields\nauth.py               — OAuth 2.0 flow, token storage, auto-refresh\nstate.py              — persists last-known claim state across runs\nnotifier.py           — email, ntfy.sh, and Pushover notifications\nconfig.example.json   — template configuration with placeholder values\nconfig.json           — your configuration (created by init.py, gitignored)\ntests/                — pytest test suite\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptojones%2Fva-claim-checker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcryptojones%2Fva-claim-checker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptojones%2Fva-claim-checker/lists"}