The core chapter of the Neblla guide — the SDK's base contract. Mandatory: every other chapter assumes what is here.

# Neblla — core

## What it is

**AI builds it in minutes. Neblla keeps it alive for years.** The backend and back office for your game, your app or your store: users, data, payments, real-time multiplayer rooms, community, AI and a dashboard to run it all.

**You write the app, Neblla handles everything behind it** — the parts that would otherwise need a server of your own: user accounts that work across every Neblla app, saved data, payments, user-published content, friends, AI, a back office and, when more than one device is involved, rooms with a clear authority. Multiplayer is one of those modules, not a requirement. Loaded with one `<script>` tag — no server of your own, no npm, no build.

What it replaces is not writing code, but standing up and maintaining a socket server, authentication, a database and a deployment. If you have not yet decided whether Neblla is the right answer for this app, or what shape to give it, read empezar.txt first. The same server logic carries from prototype to production: your server files run on Fog, spread across the devices in the room, with no server to set up (see servidor.txt). The client SDK loads with that `<script>` tag. To talk to Neblla from a server of yours there are the admin API (below) and `@neblla/server` (see servidor.txt).

## Addresses

- **developers.neblla.com** — create, edit and manage apps (dashboard and back office).
- **play.neblla.com** — the public gallery. Each app lives at `play.neblla.com/<slug>` (the slug is generated from the name when the app is created, and can be renamed at developers.neblla.com). Get the canonical URL with `neblla_get_app_url(appId)` — never build it by hand.
- **neblla.com/mcp** — the MCP server: an AI can create apps, upload files and publish them (see mcp.txt).

The SDK is served from `neblla.com/connect/app/:appId`. That URL never changes, wherever the app itself is hosted. The tag also works without the id, `neblla.com/connect/app.js`: Neblla takes the app from the page's address (its `<app>.neblla.app`, its custom domain or one of its domains), and the templates use it. A page on localhost (it opens the pre, with the local key: `neblla_pre_access`) and a compiled app carry the id. When several apps list the same site among their domains, the page's path decides: the entry with the longest path the page is under wins (`example.com/chess` over `example.com`); on a tie, the page carries the id.

## Connecting

Before any code you have to create the app (at developers.neblla.com or over MCP); that gives you an `APP_ID`. The smallest app:

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>My App</title>
  <script src="https://neblla.com/connect/app/APP_ID"></script>
</head>
<body>
  <script>
    window.onNeblla = (neblla) => {
      console.log("hello");
    };
  </script>
</body>
</html>
```

When the page loads, `onNeblla` runs with the SDK already connected. The script tag does NOT need `type="module"`.

If the SDK cannot start, `onNeblla` does not run and you are told once: define `window.onNebllaError = (detail) => { ... }` or listen for the `neblla:error` DOM event (same `detail`). `detail.code` is `unreachable` (Neblla could not be contacted), `not_found` (this page is no app's: its origin is not in the app's domains), `refused` (the app lets nobody new in right now: `reason` is `quota_exceeded`, `storage_full`, `migrating`, `rate_limited` when this address opened too many pages in a minute or made too many new guests, or `turnstile_failed` when the app asks for Turnstile and the page did not pass it), `auth_failed` (the server refused the connection, with `status`), `timeout` (no session after 15 s; the SDK keeps retrying and `onNeblla` may still arrive) or `sdk_error`. Use it to paint an "offline — retry" instead of a blank screen.

What your code throws and nobody catches reaches your log (the panel: Build › Errors and refusals; your AI: `neblla_get_logs`), with its file and line: an error or a rejected promise on the page (`client.js` and your other files) and what a handler of `lobby.js`, `gathering.js` or `room.js` throws on the room's server peer. It is a sample: at most 10 different errors a minute from each page, and the same one again only adds to its count. Nothing changes for your app: the error still shows in the console as always. Errors of other origins (the browser only says "Script error.") and of browser extensions are not sent.

## The canonical structure — six files

If the app is hosted on Neblla, its public link points at `index.html`. The canonical template is six files; only `index.html` is required, and the rest exist if the app needs them.

Front end (runs in the browser):

- **index.html** — markup. Loads `main.css`, `client.js` and the Neblla SDK.
- **main.css** — styles.
- **client.js** — runs on every connected device. Has access to the DOM. The code goes inside `window.onNeblla = (neblla) => { ... }`.

Server side (isolated logic, no DOM, the `server/` folder):

- **server/lobby.js** — users who are not in a game yet. Matchmaking: collecting "I'm ready", grouping players, booking a room, announcing the match.
- **server/gathering.js** — a room that exists and is waiting to start. Decides *when* the game begins (the common cases are configured without code in the panel, Features › Rooms).
- **server/room.js** — the running room. The room's authority: validates actions, holds state, announces changes.

The contract for this structure:

- `index.html` references `main.css` and `client.js` with `<link>` and `<script>`. It **NEVER references anything under `server/`** — the SDK loads those itself.
- The `server/` files are top-level code: `neblla` is a global, with no `onNeblla` callback.
- The `server/` files do not touch the DOM. Exactly four names are shadowed as `undefined`: `window`, `document`, `globalThis` and `self`. Everything else the runtime offers is there — including `setTimeout` and `setInterval` (see servidor.txt).
- There is no `neblla.auth` and no `neblla.room.me` on the server side. Whatever acts as the user (`auth.login`, `db.data`, `db.setPublicInfo`, `shop.buy`, …) is client-only; on the server, `neblla.db` reads and writes tables (`db.save` / `db.load` / `db.delete` with `table`).
- Files go to the app's **pre**, which the developer tries at a private link; the users get them when it is sent to **pro** (`neblla_promote`, or "Publish changes" in the panel, which calls pre "draft" and pro "the published one"), which publishes them at once: the published link shows them right away. Publishing to the gallery is yet another step (see publicar.txt).
- When these files are present, Neblla activates and deactivates them at the right moment for each room.

## Interface templates (Creator › Templates)

The developer can change the look of one of their apps from Creator › Templates («Change the look» in Build › Look): the template puts its colours, typefaces and shapes on the app's **draft** (`main.css` between the marks `/* neblla-template:start */` and `/* neblla-template:end */`, and a fonts `<link>` in `index.html`), and the developer publishes it or takes it off whenever they want. So that you can keep rewriting `client.js` and `main.css` without breaking it:

- **Declare the ids the code needs**, in one or more lines of `client.js`: `// @neblla-ids newRoomBtn joinRoomBtn roomCodeInput`. A template may move any block but never remove a declared id: if one is missing it is not applied, and it says which. If you add or remove a `getElementById`/`$('x')`, update that line.
- **Name the screens** with `data-screen="<name>"` (or a `<section id>`): if a template has a page with that name it can place it inside the screen ("Also place the screens"); screens with no page stay as they are and you are told.
- **Paint with the `--nb-*` variables** (`--nb-bg`, `--nb-surface`, `--nb-ink`, `--nb-muted`, `--nb-primary`, `--nb-on-primary`, `--nb-secondary`, `--nb-alert`, `--nb-line`, `--nb-radius`, `--nb-font-title`, `--nb-font-body`, `--nb-space`) instead of fixed colours and typefaces: that is how a template recolours the app. If you already use your own names (`--primary`, `--bg`), alias them: `--primary: var(--nb-primary)`.
- **Do not touch what sits between the `neblla-template` marks** in `main.css` or in `index.html`: it belongs to the template and is rewritten whole each time. Your rules go outside, before or after.
- **The template's blocks announce with document events; listen to them if you want to do it yourself.** A form with a table fires `nb:submit` (`detail: { table, data, done(ok) }`), a buy button `nb:buy` and a pay button `nb:pay` (`detail.product`). If you do not listen, the page saves the row with `neblla.db.save(data, { table })` and calls `neblla.shop.buy(product)`. To do it yourself (validate, add data, charge with a quantity or `series`), listen to the event and call `event.preventDefault()` **before** it bubbles up: the page then leaves it in your hands. On the form set `detail.pending = true` and, when done, call `detail.done(true|false)`: it then shows «sent» or «could not be sent» (without `pending` it takes the send as good at once). The table must let visitors write (public write permission in `neblla_update_app`/Config → Tables); otherwise the form will say it could not be sent.
- An `<img>` carries `alt`; the HTML uses meaningful tags (`button`, `nav`, `main`, `h1…h3`) and button text reads in any theme (light and dark, 4.5:1 contrast).

