@symbo.ls/sdk 3.1.2 → 3.2.6

package/src/services/CollabService.js

@@ -0,0 +1,900 @@
+import { BaseService } from './BaseService.js'
+import { CollabClient } from '../utils/CollabClient.js'
+import { RootStateManager } from '../state/RootStateManager.js'
+import { rootBus } from '../state/rootEventBus.js'
+import { validateParams } from '../utils/validation.js'
+import { deepStringifyFunctions } from '@domql/utils'
+import { preprocessChanges } from '../utils/changePreprocessor.js'
+
+// Helper: clone a value while converting all functions to strings. This is
+// tailored for collab payloads (tuples / granularChanges) and is more robust
+// for nested array shapes than the generic DOMQL helper.
+const FUNCTION_META_KEYS = ['node', '__ref', '__element', 'parent', 'parse']
+
+function stringifyFunctionsForTransport(value, seen = new WeakMap()) {
+  if (value === null || typeof value !== 'object') {
+    return typeof value === 'function' ? value.toString() : value
+  }
+
+  if (seen.has(value)) {
+    return seen.get(value)
+  }
+
+  const clone = Array.isArray(value) ? [] : {}
+  seen.set(value, clone)
+
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      clone[i] = stringifyFunctionsForTransport(value[i], seen)
+    }
+    return clone
+  }
+
+  const keys = Object.keys(value)
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i]
+    if (!FUNCTION_META_KEYS.includes(key)) {
+      clone[key] = stringifyFunctionsForTransport(value[key], seen)
+    }
+  }
+
+  return clone
+}
+
+export class CollabService extends BaseService {
+  constructor(config) {
+    super(config)
+    this._client = null
+    this._stateManager = null
+    this._connected = false
+    this._connecting = false
+    this._connectPromise = null
+    this._connectionMeta = null
+    this._pendingConnectReject = null
+    this._undoStack = []
+    this._redoStack = []
+    this._isUndoRedo = false
+    // Store operations made while offline so they can be flushed once the
+    // socket reconnects.
+    this._pendingOps = []
+
+    this._onSocketConnect = this._onSocketConnect.bind(this)
+    this._onSocketDisconnect = this._onSocketDisconnect.bind(this)
+    this._onSocketError = this._onSocketError.bind(this)
+  }
+
+  init({ context }) {
+    super.init({ context })
+    // console.log('CollabService init')
+    // console.log(context)
+
+    // Defer state manager creation until a valid root state is present.
+    // The root state may not be set yet when the SDK is first initialised
+    // (e.g. inside initializeSDK()). We therefore create the manager lazily
+    // either when the SDK context is later updated or right before the first
+    // connection attempt.
+    if (context?.state) {
+      try {
+        this._stateManager = new RootStateManager(context.state)
+      } catch (err) {
+        this._setError(err)
+        throw err
+      }
+    }
+
+    this._setReady()
+  }
+
+  /**
+   * Overridden to re-initialise the state manager once the root state becomes
+   * available via a subsequent SDK `updateContext()` call.
+   */
+  updateContext(context = {}) {
+    // Preserve base behaviour
+    super.updateContext(context)
+
+    // Lazily (re)create state manager if a state tree is available
+    if (context.state) {
+      this._stateManager = new RootStateManager(context.state)
+    }
+  }
+
+  /**
+   * Ensure that the state manager exists. This is called right before any
+   * operation that requires access to the root state (e.g. `connect()`).
+   * Throws an explicit error if the root state is still missing so that the
+   * caller can react accordingly.
+   */
+  _ensureStateManager() {
+    if (!this._stateManager) {
+      if (!this._context?.state) {
+        throw new Error('[CollabService] Cannot operate without root state')
+      }
+      this._stateManager = new RootStateManager(this._context.state)
+    }
+
+    // 🌐 Ensure we always have a usable `__element` stub so that calls like
+    // `el.call('openNotification', …)` or `el.call('deepStringifyFunctions', …)` do not
+    // crash in headless / Node.js environments (e.g. integration tests).
+    const root = this._stateManager?.root
+
+    if (root && !root.__element) {
+      // Minimal no-op implementation of the DOMQL element API used here
+      root.__element = {
+        /**
+         * Very small subset of the DOMQL `call` API that we rely on inside the
+         * CollabService for browser notifications and data helpers.
+         * In a Node.js test context we simply log or return fallbacks.
+         */
+        call: (method, ...args) => {
+          switch (method) {
+            case 'openNotification': {
+              const [payload = {}] = args
+              const { type = 'info', title = '', message = '' } = payload
+              const logger = type === 'error' ? console.error : console.log
+              logger(`[Notification] ${title}${message ? ` – ${message}` : ''}`)
+              return
+            }
+            case 'deepStringifyFunctions': {
+              // Pass-through to the shared utility from `smbls`
+              return deepStringifyFunctions(...args)
+            }
+            default:
+              return {}
+          }
+        }
+      }
+    }
+  }
+
+  /* ---------- Connection Management ---------- */
+  async connect(options = {}) {
+    if (this._connectPromise) {
+      return this._connectPromise
+    }
+
+    this._connectPromise = (async () => {
+      this._connecting = true
+      this._connected = false
+
+      // Make sure we have the state manager ready now that the context should
+      // contain the root state (after updateSDKContext()).
+      this._ensureStateManager()
+
+      const mergedOptions = {
+        ...this._context,
+        ...options
+      }
+
+      let { authToken: jwt } = mergedOptions
+      const { projectId, branch = 'main', pro } = mergedOptions
+
+      if (!jwt && this._tokenManager) {
+        try {
+          jwt = await this._tokenManager.ensureValidToken()
+        } catch (error) {
+          console.warn(
+            '[CollabService] Failed to obtain auth token from token manager',
+            error
+          )
+        }
+
+        if (!jwt && typeof this._tokenManager.getAccessToken === 'function') {
+          jwt = this._tokenManager.getAccessToken()
+        }
+      }
+
+      if (!jwt) {
+        throw new Error('[CollabService] Cannot connect without auth token')
+      }
+
+      this._context = {
+        ...this._context,
+        authToken: jwt,
+        projectId,
+        branch,
+        pro
+      }
+
+      if (!projectId) {
+        const state = this._stateManager?.root
+        const el = state.__element
+        el.call('openNotification', {
+          type: 'error',
+          title: 'projectId is required',
+          message: 'projectId is required for CollabService connection'
+        })
+        throw new Error('projectId is required for CollabService connection')
+      }
+
+      // Disconnect existing connection if any
+      if (this._client) {
+        await this.disconnect()
+      }
+
+      this._client = new CollabClient({
+        jwt,
+        projectId,
+        branch,
+        live: Boolean(pro)
+      })
+
+      // Mark as connected once the socket establishes a connection. This prevents
+      // the SDK from being stuck waiting for an initial snapshot that may never
+      // arrive (e.g. for new/empty documents).
+      const { socket } = this._client
+
+      try {
+        await new Promise((resolve, reject) => {
+          if (!socket) {
+            reject(new Error('[CollabService] Socket instance missing'))
+            return
+          }
+
+          if (socket.connected) {
+            resolve()
+            return
+          }
+
+          /* eslint-disable no-use-before-define */
+          const cleanup = () => {
+            socket.off('connect', handleConnect)
+            socket.off('connect_error', handleError)
+            socket.off('error', handleError)
+            socket.off('disconnect', handleDisconnect)
+            if (this._pendingConnectReject === handleError) {
+              this._pendingConnectReject = null
+            }
+          }
+
+          const handleConnect = () => {
+            cleanup()
+            resolve()
+          }
+
+          const handleError = (error) => {
+            cleanup()
+            reject(
+              error instanceof Error
+                ? error
+                : new Error(String(error || 'Unknown connection error'))
+            )
+          }
+
+          const handleDisconnect = (reason) => {
+            handleError(
+              reason instanceof Error
+                ? reason
+                : new Error(
+                    `[CollabService] Socket disconnected before connect: ${
+                      reason || 'unknown'
+                    }`
+                  )
+            )
+          }
+
+          this._pendingConnectReject = handleError
+
+          socket.once('connect', handleConnect)
+          socket.once('connect_error', handleError)
+          socket.once('error', handleError)
+          socket.once('disconnect', handleDisconnect)
+          /* eslint-enable no-use-before-define */
+        })
+      } catch (error) {
+        socket?.disconnect()
+        this._client = null
+        this._connectionMeta = null
+        throw error
+      }
+
+      this._attachSocketLifecycleListeners()
+      if (socket?.connected) {
+        this._onSocketConnect()
+      }
+
+      // Set up event listeners
+      socket?.on('ops', ({ changes }) => {
+        console.log(`ops event`)
+        this._stateManager.applyChanges(changes, { fromSocket: true })
+      })
+
+      socket?.on('commit', ({ version }) => {
+        if (version) {
+          this._stateManager.setVersion(version)
+        }
+
+        // Inform UI about automatic commit
+        rootBus.emit('checkpoint:done', { version, origin: 'auto' })
+      })
+
+      // 🔄  Presence / members / cursor updates
+      socket?.on('clients', this._handleClientsEvent.bind(this))
+
+      // 🗜️  Bundle events – emitted by the dependency bundler service
+      socket?.on('bundle:done', this._handleBundleDoneEvent.bind(this))
+      socket?.on('bundle:error', this._handleBundleErrorEvent.bind(this))
+
+      // Flush any operations that were queued while we were offline.
+      if (this._pendingOps.length) {
+        console.log(
+          `[CollabService] Flushing ${this._pendingOps.length} offline operation batch(es)`
+        )
+        this._pendingOps.forEach(
+          ({ changes, granularChanges, orders, options: opOptions }) => {
+            const { message } = opOptions || {}
+            const ts = Date.now()
+            const payload = {
+              changes,
+              granularChanges,
+              orders,
+              ts
+            }
+            if (message) {
+              payload.message = message
+            }
+            this.socket.emit('ops', payload)
+          }
+        )
+        this._pendingOps.length = 0
+      }
+
+      await this._client.ready
+
+      this._connectionMeta = {
+        projectId,
+        branch,
+        live: Boolean(pro)
+      }
+
+      return this.getConnectionInfo()
+    })()
+
+    try {
+      return await this._connectPromise
+    } finally {
+      this._connecting = false
+      this._connectPromise = null
+    }
+  }
+
+  disconnect() {
+    if (this._client?.socket) {
+      if (this._pendingConnectReject) {
+        this._pendingConnectReject(
+          new Error('[CollabService] Connection attempt aborted')
+        )
+        this._pendingConnectReject = null
+      }
+      this._detachSocketLifecycleListeners()
+      if (typeof this._client.dispose === 'function') {
+        this._client.dispose()
+      } else {
+        this._client.socket.disconnect()
+      }
+    }
+    this._client = null
+    this._connected = false
+    this._connecting = false
+    this._connectionMeta = null
+    this._pendingConnectReject = null
+    console.log('[CollabService] Disconnected')
+  }
+
+  isConnected() {
+    return Boolean(this._connected && this._client?.socket?.connected)
+  }
+
+  getConnectionInfo() {
+    return {
+      connected: this.isConnected(),
+      connecting: this._connecting,
+      projectId: this._connectionMeta?.projectId ?? null,
+      branch: this._connectionMeta?.branch ?? null,
+      live: this._connectionMeta?.live ?? null,
+      pendingOps: this._pendingOps.length,
+      undoStackSize: this.getUndoStackSize(),
+      redoStackSize: this.getRedoStackSize()
+    }
+  }
+
+  /* convenient shortcuts */
+  get ydoc() {
+    return this._client?.ydoc
+  }
+  get socket() {
+    return this._client?.socket
+  }
+
+  toggleLive(f) {
+    this._client?.toggleLive(f)
+  }
+  sendCursor(d) {
+    this._client?.sendCursor(d)
+  }
+  sendPresence(d) {
+    this._client?.sendPresence(d)
+  }
+
+  /* ---------- data helpers ---------- */
+  updateData(tuples, options = {}) {
+    // Always ensure we have a state manager so local changes are applied.
+    this._ensureStateManager()
+
+    const { isUndo = false, isRedo = false } = options
+
+    // Track operations for undo/redo (but not when performing undo/redo)
+    if (!isUndo && !isRedo && !this._isUndoRedo) {
+      this._trackForUndo(tuples, options)
+    }
+
+    // Preprocess into granular changes and derive orders
+    const root = this._stateManager?.root
+    const { granularChanges: processedTuples, orders } = preprocessChanges(
+      root,
+      tuples,
+      options
+    )
+
+    // Include any additional changes passed via opts
+    if (options.append && options.append.length) {
+      processedTuples.push(...options.append)
+    }
+
+    // Apply changes to local state tree immediately.
+    this._stateManager.applyChanges(tuples, { ...options })
+
+    // Use a dedicated helper that correctly handles nested array structures
+    // such as granular tuples while also avoiding DOM / state metadata keys.
+    const stringifiedGranularTuples =
+      stringifyFunctionsForTransport(processedTuples)
+
+    const stringifiedTuples = stringifyFunctionsForTransport(tuples)
+
+    const { message } = options
+
+    // If not connected yet, queue the operations for later synchronisation.
+    if (!this.isConnected()) {
+      console.warn('[CollabService] Not connected, queuing real-time update')
+      this._pendingOps.push({
+        changes: stringifiedTuples,
+        granularChanges: stringifiedGranularTuples,
+        orders,
+        options
+      })
+      return
+    }
+
+    // When connected, send the operations to the backend.
+    if (this.socket?.connected) {
+      const ts = Date.now()
+      // console.log('[CollabService] Sending operations to the backend', {
+      //   changes: stringifiedTuples,
+      //   granularChanges: stringifiedGranularTuples,
+      //   orders,
+      //   ts,
+      //   message
+      // })
+      const payload = {
+        changes: stringifiedTuples,
+        granularChanges: stringifiedGranularTuples,
+        orders,
+        ts
+      }
+
+      if (message) {
+        payload.message = message
+      }
+
+      this.socket.emit('ops', payload)
+    }
+
+    return { success: true }
+  }
+
+  _trackForUndo(tuples, options) {
+    // Get current state before changes for undo
+    const undoOperations = tuples.map((tuple) => {
+      const [action, path] = tuple
+      const currentValue = this._getValueAtPath(path)
+
+      if (action === 'delete') {
+        // For delete operations, store the current value to restore
+        return ['update', path, currentValue]
+      }
+      if (typeof currentValue !== 'undefined') {
+        return ['update', path, currentValue]
+      }
+      return ['delete', path]
+    })
+
+    this._undoStack.push({
+      operations: undoOperations,
+      originalOperations: tuples,
+      options,
+      timestamp: Date.now()
+    })
+
+    // Clear redo stack when new operation is performed
+    this._redoStack.length = 0
+
+    // Limit undo stack size (configurable)
+    const maxUndoSteps = this._options?.maxUndoSteps || 50
+    if (this._undoStack.length > maxUndoSteps) {
+      this._undoStack.shift()
+    }
+  }
+
+  _getValueAtPath(path) {
+    // Get value from root state at given path
+    const state = this._stateManager?.root
+    if (!state || !state.getByPath) {
+      return null
+    }
+
+    try {
+      return state.getByPath(path)
+    } catch (error) {
+      console.warn('[CollabService] Could not get value at path:', path, error)
+      return null
+    }
+  }
+
+  undo() {
+    if (!this._undoStack.length) {
+      const state = this._stateManager?.root
+      const el = state.__element
+      el.call('openNotification', {
+        type: 'error',
+        title: 'Nothing to undo'
+      })
+      throw new Error('Nothing to undo')
+    }
+
+    if (!this.isConnected()) {
+      console.warn('[CollabService] Not connected, cannot undo')
+      return
+    }
+
+    const undoItem = this._undoStack.pop()
+    const { operations, originalOperations, options } = undoItem
+
+    // Move to redo stack
+    this._redoStack.push({
+      operations: originalOperations,
+      originalOperations: operations,
+      options,
+      timestamp: Date.now()
+    })
+
+    // Apply undo operations
+    this._isUndoRedo = true
+    try {
+      this.updateData(operations, {
+        ...options,
+        isUndo: true,
+        message: `Undo: ${options.message || 'operation'}`
+      })
+    } finally {
+      this._isUndoRedo = false
+    }
+
+    return operations
+  }
+
+  redo() {
+    if (!this._redoStack.length) {
+      const state = this._stateManager?.root
+      const el = state.__element
+      el.call('openNotification', {
+        type: 'error',
+        title: 'Nothing to redo'
+      })
+      throw new Error('Nothing to redo')
+    }
+
+    if (!this.isConnected()) {
+      console.warn('[CollabService] Not connected, cannot redo')
+      return
+    }
+
+    const redoItem = this._redoStack.pop()
+    const { operations, originalOperations, options } = redoItem
+
+    // Move back to undo stack
+    this._undoStack.push({
+      operations: originalOperations,
+      originalOperations: operations,
+      options,
+      timestamp: Date.now()
+    })
+
+    // Apply redo operations
+    this._isUndoRedo = true
+    try {
+      this.updateData(operations, {
+        ...options,
+        isRedo: true,
+        message: `Redo: ${options.message || 'operation'}`
+      })
+    } finally {
+      this._isUndoRedo = false
+    }
+
+    return operations
+  }
+
+  /* ---------- Undo/Redo State ---------- */
+  canUndo() {
+    return this._undoStack.length > 0
+  }
+
+  canRedo() {
+    return this._redoStack.length > 0
+  }
+
+  getUndoStackSize() {
+    return this._undoStack.length
+  }
+
+  getRedoStackSize() {
+    return this._redoStack.length
+  }
+
+  clearUndoHistory() {
+    this._undoStack.length = 0
+    this._redoStack.length = 0
+  }
+
+  addItem(type, data, opts = {}) {
+    try {
+      validateParams.type(type)
+      validateParams.data(data, type)
+
+      const { value, ...schema } = data
+
+      // Base tuple for the actual value update
+      const tuples = [
+        ['update', [type, data.key], value],
+        ['update', ['schema', type, data.key], schema || {}]
+      ]
+
+      // Prevent components:changed event emission when updateData is invoked via addItem
+      const updatedOpts = { ...opts, skipComponentsChangedEvent: true }
+
+      return this.updateData(tuples, updatedOpts)
+    } catch (error) {
+      throw new Error(`Failed to add item: ${error.message}`, { cause: error })
+    }
+  }
+
+  addMultipleItems(items, opts = {}) {
+    const tuples = []
+
+    try {
+      items.forEach(([type, data]) => {
+        validateParams.type(type)
+        validateParams.data(data, type)
+
+        const { value, ...schema } = data
+
+        tuples.push(
+          ['update', [type, data.key], value],
+          ['update', ['schema', type, data.key], schema]
+        )
+      })
+
+      this.updateData([...tuples, ...(opts.append || [])], {
+        message: `Created ${tuples.length} items`,
+        ...opts
+      })
+      return tuples
+    } catch (error) {
+      const state = this._stateManager?.root
+      const el = state.__element
+      el.call('openNotification', {
+        type: 'error',
+        title: 'Failed to add item',
+        message: error.message
+      })
+      throw new Error(`Failed to add item: ${error.message}`, { cause: error })
+    }
+  }
+
+  updateItem(type, data, opts = {}) {
+    try {
+      validateParams.type(type)
+      validateParams.data(data, type)
+
+      const { value, ...schema } = data
+      const tuples = [
+        ['update', [type, data.key], value],
+        ['update', ['schema', type, data.key], schema]
+      ]
+      return this.updateData(tuples, opts)
+    } catch (error) {
+      const state = this._stateManager?.root
+      const el = state.__element
+      el.call('openNotification', {
+        type: 'error',
+        title: 'Failed to update item',
+        message: error.message
+      })
+      throw new Error(`Failed to update item: ${error.message}`, {
+        cause: error
+      })
+    }
+  }
+
+  deleteItem(type, key, opts = {}) {
+    try {
+      validateParams.type(type)
+      validateParams.key(key, type)
+
+      const tuples = [
+        ['delete', [type, key]],
+        ['delete', ['schema', type, key]],
+        ...(opts.append || [])
+      ]
+      return this.updateData(tuples, {
+        message: `Deleted ${key} from ${type}`,
+        ...opts
+      })
+    } catch (error) {
+      const state = this._stateManager?.root
+      const el = state.__element
+      el.call('openNotification', {
+        type: 'error',
+        title: 'Failed to delete item',
+        message: error.message
+      })
+      throw new Error(`Failed to delete item: ${error.message}`, {
+        cause: error
+      })
+    }
+  }
+
+  /* ---------- socket event helpers ---------- */
+  /**
+   * Handle "clients" or "presence" events coming from the collab socket.
+   * The backend sends the full `clients` object which we directly patch to
+   * the root state, mimicking the legacy SocketService behaviour so that
+   * existing UI components keep working unmodified.
+   */
+  _handleClientsEvent(data = {}) {
+    const root = this._stateManager?.root
+    if (root && typeof root.replace === 'function') {
+      root.clients = data
+    }
+    rootBus.emit('clients:updated', data)
+  }
+
+  /* ---------- Dependency bundling events ---------- */
+  _handleBundleDoneEvent({
+    project,
+    ticket,
+    dependencies = {},
+    schema = {}
+  } = {}) {
+    console.info('[CollabService] Bundle done', { project, ticket })
+
+    // Update local state with latest dependency information
+    try {
+      this._ensureStateManager()
+
+      const { dependencies: schemaDependencies = {} } = schema || {}
+
+      const tuples = [
+        ['update', ['dependencies'], dependencies],
+        ['update', ['schema', 'dependencies'], schemaDependencies]
+      ]
+
+      this._stateManager.applyChanges(tuples, {
+        fromSocket: true,
+        preventFetchDeps: true,
+        preventUpdate: ['Iframe']
+      })
+    } catch (err) {
+      console.error('[CollabService] Failed to update deps after bundle', err)
+    }
+
+    // Notify UI via rootBus and toast/notification helper if available
+    const root = this._stateManager?.root
+    const el = root?.__element
+
+    if (el?.call) {
+      el.call('openNotification', {
+        type: 'success',
+        title: 'Dependencies ready',
+        message: `Project ${project} dependencies have been bundled successfully.`
+      })
+    }
+
+    rootBus.emit('bundle:done', { project, ticket })
+  }
+
+  _handleBundleErrorEvent({ project, ticket, error } = {}) {
+    console.error('[CollabService] Bundle error', { project, ticket, error })
+
+    const root = this._stateManager?.root
+    const el = root?.__element
+
+    if (el?.call) {
+      el.call('openNotification', {
+        type: 'error',
+        title: 'Dependency bundle failed',
+        message:
+          error ||
+          `An error occurred while bundling dependencies for project ${project}.`
+      })
+    }
+
+    rootBus.emit('bundle:error', { project, ticket, error })
+  }
+
+  /* ---------- Manual checkpoint ---------- */
+  _attachSocketLifecycleListeners() {
+    const socket = this._client?.socket
+    if (!socket) {
+      return
+    }
+
+    socket.on('connect', this._onSocketConnect)
+    socket.on('disconnect', this._onSocketDisconnect)
+    socket.on('connect_error', this._onSocketError)
+  }
+
+  _detachSocketLifecycleListeners() {
+    const socket = this._client?.socket
+    if (!socket) {
+      return
+    }
+
+    socket.off('connect', this._onSocketConnect)
+    socket.off('disconnect', this._onSocketDisconnect)
+    socket.off('connect_error', this._onSocketError)
+  }
+
+  _onSocketConnect() {
+    this._connected = true
+  }
+
+  _onSocketDisconnect(reason) {
+    this._connected = false
+
+    if (reason && reason !== 'io client disconnect') {
+      console.warn('[CollabService] Socket disconnected', reason)
+    }
+  }
+
+  _onSocketError(error) {
+    console.warn('[CollabService] Socket connection error', error)
+  }
+
+  /**
+   * Manually request a checkpoint / commit of buffered operations on the server.
+   * Resolves with the new version number once the backend confirms via the
+   * regular "commit" event.
+   */
+  checkpoint() {
+    if (!this.isConnected()) {
+      console.warn('[CollabService] Not connected, cannot request checkpoint')
+      return Promise.reject(new Error('Not connected'))
+    }
+
+    return new Promise((resolve) => {
+      const handler = ({ version }) => {
+        // Ensure we clean up the listener after the first commit event.
+        this.socket?.off('commit', handler)
+        rootBus.emit('checkpoint:done', { version, origin: 'manual' })
+        resolve(version)
+      }
+
+      // Listen for the next commit that the server will emit after checkpoint.
+      this.socket?.once('commit', handler)
+
+      // Trigger server-side checkpoint.
+      this.socket?.emit('checkpoint')
+    })
+  }
+}