@revfleet/hscli 0.8.12 → 0.9.0

package/docs/MARKETING_SETUP.md

@@ -227,9 +227,29 @@ hscli forms create --source-format v2 --data '{"name":"Legacy form","submitText"
 
 # Real legacy writes preflight target CRM properties and skip missing fields; add --strict to fail instead
 hscli forms create --source-format v2 --strict --data '{"name":"Legacy form","formFieldGroups":[{"fields":[{"name":"email","label":"Email","fieldType":"email","required":true}]}]}' --dry-run
+
+# Legacy consent checkboxes must use target subscription definition IDs
+hscli forms create --source-format v2 --subscription-type-map ./id-maps/subscription-types.json --data '{"name":"Legacy form","formFieldGroups":[{"fields":[{"name":"email","label":"Email","fieldType":"email"}]}]}' --dry-run
 ```
 
-> **API:** `forms` scope. Full CRUD on forms including field configuration. Legacy forms/v2 payloads are auto-translated on create/update when detected; use `hscli forms translate-v2` to inspect the v3 payload before replay. During real writes, hscli preflights target CRM properties, skips missing fields by default, and auto-splits field groups to HubSpot's 3-field v3 limit.
+> **API:** `forms` scope. Full CRUD on forms including field configuration. Legacy forms/v2 payloads are auto-translated on create/update when detected; use `hscli forms translate-v2` to inspect the v3 payload before replay. During real writes, hscli preflights target CRM properties, skips missing fields by default, auto-splits field groups to HubSpot's 3-field v3 limit, and requires `--subscription-type-map` when legacy consent metadata references source subscription IDs.
+
+> **Subscription definition migration note:** Public APIs can read subscription
+> definitions (`/communication-preferences/v3/definitions` and
+> `/communication-preferences/v4/definitions`), but public create returned HTTP
+> 405 during cross-portal migration testing. HubSpot's Email > Subscription
+> Types UI writes through internal `/api/subscriptions/v1/definitions`. When
+> using a browser-session migration helper, match by
+> `name + purpose/process + communicationMethod/channel + businessUnitId` and
+> remap business units before write.
+>
+> hscli exposes this as an explicit migration adapter:
+> `hscli communication-preferences definitions create-internal --portal-id <id>
+> --cookie-file <cookies> --data '{...}' --business-unit-map ./id-maps/business-units.json`.
+> The adapter is Email-only and rejects non-Email `communicationMethod`,
+> `channel`, or `method` values; Chat/Call/Post definitions need separately
+> probed adapters.
+> There is intentionally no generic internal API passthrough.
 
 ---
 

package/docs/MCP.md

@@ -14,9 +14,16 @@ node dist/cli.js mcp
 Or if installed globally:
 
 ```bash
