Skip to content

feat: first release, HubSpot CRM sync, read-only api, token sign-in - #1

Merged
leemour merged 18 commits into
mainfrom
feat/first-release
Nov 17, 2026
Merged

leemour merged 18 commits into
mainfrom
feat/first-release

Conversation

@leemour

@leemour leemour commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

The first release of @wirecat/hubspot-cli (command hubspot, env prefix WCHUBSPOT_), made with new from cli-template 0.25.0 on cli-core 0.687.0 and cli-base 0.109.0.

What it does

  • Sign-in with a HubSpot service key, or an existing legacy private app's token, read hidden or from stdin. It is checked against GET /account-info/2026-03/details and kept with the account's id in the keyring. WCHUBSPOT_TOKEN needs WCHUBSPOT_ACCOUNT beside it, and every online command checks the two match.
  • CRM through cli-core's addCrmCommands, like bitrix24-cli and amo-cli:
    • sync of deals, contacts, companies, leads, activities (notes, calls, e-mails, meetings, tasks), owners, pipelines and properties into the shared store;
    • live reads of people, organizations and users.
    • Change rounds are built from search by modified time. Search answers carry no associations, so they are read in batches.
  • api: 157 operations generated from 15 HubSpot CRM specs (version 2026-03), merged by cli-base mergeOpenApi. It is read-only in this release: writes are listed as excluded.
  • Rate limits: 240 requests a minute per account. A daily 429 holds until midnight in the account's time zone, and is never retried in a loop.
  • Setup in the terminal and in WireCat Desktop, from one wirecat.setup JSON document (hubspot <profile> setup show --json), in en, es and ru.

Checks

  • pnpm ci:quick passes.
  • pnpm test passes: 16 files, 198 tests, including crmSourceContract and crmSyncContract over every trait combination.
  • cli-dev ready: verified for every row except the live check.
    • crmWriteContract is excepted in lint/contract-exceptions.json, because this release writes nothing.
  • The live check waits for a HubSpot developer test account (owner).

Review

Five rounds by fresh agents, each reviewing the previous round's diff. 42 findings, all fixed. The main ones:

  • api allowed writes without asking; it is now read-only.
  • Batch reads counted as reads, not writes.
  • ids() paging was untested; it now has tests.
  • Activities past HubSpot's 10,000 search cap were lost.
  • A daily 429 handling bug, then the api budget.
  • Pace is now per account.
  • WCHUBSPOT_ACCOUNT is checked against the key.
  • Lead stage mapping.
  • gitleaks rules for HubSpot keys.
  • A negative wait near a midnight skipped by daylight saving.

Measurement

cli-testing#382: 2,340 hand-written source lines against 4,148 comparable lines in bitrix24-cli and 5,026 in amo-cli. On the plan's own bitrix24 baseline, that is 31 % less.

🤖 Generated with Claude Code

Conformance

  • Live check: 0.0.0 9480090b3333018d432eb67d37d8182ac42cb620 2026-11-17 scripts/live.sh v2:8144cc08e1797e227f4616078c55339b74d7b6a73cfbdaf1533ffd977eb2f61f
  • Live check: 0.0.0 e45c62a560f2a806827dd66f417727acbc594264 2026-11-17 scripts/live.sh v2:222d1eec23dcc38f409028642d4555014138cd48485342403719d2083da26488

leemour and others added 18 commits November 17, 2026 03:09
- spec/hubspot: contacts, companies, deals, tickets, leads, notes, calls,
  emails, meetings, tasks, owners, pipelines, properties, associations and
  account info, merged by mergeOpenApi.
- The associations spec names three shared operations after 2025-09; a
  per-source patch gives them the object specs' ids so the merge takes the
  path once.
- Names from the paths, 0-3 as deals; permission groups in cli-core's CRM
  words (people, organizations, deals, leads, users, fields).
