feat: sectional onboarding tester for first-request page#45
Merged
Conversation
e0102ad to
261de9c
Compare
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.
261de9c to
f550696
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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-requestonly 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:
name(req),city,state_code,street/v2/person/documentation/person-searchphone(req)/v2/person/documentation/person-search/reverse-phone-lookupstreet(req),city,state_code(req)/v2/property/documentation/property-search4xx 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:
sectionand the outgoing queryparams(API key excluded) so we can see what people are actually searching for.section,success,status,result_count(sniffed from the v2 response shape —metadata.result_countfor person, presence ofresultfor property), and anerrortag for 4xx/network failures. Theresult_countfield lets us identify trial users making queries that return nothing.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
src/components/activation/onboarding-tester.tsx(replacesapi-key-tester.tsx)./docs/api/test-proxybecomes a dynamic route under/[endpoint]with an allowlist (person,property) — so the property section can hit/v2/propertywhile the person/phone sections continue to hit/v2/person. The proxy is otherwise unchanged.mdx-components.tsxswaps the registration;making-your-first-request.mdxswaps the component invocation and refreshes the intro copy.Bonus: walkthrough completion-link fix
While reviewing link patterns I noticed
src/components/webhooks/walkthrough.tsxhard-coded/docs/...hrefs on its threeLinkcompletion links. Next.js'snext/linkauto-appliesbasePath, 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-existingbun:testimport error, present onmain)bun run lint— cleanbun run format:check— cleanbun run dev— eyeballed all four anchor destinations resolve correctly to/docs/documentation/...