-hscli mcp
+hscli mcp                                      # minimal: essential CRM reads
+hscli mcp --surface crm                        # curated CRM reads + writes
+hscli mcp --surface migration                  # cross-product migration tools
+hscli mcp --surface full                       # all tools, including raw API
 ```
 
+The default `minimal` surface keeps agent context and write exposure small.
+Set `HSCLI_MCP_SURFACE=minimal|crm|migration|full` when the MCP client cannot
+pass command arguments.
+
 ## Profile isolation and safety defaults
 
 - **Profile isolation**: set `HSCLI_MCP_PROFILE=<profile>` to hard-lock the MCP server to one auth profile.
@@ -77,96 +84,28 @@ If your client accepts env vars, set:
 - `HSCLI_HOME` to the auth profile directory containing `auth.json`
 - `HSCLI_MCP_PROFILE` to force strict profile isolation
 
-## Tool catalog
-
-### Contacts
-- `crm_contacts_list`
-- `crm_contacts_get`
-- `crm_contacts_search`
-- `crm_contacts_create` *(write, dry-run by default)*
-- `crm_contacts_update` *(write, dry-run by default)*
-- `crm_contacts_delete` *(write, dry-run by default)*
-- `crm_contacts_merge` *(write, dry-run by default)*
-- `crm_contacts_batch_read`
-- `crm_contacts_batch_upsert` *(write, dry-run by default)*
-- `crm_contacts_batch_archive` *(write, dry-run by default)*
-
-### Companies
-- `crm_companies_list`
-- `crm_companies_get`
-- `crm_companies_search`
-- `crm_companies_create` *(write, dry-run by default)*
-- `crm_companies_update` *(write, dry-run by default)*
-- `crm_companies_delete` *(write, dry-run by default)*
-- `crm_companies_merge` *(write, dry-run by default)*
-- `crm_companies_batch_read`
-- `crm_companies_batch_upsert` *(write, dry-run by default)*
-- `crm_companies_batch_archive` *(write, dry-run by default)*
-
-### Deals
-- `crm_deals_list`
-- `crm_deals_get`
-- `crm_deals_search`
-- `crm_deals_create` *(write, dry-run by default)*
-- `crm_deals_update` *(write, dry-run by default)*
-- `crm_deals_delete` *(write, dry-run by default)*
-- `crm_deals_merge` *(write, dry-run by default)*
-- `crm_deals_batch_read`
-- `crm_deals_batch_upsert` *(write, dry-run by default)*
-- `crm_deals_batch_archive` *(write, dry-run by default)*
-
-### Tickets
-- `crm_tickets_list`
-- `crm_tickets_get`
-- `crm_tickets_search`
-- `crm_tickets_create` *(write, dry-run by default)*
-- `crm_tickets_update` *(write, dry-run by default)*
-- `crm_tickets_delete` *(write, dry-run by default)*
-- `crm_tickets_merge` *(write, dry-run by default)*
-- `crm_tickets_batch_read`
-- `crm_tickets_batch_upsert` *(write, dry-run by default)*
-- `crm_tickets_batch_archive` *(write, dry-run by default)*
-
-### Engagements
-- `crm_notes_*` (`list/get/search/create/update/delete`)
-- `crm_calls_*` (`list/get/search/create/update/delete`)
-- `crm_tasks_*` (`list/get/search/create/update/delete`)
-- `crm_emails_*` (`list/get/search/create/update/delete`)
-- `crm_meetings_*` (`list/get/search/create/update/delete`)
-
-### Properties
-- `crm_properties_list`
-- `crm_properties_get`
-- `crm_properties_create` *(write, dry-run by default)*
-- `crm_properties_batch_create` *(write, dry-run by default; supports custom object type IDs, reserved-name skips, option cleanup, empty-enum demotion/skip)*
-- `crm_properties_update` *(write, dry-run by default)*
-
-### Associations
-- `crm_associations_list`
-- `crm_associations_create` *(write, dry-run by default)*
-- `crm_associations_remove` *(write, dry-run by default)*
-
-### Imports
-- `crm_imports_create` *(write, dry-run by default)*
-- `crm_imports_list`
-- `crm_imports_get`
-- `crm_imports_errors`
-
-### Owners
-- `crm_owners_list`
-
-### Pipelines
-- `crm_pipelines_list`
-- `crm_pipelines_get`
-
-### Custom Objects
-- `crm_custom_schemas_list|get|create|update`
-- `crm_custom_records_list|get|search|create|update|delete`
-
-### Raw API
-- `hub_api_request` *(write methods dry-run by default)*
+## Tool surfaces
+
+| Surface | Tools | Intended use | Raw API |
+|---|---:|---|---|
+| `minimal` | 29 | Agent discovery and essential CRM reads | No |
+| `crm` | 136 | CRM objects, schemas, properties, associations, imports | No |
+| `migration` | 179 | Curated cross-product backup and migration work | No |
+| `full` | 180 | Explicit operator access to every registered tool | Yes |
+
+The exact catalog is generated from runtime registration metadata, including
+domain, inferred risk, surfaces, and description:
+[MCP_TOOL_CATALOG.md](MCP_TOOL_CATALOG.md).
+
+Regenerate and verify it with:
+
+```bash
+npm run docs:mcp
+npm run docs:mcp:check
+```
 
 ## Notes
 
 - MCP transport is stdio only in this implementation.
 - Existing auth + HTTP core logic is reused (`getToken`, `HubSpotClient`, `maybeWrite`, redaction).
+- `hub_api_request` is exposed only by `--surface full`.

package/docs/MCP_TOOL_CATALOG.md

@@ -0,0 +1,192 @@
+# MCP Tool Catalog
+
+Generated from the runtime registration schemas. Do not edit manually.
+
+- Minimal: 29 tools
+- CRM: 136 tools
+- Migration: 179 tools
+- Full: 180 tools
+
+| Tool | Domain | Risk | Surfaces | Description |
+|---|---|---|---|---|
+| `cms_redirects_create` | cms | write | migration, full | Create a CMS URL redirect (dry-run by default unless force=true). Not available via HubSpot Remote MCP. |
+| `cms_redirects_delete` | cms | delete | migration, full | Delete a CMS URL redirect (dry-run by default unless force=true). Not available via HubSpot Remote MCP. |
+| `cms_redirects_list` | cms | read | migration, full | List CMS URL redirects. Not available via HubSpot Remote MCP. |
+| `conversations_inboxes_list` | conversations | read | migration, full | List conversation inboxes. Not available via HubSpot Remote MCP. |
+| `conversations_messages_send` | conversations | write | migration, full | Send a message into a conversation thread (dry-run by default unless force=true). Not available via HubSpot Remote MCP. |
+| `conversations_threads_list` | conversations | read | migration, full | List conversation threads. Not available via HubSpot Remote MCP. |
+| `crm_associations_create` | crm | write | crm, migration, full | Create default association (dry-run by default unless force=true). Supports standard types, engagements, and custom object type IDs. |
+| `crm_associations_list` | crm | read | minimal, crm, migration, full | List associations between CRM objects (supports standard types, engagements, and custom object type IDs like 2-199622513) |
+| `crm_associations_remove` | crm | delete | crm, migration, full | Remove default association (dry-run by default unless force=true). Supports standard types, engagements, and custom object type IDs. |
+| `crm_calls_batch_archive` | crm | delete | crm, migration, full | Batch archive calls (dry-run by default unless force=true) |
+| `crm_calls_batch_read` | crm | read | crm, migration, full | Batch read calls |
+| `crm_calls_batch_upsert` | crm | write | crm, migration, full | Batch upsert calls (dry-run by default unless force=true) |
+| `crm_calls_create` | crm | write | crm, migration, full | Create call (dry-run by default unless force=true) |
+| `crm_calls_delete` | crm | delete | crm, migration, full | Delete/archive call by ID (dry-run by default unless force=true) |
+| `crm_calls_get` | crm | read | crm, migration, full | Get one call by ID |
+| `crm_calls_list` | crm | read | crm, migration, full | List calls |
+| `crm_calls_merge` | crm | write | crm, migration, full | Merge calls records (endpoint support varies by object) |
+| `crm_calls_search` | crm | read | crm, migration, full | Search calls |
+| `crm_calls_update` | crm | write | crm, migration, full | Update call (dry-run by default unless force=true) |
+| `crm_companies_batch_archive` | crm | delete | crm, migration, full | Batch archive companies (dry-run by default unless force=true) |
+| `crm_companies_batch_read` | crm | read | minimal, crm, migration, full | Batch read companies |
+| `crm_companies_batch_upsert` | crm | write | crm, migration, full | Batch upsert companies (dry-run by default unless force=true) |
+| `crm_companies_create` | crm | write | crm, migration, full | Create companie (dry-run by default unless force=true) |
+| `crm_companies_delete` | crm | delete | crm, migration, full | Delete/archive companie by ID (dry-run by default unless force=true) |
+| `crm_companies_get` | crm | read | minimal, crm, migration, full | Get one companie by ID |
+| `crm_companies_list` | crm | read | minimal, crm, migration, full | List companies |
+| `crm_companies_merge` | crm | write | crm, migration, full | Merge companies records (endpoint support varies by object) |
+| `crm_companies_search` | crm | read | minimal, crm, migration, full | Search companies |
+| `crm_companies_update` | crm | write | crm, migration, full | Update companie (dry-run by default unless force=true) |
+| `crm_contacts_batch_archive` | crm | delete | crm, migration, full | Batch archive contacts (dry-run by default unless force=true) |
+| `crm_contacts_batch_read` | crm | read | minimal, crm, migration, full | Batch read contacts |
+| `crm_contacts_batch_upsert` | crm | write | crm, migration, full | Batch upsert contacts (dry-run by default unless force=true) |
+| `crm_contacts_create` | crm | write | crm, migration, full | Create contact (dry-run by default unless force=true) |
+| `crm_contacts_delete` | crm | delete | crm, migration, full | Delete/archive contact by ID (dry-run by default unless force=true) |
+| `crm_contacts_get` | crm | read | minimal, crm, migration, full | Get one contact by ID |
+| `crm_contacts_list` | crm | read | minimal, crm, migration, full | List contacts |
+| `crm_contacts_merge` | crm | write | crm, migration, full | Merge contacts records (endpoint support varies by object) |
+| `crm_contacts_search` | crm | read | minimal, crm, migration, full | Search contacts |
+| `crm_contacts_update` | crm | write | crm, migration, full | Update contact (dry-run by default unless force=true) |
+| `crm_custom_records_create` | crm | write | crm, migration, full | Create custom object record (dry-run by default unless force=true) |
+| `crm_custom_records_delete` | crm | delete | crm, migration, full | Delete custom object record (dry-run by default unless force=true) |
+| `crm_custom_records_get` | crm | read | crm, migration, full | Get custom object record by objectType and id |
+| `crm_custom_records_list` | crm | read | crm, migration, full | List custom object records by objectType |
+| `crm_custom_records_search` | crm | read | crm, migration, full | Search custom object records |
+| `crm_custom_records_update` | crm | write | crm, migration, full | Update custom object record (dry-run by default unless force=true) |
+| `crm_custom_schemas_create` | crm | write | crm, migration, full | Create custom object schema (dry-run by default unless force=true) |
+| `crm_custom_schemas_get` | crm | read | crm, migration, full | Get custom object schema by objectType |
+| `crm_custom_schemas_list` | crm | read | crm, migration, full | List custom object schemas |
+| `crm_custom_schemas_update` | crm | write | crm, migration, full | Update custom object schema (dry-run by default unless force=true) |
+| `crm_deals_batch_archive` | crm | delete | crm, migration, full | Batch archive deals (dry-run by default unless force=true) |
+| `crm_deals_batch_read` | crm | read | minimal, crm, migration, full | Batch read deals |
+| `crm_deals_batch_upsert` | crm | write | crm, migration, full | Batch upsert deals (dry-run by default unless force=true) |
+| `crm_deals_create` | crm | write | crm, migration, full | Create deal (dry-run by default unless force=true) |
+| `crm_deals_delete` | crm | delete | crm, migration, full | Delete/archive deal by ID (dry-run by default unless force=true) |
+| `crm_deals_get` | crm | read | minimal, crm, migration, full | Get one deal by ID |
+| `crm_deals_list` | crm | read | minimal, crm, migration, full | List deals |
+| `crm_deals_merge` | crm | write | crm, migration, full | Merge deals records (endpoint support varies by object) |
+| `crm_deals_search` | crm | read | minimal, crm, migration, full | Search deals |
+| `crm_deals_update` | crm | write | crm, migration, full | Update deal (dry-run by default unless force=true) |
+| `crm_emails_batch_archive` | crm | delete | crm, migration, full | Batch archive emails (dry-run by default unless force=true) |
+| `crm_emails_batch_read` | crm | read | crm, migration, full | Batch read emails |
+| `crm_emails_batch_upsert` | crm | write | crm, migration, full | Batch upsert emails (dry-run by default unless force=true) |
+| `crm_emails_create` | crm | write | crm, migration, full | Create email (dry-run by default unless force=true) |
+| `crm_emails_delete` | crm | delete | crm, migration, full | Delete/archive email by ID (dry-run by default unless force=true) |
+| `crm_emails_get` | crm | read | crm, migration, full | Get one email by ID |
+| `crm_emails_list` | crm | read | crm, migration, full | List emails |
+| `crm_emails_merge` | crm | write | crm, migration, full | Merge emails records (endpoint support varies by object) |
+| `crm_emails_search` | crm | read | crm, migration, full | Search emails |
+| `crm_emails_update` | crm | write | crm, migration, full | Update email (dry-run by default unless force=true) |
+| `crm_exports_create` | crm | write | crm, migration, full | Create a CRM export (dry-run by default unless force=true) |
+| `crm_exports_get` | crm | read | crm, migration, full | Get a CRM export by ID |
+| `crm_exports_list` | crm | read | crm, migration, full | List CRM exports with pagination |
+| `crm_exports_status` | crm | read | crm, migration, full | Get the status of a CRM export |
+| `crm_imports_create` | crm | write | crm, migration, full | Create import (dry-run by default unless force=true) |
+| `crm_imports_errors` | crm | read | crm, migration, full | Get import errors |
+| `crm_imports_get` | crm | read | crm, migration, full | Get import by ID |
+| `crm_imports_list` | crm | read | crm, migration, full | List import jobs |
+| `crm_lists_create` | crm | write | crm, migration, full | Create a CRM list (dry-run by default unless force=true) |
+| `crm_lists_delete` | crm | delete | crm, migration, full | Delete a CRM list (dry-run by default unless force=true) |
+| `crm_lists_get` | crm | read | crm, migration, full | Get a CRM list by ID |
+| `crm_lists_list` | crm | read | crm, migration, full | List CRM lists with pagination |
+| `crm_lists_memberships` | crm | read | crm, migration, full | Get memberships of a CRM list |
+| `crm_lists_update` | crm | write | crm, migration, full | Update a CRM list (dry-run by default unless force=true) |
+| `crm_meetings_batch_archive` | crm | delete | crm, migration, full | Batch archive meetings (dry-run by default unless force=true) |
+| `crm_meetings_batch_read` | crm | read | crm, migration, full | Batch read meetings |
+| `crm_meetings_batch_upsert` | crm | write | crm, migration, full | Batch upsert meetings (dry-run by default unless force=true) |
+| `crm_meetings_create` | crm | write | crm, migration, full | Create meeting (dry-run by default unless force=true) |
+| `crm_meetings_delete` | crm | delete | crm, migration, full | Delete/archive meeting by ID (dry-run by default unless force=true) |
+| `crm_meetings_get` | crm | read | crm, migration, full | Get one meeting by ID |
+| `crm_meetings_list` | crm | read | crm, migration, full | List meetings |
+| `crm_meetings_merge` | crm | write | crm, migration, full | Merge meetings records (endpoint support varies by object) |
+| `crm_meetings_search` | crm | read | crm, migration, full | Search meetings |
+| `crm_meetings_update` | crm | write | crm, migration, full | Update meeting (dry-run by default unless force=true) |
+| `crm_notes_batch_archive` | crm | delete | crm, migration, full | Batch archive notes (dry-run by default unless force=true) |
+| `crm_notes_batch_read` | crm | read | crm, migration, full | Batch read notes |
+| `crm_notes_batch_upsert` | crm | write | crm, migration, full | Batch upsert notes (dry-run by default unless force=true) |
+| `crm_notes_create` | crm | write | crm, migration, full | Create note (dry-run by default unless force=true) |
+| `crm_notes_delete` | crm | delete | crm, migration, full | Delete/archive note by ID (dry-run by default unless force=true) |
+| `crm_notes_get` | crm | read | crm, migration, full | Get one note by ID |
+| `crm_notes_list` | crm | read | crm, migration, full | List notes |
+| `crm_notes_merge` | crm | write | crm, migration, full | Merge notes records (endpoint support varies by object) |
+| `crm_notes_search` | crm | read | crm, migration, full | Search notes |
+| `crm_notes_update` | crm | write | crm, migration, full | Update note (dry-run by default unless force=true) |
+| `crm_owners_list` | crm | read | minimal, crm, migration, full | List HubSpot owners |
+| `crm_pipelines_get` | crm | read | minimal, crm, migration, full | Get one pipeline |
+| `crm_pipelines_list` | crm | read | minimal, crm, migration, full | List pipelines for object type |
+| `crm_pipelines_stages` | crm | read | minimal, crm, migration, full | List stages for a pipeline |
+| `crm_properties_batch_create` | crm | write | crm, migration, full | Batch-create properties for a standard object or custom object type ID (dry-run by default unless force=true) |
+| `crm_properties_create` | crm | write | crm, migration, full | Create property (dry-run by default unless force=true) |
+| `crm_properties_get` | crm | read | minimal, crm, migration, full | Get one property definition |
+| `crm_properties_list` | crm | read | minimal, crm, migration, full | List properties for an object type |
+| `crm_properties_update` | crm | write | crm, migration, full | Update property (dry-run by default unless force=true) |
+| `crm_property_groups_create` | crm | write | crm, migration, full | Create a property group (dry-run by default unless force=true) |
+| `crm_property_groups_list` | crm | read | crm, migration, full | List property groups for an object type |
+| `crm_property_groups_update` | crm | write | crm, migration, full | Update a property group (dry-run by default unless force=true) |
+| `crm_tasks_batch_archive` | crm | delete | crm, migration, full | Batch archive tasks (dry-run by default unless force=true) |
+| `crm_tasks_batch_read` | crm | read | crm, migration, full | Batch read tasks |
+| `crm_tasks_batch_upsert` | crm | write | crm, migration, full | Batch upsert tasks (dry-run by default unless force=true) |
+| `crm_tasks_create` | crm | write | crm, migration, full | Create task (dry-run by default unless force=true) |
+| `crm_tasks_delete` | crm | delete | crm, migration, full | Delete/archive task by ID (dry-run by default unless force=true) |
+| `crm_tasks_get` | crm | read | crm, migration, full | Get one task by ID |
+| `crm_tasks_list` | crm | read | crm, migration, full | List tasks |
+| `crm_tasks_merge` | crm | write | crm, migration, full | Merge tasks records (endpoint support varies by object) |
+| `crm_tasks_search` | crm | read | crm, migration, full | Search tasks |
+| `crm_tasks_update` | crm | write | crm, migration, full | Update task (dry-run by default unless force=true) |
+| `crm_tickets_batch_archive` | crm | delete | crm, migration, full | Batch archive tickets (dry-run by default unless force=true) |
+| `crm_tickets_batch_read` | crm | read | minimal, crm, migration, full | Batch read tickets |
+| `crm_tickets_batch_upsert` | crm | write | crm, migration, full | Batch upsert tickets (dry-run by default unless force=true) |
+| `crm_tickets_create` | crm | write | crm, migration, full | Create ticket (dry-run by default unless force=true) |
+| `crm_tickets_delete` | crm | delete | crm, migration, full | Delete/archive ticket by ID (dry-run by default unless force=true) |
+| `crm_tickets_get` | crm | read | minimal, crm, migration, full | Get one ticket by ID |
+| `crm_tickets_list` | crm | read | minimal, crm, migration, full | List tickets |
+| `crm_tickets_merge` | crm | write | crm, migration, full | Merge tickets records (endpoint support varies by object) |
+| `crm_tickets_search` | crm | read | minimal, crm, migration, full | Search tickets |
+| `crm_tickets_update` | crm | write | crm, migration, full | Update ticket (dry-run by default unless force=true) |
+| `files_delete` | files | delete | migration, full | Permanently delete a file (dry-run by default unless force=true). Not available via HubSpot Remote MCP. |
+| `files_get` | files | read | migration, full | Get metadata for a single file by ID. Not available via HubSpot Remote MCP. |
+| `files_list` | files | read | migration, full | List uploaded files. Not available via HubSpot Remote MCP. |
+| `files_signed_url` | files | read | migration, full | Generate a time-limited signed URL for a private file. Not available via HubSpot Remote MCP. |
+| `forms_create` | forms | write | migration, full | Create a marketing form. Legacy forms/v2 payloads are translated to v3 automatically. Dry-run by default unless force=true. |
+| `forms_get` | forms | read | migration, full | Get one form by ID. Not available via HubSpot Remote MCP. |
+| `forms_list` | forms | read | migration, full | List marketing forms. Not available via HubSpot Remote MCP. |
+| `forms_submissions` | forms | read | migration, full | List submissions for a form. Not available via HubSpot Remote MCP. |
+| `forms_submit` | forms | write | migration, full | Programmatically submit a form (server-side submission endpoint). Dry-run by default unless force=true. |
+| `forms_update` | forms | write | migration, full | Update a marketing form. Legacy forms/v2 payloads are translated to v3 automatically. Dry-run by default unless force=true. |
+| `get_campaign_analytics` | compat | read | migration, full | Get campaign analytics (aggregated metrics) for one or more campaigns. HubSpot-compat. |
+| `get_campaign_asset_metrics` | compat | read | migration, full | Get metrics for specific CRM objects associated with a campaign. HubSpot-compat. |
+| `get_campaign_asset_types` | compat | read | migration, full | List available campaign asset types (emails, blog posts, ads, etc.). HubSpot-compat. |
+| `get_campaign_contacts_by_type` | compat | read | migration, full | Paginated contact IDs for a campaign filtered by attribution type (e.g. 'INFLUENCED'). HubSpot-compat. |
+| `get_crm_objects` | compat | read | minimal, crm, migration, full | Batch read CRM records by ID. HubSpot-compat: max 100 IDs per request. |
+| `get_properties` | compat | read | minimal, crm, migration, full | Get full property definitions (types, enum options) for an object type. HubSpot-compat. |
+| `get_user_details` | compat | read | minimal, crm, migration, full | Get the authenticated user's account info, portal details, and OAuth scopes. HubSpot-compat tool. |
+| `hub_api_request` | hub | write | full | Raw HubSpot API request with safety controls |
+| `hubdb_publish` | hubdb | write | migration, full | Publish a HubDB table's draft state to live (dry-run by default unless force=true). Not available via HubSpot Remote MCP. |
+| `hubdb_row_create` | hubdb | write | migration, full | Create a row in a HubDB draft table (dry-run by default unless force=true). Call hubdb_publish to publish. Not available via HubSpot Remote MCP. |
+| `hubdb_row_update` | hubdb | write | migration, full | Update a HubDB row in the draft table (dry-run by default unless force=true). Not available via HubSpot Remote MCP. |
+| `hubdb_rows_list` | hubdb | read | migration, full | List rows in a HubDB table. Not available via HubSpot Remote MCP. |
+| `hubdb_tables_list` | hubdb | read | migration, full | List HubDB tables. Not available via HubSpot Remote MCP. |
+| `hubspot_module_compose` | modules | read | migration, full | Compose a widget body for a HubSpot drag-and-drop module using given field values. Validates the values against the module's fields.json schema before returning — rejects unknown fields and type mismatches. The returned widget is ready to drop into an email or CMS page's content.widgets[widgetId], with the schema + metadata HubSpot's renderer expects. Use this instead of hand-shaping widget bodies. |
+| `hubspot_module_describe` | modules | read | migration, full | Return the full field schema for a HubSpot drag-and-drop module (the same schema a user sees when clicking a module in the editor). Fields include name, label, type (text, richtext, number, boolean, color, choice, group, image, link, ...), required flag, default, choices, and nested children for groups. Call this before hubspot_module_compose to know what fields to pass. |
+| `hubspot_module_list` | modules | read | migration, full | Enumerate @hubspot/* built-in drag-and-drop modules available on the caller's portal. Each entry reports whether fields.json resolves (i.e. whether the module can be used in widgets). Useful for discovery — call hubspot_module_describe on any available entry to see its field schema. |
+| `manage_crm_objects` | compat | write | crm, migration, full | Create, update, or DELETE CRM records. HubSpot-compat surface extended with 'delete' — policy-file + change-ticket still enforced server-side. Bulk max 100 records per call. |
+| `marketing_emails_get` | marketing | read | migration, full | Get one marketing email by ID. Not available via HubSpot Remote MCP. |
+| `marketing_emails_list` | marketing | read | migration, full | List marketing emails. Not available via HubSpot Remote MCP. |
+| `marketing_emails_statistics` | marketing | read | migration, full | Get statistics for a marketing email. Not available via HubSpot Remote MCP. |
+| `reporting_dashboards_get` | reporting | read | migration, full | Get an analytics report/dashboard by ID |
+| `reporting_dashboards_list` | reporting | read | migration, full | List analytics reports/dashboards with pagination |
+| `sales_sequences_enrollments` | sales | read | migration, full | Get enrollments for a sales sequence |
+| `sales_sequences_get` | sales | read | migration, full | Get a sales sequence by ID |
+| `sales_sequences_list` | sales | read | migration, full | List sales sequences with pagination |
+| `search_crm_objects` | compat | read | minimal, crm, migration, full | Search CRM records by filter groups, text query, sorts, and pagination. HubSpot-compat: accepts the same filterGroups/query/sorts/properties/limit/after shape as HubSpot Remote MCP. |
+| `search_owners` | compat | read | minimal, crm, migration, full | Find CRM owners by email or ID, or list all. HubSpot-compat: max 100 results. |
+| `search_properties` | compat | read | minimal, crm, migration, full | Keyword-search property definitions for an object type. HubSpot-compat: max 5 keywords. |
+| `webhooks_create_subscription` | webhooks | write | migration, full | Create a webhook subscription (dry-run by default unless force=true). Not available via HubSpot Remote MCP. |
+| `webhooks_delete_subscription` | webhooks | delete | migration, full | Delete a webhook subscription (dry-run by default unless force=true). Not available via HubSpot Remote MCP. |
+| `webhooks_list_subscriptions` | webhooks | read | migration, full | List webhook subscriptions for a HubSpot app. Not available via HubSpot Remote MCP. |
+| `workflows_enroll` | workflows | write | migration, full | Enroll a contact into a legacy v3 workflow (dry-run by default unless force=true). Not available via HubSpot Remote MCP. |
+| `workflows_get` | workflows | read | migration, full | Get one workflow by flowId (v4). Not available via HubSpot Remote MCP. |
+| `workflows_list` | workflows | read | migration, full | List workflows (v4). Not available via HubSpot Remote MCP. |
+| `workflows_unenroll` | workflows | read | migration, full | Remove a contact from a legacy v3 workflow (dry-run by default unless force=true). Not available via HubSpot Remote MCP. |
+

package/docs/MIGRATION_ADAPTERS.md

@@ -0,0 +1,115 @@
+# Migration Adapters
+
+This page captures the migration gaps that surfaced during a large HubSpot
+portal mirror and how hscli should handle them in future runs.
+
+## Upstreamed into hscli
+
+- Read-only profiles now support HubSpot read endpoints that use `POST`
+  payloads, such as CRM search, batch-read, lists search, CMS batch-read,
+  communication-preference status batch-read, and association batch-read.
+- Standard CRM objects expose batch create/update/upsert/archive flows.
+- Custom object records expose batch read/create/update/archive flows.
+- CRM association replay has `crm associations batch-read` and
+  `crm associations batch-create`, including explicit v4 association types.
+- Custom object schema PATCH fails early when the payload contains
+  `properties`; use `crm properties batch-create <objectType>` instead.
+- Property batch-create accepts source property dumps and removes common
+  migration hazards: HubSpot-defined/read-only definitions, known reserved
+  names, blank enum options, empty enums, and label/name collisions.
+- Owner-reference properties keep `referencedObjectType` and automatically add
+  `externalOptions: true`, which HubSpot requires for referenced options.
+- Forms can translate legacy v2 payloads into v3 payloads, split oversized
+  field groups, preflight missing target properties, and remap consent
+  subscription type IDs.
+- Business units can be captured through the internal browser-session endpoint
+  when the public settings endpoint is unavailable.
+- Business units can be created through the internal browser-session endpoint
+  with `--skip-existing`, which removes the need for DevTools snippets in the
+  common sandbox replay path.
+- Permission sets can be listed/read/created/updated/deleted/cloned through the
+  internal browser-session endpoint.
+- Permission-set assignments can be captured from app-users payloads and applied
+  through the allowlisted Chirp RPC
+  `/api/chirp-frontend-app/v1/gateway/com.hubspot.appusers.rpc.PermissionSetAssignmentsRpc/assignUserToPermissionSets?portalId={portalId}`
+  with `assignments: [{ userId, permissionSetIds }]`. Use
+  `settings permission-sets users assign` for a single user, or
+  `settings permission-sets users assign-batch --data <payload>` to replay the
+  native `assignments[]` body for one or more users.
+- Permission migration can also capture the atomic role catalog, role
+  categories, scope buckets, seat catalog, user seat assignments, and permission
+  templates through the `settings permission-sets *` internal adapters.
+- Permission access audit capture can use the app-user audit Chirp RPCs for
+  permission-set assignment history, role change history, and per-user access
+  audit evidence. Keep these as capture/audit adapters; do not expose them as a
+  generic internal RPC passthrough.
+- Full workflow definitions can be captured through
+  `/api/automationplatform/v1/hybrid/{flowId}`, including actions, branches,
+  triggers, goals, and output metadata.
+- Brand kits, colors, logos, favicons, fonts, and brand voice metadata can be
+  captured through `/api/branding/v1/*` internal browser-session endpoints.
+- Drag-and-drop marketing emails can be captured through `/api/cosemail/v1/*`,
+  including layout/theme/flex-area/body metadata.
+- New CTA builder placements can be captured through `/api/ctas/v3/placements`.
+- Design Manager templates, themes, modules, and layouts can be captured
+  through `/api/designmanager/v1/*`.
+- CMS content v2 pages/templates, site settings, global groups, built-in module
+  mappings, and content-portal-copy job status are included in the internal
+  backup allowlist for downgrade/migration evidence.
+- Non-email subscription types can be captured through
+  `/api/email/public/v1/subscriptions`.
+- Subscription visibility rules, privacy/GDPR settings, and business-unit
+  display maps can be captured through allowlisted subscription Chirp RPCs.
+- CRM UI search, CRM GraphQL, object preview, and single-object UI payloads are
+  available through the `crm-search` internal capture surface for report/help
+  desk/quote/index fidelity checks.
+- List/segment capture now includes list v3, list v2, contacts-list,
+  contact-list-management, ILS segment, segments UI, and legacy segment-search
+  fallbacks because HubSpot's list APIs are fragmented across portals.
+- Social broadcasts and connected social accounts can be captured through
+  `/api/broadcast/v2/*`; ads account/UI metadata is read-only Chirp RPC only.
+- Browser-session adapters share one guarded resolver: `--ui-domain` must be a
+  HubSpot app host, and Netscape/JSON cookie exports are filtered to that host
+  so unrelated cookies are not forwarded.
+- Browser-session adapters prefer the `hubspotapi-csrf` cookie value for the
+  `X-HubSpot-CSRF-hubspotapi` header. This is the modern internal-CSRF pattern;
+  `csrf.app` remains accepted for older surfaces.
+- User creates suppress invite/welcome emails by default. Passing
+  `--allow-invite-email` is required before hscli will allow payloads such as
+  `sendWelcomeEmail:true`.
+- `crm migration id-map apply` remaps local batch payload fields without making
+  HubSpot calls, which is the default path for owners, teams, business units,
+  custom object type IDs, and other source-to-target IDs.
+
+## Still Adapter-First
+
+These surfaces are supported by migration-specific adapters or manual review
+until their endpoint behavior is stable enough to promote to first-class CLI
+commands:
+
+- Team-assignment flows, especially when super admins must be left untouched.
+- Team creation/update. The public team API is read-only on many portals, so
+  creation stays adapter-first until the internal endpoint contract is proven.
+- Workflow full replay and activation. Capture is now much stronger via the
+  hybrid internal endpoint, but a safe replay still needs an adapter that remaps
+  action references, strips/replaces send-email actions for sandbox safety,
+  lands workflows disabled, and performs a two-pass workflow ID remap.
+- Subscription type replay through internal subscription-definition endpoints
+  when public communication-preference definitions are incomplete for
+  brand-scoped portals. Non-email channels are now capturable, but channel-safe
+  write adapters still need sandbox confirmation.
+- Reports, dashboards, datasets, playbooks, sequences body, and some sales-email
+  assets. These are UI-only or internal-only on many portals and should stay
+  documented as non-public migration exceptions unless endpoint coverage is
+  proven.
+- Static list membership replay for large datasets. Use hscli for list CRUD and
+  membership operations, but rely on a migration adapter for batching, source
+  filtering, dependency ordering, and explicit skip policies for out-of-scope
+  lists.
+
+## Operator Rule
+
+Prefer hscli first for every read/write path. If a browser-session/internal
+adapter is required, keep it explicit, scoped to one migration phase, rate
+limited, idempotent, and backed by an id-map or verifier output that hscli can
+consume later.