- batch/archive, labels/archive, gdpr-delete and merge are destructive.
- Sign-in: Bearer private app token or service key.
- Env prefix WCHUBSPOT_ (HUBSPOT_ is read by HubSpot's own tools, NEED-2710).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…en sign-in

- src/hubspot: transport (Bearer token, 429 DAILY waits to the account's
  midnight, pace under 100/10 s and search's 5/s), account details.
- src/crm: hubspotCrmSource. Full rounds list by after; change rounds search
  by modified time with a 10 min overlap and reset past 10 000 results;
  deletions by ids(); owners, properties, pipelines, live people and
  organizations, activities from notes, calls, e-mails, meetings and tasks.
  Leads refused by scope are a gap, not a failure.
- crmSourceContract with its fault cases and crmSyncContract over
  CRM_TRAIT_COMBINATIONS against a strict fake built on fakeApi.
- session start reads a private app token or service key from stdin, checks
  it with account details and keys the account by portalId; a second profile
  on the same portal is refused.
- addCrmCommands, store provider, config, program, setup flow, schedule and
  docs in the shape of amo-cli and bitrix24-cli; read-only, no OAuth yet.
- The search request schema follows HubSpot's search guide (after optional,
  sorts as objects).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…only contract exception

- remove-sample: the comments sample, its fake and tests; contracts, MCP
  catalogue and docs regenerated.
- src/commands/api.ts hands the environment's clock and sleep to the pacer
  and retrying, so its test never waits for real.
- tsconfig includes the setup flow's JSON texts.
- lint/contract-exceptions.json: crmWriteContract, since this release has
  no CRM writes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
They read records by ids in the body; marked write, they would ask and
count as writes in the api group and over MCP.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ging, cli-core's providerCall

- api keeps only reads; api show names why a write is missing. Errors map
  through failureOf: a 403 names the scope, a DAILY 429 waits to the
  account's midnight and is never sent again.
- ids() pages by the source's page size; tests cover a deletion on page 2.
- Activities past 10 000 at one moment list the type in full instead of
  losing rows; paging and overlap are tested.
- The transport is built on cli-core's providerCall: reads retried, writes
  never; 10 s timeout, 20 s longest pace wait; HubSpot's category in the run
  record; hosts from DESKTOP.hosts.
- The daily-limit midnight comes from the account's IANA time zone via Intl.
- Pace by account (account-<portalId>), requestMs 500.
- A deal's company is the primary one (association type 5); leads' created
  date from createdate or hs_createdate; closed lead stages without a
  documented outcome are lost; call statuses CONNECTING and
  CALLING_CRM_USER are not done; company type filter.
- 403 reads missingScopes and requiredGranularScopes; a 400 never echoes
  HubSpot's message; property lists in GET addresses capped with a gap.
- gitleaks rules for HubSpot keys, phones and e-mails; session answers
  kind: token; DESIGN.md's First task section removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…CCOUNT, tests that can fail

- api's retrying has the 20 s budget, so after a DAILY 429 the next command
  refuses at once instead of sleeping to midnight.
- WCHUBSPOT_TOKEN needs WCHUBSPOT_ACCOUNT, as amo's AMO_TOKEN needs AMO_HOST;
  api and CRM commands share the account's pace; no account-info request
  on store-only reads.
- Lead stages: HubSpot documents only open or closed; a closed stage is
  lost when it is the documented Disqualified stage, else won.
- Doc links for call, e-mail, meeting and task statuses and association
  type ids; SCHEDULED is not a documented call status.
- Tests for refused change rounds, a list without results, the round's end
  cursor, the property cap's gap, the 20 s pace wait, the 10 s timeout and
  the host list.
- session.unreadable from cli-core; user: null in account answers; gitleaks
  matches every HubSpot region; changelog entries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… stages by id, daily hold without a time zone

- A run with WCHUBSPOT_TOKEN asks HubSpot whose key it is before it opens
  the store for writing, and refuses a WCHUBSPOT_ACCOUNT that differs
  (account.mismatch); a store-only read before any checked sync refuses
  (account.unchecked); a non-numeric id has its own reason. session status
  --check works with the key alone and names the account id.
- Closed lead stages: probability, then HubSpot's default stage ids, then
  the English names; any other closed stage counts as lost with a gap.
- Without the account's time zone, a spent daily allowance holds the
  account only to the next quarter hour of UTC, the earliest reset in any
  zone, and says so.
- Tests: lead stage outcomes incl. a Spanish portal, meeting outcome in
  lower case, account mismatch before any store write.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…N, the account's time zone kept

- A command that reaches HubSpot checks the key's account once and keeps
  its time zone for the daily limit; people, organizations and users list
  work on a fresh store.
- An offline local write (store apply --offline) sends nothing and takes
  only the account a checked run saved.
- Without any time zone, a spent daily allowance holds to the next real
  midnight among the zones Intl knows.
- Test: a default lead stage id wins over its label.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…lback tests

- The wait to midnight keeps the offset change only when it lands on the
  new day; a midnight that summer time skips (Santiago, Cairo, Havana,
  Beirut, Azores) no longer gives a negative wait and an instant retry.
- The no-zone search reads offsets directly, so an unknown zone cannot
  recurse; formatters are cached per zone.
- crm-shared: dead conditions dropped; tests that --offline is refused
  before any check and that store status after a sync sends nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s closed to new ones

HubSpot's service key guide lists the steps: Development → Keys → Service keys,
Create service key, Add new scope, Update, Create, then Show and Copy. Some
accounts show it under Settings → Integrations instead (HubSpot changelog). New
private apps cannot be created since 2026-10-26; existing tokens still work.
The setup flow (terminal and WireCat Desktop, from setup show --json) and
docs/installation.md now say this, in en, es and ru.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-disk do

CI's check failed on coverage only (198 tests pass): the generated api types in
src/generated/schemas.ts were at 54% of lines and 5% of functions. The family
leaves generated code out (notion-cli, gcal-cli, yandex-disk-cli), and
cli-template's own fix (6630208) is not released yet. With it: lines 95.97%,
statements 94.17%, functions 93.41%, branches 83.1%.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CI's test matrix found 272 commands and options no test ran. Now 0 missing:
- src/api.test.ts sends every operation once more with all its options, the
  body from --body-file, and --all on each paged list (the fake repeats its
  cursor, so --all must stop with provider.invalid-response, not loop);
  api list shows reads only.
- src/commands/crm-options.test.ts runs every option of the shared CRM
  commands against the fake account, after amo's crm-options test.
- src/schedule.test.ts is amo's in full: digest, list and remove, no token in
  the files, read-only refusals, exec and run, the kept environment.
- src/setup/flow.test.ts: apply --dry-run, apply, show.
- The sandbox gives each test its own state folder and store and clears
  WCHUBSPOT_TOKEN and WCHUBSPOT_ACCOUNT, as amo's does.
- store and schedule options cli-core owns carry amo's reasons.

pnpm release:check passes: 208 tests, lines 95.97%.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- README opens with docs/images/social-preview.png (1280x640, the shared
  style: command name in the gradient, tagline, "part of WireCat" footer),
  through its raw.githubusercontent.com URL so npmjs.com shows it too. The
  image text, the alt text and the README heading say the same thing
  (WC-DOC-21). Rendered with headless Chrome from the same HTML as b24's.
- Sections follow WC-DOC-7: quick start, what you can do, for AI agents,
  why hubspot, main features, sign-in and profiles, settings and
  permissions, limits, security, when something goes wrong, documentation,
  development.
- The quick start says the first release is not on npm yet and points to
  running from a clone. Remove that sentence when the release is on npm.
- mcp add now shows --allow-writes: without it the command refuses,
  because the server offers local writes such as sync and schedules.
- Docs links point at docs/ in the repository, since
  wirecat.dev/en/docs/hubspot does not exist yet. No npm badges until the
  package is published.
- package.json: description in the family's "CLI for AI agents" form, and
  keywords that match the repository topics.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…he first release

The note said to run hubspot from a clone, but a clone gives node dist/bin/hubspot.js,
not a hubspot command, and the note had to go at release anyway.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
HubSpot has no crm.objects.{notes,calls,meetings,tasks}.read scopes in its
key UI. On test account 149800303 a key with the contacts, companies and
deals scopes read notes, calls, meetings and tasks; e-mails answered 403
asking for sales-email-read (or crm.objects.emails.read). The setup flow,
README and installation page now ask for sales-email-read only, and an
activity gap names the scope that actually helps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leemour
leemour merged commit d5c6c18 into main Nov 17, 2026
17 checks passed
@leemour
leemour deleted the feat/first-release branch November 17, 2026 16:54
@leemour leemour mentioned this pull request Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant