@revfleet/hscli 0.8.12 → 0.9.0

package/docs/PORTAL_BACKUP.md

@@ -0,0 +1,212 @@
+# Portal Backup
+
+Use `hscli /backup` to start from intent, then `hscli backup plan` when a
+HubSpot portal needs to be preserved before a downgrade, migration,
+consolidation, or forensic audit.
+
+The command is plan-only. It does not call HubSpot and it does not write local
+files. It renders a public-API-first runbook plus an explicit internal API
+capture brief for browser-session tools such as a Claude extension.
+When `--include-internal` is set, it also renders an `internalCapturePlan`
+section with executable `hscli internal capture` commands derived from the
+versioned internal allowlist.
+
+See [`INTERNAL_ENDPOINTS.md`](./INTERNAL_ENDPOINTS.md) for the condensed
+allowlisted browser-session endpoint map. The full catalogue and discovery log
+live in [`INTERNAL-ENDPOINTS.md`](./INTERNAL-ENDPOINTS.md) and
+[`INTERNAL-ENDPOINTS-DISCOVERY.md`](./INTERNAL-ENDPOINTS-DISCOVERY.md).
+
+```bash
+hscli --profile source-readonly backup plan \
+  --portal-id "$PORTAL_ID" \
+  --out-dir "$HOME/client-migration-assets/portal-$PORTAL_ID-full-backup" \
+  --include-internal \
+  --snapshot-id "portal-$PORTAL_ID-full-backup" \
+  --json
+```
+
+## Safety Model
+
+- Source profiles must be set to read-only before capture.
+- The plan never includes `--force` in executable commands.
+- Public API capture comes first.
+- Browser-session capture is explicit and allowlisted.
+- `backup plan` is the orchestrator; `internal capture` is the adapter that
+  executes only the allowlisted read/read-like internal endpoints.
+- `hscli internal capture` turns allowlisted catalogue surfaces into concrete
+  read-only JSON captures. It is not a generic internal API passthrough.
+- The internal capture allowlist is versioned in
+  `src/commands/internal/catalog.ts`; add endpoints there with tests before
+  relying on them in a client backup.
+- Internal capture should stay GET-only, except documented read-only search or
+  preview POST calls where the request body is saved.
+- Backup assets must stay outside the hscli git repository.
+- `migration/` is ignored because local capture data is client data.
+
+## HubSpot 360 Coverage
+
+The JSON output includes a `coverageModel` with explicit domain coverage:
+
+- account identity, private apps, API usage, and audit logs
+- CRM records, custom objects, properties, pipelines, association labels, and
+  engagements
+- marketing assets, campaigns, forms, lists, subscription types, email
+  fallbacks, and consent surfaces
+- sales, service, CMS, commerce, files, operations, automation, reporting,
+  settings, integrations, and governance
+- UI-only surfaces such as business units, permission sets, custom views,
+  datasets, dashboard layouts, report filters, and full workflow action graphs
+
+The plan should not pretend that public APIs cover everything. Public API
+capture comes first; browser-session/internal capture then documents the
+remaining HubSpot UI-only surfaces and blockers.
+
+## What the Plan Captures
+
+Public API capture:
+
+- account info, private apps, API usage
+- users, teams, owners, currencies
+- CRM schemas, property groups, properties, pipelines, stages
+- association labels
+- lists, forms, workflows, marketing emails, campaigns
+- sales sequences, meetings, calling, goals
+- service conversations, feedback submissions, chatflows, ticket pipelines
+- CMS pages, blogs, HubDB tables, redirects, domains, audit logs, SEO audit
+- files and file folders
+- communication preferences
+- public reporting/dashboard inventory
+- records smoke-test commands for standard CRM objects
+
+Internal/browser-session capture brief:
+
+- business units
+- full app-users payloads
+- permission sets
+- permission-set assignments, atomic role catalog, role categories, scope
+  buckets, permission templates, seat catalog, and seat assignments
+- datasets, SQL reporting metadata, reportable sources, and join metadata
+- reports, report history/audit, dashboard definitions, dashboard permissions,
+  widgets, report favorites, report templates, reporting-frontend report lists,
+  and report-list views when public APIs omit details
+- custom views, pinned views, CRM index views, visualization settings, and UI
+  search snapshots
+- full workflow hybrid definitions, action graph details, validation output,
+  action catalog, CRM object snapshots, canvas errors, access checks,
+  filter-description previews, card positions, and bulk-processing metadata
+- property v4 metadata, v1/v2 legacy fallbacks, property groups, grouped
+  property listings, recycled properties, quota/count metadata, fill-rate
+  snapshots, validation constraints, conditional options, and conditional rule
+  RPC reads
+- CRM search, CRM GraphQL, object preview, and single-object UI payload helpers
+  used by report builders, quotes, help desk, and object index pages
+- list/segment definitions from overlapping list v3, list v2, contacts-list,
+  contact-list-management, ILS segment, segments UI, and legacy segment-search
+  surfaces
+- per-object audit logs for lists, dashboards, reports, and workflows
+- field-level permissions and report permissions
+- field-level permission bypass users
+- marketing email body/settings fallbacks
+- all communication subscription channels, including non-email definitions
+- brand kits, brand colors, logos, favicons, fonts, and brand voice metadata
+- internal marketing-email definitions from `cosemail`, including
+  drag-and-drop layout/theme/flex area metadata
+- CTA placements from the new CTA builder
+- Design Manager templates, content v2 templates/pages, themes, modules,
+  layouts, global groups, built-in module mapping, site settings, and
+  content-copy job status
+- social broadcasts, connected social channels, and read-only ads account/UI
+  metadata RPCs
+- sales snippets with body/htmlBody and shortcut metadata
+- sequence usage/health, sales template bodies/usage, playbook count/version,
+  and playbook question metadata
+- payment-account eligibility and connected-account status
+- schema/object metadata, portal-scoped object types, event object types, and
+  framework-builder UI metadata
+- allowlisted read-only Chirp RPC fallbacks for metadata services only
+
+## Downgrade Checklist
+
+1. Render the plan.
+2. Create the output directory outside the repo.
+3. Set the source profile to read-only.
+4. Start a trace/no-write log.
+5. Run public metadata capture.
+6. Run public record capture until each object has no next cursor.
+7. Run `hscli internal surfaces` and `hscli internal capture --all` with an
+   authenticated HubSpot browser session.
+8. Produce `capture-manifest.json`.
+9. Verify the no-write log contains only GET and approved read-only POST calls.
+10. Scan the archive for secrets before sharing it.
+
+## Claude / Browser-Session Handoff
+
+The `claudeExtensionBrief` field in the JSON output is designed to be pasted
+directly into a browser-session agent. It includes the portal ID, output
+directory, no-write rule, required endpoints, optional endpoints, and logging
+requirements.
+
+Prefer the native hscli capture adapter first:
+
+```bash
+hscli --profile source-readonly --json internal surfaces
+hscli --profile source-readonly --json internal capture \
+  --all \
+  --portal-id "$PORTAL_ID" \
+  --cookie-file "$HUBSPOT_COOKIE_FILE" \
+  --out-dir "$OUT_DIR/internal-api/allowlisted-capture"
+```
+
+For large or sensitive portals, prefer the surface-by-surface commands emitted
+by `backup plan`:
+
+```bash
+hscli --profile source-readonly --json backup plan \
+  --portal-id "$PORTAL_ID" \
+  --include-internal \
+  --out-dir "$OUT_DIR" \
+  > "$OUT_DIR/backup-plan.json"
+
+# Then copy reviewed commands from:
+#   internalCapturePlan.surfaceCommands
+#   internalCapturePlan.parameterizedExamples
+```
+
+When a surface contains a read-only POST that needs a specific request body,
+capture it explicitly instead of guessing:
+
+```bash
+hscli --profile source-readonly --json internal capture \
+  --surface permission-access \
+  --endpoint app-users-batch \
+  --portal-id "$PORTAL_ID" \
+  --cookie-file "$HUBSPOT_COOKIE_FILE" \
+  --body-file app-users-batch="$OUT_DIR/internal-api/bodies/app-users-batch.json" \
+  --out-dir "$OUT_DIR/internal-api/permission-access"
+```
+
+The body file is parsed as JSON, redacted into
+`<endpoint>.request.json`, and hashed in `capture-manifest.json`. This keeps
+Claude/browser-session captures reproducible without turning hscli into a
+generic internal API client.
+
+Use a browser-session agent for endpoints that need user interaction, per-asset
+request bodies, or feature-gated pages that the generic allowlisted capture
+cannot parameterize safely.
+
+If an endpoint returns `401`, `403`, or `404`, document the blocker and continue.
+Do not modify source permissions or retry write-like endpoints during backup.
+
+For HubSpot internal browser-session endpoints, prefer the `hubspotapi-csrf`
+cookie value as the `X-HubSpot-CSRF-hubspotapi` header. `csrf.app` is accepted
+for older internal surfaces, but many modern endpoints require
+`hubspotapi-csrf`.
+
+The internal endpoint catalog is intentionally generic. Do not paste client
+portal IDs, session IDs, browser cookies, CSRF tokens, or raw migration files
+into hscli docs or commits. Keep that material in the local backup archive only.
+
+Read-only POST endpoints are allowed only for search, preview, batch hydration,
+or metadata RPC calls where HubSpot uses POST for reads. Log the request body
+hash and save the exact body next to the response so the no-write proof remains
+auditable.

package/docs/PUBLISHING.md

@@ -14,7 +14,7 @@ How to cut a new release of `@revfleet/hscli` on npm. Written for the maintainer
 ### 1. Land all changes on a feature branch
 
 ```bash
-cd /Users/louisv/Pro-Desktop/Projets/hscli-main
+cd /path/to/hscli
 git checkout -b <branch-name>
 # ... commits ...
 git push -u origin <branch-name>