@revfleet/hscli 0.8.11 → 0.9.0

package/docs/SALES_CONTENT_INTERNAL_PUNCH_LIST.md

@@ -0,0 +1,504 @@
+# Sales Content Internal Punch List
+
+Status: staged backlog with a first migration-capable slice implemented.
+Read surfaces are available for sales content, and narrow write/migration
+helpers are available for sequences, sales templates, and playbooks. Broader
+full-fidelity migration still requires sandbox contract testing before it should
+be used on client production-adjacent portals.
+
+This captures internal HubSpot surfaces discovered during migration work for
+sequences, playbooks, sales templates, shared content permissions, and related
+analytics. Existing public commands such as `hscli sales sequences` should stay
+public-API first; this punch list describes the future cookie-auth/internal
+surface needed for full-fidelity backup and migration.
+
+Reference endpoint details and payload schemas should live in
+`HSCLI-ENDPOINTS.md` or the migration-specific endpoint catalog.
+
+Implemented slice:
+
+- Browser-session fetch requests now use `credentials: "include"`.
+- Browser-session commands already accept `--cookie`, `--cookie-file`,
+  `HSCLI_HUBSPOT_COOKIE`, `HSCLI_HUBSPOT_COOKIE_FILE`, `--csrf`, and
+  `HSCLI_HUBSPOT_CSRF`.
+- `hubspotapi-csrf` is accepted as the modern CSRF cookie.
+- `hscli sales-content search` wraps internal sales content search.
+- `hscli sequences list|get|create|delete|migrate` reads, creates, deletes, and
+  migrates internal sequence payloads with destination owner/template remapping.
+- `hscli sales-templates list|get|usage|create` reads template payloads and can
+  create a destination template from inline or file-backed HTML.
+- `hscli playbooks list|get|questions|create|update|delete|migrate` reads and
+  migrates playbook payloads through the read/write Chirp RPC surface.
+- Shared sales-content permission updates are available through the
+  sequence/playbook migration helpers when destination teams/users are supplied.
+
+Still backlog:
+
+- standalone `permissions get|set`
+- standalone `sequences clone`
+- standalone `sales-templates migrate`
+- playbook/template permission verification reads
+- doctor capability probes for these internal surfaces
+- deeper policy gates for write/delete/permissions
+- expanded sandbox contract tests across real portals
+
+## 1. Cookie / CSRF Transport
+
+Why: internal HubSpot endpoints are same-origin browser-session endpoints, not
+private-app bearer-token endpoints.
+
+Code area: `src/core/http.ts` or the shared HubSpot HTTP client/session layer.
+
+Add / verify:
+
+- auth mode: `cookie`
+- cookie input: `--cookie`, `--cookie-file`, or `HSCLI_HUBSPOT_COOKIE`
+- cookie jar support for Netscape-format browser exports
+- CSRF cookie name: `hubspotapi-csrf`
+- CSRF header name: `X-HubSpot-CSRF-hubspotapi`
+- automatic CSRF extraction from cookie jar or cookie header
+- automatic CSRF header injection for internal calls
+- `credentials: "include"` for fetch options where supported
+- trace redaction for the `hubspotapi-csrf` value
+
+Smoke test:
+
+```bash
+hscli sequences list --cookie-file ~/.hubspot-cookie.txt
+```
+
+## 2. Top-Level `hscli sequences`
+
+Code area: `src/commands/sequences/index.ts`.
+
+### `hscli sequences list`
+
+- Endpoint: `POST /api/salescontentsearch/v2/search?portalId={portalId}`
+- Body: `{ "query": "", "limit": <limit>, "offset": <offset> }`
+- Pagination: use `hasMore`
+- Filtering: client-side `contentType === "SEQUENCE"`
+- Output columns: `id`, `name`, `owner`, `folderId`, `dynamic`,
+  `lastUsedAt`, `teams`, `visibleToAll`
+
+### `hscli sequences get <id>`
+
+- Endpoint: `GET /api/sequences/v3/sequences/{id}?portalId={portalId}`
+- Output: `{ sequence, userView }`
+- Pretty print: steps, settings, dependencies
+- Optional: `--with-stats` using sequence enrollment analytics below
+
+### `hscli sequences create`
+
+- Endpoint: `POST /api/sequences/v3/sequences/create?portalId={portalId}`
+- Body wrapper: `{ "sequenceEgg": <transformed-sequence> }`
+- Inputs: `--from <jsonfile>`, `--remap-templates <mapfile>`
+- Strip server-set fields:
+  - `id`
+  - `sequenceId`
+  - `sequenceStepId`
+  - `createdAt`
+  - `updatedAt`
+  - `deletedAt`
+- Apply template ID remapping before create.
+- If `--permissions <jsonfile>` is provided, call the shared permissions
+  helper after create.
+- Log warning: `active: "INACTIVE"` is ignored by the API.
+
+### `hscli sequences delete <id...>`
+
+- Endpoint: `DELETE /api/sequences/v3/sequences/batch?portalId={portalId}`
+- Body: `{ "ids": ["..."] }`
+- Require confirmation unless `--force`.
+
+### `hscli sequences clone <src-id> --dest <portalId>`
+
+- Pipeline:
+  - fetch source sequence
+  - transform payload
+  - remap owner
+  - remap templates
+  - create destination sequence
+  - set destination permissions
+- Template mapping strategy: match by `name + subject + normalized_body`
+  across portals.
+
+## 3. Top-Level `hscli playbooks`
+
+Code area: `src/commands/playbooks/index.ts`.
+
+Auth: cookie + Chirp RPC through
+`POST /api/chirp-frontend-app/v1/gateway/...`.
+
+### `hscli playbooks list`
+
+- Endpoint:
+  `POST /api/chirp-frontend-app/v1/gateway/com.hubspot.playbooks.rpc.PlaybooksRpc/listPlaybooks`
+- Body: `{}`
+- Response path: `.data.playbooks[]`
+- Includes inline `body` and `htmlBody`.
+
+### `hscli playbooks get <id>`
+
+- Option A: call `listPlaybooks` and filter by `id`
+- Option B:
+  `POST .../com.hubspot.playbooks.rpc.PlaybooksRpc/getLatestPlaybookVersion`
+- Body: `{ "playbookId": <id> }`
+
+### `hscli playbooks questions <id>`
+
+- Endpoint:
+  `POST .../com.hubspot.playbooks.rpc.PlaybookQuestionsRpc/getLatestQuestionsByPlaybook`
+- Body: `{ "playbookId": <id> }`
+- Output: `{ questions: [...] }`
+
+### `hscli playbooks clone <src-id> --dest <portalId>`
+
+- Status: read-only for now.
+- Playbook write endpoint is not validated.
+- Document as a known migration gap until sandbox write behavior is proven.
+
+## 4. Shared `hscli permissions`
+
+Code area: `src/commands/permissions.ts`.
+
+Used by sequences, sales templates, playbooks, snippets, and documents.
+
+### `hscli permissions set <objectType> <id1,id2,...>`
+
+Flags:
+
+- `--teams <ids>`
+- `--users <ids>`
+- `--visible-to-all`
+- `--private`
+
+Endpoint:
+
+```text
+PUT /api/contentpermissions/v1/permissions?portalId={portalId}
+```
+
+Body:
+
+```json
+{
+  "objectType": "SEQUENCE",
+  "objectIds": ["123"],
+  "permissions": {
+    "TEAM": [],
+    "USER": []
+  },
+  "visibleToAll": false,
+  "private": true
+}
+```
+
+Object type enum:
+
+- `SEQUENCE`
+- `TEMPLATE`
+- `PLAYBOOK`
+- `DOCUMENT`
+- `SNIPPET`
+
+Behavior:
+
+- Replace semantics.
+- Fetch current state first.
+- Show diff before overwrite.
+- Gate writes through policy and `--force`.
+
+### `hscli permissions get <objectType> <id>`
+
+- No standalone GET endpoint is confirmed.
+- Use `salescontentsearch` and extract:
+  - `permissionedTeamIds`
+  - `permissionedUserIds`
+  - `visibleToAll`
+  - `private`
+
+## 5. Top-Level `hscli sales-templates`
+
+Code area: `src/commands/sales-templates/index.ts`.
+
+### `hscli sales-templates list`
+
+- Endpoint: `GET /api/templates/v1/templates?portalId={portalId}`
+- Response: flat array
+- Pagination: not required for typical portals unless tests prove otherwise
+
+### `hscli sales-templates get <id>`
+
+- Endpoint: `GET /api/sales-templates/v2/templates/{id}?portalId={portalId}`
+- Output fields:
+  - `id`
+  - `name`
+  - `subject`
+  - `body`
+  - `htmlBody`
+  - `userId`
+  - `sharedUsers`
+  - `active`
+  - `folderId`
+
+### `hscli sales-templates usage`
+
+- Endpoint:
+  `GET /api/sales-templates/v2/templates/usage?portalId={portalId}`
+- Output:
+  - `limit`
+  - `userLimit`
+  - `currentUsage`
+
+### `hscli sales-templates create`
+
+- Endpoint: `POST /api/sales-templates/v2/templates?portalId={portalId}`
+- Minimum body:
+  - `name`
+  - `subject`
+  - `body`
+- Input: `--from <jsonfile>`
+- Validate optional fields after sandbox contract tests.
+
+## 6. Top-Level `hscli sales-content search`
+
+Code area: `src/commands/sales-content/index.ts`.
+
+Command:
+
+```bash
+hscli sales-content search \
+  --type SEQUENCE \
+  --owner <ownerId> \
+  --query "renewal"
+```
+
+Endpoint:
+
+```text
+POST /api/salescontentsearch/v2/search?portalId={portalId}
+```
+
+Body:
+
+```json
+{
+  "query": "",
+  "limit": 100,
+  "offset": 0
+}
+```
+
+Behavior:
+
+- Paginate with `hasMore`.
+- Filter `contentType` client-side because the API `filters[]` shape was
+  inconsistent in tests.
+- Output: `type`, `id`, `name`, `owner`, `lastUsedAt`, `teams`,
+  `visibleToAll`.
+
+## 7. Sequence Enrollment Analytics
+
+Used by `sequences list --with-stats` and `sequences get --with-stats`.
+
+Object type: `0-68` (`SEQUENCE_ENROLLMENT`).
+
+Total count endpoint:
+
+```text
+POST /api/crm-search/search?portalId={portalId}
+```
+
+Body:
+
+```json
+{
+  "objectTypeId": "0-68",
+  "count": 1,
+  "filterGroups": [
+    {
+      "filters": [
+        {
+          "property": "hs_sequence_id",
+          "value": "<seqId>",
+          "operator": "EQ"
+        }
+      ]
+    }
+  ],
+  "requestOptions": {
+    "includeAllValues": false
+  },
+  "sorts": []
+}
+```
+
+Breakdown endpoint:
+
+```text
+POST /api/crm-search/report?portalId={portalId}
+```
+
+Aggregation:
+
+```json
+{
+  "aggregations": [
+    {
+      "name": "enrollment_status",
+      "type": "TERMS",
+      "size": 20,
+      "property": "hs_enrollment_status"
+    }
+  ]
+}
+```
+
+Relevant properties:
+
+- `hs_sequence_id`
+- `hs_enrolled_at`
+- `hs_ended_at`
+- `hs_enrollment_status`
+- `hs_email_sent_count`
+- `hs_email_open_count`
+- `hs_email_replied_count`
+- `hs_email_bounced_count`
+- `hs_finished_count`
+- `hs_unenrolled_count`
+- `hs_error_count`
+- `hs_ended_no_response_count`
+- `hs_enrolled_by`
+- `hs_recipient_email`
+- `hs_first_name`
+- `hs_last_name`
+
+## 8. Migration Adapter: `hscli migrate sequences`
+
+Code area: `src/commands/migrate/sequences.ts`.
+
+Command:
+
+```bash
+hscli migrate sequences \
+  --src-portal <source> \
+  --dst-portal <target> \
+  --ids <id1,id2> \
+  --owner-map owners.json \
+  --team-map teams.json \
+  --dry-run
+```
+
+Pipeline:
+
+- Discover destination templates with `sales-templates list`.
+- Discover source sequences with `sales-content search --type SEQUENCE`.
+- Fetch each source sequence with `sequences get`.
+- Remap template IDs by `name + subject + normalized_body` similarity.
+- Require similarity ratio `>= 0.95`.
+- Fail if any template is unmappable.
+- Remap owners from `--owner-map`.
+- Default missing owner to running user only when explicitly allowed by policy.
+- Strip server-set fields from sequence, steps, and nested patterns:
+  - `id`
+  - `sequenceId`
+  - `sequenceStepId`
+  - `createdAt`
+  - `updatedAt`
+  - `deletedAt`
+- Preserve dependency fields:
+  - `requiredByStepOrder`
+  - `reliesOnStepOrder`
+  - `branchNumber`
+- Create destination sequence.
+- Set destination permissions with explicit team/user mapping.
+- Never default to `visibleToAll`.
+- Output CSV: `srcId,dstId,status,notes`.
+
+Known gotchas:
+
+- `active: "INACTIVE"` is overridden by the API to active.
+- New sequences are safe only while they have no enrollments.
+- Permissions in `sequenceEgg` are ignored.
+- Permissions must be set with separate `PUT /api/contentpermissions/v1/permissions`.
+- Dependencies in `sequenceEgg` are respected.
+- The API appends an automatic `FINISH_ENROLLMENT` step.
+- Expected step count: `dst.steps.length = src.steps.length + 1`.
+
+## 9. Existing Command Updates
+
+### `hscli doctor capabilities`
+
+Add probes:
+
+- `GET /api/sequences/v3/sequences/{id}`
+- `POST /api/sequences/v3/sequences/create`
+- `PUT /api/contentpermissions/v1/permissions`
+- `POST /api/chirp-frontend-app/v1/gateway/com.hubspot.playbooks.rpc.PlaybooksRpc/getPlaybookCount`
+- `GET /api/sales-templates/v2/templates/usage`
+
+Each probe should report:
+
+- status
+- response time
+- user permission scopes from `GET /api/login-verify/hub-user-info`
+
+### `hscli trace`
+
+Add redaction for:
+
+- `hubspotapi-csrf` cookie value
+- `X-HubSpot-CSRF-hubspotapi` header value
+- browser cookie values in cookie-mode requests
+
+### `hscli policy`
+
+Add capabilities:
+
+- `sequences.write`
+- `sequences.delete`
+- `permissions.write`
+- `playbooks.write`
+
+Policy defaults:
+
+- `sequences.write`: require `--force`, dry-run first, optional time window
+- `sequences.delete`: require `--force` and change ticket
+- `permissions.write`: require `--force` and target-team allowlist
+- `playbooks.write`: disabled by default because write endpoint is not proven
+
+## 10. Contract Tests
+
+Gate with `HSCLI_ENABLE_SANDBOX_CONTRACT=1`.
+
+Add:
+
+- create test sequence
+- fetch test sequence
+- diff source/create output
+- delete test sequence
+- set permissions
+- search and verify permissions
+- reset permissions
+- run full source-to-target sequence migration between two sandbox portals
+
+## Endpoint Catalog
+
+| Verb | Path | Command | Auth |
+|---|---|---|---|
+| GET | `/api/sequences/v3/sequences/{id}` | `sequences get` | cookie |
+| POST | `/api/sequences/v3/sequences/create` | `sequences create` | cookie |
+| DELETE | `/api/sequences/v3/sequences/batch` | `sequences delete` | cookie |
+| POST | `/api/salescontentsearch/v2/search` | `sales-content search`, `sequences list` | cookie |
+| POST | `/api/crm-search/search` with `objectTypeId=0-68` | `sequences get --with-stats` | cookie |
+| POST | `/api/crm-search/report` with `objectTypeId=0-68` | `sequences get --with-stats` | cookie |
+| GET | `/api/sales-templates/v2/templates/{id}` | `sales-templates get` | cookie |
+| GET | `/api/sales-templates/v2/templates/usage` | `sales-templates usage` | cookie |
+| POST | `/api/sales-templates/v2/templates` | `sales-templates create` | cookie |
+| GET | `/api/templates/v1/templates` | `sales-templates list` | cookie |
+| POST | `/api/chirp-frontend-app/v1/gateway/com.hubspot.playbooks.rpc.PlaybooksRpc/listPlaybooks` | `playbooks list` | cookie + chirp |
+| POST | `/api/chirp-frontend-app/v1/gateway/com.hubspot.playbooks.rpc.PlaybooksRpc/getPlaybookCount` | `playbooks usage` | cookie + chirp |
+| POST | `/api/chirp-frontend-app/v1/gateway/com.hubspot.playbooks.rpc.PlaybookQuestionsRpc/getLatestQuestionsByPlaybook` | `playbooks questions` | cookie + chirp |
+| PUT | `/api/contentpermissions/v1/permissions` | `permissions set` | cookie |
+| GET | `/api/app-users/v1/teams` | `teams list` | cookie |
+| GET | `/api/login-verify/hub-user-info` | internal doctor whoami | cookie |

