Skip to content

feat(NB-3138): add hubspot:export-marketing command - #15

Merged
codelikesuraj merged 2 commits into
5.xfrom
feat/NB-3138-marketing-export
Oct 15, 2026
Merged

codelikesuraj merged 2 commits into
5.xfrom
feat/NB-3138-marketing-export

Conversation

@cannycookie

Copy link
Copy Markdown
Contributor

Summary

  • New hubspot:export-marketing command exports contacts, contact lists, list memberships, subscription definitions, per-email subscription statuses and spam-report events to a filesystem disk.
  • MarketingExportSource contract with SdkMarketingExportSource (hubspot/api-client 13.x). Bound lazily in HubspotApiServiceProvider, so tests bind a fake and need no credentials.
  • MarketingExporter writes files in a fixed order and the manifest last. Archived contacts are never requested ($archived = false). A false return from a throw => false disk raises RuntimeException.
  • New export config block (disk, directory, page_size, membership_page_size, contact_properties).
  • README section covering the command, required private-app scopes, output formats and the per-contact status call cost.

Companion neurohub change: marketing:import-hubspot (neurohub PR to feature/NB-3135-marketing-campaigns, linked from NB-3138).

Test plan

  • tests/Feature/ExportMarketingCommandTest.php: 7 tests (all files + manifest counts, mapping template, --skip-preferences, unavailable events warning, write failure, two-page cursor on the SDK source, status-loop failure keeps bulk files and no manifest)
  • Full package suite: 53 passed

After merge

A human tags the next minor on 5.x (currently 5.1.1, so 5.2.0). The neurohub branch then runs composer update visualbuilder/filament-hubspot --no-interaction. Tagging is deferred to a human, not done by the agent.

YouTrack

NB-3138

Tier: coding_complex

🤖 Generated with Claude Code

- MarketingExportSource contract with an SDK implementation (contacts, lists,
  memberships, subscription definitions and statuses, spam-report events)
- MarketingExporter writes JSON/JSONL files in a fixed order; manifest last
- ExportMarketingCommand with --disk, --dir, --skip-preferences, --skip-events,
  --property options; new `export` config block
- Archived contacts are never exported; write failures on throw=false disks
  raise a RuntimeException
- Fake source fixture and feature tests

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

@codelikesuraj codelikesuraj left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review notes (2026-10-15)

Checked against the approved NB-3138 plan and the installed hubspot/api-client 13.2.0. Every SDK call matches (getPage with archived=false, list search offset paging, membership cursor paging, preference definition and status APIs, apiRequest for spam events). Write order, streaming through php://temp, the === false write checks, the mapping template and the manifest all match the plan. Package suite: 53 passing.

Should fix

  1. src/Commands/ExportMarketingCommand.php:36: catch (Throwable) returns FAILURE without report($e). A failure hours into a production export leaves one console line and nothing in the log. Add report($e) before the error line.
  2. No CHANGELOG.md entry. Add ## 5.2.0 - unreleased / ### Added for hubspot:export-marketing, since a human tags it after merge.
  3. src/Export/SdkMarketingExportSource.php:76 (contactLists()) and the spam-events loop at :168: while (getHasMore()) with no guard against the same offset coming back, a known quirk of the legacy endpoints. Break when the offset does not advance.
  4. SdkMarketingExportSource.php:592-596: only ClientException (4xx) is caught on the first events page. A 5xx fails the whole run after the slow per-contact status loop has finished. Catch BadResponseException and distinguish "unavailable" from a logged failure.
  5. Test gaps in tests/Feature/ExportMarketingCommandTest.php: --skip-events, --disk/--dir/--property overrides, paging termination for lists and memberships, subscriptionStatuses() mapping an ApiException to error, spamReportEvents() returning null, and writeStream() === false.

Nits

  • MarketingExporter.php:267 and :378 call now() twice for the run directory and exported_at; capture once.
  • The local $report closure in MarketingExporter.php:269 reads like Laravel's report() helper.
  • The test file's global helpers (exportRunDir(), readJsonl(), readJson()) would collide with a second test file using the same names.

After merge: tag 5.2.0, then on the neurohub branch run composer update visualbuilder/filament-hubspot and commit the lock.

- log the failure before printing it, so a multi-hour run leaves a trace
- stop paging lists and spam reports when HubSpot repeats an offset
- treat a 5xx from the events endpoint as unavailable after logging it,
  instead of failing the run after the status loop has completed
- take one timestamp for the run directory and exported_at
- rename the progress closure so it does not read like report()
- changelog entry for 5.2.0
- tests: --skip-events, --property merging, --disk/--dir overrides,
  streamed-write failure, stalled offsets, events errors, preference errors
@codelikesuraj

Copy link
Copy Markdown
Collaborator

Review notes applied in 3fa357c:

  • The command logs the failure with report($e) before printing it.
  • contactLists() and the spam-report pages stop when HubSpot repeats an offset.
  • A 5xx from the events endpoint is logged and treated as unavailable instead of failing the run.
  • One timestamp for the run directory and exported_at; the progress closure is named $progressLine.
  • CHANGELOG entry under 5.2.0 - unreleased.
  • Tests: --skip-events, --property merging without duplicates, --disk/--dir overrides, a refused writeStream(), stalled offsets on lists and events, 4xx/5xx on the events endpoint, a preference API error mapped onto the status row. Package suite: 61 passing.

@codelikesuraj
codelikesuraj merged commit f5f782b into 5.x Oct 15, 2026
7 checks passed
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.

2 participants