Surface operation parameter examples in generated type JSDoc by JuroUhlar · Pull Request #253 · fingerprintjs/node-sdk

JuroUhlar · 2026-07-01T17:02:03Z

Surface operation parameter examples in the generated type JSDoc — the one thing openapi-typescript 7.13.0 (#254) still doesn't do natively.

hoistParameterExamples lifts each parameter's examples array onto the parameter object (openapi-typescript builds a param's JSDoc there, not from its nested schema), where it renders as one @example tag per entry. Also converts generate.mjs → generate.mts.

@example

openapi-typescript builds a parameter's JSDoc from the parameter object rather than its nested schema, so operation parameter examples never reached the generated types. Hoist each parameter's schema example (also unwrapping array items) up to the parameter level so client method params carry an @example tag.

Fold the JSON Schema `examples` array into the `@example` tag that openapi-typescript emits (it only reads the singular `example` keyword), and propagate examples across $ref properties like descriptions already are. Multiple examples render as separate `@example` tags (the JSDoc convention); array/object example values are emitted as compact one-line JSON.

changeset-bot · 2026-07-01T17:02:08Z

🦋 Changeset detected

Latest commit: 0496075

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-07-01T17:03:05Z

Coverage report

St.^❔	Category	Percentage	Covered / Total
🟢	Statements	100%	183/183
🟢	Branches	100%	63/63
🟢	Functions	100%	35/35
🟢	Lines	100%	181/181

Test suite run success

76 tests passing in 9 suites.

Report generated by 🧪jest coverage report action from 0496075

Show full coverage report

St	File	% Stmts	% Branch	% Funcs	% Lines
🟢	All files	100	100	100	100
🟢	src	100	100	100	100
🟢	index.ts	100	100	100	100
🟢	sealedResults.ts	100	100	100	100
🟢	serverApiClient.ts	100	100	100	100
🟢	types.ts	100	100	100	100
🟢	urlUtils.ts	100	100	100	100
🟢	webhook.ts	100	100	100	100
🟢	src/errors	100	100	100	100
🟢	apiErrors.ts	100	100	100	100
🟢	handleErrorResponse.ts	100	100	100	100
🟢	toError.ts	100	100	100	100
🟢	unsealError.ts	100	100	100	100

Rename generate.mjs to generate.mts and add explicit types. Run it via Node's native type stripping (node generate.mts), which requires Node >=22.6 — noted in contributing.md. Output is unchanged; the published SDK and CI are unaffected.

Copilot

Pull request overview

Updates the type-generation pipeline to surface OpenAPI/JSON Schema examples as JSDoc @example tags in the generated TypeScript types, including operation parameter examples that previously didn’t appear on client method parameter types.

Changes:

Walk the parsed OpenAPI document to fold JSON Schema examples[] into example and hoist parameter schema examples onto the parameter object before running openapi-typescript.
Propagate example across $ref properties similarly to how descriptions are propagated.
Post-process generated output to split multiple examples into separate @example JSDoc tags, and regenerate src/generatedApiTypes.ts.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