package/docs/TUTORIALS/secure-agent-writes.md

@@ -170,6 +170,55 @@ Now every tool call the agent makes is filtered through the same rules.
 - Change tickets travel with the request and are written to telemetry.
 - Off-hours writes are rejected — no more 2am surprises.
 
+## Seal an approved action
+
+Policies decide whether a request is allowed. Action contracts additionally
+prove exactly which hscli arguments were reviewed. Create a draft without
+credentials or shell commands:
+
+```json
+{
+  "profile": "sandbox",
+  "portalId": "123456",
+  "createdAt": "2026-07-09T09:00:00.000Z",
+  "expiresAt": "2026-07-09T10:00:00.000Z",
+  "changeTicket": "CHG-12345",
+  "operation": {
+    "summary": "Update one approved contact property",
+    "commands": [
+      {
+        "argv": ["crm", "contacts", "update", "101", "--data", "{\"properties\":{\"lifecyclestage\":\"lead\"}}"],
+        "verifyArgv": ["crm", "contacts", "get", "101", "--properties", "lifecyclestage"]
+      }
+    ]
+  },
+  "limits": { "maxCommands": 1, "maxRecords": 1 }
+}
+```
+
+Seal and review it:
+
+```bash
+hscli --json agent contract create --input ./draft.json | jq '.data' > ./contract.json
+hscli --json --profile sandbox --change-ticket CHG-12345 \
+  agent contract verify ./contract.json
+hscli --json --profile sandbox --change-ticket CHG-12345 \
+  agent contract apply ./contract.json
+```
+
+The last command is still plan-only. Execution requires both approvals:
+
+```bash
+hscli --json --profile sandbox --policy-file ./policy.json \
+  --change-ticket CHG-12345 --force \
+  agent contract apply ./contract.json --execute
+```
+
+The runner checks the SHA-256 digest, deterministic contract ID, profile,
+known portal ID, expiry, and ticket before starting. It invokes only hscli
+argument arrays with `shell:false`; `agent`, `auth`, `internal`, `mcp`, and
+global routing flags are forbidden inside contracts.
+
 ## Going further
 
 - Pair this with `hscli trace start` (see the [trace tutorial](trace-replay-repro.md)) to record every request + matched rule to a JSONL file.

