@inference-ui/node

Node.js client SDK for Inference UI - interact with the Cloudflare-hosted API from your Node.js backend.

Installation

npm install @inference-ui/node

Quick Start

import { InferenceUIClient } from '@inference-ui/node';

// Initialize client with your API key
const client = new InferenceUIClient({
  apiKey: process.env.INFERENCE_API_KEY, // sk_live_xxx
});

// Get current user
const user = await client.getCurrentUser();
console.log(user);

// Track events
await client.trackEvent({
  event: 'user_signup',
  timestamp: Date.now(),
  data: { plan: 'business' },
});

// Query analytics
const analytics = await client.queryAnalytics({
  startDate: Date.now() - 30 * 24 * 60 * 60 * 1000, // 30 days ago
  endDate: Date.now(),
  metrics: ['events', 'users'],
});

Features

• ✅ Type-Safe - Full TypeScript support with type definitions
• ✅ GraphQL Client - Built-in GraphQL client for API queries/mutations
• ✅ User Management - Get user info, check tier limits
• ✅ API Key Management - Create, list, and revoke API keys
• ✅ Event Tracking - Track events and batch operations
• ✅ Analytics - Query usage metrics and analytics data
• ✅ Flow Management - Create and manage UX flows

API Reference

Client Initialization

const client = new InferenceUIClient({
  apiKey: 'sk_live_xxx',           // Required: Your API key
  apiUrl: 'https://...',           // Optional: Custom API endpoint
  timeout: 30000,                  // Optional: Request timeout (ms)
  headers: { 'X-Custom': 'value' } // Optional: Custom headers
});

User Management

// Get current user
const user = await client.getCurrentUser();
// Returns: { id, email, tier, createdAt }

API Key Management

// Create new API key
const apiKey = await client.createApiKey({
  name: 'Production API',
  expiresInDays: 90, // Optional
});
// Returns: { apiKey, keyPrefix, createdAt, expiresAt }
// ⚠️ apiKey is only shown once - store it securely!

// List all API keys
const keys = await client.listApiKeys();
// Returns: [{ id, keyPrefix, name, lastUsedAt, expiresAt, revokedAt, createdAt }]

// Revoke an API key
await client.revokeApiKey('sk_live_abc1');

Event Tracking

// Track single event
await client.trackEvent({
  event: 'button_click',
  component: 'PurchaseButton',
  timestamp: Date.now(),
  data: { price: 99.99 },
});

// Track multiple events (batch)
await client.trackEvents([
  { event: 'page_view', timestamp: Date.now() },
  { event: 'form_submit', timestamp: Date.now() },
]);

Analytics

// Query analytics
const analytics = await client.queryAnalytics({
  userId: 'user_123',              // Optional: specific user
  startDate: 1704067200000,        // Required: start timestamp
  endDate: 1706745600000,          // Required: end timestamp
  metrics: ['events', 'sessions'], // Optional: specific metrics
  groupBy: 'day',                  // Optional: group by time period
});
// Returns: { metrics: {...}, breakdown: [...] }

// Get usage metrics
const usage = await client.getUsageMetrics();
// Returns: { userId, tier, eventsThisMonth, eventsLimit, ... }

Flow Management

// Get all flows
const flows = await client.getFlows();

// Get specific flow
const flow = await client.getFlow('flow_123');

// Create new flow
const newFlow = await client.createFlow('Onboarding', [
  { id: '1', component: 'WelcomeScreen' },
  { id: '2', component: 'ProfileSetup' },
]);

// Delete flow
await client.deleteFlow('flow_123');

Usage Examples

Next.js API Route

// app/api/analytics/route.ts
import { InferenceUIClient } from '@inference-ui/node';

const client = new InferenceUIClient({
  apiKey: process.env.INFERENCE_API_KEY!,
});

export async function GET() {
  const analytics = await client.queryAnalytics({
    startDate: Date.now() - 7 * 24 * 60 * 60 * 1000, // Last 7 days
    endDate: Date.now(),
  });

  return Response.json(analytics);
}

Express Server

import express from 'express';
import { InferenceUIClient } from '@inference-ui/node';

const app = express();
const client = new InferenceUIClient({
  apiKey: process.env.INFERENCE_API_KEY!,
});

app.post('/track', async (req, res) => {
  await client.trackEvent({
    event: req.body.event,
    timestamp: Date.now(),
    data: req.body.data,
  });

  res.json({ success: true });
});

app.listen(3000);

Scheduled Jobs (Cron)

import { InferenceUIClient } from '@inference-ui/node';

const client = new InferenceUIClient({
  apiKey: process.env.INFERENCE_API_KEY!,
});

// Daily analytics report
async function dailyReport() {
  const yesterday = Date.now() - 24 * 60 * 60 * 1000;
  const today = Date.now();

  const analytics = await client.queryAnalytics({
    startDate: yesterday,
    endDate: today,
    metrics: ['events', 'users', 'sessions'],
  });

  console.log('Daily Analytics:', analytics);
}

// Run daily
setInterval(dailyReport, 24 * 60 * 60 * 1000);

TypeScript Support

Full TypeScript support with exported types:

import type {
  InferenceUIConfig,
  User,
  ApiKey,
  Event,
  AnalyticsQuery,
  UsageMetrics,
} from '@inference-ui/node';

Error Handling

try {
  const user = await client.getCurrentUser();
} catch (error) {
  if (error.message.includes('Unauthorized')) {
    console.error('Invalid API key');
  } else if (error.message.includes('timeout')) {
    console.error('Request timed out');
  } else {
    console.error('API error:', error);
  }
}

Environment Variables

# .env
INFERENCE_API_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxx

Links

• npm: https://www.npmjs.com/package/@inference-ui/node
• GitHub: https://github.com/Neureus/Inference-UI
• Documentation: https://inference-ui.dev/docs/node-sdk
• API Reference: https://inference-ui.dev/docs/api

License

MIT