@revfleet/hscli 0.8.7 → 0.8.11

package/docs/ROADMAP_PHASE1_TO_3.md

@@ -0,0 +1,96 @@
+# ROADMAP: Phase 1 to Phase 3
+
+> See also: [ARCHITECTURE.md](ARCHITECTURE.md) · [SAFETY_MODEL.md](SAFETY_MODEL.md) · [RELEASE_GOVERNANCE.md](RELEASE_GOVERNANCE.md) · [WHY_HOW_WHAT.md](WHY_HOW_WHAT.md)
+
+## Scope
+This roadmap defines execution from foundational CLI to production-ready HubSpot operations with strict safety and reliability gates.
+
+## Phase 1 (✅ Complete): Core CRM + Safety Baseline
+
+### Delivered
+- CRM object commands (contacts, companies, deals, tickets): list/get/search/create/update/delete/merge + batch operations
+- Pagination/filter flags baseline on object list/search commands
+- Properties commands: list/get/create/update with strict object-type allowlists
+- Associations commands: list/create/remove
+- Owners read command: list with pagination/filter flags
+- Pipelines read commands: list/get (strictly scoped to deals/tickets)
+- Custom object support: schema + record CRUD/search
+- Engagement support: notes, calls, tasks, emails, meetings
+- Incremental sync utility (`crm sync pull`)
+- Domain command groups: marketing, forms, files, cms, workflows, service
+- Raw API command (`api request`) for controlled endpoint coverage
+- Unified write safety middleware (`maybeWrite`):
+  - `--dry-run` previews writes
+  - `--force` required for live write execution
+- Policy middleware:
+  - `--policy-file` profile-based write/delete rules
+  - `--change-ticket` enforcement where required
+- JSON output consistency and redaction controls
+- Profile isolation support via `HSCLI_HOME` (environment-isolated auth store)
+- OAuth-oriented auth tooling (`oauth-url`, `oauth-exchange`, token introspection)
+- Request telemetry + correlation ID support
+- Zod response schema validation with graceful degradation (`HSCLI_STRICT_SCHEMAS=1` for strict mode)
+- ESLint with typescript-eslint (0 errors, integrated into `release:verify`)
+
+## Phase 2 (✅ Complete): Reliability and Operational Hardening
+
+### Delivered
+- Hublet-aware API routing for EU1/AP1 portals (`createClient(profile)`, `doctor hublet-check`)
+- Retry/backoff with exponential delay on 429 + 5xx (max 3 retries, Retry-After header respect)
+- Rate limit observation (rolling + daily quotas, pacing, daily exhaustion guard)
+- Idempotency keys auto-generated for all write operations
+- Encrypted token vault (AES-256-GCM, PBKDF2 600k iterations) — transparent via auth.ts
+  - `hscli auth encrypt` / `hscli auth decrypt` CLI commands
+  - `HSCLI_VAULT_PASSPHRASE` env var for automated workflows
+- Permission profiles (`hscli auth set-mode <profile> read-only|read-write`)
+  - Enforced at HTTP client level before any request
+- Hardened test matrix: 155 tests across 9 suites
+  - Unit: hublet detection, schemas, permissions, vault
+  - Bugfix regression: vault bypass, 404 remap, safeJson, sync state
+  - Integration: MCP tools (32 tests), CLI commands (34 tests)
+  - Contract: sandbox smoke tests (10, opt-in via `HSCLI_ENABLE_SANDBOX_CONTRACT=1`)
+- `npm audit` integrated into release:verify
+
+### Exit criteria status
+- ✅ Zero unredacted secret leak in logs/errors (redaction controls + vault)
+- ✅ Write-path controls enforced across all mutating endpoints (policy + permission profiles)
+- ⚠️ Stable e2e suite against HubSpot sandbox — tests exist but opt-in, not CI-automated yet
+- ⚠️ Domain coverage validated against production-safe contract suite — partial
+
+## Phase 3 (✅ Complete): Production Readiness + Distribution
+
+### Completed
+- Checksums via `npm run release:checksums`
+- `release:verify` pipeline: typecheck → lint → test → build → checksums
+- npm audit in release gates
+- CI/CD pipeline (GitHub Actions): lint + test + build on push/PR (Node 20+22 matrix)
+- Cookbook / examples documentation per command (`docs/COOKBOOK.md`)
+- Signed release artifacts + provenance attestation (GitHub Actions release workflow)
+- Supply-chain automation (Dependabot: npm weekly + GitHub Actions weekly)
+- P1/P2 bug fixes: vault bypass enforcement, 404 record-vs-endpoint disambiguation, safeJson body handling, sync cursor/mode isolation
+- Plugin/extension interface (`src/core/plugins.ts`, `docs/PLUGIN_GUIDE.md`)
+  - HSCLI_PLUGINS env var allowlist (default) + opt-in node_modules keyword auto-discovery via HSCLI_PLUGIN_AUTO_DISCOVER
+  - PluginContext exposes createClient, maybeWrite, printResult, CliError
+  - Safety gates (dry-run/force/policy) enforced for plugin writes
+- Operational playbooks for incident response (`docs/OPERATIONAL_PLAYBOOKS.md`)
+
+### Remaining
+- (none — Phase 3 complete)
+
+### Exit criteria
+- Reproducible build from clean checkout
+- CI green on every PR
+- Signed release + checksum published per version
+- Production launch checklist complete (security, reliability, observability)
+
+## Risk Register (Top Items)
+- Token leakage risk in logs/errors — **mitigated** (redaction + vault encryption)
+- Unsafe write execution without human confirmation — **mitigated** (--force gate + permission profiles)
+- Command drift from HubSpot API contracts — **mitigated** (Zod schema validation)
+- Dependency compromise in npm supply chain — **mitigated** (npm audit in CI + Dependabot weekly)
+
+## Execution Order
+1. ~~Finish Phase 1 gaps~~ ✅
+2. ~~Implement Phase 2 reliability hardening~~ ✅
+3. ~~Lock Phase 3 release and governance controls~~ ✅ (core items)
+4. ~~Operational playbooks + plugin interface~~ ✅

