Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .changeset/event-discriminated-union.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
'@fingerprint/node-sdk': minor
---

**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](https://docs.fingerprint.com/reference/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:

```ts
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.
5 changes: 5 additions & 0 deletions .changeset/event-simulator-browser.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@fingerprint/node-sdk': minor
---

**events**: `simulator` also flags Safari running inside the iOS Simulator, not only the native iOS SDK
5 changes: 5 additions & 0 deletions .changeset/webhook-type.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@fingerprint/node-sdk': minor
---

**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.
2 changes: 1 addition & 1 deletion .schema-version
Original file line number Diff line number Diff line change
@@ -1 +1 @@
v3.10.0
v3.11.0
3 changes: 2 additions & 1 deletion example/getEvent.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,8 @@ try {
const event = await client.getEvent(eventId, { ruleset_id: rulesetId })
console.log(JSON.stringify(event, null, 2))

if (rulesetId && event.rule_action) {
// Only device events have a rule action.
if (rulesetId && event.source === 'device' && event.rule_action) {
const { type, ruleset_id, rule_id, rule_expression } = event.rule_action
console.log(`Rule action: ${type} (ruleset: ${ruleset_id}, rule: ${rule_id}, expression: ${rule_expression})`)

Expand Down
17 changes: 13 additions & 4 deletions readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,10 @@ client.getEvent('<eventId>').then((event) => {

// Get an event with a ruleset evaluation
client.getEvent('<eventId>', { ruleset_id: '<rulesetId>' }).then((event) => {
console.log(event.rule_action?.type) // 'allow' or 'block'
// Only device events have Identification and a rule action, edge events (Automation Intelligence API) don't.
if (event.source === 'device') {
console.log(event.rule_action?.type) // 'allow' or 'block'
}
})

// Search for identification events
Expand Down Expand Up @@ -151,12 +154,18 @@ Other `SdkError`s:

#### Webhook types

When handling [Webhooks](https://dev.fingerprint.com/reference/posteventwebhook#/) coming from Fingerprint, you can cast the payload as the built-in `Event` type:
When handling [Webhooks](https://docs.fingerprint.com/reference/posteventwebhook) coming from Fingerprint, you can cast the payload as the built-in `Webhook` type:

```ts
import { Event } from '@fingerprint/node-sdk'
import { Webhook } from '@fingerprint/node-sdk'

const webhook = eventWebhookBody as unknown as Webhook

const event = eventWebhookBody as unknown as Event
// Edge events (Automation Intelligence API) have no Identification.
// Bodies stored before `source` was added have no `source`; they are device events.
if (webhook.source !== 'edge') {
console.log(webhook.identification?.visitor_id)
}
```

#### Webhook signature validation
Expand Down
121 changes: 107 additions & 14 deletions resources/fingerprint-server-api.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -943,7 +943,8 @@ paths:
schema:
type: boolean
description: >
Filter events by iOS Simulator Detection result.
Filter events by the Simulator Detection result (native iOS SDK and
Safari on iOS).


> Note: When using this parameter, only events with the `simulator`
Expand Down Expand Up @@ -1212,6 +1213,11 @@ components:
enum:
- device
- edge
EnvironmentId:
type: string
examples:
- ae_47abaca3db2c7c43
description: Environment ID of the event.
Url:
type: string
examples:
Expand Down Expand Up @@ -1619,6 +1625,55 @@ components:
description: >
`true` if the request came from a device running a VPN, `false`
otherwise.
EventEdge:
type: object
description: >-
An event generated by the Automation Intelligence API (`source` is
`edge`), containing IP and bot analysis for a request intercepted at the
edge. No client-side agent is involved, so Identification (`visitor_id`)
and Smart Signals derived from device telemetry are not available.
`ip_info` is always present, but is empty when no IP intelligence is
available for the request. `environment_id` is only included in
webhooks, when the `/edge` request was authenticated with an
environment-scoped secret API key. API responses (`POST /v4/edge`, `GET
/v4/events`) never include it.
required:
- event_id
- timestamp
- source
- ip_info
properties:
event_id:
$ref: '#/components/schemas/EventId'
timestamp:
$ref: '#/components/schemas/Timestamp'
source:
$ref: '#/components/schemas/EventSource'
const: edge
linked_id:
$ref: '#/components/schemas/LinkedId'
environment_id:
$ref: '#/components/schemas/EnvironmentId'
tags:
$ref: '#/components/schemas/Tags'
url:
$ref: '#/components/schemas/Url'
bot_info:
$ref: '#/components/schemas/BotInfo'
ip_info:
$ref: '#/components/schemas/IPInfo'
proxy:
$ref: '#/components/schemas/Proxy'
proxy_confidence:
$ref: '#/components/schemas/ProxyConfidence'
proxy_details:
$ref: '#/components/schemas/ProxyDetails'
vpn:
$ref: '#/components/schemas/Vpn'
vpn_confidence:
$ref: '#/components/schemas/VpnConfidence'
vpn_methods:
$ref: '#/components/schemas/VpnMethods'
ErrorCode:
type: string
enum:
Expand Down Expand Up @@ -1728,11 +1783,6 @@ components:
enum:
- partially_completed
- completed
EnvironmentId:
type: string
examples:
- ae_47abaca3db2c7c43
description: Environment ID of the event.
Suspect:
type: boolean
description: >-
Expand Down Expand Up @@ -2378,10 +2428,14 @@ components:
block: '#/components/schemas/EventRuleActionBlock'
Simulator:
type: boolean
description: |
iOS specific simulator detection. There are 2 values:
description: >
Flags requests coming from an iOS Simulator. Covers the native iOS SDK
and Safari running inside the iOS Simulator. There are 2 values:

* `true` - Simulator environment detected.
* `false` - No signs of simulator or the client is not iOS.

* `false` - No signs of a simulator, or the request does not come from
iOS (native iOS SDK or Safari on iOS).
SuspectScore:
type: integer
examples:
Expand Down Expand Up @@ -3159,18 +3213,21 @@ components:
case. This field is in the beta phase and only available to select
customers. If you are interested, please [contact our support
team](https://fingerprint.com/support/).
Event:
EventDevice:
type: object
description: >-
Contains results from Fingerprint Identification and all active Smart
Signals. Some Smart Signals are only supported for certain device types,
these fields will be omitted for events not generated from the supported
devices. Consult the [Smart Signals
An event generated by the JS agent or a mobile SDK running on an
end-user device (`source` is `device`). Contains results from
Fingerprint Identification and all active Smart Signals. Some Smart
Signals are only supported for certain device types, these fields will
be omitted for events not generated from the supported devices. Consult
the [Smart Signals
reference](https://docs.fingerprint.com/docs/smart-signals-reference)
for more details.
required:
- event_id
- timestamp
- source
properties:
event_id:
$ref: '#/components/schemas/EventId'
Expand All @@ -3186,6 +3243,7 @@ components:
- browser
source:
$ref: '#/components/schemas/EventSource'
const: device
x-platforms:
- android
- ios
Expand Down Expand Up @@ -3414,6 +3472,7 @@ components:
$ref: '#/components/schemas/Simulator'
x-platforms:
- ios
- browser
suspect_score:
$ref: '#/components/schemas/SuspectScore'
x-platforms:
Expand Down Expand Up @@ -3518,6 +3577,40 @@ components:
- browser
- ios
- android
Event:
type: object
description: >
A Device Intelligence or Automation Intelligence event. Check `source`
first, because it determines which properties the event can contain.


Both sources can contain:

- Request metadata like `event_id`, `timestamp`, `source`, `linked_id`,
`environment_id`, `tags`, `url`.

- IP and bot analysis fields like `ip_info`, `bot_info`, `proxy`, `vpn`.


Sources:

- `device` - generated by the Fingerprint JavaScript agent or a mobile
SDK running on an end-user device. Also contains Identification
(`visitor_id`) and Smart Signals derived from device telemetry. See
`EventDevice`.

- `edge` - generated by the Automation Intelligence API (`/edge`
endpoint) for a request intercepted at the edge. Contains only the
properties above. See `EventEdge`.
required: []
oneOf:
- $ref: '#/components/schemas/EventDevice'
- $ref: '#/components/schemas/EventEdge'
discriminator:
propertyName: source
mapping:
device: '#/components/schemas/EventDevice'
edge: '#/components/schemas/EventEdge'
EventUpdate:
type: object
required: []
Expand Down
Loading
Loading