@revfleet/hscli 0.8.6 → 0.8.10

package/docs/OPERATIONAL_PLAYBOOKS.md

@@ -0,0 +1,322 @@
+# Operational Playbooks
+
+Incident response procedures for hscli operations.
+
+---
+
+## 1. Token Compromise
+
+**Severity:** Critical
+
+### Symptoms
+- Unexpected API activity on HubSpot portal (unknown writes, bulk deletes)
+- Token appears in logs, error messages, or third-party systems
+- HubSpot reports suspicious API usage via email
+
+### Diagnosis
+```bash
+# Check recent telemetry for unusual activity
+cat ~/.revfleet/telemetry.jsonl | grep '"method":"DELETE"' | tail -20
+
+# Check which profiles exist
+hscli auth profiles
+
+# Inspect token scopes
+hscli auth token-info --profile <profile>
+```
+
+### Immediate Response
+1. **Revoke the token** in HubSpot portal: Settings > Integrations > Private Apps > Revoke
+2. **Rotate credentials**: generate a new private app token with minimum necessary scopes
+3. **If vault was encrypted**: re-encrypt with a new passphrase
+   ```bash
+   export HSCLI_VAULT_PASSPHRASE="new-passphrase"
+   hscli auth decrypt   # with old passphrase
+   hscli auth login --token "pat-xxx-new-token"
+   hscli auth encrypt   # with new passphrase
+   ```
+4. **Audit recent actions** via HubSpot audit log (Settings > Account > Audit Logs)
+
+### Recovery
+```bash
+# Login with new token
+hscli auth login --token "pat-eu1-new-token" --profile production
+
+# Verify connectivity
+hscli crm contacts list --limit 1 --profile production
+
+# Lock to read-only while investigating
+hscli auth set-mode production read-only
+```
+
+### Prevention
+- Always use encrypted vault (`hscli auth encrypt`)
+- Never pass tokens as CLI arguments in shared environments — use `--token-stdin`
+- Set profiles to `read-only` by default; switch to `read-write` only when needed
+- Review `HSCLI_TELEMETRY_FILE` logs regularly
+
+---
+
+## 2. Rate Limit Exhaustion
+
+**Severity:** High
+
+### Symptoms
+- `RATE_LIMIT_DAILY_EXHAUSTED` error
+- `HTTP_RETRY_EXHAUSTED` after 429 responses
+- Increasingly long pauses between API calls (pacing)
+
+### Diagnosis
+```bash
+# Check telemetry for 429 responses
+cat ~/.revfleet/telemetry.jsonl | grep '"status":429' | wc -l
+
+# Check current rate limit state via a simple request
+hscli crm contacts list --limit 1 --telemetry-file /tmp/ratelimit-check.jsonl
+cat /tmp/ratelimit-check.jsonl
+```
+
+### Mitigation
+1. **Stop batch operations** immediately
+2. **Wait for reset**: daily quota resets at UTC midnight
+3. **Reduce batch sizes**: use `--limit 10` instead of `--limit 100`
+4. **Space out requests**: add delays between sync pull runs
+
+```bash
+# Small incremental sync instead of bulk
+hscli crm sync pull contacts --limit 10 --max-pages 1
+
+# Check if quota has recovered
+hscli crm contacts list --limit 1
+```
+
+### Prevention
+- Use `--telemetry-file` to monitor API usage patterns
+- Run batch operations during off-peak hours
+- Set `--max-pages` limits on sync operations
+- Use `--limit` to control page sizes
+
+---
+
+## 3. Vault Passphrase Loss
+
+**Severity:** High
+
+### Symptoms
+- `VAULT_PASSPHRASE_REQUIRED` error on any command
+- Cannot read or write auth profiles
+
+### Diagnosis
+```bash
+# Confirm vault is encrypted
+ls -la ~/.revfleet/auth.enc
+
+# Check if plain auth.json exists as backup
+ls -la ~/.revfleet/auth.json
+```
+
+### Recovery
+
+**If `auth.json` backup exists:**
+```bash
+# Remove encrypted vault, use plain file
+rm ~/.revfleet/auth.enc
+# Verify access
+hscli auth profiles
+# Re-encrypt with new passphrase
+export HSCLI_VAULT_PASSPHRASE="new-passphrase"
+hscli auth encrypt
+```
+
+**If no backup exists:**
+```bash
+# Remove encrypted vault
+rm ~/.revfleet/auth.enc
+# Re-authenticate with each profile
+hscli auth login --token "pat-xxx-token" --profile default
+hscli auth login --token "pat-xxx-other" --profile staging
+# Re-encrypt
+export HSCLI_VAULT_PASSPHRASE="new-passphrase"
+hscli auth encrypt
+```
+
+### Prevention
+- Store vault passphrase in a password manager (1Password, Bitwarden)
+- For CI: store in encrypted secrets (GitHub Secrets, Vault)
+- Keep a secure backup of `auth.json` before encrypting
+
+---
+
+## 4. API Contract Drift
+
+**Severity:** Medium
+
+### Symptoms
+- Console warnings: `Schema validation warning: ...`
+- With `HSCLI_STRICT_SCHEMAS=1`: `SCHEMA_VALIDATION_ERROR` errors
+- Unexpected response shapes or missing fields
+
+### Diagnosis
+```bash
+# Enable strict mode to surface all validation failures
+HSCLI_STRICT_SCHEMAS=1 hscli crm contacts list --limit 1
+
+# Check HubSpot API changelog
+# https://developers.hubspot.com/changelog
+
+# Test specific endpoints
+hscli api request --method GET --path "/crm/v3/objects/contacts?limit=1" --json
+```
+
+### Mitigation
+1. **Non-strict mode (default)**: warnings are logged but commands continue working
+2. **Update schemas**: modify `src/core/schemas.ts` to match new API shapes
+3. **Use passthrough**: all schemas use `.passthrough()` so extra fields are preserved
+
+### Escalation
+- File an issue with the exact response shape and expected schema
+- Check HubSpot developer forum for known API changes
+- Temporarily disable strict mode: `unset HSCLI_STRICT_SCHEMAS`
+
+---
+
+## 5. Capability/Tier Mismatch
+
+**Severity:** Medium
+
+### Symptoms
+- `ENDPOINT_NOT_AVAILABLE` error
+- `CAPABILITY_UNSUPPORTED` error
+- `CAPABILITY_SCOPE_MISSING` in strict mode
+
+### Diagnosis
+```bash
+# Check what capabilities are available
+hscli doctor capabilities --refresh --json
+
+# Check token scopes
+hscli auth token-info
+
+# Test the specific endpoint directly
+hscli api request --method GET --path "/marketing/v3/emails?limit=1"
+```
+
+### Resolution
+1. **Missing scopes**: create a new private app with required scopes in HubSpot
+2. **Tier limitation**: upgrade HubSpot plan (e.g., Marketing Hub for email API)
+3. **Use fallback**: the error message includes a fallback command
+4. **Clear stale cache**:
+   ```bash
+   rm ~/.revfleet/capabilities.json
+   hscli doctor capabilities --refresh
+   ```
+
+---
+
+## 6. EU1/Hublet Routing Errors
+
+**Severity:** High
+
+### Symptoms
+- 401/403 errors on EU1 portal despite valid token
+- Data from wrong portal (NA data instead of EU)
+- `doctor hublet-check` reports mismatches
+
+### Diagnosis
+```bash
+# Run hublet consistency check
+hscli doctor hublet-check --json
+
+# Verify profile configuration
+hscli auth profile-show --profile default
+```
+
+### Resolution
+```bash
+# Re-login — hublet auto-detected from token prefix
+hscli auth login --token "pat-eu1-your-token"
+
+# Verify routing
+hscli doctor hublet-check
+# Should show: hublet=eu1, apiDomain=api-eu1.hubapi.com
+
+# If using HubSpot's official @hubspot/cli too, ensure its ~/.hscli.config.yml has env: eu1
+```
+
+### Prevention
+- Always use `pat-eu1-*` tokens for EU1 portals
+- Run `hscli doctor hublet-check` after initial setup
+- Check `apiDomain` in profile: `hscli auth profile-show`
+
+---
+
+## 7. Permission Profile Lockout
+
+**Severity:** Low
+
+### Symptoms
+- `PERMISSION_DENIED` error: "Profile 'X' is configured as read-only"
+- Write operations fail despite `--force`
+
+### Diagnosis
+```bash
+# Check current mode
+hscli auth profile-show --profile <name>
+# Look for: "mode": "read-only"
+```
+
+### Recovery
+```bash
+# Switch back to read-write
+hscli auth set-mode <profile> read-write
+
+# Verify
+hscli --force crm contacts create --data '{"properties":{"email":"test@example.com"}}' --dry-run
+```
+
+### Audit
+- Check who changed the mode and when (git log if config is versioned)
+- Consider if read-only was set intentionally for safety
+
+---
+
+## 8. Rollback Procedure
+
+**Severity:** Varies
+
+### When to Rollback
+- New version introduces breaking changes
+- Plugin causes unexpected behavior
+- Build artifacts are corrupted
+
+### Steps
+```bash
+# Check recent commits
+git log --oneline -10
+
+# Rollback to previous known-good commit
+git checkout <commit-hash>
+
+# Rebuild
+npm ci && npm run build
+
+# Verify
+npm test
+hscli crm contacts list --limit 1
+```
+
+### Post-Rollback
+1. Verify all tests pass: `npm test`
+2. Verify auth still works: `hscli auth profiles`
+3. Check MCP server if used: verify `.mcp.json` points to correct `dist/cli.js`
+4. Document the rollback reason for post-mortem
+
+---
+
+## General Escalation Path
+
+1. **Check docs**: `docs/COOKBOOK.md`, `docs/PLUGIN_GUIDE.md`
+2. **Check diagnostics**: `hscli doctor hublet-check`, `hscli doctor capabilities --refresh`
+3. **Enable telemetry**: `--telemetry-file /tmp/debug.jsonl`
+4. **Enable strict mode**: `HSCLI_STRICT_SCHEMAS=1 HSCLI_STRICT_CAPABILITIES=1`
+5. **File issue**: include error code, redacted command, and telemetry output

