Skip to main content

API Reference

API documentation for Chronicle services.

Relay Service

WebSocket API

Connection

ws://relay.chronicle.dev/ws/documents/:document_id
  ?user_id=<user_id>
  &user_name=<display_name>
  &color=<hex_or_hsl>

Message Types

Operations (Binary) CRDT operations are sent as binary protobuf messages:
message CRDTOperation {
  string operation_id = 1;
  string document_id = 2;
  string author_id = 3;
  oneof operation {
    LSeqInsert insert = 10;
    LSeqDelete delete = 11;
    LSeqFormat format = 12;
  }
  int64 hlc_timestamp = 20;
  int32 hlc_counter = 21;
}
Presence (JSON)
{
  "type": "cursor_update",
  "user_id": "user-123",
  "cursor": {
    "position": 42,
    "selection": { "from": 42, "to": 50 }
  }
}

HTTP API

Health Check

GET /api/health
Response:
{
  "status": "healthy",
  "service": "chronicle-relay",
  "version": "0.1.0"
}

Readiness Check

GET /api/ready
Response:
{
  "status": "ready",
  "service": "chronicle-relay",
  "version": "0.1.0"
}

Editor Package

EditorState

import { EditorState, Schema } from '@chronicle-hq/editor';

const state = EditorState.create({
  schema: mySchema,
  doc: initialDoc,
  plugins: [new TimelinePlugin()],
});

// Apply transaction
const newState = state.apply(transaction);

// Create transaction
const tr = state.tr();

EditorView

import { EditorView } from '@chronicle-hq/editor';

const view = new EditorView({
  state,
  mount: document.getElementById('editor'),
  dispatchTransaction: (tr) => {
    const newState = view.state.apply(tr);
    view.updateState(newState);
  },
});

TimelinePlugin

import { TimelinePlugin } from '@chronicle-hq/editor/plugins';

const timeline = new TimelinePlugin({
  onTimeChange: (hlcTimestamp) => {
    console.log('Viewing:', hlcTimestamp);
  },
  onViewHistorical: (isHistorical) => {
    // Update UI to show historical mode
  },
});

// Navigate
await timeline.goToTime(1708780800000);
await timeline.goToPresent();

// Query
const entries = await timeline.getEntriesInRange({
  from: Date.now() - 86400000,
  to: Date.now(),
});

TimechainAdapter

import { TimechainAdapter } from '@chronicle-hq/editor/adapters';

const adapter = new TimechainAdapter({
  connection: 'wss://relay.chronicle.dev',
  documentId: 'doc-123',
  userId: 'user-456',
});

await adapter.connect();

// Apply local operation
await adapter.applyLocal(operation);

// Subscribe to remote operations
const unsubscribe = adapter.onRemoteOperation((op) => {
  // Apply to local state
});

// Cleanup
await adapter.disconnect();