@nolag/collab

import { NoLagApi } from "@nolag/js-sdk";

const api = new NoLagApi(process.env.NOLAG_API_KEY); // nlg_live_...
const app = await api.apps.create({ name: "My App", blueprintId: "nolag-collab-sdk" });
console.log(app.slug); // e.g. "my-app-a3f9": this is your appName

const actor = await api.actors.create({ name: "web-client", actorType: "user" });
console.log(actor.accessToken); // shown once; keep it

npm install @nolag/collab @nolag/js-sdk

import { NoLag } from '@nolag/js-sdk'
import { NoLagCollab } from '@nolag/collab'

// The app owns one core client. In a browser, pass a token provider so the
// SDK can mint fresh short-lived client tokens from your backend.
const client = NoLag(async () => (await (await fetch('/api/nolag-token')).json()).token)

// Inject the client into the collab wrapper
const collab = new NoLagCollab({
  client,
  appName: APP_SLUG,     // the slug returned when you created the app
  username: 'Alice',
  idleTimeout: 30_000,   // report a remote user idle after 30 s without cursor activity
  cursorThrottle: 50,    // minimum ms between cursor broadcasts (default 50)
})

await client.connect()   // the app owns the connection
await collab.ready()     // wrapper setup complete

// Join the seeded document (each document is a separate collaboration session)
const doc = collab.joinDocument('my-doc')

// Operations

// React to operations from other users (your own are not echoed back)
doc.on('operation', (op) => {
  console.log(`${op.username} sent ${op.type} at ${op.position}`, op.content ?? op.data)
})

// insert, delete and replace use position, length and content
doc.sendOperation('insert', { position: 42, content: 'Hello, world!' })
doc.sendOperation('delete', { position: 42, length: 13 })
doc.sendOperation('replace', { position: 0, length: 5, content: 'Hi' })

// format and custom carry their payload in `data`
doc.sendOperation('format', { position: 10, length: 5, data: { bold: true } })
doc.sendOperation('custom', {
  data: { kind: 'highlight', color: '#ffcc00', range: { start: 0, end: 20 } },
})

// Operations this client has seen since joining (in-memory, synchronous)
const ops = doc.getOperations()
console.log(`${ops.length} operations cached`)

// Cursors

// Broadcast the local cursor (throttled). Use line/column for text editors,
// x/y for canvases, selection for ranges, path for multi-file documents.
doc.updateCursor({ line: 3, column: 8, selection: { start: 40, end: 55 } })

// Remote cursors from the local cache
const cursors = doc.getCursors()
console.log('Remote cursors:', cursors.length)

doc.on('cursorMoved', (cursor) => {
  renderCursor(cursor.userId, { line: cursor.line, column: cursor.column, color: cursor.color })
})

// Awareness

// Set your own status; it travels in room presence
doc.setStatus('viewing')  // 'active' | 'idle' | 'viewing'

// Fires when a remote user's idle timer elapses on this client
doc.on('awarenessChanged', ({ userId, status }) => {
  console.log(`User ${userId} is now ${status}`)
})

// A remote user's explicit status is read from the user record
console.log(doc.getUsers().map((u) => `${u.username}: ${u.status}`))

// Presence

collab.on('userOnline', (user) => console.log('Joined lobby:', user.username))
collab.on('userOffline', (user) => console.log('Left lobby:', user.username))

doc.on('userJoined', (user) => console.log('Joined document:', user.username))
doc.on('userLeft', (user) => console.log('Left document:', user.username))

// Teardown

// The wrapper releases its handlers; the app closes the socket.
collab.detach()
client.disconnect()