@eventmodelers/node-kit 0.0.2

package/templates/realtime-agent/node_modules/@supabase/realtime-js/src/lib/websocket-factory.ts

@@ -0,0 +1,204 @@
+export interface WebSocketLike {
+  readonly CONNECTING: number
+  readonly OPEN: number
+  readonly CLOSING: number
+  readonly CLOSED: number
+  readonly readyState: number
+  readonly url: string
+  readonly protocol: string
+
+  /**
+   * Closes the socket, optionally providing a close code and reason.
+   */
+  close(code?: number, reason?: string): void
+  /**
+   * Sends data through the socket using the underlying implementation.
+   */
+  send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void
+
+  onopen: ((this: any, ev: Event) => any) | null
+  onmessage: ((this: any, ev: MessageEvent) => any) | null
+  onclose: ((this: any, ev: CloseEvent) => any) | null
+  onerror: ((this: any, ev: Event) => any) | null
+
+  /**
+   * Registers an event listener on the socket (compatible with browser WebSocket API).
+   */
+  addEventListener(type: string, listener: EventListener): void
+  /**
+   * Removes a previously registered event listener.
+   */
+  removeEventListener(type: string, listener: EventListener): void
+
+  // Add additional properties that may exist on WebSocket implementations
+  binaryType?: string
+  bufferedAmount?: number
+  extensions?: string
+  dispatchEvent?: (event: Event) => boolean
+}
+
+export interface WebSocketEnvironment {
+  type: 'native' | 'ws' | 'cloudflare' | 'unsupported'
+  /** WebSocket constructor for this environment, if available. */
+  wsConstructor?: typeof WebSocket
+  error?: string
+  workaround?: string
+}
+
+/**
+ * Extended globalThis with optional runtime-specific properties
+ * that may or may not exist depending on the environment.
+ */
+interface RuntimeGlobals {
+  WebSocket?: { new (url: string, protocols?: string | string[]): WebSocketLike }
+  WebSocketPair?: unknown
+  EdgeRuntime?: unknown
+}
+
+/**
+ * Utilities for creating WebSocket instances across runtimes.
+ */
+export class WebSocketFactory {
+  /**
+   * Static-only utility – prevent instantiation.
+   */
+  private constructor() {}
+  private static detectEnvironment(): WebSocketEnvironment {
+    if (typeof WebSocket !== 'undefined') {
+      return { type: 'native', wsConstructor: WebSocket }
+    }
+
+    const gt = globalThis as typeof globalThis & RuntimeGlobals
+    if (typeof globalThis !== 'undefined' && typeof gt.WebSocket !== 'undefined') {
+      return { type: 'native', wsConstructor: gt.WebSocket as typeof WebSocket }
+    }
+
+    const gl =
+      typeof global !== 'undefined' ? (global as typeof global & RuntimeGlobals) : undefined
+    if (gl && typeof gl.WebSocket !== 'undefined') {
+      return { type: 'native', wsConstructor: gl.WebSocket as typeof WebSocket }
+    }
+
+    if (
+      typeof globalThis !== 'undefined' &&
+      typeof gt.WebSocketPair !== 'undefined' &&
+      typeof globalThis.WebSocket === 'undefined'
+    ) {
+      return {
+        type: 'cloudflare',
+        error:
+          'Cloudflare Workers detected. WebSocket clients are not supported in Cloudflare Workers.',
+        workaround:
+          'Use Cloudflare Workers WebSocket API for server-side WebSocket handling, or deploy to a different runtime.',
+      }
+    }
+
+    if (
+      (typeof globalThis !== 'undefined' && gt.EdgeRuntime) ||
+      (typeof navigator !== 'undefined' && navigator.userAgent?.includes('Vercel-Edge'))
+    ) {
+      return {
+        type: 'unsupported',
+        error:
+          'Edge runtime detected (Vercel Edge/Netlify Edge). WebSockets are not supported in edge functions.',
+        workaround:
+          'Use serverless functions or a different deployment target for WebSocket functionality.',
+      }
+    }
+
+    // Use dynamic property access to avoid Next.js Edge Runtime static analysis warnings
+    const _process = (globalThis as Record<string, unknown>)['process'] as
+      | { versions?: { node?: string } }
+      | undefined
+    if (_process) {
+      const processVersions = _process['versions']
+      if (processVersions && processVersions['node']) {
+        // Remove 'v' prefix if present and parse the major version
+        const versionString = processVersions['node']
+        const nodeVersion = parseInt(versionString.replace(/^v/, '').split('.')[0])
+
+        // Node.js 22+ should have native WebSocket
+        if (nodeVersion >= 22) {
+          // Check if native WebSocket is available (should be in Node.js 22+)
+          if (typeof globalThis.WebSocket !== 'undefined') {
+            return { type: 'native', wsConstructor: globalThis.WebSocket }
+          }
+          // If not available, user needs to provide it
+          return {
+            type: 'unsupported',
+            error: `Node.js ${nodeVersion} detected but native WebSocket not found.`,
+            workaround: 'Provide a WebSocket implementation via the transport option.',
+          }
+        }
+
+        // Node.js < 22 doesn't have native WebSocket
+        return {
+          type: 'unsupported',
+          error: `Node.js ${nodeVersion} detected without native WebSocket support.`,
+          workaround:
+            'For Node.js < 22, install "ws" package and provide it via the transport option:\n' +
+            'import ws from "ws"\n' +
+            'new RealtimeClient(url, { transport: ws })',
+        }
+      }
+    }
+
+    return {
+      type: 'unsupported',
+      error: 'Unknown JavaScript runtime without WebSocket support.',
+      workaround:
+        "Ensure you're running in a supported environment (browser, Node.js, Deno) or provide a custom WebSocket implementation.",
+    }
+  }
+
+  /**
+   * Returns the best available WebSocket constructor for the current runtime.
+   *
+   * @category Realtime
+   *
+   * @example Example with error handling
+   * ```ts
+   * try {
+   *   const WS = WebSocketFactory.getWebSocketConstructor()
+   *   const socket = new WS('wss://example.com/socket')
+   * } catch (error) {
+   *   console.error('WebSocket not available in this environment.', error)
+   * }
+   * ```
+   */
+  public static getWebSocketConstructor(): typeof WebSocket {
+    const env = this.detectEnvironment()
+    if (env.wsConstructor) {
+      return env.wsConstructor
+    }
+    let errorMessage = env.error || 'WebSocket not supported in this environment.'
+    if (env.workaround) {
+      errorMessage += `\n\nSuggested solution: ${env.workaround}`
+    }
+    throw new Error(errorMessage)
+  }
+
+  /**
+   * Detects whether the runtime can establish WebSocket connections.
+   *
+   * @category Realtime
+   *
+   * @example Example in a Node.js script
+   * ```ts
+   * if (!WebSocketFactory.isWebSocketSupported()) {
+   *   console.error('WebSockets are required for this script.')
+   *   process.exitCode = 1
+   * }
+   * ```
+   */
+  public static isWebSocketSupported(): boolean {
+    try {
+      const env = this.detectEnvironment()
+      return env.type === 'native' || env.type === 'ws'
+    } catch {
+      return false
+    }
+  }
+}
+
+export default WebSocketFactory

