Fireberry SDK

The Fireberry SDK (@fireberry/sdk) enables your app to communicate with the Fireberry platform. Use it to access information about the current user and record, and to perform data operations.

Resources:

Installation

npm install @fireberry/sdk

Quick Start

import FireberryClientSDK from '@fireberry/sdk/client';

// 1. Create the client
const client = new FireberryClientSDK();

// 2. Initialize (required before using context or API)
await client.initializeContext();

// 3. Use context and API
const { user, record } = client.context;
const { fullName } = user;
console.log(`Hello, ${fullName}!`);

const results = await client.api.query(1, {
  fields: 'accountid,accountname',
  query: 'status = "active"'
});

How It Works

Your app runs in an iframe inside Fireberry. The SDK handles all communication with the parent window:

sequenceDiagram
    participant App as Your App (iframe)
    participant SDK as Fireberry SDK
    participant FB as Fireberry Platform

    App->>SDK: initializeContext()
    SDK->>FB: Request context
    FB-->>SDK: User + Record info
    SDK-->>App: Context ready

    App->>SDK: api.query(...)
    SDK->>FB: Query API request
    FB-->>SDK: Data response
    SDK-->>App: Results

Context

Context provides information about who's using your app and what they're looking at.

Accessing Context

await client.initializeContext();

const { user, record } = client.context;

// User info (always available)
console.log(user.id);        // User's unique ID
console.log(user.fullName);  // User's display name

// Record info (only in Record components)
console.log(record.id);      // Current record ID
console.log(record.type);    // Object type number

Context by Component Type

Context	Record Component	Side Menu	Global Menu
`user.id`	✓	✓	✓
`user.fullName`	✓	✓	✓
`record.id`	✓	—	—
`record.type`	✓	—	—

📘
Note
Record context is only available in Record components. For Side Menu and Global Menu components, record will be empty.

API Methods

The SDK provides four methods for working with Fireberry data:

Method	Description
`api.query()`	Retrieve records
`api.create()`	Create a new record
`api.update()`	Update an existing record
`api.delete()`	Delete a record

query

Retrieve records based on criteria.

const results = await client.api.query(objectType, {
  fields: 'accountid,accountname,status,createdon',
  query: 'status = "active"',
  page_size: 20,      // optional
  page_number: 1      // optional
});

Parameters:

Parameter	Type	Description
`objectType`	`string \| number`	The object type to query
`fields`	`string`	Comma-separated list of fields to return
`query`	`string`	Filter expression
`page_size`	`number`	Records per page (optional)
`page_number`	`number`	Page number, 1-indexed (optional)

Query syntax:

Operator	Example
`=`	`status = "active"`
`!=`	`status != "closed"`
`AND`	`status = "active" AND priority = "high"`
`OR`	`status = "open" OR status = "pending"`

create

Create a new record.

const result = await client.api.create(objectType, {
  name: 'New Project',
  status: 'active',
  priority: 'high'
});

if (result.success) {
  console.log('Created:', result.data.id);
}

update

Update an existing record.

const result = await client.api.update(objectType, recordId, {
  status: 'completed'
});

if (result.success) {
  console.log('Updated successfully');
}

delete

Delete a record.

const result = await client.api.delete(objectType, recordId);

if (result.success) {
  console.log('Deleted');
}

Response Format

All API methods return the same structure:

interface ResponseData {
  success: boolean;
  data: any;
  error?: {
    status: number;
    statusText: string;
    data: { Message?: string };
  };
  requestId: string;
}

Handling responses:

const result = await client.api.query(1, {
  fields: 'accountid,accountname',
  query: 'status = "active"'
});

if (result.success) {
  console.log('Data:', result.data);
} else {
  console.error('Error:', result.error?.data.Message);
}

TypeScript Support

The SDK includes full TypeScript definitions. You can provide generic types for stronger typing:

interface Account {
  accountid: string;
  accountname: string;
  status: string;
}

const client = new FireberryClientSDK<Account>();
await client.initializeContext();

const results = await client.api.query(1, {
  fields: 'accountid,accountname,status',
  query: 'status = "active"'
});

// results.data is typed as Account

Complete Example

A React component that displays and updates data:

import { useEffect, useState } from 'react';
import FireberryClientSDK from '@fireberry/sdk/client';

function TaskList() {
  const [client] = useState(() => new FireberryClientSDK());
  const [tasks, setTasks] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function init() {
      await client.initializeContext();

      const result = await client.api.query(1, {
        fields: 'accountid,accountname,status',
        query: 'status != "completed"'
      });

      if (result.success) {
        setTasks(Array.isArray(result.data) ? result.data : [result.data]);
      }
      setLoading(false);
    }

    init();
  }, [client]);

  const completeTask = async (taskId) => {
    const result = await client.api.update(1, taskId, { status: 'completed' });
    if (result.success) {
      setTasks(tasks.filter(t => t.accountid !== taskId));
    }
  };

  if (loading) return <div>Loading...</div>;

  return (
    <ul>
      {tasks.map(task => (
        <li key={task.accountid}>
          {task.accountname}
          <button onClick={() => completeTask(task.id)}>Complete</button>
        </li>
      ))}
    </ul>
  );
}

Cleanup

When your component unmounts, clean up the SDK:

// Clean up event listeners and pending requests
client.destroy();

In React:

useEffect(() => {
  const client = new FireberryClientSDK();
  // ... setup

  return () => client.destroy();
}, []);

Timeouts

API requests timeout after 60 seconds by default. If a request takes longer, the promise rejects with a timeout error.

Next Steps

Design System — Build UIs with Fireberry components
Component Types — Understand context availability by component type
CLI — Deploy and manage your apps