bachs-cli 0.1.0__tar.gz

bachs_cli-0.1.0/.gitignore

@@ -0,0 +1,244 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+*.pyc
+scripts/seed_admin.py
+.DS_Store
+
+.env
+.env.stripe-smoke
+
+# Node.js
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+misc.py
+# Distribution / packaging
+.Python
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+dist/
+build/
+*.egg-info/
+# C extensions
+*.so
+*.dump*
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+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
+
+# Pytest
+.cache
+.pytest_cache/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Jupyter Notebook checkpoints
+.ipynb_checkpoints
+
+# VS Code settings
+.vscode/
+
+# PyCharm
+.idea/
+*.iml
+
+# MacOS
+.DS_Store
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Icon?
+Desktop.ini
+
+# Coverage reports
+htmlcov/
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+
+# Environment variables
+.env
+
+# Pyre type checker
+.pyre/
+*.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/
+
+# Other files to ignore (customize as needed)
+*.log
+*.pot
+*.pyc
+
+# Ignore local configuration files
+local_settings.py
+# 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
+
+# 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
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.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/
+node_modules/
+*/node_modules/
+.aider*
+
+# Simulator load-test runtime manifest
+scripts/loadtest/manifest.json
+
+# Simulator load-test input data (checkout id CSVs) — keep local, not in repo
+test_webhooks_*.csv
+
+# SDD agent scratch (briefs, reports, ledgers) — never a deliverable.
+.superpowers/
+
+# Reconciliation report output — contains customer names
+payaza_recon*.csv
+.worktrees/

bachs_cli-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: bachs-cli
+Version: 0.1.0
+Summary: Forward live Bachs webhook events to your local machine
+Project-URL: Homepage, https://bachs.io
+Project-URL: Documentation, https://docs.bachs.io/developer-portal/local-testing
+Project-URL: Changelog, https://docs.bachs.io/changelog/api
+Author-email: Bachs <support@bachs.io>
+License: MIT
+Keywords: bachs,cli,local-testing,payments,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=12.0
+Description-Content-Type: text/markdown
+
+# bachs CLI
+
+Forward live webhook events to your local machine. No tunnel, no public URL, no
+third-party account.
+
+## Install
+
+```bash
+pip install bachs-cli
+# or, without installing:
+pipx run bachs-cli listen --forward-to localhost:3000/webhooks
+```
+
+## Use
+
+```bash
+bachs login --api-key sk_sandbox_...
+bachs listen --forward-to localhost:3000/webhooks
+```
+
+Every delivery prints as it arrives — event type, the status your handler
+returned, and how long it took:
+
+```
+Ready! Forwarding sandbox events to http://localhost:3000/webhooks
+Your webhook signing secret is whsec_a1b2c3... (^C to quit)
+Session whls_8f2e… · 26 event type(s)
+
+✓ collection.succeeded evt_3ab4e0d5 200 [42ms]
+✗ refund.paid          evt_7c1f22a9 500 [131ms]
+```
+
+Narrow it down:
+
+```bash
+bachs listen --forward-to localhost:3000/webhooks --events collection.succeeded,refund.paid
+```
+
+Redeliver something that already happened. This needs no session and no socket
+— it works against your registered endpoints too:
+
+```bash
+bachs events replay evt_3ab4e0d5d27445cf8a52ab3d8cb8f0b1
+```
+
+## How it works
+
+The connection is opened **outbound** from your machine, so nothing needs to
+reach you: no public URL, no inbound port, and it works behind NAT and
+corporate firewalls.
+
+Each session gets its **own signing secret**, printed when it starts. Payloads
+are genuinely signed with it, so your verification code is exercised for real —
+and your production endpoint's secret never leaves production.
+
+A session is a webhook destination like any other, so event filtering,
+delivery records and the dashboard all work the same way.
+
+## Environments
+
+The API key prefix picks the environment: `sk_sandbox_` for sandbox,
+`sk_live_` for production. There is no `--env` flag to get out of step with the
+key you are using.
+
+## Notes
+
+- Deliveries to a session are **not retried**. If your handler is down or your
+  laptop is asleep, the event is dropped and shown as failed — you are watching
+  the terminal, and a backlog arriving tomorrow would not help.
+- Credentials are stored at `~/.config/bachs/config.json`, mode 0600. Set
+  `BACHS_API_KEY` instead if you would rather not write a key to disk.

