govinbox 0.1.0__tar.gz

govinbox-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: govinbox
+Version: 0.1.0
+Summary: GovInbox CLI: federal set-aside contract opportunities from your terminal or your AI agent
+Author: Artifex Innovations LLC
+License: Proprietary
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# govinbox CLI
+
+Federal set-aside contract opportunities from your terminal. Or your AI agent's terminal.
+
+The CLI is a thin wrapper over the versioned GovInbox REST API. All the logic lives on the server behind `/v1/`. This tool only builds requests and prints answers. It has zero dependencies beyond Python itself.
+
+## Install
+
+Coming soon: `pip install govinbox`. Until the first release, install straight from the repo:
+
+```bash
+pip install git+https://github.com/AUsernameForYou/setaside-radar.git#subdirectory=cli
+```
+
+Requires Python 3.10 or newer. That is the whole install. No API keys to configure by hand, no virtualenv dance.
+
+## Quickstart
+
+```bash
+govinbox login
+# paste your API token (from your trial confirmation email or account page)
+
+govinbox search --set-aside sdvosb --naics 5415 --limit 10
+
+govinbox opportunity <notice-id>
+
+govinbox digest
+```
+
+## Commands
+
+Every command takes `--json` for machine-readable output (agents, pipes, scripts). Without it you get readable tables.
+
+| Command | What it does |
+|---|---|
+| `govinbox login` | Save your API token on this machine (stored at `~/.config/govinbox/credentials`, readable only by you). The token is verified against the server; if it fails, nothing is kept. |
+| `govinbox logout` | Remove the saved token. |
+| `govinbox whoami` | Check the saved token is valid and show how many watchlists you have. |
+| `govinbox search` | Search opportunities. Filters: `--set-aside` (sdvosb, 8a, hubzone, wosb, veteran, indian, smallbiz), `--naics` (prefix like 5415), `--keyword`, `--agency` (e.g. "veterans affairs"), `--days` (default 7), `--limit` (default 25). |
+| `govinbox opportunity <id>` | Full details for one opportunity, including the SAM.gov link and early signals. |
+| `govinbox watchlists` | List your saved searches. |
+| `govinbox watchlist <id>` | Show one saved search. |
+| `govinbox digest [--watchlist <id>] [--days N]` | New matches for your watchlists, plain-English lines, newest first. |
+| `govinbox version` | CLI version, API endpoint, and server version. |
+
+Add `--debug` to any command to see full error details.
+
+## Examples
+
+```bash
+# SDVOSB IT opportunities posted in the last 3 days
+govinbox search --set-aside sdvosb --naics 5415 --days 3
+
+# Pipe titles into another tool (this is the agent pattern)
+govinbox search --keyword cybersecurity --json | jq -r '.items[].title'
+
+# Everything due within the week, as JSON
+govinbox search --limit 100 --json | jq '[.items[] | select(.days_left <= 7)]'
+
+# This morning's digest for one watchlist
+govinbox digest --watchlist abc123 --days 1
+
+# Full detail plus raw data for scripting
+govinbox opportunity abc123 --json > opp.json
+```
+
+## Auth
+
+`govinbox login` prompts for your API token and saves it to `~/.config/govinbox/credentials` with owner-only permissions (0600). Nothing is ever printed back.
+
+Two overrides, for CI and agents:
+
+- `GOVINBOX_API_TOKEN` environment variable: used instead of the saved token.
+- `GOVINBOX_API_URL` environment variable: point at a staging server instead of `https://api.getgovinbox.com`.
+
+If your token is rejected you will see:
+
+> Your API token was rejected. Run `govinbox login` to refresh your token.
+
+That is always the fix. If it keeps failing, check that you pasted the full token.
+
+## How versioning works
+
+The CLI never contains business logic, so it rarely needs to change. The API is versioned (`/v1/`), and every request sends an `X-GovInbox-CLI-Version` header identifying the client. The server does not act on the header today; it exists so the server can warn outdated clients in the future. `govinbox version` compares your CLI against the server's reported version.
+
+## Exit codes
+
+Scripts can rely on these:
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | General error (bad arguments from the server, network failure, unexpected error) |
+| 2 | Not logged in, or the token was rejected (`govinbox login` is the fix) |
+| 3 | Subscription lapsed (HTTP 402) |
+| 4 | Rate limited (HTTP 429; the message tells you when to retry) |
+| 5 | Not found (HTTP 404) |
+| 6 | Bad request (HTTP 400) |
+| 130 | Cancelled with Ctrl-C |
+
+Errors print one plain-English line to stderr and never a traceback, unless you pass `--debug`.

