agencycore-cli 0.1.0__tar.gz

agencycore_cli-0.1.0/.claude/rules/code-patterns.md

@@ -0,0 +1,43 @@
+---
+paths:
+  - "src/**/*.py"
+---
+
+# Code Patterns
+
+## Environment Selection
+- `ac login` defaults to staging (`STAGING_*` constants in `config.py`)
+- `ac login --dev` uses local dev (`DEV_*` constants in `config.py`)
+- Explicit `--api-url`, `--supabase-url`, `--supabase-anon-key` flags override environment defaults
+
+## Command Structure
+- Each command group is a `typer.Typer()` sub-app registered via `app.add_typer()` in `main.py`
+- CRM commands use `_api_request()` helper for HTTP calls with built-in error handling
+- Use `_build_body()` helper to construct request bodies from non-None fields (handles tags splitting)
+- IDs are positional `typer.Argument()`, optional fields are `typer.Option(None, ...)`
+- Tags: accept comma-separated string on CLI, `_build_body` splits to list automatically
+- Dates: ISO format strings (`2026-03-15`)
+
+## API Route Prefix
+- CRM routes use the `_CRM` constant from `crm/__init__.py` (currently `/api/v1/crm`)
+- Envoy routes use the `_ENVOY` constant from `envoy/__init__.py` (currently `/api/v1/envoy`)
+- Both domains share `_api_request()` and `_build_body()` from `crm/__init__.py`
+- Non-versioned routes (`/whoami`, `/health`) use root paths directly
+- No trailing slashes on API paths
+
+## Error Handling
+- `_api_request()` catches both `httpx.HTTPStatusError` (API errors) and `httpx.HTTPError` (connection errors)
+- `_handle_error()` extracts detail from API error responses and exits with code 1
+- Non-CRM/Envoy commands (auth, health) handle errors directly in the command function
+
+## Output
+- Rich output by default via `formatting.py` helpers (`print_table`, `print_detail`)
+- `--json` flag outputs raw JSON to stdout for piping/scripting
+- `--json` is a global option on both the `crm` and `envoy` app group callbacks, passed via `typer.Context`
+- Access in subcommands: add `ctx: typer.Context` parameter, read `ctx.obj["json"]`
+
+## Delete Commands
+- Always require `--yes` / `-y` flag or interactive `typer.confirm()` prompt
+
+## Create Commands
+- Fetch `organization_id` from `/whoami` before creating resources

agencycore_cli-0.1.0/.claude/rules/project-structure.md

