Summary

Adds marketplace funnel telemetry events to the auto-provision path of vercel integration add (FF_AUTO_PROVISION_INSTALL=1). The legacy path is not instrumented — it will be removed.

Events tracked (9):

• marketplace_install_flow_started
• marketplace_checkout_plan_selected — includes plan_selection_method (cli_flag / server_default)
• marketplace_checkout_provisioning_started
• marketplace_checkout_provisioning_completed — includes resource_id
• marketplace_checkout_provisioning_failed — includes error_message
• marketplace_project_connected — includes project_id, resource_id
• marketplace_project_connect_failed — includes project_id, resource_id, error_message
• marketplace_install_flow_web_fallback — reason passed through from server response
• marketplace_install_flow_dropped — input validation failures after funnel entry (metadata_parse_error, metadata_validation_failed, resource_name_invalid)

All events carry base props: integration_id, integration_slug, integration_name, product_id, product_slug, team_id, source: "cli", is_auto_provision: true

Web fallback events include pass-through fields from the auto-provision API response: auto_provision_result_kind, auto_provision_result_reason, auto_provision_error_message. No client-side interpretation — server values forwarded as-is.

Implementation

• One generic telemetry method: trackMarketplaceEvent(event, props) — no per-event interfaces or typed wrappers
• Base props built once, spread into each event call
• AutoProvisionFallback.kind and .reason typed as string for forward-compatibility with new API responses
• onProjectConnected callback added to PostProvisionOptions to decouple telemetry from post-provision setup
• Fallback reason: fallback.reason ?? fallback.kind — pure pass-through from server
• Every post-flow_started exit has a terminal event — no silent funnel drops

Fallback guard fix

isAutoProvisionFallback changed from allowlist (['metadata', 'unknown'].includes(kind)) to denylist (kind !== 'provisioned'). This is a behavioral change beyond telemetry:

• Bug fix: The old allowlist missed kind: 'install' (returned when policies not accepted) — would have thrown an unhandled error instead of falling back to the browser
• Forward-compatible: New API kind values (e.g. multiple_installations from https://github.com/vercel/api/pull/61258) are automatically handled as browser fallbacks
• Safe: The structural checks (url, integration, product fields present + HTTP 422) are the real guard, ensuring only actual step responses are caught

The API currently returns 4 kind values: provisioned (201 success), install, metadata, unknown (all 422 fallbacks). The denylist ensures the CLI doesn't need updating each time the API adds a new fallback reason.

Event Lifecycle

Happy Path

 ① flow_started
       │
 ② plan_selected (cli_flag | server_default)
       │
 ③ provisioning_started
       │
 ④ provisioning_completed
       │
 ⑤ project_connected (if project linked)

Unhappy Paths

PATH 1: Policy Declined
───────────────────────
 ① flow_started
 ✖ flow_dropped (reason: policy_declined)
 → EXIT

PATH 2: Input Validation Failure
─────────────────────────────────
 ① flow_started
 ✖ flow_dropped (reason: metadata_parse_error
                       | metadata_validation_failed
                       | resource_name_invalid)
 → EXIT

PATH 3: Server Fallback
───────────────────────
 ① flow_started
 ② plan_selected
 ③ provisioning_started
 ✖ web_fallback (reason: server kind/reason)
 → Open browser fallback → EXIT

PATH 4: Provisioning API Error
──────────────────────────────
 ① flow_started
 ② plan_selected
 ③ provisioning_started
 ✖ provisioning_failed
 → EXIT

Terminal Events by Exit Type

Dependency

• Depends on: https://github.com/vercel/api/pull/60858 (adds reason field to auto-provision responses) — merged and deployed
• Without the API PR: CLI uses fallback kind value as the telemetry reason
• With the API PR: CLI reads the specific reason for full funnel specificity

Test plan

• 73/73 auto-provision tests passing
• 75/75 legacy path tests passing (no changes to legacy path)
• Telemetry events asserted for happy path
• TypeScript compiles cleanly
• CI passes

Fixes: MKT-2615

🤖 Generated with Claude Code