File	Description
generate.mjs	Adds example folding/hoisting + `$ref` example propagation and post-processing to split multi-example tags in generated JSDoc.
src/generatedApiTypes.ts	Regenerated output now includes `@example` tags across schemas and operation parameters.
.changeset/jsdoc-schema-examples.md	Patch changeset entry for schema examples appearing as JSDoc `@example`.
.changeset/jsdoc-parameter-examples.md	Patch changeset entry for parameter examples appearing as JSDoc `@example`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Use tsx instead of Node native type stripping so the generator runs on Node >=18.17 (the SDK's supported range), removing the temporary contributing.md caveat.

…jsdoc-examples

Copilot

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated no new comments.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

mcnulty-fp

Looks like the latest version of openapi-typescript adds some support for examples. Here's a draft PR with the new JSDoc based on feat/open-api-v3.4.2: #254.

So, if openapi-typescript is upgraded the workaround for multiple examples can be removed.

However, it looks like openapi-typescript still wants the example to be on the parameter object rather than the schema object so the hoisting workaround in this PR is still useful.

@example

openapi-typescript 7.13.0 (merged via #254) now surfaces schema examples, splits multiple examples into separate @example tags, and propagates examples across $refs natively. Drop the generator logic that duplicated this (foldExamplesIntoExample for schemas, normalizeExample, serializeExample, dedentExampleTags, and $ref example propagation), keeping only operation parameter example hoisting, which openapi-typescript still ignores.

Every parameter schema in the spec carries the singular `example` keyword (and array items do too), so the `examples[]` array fallback never fires. Regenerated output is byte-identical.

Read the JSON Schema `examples` array rather than the singular `example` keyword. The schema carries `example` only as a compat duplicate for tools that can't read `examples[]`, and it may be removed upstream; `examples[]` is the stable source. Regenerated output is byte-identical.

Hoist the whole `examples` array onto the parameter object instead of a single value. openapi-typescript renders one `@example` tag per array entry, so params with multiple examples now surface all of them (previously only the first survived). Regenerated output is byte-identical for the current schema, where every parameter has a single example.

JuroUhlar · 2026-07-02T10:27:18Z

Looks like the latest version of openapi-typescript adds some support for examples. Here's a draft PR with the new JSDoc based on feat/open-api-v3.4.2: #254.

So, if openapi-typescript is upgraded the workaround for multiple examples can be removed.

However, it looks like openapi-typescript still wants the example to be on the parameter object rather than the schema object so the hoisting workaround in this PR is still useful.

@mcnulty-fp Ah, rookie mistake not trying to just upgrade the library first 🤦 thanks for catching that! I merged your changes to main, updated this PR to keep just the hoisting workaround for query params

Copilot

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

@example

Array-typed params surfaced a scalar @example (e.g. @example OpenAI) that was inconsistent with the declared string[] type. Wrap each item example in an array; pre-serialize so openapi-typescript keeps it single-line.

github-actions · 2026-07-02T10:45:22Z

🚀 Following releases will be created using changesets from this PR:

@fingerprint/node-sdk@7.4.0

Minor Changes

events: Add device, os, and os_version to Event (7525139)
events-search: Add source query parameter to filter events by edge (Automation Intelligence) source (7525139)
events: Add unknown value to proxy_details.proxy_type, reported when a proxy is detected solely by the ML model (a5c7d75)
events: Add battery_level and battery_low_power_mode to RawDeviceAttributes (7525139)
events: Add ml_prediction to vpn_methods (7525139)
events: Add vpn_ml_score to Event (7525139)
events-search: Document 404 response for searchEvents operation (7525139)

Patch Changes

Include operation parameter examples as @example tags in the generated type JSDoc (d17d0b1)

JuroUhlar added 2 commits July 1, 2026 17:40

JuroUhlar requested review from Orkuncakilkaya, ilfa, makma and mcnulty-fp as code owners July 1, 2026 17:02

JuroUhlar marked this pull request as draft July 1, 2026 17:03

refactor: convert type generator to TypeScript

8087c7f

Rename generate.mjs to generate.mts and add explicit types. Run it via Node's native type stripping (node generate.mts), which requires Node >=22.6 — noted in contributing.md. Output is unchanged; the published SDK and CI are unaffected.

JuroUhlar requested a review from Copilot July 1, 2026 17:51

Copilot started reviewing on behalf of JuroUhlar July 1, 2026 17:51 View session

Copilot AI reviewed Jul 1, 2026

View reviewed changes

JuroUhlar added 9 commits July 1, 2026 19:01

chore: consolidate jsdoc example changesets into one

d17d0b1

chore: run type generator via tsx

a699168

Use tsx instead of Node native type stripping so the generator runs on Node >=18.17 (the SDK's supported range), removing the temporary contributing.md caveat.

docs: tighten comments in type generator

1475aff

refactor: group generator helpers above main flow

c1c7f4a

refactor: run example fold inside generator try block

501b721

refactor: load schema inside generator try block

3c34fab

chore: improve readability

e187712

refactor: rename splitExampleTags to dedentExampleTags

5dc38ef

Merge remote-tracking branch 'origin/feat/open-api-v3.4.2' into feat/…

cade7ed

…jsdoc-examples

JuroUhlar marked this pull request as ready for review July 1, 2026 19:03

JuroUhlar requested a review from Copilot July 1, 2026 19:06

Copilot started reviewing on behalf of JuroUhlar July 1, 2026 19:07 View session

Copilot AI reviewed Jul 1, 2026

View reviewed changes

mcnulty-fp requested changes Jul 1, 2026

View reviewed changes

Base automatically changed from feat/open-api-v3.4.2 to main July 2, 2026 08:08

JuroUhlar changed the title ~~Surface schema & parameter examples in generated type JSDoc~~ Surface operation parameter examples in generated type JSDoc Jul 2, 2026

JuroUhlar added 3 commits July 2, 2026 11:08

refactor: drop unused examples[] branch in param example extraction

3ddd60a

Every parameter schema in the spec carries the singular `example` keyword (and array items do too), so the `examples[]` array fallback never fires. Regenerated output is byte-identical.

JuroUhlar requested a review from Copilot July 2, 2026 10:25

Copilot started reviewing on behalf of JuroUhlar July 2, 2026 10:25 View session

Copilot AI reviewed Jul 2, 2026

View reviewed changes

Comment thread generate.mts

fix: render array-typed param examples as arrays matching their type

0496075

Array-typed params surfaced a scalar @example (e.g. @example OpenAI) that was inconsistent with the declared string[] type. Wrap each item example in an array; pre-serialize so openapi-typescript keeps it single-line.

JuroUhlar requested a review from mcnulty-fp July 2, 2026 13:00

necipallef reviewed Jul 2, 2026

View reviewed changes

Comment thread package.json

mcnulty-fp approved these changes Jul 2, 2026

View reviewed changes

JuroUhlar merged commit d1bd73d into main Jul 2, 2026
17 checks passed

JuroUhlar deleted the feat/jsdoc-examples branch July 2, 2026 13:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Surface operation parameter examples in generated type JSDoc#253

Surface operation parameter examples in generated type JSDoc#253
JuroUhlar merged 17 commits into
mainfrom
feat/jsdoc-examples

JuroUhlar commented Jul 1, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jul 1, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 1, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

mcnulty-fp left a comment

Uh oh!

JuroUhlar commented Jul 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

github-actions Bot commented Jul 2, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

JuroUhlar commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report

Test suite run success

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

mcnulty-fp left a comment

Choose a reason for hiding this comment

Uh oh!

JuroUhlar commented Jul 2, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

github-actions Bot commented Jul 2, 2026

🚀 Following releases will be created using changesets from this PR:

@fingerprint/node-sdk@7.4.0

Minor Changes

Patch Changes

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

JuroUhlar commented Jul 1, 2026 •

edited

Loading

changeset-bot Bot commented Jul 1, 2026 •

edited

Loading

github-actions Bot commented Jul 1, 2026 •

edited

Loading