@@ -0,0 +1,75 @@
+# Project Structure
+
+```
+ac-cli/
+├── src/ac_cli/
+│   ├── main.py              # Entry point, registers all sub-apps
+│   ├── client.py            # Authenticated httpx client from stored config
+│   ├── config.py            # Load/save ~/.agencycore/config.json, environment constants (STAGING_*, DEV_*)
+│   ├── formatting.py        # Shared output: print_table, print_detail, print_json
+│   └── commands/
+│       ├── auth.py           # login, logout, whoami
+│       ├── health.py         # health check (no auth)
+│       ├── crm/              # CRM subcommands (package)
+│       │   ├── __init__.py    # app, shared helpers (_CRM, _api_request, _build_body, _handle_error), search, dashboard
+│       │   ├── companies.py   # companies_app: list, get, create, update, delete
+│       │   ├── people.py      # people_app: list, get, create, update, delete
+│       │   ├── deals.py       # deals_app: list, get, create, update, move, order, delete
+│       │   ├── activities.py  # activities_app: list, get, create, update, complete, delete
+│       │   ├── communications.py  # communications_app: list, get, thread, unread, mark-read, delete, delete-thread, update, archive, unarchive, contact-by-email, resolve-contact, draft-email, generate-draft, unread-thread-ids
+│       │   ├── lists.py       # lists_app: list, get, create, update, members, add-member, remove-member, delete
+│       │   └── imports.py     # imports_app: preview, commit
+│       └── envoy/            # Envoy outreach subcommands (package)
+│           ├── __init__.py    # app, _ENVOY prefix, envoy_callback, registers sub-apps
+│           ├── sequences.py   # sequences_app: list, get, create, update, delete, launch, pause, resume
+│           ├── steps.py       # steps_app: create, update, delete, reorder, stats
+│           ├── recipients.py  # recipients_app: list, add, remove
+│           ├── outbox.py      # outbox_app: pending, sent, step-drafts, update-draft, approve, reject, regenerate
+│           └── dashboard.py   # dashboard_command (standalone command, not sub-app)
+├── tests/
+│   ├── conftest.py           # Shared fixtures (mock_api, mock_config, invoke)
+│   ├── test_formatting.py
+│   ├── test_crm_search.py
+│   ├── test_crm_companies.py
+│   ├── test_crm_people.py
+│   ├── test_crm_deals.py
+│   ├── test_crm_activities.py
+│   ├── test_crm_communications.py
+│   ├── test_crm_dashboard.py
+│   ├── test_crm_lists.py
+│   ├── test_crm_imports.py
+│   ├── test_envoy_sequences.py
+│   ├── test_envoy_steps.py
+│   ├── test_envoy_recipients.py
+│   ├── test_envoy_outbox.py
+│   ├── test_envoy_dashboard.py
+│   └── test_token_refresh.py
+├── pyproject.toml
+└── uv.lock
+```
+
+## Adding New CRM Subcommand Groups
+1. Create `src/ac_cli/commands/crm/<group>.py` with `<group>_app = typer.Typer(help="...")`
+2. Import shared helpers: `from ac_cli.commands.crm import _CRM, _api_request, _build_body`
+3. Add `ctx: typer.Context` as first parameter to commands that need `--json` output
+4. Use `_api_request("get", ...)` for API calls and `_build_body(...)` for request bodies
+5. Read JSON flag via `ctx.obj["json"]`
+6. Register in `crm/__init__.py`: import the app and call `app.add_typer(<group>_app, name="<group>")`
+
+## Adding Envoy Subcommand Groups
+1. Create `src/ac_cli/commands/envoy/<group>.py` with `<group>_app = typer.Typer(help="...")`
+2. Import shared helpers: `from ac_cli.commands.crm import _api_request, _build_body`
+3. Import envoy prefix: `from ac_cli.commands.envoy import _ENVOY`
+4. Add `ctx: typer.Context` as first parameter to commands that need `--json` output
+5. Read JSON flag via `ctx.obj["json"]`
+6. Register in `envoy/__init__.py`: import the app and call `app.add_typer(<group>_app, name="<group>")`
+
+## Adding Non-CRM/Envoy Command Groups
+1. Create `src/ac_cli/commands/<group>.py` (or package) with `app = typer.Typer(help="...")`
+2. Import and register in `main.py`: `app.add_typer(<group>.app, name="<group>")`
+
+## API Endpoints
+- CRM commands hit `/api/v1/crm/*` — the `_CRM` constant in `crm/__init__.py` holds this prefix
+- Envoy commands hit `/api/v1/envoy/*` — the `_ENVOY` constant in `envoy/__init__.py` holds this prefix
+- Both share `_api_request()` and `_build_body()` helpers from `crm/__init__.py`
+- The API base URL is stored in `~/.agencycore/config.json` (set during `ac login`). Environment constants live in `config.py`: `STAGING_*` (default) and `DEV_*` (used with `ac login --dev`).

agencycore_cli-0.1.0/.claude/rules/testing.md

@@ -0,0 +1,32 @@
+---
+paths:
+  - "tests/**/*.py"
+---
+
+# Testing
+
+## Stack
+- **pytest** for test runner
+- **respx** for mocking httpx requests (cleaner than pytest-httpx for sync client)
+- **typer.testing.CliRunner** for invoking CLI commands
+
+## Fixtures (in `tests/conftest.py`)
+- `cli_runner` — CliRunner instance
+- `mock_config` — patches `load_config()` to return valid auth config
+- `mock_api` — respx mock router intercepting httpx calls to API base URL
+- `invoke` — convenience function combining all three: `invoke(["crm", "companies", "list"])`
+
+## What to Test Per Command
+- **Happy path**: correct API call made, response rendered (table or JSON)
+- **`--json` flag**: output is valid JSON (parse with `json.loads`)
+- **Error handling**: API returns 404/422/500 → CLI prints error, exits code 1
+- **`--yes` on delete**: skips confirmation prompt
+- **Abort on delete**: `input="n\n"` → exits code 1
+
+## Running
+```bash
+uv run pytest                              # All tests (165 tests)
+uv run pytest tests/test_crm_deals.py      # Single CRM test file
+uv run pytest tests/test_envoy_outbox.py   # Single Envoy test file
+uv run pytest -k "test_companies"          # By name pattern
+```

