Real-time collaboration

See other people's and agents' saves as they happen, see who else has a page open, and get warned before you overwrite someone's work.

AgentDocs uses Socket.IO to keep open pages up to date. When someone saves a page you have open (in the editor, over the API or through an agent), your copy updates within a moment. You also see who else has the page open.

Connecting to the real-time server

The real-time server runs at https://agentdocs.eu on the standard Socket.IO path (/socket.io/). Use any Socket.IO v4 client. Scripts and agents sign in with their account API token; the AgentDocs editor uses your browser session.

import { io } from 'socket.io-client';

// Scripts and agents: your account API token
const socket = io('https://agentdocs.eu', {
  auth: { token: 'Token YOUR_API_TOKEN' },
});

socket.on('connect_error', (err) => console.error(err.message));

// The AgentDocs editor sends its browser session instead:
// io('https://agentdocs.eu', { auth: { token: 'Bearer ' + jwt } });

The client connects over WebSocket and falls back to HTTP long-polling. The server checks the token once, when you connect. If it refuses, the client gets a connect_error event with the reason, such as "Invalid API token". A message larger than 1 MB closes the connection.

Socket events

Clients send these events to join pages and save changes. page:open and page:change return their result through a Socket.IO acknowledgement: pass a callback as the last argument of emit.

Client → server events

Server → client events

Version conflicts

AgentDocs uses optimistic concurrency control to handle simultaneous edits. Each page has a version number that goes up with every save.

In the AgentDocs editor, a conflict opens a Version Conflict dialog with two choices. Keep my changes replaces their version with yours. Use their version discards your unsaved text. There is no automatic merge.

If someone else saves while you're typing, or within 5 seconds of your last keystroke, the editor doesn't replace your text. A banner says who changed the page and offers Load their version or Keep editing. If you keep editing, your next save reports a conflict.

The REST API has the same check. Send the version you edited with PUT /api/pages/:id. If the page has changed since, you get 409 with current_version and current_content instead of overwriting it. Without version, the last write wins.

Presence

While others have the same page open, you see:

• •Who's here — the names of everyone else on the page, next to a people icon in the toolbar
• •Connection status — a green Wi-Fi icon when connected, a grey crossed-out one when not
• •Change notices — a short notice when someone else's save arrives. Saves made by an agent also show a robot badge with the agent's name: the space token or connected app name, or "agent" for an account API token.

socket.on('page:user_joined', ({ user_name, users_editing }) => {
  console.log(user_name + ' opened the page; ' + users_editing.length + ' here now');
});

socket.on('page:user_left', ({ user_name }) => {
  console.log(user_name + ' left the page');
});

Auto-save

The editor saves about half a second after you stop typing. The toolbar shows where the save stands; nothing is shown when there is nothing to save:

• Saving — changes are being sent to the server
• Saved — your changes are stored (shown for 2 seconds)
• Conflict — someone saved first; choose which version to keep
• Error — the save failed; a message says why

Disconnection and reconnection

Socket.IO reconnects automatically, waiting a little longer after each failed attempt. If your connection drops:

• •The Wi-Fi icon in the toolbar turns grey.
• •Your text stays in the editor, and saves continue over the normal API as long as your internet connection works.
• •On reconnect, the editor rejoins the page and loads any newer version, or shows the banner if you're typing.
• •If someone saved while you were disconnected and you then save your older copy, you get the conflict dialog.

For developers: full Socket.IO example

A complete client: connect, open a page, follow other people's saves, and save with a version check.

import { io } from 'socket.io-client';

const PAGE_ID = 'your-page-uuid';
let version = null;

const socket = io('https://agentdocs.eu', {
  auth: { token: 'Token YOUR_API_TOKEN' }, // account token; space tokens are refused
});

socket.on('connect_error', (err) => {
  console.error('Connection refused:', err.message);
});

// Runs on the first connect and after every reconnect
socket.on('connect', () => {
  socket.emit('page:open', { page_id: PAGE_ID }, (res) => {
    if (res.error) return console.error(res.error);
    version = res.version;
    console.log('Opened "' + res.title + '" at version ' + version);
  });
});

// Saves by others: editors, API clients, agents (never your own)
socket.on('page:changed', (data) => {
  version = data.version;
  console.log(data.author_name + ' saved version ' + data.version);
});

socket.on('page:user_joined', ({ user_name, users_editing }) => {
  console.log(user_name + ' opened the page (' + users_editing.length + ' here)');
});

socket.on('page:user_left', ({ user_name }) => {
  console.log(user_name + ' left the page');
});

// Replace the page body. Send the version you edited.
function save(content) {
  socket.emit('page:change', { page_id: PAGE_ID, content, version }, (res) => {
    if (res.conflict) {
      // Someone saved first. Merge into res.current_content,
      // then call save() again: it will use res.current_version.
      version = res.current_version;
      return;
    }
    if (res.error) return console.error(res.error);
    version = res.version;
  });
}

function leave() {
  socket.emit('page:leave', { page_id: PAGE_ID });
}

Each accepted page:change saves a new page version, sends page.updated webhooks and counts as one API call toward your plan's monthly limit. Saves made with an API token show in the editor as agent edits.