bachs_cli-0.1.0/README.md

@@ -0,0 +1,71 @@
+# bachs CLI
+
+Forward live webhook events to your local machine. No tunnel, no public URL, no
+third-party account.
+
+## Install
+
+```bash
+pip install bachs-cli
+# or, without installing:
+pipx run bachs-cli listen --forward-to localhost:3000/webhooks
+```
+
+## Use
+
+```bash
+bachs login --api-key sk_sandbox_...
+bachs listen --forward-to localhost:3000/webhooks
+```
+
+Every delivery prints as it arrives — event type, the status your handler
+returned, and how long it took:
+
+```
+Ready! Forwarding sandbox events to http://localhost:3000/webhooks
+Your webhook signing secret is whsec_a1b2c3... (^C to quit)
+Session whls_8f2e… · 26 event type(s)
+
+✓ collection.succeeded evt_3ab4e0d5 200 [42ms]
+✗ refund.paid          evt_7c1f22a9 500 [131ms]
+```
+
+Narrow it down:
+
+```bash
+bachs listen --forward-to localhost:3000/webhooks --events collection.succeeded,refund.paid
+```
+
+Redeliver something that already happened. This needs no session and no socket
+— it works against your registered endpoints too:
+
+```bash
+bachs events replay evt_3ab4e0d5d27445cf8a52ab3d8cb8f0b1
+```
+
+## How it works
+
+The connection is opened **outbound** from your machine, so nothing needs to
+reach you: no public URL, no inbound port, and it works behind NAT and
+corporate firewalls.
+
+Each session gets its **own signing secret**, printed when it starts. Payloads
+are genuinely signed with it, so your verification code is exercised for real —
+and your production endpoint's secret never leaves production.
+
+A session is a webhook destination like any other, so event filtering,
+delivery records and the dashboard all work the same way.
+
+## Environments
+
+The API key prefix picks the environment: `sk_sandbox_` for sandbox,
+`sk_live_` for production. There is no `--env` flag to get out of step with the
+key you are using.
+
+## Notes
+
+- Deliveries to a session are **not retried**. If your handler is down or your
+  laptop is asleep, the event is dropped and shown as failed — you are watching
+  the terminal, and a backlog arriving tomorrow would not help.
+- Credentials are stored at `~/.config/bachs/config.json`, mode 0600. Set
+  `BACHS_API_KEY` instead if you would rather not write a key to disk.

bachs_cli-0.1.0/bachs_cli/__init__.py

@@ -0,0 +1,3 @@
+"""The `bachs` CLI."""
+
+__version__ = "0.1.0"

bachs_cli-0.1.0/bachs_cli/config.py