package/docs/OPERATIONS_SETUP.md

@@ -0,0 +1,362 @@
+# Operations Setup Guide
+
+> See also: [PORTAL_SETUP.md](PORTAL_SETUP.md) · [REPORTING_SETUP.md](REPORTING_SETUP.md) · [INTEGRATIONS_NOTIFICATIONS_SETUP.md](INTEGRATIONS_NOTIFICATIONS_SETUP.md)
+
+Complete configuration guide for HubSpot Operations Hub settings. Covers data sync, data quality, workflows, datasets, custom properties, and data management.
+
+**Prerequisites:**
+- Portal authenticated (`hscli auth whoami`)
+- Private App scopes: `crm.objects.contacts.read/write`, `crm.schemas.contacts.read`
+- Operations Hub license (Starter/Professional/Enterprise for advanced features)
+
+---
+
+## 1. Data Sync
+
+**Where:** Settings > Integrations > Data Sync (or Connected Apps)
+
+### 1.1 Two-Way Sync Configuration
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Connected app | Select third-party app to sync | Bidirectional data flow |
+| Sync direction | Two-way, HubSpot → app, or app → HubSpot | Controls data flow direction |
+| Object mapping | Map HubSpot objects to app objects | Correct data alignment |
+| Field mapping | Map HubSpot properties to app fields | Accurate data transfer |
+| Sync rules | How conflicts are resolved (most recent wins, prefer HubSpot, prefer app) | Data consistency |
+| Filter rules | Which records to sync (e.g., only active customers) | Prevent syncing irrelevant data |
+| Initial sync | Full historical sync vs. going-forward only | Complete vs. fresh-start data |
+
+### 1.2 Common Data Sync Integrations
+
+| App | Objects synced | Use case |
+|-----|---------------|----------|
+| Salesforce | Contacts, Companies, Deals, Activities | CRM bidirectional sync |
+| Microsoft Dynamics | Contacts, Companies, Deals | CRM sync |
+| Mailchimp | Contacts, Lists | Email marketing sync |
+| Google Contacts | Contacts | Address book sync |
+| NetSuite | Contacts, Companies, Products, Invoices | ERP sync |
+| QuickBooks | Contacts, Invoices, Products | Accounting sync |
+| Zendesk | Contacts, Tickets | Support data sync |
+
+### 1.3 Sync Health Monitoring
+
+| Metric | What to monitor | Action |
+|--------|----------------|--------|
+| Sync errors | Failed record syncs | Review and fix field mapping issues |
+| Sync lag | Time delay between systems | Check API rate limits |
+| Record count | Total records synced | Verify expected volume |
+| Conflict resolution | How conflicts were handled | Audit data accuracy |
+
+---
+
+## 2. Data Quality
+
+**Where:** Operations > Data Quality (Operations Hub Professional+)
+
+### 2.1 Data Quality Command Center
+
+| Feature | Configuration | Purpose |
+|---------|--------------|---------|
+| Property insights | Auto-detected issues per property | Identify data problems |
+| Data health trends | Dashboard of data quality over time | Track improvement |
+| Fix recommendations | Suggested fixes for common issues | Guided cleanup |
+| Duplicate management | Detect and merge duplicate records | Data deduplication |
+
+### 2.2 Data Quality Automation
+
+| Rule type | Example | Purpose |
+|-----------|---------|---------|
+| Capitalize names | "john doe" → "John Doe" | Consistent formatting |
+| Fix phone format | Various formats → standardized | Consistent phone numbers |
+| Clean dates | Various date formats → ISO standard | Consistent date formatting |
+| Trim whitespace | Remove leading/trailing spaces | Clean data entry |
+| Standardize state | "calif." → "California" | Consistent address data |
+
+**hscli:**
+```bash
+# Search for contacts with data issues (e.g., missing email)
+hscli crm contacts search --data '{
+  "filterGroups": [{
+    "filters": [{
+      "propertyName": "email",
+      "operator": "NOT_HAS_PROPERTY"
+    }]
+  }],
+  "limit": 50
+}'
+
+# Bulk update to fix formatting
+hscli crm contacts batch update --data '{
+  "inputs": [
+    {"id": "123", "properties": {"firstname": "John"}},
+    {"id": "456", "properties": {"firstname": "Jane"}}
+  ]
+}' --force
+```
+
+### 2.3 Duplicate Management
+
+**Where:** Contacts > Actions > Manage Duplicates (or Operations > Data Quality)
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Detection rules | Match by email, name, phone, company | Find potential duplicates |
+| Auto-merge rules | Which record wins (most recent, most complete) | Automated cleanup |
+| Manual review queue | Review suggested merges before applying | Prevent false merges |
+| Merge behavior | Primary record + merged data | Data preservation |
+
+---
+
+## 3. Workflows (Programmable Automation)
+
+**Where:** Automation > Workflows
+
+### 3.1 Operations-Specific Workflow Actions
+
+| Action | Description | Use case |
+|--------|-------------|----------|
+| **Custom code** | Run JavaScript/Python in workflow | Complex data transformations |
+| **Webhook** | Call external API | Trigger actions in other systems |
+| **Format data** | Transform property values | Standardize data on the fly |
+| **Create/update records** | CRM operations within workflow | Cross-object automation |
+| **Data sync trigger** | Trigger sync on record change | Real-time data sync |
+
+### 3.2 Custom Code Actions (Operations Hub Professional+)
+
+| Feature | Configuration | Purpose |
+|---------|--------------|---------|
+| Language | Node.js 18 (JavaScript) | Custom logic |
+| Inputs | Define input properties from enrollment trigger | Pass data into code |
+| Outputs | Define output properties | Pass results to next action |
+| Secrets | Store API keys securely | Secure external API calls |
+| Timeout | Max 20 seconds execution | Performance guardrail |
+
+```javascript
+// Example: Enrich company data with external API
+exports.main = async (event, callback) => {
+  const domain = event.inputFields['company_domain'];
+  const response = await fetch(`https://api.enrichment.com/company?domain=${domain}`, {
+    headers: { 'Authorization': `Bearer ${process.env.ENRICHMENT_API_KEY}` }
+  });
+  const data = await response.json();
+  callback({
+    outputFields: {
+      industry: data.industry,
+      employee_count: data.employees,
+      annual_revenue: data.revenue
+    }
+  });
+};
+```
+
+### 3.3 Webhook Actions
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| URL | Endpoint to call | External system integration |
+| Method | POST, GET, PUT, DELETE | API operation type |
+| Headers | Auth headers, content type | API authentication |
+| Body | JSON payload with HubSpot data | Data to send |
+| Response mapping | Map response to HubSpot properties | Update CRM from response |
+
+---
+
+## 4. Datasets
+
+**Where:** Reports > Datasets (Operations Hub Professional+)
+
+### 4.1 Dataset Configuration
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Data sources | Select CRM objects to include | Define data scope |
+| Joins | How objects relate (contacts + deals + companies) | Cross-object analysis |
+| Calculated fields | Custom formulas on existing data | Derived metrics |
+| Filters | Which records to include | Focused datasets |
+| Permissions | Who can use the dataset | Data governance |
+
+### 4.2 Calculated Field Types
+
+| Type | Example | Formula |
+|------|---------|---------|
+| Date math | Days since last activity | `DATEDIFF(NOW(), last_activity_date)` |
+| String manipulation | Full name from first + last | `CONCAT(firstname, " ", lastname)` |
+| Conditional | Lead grade based on score | `IF(score > 80, "A", IF(score > 50, "B", "C"))` |
+| Aggregation | Total deal value per company | `SUM(deal_amount)` |
+| Math | Discount percentage | `(original_price - sale_price) / original_price` |
+
+### 4.3 Dataset Best Practices
+
+| Practice | Why |
+|----------|-----|
+| Name clearly | Easy discovery for report builders |
+| Document calculated fields | Others understand the logic |
+| Limit scope | Performance and relevance |
+| Test with sample data | Verify calculations before sharing |
+| Set permissions | Prevent unauthorized access to sensitive data |
+
+---
+
+## 5. Custom Properties & Objects
+
+### 5.1 Property Management Strategy
+
+**Where:** Settings > Properties
+
+| Guideline | Recommendation | Why |
+|-----------|---------------|-----|
+| Naming convention | `snake_case` with prefix (e.g., `ops_sync_status`) | Avoid conflicts, easy identification |
+| Property groups | Organize related properties into groups | Clean UI for users |
+| Required fields | Only require what's truly necessary | Balance data quality with usability |
+| Field validation | Use appropriate field types and validation | Prevent bad data at entry |
+| Documentation | Maintain a property dictionary | Team knows what each property means |
+
+**hscli:**
+```bash
+# List all contact properties
+hscli crm properties list contacts --limit 100
+
+# Create a custom property
+hscli crm properties create contacts --data '{
+  "name": "ops_data_source",
+  "label": "Data Source",
+  "type": "enumeration",
+  "fieldType": "select",
+  "groupName": "contactinformation",
+  "options": [
+    {"label": "Website", "value": "website", "displayOrder": 0},
+    {"label": "Import", "value": "import", "displayOrder": 1},
+    {"label": "API", "value": "api", "displayOrder": 2},
+    {"label": "Integration", "value": "integration", "displayOrder": 3}
+  ]
+}' --force
+
+# Delete a property (careful!)
+hscli crm properties delete contacts <propertyName> --force
+```
+
+### 5.2 Custom Objects (Enterprise)
+
+**Where:** Settings > Objects > Custom Objects
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| Object name | Singular and plural labels | UI display |
+| Primary display property | Which property shows in record title | Quick identification |
+| Properties | Custom properties for the object | Data model |
+| Associations | Links to standard objects (contacts, companies, deals) | Relational data |
+| Pipelines | Optional pipeline for status tracking | Process management |
+
+**hscli:**
+```bash
+# List custom objects (schemas)
+hscli crm schemas list
+
+# Create a custom object
+hscli crm schemas create --data '{
+  "name": "project",
+  "labels": {"singular": "Project", "plural": "Projects"},
+  "primaryDisplayProperty": "project_name",
+  "properties": [
+    {"name": "project_name", "label": "Project Name", "type": "string", "fieldType": "text"},
+    {"name": "project_status", "label": "Status", "type": "enumeration", "fieldType": "select",
+     "options": [{"label": "Active", "value": "active"}, {"label": "Complete", "value": "complete"}]},
+    {"name": "start_date", "label": "Start Date", "type": "date", "fieldType": "date"}
+  ],
+  "associatedObjects": ["CONTACT", "COMPANY"]
+}' --force
+```
+
+---
+
+## 6. Import & Export
+
+**Where:** Contacts > Import (or any object > Import)
+
+### 6.1 Import Settings
+
+| Setting | What to configure | Why it matters |
+|---------|-------------------|----------------|
+| File format | CSV or XLSX | Data source format |
+| Object type | Which CRM object to import to | Target destination |
+| Column mapping | Map file columns to HubSpot properties | Correct data placement |
+| Import type | Create new, update existing, or both | Control record creation |
+| Deduplication | Match on email, record ID, or custom property | Prevent duplicates |
+| List creation | Auto-create list of imported records | Track imported batch |
+
+### 6.2 Import Best Practices
+
+| Practice | Why |
+|----------|-----|
+| Clean data before import | Garbage in, garbage out |
+| Test with small sample first | Verify mapping before bulk import |
+| Include unique identifier | Email for contacts, domain for companies |
+| Use consistent date format | YYYY-MM-DD or MM/DD/YYYY |
+| Remove duplicates in source file | Don't create duplicate CRM records |
+| Back up before large imports | Safety net |
+
+**hscli:**
+```bash
+# Import contacts from CSV
+hscli crm imports create --file ./contacts.csv --object contacts --force
+
+# Check import status
+hscli crm imports list --limit 10
+```
+
+---
+
+## Setup Checklist
+
+### Data Sync
+```
+[ ] Key integrations identified for data sync
+[ ] Sync direction configured per integration
+[ ] Field mappings defined and tested
+[ ] Conflict resolution rules set
+[ ] Filter rules configured (which records to sync)
+[ ] Sync health monitoring in place
+```
+
+### Data Quality
+```
+[ ] Data quality command center reviewed
+[ ] Formatting automation rules created (names, phones, dates)
+[ ] Duplicate detection rules configured
+[ ] Initial duplicate review and merge completed
+[ ] Ongoing data quality monitoring established
+```
+
+### Workflows
+```
+[ ] Custom code actions created for complex logic (if needed)
+[ ] Webhook integrations configured
+[ ] Data formatting workflows active
+[ ] Cross-object automation workflows built
+```
+
+### Datasets
+```
+[ ] Key datasets created for reporting
+[ ] Calculated fields defined and tested
+[ ] Dataset permissions set
+[ ] Report builders trained on available datasets
+```
+
+### Properties & Objects
+```
+[ ] Property naming convention established
+[ ] Property groups organized
+[ ] Unnecessary properties archived
+[ ] Custom objects created (if needed)
+[ ] Association relationships configured
+```
+
+### Import/Export
+```
+[ ] Import process documented
+[ ] Import templates created (CSV with correct columns)
+[ ] Initial data import completed and verified
+[ ] Ongoing import process established (if recurring)
+```