This document provides comprehensive reference documentation for the
@lilith/sdk-ts TypeScript SDK.
Overview#
The Lilith TypeScript SDK provides a comprehensive client library for interacting with the Lilith AI Wisdom Platform. It supports browsers, Node.js 18+, and edge runtime environments.
Package: @lilith/sdk-ts Version: 1.0.0 Module Type: ESM
Installation#
# npm
npm install @lilith/sdk-ts
# yarn
yarn add @lilith/sdk-ts
# pnpm
pnpm add @lilith/sdk-ts
Quick Start#
import { APIClient, SeamlessAuthClient } from '@lilith/sdk-ts';
// Initialize API client
const api = new APIClient({
baseUrl: 'https://api.lilith.ai',
token: 'your-jwt-token',
});
// Or use authentication client
const auth = new SeamlessAuthClient({
baseUrl: 'https://api.lilith.ai',
platform: 'web',
});
await auth.signIn({ email: 'user@example.com', password: 'password' });
APIClient Class#
The main client class for interacting with Lilith platform APIs.
Constructor#
new APIClient(options: APIClientOptions)
| Parameter | Type | Required | Description |
|---|---|---|---|
options.baseUrl |
string |
Yes | Base URL of the Lilith API |
options.token |
string |
No | JWT authentication token |
options.fetchImpl |
typeof fetch |
No | Custom fetch implementation |
Example:
const api = new APIClient({
baseUrl: 'https://api.lilith.ai',
token: 'eyJhbGciOiJIUzI1NiIs...',
});
Chat Methods#
chat(request)#
Send a non-streaming chat message to an AI persona.
async chat(request: ChatRequest): Promise<ChatResponse>
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
conversation_id |
string |
No | Existing conversation ID |
persona |
string |
Yes | AI persona identifier |
input.text |
string |
No | Text message content |
input.audio |
string |
No | Base64-encoded audio |
mode |
'text' | 'voice' |
Yes | Interaction mode |
options.cite |
boolean |
No | Include citations |
options.depth |
'practical' | 'scholarly' |
No | Response depth |
options.stream |
boolean |
No | Enable streaming |
Returns: ChatResponse
| Field | Type | Description |
|---|---|---|
message_id |
string |
Unique message identifier |
conversation_id |
string |
Conversation identifier |
text |
string |
Response text content |
citations |
Citation[] |
Source citations |
audio_url |
string |
Audio response URL |
metrics |
ChatMetrics |
Performance metrics |
Example:
const response = await api.chat({
persona: 'zen_master',
input: { text: 'How do I find inner peace?' },
mode: 'text',
options: { cite: true, depth: 'practical' },
});
console.log(response.text);
console.log(response.citations);
streamChat(request)#
Send a streaming chat message with real-time response tokens.
async *streamChat(request: ChatRequest): AsyncGenerator<ChatEvent>
Parameters: Same as chat() with options.stream: true
Yields: ChatEvent
| Event Type | Data | Description |
|---|---|---|
token |
{ text: string } |
Individual response token |
citations |
Citation[] |
Citation data |
audio |
{ url: string } |
Audio metadata |
done |
null |
Stream completion |
error |
{ message: string } |
Error information |
Example:
const stream = api.streamChat({
persona: 'stoic_mentor',
input: { text: 'Teach me about resilience' },
mode: 'text',
options: { stream: true },
});
for await (const event of stream) {
switch (event.event) {
case 'token':
process.stdout.write(event.data?.text ?? '');
break;
case 'citations':
console.log('Sources:', event.data);
break;
case 'done':
console.log('\nComplete');
break;
case 'error':
console.error('Error:', event.data);
break;
}
}
Conversation Methods#
listConversations(cursor?, limit?)#
List user's conversations with pagination.
async listConversations(cursor?: string, limit?: number): Promise<ConversationListResponse>
| Parameter | Type | Default | Description |
|---|---|---|---|
cursor |
string |
- | Pagination cursor |
limit |
number |
20 | Items per page |
Returns: ConversationListResponse
| Field | Type | Description |
|---|---|---|
conversations |
ConversationSummary[] |
Conversation list |
total |
number |
Total count |
nextCursor |
string |
Next page cursor |
getConversation(conversationId)#
Get full conversation with messages.
async getConversation(conversationId: string): Promise<Conversation>
Returns: Conversation with messages array.
deleteConversation(conversationId)#
Delete a conversation.
async deleteConversation(conversationId: string): Promise<void>
resetConversation(conversationId)#
Reset conversation context while preserving history.
async resetConversation(conversationId: string): Promise<void>
Content Generation Methods#
generateLecture(request)#
Generate an AI-powered educational lecture.
async generateLecture(request: LectureRequest): Promise<LectureResponse>
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
topic |
string |
Yes | Lecture topic |
duration_min |
number |
Yes | Duration in minutes |
tradition |
string[] |
No | Spiritual traditions |
lang |
string |
No | Language code |
voice |
string |
No | TTS voice ID |
outline_level |
string |
No | Detail level |
include_citations |
boolean |
No | Include sources |
ttsSynthesize(request)#
Convert text to speech.
async ttsSynthesize(request: TTSRequest): Promise<TTSResponse>
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
text |
string |
Yes | Text to synthesize |
voice |
string |
Yes | Voice ID |
format |
string |
No | Audio format (mp3, opus, wav) |
speed |
number |
No | Playback speed (0.5-2.0) |
pitch |
number |
No | Voice pitch (0.5-2.0) |
ingest(request)#
Ingest content into the knowledge base.
async ingest(request: IngestRequest): Promise<IngestResponse>
Agent Methods#
createAgent(request)#
Create a new AI agent.
async createAgent(request: AgentCreateRequest): Promise<Agent>
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
name |
string |
Yes | Agent name |
agent_type |
string |
Yes | Agent type identifier |
description |
string |
No | Agent description |
capabilities |
string[] |
No | Agent capabilities |
model |
string |
No | LLM model identifier |
system_prompt |
string |
No | System prompt |
tools |
string[] |
No | Available tools |
autonomyLevel |
'autonomous' | 'supervised' | 'manual' |
No | Autonomy level |
Example:
const agent = await api.createAgent({
name: 'Meditation Guide',
agent_type: 'wellness',
description: 'Guides users through meditation practices',
capabilities: ['guided_meditation', 'breathing_exercises'],
autonomyLevel: 'supervised',
});
listAgents(filters?)#
List agents with optional filters.
async listAgents(filters?: AgentListFilters): Promise<AgentListResponse>
| Filter | Type | Description |
|---|---|---|
type |
string |
Agent type |
status |
string |
Agent status |
enabled |
boolean |
Enabled state |
persona |
string |
Associated persona |
getAgent(agentId)#
Get agent by ID.
async getAgent(agentId: string): Promise<Agent>
createAgentSession(request)#
Create an interactive agent session.
async createAgentSession(request: AgentSessionCreateRequest): Promise<AgentSession>
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
agent_id |
string |
Yes | Agent to use |
user_id |
string |
Yes | User identifier |
context |
Record<string, unknown> |
No | Session context |
getAgentSession(sessionId)#
Get session details.
async getAgentSession(sessionId: string): Promise<AgentSession>
Agent Memory Methods#
getAgentMemory(userId, memoryType?, includeStats?)#
Retrieve agent memory for a user.
async getAgentMemory(
userId: string,
memoryType?: string,
includeStats?: boolean
): Promise<AgentMemoryResponse>
storeAgentMemory(userId, request)#
Store a memory entry.
async storeAgentMemory(
userId: string,
request: AgentMemoryStoreRequest
): Promise<AgentMemoryStoreResponse>
resetAgentMemory(userId, memoryType?)#
Clear agent memory.
async resetAgentMemory(
userId: string,
memoryType?: string
): Promise<AgentMemoryResetResponse>
Workflow Methods#
createWorkflow(request)#
Create a notification workflow.
async createWorkflow(request: WorkflowCreateRequest): Promise<Workflow>
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
agent_id |
string |
Yes | Assigned agent |
user_id |
string |
Yes | Target user |
notification_type |
string |
Yes | Notification type |
priority |
number |
No | Priority level |
triggers |
WorkflowTrigger[] |
No | Trigger conditions |
listWorkflows(filters?)#
List workflows.
async listWorkflows(filters?: WorkflowListFilters): Promise<WorkflowListResponse>
executeWorkflow(workflowId, request?)#
Execute a workflow.
async executeWorkflow(
workflowId: string,
request?: WorkflowExecuteRequest
): Promise<WorkflowExecutionResult>
AI Agent Methods#
listAIAgents()#
List domain-specific AI agents.
async listAIAgents(): Promise<AIAgentListResponse>
getAIAgent(agentId)#
Get AI agent details.
async getAIAgent(agentId: string): Promise<{ agent: DomainAgent }>
getAIAgentsByRole(role)#
Find agents by role.
async getAIAgentsByRole(role: string): Promise<AIAgentQueryResponse>
getAIAgentsByCapability(capability)#
Find agents by capability.
async getAIAgentsByCapability(capability: string): Promise<AIAgentQueryResponse>
getAIAgentsByTool(toolName)#
Find agents by tool.
async getAIAgentsByTool(toolName: string): Promise<AIAgentQueryResponse>
createAIAgentTask(agentId, request)#
Create a task for an AI agent.
async createAIAgentTask(
agentId: string,
request: AIAgentTaskRequest
): Promise<AIAgentTaskResponse>
Admin Methods#
Note: Admin methods require elevated permissions.
User Management#
// Update user roles
async adminUpdateUserRoles(userId: string, roles: string[]): Promise<AdminUserRolesResponse>
// Get user audit logs
async adminGetUserAuditLogs(userId: string): Promise<AdminUserAuditLogsResponse>
Backup & Restore#
// Create backup
async createBackup(request?: BackupRequest): Promise<BackupResponse>
// List backups
async listBackups(): Promise<BackupListResponse>
// Get backup status
async getBackupStatus(backupId: string): Promise<BackupResponse>
// Delete backup
async deleteBackup(backupId: string): Promise<void>
// Create restore operation
async createRestore(request: RestoreRequest): Promise<RestoreResponse>
// Get restore status
async getRestoreStatus(restoreId: string): Promise<RestoreResponse>
System Management#
// Get system health
async getSystemHealth(): Promise<SystemHealthResponse>
// Get system configuration
async getSystemConfig(): Promise<SystemConfigResponse>
// Set maintenance mode
async setMaintenanceMode(request: MaintenanceRequest): Promise<MaintenanceResponse>
// Get maintenance status
async getMaintenanceStatus(): Promise<MaintenanceResponse>
Autoscaling & GPU#
// Get autoscaling status
async getAutoscalingStatus(): Promise<AutoscalingStatusResponse>
// Execute scaling action
async executeScalingAction(request: ScalingActionRequest): Promise<ScalingActionResponse>
// Get GPU metrics
async getGPUMetrics(): Promise<GPUMetricsResponse>
SeamlessAuthClient Class#
Handles authentication across multiple platforms with seamless state synchronization.
Constructor#
new SeamlessAuthClient(options: SeamlessAuthClientOptions)
| Parameter | Type | Required | Description |
|---|---|---|---|
options.baseUrl |
string |
Yes | API base URL |
options.coordinator |
SeamlessAuthCoordinator |
No | State coordinator |
options.fetchImpl |
typeof fetch |
No | Custom fetch |
options.platform |
SeamlessAuthPlatform |
No | Platform identifier |
Platforms: 'web' | 'mobile' | 'desktop' | 'sdk'
Authentication Methods#
signIn(credentials, options?)#
Authenticate a user.
async signIn(
credentials: SignInCredentials,
options?: AuthOptions
): Promise<SeamlessAuthState>
Credentials:
| Field | Type | Required | Description |
|---|---|---|---|
email |
string |
Yes | User email |
password |
string |
No | Password (for password auth) |
mfaCode |
string |
No | MFA verification code |
Example:
const state = await auth.signIn({
email: 'user@example.com',
password: 'securePassword123',
});
console.log('Logged in as:', state.user?.email);
register(credentials, options?)#
Register a new user.
async register(
credentials: RegisterCredentials,
options?: AuthOptions
): Promise<SeamlessAuthState>
Credentials:
| Field | Type | Required | Description |
|---|---|---|---|
email |
string |
Yes | User email |
password |
string |
Yes | Password |
displayName |
string |
No | Display name |
acceptedTerms |
boolean |
No | Terms acceptance |
signOut()#
Sign out and clear session.
async signOut(): Promise<void>
refresh()#
Refresh the authentication token.
async refresh(): Promise<SeamlessAuthState>
validate()#
Validate the current token.
async validate(): Promise<TokenValidationResult>
Returns:
| Field | Type | Description |
|---|---|---|
valid |
boolean |
Token validity |
userId |
string |
User ID |
expiresAt |
string |
Expiration timestamp |
scopes |
string[] |
Permission scopes |
Profile Methods#
getProfile()#
Get user profile.
async getProfile(): Promise<UserProfile>
updateProfile(updates)#
Update user profile.
async updateProfile(updates: UpdateProfileRequest): Promise<UserProfile>
deleteAccount()#
Delete user account.
async deleteAccount(): Promise<void>
Session Methods#
listSessions()#
List active sessions.
async listSessions(): Promise<SessionInfo[]>
revokeSession(sessionId)#
Revoke a session.
async revokeSession(sessionId: string): Promise<void>
Password Methods#
changePassword(request)#
Change password.
async changePassword(request: PasswordChangeRequest): Promise<void>
requestPasswordReset(email)#
Request password reset.
async requestPasswordReset(email: string): Promise<void>
confirmPasswordReset(token, newPassword)#
Confirm password reset.
async confirmPasswordReset(token: string, newPassword: string): Promise<void>
OAuth Methods#
getOAuthProviders()#
Get available OAuth providers.
async getOAuthProviders(): Promise<OAuthProvider[]>
getOAuthAuthorizationUrl(provider, redirectUri?)#
Get OAuth authorization URL.
async getOAuthAuthorizationUrl(
provider: OAuthProviderType,
redirectUri?: string
): Promise<OAuthAuthorizationUrl>
Providers: 'google' | 'github' | 'apple' | 'facebook'
completeOAuthSignIn(provider, code, state?)#
Complete OAuth flow.
async completeOAuthSignIn(
provider: OAuthProviderType,
code: string,
state?: string
): Promise<OAuthCallbackResult>
WebAuthn Methods#
registerWebAuthnCredential(request)#
Register a WebAuthn credential (passkey).
async registerWebAuthnCredential(
request: WebAuthnRegisterRequest
): Promise<WebAuthnCredential>
authenticateWithWebAuthn(request)#
Authenticate with WebAuthn.
async authenticateWithWebAuthn(
request: WebAuthnAuthenticateRequest
): Promise<SeamlessAuthState>
Two-Factor Authentication#
enable2FA()#
Enable 2FA and get setup data.
async enable2FA(): Promise<TwoFactorEnableResponse>
Returns:
| Field | Type | Description |
|---|---|---|
secret |
string |
TOTP secret |
qr_code |
string |
QR code data URL |
backup_codes |
string[] |
Recovery codes |
verify2FA(code)#
Verify 2FA setup.
async verify2FA(code: string): Promise<TwoFactorVerifyResponse>
disable2FA(password)#
Disable 2FA.
async disable2FA(password: string): Promise<TwoFactorDisableResponse>
toggleMFA(enable?)#
Toggle MFA status.
async toggleMFA(enable?: boolean): Promise<MFAToggleResponse>
State Management#
getState()#
Get current authentication state.
getState(): SeamlessAuthState
Returns:
| Field | Type | Description |
|---|---|---|
user |
AuthUser | null |
Current user |
session |
AuthSession | null |
Current session |
token |
string | null |
JWT token |
lastOrigin |
string | null |
Last update origin |
lastUpdatedAt |
string | null |
Last update timestamp |
onStateChange(handler)#
Subscribe to state changes.
onStateChange(handler: (state: SeamlessAuthState) => void): () => void
Example:
const unsubscribe = auth.onStateChange((state) => {
if (state.user) {
console.log('User logged in:', state.user.email);
} else {
console.log('User logged out');
}
});
// Later: cleanup
unsubscribe();
Type Definitions#
Chat Types#
interface ChatRequest {
conversation_id?: string;
persona: string;
input: {
text?: string | null;
audio?: string | null; // base64
};
mode: 'text' | 'voice';
options?: {
cite?: boolean;
depth?: 'practical' | 'scholarly';
stream?: boolean;
};
}
interface ChatResponse {
message_id: string;
conversation_id: string;
text?: string;
citations?: Citation[];
audio_url?: string | null;
metrics?: {
tokens_in?: number;
tokens_out?: number;
latency_ms?: number;
model_inference_ms?: number;
};
}
interface Citation {
source_uri: string;
span?: { start: number; end: number };
license?: string;
confidence?: number;
}
Agent Types#
interface Agent {
id: string;
name: string;
type: string;
description?: string;
capabilities?: string[];
role?: string;
status?: 'active' | 'inactive' | 'training' | 'error' | 'maintenance';
model?: string;
system_prompt?: string;
tools?: string[];
autonomyLevel?: string;
createdAt?: string;
updatedAt?: string;
config?: Record<string, unknown>;
statistics?: {
tasksCompleted?: number;
avgResponseTime?: number;
successRate?: number;
};
}
interface AgentSession {
session_id: string;
user_id: string;
agent_id: string;
status: 'active' | 'paused' | 'completed' | 'error';
context?: Record<string, unknown>;
messages?: Array<{
role: 'user' | 'assistant' | 'system';
content: string;
timestamp: string;
}>;
createdAt: string;
lastActivityAt: string;
}
Authentication Types#
interface UserProfile {
id: string;
email: string;
username?: string;
fullName?: string;
avatarUrl?: string;
roles: string[];
mfaEnabled: boolean;
isVerified: boolean;
createdAt: string;
updatedAt: string;
preferences?: Record<string, unknown>;
}
interface SessionInfo {
sessionId: string;
deviceId: string;
platform: string;
lastActivityAt: string;
createdAt: string;
isCurrent: boolean;
}
Error Handling#
The SDK throws standard JavaScript Error objects with descriptive messages:
try {
const response = await api.chat({
persona: 'zen_master',
input: { text: 'Hello' },
mode: 'text',
});
} catch (error) {
if (error instanceof Error) {
// Parse HTTP status from message format: "401 Unauthorized: ..."
const statusMatch = error.message.match(/^(\d{3})/);
const status = statusMatch ? parseInt(statusMatch[1]) : 0;
switch (status) {
case 401:
console.log('Authentication required');
break;
case 429:
console.log('Rate limit exceeded');
break;
case 500:
console.log('Server error');
break;
default:
console.log('Error:', error.message);
}
}
}
Platform Support#
Browser Compatibility#
| Browser | Minimum Version |
|---|---|
| Chrome | 90+ |
| Firefox | 88+ |
| Safari | 14+ |
| Edge | 90+ |
Node.js#
- Node.js 18.0+ (native fetch required)
- Compatible with CommonJS and ES modules
Edge Runtimes#
- Cloudflare Workers
- Vercel Edge Functions
- Deno Deploy
Environment Variables#
# API Configuration
LILITH_API_BASE_URL=https://api.lilith.ai
LILITH_API_TIMEOUT=30000
# Debug Mode
LILITH_DEBUG=true
Best Practices#
Token Management#
// Store tokens securely
const api = new APIClient({
baseUrl: process.env.LILITH_API_BASE_URL!,
token: secureTokenStorage.get(),
});
// Refresh tokens before expiration
auth.onStateChange((state) => {
if (state.token) {
secureTokenStorage.set(state.token);
}
});
Streaming Best Practices#
// Handle streaming with proper cleanup
const controller = new AbortController();
try {
const stream = api.streamChat({
persona: 'guide',
input: { text: 'Long meditation' },
mode: 'text',
options: { stream: true },
});
for await (const event of stream) {
if (controller.signal.aborted) break;
// Process event
}
} catch (error) {
if (!controller.signal.aborted) {
console.error('Stream error:', error);
}
}
Error Recovery#
// Implement retry logic
async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
let lastError: Error;
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (error) {
lastError = error as Error;
if (error.message.includes('429')) {
await new Promise((r) => setTimeout(r, Math.pow(2, i) * 1000));
} else {
throw error;
}
}
}
throw lastError!;
}
Related Documentation#
- Authentication Guide - Authentication flows and security
- API Versioning - Version management and migration
- Error Codes - Complete error reference
- Partner API SDK - Third-party integration SDK
Support#
- GitHub Issues: Report bugs
- Documentation: https://docs.lilith.ai
- Email: sdk-support@lilith.ai