@symbo.ls/sdk 3.1.2 → 3.2.6

package/src/utils/CollabClient.js

@@ -0,0 +1,248 @@
+import { io } from 'socket.io-client'
+import * as Y from 'yjs'
+import { nanoid } from 'nanoid'
+import environment from '../config/environment.js'
+// import gzip from 'gzip-js' // reserved for future compression features
+
+// diff / patch helpers
+import { diffJson, applyOpsToJson } from './jsonDiff.js'
+
+/* eslint-disable no-use-before-define, no-new, no-promise-executor-return */
+
+// Dexie and IndexeddbPersistence will be conditionally imported in browser environments
+
+export class CollabClient {
+  /* public fields */
+  socket = null
+  ydoc = null
+  branch = 'main'
+  live = false
+  projectId = null
+  jwt = null
+
+  /* private state */
+  _buffer = []
+  _flushTimer = null
+  _clientId = nanoid()
+  _outboxStore = createMemoryOutbox() // Dexie table fallback
+  _readyResolve
+  ready = new Promise(res => (this._readyResolve = res))
+
+  constructor ({ jwt, projectId, branch = 'main', live = false }) {
+    Object.assign(this, { jwt, projectId, branch, live })
+
+    /* 1️⃣  create Yjs doc + offline persistence */
+    this.ydoc = new Y.Doc()
+
+    // Only use IndexeddbPersistence in browser environments
+    const hasIndexedDB = typeof globalThis.indexedDB !== 'undefined'
+
+    if (typeof window === 'undefined' || !hasIndexedDB) {
+      // In Node.js (or when indexedDB is not available), skip persistence
+      console.log('[CollabClient] IndexedDB not available – skipping offline persistence')
+    } else {
+      // Dynamically import IndexeddbPersistence only when indexedDB exists
+      import('y-indexeddb')
+        .then(({ IndexeddbPersistence }) => {
+          new IndexeddbPersistence(`${projectId}:${branch}`, this.ydoc)
+        })
+        .catch(err => {
+          console.warn('[CollabClient] Failed to load IndexeddbPersistence:', err)
+        })
+    }
+
+    /* 2️⃣  init Dexie for outbox (browser only) */
+    if (typeof window !== 'undefined' && hasIndexedDB) {
+      // In browser environments, use Dexie
+      createDexieOutbox(`${projectId}:${branch}`)
+        .then(outboxStore => {
+          this._outboxStore = outboxStore
+        })
+        .catch(err => {
+          console.warn('[CollabClient] Failed to load Dexie:', err)
+        })
+    }
+
+    /* 3️⃣  WebSocket transport */
+    this.socket = io(environment.socketUrl, {
+      path: '/collab-socket',
+      transports: ['websocket'],
+      auth: { token: jwt, projectId, branch, live },
+      reconnectionAttempts: Infinity,
+      reconnectionDelayMax: 4000
+    })
+
+    /* socket events */
+    this.socket
+      .on('snapshot', this._onSnapshot)
+      .on('ops', this._onOps)
+      .on('commit', this._onCommit)
+      .on('liveMode', this._onLiveMode)
+      .on('connect', this._onConnect)
+      .on('error', this._onError)
+
+    /* Track last known JSON representation so we can compute granular diffs. */
+    this._prevJson = this.ydoc.getMap('root').toJSON()
+
+    /* 4️⃣  hook Yjs change listener */
+    this.ydoc.on('afterTransaction', tr => {
+      // Ignore changes that originated from remote patches.
+      if (tr.origin === 'remote') {return}
+
+      const currentJson = this.ydoc.getMap('root').toJSON()
+
+      // Compute minimal diff between previous and current state.
+      const ops = diffJson(this._prevJson, currentJson)
+
+      // Cache new snapshot for next diff calculation.
+      this._prevJson = currentJson
+
+      if (!ops.length) {return}
+      this._queueOps(ops)
+    })
+  }
+
+  /* ---------- public helpers ---------- */
+  toggleLive (flag) { this.socket.emit('toggleLive', Boolean(flag)) }
+  sendCursor (data) { this.socket.emit('cursor', data) }
+  sendPresence (d) { this.socket.emit('presence', d) }
+
+  /* ---------- private handlers ---------- */
+  _onSnapshot = ({ data /* Uint8Array */ }) => {
+    if (Array.isArray(data) ? data.length : (data && data.byteLength)) {
+      // First paint; trust server compressed payload (≤256 kB)
+      Y.applyUpdate(this.ydoc, Uint8Array.from(data))
+    } else {
+      console.warn('[collab] Received empty snapshot – skipping applyUpdate')
+    }
+
+    // Store current state as baseline for future diffs.
+    this._prevJson = this.ydoc.getMap('root').toJSON()
+    if (typeof this._readyResolve === 'function') {
+      this._readyResolve()
+      this._readyResolve = null
+    }
+  }
+
+  _onOps = ({ changes }) => {
+    // Apply remote ops
+    applyOpsToJson(changes, this.ydoc)
+
+    // Refresh baseline snapshot so we don't generate redundant diffs for the
+    // just-applied remote changes.
+    this._prevJson = this.ydoc.getMap('root').toJSON()
+  }
+
+  _onCommit = async ({ version }) => {
+    await this._outboxStore.clear()
+    console.info('[collab] committed', version)
+  }
+
+  _onConnect = async () => {
+    // Mark client as ready if we haven't received a snapshot yet
+    if (typeof this._readyResolve === 'function') {
+      this._readyResolve()
+      // Prevent multiple resolutions
+      this._readyResolve = null
+    }
+
+    // flush locally stored ops
+    const queued = await this._outboxStore.toArray()
+    if (queued.length) {
+      this.socket.emit('ops', {
+        changes: queued.flatMap(e => e.ops),
+        ts: Date.now(),
+        clientId: this._clientId
+      })
+      await this._outboxStore.clear()
+    }
+  }
+
+  /* ---------- buffering & debounce ---------- */
+  _queueOps (ops) {
+    this._buffer.push(...ops)
+    this._outboxStore.put({ id: nanoid(), ops })
+
+    if (this.live && this.socket.connected) {
+      this._flushNow()
+    } else {
+      clearTimeout(this._flushTimer)
+      this._flushTimer = setTimeout(() => this._flushNow(), 40)
+    }
+  }
+
+  _flushNow () {
+    if (!this._buffer.length || !this.socket.connected) {return}
+    this.socket.emit('ops', {
+      changes: this._buffer,
+      ts: Date.now(),
+      clientId: this._clientId
+    })
+    this._buffer.length = 0
+  }
+
+  dispose () {
+    clearTimeout(this._flushTimer)
+    this._flushTimer = null
+    this._buffer.length = 0
+
+    if (this._outboxStore?.clear) {
+      try {
+        const result = this._outboxStore.clear()
+        if (result && typeof result.catch === 'function') {
+          result.catch(() => {})
+        }
+      } catch (error) {
+        console.warn('[CollabClient] Failed to clear outbox store during dispose:', error)
+      }
+    }
+
+    if (this.socket) {
+      this.socket.off('snapshot', this._onSnapshot)
+      this.socket.off('ops', this._onOps)
+      this.socket.off('commit', this._onCommit)
+      this.socket.off('liveMode', this._onLiveMode)
+      this.socket.off('connect', this._onConnect)
+      this.socket.off('error', this._onError)
+      this.socket.removeAllListeners()
+      this.socket.disconnect()
+      this.socket = null
+    }
+
+    if (this.ydoc) {
+      this.ydoc.destroy()
+      this.ydoc = null
+    }
+
+    if (typeof this._readyResolve === 'function') {
+      this._readyResolve()
+      this._readyResolve = null
+    }
+  }
+
+  _onLiveMode = (flag) => {
+    this.live = flag
+  }
+
+  _onError = (e) => {
+    console.warn('[collab] socket error', e)
+  }
+}
+
+/* ---------- Memory storage helper for Node.js ---------- */
+function createMemoryOutbox () {
+  const store = new Map()
+  return {
+    put: (item) => store.set(item.id, item),
+    toArray: () => Array.from(store.values()),
+    clear: () => store.clear()
+  }
+}
+
+/* ---------- Dexie helper for browser ---------- */
+async function createDexieOutbox (name) {
+  const { default: Dexie } = await import('dexie')
+  const db = new Dexie(`collab-${name}`)
+  db.version(1).stores({ outbox: 'id, ops' })
+  return db.table('outbox')
+}