agencycore_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --all-extras --python ${{ matrix.python-version }}
+      - name: Run tests
+        run: uv run pytest
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: test
+    environment:
+      name: pypi
+      url: https://pypi.org/p/agencycore-cli
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - name: Build package
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agencycore_cli-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/

agencycore_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,72 @@
+# ac-cli
+
+Python CLI for AgencyCore. Built with Typer + httpx + Rich + Supabase auth.
+
+## Setup
+
+```bash
+uv sync                    # Install all dependencies
+uv sync --all-extras       # Install with dev dependencies (pytest, respx)
+```
+
+## Commands
+
+```
+ac login / logout / whoami   # Auth commands
+ac health check              # API health (no auth)
+
+# CRM
+ac crm search <query>        # Search companies, contacts, deals
+ac crm companies list|get|create|update|delete
+ac crm people list|get|create|update|delete
+ac crm deals list|get|create|update|move|order|delete
+ac crm activities list|get|create|update|complete|delete
+ac crm comms list|get|thread|unread|mark-read|delete|delete-thread|update|archive|unarchive|contact-by-email|resolve-contact|draft-email|generate-draft|unread-thread-ids
+ac crm dashboard [--period N]
+ac crm lists list|get|create|update|members|add-member|remove-member|delete
+ac crm import preview|commit
+
+# Envoy (outreach)
+ac envoy sequences list|get|create|update|delete|launch|pause|resume
+ac envoy steps create|update|delete|reorder|stats
+ac envoy recipients list|add|remove
+ac envoy outbox pending|sent|step-drafts|update-draft|approve|reject|regenerate
+ac envoy dashboard
+```
+
+All CRM and Envoy commands support `--json` flag for scripting (set on `ac crm --json` or `ac envoy --json`). The flag is passed via `typer.Context`.
+
+## Running Checks
+
+```bash
+uv run pytest              # Run all tests (165 tests)
+uv run pytest tests/test_crm_companies.py -v  # Single test file
+uv run python -m ac_cli.main --help            # Verify CLI loads
+```
+
+## Dependency Management
+
+Uses **uv** for dependency management. Both `pyproject.toml` and `uv.lock` must stay in sync.
+
+```bash
+uv add <package>           # Add a dependency
+uv add --dev <package>     # Add a dev dependency
+uv lock                    # Regenerate lockfile after manual pyproject.toml edits
+```
+
+## Config
+
+Credentials stored in `~/.agencycore/config.json` (file mode 0600).
+
+### Environments
+
+`ac login` defaults to **staging**. Use `--dev` for local development:
+
+```bash
+ac login              # Staging (api.agencycore.dev)
+ac login --dev        # Local dev (localhost:8008 + local Supabase)
+```
+
+Environment constants (URLs, anon keys) are defined in `config.py`:
+- `STAGING_*` — staging API + Supabase
+- `DEV_*` — localhost API + local Supabase (`127.0.0.1:54321`)

agencycore_cli-0.1.0/LICENSE

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

