Conversation
SPIKE INTER-2457 option C. Docs and Node keep the union. Other SDK schemas flatten Event with source optional. Do not merge.
🦋 Changeset detectedLatest commit: 767520f The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
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 |
This was referenced Aug 31, 2026
Contributor
Schema Diff vs Published Schemas
|
Edge events have no sdk.platform. Device still annotates url and bot_info as browser.
EventEdge omits x-platforms. Flatten was taking the last variant and dropping Device annotations on shared fields.
Contributor
There was a problem hiding this comment.
Pull request overview
Implements SPIKE “Option C” for INTER-2457 by splitting the v4 Event model into EventDevice and EventEdge (discriminated by source) for docs/Node output, while generating flattened Event variants for other SDK schemas and updating /edge to return EventEdge.
Changes:
- Introduce
EventDevice,EventEdge, andEventBase; redefineEventas asource-discriminated union and update docs text/examples accordingly - Add a targeted transformer to flatten only
Event’soneOffor selected SDK schema outputs, and preservex-platformsannotations when variants omit them - Update build/workflow wiring to produce and sync a new
fingerprint-server-api-v4-flat.yamlschema for Python/PHP, and adjust/edgeresponse schema
Reviewed changes
Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| vite.config.ts | Adds a new flat v4 schema output and clarifies which SDKs consume each v4 output |
| utils/transformers/transformSchema.ts | Introduces v4 “flat” transformer pipeline and integrates Event flattening into flat/normalized outputs |
| utils/transformers/transformSchema.spec.ts | Updates v4 pipeline assertions to reflect Event union vs flattened variants and /edge retention |
| utils/transformers/flattenNamedSchemaOneOfTransformer.ts | New transformer to flatten oneOf for a single named schema (used for Event) |
| utils/transformers/flattenNamedSchemaOneOfTransformer.spec.ts | Adds coverage for the new transformer behavior (flattening + optional properties + x-platforms) |
| utils/replaceOneOf.ts | Preserves x-platforms from earlier variants when later variants omit it during merge |
| utils/replaceOneOf.spec.ts | Adds a unit test validating x-platforms retention behavior |
| schemas/paths/examples/webhook/webhook_event.json | Adds source to the webhook event example payload |
| schemas/paths/event.yaml | Updates GET /events/{event_id} description to explain EventDevice vs EventEdge return shape |
| schemas/paths/edge.yaml | Switches POST /edge 200 response schema from EdgeResponse to EventEdge |
| schemas/components/schemas/EventEdge.yaml | Adds new EventEdge schema definition for Automation Intelligence events |
| schemas/components/schemas/EventDevice.yaml | Adds new EventDevice schema definition for identification + Smart Signals events |
| schemas/components/schemas/EventBase.yaml | Adds new base schema for shared event identifiers/metadata |
| schemas/components/schemas/Event.yaml | Redefines Event as a source-discriminated union of EventDevice and EventEdge |
| schemas/components/schemas/EdgeResponse.yaml | Removes legacy EdgeResponse schema (replaced by EventEdge) |
| .github/workflows/sync-server-side-sdks-schema.yml | Points Python/PHP schema sync to the new flat v4 schema output |
| .changeset/event-edge.md | Adds a changeset describing the schema/model changes and /edge response update |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Contributor
🚀 Following releases will be created using changesets from this PR:fingerprint-pro-server-api-openapi@3.8.0Minor Changes
|
Contributor
Author
|
@copilot review |
Contributor
Reviewed the current state: tests (102/102), build, typecheck, and |
Sibling const next to $ref is ignored by generators. Flatten still unwraps to an optional EventSource $ref.
Keep the same source form as EventRuleActionAllow. Bare oneOf parents now run the same normalizeRefSiblings pass on variants.
Contributor
Author
|
This was a prototype done as part of a spike. Closing now, still usable as a reference during the production implementation. |
This branch was successfully deployed
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
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.
SPIKE. Do not merge. Option C for INTER-2457. Distinct from the earlier spike that left
EventasoneOfin every SDK schema.EventisEventDevice | EventEdge, discriminatorsource.fingerprint-server-api-v4-flat.yaml(Event flattened,sourceoptional,start/endstill date|int).v4-normalized.yamlalso flattens Event (and still splitsstart/end).POST /edgereturnsEventEdge.EdgeResponseremoved.v4-flat.yaml.EventEdgehas nox-platforms(nosdk.platformon edge).EventDevicestill marksurl/bot_infoas browser.EventDevice; wrap at HTTP).sourceon both variants isallOf: [$ref EventSource, const]likeEventRuleAction.type. Flatten still unwraps to an optional$ref.SDK spikes (option C)
Discussion point: flatten property order
flattenNamedSchemaOneOfTransformeremits Event properties inEventDeviceorder, not the last published Event order.sourcemoves from 3rd toward the VPN block. JSON and named accessors are fine. Two generated breaks:Event(ctor:sourceis no longer the 3rd arg;Option<string>slots can silently mis-bind. See dotnet-sdk#201.searchEventslast two optionals swapped (source↔active_call). See php-sdk#272.Fix if we need a literal no-break: reorder flattened
Event.propertiesto the last published Event key order after merge.Discussion point:
sourcerequired on the union, optional in flat SDKssourcehas to be required onEventDevice/EventEdgefor the discriminator. JSON Schema could leave it optional on Device only, but OpenAPI codegen treats a missing discriminator as undefined. Flat SDK schemas still strip it fromrequired. Generated the unflattened union once for Java/Go/Python/.NET/PHP: same shapes asEventRuleAction. No nestedSourceEnum. Later majors: stop flattening + default omit todevice(JavaUnknownEvent/ Go both-nil are wrong for missingsource). PHP stays a merged bag until templates change, same as RuleAction.Known: EventEdge YAML duplication
Request/IP fields (
url,bot_info,ip_info,proxy*,vpn*) are copied onEventDeviceandEventEdge. They can drift.Known: flattened Event keeps Device
x-platformsonurl/bot_infoThose tags mean JS-agent identification (
urlis page URL,bot_infois BotD). Edge has the same fields from the HTTP request you POST, so it omitsx-platforms. Flatten keeps the Device tags when Edge omits them, so mergedEvent.url/bot_infostaybrowser. SDK generators ignorex-platforms; this is schema metadata only.To fix: stop copying
x-platformsonto overlapping fields, or dropurl/bot_infotags on the flattenedEvent.