@supabase/realtime-js 2.79.1-canary.2 → 2.80.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/realtime-js",
-  "version": "2.79.1-canary.2",
+  "version": "2.80.0",
   "description": "Listen to realtime updates to your PostgreSQL database",
   "keywords": [
     "realtime",
@@ -28,9 +28,7 @@
   "author": "Supabase",
   "license": "MIT",
   "scripts": {
-    "clean": "rimraf dist docs/v2",
-    "format": "prettier --write \"{src,test}/**/*.ts\"",
-    "build": "npm run clean && npm run format && npm run build:main && npm run build:module",
+    "build": "npm run build:main && npm run build:module",
     "build:main": "tsc -p tsconfig.json",
     "build:module": "tsc -p tsconfig.module.json",
     "test": "vitest run",
@@ -43,9 +41,9 @@
   },
   "dependencies": {
     "@types/phoenix": "^1.6.6",
-    "ws": "^8.18.2",
     "@types/ws": "^8.18.1",
-    "@supabase/node-fetch": "2.6.15"
+    "tslib": "2.8.1",
+    "ws": "^8.18.2"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.16.4",
@@ -56,5 +54,8 @@
     "mock-socket": "^9.3.1",
     "nyc": "^15.1.0",
     "web-worker": "1.2.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
   }
 }

package/src/RealtimeChannel.ts

