feat(billing): emit subscription_changed analytics on plan change (guarded by AnalyticsService.isConfigured)

[PierreBrisorgueil]

Summary

• Add AnalyticsService.isConfigured() to lib/services/analytics.js — returns client !== null; cheap pre-check for callers that want to skip payload construction when PostHog is not active.
• In handleSubscriptionUpdated (billing.webhook.service.js): emit subscription_changed analytics event after plan.changed fires, carrying previousPlan/newPlan/isDowngrade. Guarded by isConfigured() — downstreams without PostHog get a clean no-op. Non-fatal try/catch ensures analytics never disrupts webhook processing.
• New unit test: 5 cases covering plan-change capture, isDowngrade flag, no-op when not configured, no emit on same-plan event, no emit on stale event.

Why devkit-level

AnalyticsService is a devkit-level abstraction (Node #3640/#3653 PostHog integration). The subscription_changed emit is generic — any downstream with PostHog configured gets Stripe plan-change visibility automatically after /update-stack. The isConfigured() guard makes it safe for downstreams without PostHog.

Why now

This restores trawl observability that was correctly dropped by /update-stack #1316 (devkit shouldn't carry trawl-specific code), now promoted to devkit so every downstream benefits.

Safety

• isConfigured() guard: capture is skipped entirely when PostHog client is not initialised.
• Non-fatal try/catch: analytics failure cannot disrupt webhook processing.
• Placed after billingEvents.emit('plan.changed', ...) — no change to existing plan-change flow.

Cross-ref

• Closes feat(billing): promote subscription_changed analytics emit upstream to devkit #3768
• Regression source: trawl /update-stack build(deps): bump chalk from 4.1.0 to 4.1.1 #1316
• Trawl follow-up: comes-io/trawl_node#1315
• Infra alignment plan: 2026-06-01-trawl-promote-up-followups.md Task 5

Test plan

• NODE_ENV=test npm run test:unit -- modules/billing/tests/billing.webhook.subscription-changed-analytics → 5/5 pass
• NODE_ENV=test npm run test:unit -- modules/billing/tests/billing.webhook → full webhook suite green
• CI green

[coderabbitai]

Warning

Review limit reached

@PierreBrisorgueil, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 56 minutes and 12 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: b5434172-663f-46fc-80c7-2667d0ba0ea1

📥 Commits

Reviewing files that changed from the base of the PR and between 11ab4b7 and 494445d.

📒 Files selected for processing (3)

• lib/services/analytics.js
• modules/billing/services/billing.webhook.service.js
• modules/billing/tests/billing.webhook.subscription-changed-analytics.unit.tests.js

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/promote-subscription-changed-analytics

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 66.66667% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.11%. Comparing base (7ed5291) to head (494445d).
⚠️ Report is 5 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff             @@
##           master    #3769       +/-   ##
===========================================
+ Coverage   59.43%   90.11%   +30.67%     
===========================================
  Files         151      151               
  Lines        4970     4976        +6     
  Branches     1577     1579        +2     
===========================================
+ Hits         2954     4484     +1530     
+ Misses       1491      387     -1104     
+ Partials      525      105      -420     

Flag	Coverage Δ
integration	59.40% <33.33%> (-0.04%)	⬇️
unit	68.95% <66.66%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7ed5291...494445d. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

This PR extends the devkit analytics abstraction to support a cheap “configured?” pre-check, and uses it in the billing Stripe webhook to emit a subscription_changed PostHog event when a subscription’s plan changes. It also adds a dedicated unit test suite to validate the analytics emit behavior around plan changes.

Changes:

• Add AnalyticsService.isConfigured() (PostHog client initialised check) to allow callers to skip payload construction when analytics is disabled.
• Emit subscription_changed analytics from handleSubscriptionUpdated when previous_attributes.items indicates a plan change (including previousPlan, newPlan, isDowngrade).
• Add unit tests covering capture/no-op scenarios and downgrade detection.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
lib/services/analytics.js	Adds isConfigured() helper and exports it on AnalyticsService.
modules/billing/services/billing.webhook.service.js	Emits subscription_changed analytics event on plan change (guarded by isConfigured()).
modules/billing/tests/billing.webhook.subscription-changed-analytics.unit.tests.js	Adds new unit test suite for the plan-change analytics emit behavior.