package/docs/SAFETY_MODEL.md

@@ -0,0 +1,40 @@
+# Safety model
+
+> See also: [ARCHITECTURE.md](ARCHITECTURE.md) · [COMMAND_COMPATIBILITY.md](COMMAND_COMPATIBILITY.md) · [TESTING_PLAN.md](TESTING_PLAN.md)
+
+## Principles
+1. **No silent mutation**: write commands require explicit invocation and can be simulated via `--dry-run`.
+2. **Deterministic output**: `--json` mode emits structured envelopes for CI/automation.
+3. **Least secret exposure**: tokens are profile-scoped in a local config file and never printed by default.
+4. **Policy-first execution**: optional policy file can deny writes/deletes or require change-ticket context.
+5. **Graceful API resilience**: timeout + retry skeleton handles transient failures and rate limits.
+
+## Dry-run Contract
+- Applies to all mutating commands routed through `maybeWrite`.
+- In dry-run mode, command returns:
+  - target endpoint
+  - method
+  - payload
+  - `dryRun: true`
+- No network mutation request is sent.
+
+## Rate Limit & Retry Baseline
+- Retry on: `429`, `5xx`, and network errors.
+- Honor `Retry-After` header when present.
+- Use capped exponential backoff.
+- Share observed HubSpot rate-limit state across clients in the same process by profile + API base URL.
+- Enforce HubSpot `X-HubSpot-RateLimit-Secondly`, rolling interval, and daily remaining headers before the next request.
+- Stop before daily quota exhaustion with `RATE_LIMIT_DAILY_EXHAUSTED`.
+- Enforce request timeout (`30s`) to prevent hung command invocations.
+- Surface retry exhaustion as `HTTP_RETRY_EXHAUSTED`.
+
+## Profiles & Access
+- Profiles isolate tokens per environment/workspace.
+- `--profile` allows explicit target account selection.
+- Missing token fails fast with guidance.
+
+## Safe Defaults
+- Default limit for list/search is conservative (`10`).
+- Explicit JSON payload required for create/update.
+- Unknown command errors are structured and non-destructive.
+- API paths are constrained to approved HubSpot scopes.

package/docs/SALES_SETUP.md