package/docs/WHY_HOW_WHAT.md

@@ -3,10 +3,11 @@
 > See also: [ARCHITECTURE.md](ARCHITECTURE.md) · [SAFETY_MODEL.md](SAFETY_MODEL.md) · [ROADMAP_PHASE1_TO_3.md](ROADMAP_PHASE1_TO_3.md)
 
 ## WHY this CLI exists
-`hscli` exists to give operators a safe, automatable, production-grade command interface to HubSpot APIs without needing to write code each time. It solves three operational problems:
-- **Speed:** repetitive CRM operations become scriptable and repeatable.
-- **Safety:** write controls prevent accidental destructive mutations.
-- **Reliability:** consistent output + retry behavior reduce brittle ad-hoc scripts.
+`hscli` exists to give operators and agents a safe, automatable, production-grade command interface to HubSpot without needing to write one-off scripts each time. HubSpot is moving toward an agent-ready platform where APIs, MCP, CLI, and connectors let agents operate the CRM; `hscli` focuses on the operator layer around that movement:
+- **Speed:** repetitive CRM, migration, backup, and reporting work becomes scriptable and repeatable.
+- **Safety:** write controls, profile boundaries, policy files, and change tickets prevent accidental destructive mutations.
+- **Reliability:** consistent output, retry behavior, rate-limit handling, and trace/audit evidence reduce brittle ad-hoc scripts.
+- **Context:** deterministic portal context, parity checks, and multi-portal plans give agents useful structure before they summarize or act.
 
 ## WHAT has been built (and what remains)
 