## Images, animations and atlases from Neblla Creator › Flat

What the dev draws in Creator › Flat reaches their app through «Export» → «Send to my app»: it lands in the app's Media, collection `creator`, and each file carries a **note for you** (`neblla_media` returns it as `note`): what it is and how to use it. Read it before using the file; an atlas JSON is of kind `data`. What Flat writes:

- **Pictures** (`PNG`, `PNG-8`, `WebP`, `JPG`, `SVG`): one per size asked for, with the suffix in the name (`button.png`, `button@2x.png`, `button-48.png`). Use them with `<img>` or `background-image`; with both scales, `srcset="button.png 1x, button@2x.png 2x"`. SVG only comes out when everything was vector, with one group per layer and its name as `id`.
- **Animated GIF and WebP**: shown with an `<img>`, they loop on their own.
- **Sprite atlas**: a `PNG` and its `JSON` (sometimes several, `sprites-0.png`, `sprites-1.png`…, when they did not fit one). The JSON comes in one of two formats and says, for each frame, where it is on the sheet (`frame`), how much transparent edge was trimmed (`spriteSourceSize` and `sourceSize`), its pause in milliseconds (`duration`) and its anchor (`pivot` in the TexturePacker format; `meta.slices` `<name>_anchor` in Aseprite's). If the atlas turns tall drawings, those frames carry `rotated: true` (turned a quarter clockwise; `frame.w` and `frame.h` are the sheet's; Phaser and Pixi understand it). Named anchors (a hand, a muzzle) are in `anchors` (`{ name: { x, y } }`, as a share of the drawing) in the TexturePacker format and `meta.slices` `<name>_anchor_<anchor>` in Aseprite's. Buttons with a 9-slice carry their margins in `slice` (`{ l, t, r, b }`) or in `meta.slices` `<name>_9slice`.
  - **TexturePacker «JSON hash»** (Phaser, Pixi): `this.load.atlas('sprites', 'sprites.png', 'sprites.json')` and then `this.add.sprite(x, y, 'sprites', 'walk_00')`. Animation tags are in `meta.tags` (`[{ name, frames: [names], direction }]`): `this.anims.create({ key: tag.name, frames: tag.frames.map(f => ({ key: 'sprites', frame: f })), frameRate: 10 })`.
  - **Aseprite «JSON data»** (Godot, Unity and Flat's engine): `frames` by name, and the tags in `meta.frameTags` (`{ name, from, to, direction }`, indices in the order of `frames`).
  - Each frame's pause is `duration` (ms): use it instead of a fixed `frameRate` when the dev tuned the times.
- **Tileset** (`*-tileset.png` and `*-tileset.tsj`): for Tiled, with tile size, columns, margin and spacing in the `.tsj`.

If the dev sends the atlas a canvas with a repeated name, or a sprite bigger than the atlas, Flat says so and writes nothing: do not make up the file that is missing.

## The client / presenter / server model

- **Client** — every connected device running `client.js`. Has the DOM, `neblla.auth.me` (you in the app) and `neblla.room.me` (you in the room).
- **Presenter** — a client with a distinguished social role (the bingo caller, the shared screen in a Jackbox-style game). It is the first device to enter the room; if it leaves, the SDK promotes another one (NOT by FIFO — Neblla picks it) and fires `neblla.room.on('presenter')`. Read it with `neblla.room.me.isPresenter`, talk to it with `neblla.message.to('presenter', data)`. It is optional: plenty of games never need one. It is a different role from the server: the `server/` files run on the server peer, which may or may not be the same device.
- **Server** — whoever runs the `server/` files: Fog, three devices in the room chosen by Neblla (see servidor.txt). It is the room's authority. Talk to it with `neblla.message.to('server', data)`. **On the client there is no `neblla.server` and no `user.isServer`** — its identity is opaque on purpose: it changes during the game and your code must not depend on it.

Presenter and server are different roles. They can land on the same device by chance; your code must not count on it.

## The events-only contract

CLIENT and SERVER **never call each other directly**. They only communicate through events:

| Sender (method)                          | Receiver (event)                        | Meaning |
|------------------------------------------|-----------------------------------------|---------|
| `message.send(data)` from a client       | `message.on` on everyone, `from`: their id | Broadcast between peers. It reaches you too, with `fromMe: true`. |
| `message.send(data)` from the server     | `message.on` on everyone, `from: 'server'` | The game's authoritative voice, reaching every client. |
| `message.to(userId, data)`               | `message.on` on that member only        | Private to one member of the room, from a client or from the server. Arrives with `private: true`. Not broadcast. |
| `message.to('server', data)` (client)    | `message.on` on the server, `to: 'server'` | Private to the server. Arrives at `room.js` / `gathering.js` / `lobby.js` depending on the phase. Not broadcast. |
| `message.to('presenter', data)` (client) | `message.on` on the presenter, `to: 'presenter'` | Private to the client whose `isPresenter === true`. Not broadcast. |
| `state.set(state)` (server)              | `state.on` on everyone                  | Authoritative, public state. Updates `neblla.state.get()` everywhere. Travels P2P. Secrets go in a No-code envelope. |

A message reaches `neblla.message.on(cb)` as `{ from, to, data, user, time }`: `from` is the sender's id or `'server'`; `to` is `null` (the whole room), an id, `'server'` or `'presenter'`. Messages are open JSON and ephemeral: use the server to re-send state to newcomers. Each module listens to its own events and lets go with `.off`: `neblla.message.on(cb)` / `neblla.message.off(cb)`, `neblla.state.on(cb)`, `neblla.room.on('userJoined', cb)` / `neblla.room.off('userJoined', cb)`… There is no `on` at the root of `neblla` and no `'*'` wildcard: an event name the module does not have throws `unknown_event`.

## A room's lifecycle

1. **lobby** — every connected user lands in the special `lobby` room. For matchmaking, picking a name, browsing rooms — not for playing. Its events carry an `isLobby` boolean.
2. **gathering** — `neblla.rooms.book({ config? })` books a room with a unique id (the server picks it, never the client). It is born in the `gathering` state, visible from the lobby through `neblla.rooms.gathering`. Users enter with `neblla.rooms.join(roomId)`.
3. **running** — the room is started by `neblla.room.start()`. From a client **only the presenter may call it**; `server/gathering.js` may also call it to start the room on its own. Nobody else can. The SDK picks the server and starts `server/room.js`. From then on `message.to('server', …)`, the server's messages (`from: 'server'`) and `state.set` work.

`neblla.room.leave()` returns to the lobby. A user can only be in one room at a time. The same room name means the same group. Full detail in salas.txt.

## App shapes

Decide the shape BEFORE you write code. An app with rooms is born with one example: the server sets the state, the clients paint it and talk through `message`. The three room shapes below are recipes, with the server's and the clients' code, in salas.txt ("Recipes: three shapes of room"). Without rooms, the app is lobby-only or solo + save. To choose: is it multi-user? is there an authority (a server that validates)? does that authority show a different screen? and, if it is multi-user without an authority, separate rooms or one shared space?

| Shape            | Authority     | Two UIs | Multi | Rooms | Examples |
|------------------|---------------|---------|-------|-------|----------|
| Referee          | Yes (server)  | No      | Yes   | Yes   | Chess, UNO, connect 4, battleship |
| Screen + phones  | Yes (server)  | Yes     | Yes   | Yes   | Kahoot, Jeopardy, Pictionary, Werewolf |
| All at once      | No            | No      | Yes   | Yes   | Shared whiteboard, canvas, watch party |
| Lobby-only       | No            | No      | Yes   | No    | Global wall, pixel canvas, live cursors |
| Solo + save      | —             | —       | No    | No    | Habits, sudoku, a journal |

- **Referee and Screen + phones** (recipes): the authority lives in `room.js`. With a screen and phones, `client.js` branches on who holds the host screen. `if (neblla.room.me?.isPresenter)` is only correct while no `board` role is pinned; the branch that survives a pinned board and a lost presenter is `neblla.room.me?.isBoard || (!neblla.room.board && neblla.room.me?.isPresenter && !isLobby)` — see empezar.txt.
- **All at once** (recipe): `room.js` is empty. Separate rooms, each one a shared surface. Every peer is equal: `neblla.message.send` your changes, apply the incoming ones in `neblla.message.on`. Last-write-wins unless you bring your own CRDT. **And the document itself is better kept out of the room**: `room.data` starts with a 10 KB anti-abuse limit (you change it or turn it off), but what several people edit lives better in community entries (one entry per person so there is no write conflict) and only the notice that something changed travels through the room. The full recipe is in comunidad.txt, "A shared store bigger than a room".
- **Lobby-only**: like "all at once" but with NO rooms — everyone shares the single global lobby. No `rooms.join` / `rooms.book` / `room.start`, no `gathering` and no `room.js`: just presence (`room.on('userJoined')` / `room.on('userLeft')`) plus peer-to-peer `message.send`. The only server file is `server/lobby.js`, and it is optional, for keeping a canonical snapshot to hand to latecomers. Choose this over collab when everyone goes to ONE shared space and there is no need to separate groups.
- **Solo + save**: no rooms, no messages. Just `neblla.db.save()` and `neblla.db.data`.

You can mix these, or invent your own.

## The smallest working app pattern

Authoritative logic — the client asks, `room.js` validates and announces:

```javascript
// client.js — ask for an action:
neblla.message.to('server', { action: 'play-card', card: 5 });

// room.js — validate and announce state:
let gameState = neblla.state.get() || initialState();

neblla.message.on(m => {
  if (m.to !== 'server') return;   // the server also hears what is broadcast to the room
  gameState = applyAction(gameState, m.from, m.data);
  neblla.state.set(gameState);
});

// client.js — react:
neblla.state.on(state => render(state));
```

Multiplex messages with a `type` field:

```javascript
neblla.message.send({ type: 'state-update', state });

neblla.message.on(m => {
  switch (m.data.type) {
    case 'chat': handleChat(m); break;
    case 'state-update': handleState(m); break;
  }
});
```

## Keys: values you set and the app reads live

To change something without touching code —an active event, a weekend points multiplier, today's challenge, a message of the day— the developer sets **keys** in the panel (Build › Advanced › Keys and secrets) or with `neblla_update_app({ keys: { todays_challenge: 42 } })`, and the app reads them with `await neblla.api.key('todays_challenge')`. It always returns the current value. They are text, a number, yes/no or a JSON, and they are **public**: anyone who opens the app can read them, so never put a secret in a key.

## Connecting to other services, without a server of yours

**Calling an API with your secret: `api.call`.** Save the secret once with `neblla_set_api_secret`: a name (`CLOUDINARY`), the value (written and never read back), the only base URL it may call (`https://…`) and where the secret goes, with `{secret}` in a header or in the query (`{ "Authorization": "Bearer {secret}" }`). The app uses it like this:

```javascript
const r = await neblla.api.call('CLOUDINARY', '/image/upload', { file, upload_preset: 'x' });   // → { status, contentType, body }
```

From `server/` it always works; from a user's client, only with `fromClient: true`.

**Emailing with your own provider.** Neblla does not send emails on your behalf: you send them with your Resend, Postmark or whatever account. Save its key as a secret (`RESEND`, base URL `https://api.resend.com`, header `Authorization: Bearer {secret}`) and call its API when needed, with the email you received at login with the `email` scope:

```javascript
await neblla.api.call('RESEND', '/emails', {
  from: 'My game <hello@mygame.com>', to: email,
  subject: 'Your turn', html: '<p>Your opponent has moved.</p>',
});
``` To protect your bill: `limits` per user (minute, hour, six hours, day, week, month), per app (day, month) and `loggedInOnly`. The bytes both ways count as quota.

**Neblla tells you: outgoing webhooks.** `neblla_update_app({ webhooks: [{ event: 'purchase', secret: 'N8N', path: '/purchase' }] })`: when the event happens, Neblla POSTs `{ event, appId, at, data }` to that secret's URL (your n8n, for instance). Events: `purchase` (also every renewal of a subscription), `refund`, `subscription_end` (a subscription ends), `register` (a new user), `erasure_request`, `ban` (you ban a user or lift it: `{ userId, status }`), `flag` (a room is flagged, or you flag a user by hand: `{ room, reason, users, by }`), `community_report` (an entry is reported: `{ entryId, reason, reports, suspended }`, without saying who reported it) and `booking` (a user books a place, or the place they paid for at booking is confirmed: `{ userId, bookingId, set, slotId, start, title }`, plus `cost` and `creditKind` when it took credits, or `paid` and `purchaseId` when it was paid). Users go by their id in your app. The latest deliveries, with `neblla_list_webhook_deliveries`.

**Another service tells your app: incoming webhooks.** `neblla_create_hook({ name, to: 'room', room })` gives a URL (with a token shown only when it is made) where a third party —Twitch, a payment provider, n8n— sends a JSON. Neblla hands it to that room, whose server hears it with `neblla.room.on('hook', ({ name, data }) => …)`, or with `to: 'user'` to the user the call names (`?user=<their id in your app>`). With `to: 'inbox'` each call stays as a notice in your Inbox (People › Inbox), even when nobody is connected: an order from your shop elsewhere, a Tally form, an n8n alert. It shows the hook's name as sender, a readable line (the JSON's `message`, `text` or `title`, or its first values) and the whole JSON below; it cannot be answered, and once the Inbox cap per sender is reached the oldest notice goes. To see an event of your own app there (a purchase, a refund), make a secret with that URL as its address and point an outgoing webhook at it. Up to 64 KB per call.

