extendvcc-cli 0.1.0__tar.gz

extendvcc_cli-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,76 @@
+name: Bug Report
+description: Something isn't working as expected.
+title: "bug: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before submitting: confirm the bug is reproducible with the latest version. **Do not include card numbers, CVCs, API tokens, or any account credentials in this report.**
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened? What did you expect to happen instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal steps to trigger the bug.
+      placeholder: |
+        1. Run `extendvcc ...`
+        2. Observe ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What should have happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened? Include the full error output (with secrets redacted).
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      placeholder: "e.g. macOS 14.5, Ubuntu 22.04"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python Version
+      placeholder: "e.g. 3.12.3"
+    validations:
+      required: true
+
+  - type: input
+    id: extendvcc
+    attributes:
+      label: extendvcc Version
+      placeholder: "e.g. 0.1.0  (run: extendvcc --version)"
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: no_secrets
+    attributes:
+      label: Security Confirmation
+      options:
+        - label: I have confirmed this report contains no card numbers, CVCs, API tokens, IMAP passwords, session data, or any other sensitive credentials.
+          required: true

extendvcc_cli-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security Vulnerability
+    url: https://github.com/4LAU/extendvcc/security/advisories/new
+    about: Report a security vulnerability privately via GitHub Security Advisories. Do not open a public issue.

extendvcc_cli-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,36 @@
+name: Feature Request
+description: Propose a new feature or improvement.
+title: "feat: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this solve? What can't you do today, or what's unnecessarily hard?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: What would you like to see? Describe the behavior, CLI flags, or API changes you have in mind.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: What workarounds have you tried? Are there other ways to solve this?
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Anything else that would help — links, related issues, examples from other tools.
+    validations:
+      required: false

extendvcc_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv venv && uv pip install -e '.[dev]'
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv venv && uv pip install -e '.[dev]'
+      - run: uv run pytest tests/ -v
+
+  gitleaks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install gitleaks
+        run: |
+          curl -sSfL "https://github.com/gitleaks/gitleaks/releases/download/v8.24.3/gitleaks_8.24.3_linux_x64.tar.gz" \
+            | tar xz -C /usr/local/bin gitleaks
+      - name: Scan
+        run: gitleaks detect --source . -v --redact

