chore(shared,ui): Add telemetry event for flow steps

[LauraBeatris]

Description

This PR adds a new telemetry event to track when a flow step gets mounted, so we can leverage it on multi step flows such as self-serve SSO.

We want to leverage those events to later query the average time between when the user lands on the first step and actually ends up activating the connection.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features

  • Introduced a new generic FLOW_STEP_MOUNTED telemetry event builder to support measuring multi-step flow funnels.
  • Added telemetry capture to the self-serve SSO flow, recording when key steps mount or complete, including timestamps, connection status, and relevant identifiers.

• Chores

  • Enhanced telemetry tracking for SSO configuration workflows to improve system observability and monitoring.

[changeset-bot]

🦋 Changeset detected

Latest commit: c2212d3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Patch
@clerk/ui	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/vue	Patch
@clerk/swingset	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 22, 2026 7:49pm
swingset	Ready	Preview, Comment	Jun 22, 2026 7:49pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 6c52bdda-b596-4ed0-9018-26af5dbf35f0

📥 Commits

Reviewing files that changed from the base of the PR and between 8377b13 and c2212d3.

📒 Files selected for processing (4)

• .changeset/gold-ends-throw.md
• packages/shared/src/telemetry/events/flow-step.ts
• packages/ui/src/components/ConfigureSSO/steps/ActivateStep.tsx
• packages/ui/src/components/ConfigureSSO/steps/OrganizationDomainsStep.tsx

✅ Files skipped from review due to trivial changes (1)

• .changeset/gold-ends-throw.md

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/ui/src/components/ConfigureSSO/steps/ActivateStep.tsx
• packages/ui/src/components/ConfigureSSO/steps/OrganizationDomainsStep.tsx

---

📝 Walkthrough

Walkthrough

Adds a new eventFlowStepMounted telemetry event builder in the shared telemetry package and integrates it into two ConfigureSSO step components: ActivateStep emits the event after a successful connection activation, and OrganizationDomainsStep emits it once on mount via a useRef-guarded useEffect. Both events capture organization and connection identifiers for flow funnel tracking.

Changes

Flow Step Telemetry

Layer / File(s)	Summary
eventFlowStepMounted helper and export packages/shared/src/telemetry/events/flow-step.ts, packages/shared/src/telemetry/events/index.ts	Defines the FLOW_STEP_MOUNTED event name constant, default sampling rate, EventFlowStepMounted payload type (flow, step, metadata, plus additional fields via intersection), and the eventFlowStepMounted builder function. Re-exports from the telemetry events barrel.
Telemetry recording in ActivateStep and OrganizationDomainsStep packages/ui/src/components/ConfigureSSO/steps/ActivateStep.tsx, packages/ui/src/components/ConfigureSSO/steps/OrganizationDomainsStep.tsx	ActivateStep calls useClerk and useOrganization and emits eventFlowStepMounted('configureSSO', 'activate', ...) after successful activation, including timestamp and connection status. OrganizationDomainsStep adds useEffect and useRef to emit the event once on mount for the verify-domain step, guarded by ref to prevent duplicate records, including connection status, connection ID, and organization ID.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• clerk/javascript#8882: Introduces or reworks ActivateStep logic, directly overlapping with the telemetry emission added to the activation handler in this PR.

Suggested reviewers

• iagodahlem

Poem

🐇 Hop, hop, a step was mounted today,
A telemetry event sent on its way!
flow-step.ts born with timestamp in tow,
ConfigureSSO steps now tracked as they go.
The rabbit cheers — the data will flow! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main change: adding a telemetry event for flow steps across shared and ui packages.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8951

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8951

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8951

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8951

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@8951

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@8951

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@8951

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8951

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8951

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8951

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8951

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8951

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8951

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8951

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8951

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8951

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8951

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8951

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8951

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8951

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8951

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8951

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8951

commit: c2212d3

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/shared/src/telemetry/events/flow-step.ts`:
- Around line 34-38: The spread of payload in the telemetry event payload object
allows external data to override the core flow-step fields (flow, step, and
timestamp). Reorder the properties in the payload object so that the spread of
payload comes first, followed by the explicit core fields (flow, step, and
timestamp) so that these critical telemetry fields take precedence and cannot be
overridden by any data in the payload parameter.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: b8bab827-d791-4454-80d8-9457d04e4a9c

📥 Commits

Reviewing files that changed from the base of the PR and between dd51fe4 and 8377b13.

📒 Files selected for processing (4)

• packages/shared/src/telemetry/events/flow-step.ts
• packages/shared/src/telemetry/events/index.ts
• packages/ui/src/components/ConfigureSSO/steps/ActivateStep.tsx
• packages/ui/src/components/ConfigureSSO/steps/OrganizationDomainsStep.tsx

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-22T19:50:45.629Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	1

---

@clerk/shared

Current version: 4.20.0
Recommended bump: MINOR → 4.21.0

Subpath ./telemetry

🟢 Additions (1)

Added: eventFlowStepMounted

+ declare function eventFlowStepMounted(flow: string, step: string, metadata?: TelemetryEventRaw['payload'], eventSamplingRate?: number): TelemetryEventRaw<EventFlowStepMounted>;

Added function eventFlowStepMounted

---

Report generated by Break Check

_{Last ran on c2212d3.}