package/templates/realtime-agent/node_modules/@supabase/realtime-js/src/phoenix/channelAdapter.ts

@@ -0,0 +1,149 @@
+import { Channel } from '@supabase/phoenix'
+import { CHANNEL_STATES, MAX_PUSH_BUFFER_SIZE } from '../lib/constants'
+import type { RealtimeChannelOptions } from '../RealtimeChannel'
+import SocketAdapter from './socketAdapter'
+import type {
+  ChannelBindingCallback,
+  ChannelOnMessage,
+  ChannelOnErrorCallback,
+  ChannelFilterBindings,
+  Params,
+  ChannelState,
+  Push,
+  Timer,
+} from './types'
+
+export default class ChannelAdapter {
+  private channel: Channel
+  private socket: SocketAdapter
+
+  constructor(socket: SocketAdapter, topic: string, params: RealtimeChannelOptions) {
+    const phoenixParams = phoenixChannelParams(params)
+    this.channel = socket.getSocket().channel(topic, phoenixParams)
+    this.socket = socket
+  }
+
+  get state(): ChannelState {
+    return this.channel.state
+  }
+
+  set state(state: ChannelState) {
+    this.channel.state = state
+  }
+
+  get joinedOnce(): boolean {
+    return this.channel.joinedOnce
+  }
+
+  get joinPush(): Push {
+    return this.channel.joinPush
+  }
+
+  get rejoinTimer(): Timer {
+    return this.channel.rejoinTimer
+  }
+
+  on(event: string, callback: ChannelBindingCallback): number {
+    return this.channel.on(event, callback)
+  }
+
+  off(event: string, refNumber?: number) {
+    this.channel.off(event, refNumber)
+  }
+
+  subscribe(timeout?: number): Push {
+    return this.channel.join(timeout)
+  }
+
+  unsubscribe(timeout?: number): Push {
+    return this.channel.leave(timeout)
+  }
+
+  teardown() {
+    this.channel.teardown()
+  }
+
+  onClose(callback: ChannelBindingCallback) {
+    this.channel.onClose(callback)
+  }
+
+  onError(callback: ChannelOnErrorCallback): number {
+    return this.channel.onError(callback)
+  }
+
+  push(event: string, payload: { [key: string]: any }, timeout?: number): Push {
+    let push: Push
+
+    try {
+      push = this.channel.push(event, payload, timeout)
+    } catch (error) {
+      throw new Error(
+        `tried to push '${event}' to '${this.channel.topic}' before joining. Use channel.subscribe() before pushing events`
+      )
+    }
+
+    if (this.channel.pushBuffer.length > MAX_PUSH_BUFFER_SIZE) {
+      const removedPush = this.channel.pushBuffer.shift()!
+      removedPush.cancelTimeout()
+      this.socket.log(
+        'channel',
+        `discarded push due to buffer overflow: ${removedPush.event}`,
+        removedPush.payload()
+      )
+    }
+    return push
+  }
+
+  updateJoinPayload(payload: Record<string, any>) {
+    const oldPayload = this.channel.joinPush.payload()
+    this.channel.joinPush.payload = () => ({ ...oldPayload, ...payload })
+  }
+
+  canPush() {
+    return this.socket.isConnected() && this.state === CHANNEL_STATES.joined
+  }
+
+  isJoined() {
+    return this.state === CHANNEL_STATES.joined
+  }
+
+  isJoining() {
+    return this.state === CHANNEL_STATES.joining
+  }
+
+  isClosed() {
+    return this.state === CHANNEL_STATES.closed
+  }
+
+  isLeaving() {
+    return this.state === CHANNEL_STATES.leaving
+  }
+
+  updateFilterBindings(filterBindings: ChannelFilterBindings) {
+    this.channel.filterBindings = filterBindings
+  }
+
+  updatePayloadTransform(callback: ChannelOnMessage) {
+    this.channel.onMessage = callback
+  }
+
+  /**
+   * @internal
+   */
+  getChannel() {
+    return this.channel
+  }
+}
+
+function phoenixChannelParams(options: RealtimeChannelOptions): Params {
+  return {
+    config: {
+      ...{
+        broadcast: { ack: false, self: false },
+        presence: { key: '', enabled: false },
+        private: false,
+      },
+      ...options.config,
+    },
+  }
+}

