Official TypeScript/JavaScript SDK for the Lilith Partner API.
Installation#
bash
npm install @lilith/partner-sdk node-fetch
Quick Start#
typescript
import { LilithPartnerClient } from '@lilith/partner-sdk';
// Initialize the client
const client = new LilithPartnerClient({
apiKey: 'lilith_live_your_api_key_here',
baseURL: 'https://api.lilith.example.com/partner', // optional
});
// Generate AI chat response
const chatResponse = await client.chat({
message: 'What is mindfulness?',
persona: 'zen_master',
});
console.log(chatResponse.response);
// Synthesize speech
const ttsResponse = await client.synthesizeSpeech({
text: 'Welcome to your mindfulness practice',
voice_id: 'calm_female_01',
format: 'opus',
});
console.log(`Audio URL: ${ttsResponse.audio_url}`);
Partner Registration#
typescript
// Register a new partner account
const registration = await client.registerPartner({
organization_name: 'My Company',
contact_email: 'contact@mycompany.com',
contact_name: 'John Doe',
website_url: 'https://mycompany.com',
use_case_description: 'Building a meditation app',
tier_request: 'professional',
});
console.log(`Partner ID: ${registration.partner_id}`);
console.log(`Status: ${registration.status}`);
API Key Management#
typescript
// Generate a new API key (after partner approval)
const apiKey = await client.createAPIKey(partnerId, {
name: 'Production API Key',
description: 'Main API key for production use',
scopes: ['chat', 'content', 'tts'],
environment: 'production',
});
console.log(`API Key: ${apiKey.api_key}`);
console.log(`Rate Limits: ${JSON.stringify(apiKey.rate_limits)}`);
// List all API keys
const keys = await client.listAPIKeys(partnerId);
console.log(`Total keys: ${keys.total_keys}`);
Chat API#
typescript
const response = await client.chat({
message: 'Teach me about meditation',
persona: 'zen_master',
user_id: 'optional-user-id',
});
console.log(response.response);
console.log(`Processing time: ${response.processing_time_ms}ms`);
Content API#
typescript
// Retrieve content
const content = await client.getContent();
console.log(`Found ${content.total_count} items`);
content.content.forEach((item) => {
console.log(`${item.title} (${item.type}, ${item.duration_minutes}min)`);
});
Text-to-Speech API#
typescript
const audio = await client.synthesizeSpeech({
text: 'Close your eyes and breathe deeply',
voice_id: 'calm_female_01',
format: 'opus',
});
console.log(`Audio URL: ${audio.audio_url}`);
console.log(`Duration: ${audio.duration_sec} seconds`);
Webhooks#
typescript
const webhook = await client.createWebhook(partnerId, {
url: 'https://myapp.com/webhooks/lilith',
events: ['chat.completed', 'tts.generated'],
description: 'Main webhook endpoint',
});
console.log(`Webhook ID: ${webhook.subscription_id}`);
console.log(`Secret: ${webhook.secret}`); // Use for signature verification
Analytics#
typescript
// Get partner usage analytics
const analytics = await client.getAnalytics(partnerId, {
timeframe: 'week',
includeDetails: true,
});
console.log(`Total requests: ${analytics.summary.total_requests}`);
console.log(`Active API keys: ${analytics.summary.active_api_keys}`);
console.log(`Error rate: ${analytics.summary.error_rate * 100}%`);
// Endpoint-specific usage
Object.entries(analytics.usage_by_endpoint).forEach(([endpoint, stats]) => {
console.log(`${endpoint}: ${stats.requests} requests (${stats.percentage}%)`);
});
Error Handling#
typescript
import { PartnerAPIClientError } from '@lilith/partner-sdk';
try {
const response = await client.chat({
message: 'Hello',
persona: 'zen_master',
});
} catch (error) {
if (error instanceof PartnerAPIClientError) {
if (error.isRateLimitError()) {
console.error(
`Rate limit exceeded. Retry after ${error.getRetryAfter()} seconds`
);
} else if (error.isAuthError()) {
console.error('Authentication error:', error.message);
} else if (error.isScopeError()) {
console.error('Insufficient scope for this operation');
} else {
console.error(`API error [${error.errorCode}]: ${error.message}`);
}
} else {
console.error('Unexpected error:', error);
}
}
Advanced Usage#
Custom Base URL#
typescript
const client = new LilithPartnerClient({
apiKey: 'your_api_key',
baseURL: 'https://custom-api.example.com',
timeout: 60000, // 60 seconds
});
Bearer Token Authentication#
The SDK automatically uses the provided apiKey with the X-API-Key header. To
use Bearer token authentication, you can pass the token as the apiKey:
typescript
const client = new LilithPartnerClient({
apiKey: 'your_token_here',
});
// The client will use: Authorization: Bearer your_token_here
Rate Limiting#
The Partner API enforces rate limits based on your tier:
- Starter: 50 req/min, 500 req/hour, 5,000 req/day
- Professional: 200 req/min, 5,000 req/hour, 50,000 req/day
- Enterprise: 1,000 req/min, 25,000 req/hour, 500,000 req/day
Rate limit errors include a retry_after value indicating when you can retry
the request.
TypeScript Support#
This SDK is written in TypeScript and includes full type definitions:
typescript
import type {
ChatRequest,
ChatResponse,
PartnerAnalytics,
RateLimits,
} from '@lilith/partner-sdk';
const request: ChatRequest = {
message: 'Hello',
persona: 'zen_master',
};
const response: ChatResponse = await client.chat(request);
API Reference#
Client Methods#
registerPartner(request)- Register new partner accountapprovePartner(partnerId, request)- Approve partner (admin)createAPIKey(partnerId, request)- Generate API keylistAPIKeys(partnerId)- List partner's API keyschat(request)- Generate AI chat responsegetContent(query?)- Retrieve contentsynthesizeSpeech(request)- Text-to-speech synthesisgetAnalytics(partnerId, options?)- Get usage analyticsgetEndpointMetrics(timeframe?)- Get endpoint metrics (admin)createWebhook(partnerId, request)- Create webhook subscriptiongetDocumentation()- Get OpenAPI documentationgetTiers()- Get tier informationcheckHealth()- Check API health
Error Methods#
isRateLimitError()- Check if rate limit errorisAuthError()- Check if authentication errorisScopeError()- Check if scope/permission errorgetRetryAfter()- Get retry-after value for rate limits
License#
MIT
Support#
For support, please contact partners@lilith.example.com or visit https://docs.lilith.example.com