**Scheduled tasks: Automations.** `neblla_set_automation({ name, when, action })` does something at a time or every so often, without a server of yours. `when`: `{ at: date }` once, `{ every: minutes }` (5 to 10,080) or `{ daily: 'HH:MM', days?, tz? }`. Actions: `openRoom` (books a room with its config: the boss room opens at 11:00), `message` (hands data to a live room, whose server hears it with `neblla.room.on('hook')`) and `callApi` (calls an API with one of your secrets: the evening reminder through Resend, your n8n…). Up to 50 per app; `neblla_list_automations`, `neblla_run_automation` to try it now and `neblla_delete_automation`. Automations are shortcuts for the small things that live inside your app. A flow across services —your CRM, a spreadsheet, Slack, several steps with conditions— belongs in your n8n, Make or Zapier: Neblla tells them with outgoing webhooks, listens to them with incoming hooks, and your flow acts on the app through the admin API.

**Business templates, no code.** For what repeats across many apps, Neblla brings ready-made actions, atomic and run on Neblla, that you only configure. They are a starting point: if the business already has its own tool, it connects the same way as your n8n.

- **Bookings and credits.** Configure them once: `neblla_update_app({ business: { booking: { classes: { cancelHours: 12, cost: 1, creditKind: 'pass' } }, credits: { pass: { products: { pack10: 10 } } } } })`: each "classes" booking spends 1 credit, cancelling more than 12 hours ahead gives it back, and buying the `pack10` product tops up 10. If the product is a subscription, it tops up every paid period (not the free trial); `{ pack10: { n: 20, mode: 'fill' } }` fills the balance up to 20 instead of adding («every month you have 20 classes again», what is left does not pile up; a balance above it stays). A kind with `unlocks: ['agua']` (media collection keys, or `'*'`) also unlocks one private original of those collections per credit, for good (pagos.txt, "Files for sale"). A full refund or a lost dispute takes that purchase's credits back; the ones already spent do not come back (the balance stops at zero and the `refund` webhook carries `credits: { kind, taken, short }`). Nobody goes over capacity even if they book at the same moment. From the client (signed in):
  ```javascript
  const slots = await neblla.business.booking.slots('classes', { from, to });  // with `left`, the free places; never who booked
  const { booking, left } = await neblla.business.booking.reserve('classes', slotId);
  const { cancelled, refunded } = await neblla.business.booking.cancel('classes', slotId);
  const mine = await neblla.business.booking.mine('classes');                  // with the slot's start, end and title
  const { balance } = await neblla.business.credits.balance('pass');
  ```
  Errors: `login_required`, `slot_full`, `already_booked`, `slot_past`, `not_enough_credits`, `booking_not_found`, `unknown_booking_set`.
