Serenities SDK

The official JavaScript/TypeScript SDK for building apps with Serenities.

Quick Start

The SDK is auto-configured in App Builder projects. Just import and use.

Import Patterns

Option 1: Default Import (Recommended)

import serenities from '../api/sdk';

// Use the pre-configured client
await serenities.entities.Tasks.list();
await serenities.user.me();
await serenities.ai.invoke({ prompt: '...' });

Option 2: Named Imports

import { entities, user, ai, payments, flows } from '../api/sdk';

await entities.Tasks.list();
await user.me();

Option 3: Custom Client (NPM / API Key)

import { createClient } from '@serenities/sdk';

const client = createClient({
  projectId: 'your-project-id',
  apiBase: 'https://app.serenitiesai.com',
  apiKey: 'mk_live_xxx',  // optional, for server-side
});

await client.entities.Tasks.list();

Available Modules

entities

CRUD operations for your tables

user

Authentication and user management

ai

LLM invocation and image generation

email

Send transactional emails

files

File upload and management

payments

Stripe integration

flows

Trigger automation flows

entities - Table CRUD

Access your database tables dynamically. Use table names exactly as they appear in your database.

List All Rows

const tasks = await serenities.entities.Tasks.list();

// With sorting and limit
const recent = await serenities.entities.Tasks.list('-createdAt', 50);

Create

const newTask = await serenities.entities.Tasks.create({
  title: 'New Task',
  status: 'pending',
  priority: 1
});

Update

await serenities.entities.Tasks.update('row-id', {
  status: 'completed'
});

Delete

await serenities.entities.Tasks.delete('row-id');

Get Single Row

const task = await serenities.entities.Tasks.get('row-id');

Filter

const completed = await serenities.entities.Tasks.filter({
  status: 'completed'
});

user - Authentication

// Get current user (null if not logged in)
const currentUser = await serenities.user.me();

// Redirect to login page
serenities.user.login();
serenities.user.login('/dashboard');  // with redirect after login

// Log out
await serenities.user.logout();

// Sign up new user
await serenities.user.signup(email, password, name, profileData);

// Password reset flow
await serenities.user.forgotPassword(email);
await serenities.user.resetPassword(token, newPassword);

// Email verification
await serenities.user.verifyEmail(token);
await serenities.user.resendVerification(email);

ai - LLM & Image Generation

Invoke LLM

const response = await serenities.ai.invoke({
  prompt: 'Summarize this article...',
  model: 'gpt-4',  // optional
  systemPrompt: 'You are a helpful assistant'  // optional
});

console.log(response.text);

Generate Image

const image = await serenities.ai.generateImage({
  prompt: 'A sunset over mountains'
});

email - Send Emails

await serenities.email.send({
  to: 'user@example.com',
  subject: 'Welcome!',
  body: '<h1>Hello</h1><p>Welcome to our app!</p>'
});

files - File Upload

const file = await serenities.files.upload({
  file: base64Content,
  filename: 'document.pdf',
  folder: 'uploads'
});

payments - Stripe Integration

// List available products
const products = await serenities.payments.listProducts();

// Create checkout session
const { url } = await serenities.payments.createCheckoutSession({
  priceId: 'price_xxxxx',
  successUrl: '/success',
  cancelUrl: '/cancel'
});

window.location.href = url;

flows - Automation

// Invoke a flow by name
const result = await serenities.flows.invoke('send-welcome-email', {
  userId: 'user-123',
  email: 'user@example.com'
});

Complete Example

A full React component showing authentication and CRUD operations:

import React, { useState, useEffect } from 'react';
import serenities from '../api/sdk';

export default function TasksPage() {
  const [tasks, setTasks] = useState([]);
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function loadData() {
      // Check auth
      const currentUser = await serenities.user.me();
      setUser(currentUser);

      // Load tasks
      const allTasks = await serenities.entities.Tasks.list('-createdAt');
      setTasks(allTasks);
      setLoading(false);
    }
    loadData();
  }, []);

  const addTask = async (title) => {
    const newTask = await serenities.entities.Tasks.create({
      title,
      status: 'pending'
    });
    setTasks([newTask, ...tasks]);
  };

  const completeTask = async (id) => {
    await serenities.entities.Tasks.update(id, { status: 'completed' });
    setTasks(tasks.map(t =>
      t.id === id ? { ...t, status: 'completed' } : t
    ));
  };

  const deleteTask = async (id) => {
    await serenities.entities.Tasks.delete(id);
    setTasks(tasks.filter(t => t.id !== id));
  };

  if (loading) return <div className="p-8">Loading...</div>;

  if (!user) {
    return (
      <div className="p-8 text-center">
        <p className="mb-4">Please log in to view tasks</p>
        <button
          onClick={() => serenities.user.login()}
          className="px-4 py-2 bg-blue-500 text-white rounded"
        >
          Log In
        </button>
      </div>
    );
  }

  return (
    <div className="p-8 max-w-2xl mx-auto">
      <h1 className="text-2xl font-bold mb-6">My Tasks</h1>
      {/* ... rest of UI */}
    </div>
  );
}

NPM Installation (Coming Soon)

The SDK will be available on npm for use outside App Builder:

npm install @serenities/sdk