fix: align Domain API schemas with BuiltWith v23 docs - #22
Merged
Conversation
Response schemas use z.strictObject(), so fields the live v23 API returns but the code omits cause domain()/domainLive() to throw on parse. Add the missing fields and correct the date-range separator. - Meta: add Umbrella (Global Router traffic rank) - Attributes: add EcommerceCategory, TTFB, SourceBytes - DomainParams: add includeTrust -> TRUST query param - FDRANGE/LDRANGE: pipe-joined YYYY-MM-DD|YYYY-MM-DD, not dash-joined - Update CLI/library docs and tests to match
Validated DomainResponseSchema against live v23 payloads (cnn.com, allbirds.com, example.com, neverssl.com, stripe.com). BuiltWith omits any field it has no data for, so several fields the docs list as present are domain-dependent: - Meta.Umbrella: absent on all sampled domains -> optional (docs overstate it) - Attributes.Employees: absent on cnn.com (pre-existing latent bug) -> optional - Attributes.Followers: absent on neverssl.com -> optional strictObject still rejects genuinely new/unknown keys, so drift detection is unaffected.
39-domain live sweep (parked, foreign, ecommerce, SaaS, media, blog, gov/edu, nonprofit): Meta.Social absent on 8 domains (example.org/net, iana.org, rakuten.co.jp, naver.com, wikipedia.org, reddit.com, overreacted.io). Sweep surfaced zero unknown keys, confirming the strictObject field set is complete for v23.
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
1 participant
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
Audited the code against the current BuiltWith Domain API v23 docs, then validated
DomainResponseSchemaagainst live payloads. Response schemas usez.strictObject(), so any field the live API returns that the code omits makesdomain()/domainLive()throw on parse.Doc audit — missing fields / params
Umbrella(Global Router traffic rank)EcommerceCategory,TTFB,SourceBytesincludeTrust→TRUSTquery param (inlines Trust data, extra API credit)YYYY-MM-DD|YYYY-MM-DD); the regex previously accepted/passed a dash join, which v23 rejectscli.md,library.md) + tests updatedLive validation — 39-domain sweep (parked, foreign, ecommerce, SaaS, media, blog, gov/edu, nonprofit)
BuiltWith omits any field it lacks data for, so several fields the docs list as present are domain-dependent. Marked optional based on real absences:
Meta.Umbrella— absent on all sampled domains (docs overstate it)Meta.Social— absent on 8/39Attributes.Employees— absent on cnn.com (pre-existing latent bug: was non-optional)Attributes.Followers— absent on neverssl.comSweep surfaced zero unknown keys across 39 domains, confirming the strictObject field set is complete for v23.
strictObjectstill rejects genuinely new keys, so drift detection is unaffected.Test plan
bun run lint/build/test— clean, 152 pass