Build mini-apps for Roomcord

Add a workflow to the room where your team already works. Start from the starter, poll or approvals example, then build an app for your room.

What a mini-app is

A mini-app is a small app that lives inside one Roomcord room. The room keeps the app’s data as records in collections. The app’s functions run in a sandbox on the server and are the only code that changes those records. Room members and the AI agents installed in the room call the functions, and the client shows a generic screen built from the app’s schemas.

Before you start

• Node.js and npm on your machine.
• An account on your company’s Roomcord for Enterprise server.
• The admin role in the room where you publish the app. Only room admins push and approve apps.

Quickstart

This guide uses version 4.1.0 of @fulldivevr/workcord-cli. The command-line tool is named workcord. Every command prints JSON on stdout.

1. Install the CLI.

   npm i -g @fulldivevr/workcord-cli
   

2. Log in. A code arrives by email and the CLI asks for it. If your company runs its own server, ask your administrator for its origin and add --base-url <origin> to this command once. The login saves the server.

   workcord auth login --email [email protected] --save
   

3. Find the id of the room.

   workcord rooms list
   

4. Write a new app folder from the template.

   workcord app init my-app
   

5. Run the server’s checks and the app’s tests on your machine. No server is needed.

   workcord app test my-app
   

6. Save the app as the room’s pending draft. The result has the draftId.

   workcord app push my-app --room <roomId>
   

7. Approve the draft. The app is now installed in that room.

   workcord app drafts --room <roomId>
   workcord app approve <draftId> --room <roomId>
   

8. Call a function.

   workcord app call my-app addEntry --room <roomId> --data '{"title":"Dune"}'
   workcord app describe my-app --room <roomId>
   

Before you push an upgrade, run workcord app validate my-app --room <roomId>. It adds the checks that need the room: the version and the records that exist.

Package format

A package is a folder:

my-app/
  manifest.json      id, version, name, summary, icon, collections, functions
  GUIDE.md           for agents: what the app is for, which function to use when
  functions/
    addEntry.js      one file per function in the manifest
  tests/
    entries.json     one scenario or a list of scenarios

• manifest.json declares the collections, each with a JSON Schema that every write must match, and the functions, each with a description, an input schema and a callers list.
• callers names who may call a function: members, admins or agents. Agents choose a function by its description.
• GUIDE.md tells agents how to use the app.
• tests/ has at least one scenario. The checks run every scenario before a push and again before an approval.

Function shape

A function file has exactly one export default and no other import or export. It receives the event and a context:

export default async (event, ctx) => {
  const { title, notes } = event.data;
  return ctx.db.entries.insert({ title, notes, status: 'open' });
};

• event.data is the input, after the schema check.
• event.caller is the user or agent that made the call. The engine sets it, so app code never authenticates.
• ctx.db.<collection> has get, query, insert, update and delete. Every call returns a promise.
• throw new AppError(code, message) returns that code and message to the caller.

Every write keeps a version of the record, and a delete keeps the record’s history.

Limits

Functions have no network, no file system, no timers and no imports. They cannot call other apps or read other rooms. Agents do that work.

Who can publish

Only room admins push and approve apps. Agents in the room can save a draft, but an admin approves it. An approved app is installed in that room only. Each new version must have a higher version than every version the room approved before.

Examples and the full guide

The public repository fulldiveVR/roomcord-mini-apps has three examples to start from: starter, poll and approvals.

The full guide covers collections, queries, display hints, test scenarios, upgrades and error codes.