govinbox-0.1.0/README.md

@@ -0,0 +1,101 @@
+# govinbox CLI
+
+Federal set-aside contract opportunities from your terminal. Or your AI agent's terminal.
+
+The CLI is a thin wrapper over the versioned GovInbox REST API. All the logic lives on the server behind `/v1/`. This tool only builds requests and prints answers. It has zero dependencies beyond Python itself.
+
+## Install
+
+Coming soon: `pip install govinbox`. Until the first release, install straight from the repo:
+
+```bash
+pip install git+https://github.com/AUsernameForYou/setaside-radar.git#subdirectory=cli
+```
+
+Requires Python 3.10 or newer. That is the whole install. No API keys to configure by hand, no virtualenv dance.
+
+## Quickstart
+
+```bash
+govinbox login
+# paste your API token (from your trial confirmation email or account page)
+
+govinbox search --set-aside sdvosb --naics 5415 --limit 10
+
+govinbox opportunity <notice-id>
+
+govinbox digest
+```
+
+## Commands
+
+Every command takes `--json` for machine-readable output (agents, pipes, scripts). Without it you get readable tables.
+
+| Command | What it does |
+|---|---|
+| `govinbox login` | Save your API token on this machine (stored at `~/.config/govinbox/credentials`, readable only by you). The token is verified against the server; if it fails, nothing is kept. |
+| `govinbox logout` | Remove the saved token. |
+| `govinbox whoami` | Check the saved token is valid and show how many watchlists you have. |
+| `govinbox search` | Search opportunities. Filters: `--set-aside` (sdvosb, 8a, hubzone, wosb, veteran, indian, smallbiz), `--naics` (prefix like 5415), `--keyword`, `--agency` (e.g. "veterans affairs"), `--days` (default 7), `--limit` (default 25). |
+| `govinbox opportunity <id>` | Full details for one opportunity, including the SAM.gov link and early signals. |
+| `govinbox watchlists` | List your saved searches. |
+| `govinbox watchlist <id>` | Show one saved search. |
+| `govinbox digest [--watchlist <id>] [--days N]` | New matches for your watchlists, plain-English lines, newest first. |
+| `govinbox version` | CLI version, API endpoint, and server version. |
+
+Add `--debug` to any command to see full error details.
+
+## Examples
+
+```bash
+# SDVOSB IT opportunities posted in the last 3 days
+govinbox search --set-aside sdvosb --naics 5415 --days 3
+
+# Pipe titles into another tool (this is the agent pattern)
+govinbox search --keyword cybersecurity --json | jq -r '.items[].title'
+
+# Everything due within the week, as JSON
+govinbox search --limit 100 --json | jq '[.items[] | select(.days_left <= 7)]'
+
+# This morning's digest for one watchlist
+govinbox digest --watchlist abc123 --days 1
+
+# Full detail plus raw data for scripting
+govinbox opportunity abc123 --json > opp.json
+```
+
+## Auth
+
+`govinbox login` prompts for your API token and saves it to `~/.config/govinbox/credentials` with owner-only permissions (0600). Nothing is ever printed back.
+
+Two overrides, for CI and agents:
+
+- `GOVINBOX_API_TOKEN` environment variable: used instead of the saved token.
+- `GOVINBOX_API_URL` environment variable: point at a staging server instead of `https://api.getgovinbox.com`.
+
+If your token is rejected you will see:
+
+> Your API token was rejected. Run `govinbox login` to refresh your token.
+
+That is always the fix. If it keeps failing, check that you pasted the full token.
+
+## How versioning works
+
+The CLI never contains business logic, so it rarely needs to change. The API is versioned (`/v1/`), and every request sends an `X-GovInbox-CLI-Version` header identifying the client. The server does not act on the header today; it exists so the server can warn outdated clients in the future. `govinbox version` compares your CLI against the server's reported version.
+
+## Exit codes
+
+Scripts can rely on these:
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | General error (bad arguments from the server, network failure, unexpected error) |
+| 2 | Not logged in, or the token was rejected (`govinbox login` is the fix) |
+| 3 | Subscription lapsed (HTTP 402) |
+| 4 | Rate limited (HTTP 429; the message tells you when to retry) |
+| 5 | Not found (HTTP 404) |
+| 6 | Bad request (HTTP 400) |
+| 130 | Cancelled with Ctrl-C |
+
+Errors print one plain-English line to stderr and never a traceback, unless you pass `--debug`.

