@revfleet/hscli 0.8.7 → 0.8.11

package/docs/COMMERCE_SETUP.md

@@ -0,0 +1,400 @@
+# Commerce Setup Guide
+
+> See also: [PORTAL_SETUP.md](PORTAL_SETUP.md) · [SALES_SETUP.md](SALES_SETUP.md) · [REPORTING_SETUP.md](REPORTING_SETUP.md)
+
+Complete configuration guide for HubSpot Commerce Hub settings. Covers products, payment processing, payment links, quotes, invoices, subscriptions, tax, and commerce automation.
+
+**Prerequisites:**
+- Portal authenticated (`hscli auth whoami`)
+- Private App scopes: `e-commerce`, `crm.objects.line_items.read/write`
+- HubSpot Payments enabled (US only) or Stripe integration connected
+
+---
+
+## 1. Products
+
+**Where:** Settings > Objects > Products
+
+### 1.1 Product Library
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Product name | Name of each product/service | Appears on quotes, invoices, payment links |
+| SKU | Stock keeping unit identifier | Internal tracking and reporting |
+| Unit price | Default selling price | Pre-populated on line items |
+| Description | Product description | Customer-facing on quotes/invoices |
+| Billing frequency | One-time, monthly, quarterly, annually | Revenue recognition and subscription handling |
+| Cost of goods sold | COGS per unit | Margin and profitability reporting |
+| Product image | Product photo/icon | Visual on quotes and payment links |
+
+**hscli:**
+```bash
+# List all products
+hscli crm products list --limit 50
+
+# Create a product
+hscli crm products create --data '{
+  "properties": {
+    "name": "Professional Plan",
+    "description": "Monthly professional subscription",
+    "price": "99.00",
+    "hs_sku": "PRO-001",
+    "hs_recurring_billing_period": "P1M",
+    "hs_cost_of_goods_sold": "20.00"
+  }
+}' --force
+
+# Update a product
+hscli crm products update <productId> --data '{
+  "properties": {
+    "price": "109.00"
+  }
+}' --force
+```
+
+### 1.2 Product Properties
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `name` | Text | Product name |
+| `price` | Currency | Unit price |
+| `hs_sku` | Text | SKU |
+| `description` | Text | Description |
+| `hs_recurring_billing_period` | Select | Billing frequency (P1M, P3M, P12M) |
+| `hs_cost_of_goods_sold` | Currency | COGS |
+| `hs_images` | Text | Image URL |
+| `tax` | Number | Tax rate (if applicable) |
+
+---
+
+## 2. Payment Processing
+
+**Where:** Settings > Commerce > Payments
+
+### 2.1 HubSpot Payments (US Only)
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Business verification | Legal entity name, EIN, address | Required for processing |
+| Bank account | Payout bank account | Where funds are deposited |
+| Statement descriptor | What appears on customer bank statements | Brand recognition on statements |
+| Payment methods | Credit card, ACH/bank transfer | Offer customer payment options |
+| Payout schedule | Daily, weekly, or monthly payouts | Cash flow management |
+
+### 2.2 Stripe Integration (Global)
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Stripe account | Connect existing Stripe account | Leverage existing payment infrastructure |
+| Sync settings | Products, customers, subscriptions | Keep HubSpot and Stripe in sync |
+| Webhook events | Payment success, failure, refund | Real-time status updates |
+
+### 2.3 Payment Methods
+
+| Method | Availability | Processing fee (typical) |
+|--------|-------------|------------------------|
+| Credit card | HubSpot Payments + Stripe | 2.9% + $0.30 |
+| Debit card | HubSpot Payments + Stripe | 2.9% + $0.30 |
+| ACH/Bank transfer | HubSpot Payments | 0.5% (cap $10) |
+| Wire transfer | Manual (outside HubSpot) | Varies |
+
+> **API:** Payment processing setup is UI-only. Payment events trigger CRM updates accessible via API.
+
+---
+
+## 3. Payment Links
+
+**Where:** Commerce > Payment Links
+
+### 3.1 Payment Link Configuration
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Link name | Internal name for the payment link | Organization and tracking |
+| Products | Select products from library | What the customer is buying |
+| Quantity | Fixed or customer-selectable | Flexibility for customers |
+| Discounts | Percentage or fixed amount | Promotions and special pricing |
+| Checkout page | Branding, custom fields | Professional checkout experience |
+| Redirect URL | Post-payment redirect page | Thank you page or onboarding |
+| Expiration | Optional expiry date | Time-limited offers |
+
+### 3.2 Checkout Customization
+
+| Element | Configuration |
+|---------|--------------|
+| Company logo | Brand logo on checkout page |
+| Colors | Match brand palette |
+| Custom fields | Additional info collection (company name, address, etc.) |
+| Terms & conditions | Link to terms page |
+| Billing address | Require billing address collection |
+| Shipping address | Require shipping address (physical products) |
+
+**hscli:**
+```bash
+# List payment links
+hscli commerce payment-links list --limit 20
+
+# Create a payment link
+hscli commerce payment-links create --data '{
+  "name": "Pro Plan Monthly",
+  "lineItems": [
+    {"productId": "<productId>", "quantity": 1}
+  ]
+}' --force
+```
+
+---
+
+## 4. Quotes (Commerce)
+
+**Where:** Settings > Objects > Quotes
+
+### 4.1 Quote Configuration
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Quote templates | Branded templates (logo, colors, layout) | Professional appearance |
+| Default expiration | Validity period (e.g., 30 days) | Urgency and expectation management |
+| E-signature | Enable native or integrated e-sign | Streamline deal closing |
+| Payment on quote | Enable payment collection | Combine quote + payment |
+| Countersignature | Internal approval before sending | Control on pricing/terms |
+| Snippet | Pre-built text blocks for quotes | Consistency and speed |
+| Quote numbering | Prefix and auto-increment | Professional tracking |
+
+### 4.2 Quote Workflow
+
+```
+Create Quote → Add Line Items → Apply Discounts → Add Terms
+    → Preview → Send for Signature → Collect Payment → Mark Won
+```
+
+### 4.3 Quote Approval Workflow
+
+| Condition | Action |
+|-----------|--------|
+| Discount > 20% | Require manager approval |
+| Deal amount > $50K | Require VP approval |
+| Non-standard terms | Require legal review |
+| Custom pricing | Require finance approval |
+
+---
+
+## 5. Invoices
+
+**Where:** Commerce > Invoices | Settings > Commerce > Invoices
+
+### 5.1 Invoice Settings
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Invoice template | Branded template (logo, colors) | Professional invoicing |
+| Invoice numbering | Prefix + auto-increment (e.g., INV-0001) | Accounting compliance |
+| Payment terms | Net 15, Net 30, Net 60, Due on receipt | Cash flow expectations |
+| Default currency | Primary currency | Multi-currency support |
+| Tax settings | Tax rates, tax IDs | Compliance |
+| Late payment terms | Late fee percentage or flat amount | Incentivize timely payment |
+| Remittance info | Bank details for wire transfer | Alternative payment method |
+| Notes | Default footer notes | Standard terms or thank-you |
+
+### 5.2 Invoice Automation
+
+| Trigger | Action | Purpose |
+|---------|--------|---------|
+| Invoice created | Send to customer via email | Prompt delivery |
+| Payment due in 7 days | Send reminder email | Proactive collection |
+| Invoice overdue | Send overdue notice | Collections process |
+| Invoice overdue > 30 days | Escalate to manager | Escalated collections |
+| Payment received | Send receipt, update deal | Confirmation and bookkeeping |
+
+**hscli:**
+```bash
+# List invoices
+hscli commerce invoices list --limit 20
+
+# Get invoice details
+hscli commerce invoices get <invoiceId>
+
+# Create an invoice
+hscli commerce invoices create --data '{
+  "properties": {
+    "hs_invoice_date": "2026-03-15",
+    "hs_due_date": "2026-04-14",
+    "hs_currency_code": "USD"
+  },
+  "associations": [
+    {"to": {"id": "<contactId>"}, "types": [{"associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 100}]}
+  ]
+}' --force
+```
+
+---
+
+## 6. Subscriptions
+
+**Where:** Commerce > Subscriptions
+
+### 6.1 Subscription Settings
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Billing frequency | Monthly, quarterly, annual | Recurring revenue cadence |
+| Auto-renewal | Enable/disable auto-renewal | Revenue continuity |
+| Cancellation policy | Immediate, end of period, with notice | Customer expectations |
+| Proration | Prorate upgrades/downgrades | Fair billing on plan changes |
+| Trial periods | Free trial duration (if applicable) | Customer acquisition |
+| Grace period | Days after failed payment before suspension | Reduce involuntary churn |
+
+### 6.2 Subscription Lifecycle
+
+```
+Trial (optional) → Active → Renewal
+    ↓                         ↓
+  Cancel              Payment Failed
+    ↓                         ↓
+  Expired            Retry (dunning)
+                              ↓
+                    Suspended → Canceled
+```
+
+### 6.3 Dunning Management (Failed Payments)
+
+| Attempt | Timing | Action |
+|---------|--------|--------|
+| 1st retry | 3 days after failure | Auto-retry payment |
+| 2nd retry | 5 days after failure | Auto-retry + email notification |
+| 3rd retry | 7 days after failure | Auto-retry + escalation email |
+| Final | 10 days after failure | Suspend subscription, notify customer |
+
+---
+
+## 7. Tax Configuration
+
+**Where:** Settings > Commerce > Tax
+
+### 7.1 Tax Settings
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Tax calculation | Automatic or manual | Compliance complexity |
+| Tax rates | Per product or per region | Correct tax collection |
+| Tax ID display | Show tax ID on invoices | B2B compliance |
+| Tax-exempt customers | Flag tax-exempt contacts/companies | Avoid over-charging |
+| Tax reporting | Integration with accounting software | Simplified tax filing |
+
+### 7.2 Tax by Region
+
+| Region | Tax type | Configuration |
+|--------|----------|--------------|
+| United States | Sales tax | State-by-state rates, nexus rules |
+| European Union | VAT | Country rates, reverse charge for B2B |
+| Canada | GST/HST/PST | Province-based |
+| Australia | GST | Flat 10% |
+| United Kingdom | VAT | Standard 20%, reduced rates |
+
+> **API:** Tax configuration is primarily UI-based. Tax amounts on line items are accessible via the API.
+
+---
+
+## 8. Commerce Automation
+
+**Where:** Automation > Workflows (commerce triggers)
+
+### 8.1 Payment Workflows
+
+| Trigger | Actions | Purpose |
+|---------|---------|---------|
+| Payment received | Send receipt email, update deal stage, create task | Post-payment processing |
+| Payment failed | Notify customer, create retry task, alert finance | Payment recovery |
+| Refund issued | Send confirmation, update deal, adjust revenue | Refund processing |
+| Subscription created | Welcome email, create onboarding ticket | Customer onboarding |
+| Subscription canceled | Exit survey, notify CSM, update lifecycle | Churn management |
+| Invoice overdue | Send reminders (3, 7, 14, 30 days) | Collections automation |
+
+### 8.2 Revenue Workflows
+
+| Trigger | Actions | Purpose |
+|---------|---------|---------|
+| MRR change | Update dashboards, notify finance | Revenue tracking |
+| Upgrade | Thank you email, update plan property | Expansion revenue |
+| Downgrade | Retention offer email, alert CSM | Churn prevention |
+| Renewal due in 30 days | Notify account manager, create renewal task | Proactive renewal |
+
+---
+
+## Setup Checklist
+
+### Products
+```
+[ ] Product library populated with all products/services
+[ ] Pricing configured (one-time and recurring)
+[ ] SKUs assigned
+[ ] Product descriptions written
+[ ] COGS entered (for margin reporting)
+[ ] Billing frequencies set for subscription products
+```
+
+### Payment Processing
+```
+[ ] HubSpot Payments verified OR Stripe connected
+[ ] Payout bank account configured
+[ ] Statement descriptor set
+[ ] Payment methods enabled (card, ACH)
+[ ] Test payment processed successfully
+```
+
+### Payment Links
+```
+[ ] At least one payment link created
+[ ] Checkout page branded (logo, colors)
+[ ] Redirect URL configured (thank you page)
+[ ] Custom fields added (if needed)
+[ ] Payment link tested end-to-end
+```
+
+### Quotes
+```
+[ ] Quote template branded
+[ ] Default expiration set
+[ ] E-signature enabled (if applicable)
+[ ] Payment on quotes enabled (if applicable)
+[ ] Approval workflows configured (discount thresholds)
+[ ] Quote numbering configured
+```
+
+### Invoices
+```
+[ ] Invoice template branded
+[ ] Invoice numbering configured
+[ ] Payment terms set (Net 30, etc.)
+[ ] Tax settings configured
+[ ] Reminder email automation set up
+[ ] Overdue notice automation set up
+```
+
+### Subscriptions
+```
+[ ] Billing frequencies defined per product
+[ ] Auto-renewal settings configured
+[ ] Cancellation policy defined
+[ ] Proration rules set
+[ ] Dunning management configured (retry schedule)
+[ ] Grace period set for failed payments
+```
+
+### Tax
+```
+[ ] Tax calculation method chosen (auto/manual)
+[ ] Tax rates configured per product or region
+[ ] Tax-exempt customers flagged
+[ ] Tax ID displayed on invoices (if B2B)
+```
+
+### Commerce Automation
+```
+[ ] Payment received workflow active
+[ ] Payment failed workflow active
+[ ] Invoice overdue reminder workflow active
+[ ] Subscription created onboarding workflow active
+[ ] Subscription canceled churn workflow active
+[ ] Renewal reminder workflow active
+```

