BuildAI SDK

A comprehensive SDK for BuildAI applications with seamless entity management, integrations, backend functions, and authentication.

Installation

npm install @buildaispace/sdk

Quick Start

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

const buildai = createClient({
  appId: 'your-app-id', // Required
  serverUrl: 'https://buildai.space', // Optional
  token: 'your-access-token' // Optional, for user authentication
});

const meals = await buildai.entities.Meal.list('created_at:desc', 10);
const filteredMeals = await buildai.entities.Meal.filter({type: 'vegetarian'});

const llmResponse = await buildai.integrations.Core.InvokeLLM({
  prompt: 'Analyze this data',
  response_json_schema: {type: 'object'}
});

const user = await buildai.auth.me();
await buildai.auth.updateMyUserData({firstName: 'John'});

Authentication

Manual Token

const buildai = createClient({
  appId: 'your-app-id',
  token: 'your-access-token'
});

Auth Methods

const isAuth = await buildai.auth.isAuthenticated();
const user = await buildai.auth.me();
await buildai.auth.updateMyUserData({firstName: 'John', lastName: 'Doe'});
buildai.auth.setToken('new-token');
buildai.setToken('new-token');

Entity Operations

Core Methods

// List all entities
const entities = await buildai.entities.EntityName.list(
  'created_at:desc',
  10,
  0,
  ['name', 'email']
);

// Filter entity by status
const filtered = await buildai.entities.EntityName.filter(
  {status: 'active'},
  'created_at:desc',
  10,
  0,
  ['name' ,'email']
);

// Get a specific entity
const entity = await buildai.entities.EntityName.get('entity-id');

// Create an entity
const newEntity = await buildai.entities.EntityName.create({
  name: 'New Entity',
  description: 'Entity description'
});

// Update an entity
const updated = await buildai.entities.EntityName.update('entity-id', {
  name: 'Updated Name'
});

// Delete an entity
await buildai.entities.EntityName.delete('entity-id');

// Bulk create entities
const entities = await buildai.entities.EntityName.bulkCreate([
  {name: 'Entity 1'},
  {name: 'Entity 2'}
]);

Working with Integrations

Core Integrations

const response = await buildai.integrations.Core.InvokeLLM({
  prompt: 'Analyze this data',
  response_json_schema: {
    type: 'object',
    properties: {
      analysis: {type: 'string'},
      confidence: {type: 'number'}
    }
  },
});

await buildai.integrations.Core.SendEmail({
  to: '[email protected]',
  subject: 'Hello from BuildAI',
  body: 'This is an automated email',
});

const uploadResult = await buildai.integrations.Core.UploadFile({
  file: fileObject,
});

Installable Integrations

await buildai.integrations.CustomPackage.CustomEndpoint({
  param1: 'value1',
  param2: 'value2'
});

File Handling

const formData = new FormData();
formData.append('file', fileObject);
formData.append('category', 'invoices');

await buildai.integrations.Core.ProcessDocument(formData);

await buildai.integrations.Core.ProcessDocument({
  file: fileObject,
  category: 'invoices',
  metadata: {priority: 'high'}
});

Functions

Call your backend functions deployed on BuildAI. Functions are dynamically accessed based on the function names available in your app.

Basic Function Call

// Call a function with parameters
const result = await buildai.functions.myCustomFunction({
  param1: 'value1',
  param2: 'value2'
});

// Process order example
const orderResult = await buildai.functions.processOrder({
  orderId: '123',
  items: [{id: 1, quantity: 2}],
});

// Generate report example
const report = await buildai.asServiceRole.functions.generateReportData({
  startDate: '2024-01-01',
  endDate: '2024-12-31',
});

Error Handling

import { BuildAIError } from '@buildaispace/sdk';

try {
  const result = await buildai.entities.User.create({email: 'invalid'});
} catch (error) {
  if (error instanceof BuildAIError) {
    console.log('Status:', error.status);
    console.log('Code:', error.code);
    console.log('Data:', error.data);
  }
}

Configuration Options

const buildai = createClient({
  serverUrl: 'https://buildai.space', // Optional, defaults to 'https://buildai.space'
  appId: 'your-app-id', // Required
  env: 'prod', // Optional, default to 'prod'
  token: 'your-token', // Optional, for user authentication
  serviceToken: 'your-service-token' // Optional, for service role operations
});

Service Role Authentication

Service role authentication allows server-side applications to perform operations with elevated privileges. This is useful for administrative tasks, background jobs, and server-to-server communication.

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

// Create a client with service role token
const buildai = createClient({
  appId: 'your-app-id',
  token: 'user-token',              // For user operations
  serviceToken: 'service-token'     // For service role operations
});

// User operations (uses user token - limited by permissions)
const publicData = await buildai.entities.Product.list();

// Service role operations (uses service token - elevated privileges)
const sensitiveData = await buildai.asServiceRole.entities.SensitiveData.list();
const adminRecords = await buildai.asServiceRole.entities.AuditLog.filter({
  action: 'admin_access'
});

// Service role has access to:
// - buildai.asServiceRole.entities
// - buildai.asServiceRole.integrations
// - buildai.asServiceRole.functions
// Note: Service role does NOT have access to auth module for security

// If no service token is provided, accessing asServiceRole throws an error
const clientWithoutService = createClient({ appId: 'your-app-id' });
try {
  await clientWithoutService.asServiceRole.entities.SensitiveData.list();
} catch (error) {
  // Error: Service token is required to use asServiceRole
}

TypeScript Support

import { BuildAIClient, Entity, ClientConfig } from '@buildaispace/sdk';

const config: ClientConfig = {
  appId: 'your-app-id',
  env: 'prod'
};

const client: BuildAIClient = createClient(config);
const users: Entity[] = await client.entities.User.list();

License

MIT License