@semiotic-labs/agentium-sdk

TypeScript SDK for interacting with the Agentium Network API. Supports identity connection, OAuth token management, and W3C Verifiable Credentials (VCs) with Ed25519 signatures.

Installation

npm install @semiotic-labs/agentium-sdk

Quick Start

import { AgentiumClient } from '@semiotic-labs/agentium-sdk';

const client = new AgentiumClient();

// Connect with Google identity
const response = await client.connectGoogleIdentity(googleJwtToken);
console.log('User DID:', response.did);
console.log('Access Token:', response.accessToken);

API Reference

Client Setup

import { AgentiumClient } from '@semiotic-labs/agentium-sdk';

// Default: https://api.agentium.network
const client = new AgentiumClient();

// Custom endpoint (for local/staging)
const client = new AgentiumClient({ baseURL: 'http://localhost:8080' });

// For bundlers like Vite that require explicit WASM URL
import wasmUrl from '@semiotic-labs/agentium-sdk/wasm?url';
const client = new AgentiumClient({ wasmUrl });

Identity Connection

connectGoogleIdentity(googleToken, options?)

Connects a Google identity to an Agentium identity.

// Standard Google Sign-In
const response = await client.connectGoogleIdentity(googleJwtToken);

// External OAuth (e.g., zkLogin) - skip audience validation
const response = await client.connectGoogleIdentity(googleJwtToken, {
  skipAudienceValidation: true,
});

Returns: ConnectIdentityResponse with did, accessToken, refreshToken, expiresIn, isNew, badge

Token Management

exchangeApiKey(apiKey)

Exchanges an API key for JWT tokens (M2M authentication).

const tokens = await client.exchangeApiKey('ak_your_api_key');

refreshToken(refreshTokenValue)

Refreshes an access token using a refresh token.

const newTokens = await client.refreshToken(currentRefreshToken);

Verifiable Credentials

The SDK supports W3C Verifiable Credentials issued as JWTs with Ed25519 signatures.

Storage Setup

import { createBrowserStorage, createMemoryStorage } from '@semiotic-labs/agentium-sdk';

// Browser environment (uses localStorage)
client.setVcStorage(createBrowserStorage());

// Node.js or testing (in-memory)
client.setVcStorage(createMemoryStorage());

fetchMembershipCredential(token)

Fetches a membership credential from the backend.

const vcJwt = await client.fetchMembershipCredential(authToken);

verifyCredential(jwt)

Verifies a JWT-VC against the issuer's public key.

const result = await client.verifyCredential(vcJwt);

if (result.valid) {
  console.log('Subject DID:', result.claims?.sub);
} else {
  console.error('Error:', result.error?.code, result.error?.message);
}

connectAndStoreMembership(token)

Full flow: fetch, verify, and store a membership credential.

const result = await client.connectAndStoreMembership(authToken);

getStoredCredential()

Retrieves the stored VC JWT from storage.

const storedVc = client.getStoredCredential();

WASM Utilities

Low-level cryptographic operations for Ed25519. WASM is automatically initialized on first use — no manual setup required.

import { verifyJwt, generateKeypair, getPublicKey } from '@semiotic-labs/agentium-sdk';

// Generate key pair
const { privateKey, publicKey } = await generateKeypair();

// Verify JWT directly
const result = await verifyJwt(jwtString, publicKeyJwk);

Bundler Configuration (Vite, etc.)

For bundlers like Vite that require explicit WASM URL resolution, pass wasmUrl to the client constructor (see Client Setup).

If using low-level WASM utilities directly (without AgentiumClient), initialize manually:

import { ensureWasmReady } from '@semiotic-labs/agentium-sdk';
import wasmUrl from '@semiotic-labs/agentium-sdk/wasm?url';

await ensureWasmReady(wasmUrl);

Error Handling

All API methods throw AgentiumApiError on failure:

import { AgentiumApiError } from '@semiotic-labs/agentium-sdk';

try {
  await client.connectGoogleIdentity(token);
} catch (error) {
  if (error instanceof AgentiumApiError) {
    console.error(`API Error (${error.statusCode}): ${error.message}`);
  }
}

Telemetry

The SDK provides a flexible telemetry system that forwards tracing events from the WASM layer to JavaScript. Consumers can define custom sinks to handle events (logging, analytics, monitoring services, etc.).

Note: The WASM layer currently emits events only — spans are not yet supported.

Initialization

Telemetry must be initialized after WASM is ready and can only be called once. If not initialized, no telemetry is emitted (silent by default).

import { ensureWasmReady, initTelemetry, consoleSink } from '@semiotic-labs/agentium-sdk';

await ensureWasmReady();
initTelemetry({ sink: consoleSink });

Built-in Sinks

• consoleSink — Logs events to the browser/Node console using the appropriate method (console.error, console.warn, etc.)
• nullSink — Discards all events (useful for explicitly disabling telemetry)

Filtering Events

Filter events by level or target module:

import { withLevelFilter, withTargetFilter, consoleSink } from '@semiotic-labs/agentium-sdk';

// Only log errors and warnings
const errorSink = withLevelFilter(['error', 'warn'], consoleSink);

// Only log events from agentium modules
const agentiumSink = withTargetFilter(['agentium_sdk'], consoleSink);

Composing Sinks

Combine multiple sinks to forward events to different destinations:

import { composeSinks, withLevelFilter, consoleSink, initTelemetry } from '@semiotic-labs/agentium-sdk';

const myAnalyticsSink = (event) => {
  // Send to your analytics service
  analytics.track('sdk_event', event);
};

initTelemetry({
  sink: composeSinks(
    withLevelFilter(['error', 'warn', 'info'], consoleSink),
    myAnalyticsSink
  ),
  filter: 'agentium_sdk=debug' // tracing-subscriber EnvFilter syntax
});

Event Structure

Events passed to sinks have the following shape:

interface TelemetryEvent {
  kind: 'event';                    // Event type (currently always "event")
  level: 'error' | 'warn' | 'info' | 'debug' | 'trace';
  target: string;                   // Module path (e.g., "agentium_sdk_wasm::vc")
  name?: string;                    // Event name
  fields: Record<string, unknown>;  // Structured fields from the event
  ts_ms: number;                    // Timestamp in milliseconds
}

API Documentation

Generate full API documentation from source:

npm run docs

Documentation is output to the docs/ folder.

Development

Setup

git clone https://github.com/semiotic-agentium/agentium-sdk.git
cd agentium-sdk
npm install

Scripts

npm test              # Run tests
npm run build         # Build (WASM + TypeScript)
npm run docs          # Generate API docs
npm run lint          # Lint code
npm run check         # Lint + format check
npm run check:python  # Type-check Python code (mypy)
npm run format:all    # Format all code (TS, Python, Rust)
npm run format:rust   # Format Rust code

REUSE Compliance

This project follows the REUSE Specification.

pip install reuse          # Install REUSE tool
npm run reuse:check        # Verify compliance
npm run reuse:write        # Apply SPDX headers

Python SDK

A Python SDK is also available with equivalent functionality. See the Python SDK documentation for installation and usage.

pip install agentium

License

MIT