govinbox-0.1.0/govinbox/__init__.py

@@ -0,0 +1,8 @@
+"""GovInbox public CLI: thin wrapper over the versioned GovInbox REST API.
+
+All business logic lives server-side behind /v1/. This package only builds
+requests, sends them with the caller's API token, and pretty-prints responses.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

govinbox-0.1.0/govinbox/__main__.py

@@ -0,0 +1,6 @@
+"""Allows `python -m govinbox ...` as an alternative to the `govinbox` script."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

govinbox-0.1.0/govinbox/auth.py

@@ -0,0 +1,70 @@
+"""Token storage for the GovInbox CLI.
+
+The token lives in ~/.config/govinbox/credentials (mode 0600). A
+GOVINBOX_API_TOKEN environment variable overrides the file, which is handy
+for CI and for agents that inject secrets via the environment.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+
+CONFIG_DIR = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "govinbox"
+CREDENTIALS_FILE = CONFIG_DIR / "credentials"
+ENV_TOKEN = "GOVINBOX_API_TOKEN"
+
+
+def get_token() -> str | None:
+    """Return the stored token, or None when the user has not logged in."""
+    env = os.environ.get(ENV_TOKEN)
+    if env:
+        return env.strip() or None
+    try:
+        data = json.loads(CREDENTIALS_FILE.read_text())
+    except (FileNotFoundError, json.JSONDecodeError):
+        return None
+    token = data.get("token")
+    return token.strip() if token else None
+
+
+def token_source() -> str:
+    """Where the current token came from, for user-facing messages."""
+    if os.environ.get(ENV_TOKEN):
+        return f"environment variable {ENV_TOKEN}"
+    return str(CREDENTIALS_FILE)
+
+
+def save_token(token: str) -> Path:
+    """Persist the token with owner-only permissions. Returns the file path.
+
+    Uses os.open with mode 0600 so the file is never briefly world-readable
+    between creation and chmod.
+    """
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    fd = os.open(CREDENTIALS_FILE, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        os.write(fd, (json.dumps({"token": token.strip()}) + "\n").encode("utf-8"))
+    finally:
+        os.close(fd)
+    # Belt and suspenders: enforce 0600 even if the file already existed with
+    # wider permissions.
+    os.chmod(CREDENTIALS_FILE, stat.S_IRUSR | stat.S_IWUSR)
+    return CREDENTIALS_FILE
+
+
+def clear_token() -> bool:
+    """Remove the stored token. True when something was removed."""
+    try:
+        CREDENTIALS_FILE.unlink()
+        return True
+    except FileNotFoundError:
+        return False
+
+
+def mask(token: str) -> str:
+    """Last four characters, for confirming which token is in use."""
+    t = token.strip()
+    return "…" + t[-4:] if len(t) > 4 else "…"