package/templates/realtime-agent/node_modules/@supabase/realtime-js/src/phoenix/presenceAdapter.ts

@@ -0,0 +1,116 @@
+import { Presence } from '@supabase/phoenix'
+import type { PresenceState, PresenceStates } from './types'
+import type {
+  RealtimePresenceOptions,
+  RealtimePresenceState,
+  Presence as RealtimePresenceType,
+} from '../RealtimePresence'
+import ChannelAdapter from './channelAdapter'
+
+export default class PresenceAdapter {
+  private presence: Presence
+
+  constructor(channel: ChannelAdapter, opts?: RealtimePresenceOptions) {
+    const phoenixOptions = phoenixPresenceOptions(opts)
+    this.presence = new Presence(channel.getChannel(), phoenixOptions)
+
+    this.presence.onJoin((key, currentPresence, newPresence) => {
+      const onJoinPayload = PresenceAdapter.onJoinPayload(key, currentPresence, newPresence)
+      channel.getChannel().trigger('presence', onJoinPayload)
+    })
+
+    this.presence.onLeave((key, currentPresence, leftPresence) => {
+      const onLeavePayload = PresenceAdapter.onLeavePayload(key, currentPresence, leftPresence)
+      channel.getChannel().trigger('presence', onLeavePayload)
+    })
+
+    this.presence.onSync(() => {
+      channel.getChannel().trigger('presence', { event: 'sync' })
+    })
+  }
+
+  get state() {
+    return PresenceAdapter.transformState(this.presence.state)
+  }
+
+  /**
+   * @private
+   * Remove 'metas' key
+   * Change 'phx_ref' to 'presence_ref'
+   * Remove 'phx_ref' and 'phx_ref_prev'
+   *
+   * @example Transform state
+   * // returns {
+   *  abc123: [
+   *    { presence_ref: '2', user_id: 1 },
+   *    { presence_ref: '3', user_id: 2 }
+   *  ]
+   * }
+   * RealtimePresence.transformState({
+   *  abc123: {
+   *    metas: [
+   *      { phx_ref: '2', phx_ref_prev: '1' user_id: 1 },
+   *      { phx_ref: '3', user_id: 2 }
+   *    ]
+   *  }
+   * })
+   *
+   */
+  static transformState(state: PresenceStates): RealtimePresenceState {
+    state = cloneState(state)
+
+    return Object.getOwnPropertyNames(state).reduce((newState, key) => {
+      const presences = state[key]
+      newState[key] = transformState(presences)
+
+      return newState
+    }, {} as RealtimePresenceState)
+  }
+
+  static onJoinPayload(key: string, currentPresence: PresenceState, newPresence: PresenceState) {
+    const currentPresences = parseCurrentPresences(currentPresence)
+    const newPresences = transformState(newPresence)
+
+    return {
+      event: 'join',
+      key,
+      currentPresences,
+      newPresences,
+    }
+  }
+
+  static onLeavePayload(key: string, currentPresence: PresenceState, leftPresence: PresenceState) {
+    const currentPresences = parseCurrentPresences(currentPresence)
+    const leftPresences = transformState(leftPresence)
+
+    return {
+      event: 'leave',
+      key,
+      currentPresences,
+      leftPresences,
+    }
+  }
+}
+
+function transformState(presences: PresenceState) {
+  return presences.metas.map((presence) => {
+    presence['presence_ref'] = presence['phx_ref']
+
+    delete presence['phx_ref']
+    delete presence['phx_ref_prev']
+
+    return presence
+  }) as RealtimePresenceType[]
+}
+
+function cloneState(state: PresenceStates): PresenceStates {
+  return JSON.parse(JSON.stringify(state))
+}
+
+function phoenixPresenceOptions(opts?: RealtimePresenceOptions) {
+  return opts?.events && { events: opts.events }
+}
+
+function parseCurrentPresences(currentPresences?: PresenceState) {
+  return currentPresences?.metas ? transformState(currentPresences) : []
+}

