Merge branch 'main' into fix/jjl/format-opaque-uid-events-v2

.github/workflows/validate-typos.yml

@@ -0,0 +1,11 @@
+name: Typos
+on:
+  pull_request:
+
+jobs:
+  typos:
+    name: Check for language typos
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: crate-ci/[email protected]

.typos.toml

@@ -0,0 +1,2 @@
+[default.extend-identifiers]
+bneEmHKG2yUe = "bneEmHKG2yUe"

topsort-api-v2.yml

@@ -92,6 +92,9 @@ paths:
       tags:
         - Auctions
       summary: Create auctions
+      description: |
+        Use the `/auctions` endpoint to create auctions. Each batch of auction requests can be a combination of 
+        sponsored listing auctions and banner auctions. Each auction type has a unique body schemas.
       operationId: createAuctions
       requestBody:
         description: |
@@ -297,16 +300,16 @@ paths:
       tags:
         - Events
       summary: Report events
+      description: |
+        Use the `/events` endpoint to report user interactions and activity in on a marketplace:
+        - **Impressions** — a user viewed an asset.
+        - **Clicks** — a user clicked on an asset.
+        - **Purchases** — a user created an order.
+
+        Interactions require either a `resolvedBidId` from the `/v2/auctions` response or an `entity` that describes 
+        the entity to attribute.
       operationId: reportEvents
       requestBody:
-        description: |
-          Use the `/events` endpoint to notify Topsort about significant consumer interactions on the marketplace app:
-          - **Impressions** — a set of impressions means such promotables have become visible to the consumer.
-          - **Clicks** — a click is sent to Topsort when the consumer has clicked on a promotable.
-          - **Purchases** — a purchase is sent to Topsort once a consumer places an order.
-
-          For promoted interactions, include the `resolvedBidId` field from the `/v2/auctions` response.
-          For unpromoted interactions, include the `entity` field to describe what was interacted with.
         content:
           application/json:
             schema:
@@ -319,6 +322,51 @@ paths:
           $ref: '#/components/responses/UnauthorizedError'
         400:
           $ref: '#/components/responses/BadRequest'
+  /v2/events/beta/link-users:
+    post:
+      tags:
+        - Events
+      summary: '[Beta] Report Link Users'
+      description: |
+        Use the `/events/beta/link-users` endpoint to report to Topsort linked opaque user IDs.
+
+        This endpoint allows linking two opaque user IDs for attribution purposes. The `from` field represents the 
+        original opaque user ID, and the `to` field represents the target opaque user ID to be linked. The request 
+        will fail if the `from` and `to` opaque user IDs are the same.
+
+        Contact your sales representative to gain access to this endpoint and start using it.
+      x-beta: 'true'
+      operationId: linkUsers
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                from:
+                  type: string
+                  description: The opaque user ID of the original user account.
+                  minLength: 1
+                  maxLength: 64
+                to:
+                  type: string
+                  description: The opaque user ID of the target user account to be linked.
+                  minLength: 1
+                  maxLength: 64
+              required:
+                - from
+                - to
+              example:
+                from: 'user123'
+                to: 'user456'
+        required: true
+      responses:
+        204:
+          description: Users account link was reported successfully.
+        401:
+          $ref: '#/components/responses/UnauthorizedError'
+        400:
+          $ref: '#/components/responses/BadRequest'
 
 components:
   responses: