Release v0.4.0

Origin-SHA: 519a082a8e67851cd9177606b48235fb64be5073

Author: ryanio

AGENTS.md

@@ -24,6 +24,7 @@ pnpm run check-types   # TypeScript type checking
 | `src/helpers.ts` | Topic construction for Phoenix channel subscriptions |
 | `src/index.ts` | Public exports |
 | `test/client.spec.ts` | Unit tests with mock WebSocket |
+| `test/helpers.ts` | Test utilities for accessing private client internals (socket, channels) |
 | `test/mock-ws.ts` | Mock WebSocket server for testing |
 
 ## Review Checklist

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @opensea/stream-js
 
+## 0.4.0
+
+### Minor Changes
+
+- 4ff61ae: Add server-side event type filtering support. The `onEvents` method now passes `event_types` array in Phoenix channel join params, enabling the backend to filter events at subscription time. Individual `on*` methods remain backward-compatible.
+
 ## 0.3.1
 
 ### Patch Changes

package.json

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

src/client.ts

@@ -87,8 +87,12 @@ export class OpenSeaStreamClient {
     return this.socket.disconnect(callback)
   }
 
-  private createChannel = (topic: string): Channel => {
-    const channel = this.socket.channel(topic)
+  private createChannel = (
+    topic: string,
+    eventTypes?: EventType[],
+  ): Channel => {
+    const params = eventTypes ? { event_types: eventTypes } : {}
+    const channel = this.socket.channel(topic, params)
     channel
       .join()
       .receive("ok", () => this.info(`Successfully joined channel "${topic}"`))
@@ -98,11 +102,11 @@ export class OpenSeaStreamClient {
     return channel
   }
 
-  private getChannel = (topic: string): Channel => {
+  private getChannel = (topic: string, eventTypes?: EventType[]): Channel => {
     let channel = this.channels.get(topic)
     if (!channel) {
       this.debug(`Creating channel for topic: "${topic}"`)
-      channel = this.createChannel(topic)
+      channel = this.createChannel(topic, eventTypes)
     }
     return channel
   }
@@ -111,12 +115,13 @@ export class OpenSeaStreamClient {
     eventType: EventType,
     collectionSlug: string,
     callback: Callback<Event>,
+    eventTypes?: EventType[],
   ) => {
     this.socket.connect()
 
     const topic = collectionTopic(collectionSlug)
     this.debug(`Fetching channel ${topic}`)
-    const channel = this.getChannel(topic)
+    const channel = this.getChannel(topic, eventTypes)
     this.debug(`Subscribing to ${eventType} events on ${topic}`)
 
     const onClientEvent = this.onEvent
@@ -231,7 +236,7 @@ export class OpenSeaStreamClient {
     callback: Callback<BaseStreamMessage<unknown>>,
   ) => {
     const subscriptions = eventTypes.map(eventType =>
-      this.on(eventType, collectionSlug, callback),
+      this.on(eventType, collectionSlug, callback, eventTypes),
     )
 
     return () => {

test/client.spec.ts

@@ -343,3 +343,33 @@ describe("middleware", () => {
     streamClient.disconnect()
   })
 })
+
+describe("server-side event type filtering", () => {
+  test("onEvents passes event_types in join params", () => {
+    streamClient = new OpenSeaStreamClient(clientOpts)
+
+    const socket = getSocket(streamClient)
+    const channelSpy = vi.spyOn(socket, "channel")
+
+    streamClient.onEvents(
+      "c1",
+      [EventType.ITEM_LISTED, EventType.ITEM_SOLD],
+      vi.fn(),
+    )
+
+    expect(channelSpy).toHaveBeenCalledWith("collection:c1", {
+      event_types: [EventType.ITEM_LISTED, EventType.ITEM_SOLD],
+    })
+  })
+
+  test("individual on* methods do not pass event_types", () => {
+    streamClient = new OpenSeaStreamClient(clientOpts)
+
+    const socket = getSocket(streamClient)
+    const channelSpy = vi.spyOn(socket, "channel")
+
+    streamClient.onItemListed("c1", vi.fn())
+
+    expect(channelSpy).toHaveBeenCalledWith("collection:c1", {})
+  })
+})