@@ -0,0 +1,369 @@
+# Sales Setup Guide
+
+> See also: [PORTAL_SETUP.md](PORTAL_SETUP.md) · [MARKETING_SETUP.md](MARKETING_SETUP.md) · [COMMERCE_SETUP.md](COMMERCE_SETUP.md) · [REPORTING_SETUP.md](REPORTING_SETUP.md)
+
+Complete configuration guide for HubSpot Sales Hub settings. Covers deals pipeline, quotes, meetings, sequences, playbooks, forecasting, and sales automation.
+
+**Prerequisites:**
+- Portal authenticated (`hscli auth whoami`)
+- Private App scopes: `crm.objects.deals.read/write`, `sales-email-read`, `crm.schemas.deals.read/write`
+- Users & Teams configured (see [PORTAL_SETUP.md](./PORTAL_SETUP.md))
+
+---
+
+## 1. Deals & Pipeline
+
+**Where:** Settings > Objects > Deals
+
+### 1.1 Pipeline Configuration
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Pipeline name | Name for each sales process (e.g., "New Business", "Renewals") | Separate pipelines for different sales motions |
+| Deal stages | Ordered stages with win probability % | Tracks deal progression, powers forecasting |
+| Stage probability | Win likelihood per stage (e.g., Discovery = 20%, Proposal = 60%) | Weighted pipeline value and forecasting |
+| Stage requirements | Required properties before moving to next stage | Data quality and process enforcement |
+| Multiple pipelines | Separate pipelines for different deal types | Each sales motion has unique stages |
+
+**hscli:**
+```bash
+# List all pipelines
+hscli crm pipelines list deals
+
+# Get pipeline details (stages, probabilities)
+hscli crm pipelines get deals <pipelineId>
+
+# Create a new pipeline
+hscli crm pipelines create deals --data '{
+  "label": "New Business",
+  "displayOrder": 0,
+  "stages": [
+    {"label": "Appointment Scheduled", "displayOrder": 0, "metadata": {"probability": "0.2"}},
+    {"label": "Qualified to Buy", "displayOrder": 1, "metadata": {"probability": "0.4"}},
+    {"label": "Presentation Scheduled", "displayOrder": 2, "metadata": {"probability": "0.6"}},
+    {"label": "Decision Maker Bought-In", "displayOrder": 3, "metadata": {"probability": "0.8"}},
+    {"label": "Contract Sent", "displayOrder": 4, "metadata": {"probability": "0.9"}},
+    {"label": "Closed Won", "displayOrder": 5, "metadata": {"probability": "1.0"}},
+    {"label": "Closed Lost", "displayOrder": 6, "metadata": {"probability": "0.0"}}
+  ]
+}' --force
+
+# Update a pipeline stage
+hscli crm pipelines stages update deals <pipelineId> <stageId> --data '{
+  "label": "Negotiation",
+  "metadata": {"probability": "0.85"}
+}' --force
+```
+
+### 1.2 Deal Properties
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `dealname` | Text | Deal name (auto or manual) |
+| `amount` | Currency | Deal value |
+| `closedate` | Date | Expected close date |
+| `dealstage` | Select | Current pipeline stage |
+| `pipeline` | Select | Which pipeline |
+| `hubspot_owner_id` | Owner | Assigned sales rep |
+| `deal_currency_code` | Select | Currency (if multi-currency enabled) |
+
+**hscli:**
+```bash
+# Create custom deal property
+hscli crm properties create deals --data '{
+  "name": "deal_source",
+  "label": "Deal Source",
+  "type": "enumeration",
+  "fieldType": "select",
+  "groupName": "dealinformation",
+  "options": [
+    {"label": "Inbound", "value": "inbound", "displayOrder": 0},
+    {"label": "Outbound", "value": "outbound", "displayOrder": 1},
+    {"label": "Partner Referral", "value": "partner", "displayOrder": 2},
+    {"label": "Event", "value": "event", "displayOrder": 3}
+  ]
+}' --force
+```
+
+### 1.3 Deal Automation
+
+**Where:** Settings > Objects > Deals > Pipelines > Automate tab
+
+| Trigger | Action | Example |
+|---------|--------|---------|
+| Deal enters stage | Create task | "Send proposal" task when deal enters Proposal stage |
+| Deal enters stage | Send notification | Alert manager when deal enters Negotiation |
+| Deal enters stage | Update property | Set close date to 30 days from now when qualified |
+| Deal won | Trigger workflow | Send welcome email, create onboarding ticket |
+| Deal lost | Trigger workflow | Add to re-engagement nurture |
+
+---
+
+## 2. Quotes
+
+**Where:** Settings > Objects > Quotes
+
+### 2.1 Quote Settings
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Quote template | Default template with branding | Professional-looking quotes |
+| Quote expiration | Default validity period (e.g., 30 days) | Creates urgency |
+| E-signature | Enable electronic signatures | Streamlines deal closing |
+| Payment collection | Collect payment via quote | Combines quote acceptance + payment |
+| Quote numbering | Auto-numbering prefix and sequence | Professional quote tracking |
+| Terms & conditions | Default legal terms on quotes | Legal compliance |
+| Countersignature | Require internal countersign | Approval process for large deals |
+
+**hscli:**
+```bash
+# List quotes
+hscli crm quotes list --limit 20
+
+# Get quote details
+hscli crm quotes get <quoteId>
+```
+
+---
+
+## 3. Products & Line Items
+
+**Where:** Settings > Objects > Products
+
+**hscli:**
+```bash
+# List products
+hscli crm products list --limit 50
+
+# Create a product
+hscli crm products create --data '{
+  "properties": {
+    "name": "Enterprise License",
+    "description": "Annual enterprise software license",
+    "price": "25000",
+    "hs_sku": "ENT-001",
+    "hs_recurring_billing_period": "P12M"
+  }
+}' --force
+
+# Create a line item (associated with a deal)
+hscli crm line-items create --data '{
+  "properties": {
+    "name": "Enterprise License",
+    "quantity": "1",
+    "price": "25000",
+    "hs_product_id": "<productId>"
+  }
+}' --force
+```
+
+---
+
+## 4. Meetings & Scheduling
+
+**Where:** Settings > Sales > Meetings
+
+### 4.1 Meeting Link Configuration
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Calendar connection | Google Calendar or Outlook 365 | Real-time availability sync |
+| Meeting link URL | Custom slug (e.g., `meetings.yourcompany.com/john`) | Clean booking links |
+| Duration options | 15, 30, 45, 60 min | Match meeting types to durations |
+| Availability window | Working hours + buffer time | Prevent back-to-back meetings |
+| Buffer time | Minutes before/after meetings | Prep time |
+| Minimum notice | Hours before a meeting can be booked | Prevent last-minute bookings |
+
+### 4.2 Meeting Types
+
+| Type | Configuration | Use case |
+|------|--------------|----------|
+| Personal | 1:1 with specific rep | Discovery calls, demos |
+| Team (round-robin) | Rotates among team members | Inbound lead distribution |
+| Group | Multiple reps on same call | Panel interviews, complex demos |
+
+---
+
+## 5. Sequences
+
+**Where:** Sales > Sequences | Settings > Sales > Sequences
+
+### 5.1 Sequence Settings
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Sending window | Days and hours when emails send | Respect business hours |
+| Throttle | Max enrollments per day per user | Avoid spam flags |
+| Unenroll triggers | Contact replies, books meeting, deal created | Stop when goal met |
+| Sender | Individual user's connected email | Sends from rep's email |
+
+### 5.2 Sequence Steps
+
+| Step type | Description | Timing |
+|-----------|-------------|--------|
+| Automated email | Sent automatically | Delay in days from previous step |
+| Manual email task | Task for rep to personalize | Appears in task queue |
+| Call task | Task to make a phone call | Appears in task queue |
+| LinkedIn task | Task for LinkedIn outreach | Manual execution |
+| General task | Any custom task | Flexible follow-up |
+
+---
+
+## 6. Playbooks
+
+**Where:** Sales > Playbooks (Sales Hub Professional+)
+
+| Type | Use case | Example |
+|------|----------|---------|
+| Discovery | First call qualification | BANT questions, pain points |
+| Demo | Product demonstration | Feature walkthrough |
+| Negotiation | Price/terms discussion | Discount authority, objections |
+| Onboarding | Post-sale kickoff | Implementation timeline |
+
+---
+
+## 7. Forecasting
+
+**Where:** Sales > Forecasting | Settings > Sales > Forecasting
+
+### 7.1 Forecast Settings
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Forecast period | Monthly or quarterly | Match your business cadence |
+| Pipeline(s) | Which pipelines to include | Scope of forecast |
+| Forecast categories | Pipeline, Best Case, Commit, Closed | Deal confidence classification |
+| Targets/quotas | Revenue targets per rep, team, period | Forecast vs. target comparison |
+
+### 7.2 Forecast Categories
+
+| Category | Definition |
+|----------|-----------|
+| Pipeline | In pipeline, not yet qualified |
+| Best Case | Could close if things go well |
+| Commit | High confidence, verbal commitment |
+| Closed | Won and signed |
+| Omit | Excluded from forecast |
+
+---
+
+## 8. Sales Automation & Workflows
+
+### 8.1 Common Sales Workflows
+
+| Trigger | Actions | Purpose |
+|---------|---------|---------|
+| New deal created | Assign owner, create tasks | New deal setup |
+| Deal stage change | Update properties, create tasks | Enforce process |
+| Deal idle > X days | Reminder + escalation | Prevent stagnation |
+| Deal amount > threshold | Require approval | Oversight on large deals |
+| Deal closed won | Onboarding ticket, welcome email | Handoff to CS |
+| Deal closed lost | Nurture sequence, log reason | Feedback + re-engagement |
+
+---
+
+## 9. Connected Email & Calling
+
+### 9.1 Email Integration
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Email provider | Gmail or Outlook 365 | Two-way email sync |
+| Log emails | Auto-log sent/received to CRM | Complete communication history |
+| Track opens/clicks | Enable tracking | Know when prospects engage |
+
+### 9.2 Calling
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Calling provider | HubSpot, Twilio, or third-party | Make calls from CRM |
+| Call recording | Enable/disable (check local laws) | Training, compliance |
+| Call outcomes | Connected, left voicemail, no answer | Track call effectiveness |
+
+---
+
+## 10. Documents & Templates
+
+### 10.1 Documents
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Document library | Upload sales collateral | Centralized content |
+| Tracking | Track views and time spent | Buyer engagement signals |
+| Require email | Require email before access | Identify viewers |
+
+### 10.2 Email Templates
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Template library | Pre-built email templates | Saves time, ensures quality |
+| Personalization tokens | Dynamic fields | Personalized at scale |
+| Folders | Organize by use case | Easy discovery |
+
+---
+
+## Setup Checklist
+
+### Deals & Pipeline
+```
+[ ] Primary pipeline created with stages and probabilities
+[ ] Stage requirements configured
+[ ] Deal automation rules set
+[ ] Custom deal properties created
+[ ] Additional pipelines created (if needed)
+```
+
+### Quotes
+```
+[ ] Quote template branded
+[ ] Default expiration set
+[ ] E-signature enabled
+[ ] Quote numbering configured
+```
+
+### Products
+```
+[ ] Product library populated
+[ ] Pricing and billing frequency set
+[ ] SKUs assigned
+```
+
+### Meetings
+```
+[ ] Calendar connected for all reps
+[ ] Meeting links configured per rep
+[ ] Round-robin team link set up
+[ ] Availability and buffer times configured
+```
+
+### Sequences
+```
+[ ] Sending windows configured
+[ ] Throttle limits set
+[ ] Unenroll triggers configured
+[ ] At least one sequence created
+```
+
+### Forecasting
+```
+[ ] Forecast period set
+[ ] Forecast categories defined
+[ ] Targets/quotas set per rep and team
+```
+
+### Sales Automation
+```
+[ ] New deal workflow created
+[ ] Deal stage automations configured
+[ ] Idle deal alerts set up
+[ ] Closed-won handoff workflow active
+[ ] Closed-lost feedback workflow active
+```
+
+### Email & Calling
+```
+[ ] All reps connected personal email
+[ ] Email tracking enabled
+[ ] Calling provider configured
+[ ] Call outcomes defined
+```