agencycore_cli-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: agencycore-cli
+Version: 0.1.0
+Summary: AgencyCore CLI — manage your CRM, outreach, and more from the terminal
+Project-URL: Homepage, https://github.com/AlterityNetwork/ac-cli
+Project-URL: Repository, https://github.com/AlterityNetwork/ac-cli
+Project-URL: Issues, https://github.com/AlterityNetwork/ac-cli/issues
+Author-email: AlterityNetwork <dev@agencycore.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agencycore,cli,crm,pipeline,sales
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+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 :: Office/Business
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Requires-Dist: socksio>=1.0.0
+Requires-Dist: supabase>=2.0
+Requires-Dist: typer>=0.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgencyCore CLI
+
+Command-line interface for [AgencyCore](https://agencycore.dev) — manage your CRM, outreach sequences, and pipeline from the terminal.
+
+## Install
+
+```bash
+pip install agencycore-cli
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install agencycore-cli
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```bash
+# Log in (connects to AgencyCore staging by default)
+ac login
+
+# Use --dev for local development
+ac login --dev
+
+# Check your identity
+ac whoami
+
+# Check API health
+ac health check
+```
+
+## CRM Commands
+
+```bash
+# Companies
+ac crm companies list
+ac crm companies get <id>
+ac crm companies create --name "Acme Corp" --industry Technology
+
+# People (Contacts)
+ac crm people list
+ac crm people create --email jane@acme.com --full-name "Jane Smith"
+
+# Deals
+ac crm deals list
+ac crm deals create --name "Enterprise Deal" --stage qualified --amount 50000
+ac crm deals move <id> --stage negotiation
+
+# Activities
+ac crm activities list --status pending
+ac crm activities create --type call --title "Follow up" --due-date 2026-03-20
+
+# Communications
+ac crm comms unread
+ac crm comms draft-email --contact-id <id> --subject "Hello" --content "..."
+
+# Search & Dashboard
+ac crm search "acme"
+ac crm dashboard --period 30
+
+# Lists & Import
+ac crm lists list
+ac crm import preview --file contacts.json
+```
+
+## Envoy (Outreach)
+
+```bash
+ac envoy sequences list
+ac envoy outbox pending
+ac envoy dashboard
+```
+
+## Output Modes
+
+All commands support rich table output (default) or JSON for scripting:
+
+```bash
+ac crm deals list                          # Pretty tables
+ac crm --json deals list                   # Raw JSON
+ac crm --json deals list | jq '.[].name'   # Pipe to jq
+```
+
+## Development
+
+```bash
+git clone https://github.com/AlterityNetwork/ac-cli.git
+cd ac-cli
+uv sync --all-extras
+uv run pytest
+```
+
+## License
+
+MIT

agencycore_cli-0.1.0/README.md

@@ -0,0 +1,98 @@
+# AgencyCore CLI
+
+Command-line interface for [AgencyCore](https://agencycore.dev) — manage your CRM, outreach sequences, and pipeline from the terminal.
+
+## Install
+
+```bash
+pip install agencycore-cli
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install agencycore-cli
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```bash
+# Log in (connects to AgencyCore staging by default)
+ac login
+
+# Use --dev for local development
+ac login --dev
+
+# Check your identity
+ac whoami
+
+# Check API health
+ac health check
+```
+
+## CRM Commands
+
+```bash
+# Companies
+ac crm companies list
+ac crm companies get <id>
+ac crm companies create --name "Acme Corp" --industry Technology
+
+# People (Contacts)
+ac crm people list
+ac crm people create --email jane@acme.com --full-name "Jane Smith"
+
+# Deals
+ac crm deals list
+ac crm deals create --name "Enterprise Deal" --stage qualified --amount 50000
+ac crm deals move <id> --stage negotiation
+
+# Activities
+ac crm activities list --status pending
+ac crm activities create --type call --title "Follow up" --due-date 2026-03-20
+
+# Communications
+ac crm comms unread
+ac crm comms draft-email --contact-id <id> --subject "Hello" --content "..."
+
+# Search & Dashboard
+ac crm search "acme"
+ac crm dashboard --period 30
+
+# Lists & Import
+ac crm lists list
+ac crm import preview --file contacts.json
+```
+
+## Envoy (Outreach)
+
+```bash
+ac envoy sequences list
+ac envoy outbox pending
+ac envoy dashboard
+```
+
+## Output Modes
+
+All commands support rich table output (default) or JSON for scripting:
+
+```bash
+ac crm deals list                          # Pretty tables
+ac crm --json deals list                   # Raw JSON
+ac crm --json deals list | jq '.[].name'   # Pipe to jq
+```
+
+## Development
+
+```bash
+git clone https://github.com/AlterityNetwork/ac-cli.git
+cd ac-cli
+uv sync --all-extras
+uv run pytest
+```
+
+## License
+
+MIT

agencycore_cli-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agencycore-cli"
+version = "0.1.0"
+description = "AgencyCore CLI — manage your CRM, outreach, and more from the terminal"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "AlterityNetwork", email = "dev@agencycore.dev" },
+]
+keywords = ["crm", "cli", "agencycore", "sales", "pipeline"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "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 :: Office/Business",
+]
+dependencies = [
+    "typer>=0.9",
+    "httpx>=0.27",
+    "supabase>=2.0",
+    "rich>=13.0",
+    "socksio>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "respx>=0.22",
+]
+
+[project.urls]
+Homepage = "https://github.com/AlterityNetwork/ac-cli"
+Repository = "https://github.com/AlterityNetwork/ac-cli"
+Issues = "https://github.com/AlterityNetwork/ac-cli/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ac_cli"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[project.scripts]
+ac = "ac_cli.main:app"

