ultralightpro-sdk

TypeScript SDK for the Ultralight platform.

Installation

npm install ultralightpro-sdk

Or with Deno:

import { Ultralight } from 'https://ultralight.dev/sdk/mod.ts';

Quick Start

import { Ultralight } from 'ultralightpro-sdk';

const ul = new Ultralight({
  token: process.env.ULTRALIGHT_TOKEN
});

// List your apps
const { apps } = await ul.apps.list();
console.log(apps);

// Create an app
const app = await ul.apps.create({
  name: 'My Weather App',
  files: [{
    path: 'index.ts',
    content: `
      export function getWeather(city: string) {
        return { city, temp: 72, conditions: "Sunny" };
      }
    `
  }]
});

// Run a function
const result = await ul.run(app.app_id, 'getWeather', { city: 'NYC' });
console.log(result); // { city: 'NYC', temp: 72, conditions: 'Sunny' }

API Reference

Ultralight

Main client class.

const ul = new Ultralight({
  token: 'your-token',      // Required: JWT or API key
  apiUrl: 'https://...',    // Optional: Custom API URL
});

Apps

// List apps
const { apps, total } = await ul.apps.list({
  visibility: 'all',        // 'all' | 'public' | 'private' | 'unlisted'
  limit: 50,
  offset: 0,
  includeDrafts: true
});

// Get app details
const app = await ul.apps.get('app-id', {
  includeCode: true,
  includeSkills: true
});

// Create app
const newApp = await ul.apps.create({
  name: 'My App',
  slug: 'my-app',
  description: 'Does cool stuff',
  visibility: 'private',
  files: [
    { path: 'index.ts', content: '...' }
  ],
  autoGenerateDocs: true
});

// Update app
await ul.apps.update('app-id', {
  name: 'New Name',
  description: 'New description',
  visibility: 'public',
  tags: ['utility', 'api']
});

// Delete app
await ul.apps.delete('app-id');

// Search apps
const { results } = await ul.apps.search('weather api');

Drafts

// Upload a draft
await ul.drafts.upload('app-id', {
  files: [{ path: 'index.ts', content: '...' }]
});

// Get draft status
const draft = await ul.drafts.get('app-id', { includeDiff: true });

// Publish draft
await ul.drafts.publish('app-id', {
  regenerateDocs: true,
  versionBump: 'minor'  // 'patch' | 'minor' | 'major'
});

// Discard draft
await ul.drafts.discard('app-id');

Documentation

// Generate docs from code
await ul.docs.generate('app-id', { aiEnhance: false });

// Get docs
const docs = await ul.docs.get('app-id', 'markdown'); // 'markdown' | 'json' | 'mcp'

// Update docs
await ul.docs.update('app-id', '# Skills.md content...');

Execution

// Run a function
const result = await ul.run('app-id', 'functionName', { arg: 'value' }, {
  useDraft: false
});

Discovery

// Semantic search for apps
const results = await ul.discover('send emails', {
  limit: 10,
  includePrivate: true,
  minSimilarity: 0.5
});

MCP Client

// Create MCP client for an app
const mcp = ul.mcp('app-id');

// List available tools
const tools = await mcp.listTools();

// Call a tool
const output = await mcp.callTool('functionName', { arg: 'value' });

Error Handling

import { Ultralight, UltralightError } from 'ultralightpro-sdk';

try {
  await ul.run('app-id', 'someFunction');
} catch (err) {
  if (err instanceof UltralightError) {
    console.error(`Error ${err.code}: ${err.message}`);
  }
}

License

MIT