diff --git a/package.json b/package.json index a673b99a9b1..2b4364f73dc 100644 --- a/package.json +++ b/package.json @@ -17,8 +17,10 @@ "clean": "rm -rf **/dist **/build **/.build **/node_modules **/.gradle **/vendor **/bin **/obj **/__pycache__ || true", "cli": "yarn workspace scripts start", "docker:setup": "./scripts/docker/setup.sh", + "eslint": "eslint", "fix:json": "eslint '**/*.json' --fix", "github-actions:lint": "eslint '.github/**/*.yml'", + "lint-staged": "lint-staged", "postinstall": "husky && yarn workspace eslint-plugin-automation-custom build", "playground:browser": "yarn workspace javascript-browser-playground start", "scripts:build": "yarn workspace scripts build:actions", @@ -48,5 +50,6 @@ "engines": { "node": "^24.0.0", "yarn": "^4.0.0" - } + }, + "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e" } diff --git a/specs/insights/common/schemas/AddedToCartObjectIDs.yml b/specs/insights/common/schemas/AddedToCartObjectIDs.yml index cb794939f41..e7088c50bad 100644 --- a/specs/insights/common/schemas/AddedToCartObjectIDs.yml +++ b/specs/insights/common/schemas/AddedToCartObjectIDs.yml @@ -27,6 +27,8 @@ properties: $ref: './EventAttributes.yml#/timestamp' value: $ref: './EventAttributes.yml#/value' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/AddedToCartObjectIDsAfterSearch.yml b/specs/insights/common/schemas/AddedToCartObjectIDsAfterSearch.yml index 7dab5cb642b..3392ad597f6 100644 --- a/specs/insights/common/schemas/AddedToCartObjectIDsAfterSearch.yml +++ b/specs/insights/common/schemas/AddedToCartObjectIDsAfterSearch.yml @@ -28,6 +28,8 @@ properties: $ref: './EventAttributes.yml#/timestamp' value: $ref: './EventAttributes.yml#/value' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ClickedFilters.yml b/specs/insights/common/schemas/ClickedFilters.yml index 5b5c79c8817..0126dcfe185 100644 --- a/specs/insights/common/schemas/ClickedFilters.yml +++ b/specs/insights/common/schemas/ClickedFilters.yml @@ -16,6 +16,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ClickedObjectIDs.yml b/specs/insights/common/schemas/ClickedObjectIDs.yml index 0b1c43588f5..8ed76319c94 100644 --- a/specs/insights/common/schemas/ClickedObjectIDs.yml +++ b/specs/insights/common/schemas/ClickedObjectIDs.yml @@ -20,6 +20,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml b/specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml index 40fe705b34b..1800f945358 100644 --- a/specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml +++ b/specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml @@ -24,6 +24,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ConvertedFilters.yml b/specs/insights/common/schemas/ConvertedFilters.yml index b3e75a874b0..b7f56b664b7 100644 --- a/specs/insights/common/schemas/ConvertedFilters.yml +++ b/specs/insights/common/schemas/ConvertedFilters.yml @@ -15,6 +15,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ConvertedObjectIDs.yml b/specs/insights/common/schemas/ConvertedObjectIDs.yml index f4f3945914f..cf8f80ecdc2 100644 --- a/specs/insights/common/schemas/ConvertedObjectIDs.yml +++ b/specs/insights/common/schemas/ConvertedObjectIDs.yml @@ -20,6 +20,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml b/specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml index f346f6c16b2..dbd68cbd45d 100644 --- a/specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml +++ b/specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml @@ -24,6 +24,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/EventAttributes.yml b/specs/insights/common/schemas/EventAttributes.yml index c9c786806f8..e65f96916da 100644 --- a/specs/insights/common/schemas/EventAttributes.yml +++ b/specs/insights/common/schemas/EventAttributes.yml @@ -83,6 +83,32 @@ filters: maxItems: 20 example: ['brand:apple'] +agent: + description: a set of fields for matching events to agent responses. + type: object + properties: + agentID: + description: the ID of the agent to which this event is related. + type: string + minLength: 1 + maxLength: 256 + messageID: + description: the ID of the agent message to which this event is related. + type: string + minLength: 1 + maxLength: 256 + toolCallID: + description: the ID of the instant search tool to which this event is related. + type: string + minLength: 1 + maxLength: 256 + conversationID: + description: the ID of the instant search conversation to which this event is related. + type: string + minLength: 1 + maxLength: 256 + required: + - messageID positions: type: array items: @@ -181,6 +207,17 @@ currency: description: Three-letter [currency code](https://www.iso.org/iso-4217-currency-codes.html). example: EUR +sessionID: + type: string + # We don't necessarily need to be this restrictive: + pattern: '[0-9a-f]{32}' + minLength: 32 + maxLength: 32 + description: | + Unique identifier for a session + [TODO]: Document here where this is derived and how it is used. + example: 3e48cd0616e466948dd85abf5c3fbbe2 + value: description: | Total monetary value of this event in units of `currency`. diff --git a/specs/insights/common/schemas/EventsItems.yml b/specs/insights/common/schemas/EventsItems.yml index dff4c0eea07..6cfd792d1fb 100644 --- a/specs/insights/common/schemas/EventsItems.yml +++ b/specs/insights/common/schemas/EventsItems.yml @@ -11,3 +11,4 @@ oneOf: - $ref: './ConvertedFilters.yml' - $ref: './ViewedObjectIDs.yml' - $ref: './ViewedFilters.yml' + - $ref: './InstantSearchTelemetry.yml' diff --git a/specs/insights/common/schemas/InstantSearchTelemetry.yml b/specs/insights/common/schemas/InstantSearchTelemetry.yml new file mode 100644 index 00000000000..c6ad11414b2 --- /dev/null +++ b/specs/insights/common/schemas/InstantSearchTelemetry.yml @@ -0,0 +1,32 @@ +type: object +title: Instant Search Telemetry Event +description: | + Tracks an initial user interaction with the Agentic Analytics API. +properties: + eventType: + $ref: './InstantSearchTelemetryEvent.yml' + eventName: + $ref: './EventAttributes.yml#/eventName' + sessionID: + $ref: './EventAttributes.yml#/sessionID' + userToken: + $ref: './EventAttributes.yml#/userToken' + # This is not specified in the Agentic Analytics document but is optional in all other schemas + # Can we keep it here for consistency? + authenticatedUserToken: + $ref: './EventAttributes.yml#/authenticatedUserToken' + timestamp: + $ref: './EventAttributes.yml#/timestamp' + performance: + description: free form object for performance data. + type: object + widgets: + description: free form object for widget information. + type: object +required: + - eventName + - sessionID + - eventType + - userToken +x-discriminator-fields: + - eventType diff --git a/specs/insights/common/schemas/InstantSearchTelemetryEvent.yml b/specs/insights/common/schemas/InstantSearchTelemetryEvent.yml new file mode 100644 index 00000000000..1b6ead685ac --- /dev/null +++ b/specs/insights/common/schemas/InstantSearchTelemetryEvent.yml @@ -0,0 +1,2 @@ +type: string +enum: [instantsearch_telemetry] diff --git a/specs/insights/common/schemas/PurchasedObjectIDs.yml b/specs/insights/common/schemas/PurchasedObjectIDs.yml index f8d3a61f038..70155afe64a 100644 --- a/specs/insights/common/schemas/PurchasedObjectIDs.yml +++ b/specs/insights/common/schemas/PurchasedObjectIDs.yml @@ -27,6 +27,8 @@ properties: $ref: './EventAttributes.yml#/timestamp' value: $ref: './EventAttributes.yml#/value' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/PurchasedObjectIDsAfterSearch.yml b/specs/insights/common/schemas/PurchasedObjectIDsAfterSearch.yml index 1932a7e4ebf..baf6683f885 100644 --- a/specs/insights/common/schemas/PurchasedObjectIDsAfterSearch.yml +++ b/specs/insights/common/schemas/PurchasedObjectIDsAfterSearch.yml @@ -26,6 +26,8 @@ properties: $ref: './EventAttributes.yml#/timestamp' value: $ref: './EventAttributes.yml#/value' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ViewedFilters.yml b/specs/insights/common/schemas/ViewedFilters.yml index 5e7a1356e46..ff19351dbe3 100644 --- a/specs/insights/common/schemas/ViewedFilters.yml +++ b/specs/insights/common/schemas/ViewedFilters.yml @@ -19,6 +19,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ViewedObjectIDs.yml b/specs/insights/common/schemas/ViewedObjectIDs.yml index aba9c3b1939..caabc67abf0 100644 --- a/specs/insights/common/schemas/ViewedObjectIDs.yml +++ b/specs/insights/common/schemas/ViewedObjectIDs.yml @@ -16,6 +16,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/paths/pushEvents.yml b/specs/insights/paths/pushEvents.yml index 8d456d6add9..09f0ba221e7 100644 --- a/specs/insights/paths/pushEvents.yml +++ b/specs/insights/paths/pushEvents.yml @@ -185,7 +185,21 @@ post: userToken: anonymous-user-1 authenticatedUserToken: user-1 filters: ['category:books'] - + InstantSearchTelemetry: + summary: InstantSearch Telemetry event + value: + events: + - eventName: My Event Name + eventType: instantsearch_telemetry + userToken: anonymous-user-1 + sessionID: f47ac10b-58cc-4372-a567-0e02b2c3d479 + client_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 + performance: + foo: 343 + bar: 'blah' + widgets: + ping: + pong: 21 responses: '200': description: OK @@ -197,11 +211,7 @@ post: Success: summary: Events successfully sent to the Insights API description: >- - Success indicates that the Insights API received the events correctly, - and that event properties are formatted correctly. - Success doesn't imply that the event can be used by any Algolia feature. - For example, the Insights API doesn't check if the index name you provided exists, - or if the object IDs exist in your index. + Success indicates that the Insights API received the events correctly, and that event properties are formatted correctly. Success doesn't imply that the event can be used by any Algolia feature. For example, the Insights API doesn't check if the index name you provided exists, or if the object IDs exist in your index. value: status: 200 message: OK @@ -283,8 +293,7 @@ post: NoEvents: summary: No events description: >- - This can happen if you're sending an empty `events` array, - or if you try to send a single event object instead of the `events` array. + This can happen if you're sending an empty `events` array, or if you try to send a single event object instead of the `events` array. value: status: 422 message: No events to process @@ -360,8 +369,7 @@ post: WrongPositionsItems: summary: Wrong number of items in positions array description: >- - For click events with the `queryID` and `objectIDs` attributes, - you must include the `positions` attribute with the same number of items as the `objectIDs` attribute. + For click events with the `queryID` and `objectIDs` attributes, you must include the `positions` attribute with the same number of items as the `objectIDs` attribute. value: status: 422 message: Event of type click should have the same number of ObjectIDs and Positions