chore: vendor the OpenAPI spec and add a refresh script - #983
Open
vdusek wants to merge 5 commits into
Open
Conversation
Lands only the input artifact. Nothing reads the snapshot yet -- the type generator, the generated types and the scheduled sync workflow follow separately, so that change can land as one complete functional unit. The path is src/generated/ even though nothing generates the file today; it is where the generator will look for it, and matching it now avoids a rename later. scripts/fetch-spec.mts writes the response bytes through untouched instead of re-serializing them, and reads them via arrayBuffer rather than text, since text would strip a leading BOM and decode a non-UTF-8 body into replacement characters that still parse as JSON. It validates shape -- parseable JSON, openapi 3.1.x, non-empty paths and components.schemas -- before touching the target, and writes through a temp file plus rename, so a docs outage serving an error page with a 200 cannot land as a corrupt snapshot. The validated summary is built from narrowed values rather than asserted onto the parsed document, so dropping a check becomes a compile error instead of a crash after the write. Operational failures (offline, DNS, timeout, write errors) are funnelled into the same one-line report as validation failures, and the write is skipped when the bytes already match. .gitattributes pins LF for the whole repo. All 156 tracked text files are already LF in the index, so it renormalizes nothing; it exists so a clone made with core.autocrlf=true cannot turn a refresh into 29k lines of line-ending churn. tsconfig.scripts.json needs an explicit `types: ["node"]`. This setup gets no automatic @types inclusion, and unlike src/ a script importing only node: builtins pulls in nothing transitively, so without it the Node globals go unresolved.
vdusek
added
adhoc
Contributor
|
✅ The link checker did not find any broken links. See more at https://github.com/apify/apify-client-js/actions/runs/30553941136#summary-90909424209 |
vdusek
changed the title
vdusek
marked this pull request as ready for review
July 31, 2026 09:44
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
2 participants
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.
Vendors the published OpenAPI spec as a committed snapshot, plus a script to refresh it. Input artifact only — nothing reads it yet. Precondition for #985, which generates all output models from this snapshot and refreshes it on a schedule; that PR lands on top of this one.
spec/openapi.json— the snapshot (995 kB,openapi: 3.1.2, 131 paths, 237 schemas), and the only input codegen will read.linguist-generated, so it collapses in diffs.scripts/fetch-spec.mts+pnpm spec:fetch— downloads it, rejects anything that isn't a plausible OpenAPI 3.1 document, then writes the bytes verbatim via temp file + rename. An error page served with a 200 can't overwrite the snapshot.tsconfig.scripts.json+pnpm tsc-check-scripts—scripts/sat outside the main project'sinclude, so nothing type-checked it. Wired into the existinglintjob..gitattributes— pins LF repo-wide, so a clone made withcore.autocrlf=truecan't turn a refresh into 29k lines of line-ending churn. Renormalizes nothing today.spec/and notsrc/— it's a build input, not source.resolveJsonModuleis on, so one stray import fromsrc/would emit the whole document intodist/and publish it (verified). Same layout as the Python client; the generated types will land insrc/generated/api.ts.pnpm spec:fetchand confirm the tree stays clean. That proves the committed bytes are what the endpoint serves.info.versionis an apify-docs build stamp, not an API version, so any docs redeploy flips that one line. The sync cron will have to gate on the generated output rather than on a spec diff.pnpm spec:fetchneeds Node >= 22.18 (native type stripping). Maintainer-only, so noengineschange — that belongs with the v4 Node baseline.✍️ Drafted by Claude Code