Arlopass Docs

ArlopassClient

The core client class. Manages connection state, provider selection, and chat operations over the protocol transport.

import { ArlopassClient } from "@arlopass/web-sdk";

Constructor options

Prop Type Default Description
transport required ArlopassTransport — Transport implementation (provided by the browser extension via window.arlopass).
origin string "https://app.arlopass.local" Origin URL for envelope metadata. Auto-set to window.location.origin when in a browser.
timeoutMs number 5000 Default request timeout in milliseconds.
envelopeTtlMs number 60000 Time-to-live for protocol envelopes.
protocolVersion string "1.0.0" Protocol version string.
nonce string — Nonce for envelope signatures.
now () => Date — Clock function for envelope timestamps. Defaults to () => new Date().
randomId () => string — ID generator for request/correlation IDs. Defaults to crypto.randomUUID().
defaultCapabilities readonly ProtocolCapability[] — Capabilities to request during connect.
defaultProviderId string "provider.system" Fallback provider ID for envelopes before selection.
defaultModelId string "model.default" Fallback model ID for envelopes before selection.
tracing TelemetryTracing — Optional tracing hook for observability. 
const client = new ArlopassClient({
  transport,
  origin: window.location.origin,
});

Properties

Prop Type Default Description
state ClientState — Current connection state (readonly getter).
sessionId string | undefined — Active session ID after connect, undefined before.
selectedProvider { providerId: string; modelId: string } | undefined — Currently selected provider/model pair.
contextWindowSize number — Context window size in tokens for the selected model. Falls back to 4096 for unknown models.
chat { send, stream } — Chat operation namespace (see Methods below).

Methods

Prop Type Default Description
connect (options: ConnectOptions) => Promise<ConnectResult> — Establish connection with the extension. Transitions state: disconnected → connecting → connected.
disconnect () => Promise<void> — Disconnect and reset state to disconnected.
listProviders () => Promise<ListProvidersResult> — Fetch available providers and models. Requires connected state.
selectProvider (input: SelectProviderInput) => Promise<SelectProviderResult> — Select a provider/model pair. Requires connected state.
chat.send (input: ChatInput, options?: ChatOperationOptions) => Promise<ChatSendResult> — Send messages and receive a complete response. Requires connected state + selected provider.
chat.stream (input: ChatInput, options?: ChatOperationOptions) => AsyncIterable<ChatStreamEvent> — Send messages and stream the response as chunks. Supports AbortSignal via options.signal.
getContextInfo (messages: readonly ChatMessage[], reserveOutputTokens?: number) => ContextWindowInfo — Compute context window usage for the selected model given a set of messages. Useful for token meters and "context full" warnings. 
const client = new ArlopassClient({ transport: window.arlopass });

await client.connect({ appId: "com.example.myapp" });
const { providers } = await client.listProviders();
await client.selectProvider({ providerId: "openai", modelId: "gpt-4o" });
// Non-streaming
const result = await client.chat.send({
  messages: [{ role: "user", content: "Hello" }],
});
console.log(result.message.content);

// Streaming
for await (const event of client.chat.stream({
  messages: [{ role: "user", content: "Hello" }],
})) {
  if (event.type === "chunk") process.stdout.write(event.delta);
}

// Context window info
const info = client.getContextInfo(messages);
console.log(
  `${info.usedTokens}/${info.maxTokens} (${Math.round(info.usageRatio * 100)}%)`,
);
console.log("Window size:", client.contextWindowSize);

State machine

// State machine transitions:
//
// disconnected ──connect()──→ connecting ──success──→ connected
//                                  │                      │
//                                  └──fail──→ failed      ├──degraded
//                                                         │
// connected ──disconnect()──→ disconnected       reconnecting
//                                                    │
//                                                    └──→ connected | failed