Release v0.3.0

Author: ryanio

CHANGELOG.md

@@ -0,0 +1,7 @@
+# @opensea/stream-js
+
+## 0.3.0
+
+### Minor Changes
+
+- Add `version` field to `BaseStreamMessage` for out-of-order event resolution

README.md

@@ -171,6 +171,41 @@ client.onItemCancelled('collection-slug', (event) => {
 
 If you'd like to listen to an event from all collections use wildcard `*` for the `collectionSlug` parameter.
 
+# Event Versioning
+
+Every stream event includes a numeric `version` field that is **monotonically increasing per source entity**. Use it to handle out-of-order event delivery: when two events arrive for the same entity, the one with the higher `version` is the newer state.
+
+## Version scale depends on event type
+
+The backend emits whichever authoritative monotonic counter exists for the underlying entity, so the *scale* of `version` varies:
+
+| Event types | `version` semantic |
+| --- | --- |
+| `item_listed`, `item_cancelled`, `item_received_offer`, `item_received_bid`, `collection_offer`, `trait_offer`, `order_invalidate`, `order_revalidate` | Order revision counter (small monotonic integer per order) |
+| `item_transferred`, `item_sold`, `item_metadata_updated` | Epoch milliseconds of the event's source timestamp |
+
+Both representations are monotonic and sufficient for resolving out-of-order delivery, but the two scales are **not comparable to each other**. Never compare `version` across different event families or across unrelated entities — only compare versions for the same entity within the same event family.
+
+## Usage
+
+Scope your stored versions by event type (or by the source entity — order id for order-derived events, nft_id for item events):
+
+```typescript
+const latestOrderVersion = new Map<string, number>();
+
+client.onItemListed('*', (event) => {
+  const orderHash = event.payload.order_hash;
+  const prev = latestOrderVersion.get(orderHash) ?? 0;
+  if (event.version > prev) {
+    latestOrderVersion.set(orderHash, event.version);
+    // Process — this is newer state for this order
+  }
+  // Otherwise discard — we already have newer state for this order
+});
+```
+
+Multiple backend pods process events, DLQ replays can deliver older state, and normal Kafka processing can deliver events out of order. Comparing `version` within the same entity lets consumers always converge to the correct current state.
+
 # Types
 
 Types are included to make working with our event payload objects easier.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/stream-js",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "A TypeScript SDK to receive pushed updates from OpenSea over websocket",
   "license": "MIT",
   "author": "OpenSea Developers",

src/types.ts

@@ -70,6 +70,7 @@ export type Payload = {
 
 export type BaseStreamMessage<Payload> = {
   event_type: string
+  version: number
   sent_at: string
   payload: Payload
 }

test/client.spec.ts

@@ -133,6 +133,78 @@ describe("event streams", () => {
   })
 })
 
+describe("version", () => {
+  test("passes custom version to callback", () => {
+    const collectionSlug = "c1"
+
+    streamClient = new OpenSeaStreamClient({
+      ...clientOpts,
+      connectOptions: { transport: WebSocket },
+    })
+
+    const socket = getSocket(streamClient)
+    vi.spyOn(socket, "endPointURL").mockImplementation(
+      () => "ws://localhost:1234",
+    )
+
+    const onEvent = vi.fn()
+    streamClient.onEvents(collectionSlug, [EventType.ITEM_LISTED], event =>
+      onEvent(event),
+    )
+
+    const payload = mockEvent(
+      EventType.ITEM_LISTED,
+      {},
+      {
+        version: 1713300042000,
+      },
+    )
+
+    server.send(
+      encode({
+        topic: collectionTopic(collectionSlug),
+        event: EventType.ITEM_LISTED,
+        payload,
+      }),
+    )
+
+    expect(onEvent).toHaveBeenCalledWith(payload)
+    expect(onEvent.mock.calls[0][0].version).toBe(1713300042000)
+  })
+
+  test("includes default version in all events", () => {
+    const collectionSlug = "c1"
+
+    streamClient = new OpenSeaStreamClient({
+      ...clientOpts,
+      connectOptions: { transport: WebSocket },
+    })
+
+    const socket = getSocket(streamClient)
+    vi.spyOn(socket, "endPointURL").mockImplementation(
+      () => "ws://localhost:1234",
+    )
+
+    const onEvent = vi.fn()
+    streamClient.onEvents(collectionSlug, [EventType.ITEM_LISTED], event =>
+      onEvent(event),
+    )
+
+    const payload = mockEvent(EventType.ITEM_LISTED, {})
+
+    server.send(
+      encode({
+        topic: collectionTopic(collectionSlug),
+        event: EventType.ITEM_LISTED,
+        payload,
+      }),
+    )
+
+    expect(onEvent).toHaveBeenCalledWith(payload)
+    expect(onEvent.mock.calls[0][0].version).toBe(1713300000000)
+  })
+})
+
 describe("middleware", () => {
   test("single", () => {
     const collectionSlug = "c1"

test/helpers.ts

@@ -34,10 +34,13 @@ export const encode = ({
 export const mockEvent = <Payload = unknown>(
   eventType: EventType,
   payload: Payload,
+  overrides?: Partial<BaseStreamMessage<Payload>>,
 ): BaseStreamMessage<Payload> => {
   return {
     event_type: eventType,
+    version: 1713300000000,
     payload,
     sent_at: Date.now().toString(),
+    ...overrides,
   }
 }