@semiont/api-client

TypeScript SDK for Semiont — a knowledge management system for semantic annotations, AI-powered analysis, and collaborative document understanding.

The api-client is a transparent proxy to @semiont/make-meaning. The browser writes code as though it has direct access to the knowledge system. HTTP, auth, SSE, and caching are internal concerns.

The 7 Verbs

The API is organized by the domain's verbs — the same verbs that organize the EventBus protocol, the documentation, and the backend actors:

import { SemiontApiClient } from '@semiont/api-client';

const semiont = new SemiontApiClient({ baseUrl, eventBus, getToken });

// Browse — reads from materialized views
const resource = semiont.browse.resource(resourceId);       // Observable
const annotations = semiont.browse.annotations(resourceId); // Observable
const content = await semiont.browse.resourceContent(rid);   // Promise

// Mark — annotation CRUD + AI assist
await semiont.mark.annotation(resourceId, input);
await semiont.mark.delete(resourceId, annotationId);
semiont.mark.assist(resourceId, 'linking', options);         // Observable (progress)

// Bind — reference linking
await semiont.bind.body(resourceId, annotationId, operations);

// Gather — LLM context assembly
semiont.gather.annotation(annotationId, resourceId);         // Observable (progress → context)

// Match — semantic search
semiont.match.search(resourceId, referenceId, context);      // Observable (results)

// Yield — resource creation + AI generation
await semiont.yield.resource(data);
semiont.yield.fromAnnotation(resourceId, annotationId, opts); // Observable (progress)

// Beckon — attention coordination
semiont.beckon.attention(annotationId, resourceId);           // void (ephemeral)

// + Job, Auth, Admin namespaces

Return Type Conventions

• Browse live queries → Observable (events-stream driven, cached in BehaviorSubject)
• Browse one-shot reads → Promise (fetch once, no cache)
• Commands (mark, bind, yield.resource) → Promise (fire-and-forget)
• Long-running ops (gather, match, yield.fromAnnotation, mark.assist) → Observable (progress + result)
• Ephemeral signals (beckon) → void

Auth is Internal

The client takes a getToken function at construction. No per-call auth:

const semiont = new SemiontApiClient({
  baseUrl: baseUrl('http://localhost:4000'),
  eventBus: new EventBus(),
  getToken: () => accessToken(token),
});

// No auth on individual calls
const annotations = semiont.browse.annotations(resourceId);
await semiont.mark.annotation(resourceId, input);
await semiont.bind.body(resourceId, annotationId, operations);

Update the token getter at any time via semiont.setTokenGetter(getter).

Installation

npm install @semiont/api-client

Prerequisites: Semiont backend running. See Running the Backend.

Documentation

• Usage Guide — authentication, resources, annotations, streaming
• API Reference — complete method documentation
• Utilities Guide — text encoding, fuzzy anchoring, SVG utilities
• Logging Guide — logger setup and troubleshooting

Key Features

• Verb-oriented — 7 domain namespaces mirror @semiont/make-meaning's actor model
• Type-safe — OpenAPI types from @semiont/core, branded identifiers
• Observable reads — live-updating views via EventBus + events-stream SSE
• Framework-agnostic — pure TypeScript + RxJS, no React dependency

License

Apache-2.0