SDK Overview

@ilana/sdk is the foundation for Bring Your Own Frontend (BYOFE) — a lightweight TypeScript client that lets you build any kind of UI powered by Ilana's governance engine. Chat interfaces, search bars, form assistants, command palettes, internal tools — you design the experience, Ilana handles the governance.

Your frontend. Our governance.

Installation

npm install @ilana/sdk

Works in Node.js, browsers, and edge runtimes.

Quick Example

import { IlanaClient } from '@ilana/sdk';

const client = new IlanaClient({
  runtimeUrl: 'https://api.getilana.ai',
  token: 'your-embed-token',
});

const result = await client.query({
  botId: 'your-bot-id',
  input: 'What features do you offer?',
});

if (result.ok) {
  console.log(result.data.response);

  // Governance metadata for building context-aware UIs
  console.log(result.data.metadata.capabilityAllowed);
  console.log(result.data.metadata.enforcementReason);
}

Why BYOFE?

The embed widget gives you a ready-made chat interface. The SDK gives you full control:

• Build any UI pattern — not just chat. Search, forms, tooltips, CLI tools, Slack bots, etc.
• Access governance metadata on every response — adapt your UI based on what's allowed, enforced, or restricted
• Handle errors and edge cases your way — custom retry logic, fallback UIs, graceful degradation
• Server-side or client-side — works anywhere JavaScript runs

What's Included

• IlanaClient — Main client class for sending queries
• IlanaSDKError — Typed error class with error codes
• Result pattern — { ok: true, data } or { ok: false, error } by default
• throwOnError mode — Opt into throwing IlanaSDKError instead

Sections

• Client Configuration — Constructor options and setup
• Querying — Sending queries and handling responses
• Error Handling — Error codes, Result type, and error classes