- **Paying each booking at booking, no credits.** `{ appointments: { cancelHours: 24, pay: 'booking', product: 'visit' } }`, with `visit` a one-time product that gives no credits (if a credit kind uses it, `invalid_business`). `reserve` holds the place for 35 minutes and opens Stripe's checkout in a window: it returns `{ booking, held: true, holdUntil, url }`, and the place is the user's when the payment arrives, which `neblla.business.booking.on('update', ({ set, booking }) => …)` reports with `booking.status` `'reserved'` (or `'cancelled'` with `reason: 'full'` if they paid late and no place was left, or `reason: 'cancelled'` if they had cancelled before the payment came: the money goes back on its own; and `reason: 'refunded'` when it is refunded in Stripe, or `reason: 'slot_gone'` if its slot is deleted, or `reason: 'cancelled_by_app'` if the app cancels the booking). Booking again while paying, or once their time ran out, is the same booking. Cancelling in time refunds the money in Stripe, Neblla's fee included, and a refund made in Stripe cancels the booking. Its own errors: `booking_product_missing` (the set has no product), `invalid_booking_product` (a subscription cannot pay a booking), `checkout_failed`, and `popup_blocked` with `url` if the browser blocked the window (open it yourself from a click). To show the price before booking, `services()` brings `price` on that service (`{ amount, currency }`, in cents: «€7.00»), also when the product is not in the shop.
- **Automations with a template:** `neblla_set_automation({ name, when, template, … })`.
  - `booking.reminder` `{ set, secret, path?, hoursAhead? }` (24 h by default): for each booking starting soon, and only once, Neblla sends `{ event, set, player: { id, name, email }, slot, booking }` to that secret's URL (the email only if the user gave it to your app). That URL is your n8n, Make or your server, and the email goes out from there with your Resend or whatever you use: Neblla gives the timely nudge and your flow writes and sends the message.
  - `community.digest` `{ days?, limit?, secret and/or room }`: the best-rated entries of the period (7 days and 10 by default).
  - `game.dailyTournament` `{ board, day?, top?, secret and/or room }`: the day's top of a protected ranking (`neblla.scores`, which no player writes; see identidad.txt), stored and sent as `{ event, board, day, ranking: [{ place, player, value, at, info? }] }`; `day` is `'today'` (UTC, the default) or `'yesterday'`. Or `{ table, field, top?, hours?, secret and/or room }`: the leaderboard of one of your tables for the period (its rows are written by the players), sent as `{ event, table, field, ranking: [{ place, player, value, row }] }`.

The data is your app's (in your database if you have BYODB): table names starting with `nb_` are reserved for this.

**Administration is not in the SDK.** Creating and deleting slots, seeing who booked, moving or cancelling someone else's booking, adjusting credits by hand, querying any table: that goes through the MCP (`neblla_booking` with `createSlot` (`{ set, start, end?, capacity, title?, repeat?, site?, staff?, resource?, min? }`; the site, the teacher and the room, below; `repeat`, too), `updateSlot`, `deleteSlot` —it gives credits back—, `series`, `slots`, `list`, `cancel`, `move`, `cancelSession`, `times`; `neblla_business` with the sites, resources, professionals and accounts; `neblla_credits` with `balance` and `adjust`), through the **admin API** (`POST /api/apps/<appId>/admin/<tool>/<op>`, e.g. `/admin/booking/list` or `/admin/credits/adjust`, with the same body) (with `Authorization: Bearer` and the server key; for example `POST https://neblla.com/api/apps/<appId>/tables/<table>/query` with `{ where, orderBy, limit, offset, owner, count }`, `POST …/tables/<table>/rows` with `{ owner, data }` to create or `{ id, data }` to replace, and `DELETE …/tables/<table>/rows/<id>`, these two if the table has `server: 'write'`), webhooks, Automations, the **back-office panels** and the developer panel itself, which does what those tools do with the same functions: the Business tab (the agenda as a week calendar, who is coming and each client's credits, the accounts, and the services, professionals, resources and sites; the passes, in Money › Products), Features › Data (the tables' fields and their rows), Features › Scores and rankings (the rankings of `neblla.scores`), People › User groups, each user's card (use a purchase, credits, groups), Build › Webhooks and Keys and secrets, Money › Plan and usage and Payouts (taxes), Publish › Stores and Settings › Your own login (JWT providers). What is not simple (a new table, a custom screen, an automation) the panel leaves as a sentence ready to ask your AI.

**Slots that repeat, as in a calendar.** `repeat` is a repetition rule like any calendar's (the usual part of iCalendar's RRULE, RFC 5545), the same for classes, appointments, matches, tournaments or shifts:

```javascript
// Yoga on Tuesdays and Thursdays at 18:00 Madrid time, until June, without the Thursday of Christmas
neblla_booking({ appId, action: 'createSlot', set: 'classes', title: 'Yoga', capacity: 12,
  start: '2026-10-20T18:00:00+02:00', end: '2026-10-20T19:00:00+02:00',
  repeat: { freq: 'weekly', byDay: ['TU', 'TH'], until: '2027-06-30', except: ['2026-12-24'], timeZone: 'Europe/Madrid' } })
// The tournament, on the last Friday of every month, 10 times
repeat: { freq: 'monthly', byDay: '-1FR', count: 10 }   // or the string 'FREQ=MONTHLY;BYDAY=-1FR;COUNT=10'
```

- `freq`: `'daily'`, `'weekly'`, `'monthly'` or `'yearly'`; `interval`: every how many (`2` with `'weekly'`, every other week; up to 1000).
- `byDay`: the days of the week (`'MO'`…`'SU'`); in a month (or a year), with a number before: `'2TU'` is the second Tuesday and `'-1FR'` the last Friday. `byMonthDay`: a fixed day of the month (`15`; `-1` is the last one). `byMonth`: the months (1–12). `wkst`: the day the week starts on (`'MO'` by default), which counts with an `interval` above 1 in `'weekly'`.
- `until` (a date is that whole day) or `count` (so many times, up to 10,000); with neither, it does not end. `except`: the dates skipped (up to 500).
- `timeZone` (IANA, e.g. `'Europe/Madrid'`): the local hour stays when the clocks change. Without it, the zone of its site (or of its `hours`), then of its professional's `hours`; with none, UTC. This holds for a rule given as an RRULE string too.
- The cases are the days the rule gives from `start` on, at `start`'s time (if `start` does not fall on the rule, that day is not a case). Each case is a slot, and those of one series share a `series` id (and `occurrence`, the time the rule gave it). Neblla makes a year of cases (counted from now, or from the first one if it starts later) and the following ones as time goes by: when the set's slots are read (by players, a panel, the admin API or the reminders), at most once an hour, so there is no cap of cases and a series without an end never stops. If one fails when making it, none is made. `createSlot` answers `{ slot, slots, series }`; `series` `{ set, series }` gives back the rule (also as `rrule`) and how far its slots go (`ahead`, or `ended: true`).
- Changing and deleting, as in a calendar: `updateSlot` `{ set, slot, scope?, start?, end?, capacity?, title?, repeat? }` and `deleteSlot` `{ set, slot, scope? }`, with `scope` `'one'` (the default: that case alone; a moved one stays in its series and a deleted one becomes an exception), `'following'` (this one and the next) or `'all'` (every one not started yet; past ones stay as history). A new `start` moves every case as much as this one (the same days, at the new time); a new `repeat` gives them anew: a case whose day stays keeps its slot and its bookings, the one of a day that goes is deleted and whoever had a place gets their credits or money back, and a new day brings a new slot. A slot that goes (with `deleteSlot` or because its day goes) cancels its bookings, and the player hears it on `neblla.business.booking.on('update')` with `status: 'cancelled'` and `reason: 'slot_gone'`. With fewer places than bookings nobody loses theirs: the slot just takes no more. If earlier cases are still to come, "this and following" with another time or rule moves the following ones to a new series and the old one ends there. `updateSlot` also changes a lone slot. A weekly series made before there were rules has no rule: its titles and places change, but not its time or its rule (`invalid_slot` with `field: 'repeat'`); change its cases one by one, or delete it and make it again.
- `repeat: { weekly: true, until, timeZone? }` still works: it is `{ freq: 'weekly', until, timeZone }`.