package/src/utils/TokenManager.js

@@ -6,7 +6,7 @@ export class TokenManager {
   constructor (options = {}) {
     this.config = {
       storagePrefix: 'symbols_',
-      storageType: 'localStorage', // 'localStorage' | 'sessionStorage' | 'memory'
+      storageType: (typeof window === 'undefined' || process.env.NODE_ENV === 'test' || process.env.NODE_ENV === 'testing') ? 'memory' : 'localStorage', // 'localStorage' | 'sessionStorage' | 'memory'
       refreshBuffer: 60 * 1000, // Refresh 1 minute before expiry
       maxRetries: 3,
       apiUrl: options.apiUrl || '/api',
@@ -52,13 +52,30 @@ export class TokenManager {
       return this._memoryStorage
     }
 
+    // Guard against environments where accessing storage throws (e.g., opaque origins)
+    const safeGetStorage = (provider) => {
+      try {
+        const storage = provider()
+        // Try a simple set/remove cycle to ensure it is usable
+        const testKey = `${this.config.storagePrefix}__tm_test__`
+        storage.setItem(testKey, '1')
+        storage.removeItem(testKey)
+        return storage
+      } catch {
+        return null
+      }
+    }
+
+    const localStorageInstance = safeGetStorage(() => window.localStorage)
+    const sessionStorageInstance = safeGetStorage(() => window.sessionStorage)
+
     switch (this.config.storageType) {
       case 'sessionStorage':
-        return window.sessionStorage
+        return sessionStorageInstance || this._memoryStorage
       case 'memory':
         return this._memoryStorage
       default:
-        return window.localStorage
+        return localStorageInstance || this._memoryStorage
     }
   }
 
@@ -147,7 +164,28 @@ export class TokenManager {
     if (!this.tokens.expiresAt) {return true} // No expiry info, assume valid
 
     const now = Date.now()
-    return now < (this.tokens.expiresAt - this.config.refreshBuffer)
+    const isValid = now < (this.tokens.expiresAt - this.config.refreshBuffer)
+
+    if (!isValid) {
+      console.log('[TokenManager] Access token is expired or near expiry:', {
+        now: new Date(now).toISOString(),
+        expiresAt: new Date(this.tokens.expiresAt).toISOString(),
+        refreshBuffer: this.config.refreshBuffer
+      })
+    }
+
+    return isValid
+  }
+
+  /**
+   * Check if access token exists and is not expired (without refresh buffer)
+   */
+  isAccessTokenActuallyValid () {
+    if (!this.tokens.accessToken) {return false}
+    if (!this.tokens.expiresAt) {return true} // No expiry info, assume valid
+
+    const now = Date.now()
+    return now < this.tokens.expiresAt
   }
 
   /**
@@ -303,23 +341,30 @@ export class TokenManager {
    * Save tokens to storage
    */
   saveTokens () {
-    const {storage} = this
-    const keys = this.storageKeys
+    try {
+      const {storage} = this
+      const keys = this.storageKeys
 
-    if (this.tokens.accessToken) {
-      storage.setItem(keys.accessToken, this.tokens.accessToken)
-    }
+      if (this.tokens.accessToken) {
+        storage.setItem(keys.accessToken, this.tokens.accessToken)
+      }
 
-    if (this.tokens.refreshToken) {
-      storage.setItem(keys.refreshToken, this.tokens.refreshToken)
-    }
+      if (this.tokens.refreshToken) {
+        storage.setItem(keys.refreshToken, this.tokens.refreshToken)
+      }
 
-    if (this.tokens.expiresAt) {
-      storage.setItem(keys.expiresAt, this.tokens.expiresAt.toString())
-    }
+      if (this.tokens.expiresAt) {
+        storage.setItem(keys.expiresAt, this.tokens.expiresAt.toString())
+      }
+
+      if (this.tokens.expiresIn) {
+        storage.setItem(keys.expiresIn, this.tokens.expiresIn.toString())
+      }
 
-    if (this.tokens.expiresIn) {
-      storage.setItem(keys.expiresIn, this.tokens.expiresIn.toString())
+    } catch (error) {
+      console.error('[TokenManager] Error saving tokens to storage:', error)
+      // Don't throw here as it would break the token setting flow
+      // but log the error for debugging
     }
   }
 
@@ -327,25 +372,35 @@ export class TokenManager {
    * Load tokens from storage
    */
   loadTokens () {
-    const {storage} = this
-    const keys = this.storageKeys
-
-    const accessToken = storage.getItem(keys.accessToken)
-    const refreshToken = storage.getItem(keys.refreshToken)
-    const expiresAt = storage.getItem(keys.expiresAt)
-    const expiresIn = storage.getItem(keys.expiresIn)
+    try {
+      const {storage} = this
+      const keys = this.storageKeys
+
+      const accessToken = storage.getItem(keys.accessToken)
+      const refreshToken = storage.getItem(keys.refreshToken)
+      const expiresAt = storage.getItem(keys.expiresAt)
+      const expiresIn = storage.getItem(keys.expiresIn)
+
+      if (accessToken) {
+        this.tokens = {
+          accessToken,
+          refreshToken,
+          expiresAt: expiresAt ? parseInt(expiresAt, 10) : null,
+          expiresIn: expiresIn ? parseInt(expiresIn, 10) : null,
+          tokenType: 'Bearer'
+        }
 
-    if (accessToken) {
+        // Schedule refresh for loaded tokens
+        this.scheduleRefresh()
+      }
+    } catch (error) {
+      console.error('[TokenManager] Error loading tokens from storage:', error)
       this.tokens = {
-        accessToken,
-        refreshToken,
-        expiresAt: expiresAt ? parseInt(expiresAt, 10) : null,
-        expiresIn: expiresIn ? parseInt(expiresIn, 10) : null,
-        tokenType: 'Bearer'
+        accessToken: null,
+        refreshToken: null,
+        expiresAt: null,
+        expiresIn: null
       }
-
-      // Schedule refresh for loaded tokens
-      this.scheduleRefresh()
     }
   }
 

package/src/utils/changePreprocessor.js

@@ -0,0 +1,239 @@
+
+import { diffJson } from './jsonDiff.js'
+import { computeOrdersForTuples } from './ordering.js'
+
+function isPlainObject (val) {
+  return val && typeof val === 'object' && !Array.isArray(val)
+}
+
+function getByPathSafe (root, path) {
+  if (!root || typeof root.getByPath !== 'function') { return null }
+  try { return root.getByPath(path) } catch { return null }
+}
+
+// Given the original high-level tuples and a fully qualified path, resolve the
+// "next" value that the change set intends to write at that path.
+// This walks tuples from last to first so that later changes win, and supports
+// nested paths where the tuple only targets a parent container, e.g.:
+//   ['update', ['components', 'CanvasLogoDropdown'], { ... }]
+// for a granular path like:
+//   ['components', 'CanvasLogoDropdown', 'ProjectNav', 'ListInDropdown', 'children']
+function resolveNextValueFromTuples (tuples, path) {
+  if (!Array.isArray(tuples) || !Array.isArray(path)) { return null }
+
+  // Walk from the end to honour the latest change
+  for (let i = tuples.length - 1; i >= 0; i--) {
+    const t = tuples[i]
+    if (!Array.isArray(t) || t.length < 3) {
+      // eslint-disable-next-line no-continue
+      continue
+    }
+    const [action, tuplePath, tupleValue] = t
+    if ((action !== 'update' && action !== 'set') || !Array.isArray(tuplePath)) {
+      // eslint-disable-next-line no-continue
+      continue
+    }
+    if (tuplePath.length > path.length) {
+      // eslint-disable-next-line no-continue
+      continue
+    }
+
+    // Ensure tuplePath is a prefix of the requested path
+    let isPrefix = true
+    for (let j = 0; j < tuplePath.length; j++) {
+      if (tuplePath[j] !== path[j]) {
+        isPrefix = false
+        break
+      }
+    }
+    if (!isPrefix) {
+      // eslint-disable-next-line no-continue
+      continue
+    }
+
+    // Direct match: the tuple already targets the exact path
+    if (tuplePath.length === path.length) {
+      return tupleValue
+    }
+
+    // Nested match: drill into the tuple value using the remaining segments
+    let current = tupleValue
+    for (let j = tuplePath.length; j < path.length; j++) {
+      if (current == null) { return null }
+      current = current[path[j]]
+    }
+    if (current !== null) {
+      return current
+    }
+  }
+
+  return null
+}
+
+/**
+ * Preprocess broad project changes into granular changes and ordering metadata.
+ * - Expands top-level object updates (e.g. ['update', ['components'], {...}])
+ *   into fine-grained ['update'|'delete', [...], value] tuples using a diff
+ *   against the current state when available
+ * - Preserves schema paths as-is
+ * - Filters out explicit deletes targeting __order keys
+ * - Appends any extra tuples from options.append
+ * - Computes stable orders for impacted parent containers
+ * - IMPORTANT: When the tuple represents creation of a brand-new entity
+ *   (e.g. ['update', ['components', key], {...}] where the path did not exist
+ *   before, or the corresponding ['schema', ...] path is new), we DO NOT
+ *   expand it into many granular changes. We keep the original change to avoid
+ *   generating noisy diffs for creates.
+ */
+export function preprocessChanges (root, tuples = [], options = {}) {
+  const expandTuple = (t) => {
+    const [action, path, value] = t || []
+    const isSchemaPath = Array.isArray(path) && path[0] === 'schema'
+    const isFilesPath = Array.isArray(path) && path[0] === 'files'
+    if (action === 'delete') { return [t] }
+
+    const canConsiderExpansion = (
+      action === 'update' &&
+      Array.isArray(path) &&
+      (
+        path.length === 1 ||
+        path.length === 2 ||
+        (isSchemaPath && path.length === 3)
+      ) &&
+      isPlainObject(value)
+    )
+    if (!canConsiderExpansion || isFilesPath || (value && value.type === 'files')) { return [t] }
+
+    // Detect brand-new entity creation:
+    // - Non-schema entities typically come as ['update', [type, key], {...}]
+    // - Schema entries as ['update', ['schema', type, key], {...}]
+    // If the exact path does not exist yet, treat it as a "create" operation and
+    // do NOT expand into granular leaf updates.
+    const prevRaw = getByPathSafe(root, path)
+    const isCreatePath = (
+      (Array.isArray(path)) &&
+      action === 'update' &&
+      (
+        // e.g. ['update', ['components', 'NewKey'], {...}]
+        (!isSchemaPath && path.length === 2) ||
+        // e.g. ['update', ['schema', 'components', 'NewKey'], {...}]
+        (isSchemaPath && path.length === 3)
+      ) &&
+      (prevRaw === null || typeof prevRaw === 'undefined')
+    )
+    if (isCreatePath) { return [t] }
+
+    const prev = prevRaw || {}
+    const next = value || {}
+    if (!isPlainObject(prev) || !isPlainObject(next)) { return [t] }
+
+    const ops = diffJson(prev, next, [])
+    // If diff yields no nested ops, preserve the original tuple as a fallback
+    // (e.g. when value equality or missing previous state prevents expansion).
+    if (!ops.length) { return [t] }
+
+    const out = []
+    for (let i = 0; i < ops.length; i++) {
+      const op = ops[i]
+      const fullPath = [...path, ...op.path]
+      const last = fullPath[fullPath.length - 1]
+      if (op.action === 'set') {
+        out.push(['update', fullPath, op.value])
+      } else if (op.action === 'del') {
+        if (last !== '__order') { out.push(['delete', fullPath]) }
+      }
+    }
+    // Prefer granular leaf operations only to minimize payload duplication.
+    return out
+  }
+
+  const minimizeTuples = (input) => {
+    const out = []
+    const seen = new Set()
+    for (let i = 0; i < input.length; i++) {
+      const expanded = expandTuple(input[i])
+      for (let k = 0; k < expanded.length; k++) {
+        const tuple = expanded[k]
+        const isDelete = Array.isArray(tuple) && tuple[0] === 'delete'
+        const isOrderKey = (
+          isDelete &&
+          Array.isArray(tuple[1]) &&
+          tuple[1][tuple[1].length - 1] === '__order'
+        )
+        if (!isOrderKey) {
+          const key = JSON.stringify(tuple)
+          if (!seen.has(key)) { seen.add(key); out.push(tuple) }
+        }
+      }
+    }
+    return out
+  }
+
+  const granularChanges = (() => {
+    try {
+      const res = minimizeTuples(tuples)
+      if (options.append && options.append.length) { res.push(...options.append) }
+      return res
+    } catch {
+      // Fallback to original tuples if anything goes wrong
+      return Array.isArray(tuples) ? tuples.slice() : []
+    }
+  })()
+
+  const hydratedGranularChanges = granularChanges.map(t => {
+    if (!Array.isArray(t) || t.length < 3) { return t }
+    const [action, path] = t
+    if ((action !== 'update' && action !== 'set') || !Array.isArray(path)) {
+      return t
+    }
+
+    const nextValue = resolveNextValueFromTuples(tuples, path)
+    if (nextValue === null) {
+      return t
+    }
+
+    return [action, path, nextValue]
+  })
+
+  // Base orders from granular changes/state
+  const baseOrders = computeOrdersForTuples(root, hydratedGranularChanges)
+
+  // Prefer explicit order for containers updated via ['update', [type], value] or ['update', [type, key], value]
+  const preferOrdersMap = new Map()
+  for (let i = 0; i < tuples.length; i++) {
+    const t = tuples[i]
+    if (!Array.isArray(t) || t.length < 3) {
+      // eslint-disable-next-line no-continue
+      continue
+    }
+    const [action, path, value] = t
+    const isFilesPath = Array.isArray(path) && path[0] === 'files'
+    if (
+      action !== 'update' ||
+      !Array.isArray(path) ||
+      (path.length !== 1 && path.length !== 2) ||
+      !isPlainObject(value) ||
+      isFilesPath ||
+      (value && value.type === 'files')
+    ) {
+      // eslint-disable-next-line no-continue
+      continue
+    }
+    const keys = Object.keys(value).filter(k => k !== '__order')
+    const key = JSON.stringify(path)
+    preferOrdersMap.set(key, { path, keys })
+  }
+
+  const mergedOrders = []
+  const seen = new Set()
+  // Add preferred top-level orders first
+  preferOrdersMap.forEach((v, k) => { seen.add(k); mergedOrders.push(v) })
+  // Add remaining base orders
+  for (let i = 0; i < baseOrders.length; i++) {
+    const v = baseOrders[i]
+    const k = JSON.stringify(v.path)
+    if (!seen.has(k)) { seen.add(k); mergedOrders.push(v) }
+  }
+
+  return { granularChanges: hydratedGranularChanges, orders: mergedOrders }
+}