@@ -0,0 +1,102 @@
+"""
+Credentials and environment for the CLI.
+
+The API key prefix already encodes the environment — `sk_sandbox_` against
+sandbox, `sk_live_` against production — so there is no separate `--env` flag
+to get out of step with the key being used. Passing a sandbox key and a
+production base URL is not a combination worth supporting.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+SANDBOX_BASE_URL = "https://sandbox-api.bachs.io"
+LIVE_BASE_URL = "https://api.bachs.io"
+
+CONFIG_DIR = Path(os.environ.get("BACHS_CONFIG_DIR", Path.home() / ".config" / "bachs"))
+CONFIG_PATH = CONFIG_DIR / "config.json"
+
+
+class ConfigError(Exception):
+    """Something is wrong with the stored or supplied credentials."""
+
+
+@dataclass
+class Config:
+    api_key: str
+    base_url: str
+
+    @property
+    def is_sandbox(self) -> bool:
+        return self.api_key.startswith("sk_sandbox_")
+
+    @property
+    def ws_url(self) -> str:
+        """The socket URL for this environment."""
+        return self.base_url.replace("https://", "wss://").replace(
+            "http://", "ws://"
+        ) + "/v1/webhooks/listen/connect"
+
+
+def _base_url_for(api_key: str) -> str:
+    if api_key.startswith("sk_sandbox_"):
+        return SANDBOX_BASE_URL
+    if api_key.startswith("sk_live_"):
+        return LIVE_BASE_URL
+    raise ConfigError(
+        "API key must start with sk_sandbox_ or sk_live_. "
+        "The prefix selects the environment."
+    )
+
+
+def save(api_key: str) -> Path:
+    """
+    Store the key for later commands.
+
+    Written 0600 in a 0700 directory. This is a plaintext secret on disk, which
+    is worth being explicit about: the OS keychain would be better, and the
+    cross-platform story for that is enough work to be its own change. Until
+    then the file permissions are the whole protection, so they are set
+    deliberately rather than left to the umask.
+    """
+    _base_url_for(api_key)  # reject a bad prefix before writing it
+
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    os.chmod(CONFIG_DIR, stat.S_IRWXU)
+
+    CONFIG_PATH.write_text(json.dumps({"api_key": api_key}, indent=2) + "\n")
+    os.chmod(CONFIG_PATH, stat.S_IRUSR | stat.S_IWUSR)
+    return CONFIG_PATH
+
+
+def load(api_key_override: Optional[str] = None) -> Config:
+    """
+    Resolve credentials: --api-key, then BACHS_API_KEY, then the config file.
+
+    The env var sits above the file so CI can run without writing one, and
+    below the flag so a one-off invocation can target another account.
+    """
+    api_key = api_key_override or os.environ.get("BACHS_API_KEY")
+
+    if not api_key:
+        if not CONFIG_PATH.exists():
+            raise ConfigError(
+                "No API key found. Run `bachs login --api-key sk_sandbox_...`, "
+                "set BACHS_API_KEY, or pass --api-key."
+            )
+        try:
+            api_key = json.loads(CONFIG_PATH.read_text()).get("api_key")
+        except (json.JSONDecodeError, OSError) as exc:
+            raise ConfigError(f"Could not read {CONFIG_PATH}: {exc}") from exc
+
+    if not api_key:
+        raise ConfigError(f"No api_key in {CONFIG_PATH}.")
+
+    base_url = os.environ.get("BACHS_BASE_URL") or _base_url_for(api_key)
+    return Config(api_key=api_key, base_url=base_url)

bachs_cli-0.1.0/bachs_cli/listen.py

@@ -0,0 +1,266 @@
+"""
+`bachs listen` — forward live events to a local port.
+
+The connection is opened OUTBOUND from this machine. That is what removes the
+need for a tunnel: no public URL, no inbound port, and it works behind NAT and
+corporate firewalls because it is an ordinary outgoing HTTPS connection.
+
+Shape of the loop: create a session over HTTP, dial the socket, and for each
+frame that arrives POST it to the local target and report the result back up
+the socket. Reconnect with backoff when the socket drops, because laptops
+sleep, wifi flaps, and the server cycles connections on deploy.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from typing import Optional
+
+import httpx
+import websockets
+
+from bachs_cli.config import Config
+
+# The server tells us how often to cycle; this is the fallback if it does not.
+DEFAULT_RECONNECT_SECONDS = 60
+
+# Reconnect backoff. Starts fast because most drops are transient (a deploy, a
+# brief network blip) and a developer watching a terminal should see it come
+# back immediately. Caps low enough that a laptop waking from sleep reconnects
+# within a few seconds rather than sitting idle.
+BACKOFF_INITIAL = 1.0
+BACKOFF_MAX = 15.0
+BACKOFF_FACTOR = 2.0
+
+
+class Colors:
+    GREEN = "\033[32m"
+    RED = "\033[31m"
+    YELLOW = "\033[33m"
+    DIM = "\033[2m"
+    BOLD = "\033[1m"
+    RESET = "\033[0m"
+
+
+def _status_colour(status: Optional[int]) -> str:
+    if status is None:
+        return Colors.RED
+    if 200 <= status < 300:
+        return Colors.GREEN
+    return Colors.RED
+
+
+def _normalise_target(forward_to: str) -> str:
+    """
+    Accept the shapes people actually type.
+
+    `localhost:3000/webhooks`, `:3000/webhooks` and a full URL should all work
+    — requiring a scheme for a local address is pointless friction.
+    """
+    target = forward_to.strip()
+    if target.startswith(("http://", "https://")):
+        return target
+    if target.startswith(":"):
+        return f"http://localhost{target}"
+    return f"http://{target}"
+
+
+async def _create_session(
+    config: Config,
+    *,
+    forward_to: str,
+    events: Optional[list[str]],
+    device_name: Optional[str],
+) -> dict:
+    async with httpx.AsyncClient(timeout=30) as client:
+        response = await client.post(
+            f"{config.base_url}/v1/webhooks/listen/sessions",
+            headers={"Authorization": f"Bearer {config.api_key}"},
+            json={
+                "device_name": device_name,
+                "forward_to": forward_to,
+                "events": events,
+            },
+        )
+
+    if response.status_code >= 400:
+        # Surface the server's message rather than a bare status: a bad event
+        # name or a key missing webhooks:write is worth reading.
+        try:
+            detail = response.json()
+        except Exception:
+            detail = response.text
+        raise RuntimeError(f"Could not create session ({response.status_code}): {detail}")
+
+    return response.json()
+
+
+async def _forward_one(
+    client: httpx.AsyncClient, target: str, frame: dict
+) -> tuple[Optional[int], float, Optional[str]]:
+    """
+    POST one event to the local handler.
+
+    Returns (status, duration_ms, error). The signature header is passed
+    through exactly as the server built it, so the developer's verification
+    code sees a real signed request.
+    """
+    headers = {
+        "Content-Type": "application/json",
+        "X-Bachs-Timestamp": str(frame.get("timestamp", "")),
+        "User-Agent": "Bachs-CLI-Listen/1.0",
+    }
+    signature = frame.get("signature")
+    if signature:
+        headers["X-Bachs-Signature-V2"] = signature
+
+    started = time.monotonic()
+    try:
+        response = await client.post(
+            target, content=frame.get("payload", ""), headers=headers
+        )
+        return response.status_code, (time.monotonic() - started) * 1000, None
+    except Exception as exc:
+        return None, (time.monotonic() - started) * 1000, str(exc)
+
+
+async def _run_socket(
+    config: Config, session: dict, target: str, *, cycle_after: float
+) -> None:
+    """
+    One connection's lifetime.
+
+    Returns normally when it is time to cycle the connection, which the caller
+    treats as an expected reconnect rather than a failure.
+    """
+    ws_url = f"{config.ws_url}?token={session['token']}"
+    deadline = time.monotonic() + cycle_after
+
+    async with websockets.connect(ws_url, open_timeout=20) as socket:
+        async with httpx.AsyncClient(timeout=30, follow_redirects=False) as http:
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    return
+
+                try:
+                    raw = await asyncio.wait_for(socket.recv(), timeout=remaining)
+                except asyncio.TimeoutError:
+                    return  # time to cycle
+
+                try:
+                    frame = json.loads(raw)
+                except json.JSONDecodeError:
+                    continue
+
+                kind = frame.get("type")
+                if kind == "ready":
+                    continue
+                if kind == "pong":
+                    continue
+                if kind != "webhook.forward":
+                    continue
+
+                status, duration_ms, error = await _forward_one(http, target, frame)
+
+                colour = _status_colour(status)
+                event_type = frame.get("event_type", "?")
+                event_id = frame.get("event_id", "?")
+                if error:
+                    print(
+                        f"{colour}✗{Colors.RESET} {event_type} "
+                        f"{Colors.DIM}{event_id}{Colors.RESET} "
+                        f"{colour}{error}{Colors.RESET} "
+                        f"{Colors.DIM}[{duration_ms:.0f}ms]{Colors.RESET}",
+                        flush=True,
+                    )
+                else:
+                    mark = "✓" if status and 200 <= status < 300 else "✗"
+                    print(
+                        f"{colour}{mark}{Colors.RESET} {event_type} "
+                        f"{Colors.DIM}{event_id}{Colors.RESET} "
+                        f"{colour}{status}{Colors.RESET} "
+                        f"{Colors.DIM}[{duration_ms:.0f}ms]{Colors.RESET}",
+                        flush=True,
+                    )
+
+                # Report back so the delivery shows up in the dashboard with
+                # what the local handler actually said.
+                try:
+                    await socket.send(
+                        json.dumps(
+                            {
+                                "type": "delivery_result",
+                                "event_id": event_id,
+                                "attempt_id": frame.get("attempt_id"),
+                                "status": status,
+                                "duration_ms": round(duration_ms, 2),
+                                "error": error,
+                            }
+                        )
+                    )
+                except Exception:
+                    # The socket is going away; the outer loop will reconnect.
+                    return
+
+
+async def listen(
+    config: Config,
+    *,
+    forward_to: str,
+    events: Optional[list[str]] = None,
+    device_name: Optional[str] = None,
+) -> int:
+    target = _normalise_target(forward_to)
+
+    session = await _create_session(
+        config, forward_to=forward_to, events=events, device_name=device_name
+    )
+    cycle_after = float(session.get("reconnect_after_seconds") or DEFAULT_RECONNECT_SECONDS)
+
+    env = "sandbox" if config.is_sandbox else f"{Colors.YELLOW}live{Colors.RESET}"
+    print(f"{Colors.BOLD}Ready!{Colors.RESET} Forwarding {env} events to {target}")
+    print(
+        f"Your webhook signing secret is "
+        f"{Colors.BOLD}{session['signing_secret']}{Colors.RESET} (^C to quit)"
+    )
+    subscribed = session.get("events") or []
+    print(
+        f"{Colors.DIM}Session {session['session_id']} · "
+        f"{len(subscribed)} event type(s){Colors.RESET}\n",
+        flush=True,
+    )
+
+    backoff = BACKOFF_INITIAL
+    try:
+        while True:
+            try:
+                await _run_socket(config, session, target, cycle_after=cycle_after)
+                backoff = BACKOFF_INITIAL  # a clean cycle is not a failure
+            except (OSError, websockets.WebSocketException) as exc:
+                print(
+                    f"{Colors.YELLOW}⟳{Colors.RESET} {Colors.DIM}connection lost "
+                    f"({exc}); reconnecting in {backoff:.0f}s{Colors.RESET}",
+                    flush=True,
+                )
+                await asyncio.sleep(backoff)
+                backoff = min(backoff * BACKOFF_FACTOR, BACKOFF_MAX)
+    except asyncio.CancelledError:
+        raise
+    finally:
+        # Release the session so fanout stops aiming at a socket nobody holds.
+        # Best effort: the server's reaper covers the case where this does not
+        # get to run.
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                await client.delete(
+                    f"{config.base_url}/v1/webhooks/listen/sessions/"
+                    f"{session['session_id']}",
+                    headers={"Authorization": f"Bearer {config.api_key}"},
+                )
+        except Exception:
+            pass
+
+    return 0

