Repository navigation
OpenAPI schema sync (v3.11.0) - #307
Conversation
🦋 Changeset detectedLatest commit: deb9559 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 |
Coverage report
Test suite run success137 tests passing in 32 suites. Report generated by 🧪jest coverage report action from deb9559 Show full coverage report
|
…pe (#308) ### Context [INTER-2896](https://fingerprintjs.atlassian.net/browse/INTER-2896) | stacked on #307 (schema sync v3.11.0) | replaces prototype #300 ### Why The v3.11.0 schema makes `Event` a union of `EventDevice | EventEdge`, so #307 fails the build until the example, readme, and webhook typing narrow on `source`. ### Things to note - **⚠️ Type-breaking change, released as `minor`.** Reading `event.identification` or `event.rule_action` without checking `source === 'device'` no longer compiles, and `Event` objects without `source` are rejected. The changeset says so explicitly, like the v3.3.0 one in 7.3.0. - **Merge into #307's branch, not `main`.** #307's build fails on `example/getEvent.mjs` without this PR. - **`Event` keeps `source` required; `Webhook` makes it optional on device events.** Webhook bodies stored before `source` existed don't have it, and resends deliver the stored body as-is. So API code checks `source === 'device'`, webhook code checks `source !== 'edge'`. ### Verification On this branch: `pnpm build`, `lint`, `test:dts` and all 135 tests pass. `test:dts` type-checks `example/getEvent.mjs`, the file that fails #307's build. Type tests in `eventType.spec.ts` check that `Webhook` accepts a body without `source`. ### Change outline Public types (`src/types.ts`, `src/index.ts`): ```diff + export EventDevice, EventEdge // variants, now importable type Event = EventDevice | EventEdge // from the schema, `source` required + type Webhook = + | (EventDevice with source?: 'device') // bodies stored before `source` + | EventEdge ``` What users write now: ```diff const event = await client.getEvent(id, { ruleset_id }) - console.log(event.rule_action?.type) + if (event.source === 'device') console.log(event.rule_action?.type) - const event = webhookBody as Event + const webhook = webhookBody as Webhook + if (webhook.source !== 'edge') console.log(webhook.identification) ``` Changesets, rewritten for Node SDK users (all `minor`): ```text event-discriminated-union.md #⚠️ type-breaking: Event is a union, # check source before device-only fields webhook-type.md # new Webhook type event-simulator-browser.md # simulator also flags Safari in iOS Simulator ``` [INTER-2896]: https://fingerprintjs.atlassian.net/browse/INTER-2896?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
🟡 Changes recommended
The required source field is not validated or added by the sealed-results helpers, causing legacy device results to be skipped by the recommended source check; normalization or a compatible return type and regression coverage are needed.
1 open issue
What changed in this PR
Synchronizes the Node SDK with OpenAPI v3.11.0, distinguishing device and edge events while preserving legacy webhook typing.
Changes:
- Introduces device/edge event types and exports a backward-compatible
Webhooktype. - Updates examples and documentation for source-based narrowing and broader iOS Simulator detection.
- Adds edge-event fixtures, response tests, and webhook type checks.
| File | Description |
|---|---|
tests/unit-tests/eventType.spec.ts |
Tests webhook compatibility and type narrowing. |
tests/mocked-responses-tests/searchEventsTests.spec.ts |
Tests edge-event search responses and narrowing. |
tests/mocked-responses-tests/mocked-responses-data/webhook/webhook_event.json |
Adds the device source to the webhook fixture. |
tests/mocked-responses-tests/mocked-responses-data/events/search/get_event_search_edge_200.json |
Adds an edge-event search fixture. |
tests/mocked-responses-tests/mocked-responses-data/events/search/get_event_search_200.json |
Adds a chargebacks label example. |
tests/mocked-responses-tests/mocked-responses-data/events/get_event_with_edge_200.json |
Adds an edge-event response fixture. |
tests/mocked-responses-tests/mocked-responses-data/events/get_event_ruleset_200.json |
Adds a chargebacks label example. |
tests/mocked-responses-tests/mocked-responses-data/events/get_event_200.json |
Adds a chargebacks label example. |
tests/mocked-responses-tests/getEventTests.spec.ts |
Tests edge-event retrieval and narrowing. |
tests/mocked-responses-tests/castWebhookEventTest.spec.ts |
Uses the dedicated webhook type. |
src/types.ts |
Defines public event variants and webhook typing. |
src/serverApiClient.ts |
Updates the documentation example to narrow device events. |
src/index.ts |
Exports the new public types. |
src/generatedApiTypes.ts |
Regenerates event types and simulator descriptions. |
resources/fingerprint-server-api.yaml |
Updates the schema with event variants and simulator coverage. |
readme.md |
Documents event narrowing and legacy webhook handling. |
example/getEvent.mjs |
Restricts rule-action handling to device events. |
.schema-version |
Records schema version v3.11.0. |
.changeset/webhook-type.md |
Documents the new webhook type. |
.changeset/event-simulator-browser.md |
Documents Safari simulator detection coverage. |
.changeset/event-discriminated-union.md |
Explains breaking type changes and migration steps. |
Review effort: Balanced
### Context [INTER-2896](https://fingerprintjs.atlassian.net/browse/INTER-2896) | stacked on #307 (schema sync v3.11.0) | replaces prototype #300 ### Why The v3.11.0 schema makes `Event` a union of `EventDevice | EventEdge`, so #307 fails the build until the example, readme, and webhook typing narrow on `source`. ### Things to note - **⚠️ Type-breaking change, released as `minor`.** Reading `event.identification` or `event.rule_action` without checking `source === 'device'` no longer compiles, and `Event` objects without `source` are rejected. The changeset says so explicitly, like the v3.3.0 one in 7.3.0. - **Merge into #307's branch, not `main`.** #307's build fails on `example/getEvent.mjs` without this PR. - **`Event` keeps `source` required; `Webhook` makes it optional on device events.** Webhook bodies stored before `source` existed don't have it, and resends deliver the stored body as-is. So API code checks `source === 'device'`, webhook code checks `source !== 'edge'`. ### Verification On this branch: `pnpm build`, `lint`, `test:dts` and all 135 tests pass. `test:dts` type-checks `example/getEvent.mjs`, the file that fails #307's build. Type tests in `eventType.spec.ts` check that `Webhook` accepts a body without `source`. ### Change outline Public types (`src/types.ts`, `src/index.ts`): ```diff + export EventDevice, EventEdge // variants, now importable type Event = EventDevice | EventEdge // from the schema, `source` required + type Webhook = + | (EventDevice with source?: 'device') // bodies stored before `source` + | EventEdge ``` What users write now: ```diff const event = await client.getEvent(id, { ruleset_id }) - console.log(event.rule_action?.type) + if (event.source === 'device') console.log(event.rule_action?.type) - const event = webhookBody as Event + const webhook = webhookBody as Webhook + if (webhook.source !== 'edge') console.log(webhook.identification) ``` Changesets, rewritten for Node SDK users (all `minor`): ```text event-discriminated-union.md #⚠️ type-breaking: Event is a union, # check source before device-only fields webhook-type.md # new Webhook type event-simulator-browser.md # simulator also flags Safari in iOS Simulator ``` [INTER-2896]: https://fingerprintjs.atlassian.net/browse/INTER-2896?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
b1014dc to
deb9559
Compare
🚀 Following releases will be created using changesets from this PR:@fingerprint/node-sdk@7.11.0Minor Changes
|
…309) Replaces the deprecated `dev.fingerprint.com` links in code docs and the readme with `docs.fingerprint.com`. `CHANGELOG.md` is untouched (release history). Each new URL is the page the old URL redirects to, unless noted. Final status is from `curl -sL`. | Old URL | New URL | Status | |---|---|---| | `dev.fingerprint.com/reference/pro-server-api` | `docs.fingerprint.com/reference/server-api` | 200 | | `dev.fingerprint.com/reference/posteventwebhook#/` | `docs.fingerprint.com/reference/posteventwebhook` (dropped `#/`) | 200 | | `dev.fingerprint.com/docs/webhooks-security` | `docs.fingerprint.com/docs/webhooks#protecting-your-webhooks` | 200 | | `dev.fingerprint.com/reference/deletevisitordata` | `docs.fingerprint.com/reference/server-api-delete-visitor-id` (redirect lands on the v3 page; v4 page used) | 200 | | `dev.fingerprint.com/docs/sealed-client-results` | `docs.fingerprint.com/docs/sealed-client-results` | 200 | | `dev.fingerprint.com/docs/smart-signals-overview` | `docs.fingerprint.com/docs/smart-signals-reference` | 200 | | `dev.fingerprint.com/reference/getevent` | `docs.fingerprint.com/reference/server-api-get-event` | 200 | | `dev.fingerprint.com/docs/js-agent#visitorid` | `docs.fingerprint.com/reference/js-agent-get-function#visitor_id` (old anchor gone; redirect target has none) | 200 | | `dev.fingerprint.com/reference/get-function#visitorid` | `docs.fingerprint.com/reference/js-agent-get-function#visitor_id` | 200 | | `dev.fingerprint.com/reference/get-function#linkedid` | `docs.fingerprint.com/reference/js-agent-get-function#linkedid` | 200 | | `dev.fingerprint.com/reference/updateevent` | `docs.fingerprint.com/reference/server-api-update-event` | 200 | | `dev.fingerprint.com/reference/server-api-v4-get-event` | `docs.fingerprint.com/reference/server-api-get-event` | 200 | Anchors `#protecting-your-webhooks`, `#visitor_id`, `#linkedid` exist on the target pages (checked in the docs repo and the live pages). Overlap: #308 (stacked on #307) already changes the webhook link in `src/types.ts` and `readme.md`, so this may conflict there. Co-authored-by: JuroUhlar <11249993+JuroUhlar@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Schema sync for v3.11.0 OpenAPI schema release.
Ticket: INTER-2896