@kolbo/app-sdk

The official SDK for Kolbo App Builder generated apps.

Provides a unified client for auth, data, storage, and AI — all backed by the Kolbo platform.

Installation

npm install @kolbo/app-sdk

Usage

In apps generated by Kolbo App Builder, src/lib/kolbo.ts is auto-injected and pre-configured. You never need to call createClient yourself — just import:

import { kolbo } from '../lib/kolbo';

For custom apps or external projects:

import { createClient } from '@kolbo/app-sdk';

const kolbo = createClient(); // reads VITE_KOLBO_* env vars automatically

Namespaces

kolbo.auth

Kolbo-native auth. Email + password, email OTP, and Google OAuth (via the shared Kolbo proxy at auth.kolbo.ai) — all backed by Kolbo's own user store. No separate Supabase project required.

// Email + password
await kolbo.auth.signUp({ email: '[email protected]', password: 'secret' });
await kolbo.auth.signInWithPassword({ email: '[email protected]', password: 'secret' });

// Email OTP (magic code)
await kolbo.auth.signInWithOtp({ email: '[email protected]' });
await kolbo.auth.verifyOtp({ email: '[email protected]', code: '123456' });

// Google OAuth — works identically in sandbox previews and published URLs.
// Opens a popup, uses PKCE, returns a Kolbo session.
const { data, error } = await kolbo.auth.signInWithGoogle({ redirectTo: '/auth/callback' });

// Get current user
const { data: { user } } = await kolbo.auth.getUser();

// Sign out
await kolbo.auth.signOut();

// Listen to auth state changes (same-tab + cross-tab via `storage` events)
const { data: { subscription } } = kolbo.auth.onAuthStateChange((event, session) => { ... });
// ...later
subscription.unsubscribe();

Bring-your-own Supabase (optional)

Set VITE_KOLBO_BACKEND=supabase and provide VITE_SUPABASE_URL + VITE_SUPABASE_ANON_KEY to route auth + data through your own Supabase project instead of Kolbo's backend. Requires @supabase/supabase-js as a peer dependency.

kolbo.data

MongoDB-backed shared database. Scoped to your app — other apps can't read your data.

// List with filter + sort + pagination
const { data, error } = await kolbo.data.list('tasks', {
  where: { userId: user.id, status: 'active' },
  sort: { createdAt: -1 },
  limit: 20,
  offset: 0,
});

// CRUD
const { data: task } = await kolbo.data.create('tasks', { title: 'Buy milk', userId: user.id });
const { data: updated } = await kolbo.data.update('tasks', task._id, { status: 'done' });
await kolbo.data.delete('tasks', task._id);

kolbo.storage

// Upload a file
const { data } = await kolbo.storage.upload('avatars', file.name, file);
const publicUrl = data.url; // permanent CDN URL

// List files
const { data: files } = await kolbo.storage.list('avatars');

// Delete
await kolbo.storage.delete('avatars', data.id);

kolbo.ai

Call Kolbo's AI APIs. Polls automatically — resolves when generation is complete.

// Chat / text generation
const { content, session_id } = await kolbo.ai.chat({ message: 'Tell me a joke' });

// Continue a conversation
const { content: reply } = await kolbo.ai.chat({ message: 'Another one', session_id });

// Image generation
const { url } = await kolbo.ai.generateImage({ prompt: 'Sunset over the ocean', aspect_ratio: '16:9' });

// Video generation (takes 1–5 minutes)
const { url: videoUrl } = await kolbo.ai.generateVideo({ prompt: 'Timelapse of a busy city', duration: 5 });

// Music
const { url: musicUrl } = await kolbo.ai.generateMusic({ prompt: 'Upbeat jazz background' });

// TTS
const { url: speechUrl } = await kolbo.ai.generateSpeech({ text: 'Hello world', voice: 'shimmer' });

VITE_KOLBO_API_KEY and VITE_KOLBO_BASE are auto-injected into every Kolbo App Builder app. You never need to configure them manually.

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | VITE_KOLBO_APP_ID | ✅ | Your app's unique ID | | VITE_KOLBO_API_URL | ✅ | Kolbo backend URL (auth + data + storage live under /api/*) | | VITE_KOLBO_API_KEY | For kolbo.ai | Kolbo public API key | | VITE_KOLBO_BASE | For kolbo.ai | Kolbo API base URL (default: https://api.kolbo.ai/api) | | VITE_KOLBO_OAUTH_PROXY_URL | Optional | Override Kolbo OAuth proxy base (default: https://auth.kolbo.ai/oauth/v1) | | VITE_KOLBO_BACKEND | Optional | kolbo (default) or supabase (BYO Supabase) | | VITE_SUPABASE_URL | BYO Supabase only | Your own Supabase project URL | | VITE_SUPABASE_ANON_KEY | BYO Supabase only | Your own Supabase anon key |

All variables are automatically injected by Kolbo App Builder at build time.

License

MIT