@@ -11,13 +11,19 @@ import type {
 import * as Transformers from './lib/transformers'
 import { httpEndpointURL } from './lib/transformers'
 
+type ReplayOption = {
+  since: number
+  limit?: number
+}
+
 export type RealtimeChannelOptions = {
   config: {
     /**
      * self option enables client to receive message it broadcast
      * ack option instructs server to acknowledge that broadcast message was received
+     * replay option instructs server to replay broadcast messages
      */
-    broadcast?: { self?: boolean; ack?: boolean }
+    broadcast?: { self?: boolean; ack?: boolean; replay?: ReplayOption }
     /**
      * key option is used to track presence payload across clients
      */
@@ -29,6 +35,41 @@ export type RealtimeChannelOptions = {
   }
 }
 
+type RealtimeChangesPayloadBase = {
+  schema: string
+  table: string
+}
+
+type RealtimeBroadcastChangesPayloadBase = RealtimeChangesPayloadBase & {
+  id: string
+}
+
+export type RealtimeBroadcastInsertPayload<T extends { [key: string]: any }> =
+  RealtimeBroadcastChangesPayloadBase & {
+    operation: `${REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.INSERT}`
+    record: T
+    old_record: null
+  }
+
+export type RealtimeBroadcastUpdatePayload<T extends { [key: string]: any }> =
+  RealtimeBroadcastChangesPayloadBase & {
+    operation: `${REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.UPDATE}`
+    record: T
+    old_record: T
+  }
+
+export type RealtimeBroadcastDeletePayload<T extends { [key: string]: any }> =
+  RealtimeBroadcastChangesPayloadBase & {
+    operation: `${REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.DELETE}`
+    record: null
+    old_record: T
+  }
+
+export type RealtimeBroadcastPayload<T extends { [key: string]: any }> =
+  | RealtimeBroadcastInsertPayload<T>
+  | RealtimeBroadcastUpdatePayload<T>
+  | RealtimeBroadcastDeletePayload<T>
+
 type RealtimePostgresChangesPayloadBase = {
   schema: string
   table: string
@@ -203,6 +244,10 @@ export default class RealtimeChannel {
 
     this.broadcastEndpointURL = httpEndpointURL(this.socket.endPoint)
     this.private = this.params.config.private || false
+
+    if (!this.private && this.params.config?.broadcast?.replay) {
+      throw `tried to use replay on public channel '${this.topic}'. It must be a private channel.`
+    }
   }
 
   /** Subscribe registers your client with the server */
@@ -386,6 +431,10 @@ export default class RealtimeChannel {
     callback: (payload: {
       type: `${REALTIME_LISTEN_TYPES.BROADCAST}`
       event: string
+      meta?: {
+        replayed?: boolean
+        id: string
+      }
       [key: string]: any
     }) => void
   ): RealtimeChannel
@@ -395,9 +444,49 @@ export default class RealtimeChannel {
     callback: (payload: {
       type: `${REALTIME_LISTEN_TYPES.BROADCAST}`
       event: string
+      meta?: {
+        replayed?: boolean
+        id: string
+      }
       payload: T
     }) => void
   ): RealtimeChannel
+  on<T extends Record<string, unknown>>(
+    type: `${REALTIME_LISTEN_TYPES.BROADCAST}`,
+    filter: { event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.ALL },
+    callback: (payload: {
+      type: `${REALTIME_LISTEN_TYPES.BROADCAST}`
+      event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.ALL
+      payload: RealtimeBroadcastPayload<T>
+    }) => void
+  ): RealtimeChannel
+  on<T extends { [key: string]: any }>(
+    type: `${REALTIME_LISTEN_TYPES.BROADCAST}`,
+    filter: { event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.INSERT },
+    callback: (payload: {
+      type: `${REALTIME_LISTEN_TYPES.BROADCAST}`
+      event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.INSERT
+      payload: RealtimeBroadcastInsertPayload<T>
+    }) => void
+  ): RealtimeChannel
+  on<T extends { [key: string]: any }>(
+    type: `${REALTIME_LISTEN_TYPES.BROADCAST}`,
+    filter: { event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.UPDATE },
+    callback: (payload: {
+      type: `${REALTIME_LISTEN_TYPES.BROADCAST}`
+      event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.UPDATE
+      payload: RealtimeBroadcastUpdatePayload<T>
+    }) => void
+  ): RealtimeChannel
+  on<T extends { [key: string]: any }>(
+    type: `${REALTIME_LISTEN_TYPES.BROADCAST}`,
+    filter: { event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.DELETE },
+    callback: (payload: {
+      type: `${REALTIME_LISTEN_TYPES.BROADCAST}`
+      event: REALTIME_POSTGRES_CHANGES_LISTEN_EVENT.DELETE
+      payload: RealtimeBroadcastDeletePayload<T>
+    }) => void
+  ): RealtimeChannel
   on<T extends { [key: string]: any }>(
     type: `${REALTIME_LISTEN_TYPES.SYSTEM}`,
     filter: {},
@@ -417,6 +506,68 @@ export default class RealtimeChannel {
     }
     return this._on(type, filter, callback)
   }
+  /**
+   * Sends a broadcast message explicitly via REST API.
+   *
+   * This method always uses the REST API endpoint regardless of WebSocket connection state.
+   * Useful when you want to guarantee REST delivery or when gradually migrating from implicit REST fallback.
+   *
+   * @param event The name of the broadcast event
+   * @param payload Payload to be sent (required)
+   * @param opts Options including timeout
+   * @returns Promise resolving to object with success status, and error details if failed
+   */
+  async httpSend(
+    event: string,
+    payload: any,
+    opts: { timeout?: number } = {}
+  ): Promise<{ success: true } | { success: false; status: number; error: string }> {
+    const authorization = this.socket.accessTokenValue
+      ? `Bearer ${this.socket.accessTokenValue}`
+      : ''
+
+    if (payload === undefined || payload === null) {
+      return Promise.reject('Payload is required for httpSend()')
+    }
+
+    const options = {
+      method: 'POST',
+      headers: {
+        Authorization: authorization,
+        apikey: this.socket.apiKey ? this.socket.apiKey : '',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        messages: [
+          {
+            topic: this.subTopic,
+            event,
+            payload: payload,
+            private: this.private,
+          },
+        ],
+      }),
+    }
+
+    const response = await this._fetchWithTimeout(
+      this.broadcastEndpointURL,
+      options,
+      opts.timeout ?? this.timeout
+    )
+
+    if (response.status === 202) {
+      return { success: true }
+    }
+
+    let errorMessage = response.statusText
+    try {
+      const errorBody = await response.json()
+      errorMessage = errorBody.error || errorBody.message || errorMessage
+    } catch {}
+
+    return Promise.reject(new Error(errorMessage))
+  }
+
   /**
    * Sends a message into the channel.
    *
@@ -436,6 +587,12 @@ export default class RealtimeChannel {
     opts: { [key: string]: any } = {}
   ): Promise<RealtimeChannelSendResponse> {
     if (!this._canPush() && args.type === 'broadcast') {
+      console.warn(
+        'Realtime send() is automatically falling back to REST API. ' +
+          'This behavior will be deprecated in the future. ' +
+          'Please use httpSend() explicitly for REST delivery.'
+      )
+
       const { event, payload: endpoint_payload } = args
       const authorization = this.socket.accessTokenValue
         ? `Bearer ${this.socket.accessTokenValue}`

package/src/RealtimeClient.ts

@@ -465,24 +465,10 @@ export default class RealtimeClient {
    * @internal
    */
   _resolveFetch = (customFetch?: Fetch): Fetch => {
-    let _fetch: Fetch
     if (customFetch) {
-      _fetch = customFetch
-    } else if (typeof fetch === 'undefined') {
-      // Node.js environment without native fetch
-      _fetch = (...args) =>
-        import('@supabase/node-fetch' as any)
-          .then(({ default: fetch }) => fetch(...args))
-          .catch((error) => {
-            throw new Error(
-              `Failed to load @supabase/node-fetch: ${error.message}. ` +
-                `This is required for HTTP requests in Node.js environments without native fetch.`
-            )
-          })
-    } else {
-      _fetch = fetch
+      return (...args) => customFetch(...args)
     }
-    return (...args) => _fetch(...args)
+    return (...args) => fetch(...args)
   }
 
   /**

package/src/lib/transformers.ts

@@ -251,8 +251,21 @@ export const toTimestampString = (value: RecordValue): RecordValue => {
 }
 
 export const httpEndpointURL = (socketUrl: string): string => {
-  let url = socketUrl
-  url = url.replace(/^ws/i, 'http')
-  url = url.replace(/(\/socket\/websocket|\/socket|\/websocket)\/?$/i, '')
-  return url.replace(/\/+$/, '') + '/api/broadcast'
+  const wsUrl = new URL(socketUrl)
+
+  wsUrl.protocol = wsUrl.protocol.replace(/^ws/i, 'http')
+
+  wsUrl.pathname = wsUrl.pathname
+    .replace(/\/+$/, '') // remove all trailing slashes
+    .replace(/\/socket\/websocket$/i, '') // remove the socket/websocket path
+    .replace(/\/socket$/i, '') // remove the socket path
+    .replace(/\/websocket$/i, '') // remove the websocket path
+
+  if (wsUrl.pathname === '' || wsUrl.pathname === '/') {
+    wsUrl.pathname = '/api/broadcast'
+  } else {
+    wsUrl.pathname = wsUrl.pathname + '/api/broadcast'
+  }
+
+  return wsUrl.href
 }

package/src/lib/version.ts

@@ -4,4 +4,4 @@
 // - Debugging and support (identifying which version is running)
 // - Telemetry and logging (version reporting in errors/analytics)
 // - Ensuring build artifacts match the published package version
-export const version = '2.79.1-canary.2'
+export const version = '2.80.0'