package/templates/realtime-agent/node_modules/@supabase/realtime-js/src/phoenix/socketAdapter.ts

@@ -0,0 +1,168 @@
+import { Socket } from '@supabase/phoenix'
+import type {
+  Message,
+  SocketOnClose,
+  SocketOnMessage,
+  SocketOnOpen,
+  SocketOnError,
+  SocketOptions,
+  SocketStateChangeCallbacks,
+  Vsn,
+  Encode,
+  Decode,
+  HeartbeatCallback,
+  Timer,
+} from './types'
+import { CONNECTION_STATE, ConnectionState } from '../lib/constants'
+import type { HeartbeatTimer, WebSocketLikeConstructor } from '../RealtimeClient'
+
+export default class SocketAdapter {
+  private socket: Socket
+
+  constructor(endPoint: string, options: SocketOptions) {
+    this.socket = new Socket(endPoint, options)
+  }
+
+  get timeout(): number {
+    return this.socket.timeout
+  }
+
+  get endPoint(): string {
+    return this.socket.endPoint
+  }
+
+  get transport(): WebSocketLikeConstructor {
+    return this.socket.transport as WebSocketLikeConstructor
+  }
+
+  get heartbeatIntervalMs(): number {
+    return this.socket.heartbeatIntervalMs
+  }
+
+  get heartbeatCallback(): HeartbeatCallback {
+    return this.socket.heartbeatCallback
+  }
+
+  set heartbeatCallback(callback: HeartbeatCallback) {
+    this.socket.heartbeatCallback = callback
+  }
+
+  get heartbeatTimer(): HeartbeatTimer {
+    return this.socket.heartbeatTimer
+  }
+
+  get pendingHeartbeatRef(): string | null {
+    return this.socket.pendingHeartbeatRef
+  }
+
+  get reconnectTimer(): Timer {
+    return this.socket.reconnectTimer
+  }
+
+  get vsn(): Vsn {
+    return this.socket.vsn
+  }
+
+  get encode(): Encode<void> {
+    return this.socket.encode
+  }
+
+  get decode(): Decode<void> {
+    return this.socket.decode
+  }
+
+  get reconnectAfterMs(): (tries: number) => number {
+    return this.socket.reconnectAfterMs
+  }
+
+  get sendBuffer(): (() => void)[] {
+    return this.socket.sendBuffer
+  }
+
+  get stateChangeCallbacks(): SocketStateChangeCallbacks {
+    return this.socket.stateChangeCallbacks
+  }
+
+  connect() {
+    this.socket.connect()
+  }
+
+  disconnect(
+    callback: () => void,
+    code?: number,
+    reason?: string,
+    timeout: number = 10000
+  ): Promise<'ok' | 'timeout'> {
+    return new Promise((resolve) => {
+      setTimeout(() => resolve('timeout'), timeout)
+      this.socket.disconnect(
+        () => {
+          callback()
+          resolve('ok')
+        },
+        code,
+        reason
+      )
+    })
+  }
+
+  push(data: Message<Record<string, unknown>>) {
+    this.socket.push(data)
+  }
+
+  log(kind: string, msg: string, data?: any) {
+    this.socket.log(kind, msg, data)
+  }
+
+  makeRef(): string {
+    return this.socket.makeRef()
+  }
+
+  onOpen(callback: SocketOnOpen) {
+    this.socket.onOpen(callback)
+  }
+
+  onClose(callback: SocketOnClose) {
+    this.socket.onClose(callback)
+  }
+
+  onError(callback: SocketOnError) {
+    this.socket.onError(callback)
+  }
+
+  onMessage(callback: SocketOnMessage) {
+    this.socket.onMessage(callback)
+  }
+
+  isConnected() {
+    return this.socket.isConnected()
+  }
+
+  isConnecting() {
+    return this.socket.connectionState() == CONNECTION_STATE.connecting
+  }
+
+  isDisconnecting() {
+    return this.socket.connectionState() == CONNECTION_STATE.closing
+  }
+
+  connectionState(): ConnectionState {
+    // @ts-ignore - requires better typing and exposing type in phoenix
+    return this.socket.connectionState()
+  }
+
+  endPointURL(): string {
+    return this.socket.endPointURL()
+  }
+
+  sendHeartbeat() {
+    this.socket.sendHeartbeat()
+  }
+
+  /**
+   * @internal
+   */
+  getSocket() {
+    return this.socket
+  }
+}

package/templates/realtime-agent/node_modules/@supabase/realtime-js/src/phoenix/types.ts

@@ -0,0 +1,32 @@
+export type {
+  Socket,
+  SocketOptions,
+  SocketState,
+  SocketOnOpen,
+  SocketOnError,
+  SocketOnMessage,
+  SocketOnClose,
+  SocketStateChangeCallbacks,
+  Channel,
+  ChannelState,
+  ChannelEvent,
+  ChannelBindingCallback,
+  ChannelFilterBindings,
+  ChannelOnMessage,
+  ChannelOnErrorCallback,
+  PresenceState,
+  Message,
+  Params,
+  Transport,
+  Timer,
+  Vsn,
+  Encode,
+  Decode,
+  HeartbeatCallback,
+  HeartbeatStatus,
+} from '@supabase/phoenix'
+
+import type { Channel, PresenceState } from '@supabase/phoenix'
+
+export type Push = ReturnType<Channel['push']>
+export type PresenceStates = Record<string, PresenceState>