Skip to content

OpenAPI schema sync (v3.11.0) - #307

Merged
JuroUhlar merged 5 commits into
mainfrom
feat/open-api-v3.11.0
Nov 16, 2026
Merged

JuroUhlar merged 5 commits into
mainfrom
feat/open-api-v3.11.0

Conversation

@fingerprint-dx-team-actions-runner

@fingerprint-dx-team-actions-runner fingerprint-dx-team-actions-runner Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Schema sync for v3.11.0 OpenAPI schema release.

Ticket: INTER-2896

@changeset-bot

changeset-bot Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest 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

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Coverage report

St.❔
Category Percentage Covered / Total
🟢 Statements 98.25% 168/171
🟢 Branches 97.03% 98/101
🟢 Functions 100% 37/37
🟢 Lines 98.21% 165/168

Test suite run success

137 tests passing in 32 suites.

Report generated by 🧪jest coverage report action from deb9559

Show full coverage report
St File % Stmts % Branch % Funcs % Lines Uncovered Line #s
🟢 All files 98.24 97.02 100 98.21
🟢  src 98.54 98.76 100 98.51
🔴   ...edApiTypes.ts 0 0 0 0
🔴   index.ts 0 0 0 0
🟢   sealedResults.ts 100 100 100 100
🟢   ...rApiClient.ts 96.15 97.22 100 96.15 364,368
🟢   types.ts 100 100 100 100
🟢   urlUtils.ts 100 100 100 100
🟢   webhook.ts 100 100 100 100
🟢  src/errors 97.05 90 100 96.96
🟢   apiErrors.ts 100 100 100 100
🟢   ...orResponse.ts 100 100 100 100
🟢   toError.ts 87.5 88.88 100 87.5 21
🟢   unsealError.ts 100 50 100 100 14

@JuroUhlar
JuroUhlar added this pull request to stack #310 November 16, 2026 15:14
@JuroUhlar
JuroUhlar removed this pull request from stack #310 November 16, 2026 15:17
JuroUhlar added a commit that referenced this pull request Nov 16, 2026
…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
@JuroUhlar
JuroUhlar requested a balanced review from Copilot November 16, 2026 15:28
@github-actions

This comment has been minimized.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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 Webhook type.
  • 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

Comment thread src/generatedApiTypes.ts Resolved
@JuroUhlar
JuroUhlar marked this pull request as draft November 16, 2026 15:34
@JuroUhlar
JuroUhlar requested a balanced review from Copilot November 16, 2026 16:02
### 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
@JuroUhlar
JuroUhlar force-pushed the feat/open-api-v3.11.0 branch from b1014dc to deb9559 Compare November 16, 2026 16:03
@github-actions

Copy link
Copy Markdown
Contributor

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

@fingerprint/node-sdk@7.11.0

Minor Changes

  • types: ⚠️ Type-breaking change in generated TypeScript types for OpenAPI v3.11.0. No runtime change.

    • Event is now a union of EventDevice and EventEdge, discriminated by source. Both are exported. Edge events (Automation Intelligence API) have no Identification, no rule_action, and none of the Smart Signals that need device data. They still have IP, proxy, VPN and bot detection.

    • Code that reads device-only fields such as event.identification or event.rule_action no longer compiles. Check source first:

      if (event.source === 'device') {
        console.log(event.rule_action?.type)
      }
    • source is now required on Event. Objects typed as Event without source (for example, test fixtures) no longer compile. For webhook bodies, use the new Webhook type. (0df37fc)

  • events: simulator also flags Safari running inside the iOS Simulator, not only the native iOS SDK (0df37fc)

  • webhooks: Add Webhook type for webhook bodies. Same as Event, but source is optional on device events, because webhooks stored before source existed don't have it. (c997597)

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The SDK schema update has no active review issues requiring changes.

1 open issue

Review effort: Balanced

@JuroUhlar
JuroUhlar marked this pull request as ready for review November 16, 2026 16:16
@JuroUhlar
JuroUhlar merged commit 4b1c846 into main Nov 16, 2026
19 checks passed
@JuroUhlar
JuroUhlar deleted the feat/open-api-v3.11.0 branch November 16, 2026 21:44
JuroUhlar added a commit that referenced this pull request Nov 17, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants