Keep clients synchronized

Keep a catalog open while its view is active. The SDK verifies incoming changes before exposing them through its local data API.

Listen to changes

Attach listeners to an already open instance. This helper forwards verified data and connection status to your view:

export function bindCatalogView(ulda, render, reportError) {
  const renderCurrent = () => {
    render({
      status: ulda.status,
      data: ulda.status === 'open' ? ulda.snapshot() : null,
    });
  };

  const stopChanges = ulda.on('change', renderCurrent);
  const stopStatus = ulda.on('status', renderCurrent);
  const stopErrors = ulda.on('error', error => {
    reportError(error.code);
  });

  renderCurrent();

  return () => {
    stopChanges();
    stopStatus();
    stopErrors();
  };
}

render and reportError are application callbacks. This example hides editable data while the session is not open; an application can separately choose to display a retained offline snapshot.

The change event carries a kind and affected resource IDs, not plaintext. Read the SDK's snapshot after the event. A deletion can close the session, so check its status before reading.

SDK events

Event	What it tells you
change	Application data may have changed. Kinds are updated, deleted and recovered.
status	The session moved to a new state.
error	An SDK error, identified by its fixed code.
reconnect	Recovery progress: waiting, attempt, restored, stopped or cancelled.
trace	A diagnostic summary of IDs, counts and processing steps, without plaintext.

Listener functions should be synchronous, or handle their own asynchronous failures. The SDK does not await a promise returned by a listener.

Understand session status

Status	Meaning
connecting	The initial connection and handshake are in progress.
ready	Transport is ready, but no catalog is open.
open	A verified catalog is available. Individual operations can still be blocked.
disconnected	Transport is unavailable; a retained local snapshot may be readable.
reconnecting	A bounded recovery attempt is running.
needsResync	An integrity fault or unresolved operation prevents normal writes.
closed	The instance is finished. Create another instance to open a session.

Use status to drive the interface and each method's promise to track its own result.

Subscriptions are automatic

Server Read, Create and Update operations subscribe the connection to the affected resources. A master update may introduce new content IDs; the SDK reads them using credentials from the decrypted catalog.

There is no public watch flag or per-resource unsubscribe method. The function returned by ulda.on() removes a local callback, not the server subscription. Subscriptions end with the connection and are restored by verified reads after reconnect.

Confirm your own writes

await ulda.data.notes.text.update('Ready for tomorrow');
const confirmed = ulda.value('notes');

The writer receives an acknowledgement. Other subscribed clients receive a change notification; the server does not echo that same update back to its writer.

change is an invalidation signal, not a receipt for every local method or a durable transaction log. Reconnection restores current state through reads rather than replaying all missed events.

Close the view

Call the listener cleanup functions when the view is disposed. When nothing else owns the SDK instance, close it:

await ulda.close();

Closing releases the session and invalidates its references. It does not delete server data.

For connection failures and uncertain writes, continue with conflicts and recovery. The lower-level transport's changed event contains ciphertext below SDK verification; it is not a replacement for the application-level change event.