agencycore_cli-0.1.0/src/ac_cli/client.py

@@ -0,0 +1,81 @@
+"""Authenticated httpx client for the AgencyCore API."""
+
+import httpx
+import typer
+
+from ac_cli.config import load_config, save_config
+
+
+def _refresh_access_token(cfg: dict) -> str:
+    """Use stored refresh_token to obtain a new access_token from Supabase.
+
+    Persists the new tokens to config. Returns the new access_token.
+    Raises typer.Exit on failure.
+    """
+    from supabase import create_client
+
+    supabase_url = cfg.get("supabase_url")
+    supabase_anon_key = cfg.get("supabase_anon_key")
+    refresh_token = cfg.get("refresh_token")
+
+    if not supabase_url or not supabase_anon_key or not refresh_token:
+        typer.echo("Session expired. Run `ac login` to re-authenticate.")
+        raise typer.Exit(code=1)
+
+    try:
+        sb = create_client(supabase_url, supabase_anon_key)
+        response = sb.auth.refresh_session(refresh_token)
+    except Exception as exc:
+        typer.echo(f"Token refresh failed: {exc}\nRun `ac login` to re-authenticate.")
+        raise typer.Exit(code=1) from exc
+
+    session = response.session
+    if not session:
+        typer.echo("Token refresh returned no session. Run `ac login` to re-authenticate.")
+        raise typer.Exit(code=1)
+
+    cfg["access_token"] = session.access_token
+    cfg["refresh_token"] = session.refresh_token
+    save_config(cfg)
+    return session.access_token
+
+
+class _AuthClient(httpx.Client):
+    """httpx.Client that auto-refreshes expired Supabase tokens on 401."""
+
+    def __init__(self, cfg: dict, **kwargs: object) -> None:
+        self._cfg = cfg
+        super().__init__(**kwargs)
+
+    def send(self, request: httpx.Request, **kwargs: object) -> httpx.Response:
+        response = super().send(request, **kwargs)
+
+        if response.status_code == 401:
+            new_token = _refresh_access_token(self._cfg)
+            request.headers["Authorization"] = f"Bearer {new_token}"
+            self.headers["Authorization"] = f"Bearer {new_token}"
+            response = super().send(request, **kwargs)
+
+        return response
+
+
+def get_api_client() -> httpx.Client:
+    """Return an httpx.Client with base URL and auth header from stored config.
+
+    The client auto-refreshes the Supabase access token on 401 responses.
+    Raises typer.Exit if not logged in.
+    """
+    cfg = load_config()
+    access_token = cfg.get("access_token")
+    api_url = cfg.get("api_url")
+
+    if not access_token or not api_url:
+        typer.echo("Not logged in. Run `ac login` first.")
+        raise typer.Exit(code=1)
+
+    return _AuthClient(
+        cfg=cfg,
+        base_url=api_url,
+        headers={"Authorization": f"Bearer {access_token}"},
+        timeout=30.0,
+    )