Skip to content

feat: sectional onboarding tester for first-request page#45

Merged
mollases merged 2 commits into
mainfrom
feat/sectional-onboarding-tester
Jun 11, 2026
Merged

feat: sectional onboarding tester for first-request page#45
mollases merged 2 commits into
mainfrom
feat/sectional-onboarding-tester

Conversation

@lhagenWP

@lhagenWP lhagenWP commented Jun 10, 2026

Copy link
Copy Markdown
Collaborator

Summary

Trial users who just received their API key need to see the API against their own use case, not someone else's. The current onboarding flow on /docs/documentation/making-your-first-request only offered a single hardcoded query (name=John Smith&city=Seattle&state_code=WA), so the first impression every trial user got was a query about someone they have no interest in.

This PR replaces the single-shot <ApiKeyTester /> with a three-section <OnboardingTester /> covering the three primary use cases.

What changes for trial users

Paste API key once, then pick the use case that matches what they're building:

Section Inputs Hits Guide link
Search for a Person name (req), city, state_code, street /v2/person /documentation/person-search
Look Up a Phone Number phone (req) /v2/person /documentation/person-search/reverse-phone-lookup
Search for a Property street (req), city, state_code (req) /v2/property /documentation/property-search

4xx responses get human-readable classification instead of a generic failure — 403 → "invalid key", 429 → "rate limit", 404 → "no results found, your key is working".

Analytics

The legacy single-shot test event is replaced by three section-aware events so engagement can be measured per use case:

  • Send (on click): section and the outgoing query params (API key excluded) so we can see what people are actually searching for.
  • Result (on response): section, success, status, result_count (sniffed from the v2 response shape — metadata.result_count for person, presence of result for property), and an error tag for 4xx/network failures. The result_count field lets us identify trial users making queries that return nothing.
  • Guide click: section, on a guide-link click.

The page-view event already fires on navigation, so a separate per-section impression event isn't needed.

Architecture

  • New: src/components/activation/onboarding-tester.tsx (replaces api-key-tester.tsx).
  • Proxy at /docs/api/test-proxy becomes a dynamic route under /[endpoint] with an allowlist (person, property) — so the property section can hit /v2/property while the person/phone sections continue to hit /v2/person. The proxy is otherwise unchanged.
  • mdx-components.tsx swaps the registration; making-your-first-request.mdx swaps the component invocation and refreshes the intro copy.

Bonus: walkthrough completion-link fix

While reviewing link patterns I noticed src/components/webhooks/walkthrough.tsx hard-coded /docs/... hrefs on its three Link completion links. Next.js's next/link auto-applies basePath, so those hrefs were rendering as /docs/docs/documentation/... and 404'ing. Folded into a separate commit (fix: drop /docs prefix from walkthrough completion links). Reachable only after completing the walkthrough flow at /docs/documentation/webhooks/quickstart, which is presumably why it hadn't been noticed.

Verification

  • bun run types:check — clean (only pre-existing bun:test import error, present on main)
  • bun run lint — clean
  • bun run format:check — clean
  • bun run dev — eyeballed all four anchor destinations resolve correctly to /docs/documentation/...

@lhagenWP lhagenWP force-pushed the feat/sectional-onboarding-tester branch from e0102ad to 261de9c Compare June 10, 2026 20:56
lhagenWP added 2 commits June 10, 2026 17:30
Replaces the one-size-fits-all <ApiKeyTester /> on
making-your-first-request.mdx with a three-section <OnboardingTester />
matching the three primary API use cases: person search, reverse phone
lookup, and property search.

The legacy tester only made one boilerplate request
(`name=John Smith&city=Seattle&state_code=WA`), which gave a trial user
who just received their key no visibility into how the API performs
against their own use case.

Behavior:
- Shared API key field at the top, then three stacked sections. Each
  section has the form fields its use case actually needs (e.g. phone
  section asks for a phone number; property section asks for street and
  state), a Send button, an inline response panel, and a Link to the
  deeper guide for that use case.
- The proxy at /docs/api/test-proxy is now a dynamic route under
  /[endpoint] with an allowlist (`person`, `property`), so the property
  section can hit /v2/property while the person/phone sections continue
  to hit /v2/person.
- 4xx responses get human-readable classification rather than a generic
  failure — 403 is "invalid key", 429 is "rate limit", 404 is "no
  results found, your key is working".

Analytics:
- Per-section events on Send (with the outgoing query params), on
  response (with success/status/result_count), and on guide-link
  click. The result_count signal sniffs the v2 response shape so we
  can tell whether a section is producing empty results.
- The legacy single-shot test event is replaced by these
  section-scoped events.

Removed:
- src/components/activation/api-key-tester.tsx
- src/app/api/test-proxy/route.ts (replaced by the dynamic route)
The three Link hrefs on the webhook walkthrough completion screen
hard-coded the basePath (`/docs/documentation/...`), but next/link's
Link auto-applies the `basePath: "/docs"` from next.config.mjs — so
the rendered URLs were doubly-prefixed (`/docs/docs/documentation/...`)
and 404'd. Surfaced while reviewing the same pattern in the new
onboarding tester.

Drop the `/docs` prefix to match the convention used in MDX content
and in changelog-banner.tsx — bare paths that Link prefixes
automatically.

Reachable via /docs/documentation/webhooks/quickstart after completing
the walkthrough flow.
@lhagenWP lhagenWP force-pushed the feat/sectional-onboarding-tester branch from 261de9c to f550696 Compare June 10, 2026 21:30
@mollases mollases merged commit 25d7921 into main Jun 11, 2026
1 check 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