**A whole business: sites, resources and professionals.** The same system serves a yoga teacher in several centres, a centre with rooms, a dog groomer, a language school, a restaurant, a car park or a padel court. Each set of bookings is a **service**, and Neblla checks what it uses:

- `neblla_business` keeps the pieces, each with optional `hours`: **sites** (`kind: 'sites'`, `{ name, timeZone?, address?, hours? }`), **resources** (`'resources'`, a group of identical units: `{ name, site?, count, capacity, hours? }`, e.g. "Terrace table", `count: 12`, `capacity: 2`; "Big room", `count: 1`, `capacity: 15`) and **professionals** (`'staff'`, `{ name, email?, sites?, hours? }`). Actions `list`, `save` (with an `id`, it changes only what you send) and `remove` (`in_use` while a session to come or a service uses it).
- `hours`: `{ timeZone?, week: { MO: ['09:00-14:00', '16:00-20:00'], … }, closed?: ['2026-12-25'] }`; a day left out is closed; without `hours`, always open. A professional's range can say where they are: `{ from: '17:00', to: '21:00', site: 'centro' }` (the teacher who teaches in several centres).
- The service says what it needs: `{ name?, minutes?, min?, max?, confirmHours?, remindHours?, remindText?, chat?, recoverStanding?, resources?: [ids], staff?: true | [ids], steps?: [{ minutes, resources, staff? }], book? }`. `steps` run in a row for the same client (the groomer: `[{ minutes: 30, resources: ['bath'] }, { minutes: 45, resources: ['table'] }]`, with one bath and two tables).
- `book: 'sessions'` (the default): the business opens the sessions with `createSlot`, which now takes `site`, `staff`, `resource` and `min`. The session must fit the hours of its site, its professional and its resource, the professional cannot be in another one at the same time and the resource must have a unit free; if not, `busy` with `what` (`site_hours`, `staff_hours`, `staff_site`, `staff_busy`, `resource_hours`, `resource_full`) and `id`. A series is checked case by case: all of them fit, or `busy` with `conflicts`; with `skipBusy: true` those dates are left out. Without `end`, it lasts the service's `minutes`; without `capacity`, its `max` or what fits in the resource.
- `book: 'times'`: the client picks a free time and the session is theirs alone (the groomer, a table, a parking space). `book: 'open'`: they pick a free time and others join until it is full (padel). `neblla_booking` `times` `{ set, from?, to?, site?, staff?, step? }` gives the free times: a professional free and in their hours, and a free unit of each resource.
- **Minimum.** With `min`, the session is `'proposed'` until it has that many people and `'confirmed'` once it has them. `confirmHours` hours before it starts (12 by default with a minimum) it is decided: with the minimum it stays confirmed for good; without it, it is cancelled on its own, everyone gets their credits or money back and hears it on `on('update')` with `reason: 'below_min'`. A session opened when its deadline had already passed (at 18:00 a match for 20:00 with a 6-hour deadline, or one already started) has no deadline: it is not cancelled on its own and goes ahead with whoever comes; the same if it is moved or reopened inside its deadline. `confirmBy` is then `null`. `slots` says it for each slot: `state`, `min` and `confirmBy`, and the names of its site, professional and resource (`siteName`, `staffName`, `resourceName`). `cancelSession` `{ set, slot, reason? }` cancels a whole session (the teacher is ill): everyone gets theirs back (`reason: 'session_cancelled'`) and the session stays in the agenda as cancelled.
- **Reminder in the inbox.** With `remindHours` on the service (1 to 336; e.g. `24`), each booking gets, that many hours before and only once, a message from the business in the client's inbox (`neblla.inbox`, the same channel as your messages), in their language and with their name: "Hi Marta! Reminder: Yoga with Ana, tomorrow at 08:00 PM (Room 1). If you can't make it, cancel it in the app.". The time is in the zone of the site or of the series (with neither, in UTC, and it says so). With `remindText` the text is yours, with `{name}`, `{service}`, `{day}`, `{time}`, `{staff}`, `{site}` and `{for}`. The message carries `data: { type: 'booking.reminder', set, slot, booking, start }`, for the app to show it its way. A booking made when its reminder time had already passed is not reminded (it was just booked). To send it yourself by email, the `booking.reminder` automation template (above).
- **The client's card.** `neblla_business` `userBookings` `{ user }` gives all their bookings, of any service: `upcoming` (soonest first) and `past` (latest first, 50 at most), each with its service, time, place and status. `userNotes` `{ user }`, `userNote` `{ user, text }` and `removeUserNote` `{ id }` are the business's private notes about them ("knee injury: no inversions"): the client never sees them, they keep who in the team wrote them (`by`) and they go when the client is erased. In the panel, People › each user's card shows it, and the name on each booking in the Agenda and in Bookings opens that card. A Professional sees the bookings of their own sessions, reads and writes notes, and removes only their own.
- **Each session's chat.** With `chat: true` on the service, each session has its private chat with whoever has a place in it: booking puts the client in and cancelling takes them out (if inside, back to the lobby). It is a private room of your rooms (`rooms`, `room` and `message` on): `reserve`, `mine` and `slots` (in their own) bring `room`, and the app enters with `neblla.rooms.join(room)`, reads the history with `neblla.room.history()` and writes with `neblla.message.send({ text })`; as they follow it, a message written while they are away reaches them as a notice. Nobody invites, kicks or leaves by hand (`business_room`): its list is the bookings. The business reads and writes in it from the panel's Agenda, or with `neblla_booking` `chat` `{ set, slot, before?, limit? }` (newest first; each message with `from: 'business'`, or with the client's `user` and `name`) and `chatPost` `{ set, slot, text, scope? }`: those inside hear it in `neblla.message.on` with `m.from === 'business'` and `m.data` `{ text, from: 'business', name }` (in the history, `from: 'business'` and `body`) (the professional's name, or the app's). A Professional, in their own sessions. The room never expires for inactivity and goes with its session. The business can write before anyone books (a notice: «Don't forget your mats on Wednesday»): whoever books reads it in the history; with `scope` `"following"` or `"all"` it goes in those cases of the repetition (the ones that exist, a year ahead).
- **Fixed place.** `business.standing: { mondayPass: { set: 'yoga', series } }` (`series`, the id of a repetition of the service: `neblla_booking` `series` `{ set }` lists them) makes the product `mondayPass` a fixed place: buying it books the client in every case of that series in the period paid, spending no credits. A one-time product covers what is left of the calendar month (in the series' zone); a subscription, each paid period, and each renewal books the next one. A case already full is left out, and the client hears it in `on('update', ({ set, standing }) => …)` with `standing: { productId, series, until, booked: [{ slot, start, booking }], skipped: [{ slot, start, reason: 'slot_full' }] }`; one they already had stays as it was. Cancelling a case frees the place and gives nothing back; booking it again within the period is free. A refund of the purchase cancels the cases to come. `mine` and `slots` mark `standing: productId` on what came from it, `neblla.business.booking.standing(set?)` gives their running fixed places (`[{ productId, set, series, title, until, choices?, next? }]`) and `services()` brings `standing` with what is on sale (`[{ productId, set, series: [ids], choices: [{ series, title, start, rrule, timeZone }] }]`). In the panel, Money › Products › Fixed places. The product cannot give credits or pay a booking (`invalid_business`).
- **A fixed place with several timetables.** `series` is also a list: `{ twiceAWeek: { set: 'yoga', series: [monWed, tueThu, evenings] } }` is **one product** (what Stripe charges) with several timetables to choose from: "2 classes a week, €55" at three times, a gym's mornings or evenings, a car park's morning pass. One id alone is a list of one and works as always. When buying, the client chooses: `neblla.shop.buy(productId, 1, { series })`; with no choice and none made before, the purchase is refused with `series_required` and `choices`. The choice is kept in Neblla, not in Stripe, and each period bought or renewed books the timetable chosen. The client changes it with no payment: `neblla.business.booking.changeStanding(productId, series, { when })` with `when: 'next'` (from the next period; this one stays as it is) or `'now'` (the default: from now, if there is a place in **every** case left of the period; if not, `series_full` with `full: [{ slot, start }]` and nothing changes). From now, it books the new cases, cancels those of the timetable before and says so in `on('update')` with `standing: { …, booked, cancelled }`. The business can make the change for the client with `neblla_booking` `changeStanding { set, user, productId, series, when? }`. In the panel, each fixed place has checkboxes, one per timetable.
- **The client changes a single day.** A service with `moveHours` (hours) lets the client move a booking of theirs to another session of the same service with a place, paying nothing, up to that many hours before the one they leave: `neblla.business.booking.move(set, slotId, toSlotId, { for })` → `{ moved, booking }` ("Friday for Saturday that week"; the same for a booking paid with credits or at booking, which keeps what it cost). A fixed place's case only moves within its period (`outside_period` with `until`), and the day it leaves is no longer theirs for free (booking it is an ordinary booking). Refusals: `move_not_allowed` (the service has no `moveHours`; then only the business moves, with `neblla_booking` `move`), `too_late_to_move` (with `moveHours`), `slot_full`, `already_booked`, `slot_cancelled`, `slot_past`. In the panel, the service says "The client changes session up to (hours before)".
- **Closed days.** `neblla_business` `close` `{ kind?: 'sites' | 'resources' | 'staff' (without it, the whole business), id?, from, to?, reason?, timeZone? }` closes a day or a stretch: "the site is closed on 29 October" (`{ kind: 'sites', id: 'centro', from: '2026-10-29', reason: 'Holiday' }`), "the big room under repair from the 3rd to the 7th", "Marc is away on Friday", the groomer's week off, a floor of the car park, a game server's maintenance. `from` and `to` are dates (that whole day, `to` the last one closed) in the place's zone (or `timeZone`; else UTC), or ISO instants. Every session it reaches that has not started is cancelled by itself, as the business cancelling it: what was paid with credits or at booking comes back; a fixed place's case does not (the fee is the same), unless the service has `recoverStanding: true`, which gives it back as a credit (the school that gives the class). Each client hears it on `on('update')` with `reason: 'closed'`, `note` (the reason), `refunded` (whether they get the class back) and `standing`. The cases of a repetition made later on those dates are born cancelled, and opening, moving or booking at a free time a session there answers `busy` with `what: 'closed'`. `closures` `{ from?, to? }` lists them; `reopen` `{ closure }` takes one away and the sessions nobody had booked come back (those with people stay cancelled: they already got back what was theirs). In the app, `slots` also brings the cancelled sessions (`state: 'cancelled'`, with `reason`, "Holiday"), and to whoever had a place, `wasBooked` and `refunded`; `neblla.business.booking.closures({ from, to })` gives the closures (`[{ id, start, end, reason, of?, site? | resource? | staff?, name? }]`) to paint the whole day as a holiday. In the panel, Business › Agenda › Closed days.
- **Accounts.** `neblla_business` `accounts` `{ from?, to? }` (this month by default): per professional, site and resource, how many sessions, minutes and people, to pay them outside Neblla (the school that pays its teachers). `note` `{ who: 'staff:<id>' | 'site:<id>' | a name, amount (cents: what the business owes; negative, what it paid), date?, note? }` writes it down by hand (the teacher who pays each centre a different amount), and `accounts` brings the notes with their total per `who`.
- All of this is administration: the MCP, the admin API (`/admin/business/<op>`) and the panel. What the client does goes in the app's SDK, and only for themselves (or for whom they book): they neither make services nor touch anyone else's agenda.
- **From the app (signed in).** The client sees what the business offers, the free times, and books:
  ```javascript
  const { services, sites, staff } = await neblla.business.booking.services();  // each service: id, name, book, minutes, min, max, cost, pay, remindHours, chat…; sites and professionals by name (never their email or hours)
  const free = await neblla.business.booking.times('full_groom', { from, to, staff: 'luis' });  // [{ start, end, site? }], for 'times' and 'open'
  const r = await neblla.business.booking.reserveAt('full_groom', { start: free[0].start });  // a session made for them, with what is free; r.slot is the session
  await neblla.business.booking.reserve('yoga', slotId, { for: 'Lucía' });          // a place for someone else (the mother books for her daughter); cancel(set, slotId, { for: 'Lucía' })
  await neblla.business.booking.reserveAt('table', { start, party: 4 });            // several places at once: a table for 4
  ```
  Padel (`book: 'open'`): whoever picks a time with `reserveAt` makes their match, and the others see it in `slots('padel')` and join with `reserve`; with `min: 4`, it is confirmed on reaching 4 or cancelled by itself at `confirmHours`. Own errors: `time_taken` (that time is no longer free), `invalid_party`, `already_booked`, and `invalid_args` with `field` in `times` (a month at most).
- **Businesses that sign up from the app.** An app with many businesses inside (the clubs of a padel app, a network of coworkings, teachers who join a platform of classes) opens its form with `neblla_update_app({ business: { apply: { fields: [{ key: 'courts', label: 'How many courts?', type: 'number', required: true }], group: 'managers' } } })` (`type`: `'text'`, `'number'` or `'boolean'`; `group`, the id of a group of the team whose rights each new business's team copies; without it, Business to write; `apply: true` opens it with no questions of its own). A user with a session asks from the app:
  ```javascript
  const { application } = await neblla.business.apply({ name: 'Club Pádel Centro', address: 'Calle de Atocha 120, Madrid', timeZone: 'Europe/Madrid',
    phone: '+34 600 000 000', about: 'Four indoor courts', photo: 'https://…/club.jpg', fields: { courts: 4 } });  // application.status === 'pending'
  const mine = await neblla.business.applications();   // [{ id, status: 'pending' | 'approved' (with site) | 'rejected' (with reason), name, at, … }], newest first
  neblla.business.on('update', ({ application }) => paint(application));   // approved or rejected
  ```
  The application waits (`pending`; one at a time per user: `application_pending` with its `id`) and the developer gets the webhook `business_application` (`{ userId, application, name, address, timeZone }`) and an alert in the panel. They see it in Business › Applications or with `neblla_business` `applications` `{ status? }` (`'pending'` by default, `'approved'`, `'rejected'`, `'all'`; the oldest first, with the name and email of whoever asked). `approve` `{ application }` (the app's owner only: it lets someone into the team) makes the site with what they wrote (its `id` from the name), a group of the team limited to that site with the template's rights, and puts the applicant in that group with the same Neblla account they signed in to the app with: it reaches them as an invitation of the team, accepted in developers.neblla.com › My apps. Someone already in the team (their second club) keeps their groups and adds the new one. `reject` `{ application, reason? }` deletes nothing: they read the reason and can apply again. Errors: `applications_closed` (the app has no `business.apply`), `invalid_application` with `field`, `login_required`, `applicant_without_account`. Sites also keep `phone`, `about`, `photo` (https) and `fields`, and `services()` brings them to paint the list of clubs.
- **Results of matches.** A service with `results: { teams: 2, reportHours: 48, board?: 'level', cheater?: 'block' | 'ban', cheaterHint?: { lost: 3, ratio: 0.3 } }` makes each session already played a match between side `'A'` and side `'B'`: padel, a club's chess league, an amateur tournament of a game. Booking puts each player on a side (`reserve(set, slot, { team: 'A' })`, or the one with fewer; each side has half the places: `team_full`, `invalid_team`), and `slots` brings `teams: { A, B }` with how many are on each. Once the match ended, each player says who won:
  ```javascript
  const m = await neblla.business.matches.report(matchId, { winner: 'A', score: '6-3 4-6 7-5' });  // winner: 'A' | 'B' | 'draw'
  // m: { match, set, start, state, deadline, teams: { A: [userId], B: [userId] }, team, reported, winner?, score? }
  const mine = await neblla.business.matches.mine();          // their matches already played, newest first, with their state
  neblla.business.matches.on('update', (m) => paint(m));      // someone said it, it was agreed, disputed, settled by the developer (resolution.reason 'cheater' when a cheater lost theirs)
  ```
  `matches` lives in `neblla.business`, like `booking` and `credits` (the SDK root holds only modules: there is no `neblla.matches`). The states: `open` (a side has not said it yet; a player can change theirs), `agreed` (everyone who said it agrees and both sides said it: it counts), `disputed` (someone said otherwise: it does not count until the developer decides), `resolved` (the developer decided), `none` (the `reportHours` passed with nothing said: no result) and `annulled`. When the time runs out, what was said with no disagreement counts. Errors: `match_not_played`, `not_in_match`, `invalid_result` with `field`, `match_decided`, `report_closed` (with `deadline`), `match_cancelled`, `cheater_blocked`. A result that counts moves the service's ELO board (`board`, see identidad.txt). A dispute reaches the developer as the webhook `match_disputed` (`{ match, set, start, reports: [{ userId, team, winner, score? }] }`) and an alert in the panel, and waits in People › Disputes (the oldest first, with what each said, the session's chat and each player's history of disputes) or in `neblla_matches` `disputes`. They decide it with `resolve` `{ match, winner, note? }` (also one nobody agreed on; it counts from then and moves the board then; whoever said otherwise counts one more dispute lost) or annul it with `annul` `{ match, note? }` (it stops counting and the board is counted again without it). The games of a room can be matches too: see «Results in rooms».
- **Results in rooms.** The games played in a Neblla room (online chess, a duel, a 2 against 2) are matches with the same results, the same ELO and the same disputes, with no service and no bookings: `neblla_update_app({ matches: { reportHours: 24, board: 'level' } })` (the same shape as `results`; `true` with the defaults, `null` turns it off). Each time a room starts (`neblla.room.start()`), Neblla opens its match between side `'A'` and side `'B'` of the signed-in players inside, by order of arrival (A, B, A, B…), or the sides whoever starts it says: `neblla.room.start({ teams: { A: [id], B: [id] } })` (ids of `neblla.room.users`; a guest or someone outside answers `invalid_teams` and the room does not start). A guest is on no side, and with fewer than one player per side there is no match. It is in the `room` module:
  ```javascript
  neblla.room.match;                                                        // { match, room, start, state, deadline, teams: { A: [userId], B: [userId] }, team } or null
  await neblla.room.matches.report(neblla.room.match, { winner: 'A' });    // at the end, each player says it (also after leaving, until the deadline)
  const mine = await neblla.room.matches.mine();                           // their games of rooms, newest first
  neblla.room.matches.on('update', (p) => paint(p));                        // like neblla.business.matches.on
  ```
  The rest is as with sessions: the states, the deadline (`reportHours` from when it started), the ELO board (`board`), the queue in People › Disputes and `neblla_matches` (with the room's name as its title and no chat), and the cheaters (`cheaterHint`, `cheater`). If the room's server (`room.js`) knows who won, let it show it and let each player confirm it with `report`: whoever denies it opens a dispute. With the `business` module, `neblla.business.matches.mine()` brings the rooms' too.
- **Cheaters.** Each player keeps a tally (`neblla_matches` `player` `{ user }` → `{ reported, disputed, lost, ratio, hint, cheater? }`, also on their card in the panel): with `hint: true` they pass the service's threshold (`results.cheaterHint`; by default 3 disputes lost and more than 30 % of their matches in dispute) and the queue marks them, but Neblla does not decide: the developer declares them with «Declare a cheater» in the queue or on their card, or with `declareCheater` `{ user, note? }`. Their open disputes go to the other side (the players hear it with `reason: 'cheater'`), what they said in matches not decided stops counting, they are flagged (as `neblla_flag_user`) and, as `results.cheater` says (the strictest of the services), they can no longer say results (`'block'`, the default: `cheater_blocked`) or are banned (`'ban'`). `clearCheater` `{ user }` withdraws it (what was settled stays); `cheaters` lists them.
- **Open matches for a level.** A session of a `book: 'open'` service can ask for a level on an ELO board: `reserveAt('padel', { start, level: { board: 'level', min: 1300, max: 1500 } })`; without `level`, when the service has `results: { board, levelRange: 100 }`, its maker's rating ± that range. `slots('padel')` shows each player only the sessions of their level (and their own, or those they are in), with `level: { board, min, max }` on each; a guest sees them all. Booking outside the range answers `level_out_of_range` with `min`, `max` and their `rating` (someone who never played has the board's `start`). Its maker widens it while it has places left: `neblla.business.booking.widenLevel('padel', slotId, { min: 1100 })` → `{ slot, level }` (never narrower: `invalid_level`; someone else's, `not_your_match`; full, `slot_full`). With `min: 4` it is confirmed when full, like any match. It works the same for a language school with groups by level (a board the school sets with `setRating`) or a chess club. `times` are free times, with no match yet: they carry no level. Errors: `invalid_level` with `field`, `unknown_board`, `not_elo_board`.
- **Seen first by whoever has a product.** A service with `early: { products: ['premium'], hours: 12 }` keeps its new sessions (the ones the business opens, also the cases of a series, and the open matches a player makes with `reserveAt`) for whoever has one of those products (bought and not spent, or a live subscription) during their first `hours` (12 if not said), and for whoever made it: the «Premium» that sees open matches before anyone, the gym member who books a class first, the presale for subscribers. To them `slots()` brings the session with `earlyUntil` (until when it is theirs alone); the rest do not see it until then. Booking earlier answers `early_access` with `until` (and `products`, to offer the purchase). Whoever already has a place keeps seeing it; a standing place and the panel do not wait. Removing `early` from the service opens it to everyone at once.
- **Ratings both ways.** After a session already played, each client who had a place rates the site (Airbnb with host and guest, a network of clubs, a platform of private lessons):
  ```javascript
  await neblla.business.rate({ site: 'centro', slot: sessionId, rating: 5, text: 'New courts and good light' });  // 1 to 5; one per session, again changes it → { review }
  const { rating, ratingCount, reviews } = await neblla.business.reviews('centro');                             // a site's reviews, newest first: [{ rating, text?, name?, at }]
  ```
  `services()` brings `rating` and `ratingCount` on each site (public). The business rates each client of a session already played with `neblla_business` `rateUser` `{ user, slot, rating, text? }` (also on their card in the panel, «Rate» on their past sessions): anyone of the team with rights on that site (C350), and a Professional only in their own sessions. Their average is seen only by the businesses of the app: `userRating` `{ user }` → `{ rating, ratingCount, reviews }`, their card, and `clientRating` next to each booking in the `agenda`. Errors: `session_not_played`, `not_in_session`, `invalid_review` with `field`, `slot_cancelled`, `login_required`. The developer moderates them in Business › Ratings or with `reviews` `{ kind?: 'sites' | 'users', id?, hidden? }` and `hideReview` `{ review, hidden? }`: a hidden one stays, counts for nothing in the average and nobody reads it (even when its author writes it again); `hidden: false` brings it back.

**Custom panels and your team.** In the panel (Features › Custom screens) you define your own screens —"Today's bookings", "Monthly attendance"— as views of your tables with filters and columns, and buttons that call those actions —"Cancel booking", "Give credit back". Your agent can build them over MCP:

```javascript
neblla_set_panel({ appId, name: 'today', panel: {
  title: "Today's bookings",
  source: { booking: 'classes' },                     // or { table: 'bookings' }
  where: { start: { gte: '$today', lt: '$tomorrow' } },
  filters: [{ field: 'slot', label: 'Class' }],
  columns: ['player.name', { field: 'start', label: 'Time' }],
  actions: [{ label: 'Cancel booking', call: 'booking.cancel', confirm: true }],
} })
```

- `where` takes relative dates: `$now`, `$today`, `$tomorrow`, `$dayAfterTomorrow`, `$weekStart`, `$monthStart`, `$nextMonthStart`. So "Monthly attendance" is `{ start: { gte: '$monthStart', lt: '$nextMonthStart' } }`.
- A bookings panel lists every slot of its range, free or not: a row per booking (`id`, `slot`, `title`, `start`, `end`, `status` —`'reserved'`, or `'held'` while paying—, `cost`, `at`, `player` (`{ name }`: the public name your app gives them or, without one, the name of their Neblla account), `capacity`, `left` —the places left— and `series` when the slot repeats) and one per slot nobody has booked (`status: 'free'`, with no `id` nor player). So a slot just made shows at once: "Thursday 17:00 · free", "18:00 · free", "19:00 · Ana López". The same for classes, appointments, matches or tournaments, and the cases of a series are rows like any slot. Filters, `where` (`in` works too; `{ status: 'reserved' }` keeps only the bookings) and `orderBy` (by default, `start`) still apply, and row buttons only show on rows with a booking: a `'held'` place shows as "Awaiting payment" (in the `status` column or, without it, after the player's name), with no buttons (`booking_held` if acted on), until it is paid or lapses on its own after 35 minutes. Without `columns`, it shows `start`, `title`, `player.name` and, if a slot takes more than one place, `left`.
- The actions `booking.cancel`, `booking.move`, `credits.adjust`, `table.remove` and `table.save`, with their `args`, go on each row. `booking.createSlot` is a button over the panel that asks for a short form (title, start, minutes, places and how it repeats, as in a calendar: every day, week, month or year, every how many, which days of the week, in a month the same day or the same weekday —"the second Tuesday", "the last Friday"—, and until a date or how many times); its `args` fill it in beforehand: `{ label: 'New slot', call: 'booking.createSlot', args: { title: 'Yoga', capacity: 12, minutes: 60 } }` (also `start` —a date or `$tomorrow`…—, `timeZone` and the repetition: `freq`, `interval`, `byDay`, `byMonthDay`, `until`, `count`; without it, the time is that of the browser of whoever presses it; with `confirm`, it asks before creating). To press it, a role needs to write `nb_slots` (in the panel, the box «Can open new slots» in Personas › Grupos › Papeles). The start and the «until» are picked with the panel's own date picker, in its language. That way the studio's owner sets up the timetable alone: "Yoga, Tuesdays at 18:00, until June" is every Tuesday until June in one go.
- `neblla_run_panel` runs it and returns the rows, to try it without opening the back office.

 And not only for you: you invite your team —the studio owner, the teachers, a partner— from the panel (Business › Your team) or with `neblla_team({ appId, action: 'add', email, groups })`. First the whole address is looked up (`lookup`; nobody can browse who has an account). If they have a Neblla account, an email goes out and they accept it signed in to developers.neblla.com with that address, with any Neblla account (the one they use in the apps, or a new one; no need to be a developer: they see an empty back office and, in My apps, the invitation), or they send it to «Banned», and then they cannot be invited again until they take it back; the invitation expires after 7 days (`expiresInDays`, up to 30) and can be sent again. If they have no account yet, you **pre-register** them: everything is ready, the invitation does not expire and waits for them the day they sign up with that address (status `not_registered` until then). A friend of yours on Neblla is invited without typing their address (`friend`, from `action: 'friends'`), and you do not see it until they accept. In the list, the status says «Not registered», «Invitation not accepted» or nothing, once they are in. Each person is in one or more **groups** (Business › Groups) and their permissions add up: a partner who also teaches is in «Partners» and in «Professionals». A group is a name and what it can do on each area of the panel, see (`read`) or change (`write`), and the server applies it on every screen of the panel and every tool of the MCP (they also come in through the MCP with their own account). So you do not start from scratch there are five example groups, to use as they are or as the template of one of yours: **Partners** (`partner`, everything but money, the plan, the app's own domain and deleting the app), **Community and support** (`support`, the people of the app and the sales to read, without touching money or code), **View only** (`viewer`, everything, read only), **Custom screens only** (`screens`: only the panels you give with `panels`, for the teacher or a client) and **Professionals** (`staff`, for the teacher, the physio or the groomer of a business: in the Business tab they see and change only what is theirs —the sessions they give and who comes, their hours, their line of the accounts—; they open sessions only in their own name. They are the professional of Business › Professionals with the same email; with no card for that email, they see nothing). «Only theirs» in Business (`own`) holds while every group that gives them Business says so. A group can also be **limited to some sites** (`neblla_team` `group_save` with `sites: ['centro']`; in the panel, «Only these sites»): its members only see and change the sessions, resources, professionals, closed days, bookings, chats, accounts and client cards (the clients with bookings at those sites) of those sites, through the panel, the MCP or the admin API, and such a group gives neither People nor Moderation (they are the whole app's). It is the manager of one club in an app of many clubs, or of one centre of a chain of gyms. Only you change the team and the money: a group can see them, never change them (`read_only_area`). What their groups do not allow answers `not_allowed`. Your team's «Edit with AI» and «Ask the AI» run on **your** Claude key, the owner's (without one they get `no_claude_key` with `ownerKey: true`), and the activity log says who used it. Only you change the team and its groups, and take access away. These groups are the back office's; what each user can do inside the app are the app's roles. On top of that you can give anyone a role of the app (`role`, see identidad.txt, "Groups and permissions"): they see the panels whose source they can read and press the buttons where they can write; without `write`, the button answers `not_allowed`. In a role, bookings are `nb_bookings` and credits `nb_credits`: `{ teacher: { nb_bookings: 'read write' } }`. Panels see every table and every user; that is why they live in the back office and never in the app.

None of this needs a server of yours. And if you want your own logic on a server, your `room.js` can run on Server, in Neblla's cloud or on your own server (see servidor.txt).

## The rules that matter

- `message.send()` from `client.js` reaches EVERYONE including you — use `m.fromMe` to tell them apart. From the server there is no "me".
- `db.setPublicInfo()` is for data other people can see; `db.save()` is for private data that persists. `neblla.db.data` never reaches other clients, nor the peer running `room.js`.
- `db.save()` returns a promise: it resolves once the save is done (`{ data, mode, pending }`) and rejects with a code (`save_too_large`, `invalid_save`…). You need not await it; if you don't, the failure still reaches `db.on('error')`. For an offline mode, keep the changes locally yourself and send each one later with `{ at }`, the time it happened (see identidad.txt).
- `rooms.book()` books a name but does NOT enter. Follow it with `rooms.join()`.
- The `server/` files run on three devices at once (Fog). If all of them leave at once, the next one starts `room.js` again with `neblla.state.get()` already loaded: keep in the state whatever has to survive (see servidor.txt).
- WebRTC P2P is negotiated automatically; the routes are transparent.
- AI (`neblla.ai`) needs a login except in browser-direct mode. Communications with the developer need a login.
- There is no `createRoom()`: a room is opened with `rooms.book → rooms.join → room.start`.