package/docs/COMPARISON.md

@@ -0,0 +1,146 @@
+# hscli capability surface
+
+A factual inventory of what `hscli` exposes via its CLI and MCP server surface, and the HubSpot operations it covers. No comparisons, no marketing framing — just what's in the box.
+
+Last updated: 2026-04-22 (v0.8.0)
+
+## MCP tool surface
+
+`hscli mcp` exposes two tool families over stdio:
+
+### Native tool family (per-object)
+
+| Object | Tools |
+|---|---|
+| contacts, companies, deals, tickets, line items, products, quotes, invoices, orders, carts | `crm_<type>_list`, `_get`, `_search`, `_create`, `_update`, `_delete`, `_merge`, `_batch_read`, `_batch_upsert`, `_batch_archive` |
+| notes, calls, tasks, emails, meetings | Same 10 tools each |
+| custom objects | `crm_custom_schemas_{list,get,create,update}`, `crm_custom_records_{list,get,search,create,update,delete}` |
+| properties | `crm_properties_{list,get,create,update}`, `crm_property_groups_{list,create,update}` |
+| associations | `crm_associations_{list,create,remove}` |
+| pipelines | `crm_pipelines_{list,get,stages}` |
+| lists | `crm_lists_{list,get,create,update,delete,memberships}` |
+| imports | `crm_imports_{create,list,get,errors}` |
+| exports | `crm_exports_{create,list,get,status}` |
+| sequences | `sales_sequences_{list,get,enrollments}` |
+| reporting | `reporting_dashboards_{list,get}` |
+| raw | `hub_api_request` |
+
+### HubSpot Remote MCP compatibility family
+
+`hscli mcp` also registers the 11 tool names used by HubSpot's hosted Remote MCP server at `mcp.hubspot.com`. An agent built against the HubSpot Remote MCP can point at `hscli mcp` without modification:
+
+| Tool | Scope | Notes |
+|---|---|---|
+| `get_user_details` | Read | Returns portal / account info |
+| `search_crm_objects` | Read | filterGroups (max 5) + query + sorts + pagination |
+| `get_crm_objects` | Read | Batch read by ID, max 100/call |
+| `manage_crm_objects` | Write + **delete** | `operation: "create" \| "update" \| "delete"` — the `delete` operation is an hscli extension (HubSpot Remote MCP is create/update only) |
+| `search_properties` | Read | Keyword filter, max 5 keywords |
+| `get_properties` | Read | Full property definitions |
+| `search_owners` | Read | By email, by ID, or list |
+| `get_campaign_analytics` | Read | Per-campaign metrics |
+| `get_campaign_contacts_by_type` | Read | Paginated, with `attributionType` |
+| `get_campaign_asset_types` | Read | Supported asset types |
+| `get_campaign_asset_metrics` | Read | Per-asset metrics |
+
+### Extension tool family (hscli-only)
+
+Tools for surfaces not exposed by HubSpot's hosted Remote MCP:
+
+| Area | Tools |
+|---|---|
+| Workflows | `workflows_{list,get,enroll,unenroll}` |
+| Files | `files_{list,get,delete,signed_url}` |
+| Forms | `forms_{list,get,submissions,submit}` |
+| Webhooks | `webhooks_{list_subscriptions,create_subscription,delete_subscription}` |
+| Marketing emails | `marketing_emails_{list,get,statistics}` |
+| HubDB | `hubdb_{tables_list,rows_list,row_create,row_update,publish}` |
+| CMS URL redirects | `cms_redirects_{list,create,delete}` |
+| Conversations | `conversations_{inboxes_list,threads_list,messages_send}` |
+
+## CLI surface
+
+Every MCP tool has a matching CLI subcommand. Top-level command groups:
+
+```
+hscli auth               Token mgmt (login, logout, whoami, encrypt, decrypt)
+hscli crm                Full CRM surface (contacts, companies, deals, tickets,
+                         custom objects, properties, pipelines, associations,
+                         imports, exports, describe/validate, owners, etc.)
+hscli marketing          Emails, campaigns, ads, forms, landing pages,
+                         transactional, subscriptions, events, behavioral events
+hscli sales              Sequences, meetings, calling, scheduler, sales extensions
+hscli service            Conversations (threads, messages, inboxes, channels),
+                         feedback, chatflows, knowledge-base
+hscli cms                Blog posts + authors + tags, site pages, landing pages,
+                         HubDB (tables, rows, drafts, publishing), URL redirects,
+                         source-code, domains, SEO audit, site search, comments
+hscli workflows          v4 flows + legacy v2/v3 workflow enrollment
+hscli automation         Custom actions
+hscli files              File upload, list, delete, signed URLs
+hscli forms              Forms CRUD + submissions
+hscli webhooks           Subscription CRUD
+hscli settings           Users, teams, business units, currencies, GDPR,
+                         audit-logs, communication preferences (v3 + v4 batch)
+hscli account            Account info, audit-logs, private-apps, API usage
+hscli reporting          Analytics v2 reports/dashboards
+hscli exports            CRM exports
+hscli lists              Lists (v3) + folders + memberships
+hscli conversations      Threads, messages, inboxes, channels, custom-channels
+hscli api                Raw API request with scope allowlisting
+hscli doctor             Diagnostics + capability probing
+hscli policy             policy-as-code: list, show-matching, validate, templates
+hscli audit              Operational audit over trace JSONL files
+hscli trace              Session tracing + replay
+hscli seed               Generate test portal data (tier-aware)
+hscli mcp                Run MCP server over stdio
+```
+
+Legacy v1/v2 API support lives under `hscli contacts-v1`, `hscli companies-v2`, `hscli deals-v1`, `hscli owners-v2`, `hscli engagements-v1`, `hscli properties-legacy`, `hscli reports-v2`, `hscli calling-v1`, `hscli channels`, `hscli broadcast`, `hscli appinstalls`, `hscli marketing-emails-v1`.
+
+## HubSpot API coverage
+
+**Total endpoints covered:** 1,180 (verified against an automated scrape of HubSpot's developer documentation + live probe runs against multiple tier profiles).
+
+Whether an endpoint returns 2xx on a given portal depends on HubSpot's tier gates:
+
+| Portal tier | Reachable endpoints (read + write) |
+|---|---:|
+| Free | ~550 / 1180 (46.6%) |
+| Starter | ~640 / 1180 (54.2%) |
+| Professional | ~890 / 1180 (75.4%) |
+| Enterprise (all hubs) + Commerce + Ops | ~1140 / 1180 (96.6%) |
+
+Per-endpoint tier mapping: [docs/TIERS.md](TIERS.md).
+
+## Auth models
+
+| Method | Supported | Notes |
+|---|:---:|---|
+| HubSpot Private App token | ✅ | Primary. Scriptable / machine-to-machine / CI. |
+| OAuth authorization code | Partial | Available for developer apps via `hscli auth login --oauth` |
+| OAuth refresh-token rotation | ✅ | Persisted in `~/.revfleet/auth.json` (or encrypted `auth.enc`) |
+| Legacy `hapikey` | ❌ | Retired by HubSpot (June 2023) |
+
+## Safety model
+
+- **Mutations are blocked by default.** `--force` or `--dry-run` required; neither = preview only.
+- **Policy-as-code.** `--policy-file <path>` (or `HSCLI_POLICY_FILE`) evaluates rules with method + path globs, time windows (tz-aware), change-ticket requirements, approval gates. See [docs/POLICY_EXAMPLE.json](POLICY_EXAMPLE.json).
+- **Change tickets.** `--change-ticket <id>` required by policy for guarded writes; value is written to telemetry.
+- **Path scope allowlisting.** All requests must resolve to an approved HubSpot API path root; traversal is rejected.
+- **Idempotency keys.** Every write includes an `Idempotency-Key` header for replay-safe retries.
+- **Token redaction.** Bearer tokens, `token=`, `api_key=`, and `Authorization:` values are scrubbed from every output and error payload.
+- **Rate-limit awareness.** Reads HubSpot's `X-HubSpot-RateLimit-*` headers; proactive throttling + daily quota reset in the portal's declared timezone.
+- **Capability probing.** Endpoints are fingerprinted by `portalId + scopes`; `--strict-capabilities` fails fast on unsupported endpoints before issuing a network call.
+
+## Observability
+
+- **Trace.** `hscli trace start` writes every request to a JSONL file with method, path, status, latency, profile, MCP tool name (if applicable), optional request/response bodies. Session state lives at `~/.revfleet/trace-session.json`. See [docs/TUTORIALS/trace-replay-repro.md](TUTORIALS/trace-replay-repro.md).
+- **Audit.** `hscli audit {timeline,who,what,writes,by-tool}` aggregates trace JSONL into operational audit views (who did what when, which tool is buggy, which path had the most writes). See [docs/TUTORIALS/audit-portal-writes.md](TUTORIALS/audit-portal-writes.md).
+- **Replay.** `hscli trace replay <file>` re-issues GETs (writes are intentionally non-replayable).
+
+## Hosting / deployment
+
+- **Self-hosted.** `hscli` runs on your machine / CI runner / private infrastructure. No traffic transits third-party servers.
+- **Token sovereignty.** HubSpot tokens stay at rest in `~/.revfleet/auth.json` (mode 0600, dir mode 0700) or encrypted `auth.enc` when `HSCLI_VAULT_PASSPHRASE` is set.
+- **No telemetry phoning home.** Trace files are local-only; `hscli` ships no outbound telemetry.