@@ -38,6 +39,11 @@
   - secret redaction in output/error serialization
   - profile environment isolation via `HSCLI_HOME`
   - request scope guard, timeout, retries, and correlation id
+- Agent/operator workflows:
+  - deterministic `agent plan` runbooks
+  - read-only `context build` portal profiles
+  - `doctor parity` public/internal/hybrid/UI-only coverage map
+  - `portals list|plan` for explicit multi-portal management
 - Auth model expansion:
   - profile listing/inspection
   - OAuth authorize URL + code exchange

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@revfleet/hscli",
-  "version": "0.8.11",
-  "description": "Agentic HubSpot CLI + MCP server. Covers ~all documented public endpoints (1180 across 55+ command domains). Reachability is tier/scope/auth-model gated — UI-only surfaces and deprecated APIs excluded. Enterprise safety rails, self-hosted.",
+  "version": "0.9.0",
+  "description": "HubSpot operations and migration control plane for humans and agents, with deterministic runbooks, policy guardrails, and auditable evidence.",
   "type": "module",
   "bin": {
     "hscli": "dist/cli.js"
@@ -15,6 +15,8 @@
     "test:contract": "HSCLI_ENABLE_SANDBOX_CONTRACT=1 vitest run tests/contract.sandbox.test.ts",
     "lint": "eslint src/ tests/",
     "lint:fix": "eslint src/ tests/ --fix",
+    "docs:mcp": "npm run build && node scripts/generate-mcp-catalog.mjs",
+    "docs:mcp:check": "npm run build && node scripts/generate-mcp-catalog.mjs --check",
     "release:checksums": "node scripts/release-checksums.mjs",
     "audit": "npm audit --audit-level=high",
     "release:verify": "npm run typecheck && npm run lint && npm test && npm run audit && npm run build && npm run release:checksums && shasum -a 256 -c release/checksums.sha256",