extendvcc_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,94 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - os: macos-latest
+            arch: arm64
+            artifact: extendvcc-macos-arm64
+          - os: macos-13
+            arch: x86_64
+            artifact: extendvcc-macos-x86_64
+          - os: ubuntu-latest
+            arch: x86_64
+            artifact: extendvcc-linux-x86_64
+          - os: windows-latest
+            arch: x86_64
+            artifact: extendvcc-windows-x86_64.exe
+
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install pyinstaller
+      - run: pip install -e .
+      - run: pyinstaller --onefile --name ${{ matrix.artifact }} --strip src/extendvcc/cli.py
+        shell: bash
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.artifact }}
+          path: dist/${{ matrix.artifact }}*
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[dev]"
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+      - run: pytest tests/ -q
+
+  release:
+    needs: [build, test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          merge-multiple: true
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: extendvcc-*
+          generate_release_notes: true
+
+  build-dist:
+    needs: [test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+
+  publish:
+    needs: [build-dist, test]
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0

extendvcc_cli-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.pyc
+*.pyo
+dist/
+build/
+*.egg-info/
+.venv/
+.env
+.env.*
+.claude/
+.codex/
+.ruff_cache/
+.pytest_cache/
+*.jsonl
+*.json
+!tests/fixtures/*.json
+.worktrees/

extendvcc_cli-0.1.0/AGENTS.md

@@ -0,0 +1,95 @@
+# AGENTS.md: Contributor Guide
+
+Tool-agnostic guide for AI agents and human contributors. For Claude Code specifics, see `CLAUDE.md`.
+
+---
+
+## Project Overview
+
+`extendvcc` is an unofficial Python client and CLI for Extend's private virtual card API (`api.paywithextend.com`). It handles Cognito SRP authentication with device remembering and email OTP, the full virtual-card lifecycle (create, list, update, cancel, close, reveal), parent credit-card enrollment, and a JSONL audit ledger for all card mutations. HTTP uses `impit` for Chrome TLS fingerprinting, which is necessary because Extend blocks non-browser TLS profiles.
+
+---
+
+## Build, Lint, Test
+
+All three must be clean before any change is considered done:
+
+```bash
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
+uv run pytest tests/ -v
+```
+
+Install dev dependencies first if needed: `uv pip install -e '.[dev]'`
+
+---
+
+## Module Map
+
+```
+src/extendvcc/
+├── __init__.py      # Public API re-exports
+├── _paths.py        # Lazy state_dir() / ledger_path() with CLI override, env, default
+├── _jsonl.py        # Vendored append_jsonl helper
+├── auth.py          # Cognito SRP login, device remembering, token refresh, session persistence
+├── client.py        # HTTP client (impit), kill switch, rate limiting, account-risk detection
+├── cards.py         # Card CRUD — create, list, get, update, cancel, close, reveal, enroll, bulk
+├── imap_otp.py      # IMAP-based OTP retrieval for Cognito EMAIL_OTP challenges
+├── ledger.py        # JSONL audit ledger for card mutations (pending/confirm/fail)
+├── models.py        # CardStatus, VirtualCard, CreditCard, Issuer, Recurrence
+└── cli.py           # Full lifecycle CLI (login, cards, create, reveal, etc.)
+```
+
+---
+
+## Coding Style
+
+- **HTTP:** All network requests go through `impit` with Chrome TLS fingerprinting. Never import `httpx` or `requests` directly; Extend detects and blocks non-browser TLS profiles.
+- **Paths:** Use `_paths.py` helpers (`state_dir()`, `ledger_path()`). Never compute paths at module level. Always resolve lazily so CLI flags and env vars take effect.
+- **Functions:** One function at a time, max ~30 lines. Search existing code before adding anything new.
+- **Logging:** Never log or print card numbers, CVCs, or full tokens. Mask to last 4 digits when logging is necessary.
+- **Tests:** All tests run offline with fakes. Mock only at the I/O boundary (HTTP client, filesystem, IMAP). See `docs/testing-policy.md`.
+
+---
+
+## Commit Conventions
+
+Follow Conventional Commits:
+
+```
+feat: add bulk-create pacing option
+fix: handle expired session token on first request
+chore: bump impit to 0.13.0
+style: fix trailing whitespace
+docs: add reveal example to README
+test: add ledger concurrent-write invariant
+```
+
+Scope is optional. Keep the subject line under 72 characters.
+
+---
+
+## What Needs Approval vs. Proceed
+
+**Get maintainer approval before changing:**
+- Auth flow (Cognito SRP, device remembering, OTP, token refresh)
+- Anything that touches card number or CVC handling
+- Public API surface (`__init__.py` exports, CLI command names/flags)
+- Destructive operations (data deletion, credential rotation)
+
+**Proceed without asking:**
+- Bug fixes inside existing functions
+- New tests
+- Documentation updates
+- Dependency version bumps
+- Refactors that don't change the public API
+
+---
+
+## Security Rules
+
+- **Never store or log PAN/CVC:** the ledger never persists card numbers or CVCs. Mask to last 4 when logging.
+- **Never make real Extend API calls in tests:** all tests run offline with fakes. Network access in tests is not skipped; it is deleted.
+- **Never commit session files, credential caches, or `.env*` files:** these contain live auth tokens.
+- **Credentials via env vars:** `EXTENDVCC_EMAIL`, `EXTENDVCC_PASSWORD`, `EXTENDVCC_IMAP_*`. Interactive prompts in CLI. No hardcoded credentials anywhere.
+- Session and state files are written with `0600` permissions. The HTTP client has a kill switch that disables itself on risk signals (403, WAF blocks, verification prompts).

extendvcc_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [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-06-14
+
+### Added
+
+- **Authentication:** Cognito SRP login with device remembering; automatic token refresh; session persistence to disk with `0600` permissions.
+- **Email OTP:** IMAP-based OTP retrieval for Cognito `EMAIL_OTP` challenges, configurable via `EXTENDVCC_IMAP_*` env vars.
+- **Virtual card lifecycle:** create, list, get, update, cancel, close, and reveal (PAN + CVC + expiry) virtual cards.
+- **Reveal:** masked stdout output by default; `--json-path` writes full credentials to a file with `0600` permissions.
+- **Parent credit cards:** enroll and activate parent credit cards.
+- **Bulk create:** create multiple virtual cards with configurable pacing to avoid rate limits.
+- **Recurring cards:** support for `DAILY`, `WEEKLY`, and `MONTHLY` recurrence periods with configurable terminators.
+- **JSONL audit ledger:** append-only ledger records every card mutation as pending → confirmed or failed; `reconcile` command flags unconfirmed entries.
+- **Kill switch:** HTTP client disables itself on account-risk signals (403, WAF blocks, verification prompts) to avoid account suspension.
+- **Chrome TLS fingerprinting:** all HTTP via `impit`; Extend blocks non-browser TLS profiles.
+- **CLI:** full lifecycle commands: `login`, `accounts`, `issuers`, `cards`, `card`, `usage`, `enroll`, `activate`, `create`, `bulk`, `update`, `cancel`, `close`, `reveal`, `reconcile`, `status`, `clear-disabled`.
+- **Python API:** public re-exports in `extendvcc.__init__` for programmatic use.
+- **Typed:** `py.typed` marker (PEP 561); type hints throughout.
+
+[Unreleased]: https://github.com/4LAU/extendvcc/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/4LAU/extendvcc/releases/tag/v0.1.0

extendvcc_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,67 @@
+# extendvcc
+
+Unofficial Python client and CLI for Extend's private virtual card API.
+
+**Stack:** Python 3.11+, src/ layout, hatchling build, impit (Chrome TLS fingerprinting), filelock, argparse CLI, pytest, ruff.
+
+---
+
+## Critical Rules
+
+1. **NEVER expose secrets:** card numbers, CVCs, API tokens, session files, PII. If exposed: STOP and rotate immediately.
+2. **NEVER use `git add .`:** add files individually. gitleaks pre-commit enforces this.
+3. **NEVER log or print card numbers, CVCs, or full tokens.** Mask to last 4 digits when logging is necessary.
+4. **NEVER make real Extend API calls in tests.** All tests run offline with fakes.
+5. **NEVER commit session files, credential caches, or `.env*` files.**
+6. **NEVER claim tests pass without showing actual output.**
+
+---
+
+## Definition of Done
+
+```bash
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
+uv run pytest tests/ -v
+```
+
+All three clean before claiming done.
+
+---
+
+## Code Practices
+
+**Ask maintainer approval for:** auth flow changes, anything touching card number/CVC handling, public API surface changes, destructive ops. Everything else: proceed.
+
+**Generation:** Search existing code first. One function at a time (max 30 lines).
+
+**impit:** All HTTP goes through `impit` with Chrome TLS fingerprinting. Never use bare `httpx` or `requests`; Extend fingerprints non-browser clients.
+
+**Credentials:** Env vars (`EXTENDVCC_EMAIL`, `EXTENDVCC_PASSWORD`, `EXTENDVCC_IMAP_*`). Interactive prompts in CLI. No 1Password integration in this package.
+
+**Paths:** Lazy resolution via `_paths.py`. CLI flags override env vars override defaults. Never use module-level `Path` constants that resolve at import time.
+
+---
+
+## Module Map
+
+```
+src/extendvcc/
+├── __init__.py      # Public API re-exports
+├── _paths.py        # Lazy state_dir() / ledger_path() with CLI override, env, default
+├── _jsonl.py        # Vendored append_jsonl helper
+├── auth.py          # Cognito SRP login, device remembering, token refresh, session persistence
+├── client.py        # HTTP client (impit), kill switch, rate limiting, account-risk detection
+├── cards.py         # Card CRUD — create, list, get, update, cancel, close, reveal, enroll, bulk
+├── imap_otp.py      # IMAP-based OTP retrieval for Cognito EMAIL_OTP challenges
+├── ledger.py        # JSONL audit ledger for card mutations (pending/confirm/fail)
+├── models.py        # CardStatus, VirtualCard, CreditCard, Issuer, Recurrence
+└── cli.py           # Full lifecycle CLI (login, cards, create, reveal, etc.)
+```
+
+---
+
+## Testing
+
+See `docs/testing-policy.md`. All tests offline, mock only at I/O boundary, every test protects a named invariant.
+

extendvcc_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+Fork the repo, create a feature branch, open a PR.
+
+## Setup
+
+```bash
+pip install -e '.[dev]'
+```
+
+## Checks
+
+Both must pass before merging:
+
+```bash
+ruff check src/ tests/
+pytest tests/ -v
+```
+
+All tests run offline; no real API calls are made.
+
+## Pre-commit
+
+A gitleaks pre-commit hook is required to prevent accidental secret leaks.

extendvcc_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 extendvcc contributors
+
+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.