bachs_cli-0.1.0/bachs_cli/main.py

@@ -0,0 +1,252 @@
+"""
+`bachs` command-line interface.
+
+Command tree:
+
+    bachs login   --api-key sk_sandbox_...
+    bachs whoami
+    bachs listen  --forward-to localhost:3000/webhooks [--events a,b] [--all]
+    bachs events replay <evt_id> [--forward-to ...]
+
+A note on flag naming, because this is the point where it is cheap to get
+right. `--events` takes event type names and is the only way to select them;
+there is deliberately no parallel vocabulary for a second kind of event. Stripe
+added one (`--thin-events`, `--forward-thin-to`, `--forward-thin-connect-to`)
+and spent years unwinding it. If Bachs ever ships a second payload shape, it
+extends `--events`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from typing import Optional
+
+import httpx
+
+from bachs_cli import __version__
+from bachs_cli.config import ConfigError, load, save
+from bachs_cli.listen import Colors, listen
+
+
+_SUBCOMMANDS = {"login", "whoami", "listen", "events"}
+
+
+def _leading_api_key(argv: list[str]) -> Optional[str]:
+    """
+    Pull --api-key from the part of argv before the subcommand.
+
+    Scans only up to the first subcommand so `bachs events replay --api-key K`
+    is left to argparse rather than being read twice.
+    """
+    for index, token in enumerate(argv):
+        if token in _SUBCOMMANDS:
+            return None
+        if token == "--api-key" and index + 1 < len(argv):
+            return argv[index + 1]
+        if token.startswith("--api-key="):
+            return token.split("=", 1)[1]
+    return None
+
+
+def _split_events(value: Optional[str]) -> Optional[list[str]]:
+    if not value:
+        return None
+    items = [item.strip() for item in value.split(",") if item.strip()]
+    return items or None
+
+
+def _cmd_login(args: argparse.Namespace) -> int:
+    path = save(args.api_key)
+    env = "sandbox" if args.api_key.startswith("sk_sandbox_") else "live"
+    print(f"Saved {env} credentials to {path}")
+    if env == "live":
+        print(
+            f"{Colors.YELLOW}Note:{Colors.RESET} this is a live key. "
+            f"`bachs listen` will forward real events."
+        )
+    return 0
+
+
+def _cmd_whoami(args: argparse.Namespace) -> int:
+    config = load(args.api_key)
+    env = "sandbox" if config.is_sandbox else "live"
+    print(f"Environment: {env}")
+    print(f"API base:    {config.base_url}")
+    print(f"Key:         {config.api_key[:16]}…")
+    return 0
+
+
+def _cmd_listen(args: argparse.Namespace) -> int:
+    config = load(args.api_key)
+
+    if args.events and args.all:
+        # Silently preferring one would leave the developer wondering why a
+        # filter they passed did nothing.
+        print(
+            f"{Colors.RED}error:{Colors.RESET} pass either --events or --all, "
+            f"not both.",
+            file=sys.stderr,
+        )
+        return 2
+
+    events = None if args.all else _split_events(args.events)
+
+    try:
+        return asyncio.run(
+            listen(
+                config,
+                forward_to=args.forward_to,
+                events=events,
+                device_name=args.device_name,
+            )
+        )
+    except KeyboardInterrupt:
+        print("\nStopped.")
+        return 130
+
+
+def _cmd_events_replay(args: argparse.Namespace) -> int:
+    """
+    Redeliver a past event.
+
+    This is a plain API call — no socket and no session involved. It works
+    against registered endpoints too, which is why it is useful on its own and
+    not only alongside `listen`.
+    """
+    config = load(args.api_key)
+
+    response = httpx.post(
+        f"{config.base_url}/v1/webhooks/replay",
+        headers={"Authorization": f"Bearer {config.api_key}"},
+        json={"event_id": args.event_id},
+        timeout=30,
+    )
+
+    if response.status_code >= 400:
+        try:
+            detail = response.json()
+        except Exception:
+            detail = response.text
+        print(
+            f"{Colors.RED}error:{Colors.RESET} replay failed "
+            f"({response.status_code}): {detail}",
+            file=sys.stderr,
+        )
+        return 1
+
+    body = response.json()
+    print(
+        f"{Colors.GREEN}✓{Colors.RESET} queued {body.get('event_type')} "
+        f"{Colors.DIM}{body.get('event_id')}{Colors.RESET} "
+        f"attempt {body.get('attempt_id')}"
+    )
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="bachs", description="Bachs command-line interface"
+    )
+    parser.add_argument("--version", action="version", version=f"bachs {__version__}")
+    parser.add_argument(
+        "--api-key",
+        default=None,
+        help="Override the stored key. The prefix selects the environment.",
+    )
+
+    # --api-key is accepted both before and after the subcommand, because both
+    # read naturally and guessing wrong is a confusing "unrecognized arguments"
+    # error. A shared parent parser keeps one definition for both positions.
+    key_parent = argparse.ArgumentParser(add_help=False)
+    key_parent.add_argument(
+        "--api-key",
+        default=None,
+        dest="api_key",
+        help="Override the stored key. The prefix selects the environment.",
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_login = sub.add_parser("login", help="Store an API key")
+    p_login.add_argument("--api-key", required=True, dest="api_key")
+    p_login.set_defaults(func=_cmd_login)
+
+    p_whoami = sub.add_parser(
+        "whoami", parents=[key_parent], help="Show the active environment"
+    )
+    p_whoami.set_defaults(func=_cmd_whoami)
+
+    p_listen = sub.add_parser(
+        "listen",
+        parents=[key_parent],
+        help="Forward live events to a local port",
+    )
+    p_listen.add_argument(
+        "--forward-to",
+        "-f",
+        required=True,
+        help="Local target, e.g. localhost:3000/webhooks",
+    )
+    p_listen.add_argument(
+        "--events",
+        "-e",
+        default=None,
+        help="Comma-separated event types, e.g. collection.succeeded,refund.paid",
+    )
+    p_listen.add_argument(
+        "--all",
+        action="store_true",
+        help="Forward every event type. The default when --events is omitted.",
+    )
+    p_listen.add_argument(
+        "--device-name",
+        default=None,
+        help="Label for this session in the dashboard",
+    )
+    p_listen.set_defaults(func=_cmd_listen)
+
+    p_events = sub.add_parser("events", help="Work with past events")
+    events_sub = p_events.add_subparsers(dest="events_command", required=True)
+    p_replay = events_sub.add_parser(
+        "replay", parents=[key_parent], help="Redeliver a past event"
+    )
+    p_replay.add_argument("event_id", help="e.g. evt_3ab4e0d5d27445cf8a52ab3d8cb8f0b1")
+    p_replay.add_argument(
+        "--forward-to",
+        default=None,
+        help="Accepted for symmetry with `listen`; replay targets your "
+        "registered endpoints and any live session.",
+    )
+    p_replay.set_defaults(func=_cmd_events_replay)
+
+    return parser
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = build_parser()
+
+    # --api-key is defined on the top-level parser AND on the subcommands, so
+    # `bachs --api-key K whoami` and `bachs whoami --api-key K` both parse. The
+    # subcommand's parser writes to the same attribute though, so a subcommand
+    # with no value overwrites a leading one with None. Read the leading form
+    # off the raw argv first, and fall back to it.
+    leading_key = _leading_api_key(argv if argv is not None else sys.argv[1:])
+
+    args = parser.parse_args(argv)
+    if getattr(args, "api_key", None) is None and leading_key:
+        args.api_key = leading_key
+
+    try:
+        return args.func(args)
+    except ConfigError as exc:
+        print(f"{Colors.RED}error:{Colors.RESET} {exc}", file=sys.stderr)
+        return 2
+    except RuntimeError as exc:
+        print(f"{Colors.RED}error:{Colors.RESET} {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bachs_cli-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bachs-cli"
+version = "0.1.0"
+description = "Forward live Bachs webhook events to your local machine"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Bachs", email = "support@bachs.io" }]
+keywords = ["bachs", "webhooks", "payments", "cli", "local-testing"]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Internet :: WWW/HTTP",
+]
+
+# Kept deliberately small. This installs onto developer machines we do not
+# control, so every dependency is a chance to conflict with something already
+# in their environment. Both of these are pure-python and near-ubiquitous.
+dependencies = [
+    "httpx>=0.27",
+    "websockets>=12.0",
+]
+
+[project.urls]
+Homepage = "https://bachs.io"
+Documentation = "https://docs.bachs.io/developer-portal/local-testing"
+Changelog = "https://docs.bachs.io/changelog/api"
+
+# `bachs-cli` is the package; `bachs` is the command. That split is the
+# ecosystem convention (twilio/twilio-cli, aws/awscli) and it keeps the bare
+# `bachs` name on PyPI free for the SDK, which is what people expect to import.
+[project.scripts]
+bachs = "bachs_cli.main:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["bachs_cli"]
+
+[tool.hatch.build.targets.sdist]
+include = ["bachs_cli", "README.md"]