wealthbox-cli 1.0.2__tar.gz → 1.0.3__tar.gz

wealthbox_cli-1.0.3/.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install mkdocs-material
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

wealthbox_cli-1.0.3/.gitignore

@@ -0,0 +1,50 @@
+# Python bytecode
+__pycache__/
+*.py[codz]
+*$py.class
+*.so
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.installed.cfg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment / secrets
+.env
+.envrc
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+.pytype/
+
+# Linting
+.ruff_cache/
+
+# Editors / IDEs
+.idea/
+.vscode/
+
+# MkDocs build output
+site/
+
+# Project-specific
+dev/
+.claude/
+CLAUDE.md
+docs/superpowers/

wealthbox_cli-1.0.2/README.md → wealthbox_cli-1.0.3/PKG-INFO

@@ -1,16 +1,54 @@
-# Wealthbox CLI
+Metadata-Version: 2.4
+Name: wealthbox-cli
+Version: 1.0.3
+Summary: CLI and client library for the Wealthbox CRM API
+Project-URL: Homepage, https://github.com/massive-value/wealthbox-cli
+Project-URL: Documentation, https://massive-value.github.io/wealthbox-cli/
+Project-URL: Repository, https://github.com/massive-value/wealthbox-cli
+Project-URL: Issues, https://github.com/massive-value/wealthbox-cli/issues
+Project-URL: Changelog, https://github.com/massive-value/wealthbox-cli/blob/main/CHANGELOG.md
+Author: Kadin Bullock
+License: Apache-2.0
+License-File: LICENSE
+Keywords: api,cli,client-management,command-line,contacts,crm,financial-advisor,fintech,wealth-management,wealthbox
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: python-dotenv<2.0,>=1.0
+Requires-Dist: tabulate<1.0,>=0.9
+Requires-Dist: typer<1.0,>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Wealthbox CLI — Command-Line Client for the Wealthbox CRM API
 
 [![PyPI version](https://img.shields.io/pypi/v/wealthbox-cli)](https://pypi.org/project/wealthbox-cli/)
+[![Downloads](https://img.shields.io/pypi/dm/wealthbox-cli)](https://pypi.org/project/wealthbox-cli/)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 
-A command-line interface for interacting with the Wealthbox CRM API.
+**wealthbox-cli** (`wbox`) is a command-line tool and Python client library for the [Wealthbox CRM](https://www.wealthbox.com/) API. It gives financial advisors, developers, and RIA firms full CRUD access to contacts, tasks, events, notes, households, and more — directly from the terminal. Automate your CRM workflows, export data, and integrate Wealthbox into scripts and CI pipelines.
 
-This tool provides structured access to contacts, households, tasks,
-events, notes, users, categories, and more — directly from your
-terminal.
-
-Official API documentation: https://dev.wealthbox.com
+[Documentation](https://massive-value.github.io/wealthbox-cli/) | [PyPI](https://pypi.org/project/wealthbox-cli/) | [API Reference](https://dev.wealthbox.com)
 
 > **Disclaimer:** This is an unofficial, community-built tool. It is not affiliated with,
 > endorsed by, or supported by Wealthbox or its parent company. "Wealthbox" is a trademark
@@ -18,6 +56,16 @@ Official API documentation: https://dev.wealthbox.com
 
 ------------------------------------------------------------------------
 
+## Why Use wealthbox-cli?
+
+- **No coding required** — structured CLI flags replace raw JSON and cURL commands
+- **Automate CRM workflows** — script bulk updates, data exports, and scheduled tasks
+- **Multiple output formats** — pipe JSON, CSV, or TSV directly to files or other tools
+- **Built for financial advisors and developers** — covers contacts, households, tasks, events, notes, categories, and custom fields
+- **Open source** — Apache 2.0 licensed, community-driven, and extensible
+
+------------------------------------------------------------------------
+
 ## Features
 
 -   Full CRUD support for:
@@ -127,10 +175,10 @@ For the full command reference see [docs/cli-reference.md](docs/cli-reference.md
 For this workspace, the easiest entrypoint is:
 
 ```bash
-./run-wbox.sh me --format json
-./run-wbox.sh users list --format json
-./run-wbox.sh contacts list --per-page 1 --format json
-./run-wbox.sh contacts add person --first-name Jane --last-name Doe --format json
+scripts/run-wbox.sh me --format json
+scripts/run-wbox.sh users list --format json
+scripts/run-wbox.sh contacts list --per-page 1 --format json
+scripts/run-wbox.sh contacts add person --first-name Jane --last-name Doe --format json
 ```
 
 The wrapper:
@@ -140,7 +188,7 @@ The wrapper:
 
 ------------------------------------------------------------------------
 
-## Project Structure
+## Architecture and Project Structure
 
     src/
       wealthbox_tools/
@@ -149,6 +197,8 @@ The wrapper:
         models/     # Pydantic v2 models for input validation
     tests/          # pytest integration tests (respx mocks)
 
+Built with [Typer](https://typer.tiangolo.com/), [httpx](https://www.python-httpx.org/), and [Pydantic v2](https://docs.pydantic.dev/).
+
 **Client mixin pattern:** `WealthboxClient` inherits from resource mixins (`ContactsMixin`, `TasksMixin`, `EventsMixin`, etc.) plus `_WealthboxBase` (core HTTP, rate limiting, error handling). To add a new resource, create a mixin and register it in `client/__init__.py`.
 
 **Rate limiting:** Sliding-window (300 req / 5-min window); state persists across processes via `~/.wbox_rate_limit.json`. 429 responses trigger automatic retry.
@@ -180,7 +230,7 @@ git pull
 .venv/bin/pip install -e .
 
 # Run the read-only smoke test
-./smoke_test.sh
+scripts/smoke_test.sh
 ```
 
 Smoke test coverage:
@@ -197,6 +247,43 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor guide.
 
 ------------------------------------------------------------------------
 
+## Claude Code Skill
+
+A `/wealthbox-crm` skill is included for [Claude Code](https://claude.ai/download) users. It provides natural-language access to all `wbox` commands with progressive disclosure and optional firm-specific conventions.
+
+### Install the skill
+
+```bash
+# Copy the skill to your user-level Claude Code skills directory
+# macOS/Linux
+cp -r docs/skills/wealthbox-crm ~/.claude/skills/wealthbox-crm
+
+# Windows (PowerShell)
+Copy-Item -Recurse docs\skills\wealthbox-crm $env:USERPROFILE\.claude\skills\wealthbox-crm
+```
+
+### Usage
+
+In any Claude Code conversation:
+
+```
+/wealthbox-crm create a contact for Jane Doe, she's a new prospect
+/wealthbox-crm list my tasks due this week
+/wealthbox-crm add a note to contact 123 about today's meeting
+```
+
+### Firm-specific configuration (optional)
+
+To customize the skill for your firm's conventions:
+
+```bash
+cp ~/.claude/skills/wealthbox-crm/firm-config.example.md ~/.claude/skills/wealthbox-crm/firm-config.md
+```
+
+Edit `firm-config.md` with your firm's required fields, defaults, naming conventions, and multi-step workflows. See the example file for all available options.
+
+------------------------------------------------------------------------
+
 ## Troubleshooting
 
 **401 Unauthorized** — Check your API token.

wealthbox_cli-1.0.2/PKG-INFO → wealthbox_cli-1.0.3/README.md

@@ -1,47 +1,13 @@
-Metadata-Version: 2.4
-Name: wealthbox-cli
-Version: 1.0.2
-Summary: CLI and client library for the Wealthbox CRM API
-Project-URL: Homepage, https://github.com/massive-value/wealthbox-cli
-Project-URL: Issues, https://github.com/massive-value/wealthbox-cli/issues
-Project-URL: Repository, https://github.com/massive-value/wealthbox-cli
-Author: Kadin Bullock
-License: Apache-2.0
-License-File: LICENSE
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.11
-Requires-Dist: httpx<1.0,>=0.27
-Requires-Dist: pydantic<3.0,>=2.0
-Requires-Dist: python-dotenv<2.0,>=1.0
-Requires-Dist: tabulate<1.0,>=0.9
-Requires-Dist: typer<1.0,>=0.12
-Provides-Extra: dev
-Requires-Dist: mypy>=1.10; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: respx>=0.21; extra == 'dev'
-Requires-Dist: ruff>=0.4; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# Wealthbox CLI
+# Wealthbox CLI — Command-Line Client for the Wealthbox CRM API
 
 [![PyPI version](https://img.shields.io/pypi/v/wealthbox-cli)](https://pypi.org/project/wealthbox-cli/)
+[![Downloads](https://img.shields.io/pypi/dm/wealthbox-cli)](https://pypi.org/project/wealthbox-cli/)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 
-A command-line interface for interacting with the Wealthbox CRM API.
+**wealthbox-cli** (`wbox`) is a command-line tool and Python client library for the [Wealthbox CRM](https://www.wealthbox.com/) API. It gives financial advisors, developers, and RIA firms full CRUD access to contacts, tasks, events, notes, households, and more — directly from the terminal. Automate your CRM workflows, export data, and integrate Wealthbox into scripts and CI pipelines.
 
-This tool provides structured access to contacts, households, tasks,
-events, notes, users, categories, and more — directly from your
-terminal.
-
-Official API documentation: https://dev.wealthbox.com
+[Documentation](https://massive-value.github.io/wealthbox-cli/) | [PyPI](https://pypi.org/project/wealthbox-cli/) | [API Reference](https://dev.wealthbox.com)
 
 > **Disclaimer:** This is an unofficial, community-built tool. It is not affiliated with,
 > endorsed by, or supported by Wealthbox or its parent company. "Wealthbox" is a trademark
@@ -49,6 +15,16 @@ Official API documentation: https://dev.wealthbox.com
 
 ------------------------------------------------------------------------
 
+## Why Use wealthbox-cli?
+
+- **No coding required** — structured CLI flags replace raw JSON and cURL commands
+- **Automate CRM workflows** — script bulk updates, data exports, and scheduled tasks
+- **Multiple output formats** — pipe JSON, CSV, or TSV directly to files or other tools
+- **Built for financial advisors and developers** — covers contacts, households, tasks, events, notes, categories, and custom fields
+- **Open source** — Apache 2.0 licensed, community-driven, and extensible
+
+------------------------------------------------------------------------
+
 ## Features
 
 -   Full CRUD support for:
@@ -158,10 +134,10 @@ For the full command reference see [docs/cli-reference.md](docs/cli-reference.md
 For this workspace, the easiest entrypoint is:
 
 ```bash
-./run-wbox.sh me --format json
-./run-wbox.sh users list --format json
-./run-wbox.sh contacts list --per-page 1 --format json
-./run-wbox.sh contacts add person --first-name Jane --last-name Doe --format json
+scripts/run-wbox.sh me --format json
+scripts/run-wbox.sh users list --format json
+scripts/run-wbox.sh contacts list --per-page 1 --format json
+scripts/run-wbox.sh contacts add person --first-name Jane --last-name Doe --format json
 ```
 
 The wrapper:
@@ -171,7 +147,7 @@ The wrapper:
 
 ------------------------------------------------------------------------
 
-## Project Structure
+## Architecture and Project Structure
 
     src/
       wealthbox_tools/
@@ -180,6 +156,8 @@ The wrapper:
         models/     # Pydantic v2 models for input validation
     tests/          # pytest integration tests (respx mocks)
 
+Built with [Typer](https://typer.tiangolo.com/), [httpx](https://www.python-httpx.org/), and [Pydantic v2](https://docs.pydantic.dev/).
+
 **Client mixin pattern:** `WealthboxClient` inherits from resource mixins (`ContactsMixin`, `TasksMixin`, `EventsMixin`, etc.) plus `_WealthboxBase` (core HTTP, rate limiting, error handling). To add a new resource, create a mixin and register it in `client/__init__.py`.
 
 **Rate limiting:** Sliding-window (300 req / 5-min window); state persists across processes via `~/.wbox_rate_limit.json`. 429 responses trigger automatic retry.
@@ -211,7 +189,7 @@ git pull
 .venv/bin/pip install -e .
 
 # Run the read-only smoke test
-./smoke_test.sh
+scripts/smoke_test.sh
 ```
 
 Smoke test coverage:
@@ -228,6 +206,43 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor guide.
 
 ------------------------------------------------------------------------
 
+## Claude Code Skill
+
+A `/wealthbox-crm` skill is included for [Claude Code](https://claude.ai/download) users. It provides natural-language access to all `wbox` commands with progressive disclosure and optional firm-specific conventions.
+
+### Install the skill
+
+```bash
+# Copy the skill to your user-level Claude Code skills directory
+# macOS/Linux
+cp -r docs/skills/wealthbox-crm ~/.claude/skills/wealthbox-crm
+
+# Windows (PowerShell)
+Copy-Item -Recurse docs\skills\wealthbox-crm $env:USERPROFILE\.claude\skills\wealthbox-crm
+```
+
+### Usage
+
+In any Claude Code conversation:
+
+```
+/wealthbox-crm create a contact for Jane Doe, she's a new prospect
+/wealthbox-crm list my tasks due this week
+/wealthbox-crm add a note to contact 123 about today's meeting
+```
+
+### Firm-specific configuration (optional)
+
+To customize the skill for your firm's conventions:
+
+```bash
+cp ~/.claude/skills/wealthbox-crm/firm-config.example.md ~/.claude/skills/wealthbox-crm/firm-config.md
+```
+
+Edit `firm-config.md` with your firm's required fields, defaults, naming conventions, and multi-step workflows. See the example file for all available options.
+
+------------------------------------------------------------------------
+
 ## Troubleshooting
 
 **401 Unauthorized** — Check your API token.

wealthbox_cli-1.0.3/docs/changelog.md

@@ -0,0 +1,116 @@
+# Changelog
+
+All notable changes to **wealthbox-cli** are documented here.
+
+This project uses [Semantic Versioning](https://semver.org/).
+
+---
+
+## [1.0.2](https://github.com/massive-value/wealthbox-cli/releases/tag/v1.0.2) — 2026-03-30
+
+### Changed
+- Redesigned comment handling — comments are now embedded in `get` commands
+- Added ID shorthand for resource lookups
+
+---
+
+## [1.0.1](https://github.com/massive-value/wealthbox-cli/releases/tag/v1.0.1) — 2026-03-30
+
+### Changed
+- Updated README with API token instructions and config commands
+- Added deploy workflow documentation
+
+---
+
+## [1.0.0](https://github.com/massive-value/wealthbox-cli/releases/tag/v1.0.0) — 2026-03-29
+
+### Added
+- Full CRUD for contacts (person, household, organization, trust), tasks, events, and notes
+- Household member management (`add-member`, `remove-member`)
+- Read/list access for users, activity, `me`, and categories
+- Type-specific contact creation subcommands: `contacts add person|household|org|trust`
+- `--more-fields` escape hatch for uncommon JSON fields on contacts, tasks, projects, opportunities, and workflows
+- Multiple output formats: `json`, `table`, `csv`, `tsv` via `--format`
+- Nested field flattening for tabular output (linked_to, email_addresses, tags, etc.)
+- Client-side filtering for fields the API doesn't support server-side (e.g. `--assigned-to` on contacts)
+- Category and custom field lookups (resource-scoped and workspace-level)
+- Token management via `wbox config set-token|show|clear`
+- Authentication via `--token` flag, `WEALTHBOX_TOKEN` env var, config file, or `.env`
+- Sliding-window rate limiter (300 req / 5-min window) with automatic retry on 429
+- GitHub Actions CI (lint + test across Python 3.11, 3.12, 3.13)
+- PyPI publishing via trusted publishers (OIDC)
+
+---
+
+## [0.8.5](https://github.com/massive-value/wealthbox-cli/releases/tag/v0.8.5)
+
+### Changed
+- Standardized CLI help text across all commands
+
+---
+
+## [0.8.4](https://github.com/massive-value/wealthbox-cli/releases/tag/v0.8.4)
+
+### Added
+- PyPI badges and install instructions
+
+---
+
+## [0.8.0](https://github.com/massive-value/wealthbox-cli/releases/tag/v0.8.0)
+
+### Added
+- Events CRUD support
+- Notes CRUD support (create, read, update — delete not supported by API)
+
+---
+
+## [0.7.0](https://github.com/massive-value/wealthbox-cli/releases/tag/v0.7.0)
+
+### Added
+- Tasks CRUD support
+- Task categories
+
+---
+
+## [0.6.0](https://github.com/massive-value/wealthbox-cli/releases/tag/v0.6.0)
+
+### Added
+- Household member management commands
+
+---
+
+## [0.5.0](https://github.com/massive-value/wealthbox-cli/releases/tag/v0.5.0)
+
+### Added
+- Contact CRUD operations
+- Contact categories and metadata lookups
+
+---
+
+## [0.4.0](https://github.com/massive-value/wealthbox-cli/releases/tag/v0.4.0)
+
+### Added
+- Output format support (`--format json|table|csv|tsv`)
+
+---
+
+## [0.3.0](https://github.com/massive-value/wealthbox-cli/releases/tag/v0.3.0)
+
+### Added
+- User listing and `me` command
+- Activity feed with cursor-based pagination
+
+---
+
+## [0.2.0](https://github.com/massive-value/wealthbox-cli/releases/tag/v0.2.0)
+
+### Added
+- Rate limiting (sliding-window, 300 req / 5-min)
+- Token configuration (`--token`, env var, `.env`)
+
+---
+
+## [0.1.0](https://github.com/massive-value/wealthbox-cli/releases/tag/v0.1.0)
+
+### Added
+- Initial release — basic Wealthbox API client with CLI scaffolding

wealthbox_cli-1.0.3/docs/contributing.md

@@ -0,0 +1,95 @@
+# Contributing to Wealthbox CLI
+
+Thank you for your interest in contributing to **wealthbox-cli**!
+
+---
+
+## Development Setup
+
+```bash
+git clone https://github.com/massive-value/wealthbox-cli
+cd wealthbox-cli
+python -m venv .venv
+source .venv/bin/activate  # macOS/Linux
+# OR
+.venv\Scripts\activate     # Windows
+
+pip install -e ".[dev]"
+```
+
+Configure your Wealthbox API token:
+
+```bash
+wbox config set-token
+```
+
+---
+
+## Running Tests
+
+```bash
+pytest
+```
+
+Tests use [respx](https://lundberg.github.io/respx/) to mock HTTP at the transport layer — no real API calls are made.
+
+## Code Style
+
+```bash
+ruff check src/ tests/
+```
+
+- **ruff** for linting (E, F, I rules; 120-char line length)
+- **mypy** in strict mode
+
+---
+
+## Project Architecture
+
+Three layers under `src/wealthbox_tools/`:
+
+| Layer | Purpose |
+|-------|---------|
+| `cli/` | [Typer](https://typer.tiangolo.com/) commands — user-facing, delegates to client |
+| `client/` | Async HTTP client built from [httpx](https://www.python-httpx.org/) mixins |
+| `models/` | [Pydantic v2](https://docs.pydantic.dev/) models for input validation |
+
+`WealthboxClient` (in `client/__init__.py`) inherits from all resource mixins plus `_WealthboxBase` (core HTTP, rate limiting, error handling).
+
+---
+
+## Adding a New Resource
+
+1. Add Pydantic models to `models/<resource>.py` (CreateInput, UpdateInput, ListQuery)
+2. Add a client mixin to `client/<resource>.py` with async CRUD methods
+3. Register the mixin in `client/__init__.py`
+4. Add CLI commands to `cli/<resource>.py`
+5. Register the CLI sub-app in `cli/main.py`
+6. Add category types via `make_category_command()` if applicable
+7. Add tests in `tests/test_<resource>_create.py` and `tests/test_<resource>_update.py`
+
+---
+
+## CI
+
+Pull requests and pushes to `main` run GitHub Actions CI:
+
+- **Lint:** `ruff check src/ tests/`
+- **Test:** `pytest` across Python 3.11, 3.12, 3.13
+
+Both must pass before merging.
+
+---
+
+## Pull Requests
+
+- Keep PRs focused — one feature or fix per PR
+- All tests must pass
+- No ruff errors
+- Update the CLI reference docs if commands change
+
+---
+
+## Reporting Issues
+
+Open an issue at [github.com/massive-value/wealthbox-cli/issues](https://github.com/massive-value/wealthbox-cli/issues) with steps to reproduce, expected behavior, and actual behavior.