# Palbase — full documentation

> Palbase — the backend for apps. Every project has auth, storage, realtime,
> flags, notifications, secrets, analytics, AI and purchases, called from web
> apps with the publishable key (`palbase/web`), from iOS (Swift) and Android
> (Kotlin) with the native SDKs, and from servers with the secret key
> (`palbase/server`). Your own backend runs on a machine built from a GitHub
> branch on every push, beside a Postgres database of its own. Backends are
> `palbase/backend`: `@Controller` classes whose methods are routes,
> `@Injectable` services that arrive by constructor, a `@Module` that lists what
> exists, `PalbaseFactory.create(AppModule)` in `src/main.ts`, and the schema
> declared with Palgres in `src/db/public.ts`. A push to the branch is the
> deploy; the CLI (`npx palbase`) does the rest — client apps, the purchase
> catalog, environments, tokens.



<!-- ===== getting-started/introduction ===== -->

# Introduction

Palbase is a backend platform in two halves. **Every project has a set of modules** — auth, storage, realtime, flags, notify, secrets and analytics — that an app uses with no backend of its own, the way it would use Firebase: sign users in, keep their files, push them messages, read flags, count events. And when a project needs code of its own, it runs on **machines** built from a GitHub branch on every push, beside **Postgres databases** of its own — with a TypeScript framework, `palbase/backend`, that is made for exactly that.

You can use either half without the other. Most projects start with the modules from an app, and add a backend when a rule has to live somewhere an app cannot change it.

## A taste

An app signs a user up with the project's publishable key:

```ts
// app/signup.ts
import { createClient } from "palbase/web";

const palbase = createClient({ url: "https://<ref>.palbase.studio", publishableKey: "pb_<ref>_c…" });

const { user } = await palbase.auth.signUp({ email: "ada@example.com", password: "a passphrase of fifteen+" });
console.log(user.id);
```

A server — any server — sends that user an email with the secret key:

```ts
// server/welcome.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

await palbase.notify.sendEmail({ body: { to: "ada@example.com", subject: "Welcome", text: "Glad you are here." } });
```

And a backend of your own is a class whose methods are routes, served on a machine:

```ts
// src/modules/notes/notes.controller.ts
import { Body, Controller, Database, Post, User, z, type UserT } from "palbase/backend";

const CreateNote = z.object({ title: z.string().min(1).max(200) });
type CreateNote = z.infer<typeof CreateNote>;

@Controller("/notes")
export class NotesController {
  // Every route needs a signed-in user unless it says otherwise; @User() is them.
  @Post("")
  async create(@Body(CreateNote) body: CreateNote, @User() user: UserT): Promise<{ id: string }> {
    const [row] = await Database.$query<{ id: string }>("insert into notes (owner, title) values ($1, $2) returning id", [user.id, body.title]);
    return row;
  }
}
```

Push it to its branch, and the machine builds it and rolls it out beside the version that serves. The [Quickstart](/docs/getting-started/quickstart) does all three, end to end.

## What every project has

| Module | What it does | From an app (publishable key) | From a server (secret key) |
|---|---|---|---|
| **auth** | Users, sessions, passwords, passkeys, second factors, magic links, phone codes, social sign-in, test users | [Web Auth](/docs/web/auth) | [Authentication](/docs/backend/authentication), [Test Users](/docs/backend/test-users) |
| **storage** | Buckets and files, public reads, signed URLs, image renditions | [Uploads](/docs/web/uploads) — through a URL a server signed | [Storage](/docs/backend/storage), [Direct Uploads](/docs/backend/direct-uploads) |
| **realtime** | Channels over one socket: broadcasts, shared state, presence; a backend's gateways | [Web Realtime](/docs/web/realtime), [Web Gateways](/docs/web/gateways) | [Realtime](/docs/backend/realtime), [Gateways](/docs/backend/gateways), [Channels](/docs/backend/channels) |
| **flags** | Feature flags and remote config, per-user values | [Web Flags](/docs/web/flags) | [Flags](/docs/backend/flags) |
| **notify** | Email, push, SMS and WhatsApp; templates, topics, preferences | a user's devices, preferences and topics | [Notifications](/docs/backend/notifications) |
| **secrets** | The project's secrets, versioned, in two sets | — | [Secrets](/docs/backend/secrets) |
| **analytics** | Events, identifies, page views; summaries, funnels and retention | [Web Analytics](/docs/web/analytics) | [Analytics](/docs/analytics/overview), [Reading Analytics](/docs/analytics/reading) |
| **ai** | The platform's models: answers, tools, agents, and chats with the members a backend names | Through a backend's gateway: a chat's members join it ([Web Gateways](/docs/web/gateways#chat-gateways)) | [AI](/docs/backend/ai) |

Each module answers at the project's address, under a path of its own (`/auth/…`, `/storage/…`, `/flags/…`), and each has a contract — the OpenAPI document the SDK's clients are generated from. The SDKs are a convenience over those paths, not a requirement: anything that speaks HTTPS can call them.

And for code of your own:

| | |
|---|---|
| **Machines** | Your program, built from a repository's branch and directory on every push; sizes that sleep and sizes that never do; logs, builds and rollback — [Machines](/docs/machines/overview) |
| **Databases** | Postgres 18 with pgvector and PostGIS, backups and point-in-time restore, a read-only SQL console in Studio — [Databases](/docs/machines/databases) |
| **`palbase/backend`** | Controllers, services and modules in TypeScript, secure by default, with the project's modules and its database built in — [Backend SDK](/docs/backend/overview) |

## The surfaces

| Surface | What it is | Docs |
|---|---|---|
| `palbase/web` | The client for web and JavaScript apps: `createClient` with the publishable key — auth, the session, the realtime socket | [Web SDK](/docs/web/overview) |
| `palbase/server` | The client for servers: `createServer` with a secret key — every module's server calls, and the receiver for the project's webhooks | [Server SDK](/docs/server/overview) |
| `palbase/backend` | The framework a machine runs: `PalbaseFactory`, `@Module`, `@Controller`, and `Palbase`, `Database` and `Log` | [Backend SDK](/docs/backend/overview) |
| `palgres` | The database half of the framework: the schema in TypeScript, typed queries, and migrations that run beside the version that serves | [Schema](/docs/backend/schema), [Schema changes](/docs/backend/migrations) |
| Studio | Organizations, projects and environments; every module's screens; machines, databases, keys and secrets | [Organizations](/docs/getting-started/organizations) |

Palbase has SDKs in TypeScript (`palbase/web`, `palbase/server`, `palbase/backend`), Swift and Kotlin. An iOS app takes the Swift SDK, `palbase-swift` with Swift Package Manager ([iOS SDK](/docs/ios/overview)), and an Android app the Kotlin one, `studio.palbase:palbase` and an artifact per module ([Android SDK](/docs/android/overview)). An app on another platform, such as a game engine, calls the modules over HTTPS with the publishable key in the `apikey` header and the user's access token as `Authorization: Bearer …`, the same requests the SDKs make.

The TypeScript SDKs are one npm package, `palbase`, whose parts are its subpaths — the CLI comes with it (`npx palbase`) — and `palgres`, which `palbase/backend` brings: `npm install palbase` (or `bun add palbase`). They ship compiled, under the Palbase SDK License ([Project Structure](/docs/getting-started/project-structure)).

## Organizations, projects and environments

An **organization** is a team, a **project** is an app in it, and an **environment** is the thing that runs: each one a project of the platform's own, with **nothing shared** with another environment — its own address, its own keys, its own users and files, its own machines and databases. A staging copy of production is a second environment, with its machines built from another branch. Everyone in the organization reaches its projects at their role, owner, admin or member: members, invitations, roles and the audit log are in [Organizations](/docs/getting-started/organizations).

A project's **first environment** has the slug `main`. Every environment answers at one address, named by its **ref**:

```text
https://<ref>.palbase.studio
```

The ref is on the environment's **Settings**, and it never changes. A machine of the environment answers under the app domain — `https://<ref>.app.palbase.studio` for the one named `backend` — and a database at `<name>-<ref>.db.palbase.studio`.

## The keys

An environment has **publishable keys** — each [registered app](/docs/apps/overview)'s own, the one the environment was made with, and any you make — and **any number of secret keys**, on **Settings › API keys**:

| Key | Looks like | Role | Where it goes |
|---|---|---|---|
| Publishable | `pb_<ref>_c…` | `anon` | In apps: a browser bundle, a mobile app. What it reaches is what an app may do, and the signed-in user's token decides whose data. |
| Secret | `pb_<ref>_s…` | `service_role` | On servers only: a machine's secrets, a server's environment. It opens the whole project — every user, every file, every secret. |

The ref is in the key, so a key names its project. A secret key is made with a name (**Create secret key**), **shown once**, and revoked on its own (**Revoke**) — give each server its own, and a leaked one is replaced without touching the others. `createClient` refuses a secret key, and `createServer` refuses to run in a browser.

Every request to the project carries one of them in the `apikey` header; a request with none is `401 missing_api_key`, and a key of another project is the same as none (`401 invalid_api_key`). A user's access token, when one is sent, must be one this project issued (`401 invalid_token` otherwise). Past the project's requests-per-second limit, a request is `429 rate_limited` with `Retry-After: 1`; past its requests for the period, under a quota that refuses, `429 quota_exceeded` with `Retry-After` until the next period.

> **Note:** The project's address answers a browser on any site. A browser app calls it directly, with the publishable key and the signed-in user's token, as [Web SDK](/docs/web/overview#calling-the-project-from-a-browser) explains. Your own machine's backend answers cross-origin requests itself, for the origins it names.

## How code reaches a machine

One way: **a push to the machine's branch.**

1. [Connect GitHub](/docs/machines/github) — install **Palbase Cloud** on the account that owns the repository, and connect it to the environment.
2. Open a machine on a repository, a branch and a directory of it (**Backend › Machines › New machine**).
3. Push. A push that changes the machine's directory is built — its `Dockerfile`, or what Railpack detects — and rolled out beside the version that serves; it takes traffic once it answers its health check.

There is no deploy command and no tool to install. A release whose machine migrates a database runs the migration itself, beside the version that serves; a release that does not come up never takes a request; and any build that succeeded can be returned to ([Builds, Logs & Rollback](/docs/machines/builds)).

## Related

- [Quickstart](/docs/getting-started/quickstart) — a web app, a backend, a machine, end to end
- [Architecture](/docs/getting-started/architecture) — how a backend's code is shaped
- [Project Structure](/docs/getting-started/project-structure) — what a backend repository holds
- [Web SDK](/docs/web/overview) · [Server SDK](/docs/server/overview) · [Backend SDK](/docs/backend/overview)
- [Machines](/docs/machines/overview) · [Databases](/docs/machines/databases)



<!-- ===== getting-started/quickstart ===== -->

# Quickstart

In this guide you create a Palbase project in Studio, sign a user up and in from a web app, write a small backend with `palbase/backend`, put it on a machine by pushing it to GitHub, and call it from the web app as the signed-in user. Nothing here is run from a command line of Palbase's — the project is Studio's, the deploy is `git push`.

## Before you start

| You need | Why |
|---|---|
| **A Studio account** | where the project lives — Palbase is opening step by step: [request access](/signup) |
| **A GitHub repository** you can push to | a machine is built from a branch of it |
| **Bun 1.4** — [bun.sh](https://bun.sh) | the backend runs on Bun, and `bun install` writes the lockfile its build installs from |
| **Node.js 22** | the web app (Next.js) |

> **Note:** The SDK is one npm package, `palbase` — `palbase/web` for the app, `palbase/backend` for the backend (it brings `palbase/server` and `palgres`), and the CLI (`npx palbase`): `npm install palbase` (or `bun add palbase`).

## 1. Create a project

In Studio, **Projects › Create project**: a **Project name**, its **First environment**, and the **Organization** it belongs to (asked only when you have more than one). The first environment's slug is always `main`.

Open the environment. Everything in this guide is that environment's — it is a project of its own, with its own address, keys, users, machines and databases:

- its **address**, `https://<ref>.palbase.studio` — the ref is on **Settings**;
- its **publishable key**, `pb_<ref>_c…`, on **Settings › API keys** — the key apps ship.

## 2. Sign a user up from a web app

Start a Next.js app and give it the web SDK:

```json
{
  "dependencies": {
    "palbase": "^0.10.0",
    "next": "^16.3.4",
    "react": "^19.2.7",
    "react-dom": "^19.2.7"
  }
}
```

and three settings, in `.env.local`:

```text
NEXT_PUBLIC_PALBASE_URL=https://<ref>.palbase.studio
NEXT_PUBLIC_PALBASE_PUBLISHABLE_KEY=pb_<ref>_c…
NEXT_PUBLIC_BACKEND_URL=https://<ref>.app.palbase.studio
```

**A browser calls the project's address directly.** The address answers a page on any site, so nothing stands between the app and the project ([Web SDK](/docs/web/overview#calling-the-project-from-a-browser) says what it answers, and why the browser is the one to call it). Next.js needs no setting for the SDK: the package is compiled JavaScript.

The client is made once, in the browser, with the project's address:

```ts
// lib/palbase.ts
import { createClient, type PalbaseClient } from "palbase/web";

let client: PalbaseClient | undefined;

/** The project's client: its publishable key, and the signed-in user's session. */
export function palbase(): PalbaseClient {
  client ??= createClient({
    url: process.env.NEXT_PUBLIC_PALBASE_URL!,
    publishableKey: process.env.NEXT_PUBLIC_PALBASE_PUBLISHABLE_KEY!,
  });
  return client;
}
```

And a page that signs up, signs in, and — after step 6 — calls the backend:

```tsx
// app/page.tsx
"use client";

import { useState } from "react";
import { PalbaseError } from "palbase/web";
import { palbase } from "../lib/palbase";

export default function Home() {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [said, setSaid] = useState("");

  async function attempt(work: () => Promise<string>) {
    try {
      setSaid(await work());
    } catch (e) {
      setSaid(e instanceof PalbaseError ? `${e.status} ${e.code}: ${e.message}` : String(e));
    }
  }

  const signUp = () =>
    attempt(async () => {
      const { user } = await palbase().auth.signUp({ email, password });
      const session = await palbase().auth.currentSession();
      return session ? `signed up and in as ${user.id}` : `signed up as ${user.id}: verify the address, then sign in`;
    });

  const signIn = () =>
    attempt(async () => {
      const result = await palbase().auth.signIn(email, password);
      return result.user ? `signed in as ${result.user.id}` : "this account asks for a second factor";
    });

  const callBackend = () =>
    attempt(async () => {
      const session = await palbase().auth.currentSession();
      if (!session) return "sign in first";
      const res = await fetch(`${process.env.NEXT_PUBLIC_BACKEND_URL}/me`, {
        headers: { authorization: `Bearer ${session.accessToken}` },
      });
      return `${res.status} ${await res.text()}`;
    });

  return (
    <main>
      <input value={email} onChange={(e) => setEmail(e.target.value)} placeholder="email" />
      <input value={password} onChange={(e) => setPassword(e.target.value)} placeholder="password (15+ characters)" type="password" />
      <button onClick={() => void signUp()}>Sign up</button>
      <button onClick={() => void signIn()}>Sign in</button>
      <button onClick={() => void callBackend()}>Call the backend</button>
      <p>{said}</p>
    </main>
  );
}
```

Run it (`npm run dev`), sign up, and the user is in **Auth › Users** in Studio. A password of a single factor is 15 characters at least. A project that asks for a verified email answers the sign-up without a session; the verification is [Web Auth](/docs/web/auth)'s to explain.

You have used one module — auth — with no backend at all. Storage, realtime, flags, notify and analytics are the same: every project has them, the publishable key reaches what an app may do, and the secret key reaches the rest ([Introduction](/docs/getting-started/introduction)).

## 3. Write the backend

A backend is its own directory — its own repository here — that a machine builds:

```text
notes-backend/
├── Dockerfile
├── .env.example
├── package.json
├── bun.lock
├── tsconfig.json
└── src/
    ├── main.ts
    ├── app.module.ts
    ├── me.controller.ts
    └── modules/notes/
        ├── dto.ts
        ├── notes.controller.ts
        ├── notes.module.ts
        └── notes.service.ts
```

```json
{
  "name": "notes-backend",
  "private": true,
  "type": "module",
  "scripts": { "start": "bun run src/main.ts" },
  "dependencies": {
    "palbase": "^0.10.0"
  }
}
```

The decorators read the types TypeScript emits, so `tsconfig.json` turns both on:

```json
{
  "compilerOptions": {
    "target": "es2023",
    "module": "esnext",
    "moduleResolution": "bundler",
    "strict": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "allowImportingTsExtensions": true,
    "noEmit": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts"]
}
```

The schemas of a domain sit in its `dto.ts` — each one a value for `@Body` and a type of the same name:

```ts
// src/modules/notes/dto.ts
import { z } from "palbase/backend";

export const CreateNote = z.object({ title: z.string().min(1).max(200) });
export type CreateNote = z.infer<typeof CreateNote>;

export const Note = z.object({ id: z.string(), owner: z.string(), title: z.string(), created_at: z.string() });
export type Note = z.infer<typeof Note>;
```

The service holds the logic. This one keeps notes in the machine's memory — enough to see the whole path work; [step 8](#8-where-next) gives it a database:

```ts
// src/modules/notes/notes.service.ts
import { Injectable, NotFound } from "palbase/backend";
import type { CreateNote, Note } from "./dto";

// In this process only: a machine that sleeps, or a second copy, does not have them.
@Injectable()
export class NotesService {
  private readonly notes = new Map<string, Note>();

  list(owner: string): Note[] {
    return [...this.notes.values()].filter((n) => n.owner === owner);
  }

  create(owner: string, input: CreateNote): Note {
    const note: Note = { id: crypto.randomUUID(), owner, title: input.title, created_at: new Date().toISOString() };
    this.notes.set(note.id, note);
    return note;
  }

  get(owner: string, id: string): Note {
    const note = this.notes.get(id);
    if (!note || note.owner !== owner) throw new NotFound(`no note ${id}`);
    return note;
  }
}
```

The controller is HTTP only — and every route needs a signed-in user unless it says otherwise:

```ts
// src/modules/notes/notes.controller.ts
import { Body, Controller, Get, Param, Post, User, type UserT } from "palbase/backend";
import { CreateNote, type Note } from "./dto";
import { NotesService } from "./notes.service";

@Controller("/notes")
export class NotesController {
  constructor(private readonly notes: NotesService) {}

  @Get("")
  list(@User() user: UserT): Note[] {
    return this.notes.list(user.id);
  }

  @Post("", { rateLimit: { max: 30, window: 60 } })
  create(@Body(CreateNote) body: CreateNote, @User() user: UserT): Note {
    return this.notes.create(user.id, body);
  }

  @Get("/{id}")
  read(@Param("id") id: string, @User() user: UserT): Note {
    return this.notes.get(user.id, id);
  }
}
```

```ts
// src/modules/notes/notes.module.ts
import { Module } from "palbase/backend";
import { NotesController } from "./notes.controller";
import { NotesService } from "./notes.service";

@Module({ controllers: [NotesController], providers: [NotesService] })
export class NotesModule {}
```

`/me` answers who the caller is:

```ts
// src/me.controller.ts
import { Controller, Get, User, type UserT } from "palbase/backend";

@Controller("/me")
export class MeController {
  @Get("")
  me(@User() user: UserT): { id: string; email: string | null; emailVerified: boolean } {
    return { id: user.id, email: user.email, emailVerified: user.emailVerified };
  }
}
```

The root module lists what exists, and `main.ts` serves it. The browser calls the backend from the web app's origin, so the backend names that origin (CORS is the backend's own to answer):

```ts
// src/app.module.ts
import { Module } from "palbase/backend";
import { MeController } from "./me.controller";
import { NotesModule } from "./modules/notes/notes.module";

@Module({ imports: [NotesModule], controllers: [MeController] })
export class AppModule {}
```

```ts
// src/main.ts
import { PalbaseFactory } from "palbase/backend";
import { AppModule } from "./app.module";

// Serves on $PORT. The project's address, id and secret key come from the
// environment: the machine is started with them.
await PalbaseFactory.create(AppModule, {
  cors: { origins: (process.env.WEB_ORIGINS ?? "http://localhost:3000").split(",") },
});
```

How the machine runs it:

```dockerfile
FROM oven/bun:1.4.2-alpine@sha256:d888c0ae6c86d7866ff10c5aafdd9077b36aee6455b33dd270fb93c0dd5cef6f
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile --production
COPY tsconfig.json ./
COPY src ./src
USER bun
CMD ["bun", "run", "src/main.ts"]
```

And what it needs before it can start — the build reads this file, and waits rather than roll out an app that would not:

```text
PALBASE_URL=
PALBASE_PROJECT_ID=
PALBASE_SECRET_KEY=
```

Run `bun install` once to write `bun.lock`, and commit everything.

## 4. Give it the secret key

The machine is started with `PALBASE_URL` and `PALBASE_PROJECT_ID` by the platform. `PALBASE_SECRET_KEY` is yours to give — the backend uses it to reach the project's modules and to check its callers' sessions.

1. **Settings › API keys › Secret keys**: a **Key name** (`notes backend`), **Create secret key**. It is shown **once** — copy it now.
2. **Environment › Variables**, **Add secret**: the name `PALBASE_SECRET_KEY`, the key as its value.

The secret is in the environment's **production** set. A machine starts with the set it names, which you choose in the next step.

## 5. Connect GitHub and open the machine

**Backend › Machines › New machine**:

1. **Connect GitHub** — GitHub asks where to install **Palbase Cloud**; choose the repository, and connect it to this project by writing its ref when Palbase asks. Back in Studio, **Refresh** ([Connecting GitHub](/docs/machines/github)).
2. **Repository**: `you/notes-backend`; **Branch**: `main`; **Directory**: empty (the repository's root).
3. **Name**: `backend` — the machine of that name answers at `https://<ref>.app.palbase.studio`. **Size**: `shared-256`. **Port**: `8080`.
4. **Create machine**.

The branch's head is built at once. Its build stops at **Waiting for variables**, `PALBASE_SECRET_KEY` missing: the machine starts with no secrets yet. Open it, **Edit settings**, **Secrets: Production secrets**, **Save settings** — and the waiting build rolls out by itself. `.env.example` is what caught it ([Builds](/docs/machines/builds#envexample-what-the-program-must-be-given)).

## 6. Push

From now on, a push is the deploy:

```bash
git commit -am "Notes: read one by id"
git push origin main
```

The commit gets a **Palbase Cloud** check on GitHub — *Building*, then *Rolled out* — and the machine page lists the build with its log. The new version starts beside the old one and takes traffic once it answers its health check; a version that does not come up never takes a request.

## 7. Call it

Without a token, the backend refuses — in the envelope every refusal comes in:

```bash
curl -i https://<ref>.app.palbase.studio/me
# HTTP/2 401
# {"error":"unauthorized","error_description":"This route needs a signed-in user","status":401,"request_id":"req_…"}
```

From the web app, signed in, **Call the backend** answers `200` with the user's id and email: the browser sent the session's access token, and the backend checked it against the project. Notes work the same way — `POST /notes` with `{"title": "…"}` and the same header.

What the backend writes is on its machine page under **Logs**, and `Log` from `palbase/backend` puts the request's id on every line ([Builds, Logs & Rollback](/docs/machines/builds#logs)). Every request to the environment's address, whichever module answers it, is on Studio's **Logs** page ([Logs](/docs/getting-started/logs)).

## 8. Where next

- **A database.** **Database › Databases › New database**, then give it to the machine with **Run migrations** on. Declare the table in `src/db/public.ts`, pass it to `PalbaseFactory.create(AppModule, { db: { schemas: [schema] } })`, and the next push migrates it before the new version serves: [Databases](/docs/machines/databases), [Database](/docs/backend/database), [Schema](/docs/backend/schema).
- **Who sees what.** Row-level security in the schema keeps each user's rows theirs, whatever a route forgets: [Row-Level Security](/docs/backend/row-level-security).
- **The other modules** from the backend — files, email, flags, realtime — are `Palbase.storage`, `Palbase.notify`, `Palbase.flags`, `Palbase.realtime`: [Storage](/docs/backend/storage), [Notifications](/docs/backend/notifications).
- **More environments.** A staging environment is another environment of the project, with machines built from another branch.

## Related

- [Introduction](/docs/getting-started/introduction) — the modules, the keys, and environments
- [Architecture](/docs/getting-started/architecture) — how a backend's code is shaped
- [Project Structure](/docs/getting-started/project-structure) — every file of the backend above
- [Machines](/docs/machines/overview) · [Connecting GitHub](/docs/machines/github) · [Builds, Logs & Rollback](/docs/machines/builds)
- [Web SDK](/docs/web/overview) · [Web Auth](/docs/web/auth) — the client in full
- [Calling Your Backend](/docs/web/backend-calls) — the browser side of step 7



<!-- ===== getting-started/organizations ===== -->

# Organizations

Studio has three levels. An **organization** is a team: its people and their roles, its access tokens and its audit log. A **project** is an app, in one organization. An **environment** is what runs: each one a Palbase project of its own, with its own address, keys, users, files, machines and databases, and nothing shared with another.

```text
Organization      its members and their roles, access tokens, the audit log
└── Project       an app
    └── Environment   main, staging, a developer's own: address, keys,
                      users, files, flags, machines, databases
```

Everyone in an organization reaches every project and environment of it, at their role in the organization. There is no role per project or per environment.

## Organizations

Before your first project, Studio asks you to create your organization, and you are its **owner**. Any account makes more:

```sh
palbase orgs:create "Acme"
palbase orgs:list                 # your organizations and your role in each
```

An organization's **Projects** page lists its projects, and an admin renames it under **General**.

## Projects and environments

An admin creates a project, in Studio (**New project**) or from the CLI; it opens with its first environment:

```sh
palbase projects:create shop --org acme            # its first environment, main, and its keys
palbase envs:create staging -P shop                # a second environment
palbase envs:create staging -P shop --from main    # opened with main's module settings
```

- **The first environment's slug is `main`**, whatever it is called on screen: it is the project's production one, and a CLI change to it asks for confirmation.
- **Another environment's slug** starts with a letter and continues with up to 38 letters, digits or hyphens; `local` is not one. An environment's name on screen can change; its slug never does.
- **`--from`** opens the new environment with another's module settings: secrets by name, not by value. With `--with-cloud` its machines and databases are declared alike too, built from the same branches, with no data.

Each environment has its own address and keys ([Introduction](/docs/getting-started/introduction#the-keys)), and its own usage ([Usage & Limits](/docs/getting-started/usage-and-limits)).

An admin deletes an environment under its **Settings › Danger zone**, or with `palbase envs:delete <slug>`; deleting a project, under its **Settings › Delete project** or with `palbase projects:delete <project>`, deletes every environment of it. An environment's users, files, flags, keys and secrets go with it, and its machines and databases are deleted too.

## Members and invitations

An organization's **Members** page lists its people, each with their role and when they joined; its admins also see the invitations still open.

An admin invites someone by email, as an **admin** or a **member** (member unless said), with **Add member** or from the CLI:

```sh
palbase orgs:members:invite ada@example.com --role admin --org acme
palbase orgs:members:list --org acme
palbase orgs:members:remove ada@example.com --org acme   # a member, or an invitation still open
```

- **Accepting.** The invited person signs in to Studio with the email the invitation names, and accepts it there. The email must be verified: an account whose address is not is refused (`403 email_not_verified`). An invitation does not expire; it waits until it is taken or withdrawn.
- **Inviting again** keeps the invitation, with the new role and the new inviter.
- **The mail.** An invitation is mailed from Palbase when the inviter's own email is verified. An address gets one invitation mail a day from an organization and five a day from all of them together; past that the invitation still waits for it in Studio, unmailed.
- **How many.** An inviter makes 20 invitations an hour and 100 a day, and an organization 20 an hour, however many admins it has (`429` with `Retry-After`).

A member leaves an organization with `palbase orgs:members:remove` and their own email. An admin takes away a member or an admin; only an owner takes away an owner. The organization's last owner stays: make another owner first (`409 last_owner`).

A person who leaves, or is taken away, takes with them what they held at the organization's environments: the CLI's keys they were given, and the access tokens they made.

- **Owners hear of every new role.** When someone — or an access token — is given a role in one of the organization's environments, or a higher one, each owner is mailed: who, which role, which environments, when. An owner whose own owner role is taken is mailed too. The same person and role is mailed to an owner once a day for an environment, the environments it came in named in one mail. The mail comes from Palbase's platform itself, not from Studio, to the address the owner signs in with: if you did not expect it, take the person away under **Members** and write to security@pallasite.net.

## Roles

| | Member | Admin | Owner |
|---|:---:|:---:|:---:|
| Open every project and environment, and read its screens: users, files, flags, logs, usage, machines and their builds | ✓ | ✓ | ✓ |
| See which secrets there are and their versions, and the API keys by their last characters | ✓ | ✓ | ✓ |
| Read with a module's questions that change nothing: a funnel, a retention table, the database's read-only SQL console, a machine's `GET` from **Try it** | ✓ | ✓ | ✓ |
| Change anything in an environment: settings, users, flags, files, templates, machines, databases, secrets | | ✓ | ✓ |
| Read a secret's value, a task's payload, a coupon's one-time codes | | ✓ | ✓ |
| Make and revoke API keys; take a CLI key (`palbase env:pull`, `palbase run`); mint environment tokens | | ✓ | ✓ |
| Create, rename and delete projects and environments | | ✓ | ✓ |
| Invite and take away members and admins; withdraw invitations; rename the organization | | ✓ | ✓ |
| Manage access tokens; read the audit log | | ✓ | ✓ |
| Make or unmake an owner; take away an owner | | | ✓ |

A member's change to an environment is refused with `403 console_role_required`, and the refusal is kept in the audit log. In Studio, an owner changes a member's role from the **Members** list.

A role is read on every request: a member made less than an admin keeps none of the CLI keys they had at the organization's environments, and the admin tokens they made stop working at once. An access token acts at its role, member or admin and never owner, and no more than its maker's role now ([Access Tokens](/docs/getting-started/access-tokens)).

## Your Studio account

**Account security**, in the account menu at the top right, is your own account's:

- **Two-factor authentication**: a second step when you sign in, with an authenticator app or by SMS, and **recovery codes** for when you have neither. They are shown once: keep them where you keep passwords.
- **Passkeys**: sign in with this device's fingerprint, face or screen lock, or a security key, instead of a password. Add one, rename it, or remove it.
- **Connected accounts**: sign in with Google or GitHub, when Studio offers them. The last way you sign in cannot be removed: add a password or a passkey first.

A change to how you sign in needs a sign-in from the last five minutes; an older one is asked to sign in again first. Turning off a second factor asks for your current password.

The CLI signs in as you, and holds a session of yours ([CLI](/docs/cli/overview#signing-in)).

## The audit log

An organization's **Audit log** says who changed what at its environments, newest first: the change, the environment, who made it — a member by their email, an access token or an environment token by its name — the method and path, and the status it was answered. It holds every change made through Studio, the CLI and tokens; a change refused for its role; and every read of a secret's value. The path is kept without its query and the body not at all, since what was sent can hold a secret. Plain reads are not kept.

Its admins read it in Studio, or from the CLI:

```sh
palbase orgs:audit --org acme --limit 100
```

A module keeps a change made through Studio as Studio's: the audit log is where whose it was is kept. See [`palbase orgs:audit`](/docs/cli/reference#palbase-orgsaudit).

## Related

- [Access Tokens](/docs/getting-started/access-tokens) — for CI and agents, at a role of the organization
- [Usage & Limits](/docs/getting-started/usage-and-limits) — what each environment uses
- [CLI](/docs/cli/overview) — signing in, and choosing an environment
- [CLI reference](/docs/cli/reference#orgs) — `orgs`, `projects` and `envs`



<!-- ===== getting-started/architecture ===== -->

# Architecture

A Palbase backend is a plain TypeScript repository, and **one declaration says what exists, who owns it and what it may reach**: a `@Module` lists a domain's classes — its `controllers`, its `providers`, what it `exports` and whose exports it `imports` — and a class that no module lists is **refused at boot**, by name. The root module is the one `src/main.ts` hands to `PalbaseFactory.create`; every other module is reached from it through `imports`.

Dependencies arrive through the **constructor**, and the container supplies them: a dependency is named by its parameter's **type** and by nothing else. There is no `@Inject`, no `useFactory`, no `forwardRef` and no token registry. What the platform gives every handler — the project's modules, the request's database, the log — is **imported**, never injected: `Palbase`, `Database` and `Log` from `palbase/backend`.

This page answers one question: **what shape does the code take?** It is the shape of Palbase's own examples and of Studio's backend; [Project Structure](/docs/getting-started/project-structure) lists the files, and [Modules & Dependency Injection](/docs/backend/modules) the full declaration surface.

## The layers

| Layer | What it does | What it never does |
|---|---|---|
| `src/main.ts` | Boots the app: `PalbaseFactory.create(AppModule, config)` — the database's schemas, CORS, the routes' default auth and limit | holds routes or logic |
| `src/app.module.ts` | The root: `imports` every domain's module | owns a domain's classes |
| `src/modules/<domain>/<domain>.module.ts` | The declaration: which classes the domain owns, and which of them another domain may reach | holds logic · lists a class another module owns |
| `src/modules/<domain>/<name>.controller.ts` | HTTP only: validates input through a schema, picks the caller, turns the service's answer into the response. Listed in `controllers` | imports `Database` · holds business rules · keeps per-request state on the instance |
| `src/modules/<domain>/<name>.service.ts` | The decisions: which rows, whose, in what order; the calls to the project's modules. `@Injectable()`, listed in `providers` | knows about HTTP (no request, no response) · builds its own dependencies |
| `src/modules/<domain>/dto.ts` | Schemas — each a **value** for `@Body` and a same-named **type** | holds logic |
| `src/db/public.ts` | **Is** the database: tables, columns, indexes, [row-level security](/docs/backend/row-level-security) | produces migration files — there are none |

In one line: **controllers thin, services thick, schemas quiet, `db/` the single truth — and the module is the registration.**

A domain is a **folder** with a module in it, and adding one is adding a folder and naming its module in the root's `imports`. The file suffixes (`.controller.ts`, `.service.ts`) are a convention that helps a reader and decides nothing: what decides is the list a class appears in and the decorator it carries.

The rule that carries the most weight is the narrowest: **a controller does not import `Database`.** When a route starts reaching for a table, the logic has moved into the layer that is hardest to test, and the layer that was meant to hold it becomes decoration.

## Where does this go

| The need | Its home |
|---|---|
| Validate input | a schema in the module's `dto.ts`, passed to `@Body(Schema)` / `@QueryParams(Schema)` |
| Enforce ownership | a row-level-security policy in `src/db/public.ts` **and** the service's `where` — the policy is the backstop, not a reason to stop writing the filter |
| A business rule, a calculation, an ordering | the service |
| Answer with an HTTP status | `throw new NotFound(…)` (or `Forbidden`, `Conflict`, `PalError`) — from the service or the controller; no response object is needed |
| Call another domain | name its class in your constructor — its module `exports` it, and yours `imports` that module |
| Send an email, sign a file URL, read a secret | `Palbase.notify`, `Palbase.storage`, `Palbase.secrets` — in the service |
| Work at start-up or shutdown | an `onStart()` / `onShutdown()` method on a provider — awaited in dependency order |
| Work on a schedule | a [cron](/docs/backend/cron) — not a timer: a machine that sleeps runs none |
| Work done once, now or later | a [task](/docs/backend/tasks) on the machine's queue — not a cron that looks in a table every minute |
| Register a new class | add it to a module's `providers` (or `controllers`) — nothing else registers anything |
| A setting | an environment variable of the machine; a secret is a project secret the machine starts with |

## One vertical, end to end

A `notes` domain, in the order you would build it.

### 1. The database

```ts
// src/db/public.ts
import { defineSchema, defineTable, index, policy, text, timestamp, uuid } from "palbase/backend";

// Each user's notes, theirs alone: row-level security says so, whatever a route forgets.
const notes = defineTable("notes", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    owner: text(),
    title: text(),
    created_at: timestamp().defaultNow(),
  },
  policies: (p) => [
    policy("notes_own").for("all").to("authenticated").using(p.col("owner").eq(p.auth.uid())).withCheck(p.col("owner").eq(p.auth.uid())),
  ],
  indexes: (p) => [index("notes_owner_created").on(p.col("owner"), p.col("created_at"))],
});

export default defineSchema("public", { tables: [notes] });
```

One file per schema, each with a default export. There are no migration files: a release migrates the database to this declaration beside the version that serves ([Schema changes](/docs/backend/migrations)). The request runs as its caller — `authenticated`, with the token's claims — so `auth.uid()` is the signed-in user, and the policy holds for every query of the request.

> **Note:** `ownedByUser()` is the column type made for `owner`: when the user is deleted, their rows go. The platform tells the app through the project's webhook (`user.deleted`), so an app whose schema has an `ownedByUser()` or `userRef()` column does not boot without `PALBASE_WEBHOOK_SECRET`, the secret of the project's webhook endpoint — and an endpoint cannot be made from Studio. A project without one keeps its owner column a `text()` with a policy, as here. See [Event Hooks](/docs/backend/hooks).

### 2. The schemas

```ts
// src/modules/notes/dto.ts
import { z } from "palbase/backend";

export const CreateNote = z.object({ title: z.string().min(1).max(200) });
export type CreateNote = z.infer<typeof CreateNote>;

export const ListNotes = z.object({ limit: z.coerce.number().int().min(1).max(100).default(20) });
export type ListNotes = z.infer<typeof ListNotes>;

export const Note = z.object({ id: z.string(), title: z.string(), created_at: z.string() });
export type Note = z.infer<typeof Note>;
```

Each schema is exported twice under one name: the **value** a decorator validates with, and the **type** a signature reads. Any Standard Schema works — zod, valibot, arktype; `z` is re-exported from `palbase/backend` so the app and the framework agree on one zod.

### 3. The service

```ts
// src/modules/notes/notes.service.ts
import { Database, Injectable, Log, NotFound } from "palbase/backend";
import type { CreateNote, Note } from "./dto";

@Injectable()
export class NotesService {
  async list(owner: string, limit: number): Promise<Note[]> {
    // RLS already narrows this to the caller's rows; the filter says what the route means.
    return Database.public.notes.findMany({
      where: { owner },
      select: ["id", "title", "created_at"],
      orderBy: { column: "created_at", direction: "desc" },
      limit,
    });
  }

  async create(owner: string, input: CreateNote): Promise<Note> {
    const note = await Database.public.notes.insert({ owner, title: input.title });
    Log.info("note created", { note: note.id });
    return { id: note.id, title: note.title, created_at: note.created_at };
  }

  async remove(owner: string, id: string): Promise<void> {
    const gone = await Database.public.notes.deleteMany({ where: { id, owner } });
    if (gone === 0) throw new NotFound(`no note ${id}`);
  }
}
```

`Database` is **the request's own transaction**: it is opened by the first query, committed when the handler returns — before the answer goes — and rolled back when it throws. A service the handler calls shares it, so a route's writes land together or not at all. It is reached inside a request (a handler, a service it calls, an `@On` handler), never at import time or from a timer.

`Database.public.notes` is typed by the declaration file Palgres writes from `src/db/public.ts` ([Database](/docs/backend/database)): a column that does not exist, or a value of the wrong type, is a compile error. Raw SQL is `Database.$query(sql, params)`.

### 4. The controller

```ts
// src/modules/notes/notes.controller.ts
import { Body, Controller, Delete, Get, Param, Post, QueryParams, User, type UserT } from "palbase/backend";
import { CreateNote, ListNotes, type Note } from "./dto";
import { NotesService } from "./notes.service";

@Controller("/notes")
export class NotesController {
  // The container supplies this. Nothing here constructs or imports an instance.
  constructor(private readonly notes: NotesService) {}

  @Get("")
  list(@QueryParams(ListNotes) query: ListNotes, @User() user: UserT): Promise<Note[]> {
    return this.notes.list(user.id, query.limit);
  }

  @Post("", { rateLimit: { max: 30, window: 60 } })
  create(@Body(CreateNote) body: CreateNote, @User() user: UserT): Promise<Note> {
    return this.notes.create(user.id, body);
  }

  @Delete("/{id}")
  remove(@Param("id") id: string, @User() user: UserT): Promise<void> {
    return this.notes.remove(user.id, id);
  }
}
```

Every route needs a signed-in user unless it, its controller or the app's config says otherwise (`{ auth: false }`); `@User()` is that user. A body that fails its schema is a `400` naming the fields, a caller over the route's limit a `429`, a thrown `NotFound` a `404` — all in the platform's one envelope ([Responses & Errors](/docs/backend/errors)). A handler that returns nothing answers `204`; anything else is JSON.

### 5. The module

```ts
// src/modules/notes/notes.module.ts
import { Module } from "palbase/backend";
import { NotesController } from "./notes.controller";
import { NotesService } from "./notes.service";

@Module({
  controllers: [NotesController], // its entry points
  providers: [NotesService], //      the classes it owns
  exports: [], //                    which of them another module may reach
  imports: [], //                    whose exports this module may reach
})
export class NotesModule {}
```

That list **is** the registration, and the only place ownership is decided. `exports` stays empty until another domain needs one of these classes; until a name appears there, nothing outside the module can reach it. Imports are not transitive: a module reaches the exports of the modules it imports, and of no others.

### 6. The root and the boot

```ts
// src/app.module.ts
import { Module } from "palbase/backend";
import { NotesModule } from "./modules/notes/notes.module";

@Module({ imports: [NotesModule] })
export class AppModule {}
```

```ts
// src/main.ts
import { PalbaseFactory } from "palbase/backend";
import { AppModule } from "./app.module";
import schema from "./db/public";

// Serves on $PORT with its database; run by a release with PALBASE_DB_MIGRATE,
// it migrates the database to this schema and exits.
await PalbaseFactory.create(AppModule, { db: { schemas: [schema] } });
```

At boot the container reads every module, refuses what is wrong — a class no module lists, a dependency from a module that is not imported or a class it does not export, a cycle — naming the path that led to it, builds every class once, runs their `onStart()` and serves. The project's address, id and secret key come from the machine's environment.

## Never write this

These are the shapes a code assistant reaches for by default. Every one is wrong here:

- **Express-style handlers** — `app.get(...)`, `(req, res) => …`. A route is a **method on a class**.
- **A `ctx` object or middleware** — there is no context to thread and no pipeline to mount; auth, validation, limits and the error envelope are the framework's.
- **A class no module lists** — refused at boot, by name.
- **`@Inject`, `useFactory`, `forwardRef`** — a dependency is named by its constructor parameter's type and nothing else.
- **An `interface` as a dependency** — it has no runtime existence. Use a class, or an `abstract class` with one listed subclass: the container gives the one owned subclass for it, and refuses by name when there are none or two.
- **NestJS lifecycle names** — `onModuleInit`, `onApplicationBootstrap`, `onModuleDestroy` … are refused at boot. The hooks are `onStart()` and `onShutdown()`.
- **A hand-wired singleton** — `export const notes = new NotesService()`. Mark it `@Injectable()`, list it, and let the container build it once.
- **I/O in a constructor** — it runs while the app comes up, synchronously. Start-up work goes in `onStart()`, which is awaited before the first request.
- **A timer for scheduled work** — a machine that sleeps runs no timer, and three copies run three. Use a [cron](/docs/backend/cron), or a [task](/docs/backend/tasks) for work done once.
- **State in the instance that must outlive a request** — a machine may run several copies, and sleeps; what must be shared goes in the database.
- **A migration file** — there are none. The schema file is the declaration.
- **`try { … } catch { return 500 }`** — throw the error class and let the framework build the envelope; swallowing it turns a `404` into a `500`.
- **Hand-built responses** — no `new Response(...)`, no `JSON.stringify`. Return the value; return nothing for `204`.
- **A secret in the repository** — the secret key and every credential are project secrets the machine starts with; `.env.example` names them, never their values.

## Adding a feature

1. `src/db/public.ts` — declare the table and its policies.
2. `src/modules/<domain>/dto.ts` — the schemas, each a value and a type.
3. `src/modules/<domain>/<name>.service.ts` — the logic; `@Injectable()`, its dependencies as constructor parameters.
4. `src/modules/<domain>/<name>.controller.ts` — the routes; the service in the constructor, never `Database`.
5. `src/modules/<domain>/<domain>.module.ts` — list them; name the module in the root's `imports`.
6. Regenerate the tables' declaration file, if the schema changed ([Database](/docs/backend/database)).
7. Push. The release migrates the database beside the version that serves, then rolls the new version out.

## Give this to your agent

For the full reference — every decorator, every module call, every schema builder — point your coding assistant at **`/llms.txt`**, the index of these docs, or **`/llms-backend.txt`**, the slice for writing a backend: getting started, the backend SDK, the server SDK and machines, in one file. Assistants fetch those when you name them; they do not go looking.

## Related

- [Modules & Dependency Injection](/docs/backend/modules) — the four lists, and what is refused at boot
- [Project Structure](/docs/getting-started/project-structure) — every file of a backend repository
- [Controllers & Routing](/docs/backend/controllers) — the routing and decorator surface
- [Request Validation](/docs/backend/validation) — `@Body`, `@QueryParams`, `@Param`, `@Headers`
- [Responses & Errors](/docs/backend/errors) — the envelope, and the error classes
- [Database](/docs/backend/database) · [Schema](/docs/backend/schema) · [Row-Level Security](/docs/backend/row-level-security) — the database half
- [Testing](/docs/backend/testing) — services and the HTTP layer, with no network



<!-- ===== getting-started/project-structure ===== -->

# Project Structure

A Palbase backend is a directory a [machine](/docs/machines/overview) builds: a TypeScript app that Bun runs as it is, a `Dockerfile` that says how, and a `.env.example` that names what it must be given. Nothing in it is generated by a tool of Palbase's, and nothing is read by its location but the file `src/main.ts` starts with — what exists is what the modules list.

This page walks that directory file by file. The layout is the one Palbase's own examples and Studio's backend use.

## The layout

```text
notes-backend/                       ← the machine's directory (its `path`)
├── Dockerfile                       how the machine builds and runs it
├── .env.example                     the variables it must be given
├── package.json                     its dependencies — `palbase` among them
├── bun.lock                         what `bun install --frozen-lockfile` installs
├── tsconfig.json                    decorators on, with their emitted types
└── src/
    ├── main.ts                      PalbaseFactory.create(AppModule, config)
    ├── app.module.ts                the root module: imports every domain
    ├── db/
    │   └── public.ts                the `public` schema: tables, indexes, policies
    └── modules/
        ├── notes/
        │   ├── dto.ts               schemas: each a value and a type
        │   ├── notes.controller.ts  routes
        │   ├── notes.service.ts     logic
        │   └── notes.module.ts      what the domain owns, and exports
        └── core/
            ├── core.module.ts
            └── health.controller.ts
```

Two rules decide everything else:

- **A class exists when a module lists it.** A `@Controller`, an `@Injectable()` or an `@On` handler that no module lists stops the boot, naming it. A folder grants nothing.
- **A domain is a folder with a module in it**, named in the root module's `imports` (or in the imports of a module the root imports).

## `src/main.ts`

The process starts here, and it is short:

```ts
// src/main.ts
import { PalbaseFactory } from "palbase/backend";
import { AppModule } from "./app.module";
import schema from "./db/public";

await PalbaseFactory.create(AppModule, {
  db: { schemas: [schema] },
  cors: { origins: ["https://app.example.com"] },
});
```

`PalbaseFactory.create` builds every class, runs their `onStart()` and serves — on `$PORT`, which the machine sets. Everything in its config is the backend's own, with a default:

| Option | Default | |
|---|---|---|
| `palbase` | from the environment | The project: `url` (`PALBASE_URL`), `projectId` (`PALBASE_PROJECT_ID`), `secretKey` (`PALBASE_SECRET_KEY`), `webhookSecret` (`PALBASE_WEBHOOK_SECRET`) |
| `auth` | a signed-in user | Every route's auth unless the route or its controller says otherwise |
| `rateLimit` | 300 a minute per caller | Every route's limit unless it says otherwise; `false` for none |
| `bodyLimit` | 1 MiB | The largest request body |
| `cors` | off | The origins browsers may call from: `{ origins: [...] }` or `"*"` |
| `db` | none | The app's database: its `schemas`, and its address unless `PALBASE_DB_URL` says |
| `openapi` | `true` | Serve the app's contract to the platform, which Studio's backend screens read |
| `port`, `host` | `$PORT` (else 8080), `0.0.0.0` | Where it listens |
| `boot` | 5 attempts, 1 s doubling | A start whose `onStart()` fails is tried again from scratch |

A value missing or malformed stops the boot before any request is served, naming both ways to give it. What cannot heal by waiting — a missing setting, a DI mistake — stops at once; a database not up yet is waited for. See [Backend SDK](/docs/backend/overview).

## `src/app.module.ts`

```ts
// src/app.module.ts
import { Module } from "palbase/backend";
import { CoreModule } from "./modules/core/core.module";

// One import per domain: NotesModule joins this list beside CoreModule.
@Module({ imports: [CoreModule] })
export class AppModule {}
```

The root owns nothing of its own here; it is the list of domains. A small app may list a controller or two in it directly.

## `src/modules/<domain>/`

One folder per domain, and in it the four files of [Architecture](/docs/getting-started/architecture): the module, the controller, the service and the `dto.ts`. A domain that needs another's class names it in a constructor, and its module imports the module that exports it:

```ts
// src/modules/core/health.controller.ts
import { Controller, Get } from "palbase/backend";

@Controller("/health", { auth: false })
export class HealthController {
  @Get("")
  health(): { ok: true } {
    return { ok: true };
  }
}
```

```ts
// src/modules/core/core.module.ts
import { Module } from "palbase/backend";
import { HealthController } from "./health.controller";

@Module({ controllers: [HealthController] })
export class CoreModule {}
```

A route's path is its own: `/health` above is the app's, at the machine's address. Two first segments are not yours — `webhooks`, where the platform delivers the app's events and each `@Webhook` class takes a third party's ([Webhooks](/docs/backend/webhooks)), and `_palbase`, the platform's own way in — and a controller mounted under either is refused.

## `src/db/`

One file per Postgres schema, each with a **default export**, `defineSchema("<name>", { tables })`: `public.ts` for `public`, `billing.ts` for a `billing` schema. `src/main.ts` hands them to `db.schemas`.

```ts
// src/db/public.ts
import { defineSchema, defineTable, text, timestamp, uuid } from "palbase/backend";

const notes = defineTable("notes", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    owner: text(),
    title: text(),
    created_at: timestamp().defaultNow(),
  },
});

export default defineSchema("public", { tables: [notes] });
```
 A release migrates the database to them beside the version that serves; there are no migration files ([Schema](/docs/backend/schema), [Schema changes](/docs/backend/migrations)).

`Database.public.<table>` is typed by a declaration file written from those schemas with Palgres' `makeEnvDts` — commit it beside them, and write it again when a schema changes ([Database](/docs/backend/database)).

An app with no database has no `src/db/`, and no `db` in its config.

## `package.json`

```json
{
  "name": "notes-backend",
  "private": true,
  "type": "module",
  "scripts": { "start": "bun run src/main.ts" },
  "dependencies": {
    "palbase": "^0.10.0"
  }
}
```

The SDK is one npm package, `palbase`: `npm install palbase` (or `bun add palbase`). A backend imports the framework from `palbase/backend`, which brings what it is built on — `palbase/server` (the project's modules, as `Palbase`) and `palgres` (the database) — and `reflect-metadata`, which the framework loads itself. The package ships compiled JavaScript with its type declarations; Bun runs the app's own TypeScript as it is. `z` from `palbase/backend` is the zod the framework is built with: import it from there, and the app and the framework agree on one. `palbase init` writes this `package.json`.

## `tsconfig.json`

```json
{
  "compilerOptions": {
    "target": "es2023",
    "module": "esnext",
    "moduleResolution": "bundler",
    "strict": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "allowImportingTsExtensions": true,
    "noEmit": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts"]
}
```

`experimentalDecorators` and `emitDecoratorMetadata` are what make constructor injection work: the container reads each constructor's parameter **types** from the metadata TypeScript emits. Bun reads them from this file. A runner that does not emit the metadata — esbuild, and the tools built on it — leaves the container nothing to read, and the boot stops naming the class and the cure. `noEmit` is right: nothing is compiled ahead of time, and `tsc --noEmit` is the type check.

## `Dockerfile`

```dockerfile
FROM oven/bun:1.4.2-alpine@sha256:d888c0ae6c86d7866ff10c5aafdd9077b36aee6455b33dd270fb93c0dd5cef6f
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile --production
COPY tsconfig.json ./
COPY src ./src
USER bun
CMD ["bun", "run", "src/main.ts"]
```

The machine builds the directory's `Dockerfile` when it has one; without one, Railpack detects what the directory is and plans the image ([Builds](/docs/machines/builds)). A backend ships its own, for two reasons: the decorators need `tsconfig.json` beside the sources, and `bun run src/main.ts` is exactly how the app is meant to start. Pin the base image by digest, so a rebuild of the same commit builds the same image.

The process listens on `$PORT` and stops cleanly on `SIGTERM`: it finishes the requests in flight (20 seconds at most), runs `onShutdown()`, and exits — which is what a rollout asks of the version it replaces.

## `.env.example`

```text
# The names this backend reads. The machine is started with them;
# their values are never in the repository.
PALBASE_URL=
PALBASE_PROJECT_ID=
PALBASE_SECRET_KEY=
```

A build reads it as the list of variables the program needs, and does not roll out until the machine has every one — its own environment, its secret set, or what the platform gives it. It names variables, never their values: commit it, and keep the values in the project's secrets ([Builds](/docs/machines/builds)).

## What the process is given

On a machine, the program finds these in its environment:

| Variable | Set by | |
|---|---|---|
| `PORT` | the platform | The port to listen on |
| `PALBASE_URL` | the platform | `https://<ref>.palbase.studio` |
| `PALBASE_PROJECT_ID` | the platform | The project's id — the `project_id` its access tokens carry |
| `PALBASE_REPLICAS` | the platform | How many copies of the machine run |
| `PALBASE_PLATFORM_SECRET` | the platform | The key the platform signs its calls to the machine with |
| `PALBASE_DB_URL`, `PALBASE_DB_CONNECTIONS` | the platform, given a database | Its address as the app login, and one copy's share of its connections |
| `PALBASE_SECRET_KEY` | the platform | The machine's own secret key of the project (`machine: <name>` among its API keys): `Palbase.*` calls, and checking callers' sessions |
| `PALBASE_WEBHOOK_SECRET` | the platform | The secret the project's events reach the machine signed with, at the endpoint the platform keeps for it |

And what it answers the platform, at paths the internet never reaches: `GET /_palbase/health` — `200` while it serves, `503` while it stops, the machine's health check. Its contract is written by its build (run with `PALBASE_CONTRACT_OUT`, the app writes it and exits), not asked of it while it serves.

## Running it on your own machine

The same directory runs anywhere Bun does:

```bash
PALBASE_URL=https://<ref>.palbase.studio \
PALBASE_PROJECT_ID=<project id> \
PALBASE_SECRET_KEY=pb_<ref>_s… \
PORT=8080 bun run src/main.ts
```

It is a client of the project like any other: the secret key reaches the project's modules, and a caller's token is checked against the project. Studio does not show the project's id, which a machine is given; it is the `project_id` claim of any access token the project issues — the one your web app's session holds. Off a machine there is no `PALBASE_PLATFORM_SECRET`, so the contract is not served. An app with a database also needs `PALBASE_DB_URL`, a database whose schema it can bind to; a release migrates the database before the version that reads it starts — locally, run the app once with `PALBASE_DB_MIGRATE=start` and the owner's address in `PALBASE_DB_OWNER_URL` ([Schema changes](/docs/backend/migrations)).

## In a repository of several apps

A backend need not be a repository of its own. In a monorepo it is one directory of it — the machine's `path` — and an app that imports a sibling package is built with the repository's root as its `context`, its `Dockerfile` copying from there ([Connecting GitHub](/docs/machines/github#one-repository-several-machines)). A push builds the machines whose directory it changed, and no other.

## Related

- [Architecture](/docs/getting-started/architecture) — what goes in each file, and why
- [Quickstart](/docs/getting-started/quickstart) — this layout, end to end
- [Modules & Dependency Injection](/docs/backend/modules) — the four lists, and what the boot refuses
- [Builds, Logs & Rollback](/docs/machines/builds) — what the Dockerfile and `.env.example` decide
- [Machines](/docs/machines/overview) — the environment, the health check, and the port



<!-- ===== getting-started/access-tokens ===== -->

# Access Tokens

An **access token** lets a CI job or an agent act on an organization without a person signing in. It is set as the `PALBASE_TOKEN` secret of the job, and works the way a fine-grained personal token on GitHub or an access token on Vercel does, at the level of the organization.

Admins and owners manage tokens in Studio, under **Organization › Access tokens** (`/organizations/{id}/tokens`). Open the organization switcher at the top left and choose **Access tokens**, or choose it in an organization's left menu, or from **Access** in any of its environments. Members do not see them.

## Creating one

**Create token** asks for:

| Field | Meaning |
|---|---|
| Name | What the token is for, up to 100 characters on one line: `GitHub Actions` |
| Role | **Member** or **Admin**. Never owner |
| Expires after | 7, 30, 90 (the default), 180 or 365 days, or a number of days from 1 to 365 |

The token starts with `pbo_`. Studio shows it **once**, when it is created. Store it as your CI's `PALBASE_TOKEN` secret; you will not see it again. Afterwards the list shows only its last four characters, as `pbo_…a1b2`, with who made it, when it was made, when it expires and when it was last used.

If the answer to creating one is lost, Studio does not send the request again: it asks you to check the list. A token that was made but whose value was lost is deleted and made again.

## What a token can do

- It acts on the organization's projects and environments with its role: member or admin, never owner.
- An admin token opens projects and environments, registers a project's apps and sets them in each environment, and adds an environment's webhook endpoints — what a program that opens a project for each product does with no one signed in, as a Firebase service account adds an app.
- An admin token can get a CLI key. That key lives at most one day and appears in the environment's API keys as `CLI — token <name> (<host>)`.
- An admin token links a GitHub installation that another environment of the organization linked to an environment, with no GitHub sign-in: `POST /v1/environments/{ref}/github/installations` with `{ "installation_id": 123, "from": "<the other environment's ref>" }`. The environment reaches the repositories the GitHub user who linked it there can push to, and repositories created later that they can push to. With `"repositories": ["owner/name", …]` (the CLI's `github:connect --from <env> --repo owner/name`) it reaches those alone, and never one created later: what a program that opens a project for each product gives each product, so that one product's environment builds nothing of another's.
- An admin token mints [environment tokens](#environment-tokens).

## What a token cannot do

- It cannot do what only a person can: manage the organization, its members, roles and invitations, or tokens; create or revoke an environment's API keys; or reach Palbase's own environment.
- It never has more than its creator's **current** role. If the creator becomes a member, their admin tokens stop working at once. If the creator leaves the organization or is deleted, their tokens go with them.

## Deleting one

Deleting a token makes its next request fail, and the CLI keys it got are revoked. Deleting does not undo what the token did: the deploys it made and the settings it changed stay.

The webhook endpoints a token made stay too, and keep receiving events: an endpoint's secret signs what is delivered to it and opens nothing of the platform, so it belongs to its environment, as with Stripe's and GitHub's webhooks. Each endpoint names who made it in **Settings › Webhooks**, and when you delete a token Studio lists the endpoints it made, by address and environment, before you confirm (`GET /v1/orgs/{id}/tokens/{token}/webhooks`). Remove them in their environment if you no longer want them. API keys, which do open the platform, are made by a person only.

An expired token is marked **Expired** in the list and no longer works; delete it to tidy the list.

## Environment tokens

An **environment token** is for a program that works in **one** environment — an AI agent building one product — for a few hours, the way a GitHub App's installation token is for one installation. It starts with `pbe_`, and it is set as that program's `PALBASE_TOKEN`.

It is minted with `POST /v1/environments/{ref}/tokens`, by an admin of the organization (signed in, or with an admin access token) or with the environment's own **secret key** in the `apikey` header and no one signed in:

```json
{ "expires_in_minutes": 60, "name": "agent" }
```

Studio shows it **once**. It lives 60 minutes unless you ask otherwise, 240 at most, and never longer than the access token or key that minted it.

### What it can do

In its environment it does what the role of whoever minted it does there, as their own CLI would: an admin's token reads and changes the environment's machines, databases, users, flags, apps and webhooks, and sets its secrets. A token minted with the secret key acts as an admin. The role is read on every request, so a token never holds more than its minter holds now. Its changes appear in the organization's audit log under its name.

Outside its environment it does nothing. Another environment of the project answers `404`. The project itself and the organization answer `403 token_out_of_scope`, and so does anything that changes the project (its name, its apps, its environments). When it reads its project, it sees only its own environment.

**A full token of the admin role, or one minted with the secret key, is, in what it can reach, an admin of its environment.** It deploys machines, and the code it deploys runs with a secret key of the environment (`PALBASE_SECRET_KEY`, which the platform gives every machine) and reads the environment's secrets. What that code takes, it keeps after the token has ended. So:

- give a full token only to an agent you would trust as an admin of that environment;
- for narrow work, mint a token with [`scopes`](#narrowing-it): no scope deploys anything;
- the closed list below closes the routes that make or show a credential in their own answer, not what deployed code can do.

### What no environment token can do

These routes are closed to every environment token: each one makes an identity, or makes or shows a credential that would outlive the token, in its own answer. Everything else is open at the minter's role, deploying code included (see above).

They answer `403 token_out_of_scope` (or `person_only`), whoever minted the token, in Studio and at the environment's modules alike:

- mint a token: an environment token, or an organization's access token;
- create, revoke or list API keys, or take a CLI key;
- change the organization's members, roles or invitations;
- delete the environment or the project;
- link a GitHub installation from another environment;
- sign in as one of the environment's users, or make a password reset for one;
- set a user's password or email: create or import users, change a user's email (test users are its to make);
- create an OAuth client or a service account, rotate one's key, or change where an OAuth client's codes go;
- define a role, or give or take one from a user; make, change or remove an auth hook, whose claims go into every user's token, an app's role among them;
- create a database, or make new passwords for one: both answers show its passwords;
- read a secret's value, a task's payload (it may carry a token) or a coupon's one-time codes. Setting a secret is allowed;
- set or remove a sign-in provider's client secret, or change which apps' sign-ins with it the environment takes (its client ids);
- bring or remove a message provider (where the project's mail and texts are sent, and with whose credentials);
- override or remove a template that carries a sign-in or reset credential — a reset or magic-sign-in link, a verification or invitation link, a one-time code — on email, SMS or WhatsApp. The app's own notification templates stay open, so an agent still brands them.

The last three close the roundabout ways to a user's own credential: a sign-in provider's client of one's own, a message provider aimed at a server of one's own, or a reset template that tucks the link into one it fetches, would catch a sign-in the way signing in as the user would.

The sender's own settings stay open — a token sets the project's `from` address and reply-to (`/notify/settings`), and the site and redirect URLs a new product signs in against (`/admin/auth-settings`). These change where a link points, but no credential leaves unless the user follows the link themselves.

Each module refuses these itself, on the route it matched, so writing the path another way does not get past this list: an escape, a dot segment, other letter case or a slash at the end all name the same thing.

A link the token signs does not outlive it either. A signed download or upload URL, a package's upload link, a link to hand over an Apple or Stripe key, a signed bundle's download link and the link that connects GitHub all end no later than the token. The answer's `expires_at` says when.

Test users, and the sign-ins made for them, are open: they are test fixtures, and `auth:test-users` is for them.

### Narrowing it

`scopes` narrows a token to what they name, and nothing else is reached, a read as much as a change:

```json
{ "scopes": ["machines:read", "machines:logs", "auth:test-users"], "expires_in_minutes": 60, "name": "agent" }
```

| Scope | What it reaches |
|---|---|
| `machines:read` | The environment's machines, their builds, crons and queues (not a task's payload), contracts and metrics |
| `machines:logs` | A machine's logs and its builds' logs |
| `apps:sync` | What `palbase apps:sync` reads: the project's apps as they are in this environment, their client settings, the machines' contracts |
| `auth:test-users` | The environment's test users: made with their sign-ins, listed, deleted. Not other users |
| `support` | A question to Palbase's support line (`palbase support:ask`, `POST /ai/support-questions`): an agent asks Palbase what it cannot find out, not the person it works for |

### When it stops working

It stops working when it expires, when it is revoked (`DELETE /v1/environments/{ref}/tokens/{id}`, by an admin, by a token of an admin's role, or by a narrowed token itself), and when what minted it no longer holds: the admin is no longer an admin, the access token is deleted, or the secret key is revoked (within a minute). `GET /v1/environments/{ref}/tokens` lists the live ones by their last four characters.



<!-- ===== getting-started/billing ===== -->

# Billing

Each environment is billed on its own, by the calendar month (UTC): it has its own plan, its own credit and its own free quota, as a project of its own. The organization holds only what pays — its cards, its billing details and its bank transfers — and an environment's credit is never another's unless an owner or an admin moves it. Each environment is on one of two plans:

- **Free**: charged nothing. Every item has a free quota each month, and past it the environment is slowed or stopped ([Usage & Limits](/docs/getting-started/usage-and-limits#what-a-free-project-gets)); its machines and databases are of the free sizes. Every environment starts on Free. Until one of the organization's environments has paid a top-up, a person opens at most 2 projects of 2 environments each — one deleted counts until the month is out, so deleting and opening again brings no new month of free quotas — and a Free project is opened by a person, not an organization's access token.
- **Pay as you go**: the environment has credit, loaded ahead in US dollars; its first top-up by card moves it there. What it uses past its own free quota is priced and taken from its credit as it is used, every few minutes; it may open every size of machine and database. There is no monthly fee and no bill afterwards.

When an environment's credit runs out, or its month reaches its limit, only it falls back to the free quotas; the organization's other environments go on. The prices, the free quotas and the terms are on the [billing terms](https://palbase.studio/legal/billing) page.

## Opening the payment account

An owner or admin opens it in Studio, on the organization's **Billing** page, by accepting the terms for the organization (Studio records who, when, and which version). Nothing is charged. From then on each environment is moved to Pay as you go by its first top-up by card, of $10 or more: **Billing › Environments › Upgrade** on the environment, paid on Stripe's page the first time, which asks for the card, the billing address and, for a business, its VAT number, and saves the card for the organization. Tax is added on top as the billing address requires. Stripe emails an invoice for every top-up, naming its environment; **Billing › Invoices** lists them.

Once one of its environments has paid a top-up, the organization is not held to the Free limits on projects and environments.

## Top-ups

Each environment is topped up on its own, from **Billing › Environments › Manage**:

- **Now**: **Top up** — a usual amount or any other, from any of the organization's saved cards, or another card on Stripe's page (it is saved for next time).
- **Automatic**: when the environment's credit comes under a threshold, it is topped up by an amount, at most once an hour; on by default ($20 when under $5), and never past what the environment's monthly limit still needs. **Automatic top-up** changes both or turns it off. It is taken from the organization's default card; when that card declines, the same invoice is paid from the organization's other cards in turn — it is paid once at most. When every card declines, it is tried again once a day for two days, the owners and admins are emailed each time, and while a card declined today no other environment's automatic top-up tries it again that day. A declined invoice is voided (**Invoices** shows it as declined), and each try is a new one. A refund or a dispute of an environment's top-up turns its automatic top-up off.
- **By bank transfer**: **Top up › Bank transfer** makes an invoice with bank details of the organization's own; the environment gets the amount when the transfer arrives — one on Free is then moved to Pay as you go with **Manage › Move to Pay as you go**. What the organization's transfers paid past their invoices stays with it, and pays the next top-up of any of its environments first, when it covers the whole of it — a card is charged only otherwise; what is left of it 75 days after it arrived, Stripe returns to the account it came from. An organization with no card is topped up automatically from what its transfers left, while it covers the top-up.

Credit can be spent for 12 months; what is left of it then expires. The environment's sheet lists each top-up, bonus and credit moved in with what is left of it and when it expires; the one closest to expiring is spent first.

## Moving credit between environments

An owner or an admin moves an environment's credit to another environment of the same organization: all of it, or an amount (**Manage › Move credit**). Each part keeps its expiry. Credit never leaves the organization, and a member cannot move it. An environment whose credit is moved away entirely is moved to Free.

Deleting an environment, or a project and its environments, offers to move their credit to another environment first. A deleted environment keeps its credit until it is purged, 7 days after it was deleted — **Billing › Environments** offers to move it until then — and what is left of it is lost when it is purged. The organization's owners and admins are emailed when an environment is deleted holding credit, with how much and when it is lost.

## Cards and billing details

**Billing › Payment** lists the organization's cards, shared by its environments. **Add card** saves one on Stripe's page — nothing is charged — and makes it the default unless you say otherwise; any other card can be made the default or removed. The default card is removed only when it is the last one; the automatic top-ups then wait for a card, or a bank transfer.

**Edit billing details** sets the name, address and tax number (a VAT number in the EU) the next invoices are made out to. The address is checked for tax at once: one that cannot be placed is refused, and nothing changes.

## What is charged

**Usage** shows the month: each environment's plan and what it used, and to an owner or an admin what that came to before its free quota (gross) and what it was charged past it. Any member reads what was used; the amounts are an owner's or an admin's. **Download CSV** gives it item by item — a line per environment and item, units, gross and charged, with its total and what its credit gave — for an organization that bills its own customers per environment.

Palbase AI's models, on Palbase's own provider keys, are their provider's price and 10%, and each month brings each environment $1.00 of them free. A project may have a monthly AI budget of its own ([AI](/docs/backend/ai#what-it-costs)). A call under the project's own provider key is the provider's to bill. Requests, push notifications, and email, SMS and WhatsApp sent through the project's own provider are not charged.

## Each environment's own

For each environment, an owner or an admin can, on **Billing › Environments › Manage** or from the API:

- set a **monthly limit**: at it, the environment falls back to the free quotas until the month ends, while the others go on;
- move it to **Free**: it is charged nothing and held to the free quotas; its credit stays, spent once it is back on Pay as you go;
- **freeze** it: its requests are refused (`403 project_frozen`), its machines and databases stop, its data is kept, and only what it stores is charged. Unfreezing brings it back.

## When an environment's credit runs out

Nothing is owed. What it pays for stops: its machines and databases of a paid size stop (`402 machine_not_paid` while it lasts), Palbase's AI models past its month's free dollar are refused (`402 ai_payment_required`; a project's own provider key goes on), and it is held to its free quotas, as on Free; what is within them goes on. Usage measured in the few minutes before it stopped is taken from its next top-up; what it uses after it is not charged. The organization's other environments are not touched. A top-up brings it back by itself.

## Emails and webhooks

The organization's owners and admins are emailed when an environment's credit comes under the days of spend set for it (3 by default, in **Automatic top-up**) — at most once a day —, when it runs out, when its automatic top-up is declined, and when its month reaches its limit — and when an environment is deleted holding credit, a few minutes after, unless it was moved or the environment restored meanwhile. What happens at once to several environments comes in one email, naming each.

Each environment's own webhooks are told the same as it happens, as `billing.low_balance`, `billing.balance_exhausted`, `billing.topup_failed` and `billing.limit_reached` ([Webhooks](/docs/server/webhooks#the-events)) — an organization that runs its customers' apps tells them from there. They carry no amount: the amounts are the organization's owners' and admins', on its bill.

## From the terminal

The CLI does what the Billing page does, as you or with an admin's [access token](/docs/getting-started/access-tokens) in CI — save opening the payment account and paying on Stripe's page, which are a person's:

```bash
palbase billing                                   # each environment's plan, credit, month and limit
palbase billing:env shop/staging                  # an environment's own: its plan, credit, limit and automatic top-up
palbase billing:env shop/staging --limit 25 --auto-topup yes --threshold 10 --amount 50
palbase billing:env shop/staging --plan free      # or pay_as_you_go; --frozen yes|no
palbase billing:topup shop/staging 20             # from the saved card, $10 to $10,000; a Free one moves to Pay as you go
palbase billing:bank-transfer shop/staging 500    # an invoice to pay by bank transfer
palbase billing:transfer shop/staging shop/main 5 # credit moved, with its expiry; all of it when no amount is named
palbase billing:ledger shop/staging --limit 50    # every change of its credit, newest first
palbase billing:invoices                          # the top-ups' invoices, each with its environment
palbase billing:charges --period 2026-10 --csv    # the month's charges by environment and item, as the page downloads them
```

The environment is `project/environment` or its ref, else the one chosen for the directory; the organization is `--org`'s, else that environment's. Amounts are in US dollars, to the cent. A member reads the plans; the money is an owner's or an admin's.

## The API

What Studio's Billing page does, an admin's [access token](/docs/getting-started/access-tokens) does too — save opening the payment account and paying on Stripe's page, which are a person's. The calls are on Studio's API, under the organization:

| Call | What it does |
|---|---|
| `GET /v1/orgs/{id}/billing` | The payment account, and each environment's plan, credit, month and limit |
| `GET /v1/orgs/{id}/billing/environments/{ref}` | An environment's own: its plan, credit, automatic top-up, limit and month |
| `PATCH /v1/orgs/{id}/billing/environments/{ref}` | Its `plan` (`free`, `pay_as_you_go`), `frozen`, `monthly_limit_micros` (`null`: none), `auto_topup`, `auto_threshold_micros`, `auto_amount_micros`, `low_balance_days` |
| `POST /v1/orgs/{id}/billing/environments/{ref}/topups` | A top-up of it from what bank transfers left, else the default card or the one named: `{ "amount_micros": 20000000, "payment_method": "pm_…" }`; `"plan": "pay_as_you_go"` moves a Free one with it |
| `POST /v1/orgs/{id}/billing/environments/{ref}/bank-transfers` | An invoice to pay by bank transfer, for it |
| `GET /v1/orgs/{id}/billing/environments/{ref}/ledger` | Every change of its credit; `?kind=topup,bonus,transfer` for the credits alone |
| `POST /v1/orgs/{id}/billing/transfers` | Credit moved: `{ "from": "<ref>", "to": "<ref>", "amount_micros": 5000000 }`, all of it without `amount_micros` |
| `DELETE /v1/projects/{id}?move_credit_to=<ref>` | Deletes a project, its environments' credit moved first; `DELETE /v1/environments/{ref}?move_credit_to=<ref>` an environment |
| `GET /v1/orgs/{id}/billing/cards` | The cards, the default first |
| `PUT /v1/orgs/{id}/billing/cards/{card}/default` | Makes a card the default |
| `DELETE /v1/orgs/{id}/billing/cards/{card}` | Removes a card; the default only when it is the last |
| `GET` / `PUT /v1/orgs/{id}/billing/customer` | The name, `address` and `tax_id` (`{ "type": "eu_vat", "value": "…" }`, or `null`) the invoices are made out to |
| `GET /v1/orgs/{id}/billing/charges?period=2026-10` | The month's charges, by environment and item: units, gross and charged |
| `GET /v1/orgs/{id}/billing/charges.csv?period=2026-10` | The same, as CSV |
| `GET /v1/orgs/{id}/billing/invoices` | The top-ups' invoices, each with its environment; `?environment=<ref>` one's alone |

Amounts are in micro-dollars (1,000,000 is $1), in whole cents. A member reads the plans and what was used; amounts and money are an admin's.

## Related

- [Usage & Limits](/docs/getting-started/usage-and-limits) — what is metered, and what a free environment gets
- [Organizations](/docs/getting-started/organizations) — roles, and who is emailed
- [Access Tokens](/docs/getting-started/access-tokens) — an admin token for the API



<!-- ===== getting-started/usage-and-limits ===== -->

# Usage & Limits

Every environment's use is metered by the calendar month (UTC): what its modules did, what its machines and databases ran, and what it sent. Studio shows it on the project's **Settings › Usage**, environment by environment.

An environment is held to limits of three kinds, and each one says so in its answer:

- **Rates**, per second: a call over one is refused for that second (`429` with `Retry-After: 1`).
- **Limits on the month**: a limit set on one of the environment's metrics refuses that use, or only counts it, until the month ends.
- **What a free project gets**: its traffic is slowed past 5 GB, its chat messages past a million a month or 1 GiB kept, and a free database sleeps past its 400 hours. None of them stops the project or loses its data.

## Where usage is shown

**Project › Settings › Usage** shows one environment at a time (choose it at the top when the project has more than one) over the last 3, 6 or 12 months:

- this month's API requests, monthly active users, stored data and machine hours, each beside its months;
- **Limits**: each limit set on the environment, with what this month has used against it, and **Blocked** once a limit that refuses is reached;
- a chart per month of requests, active users, notifications sent by channel, stored data, download traffic, realtime messages, analytics events, machine hours, machine internet traffic, response traffic and database hours by size;
- **Every metered item**: every metric the environment used, this month and the month before.

Every member of the organization reads it ([Organizations](/docs/getting-started/organizations#roles)). The organization's owners are also mailed when a free project has sent 80% of its month's traffic and when it has sent all of it, and when a free database has been awake 80% of its hours and all of them.

## What is metered

| Metric | What counts |
|---|---|
| `requests` | **API requests**: each request to the environment's address that a module answers. Not among them: the cache's calls, the stores' reports to purchases (`/purchases/webhooks/…`), and the files the platform moves for a module's own work, such as an AI workspace's |
| `auth.mau` | **Monthly active users**: the users who signed in or kept a session alive in the month |
| `notify.email`, `notify.push`, `notify.sms`, `notify.whatsapp` | **Email**, **Push**, **SMS** and **WhatsApp** sent: an email through any sender (those through Palbase's shared sender are also `notify.email.shared`), a push delivered to a user on any of their devices, a text or a verification code, a WhatsApp message |
| `storage.bytes` | **Stored data**: the objects and their renditions, the month's largest |
| `storage.egress` | **Download traffic**: what storage sent, a part of response traffic |
| `storage.operations` | The requests storage served |
| `storage.transforms` | **Image transformations**: a picture made over from an original (resized, cropped, re-encoded); one answered from what was made before is not one |
| `cache.bytes`, `cache.egress` | **Cache memory**, the month's largest, and **Cache reads**, a part of response traffic ([Cache](/docs/backend/cache)) |
| `realtime.messages` | **Realtime messages**: each one delivered — a broadcast to ten subscribers is ten |
| `realtime.connections` | Realtime connections open at once, the month's largest |
| `messaging.messages` | **Chat messages**: each message the project's people, or its server, sent in its conversations; one sent again with the same client id is one |
| `messaging.bytes` | **Chat message storage**: what the project's messages weigh where they are kept — each one's sealed text and 768 bytes for its row and indexes — the month's largest |
| `flags.reads` | The flag reads clients made, answered in full or not modified |
| `analytics.events` | **Analytics events**: captures, identifies, aliases, screens and page views (setting a person's properties is not counted) |
| `analytics.perf`, `analytics.traces`, `analytics.console` | Performance samples kept, request traces taken, console records kept ([Analytics](/docs/analytics/overview)) |
| `machines.seconds` | **Machine hours**: how long the machines were awake, each copy counted; `machines.seconds.<size>` the same by size |
| `machines.egress` | **Machine internet traffic**: what the machines sent to the internet |
| `edge.egress` | **Response traffic**: what the environment's answers sent its clients, its modules' and its machines' alike |
| `machines.builds.seconds` | **Build hours** |
| `machines.images.bytes`, `machines.logs.bytes` | **Machine images** kept, the month's largest, and **Machine logs** kept |
| `databases.seconds.<size>` | **Database hours**: how long the databases of each size were awake |
| `databases.bytes`, `databases.backups` | What the databases hold, and what their backups hold, the month's largest |
| `databases.traffic` | What the databases read from and wrote to their disks |
| `databases.egress` | **Database client traffic**: what the databases sent clients that connect to them over their own addresses (`psql`, a backend on your computer) |
| `ai.tokens.<provider>.<model>.<kind>` | **AI tokens** with Palbase's provider keys, by model and kind: `input`, `image_input`, `output`, `cache_read`, `cache_write`. A model used with the project's own provider key is the provider's to count |
| `ai.images.<provider>.<model>` | **AI images** made, by model |
| `ai.machines.seconds`, `ai.voice.seconds`, `ai.web_search.calls` | **AI workspace hours**, **AI voice hours** and **AI web searches** |

A metric that is "the month's largest" is a level, not a sum: what the environment held at its most during the month.

## Rates

| What | How much | Past it |
|---|---|---|
| The environment's requests | 200 a second, unless Palbase set another | `429 rate_limited`, `Retry-After: 1` |
| What apps send to analytics | 1,000 events, samples, traces and records a second, counted apart from the requests | `429 rate_limited` |
| The cache's calls | As many a second as the requests, counted apart from them; 8 MiB read and 2 MiB written a second | `429 rate_limited` |
| Your backend's own routes | What each route's `rateLimit` says ([Controllers & Routing](/docs/backend/controllers)) | `429 too_many_requests` |

Realtime has rates of its own, which a project may lower ([Web Realtime](/docs/web/realtime)), and so do sign-ins and the messages a project sends. The SDKs send a refused call again on their own, waiting what `Retry-After` asks, when it is a read or a write that cannot be done twice ([Server SDK](/docs/server/overview#retries)).

## Limits on the month

A limit on the month names one metric of one environment and how much of it the month may use, and is one of two kinds: one that **refuses** past it, and one that only **counts**. Palbase sets them; the **Limits** panel lists those set on the environment. A month's use starts again at 00:00 UTC on its first day.

When a limit that refuses is reached, that use is refused until the month ends, and the refusal's `Retry-After` is the seconds until then:

| Limit on | What is refused |
|---|---|
| API requests | Every request to the environment's address but those not counted (above): `429 quota_exceeded` |
| Monthly active users | New sign-ups: `403 signups_closed`. Sign-ins go on: the people already counted keep their accounts |
| Email, push, SMS or WhatsApp | Sending on that channel: `429 quota_exceeded` |
| Stored data | Writing to storage: `429 quota_exceeded`. Reads go on |
| Realtime messages or connections | A new socket: `429 quota_exceeded`, with `Retry-After: 3600` (an hour, not the month's end); and a server's broadcast: `429 quota_exceeded` |
| Flag reads | Reading the flags: `429 quota_exceeded` |
| Chat messages, or what they weigh | Sending a message, a person's or the server's: `429 quota_exceeded` |
| Analytics events, samples, traces or console records | Sending that kind: `429 quota_exceeded` |
| Machine hours | The machines: they are stopped, dedicated sizes too, and a request to one, a new machine, a cron or a task is `429 quota_exceeded` |

A limit that counts refuses nothing: the use goes on and is metered.

## What a free project gets

An environment is free while it is on the Free plan — every environment starts on it — and while its credit has run out or its month is at its monthly limit ([Billing](/docs/getting-started/billing)). Each environment is free on its own: one running out holds no other.

- **Sizes.** Its machines are of the `shared-256` size, the one free machine size, and it has one database at most, of the `free` size: a project holds one database of a free size at a time ([Databases](/docs/machines/databases#sizes)). Every other size is paid for: opening a machine or a database of one, or moving one to it, is `403 size_not_available`. `palbase machines:sizes` and `palbase databases:sizes` list the sizes and which of them the environment may open now ([Machines](/docs/machines/overview#sizes)).
- **Traffic.** It sends 5 GB a month at full speed: its machines' internet traffic and its response traffic together. Past it, until the month ends, its machines' traffic and answers and the files its storage hands out go at about 256 kbit/s; nothing is stopped, and the API's other answers are not slowed. A slowed project's downloads are paced, and one more than it may have under way at once is `429 rate_limited` with `Retry-After`. See [Reaching the internet](/docs/machines/overview#reaching-the-internet).
- **Chat messages.** 1 million messages a month, and 1 GiB of them kept. Past either, until the month ends, the project's messages go at about one a second, all its people and its server together: a send waits its turn, 10 seconds at the most, and one whose turn is further off is `429 slowed` with `Retry-After` — the SDKs keep it in their outbox and send it again. No message is lost, and reading, syncing and everything else go on at full speed. What is kept counts at its month's largest, so a project that keeps more than 1 GiB is slowed again early each month: remove old messages, or set the project's retention ([Messaging](/docs/messaging/overview#the-projects-settings)), to stay under it.
- **A free database** is awake 400 hours a month at most. Past them it sleeps until the month ends, refusing connections, with its data kept; from then its next connection wakes it.
- **AI.** $1.00 of Palbase's models a month, at the provider's price and 10%. Past it, until the month ends, a call to them is `402 ai_payment_required`; a call under the project's own provider key goes on ([AI](/docs/backend/ai#what-it-costs)).

An environment on Pay as you go with credit is never slowed for its traffic, and its machines and databases may be of any size; a database of the `free` size keeps its 400 hours whoever holds it. What it uses past its own free quotas is charged from its own credit ([Billing](/docs/getting-started/billing)).

## Each module's own limits

| Module | Limits |
|---|---|
| Storage | 5 GiB an object unless the bucket says less; a signed URL lives 7 days at most ([Storage](/docs/backend/storage)) |
| Cache | 25 MiB of entries, the ones nearest their end dropped to make room; 512 KiB a value ([Cache](/docs/backend/cache)) |
| Tasks | 100,000 tasks not yet done, or 256 MiB of what they carry ([Tasks](/docs/backend/tasks)) |
| Machines | 5 machines, 1 to 5 copies each, 50 builds a day, logs kept 7 days ([Machines](/docs/machines/overview#limits)) |
| Databases | 3 a project, one of them of a free size at a time; a database full to its size's storage turns read-only ([Databases](/docs/machines/databases#sizes)) |
| Analytics | Events kept 90 days unless changed, 365 at most ([Analytics](/docs/analytics/overview#how-long-it-is-kept)) |

## Related

- [Billing](/docs/getting-started/billing) — each environment's plan and credit, and what is charged
- [Logs](/docs/getting-started/logs) — every request, with its status
- [Organizations](/docs/getting-started/organizations) — who sees the usage page, and who is mailed
- [Machines](/docs/machines/overview) — sizes, sleep, and traffic to the internet
- [Databases](/docs/machines/databases) — sizes, sleep and storage



<!-- ===== getting-started/logs ===== -->

# Logs

Studio's **Logs** page lists what happened in an environment, newest first, one category at a time:

| Category | A line is | Its source | Its level |
|---|---|---|---|
| **Requests** | A request to the environment's address, whichever module it went to, as the platform's edge answered it — refused ones too | The module: `auth`, `storage`, `realtime`, `flags`, `notify`, `analytics`, `secrets`, `machines` (databases included), `stores`, or `other` for a path no module answers | Info below 400, warn a 4xx, error a 5xx or no answer at all |
| **Auth** | An event of auth's audit trail: a sign-in, a sign-up, a password or session change | The event, such as `auth.login.success` | Warn a failure |
| **Notifications** | An email, SMS, WhatsApp message or push sent, and what became of it | The channel | Error one that did not arrive (failed, bounced, rejected, expired) |
| **Machines** | What a machine wrote, its migration runs included ([Builds, Logs & Rollback](/docs/machines/builds#logs)) | The machine | The level the line says of itself |
| **Builds** | A build of a machine's commit | The machine | Error a failed build, warn a cancelled one |

Each category is narrowed by text, by source and by level, over the last 15 minutes up to the last 7 days. **Live** reads again every 5 seconds; **Paused** holds the list still while you read it. A line opens whole, each of its fields with a copy button. The address of the page carries the category and the filters, so a view can be shared.

## Request lines

A request line holds what the edge knows of the request, and nothing it carried:

| Field | |
|---|---|
| `ts` | When the request arrived |
| `module` | The module it went to |
| `method`, `path` | The path **without its query**: a signed URL's signature and a token travel in the query, so it is never kept. Past 2,048 bytes it is cut |
| `status` | What the client was answered; `0` when it got no answer |
| `duration_ms` | Until the last byte of the answer was sent |
| `client_ip`, `user_agent` | Who asked: the client's address as the edge saw it, and its user agent (its first 512 bytes) |
| `request_id` | The `X-Request-Id` the client was answered with — the one to quote when asking about a request |
| `flags` | Present when the request ended short of a module's answer: `UAEX` the key or rate check refused it, `NR` no module answers its path, `UF` or `UH` the module could not be reached, `UT` it did not answer in time, `DC` the client went away |

Not its headers, not its body. A line is kept **7 days** and deleted within a day after; only the project it was made for reads it. Anyone can send a project requests, and a refused one is a line too: under a flood, each of the platform's edges keeps about 1 MiB of a project's lines a second and drops the rest, so a flood to one project does not cost the others their lines.

From a server, `GET /analytics/requests` with the project's secret key answers the same lines, newest first:

| Query | |
|---|---|
| `window_seconds` | How far back, 1 to 604,800 (a week); an hour when left out |
| `module` | One module's requests only |
| `level` | `info`, `warn`, `error`, one or more, comma-separated |
| `q` | Text found in the path or the user agent, or a request id or a client address, exactly |
| `limit` | How many lines at most, 1 to 500 (100 by default) |
| `cursor` | The `next_cursor` of the page before; absent on the last page |

```ts
// scripts/errors.ts
type RequestLine = { ts: string; module: string; method: string; path: string; status: number; request_id: string };

const res = await fetch(`${process.env.PALBASE_URL}/analytics/requests?window_seconds=600&level=error`, {
  headers: { apikey: process.env.PALBASE_SECRET_KEY! },
});
const { requests } = (await res.json()) as { requests: RequestLine[]; next_cursor?: string };

for (const r of requests) console.log(r.ts, r.status, r.module, r.method, r.path, r.request_id);
```

A secret key never goes in a browser: a call that carries one from a web page is refused (`401 secret_key_in_browser`).



<!-- ===== cli/overview ===== -->

# CLI

`palbase` is the command line for your organizations, projects and environments. It comes in the same npm package as the SDKs: `npx palbase <command>` runs it with nothing installed, and in a project that depends on `palbase` it runs the version installed there.

A machine is deployed by a push to its branch, which builds and rolls it out ([Builds, Logs & Rollback](/docs/machines/builds)); `palbase machines:deploy` builds the branch's head again, for a push GitHub did not deliver. The CLI does what a push does not — registering client apps and writing their settings, the purchase catalog, an environment's auth, storage, flags and notification settings, tokens for CI and agents, a database's dumps and restores. It is also how a script, a CI job or an AI agent works with Palbase. Every command is in the [CLI reference](/docs/cli/reference).

## Signing in

```sh
npx palbase login
```

`login` shows a one-time code and opens Studio, where you approve it while signed in. On a computer with no browser — a server, a container, an agent's sandbox — `palbase login --no-browser` prints the address to open on any device. The CLI then holds a session of yours: Studio lists it beside your other sessions, and ending it there signs the CLI out. `palbase logout` ends it from the terminal, and `palbase whoami` prints who the CLI acts as.

## Choosing an environment

Most commands act on one environment of one project. `palbase use` chooses it for the directory you are in:

```sh
palbase use shop/main          # the project "shop", its environment "main"
palbase use acme/shop/staging  # when two organizations have a project named "shop"
palbase status                 # who you are there, its machines and databases
```

The choice is kept on this computer, not in the repository, so two checkouts of the same project can each act on their own environment. Commands run in that directory, or one under it, act on it. `-P <project>` and `-E <env>` choose for a single command instead:

```sh
palbase flags:list -P shop -E staging
```

A change to a production environment asks for confirmation; `--yes` gives it in a script. `--non-interactive` makes a command refuse anything that would ask, and `--json` prints the answer as JSON for a program to read. These are the [global flags](/docs/cli/reference#global-flags) every command takes.

## Projects, environments and keys

```sh
palbase projects:create shop                 # a project with its first environment, main; its keys are printed
palbase envs:create staging --from main      # another environment of the project chosen here
palbase keys:create --kind publishable --label web
palbase open auth                            # the environment's Auth section in Studio
```

`palbase projects:list` and `palbase envs:list` list what you can reach. A new key's value is printed once; `palbase keys:list` lists the environment's keys without their values, and `palbase keys:revoke <key-id>` refuses whatever holds one from its next request.

Two environments of a project drift apart as settings change in one and not the other. `palbase config:diff --from staging --to main` shows how their module settings differ — auth, storage, flags, notifications, realtime, analytics — and `palbase config:copy --from staging --to main` makes the second equal to the first; secrets are not copied, only named. `palbase types:pull` writes the environment's secret, flag, bucket and role names into `palbase/palbase-env.d.ts`, so `Secrets.get`, `Flags` and `Storage.buckets` accept those names and no others.

## Running a backend on your computer

`palbase init` starts a backend on `palbase/backend` in the current directory: a health route, its module, its tests and a Dockerfile; `--db` adds a schema with its routes and their test ([Project Structure](/docs/getting-started/project-structure)). Nothing that already exists is written over.

The backend needs the environment's address and a key to run. Two commands give it them:

- `palbase env:pull` writes them into `.env.local`, between markers it owns; the rest of the file stays as it is. The key is yours, lasts 30 days, and is revoked by `palbase logout`. No secret's value is written: the app reads the project's secrets when it starts.
- `palbase run -- bun dev` runs a command with them in its environment and writes nothing to disk.

`palbase test` runs the backend's tests the way the platform runs them before a build takes traffic: test users are made for the run, their tokens are handed to the command, and they are deleted when it ends ([Testing](/docs/backend/testing)).

```sh
palbase test --users alice,bob --base-url http://localhost:8080 -- bun test ./tests
```

## In CI

A CI job signs in with an organization's access token instead of a person: set it as the job's `PALBASE_TOKEN` secret, and the CLI acts with it at its role — member or admin — on every project of the organization.

```sh
palbase tokens:create github-actions --role admin --days 90
```

The value is printed once. Tokens are listed with `palbase tokens:list` (never their values) and revoked with `palbase tokens:revoke <name>`; [Access Tokens](/docs/getting-started/access-tokens) says what a token may and may not do. In CI, `palbase apps:sync --check` exits 1 when the app's committed settings and clients are not what the project gives now.

## For an AI agent

An agent that works on one environment gets an environment token rather than an organization's: it does what your role does in that environment alone, for a few hours, and never makes or shows a standing credential, changes people or roles, or deletes a project or an environment.

```sh
palbase env:tokens:create --minutes 120 --name coding-agent
palbase env:tokens:create --scope machines:read,machines:logs   # only read machines and their logs
```

Give the agent the value as `PALBASE_TOKEN`. `--scope` narrows it to `machines:read`, `machines:logs`, `apps:sync`, `auth:test-users` or `support`. `palbase env:tokens:list` lists the live ones and `palbase env:tokens:revoke <id>` ends one at its next request. The docs an agent reads are at `/llms.txt`, with every page in one file at `/llms-full.txt`.

## Searching the docs

`palbase docs:search` finds what these docs say about what you need — by its meaning, in your own words; ask in English, the docs' language — and prints the sections that answer it, each with its address and its text:

```sh
palbase docs:search "<what you need>"
palbase docs:search "<what you need>" --limit 3 --json
```

Say what you need as a question of your own — what you are trying to do, not the words of a heading — and the search finds the sections that mean it.

It needs no sign-in, and a page changed here is found by what it says now within minutes. A caller searches 10 times in ten seconds, 30 a minute and 300 an hour: a sign-in or `PALBASE_TOKEN`, sent when there is one, as itself, and a search with neither by its address. When many search at once, a search waits its turn for a few seconds, or is told to search again in a moment. `--json` prints what the search answered — what an agent reads.

## Asking Palbase's support line

What the docs do not answer — a command or call that fails with nothing to act on, a page that is wrong or missing, something Palbase seems not to do — goes to Palbase's support line:

```sh
palbase support:ask "machines:deploy fails with build_failed and the log ends at npm ci — what is wrong?"
```

The answer comes from these docs and from what the environment shows you: its machines, their last builds and the end of a failed build's log, read with your own sign-in or token and sent with the question. When the answer is that Palbase lacks something, the CLI prints a case number: Palbase has it, and you are told by email when Palbase closes it. Keys, tokens and passwords in a question are masked before anyone reads it. An agent asks with an environment token that has the `support` scope. A person asks 30 questions an hour, a project 60.

## What the commands cover

| Group | What it does |
|---|---|
| [`orgs`](/docs/cli/reference#orgs), [`projects`](/docs/cli/reference#projects), [`envs`](/docs/cli/reference#envs) | Organizations and their members, projects, environments ([Organizations](/docs/getting-started/organizations)) |
| [`tokens`](/docs/cli/reference#tokens), [`keys`](/docs/cli/reference#keys), [`env`](/docs/cli/reference#env) | Access tokens, an environment's API keys, environment tokens and `.env.local` |
| [`apps`](/docs/cli/reference#apps) | The apps that call the project, and the settings and backend clients written into their repositories ([Client Apps](/docs/apps/overview)) |
| [`auth`](/docs/cli/reference#auth) | Sign-in providers, settings, roles, hooks, users, the audit trail ([Auth](/docs/auth/overview)) |
| [`storage`](/docs/cli/reference#storage), [`flags`](/docs/cli/reference#flags), [`notify`](/docs/cli/reference#notify), [`realtime`](/docs/cli/reference#realtime), [`analytics`](/docs/cli/reference#analytics), [`secrets`](/docs/cli/reference#secrets), [`webhooks`](/docs/cli/reference#webhooks) | Each module's settings and data |
| [`purchases`](/docs/cli/reference#purchases) | The catalog, paywalls, the stores' connections and customers ([Purchases](/docs/purchases/overview)) |
| [`stores`](/docs/cli/reference#stores) | Builds, testers and review on TestFlight and Google Play ([App Distribution](/docs/distribution/overview)) |
| [`github`](/docs/cli/reference#github), [`machines`](/docs/cli/reference#machines) | Connecting GitHub, machines, their builds, logs, crons and tasks ([Machines](/docs/machines/overview)) |
| [`databases`](/docs/cli/reference#databases), [`db`](/docs/cli/reference#db) | Databases, their backups, connection addresses, `psql`, dumps and schema plans ([Databases](/docs/machines/databases)) |
| [`config`](/docs/cli/reference#config), [`types`](/docs/cli/reference#types) | Comparing and copying module settings between environments, and the environment's names as TypeScript types |
| [`docs`](/docs/cli/reference#docs) | Searching these docs by meaning ([Searching the docs](#searching-the-docs)) |
| [`support`](/docs/cli/reference#support) | A question to Palbase's support line ([Asking Palbase's support line](#asking-palbases-support-line)) |



<!-- ===== cli/reference ===== -->

# CLI reference

Every command of `palbase` 0.18.6 — the CLI in the `palbase` npm package — as its own help prints it. Run it with `npx palbase <command>`, or `palbase <command>` once the package is installed; `palbase help <command>` prints the same in a terminal. Signing in, choosing an environment and using a token in CI are in [the CLI overview](/docs/cli/overview).

382 commands in 32 groups.

## Global flags

Every command takes these.

```text
  -P, --project <project>  the project (name or id; org/project when the name is in two organizations)
  -E, --env <env>          the project's environment (slug or ref)
      --json               print the answer as JSON
      --non-interactive    never ask: refuse what would need a question
  -y, --yes                confirm a change to a production environment without asking
      --debug              print each request the command sends
  -h, --help               show help
```

## General

### `palbase login`

Sign in with your Studio account

```sh
palbase login
```

Shows a one-time code and opens Studio, where you approve it while signed in there.
The CLI then holds a session of yours: Studio lists it with your others, and ending it there signs the CLI out.
On a machine with no browser (a server, an agent), open the address it prints on any device.

```text
      --no-browser  print the address instead of opening a browser
```

### `palbase logout`

Sign out: the session is ended at Palbase and forgotten on this computer

```sh
palbase logout
```

### `palbase whoami`

The account the CLI acts as, and the environment chosen for this directory

```sh
palbase whoami
```

### `palbase use`

Choose the environment this directory acts on (kept on this computer)

```sh
palbase use [<project>[/<env>] | <org>/<project>/<env>] [--clear]
```

Commands run in this directory, or a directory under it, then act on that environment unless -P/-E say otherwise.
Nothing is written into the project: two checkouts of it can each act on their own environment.
With no argument and a person at the terminal, it lists your environments to pick from.

```text
      --clear  forget the choice made for this directory
```

### `palbase status`

The environment this directory acts on: who you are there, its machines and databases

```sh
palbase status
```

### `palbase open`

Open the environment in Studio (its overview, or a section: auth, storage, flags, …)

```sh
palbase open [section]
```

### `palbase init`

Start a backend on palbase/backend here (or in `<dir>`): a health route, its module, its tests, a Dockerfile; --db adds a schema, its routes and their test

```sh
palbase init [dir] [--db] [--print]
```

Nothing already there is written over: a file init would write that exists stops it, naming the file.
--db's table is typed in palbase/palbase-env.d.ts by the block palbase db:types writes of the schema: run db:types again when you change it.
--print writes nothing: it prints the files as JSON ({ name, db, version, files: { `<path>`: `<text>` } }), for a program that seeds a repository with this release's starter (bunx `palbase@<version>` init --print `<name>` --db).
Then: bun install, palbase use `<project>/<environment>`, palbase env:pull, bun dev.
Its tests: bun test (here, no app); palbase test --users alice,bob --base-url http://localhost:8080 -- bun test ./tests (against the app you started, as test users made for the run); on the platform, palbase machines:update `<name>` --test-command "bun test ./tests" --test-users alice,bob runs them against each new build before it takes traffic.

```text
      --db     with a database: a schema file (a table each user reads alone) and its routes
      --print  print the files as JSON, write nothing ([dir] names the package)
```

### `palbase strings`

Keep the app's translations (palbase/strings/) with its code: each t("…") a sentence, every language's file with it

```sh
palbase strings [--source <language>] [--add <language>] [--translate] [--prune]
```

Reads every t("…") the backend's source calls — imported from palbase/backend, or from a module of the app that re-exports it — in the app's directory (the nearest one up with a package.json). A sentence new in the code is added to each language's file, empty: t() answers it in the source language until it is translated. A translation is kept.
A sentence the code no longer calls is kept and listed; --prune takes it out of every file. A call it could not follow (a t from a module it does not read, a linked directory) is said, where.
palbase/strings/_meta.json names the source language (the one the sentences are written in); each other language is `palbase/strings/<language>.json`, "sentence": "translation". Edit them as any file of the app.
--translate has the environment's ai module translate what is empty (the project's AI use, as any other: its cost is in the AI usage; production's asks first). A translation is used as it is written; correct it in the file.
A table in the earlier format (version 2) is written in this one.

```text
      --source <language>  the language the sentences are written in, for a table not made yet (tr, en, pt-BR)
      --add <language>     a language to translate into: its file is made (may be given more than once)
      --translate          translate what is empty, with the environment's ai module (-P/-E, or palbase use)
      --prune              take the sentences the code no longer calls out of every file
```

### `palbase run`

Run a command with the environment's address and your own key in its environment, nothing written to disk

```sh
palbase run [--secrets development|production] -- <command> [args…]
```

palbase run -- bun dev, palbase run -- npm test: the app reads the project's secrets at boot (PALBASE_SECRETS).

```text
      --secrets <set>  the project's secrets the app reads at boot: development (default) or production
```

### `palbase test`

Run the backend's tests as the platform does before a build goes out: test users made for the run and deleted after, `PALBASE_TEST_*` in the command's environment

```sh
palbase test [--machine <name>] [--users <names>] [--base-url <url>] [--secrets development|production] [-- <command> [args…]]
```

palbase test --machine backend --base-url http://localhost:8080: the machine's own test command and test users, as the platform runs them before each build of it rolls out.
palbase test --users alice,bob --base-url http://localhost:8080 -- bun test: api.signInAs("alice") acts as a test user made for this run.
The command gets what palbase run gives it, and PALBASE_TEST_AUTH_URL (the environment's address), PALBASE_TEST_IDENTITIES (the run's test users, each with its token) and, with --base-url, PALBASE_TEST_BASE_URL (where the app under test answers; without it HTTP tests skip themselves).
The test users are deleted when the command ends, however it ends — Ctrl-C too: the command is stopped, they are deleted, and palbase test ends as the signal would have.

```text
      --machine <name>  a machine whose test command (when no command is given) and test users (when --users is not) are run
      --users <names>   the test users to make for the run, comma-separated
      --base-url <url>  where the app under test answers (http://localhost:8080)
      --secrets <set>   the project's secrets the app reads at boot: development (default) or production
```

### `palbase billing`

An organization's card and each environment's plan, balance, month and limit

```sh
palbase billing [--org <org>]
```

A member reads the plans and what was used; the money (balances, amounts) is an owner's or an admin's.

```text
      --org <org>  the organization (name or id; the one of the environment chosen here, or your only one)
```

### `palbase journeys`

The environment's journeys: each one's key, name, status, way in, and when it was published

```sh
palbase journeys [--status draft|live|stopped]
```

```text
      --status <status>  draft, live or stopped alone
```

## `env`

### `palbase env:pull`

Write what the backend needs to run here into .env.local: the environment's address and your own key — no secret's value

```sh
palbase env:pull [--file <path>] [--secrets development|production]
```

The app reads the project's secrets at boot (PALBASE_SECRETS); their names are listed as comments: set one in the file to override it.
The key is yours (CLI — you (this computer)), good for 30 days, made again by env:pull and run; palbase logout revokes it.
Only the block between the palbase markers is written; the rest of the file stays as it is.

```text
      --file <path>    the file (default .env.local)
      --secrets <set>  the project's secrets the app reads at boot: development (default) or production
```

### `palbase env:tokens:list`

The environment's live tokens, by their hint (never their values)

```sh
palbase env:tokens:list
```

### `palbase env:tokens:create`

Mint a token of the environment for a program (an AI agent): your role in this environment alone, a few hours; shown this once

```sh
palbase env:tokens:create [--scope <scope>[,<scope>]] [--minutes <n>] [--name <name>]
```

It does in this environment what your role does — as your own CLI would — but never makes or shows a standing credential (a key, a token), changes people or roles, or deletes a project or an environment; nothing beyond this environment.
--scope narrows it to: machines:read, machines:logs, apps:sync, auth:test-users, support — machines:read reads the machines, their builds, crons and queues; machines:logs their logs; apps:sync what palbase apps:sync reads; auth:test-users makes and deletes test users; support asks Palbase's support line (palbase support:ask).
Give it to the program as PALBASE_TOKEN: the CLI acts in this environment alone with it. It ends after --minutes (default 60, at most 240), and with what minted it.

```text
      --scope <scope>  narrow it to: machines:read, machines:logs, apps:sync, auth:test-users, support (comma-separated, or given again); none: your role
      --minutes <n>    how long it lives (default 60, at most 240)
      --name <name>    what it is for, as the environment lists it
```

### `palbase env:tokens:revoke`

Revoke an environment's token (by its id; with PALBASE_TOKEN an environment's token, `self` revokes it): refused from its next request on

```sh
palbase env:tokens:revoke <id|self>
```

## `types`

### `palbase types:pull`

Write the environment's secret, flag, bucket and role names into palbase/palbase-env.d.ts as types: Secrets.get, Flags and Storage.buckets take them and no other

```sh
palbase types:pull [--file <path>]
```

The names of the production secrets — what the machines start with, and so what Secrets.get reads there; development's are a developer's — leaving out what the platform sets itself (PALBASE_SECRET_KEY …), every flag, each bucket with its renditions (`Storage.buckets.<name>.getPublicUrl(path`, { variant })) and every role — never a value.
Only the block between the palbase:stack markers is written; the rest of the file stays as it is. Run it again when a name is added or taken away.

```text
      --file <path>  the file (default palbase/palbase-env.d.ts)
```

## `orgs`

### `palbase orgs:list`

Your organizations and your role in each

```sh
palbase orgs:list
```

### `palbase orgs:create`

Make an organization; you are its owner

```sh
palbase orgs:create <name>
```

### `palbase orgs:members:list`

An organization's members, and the invitations still open (for its admins)

```sh
palbase orgs:members:list
```

```text
      --org <org>  the organization (name or id); needed when you are in more than one
```

### `palbase orgs:members:invite`

Invite someone to an organization by email; they accept in Studio

```sh
palbase orgs:members:invite <email> [--role admin|member]
```

```text
      --org <org>    the organization (name or id)
      --role <role>  admin or member (default member)
```

### `palbase orgs:members:remove`

Take a member (by email or user id) or an open invitation out of an organization

```sh
palbase orgs:members:remove <email|user-id>
```

```text
      --org <org>  the organization (name or id)
```

### `palbase orgs:audit`

Who changed what at an organization's environments, through Studio or the CLI, newest first — its admins'

```sh
palbase orgs:audit [--org <org>] [--limit <n>]
```

A module keeps a change made through Studio as Studio's key's: this says whose it was. What was sent is not kept.

```text
      --org <org>  the organization (name or id)
      --limit <n>  how many at most (default 50)
```

## `tokens`

### `palbase tokens:list`

An organization's access tokens (PALBASE_TOKEN for CI and agents): name, role, when they end and were last used — never their values

```sh
palbase tokens:list
```

```text
      --org <org>  the organization (name or id)
```

### `palbase tokens:create`

Make an access token of an organization for CI or an agent; its value is shown this once

```sh
palbase tokens:create <name> [--role member|admin] [--days <n>]
```

Give it to the CI as the secret PALBASE_TOKEN: the CLI acts with it in place of a sign-in. It reaches its organization's projects and environments at its role, and nothing of its people or tokens.
It ends after --days (default 90, at most 365), and goes when it is revoked or when the one who made it leaves the organization.

```text
      --org <org>    the organization (name or id)
      --role <role>  member (default) or admin: what it may change
      --days <n>     how many days it is good for (default 90)
```

### `palbase tokens:revoke`

Revoke an organization's access token (by its name or id): refused from its next request on

```sh
palbase tokens:revoke <name|id>
```

```text
      --org <org>  the organization (name or id)
```

## `billing`

### `palbase billing:charges`

A month's charges, by environment and item — used, at the price table, charged past each one's free quota — as a table or as CSV

```sh
palbase billing:charges [--period <YYYY-MM>] [--csv] [--org <org>]
```

--csv prints the CSV Studio downloads: what an organization bills its own customers by.

```text
      --org <org>         the organization (name or id; the one of the environment chosen here, or your only one)
      --period <YYYY-MM>  the month (this one by default)
      --csv               print the charges as CSV
```

### `palbase billing:invoices`

The invoices of an organization's top-ups, each of an environment: Stripe makes one of each, and emails it

```sh
palbase billing:invoices [<project/env | ref>] [--org <org>]
```

```text
      --org <org>  the organization (name or id; the one of the environment chosen here, or your only one)
```

### `palbase billing:ledger`

Every change of an environment's balance, newest first: top-ups, usage taken, credit moved, refunds, what expired

```sh
palbase billing:ledger [<project/env | ref>] [--limit <n>]
```

```text
      --limit <n>  how many at most (default 50)
```

### `palbase billing:env`

An environment's place in the bill — its plan, frozen, its month's limit, its automatic top-up — read, or changed

```sh
palbase billing:env [<project/env | ref>] [--plan free|pay_as_you_go] [--limit <usd>|none] [--frozen yes|no] [--auto-topup yes|no] [--threshold <usd>] [--amount <usd>] [--low-balance-days <n>] [-y]
```

With no flag it shows the environment: its plan, balance, automatic top-up and month.
Each environment pays for itself: at its limit, or its balance run out, it is Free until the month ends or a top-up comes; the organization's other environments go on. Moved to Pay as you go it needs credit to pay from: its first top-up (palbase billing:topup) moves it.
Frozen, its requests are refused and its machines and databases stopped, its data kept; only what it stores is charged. Freezing asks first; -y does not.

```text
      --plan <free|pay_as_you_go>  Free (charged nothing, held to the free quotas, its credit kept) or Pay as you go (paid from its balance)
      --limit <usd|none>           at most this much a month; none for no limit
      --frozen <yes|no>            frozen: its requests refused, its machines and databases stopped, its data kept
      --auto-topup <yes|no>        take a top-up from the organization's card when the balance is under the threshold
      --threshold <usd>            the balance under which it is taken
      --amount <usd>               how much it takes ($10 at least)
      --low-balance-days <n>       email the owners when the balance lasts fewer than n days of spend (1 to 60)
```

### `palbase billing:topup`

Put money on an environment's balance now — from what the organization's bank transfers left, else its saved card: $10 to $10,000, the tax on top, an invoice made of it

```sh
palbase billing:topup [<project/env | ref>] <usd> [-y]
```

It takes the money: it asks first, and -y does not. An environment on Free is moved to Pay as you go by it (its first top-up).
With no card saved yet, the first top-up is on Stripe's page, in Studio.

### `palbase billing:bank-transfer`

An invoice of an environment's top-up to pay by bank transfer, to the organization's own bank details: credited as the money arrives

```sh
palbase billing:bank-transfer [<project/env | ref>] <usd>
```

Stripe emails the invoice with the bank details; nothing is taken until the transfer arrives.
A transfer of more than the invoice stays with the organization and pays its environments' next top-ups, before any card — for 75 days, then Stripe sends what is left back.

### `palbase billing:transfer`

Move credit from one of an organization's environments to another — all of it, or an amount — each part with its expiry

```sh
palbase billing:transfer <from project/env | ref> <to project/env | ref> [<usd>] [-y]
```

An owner's or an admin's (an admin's access token too); never to another organization's environment. It asks first, and -y does not.
A deleted environment keeps its credit until it is purged (a week): move it before then, or it is lost.

## `projects`

### `palbase projects:list`

Every project of your organizations, with its environments

```sh
palbase projects:list
```

### `palbase projects:create`

Make a project with its first environment (main), and print its keys

```sh
palbase projects:create <name> [--org <org>] [--env-name <name>]
```

The first environment is the project's production one: its slug is always main.
Its secret key is printed this once; keys:create makes more.

```text
      --org <org>        the organization (name or id)
      --env-name <name>  what the first environment is called on screen (default Production)
```

### `palbase projects:delete`

Delete a project and every environment of it

```sh
palbase projects:delete <project> [-y]
```

Its environments' data goes with them (the platform keeps it a week to bring back).

## `envs`

### `palbase envs:list`

A project's environments (the project chosen here, or -P)

```sh
palbase envs:list
```

### `palbase envs:create`

Add an environment to a project (staging, a developer's own)

```sh
palbase envs:create <slug> [--name <name>] [--from <env> [--with-cloud]]
```

Each environment is a project of its own on the platform: its users, data, machines and keys are its own.
--from opens it with another environment's module settings (palbase config:copy: secrets are named, not copied); --with-cloud its machines and databases too — declared alike, built from the same branches, with no data (palbase db:copy brings it).

```text
      --name <name>  what it is called on screen (default: the slug)
      --from <env>   open it with this environment's settings (slug or ref)
      --with-cloud   with --from: its machines and databases too (the new environment's GitHub link builds the machines)
```

### `palbase envs:delete`

Delete an environment of a project, with its data

```sh
palbase envs:delete <slug>
```

## `keys`

### `palbase keys:list`

The environment's API keys (never their values)

```sh
palbase keys:list
```

### `palbase keys:create`

Make an API key of the environment; its value is shown this once

```sh
palbase keys:create --kind publishable|secret [--label <label>]
```

```text
      --kind <kind>    publishable (ships in apps) or secret (servers only)
      --label <label>  what it is for, as Studio lists it
```

### `palbase keys:revoke`

Revoke an API key of the environment; what holds it is refused from then on

```sh
palbase keys:revoke <key-id>
```

## `auth`

### `palbase auth:settings:get`

The environment's auth settings: passwords, email confirmation, sessions, tokens, passkeys, risk

```sh
palbase auth:settings:get
```

### `palbase auth:settings:set`

Change auth settings: key=value, a value read as JSON when it is JSON (12, true, ["https://…"])

```sh
palbase auth:settings:set <key=value>…
```

Text needs no quotes (site_url=https://shop.example); quote text that reads as JSON: from_name='"123"'.
The change is made on the revision read: one made beside it in the meantime (Studio, another terminal) is refused, not overwritten.
palbase auth:settings:get lists the keys.

### `palbase auth:providers:list`

The sign-in methods: email, phone and the social providers, whether each is on, their clients and stored secrets (by name)

```sh
palbase auth:providers:list
```

### `palbase auth:providers:set`

Turn a sign-in provider on or off and set it up: its client, its secret (from stdin), phone codes

```sh
palbase auth:providers:set <provider> [--enable|--disable] [setting=value…] [--client-id <id>] [--secret-stdin] …
```

email is always on. phone: --enable/--disable, and its code settings as setting=value (allow_signups, otp_ttl_seconds, otp_max_attempts, sender, sms_second_factor).
google, apple, github, microsoft: --client-id sets the browser client --client names (default web), made when the provider has none of that name.
--secret-stdin reads the client's secret from stdin (Apple: the .p8 signing key, with --team-id and --key-id) and keeps it under --credential (default: the provider's name). It is never taken from the command line and never printed.
--clients-file replaces the provider's clients with the file's {"browser_clients": […], "native_clients": […]} (native apps, several clients).

```text
      --enable               turn it on
      --disable              turn it off
      --client <key>         the browser client --client-id, --return-uri and the secret go to (default web)
      --client-id <id>       the provider's id of your app (Google web client id, Apple services id, Microsoft application id, GitHub client id)
      --return-uri <url>     where your app is sent back after sign-in (repeat it; replaces the list)
      --application <key>    the application the client is for (default app)
      --variant <name>       the build variant the client is for (default release)
      --directory <tenant>   microsoft: a tenant id, organizations, consumers or common (default common)
      --secret-stdin         read the client's secret (Apple: the .p8 key) from stdin
      --credential <key>     the name the secret is kept under (default: the provider's)
      --team-id <id>         apple: your team's id, with --secret-stdin
      --key-id <id>          apple: the signing key's id, with --secret-stdin
      --clients-file <path>  replace the provider's clients with the file's (JSON)
```

### `palbase auth:providers:disable`

Turn a sign-in provider off (phone, google, apple, github, microsoft); its clients and secrets stay

```sh
palbase auth:providers:disable <provider>
```

### `palbase auth:providers:secret:delete`

Delete a sign-in provider's stored secret by its name; one a client still uses is refused

```sh
palbase auth:providers:secret:delete <name>
```

### `palbase auth:roles:list`

The environment's roles: their permissions, which one new users get, how many users hold each

```sh
palbase auth:roles:list
```

### `palbase auth:roles:set`

Make a role, or change one: its permissions (the list is replaced), description, whether new users get it

```sh
palbase auth:roles:set <name> [--permissions <a.b,c.d>] [--description <text>] [--default yes|no]
```

```text
      --permissions <list>  resource.action permissions, comma-separated or repeated; replaces the list ("" for none)
      --description <text>  what the role is for
      --default <yes|no>    whether new users get it (one role at most)
```

### `palbase auth:roles:delete`

Delete a role; one users hold is deleted only with --force, and is taken from them

```sh
palbase auth:roles:delete <name> [--force]
```

```text
      --force  delete it although users hold it
```

### `palbase auth:hooks:list`

The blocking hooks: what auth calls, and waits for, before a sign-up, a sign-in, a token

```sh
palbase auth:hooks:list
```

### `palbase auth:hooks:create`

Register a blocking hook; its signing secret is printed this once

```sh
palbase auth:hooks:create --event <event> --url <url> [--failure-mode deny|allow] [--timeout <ms>] [--disable]
```

```text
      --event <event>              before.user.create, before.login, before.token.issue, … (the module lists them)
      --url <url>                  the https endpoint auth calls and waits for
      --failure-mode <deny|allow>  what auth does when the hook does not answer in time (default deny)
      --timeout <ms>               how long auth waits, 100–5000 ms (default 5000)
      --disable                    register it turned off
```

### `palbase auth:hooks:update`

Change a blocking hook: its event, endpoint, timeout, failure mode, on or off (its secret stays)

```sh
palbase auth:hooks:update <id> [--event …] [--url …] [--failure-mode …] [--timeout …] [--enable|--disable]
```

```text
      --event <event>              before.user.create, before.login, before.token.issue, … (the module lists them)
      --url <url>                  the https endpoint auth calls and waits for
      --failure-mode <deny|allow>  what auth does when the hook does not answer in time (default deny)
      --timeout <ms>               how long auth waits, 100–5000 ms (default 5000)
      --enable                     turn it on
      --disable                    turn it off
```

### `palbase auth:hooks:delete`

Delete a blocking hook; auth stops calling it

```sh
palbase auth:hooks:delete <id>
```

### `palbase auth:oauth-clients:list`

The OAuth clients of the environment's OpenID provider (apps that sign in with your users' accounts)

```sh
palbase auth:oauth-clients:list
```

### `palbase auth:oauth-clients:create`

Register an OAuth client; a confidential client's secret is printed this once

```sh
palbase auth:oauth-clients:create <name> [--public] [--redirect-uri <url>…] [--grant <type>…] [--scope <scope>…] [--client-id <id>]
```

```text
      --public              a public client (a CLI, a mobile app): it has no secret
      --redirect-uri <url>  where it may send the browser back (repeat it)
      --grant <type>        authorization_code (default), refresh_token, client_credentials, urn:ietf:params:oauth:grant-type:device_code
      --scope <scope>       what it may ask for (default openid, profile, email)
      --client-id <id>      a client_id to use as it is (default: a random one)
```

### `palbase auth:oauth-clients:delete`

Delete an OAuth client (by its id or its client_id)

```sh
palbase auth:oauth-clients:delete <id|client-id>
```

### `palbase auth:import`

Bring users over with what they sign in with: ids, addresses, password hashes, providers, second factors, passkeys, open sessions

```sh
palbase auth:import <file|folder> [--pepper-stdin]
```

A folder holds import bodies, one a file (users-0001.json…, each without its pepper); a file holds one such body, JSON lines (a user each) or one JSON array.
Password and recovery-code hashes keep the source's pepper: give it on stdin with --pepper-stdin — never on the command line.
Users go 1000 a call. One refused does not stop the others; a user whose id or address the project has is refused, never overwritten.

```text
      --pepper-stdin  read the source's pepper from stdin
```

### `palbase auth:users:list`

The environment's users: id, email, verified, last sign-in; --banned for the banned alone

```sh
palbase auth:users:list [--banned] [--limit <n>]
```

```text
      --banned     only the banned
      --limit <n>  how many at most (default 100)
```

### `palbase auth:users:get`

One user: their email and phone, how they sign in, whether verified or banned, their roles

```sh
palbase auth:users:get <user-id>
```

### `palbase auth:users:create`

Make a user with an email and a password (read from stdin, never the command line)

```sh
palbase auth:users:create <email> [--verified]
```

```text
      --verified  their email is taken as verified
```

### `palbase auth:users:delete`

Delete a user: their account, sessions and sign-ins go; backends hear user.deleted

```sh
palbase auth:users:delete <user-id>
```

### `palbase auth:users:ban`

Ban a user: their sessions end and they cannot sign in until unbanned

```sh
palbase auth:users:ban <user-id> [--reason <text>]
```

```text
      --reason <text>  why (kept with the ban)
```

### `palbase auth:users:unban`

Let a banned user sign in again

```sh
palbase auth:users:unban <user-id>
```

### `palbase auth:users:sign-out`

End every session of a user's: each device signs in again

```sh
palbase auth:users:sign-out <user-id>
```

### `palbase auth:users:export`

Everything the environment holds about one user, as the law lets them ask for it (GDPR art. 15/20): JSON

```sh
palbase auth:users:export <user-id> [--out <file>]
```

```text
      --out <file>  write it here instead of to standard output
```

### `palbase auth:audit`

Who did what in the environment's auth, newest first: sign-ins, changes to users and settings, admin actions

```sh
palbase auth:audit [--event <type>] [--limit <n>]
```

```text
      --event <type>  only this kind of event (user.login, admin.user.update…)
      --limit <n>     how many at most (default 50)
```

### `palbase auth:audit:verify`

Whether the audit trail is whole: each event chained to the one before, none changed or taken out

```sh
palbase auth:audit:verify
```

### `palbase auth:audit:export`

The audit trail as a file: JSON lines or CSV, a span of it, one kind of event

```sh
palbase auth:audit:export [--format ndjson|csv] [--from <time>] [--to <time>] [--event <type>] [--out <file>]
```

```text
      --format <ndjson|csv>  JSON lines (default) or CSV
      --from <time>          from this time on (RFC 3339: 2026-10-01T00:00:00Z)
      --to <time>            up to this time
      --event <type>         only this kind of event
      --out <file>           write it here instead of to standard output
```

### `palbase auth:signing-keys`

The keys the environment's tokens are signed with: the active one, those still verifying, the retired

```sh
palbase auth:signing-keys
```

### `palbase auth:signing-keys:rotate`

Sign with a new key from now on; tokens the old one signed go on verifying until they end

```sh
palbase auth:signing-keys:rotate
```

### `palbase auth:test-users:list`

The environment's test users (made with its secret key; their tokens say test: true)

```sh
palbase auth:test-users:list
```

### `palbase auth:test-users:create`

Make test users for a suite: their passwords, and with --token an access token each, shown this once; --template has the backend write the data a screen needs for each

```sh
palbase auth:test-users:create [--count <n>] [--token] [--template <name> [--machine <name>]]
```

A test user signs in as any user does; its tokens say test: true, so a backend can tell them apart. --token gives each an access token at once, for a test that calls the backend as that user.
--template `<name>` has the backend write the data of its @TestUserTemplate({ name }) for each user — its seed for one account, in its own code (palbase/backend), run on the machine --machine names or the environment's only one, for test users alone. Each user is answered with the rows written, by table, or why its template was not (no_template, not_a_test_user, template_failed, template_timeout, machine_unavailable): the user is made all the same, and the command then ends with 1. At most 10 users at once with a template.
palbase auth:test-users:template writes another template for a user made with one; palbase auth:test-users:delete has the template undone before the user is deleted.

```text
      --count <n>        how many (default 1, at most 100; 10 with --template)
      --token            an access token for each, too
      --template <name>  a @TestUserTemplate of the backend's: its data written for each user
      --machine <name>   the machine whose backend has the template (default: the environment's only one)
```

### `palbase auth:test-users:template`

Have the backend write a @TestUserTemplate's data for a test user made with a template — the same one again answers what it wrote then

```sh
palbase auth:test-users:template <user-id> <template> [--machine <name>]
```

The user is one auth:test-users:create --template made on that machine: a test user is the machine's that made it. Asked again for a template it wrote, the platform answers what it wrote then, and the backend is not called.

```text
      --machine <name>  the machine whose backend has the template (default: the environment's only one)
```

### `palbase auth:test-users:delete`

Delete a test user — one made with a template has the backend undo it first

```sh
palbase auth:test-users:delete <user-id> [--machine <name>]
```

A test user made with --template is deleted through the machine that made it: the backend's undo of each template runs first — a template with none leaves its data to user.deleted (what ownedByUser() owns goes with the user) — and an undo that fails keeps the user, for the delete to be asked again. Any other test user is deleted at once.
Without --machine the environment's machines are asked which made the user; a token that does not list the machines deletes it at once, its templates left to user.deleted.

```text
      --machine <name>  the machine that made the user with a template (default: whichever did)
```

## `storage`

### `palbase storage:buckets:list`

The environment's buckets: who may read each, the largest file and the types it takes

```sh
palbase storage:buckets:list
```

### `palbase storage:buckets:get`

A bucket's declaration in full, with its renditions

```sh
palbase storage:buckets:get <bucket>
```

### `palbase storage:buckets:set`

Make a bucket, or change one: public or private, the largest file, the content types, its renditions

```sh
palbase storage:buckets:set <bucket> [--public|--private] [--max-size <size>] [--types <a/b,c/*>] [--variants-file <path>]
```

What is not given is kept as it is (a new bucket: private, the platform's size, any type, no rendition).

```text
      --public                anyone may read its files at /storage/public/
      --private               its files are read with signed URLs and the rules
      --max-size <size>       the largest file: 10MB, 512KiB, 1GB, bytes, or platform
      --types <list>          the content types it takes, comma-separated (image/* a family); "" for any
      --variants-file <path>  its renditions, a JSON list of {name, width, height, fit, format, quality}
```

### `palbase storage:buckets:delete`

Delete an empty bucket (one that still holds files is refused)

```sh
palbase storage:buckets:delete <bucket>
```

### `palbase storage:ls`

A bucket's objects, or those under a prefix: path, size, type

```sh
palbase storage:ls <bucket>[:prefix]
```

### `palbase storage:cp`

Copy files between this computer and a bucket: a file, or a folder whole with -r

```sh
palbase storage:cp <from> <to> [-r] [--owner <user id>]
```

bucket:path names an object of the environment; anything else is a path on this computer.
Up: a file to bucket:path (a path ending in / keeps the file name); with -r, a folder to bucket:prefix, its paths kept.
Down: bucket:path to a file; with -r, every object under bucket:prefix into a folder.

```text
  -r, --recursive        a folder (up) or a prefix (down), whole
      --owner <user id>  the user uploaded objects belong to (deleted with them)
```

### `palbase storage:rm`

Delete an object, or every object under a prefix with -r

```sh
palbase storage:rm <bucket:path> [-r]
```

```text
  -r, --recursive  every object under the prefix
```

### `palbase storage:url`

A signed download URL for one object

```sh
palbase storage:url <bucket:path> [--expires <seconds>]
```

```text
      --expires <seconds>  how long it works (default 3600, at most 604800)
```

## `flags`

### `palbase flags:list`

The environment's flags as they are live: type, default, targeting (and the draft's state when it publishes)

```sh
palbase flags:list
```

### `palbase flags:set`

Define a flag or change its default and targeting (into the draft when the environment publishes)

```sh
palbase flags:set <key> <value> [--type bool|number|string|object] [--condition "<expression> => <value>"…] [--description <text>]
```

The value is read as the flag's type: true/false, a number, text, or a JSON object; a new flag's type is the value's unless --type says it.
--condition replaces the targeting (first match wins, 8 at most); --clear-conditions takes it away; without either it stays.
An environment that publishes takes the change into its shared draft (palbase flags:publish makes it live); one that does not, live at once.

```text
      --type <type>         bool, number, string or object
      --condition <rule>    "<expression> => <value>" (repeat it, in order)
      --clear-conditions    take its targeting away
      --variants <list>     a string flag's allowed values, comma-separated
      --description <text>  what the flag is for
```

### `palbase flags:delete`

Delete a flag, with every user's own value of it (from the draft when the environment publishes)

```sh
palbase flags:delete <key>
```

### `palbase flags:publish`

Show the flags draft's changes against the live version, then publish it as the next version

```sh
palbase flags:publish [-m <note>]
```

```text
  -m, --note <note>  why: kept with the version
```

### `palbase flags:versions`

The published versions of the flags, newest first, and which one is live

```sh
palbase flags:versions [--limit <n>]
```

```text
      --limit <n>  how many (default 20)
```

### `palbase flags:rollback`

Make an earlier version of the flags live again (published as the next version)

```sh
palbase flags:rollback <version> [-m <note>]
```

```text
  -m, --note <note>  why (default: rollback to <version>)
```

### `palbase flags:publishing:enable`

Turn publishing on for the environment's flags: changes go into a shared draft, live once published — for good

```sh
palbase flags:publishing:enable
```

What is live now becomes version 1. From then on flags:set and flags:delete change the draft, flags:publish makes it live as the next version, and flags:rollback brings an earlier one back. It cannot be turned off.

### `palbase flags:users:get`

Every flag as one user gets it now — their own values, the targeting, the defaults — as their client reads them

```sh
palbase flags:users:get <user-id>
```

### `palbase flags:users:set`

Give a user a flag's value of their own, whatever its default and targeting say

```sh
palbase flags:users:set <user-id> <key> <value>
```

### `palbase flags:users:unset`

Take a user's own value of a flag away, or every one with no key: the flag decides for them again

```sh
palbase flags:users:unset <user-id> [key]
```

## `notify`

### `palbase notify:providers:list`

The environment's own providers, by channel and the order they are tried (never their credentials)

```sh
palbase notify:providers:list
```

### `palbase notify:providers:set`

Bring a provider for a channel: its credentials are piped in as JSON, checked as the sender will use them, never shown

```sh
palbase notify:providers:set <channel> <provider> [--priority <n>] [--enable|--disable] < credentials.json
```

email: acs {connection_string, from_email}, ses {region, access_key_id, secret_access_key, from_domain}, sendgrid {api_key, from_domain}, smtp {host, port, username, password, from_email, use_starttls}.
sms: twilio {account_sid, auth_token, from_number}, vonage {api_key, api_secret, from}, acs {connection_string, from_number}. verify: twilio_verify {account_sid, auth_token, service_sid}.
whatsapp: meta {phone_number_id, access_token, api_version, app_secret, verify_token}. push: fcm (the service account JSON), apns {private_key, team_id, key_id, bundle_id, is_production}, expo {access_token}.
The credentials are read from stdin only: never from the command line, where the shell would keep them.

```text
      --priority <n>  lower is tried first
      --enable        turn it on
      --disable       turn it off
```

### `palbase notify:providers:remove`

Forget a provider and its credentials

```sh
palbase notify:providers:remove <channel> <provider>
```

### `palbase notify:templates:list`

The templates messages render from: the platform's defaults and the ones the environment overrides

```sh
palbase notify:templates:list [--channel email|sms|whatsapp]
```

```text
      --channel <channel>  only this channel's (default: all three)
```

### `palbase notify:templates:get`

A template as it renders now in a locale (yours, or the platform's default); --json gives the document templates:set takes

```sh
palbase notify:templates:get <slug> --locale <locale> [--channel email|sms|whatsapp]
```

```text
      --channel <channel>  email (default), sms or whatsapp
      --locale <locale>    the template's locale: en, tr, pt-BR
```

### `palbase notify:templates:set`

Override a template in a locale, from a file or stdin (email: {subject, html_body, text_body} as JSON)

```sh
palbase notify:templates:set <slug> --locale <locale> [--channel email|sms|whatsapp] [--file <path>]
```

email: {"subject", "html_body", "text_body"}; sms: the text, or {"body"}; whatsapp: {"name", "language", "variables", "code_button"} of a template approved on your Meta account.
notify:templates:get … --json > t.json gives a document to edit and set back. Handlebars: {{name}}, {{#if}}, {{#each}}.

```text
      --channel <channel>  email (default), sms or whatsapp
      --locale <locale>    the template's locale: en, tr, pt-BR
      --file <path>        the template (default: stdin)
```

### `palbase notify:templates:delete`

Remove an override: the platform's default renders again (a WhatsApp mapping is forgotten)

```sh
palbase notify:templates:delete <slug> --locale <locale> [--channel email|sms|whatsapp]
```

```text
      --channel <channel>  email (default), sms or whatsapp
      --locale <locale>    the template's locale: en, tr, pt-BR
```

### `palbase notify:topics:list`

The topics users follow, how many follow each, whether they follow it from the app

```sh
palbase notify:topics:list
```

### `palbase notify:topics:create`

Make a topic users can follow; a push to it reaches its followers

```sh
palbase notify:topics:create <name> [--self-subscribe yes|no]
```

```text
      --self-subscribe <yes|no>  users follow it from the app (default no: the project adds them)
```

### `palbase notify:topics:delete`

Delete a topic and who follows it

```sh
palbase notify:topics:delete <name>
```

### `palbase notify:settings:get`

The environment's message settings: the default locale, who email is from, where texts may go

```sh
palbase notify:settings:get
```

### `palbase notify:settings:set`

Change message settings: key=value (from_email=…, sms_countries=["+90","+44"], mx_check=true)

```sh
palbase notify:settings:set <key=value>…
```

The change is made on the revision read: one made beside it in the meantime is refused, not overwritten.

### `palbase notify:send`

Send an email or a text through the environment's providers: written here, or a template with its variables

```sh
palbase notify:send <email|sms> <to> [--template <slug> --var name=value…] [--subject <s> --text <t> --html <h>] [--body <text>]
```

A message is sent as a backend sends it (POST /notify/email, /notify/sms): its delivery is in palbase notify:messages.

```text
      --template <slug>   a template of the environment (notify:templates:list)
      --var <name=value>  a template's variable (again for each)
      --locale <locale>   the template's locale
      --subject <text>    an email's subject
      --text <text>       an email's text
      --html <html>       an email's HTML
      --body <text>       a text's words
```

### `palbase notify:messages`

The messages the environment sent, newest first, and what became of each

```sh
palbase notify:messages [--limit <n>]
```

```text
      --limit <n>  how many (default 20)
```

### `palbase notify:deliverability`

Whether each channel can send now, through which providers, and what to do when it cannot

```sh
palbase notify:deliverability
```

## `realtime`

### `palbase realtime:channels:get`

The channel declaration, in the order patterns are matched: who may join each, publish, read and write its state

```sh
palbase realtime:channels:get
```

### `palbase realtime:channels:set`

Replace the channel declaration with a JSON file or stdin ({"channels": […]} or the list)

```sh
palbase realtime:channels:set [--file <path>]
```

Each channel: {"pattern": "room:{id}", "kind": "public", "publish": true, "state_read": true, "state_write": false}, or {"pattern": "user:{uid}", "kind": "owner"}.
realtime:channels:get --json gives the document to edit. Open sockets are decided again within a heartbeat.

```text
      --file <path>  the declaration (default: stdin)
```

### `palbase realtime:limits:get`

The limits the environment holds its clients to (null: the platform's), and the platform's

```sh
palbase realtime:limits:get
```

### `palbase realtime:limits:set`

Change realtime limits: key=value (max_connections=500), null for the platform's

```sh
palbase realtime:limits:set <key=value>…
```

The keys: max_connections, max_events_per_second, max_joins_per_second, max_channels_per_connection. A value above the platform's has no effect beyond it.

### `palbase realtime:broadcast`

Send an event to a channel's subscribers, as the server does: its payload JSON (or text)

```sh
palbase realtime:broadcast <topic> <event> [payload]
```

## `analytics`

### `palbase analytics:settings:get`

How long analytics keeps events and console records, the share of performance samples kept, whether bodies are kept

```sh
palbase analytics:settings:get
```

### `palbase analytics:settings:set`

Change analytics settings: key=value (retention_days=30, perf_sample_pct=10, console_bodies=false)

```sh
palbase analytics:settings:set <key=value>…
```

A shorter retention removes what is older within minutes.

### `palbase analytics:events`

The events analytics recorded, newest first: by name, by user, over a window

```sh
palbase analytics:events [--name <event>] [--user <distinct-id>] [--window <24h>] [--limit <n>]
```

```text
      --name <event>   only this event's
      --user <id>      only this user's (their distinct id)
      --window <span>  how far back: 30m, 24h, 7d (default 24h)
      --limit <n>      how many (default 50)
```

### `palbase analytics:summary`

What analytics counted over a window: events, users, sessions, the top events

```sh
palbase analytics:summary [--window <24h>]
```

```text
      --window <span>  how far back: 30m, 24h, 7d (default 24h)
```

## `messaging`

### `palbase messaging:settings:get`

How the environment runs its conversations: how long messages are kept, whether a push says what one says, what becomes of a deleted user's messages, the hook

```sh
palbase messaging:settings:get
```

### `palbase messaging:settings:set`

Change how the environment runs its conversations: a setting left out is left as it is

```sh
palbase messaging:settings:set [--retention-days <days>|off] [--push-preview on|off] [--deleted-user-messages keep|delete]
```

A shorter retention removes the messages older than it, in every conversation. A deleted user's messages are kept or deleted as the setting is when the user is deleted.
Deleted, what of theirs had already gone from screens (seen once, its time up, vanish mode, taken back) stays its 14 days, sealed, for reports, then goes.
Only what changes is sent: a change made beside this one to another setting stays.

```text
      --retention-days <days|off>            messages older than this many days are removed (1–36500); off: kept for good
      --push-preview <on|off>                a push says what the message says (on), or only that one came (off)
      --deleted-user-messages <keep|delete>  a deleted user's messages: kept, their writer anonymous, or deleted (what went from screens before stays its 14 days for reports)
```

### `palbase messaging:hook:get`

The hook asked whom one may reach: where it is, how long it is waited for, what is done when it does not answer (never its secret)

```sh
palbase messaging:hook:get
```

### `palbase messaging:hook:set`

Set the hook asked whom one may reach, or change it; a new hook's signing secret is printed this once, or kept in a secret with --secret-to

```sh
palbase messaging:hook:set [--url <url>] [--timeout-ms <ms>] [--on-error allow|deny] [--secret-to <NAME> [--dev]]
```

Before a direct conversation opens or people are added to a group, the hook is POSTed {"event": "messaging.can_message", "action": "direct" | "group_add", "from_user_id", "to_user_ids", "conversation_id"}, signed as Standard Webhooks sign (webhook-id, webhook-timestamp, webhook-signature), and answers 200 {"allowed_user_ids": […]}.
A new hook takes --url (an https URL on the public internet). Its signing secret is printed this once, or kept in the environment's secrets with --secret-to (production; --dev: development) and printed nowhere. A hook changed keeps its secret: palbase messaging:hook:secret:rotate makes a new one.

```text
      --url <url>              where the hook is asked
      --timeout-ms <ms>        how long it is waited for: 100 to 5000 (a new hook: 2000)
      --on-error <allow|deny>  when it does not answer: allow everyone, or deny and the app is told to try again (a new hook: deny)
      --secret-to <NAME>       keep the new signing secret in the environment's secret NAME instead of printing it
      --dev                    with --secret-to: the development secrets, not production
```

### `palbase messaging:hook:remove`

Remove the hook: anyone may reach anyone, and its signing secret is forgotten

```sh
palbase messaging:hook:remove
```

### `palbase messaging:hook:secret:rotate`

Make the hook's signing secret anew: printed this once, or kept in a secret with --secret-to; the old one signs nothing more

```sh
palbase messaging:hook:secret:rotate [--secret-to <NAME> [--dev]]
```

The hook's calls are signed with the new secret alone from now: the endpoint verifies them with it (a machine reads a secret kept with --secret-to at its next start).

```text
      --secret-to <NAME>  keep the new signing secret in the environment's secret NAME instead of printing it
      --dev               with --secret-to: the development secrets, not production
```

### `palbase messaging:reports:list`

The reports people made, newest first: why, whom, which messages (what they carry: messaging:reports:get)

```sh
palbase messaging:reports:list [--status open|resolved] [--limit <n>] [--cursor <cursor>]
```

```text
      --status <status>  only the open ones, or only the resolved ones
      --limit <n>        at most this many (1–100, default 30)
      --cursor <cursor>  the next page, as the last one said it
```

### `palbase messaging:reports:get`

One report with what it carries: the reporter's note, what the messages it names said when reported and before they were edited

```sh
palbase messaging:reports:get <report id>
```

An owner's or an admin's (a member lists the reports, without what they carry); the read is in the project's access log. --json carries the messages' files with the keys that open them.
A report of a group a person deleted says who deleted it and when; naming no message, it carries the last 30 messages the reporter saw in it.
A report is deleted, with what it carries, 190 days after it is resolved; one never resolved, 2 years after it was made.

### `palbase messaging:reports:resolve`

Resolve a report, saying what came of it in the project's own words

```sh
palbase messaging:reports:resolve <report id> --resolution <text>
```

```text
      --resolution <text>  what came of it: 1 to 64 characters (warned, removed, nothing found…)
```

### `palbase messaging:access-log`

Each time people's messages were read or removed — by the project's server, or an owner or admin from Studio or the CLI — newest first: what, which conversation, whose, by whom (kept 400 days)

```sh
palbase messaging:access-log [--limit <n>] [--cursor <cursor>]
```

```text
      --limit <n>        at most this many (1–200, default 50)
      --cursor <cursor>  the next page, as the last one said it
```

### `palbase messaging:conversations:list`

The project's conversations, or a person's with --user, the latest first: whose, how many people, when it last moved

```sh
palbase messaging:conversations:list [--user <user id>] [--limit <n>] [--cursor <cursor>]
```

```text
      --user <user id>   only this person's conversations
      --limit <n>        at most this many (1–100, default 30)
      --cursor <cursor>  the next page, as the last one said it
```

### `palbase messaging:messages:list`

What a conversation said, newest first — each read in the project's access log

```sh
palbase messaging:messages:list <conversation id> [--limit <n>] [--cursor <cursor>]
```

An owner's or an admin's: a member sees the conversations and the reports, not what was said.
--json carries the messages whole, their files with the keys that open them.

```text
      --limit <n>        at most this many (1–100, default 50)
      --cursor <cursor>  the next page, as the last one said it
```

### `palbase messaging:messages:delete`

Remove a message for everyone in its conversation: what it said and its files go (in the access log)

```sh
palbase messaging:messages:delete <conversation id> <message id>
```

It is not undone: asked before it is done, whatever the environment (-y confirms).

## `config`

### `palbase config:diff`

How two environments' module settings differ (auth, storage, flags, notify, realtime, analytics, messaging; machines, databases when named)

```sh
palbase config:diff --from <env> --to <env> [--only <modules>]
```

- a key only in --from, + only in --to, ~ in both with other values. Ids, times and versions are not compared; a secret is compared as set or not, never by its value.
Exit code 0 when they are the same, 1 when they differ. --json gives each difference with both values.

```text
      --from <env>      the environment compared from (slug or ref)
      --to <env>        the environment compared to (slug or ref)
      --only <modules>  only these, comma-separated: auth,storage,flags,notify,realtime,analytics,messaging (the default), and databases,machines when named
```

### `palbase config:copy`

Make one environment's module settings equal to another's (secrets excepted: their names are said)

```sh
palbase config:copy --from <env> --to <env> [--only <modules>]
```

It shows the differences, asks before changing a production environment (-y confirms), changes the target, and compares again.
A secret is never copied: a provider's credentials and a sign-in client's secret are listed by name for you to set. A new hook or OAuth client gets its own secret, printed this once.
What the target holds that its users depend on is not taken by a copy: a bucket with files, a role users hold, a topic users follow are left and said.
--only machines,databases copies what they are declared as — a machine's source, size, copies, settings, secrets' name, database; a database's size, who may connect, backups — never a database's data (palbase db:copy) nor a secret's value. A machine or database only the target has is left serving.
Exit code 0 when the two are the same afterwards, 1 when a difference remains.

```text
      --from <env>      the environment compared from (slug or ref)
      --to <env>        the environment compared to (slug or ref)
      --only <modules>  only these, comma-separated: auth,storage,flags,notify,realtime,analytics,messaging (the default), and databases,machines when named
```

## `secrets`

### `palbase secrets:list`

The environment's secrets by name, with their version — never their values

```sh
palbase secrets:list [--dev]
```

```text
      --dev  the development set (what a backend on a developer's computer reads), not production
```

### `palbase secrets:set`

Set a secret: its value is read from stdin, never from the command line

```sh
palbase secrets:set <NAME> [--dev] < value
```

The environment's machines read production at their next start; a backend run with palbase run or env:pull reads development.

```text
      --dev  the development set (what a backend on a developer's computer reads), not production
```

### `palbase secrets:get`

Print one secret's value (an admin's)

```sh
palbase secrets:get <NAME> [--dev]
```

```text
      --dev  the development set (what a backend on a developer's computer reads), not production
```

### `palbase secrets:unset`

Take a secret away

```sh
palbase secrets:unset <NAME> [--dev]
```

```text
      --dev  the development set (what a backend on a developer's computer reads), not production
```

### `palbase secrets:versions`

A secret's versions, newest first — never their values

```sh
palbase secrets:versions <NAME> [--dev]
```

```text
      --dev  the development set (what a backend on a developer's computer reads), not production
```

### `palbase secrets:rollback`

Put a secret back to one of its versions (a new version with that value)

```sh
palbase secrets:rollback <NAME> --version <n> [--dev]
```

```text
      --dev          the development set (what a backend on a developer's computer reads), not production
      --version <n>  the version to go back to
```

### `palbase secrets:audit`

Every read and write of the environment's secrets, newest first: which secret, which key did it, when — never a value

```sh
palbase secrets:audit [--name <NAME>] [--dev | --prod] [--limit <n>]
```

A backend that reads the secrets at boot (palbase run, a machine) shows here as a read, with the key it read with: palbase keys:list names the key.
An encrypted column's values opened through Palbase (Studio's table, a secret key) are recorded under the column's address: --name patients.tc lists who opened them, and when.

```text
      --name <NAME>  only this secret's, or an encrypted field's opens (table.column)
      --dev          only the development secrets
      --prod         only the production secrets
      --limit <n>    how many (default 30)
```

## `fields`

### `palbase fields:list`

The keys the environment's encrypted database fields are sealed with — never the keys themselves

```sh
palbase fields:list
```

### `palbase fields:rotate`

Make a new key for the environment's encrypted fields (an owner's or an admin's)

```sh
palbase fields:rotate
```

It comes into force in five minutes: by then every running backend has fetched it. New values are sealed with it from then on; a palbase/backend app seals its older values again with it, in the background.
The older keys go on opening what they sealed.

### `palbase fields:keys`

Download the environment's field keys into a file (its owner's): what opens a dump of its database elsewhere

```sh
palbase fields:keys --out <file>
```

The file opens every encrypted field of the environment: keep it as you would the database's password. It is the shape palbase/server's Fields reads: new Fields({ fetch: async () => JSON.parse(readFileSync(file, 'utf8')) }).
The download is in the secrets audit trail (secrets:audit).

```text
      --out <file>  where the keys go (made readable by you alone); never the screen
```

## `transit`

### `palbase transit:list`

The keys the encrypted fields of a request to the environment's backend are sealed to — their public halves alone

```sh
palbase transit:list
```

### `palbase transit:rotate`

Make a new key for the encrypted fields of requests to the backend (an owner's or an admin's)

```sh
palbase transit:rotate [--retire-previous]
```

Apps seal to it from their next fetch of the project's keys (within the hour), or at once with --retire-previous: every older key is retired with it — what to do when one may have been taken — and an app that seals to a retired one is told so, fetches the keys again and sends its call once more.
No app needs a new build: an app holds the project's signing key, not its keys.

```text
      --retire-previous  retire every older key at once
```

### `palbase transit:retire`

Retire a transit key that is not the one in use: no request sealed to it opens from then on

```sh
palbase transit:retire <key>
```

## `webhooks`

### `palbase webhooks:list`

The environment's webhook endpoints: where its events go, which (never their secrets)

```sh
palbase webhooks:list
```

### `palbase webhooks:create`

Add a webhook endpoint; its signing secret is printed this once, or kept in a secret with --secret-to

```sh
palbase webhooks:create <url> [--events <a,b>] [--secret-to <NAME> [--dev]]
```

A machine is given its own endpoint and its secret (PALBASE_WEBHOOK_SECRET) by the platform, for the events its app takes: this is for another receiver. --secret-to keeps the secret in the environment's secrets (production; --dev: development) and prints it nowhere.

```text
      --events <list>     the events it is sent, comma-separated (user.deleted, …); none: every event
      --secret-to <NAME>  keep its signing secret in the environment's secret NAME instead of printing it
      --dev               with --secret-to: the development secrets, not production
```

### `palbase webhooks:update`

Change a webhook endpoint's address or events (its secret stays)

```sh
palbase webhooks:update <id> [--url <url>] [--events <a,b>|""]
```

```text
      --url <url>      where it is delivered now
      --events <list>  the events it is sent now, comma-separated; "" for every event
```

### `palbase webhooks:delete`

Remove a webhook endpoint: its events are no longer delivered there

```sh
palbase webhooks:delete <id>
```

### `palbase webhooks:deliveries:list`

The deliveries the platform gave up on after its tries, still owed (--failed), or every one kept 30 days (--all)

```sh
palbase webhooks:deliveries:list [--failed] [--all]
```

```text
      --failed  those it gave up on and still owes (the default)
      --all     every one kept, those delivered again among them
```

### `palbase webhooks:deliveries:redeliver`

Send a failed delivery again: the same event, its id and body, to the endpoint it failed at, within seconds

```sh
palbase webhooks:deliveries:redeliver <id>
```

As Stripe's Resend: the receiver takes an event more than once by its Palbase-Event-Id. An admin's; it is written to the organization's audit log.

## `ai`

### `palbase ai:usage`

The environment's uses of models, newest first: what each was, what it cost, and whose key it went out with

```sh
palbase ai:usage [--kind text|embedding|image] [--metadata key=value]… [--limit <n>] [--cursor <cursor>]
```

```text
      --kind <kind>           only uses of this kind: text, embedding or image
      --metadata <key=value>  only uses carrying this label (repeat for several): a product's spend, a task's
      --limit <n>             at most this many (1–500, default 50)
      --cursor <cursor>       the next page, as the last one said it
```

### `palbase ai:spend`

What Palbase's models cost the environment this month: the free dollar and what is left of it, the monthly budget, and whether they serve it now — and if not, why

```sh
palbase ai:spend
```

Palbase's models are the platform's provider keys. A month brings a dollar of them free: a Free environment's own, a paying account's once for all its projects. Past it a Free environment uses its own provider keys (ai:providers:set); a Pay as you go one pays from the account's balance, at the provider's price and 10%.
Its own provider keys always serve it, and are not counted here: their provider bills them.

### `palbase ai:models`

The models the environment may name — every text model with its rungs, window and price, and the embedding and picture models

```sh
palbase ai:models
```

### `palbase ai:providers:list`

The providers the environment calls with its own key (never the keys): its calls go out with them instead of the platform's

```sh
palbase ai:providers:list
```

### `palbase ai:providers:set`

Call a provider with the environment's own key: the key is piped in or typed unseen, never shown or put on the command line

```sh
palbase ai:providers:set <provider> [--key-stdin] < key.txt
```

Without --key-stdin the key is asked for at the terminal, and not echoed as it is typed or pasted.

```text
      --key-stdin  read the key from stdin (a pipe, a file)
```

### `palbase ai:providers:remove`

Forget the environment's own key for a provider: its calls go out with the platform's again

```sh
palbase ai:providers:remove <provider>
```

### `palbase ai:settings:get`

What the environment allows its chats — whether the app's users talk to the agents, how often, how much history is kept — and its monthly AI budget

```sh
palbase ai:settings:get
```

### `palbase ai:settings:set`

Change what the environment allows its chats, and its monthly AI budget: a setting left out is left as it is

```sh
palbase ai:settings:set [--clients on|off] [--messages-per-minute <n>] [--history-limit <bytes>|none] [--monthly-budget <usd>|none]
```

--monthly-budget is the most the environment spends a month on Palbase's models (the platform's provider keys), at what it is billed: past it a call they would serve is refused (ai_budget_reached) until the month turns (UTC) or the budget is raised, and the organization's owners are emailed once. Its own provider keys are not counted: their provider bills them. palbase ai:spend says what is spent.
Only an owner or an admin of the organization sets it, as themselves: a member's change of it is refused, and so is a key's or a token's — what spends the money does not raise its own limit.

```text
      --clients <on|off>            the app's users talk to the agents of their chats with their own session
      --messages-per-minute <n>     how many messages one user sends a minute (1–600)
      --history-limit <bytes|none>  the chat history kept at most, in bytes; none: the plan's
      --monthly-budget <usd|none>   the most spent a month on Palbase's models, in US dollars (0.01–1000000, cents at most); none: no budget
```

### `palbase ai:agents:list`

The environment's agents: its backend's (its build's contract names them) and those it keeps, a draft and published versions

```sh
palbase ai:agents:list
```

### `palbase ai:agents:show`

One agent: where it stands and what it is — a kept one's published version (or its draft, or a version), a backend's last turn

```sh
palbase ai:agents:show <name> [--draft | --version <n>]
```

```text
      --draft        the draft, as the next publish makes a version of it
      --version <n>  that version, as it was published
```

### `palbase ai:agents:create`

Save the draft of an agent the environment keeps — a new one's, or a change of one's — and publish it with --publish

```sh
palbase ai:agents:create <name> [--from <file.json>] [--instructions <text>] [--description <text>] [--model <model>] [--tool <source:name>]… [--output-schema <file.json>] [--revision <n>] [--publish]
```

Its chats talk to the version published: a draft changes nothing until it is published (ai:agents:publish, or --publish here).
A change of an agent it keeps is made on its draft: each flag given replaces its field, and the rest stays.
--from is the whole definition as JSON ({ "instructions", "model", "tools": [{ "source", "name" }], "subagents", "output", … }) — or what ai:agents:generate --json printed; each flag given replaces its field.
--tool is source:name: `backend:<ai.tool>` (`backend:<machine>/<ai.tool>` for another machine's), `client:<ai.clientTool>`, `https:<endpoint>`, `mcp:<server>`, platform:web.search|web.fetch|workspace.fetch_archive (palbase ai:tools lists them). Given, the tools are those; a backend or client tool goes by its name alone, and the platform takes what it does from the build that declares it.
--revision is the draft's revision as it was read (ai:agents:show): when another was saved since, the save is refused (draft_changed) and nothing is lost.

```text
      --from <file.json>           the definition, as JSON
      --instructions <text>        what the agent is told to do
      --description <text>         what it is for, in a sentence or two
      --model <model>              a role (fast, default, strong) or a model of ai:models
      --tool <source:name>         a tool it is given (repeat for several)
      --output-schema <file.json>  the JSON Schema of its one-shot answers
      --revision <n>               the draft's revision the change is made on
      --publish                    publish the draft as the next version once it is saved
```

### `palbase ai:agents:publish`

Make the draft of an agent the next version, the one its chats talk to from their next turn

```sh
palbase ai:agents:publish <name> [--revision <n>]
```

```text
      --revision <n>  the draft as it was read: refused when another was saved since
```

### `palbase ai:agents:rollback`

Make a version an agent had the one its chats talk to again — and its draft that version

```sh
palbase ai:agents:rollback <name> <version>
```

### `palbase ai:agents:versions`

The versions an agent the environment keeps was published as, newest first, and the one its chats talk to

```sh
palbase ai:agents:versions <name> [--limit <n>] [--cursor <cursor>]
```

```text
      --limit <n>        at most this many (1–100, default 20)
      --cursor <cursor>  the next page, as the last one said it
```

### `palbase ai:agents:generate`

Write an agent from a description — instructions, a model, the environment's tools that fit — and save it as a draft with --save

```sh
palbase ai:agents:generate "<description>" [--name <name>] [--save] [--publish]
```

Nothing is kept unless --save (or --publish) says so: the definition is printed, for ai:agents:create --from.
It is written as you — your sign-in, or PALBASE_TOKEN — 20 an hour; the platform pays for it.

```text
      --name <name>  the name it is to have (left out: one is suggested)
      --save         save it as the draft of an agent of that name
      --publish      save it and publish it as the next version
```

### `palbase ai:agents:remove`

Forget an agent the environment keeps, its versions with it: its chats stay, and are refused a message until one of its name is there again

```sh
palbase ai:agents:remove <name>
```

### `palbase ai:tools`

The tools an agent may be given: the backend's (its build's contract), the environment's endpoints, and the platform's

```sh
palbase ai:tools
```

### `palbase ai:chats:list`

The environment's chats, newest first — every one, or a member's

```sh
palbase ai:chats:list [--member <user id>] [--limit <n>] [--cursor <cursor>]
```

```text
      --member <user id>  only the chats this user is in
      --limit <n>         at most this many (1–100, default 100)
      --cursor <cursor>   the next page, as the last one said it
```

### `palbase ai:chats:show`

One chat: its agent and members, and what they wrote, newest last — with what each turn cost (--cost)

```sh
palbase ai:chats:show <chat id> [--limit <n>] [--cost]
```

```text
      --limit <n>  its last this many messages (1–100, default 50)
      --cost       what each turn a message started cost, its subagents counted
```

### `palbase ai:chats:remove`

Delete a chat: a turn still running is stopped, and its history no longer counts

```sh
palbase ai:chats:remove <chat id>
```

### `palbase ai:endpoints:list`

The environment's HTTPS tools and MCP servers an agent may be given by name (their signing secrets are never said again)

```sh
palbase ai:endpoints:list
```

### `palbase ai:endpoints:remove`

Forget an HTTPS tool or an MCP server: an agent that names it is given it no more

```sh
palbase ai:endpoints:remove <name>
```

### `palbase ai:repos:list`

The repositories a chat's workspace works in, by name, and the machine that gives their tokens

```sh
palbase ai:repos:list [--limit <n>] [--cursor <cursor>]
```

```text
      --limit <n>        at most this many (1–1000, default 100)
      --cursor <cursor>  the next page, as the last one said it
```

### `palbase ai:repos:remove`

Forget a repository: a chat's workspace checks it out no more

```sh
palbase ai:repos:remove <name>
```

## `support`

### `palbase support:ask`

Ask Palbase's support line about Palbase: answered from its documentation and what this environment shows; what Palbase lacks is logged, and you are mailed when Palbase closes it

```sh
palbase support:ask "<question>" [--no-context]
```

It is answered by a model Palbase pays for, from Palbase's documentation and — unless --no-context — this environment's machines, their last builds and a failed build's log, read with your sign-in or PALBASE_TOKEN (what it cannot read is left out).
Keys, tokens and passwords in what is sent are masked before anything reads them.
When the answer finds something Palbase lacks, it is logged under the case it names, and you are mailed when it is closed (asked with an environment token, the owners of its organization are).
A person asks 30 questions an hour, a project's people 60. An environment token narrowed to the support scope asks too.

```text
      --no-context  send the question alone, nothing of this environment's machines
```

## `docs`

### `palbase docs:search`

Search Palbase's documentation by meaning: the sections that answer it, each with its address and its text

```sh
palbase docs:search "<what you need>" [--limit <n>]
```

Ask in English, the docs' language: a question finds the section it means by its meaning and by its words — say what you need, not the words of a heading.
Each result is a section of a page: its title, its address with the section's anchor, and its text (the first 4000 characters of a longer one — the address has the rest).
Anyone may search, signed in or not: 10 searches in ten seconds, 30 a minute, 300 an hour. A sign-in or PALBASE_TOKEN is sent when there is one and is counted as itself; with none, your address is. When many search at once, a search waits its turn for a few seconds, or is told to search again in a moment.

```text
      --limit <n>  how many sections (1 to 10, default 5)
```

## `stores`

### `palbase stores:apple`

The environment's Apple account and Apple ID: whether each is connected, what Apple last said of them, what the key reaches

```sh
palbase stores:apple
```

### `palbase stores:apple:connect`

Connect an App Store Connect API key, or sign an Apple ID in: either goes from this computer straight to the environment, never through Studio

```sh
palbase stores:apple:connect --key-file <AuthKey_KEYID.p8> --issuer-id <issuer id> [--key-id <KEYID>] | --apple-id <email> [--team <team>] | [--apple-id <email>] --print-link
```

App Store Connect → Users and Access → Integrations → App Store Connect API makes the key and shows the Issuer ID; stores:apple then says what its role reaches.
Studio is asked for a one-time grant alone; the key is posted with it to the environment's own address. --print-link prints a link that takes the key in a browser instead.
--apple-id signs an Apple ID in, for what Apple's API does not do: App Review's messages and the answer to them, App Privacy, making an app record. Its password is read here and handed to Apple through the environment, never kept; then Apple's code, and the team when the Apple ID is in more than one. An owner's or an admin's.

```text
      --apple-id <email>             sign this Apple ID in instead of connecting a key
      --team <team>                  the Apple ID's team, by name or id, when it is in more than one
      --key-file <AuthKey_KEYID.p8>  the .p8 file Apple gave when the key was made
      --key-id <KEYID>               the key's id (default: from the file's name)
      --issuer-id <issuer id>        the account's issuer id
      --print-link                   only print a link that takes the key in a browser (valid 30 minutes, once)
```

### `palbase stores:apple:check`

Ask Apple about the connected key again (after the account holder accepted its agreements, or its role changed), or with --apple-id about the Apple ID

```sh
palbase stores:apple:check
```

```text
      --apple-id  check the Apple ID's session instead: whether Apple still takes it, its team and roles
```

### `palbase stores:apple:disconnect`

Take the environment's Apple key away (Apple keeps its apps and builds), or with --apple-id sign its Apple ID out

```sh
palbase stores:apple:disconnect
```

```text
      --apple-id  sign the Apple ID out, at Apple too, and forget its session; the key stays
```

### `palbase stores:apple:keys`

The keys Palbase made at Apple for the environment with its Apple ID, where each stands, and which keys the environment lacks

```sh
palbase stores:apple:keys
```

Palbase makes them with the Apple ID signed in for the environment (stores:apple:connect --apple-id): stores:apple:keys:make. No one downloads a .p8.

### `palbase stores:apple:keys:make`

Make at Apple, with the environment's Apple ID, the keys it lacks — App Store Connect API, APNs, In-App Purchase — and connect them: one confirmation

```sh
palbase stores:apple:keys:make
```

With no flag, every key the environment lacks; a key it has is kept. The Apple ID is an Admin or the Account Holder of the team.
APNs: one key for production and one for the sandbox, scoped to the environment's iOS apps; notify takes them. In-App Purchase: for one iOS app (--bundle with more than one); purchases connects it.

```text
      --asc             the App Store Connect API key
      --apns            the APNs keys
      --iap             the In-App Purchase key
      --bundle <value>  the iOS app the In-App Purchase key is for, when the environment has more than one
```

### `palbase stores:apple:keys:revoke`

Revoke at Apple an APNs or In-App Purchase key Palbase made for the environment (the App Store Connect key is revoked as stores:apple:disconnect takes it away)

```sh
palbase stores:apple:keys:revoke <key-id>
```

### `palbase stores:apple:share`

Share the environment's Apple ID session with another environment of the project, which uses it while it has none of its own

```sh
palbase stores:apple:share <environment>
```

An environment of the same project alone: Palbase refuses another project's, of your organization or not (other_project).
You are an owner or an admin of both environments; a key or an environment token does not share.
Signed out, or signed in again, the session serves none it was shared with: share it again. stores:apple:unshare takes it back.

### `palbase stores:apple:unshare`

Take the environment's Apple ID session back from another environment of the project

```sh
palbase stores:apple:unshare <environment>
```

### `palbase stores:google`

The environment's Play connection: the service account Play Console invites, what Play let it reach

```sh
palbase stores:google
```

### `palbase stores:google:connect`

Connect Google Play: Palbase makes a service account for the environment, which your Play Console invites

```sh
palbase stores:google:connect
```

No key changes hands: Palbase acts as the service account it made in its own Google Cloud project.
Then, in Play Console → Users and permissions, invite the service account with the app (Release to testing tracks; for purchases also View financial data and Manage orders and subscriptions), link the Android app (stores:apps:link) and check: stores:google:check.

### `palbase stores:google:check`

Ask Play what the environment's service account reaches of each Android app: after Play Console invited it

```sh
palbase stores:google:check
```

### `palbase stores:google:disconnect`

Delete the environment's service account at Google: Play Console's invite of it reaches nothing any more

```sh
palbase stores:google:disconnect
```

### `palbase stores:apple:sandbox-testers`

The Apple team's sandbox testers: the accounts that buy in the App Store's sandbox, how fast their subscriptions renew

```sh
palbase stores:apple:sandbox-testers
```

They are the team's, every environment's alike. Only a person makes one: App Store Connect › Users and Access › Sandbox.

### `palbase stores:apple:sandbox-testers:set`

Change how a sandbox tester buys: how fast its monthly subscriptions renew, whether its purchases are interrupted, its storefront

```sh
palbase stores:apple:sandbox-testers:set <email|id> [--renewal 3m|5m|15m|30m|1h] [--interrupt on|off] [--storefront <code>]
```

A monthly subscription renews at the rate given; a yearly one in proportion. Apple renews one 12 times at most, then lets it end.
An interrupted purchase stops for an action of the buyer's, as when a bank asks for one: what the app does then is tested.

```text
      --renewal <rate>      every 3m, 5m, 15m, 30m or 1h
      --interrupt <on|off>  interrupt its purchases
      --storefront <code>   the storefront it buys in, three letters (USA, DEU, TUR …)
```

### `palbase stores:apple:sandbox-testers:clear`

Clear sandbox testers' purchase history: each buys again as for the first time, introductory offers included

```sh
palbase stores:apple:sandbox-testers:clear <email|id>…
```

Apple clears them after it answers, which can take minutes. Then sign out of the sandbox account on the device and in again.

### `palbase stores:apps`

The environment's apps linked to their store

```sh
palbase stores:apps
```

### `palbase stores:apps:link`

Link an app of the project to its store: an iOS app to the App Store, an Android app to Google Play (with an upload key Palbase makes)

```sh
palbase stores:apps:link <app id> [--name <name in the store>]
```

```text
      --name <name>  its name in the store (default: the bundle id or package)
```

### `palbase stores:apps:record`

Make a linked iOS app's App Store Connect record with the Apple ID — Apple's API leaves it to a person on the website — and link the app to it

```sh
palbase stores:apps:record <app id> --name <App Store name> [--sku <sku>] [--locale <en-US>] [--company <seller name>]
```

```text
      --name <name>      its App Store name (30 characters at most)
      --sku <sku>        the record's own id in the team (default: the bundle id)
      --locale <locale>  its store page's first language (default: en-US)
      --company <name>   the seller's name, which a team's first app sets
```

### `palbase stores:apps:record:remove`

Remove a linked iOS app's App Store Connect record with the Apple ID, as App Store Connect's Remove App does (an app never approved)

```sh
palbase stores:apps:record:remove <app id>
```

### `palbase stores:apps:upload-key`

An Android app's upload key: the certificate Palbase signs its builds with (never its private key)

```sh
palbase stores:apps:upload-key <app id> [--out <file.pem>]
```

Play Console shows an app's upload key by this fingerprint; asked to change an app's upload key to Palbase's, it takes this certificate (--out).

```text
      --out <file.pem>  write the certificate (PEM) to this file
```

### `palbase stores:feedback`

An app's TestFlight feedback: testers' screenshots and crashes

```sh
palbase stores:feedback <app id>
```

### `palbase stores:feedback:get`

One of an app's TestFlight feedback: the device, the build, and a crash's log

```sh
palbase stores:feedback:get <app id> <crash|screenshot> <feedback id>
```

A crash's log is cut at 32 KiB: the exception and the crashed thread come first. A screenshot's images are Apple's links, which expire.

### `palbase stores:webhook`

An iOS app's App Store Connect webhook: whether Apple tells Palbase each change at once, and its last delivery

```sh
palbase stores:webhook <app id> [--make] [--ping]
```

Palbase makes the webhook when the app is linked (the key's role must be Admin or App Manager), and tries again every day while it is not on; meanwhile it reads Apple every few minutes.
--make points it at the environment again with a new secret; --ping asks Apple to send it a ping and waits for it to arrive.

```text
      --make  make it again: a new secret, pointed at the environment
      --ping  ask Apple to send it a ping, and wait for it to arrive
```

### `palbase stores:vitals`

An app's health as its store has it: crashes, terminations and hangs, crash and ANR rates by version

```sh
palbase stores:vitals <app id>
```

An iOS app: the crashes testers sent from TestFlight, what TestFlight counted of its newest builds (installs, sessions, crashes, feedback), its App Store versions' terminations, hangs and launches, and App Store crashes by day (the App Crashes report, an Admin key's).
An Android app: Play's Android vitals — each version code's crash and ANR rates over seven days, its errors, and what Play flagged.
A new day of it is the environment's stores.vitals.changed event.

### `palbase stores:packages`

The packages handed to the stores, newest first

```sh
palbase stores:packages [--app <app id>] [--limit <n>]
```

```text
      --app <app id>  only this app's
      --limit <n>     how many (1–200, default 20)
```

### `palbase stores:packages:get`

One package: its build, its bundles and its deliveries

```sh
palbase stores:packages:get <package id>
```

### `palbase stores:packages:create`

Make a package of an app: its build number, and the URL and token its .ipa is uploaded with

```sh
palbase stores:packages:create <app id> --command-id <id> [--notes <text>] [--entitlements-file <json>]
```

The build is made with the build number it answers (CFBundleVersion), then uploaded: palbase stores:packages:upload.
The same --command-id again answers the same package, with a new upload token while it waits for its build: a build machine sends its run's id.

```text
      --command-id <id>           names the request (a CI run id): sent again, the same package
      --notes <text>              notes kept with it (a commit, a branch)
      --entitlements-file <json>  what each bundle asks for, by bundle id ({"com.acme.app": {"aps-environment": "production"}})
```

### `palbase stores:packages:upload`

Hand a package its build: the .ipa or .aab goes straight to the environment's address with the upload token

```sh
palbase stores:packages:upload <package id> --file <app.ipa|app.aab> --token <upload token>
```

The token is the one stores:packages:create printed; PALBASE_UPLOAD_TOKEN stands in for --token, out of the process list.
The file goes with its Content-Length. While the module is busy with another upload it is sent again, after the wait the module names, five times at most; a package that has its build already (this token's upload arrived before) counts as uploaded.

```text
      --file <app.ipa|app.aab>  the unsigned .ipa, or the Android App Bundle (unsigned, or signed with the app's upload key), the build machine made
      --token <upload token>    the package's upload token
```

### `palbase stores:packages:bundle`

Download a package's bundle as Palbase signed it for Play: to upload it in Play Console by hand

```sh
palbase stores:packages:bundle <package id> --out <file.aab> [--channel play_internal]
```

stores:deliver sends every build to Play, an app's first too; when Play wants a release made in Play Console instead (Testing → Internal testing → Create new release), upload this file there: it is signed with the app's upload key.
The bytes come from the environment's address on a link the module sealed for this bundle, valid 15 minutes; Studio is asked for the link alone.

```text
      --out <file.aab>     where to write it
      --channel <channel>  the Play delivery (play_internal)
```

### `palbase stores:deliver`

Send a package to a channel's testers: signed, handed to Apple or Play, and given to the testers

```sh
palbase stores:deliver <package id> [--channel testflight|play_internal] [--groups <group,…>] [--what-to-test <text>] [--locale <locale>]
```

An iOS app goes to TestFlight: processed, then given to the groups; an export compliance question is answered with stores:export-compliance.
An Android app goes to Play's internal testing track, to the testers it lists in Play Console. An invite given in Play Console just now takes a while to reach Play's API: a delivery Play refuses then (google_not_allowed) is sent again later.
palbase stores:deliveries `<package id>` follows it.

```text
      --channel <channel>    where it goes: testflight, or play_internal (default: the app's platform's)
      --groups <group,…>     the groups it goes to once ready, by id or name
      --what-to-test <text>  the note testers read
      --locale <locale>      the note's locale (default: the app's primary one)
```

### `palbase stores:deliveries`

A package's deliveries: where each is now, and what to do when one failed

```sh
palbase stores:deliveries <package id>
```

### `palbase stores:what-to-test:set`

Change what testers read with a package's TestFlight build, once Apple holds the build

```sh
palbase stores:what-to-test:set <package id> --text <text> [--locale <locale>]
```

Apple's note on the build, and the delivery's own; before Apple holds the build the module says so (build_not_at_apple) — stores:deliver --what-to-test sets it with the delivery.

```text
      --text <text>      the note testers read (4000 characters at most)
      --locale <locale>  its locale (default: the app's primary one)
```

### `palbase stores:groups`

An app's groups of testers

```sh
palbase stores:groups <app id>
```

### `palbase stores:groups:create`

Make a group of testers for an app (in TestFlight an internal and an external group)

```sh
palbase stores:groups:create <app id> <name>
```

### `palbase stores:groups:rename`

Rename a group

```sh
palbase stores:groups:rename <group id> <name>
```

### `palbase stores:groups:delete`

Delete a group: its testers lose the builds it gave them

```sh
palbase stores:groups:delete <group id>
```

### `palbase stores:groups:testers`

A group's testers

```sh
palbase stores:groups:testers <group id>
```

### `palbase stores:groups:testers:set`

Set who a group holds, whole: those not named leave it

```sh
palbase stores:groups:testers:set <group id> (--emails <a@x,…> | --file <testers.txt>)
```

A file names one tester a line — email, or email,First,Last — or is a JSON array; - reads it from stdin. 100 at most.

```text
      --emails <a@x,…>  the testers' addresses
      --file <path>     the testers, one a line (- for stdin)
```

### `palbase stores:groups:add-build`

Give a group a package that TestFlight has (external testers get it after Beta App Review)

```sh
palbase stores:groups:add-build <group id> <package id>
```

### `palbase stores:review-info`

An app's TestFlight test information as Apple holds it, in one locale, and what Beta App Review still lacks — the demo password only as set or not

```sh
palbase stores:review-info <app id> [--locale <locale>]
```

```text
      --locale <locale>  the locale to read (default: the app's primary one)
```

### `palbase stores:review-info:set`

What Beta App Review needs to know of an app: only the fields given are written; it answers what is still missing

```sh
palbase stores:review-info:set <app id> [--description <text>] [--feedback-email <a@x>] [--contact-… <…>] [--demo-account-name <name> --demo-password-stdin] [--notes <text>] [--locale <locale>]
```

```text
      --description <text>         what testers should test
      --feedback-email <a@x>       where testers send feedback
      --contact-first-name <name>  whom Apple calls: first name
      --contact-last-name <name>   last name
      --contact-phone <phone>      phone
      --contact-email <a@x>        email
      --demo-account-name <name>   a sign-in for the reviewer, when the app needs one
      --demo-password-stdin        read the demo account's password from stdin (never the command line)
      --notes <text>               notes to the reviewer
      --locale <locale>            the description's and feedback address's locale (default: the app's primary one)
```

### `palbase stores:beta-review`

Plan sending a package to Beta App Review (external testers get it after Apple's review); it runs when confirmed

```sh
palbase stores:beta-review <package id>
```

### `palbase stores:export-compliance`

Plan the export compliance answer of a package's build (the question TestFlight waits on); it runs when confirmed

```sh
palbase stores:export-compliance <package id> --uses-non-exempt-encryption yes|no
```

```text
      --uses-non-exempt-encryption <yes|no>  whether the app uses encryption beyond HTTPS and what iOS provides
```

### `palbase stores:expire`

Plan expiring a package's build in TestFlight (testers can no longer install it); it runs when confirmed

```sh
palbase stores:expire <package id>
```

### `palbase stores:listing:get`

An iOS app's draft App Store page — categories, age rating, each language's text and screenshots — and its revision

```sh
palbase stores:listing:get <app id> [--out <palbase/store/listing.json>]
```

--out writes the draft to a file to edit, under palbase/; stores:listing:put saves the edit on the revision printed. A screenshot can be named there by its file under palbase/ (relative to the draft's file) instead of its SHA-256: listing:put uploads it first.
Nothing of the draft is at Apple: stores:listing:plan compares it with App Store Connect, and the plan, once confirmed, writes it.

```text
      --out <file>  write the draft to this file, under palbase/
```

### `palbase stores:listing:put`

Save an iOS app's draft App Store page, whole, on the revision it was edited from — its screenshot files uploaded first

```sh
palbase stores:listing:put <app id> --file <palbase/store/listing.json> --revision <n>
```

A screenshot is named by its SHA-256, or by a file — a path from the draft's own file, under palbase/ (nothing else is read): each file is uploaded first, and the draft is saved with its SHA-256 in its place. The file itself is left as it is.
Of two people editing at once, the second is told — the draft moved past the revision they edited — never saved over. Nothing goes to Apple: stores:listing:plan says what the draft changes there.

```text
      --file <listing.json>  the draft, as stores:listing:get --out wrote it ('-' or none: stdin)
      --revision <n>         the revision it was edited from, as stores:listing:get printed it (0: the first)
```

### `palbase stores:screenshots:upload`

Upload screenshots for an iOS app's App Store page: each is kept by its SHA-256, which the draft names it by

```sh
palbase stores:screenshots:upload <app id> <file.png|file.jpg>…
```

Each is a PNG or JPEG of 10 MB at most, of a size the App Store takes: iPhone 6.9" (1320x2868, 1290x2796, 1260x2736), iPhone 6.5" (1242x2688, 1284x2778) or iPad 13" (2064x2752, 2048x2732), or turned. The same image again is the one kept.
stores:listing:put uploads the files a draft names itself; this is for the SHA-256 alone.

### `palbase stores:review-screenshot`

Upload the screenshot App Review is shown of an in-app purchase: kept by its SHA-256, which the catalog names it by

```sh
palbase stores:review-screenshot <app id> <file.png|file.jpg>
```

A PNG or JPEG of 10 MB at most, at an App Store screenshot size — iPhone 6.9" 1320x2868, 1290x2796 or 1260x2736; iPhone 6.5" 1242x2688 or 1284x2778; iPad 13" 2064x2752 or 2048x2732 (or turned): App Review takes an in-app purchase's screenshot at no other.
Name it in the catalog, channels.ios.review.screenshot = `"sha256:<hex>"`; the next plan (palbase purchases:catalog:plan) gives it to App Store Connect, and Apple then has what it needs of the product to review it.

### `palbase stores:listing:plan`

Plan writing an iOS app's draft page to App Store Connect: what changes, language by language; it runs when confirmed

```sh
palbase stores:listing:plan <app id>
```

The draft is compared with the page of the app's version that can change; a field the draft leaves empty, and a language it has not, are left as they are.

### `palbase stores:version`

An iOS app's App Store version as App Review will see it — its build, release, phased release, price, content rights, review contact — and what App Review would refuse it for

```sh
palbase stores:version <app id>
```

The demo account's password is never read out: only whether Apple holds one. watched is what the module last saw of the version sent to App Review (it reads it every few minutes).

### `palbase stores:version:prepare`

Prepare an iOS app's App Store version: its number, build, copyright, release, phased release, content rights, a free price, App Review's details

```sh
palbase stores:version:prepare <app id> [--version <x.y.z>] [--build <n>] [--copyright <text>] [--release manual|after_approval|scheduled] [--release-at <RFC 3339>] [--phased | --no-phased] [--third-party-content | --no-third-party-content] [--free] [--territories all] [--app-privacy published|unpublished] [--review-file <review.json>] [--demo-password-stdin]
```

Only what is given is written; --version makes the next version when the app has none that can change. The build is a TestFlight build of that version, by its number.
--review-file holds App Review's details as stores:version --json shows them (its review): a field the file leaves out stays as it is. The demo account's password is read from stdin alone (--demo-password-stdin), never from the file or the command line; it goes to Apple, and is never printed or kept.

```text
      --version <x.y.z>                      the version's number: makes it when the app has none that can change
      --build <n>                            the TestFlight build App Review gets, by its build number
      --copyright <text>                     the copyright line (2026 Your Company)
      --release <how>                        how it goes out once approved: manual, after_approval or scheduled
      --release-at <RFC 3339>                a scheduled release, not before then (alone, it is scheduled)
      --phased                               release it in phases over seven days
      --no-phased                            release it to everyone at once
      --third-party-content                  the content rights statement: the app shows, contains or reaches third-party content
      --no-third-party-content               the content rights statement: it does not
      --free                                 make an app with no price free everywhere (a paid price is set in App Store Connect)
      --territories <all>                    all: sell an app sold nowhere in every country and region (chosen ones are set in App Store Connect)
      --app-privacy <published|unpublished>  say the app's privacy details were published in App Store Connect (Apple has no API for them): the missing list stops asking for them
      --review-file <review.json>            App Review's details: contact, demo account, notes ('-': stdin)
      --demo-password-stdin                  read the demo account's password from stdin (never a file or the command line)
```

### `palbase stores:version:submit`

Plan sending an iOS app's prepared version to App Review — refused, with what is missing, until it has what App Review needs; it runs when confirmed

```sh
palbase stores:version:submit <app id> [--with <product id>,…]
```

--with sends the app's in-app purchases and subscriptions with the version, by product id: a product's first review goes with an app version, as Apple requires, and each is READY_TO_SUBMIT at Apple (its text, price, availability and review screenshot complete) or nothing is planned.

```text
      --with <product id,…>  in-app purchases sent to App Review with the version, by product id
```

### `palbase stores:version:withdraw`

Plan taking the version out of App Review: it is edited again, and sent again from the start; it runs when confirmed

```sh
palbase stores:version:withdraw <app id>
```

### `palbase stores:version:release`

Plan releasing an approved version that waits for its developer (a manual release) on the App Store, for good; it runs when confirmed

```sh
palbase stores:version:release <app id>
```

### `palbase stores:version:phased`

Plan pausing, resuming or completing the version's phased release (complete: everyone gets it now); it runs when confirmed

```sh
palbase stores:version:phased <app id> <paused|active|complete>
```

### `palbase stores:app-review`

An iOS app's Resolution Center, read with the Apple ID: App Review's messages, the guidelines a rejection names, its attachments, the answer not sent yet

```sh
palbase stores:app-review <app id>
```

Apple's API gives no reason for a rejection: the Apple ID signed in for the environment reads it (stores:apple:connect --apple-id). The five threads written to last.

### `palbase stores:app-review:answer`

Write the answer to an App Review thread, as App Store Connect's draft; --send sends it

```sh
palbase stores:app-review:answer <app id> <thread id> [--file <answer.txt>] [--send]
```

The answer is read from --file, or piped in. Without --send it stays a draft, which App Store Connect's website shows too; with --send it goes to App Review.

```text
      --file <answer.txt>  the answer (default: stdin)
      --send               send it to App Review once written
```

### `palbase stores:privacy`

An iOS app's App Privacy details as App Store Connect has them, read with the Apple ID

```sh
palbase stores:privacy <app id>
```

### `palbase stores:privacy:set`

Write an iOS app's App Privacy details at Apple with the Apple ID, and publish them with --publish

```sh
palbase stores:privacy:set <app id> --file <usages.json> [--publish]
```

The file is the details' lines in Apple's words: [{"category":"USER_ID","purpose":"APP_FUNCTIONALITY","data_protection":"DATA_LINKED_TO_YOU"}], or [{"data_protection":"DATA_NOT_COLLECTED"}] alone. What Apple has and the file lacks is removed; what the file has and Apple lacks is made.

```text
      --file <usages.json>  the lines (default: stdin)
      --publish             publish them once written
```

### `palbase stores:actions`

The actions planned at Apple, newest first: what each does, and whether it ran (running: a page still being written)

```sh
palbase stores:actions [--status planned|done|declined|failed] [--limit <n>]
```

```text
      --status <status>  only those planned, done, declined or failed
      --limit <n>        how many (1–200, default 30)
```

### `palbase stores:actions:confirm`

Run a planned action at Apple: it names the hash of the plan that was shown, and is asked about first

```sh
palbase stores:actions:confirm <action id> --hash <hash>
```

What it does is shown, then asked about — in every environment, as it cannot be undone at Apple. -y confirms without asking.
An App Store page's plan is written after the answer (its screenshots take minutes): the command waits for it to be done or failed, 15 minutes at most; stopping the wait does not stop the writing.

```text
      --hash <hash>  the plan's hash, as it was shown when it was planned
```

### `palbase stores:actions:decline`

Decline a planned action: it never runs

```sh
palbase stores:actions:decline <action id>
```

## `purchases`

### `palbase purchases:catalog:get`

The environment's catalog: its newest revision, the products it sells and what they give

```sh
palbase purchases:catalog:get [--out <catalog.json>]
```

--out writes the catalog to a file to edit; catalog:put saves the edit with the revision it was edited from, which is printed.

```text
      --out <catalog.json>  write the catalog (the JSON catalog:put takes) to this file
```

### `palbase purchases:catalog:put`

Save a new revision of the whole catalog, on the revision it was edited from; nothing is written to a store

```sh
palbase purchases:catalog:put --file <catalog.json> --revision <n>
```

The module checks it first: a catalog that breaks a rule is refused with every problem, and nothing is saved.
Of two people editing at once, the second is told — the catalog moved past the revision they edited — never overwritten.
The stores are brought to it by a plan: palbase purchases:catalog:plan.

```text
      --file <catalog.json>  the catalog, as catalog:get --out wrote it ('-' or none: stdin)
      --revision <n>         the revision it was edited from (0 for the first), as catalog:get printed it
```

### `palbase purchases:catalog:validate`

Check a catalog without saving it: every problem, with its path and the store whose rule it breaks

```sh
palbase purchases:catalog:validate --file <catalog.json>
```

```text
      --file <catalog.json>  the catalog ('-' or none: stdin)
```

### `palbase purchases:catalog:plan`

Plan bringing the stores to the catalog's newest revision, store by store, before anything is written

```sh
palbase purchases:catalog:plan [<plan id>]
```

A plan is confirmed with its Stripe part's hash (purchases:catalog:confirm) — with no Stripe account connected, its App Store part's; the App Store and Google Play parts are written by the stores module once their accounts are connected.
With a plan's id it makes none: it shows that plan, and once confirmed what each store answered — the state of every product written, and a price that changes on a later day.

### `palbase purchases:catalog:confirm`

Write a plan — its Stripe part now, its App Store part through the stores module: it names the hash of the plan that was shown, and is asked about first

```sh
palbase purchases:catalog:confirm <plan id> --hash <hash>
```

What it writes is shown, then asked about — in every environment: a price written to Stripe is never changed or removed there, a product made in App Store Connect never goes away. -y confirms without asking.

```text
      --hash <hash>  the hash the plan printed (its Stripe part's; with no Stripe account, its App Store part's)
```

### `palbase purchases:catalog:decline`

Decline a plan: its Stripe part is never written

```sh
palbase purchases:catalog:decline <plan id>
```

### `palbase purchases:catalog:revisions`

Every revision the catalog was saved as, the newest first: who saved it, when, and when a plan of it was written to the stores

```sh
palbase purchases:catalog:revisions [--limit <n>] [--cursor <next>]
```

purchases:catalog:revision `<n>` reads one; purchases:catalog:restore `<n>` puts it back as the next revision.

```text
      --limit <n>      revisions a page (default 50, at most 200)
      --cursor <next>  the next page, as the last one printed it
```

### `palbase purchases:catalog:revision`

The catalog as it was saved at a revision

```sh
palbase purchases:catalog:revision <revision> [--out <catalog.json>]
```

--out writes that revision's catalog to a file, as catalog:get --out writes the newest.

```text
      --out <catalog.json>  write the revision's catalog to this file
```

### `palbase purchases:catalog:restore`

Put an older revision of the catalog back, as its next revision; nothing is written to a store

```sh
palbase purchases:catalog:restore <revision>
```

It is saved as an edit is: checked against today's rules, what customers bought kept in it — a revision that breaks one is refused with every problem.
The stores are brought to it by a plan, confirmed: palbase purchases:catalog:plan.

### `palbase purchases:customers`

Find customers by what a person writing in has: their id, an id their store gave a purchase, or the email they bought with on the web

```sh
palbase purchases:customers <query>
```

The query is a customer's id; Apple's original transaction id or any transaction id; a Google order id (GPA.…, a renewal's ..N or not); Stripe's subscription, payment intent, invoice or customer id; or an email address.
An email finds a buyer who had no account at checkout, matched whole (case aside): the address is never kept, an HMAC of it is.

### `palbase purchases:customer:get`

What a customer has, whatever store they bought in: entitlements, subscriptions, purchases, credits and limits

```sh
palbase purchases:customer:get <customer id>
```

The customer is the user's id; a guest merged into an account answers as the account.

### `palbase purchases:customer:history`

What happened to a customer, the newest first: payments, refunds, cancellations, grants, credits, moves — with who did each, and why

```sh
palbase purchases:customer:history <customer id> [--limit <n>] [--cursor <next>]
```

Credits spent are the credits' own entries; here are the credits given, taken back, expired and forgiven.

```text
      --limit <n>      events a page (default 50, at most 200)
      --cursor <next>  the next page, as the last one printed it
```

### `palbase purchases:customer:grants`

The entitlements given a customer — active, ended and revoked — with each grant's id, reason and who gave it

```sh
palbase purchases:customer:grants <customer id>
```

End one: palbase purchases:customer:revoke `<customer id>` `<grant id>`.

### `palbase purchases:customer:grant`

Give a customer one of the catalog's entitlements, for a while or for life, saying why — a promotion, a support case, a tester

```sh
palbase purchases:customer:grant <customer id> <entitlement> --reason <why> [--for 30d | --until <date>]
```

The reason is the record. Without --for or --until the grant is for life. It prints the grant's id: purchases:customer:revoke ends it.
A customer not seen before is made; nothing is charged, in any store.

```text
      --reason <why>  why it is given (500 characters at most): the record
      --for <span>    how long: 12h, 30d, 2w
      --until <date>  when it ends (2026-12-31, or a time)
```

### `palbase purchases:customer:revoke`

End a granted entitlement now; what the customer bought is not touched

```sh
palbase purchases:customer:revoke <customer id> <grant id>
```

The grant's id is the one purchases:customer:grant printed. The entitlement stays on while a purchase still gives it.

### `palbase purchases:customer:extend`

Move a customer's subscription renewal days later, for free: the App Store's extension, Google Play's deferral, Stripe's next charge moved

```sh
palbase purchases:customer:extend <customer id> <subscription id> --days <1-90> --reason customer_satisfaction|service_issue|other [--note <why>]
```

The subscription's id is the one purchases:customer:get prints. The App Store extends a paid, active subscription, at most 90 days and twice a year.
The store is asked again after: the new expiry is printed, and the customer's history keeps it with who did it.

```text
      --days <n>      how many days (1 to 90)
      --reason <why>  customer_satisfaction, service_issue or other: as the App Store asks it
      --note <why>    what support writes of it (500 characters at most): the record
```

### `palbase purchases:customer:refund`

Refund a customer's subscription — its latest payment, or what is left of its period — and end it now: Google Play and Stripe

```sh
palbase purchases:customer:refund <customer id> <subscription id> --mode full|prorated [--note <why>]
```

The customer's access ends as it answers. The App Store decides its own refunds: the customer asks Apple, which asks the app what they used — Palbase answers it when they consented in the app.

```text
      --mode <kind>  full: the latest payment; prorated: what is left of its period
      --note <why>   what support writes of it (500 characters at most): the record
```

### `palbase purchases:customer:cancel`

Turn a customer's subscription renewal off: it ends at its period's end, the customer keeping what they paid for — Google Play and Stripe

```sh
palbase purchases:customer:cancel <customer id> <subscription id> [--note <why>]
```

An App Store subscription's renewal is the customer's to turn off (Settings › Apple ID › Subscriptions).

```text
      --note <why>  what support writes of it (500 characters at most): the record
```

### `palbase purchases:customer:credits`

A customer's credit entries, the newest first: given, spent, taken back, expired, forgiven — with who did each, and why

```sh
palbase purchases:customer:credits <customer id> [--credits <key>] [--limit <n>] [--cursor <next>]
```

```text
      --credits <key>  one of the catalog's credits alone
      --limit <n>      entries a page (default 50, at most 200)
      --cursor <next>  the next page, as the last one printed it
```

### `palbase purchases:customer:credits:give`

Give a customer credits, saying why — a support case, a promotion — for a while or until spent

```sh
palbase purchases:customer:credits:give <customer id> <credits> <amount> --reason <why> [--source support|promotion] [--for 30d | --until <date>]
```

What they owe is paid first from what is given. Nothing is charged, in any store.

```text
      --reason <why>   why they are given (500 characters at most): the record
      --source <kind>  support (the default) or promotion
      --for <span>     how long they last: 12h, 30d, 2w
      --until <date>   when they expire (2026-12-31, or a time)
```

### `palbase purchases:customer:credits:forgive`

Forgive what a customer owes of a credit — all of it, or an amount — saying why

```sh
palbase purchases:customer:credits:forgive <customer id> <credits> --reason <why> [--amount <n>]
```

```text
      --reason <why>  why it is forgiven (500 characters at most): the record
      --amount <n>    how much of it (default: all they owe)
```

### `palbase purchases:customer:limit:set`

Set a customer's own maximum of a limit — above or below the catalog's — saying why, for a while or until cleared

```sh
palbase purchases:customer:limit:set <customer id> <limit> <max> --reason <why> [--for 30d | --until <date>]
```

```text
      --reason <why>  why (500 characters at most): the record
      --for <span>    how long: 12h, 30d, 2w
      --until <date>  when it ends (2026-12-31, or a time)
```

### `palbase purchases:customer:limit:clear`

Clear a customer's own maximum of a limit: the catalog's counts again

```sh
palbase purchases:customer:limit:clear <customer id> <limit>
```

### `palbase purchases:customer:limit:give`

Give a customer more of a limit for its current period, saying why — a gift on top of their maximum

```sh
palbase purchases:customer:limit:give <customer id> <limit> <amount> --reason <why> [--source support|promotion]
```

```text
      --reason <why>   why it is given (500 characters at most): the record
      --source <kind>  support (the default) or promotion
```

### `palbase purchases:stripe`

The environment's Stripe account: whether one is connected, what Stripe last said of its key

```sh
palbase purchases:stripe
```

### `palbase purchases:stripe:grant`

A link that connects a Stripe restricted key: the key goes from the browser straight to the environment, never through Studio or this computer

```sh
palbase purchases:stripe:grant
```

The link works once, for 30 minutes; a project holds 10 open at most.

### `palbase purchases:stripe:install`

A link that connects the environment's Stripe account with one click: Palbase's Stripe App, installed at Stripe — no key pasted

```sh
palbase purchases:stripe:install
```

The link opens Palbase's install page, naming the project; from there Stripe: pick the account, accept what the App may do, and Stripe sends you back to Palbase, which connects it.
It works once, for 30 minutes; --live installs the App in live mode (Stripe test mode otherwise).
A restricted key connects an account too: palbase purchases:stripe:grant.

```text
      --live  install the App in live mode (test mode otherwise)
```

### `palbase purchases:storekit`

An Xcode StoreKit configuration of the environment's iOS products, under palbase/: a build Xcode runs buys them with no App Store

```sh
palbase purchases:storekit [--app <app>] [--out <palbase/….storekit>] [--storefront <code>]
```

Each plan is the App Store product its store id names, with its text in every language the catalog has and its price; a subscription is in its group, at its tier's level, with its introductory offer and the catalog's offers on it as promotional offers (a grant has no store).
Prices are in the storefront's currency: the catalog's price, or the amount set by hand in that currency. The storefront is --storefront, else the one the file has, else the one the catalog's currency is the App Store's own price in (USD: USA, EUR: Germany, TRY: Turkey …), else USA.
Made again, the file is made whole from the catalog — the same catalog, the same file — keeping the test settings Xcode's Editor menu wrote in it. Nothing outside palbase/ is written: Xcode is pointed at the file in the scheme.

```text
      --app <app>                 the iOS app it is for (default: the one this checkout syncs, or the project's only one)
      --out <palbase/….storekit>  where under palbase/ (default: palbase/environments/<env>/<app>.storekit)
      --storefront <code>         the App Store storefront prices are in, by its three letters (USA, DEU, TUR, GBR, JPN …)
```

### `palbase purchases:apple`

The environment's App Store connection: the In-App Purchase key, where the App Store reports, whether Xcode's purchases are taken

```sh
palbase purchases:apple
```

### `palbase purchases:apple:connect`

Connect an In-App Purchase key for an iOS app: it goes from this computer straight to the environment, never through Studio

```sh
palbase purchases:apple:connect --key-file <SubscriptionKey_KEYID.p8> [--key-id <KEYID>] [--issuer-id <issuer id>] [--app <app>] | --print-link
```

App Store Connect → Users and Access → Integrations → In-App Purchase makes the key (`SubscriptionKey_<KEYID>.p8`) and shows the Issuer ID — the team's, the same as its App Store Connect API keys': left out, the one stores:apple connected is taken.
The environment verifies the app's purchases and reads its subscriptions with it, and has the stores module point the App Store's notifications at the environment.
Studio is asked for a one-time grant alone; the key is posted with it to the environment's own address. --print-link prints a link that takes the key in a browser instead.

```text
      --key-file <SubscriptionKey_KEYID.p8>  the .p8 file Apple gave when the key was made
      --key-id <KEYID>                       the key's id (default: from the file's name)
      --issuer-id <issuer id>                the team's issuer id (default: the connected App Store Connect key's)
      --app <app>                            the iOS app (default: the one this checkout syncs, or the project's only one)
      --print-link                           only print a link that takes the key in a browser (valid 30 minutes, once)
```

### `palbase purchases:apple:disconnect`

Forget the environment's In-App Purchase key: the App Store's purchases and notifications are refused from then on (what was bought stays)

```sh
palbase purchases:apple:disconnect
```

### `palbase purchases:apple:xcode-certificate`

Take the purchases Xcode's StoreKit Testing signs with this certificate, as test purchases — never on production; --remove stops

```sh
palbase purchases:apple:xcode-certificate <certificate.cer> | --remove
```

Xcode saves the certificate: select the .storekit file (palbase purchases:storekit makes it), then Editor › Save Public Certificate.
From then on what the app reports signed with it — Xcode's own purchases, on a developer's Mac — is a test purchase of the environment, with or without an In-App Purchase key; nothing of it is asked of Apple. Set again, it replaces the one before.
The production environment takes only what the App Store signed: it is refused there.

```text
      --remove  stop taking Xcode's purchases (those taken stay)
```

### `palbase purchases:google`

The environment's Google Play purchases: the app they are made in, the topic its Play Console names, whether Play's test notification arrived

```sh
palbase purchases:google
```

### `palbase purchases:google:connect`

Sell on Google Play in one of the project's Android apps: Palbase makes the app's notifications topic and has it pushed to this environment

```sh
palbase purchases:google:connect [--app <app>]
```

The project's Play connection (palbase stores:google:connect) is the account Palbase reads and acknowledges the app's purchases as: its Play Console invites it with View financial data and Manage orders and subscriptions.
Then, in Play Console: Monetize with Play › Monetization setup › Real-time developer notifications, the topic this prints, Save, and Send test notification — palbase purchases:google says when it arrived.

```text
      --app <app>  the Android app (default: the one this checkout syncs, or the project's only one)
```

### `palbase purchases:google:disconnect`

Stop taking the environment's Google Play purchases: Play's notifications stop reaching it, and the app's reports are refused (what was bought stays)

```sh
palbase purchases:google:disconnect
```

### `palbase purchases:doctor`

Whether the environment sells in the App Store now, check by check — the App Store Connect side and the purchases side — with the fix of each that fails

```sh
palbase purchases:doctor [--app <app>]
```

Apple is asked now: the keys, the agreements, the app's App Store Connect record, where the App Store reports, the sandbox testers, each product's state, the catalog's last confirmation; and whether Xcode's purchases are taken.
It exits 1 while a check that is not informational fails: run it again until every line is ✓.

```text
      --app <app>  the iOS app (default: the environment's one linked app)
```

### `palbase purchases:paywalls`

The environment's paywalls: each one's draft revision, the version published, and the placements that show it

```sh
palbase purchases:paywalls
```

A paywall is a JSON definition: purchases:paywalls:get writes one to a file, purchases:paywalls:put saves the edit as its draft, purchases:paywalls:publish makes the draft what the apps draw.
An app sees a paywall once it is published and a placement shows it.
How a definition is written — every component and field, and three to start from: palbase purchases:paywalls:guide

### `palbase purchases:paywalls:get`

Write a paywall's draft — or a version published — to a file to edit, with the revision it is at

```sh
palbase purchases:paywalls:get <name|id> [--out <palbase/paywalls/name.json>] [--version <n>]
```

The file is the definition alone, as purchases:paywalls:put takes it, under palbase/paywalls/. Its first line names its JSON Schema, written beside it (palbase/paywalls/paywall.schema.json), so an editor checks the file as it is edited.
The revision printed is the one an edit is saved on: purchases:paywalls:put --revision.

```text
      --out <file>   where under palbase/ (default: palbase/paywalls/<name>.json)
      --version <n>  a published version instead of the draft
```

### `palbase purchases:paywalls:validate`

Check a paywall definition as publishing it would, without saving it: every problem, by its path

```sh
palbase purchases:paywalls:validate --file <paywall.json>
```

Every rule of the schema is checked, and every package against the environment's catalog as it is. A warning (what App Review expects of a paywall, say) does not stop a save or a publish.
It exits 1 while a problem that is not a warning is left; --json prints { valid, problems } either way.

```text
      --file <paywall.json>  the definition ('-' or none: stdin)
```

### `palbase purchases:paywalls:put`

Save a definition as a paywall's draft, on the revision it was edited from — or make the paywall, at revision 0; --publish publishes it too

```sh
palbase purchases:paywalls:put <name|id> --file <paywall.json> --revision <n> [--publish]
```

The module checks it first: a definition that breaks a rule is refused with every problem, and nothing is saved.
Of two people editing at once, the second is told — the draft moved past the revision they edited — never overwritten.
What the apps draw changes only when the draft is published (--publish, or purchases:paywalls:publish). A new paywall takes the name its definition gives.
How a definition is written: palbase purchases:paywalls:guide

```text
      --file <paywall.json>  the definition, as purchases:paywalls:get wrote it ('-' or none: stdin)
      --revision <n>         the draft revision it was edited from, as purchases:paywalls:get printed it (0 makes a new paywall)
      --publish              publish the saved draft as the next version
```

### `palbase purchases:paywalls:publish`

Publish a paywall's draft as its next version: what the apps asking for a placement that shows it draw from then on

```sh
palbase purchases:paywalls:publish <name|id> [--revision <n>]
```

It is checked as the apps will get it: every package must be sold by the catalog, every asset still what was registered.
--revision names the draft revision that was looked at: a draft saved since is not published in its place. Without it, the draft as it is now is published.
A draft the same as the newest version publishes nothing new.

```text
      --revision <n>  the draft revision looked at (default: the draft as it is now)
```

### `palbase purchases:paywalls:delete`

Delete a paywall and its versions; one a placement or a running experiment shows is not deleted

```sh
palbase purchases:paywalls:delete <name|id>
```

### `palbase purchases:paywalls:schema`

The JSON Schema of a paywall definition: every component, its fields and their bounds, for an editor or an agent to check a file against

```sh
palbase purchases:paywalls:schema [--out <palbase/paywalls/paywall.schema.json>]
```

It is the module's contract, as the CLI was built with it: a file that passes may still be refused for what only the module knows (the catalog's packages, the project's assets) — purchases:paywalls:validate asks it.
purchases:paywalls:get writes it too, and names it on the first line of each file ("$schema").

```text
      --out <file>  where under palbase/ (default: palbase/paywalls/paywall.schema.json); --json prints it instead
```

### `palbase purchases:paywalls:guide`

How a paywall definition is written by hand — for an agent or a person: the flow, every component and field in the contract's words, three definitions to start from

```sh
palbase purchases:paywalls:guide [--out <palbase/paywalls/GUIDE.txt>]
```

It is made from the definition's JSON Schema the CLI carries (purchases:paywalls:schema), so it says what this version of the CLI checks.

```text
      --out <file>  write it to a file under palbase/ instead of printing it
```

### `palbase purchases:paywalls:assets`

The project's paywall assets: the images, videos, fonts and HTML blocks a definition names `asset:<id>`

```sh
palbase purchases:paywalls:assets
```

### `palbase purchases:paywalls:assets:upload`

Upload a file to the project's storage and register it for paywalls: it answers the `asset:<id>` a definition names

```sh
palbase purchases:paywalls:assets:upload <file> [--kind image|video|font|html]
```

The file goes to the project's public bucket paywall-assets (made when there is none; a private one is left as it is, and refuses). The module then reads it there, says what it is by its bytes, and keeps their SHA-256: an app draws what it downloads only when it is that.
An image is PNG, JPEG or WebP, at most 2 MiB; a video MP4 or MOV, 50 MiB; a font TTF, OTF or WOFF2, 5 MiB; an HTML block a zip with index.html at its root, 5 MiB.

```text
      --kind <kind>  what the file is meant to be: one whose bytes are another kind is refused
```

### `palbase purchases:paywalls:assets:delete`

Forget a paywall asset no paywall names, and remove its file from the project's storage

```sh
palbase purchases:paywalls:assets:delete <asset:id|id>
```

### `palbase purchases:paywalls:preview`

A picture of a paywall as an app draws it — the SDK's own renderer, in a headless browser — to look at before it is saved

```sh
palbase purchases:paywalls:preview <name|id> | --file <paywall.json> [--platform ios|android|web] [--appearance light|dark] [--locale <tag>] [--text-size default|largest] [--package <key>] [--state tab=<id>,switch=on|off,sheet=<id>] [--full] [--all] [--out <png>] [--html <file>]
```

It draws the file being edited (--file), or a paywall's draft by its name. The picture is the platform's screen: its status bar and home indicator kept clear, as on a phone. --full draws the whole paywall instead: the part that scrolls in full, the header and the footer once.
Prices are the environment's catalog's, as the platform sells each package; a package it does not sell there is drawn at a sample price, and named. The project's assets are downloaded and drawn when their bytes are the ones registered.
It needs Chrome, Chromium, Edge or Brave (PALBASE_BROWSER names another; PALBASE_BROWSER_ARGS adds to its arguments, as --no-sandbox in a container that has no sandbox for it). Without one the page is written as HTML to open, and it exits 3; when the browser or the renderer cannot draw it, 4.
--all draws every platform in both appearances at both text sizes into one folder (`palbase/paywalls/.preview/<name>/`). --html writes the page alone, to open in a browser. purchases:paywalls:check measures what is drawn and lists what is wrong.

```text
      --file <paywall.json>      the definition to draw ('-': stdin)
      --locale <tag>             the reader's language (default: the definition's default_locale)
      --package <product.plan>   the package selected
      --state <k=v,…>            tab=<id> (every tabs component on it), switch=on|off, sheet=<id> (open)
      --width <px>               the screen's width in CSS pixels (default: the platform's)
      --height <px>              the screen's height (default: the platform's)
      --platform <platform>      ios (default), android or web: the screen and the platform's rules
      --appearance <appearance>  light (default) or dark
      --text-size <size>         default, or largest: every text at the largest size a reader sets
      --full                     the whole paywall, as tall as it is, not the screen alone
      --all                      every platform × appearance × text size, into one folder
      --out <file>               the PNG under palbase/ (default: palbase/paywalls/.preview/<name>-<platform>-<appearance>.png); with --all, the folder
      --html <file>              write the page alone, as HTML under palbase/, to open in a browser
```

### `palbase purchases:paywalls:check`

Measure a paywall as an app draws it, on every screen, and list what is wrong — code — where — what — exiting 1 while anything is

```sh
palbase purchases:paywalls:check <name|id> | --file <paywall.json> [--platform …] [--appearance …] [--text-size …] [--locale <tag>] [--package <key>] [--state …]
```

It draws the paywall with the SDK's own renderer in a headless browser — every platform, light and dark, at the default and the largest text size, unless a flag names one — and measures what shows:
overflow_x: wider than the screen · text_cut: a text cut off · word_broken: a word (a price) broken across lines · purchase_hidden: no purchase button on the screen as it opens · covered_by_footer: an interactive part still under the fixed footer with the paywall scrolled to its end · large_gap: an empty band over 12% of the screen · contrast: text under WCAG's 4.5:1 (3:1 large) · selection_contrast: the selected package or tab under 3:1 from the others · small_target: a target under 44×44 on a phone, 24×24 on the web (a switch, a link inside a sentence and a carousel's dots aside) · image_missing: an image that did not load · repeated_text: the same words twice in one package.
Each names the component by its path in the definition (root.children[2]) and the words it shows. A text over a picture or a gradient is said apart, as not measured (unmeasured_contrast): a note, not a problem.
--json prints { problems: [{ code, where, message, screens }], notes: [ … ], screens }.
It exits 0 when nothing is wrong, 1 when something is (and on a refusal: --json then prints { error } instead), 3 without a browser, 4 when the browser or the renderer could not draw the paywall.

```text
      --file <paywall.json>      the definition to draw ('-': stdin)
      --locale <tag>             the reader's language (default: the definition's default_locale)
      --package <product.plan>   the package selected
      --state <k=v,…>            tab=<id> (every tabs component on it), switch=on|off, sheet=<id> (open)
      --width <px>               the screen's width in CSS pixels (default: the platform's)
      --height <px>              the screen's height (default: the platform's)
      --platform <platform>      ios, android or web alone (default: all three)
      --appearance <appearance>  light or dark alone (default: both)
      --text-size <size>         default or largest alone (default: both)
```

### `palbase purchases:paywalls:templates`

The module's designed paywalls to start from: each one's key, what it looks like, and the packages it sells

```sh
palbase purchases:paywalls:templates
```

palbase purchases:paywalls:new `<name>` --template `<key>` writes one to a file, selling the catalog's own packages.

### `palbase purchases:paywalls:new`

Write a new paywall's definition to a file from one of the module's templates, selling the catalog's own packages, its pictures uploaded to the project

```sh
palbase purchases:paywalls:new <name> --template <key> [--package <template package>=<product.plan> …] [--out <palbase/paywalls/name.json>]
```

A template sells pro.monthly, pro.yearly, family.monthly, family.yearly and lifetime.once: each is renamed to the catalog's package that stands for it — the same one when the catalog sells it, else a plan of the same period. One that nothing stands for is said, and stays: --package `pro.yearly=<product>.<plan>` names it.
A template's pictures are uploaded to the project's public bucket paywall-assets (made when there is none; a private one is left as it is, and nothing is written) and registered; the definition names the project's assets in their place.
Nothing is saved to the environment but those assets: the file is edited, checked and looked at (purchases:paywalls:validate, :preview, :check), then saved with purchases:paywalls:put `<name>` --file `<file>` --revision 0.

```text
      --template <key>     the template, as purchases:paywalls:templates lists them
      --package <from=to>  a template's package and the catalog's that stands for it (repeat it, or a comma list)
      --out <file>         where under palbase/ (default: palbase/paywalls/<name>.json)
```

### `palbase purchases:placements`

The environment's placements: each one's default paywall, its rules and the experiment running on it

```sh
palbase purchases:placements
```

An app asks for a placement by its key (pb.purchases.paywall("onboarding")): an experiment running for everyone there decides first, then the first of its rules that holds for the viewer, then its default paywall.

### `palbase purchases:placements:set`

Give a placement its default paywall — what it shows whoever none of its rules holds for — making the placement when it is new

```sh
palbase purchases:placements:set <placement> --paywall <name|id>
```

The apps asking for it get the paywall's newest version they can draw; a paywall never published is nothing yet: they draw their own until it is.

```text
      --paywall <name|id>  the paywall it shows
```

### `palbase purchases:placements:delete`

Forget a placement and its rules: the apps that ask for it draw their own paywall

```sh
palbase purchases:placements:delete <placement>
```

### `palbase purchases:placements:rules:get`

A placement's rules, in the order they are read — each with its conditions, schedule and target — and their revision

```sh
palbase purchases:placements:rules:get <placement> [--out <palbase/….json>]
```

--out writes them to a file to edit ({ "rules": [ … ] }); rules:put saves the edit on the revision printed.

```text
      --out <file>  write the rules to this file, under palbase/
```

### `palbase purchases:placements:rules:put`

Replace a placement's rules — all of them, in the order they are to be read — on the revision they were edited from

```sh
palbase purchases:placements:rules:put <placement> --file <rules.json> --revision <n>
```

The first rule in effect whose conditions all hold for a viewer shows its target: a published paywall, or the variant of the experiment running on the placement for the rules. At most 50 rules of at most 10 conditions.
A condition reads country, platform, app, app_version, sdk_version, locale, entitlement, first_seen_days or an attribute the app sends; purchases:placements:preview tries rules against a viewer before they are saved (--rules).
Of two people editing at once, the second is told — the rules moved past the revision they edited — never overwritten.

```text
      --file <rules.json>  the rules, as rules:get --out wrote them ('-' or none: stdin)
      --revision <n>       the revision they were edited from, as rules:get printed it
```

### `palbase purchases:placements:preview`

What a placement shows a viewer, and why: the experiment, the rule that decided — every rule, condition by condition — or the default

```sh
palbase purchases:placements:preview <placement> [--platform ios|android|web] [--country TR] [--app-version 2.1.0] [--sdk palbase-swift@0.2.0] [--locale tr-TR] [--attr key=value …] [--user <id>] [--rules <file>] [--at <RFC3339>]
```

The viewer is what its app would send. With --user, the user's entitlements and the days since they were first seen are the project's; the user (else an installation) is who an experiment's variant is drawn for.
--rules tries rules not yet saved (a rules:put file) instead of the saved ones; --at, a moment (a scheduled rule's start). Nothing is counted or changed.

```text
      --platform <platform>    ios, android or web
      --country <code>         the store's country: ISO 3166-1, two or three letters
      --app-version <version>  the app's version
      --sdk <name@version>     the SDK the app draws with (palbase-swift@0.2.0)
      --locale <tag>           the viewer's language (BCP 47)
      --attr <key=value>       what the app says of the viewer (repeat it, or a comma list)
      --user <id>              the signed-in user
      --rules <file>           rules to try instead of the saved ones
      --at <RFC 3339>          the moment (default: now)
```

### `palbase purchases:placements:results`

What each of a placement's rules showed and what its viewers did — exposures, viewers, purchases, conversion, revenue — beside the rules since removed, an experiment's variants and the default

```sh
palbase purchases:placements:results <placement> [--days <n>] [--window-days <n>] [--sandbox]
```

What was shown in the last days (30 unless said, at most 90). The rules come in the order they are read, then the rules the placement no longer has, the variants of an experiment for everyone there, its default.
A purchase counts once, for what its buyer saw first at the placement, within the window after seeing it (7 days unless said): the purchases the stores confirmed, never what an app reports. Revenue is what was paid to date, renewals in, refunds out.

```text
      --days <n>         the days of what was shown the results look back over, 1 to 90 (default 30)
      --window-days <n>  the days after first seeing what was shown a purchase counts for it, 1 to 90 (default 7)
      --sandbox          count the stores' test purchases too
```

### `palbase purchases:placements:attributes`

The attribute keys the environment's apps sent with a placement's paywall, as they said them — suggestions for attribute conditions, the most used first, each with its JSON type and the hours it was seen in

```sh
palbase purchases:placements:attributes
```

An app sends what it says of the viewer as attributes (pb.purchases.paywall(placement, { attributes })); the keys are kept, never the values. They are what apps said, unverified — anyone with the publishable key can send one —: a help to write rules, not a list of what the app defines.
A key is seen again at most once an hour, and counted in one more hour as often. At most 200 are kept: past them a new key takes the place of the key seen longest ago once that one was last seen over a day ago, so keys sent once age out.

### `palbase purchases:experiments`

The environment's paywall experiments: the placement each runs on, its variants and their shares, and how it ended

```sh
palbase purchases:experiments [--placement <placement>]
```

```text
      --placement <placement>  one placement's alone
```

### `palbase purchases:experiments:start`

Start an experiment on a placement: each viewer is shown one of 2 to 4 published paywalls, by weight, the same one every time

```sh
palbase purchases:experiments:start <placement> --variants <paywall>=<weight>,<paywall>=<weight>[,…] [--audience placement|rules] [--name <name>]
```

audience placement (the default): everyone at the placement, decided before its rules; the placement is made when new and keeps its default for when the experiment ends.
audience rules: only the viewers the placement's rules send to it — a rule's target names the experiment (purchases:placements:rules:put).
The first variant is what a stop keeps. One experiment runs on a placement at a time; each variant's paywall must be published.

```text
      --variants <paywall=weight,…>  the paywalls (name or id) and their weights; key:paywall=weight names a key (else a, b, c, d)
      --audience <audience>          placement (default) or rules
      --name <name>                  the experiment's name (default: the placement and its paywalls)
```

### `palbase purchases:experiments:stop`

Stop a running experiment, at once: what it showed becomes its first variant's paywall; its results stay

```sh
palbase purchases:experiments:stop <id|name>
```

### `palbase purchases:experiments:winner`

End a running experiment with its winner: the winner's paywall becomes the placement's default — or, with --as-rule, a rule shows it to everyone

```sh
palbase purchases:experiments:winner <id|name> --variant <key> [--as-rule]
```

For an experiment for everyone at the placement, --as-rule rolls the winner out as a live rule at the top of its rules (to narrow later) and leaves the default as it is. For one for the rules, the rules that targeted it show the winner's paywall.
purchases:experiments:results says which variant leads and whether calling it is sound yet.

```text
      --variant <key>  the winning variant's key
      --as-rule        roll the winner out as a rule for everyone, at the top of the placement's rules
```

### `palbase purchases:experiments:results`

What each variant's viewers did — exposures, viewers, purchases, conversion, revenue — each one's chance to convert best, and whether calling the leader is sound

```sh
palbase purchases:experiments:results <id|name> [--window-days <n>] [--sandbox]
```

A purchase counts for the first variant its buyer saw, within the window after seeing it (7 days unless said): the purchases the stores confirmed, never what an app reports. Revenue is what was paid to date, renewals in, refunds out.
The chance to win is Bayesian (each variant's rate a Beta distribution): how likely each one is best. The leader is called soundly once every variant has been seen enough and its chance is high enough; until then the reasons are said.

```text
      --window-days <n>  the days after first seeing a variant a purchase counts for it, 1 to 90 (default 7)
      --sandbox          count the stores' test purchases too
```

### `palbase purchases:charts`

The purchase charts, each with its definition: what it counts, over which period, and how refunds, product changes, resubscriptions and test purchases count

```sh
palbase purchases:charts
```

A chart is read with purchases:charts:get `<chart>`; the figures of now with purchases:charts:overview.

### `palbase purchases:charts:overview`

The project's figures at a glance: MRR, active subscriptions and trials now; revenue, new customers and active customers over the last 28 days

```sh
palbase purchases:charts:overview [--revenue-type gross|net_of_taxes|proceeds] [--currency <code>] [--sandbox]
```

```text
      --revenue-type <type>  gross (default), net_of_taxes or proceeds
      --currency <code>      the currency to report money in (default: the reporting currency)
      --sandbox              count the stores' test purchases too
```

### `palbase purchases:charts:get`

One purchase chart, period by period — a table of its periods and segments, or the module's CSV

```sh
palbase purchases:charts:get <chart> [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--resolution day|week|month] [--segment <dimension>] [--filter <dimension:value>]… [--revenue-type <type>] [--currency <code>] [--window-days <n>] [--cohort new_customers|new_paying_customers] [--sandbox] [--csv [--out <palbase/….csv>]]
```

Days are UTC; from and to are both included, at most two years apart (by default the last 30 days, 12 weeks or 12 months). A period marked `*` is not over: its value may still change.
Money is in the reporting currency (purchases:charts:settings) at the European Central Bank's rate of the day it was paid; proceeds take off the store's commission and Stripe's fee, which the ledger does not hold: they are estimated, and so are taxes a store did not state.
--csv prints the module's CSV (a row a segment and period) — on the terminal its control characters escaped —; with --out it is written to that file, under palbase/. A cell that would start a spreadsheet formula (=, +, -, @) begins with a quote.

```text
      --from <YYYY-MM-DD>         the first day
      --to <YYYY-MM-DD>           the last day, included (default today)
      --resolution <resolution>   day (default), week or month
      --segment <dimension>       split by a dimension (purchases:charts lists them)
      --filter <dimension:value>  keep only this value, one each --filter: --filter store:app_store --filter country:TR
      --revenue-type <type>       gross (default), net_of_taxes or proceeds
      --currency <code>           the currency to report money in (default: the reporting currency)
      --window-days <n>           the conversion window or customer lifetime, in days from a customer's first day, 0 to 730 (default: to now)
      --cohort <cohort>           the cohort explorer's cohorts: new_customers (default) or new_paying_customers
      --sandbox                   count the stores' test purchases too
      --csv                       the module's CSV instead of a table
      --out <file>                with --csv, write it to this file, under palbase/
```

### `palbase purchases:charts:settings`

The charts' settings — the reporting currency, the stores' commission, Stripe's fee and the App Store's fee on web purchases linked out of the app — read, or changed with the flags given

```sh
palbase purchases:charts:settings [--currency <code>] [--commission standard|small_business] [--stripe-percent <n>] [--stripe-fixed <amount>] [--stripe-fixed-currency <code>] [--app-store-link-percent <n>] [--app-store-link-days <n>]
```

Every amount is converted to the reporting currency at the European Central Bank's rate of the day it was paid; the ledger keeps what was paid as it was paid, so a change redraws every chart from its first day.
The commission is what proceeds take off App Store and Google Play payments: standard (30%; 15% of a subscription's renewals after its first paid year in the App Store, and of every Google Play subscription) or small_business (15%). Stripe's fee — its share and fixed part — is taken off web payments; the ledger does not hold it, so proceeds are estimated.
The App Store's link fee is what Apple takes of a web purchase bought through a link out of the iOS app in its United States storefront, within the days after the link: nothing today (App Review Guideline 3.1.1(a)), set here once Apple charges one.

```text
      --currency <code>               the reporting currency, one the European Central Bank published a rate for in the last ten days
      --commission <commission>       standard (30%) or small_business (15%)
      --stripe-percent <n>            Stripe's share of a payment, in percent (2.9)
      --stripe-fixed <amount>         Stripe's fixed fee of a payment (0.30)
      --stripe-fixed-currency <code>  the currency of Stripe's fixed fee (USD)
      --app-store-link-percent <n>    the App Store's share of a web purchase linked out of the iOS app, in percent (0)
      --app-store-link-days <n>       for how many days after the link a purchase owes it (7)
```

## `journeys`

### `palbase journeys:get`

A journey's definition, as JSON: to edit and push again (a draft), or to push under a new key (a published one)

```sh
palbase journeys:get <key>
```

### `palbase journeys:validate`

Check a journey file without saving it: every problem, at its path, with what to do about it

```sh
palbase journeys:validate <file|->
```

### `palbase journeys:push`

Save a journey file as a draft — new, or the draft's new version — and, with --publish, publish it

```sh
palbase journeys:push <file|-> [--key <key>] [--publish]
```

The key is --key, else the file's name (winback.json is winback).
A published journey does not change: push the file under a new key with --publish, then stop the old one (journeys:stop).

```text
      --key <key>  the journey's key (default: the file's name)
      --publish    publish it once saved: people enter from then on
```

### `palbase journeys:publish`

Publish a draft: people enter it from now on, and it no longer changes

```sh
palbase journeys:publish <key>
```

### `palbase journeys:simulate`

Walk a made-up person through a journey — a file, or a key — as it would run: each step, when, what it would do, how it ends; nothing is sent

```sh
palbase journeys:simulate <file|key> [--user <id>] [--property name=value]… [--audience <id>]… [--timezone <zone>] [--event name@PT2H]… [--start <time>]
```

The person enters at --start (now unless it says) and does each --event a while after entering: --event purchases.purchase.completed@P1D.
Their --property values are what branches read, --audience the audiences they are in, --timezone where a wait until a time of day is.

```text
      --user <id>              the person's id (it picks their way at a split)
      --property <name=value>  a property of theirs
      --audience <id>          an audience they are in
      --timezone <zone>        their IANA time zone (Europe/Istanbul)
      --event <name@while>     an event of theirs, a while after entering (PT2H, P1D)
      --start <time>           when they enter (RFC 3339); now unless it says
```

### `palbase journeys:stats`

What came of a journey: who entered, how their runs ended, who is in it now, its goal's conversions, each step's outcomes

```sh
palbase journeys:stats <key>
```

### `palbase journeys:runs`

A journey's people: each run's state, the step it is at, how it ended, and the steps it took

```sh
palbase journeys:runs <key> [--user <id>] [--state held|active|waiting|ended] [--limit <n>]
```

```text
      --user <id>      one person's runs
      --state <state>  held, active, waiting or ended
      --limit <n>      how many, newest first (default 50, at most 200)
```

### `palbase journeys:stop`

Stop a live journey for good: no one enters it, the runs in it end, its report stays

```sh
palbase journeys:stop <key>
```

### `palbase journeys:copy`

Copy a journey's definition into a new draft: how a published journey is changed

```sh
palbase journeys:copy <key> <new-key> [--name <name>]
```

```text
      --name <name>  the copy's name (default: the journey's)
```

### `palbase journeys:delete`

Delete a journey with its runs and its report; the people in a live one leave it at once

```sh
palbase journeys:delete <key>
```

## `apps`

### `palbase apps:list`

The project's apps, and what each is in every environment it is set in

```sh
palbase apps:list
```

### `palbase apps:create`

Register an app of the project (an iOS app names its Apple team); then set it in each environment (apps:env:set)

```sh
palbase apps:create ios|android|web <name> [--slug <slug>] [--team-id <id>] [--app-id-prefix <prefix>]
```

An app is one product on one platform: its widgets, notification service and other extensions are not apps of their own — Apple gives them bundles under the app's, and they share its sign-in.
The slug is the app's file in a checkout: `palbase/environments/<env>/<slug>.json`.

```text
      --slug <slug>             its name in a checkout (default: from the name)
      --team-id <id>            an iOS app's Apple team: 10 characters, Apple Developer › Membership
      --app-id-prefix <prefix>  an iOS app's App ID prefix when it is not the team's (an app made before 2011, or moved from another team)
```

### `palbase apps:get`

An app of the project, with what it is and its key in every environment it is set in

```sh
palbase apps:get <app>
```

### `palbase apps:update`

Rename an app, or change an iOS app's Apple team: every environment it is in is told

```sh
palbase apps:update <app> [--name <name>] [--team-id <id>] [--app-id-prefix <prefix>|""]
```

```text
      --name <name>             what it is called
      --team-id <id>            an iOS app's Apple team
      --app-id-prefix <prefix>  its App ID prefix; "" for the team's
```

### `palbase apps:delete`

Delete an app: suspended in every environment for 30 days — its builds stop reaching the project — then removed for good

```sh
palbase apps:delete <app>
```

### `palbase apps:restore`

Bring a deleted app back as it was, with its keys, in every environment

```sh
palbase apps:restore <app>
```

### `palbase apps:env:set`

What an app is in the environment: its bundle (iOS), package and signing certificates (Android) or origins (web)

```sh
palbase apps:env:set <app> [--bundle <id> [--app-clip <id>] [--watch <id>]] [--package <id> --sha256 <label>=<fingerprint>…] [--origin <url>… --redirect <url>…]
```

iOS: the app's bundle in this environment; its App Clip and watch app are the bundle followed by one more part. Its extensions are not set: they share the app's.
Android: its application ID and the SHA-256 of each certificate it is signed with — Play Console › App signing (Google's app signing key, not the upload key), ./gradlew signingReport for a debug key. Label each: debug, play_signing, upload…
Web: the origins its pages are served from (https; http only on this computer) and the addresses a sign-in may return to.
The platform publishes it to Apple and Google for the environment: a device sees a change in a day or so (Apple caches its file; Android 15 re-checks within a week).

```text
      --bundle <id>                 an iOS app's bundle identifier here
      --app-clip <id>               its App Clip's bundle (the bundle followed by one more part)
      --watch <id>                  its watch app's bundle (the bundle followed by one more part)
      --package <id>                an Android app's application ID here
      --sha256 <label=fingerprint>  a signing certificate's SHA-256, labelled (play_signing=AB:CD:…); every one the app is signed with
      --origin <url>                a web app's origin
      --redirect <url>              an address a sign-in may return to
```

### `palbase apps:env:unset`

Take an app out of the environment: its key there revoked, Apple's and Google's files no longer naming it

```sh
palbase apps:env:unset <app>
```

### `palbase apps:sync`

Write each environment's settings and backend clients (Palbe) of this checkout's apps under palbase/ — nothing else is touched

```sh
palbase apps:sync [<app>…] [--check] [--types <env>] [--backend [<machine>=]<dir>] [--as <machine>=<name>]…
```

The apps named join this checkout's (palbase/project.json); with none named, its apps are synced.
`palbase/environments/<env>/`: each app's settings (`<app>.json`), each backend's contract (`contracts/<machine>.openapi.json`) and Palbe client made from it — TypeScript for a web app, Swift for an iOS app (in `palbase/<app>.palbase`), Kotlin for an Android app. A web app imports pb from `palbase/<app>.ts`: one environment's for the editor (--types), the build's mode's for the build (palbase() in vite.config), which type-checks the app against that environment.
--check writes nothing: it exits 1 naming what differs from the project now — for CI.
--backend makes a backend's Palbe from its checkout on this computer (its palbase/backend app writes its contract and exits; nothing is connected to), to try an endpoint before any machine serves it.
A backend is `pb.<name>` in the apps — pb.shopApi.rooms.create() for the machine shop-api — unless --as names it (--as shop-api=shop): the name is the checkout's, the same in every environment, and none of the client's own (auth, flags, storage, …).

```text
      --check                    write nothing; exit 1 when the checkout is not what the project gives now
      --types <env>              the environment the editor's types are of (remembered in palbase/project.json)
      --backend <[machine=]dir>  a backend's checkout here: its Palbe made from the contract it writes, not from its machine's
      --as <machine=name>        a backend's name in the apps (pb.<name>): its machine's camelCased unless named; the same in every environment (remembered in palbase/project.json)
```

### `palbase apps:sdkconfig`

An app's settings in the environment, as palbase apps:sync writes them: its address, its publishable key, what its modules tell it

```sh
palbase apps:sdkconfig <app> [--format json|env]
```

The publishable key is public: it ships in the app. A secret key never does.

```text
      --format <format>  json (default) or env
```

## `github`

### `palbase github:connect`

Link the environment to GitHub: Palbase Cloud's GitHub app on the account whose repositories machines are built from

```sh
palbase github:connect [--device | --github-token-stdin | --from <env> [--repo <owner/name>…]] [--installation <account|id>] [--all-envs]
```

Opens GitHub; back from it, the page shows the account and you link it by writing the environment's ref.
--from `<env>`: the installation another environment of the organization linked (its slug in this project, or its ref), linked here too with no GitHub sign-in — a program that opens a project for each product (an admin, or an admin access token). The environment reaches what the GitHub user who linked it there can push to.
--repo `<owner/name>` (given again for more): with --from, the environment reaches those repositories of the installation alone, never one it reaches later — a product's environment builds nothing of another product's.
--device: no browser here — GitHub's device flow (a code you enter at github.com/login/device on any device); the GitHub token stays in memory.
--all-envs links every environment of the project the same way.

```text
      --device                     GitHub's device flow, for a computer with no browser (a server, an agent)
      --github-token-stdin         a GitHub user's token from stdin (CI): the installations it reaches, no browser and no code
      --installation <account|id>  which installation to link, when the GitHub user reaches more than one (--device)
      --all-envs                   link every environment of the project
      --from <env>                 another environment of the organization whose linked installation this one shares (its slug in this project, or its ref): no GitHub sign-in
      --repo <owner/name>          with --from: the repositories it reaches of the installation, and no other (given again for more)
```

### `palbase github:list`

The GitHub accounts linked to the environment, and who linked each

```sh
palbase github:list
```

### `palbase github:repos`

The repositories machines of the environment may be built from

```sh
palbase github:repos
```

### `palbase github:disconnect`

Unlink a GitHub account from the environment; its repositories are no longer built

```sh
palbase github:disconnect <account|installation-id>
```

## `machines`

### `palbase machines:sizes`

The machine sizes, and which of them this environment may open now

```sh
palbase machines:sizes
```

### `palbase machines:list`

The environment's machines: size, state, the version serving, address

```sh
palbase machines:list
```

### `palbase machines:call`

Call a route of a machine's backend as its apps do: the fields its contract marks encrypted sealed, its answer's opened

```sh
palbase machines:call <machine> <METHOD> <path> [--data <json>] [--token <access token>]
```

palbase machines:call api POST /patients --data '{"name":"Ada","tc":"10000000146"}'
The route is found in the machine's contract; a field it marks encrypted (palbase/backend's encrypted() and encrypt()) goes sealed to the project's key in use and comes back opened, as the app's generated client does.
--token is a user's access token, for a route that takes one; without it the call is nobody's.

```text
      --data <json>    the request's body, as JSON
      --token <token>  a user's access token: the call is theirs
```

### `palbase machines:get`

A machine in full: its source, size, environment, database and the build serving

```sh
palbase machines:get [name]
```

### `palbase machines:create`

Make a machine from the code in this directory, built on every push to its branch

```sh
palbase machines:create [name] [--size <size>] [--db <database> --migrations] [--repo --branch --path --context] …
```

Run in a checkout, it reads the repository from origin, the branch from HEAD and the directory from where you are; flags say otherwise.
The first build starts at once; --wait follows it until the machine serves, and prints its address.
The environment needs its GitHub link first: palbase github:connect.

```text
      --repo <owner/name>                 the GitHub repository (default: this checkout's origin)
      --branch <branch>                   the branch whose pushes are built and rolled out (default: the one checked out)
      --path <dir>                        the directory built, from the repository's root (default: this directory's place in it)
      --context <dir>                     what the build is given above --path (a monorepo: ".")
      --size <size>                       its size (palbase machines:sizes lists them)
      --replicas <n>                      how many copies run, each on a node of its own
      --port <port>                       the port it listens on (it also finds it in PORT)
      --health <path>                     where it answers 2xx while well; a release that does not is not rolled out
      --openapi-path <path>               where its app serves its OpenAPI contract, when it is not a Palbase backend (apps:sync makes its client from it); "" for a Palbase backend's own
      --db <database>                     a database of the environment it is given (PALBASE_DB_URL); "" for none
      --migrations                        run the database's migrations before each release (a Palbase backend's)
      --secrets <production|development>  the secrets it is started with, by name; "" for none
      --var <K=V>                         a setting it is started with (repeat it); secrets go in secrets:set
      --test-command <command>            what each new build runs before it takes traffic, in its image, against the new version itself once its migration has run (bun test, npm test); a failure fails the build and the machine runs what it ran; "" for none
      --test-users <names>                the test users each test run makes for its tests (api.signInAs), comma-separated; "" for none
      --wait                              follow the first build until the machine serves
```

### `palbase machines:update`

Change a machine: the change rolls out as a new version beside the one serving

```sh
palbase machines:update [name] [--size …] [--replicas …] [--db …] [--repo --branch --path --context] …
```

```text
      --repo <owner/name>                 the GitHub repository (default: this checkout's origin)
      --branch <branch>                   the branch whose pushes are built and rolled out (default: the one checked out)
      --path <dir>                        the directory built, from the repository's root (default: this directory's place in it)
      --context <dir>                     what the build is given above --path (a monorepo: ".")
      --size <size>                       its size (palbase machines:sizes lists them)
      --replicas <n>                      how many copies run, each on a node of its own
      --port <port>                       the port it listens on (it also finds it in PORT)
      --health <path>                     where it answers 2xx while well; a release that does not is not rolled out
      --openapi-path <path>               where its app serves its OpenAPI contract, when it is not a Palbase backend (apps:sync makes its client from it); "" for a Palbase backend's own
      --db <database>                     a database of the environment it is given (PALBASE_DB_URL); "" for none
      --migrations                        run the database's migrations before each release (a Palbase backend's)
      --secrets <production|development>  the secrets it is started with, by name; "" for none
      --var <K=V>                         a setting it is started with (repeat it); secrets go in secrets:set
      --test-command <command>            what each new build runs before it takes traffic, in its image, against the new version itself once its migration has run (bun test, npm test); a failure fails the build and the machine runs what it ran; "" for none
      --test-users <names>                the test users each test run makes for its tests (api.signInAs), comma-separated; "" for none
```

### `palbase machines:env:list`

What a machine is started with, and where each comes from (the platform, the machine, its secrets)

```sh
palbase machines:env:list [name]
```

### `palbase machines:env:set`

Set settings a machine is started with (not secrets: secrets:set keeps those)

```sh
palbase machines:env:set K=V… [--machine <name>]
```

```text
      --machine <name>  the machine (default: the only one, or this directory's)
```

### `palbase machines:env:unset`

Take settings away from what a machine is started with

```sh
palbase machines:env:unset K… [--machine <name>]
```

```text
      --machine <name>  the machine (default: the only one, or this directory's)
```

### `palbase machines:builds`

A machine's builds, newest first

```sh
palbase machines:builds [name]
```

### `palbase machines:builds:log`

A build's log (the newest build's when none is named)

```sh
palbase machines:builds:log [build] [--machine <name>]
```

```text
      --machine <name>  the machine (default: the only one, or this directory's)
```

### `palbase machines:logs`

A machine's log: the last hour, or since a time; -f follows what it writes next

```sh
palbase machines:logs [name] [-f] [--since <time>] [--lines <n>] [--search <text>]
```

```text
  -f, --follow         keep printing what the machine writes
      --since <time>   from when: an RFC 3339 time, or 10m, 2h, 1d ago
      --lines <n>      how many lines at most (default 200)
      --search <text>  only the lines that hold this text
```

### `palbase machines:deploy`

Build the head of a machine's branch now and roll it out, as a push does

```sh
palbase machines:deploy [name] [--wait]
```

A push to the branch does this by itself; this is for the one GitHub did not deliver, or a build again.
The commit is the branch's head on GitHub: push first.

```text
      --wait  follow the build until the machine serves it
```

### `palbase machines:rollback`

Serve an earlier build again (the one before the serving one, or a named one)

```sh
palbase machines:rollback [name] [--to <build>]
```

```text
      --to <build>  the build to go back to (default: the last one that served before)
```

### `palbase machines:crons`

The crons a machine runs on a schedule (its app's @Cron classes): when each is next due, on which zone's clocks, and how its last run went

```sh
palbase machines:crons [name]
```

### `palbase machines:crons:runs`

A cron's runs, newest first

```sh
palbase machines:crons:runs <cron> [--machine <name>]
```

```text
      --machine <name>  the machine (default: the only one, or this directory's)
```

### `palbase machines:crons:run`

Run a cron now, apart from its schedule — the machine woken for it if asleep

```sh
palbase machines:crons:run <cron> [--machine <name>]
```

```text
      --machine <name>  the machine (default: the only one, or this directory's)
```

### `palbase machines:crons:pause`

Pause a cron: it is not run until resumed, whatever version of the machine comes up meanwhile

```sh
palbase machines:crons:pause <cron> [--machine <name>]
```

```text
      --machine <name>  the machine (default: the only one, or this directory's)
```

### `palbase machines:crons:resume`

Resume a paused cron: it is due at its next time from now — what it missed is not made up

```sh
palbase machines:crons:resume <cron> [--machine <name>]
```

```text
      --machine <name>  the machine (default: the only one, or this directory's)
```

### `palbase machines:tasks`

The tasks on a machine's queue (its app's @Task classes), newest first: of one state, one type, or all

```sh
palbase machines:tasks [--machine <name>] [--state waiting|running|succeeded|failed|cancelled] [--task <type>] [--limit <n>]
```

```text
      --machine <name>  the machine (default: the only one, or this directory's)
      --state <state>   only tasks in this state
      --task <type>     only tasks of this type
      --limit <n>       the most listed (50; 100 at most)
```

### `palbase machines:tasks:types`

The task types a machine's running version declares, and what each one's queue holds

```sh
palbase machines:tasks:types [name]
```

### `palbase machines:tasks:get`

One task on a machine's queue, with what it carries

```sh
palbase machines:tasks:get <task id> [--machine <name>]
```

```text
      --machine <name>  the machine (default: the only one, or this directory's)
```

### `palbase machines:tasks:enqueue`

Put a task on a machine's queue, as its app's Tasks.enqueue does

```sh
palbase machines:tasks:enqueue <type> [--payload '<json>'] [--delay <seconds>] [--key <key>] [--machine <name>]
```

```text
      --machine <name>   the machine (default: the only one, or this directory's)
      --payload <json>   what it carries: a JSON value (64 KiB at most)
      --delay <seconds>  due this many seconds from now (30 days at most)
      --key <key>        put once under this key (held until a day after the task is over)
```

### `palbase machines:tasks:retry`

Put a task that failed back on the queue, due now, with as many attempts again as its type gives

```sh
palbase machines:tasks:retry <task id> [--machine <name>]
```

```text
      --machine <name>  the machine (default: the only one, or this directory's)
```

### `palbase machines:tasks:cancel`

Take a task that is waiting off the queue: it is not run, nor tried again

```sh
palbase machines:tasks:cancel <task id> [--machine <name>]
```

```text
      --machine <name>  the machine (default: the only one, or this directory's)
```

### `palbase machines:contract`

The API a Palbase backend serves (its OpenAPI document), as the platform reads it from the machine

```sh
palbase machines:contract [name]
```

### `palbase machines:delete`

Delete a machine: it stops serving, its address answers nothing

```sh
palbase machines:delete <name>
```

## `databases`

### `palbase databases:sizes`

The database sizes, and which of them this environment may open now

```sh
palbase databases:sizes
```

### `palbase databases:list`

The environment's databases: size, state, how full

```sh
palbase databases:list
```

### `palbase databases:get`

A database in full, with how to connect to it

```sh
palbase databases:get <name>
```

### `palbase databases:create`

Open a database; its passwords are kept on this computer (the platform shows them once)

```sh
palbase databases:create [name] [--size <size>] [--allow <ip/cidr,…>] [--backup-days <n>] [--show-passwords]
```

```text
      --size <size>      its size (palbase databases:sizes lists what is open)
      --allow <list>     who may connect, as addresses or CIDRs, comma-separated (default: anyone with the password)
      --backup-days <n>  how many days of backups to keep, 1 to 35
      --show-passwords   print the passwords too (they are kept on this computer either way)
```

### `palbase databases:update`

Change a database's size, who may connect to it, or how long its backups are kept

```sh
palbase databases:update <name> [--size <size>] [--allow <list>|""] [--backup-days <n>] [--wait]
```

A new size is taken at once and the database moves to it serving on (palbase databases:sizes lists them): its sessions on the direct port end once, when its primary moves, and new logins wait a few seconds then.

```text
      --size <size>      the size to move it to
      --allow <list>     who may connect (comma-separated addresses or CIDRs); "" for anyone with the password
      --backup-days <n>  how many days of backups to keep, 1 to 35
      --wait             with --size: follow the move until it serves at the new size
```

### `palbase databases:password:reset`

Make a database role's password new; it is kept on this computer, the old one stops working

```sh
palbase databases:password:reset <name> --role owner|app [--show-password]
```

The app role's new password reaches the machines given the database as they roll out with it; they keep serving.

```text
      --role <role>    owner (migrations, the console) or app (what the machines use)
      --show-password  print it too
```

### `palbase databases:restore`

Bring a database back to a moment of its backups

```sh
palbase databases:restore <name> --to <time>
```

```text
      --to <time>  the moment, as an RFC 3339 time (2026-10-08T12:00:00Z)
```

### `palbase databases:delete`

Delete a database (the platform keeps it 7 days to take back)

```sh
palbase databases:delete <name>
```

### `palbase databases:undelete`

Take back a database deleted in the last 7 days

```sh
palbase databases:undelete <name>
```

### `palbase databases:purge`

Delete a deleted database for good, now

```sh
palbase databases:purge <name>
```

## `db`

### `palbase db:url`

A database's connection address, for any tool (Prisma, Drizzle, pg_dump, a GUI)

```sh
palbase db:url [name] [--role owner|app] [--pooled] [--with-password]
```

Without --with-password the address holds no password: give the tool PGPASSWORD, or pass --with-password and keep the line out of your history.
The address asks for a checked certificate (sslmode=verify-full). Node drivers check it against the system's roots by themselves; psql, pg_dump and other libpq tools do only with PGSSLROOTCERT=system (Postgres 16+). The address does not say so itself: a driver that sends what it does not know to the server (postgres.js) would be refused.

```text
      --role <role>    owner (migrations, dumps) or app (what the machines use); default owner
      --pooled         the pooled port (PgBouncer, transaction mode): for an app's many short connections
      --with-password  put the password in the address
```

### `palbase db:shell`

Psql on a database (it wakes if asleep); -c runs one statement and ends

```sh
palbase db:shell [name] [--role owner|app] [--command <sql>]
```

```text
      --role <role>    owner (migrations, dumps) or app (what the machines use); default owner
  -c, --command <sql>  run this and end
```

### `palbase db:dump`

A copy of a database (pg_dump's custom format), as its owner

```sh
palbase db:dump [name] [--file <path>] [--schema-only]
```

```text
      --file <path>  where to write it (default <database>-<time>.dump)
      --schema-only  its structure, not its data
```

### `palbase db:restore`

Load a dump into a database, as its owner: a custom-format dump (pg_restore) or a .sql file (psql)

```sh
palbase db:restore <file> [--db <name>] [--clean]
```

A database Palbase did not make is taken over by its first release: its tables stay as they are (palbase db:pull writes their schema files).

```text
      --db <name>  the database (default: the environment's only one)
      --clean      drop what the dump makes before making it again
```

### `palbase db:copy`

Copy a database's data from one environment of the project to another

```sh
palbase db:copy --from <env> --to <env> [--db <name>] [--to-db <name>]
```

The target is overwritten with the source: what it held of the same tables goes (pg_restore --clean).
An encrypted field (.encrypted(), palbase/server's fields) is copied as •••, sealed with the target's keys: one environment's values never land readable in another.

```text
      --from <env>    the environment copied from (slug)
      --to <env>      the environment copied into (slug)
      --db <name>     the source's database (default: its only one)
      --to-db <name>  the target's database (default: the same name)
```

### `palbase db:plan`

What a start of the app's schema would do to a database, and what it would refuse — nothing is changed

```sh
palbase db:plan [--url <postgres-url> | --db <name>] [--check]
```

--check ends with 1 when the schema would be refused: run it in CI before a push to production (-E main).

```text
      --url <postgres-url>  a database of your own (a local Postgres 18): the schema goes in it at once
      --db <name>           the environment's database (default: its only one)
      --entry <file>        the app's entry, what it is started with (default src/main.ts)
      --check               end with 1 when the plan has refusals
```

### `palbase db:status`

A database's Palgres ledger: the version serving, and the migration open and who opened it

```sh
palbase db:status [--url <postgres-url> | --db <name>]
```

```text
      --url <postgres-url>  a database of your own (a local Postgres 18): the schema goes in it at once
      --db <name>           the environment's database (default: its only one)
      --entry <file>        the app's entry, what it is started with (default src/main.ts)
```

### `palbase db:push`

Try the app's schema on a database: your own one at once, the environment's beside the version serving

```sh
palbase db:push [--url <postgres-url> | --db <name>] [--reset]
```

On a database of your own (--url) the migration is started and completed at once; a refused one can --reset (its data goes, the schema is made anew).
On the environment's database it is only started: the release serving goes on with its version, your backend with yours; the next release completes it, or takes its place.
One migration is open at a time: yours is replaced by your next push; another developer's or a release's is said, and yours waits.
Production's schema changes with its releases alone: db:push refuses it (db:plan -E main shows what a release would do).

```text
      --url <postgres-url>  a database of your own (a local Postgres 18): the schema goes in it at once
      --db <name>           the environment's database (default: its only one)
      --entry <file>        the app's entry, what it is started with (default src/main.ts)
      --reset               with --url: make the schema anew, its data gone
```

### `palbase db:migrate`

A migration step by hand: start, complete or rollback — for a database whose app runs elsewhere, or to finish one

```sh
palbase db:migrate <start|complete|rollback> [--url <postgres-url> | --db <name>]
```

An app that is not one of the environment's machines: start, release the app, then complete once the old one is gone (pgroll's way).

```text
      --url <postgres-url>  a database of your own (a local Postgres 18): the schema goes in it at once
      --db <name>           the environment's database (default: its only one)
      --entry <file>        the app's entry, what it is started with (default src/main.ts)
```

### `palbase db:pull`

Write the schema files (`db/*.ts`) of what a database holds: to take a database over

```sh
palbase db:pull [--url <postgres-url> | --db <name>] [--dir <dir>]
```

Its first release then takes the database over: the tables stay as they are, nothing is copied.

```text
      --url <postgres-url>  a database of your own (a local Postgres 18): the schema goes in it at once
      --db <name>           the environment's database (default: its only one)
      --entry <file>        the app's entry, what it is started with (default src/main.ts)
      --dir <dir>           where db/ is written (default: here)
```

### `palbase db:seed`

Run db/seed.ts against a database that is not production

```sh
palbase db:seed [--url <postgres-url> | --db <name>] [--file <path>]
```

```text
      --url <postgres-url>  a database of your own (a local Postgres 18): the schema goes in it at once
      --db <name>           the environment's database (default: its only one)
      --entry <file>        the app's entry, what it is started with (default src/main.ts)
      --file <path>         the seed script (default db/seed.ts)
```

### `palbase db:types`

Write the app's tables into palbase/palbase-env.d.ts as types — rows, inserts, unique keys and relations both ways (with, has) — from its schema files

```sh
palbase db:types [--entry <file>] [--file <path>]
```

`Database.public.<table>` and `Database.<schema>.<table>` are typed from them with no import and no generic — the relations of a foreign key to another file's table too, which a schema's own type (TablesOf) cannot see: an app that declares Tables with TablesOf leaves that out once it has these. palbase init --db writes the block of its starter schema; run db:types again when a schema changes.
No database is asked: the app is started in its types mode, which reads its schema files and writes nothing else. Only the block between the palbase:env markers is written; run it again when a schema changes.

```text
      --entry <file>  the app's entry, what it is started with (default src/main.ts)
      --file <path>   the file (default palbase/palbase-env.d.ts)
```



<!-- ===== backend/overview ===== -->

# Overview

`palbase/backend` is the framework you write a Palbase backend in. You write plain TypeScript: class controllers whose methods are routes, `@Injectable()` services that hold the logic, schemas that validate what comes in, and a `@Module` per domain that says which of those classes exist. One call in `src/main.ts`, `PalbaseFactory.create(AppModule)`, builds them and serves them over HTTP. Your repository is built into a [machine](/docs/machines/overview) on every push to its branch, and the machine runs that file. There is no deploy command and no router file, and nothing reads a directory by its name. The modules and the decorators are the whole contract between your source and the framework.

## Quick example

Four files make a working backend: the entry point, the root module, and one domain.

```ts
// src/main.ts
import { PalbaseFactory } from "palbase/backend";
import { AppModule } from "./app.module";

// Serves on $PORT (8080 unless the machine says). The project's address, id
// and secret key come from the environment: on a machine the platform sets
// PALBASE_URL, PALBASE_PROJECT_ID and the machine's own PALBASE_SECRET_KEY.
await PalbaseFactory.create(AppModule);
```

```ts
// src/app.module.ts
import { Module } from "palbase/backend";
import { NotesModule } from "./modules/notes/notes.module";

@Module({ imports: [NotesModule] })
export class AppModule {}
```

```ts
// src/modules/notes/notes.module.ts
import { Module } from "palbase/backend";
import { NotesController } from "./notes.controller";
import { NotesService } from "./notes.service";

@Module({ controllers: [NotesController], providers: [NotesService] })
export class NotesModule {}
```

```ts
// src/modules/notes/notes.controller.ts
import { Body, Controller, Get, Param, Post, User, z, type UserT } from "palbase/backend";
import { NotesService, type Note } from "./notes.service";

const CreateNote = z.object({ title: z.string().min(1).max(200) });
type CreateNote = z.infer<typeof CreateNote>;

@Controller("/notes")
export class NotesController {
  constructor(private readonly notes: NotesService) {}

  @Post("")
  create(@Body(CreateNote) body: CreateNote, @User() user: UserT): Note {
    return this.notes.create(user.id, body.title);
  }

  @Get("/{id}")
  read(@Param("id") id: string, @User() user: UserT): Note {
    return this.notes.get(user.id, id);
  }
}
```

```ts
// src/modules/notes/notes.service.ts
import { Injectable, Log, NotFound } from "palbase/backend";

export interface Note {
  id: string;
  owner: string;
  title: string;
}

// Kept in memory to keep the example small; a real app keeps them in its
// database (see Database).
@Injectable()
export class NotesService {
  private readonly notes = new Map<string, Note>();

  create(owner: string, title: string): Note {
    const note: Note = { id: crypto.randomUUID(), owner, title };
    this.notes.set(note.id, note);
    Log.info("note created", { id: note.id });
    return note;
  }

  get(owner: string, id: string): Note {
    const note = this.notes.get(id);
    if (!note || note.owner !== owner) throw new NotFound(`no note ${id}`);
    return note;
  }
}
```

That serves `POST /notes` and `GET /notes/{id}`, both for signed-in users only, because every route needs a user unless it says otherwise. A client calls them at the machine's address, `https://<ref>.app.palbase.studio/notes`, with the user's access token as `Authorization: Bearer …`. See [Calling Your Backend](/docs/web/backend-calls).

## The mental model

| Concept | What it is |
|---|---|
| **Module** | A class decorated with `@Module({ imports, controllers, providers, exports })`. It decides ownership: a `@Controller` or `@Injectable()` class no module lists stops the boot by name. The root module (`AppModule` above) is the one `PalbaseFactory.create` is given, and every other module is reached through `imports`. |
| **Controller** | A class decorated with `@Controller(basePath)`. Each method decorated with `@Get`, `@Post`, `@Put`, `@Patch`, `@Delete` or `@Query` is one route. |
| **Service** | An `@Injectable()` class listed in its module's `providers`. It holds the business logic, so controllers stay thin. |
| **Dependency injection** | A class names what it needs as constructor parameters, and the container supplies them by **type**. There is no `@Inject` and no token registry. |
| **Schema** | Any [Standard Schema](https://standardschema.dev) (zod, valibot, arktype) given to `@Body`, `@QueryParams` or `@Headers`. `z` is re-exported from `palbase/backend`. |
| **Answer** | What the method returns is the response: `200` with its JSON, or `204` when it returns `undefined` or `null`. |
| **Errors** | Throw `NotFound`, `Conflict`, `Forbidden`, … or a `PalError` of your own. Every refusal is sent in one envelope. |
| **Webhook** | A `@Webhook` class listed in `providers`: a third party's signed deliveries (Stripe, GitHub, Slack, …) at `POST /webhooks/<name>`, each handed to the `@On` of its event. See [Webhooks](/docs/backend/webhooks). |
| **Gateway** | A `@Gateway(pattern)` class listed in `providers`: a realtime channel of the app, with who may join, its typed events, and its members' messages, each answered with an ack. Apps join it through their generated client. See [Gateways](/docs/backend/gateways). |

## What a handler imports

A handler or a service reaches three things by import. Nothing is injected for them, and there is no `ctx` parameter to pass around.

| Import | What it is | Docs |
|---|---|---|
| `Palbase` | The project's modules, called with the app's secret key: `Palbase.auth`, `Palbase.storage`, `Palbase.notify`, `Palbase.secrets`, `Palbase.flags`, `Palbase.analytics`, `Palbase.realtime`, `Palbase.machines`. It is the `palbase/server` client, made for you, with two more: `Palbase.ai`, the project's models, agents and chats, and `Palbase.gateways`, the app's gateways. | [Server SDK](/docs/server/overview), [AI](/docs/backend/ai), [Gateways](/docs/backend/gateways) |
| `Database` | The request's own transaction against the app's Postgres: `Database.public.<table>`, `$query`, `$transaction`, `$atomic`, `$asService()`. Committed when the handler returns, rolled back when it throws. | [Database](/docs/backend/database) |
| `Log` | Structured logging: one JSON line per call, carrying the request's id. | [Logging](#logging) |

`Palbase` is bound when the app is served. Reaching it before `PalbaseFactory.create` has run throws `Palbase.<module> is reached before the app is served`. `Database` is the request's, so it is reached inside a request: from a handler, a service a handler calls, or an `@On` handler. Reaching it at import time, from a timer or from `onStart()` throws and names where it was reached.

Per-request values come from parameter decorators instead: `@User()`, `@OptionalUser()`, `@Body()`, `@QueryParams()`, `@Param()`, `@Headers()`, `@Req()`, `@RequestId()` and `@Client()`. See [Request Validation](/docs/backend/validation) and [Authentication](/docs/backend/authentication).

## `PalbaseFactory.create(root, config?)`

The bootstrap takes the root module (or an array of them) and the backend's own settings. Each setting has one place: the app's defaults are here, a route's own auth and limit are on its decorator, and a module's settings (auth providers, storage buckets, notify senders) stay in that module, in Studio.

| Setting | Default | What it does |
|---|---|---|
| `palbase` | from the environment | `{ url, projectId, secretKey, webhookSecret }`: the project this backend belongs to. Each value is read from `PALBASE_URL`, `PALBASE_PROJECT_ID`, `PALBASE_SECRET_KEY` and `PALBASE_WEBHOOK_SECRET` unless given here. |
| `auth` | `true` | Every route's auth unless its controller or the route says otherwise. See [Authentication](/docs/backend/authentication). |
| `rateLimit` | `{ max: 300, window: 60 }` | Every route's limit per caller, unless the route says otherwise. `false` for none. |
| `bodyLimit` | 1 MiB | Bytes a request body may be. A larger one is `413 payload_too_large`. |
| `cors` | off | `{ origins: ["https://app.example.com"], maxAge? }`, or `origins: "*"`. A backend that browsers call from another origin names them here. |
| `db` | none | `{ schemas: [schema] }`: the app's database. See [Database](/docs/backend/database). |
| `port`, `host` | `$PORT` or 8080, `0.0.0.0` | Where it listens. `port: 0` takes a free one (tests). |
| `boot` | `{ attempts: 5, backoffMs: 1000 }` | How often a failed `onStart()` is tried again. |
| `exitOnFatal` | `true` | Exit 1 on an uncaught error. A test turns it off. |
| `env` | `process.env` | Where the `PALBASE_*` values are read from. |

A value that is missing or malformed stops the boot before any request is served, naming each problem and both ways to give it:

```text
[palbase] the app cannot start:
  - palbase.secretKey / PALBASE_SECRET_KEY is the project secret key (pb_<ref>_s…), kept in the project's Secrets
```

On a machine, the platform sets `PORT`, `PALBASE_URL` (the project's address, `https://<ref>.palbase.studio`), `PALBASE_PROJECT_ID`, `PALBASE_REPLICAS`, `PALBASE_PLATFORM_SECRET`, the machine's own `PALBASE_SECRET_KEY` and its `PALBASE_WEBHOOK_SECRET`, plus `PALBASE_DB_URL` and `PALBASE_DB_CONNECTIONS` when the machine is given a database. Nothing is set by hand. The machine's key is a secret key of the project, listed under **Settings › API keys** as `machine: <name>`: revoked, it is replaced and the machine rolls out with the new one, and it goes with the machine. See [Secrets](/docs/backend/secrets) and [Machines](/docs/machines/overview).

## What one request goes through

Every request takes the same path. Each step answers in the [error envelope](/docs/backend/errors) when it refuses:

1. **The route.** No route for the method and path: `404 not_found`.
2. **The caller.** A bearer token is verified against the project's keys. A route that needs a user and has none answers `401`. When tokens cannot be checked right now, the answer is `503 auth_unavailable` with `Retry-After`.
3. **A verified email**, when the route asks for one: `403 email_not_verified`.
4. **The route's rate limit**, spent before the body is read: `429 too_many_requests` with `Retry-After`.
5. **The body's size**: `413 payload_too_large`.
6. **The parameters**, against their schemas: `400 bad_request`, naming the fields.
7. **The handler**, inside the request's database transaction when the app has a database.
8. **The answer**: `204` for `undefined` or `null`, `200` with JSON otherwise.

Two first path segments are the platform's and never your controllers': `_palbase` (the app's health at `GET /_palbase/health`, and the platform's signed calls: its [crons](/docs/backend/cron) and [tasks](/docs/backend/tasks), an upload's steps, a [gateway](/docs/backend/gateways)'s, an agent's [tools](/docs/backend/ai#tools)) and `webhooks` (the platform delivers [events](/docs/backend/hooks) to `POST /webhooks/palbase`, and a [`@Webhook`](/docs/backend/webhooks) class takes a third party's at `POST /webhooks/<name>`). A `@Controller` mounted under either is refused when it is declared.

## Lifecycle

- **Boot.** Every class is built once, dependencies first. Then each one's `onStart()` runs, in that order. A boot that fails in `onStart()` (a database not up yet) is tried again from scratch after 1, 2, 4 and 8 seconds. If it still fails, the process exits 1 and the machine starts it again. What waiting cannot fix, such as a missing setting or a [DI mistake](/docs/backend/modules), stops at once.
- **Serving.** `GET /_palbase/health` answers `200 {"ok":true}` while the app serves. It is the machine's health check by default.
- **Stopping.** On `SIGTERM` the app stops taking connections and gives the requests in flight up to 20 seconds. Then it runs every `onShutdown()`, in reverse order. Health answers `503` meanwhile. A machine's sandbox sends `SIGTERM` more than once, milliseconds apart: the app stops once, and a later signal changes nothing.
- **A crash.** An uncaught error or an unhandled rejection is logged. The requests in flight get a few seconds, and the process exits 1 for the machine to start it again, rather than run half-alive.
- **A migration run.** Started with `PALBASE_DB_MIGRATE`, the same image migrates its database and exits without serving anything. See [Schema changes](/docs/backend/migrations).

## Setup

A backend is an ordinary TypeScript project. The examples run on [Bun](https://bun.sh), which runs TypeScript and its decorator metadata as written, and whose SQL client the database uses by default. `tsconfig.json` needs two settings for the container to read constructor types:

```json
{
  "compilerOptions": {
    "target": "es2023",
    "module": "esnext",
    "moduleResolution": "bundler",
    "strict": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "allowImportingTsExtensions": true,
    "noEmit": true
  },
  "include": ["src/**/*.ts"]
}
```

Without `emitDecoratorMetadata`, a class with constructor parameters stops the boot with `metadata missing`. A build that strips types without emitting metadata (esbuild) does the same; tsc, Bun and SWC emit it. How the repository is laid out and built is in [Project Structure](/docs/getting-started/project-structure).

## Logging

`Log` writes one JSON line per call: `time`, `level`, `msg`, the request's `request_id` when there is a request, and the fields you pass. An `Error` among them is written with its name, message and stack. `debug` and `info` go to stdout, `warn` and `error` to stderr. What a machine writes is in Studio's machine page and in its logs API. See [Builds, Logs & Rollback](/docs/machines/builds).

```ts
// src/modules/notes/notes.audit.ts
import { Injectable, Log } from "palbase/backend";

@Injectable()
export class NotesAudit {
  record(noteId: string, payload: unknown, err: unknown): void {
    Log.info("note created", { noteId });
    Log.warn("rate approaching limit");
    Log.error("import failed", { error: err });
    Log.debug("raw payload", { payload });
  }
}
```

```text
{"time":"2026-10-08T09:12:44.012Z","level":"info","msg":"note created","request_id":"req_6f1c…","noteId":"3b0e…"}
```

The framework logs its own lines the same way, prefixed `[palbase]`: the routes it serves at boot, a handler's unhandled error (with the route), a module that did not answer.

## The rules checklist

1. **A class exists because a module lists it.** `@Controller` classes go in `controllers`, `@Injectable()` services and `@On` handler classes go in `providers`. A declared class no module lists stops the boot with `unowned class`. Export every class by name: modules import them as `import { X } from "./x"`.
2. **The root module is the one you pass.** `PalbaseFactory.create(AppModule)` reaches every other module through `imports`, and imports are not transitive.
3. **Providers are `@Injectable()`.** A class in `providers` without it (and without an `@On` method) stops the boot with `undeclared provider`.
4. **Constructor parameters are classes.** An `interface`, a union or a primitive has no class to build, so it stops the boot with `unresolvable dependency`. Use a class or an `abstract class`.
5. **`onStart()` and `onShutdown()` are the lifecycle.** NestJS's `onModuleInit` and the rest are refused by name, so they are never silently ignored.
6. **Every route needs a signed-in user unless it says `auth: false`.** `@User()` on a route that does not need one stops the boot: use `@OptionalUser()`.
7. **Schemas are Standard Schema values.** Import `z` from `palbase/backend` and pass the schema itself: `@Body(CreateNote)`.
8. **Return the value, or nothing.** A handler's return is its `200` JSON; `undefined` or `null` is `204`. There is no response object to write to.
9. **Throw to refuse.** `throw new NotFound("…")` from a controller or a service. Anything that is not an `HttpError` is a `500`, logged with its stack.
10. **`experimentalDecorators` and `emitDecoratorMetadata`** in `tsconfig.json`.

## Where to next

| Topic | Page |
|---|---|
| `@Module`'s four lists, injection by type, `onStart` and `onShutdown` | [Modules & Dependency Injection](/docs/backend/modules) |
| Routes, paths, rate limits | [Controllers & Routing](/docs/backend/controllers) |
| `@Body`, `@QueryParams`, `@Param`, `@Headers`, and the 400 they answer | [Request Validation](/docs/backend/validation) |
| Default auth, `@User`, `@OptionalUser`, verified email | [Authentication](/docs/backend/authentication) |
| The answer, the envelope, the error classes | [Responses & Errors](/docs/backend/errors) |
| Postgres, declared in TypeScript | [Database](/docs/backend/database) · [Schema](/docs/backend/schema) · [Row-Level Security](/docs/backend/row-level-security) · [Schema changes](/docs/backend/migrations) |
| The project's modules from your backend | [Storage](/docs/backend/storage) · [Secrets](/docs/backend/secrets) · [Flags](/docs/backend/flags) · [Notifications](/docs/backend/notifications) · [Realtime](/docs/backend/realtime) |
| Realtime channels of your app, and chats of the project's agents | [Gateways](/docs/backend/gateways) · [AI](/docs/backend/ai) |
| The platform's events | [Event Hooks](/docs/backend/hooks) |
| Tests | [Test Users](/docs/backend/test-users) · [Testing](/docs/backend/testing) |
| Where it runs | [Machines](/docs/machines/overview) · [Connecting GitHub](/docs/machines/github) |

## Related

- [Project Structure](/docs/getting-started/project-structure): how a backend repository is laid out
- [Architecture](/docs/getting-started/architecture): how the pieces fit together
- [Machines](/docs/machines/overview): what runs your backend
- [Server SDK](/docs/server/overview): the client `Palbase` is



<!-- ===== backend/modules ===== -->

# Modules & Dependency Injection

One `@Module` declaration says **what exists, who owns it, and what it may reach**. It is the only place ownership is decided. A `@Controller` or `@Injectable()` class that no module lists does not exist, and the app refuses to start rather than serve without it. Being in a particular folder grants nothing.

A dependency is named by its constructor parameter's **type**, and by nothing else. There is no `@Inject`, no `useFactory`, no `forwardRef` and no token registry.

## The four lists

A module is named after its **domain** and lives with it: `src/modules/notes/` holds the module, the controller, the service and the schemas that belong to notes.

```ts
// src/modules/notes/notes.module.ts
import { Module } from "palbase/backend";
import { NotesController } from "./notes.controller";
import { NotesService } from "./notes.service";

@Module({
  controllers: [NotesController],
  providers: [NotesService],
  exports: [NotesService], // the class another module may reach
  imports: [],             // whose exports THIS module may reach
})
export class NotesModule {}
```

```ts
// src/modules/notes/notes.service.ts
import { Injectable, NotFound } from "palbase/backend";

export interface Note {
  id: string;
  title: string;
}

@Injectable()
export class NotesService {
  private readonly notes = new Map<string, Note>();

  get(id: string): Note {
    const note = this.notes.get(id);
    if (!note) throw new NotFound(`no note ${id}`);
    return note;
  }
}
```

```ts
// src/modules/notes/notes.controller.ts
import { Controller, Get, Param } from "palbase/backend";
import { NotesService, type Note } from "./notes.service";

@Controller("/notes")
export class NotesController {
  // The container supplies this. Nothing here constructs or imports an instance.
  constructor(private readonly notes: NotesService) {}

  @Get("/{id}")
  get(@Param("id") id: string): Note {
    return this.notes.get(id);
  }
}
```

Four lists answer four different questions, and nothing else answers them:

| List | The question it answers |
|---|---|
| `providers` | which classes does this module **own** (`@Injectable()` services, classes with [`@On`](/docs/backend/hooks) handlers, and [`@Webhook`](/docs/backend/webhooks) classes) |
| `controllers` | which `@Controller` classes it owns |
| `exports` | which of its own providers **another** module may reach |
| `imports` | whose exports **this** module may reach |

Every list is optional and empty by default. A module with nothing but `imports` is how the root module gathers the domains:

```ts
// src/app.module.ts
import { Module } from "palbase/backend";
import { NotesModule } from "./modules/notes/notes.module";

@Module({ imports: [NotesModule] })
export class AppModule {}
```

```ts
// src/main.ts
import { PalbaseFactory } from "palbase/backend";
import { AppModule } from "./app.module";

await PalbaseFactory.create(AppModule);
```

`PalbaseFactory.create` takes the root module, or an array of them. Every module the app has is reached from there through `imports`. A module nothing imports is not part of the app.

## A class no module lists does not exist

`@Controller`, `@Injectable()` and `@On` record the class they decorate when its file is imported. When the app is built, every recorded class must be owned by exactly one module the root reaches. Otherwise the app stops before it serves anything, and the error names the class:

```text
DiError:
Kind:  unowned class
Path:  PricingService
At:    PricingService
PricingService is declared but no module lists it: it would never be built

Potential solutions:
  - list it in a module's controllers or providers
  - or delete it
```

Every container error is a `DiError` with a `kind`, the path that led to it, and what to do. They are all raised at boot, before the first request, and none is retried: waiting does not fix a wiring mistake.

| `kind` | What it means |
|---|---|
| `unowned class` | A declared class no module lists, or a dependency nobody owns |
| `duplicate ownership` | Two modules list the same class, or an abstract dependency has more than one owned subclass |
| `undeclared provider` | A class in `providers` that is not `@Injectable()` (nor has an `@On` method), or a class in `controllers` that is not a `@Controller` |
| `unknown export` | A module exports a class it does not own |
| `unknown import` | Something in `imports` is not a `@Module`, or a module imports itself |
| `missing import` | A class needs another module's class, and its module does not import that module |
| `private dependency` | The other module owns the class but does not export it |
| `unresolvable dependency` | A constructor parameter typed as an interface, a union or a primitive |
| `metadata missing` | A class takes constructor parameters but no types were emitted |
| `dependency cycle` | `A → B → A` |
| `nest lifecycle name` | A class has `onModuleInit` or another NestJS hook, which would never be called |

## `exports` and `imports`: the boundary

A module reaches another module's class when **both** sides say so: the owner exports it, and the module that needs it imports the owner directly.

```ts
// src/modules/billing/billing.service.ts
import { Injectable } from "palbase/backend";

@Injectable()
export class BillingService {
  planOf(userId: string): "free" | "pro" {
    return userId.startsWith("usr_") ? "free" : "pro";
  }
}
```

```ts
// src/modules/billing/billing.module.ts
import { Module } from "palbase/backend";
import { BillingService } from "./billing.service";

@Module({ providers: [BillingService], exports: [BillingService] })
export class BillingModule {}
```

```ts
// src/modules/reports/reports.controller.ts
import { Controller, Get, User, type UserT } from "palbase/backend";
import { BillingService } from "../billing/billing.service";

@Controller("/reports")
export class ReportsController {
  constructor(private readonly billing: BillingService) {}

  @Get("/plan")
  plan(@User() user: UserT): { plan: "free" | "pro" } {
    return { plan: this.billing.planOf(user.id) };
  }
}
```

```ts
// src/modules/reports/reports.module.ts
import { Module } from "palbase/backend";
import { BillingModule } from "../billing/billing.module";
import { ReportsController } from "./reports.controller";

@Module({ imports: [BillingModule], controllers: [ReportsController] })
export class ReportsModule {}
```

Leave `BillingModule` out of `imports` and the boot stops with `missing import`, naming both modules. Leave `BillingService` out of `exports` and it stops with `private dependency`. **Imports are not transitive.** If `ReportsModule` imports `BillingModule` and `BillingModule` imports `AccountsModule`, `ReportsModule` still cannot reach `AccountsModule`'s classes without importing it itself.

## Dependency injection: the constructor is the seam

Every owned class is built **once**, dependencies first, and every class that names it gets the same instance. A class names what it needs as constructor parameters; the container reads their types from the metadata TypeScript emits (`design:paramtypes`) and passes the instances in. Controllers take services this way, and services take other services.

```ts
// src/modules/notes/clock.ts
import { Injectable } from "palbase/backend";

@Injectable()
export class Clock {
  now(): Date {
    return new Date();
  }
}
```

```ts
// src/modules/notes/reminders.service.ts
import { Injectable } from "palbase/backend";
import { Clock } from "./clock";

@Injectable()
export class RemindersService {
  constructor(private readonly clock: Clock) {}

  isDue(at: Date): boolean {
    return at.getTime() <= this.clock.now().getTime();
  }
}
```

### What the container cannot inject

A parameter's type must be a **class**: something that exists at run time. An `interface`, a type alias, a union, `string` or `number` erases to `Object` (or nothing) in the emitted metadata, and the boot stops with `unresolvable dependency`, naming the class and the parameter. Configuration that is a value (a URL, a limit) is read where it is used, from `process.env`. It is not injected.

## The abstraction is the type, the implementation is the provider

To depend on an abstraction, make it an `abstract class` and list a subclass in `providers`. A parameter typed as the abstract class gets the **one** owned subclass:

```ts
// src/modules/mail/mailer.ts
import { Injectable, Log } from "palbase/backend";

export abstract class Mailer {
  abstract send(to: string, subject: string): Promise<void>;
}

@Injectable()
export class LogMailer extends Mailer {
  async send(to: string, subject: string): Promise<void> {
    Log.info("mail", { to, subject });
  }
}
```

```ts
// src/modules/mail/welcome.service.ts
import { Injectable } from "palbase/backend";
import { Mailer } from "./mailer";

@Injectable()
export class WelcomeService {
  constructor(private readonly mailer: Mailer) {}

  welcome(email: string): Promise<void> {
    return this.mailer.send(email, "Welcome");
  }
}
```

```ts
// src/modules/mail/mail.module.ts
import { Module } from "palbase/backend";
import { LogMailer } from "./mailer";
import { WelcomeService } from "./welcome.service";

@Module({ providers: [LogMailer, WelcomeService] })
export class MailModule {}
```

Two owned subclasses of `Mailer` make the choice ambiguous, and the boot stops with `duplicate ownership`. Ask for the subclass itself where you mean one. In a test, the same seam lets you pass any `Mailer` to `new WelcomeService(...)` directly. See [Testing](/docs/backend/testing).

## Why there is no `@Inject`, `useFactory` or `forwardRef`

Each of them answers a question the constructor already answers. `@Inject(TOKEN)` names a dependency by a token instead of a type, so the type and the token can disagree. `useFactory` builds an instance outside the container, where its dependencies are not checked. `forwardRef` exists to make a cycle work, and a cycle is a design problem: the boot names it (`A -> B -> A`) and the fix is a third class both depend on.

## `onStart()` and `onShutdown()`

A constructor is pure wiring: synchronous, no I/O, because the container runs it at boot. Startup work is a method on the class:

```ts
// src/modules/catalog/catalog.service.ts
import { Injectable, Log, Palbase } from "palbase/backend";

@Injectable()
export class CatalogService {
  private bucketReady = false;

  // Awaited before the first request, in construction order.
  async onStart(): Promise<void> {
    await Palbase.storage.putBucket({ path: { bucket: "catalog" }, body: { public: true } });
    this.bucketReady = true;
  }

  // Run on SIGTERM, after the requests in flight have finished, in reverse order.
  async onShutdown(): Promise<void> {
    Log.info("catalog stopping", { bucketReady: this.bucketReady });
  }

  ready(): boolean {
    return this.bucketReady;
  }
}
```

- `onStart()` runs once per class, in construction order: a class's dependencies have started before it does. `Palbase` is bound by then. `Database` is not, because it is a request's.
- When one throws, the classes already started are shut down and the whole boot is tried again from scratch, waiting 1, 2, 4 and 8 seconds (`boot: { attempts, backoffMs }` in `PalbaseFactory.create`). Every attempt builds new instances. After the last attempt the error is logged and the process exits, and the machine starts it again.
- `onShutdown()` runs in reverse construction order, and every one is tried even when one throws.

NestJS's names (`onModuleInit`, `onApplicationBootstrap`, `onModuleDestroy`, `beforeApplicationShutdown`, `onApplicationShutdown`) are refused at boot with `nest lifecycle name`. They would never be called here, so a class that relied on them would fail silently.

## `emitDecoratorMetadata` is what makes injection work

The container reads constructor types from the metadata TypeScript emits with `"experimentalDecorators": true` and `"emitDecoratorMetadata": true`. Bun, tsc and SWC emit it. esbuild does not. Without it, a class with constructor parameters stops the boot with `metadata missing`:

```text
DiError:
Kind:  metadata missing
Path:  ReportsController
At:    ReportsController
ReportsController takes 1 constructor parameter(s) but no types were emitted
```

Every class with a constructor parameter must carry a decorator (`@Injectable()`, `@Controller`), because TypeScript emits the parameter types only for a decorated class.

> **Note:** A class is recorded once its file is imported, process-wide. Two copies of `palbase/backend` in one app share the record, so a class declared through either is seen. A test that builds only part of the app must pass modules that own every declared class its imports bring in.

## A domain is a folder

`src/modules/<domain>/` is a convention, not a rule the framework reads: nothing scans a directory. A domain's module, controllers, services and schemas sit together because they change together, and the module is what makes them exist. The one other place the layout matters is the schema: the database's tables are declared in `src/db/` and given to `PalbaseFactory.create(…, { db: { schemas } })`. See [Project Structure](/docs/getting-started/project-structure) and [Schema](/docs/backend/schema).

## Related

- [Overview](/docs/backend/overview): the authoring model in one page
- [Controllers & Routing](/docs/backend/controllers): what a controller declares
- [Testing](/docs/backend/testing): constructing a class with your own dependencies
- [Architecture](/docs/getting-started/architecture): how modules, controllers and services fit



<!-- ===== backend/controllers ===== -->

# Controllers & Routing

Routes are declared in code, not in a router. A controller is a class decorated with `@Controller(basePath)`, and each route is a method decorated with `@Get`, `@Post`, `@Put`, `@Patch`, `@Delete` or `@Query`. The file lives with the domain that owns it (`src/modules/todos/todos.controller.ts`), and it is served because its module's `controllers` list names the class. There is no central router to register with. A `@Controller` class no module lists stops the boot, by name. See [Modules & Dependency Injection](/docs/backend/modules).

## Quick example

```ts
// src/modules/todos/dto.ts
import { z } from "palbase/backend";

export const CreateTodo = z.object({ title: z.string().min(1).max(200) });
export type CreateTodo = z.infer<typeof CreateTodo>;

export interface Todo {
  id: string;
  owner: string;
  title: string;
  done: boolean;
}
```

```ts
// src/modules/todos/todos.service.ts
import { Injectable, NotFound } from "palbase/backend";
import type { CreateTodo, Todo } from "./dto";

@Injectable()
export class TodosService {
  private readonly todos = new Map<string, Todo>();

  list(owner: string): Todo[] {
    return [...this.todos.values()].filter((t) => t.owner === owner);
  }

  create(owner: string, input: CreateTodo): Todo {
    const todo: Todo = { id: crypto.randomUUID(), owner, title: input.title, done: false };
    this.todos.set(todo.id, todo);
    return todo;
  }

  get(id: string): Todo {
    const todo = this.todos.get(id);
    if (!todo) throw new NotFound(`no todo ${id}`);
    return todo;
  }
}
```

```ts
// src/modules/todos/todos.controller.ts
import { Body, Controller, Get, Param, Post, User, type UserT } from "palbase/backend";
import { CreateTodo, type Todo } from "./dto";
import { TodosService } from "./todos.service";

@Controller("/todos")
export class TodosController {
  // The container supplies this. Nothing here constructs or imports an instance.
  constructor(private readonly todos: TodosService) {}

  @Get("")
  list(@User() user: UserT): Todo[] {
    return this.todos.list(user.id);
  }

  @Post("", { rateLimit: { max: 10, window: 60 } })
  create(@Body(CreateTodo) body: CreateTodo, @User() user: UserT): Todo {
    return this.todos.create(user.id, body);
  }

  @Get("/{id}", { auth: false })
  get(@Param("id") id: string): Todo {
    return this.todos.get(id);
  }
}
```

```ts
// src/modules/todos/todos.module.ts
import { Module } from "palbase/backend";
import { TodosController } from "./todos.controller";
import { TodosService } from "./todos.service";

@Module({ controllers: [TodosController], providers: [TodosService] })
export class TodosModule {}
```

That serves three routes:

| Method | Verb | Full path | Auth | Limit |
|---|---|---|---|---|
| `list` | GET | `/todos` | a signed-in user (the default) | 300 a minute (the default) |
| `create` | POST | `/todos` | a signed-in user | 10 a minute |
| `get` | GET | `/todos/{id}` | anyone | 300 a minute |

At boot the app logs them: `[palbase] serving 3 route(s) on :8080`, with the list. Studio's **Backend › Endpoints** screen shows the same table, read from the app's own contract.

## `@Controller(basePath, options?)`

- `basePath` is where every route of the class is served (`"/todos"`). It must be a string.
- `options.auth` sets the controller-wide auth, which a route's own `auth` overrides. It is `true`, `false`, or `{ required?, verifiedEmail? }`. See [Authentication](/docs/backend/authentication).

Controllers are built **once**, at boot, and that one instance serves every request. A field is fine for wiring (the services the constructor took), but never store per-request state in one: concurrent requests share it. Per-request data comes from the parameter decorators.

A `@Controller` class with no routes stops the boot (`@Controller X has no routes`): a controller with nothing to serve is a mistake.

> **Note:** Export the class by name (`export class TodosController`). Its module takes it with `import { TodosController } from "./todos.controller"`, and curly braces cannot see a default export.

## Method decorators

Six decorators declare a route. Each takes `(path, options?)`:

| Decorator | HTTP method | Notes |
|---|---|---|
| `@Get` | GET | its body is never read |
| `@Post` | POST | |
| `@Put` | PUT | |
| `@Patch` | PATCH | |
| `@Delete` | DELETE | |
| `@Query` | QUERY | a safe, idempotent read that carries a body |

The options are `RouteOptions`, and the type is exported:

```ts
// src/modules/todos/route-options.ts
import type { RouteOptions } from "palbase/backend";

// What a method decorator's second argument accepts.
export const strict: RouteOptions = {
  // true, false, or { required?, verifiedEmail? }
  auth: { required: true, verifiedEmail: true },
  // this route's own limit per caller, window in SECONDS; false for none
  rateLimit: { max: 10, window: 60 },
};
```

That is all a route option says: who may call it and how often. Input comes from the parameter decorators ([Request Validation](/docs/backend/validation)), and the response is whatever the method returns ([Responses & Errors](/docs/backend/errors)).

The path argument must be a string. `@Get({ … })` throws when the class is declared, because the query string is read with `@QueryParams(schema)`, not with the path.

### `@Query`: reads with a body

`@Query(path, options?)` serves the route on the HTTP `QUERY` method. It is **safe and idempotent like GET, but carries a request body like POST**. Use it for reads whose input is too structured for a query string, such as search, nested filters or batch lookups:

```ts
// src/modules/todos/search.controller.ts
import { Body, Controller, Query, User, z, type UserT } from "palbase/backend";

export const SearchTodos = z.object({
  titleContains: z.string().max(100).optional(),
  ids: z.array(z.string()).max(100).default([]),
});
export type SearchTodos = z.infer<typeof SearchTodos>;

@Controller("/todos")
export class SearchController {
  @Query("/search")
  search(@Body(SearchTodos) body: SearchTodos, @User() user: UserT): { owner: string; asked: SearchTodos } {
    return { owner: user.id, asked: body };
  }
}
```

A QUERY route's input rides in the **body**, read with `@Body`. Don't confuse the `@Query` *method* decorator with the `@QueryParams` *parameter* decorator (query-string input).

Choosing a verb for a read:

- **GET**: no input, or input that fits a few query-string values (`@QueryParams`).
- **QUERY**: a read whose input is a structured object.
- **POST**: the request changes state.

### Paths

A route's full path is `basePath + path`, split on `/` with empty segments dropped. So `@Controller("/todos")` with `@Get("")`, `@Get("/")` or `@Get("//")` is served at `/todos`.

A `{name}` segment is a path parameter, read by name with `@Param("name")`. `:name` means the same:

```ts
// src/modules/comments/comments.controller.ts
import { Controller, Get, Param } from "palbase/backend";

@Controller("/todos")
export class CommentsController {
  @Get("/{id}/comments/{commentId}", { auth: false })
  getComment(@Param("id") id: string, @Param("commentId") commentId: string): { todo: string; comment: string } {
    return { todo: id, comment: commentId };
  }
}
```

- Matching is a walk over segments with an **exact segment count**: `/todos/{id}` never matches `/todos/a/b`. Literal segments compare exactly, case included.
- The **first** route in declaration order whose method and segments match wins. One declared later that can never be reached is listed in the app's contract under `x-palbase-unreachable`, with the route that answers instead.
- A parameter's value is one segment, percent-decoded, always a string. A segment that is not valid percent-encoding is `400 bad_request`.
- `@Param("x")` naming no `{x}` in the route's path stops the boot.

### Paths that are the platform's

A machine's address is yours: your routes are served from its root, and nothing of the platform's modules (`/auth`, `/storage`, …) lives there. Two first segments are the platform's own:

- `_palbase`: the app's health (`GET /_palbase/health`) and the platform's signed calls (its crons and tasks, an upload's steps, a gateway's, an agent's tools), which the platform makes from inside. A request from outside to a `_palbase` path never reaches the app.
- `webhooks`: the platform delivers [events](/docs/backend/hooks) to `POST /webhooks/palbase`, and each [`@Webhook`](/docs/backend/webhooks) class takes a third party's at `POST /webhooks/<name>`.

`@Controller` throws when it is declared if its base path's first segment is either one, and the app does not start with a route whose full path begins with one, so the mistake is a boot error, not a route that is never called.

## Parameters your app makes: `@Resolve`

Most routes of an app with teams, workspaces or stores start the same way: find what the path names and check that the caller may touch it. Write that once, as a provider, and take its result as a parameter:

```ts
// src/modules/teams/current-team.ts
import { Forbidden, Injectable, NotFound, Resolve, type ParamResolver, type ResolveContext } from "palbase/backend";

export type TeamRole = "member" | "owner";
export interface CurrentTeamT {
  id: string;
  role: TeamRole;
}

@Injectable()
export class TeamOfRequest implements ParamResolver<CurrentTeamT, TeamRole | undefined> {
  // A real app reads the membership from its database here (Database.public.team_members.findUnique).
  private readonly members = new Map<string, TeamRole>([["team_1:user_1", "owner"]]);

  resolve({ params, user }: ResolveContext, atLeast: TeamRole | undefined): CurrentTeamT {
    const role = user ? this.members.get(`${params.teamId}:${user.id}`) : undefined;
    // A team the caller is not in is one that does not exist: a different answer would let anyone count them.
    if (!role) throw new NotFound("no such team");
    if (atLeast === "owner" && role !== "owner") throw new Forbidden("owners only");
    return { id: params.teamId, role };
  }
}

/** The team the path names, the caller's role in it checked. */
export const CurrentTeam = (atLeast?: TeamRole) => Resolve(TeamOfRequest, atLeast);
```

```ts
// src/modules/teams/notes.controller.ts
import { Body, Controller, Delete, Get, Param, Post, z } from "palbase/backend";
import { CurrentTeam, type CurrentTeamT } from "./current-team";

const NewNote = z.object({ title: z.string().min(1) });

@Controller("/teams/{teamId}/notes")
export class NotesController {
  @Get("")
  list(@CurrentTeam() team: CurrentTeamT) {
    return { team: team.id, notes: [] };
  }

  @Post("")
  create(@CurrentTeam() team: CurrentTeamT, @Body(NewNote) body: z.infer<typeof NewNote>) {
    return { team: team.id, title: body.title };
  }

  @Delete("/{id}")
  remove(@CurrentTeam("owner") team: CurrentTeamT, @Param("id") id: string) {
    return { removed: id, from: team.id };
  }
}
```

```ts
// src/modules/teams/teams.module.ts
import { Module } from "palbase/backend";
import { TeamOfRequest } from "./current-team";
import { NotesController } from "./notes.controller";

@Module({ controllers: [NotesController], providers: [TeamOfRequest] })
export class TeamsModule {}
```

- **A provider.** The resolver is an `@Injectable()` its module lists, and it takes its dependencies by constructor. The controller's module reaches it as it would a constructor's dependency: listed by the same module, or exported by one it imports. A resolver it cannot reach stops the boot, naming the route and the class.
- **What it is given.** `ResolveContext` has the path's parameters (decoded), the signed-in user (`null` on a route that needs none and was called by nobody), the request's headers and its id. The second argument is what the decorator was given: here, the role the route needs.
- **Before the body.** Resolvers run before every other parameter. A caller with no right to the team hears your `404` or `403`, not a `400` about a body they should never have been asked for.
- **In the request's transaction.** The resolver uses the request's `Database`, as the handler does: a write it made goes back with the handler's if the handler throws. A resolver that only read, before a handler that waits on something else, has its connection given back during the wait like any read of the request ([A handler that waits on something else](/docs/backend/database#a-handler-that-waits-on-something-else)).
- **Not in the contract.** The app's OpenAPI document shows the path's parameters, never the resolver.

A guard (`@UseGuards` and `@Roles` in other frameworks) answers only yes or no. The resolver answers with what it found, so the handler does not look it up a second time.

## Rate limiting

Every route has a limit: 300 requests a minute **per caller** unless `PalbaseFactory.create(…, { rateLimit })` or the route says otherwise. `rateLimit: { max, window }` allows at most `max` requests per `window` **seconds**. `rateLimit: false` turns it off for one route, and `rateLimit: false` in the bootstrap turns it off for every route that does not set its own.

A list of windows holds a caller to each of them — a burst, a minute and an hour: `rateLimit: [{ max: 10, window: 10 }, { max: 30, window: 60 }, { max: 300, window: 3600 }]`. A request over any of them is refused and told to wait the longest of their waits, and it is not counted in the windows that had room: a caller told to wait out a burst has not spent its hour on the requests it was refused.

```ts
// src/modules/todos/import.controller.ts
import { Body, Controller, Post, User, z, type UserT } from "palbase/backend";

export const ImportTodos = z.object({ titles: z.array(z.string().max(200)).max(1000) });
export type ImportTodos = z.infer<typeof ImportTodos>;

@Controller("/todos")
export class ImportController {
  @Post("/import", { rateLimit: { max: 5, window: 60 } })
  importTodos(@Body(ImportTodos) body: ImportTodos, @User() user: UserT): { owner: string; imported: number } {
    return { owner: user.id, imported: body.titles.length };
  }
}
```

Over the limit, the route answers `429` with a `Retry-After` header in seconds and this body:

```json
{
  "error": "too_many_requests",
  "error_description": "Rate limit exceeded for this endpoint",
  "status": 429,
  "request_id": "req_6f1c…",
  "data": { "retryAfter": 42 }
}
```

How the limit counts, because it decides what the limit protects:

- **The caller** is the signed-in user (by the token's user id), or else the client's address. On a machine that address is the last `X-Forwarded-For` entry, the one the platform's edge appended; every entry before it is whatever the client sent. An IPv6 address counts by its /64.
- **The limit is spent before the body is read.** A caller over the limit is not read for, whatever it sends.
- **The window is fixed and kept in the process's memory**, per route and caller, for up to 100,000 keys; the key used longest ago goes first. A machine running several copies counts in each copy, so the limit holds per copy. A restart forgets every window.

There are no `X-RateLimit-*` headers: a refusal carries `Retry-After`, and a request that passed carries nothing.

> **Note:** This is your route's own limit. The project as a whole also has a requests-per-second ceiling at the platform's edge, which answers `429` above it.

To refuse inside your own logic (a per-resource cooldown, say), throw `new TooManyRequests({ retryAfter })`. It is sent the same way, with its `Retry-After`. See [Responses & Errors](/docs/backend/errors).

## CORS

A backend that browsers call from another origin names those origins in the bootstrap. Off unless given:

```ts
// src/main.ts
import { PalbaseFactory } from "palbase/backend";
import { AppModule } from "./app.module";

await PalbaseFactory.create(AppModule, {
  cors: { origins: ["https://app.example.com", "http://localhost:3000"], maxAge: 600 },
});
```

```ts
// src/app.module.ts
import { Module } from "palbase/backend";

@Module({})
export class AppModule {}
```

- A preflight (`OPTIONS` with `Access-Control-Request-Method`) from a named origin is answered `204`. One from any other origin is `403`, and its real request gets no CORS headers.
- Answers to a named origin carry `Access-Control-Allow-Origin` and expose `Retry-After` and `X-Request-Id` to the page.
- Origins are `https://host[:port]`, with `http://` only for `localhost` and `127.0.0.1`, and no path. Anything else stops the boot. `origins: "*"` allows any origin.
- The credential is the bearer token in `Authorization`, never a cookie, so there is no credentials mode to set.

## What a handler returns

The method's return is the answer. An object or an array is `200` with its JSON, and `undefined` or `null` is `204` with no body. A `Promise` is awaited first. A refusal is a throw ([Responses & Errors](/docs/backend/errors)).

When the answer needs its own status, headers or body, return a `Response`. It is sent as it was built, with the request's `X-Request-Id` and CORS' headers added:

```ts
// src/modules/files/files.controller.ts
import { Controller, Get, Param, Post } from "palbase/backend";

@Controller("/files")
export class FilesController {
  // 201 with where the new one is.
  @Post("")
  create() {
    return Response.json({ id: "f_1" }, { status: 201, headers: { location: "/files/f_1" } });
  }

  // Any status, with its headers: here a 412 and the version the client must send.
  @Get("/{id}/stale")
  stale(@Param("id") id: string) {
    return Response.json({ error: "precondition_failed", id }, { status: 412, headers: { etag: '"v7"' } });
  }

  // Not JSON: a CSV, downloaded as a file.
  @Get("/report.csv")
  report() {
    return new Response("id,name\n1,Ada\n", { headers: { "content-type": "text/csv; charset=utf-8", "content-disposition": 'attachment; filename="report.csv"' } });
  }

  // A stream, sent as it is made: one JSON line at a time.
  @Get("/feed")
  feed() {
    const encoder = new TextEncoder();
    const body = new ReadableStream<Uint8Array>({
      start(controller) {
        for (let i = 1; i <= 3; i++) controller.enqueue(encoder.encode(`${JSON.stringify({ line: i })}\n`));
        controller.close();
      },
    });
    return new Response(body, { headers: { "content-type": "application/x-ndjson" } });
  }
}
```

The request's transaction ends when the handler returns, before the answer goes. A streamed body is read after that, so read what it needs from `Database` first. A returned `Response` is an answer, whatever its status: what the handler wrote commits. Only a throw rolls it back.

A `fetch()` answer can be returned as it is: its body is already decoded, so its `Content-Encoding` and `Content-Length` are not passed on, and neither is a connection's own header (`Connection`, `Transfer-Encoding`, …).

## Keep controllers thin

A controller reads the request (its parameters, the user, what [`@Resolve`](#parameters-your-app-makes-resolve) found) and hands it to a service. The logic and the database work belong in an `@Injectable()` service the controller takes in its constructor, which can be tested on its own and shared across controllers. See [Modules & Dependency Injection](/docs/backend/modules) and [Testing](/docs/backend/testing).

## Related

- [Request Validation](/docs/backend/validation): `@Body`, `@QueryParams`, `@Param`, `@Headers`
- [Authentication](/docs/backend/authentication): route and controller `auth`
- [Responses & Errors](/docs/backend/errors): the answer and the envelope
- [Calling Your Backend](/docs/web/backend-calls): calling these routes from a browser



<!-- ===== backend/validation ===== -->

# Request Validation

A handler never reads raw input. Each part of the request it uses arrives through a **parameter decorator**, and every decorator that takes a schema validates before the handler runs. `@Body`, `@QueryParams` and `@Headers` take any [Standard Schema](https://standardschema.dev): zod (re-exported as `z` from `palbase/backend`), valibot, arktype or another library that implements it. A request that fails one is answered `400` with the fields that failed, and the handler is never called.

## Quick example

```ts
// src/modules/todos/dto.ts
import { z } from "palbase/backend";

export const CreateTodo = z.object({
  title: z.string().min(1).max(200),
  dueAt: z.iso.datetime().optional(),
  tags: z.array(z.string().max(30)).max(10).default([]),
});
export type CreateTodo = z.infer<typeof CreateTodo>;

// The query string arrives as strings: coerce what is a number.
export const ListTodos = z.object({
  limit: z.coerce.number().int().min(1).max(100).default(20),
  done: z.enum(["true", "false"]).optional(),
});
export type ListTodos = z.infer<typeof ListTodos>;
```

```ts
// src/modules/todos/todos.controller.ts
import { Body, Controller, Get, Param, Post, QueryParams, User, type UserT } from "palbase/backend";
import { CreateTodo, ListTodos } from "./dto";

@Controller("/todos")
export class TodosController {
  @Post("")
  create(@Body(CreateTodo) body: CreateTodo, @User() user: UserT): { owner: string; todo: CreateTodo } {
    // body.tags is [] when the client sent none: the schema's output is what arrives.
    return { owner: user.id, todo: body };
  }

  @Get("")
  list(@QueryParams(ListTodos) query: ListTodos): { limit: number; done: string | null } {
    return { limit: query.limit, done: query.done ?? null };
  }

  @Get("/{id}")
  get(@Param("id") id: string): { id: string } {
    return { id };
  }
}
```

The handler gets the schema's **output**: defaults filled in, coercions and transforms applied. That is why the parameter's type is `z.infer<typeof Schema>`, written once beside the schema as a same-named type.

## The parameter decorators

| Decorator | What it reads | Validated |
|---|---|---|
| `@Body(schema)` | The JSON body | always (a schema is required) |
| `@QueryParams(schema)` | The query string, as an object of strings | always (a schema is required) |
| `@Headers(schema?)` | The request's headers, names lower-cased | when given a schema |
| `@Param("name")` | One path segment, `{name}` in the route's path | no: always a string |
| `@User()` / `@OptionalUser()` | The signed-in user | see [Authentication](/docs/backend/authentication) |
| `@Req()` | The `Request` itself | no |
| `@RequestId()` | The request's id (`@TraceId()` is the same) | no |
| `@Client()` | `{ sdkVersion, appVersion, platform, osVersion }`, from the client's headers | no |

A schema passed to `@Body`, `@QueryParams` or `@Headers` must be a Standard Schema value, the object itself. Anything else (a type, a plain object, `undefined`) throws when the class is declared: `@Body(schema): schema is a Standard Schema (a zod, valibot or arktype schema)`.

### `@Body`

The body is read whole, up to the body limit (1 MiB unless `PalbaseFactory.create(…, { bodyLimit })` says otherwise). Past it, the answer is `413 payload_too_large`, before the schema sees anything. The body is parsed as JSON **whatever its `Content-Type`**. An empty body, or one that is not JSON, reaches the schema as `{}`, so the caller hears a validation error that names what was missing.

A `GET` never reads its body: a `@Body` on a GET route validates `{}`. Use `@QueryParams` for a GET, or a [`@Query`](/docs/backend/controllers) route when the input is structured.

There is no multipart and no file upload in a request body: a body is JSON. To take a file, the backend grants a [signed upload URL](/docs/backend/direct-uploads) and the client sends the bytes straight to storage.

### `@QueryParams`

The query string becomes an object of **strings**, `?limit=20&done=true` as `{ limit: "20", done: "true" }`. A key given twice keeps its last value. Coerce what is a number or a boolean in the schema (`z.coerce.number()`), and keep the schema an object of scalars.

### `@Headers`

Without a schema, `@Headers()` hands over every header as an object of strings, names lower-cased. With one, the object is validated and the schema's output arrives. A header schema should let other headers through (zod's objects strip unknown keys, so the handler simply gets the ones you named):

```ts
// src/modules/sync/sync.controller.ts
import { Controller, Headers, Post, User, z, type UserT } from "palbase/backend";

const SyncHeaders = z.object({ "x-device-id": z.string().min(8).max(64) });
type SyncHeaders = z.infer<typeof SyncHeaders>;

@Controller("/sync")
export class SyncController {
  @Post("")
  sync(@Headers(SyncHeaders) headers: SyncHeaders, @User() user: UserT): { device: string; user: string } {
    return { device: headers["x-device-id"], user: user.id };
  }
}
```

### `@Param`

`@Param("id")` is the segment `{id}` of the route's path, percent-decoded, always a string. It takes no schema. Check its shape in the service (or with `schema.parse(id)`) when it must be a UUID or a number. A `@Param` that names no segment of its route stops the boot.

### `@Req`, `@RequestId` and `@Client`

`@Req()` is the web `Request`. For a route with a body, the body has already been read by the time the handler runs, so read it through `@Body`. `@RequestId()` is the request's id: the `X-Request-Id` the caller sent when it is 8 to 128 characters of `A–Z a–z 0–9 . _ : -`, otherwise one made for it (`req_…`). It is in every answer's `X-Request-Id` header, in the error envelope and in every `Log` line of the request. `@Client()` reads what a client says of itself: `x-palbase-sdk-version`, `x-palbase-client-version`, `x-platform` and `x-os-version`, each `null` when absent.

```ts
// src/modules/support/support.controller.ts
import { Client, Controller, Get, RequestId, type ClientInfo } from "palbase/backend";

@Controller("/support", { auth: false })
export class SupportController {
  @Get("/whoami")
  whoami(@RequestId() requestId: string, @Client() client: ClientInfo): { requestId: string; platform: string | null } {
    return { requestId, platform: client.platform };
  }
}
```

## Where schemas live

Schemas are ordinary values. Put a domain's in its own `dto.ts` beside its controller, each exported as a value and a same-named type, so the controller reads `@Body(CreateTodo) body: CreateTodo`. Nothing discovers the file: it is an ordinary import. A schema two domains share belongs to the module that owns the concept, or to a small shared file both import.

Import `z` from `palbase/backend` rather than installing zod yourself. The framework re-exports the zod it is built with, so your schemas and the framework agree on one version.

## What a validation failure looks like

A failed schema answers `400 bad_request` in the [error envelope](/docs/backend/errors), with each failed field in `data.fields`:

```json
{
  "error": "bad_request",
  "error_description": "Request body failed validation",
  "status": 400,
  "request_id": "req_6f1c…",
  "data": {
    "fields": [
      { "field": "title", "message": "Too small: expected string to have >=1 characters" },
      { "field": "tags.3", "message": "Too big: expected string to have <=30 characters" }
    ]
  }
}
```

- `error_description` says which part failed: `Request body failed validation`, `Query parameters failed validation` or `Request headers failed validation`.
- `field` is the issue's path, dotted (`tags.3`). It is `""` for the value as a whole.
- `message` is the schema library's own message.
- At most 20 fields are listed. When there were more, `data.more` says how many: a body of a million bad items is not answered with a million lines.

A `BadRequest` you throw yourself has the same shape: `throw new BadRequest({ fields: [{ field: "name", message: "…" }] })`. A client handles both the same way.

## The body is data, never structure

Everything a request sent is marked as **data** where it enters: the body (as `JSON.parse` made it), the query, the headers and the user's metadata. The database takes values from data, but never a filter's operators, its branches, a `select`, an `orderBy` or a column name. `{ token: body.token }` cannot become `{ token: { neq: null } }` because the client sent an object there; the query refuses it with a `400` naming the field.

What a schema builds is the route's own: `z.object({ title: z.string() })` makes a new object, and its `title` is a value. What a schema lets through untouched (`z.unknown()`, `z.any()`, a passthrough's extra keys) stays the request's, and stays marked. Declare the shape of whatever you filter by. See [Database](/docs/backend/database).

## The answer is not validated

A schema validates what comes in. What the handler returns is sent as it is, so return the fields you mean to: build the answer from the row rather than returning the row, when the row holds more than the caller should see.

## What Studio shows

Each schema is also written into the app's contract as JSON Schema, for libraries that implement the Standard JSON Schema converter (zod does). Studio's **Backend › Endpoints** screen shows each route's body, query and header schemas from there. A schema whose library has no converter is described as any value. It is still validated.

## Related

- [Controllers & Routing](/docs/backend/controllers): the routes these decorators sit on
- [Responses & Errors](/docs/backend/errors): the envelope a `400` arrives in
- [Authentication](/docs/backend/authentication): `@User` and `@OptionalUser`
- [Direct Uploads](/docs/backend/direct-uploads): files, which never ride in a request body



<!-- ===== backend/authentication ===== -->

# Authentication

Every route needs a signed-in user unless something says otherwise. A caller proves who they are with the access token the project's auth gave them, sent as `Authorization: Bearer <token>`. The app checks that token itself, against the project's signing keys, before the handler runs. The handler receives the user as a parameter: `@User()` where one is required, `@OptionalUser()` where anyone may call. Signing up, signing in and keeping a session are the client's job ([Web Auth](/docs/web/auth)). A backend only ever sees the token.

## Quick example

```ts
// src/modules/profile/profile.controller.ts
import { Controller, Get, OptionalUser, Post, User, type UserT } from "palbase/backend";

@Controller("/profile")
export class ProfileController {
  // The default: a signed-in user, or 401.
  @Get("/me")
  me(@User() user: UserT): { id: string; email: string | null; verified: boolean } {
    return { id: user.id, email: user.email, verified: user.emailVerified };
  }

  // Anyone; a valid token makes the caller a user.
  @Get("/greeting", { auth: false })
  greeting(@OptionalUser() user: UserT | null): { text: string } {
    return { text: user ? `Hello, ${user.email ?? "friend"}` : "Hello, guest" };
  }

  // A signed-in user whose email is verified, or 403.
  @Post("/publish", { auth: { verifiedEmail: true } })
  publish(@User() user: UserT): { published: string } {
    return { published: user.id };
  }
}
```

```ts
// src/modules/profile/profile.module.ts
import { Module } from "palbase/backend";
import { ProfileController } from "./profile.controller";

@Module({ controllers: [ProfileController] })
export class ProfileModule {}
```

## Where a route's auth comes from

A route's auth is the first of these that says anything:

1. the route's own option: `@Get("/x", { auth })`;
2. its controller's: `@Controller("/x", { auth })`;
3. the app's default: `PalbaseFactory.create(AppModule, { auth })`;
4. otherwise `true`: a signed-in user.

```ts
// src/modules/catalog/catalog.controller.ts
import { Controller, Get, Post, User, type UserT } from "palbase/backend";

// Public by default: everything in this controller answers anyone…
@Controller("/catalog", { auth: false })
export class CatalogController {
  @Get("")
  list(): { items: string[] } {
    return { items: ["tea", "coffee"] };
  }

  // …except this route, which says otherwise.
  @Post("/favourites", { auth: true })
  favourite(@User() user: UserT): { user: string } {
    return { user: user.id };
  }
}
```

### The `auth` value

| Value | Meaning |
|---|---|
| `true` | A signed-in user is required. |
| `false` | Anyone may call. A valid token still makes the caller a user (`@OptionalUser()`, and the database's identity). |
| `{ required?: boolean }` | The same as `true` or `false`; `required` defaults to `true`. |
| `{ verifiedEmail: true }` | A signed-in user whose token says `email_verified: true`, or `403 email_not_verified`. |
| `{ aal: "aal2" }` | A user who signed in with a second factor (a passkey that verified its user, an authenticator or SMS code, a step-up), or `401 insufficient_user_authentication`. `"aal3"` asks more: a key that never leaves its device; `"aal1"` is a sign-in of any kind. An email code is not a second factor ([below](#second-factors-and-their-strength)). Implies a signed-in user: with `required: false` the app stops at boot. |
| `{ maxAge: 300 }` | A user who last proved who they are — signed in, or stepped up since — within the last 300 seconds, or `401 insufficient_user_authentication` with `max_age`. With `aal`, both: `{ aal: "aal2", maxAge: 300 }` is "a second factor within the last 5 minutes", what sending money or changing the account's email asks. Whole seconds above 0. Implies a signed-in user; an `@Upload` route cannot ask for it (the app stops at boot). |

`role` and `permission` fields are refused when the app boots. Its token carries no application roles, and Palbase does not check them against a database, so the boot stops with an error naming the route, saying the role check has no database to run against and that the role is to be checked in the service. How to check one is [below](#roles).

## What the caller is answered

| The request | On a route that needs a user | On a route that does not |
|---|---|---|
| no `Authorization` header | `401 unauthorized` | handled, user `null` |
| `Authorization` that is not `Bearer <token>` | `401 invalid_token` | handled, user `null` |
| a token that does not verify | `401 invalid_token`, `data.reason` says why | handled, user `null` |
| a valid token | handled, `@User()` is the user | handled, `@OptionalUser()` is the user |
| a valid token below the route's `aal` | `401 insufficient_user_authentication` | — |
| a valid token whose last authentication is older than the route's `maxAge` | `401 insufficient_user_authentication` | — |
| tokens cannot be checked right now | `503 auth_unavailable`, `Retry-After: 1` | handled, user `null` |

`insufficient_user_authentication` is RFC 9470's step-up challenge: `WWW-Authenticate: Bearer error="insufficient_user_authentication", acr_values="urn:nist:800-63:aal2"` and `data.acr_values: "aal2"`; a route with `maxAge` adds `max_age=300` and `data.max_age: 300`. The session is fine: the app steps the user up (their second factor) and calls again. Palbase's clients name it apart from a signed-out caller: `stepUpRequired` on iOS, `StepUpRequired` on Android, `kind: "stepUpRequired"` on the web; none refreshes or ends the session for it.

The step-up is one of:

- `pb.auth.mfa.stepUp(code)` with the authenticator app's code;
- `pb.auth.mfa.sendStepUpSmsCode()`, then `pb.auth.mfa.stepUpWithSms(code)` with the code it texted (`stepUp(smsCode:)` on iOS);
- `stepUp()` on the client's passkeys: Face ID, a fingerprint or the device's screen lock.

The session takes the token at the new level, and its refreshes stay there. A step-up is the session's last authentication: the token's `auth_time` is its moment, and every token the session is refreshed to keeps it, so a `maxAge` route counts from the step-up, not from the sign-in.

```ts
// src/modules/admin/approvals.controller.ts
import { Controller, Param, Post, User, type UserT } from "palbase/backend";

@Controller("/admin")
export class ApprovalsController {
  // Approving needs the admin's second factor, whatever their session.
  @Post("/approvals/{id}", { auth: { aal: "aal2" } })
  approve(@User() user: UserT, @Param("id") id: string) {
    return { approvedBy: user.id, id, how: user.amr };
  }
}
```

`data.reason` on an `invalid_token` refusal is one of `malformed`, `algorithm`, `unknown_key`, `signature`, `issuer`, `audience`, `project`, `expired`, `not_yet_valid`, `not_a_user`, `bound`, `not_a_session` or `session_ended`. A client that gets `expired` refreshes its session and calls again. `palbase/web` does that by itself for the project's modules. See [Calling Your Backend](/docs/web/backend-calls).

```ts
// src/modules/payments/transfers.controller.ts
import { Controller, Param, Post, User, type UserT } from "palbase/backend";

@Controller("/payments")
export class TransfersController {
  // Sending money asks for a second factor given in the last 5 minutes.
  @Post("/transfers/{id}/send", { auth: { aal: "aal2", maxAge: 300 } })
  send(@User() user: UserT, @Param("id") id: string) {
    return { transfer: id, sentBy: user.id, provedAt: user.authTime };
  }
}
```

### Second factors and their strength

The token says how its user last proved who they are: the level in `acr`, the method in `amr` (RFC 8176).

| Method | `acr` | `amr` | |
|---|---|---|---|
| A key that never leaves its device (a security key, a device-bound passkey) | `aal3` | `hwk` | Resists phishing. |
| A synced passkey: Face ID, a fingerprint, the screen lock | `aal2` | `swk` | Resists phishing. |
| An authenticator app's code | `aal2` | `otp` | |
| A code texted to the user's phone | `aal2` | `sms` | NIST calls it restricted (a SIM can be swapped): offer an app or a passkey beside it. |
| A code emailed to the user | `aal1` | `email` | Not a second factor: the inbox is where the password is reset (NIST SP 800-63B-4 §3.1.3.1). It is no way to step up. |
| A recovery code | `aal1` | `recovery` | A way back in, not a second factor. |

A sign-in with a password and a second factor carries both (`["pwd", "otp"]`); a step-up's token carries the step-up's method alone, the authentication its `auth_time` is the moment of. A route that will take only a passkey checks `amr` in the service.

## How the token is verified

A machine's address takes requests without an API key, and nothing in front of the app has looked at the token. The token's own signature is the only thing that says who the caller is, so the app checks all of it:

- it is a JWS of three parts, signed `ES256` or `PS256` with a `kid`. `none`, HMAC and every other algorithm are refused before any key is looked at;
- the `kid` is a key of the project's key set, `https://<ref>.palbase.studio/.well-known/jwks.json`, and the signature verifies with it. The key set is kept as long as its answer says (an hour at most), and read again when an unknown `kid` arrives, at most every 30 seconds;
- `iss` is the project's address, `aud` names it, and `project_id` is the project's id;
- `exp` is ahead and `nbf` (when present) behind, within a minute of clock skew. `auth_time` is present: it is a user's token, not a client's;
- it is not bound to a key the caller must prove (`cnf`, DPoP);
- it belongs to a session (`session_id`), and that **session still stands**. The app asks the project (`GET /auth/user` with the token) at most every 15 seconds per session. A user who signs out, whose session is revoked or who is banned loses their tokens within that time, not at their expiry.

When the key set cannot be read and none is held, or a session's standing cannot be asked, the answer is `503 auth_unavailable`, not a `401`: the token may be fine. A key set the app already holds is used for up to ten more minutes past its age while it cannot be read again.

## Injecting the user

### `@User()`: routes that need one

`@User()` is the signed-in user. It is used on a route whose auth is required. On a route that does not require a user it would be `null`, so the app stops at boot: `@User() on a route that does not need a signed-in user — use @OptionalUser() (null when nobody is)`.

### `@OptionalUser()`: routes anyone may call

`@OptionalUser()` is the user when the request carried a valid token, and `null` otherwise. A token that does not verify makes the caller nobody here; it is not refused.

### The `UserT` shape

`@User()` is a value (the decorator) and `UserT` is a type. Import both from `palbase/backend`:

| Field | Type | What it is |
|---|---|---|
| `id` | `string` | The user's id (the token's `sub`) |
| `email` | `string \| null` | The user's email, when they have one |
| `emailVerified` | `boolean` | The token's `email_verified` |
| `role` | `string \| null` | The token's role (`authenticated` for a user) |
| `metadata` | `Record<string, unknown>` | The token's `custom_claims` |
| `sessionId` | `string \| null` | The session the token belongs to |
| `test` | `boolean` | A [test user](/docs/backend/test-users) of the project |
| `acr` | `"aal1" \| "aal2" \| "aal3" \| null` | How the user signed in (the token's `acr`): `aal2` with a second factor. `null` where no token says it: an upload's or a gateway's caller, whom the platform names |
| `amr` | `string[]` | The methods the sign-in used (the token's `amr`: `pwd`, `otp`, `hwk`, …) |
| `authTime` | `number \| null` | When the user signed in or last stepped up, in Unix seconds (the token's `auth_time`) |

The object is marked as request data: the user writes their own metadata, so the database takes values from it but never treats it as a filter's structure. See [Request Validation](/docs/backend/validation).

## Device attestation

A route marked `attest: true` is called only by your own app, on a genuine device: Palbase's [iOS](/docs/ios/backend-calls#device-attestation) and [Android](/docs/android/backend-calls#device-attestation) SDKs attach a proof to the call by themselves. On iOS the proof is Apple's App Attest; on Android a key in the phone's secure hardware that Google's attestation vouches for: a locked, verified phone running your app as you signed it. A script, an emulator, a modified app or a call replayed with another body has none that verifies.

```ts
// src/modules/location/location.controller.ts
import { Body, Controller, Post, z } from "palbase/backend";

const Report = z.object({ lat: z.number(), lng: z.number() });

@Controller("/location", { auth: false })
export class LocationController {
  // A report made up with curl, or sent from a Simulator, does not get in.
  @Post("/report", { attest: true })
  report(@Body(Report) report: z.infer<typeof Report>) {
    return { received: report };
  }
}
```

`attest: true` goes on a route or on a `@Controller(path, { attest: true })`, where a route's `attest: false` leaves it out. Whether it is asked is the environment's switch, not the code's: **App Attest mode** in Studio's Authentication settings (Device trust), or `palbase auth:settings:set app_attest_mode=<mode> -E <env>`. A change applies within 30 seconds, with no deploy (the app reads it every 25).

| Mode | What an attested route does |
|---|---|
| `off` (the default) | Nothing: every call is handled. |
| `monitor` | Every call's proof is verified, and nobody is refused. Studio's Device trust shows the last 24 hours: proofs verified, proofs refused, devices that cannot attest, clients without attestation support. |
| `enforce` | A call without a proof that verifies is answered `401 app_attest_required`. |

The refusal carries `data.reason` (`app_attest_required`: no proof; `assertion_invalid`; `assertion_stale`: another call used the device's counter first; `device_unknown`: the device is not enrolled) and `data.challenge`, also in the `X-Palbase-Attest-Challenge` header: the SDK enrols the device when it must, proves the call with that challenge and sends it once more. Every answer of an attested route carries the next challenge in the same header, so a device's next call needs no extra round trip. When the proof cannot be checked (auth is not reachable, or the environment's mode was never read since the machine started) the route answers `503 attest_unavailable` with `Retry-After: 1`.

A route that decides by device — one account per phone, a shared tablet at a desk — takes the device whose proof verified with `@AttestedDevice()`: its id and platform, as auth names them.

```ts
// src/modules/shifts/shifts.controller.ts
import { AttestedDevice, Controller, Post, User, type UserT } from "palbase/backend";

@Controller("/shifts")
export class ShiftsController {
  @Post("/clock-in", { attest: true })
  clockIn(@User() user: UserT, @AttestedDevice() device: AttestedDevice | null) {
    // { id: "dev_…", platform: "ios" | "android" } under enforce; null under off and monitor.
    return { user: user.id, device: device?.id ?? null };
  }
}
```

It is the device auth verified, not the `X-Palbase-Device-Id` header the client sends: that one is only the client's word, under `off` and `monitor` too. Under `off` nothing is verified and under `monitor` nothing is refused, so `@AttestedDevice()` is `null` in both: a route does not act on a device for some calls and not for others. On a route that is not `attest: true` it is refused when the app starts.

The environment's iOS and Android apps are its registered apps (`palbase apps:env:set`): an iOS app's App Attest key is taken for its bundle and team, an Android app's key for its package and the signing certificates registered with it (Play's app signing key and your upload key; not a debug key, whose build anyone with the phone can drive to sign requests). An Android enrolment is checked again on every call: a certificate of its chain revoked since, or a signing certificate taken off the app, stops it, and after 30 days the phone enrols again. Calls an app makes at once may reach the backend in any order: each is taken once. A browser cannot attest: under `enforce`, a web app's calls to an attested route are refused. So are calls from older app versions that predate attestation; set the app's minimum version before turning `enforce` on.

## Roles

The token says who the user is, not which application roles they hold. Roles are defined and assigned in the project's auth module, with the secret key: `PUT /admin/roles/{name}` defines one with its permissions, and `PUT /admin/users/{uid}/roles/{role}` gives it to a user. A backend that needs one asks for the user's roles where it decides:

```ts
// src/modules/admin/admin-guard.service.ts
import { Forbidden, Injectable, Palbase, type UserT } from "palbase/backend";

@Injectable()
export class AdminGuard {
  async assertAdmin(user: UserT): Promise<void> {
    const { data } = await Palbase.auth.adminListUserRoles({ path: { uid: user.id } });
    if (!data.roles.includes("admin")) throw new Forbidden("This needs the admin role");
  }
}
```

```ts
// src/modules/admin/admin.controller.ts
import { Controller, Delete, Param, User, type UserT } from "palbase/backend";
import { AdminGuard } from "./admin-guard.service";

@Controller("/admin-tools")
export class AdminController {
  constructor(private readonly guard: AdminGuard) {}

  @Delete("/posts/{id}")
  async removePost(@Param("id") id: string, @User() user: UserT): Promise<{ removed: string }> {
    await this.guard.assertAdmin(user);
    return { removed: id };
  }
}
```

```ts
// src/modules/admin/admin.module.ts
import { Module } from "palbase/backend";
import { AdminController } from "./admin.controller";
import { AdminGuard } from "./admin-guard.service";

@Module({ controllers: [AdminController], providers: [AdminGuard] })
export class AdminModule {}
```

Assigning a role from your own code is the same client: `Palbase.auth.adminAssignUserRole({ path: { uid, role: "admin" } })`. A role that is not defined is `400 role_not_defined`.

## Auth and the database

When the app has a database, each request runs in a transaction **as its caller**. A signed-in caller is the `authenticated` role with the token's claims, so `auth.uid()` in a policy is their id. Anyone else is `anon`. That is what makes row-level security hold for every query a handler runs, whoever wrote it. An app whose every request is its operator's sets `db: { requests: "service" }` and decides access in its routes. See [Row-Level Security](/docs/backend/row-level-security).

## Who may call at all

A route with `auth: false` answers the internet: the machine's address takes requests from anyone. Give it a [rate limit](/docs/backend/controllers) that suits it, and keep what it returns to what anyone may see. A browser on another origin needs the origin named in [CORS](/docs/backend/controllers). The machine's address is never a reason to skip auth: there is no network boundary that only your own apps can cross.

## Related

- [Web Auth](/docs/web/auth): signing users in, and the session the token comes from
- [Calling Your Backend](/docs/web/backend-calls): sending the token
- [Row-Level Security](/docs/backend/row-level-security): the caller in the database
- [Test Users](/docs/backend/test-users): `user.test` and making test users
- [Responses & Errors](/docs/backend/errors): the envelope these refusals arrive in



<!-- ===== backend/errors ===== -->

# Responses & Errors

A handler answers by returning and refuses by throwing. What it returns is sent as JSON with `200`, or as `204` when it returns nothing. What it throws is sent in **one envelope**, the same one the framework uses for its own refusals and the project's modules use for theirs, so a client handles every refusal one way.

## Quick example

```ts
// src/modules/invites/invites.service.ts
import { Conflict, Forbidden, Injectable, NotFound, PalError, UniqueViolation } from "palbase/backend";

export interface Invite {
  code: string;
  team: string;
  usedBy: string | null;
}

@Injectable()
export class InvitesService {
  private readonly invites = new Map<string, Invite>();

  accept(code: string, userId: string): Invite {
    const invite = this.invites.get(code);
    if (!invite) throw new NotFound("No invite with that code", "invite_not_found");
    if (invite.usedBy === userId) throw new Conflict("You already joined", "already_joined");
    if (invite.usedBy) throw new Forbidden("This invite was used", "invite_used");
    if (invite.team === "closed") {
      // Any status and code of your choosing, with typed details in data.
      throw new PalError(422, "team_closed", "The team takes no new members", { team: invite.team });
    }
    invite.usedBy = userId;
    return invite;
  }

  // A database refusal, translated into one the client can act on.
  rename(e: unknown): never {
    if (UniqueViolation.is(e) && e.constraint === "teams_name_key") throw new Conflict("That name is taken", "name_taken");
    throw e;
  }
}
```

```ts
// src/modules/invites/invites.controller.ts
import { Controller, Param, Post, User, type UserT } from "palbase/backend";
import { InvitesService, type Invite } from "./invites.service";

@Controller("/invites")
export class InvitesController {
  constructor(private readonly invites: InvitesService) {}

  @Post("/{code}/accept")
  accept(@Param("code") code: string, @User() user: UserT): Invite {
    return this.invites.accept(code, user.id);
  }
}
```

A missing code answers:

```json
{
  "error": "invite_not_found",
  "error_description": "No invite with that code",
  "status": 404,
  "request_id": "req_6f1c…"
}
```

## What a handler returns

| The method returns | The answer |
|---|---|
| an object, an array, a string, a number | `200`, `Content-Type: application/json`, the value as JSON |
| `undefined` or `null` (or `Promise<void>`) | `204`, no body |
| a `Promise` | awaited, then as above |

The return type is yours to write. The framework does not read it: an interface, a zod-inferred type and an inline object type all work. Every answer carries `X-Request-Id`. There is no way to set a status or a header on a success: a handler that needs a different status for a refusal throws.

## The error envelope

Every refusal, whether the framework's, a handler's or the database's, is:

| Field | Always | What it is |
|---|---|---|
| `error` | yes | A stable code in snake_case. Branch on this. |
| `error_description` | yes | What went wrong, for a person. Do not parse it. |
| `status` | yes | The HTTP status, the same as the response's. |
| `request_id` | yes | The request's id, also in `X-Request-Id` and in every `Log` line of the request. Quote it when you look for the request in the machine's logs. |
| `data` | when there are details | A validation's `fields`, a token's `reason`, a limit's `retryAfter`, or what your own error carries. |

A refusal that ends with time also carries a `Retry-After` header in seconds: `429` and `503` always do.

### Codes the framework generates

| Status | `error` | When |
|---|---|---|
| 400 | `bad_request` | A parameter failed its schema (`data.fields`), or a path segment is not valid percent-encoding |
| 401 | `unauthorized` | The route needs a signed-in user and the request has no token |
| 401 | `invalid_token` | The token does not verify (`data.reason`), or `Authorization` is not a bearer token |
| 403 | `email_not_verified` | The route asks for a verified email |
| 404 | `not_found` | No route for the method and path |
| 413 | `payload_too_large` | The body is over the body limit |
| 429 | `too_many_requests` | The route's limit for this caller (`data.retryAfter`, `Retry-After`) |
| 500 | `internal_error` | The handler threw something that is not an `HttpError` |
| 503 | `auth_unavailable` | Tokens cannot be checked right now (`Retry-After`) |
| 503 | `service_unavailable` | A module the request called did not answer (`Retry-After`) |

The database adds its own: `409 unique_violation` (and `serialization_failure`, `deadlock_detected`), `400 invalid_value` for a value its column cannot take, `403 permission_denied` for a write RLS or a missing grant refuses (`401` to an anonymous caller), `429 too_many_requests` when its queue is full, and `503 database_unavailable` or `database_busy`. See [Database](/docs/backend/database).

## Built-in error classes

Import them from `palbase/backend` and throw them from a controller or a service:

| Class | Status | Default `error` | Constructor |
|---|---|---|---|
| `BadRequest` | 400 | `bad_request` | `(data: { fields: { field, message }[] }, message?)` |
| `Unauthorized` | 401 | `unauthorized` | `(message?, code?, data?)` |
| `Forbidden` | 403 | `forbidden` | `(message?, code?, data?)` |
| `NotFound` | 404 | `not_found` | `(message?, code?, data?)` |
| `Conflict` | 409 | `conflict` | `(message?, code?, data?)` |
| `TooManyRequests` | 429 | `too_many_requests` | `(data: { retryAfter }, message?)`, sent with `Retry-After` |
| `PalError` | any | yours | `(status, code, description, data?)` |
| `HttpError` | any | yours | `(status, error, errorDescription, data?, retryAfter?)` |

The message-first classes take an optional `code`, which becomes `error`. It is the field a client branches on, so give a refusal its own code (`invite_used`) rather than the class's default when the client should act on it. The message defaults to the class name in words (`Not found`).

`BadRequest` carries fields the way a failed schema does, so a check of your own reads like the framework's:

```ts
// src/modules/dates/dates.service.ts
import { BadRequest, Injectable } from "palbase/backend";

@Injectable()
export class DatesService {
  range(from: Date, to: Date): number {
    if (to <= from) throw new BadRequest({ fields: [{ field: "to", message: "must be after from" }] });
    return to.getTime() - from.getTime();
  }
}
```

`UniqueViolation`, `SerializationFailure` and `DeadlockDetected` are the database's. It throws them, and you catch them. `UniqueViolation.is(e)` holds for one whichever copy of the package made it, and `e.constraint` names the constraint Postgres reported. The constraint is a field, never part of the message, because a constraint name tells a stranger how the schema is built.

An error is recognised by a brand, not by `instanceof`, so two copies of the package in one app agree. Anything with a status from 400 to 599, an `error` and an `errorDescription` is sent as it says.

## Errors from the project's modules

A call through `Palbase` (storage, notify, auth…) that the module refuses throws a `PalbaseError` with the module's `status`, `code`, `requestId` and `retryAfter`. What the framework does with one that reaches it uncaught:

- **The module did not answer** (no connection, `429`, `502`, `503`, `504`): `503 service_unavailable` with `Retry-After`. The request can be tried again, and nothing about it was the caller's fault.
- **Any other refusal** (a `404` for an object that is not there, a `400` for a bad input): `500 internal_error`, logged. The module refused something the handler asked for, which is the handler's to decide.

So catch the refusals your code expects and answer them yourself:

```ts
// src/modules/files/files.service.ts
import { Injectable, NotFound, Palbase } from "palbase/backend";
import { PalbaseError } from "palbase/server";

@Injectable()
export class FilesService {
  async link(path: string): Promise<{ url: string }> {
    try {
      const signed = await Palbase.storage.createSignedUrl({ path: { bucket: "files" }, body: { path, expires_in: 300 } });
      return { url: signed.data.url };
    } catch (e) {
      if (e instanceof PalbaseError && e.status === 404) throw new NotFound("No such file", "file_not_found");
      throw e;
    }
  }
}
```

## What is logged

The caller sees the envelope. The machine's logs see more:

- an `HttpError` with a status of 500 or more is logged with the route and the error;
- anything that is not an `HttpError` is logged as `unhandled error in <route>`, with its stack. The caller sees only `The request could not be completed`, never the message, which may hold a query or a value;
- a module that did not answer, and tokens that cannot be checked, are logged as warnings.

A `4xx` you throw is not logged: it is an answer, not a failure. Use `Log` for what you want to keep. See [Overview](/docs/backend/overview).

## 503 or 500

The difference matters to every client. A `503` with `Retry-After` says "this was not you, and trying again is reasonable": an outage, a module that did not answer, tokens that cannot be checked. A `500` says the handler failed, and sending the same request again will fail the same way. Throw an `HttpError` with status 503 and a `retryAfter` when your own dependency is out. Let a bug be a 500.

## Related

- [Request Validation](/docs/backend/validation): the `400` a schema answers
- [Authentication](/docs/backend/authentication): `401`, `403` and `503 auth_unavailable`
- [Database](/docs/backend/database): the database's refusals
- [Error Handling](/docs/web/errors): how a browser client reads this envelope



<!-- ===== backend/database ===== -->

# Database

A machine given one of the project's [databases](/docs/machines/databases) is started with `PALBASE_DB_URL`, and a `palbase/backend` app that declares its schemas talks to it through `Database`. There is no client to construct: you import `Database` from `palbase/backend` and call it. Two things about it are load-bearing. `Database.public.<table>` is typed against the tables your [schema](/docs/backend/schema) declares, and every statement runs inside **the request's own transaction, as the caller** — a signed-in user is Postgres' `authenticated` role with their claims, anyone else `anon` — so [Row-Level Security](/docs/backend/row-level-security) filters what your code can even see. The one deliberate exception is `Database.$asService()`, which opens a separate transaction as the service role: explicit, greppable, never the default.

## Quick example

The schema the examples on this page use:

```ts
// src/db/public.ts
import {
  boolean, defineSchema, defineTable, integer, numeric, ownedByUser, policy, text, timestamp, userRef, uuid,
} from "palbase/backend";

export const lists = defineTable("lists", {
  columns: { id: uuid().primaryKey().defaultRandom(), owner: ownedByUser(), title: text() },
  policies: (p) => [policy("lists_own").for("all").using(p.col("owner").eq(p.auth.uid())).withCheck(p.col("owner").eq(p.auth.uid()))],
});

export const todos = defineTable("todos", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    list_id: uuid().references(() => lists.id, { onDelete: "cascade" }),
    owner: ownedByUser(),
    title: text(),
    done: boolean().default(false),
    priority: integer().default(0),
    tags: text().array().default([]),
    created_at: timestamp().defaultNow(),
  },
  policies: (p) => [policy("todos_own").for("all").using(p.col("owner").eq(p.auth.uid())).withCheck(p.col("owner").eq(p.auth.uid()))],
});

export const list_members = defineTable("list_members", {
  columns: {
    list_id: uuid().references(() => lists.id, { onDelete: "cascade" }),
    user_id: userRef({ onDelete: "cascade" }),
    role: text().default("member"),
  },
  primaryKey: ["list_id", "user_id"],
  policies: (p) => [policy("members_self").for("all").using(p.col("user_id").eq(p.auth.uid())).withCheck(p.col("user_id").eq(p.auth.uid()))],
});

export const payments = defineTable("payments", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    owner: ownedByUser(),
    idem_key: text().unique(),
    amount: numeric({ precision: 12, scale: 2 }),
  },
  policies: (p) => [policy("payments_own").for("all").using(p.col("owner").eq(p.auth.uid())).withCheck(p.col("owner").eq(p.auth.uid()))],
});

export default defineSchema("public", { tables: [lists, todos, list_members, payments] });
```

A service that reads and writes it, and the controller and module around it:

```ts
// src/modules/todos/todos.service.ts
import { Database, Injectable, NotFound } from "palbase/backend";
import type { Tables } from "palbase/backend/env";

export type Todo = Tables["todos"]["row"];

@Injectable()
export class TodosService {
  open(): Promise<Todo[]> {
    // No owner filter: RLS scopes this to the caller's own rows.
    return Database.public.todos.findMany({ where: { done: false }, orderBy: { column: "created_at", direction: "desc" } });
  }

  create(owner: string, listId: string, title: string): Promise<Todo> {
    return Database.public.todos.insert({ owner, list_id: listId, title });
  }

  async finish(id: string): Promise<Todo> {
    const todo = await Database.public.todos.update({ where: { id }, set: { done: true } });
    if (!todo) throw new NotFound("todo not found");
    return todo;
  }
}
```

```ts
// src/modules/todos/todos.controller.ts
import { Body, Controller, Get, Param, Post, User, z, type UserT } from "palbase/backend";
import { TodosService, type Todo } from "./todos.service";

const CreateTodo = z.object({ listId: z.string().uuid(), title: z.string().min(1).max(200) });
type CreateTodo = z.infer<typeof CreateTodo>;

@Controller("/todos")
export class TodosController {
  constructor(private readonly todos: TodosService) {}

  @Get("")
  list(): Promise<Todo[]> {
    return this.todos.open();
  }

  @Post("")
  create(@Body(CreateTodo) body: CreateTodo, @User() user: UserT): Promise<Todo> {
    return this.todos.create(user.id, body.listId, body.title);
  }

  @Post("/{id}/done")
  finish(@Param("id") id: string): Promise<Todo> {
    return this.todos.finish(id);
  }
}
```

```ts
// src/modules/todos/todos.module.ts
import { Module } from "palbase/backend";
import { TodosController } from "./todos.controller";
import { TodosService } from "./todos.service";

@Module({ controllers: [TodosController], providers: [TodosService] })
export class TodosModule {}
```

The app passes its schemas to the framework — `PalbaseFactory.create(AppModule, { db: { schemas: [schema] } })` in `src/main.ts` — and that is what opens the database at boot. `Database` is imported by the service, not by the controller: which rows, whose, and in what order are the decisions worth testing, and they belong in the class you test.

## One request, one transaction

Each request is one transaction, opened by its first statement:

- **committed when the handler returns** — before the answer goes — and **rolled back when it throws**, whatever it wrote;
- reached from the handler, from any service it calls, and from an [`@On` handler](/docs/backend/hooks) (a delivery is one transaction too) — **never at import time or from a timer**: outside a request `Database.<anything>` throws, naming what was reached;
- **a request that only read** (`findMany`, `findUnique`, `findById`, `count`, `aggregate`, `page`) does not wait for its `COMMIT` — a read of one statement is one round trip — and gives its connection back while the handler [waits on something else](#a-handler-that-waits-on-something-else);
- **a client that hangs up cancels it**: the statement in flight is cancelled and its connection goes back;
- **bounded**: a statement runs at most 55 seconds and waits at most 10 seconds for a lock (5 on `$asService()`), so nothing a request runs outlives the edge in front of the machine.

A database that slept, restarted or failed over closes the connections the app holds. A request that meets a closed one on its first round trip opens another and sends it again — nothing of it had committed — and the caller sees nothing. A connection lost later answers `503 database_unavailable`, because part of the work may have committed.

### A handler that waits on something else

There is nothing to set. A request whose transactions have only read gives its connections back once it has sat a millisecond with no statement running — a call to another service, a timer — and its next statement opens another transaction, bound to the caller again — never refused because the database's queue is full, and ahead of the caller's own requests that have not begun. Reads one after another, and your own code between them, stay in one transaction: giving a connection back and taking one again costs a fraction of a millisecond, so it happens only where a wait is worth it.

```ts
// src/modules/todos/todos-print.service.ts
import { Database, Injectable, NotFound } from "palbase/backend";

@Injectable()
export class TodosPrintService {
  async pdf(id: string) {
    const todo = await Database.public.todos.findUnique({ where: { id }, select: ["id", "title", "done"] });
    if (!todo) throw new NotFound("no such todo");
    // The connection is back in the pool while the other service works.
    const rendered = await fetch("https://pdf.example.com/render", { method: "POST", body: JSON.stringify(todo) });
    return new Response(rendered.body, { headers: { "content-type": "application/pdf" } });
  }
}
```

What is held to the end of the request, because ending it there could change what comes after:

- **after a write** (`insert`, `update`, `delete`, `put`, …), **a lock** (`lock` on `findUnique`, `$lockRows`, `$lockRowsWhere`, `$advisoryXactLock`), **a savepoint** (`$attempt`, `$transaction`) or **SQL of your own** (`$query` — the engine cannot know what it does): everything after it is the same transaction, so a throw still undoes all of it;
- **under a database whose default isolation is repeatable read or serializable**, where one snapshot spans the transaction's statements;
- **while an `$atomic` of the request is open** — it is a transaction of its own, and nothing of the request is given back beside it.

So make the outside call before the first write, and outside `$atomic`. A request that holds a transaction with no statement running for over a second says so in the app's log, once, naming the route:

```text
[palbase] POST /invoices: a transaction of the request could not be given back — it wrote, locked, is an $atomic or an $attempt, ran SQL of its own, or the database keeps one snapshot for it — and sat 2140 ms with no statement running: the handler waited on something else, and a database connection waited with it. Make the outside call before the first write, or outside $atomic.
```

Why giving it back is safe: under read committed, Postgres' default, every statement sees what was committed when it started, and a transaction that only read holds no row lock — the next statement sees what it would have seen in the same transaction. What does move across a wait: `now()` is the new transaction's, a migration's change to a table can land between two reads, and a policy or view that calls a function which writes has that write committed.

## Where the types come from

`Database.public.<table>` is typed by a declaration file, `palbase/palbase-env.d.ts`, that augments `palbase/backend/env`'s `Tables` (and `Schemas`, for every other schema). The CLI writes it from your schema files — each table's row, its insert, its unique keys and its relations both ways (`with`, `has`) — between its markers in that file; `palbase init --db` writes the first one. Run it again after you change a schema file, and commit the file:

```bash
palbase db:types
```

It reads the app's entry (`--entry <file>` when it is not the one the project names) and writes `palbase/palbase-env.d.ts` (`--file <path>` for another); the app's tsconfig must include the file. A schema that has not changed writes the same bytes, so a check in CI can run it and fail on a diff.

A build that cannot run the CLI writes the same declarations with palgres' `makeEnvDts([schema])`.

When you need a row type by name, import it:

```ts
import type { Tables } from "palbase/backend/env";

type Todo = Tables["todos"]["row"];
type NewTodo = Tables["todos"]["insert"];
```

> **Note:** If `Database.public.todos` is a compile error saying the property does not exist, the file has not been written for that table yet. Before any schema exists, `Tables` is empty and every `Database.public.*` access is a compile error — the types are only ever what your schema declares. The runtime never needs them — Bun runs the app without type-checking it — so the file is for your editor and `tsc`.

## The full surface

`Database` carries your schemas by name — `Database.public.<table>`, `Database.<schema>.<table>` — and operations that begin with `$`. A schema or table name can never start with `$`, so a table called `transaction` is `Database.public.transaction` and the operation is `Database.$transaction`.

| Member | What it is |
|---|---|
| `public.<table>`, `<schema>.<table>` | the typed table operations below |
| `$query<T>(sql, params?)` | raw SQL on the request's transaction — **not** read-only |
| `$transaction(fn)` | a **plan** run inside one savepoint of the request's transaction |
| `$atomic(fn, opts?)` | an independently committed transaction, with retries |
| `$attempt(fn)` | `fn` inside a `SAVEPOINT`: its failure rolls back only what its handle wrote |
| `$asService()` | the same surface as the service role, past RLS |
| `$lockRows(table, ids)` | locks those rows in primary-key order — never the caller's order, so two callers cannot deadlock on it |
| `$lockRowsWhere(table, where, { mode })` | locks the rows a filter matches, in one statement |
| `$advisoryXactLock(key)` | locks a **name** until the transaction ends — "one invoice run at a time" |

Every typed table method also has a string-keyed twin — `$insert(table, data)`, `$findMany(table, where, opts)`, `$updateMany`, `$put`, `$claim`, `$count`, `$aggregate`, `$page` and the rest — for code where the table's name is a variable. The name is `"todos"` for `public` and `"ledger.accounts"` for any other schema.

## Typed tables

Every read and every bulk write takes one object — `where`, `select`, `orderBy`, `limit`, `with` sit side by side in it.

| Method | Returns |
|---|---|
| `insert(data)` | the inserted row |
| `insertMany(rows, { onConflict?, action?, returning? })` | the rows written, or their count with `returning: false` — `action: "ignore"` skips a duplicate |
| `findById(id)` / `findUnique({ where, lock? })` | the row, or `null` — with `lock`, locked until the transaction ends |
| `findMany({ where?, select?, orderBy?, limit?, offset?, with? })` | the matching rows |
| `page({ where?, orderBy?, first?, after?, last?, before?, select?, with? })` | `{ rows, pageInfo }` — keyset pages with sealed cursors |
| `count({ where? })` | how many rows match |
| `aggregate({ where?, sum?, avg?, min?, max?, count?, groupBy? })` | the aggregate, or one row per group |
| `update({ where: { id }, set })` | the updated row, or `null` |
| `updateMany({ where, set, returning? })` | the updated rows — an empty `where` is refused |
| `delete(id)` / `deleteMany({ where })` | nothing / how many rows went |
| `put({ data, onConflict })` | insert, or overwrite the row it collided with |
| `claim(unique, extra?)` | `{ inserted, row }` — own an idempotency key, never overwrite |

`update`, `delete` and `findById` address a row by its `id` column; a table keyed otherwise is reached with `findUnique`, `updateMany` and `deleteMany`.

### Filtering and ordering

A field takes a value for equality or an operator object; fields are `AND`ed.

```ts
import { Database } from "palbase/backend";

declare const since: string;

const urgent = await Database.public.todos.findMany({
  where: {
    done: false,
    priority: { gte: 2 },
    created_at: { gt: since },
    tags: { overlaps: ["work", "urgent"] },
    OR: [{ title: { icontains: "invoice" } }, { title: { startsWith: "Pay" } }],
  },
  select: ["id", "title", "priority"],
  orderBy: [{ column: "priority", direction: "desc" }, { column: "created_at" }],
  limit: 50,
});
```

| Operator | SQL |
|---|---|
| a value | `=` — `null` is `IS NULL` |
| `{ in: [...] }` | `IN (…)` — an empty list matches no row |
| `{ neq }`, `{ gt }`, `{ gte }`, `{ lt }`, `{ lte }` | `<>`, `>`, `>=`, `<`, `<=` |
| `{ isNull: true }` / `{ isNull: false }` | `IS NULL` / `IS NOT NULL` |
| `{ contains }`, `{ icontains }`, `{ startsWith }`, `{ endsWith }` | `LIKE` / `ILIKE` on text, the pattern's `%` and `_` escaped |
| `{ contains: [...] }`, `{ overlaps: [...] }` | on an array column: `@>` (all of them), `&&` (any) |
| `OR`, `AND`, `NOT` | the branches |
| `col("other")` | compare with another column: `{ balance: { lt: col("limit") } }` |
| `now()`, `ago({ hours: 1 })` | the server's clock, and the server's clock less a span: `{ created_at: { gt: ago({ days: 7 }) } }` |
| `sqlFragment` | SQL of your own, values bound: `` where: sqlFragment`similarity(title, ${q}) > 0.3` `` |

`col`, `sqlFragment`, `increment`, `decrement`, `now`, `ago` and `withRetry` are imported from `palgres`, the package `palbase/backend` is built on. `select` narrows the returned row type; a column name in `orderBy` or `select` is checked against the schema before any SQL is written.

### Time on the database's clock: `now()` and `ago()`

```ts
import { Database } from "palbase/backend";
import { ago } from "palgres";

// Opened in the last week, by the database's clock.
const recent = await Database.public.todos.findMany({ where: { created_at: { gt: ago({ days: 7 }) } }, select: ["id", "title"] });

// Finished a month ago or more: they go.
const swept = await Database.public.todos.deleteMany({ where: { done: true, created_at: { lt: ago({ days: 30 }) } } });
```

`ago(span)` is `now()` less a span — whole `days`, `hours`, `minutes` and `seconds`, none negative — and it stands wherever `now()` does: a filter, an `insert`, an update's `set`, a plan. Both sides of the comparison are read where the data is. A window counted from `new Date()` moves with every machine's drift from the database, and a row stamped by `defaultNow()` was stamped by the database's clock.

### Relations: `has` and `with`

Every foreign key is a relation both ways — `todos.list` (forward) and `lists.todos` (reverse); [Schema](/docs/backend/schema) says how they are named. `has` filters through one, `with` fetches it in the same statement:

```ts
import { Database } from "palbase/backend";

// Lists that still have an open todo, each with its three newest.
const lists = await Database.public.lists.findMany({
  where: { has: { todos: { done: false } } },
  select: ["id", "title"],
  with: { todos: { select: ["id", "title"], orderBy: { column: "created_at", direction: "desc" }, limit: 3 } },
});

for (const list of lists) console.log(list.title, list.todos.length);
```

A `many` relation comes back as an array (`[]` when there is none), a `one` relation as a row or `null`. `with` nests three levels deep.

### Pages

`page()` is keyset pagination: the primary key is appended to the ordering, and its cursors are sealed to the query and to the caller, so a cursor from one user's query does not open another's.

```ts
import { Database } from "palbase/backend";

declare const cursor: string | undefined;

const page = await Database.public.todos.page({
  orderBy: { column: "created_at", direction: "desc" },
  first: 20,
  after: cursor,
  select: ["id", "title", "created_at"],
});
const next = page.pageInfo.hasNextPage ? page.pageInfo.endCursor : null;
```

`first`/`after` page forward and `last`/`before` back; a page is 50 rows when no size is given.

### Aggregates

```ts
import { Database } from "palbase/backend";

const totals = await Database.public.todos.aggregate({ where: { done: false }, count: true, sum: ["priority"] });
// { count: number; sum: { priority: string | null } }

const byList = await Database.public.todos.aggregate({ groupBy: ["list_id"], count: true });
// { list_id: string; count: number }[]

// Several counts, one statement: each name counts what its filter matches, within `where`.
const board = await Database.public.todos.aggregate({
  where: { done: false },
  count: { all: {}, urgent: { priority: { gte: 2 } }, work: { tags: { overlaps: ["work"] } } },
});
// { count: { all: number; urgent: number; work: number } }
```

`count: true` counts the rows; `count: { <name>: <filter> }` counts, in the same statement, the rows each filter matches — `count(*) FILTER (WHERE …)`, one scan however many names — within `where`, per group with `groupBy`, and `{}` is every row. Five limits checked as five `count()` calls are five round trips; as one `aggregate` they are one. `sum` and `avg` are strings — `sum(integer)` is a `bigint` and `sum(numeric)` a `numeric`, both lossy as a JS number — and an empty set sums to `null`, not 0.

### `put()`, `claim()` and skipping what is there

Read-then-write loses a race, and catching the unique violation does not rescue it: the failed insert aborts the request's transaction. Each of these is one statement.

```ts
import { Database } from "palbase/backend";

declare const listId: string;
declare const userId: string;
declare const idemKey: string;

// Write it, and overwrite the row it collided with.
await Database.public.list_members.put({ data: { list_id: listId, user_id: userId, role: "editor" }, onConflict: ["list_id", "user_id"] });

// Write it once: a second call with the same key gets the FIRST call's row back.
const { inserted, row } = await Database.public.payments.claim({ idem_key: idemKey }, { owner: userId, amount: "19.90" });

// Write the ones not there yet, whichever unique key they would collide on: what comes back is what was written.
const written = await Database.public.payments.insertMany(
  [{ owner: userId, idem_key: idemKey, amount: "19.90" }],
  { action: "ignore" },
);
```

`onConflict` must name columns a unique constraint or index covers. `put` overwrites; `claim` never does, and `inserted: false` is not an error — it is the answer that the work was already done. `insertMany` with `action: "ignore"` and no `onConflict` skips a row that collides with **any** unique key — the primary key or another — as Prisma's `skipDuplicates` and Drizzle's `onConflictDoNothing()` do; with `onConflict` it skips only a collision on those columns, and any other is still a `UniqueViolation`. An overwrite (`action: "update"`) has to name its columns. A skipped row is not an error and is not returned; a row a policy refuses is still refused.

### Locking the row you read: `findUnique({ lock })`

A decision read from a row is only as good as the row staying what it was. `lock` reads the row and locks it **in the same statement**, until the transaction ends — a read and then a lock would decide on a row another request changed in between:

```ts
import { Conflict, Database, NotFound } from "palbase/backend";

declare const listId: string;
declare const userId: string;

// A second request changing this member waits here, then reads what the first committed.
const member = await Database.public.list_members.findUnique({ where: { list_id: listId, user_id: userId }, select: ["role"], lock: "update" });
if (!member) throw new NotFound("no such member");
if (member.role === "owner") throw new Conflict("an owner is not demoted here", "owner");
await Database.public.list_members.updateMany({ where: { list_id: listId, user_id: userId }, set: { role: "viewer" } });
```

- **`"update"`** is `FOR UPDATE` — the row is about to change or go; **`"noKeyUpdate"`** `FOR NO KEY UPDATE` — it changes, its key stays; **`"share"`** `FOR SHARE` — it must not change while you read on, and other readers may share it.
- **It is held until the transaction ends** — the request's, or the `$atomic` callback's. Another transaction asking for the row waits — 10 seconds at most on a request, `lockTimeoutMs` in `$atomic`, then `503 database_busy` — and reads what the first committed: the new values, or `null` if it deleted the row.
- **One row has no lock order to get wrong.** For many rows use `$lockRowsWhere`, which takes them in primary-key order. Only the table's own row is locked, never what `with` fetches beside it.
- **Postgres checks a locking read against the table's update policies** as well as its select ones: a row the caller may read but not update comes back `null` with a `lock`.

### `$attempt()`: a failure that does not poison the request

When the recovery is not a `put`, put the write that may fail inside `$attempt`. It takes a `SAVEPOINT`, so only that write rolls back and the request goes on.

```ts
import { Database, UniqueViolation } from "palbase/backend";

declare const listId: string;
declare const userId: string;

const joined = await Database.$attempt(async (tx) => {
  await tx.insert("list_members", { list_id: listId, user_id: userId });
  return true;
}).catch((e: unknown) => {
  if (UniqueViolation.is(e)) return false;
  throw e;
});
```

The handle is a parameter, not the ambient `Database`: only what `tx` writes is inside the savepoint, so a concurrent branch of the same request is never rolled back with it.

## `null` means "no row" — including rows RLS hides

`findById`, `findUnique` and `update` resolve to `null` when no row matched, and that covers two cases you cannot tell apart from inside the handler: the id does not exist, or a policy hides the row from this caller. Not telling them apart is the point — a distinguishable answer would be an oracle for rows the caller may not read. Map it yourself where a missing row is the client's error:

```ts
import { Database, NotFound } from "palbase/backend";

declare const id: string;

const todo = await Database.public.todos.findById(id);
if (!todo) throw new NotFound("todo not found");
```

## Raw SQL with `$query()`

`$query<T>(sql, params?)` runs SQL on the request's transaction and returns rows as plain objects, typed as the `T` you say they are — only you know what raw SQL returns.

```ts
import { Database } from "palbase/backend";

declare const ids: string[];

const rows = await Database.$query<{ id: string; title: string }>(
  "SELECT id, title FROM todos WHERE id = ANY($1::uuid[]) AND NOT done ORDER BY created_at DESC LIMIT $2",
  [ids, 20],
);
```

> **Warning:** `$query` is **not** read-only. It runs on the same transaction the typed tables write through, so a write in it — a plain `UPDATE`, a CTE, a function that writes — commits with the request. What stands between it and your data is RLS and the caller's role, exactly as for everything else on this page.

Parameters are `$1…$n`, never interpolated. Each is sent as the text Postgres reads and the statement's casts decide its type: a string as it is; a number, bigint or boolean as its literal; a `Date` as ISO 8601; an array of scalars as a Postgres array (`= ANY($1::uuid[])`); an object, or an array holding objects, as JSON. For a `jsonb` parameter pass `JSON.stringify(value)` — an empty array alone goes as the Postgres array `{}`, which `::jsonb` reads as an object. Rows come back as the driver parses them: `bigint` and `numeric` as strings, a timestamp as an ISO string.

While a release that renames or retypes a column is between `start` and `complete`, name tables bare in the new version's raw SQL (`todos`, not `public.todos`) and name an `ON CONFLICT` target by its columns, not its constraint — the new version reads through views that hold the new names. The typed tables already work this way. See [Schema changes](/docs/backend/migrations).

## Transactions are a plan, not a session

`Database.$transaction(fn)` does not open an interactive session. The callback **describes** what should happen; nothing has run when it returns. The engine then runs the whole plan inside one savepoint of the request's transaction and answers once.

```ts
import { Conflict, Database } from "palbase/backend";

declare const userId: string;
declare const titles: string[];

const { listId } = await Database.$transaction((tx) => {
  const list = tx.public.lists.insert({ owner: userId, title: "Groceries" }).expectOne(new Conflict("the list was not written"));
  tx.public.todos.insertMany(titles.map((title) => ({ list_id: list.id, owner: userId, title })));
  return { listId: list.id };
});
```

Three rules follow, and the first two are the compiler's:

1. **The callback is synchronous.** `async` on it and `await` in it are compile errors — there is nothing to await.
2. **An operation gives a handle, not a row.** Reading a field takes `.expectOne(err)` first, which makes "what if the row is not there" an argument you cannot skip.
3. **A field you read is a `Ref`** — a value the server will produce. It can be written into a later operation and returned from the callback (it is replaced by the real value before `$transaction` resolves); it cannot be branched on.

| Plan method | What it does |
|---|---|
| `insert(values)` | one row |
| `insertMany(rows, { onConflict?, action? }?)` | many rows in one statement, every row the same columns — `action: "ignore"` alone skips a collision with any unique key |
| `put(values, { onConflict })` | insert, or overwrite what it collided with |
| `updateWhere(where, set)` | every matching row — an unfiltered update is refused |
| `deleteWhere(where)` | every matching row — an unfiltered delete is refused |
| `select(where?, { limit?, lock? })` | read rows; `lock: "update"` is a real `FOR UPDATE` |

`increment(n)`, `decrement(n)`, `now()` and `ago(span)` read the column's current value and the server's clock where the plan runs — `increment` and `decrement` in an update's `set`, `now()` and `ago()` wherever a value goes. The typed `update` and `updateMany` take them too:

```ts
import { Database, NotFound } from "palbase/backend";
import { increment } from "palgres";

declare const todoId: string;

await Database.$transaction((tx) => {
  tx.public.todos.updateWhere({ id: todoId }, { priority: increment(1) }).expectOne(new NotFound("todo not found"));
});
```

### Guards

| Guard | Meaning |
|---|---|
| `expectOne(error)` | exactly one row — and the only way to read one |
| `expectNone(error)` | no row matched |
| `expectAtLeast(n, error)` / `expectAtMost(n, error)` | a bound on the count |

A failed guard throws the error you gave and rolls the whole plan back. That replaces reading a value and branching on it: `updateWhere({ id, done: false }, { done: true }).expectOne(new Conflict("already done"))` is a race-free compare-and-set, checked where the rows are.

> **Warning:** Coercing a `Ref` (`String(ref)`, `+ref`), awaiting it or serialising it throws `TxRefError` as the plan is built. Bare truthiness is the one hole JavaScript does not let a proxy close: `if (row.done)` inside the callback is always true. Read a value before the plan and branch there, or say it as a guard.

A plan holds at most 1000 operations and 5000 rows per `insertMany`; a reference points only backwards, at an operation known to yield one row. A plan that breaks a rule throws `TxPlanError` at the line that wrote it, before anything is sent.

## `$atomic()` — a transaction of your own, with retries

`$transaction` is a savepoint of the request's transaction, so it cannot retry: a savepoint keeps its parent's snapshot. When the work needs its own boundary — a transfer, anything that must survive a serialization failure — use `$atomic`. The ledger lives in a schema of its own:

```ts
// src/db/ledger.ts
import { defineSchema, defineTable, numeric, ownedByUser, policy, timestamp, uuid } from "palbase/backend";

export const accounts = defineTable("accounts", {
  columns: { id: uuid().primaryKey().defaultRandom(), owner: ownedByUser(), balance: numeric({ precision: 14, scale: 2 }).default("0") },
  policies: (p) => [policy("accounts_own").for("all").using(p.col("owner").eq(p.auth.uid())).withCheck(p.col("owner").eq(p.auth.uid()))],
});

export const entries = defineTable("entries", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    account_id: uuid().references(() => accounts.id),
    owner: ownedByUser(),
    amount: numeric({ precision: 14, scale: 2 }),
    created_at: timestamp().defaultNow(),
  },
  policies: (p) => [policy("entries_own").for("all").using(p.col("owner").eq(p.auth.uid())).withCheck(p.col("owner").eq(p.auth.uid()))],
});

export default defineSchema("ledger", { tables: [accounts, entries] });
```

```ts
// src/modules/ledger/ledger.service.ts
import { Conflict, Database, Injectable, NotFound } from "palbase/backend";
import { decrement } from "palgres";

@Injectable()
export class LedgerService {
  withdraw(accountId: string, amount: string) {
    return Database.$atomic(
      async (tx) => {
        // Ordinary async reads and writes: this callback is not a plan.
        const account = await tx.ledger.accounts.findById(accountId);
        if (!account) throw new NotFound("account not found");
        await tx.ledger.entries.insert({ account_id: accountId, owner: account.owner, amount: `-${amount}` });
        // The compare-and-set is a plan, so the check happens where the row is.
        return tx.$transaction((plan) =>
          plan.ledger.accounts
            .updateWhere({ id: accountId, balance: { gte: amount } }, { balance: decrement(amount) })
            .expectOne(new Conflict("insufficient balance")),
        );
      },
      { isolation: "serializable", retry: 3, lockTimeoutMs: 1000 },
    );
  }
}
```

- **The callback is `async`**, and its promise resolves after `COMMIT`.
- **`retry` is 0 unless you say** (at most 10), and only serialization and deadlock failures are retried. Every retry runs the whole callback again on a fresh transaction, so keep external effects out of it.
- **It commits on its own.** A later error in the handler does not undo it, and it is not atomic with the request's transaction — so do not write the same rows on both sides.
- **Options:** `isolation` (`"read committed"`, `"repeatable read"`, `"serializable"`), `readOnly`, `lockTimeoutMs` (5000 by default), `statementTimeoutMs`, `timeoutMs` for the whole scope, retries and queueing included, and a `signal`.

`withRetry(fn, { retry })` from `palgres` gives the same narrow retry policy to work that is not one transaction.

## When the database says no

A statement Postgres refuses throws an error carrying its SQLSTATE in `sqlstate`. The ones an app branches on have classes of their own, exported by `palbase/backend`:

| Error | When | Left to reach the client |
|---|---|---|
| `UniqueViolation` | a duplicate; the constraint is in `e.constraint` | 409 |
| `SerializationFailure`, `DeadlockDetected` | retry them — `$atomic` does when asked | 409 |
| `BadRequest` | request data used as a filter's structure — see below | 400 `bad_request`, naming the field |
| an `HttpError` | a value its column cannot take (not a uuid, out of range, too long) | 400 `invalid_value`; the value is not repeated |
| an `HttpError` | a row a policy's `WITH CHECK` refuses, or a table the caller's role has no grant on (SQLSTATE `42501`) | 403 `permission_denied` to a signed-in caller, 401 to an anonymous one; nothing of the schema is said. On the service role it is the app's own grants: the driver's error, a 500 |
| `TooManyRequests` | the app's database queue is full | 429 with Retry-After |

```ts
// src/modules/payments/payments.service.ts
import { Conflict, Database, Injectable, UniqueViolation } from "palbase/backend";

@Injectable()
export class PaymentsService {
  async record(owner: string, idemKey: string, amount: string) {
    try {
      return await Database.public.payments.insert({ owner, idem_key: idemKey, amount });
    } catch (e) {
      if (UniqueViolation.is(e) && e.constraint === "payments_idem_key_key") throw new Conflict("this payment was already recorded", "duplicate_payment");
      throw e;
    }
  }
}
```

`UniqueViolation.is(e)` matches by shape and holds across two copies of the package; `instanceof` holds too for what the engine throws. The constraint's name is on `e.constraint`, for you, and never in what reaches the client. Rethrow, as above: a request that swallows a refusal and returns cannot commit — Postgres aborted its transaction — and the commit fails with `TransactionAborted` (exported by `palgres`). Swallowing a failure is what `$attempt` is for.

An outage is never a 500: the database unreachable or refusing connections is `503 database_unavailable` with Retry-After, a connection lost mid-request `503 database_unavailable`, and a lock waited for past its bound `503 database_busy`. See [Responses & Errors](/docs/backend/errors).

### Data never becomes structure

A `where` value is a value or an operator — and anything a request sent is only ever a value. The framework marks a request body as `JSON.parse` made it, and Palgres refuses a marked object wherever structure goes — a filter's operators and branches, `select`, `orderBy`, `with`, an aggregate's columns, a claim's key, `onConflict` — with a 400 naming the field. Without that, `{ token: body.token }` with a body of `{ "token": { "neq": null } }` would match every row. Write the structure in code around the values: `{ token: body.token }` with `token: z.string()`, `{ id: { in: body.ids } }`. What a route's schema builds is the route's own, so `z.object({ startsWith: z.string() })` runs as the operator you wrote; what it lets through untouched (`z.unknown()`, a passthrough's extra keys) stays the request's.

## Who each statement runs as

A transaction opens with one statement that binds the caller, its values written as literals:

```sql
SELECT set_config('role', 'authenticated', true),
       set_config('search_path', '…', true),
       set_config('application_name', '…', false),
       set_config('request.jwt.claims', '{"sub":"…","role":"authenticated",…}', true)
```

The role is `authenticated` for a request with a valid token, and `anon` with no claims for one without. `auth.uid()` in a policy reads `sub` from those claims. An operator's app whose every table is the service role's — every request deciding for itself who sees what — says `db: { schemas, requests: "service" }`, and its requests run as `service_role` with the caller's claims kept.

## `$asService()` — past RLS

`Database.$asService()` returns the same typed surface running as `service_role`, which bypasses row-level security. It is for code that legitimately reaches across users: an admin route, a cleanup, a count over everyone.

```ts
import { Database } from "palbase/backend";

const openEverywhere = await Database.$asService().public.todos.count({ where: { done: false } });
```

- **It is a second transaction, on a second connection**, opened by its first use. The role is bound once, when a transaction begins, so a sibling on the request's own transaction would still run as the caller.
- **It keeps the caller's claims.** It changes what may be touched, not who is asking.
- **The two commit as two** — the caller's first — and neither is atomic with the other. Do not write the same row from both in one request: the service side waits at most 5 seconds for a lock the caller's transaction holds, then fails.
- **It does not see what the request wrote.** The caller's transaction has not committed while the handler runs, so a row written through `Database` and read back through `$asService()` reads as it was before: a route that saves a profile and then answers it as the service answers the old one. Read it back through `Database`, or do the write and the read both as the service in one `$asService().$atomic(cb)`.
- **Inside `$asService().$atomic(cb)`, use the handle `cb` is given.** The shared `Database` is refused there: read as the service role, a helper that counts on the caller's RLS would read every user's rows.

Your own code is the only authorisation left inside it, so check the caller's right first, and call it at the point of use rather than keeping the client in a field — the value of the escape hatch is that a reviewer can grep for it.

## Connections and drivers

On a machine, the app may hold `PALBASE_DB_CONNECTIONS` connections — its share of what the database's size allows, counted across every copy of every machine given the database. Told nothing (a laptop), it holds 31. A third of the pool serves requests' first transactions and two thirds their further ones (`$asService`, `$atomic`), so an admitted request never waits for a connection only another request can free. A request that finds the queue full, or waits in it past about a second, answers `429` with Retry-After.

The default driver is Bun's built-in SQL, which is why the examples' images run the app under Bun. Off Bun there is no built-in SQL client, so give one: `db: { schemas, driver }`, with postgres.js created with `{ types: POSTGRES_JS_TYPES }` and its engine `postgresJsDriver(pool, control)`, both from `palgres`. `db.url` overrides `PALBASE_DB_URL`, for a test database of your own.

## Related

- [Schema](/docs/backend/schema) — the declarations `Database.public.*` is typed from
- [Row-Level Security](/docs/backend/row-level-security) — policies, roles, and what a policy-less table returns
- [Schema changes](/docs/backend/migrations) — how a release migrates the database beside the version serving
- [Databases](/docs/machines/databases) — opening one, its credentials, and giving it to a machine
- [Responses & Errors](/docs/backend/errors) — the envelope a thrown error becomes
- [Event Hooks](/docs/backend/hooks) — `@On` handlers, which run in a transaction of their own



<!-- ===== backend/schema ===== -->

# Schema

Your database schema lives in your repository, in TypeScript, one file per Postgres schema: `src/db/public.ts` declares `public`, `src/db/billing.ts` declares `billing`. Each file default-exports a `defineSchema("<name>", { tables })` call naming its tables, columns, foreign keys, [Row-Level Security policies](/docs/backend/row-level-security), constraints, indexes and extensions. The DSL is Palgres', re-exported by `palbase/backend`, and it is the only description of the schema you write. There are no migration files: every release of your machine migrates its database to what these files declare, beside the version still serving — see [Schema changes](/docs/backend/migrations).

## Quick example

```ts
// src/db/public.ts
import {
  boolean, defineSchema, defineTable, enumType, index, integer, jsonb,
  ownedByUser, policy, text, timestamp, uuid,
} from "palbase/backend";

export const lists = defineTable("lists", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    owner: ownedByUser(),
    title: text(),
  },
  policies: (p) => [
    policy("lists_own").for("all").to("authenticated")
      .using(p.col("owner").eq(p.auth.uid()))
      .withCheck(p.col("owner").eq(p.auth.uid())),
  ],
});

export const todos = defineTable("todos", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    list_id: uuid().references(() => lists.id, { onDelete: "cascade" }),
    owner: ownedByUser(),
    title: text(),
    status: enumType("todo_status", ["open", "done", "archived"]).default("open"),
    priority: integer().default(0),
    done: boolean().default(false),
    meta: jsonb().nullable(),
    created_at: timestamp().defaultNow(),
  },
  // `policies` and `indexes` are CALLBACKS: `p` carries this table's own column
  // names, so `p.col("ownr")` is a compile error, not a refusal from Postgres.
  policies: (p) => [
    policy("todos_own").for("all").to("authenticated")
      .using(p.col("owner").eq(p.auth.uid()))
      .withCheck(p.col("owner").eq(p.auth.uid())),
  ],
  indexes: (p) => [index("todos_owner_created").on(p.col("owner"), p.col("created_at"))],
});

export default defineSchema("public", { tables: [lists, todos] });
```

The app hands its schemas to the framework in `src/main.ts`. That is how they are found — no directory is scanned:

```ts
// src/main.ts
import { PalbaseFactory } from "palbase/backend";
import { AppModule } from "./app.module";
import schema from "./db/public";

// Serves on $PORT with its database. Run by a release with PALBASE_DB_MIGRATE,
// the same image migrates the database to this schema and exits.
await PalbaseFactory.create(AppModule, { db: { schemas: [schema] } });
```

```ts
// src/app.module.ts
import { Module } from "palbase/backend";

@Module({ imports: [] })
export class AppModule {}
```

Five things to notice:

- **A table is a value that knows its own name.** `defineTable("todos", …)` returns a binding, and `defineSchema` reads the name off it. That is what lets `todos` point at `lists`: one place writes each name, so a reference never resolves against a table whose identity is not set yet.
- **`defineSchema` takes an array** of those bindings, and its first argument is the schema's own name.
- **The file `export default`s the `defineSchema(...)` call.** `main.ts` imports that value; Palgres' type generator reads the same value.
- **Columns are `NOT NULL` by default**; `.nullable()` opts in to `NULL`.
- **RLS is on by default**, and declaring `policies` forces it on. A table with RLS and no policy denies everything — the most common reason a fresh backend's first `GET` returns `[]`. Read [Row-Level Security](/docs/backend/row-level-security) before your first release.

## One file per schema

```text
src/db/
  public.ts     → defineSchema("public", …)
  billing.ts    → defineSchema("billing", …)
```

Every schema the app declares is in the `schemas` list it gives `PalbaseFactory.create`, and its tables are reached as `Database.<schema>.<table>` — `Database.public.todos`, `Database.billing.invoices`. A foreign key into another schema imports the table binding and points at it:

```ts
// src/db/billing.ts
import { defineSchema, defineTable, numeric, uuid } from "palbase/backend";
import { lists } from "./public";

const invoices = defineTable("invoices", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    list_id: uuid().references(() => lists.id),
    amount: numeric({ precision: 12, scale: 2 }),
  },
  rls: false,
});

export default defineSchema("billing", { tables: [invoices] });
```

Export the tables another file references (`export const lists = defineTable(…)`). The written foreign key names its target with its schema — `billing.invoices.list_id` points at `public.lists`, never at a same-named table the `search_path` happens to find. A reference into a table no `defineSchema` has claimed is refused with both names, so declare the referenced schema's file and import it.

## `defineTable`

`defineTable(name, input)`. Only `columns` is required.

| Field | Type | What it is |
|---|---|---|
| `columns` | `{ [name]: ColumnBuilder }` | **required** — the table's columns |
| `rls` | `boolean` | defaults to `true`; `false` is the explicit opt-out for a public table |
| `policies` | `(p) => PolicyBuilder[]` | RLS policies; a non-empty list forces `rls` on |
| `primaryKey` | `string[]` | composite primary key, in order |
| `unique` | `{ name, columns }[]` | named multi-column `UNIQUE` constraints |
| `checks` | `{ name, expr }[]` or `(c) => CheckDef[]` | `CHECK` — raw SQL, or the typed `check(name, c.col("total").gt(0))` |
| `indexes` | `(c) => IndexBuilder[]` | `index("name").on(c.col("x"))`, partial, expression, unique, covering |
| `foreignKeys` | `(c) => ForeignKeyBuilder[]` | multi-column `FOREIGN KEY` |
| `raw` | `raw(name, sql)[]` | what the typed fields cannot say — another index method, an `EXCLUDE` |
| `ignored` | `boolean` | "this release no longer reads this table" — the first half of dropping it |

Every callback field is a callback for the same reason: the argument carries this table's own column names as a literal union, so a misspelt column is a compile error on the line you wrote it, not an error from Postgres in the middle of a release.

The returned value **is its columns**: `todos.id` is the `id` column builder, which is what makes `references(() => todos.id)` an ordinary expression your editor completes. The table's own metadata hangs off a symbol, so a column may be called `name`, `columns` or `rls` without shadowing anything. Each table gets its own copy of the column builders it is given, so a shared spread (`...audit`) of columns in two tables is two sets of columns.

## `defineSchema`

`defineSchema(name, input)`.

| Field | Type | What it is |
|---|---|---|
| `tables` | `TableHandle[]` | **required** — the `defineTable` bindings, in any order |
| `extensions` | `string[]` | Postgres extensions the migration creates — see [Postgres extensions](#postgres-extensions) |
| `raw` | `raw(name, up, { drop })[]` | schema-level units: views, functions, triggers over several tables |

`defineSchema` is where every pending reference is resolved: the `() => lists.id` callbacks run here, once every binding exists. Two tables of one name in one schema are refused, and so are two raw units of one name.

## Column types

All factories are imported from `palbase/backend`. The third column is the type `palbase-env.d.ts` gives the value on `Database.public.*` (see [Where the types come from](/docs/backend/database)).

| Factory | Postgres type | Row type |
|---|---|---|
| `uuid()` | `uuid` | `string` |
| `text()` | `text` | `string` |
| `integer()` | `integer` | `number` |
| `bigint()` | `bigint` | `string` |
| `numeric()` / `numeric({ precision, scale })` | `numeric` / `numeric(p,s)` | `string` |
| `boolean()` | `boolean` | `boolean` |
| `timestamp()` | `timestamp with time zone` | `string` |
| `date()` | `date` | `string` (`"YYYY-MM-DD"`) |
| `jsonb()` | `jsonb` | `Json` |
| `enumType(name, values)` | a Postgres enum type named `name` | the union of the values |
| `sqlType("inet")` | the Postgres type, as Postgres spells it | `string` — `number` for `smallint`, `real`, `double precision` |

A `.nullable()` column's row type becomes `T | null`. `.array()` makes any scalar an array — `text().array()` is `text[]`, surfaced as `string[]`, filtered with `contains` and `overlaps`; the only default an array takes is the empty one, `.default([])`.

`bigint()` and `numeric()` surface as **`string`**: a JavaScript number cannot hold a 64-bit integer past 2^53 or an arbitrary-precision decimal without rounding. Keep money in them and parse with `BigInt(row.amount)` or a decimal library — or declare `.asNumber()` on a column whose values you know fit in a JS number, and it surfaces as `number`. `date()` is a calendar day, not an instant: a JS `Date` would pick a time zone for it.

`sqlType()` is the escape hatch for a type the DSL does not offer — `inet`, `interval`, `citext`, `character varying(20)`, `vector(1536)`. Spell it as Postgres does (`character varying(20)`, not `varchar(20)`); a type the DSL has is refused by name (`sqlType("text")` asks for `text()`), so each type has one spelling.

### jsonb

A `jsonb()` column takes a plain object or array on insert and update — do not `JSON.stringify` it — and reads back as the value. `jsonb<T>()` takes a payload type, but **the type does not reach `palbase-env.d.ts`**: the generated file types every `jsonb` column as `Json`. Narrow it where you read it, with a schema you already have: `TagList.parse(row.tags)`.

### Enums

`enumType(name, values)` makes a real Postgres enum type, and the TypeScript side is the narrow union of the values:

```ts
import { defineTable, enumType, uuid } from "palbase/backend";

export const tickets = defineTable("tickets", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    // row type: "open" | "pending" | "closed"
    status: enumType("ticket_status", ["open", "pending", "closed"]).default("open"),
    tags: enumType("ticket_tag", ["bug", "billing", "other"]).array().default([]),
  },
});
```

The first argument is the Postgres type's name, not the column's. Adding a value is an ordinary migration; removing one is refused (Postgres cannot drop an enum value) — see [Schema changes](/docs/backend/migrations).

## Chain methods

Every builder method returns a builder, so modifiers chain.

| Method | Effect |
|---|---|
| `.primaryKey()` | `PRIMARY KEY` |
| `.notNull()` / `.nullable()` | `NOT NULL` (the default) / allow `NULL` |
| `.default(value)` | a literal `DEFAULT` |
| `.defaultRandom()` | `uuid()` — `DEFAULT gen_random_uuid()` |
| `.defaultNow()` | `timestamp()` — `DEFAULT now()`; `date()` — `CURRENT_DATE` |
| `.defaultSql(expr)` | a default the database computes, written as SQL |
| `.dbAssigned()` | a trigger or rule writes the value: optional on insert, no `DEFAULT` in the DDL |
| `.unique()` | single-column `UNIQUE` |
| `.array()` | an array of this type |
| `.identity()` | `GENERATED ALWAYS AS IDENTITY` on `integer()`/`bigint()` — off every insert and update; `{ always: false }` is `BY DEFAULT` |
| `.generated(expr, { stored? })` | `GENERATED ALWAYS AS (expr)` — virtual by default (Postgres 18), `stored: true` on disk |
| `.references(() => t.col, opts?)` | a foreign key — see [Foreign keys](#foreign-keys) |
| `.selfReferences("column", opts?)` | a foreign key onto this same table |
| `.onDelete(action)` | `ON DELETE` of a foreign-key column |
| `.asNumber()` / `.asDecimal()` | surface a `numeric`/`bigint` column as `number`, or say `string` explicitly |
| `.renamedFrom(previous)` | this column used to be called `previous` |
| `.fillWith(sql)` | how to fill a `NOT NULL` column for rows that do not supply it — see [Schema changes](/docs/backend/migrations) |
| `.ignored()` | this release no longer reads or writes the column — the first half of dropping it |

## Foreign keys

The target is a **callback**: `references(() => lists.id)`, not `references(lists.id)`. It runs inside `defineSchema`, where every binding exists, which is what makes a cycle expressible.

| Option | What it does |
|---|---|
| `onDelete` | `"cascade"`, `"set null"`, `"set default"`, `"restrict"` or `"no action"` (the default) |
| `onUpdate` | the same actions, on a change of the referenced key |
| `as` | the forward relation's name — `list_id` gives `list` by default |
| `reverseAs` | the reverse relation's name on the parent — this table's name by default |
| `index` | `false` leaves the column without the index Palgres makes for a foreign key |

Postgres does not index a foreign key's column by itself, and every join through it and every `ON DELETE CASCADE` pays for that. Palgres makes `<table>_<column>_idx` for each one unless you say `index: false` — which is right only when the column is updated often enough that an index on it would cost more than it saves.

### Pointing at this same table

A parent pointer — category trees, replies, org charts — takes the column's name and no callback:

```ts
import { defineTable, text, uuid } from "palbase/backend";

export const categories = defineTable("categories", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    name: text(),
    parent_id: uuid().nullable().selfReferences("id"),
  },
  rls: false,
});
```

### Two tables that point at each other

A cycle needs an explicit return type on **one** side, and one is enough:

```ts
import { type AnyColumn, defineTable, uuid } from "palbase/backend";

export const members = defineTable("members", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    // the annotated side — without it TypeScript chases its own tail (TS7022)
    primary_team_id: uuid().nullable().references((): AnyColumn => teams.id),
  },
});

export const teams = defineTable("teams", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    lead_id: uuid().nullable().references(() => members.id),
  },
});
```

### Two foreign keys to the same table

Every foreign key gives two relation names, which [`with` and `has`](/docs/backend/database) read: the forward one on the child (`billing_address_id` → `billing_address`) and the reverse one on the parent (by default the child table's name). Two keys from one table onto one parent collide on the reverse side, so name at least one:

```ts
import { defineTable, text, uuid } from "palbase/backend";

export const addresses = defineTable("addresses", {
  columns: { id: uuid().primaryKey().defaultRandom(), line1: text() },
});

export const orders = defineTable("orders", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    billing_address_id: uuid().references(() => addresses.id, { reverseAs: "billed_orders" }),
    shipping_address_id: uuid().references(() => addresses.id, { reverseAs: "shipped_orders" }),
  },
});
```

A collision is refused when the schema is built, naming both columns and the option that fixes that direction.

### Composite foreign keys

A key of more than one column is declared on the table, with its own name:

```ts
import { defineTable, foreignKey, text, uuid } from "palbase/backend";

export const projects = defineTable("projects", {
  columns: { org_id: uuid(), id: uuid().defaultRandom(), name: text() },
  primaryKey: ["org_id", "id"],
});

export const tasks = defineTable("tasks", {
  columns: { id: uuid().primaryKey().defaultRandom(), org_id: uuid(), project_id: uuid() },
  // A task's project must be of the same organization — a per-column key cannot say so.
  foreignKeys: (c) => [
    foreignKey("tasks_project_fkey").on(c.col("org_id"), c.col("project_id")).references(projects, "org_id", "id").onDelete("cascade"),
  ],
});
```

## Rows that belong to a user

Your users are the project's [auth](/docs/web/auth) users, and they live in the platform, not in your database — so a column holding a user's id is plain `text`, with no foreign key. Two factories declare one, and say what happens to the row when that user is deleted:

| Factory | Means | When the user is deleted |
|---|---|---|
| `ownedByUser()` | this row **belongs to** the user — `text`, `NOT NULL` | the row is deleted |
| `userRef({ onDelete })` | this row **points at** a user — `created_by`, `edited_by` | `"cascade"`: deleted; `"set null"`: the column is set to `NULL` (declare it `.nullable()`) |

```ts
import { defineTable, ownedByUser, text, userRef, uuid } from "palbase/backend";

export const notes = defineTable("notes", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    owner: ownedByUser(),
    edited_by: userRef({ onDelete: "set null" }).nullable(),
    body: text(),
  },
});
```

**At most one `ownedByUser()` per table**: which column's user takes the row with them must not depend on the order the columns are declared in.

Deleting what a schema keeps of a user is the framework's job, not yours: when the platform delivers `user.deleted`, `palbase/backend` deletes the user's owned rows and nulls the `set null` references, in one transaction as the service role. That needs the delivery to arrive, so **an app whose schema declares either factory refuses to start without `PALBASE_WEBHOOK_SECRET`** — on a machine the platform gives it, and keeps the machine's `/webhooks/palbase` endpoint for `user.deleted`. See [Event Hooks](/docs/backend/hooks) for what that endpoint takes.

> **Note:** A plain `text()` column holding a user's id is not one the framework knows to clear: nothing deletes what it keeps when the user goes, and that erasure is yours to do.

## What is optional on insert

A column is optional on insert when the database can fill it: `.nullable()`, any default (`.default()`, `.defaultRandom()`, `.defaultNow()`, `.defaultSql()`), or `.dbAssigned()`. An `.identity()` (always) or `.generated()` column is on the row and off the insert entirely. Everything else is required. For `todos` above, `Database.public.todos.insert(…)` takes `list_id`, `owner` and `title`, and may take `id`, `status`, `priority`, `done`, `meta` and `created_at`.

## Constraints and indexes

```ts
import { check, defineTable, index, integer, numeric, raw, sqlType, text, timestamp, uuid } from "palbase/backend";

export const products = defineTable("products", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    sku: text(),
    email: text().nullable(),
    price: numeric({ precision: 12, scale: 2 }),
    stock: integer().default(0),
    embedding: sqlType("vector(3)").nullable(),
    deleted_at: timestamp().nullable(),
  },
  rls: false,
  unique: [{ name: "products_sku_key", columns: ["sku"] }],
  checks: (c) => [check("products_price_positive", c.col("price").gt(0)), check("products_stock_not_negative", c.col("stock").gte(0))],
  indexes: (c) => [
    // partial: only the live rows
    index("products_live").on(c.col("sku")).where(c.col("deleted_at").isNull()),
    // partial UNIQUE: NULLs free, non-NULLs unique
    index("products_email_unique").unique().onExpression("lower(email)").where(c.col("email").isNull(true)),
    // covering, newest first
    index("products_stock").on(c.col("stock")).desc().include(["price"]),
  ],
  // What the typed fields cannot say: another index method, an operator class.
  raw: [raw("products_embedding", "CREATE INDEX IF NOT EXISTS products_embedding ON public.products USING hnsw (embedding vector_cosine_ops)")],
});
```

- **`unique`** renders a `UNIQUE` constraint and cannot carry a condition, because Postgres has no partial unique constraint. `index(name).unique().where(…)` is the declarative way to say "NULLs are free, non-NULLs are unique".
- **`checks`** comes in two forms: the typed callback above, whose column names are checked as you type, or `[{ name, expr }]` with the SQL written out. The typed form refuses a subquery or `auth.uid()` — a `CHECK` cannot hold either.
- **`indexes`** — `.on(...cols)` (order kept), `.onExpression(sql)`, `.where(pred)` in the same expression language as policies, `.unique()`, `.include(cols)`, `.asc()`/`.desc()`, `.nulls("first" | "last")`. A migration builds each one `CONCURRENTLY`, so a write never waits for it. An index whose definition changes under the same name is built beside the old one, which the version still serving reads through, and takes its name when the release completes.
- **`raw`** on a table runs its SQL as it is, as the tables' owner. A raw index is known by its name too, so a changed body under the same name is refused: give it a new name.

### Schema-level raw units

What belongs to no single table — a view, a function, a trigger over several tables — is a unit of the schema, and unlike a table's raw entry it has a teardown the migration runs:

```ts
import { boolean, defineSchema, defineTable, ownedByUser, policy, raw, text, uuid } from "palbase/backend";

export const tasks = defineTable("tasks", {
  columns: { id: uuid().primaryKey().defaultRandom(), owner: ownedByUser(), title: text(), done: boolean().default(false) },
  policies: (p) => [policy("tasks_own").for("all").using(p.col("owner").eq(p.auth.uid())).withCheck(p.col("owner").eq(p.auth.uid()))],
});

export default defineSchema("public", {
  tables: [tasks],
  raw: [
    raw(
      "open_tasks",
      "CREATE VIEW public.open_tasks WITH (security_invoker = true) AS SELECT id, owner, title FROM public.tasks WHERE NOT done",
      { drop: "DROP VIEW public.open_tasks" },
    ),
  ],
});
```

A new unit runs its `up`; a unit whose `up` changed runs its previous `drop`, then the new `up`; a unit removed from the declaration runs its `drop`. A view must be `security_invoker = true`, so the reader's policies apply through it. A view, a trigger or a rule with no `drop` is refused — a rollback could not take it back. `{ before: true }` makes a unit before the tables: a domain, a type or a function a column's default calls.

## Postgres extensions

```ts
import { defineSchema, defineTable, sqlType, text, uuid } from "palbase/backend";

const places = defineTable("places", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    name: text(),
    at: sqlType("geography(Point,4326)"),
    embedding: sqlType("vector(1536)").nullable(),
  },
  rls: false,
});

export const geo = defineSchema("public", { tables: [places], extensions: ["postgis", "vector"] });
```

The migration runs `CREATE EXTENSION IF NOT EXISTS` for each, as the database's owner, who is not a superuser — so an extension must be one the owner may create. A Palbase database is Postgres 18 and makes these trusted beside Postgres' own trusted extensions (`pg_trgm`, `citext`, `pgcrypto`, `unaccent` and the rest of contrib's trusted set): `vector` (pgvector), `postgis`, `postgis_topology`, `postgis_raster` and `pg_stat_statements`. A typed column of an extension's type is an `sqlType()`; an index of its method is a `raw` entry. Extensions are only ever added.

## Row-Level Security in the schema

RLS is declared beside the columns, in each table's `policies`, and it is on for every table that does not say `rls: false`. The builder, the roles a policy names, membership policies and the service role are on [Row-Level Security](/docs/backend/row-level-security).

## From a declaration to a database

Edit `src/db/public.ts`, commit and push to the machine's branch. The machine builds your image, and before the new version serves, the platform runs that image once with `PALBASE_DB_MIGRATE=start`: it migrates the database to the schema the image carries, while the version before keeps serving. Once nothing of the old version is left, it runs `complete`. You run nothing yourself, and a change that cannot run under both versions is refused before anything changes. How each kind of change goes — and which take two releases — is [Schema changes](/docs/backend/migrations).

## Related

- [Database](/docs/backend/database) — the typed `Database.public.*` surface these declarations type, and `palbase-env.d.ts`
- [Row-Level Security](/docs/backend/row-level-security) — policies, roles, and `$asService()`
- [Schema changes](/docs/backend/migrations) — how a release migrates, `renamedFrom`, `fillWith`, `ignored`, and what is refused
- [Databases](/docs/machines/databases) — giving a machine a database, and its migrations
- [Event Hooks](/docs/backend/hooks) — `user.deleted`, and the webhook secret an app that keeps users' ids needs



<!-- ===== backend/row-level-security ===== -->

# Row-Level Security

Row-Level Security (RLS) makes **Postgres** decide who may see and write which rows. The rule lives beside the table, declared in TypeScript in your [schema](/docs/backend/schema), instead of being scattered across handlers where one forgotten `WHERE owner = …` leaks somebody's data. Two facts decide whether your first release works: **RLS is on by default**, and **a table with RLS and no policies denies everything** — a table you have not thought about returns nothing, rather than every row to every caller. If your routes answer `[]` and `null` on data you know is there, that default is the first thing to check.

> **Warning:** This is the first release's silent failure. Declare `todos` with columns and no `policies`, push it, and the `POST` fails while the `GET` returns an empty array — no error names RLS, because nothing went wrong: the database was asked for rows and answered honestly that there are none this caller may see. The rule is one line, `rls = policies.length > 0 || table.rls !== false`, and it is fail-closed on purpose: an empty result is the cost of not thinking about a table, and a leak is the other one.

## Quick example

```ts
// src/db/public.ts
import { boolean, defineSchema, defineTable, ownedByUser, policy, text, timestamp, uuid } from "palbase/backend";

export const todos = defineTable("todos", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    // The user this row belongs to: text, NOT NULL, deleted with the user.
    owner: ownedByUser(),
    title: text(),
    done: boolean().default(false),
    created_at: timestamp().defaultNow(),
  },
  // A CALLBACK: `p` carries this table's own column names, so a misspelt column
  // is a compile error rather than a refusal from Postgres mid-release.
  policies: (p) => [
    policy("todos_own")
      .for("all")
      .to("authenticated")
      .using(p.col("owner").eq(p.auth.uid()))
      .withCheck(p.col("owner").eq(p.auth.uid())),
  ],
});

export default defineSchema("public", { tables: [todos] });
```

```ts
// src/modules/todos/todos.service.ts
import { Database, Injectable } from "palbase/backend";
import type { Tables } from "palbase/backend/env";

type Todo = Tables["todos"]["row"];

@Injectable()
export class TodosService {
  // No owner filter anywhere: the policy is the filter.
  list(): Promise<Todo[]> {
    return Database.public.todos.findMany({ orderBy: { column: "created_at", direction: "desc" } });
  }

  // The policy's WITH CHECK refuses a row whose owner is not the caller.
  add(owner: string, title: string): Promise<Todo> {
    return Database.public.todos.insert({ owner, title });
  }
}
```

The service never says whose rows it wants. Postgres reads the caller off the transaction and applies `owner = auth.uid()` to every statement — the typed tables, `$query`, a `$transaction` plan — so a route that forgets a filter cannot read past it.

## How the caller reaches the database

Every request is one transaction, and it begins by binding the caller:

```sql
SELECT set_config('role', 'authenticated', true),
       set_config('request.jwt.claims', '{"sub":"…","role":"authenticated",…}', true)
       -- and the version's search_path and application_name
```

Both settings are transaction-local, so nothing carries over to the next request on a pooled connection. The claims are the verified access token's, and `auth.uid()` reads `sub` out of them. Everything on the default `Database` surface runs inside that transaction; there is no opt-in step and nothing to forget. Going past it takes the explicit [`$asService()`](#asservice-past-rls).

## The roles a policy names

Three Postgres roles exist, and what the request is decides which one it runs as:

| Role | Who runs as it | Policies |
|---|---|---|
| `authenticated` | a request with a valid access token — `auth.uid()` is the user's id | apply |
| `anon` | a request with no token (a route with `auth: false`), with no claims — `auth.uid()` is `NULL` | apply |
| `service_role` | `Database.$asService()`, and every request of an app that says `db: { requests: "service" }` | never apply — it has `BYPASSRLS` |

`.to()` defaults to `"authenticated"`, so a policy you write without one does nothing for an anonymous caller. A table that anonymous callers read needs a policy that names `anon`:

```ts
import { boolean, defineTable, policy, text, uuid } from "palbase/backend";

export const posts = defineTable("posts", {
  columns: { id: uuid().primaryKey().defaultRandom(), title: text(), published: boolean().default(false) },
  policies: (p) => [policy("posts_read_published").for("select").to("anon", "authenticated").using(p.col("published").eq(true))],
});
```

`.to()` with no arguments is `PUBLIC` — every role. The machine connects as the database's app login, which may become `anon`, `authenticated` or `service_role` and nothing else; it cannot bypass RLS on its own. The owner — the role migrations run as — owns the tables, and the app never connects as it.

> **Note:** These roles are the database's, not the API keys'. The project's publishable key and secret key choose what a call to the [modules](/docs/getting-started/introduction) may do. A call to your machine's backend is decided by the user's access token, and inside it the only switch to the service role is the `$asService()` you write.

## Enabling RLS on a table

| You declare | Result |
|---|---|
| neither `rls` nor `policies` | **RLS on, deny-all** — the default |
| a non-empty `policies` | **RLS on**, whatever `rls` says — a policy on a table without RLS would be inert |
| `rls: false`, no policies | RLS off: every role reads and writes every row. An explicit opt-out for a public table |

A write a `WITH CHECK` refuses, or a statement on a table the caller's role has no grant on, throws an `HttpError` carrying Postgres' SQLSTATE `42501` in its `sqlstate`, and the request's transaction rolls back. Left to reach the client it answers as PostgREST does: `403 permission_denied` to a signed-in caller, `401 permission_denied` to an anonymous one, for whom signing in may be what is missing. The answer names nothing of the schema — the policy, the table and the row stay in the log. On the service role — `$asService()`, or every request of an app that says `db: { requests: "service" }` — nobody's rights were judged: a `42501` there is the app's own grants, and passes through as Postgres' error, a `500 internal_error`. When the client should know why, check what the caller may write before writing it and say so with your own `Forbidden` and code.

## The `policy()` builder

`policy(name)` starts a builder whose methods chain; the name is unique per table.

| Method | Default | Notes |
|---|---|---|
| `.for(command)` | `"all"` | `"select"`, `"insert"`, `"update"`, `"delete"` or `"all"` |
| `.to(...roles)` | `"authenticated"` | `"anon"`, `"authenticated"`, `"service_role"`; no arguments is `PUBLIC` |
| `.using(expr)` | none | `USING (…)` — which existing rows a command may see or touch |
| `.withCheck(expr)` | none | `WITH CHECK (…)` — which written rows are allowed |
| `.memberOf(table, fk, opts?)` | — | the membership subquery below; it **is** the `using`, so it refuses to combine with one |
| `.as(mode)` | `"permissive"` | `"restrictive"` ANDs the policy on top of the permissive ones |
| `.withoutIndexes()` | — | the columns it reads get no index of their own from it |

`using` and `withCheck` take the typed expression — built from the callback's `p` — or a raw SQL string for what the expressions cannot say. Prefer the typed form: `p.col(…)` is checked against this table's columns as you write it, a string only by Postgres when the policy is created.

| Expression | SQL |
|---|---|
| `p.col("owner")` | this table's column |
| `p.auth.uid()` | `(select auth.uid())` — evaluated once per statement, not per row |
| `.eq(x)`, `.neq(x)`, `.gt(x)`, `.gte(x)`, `.lt(x)`, `.lte(x)` | comparisons; `x` is another expression or a plain value |
| `.isNull()` / `.isNull(true)` | `IS NULL` / `IS NOT NULL` |
| `.and(…)`, `.or(…)`, `.not()`, `p.and(…)`, `p.or(…)`, `p.not(…)` | combinations |
| `p.lit(v)` | a value, said explicitly |
| `p.existsIn(table, (row) => …)` | a correlated `EXISTS` subquery into another table |

A plain value on the right of `.eq()` is a literal, never a column: `.eq("owner")` compares with the string `"owner"`. A column is always `p.col("owner")`.

Every column a policy reads gets an index unless one already leads with it (`<table>_<column>_idx`), because it is read on every query of the table. `.withoutIndexes()` opts a policy out of that.

### Per-command policies

Split the policies when reads and writes have different rules — anyone signed in reads, only the owner changes:

```ts
import { boolean, defineTable, ownedByUser, policy, text, uuid } from "palbase/backend";

export const notes = defineTable("notes", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    owner: ownedByUser(),
    body: text(),
    pinned: boolean().default(false),
  },
  policies: (p) => [
    policy("notes_read").for("select").using("true"),
    policy("notes_insert_own").for("insert").withCheck(p.col("owner").eq(p.auth.uid())),
    policy("notes_update_own").for("update").using(p.col("owner").eq(p.auth.uid())).withCheck(p.col("owner").eq(p.auth.uid())),
    policy("notes_delete_own").for("delete").using(p.col("owner").eq(p.auth.uid())),
  ],
});
```

Permissive policies for the same command **OR** together — a row is visible if any of them allows it. Use `.as("restrictive")` for a condition that must **also** hold whatever else is declared, such as a tenant guard.

## Membership: the pattern that does not recurse

Anything shared — a channel, a project, an organisation — has the same shape: a **membership table** joining users to the thing, and a policy on the thing asking whether the caller is in it. Written by hand the two policies point at each other, and Postgres refuses the pair when it is queried:

```text
ERROR: infinite recursion detected in policy for relation "channel_members"
```

The way out is to make it asymmetric. The membership table is protected by the caller's identity **alone** — it never looks at the thing it points to — and every other table asks it:

```ts
import { defineSchema, defineTable, policy, text, userRef, uuid } from "palbase/backend";

export const channels = defineTable("channels", {
  columns: { id: uuid().primaryKey().defaultRandom(), name: text() },
  // 2. The thing asks the membership table; memberOf() writes the subquery.
  policies: () => [policy("channels_member_read").for("select").memberOf("channel_members", "channel_id")],
});

export const channel_members = defineTable("channel_members", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    channel_id: uuid().references(() => channels.id, { onDelete: "cascade" }),
    user_id: userRef({ onDelete: "cascade" }),
  },
  // 1. The membership table names auth.uid() and nothing else, so evaluating
  //    it never reaches another policy.
  policies: (p) => [policy("members_own").for("select").using(p.col("user_id").eq(p.auth.uid()))],
});

export const messages = defineTable("messages", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    channel_id: uuid().references(() => channels.id, { onDelete: "cascade" }),
    author: userRef({ onDelete: "set null" }).nullable(),
    body: text(),
  },
  // 3. Anything hanging off the thing asks the membership table too, typed:
  //    `m` is channel_members' columns, `p` this table's.
  policies: (p) => [
    policy("messages_member_read")
      .for("select")
      .using(p.existsIn(channel_members, (m) => m.col("channel_id").eq(p.col("channel_id")).and(m.col("user_id").eq(p.auth.uid())))),
    policy("messages_member_write")
      .for("insert")
      .withCheck(
        p.col("author").eq(p.auth.uid()).and(
          p.existsIn(channel_members, (m) => m.col("channel_id").eq(p.col("channel_id")).and(m.col("user_id").eq(p.auth.uid()))),
        ),
      ),
  ],
});

export default defineSchema("public", { tables: [channels, channel_members, messages] });
```

`memberOf(membershipTable, foreignKey)` compiles to:

```sql
"id" IN (SELECT "channel_id" FROM "channel_members" WHERE "user_id" = (select auth.uid()))
```

`{ column }` is the column of this table the subquery matches (`id` by default — pass the foreign key's name on a child table), and `{ userColumn }` the membership table's user column when it is not `user_id`. `p.existsIn` is the typed form of the same idea: the subquery's columns come from the membership table's own declaration, so a misspelt one is a compile error too.

> **Note:** A policy `.for("select")` decides only what is visible. Writes need their own — `.for("insert")` with a `withCheck`, as `messages` has — or `.for("all")` when one condition governs both.

## RLS guards reads, not foreign-key checks

A `SELECT`, `UPDATE` or `DELETE` only ever reaches rows the caller may see. A **foreign-key check is not filtered**: when a row's foreign key points at a parent, Postgres validates that the parent exists whoever owns it. Without a policy that says otherwise, a caller can attach a child row to a parent it cannot read. Nothing leaks — it still cannot read the parent — but say what you mean, in the child's `withCheck`:

```ts
import { defineTable, ownedByUser, policy, text, uuid } from "palbase/backend";

export const orders = defineTable("orders", {
  columns: { id: uuid().primaryKey().defaultRandom(), owner: ownedByUser(), note: text().nullable() },
  policies: (p) => [policy("orders_own").for("all").using(p.col("owner").eq(p.auth.uid())).withCheck(p.col("owner").eq(p.auth.uid()))],
});

export const order_items = defineTable("order_items", {
  columns: { id: uuid().primaryKey().defaultRandom(), order_id: uuid().references(() => orders.id, { onDelete: "cascade" }), sku: text() },
  // Readable and writable only under an order the caller owns.
  policies: (p) => [
    policy("order_items_via_order")
      .for("all")
      .using(p.existsIn(orders, (o) => o.col("id").eq(p.col("order_id")).and(o.col("owner").eq(p.auth.uid()))))
      .withCheck(p.existsIn(orders, (o) => o.col("id").eq(p.col("order_id")).and(o.col("owner").eq(p.auth.uid())))),
  ],
});
```

The `existsIn` runs as the caller, so the `orders` it sees are already the caller's own — the subquery asks the question the foreign-key check does not.

## `$asService()`: past RLS

Some code legitimately reaches across users — an admin route, a cleanup, a count over everyone. `Database.$asService()` returns the same typed surface running as `service_role`, which bypasses RLS:

```ts
import { Database } from "palbase/backend";

// The default: only the caller's own rows.
const mine = await Database.public.todos.findMany();

// The service role: every user's rows. Explicit, and greppable in review.
const all = await Database.$asService().public.todos.findMany();
```

- **It is a second transaction, on a second connection**, opened by its first use — the role is bound once, when a transaction begins. The two commit as two, the caller's first.
- **It keeps the caller's claims**, so `auth.uid()` still resolves in a trigger or a default inside it. It changes what may be touched, not who is asking.
- **It does not nest**: the surface it returns has no `$asService()` of its own.
- **Inside `$asService().$atomic(cb)`, use the handle `cb` is given** — the shared `Database` is refused there, so a helper written against the caller's RLS cannot quietly read everyone's rows.

Inside it your own code is the only authorisation left, so check the caller's right first and call it at the point of use. An app whose every table is the service role's — an operator's tool deciding in its routes who sees what — says so once, `db: { schemas, requests: "service" }`, and every request runs as `service_role`.

## Changing a policy

Edit `policies` in the schema file, commit and push to the machine's branch. The release's migration step changes the policy in place. Postgres keeps one set of policies per table, so a changed policy holds for **both** versions from `start` on — the version still serving is held to it too. A policy that reads a column (or another table) the same release renames is refused: rename in one release, change the policy in the next. See [Schema changes](/docs/backend/migrations).

## Related

- [Schema](/docs/backend/schema) — `defineTable`, `ownedByUser()`, and where policies sit
- [Database](/docs/backend/database) — the request's transaction, `$query`, and `$asService()`
- [Authentication](/docs/backend/authentication) — who the caller is, and routes with `auth: false`
- [Schema changes](/docs/backend/migrations) — how a release applies a policy change



<!-- ===== backend/encryption ===== -->

# Field Encryption

A column marked `.encrypted()` is sealed by your app before it is written and opened when it is read, with the project's own field keys. The database, its backups and a dump of it hold ciphertext; your code reads and writes the plain value, as with any other column. It is on every plan, at no cost.

It protects a field from whoever reaches the database without the app: a leaked dump or backup, a stolen database password, a read-only SQL injection. It does not protect it from your app itself — the app holds the keys while it runs.

## Quick example

```ts
// db/public.ts
import { defineSchema, defineTable, text, uuid } from "palbase/backend";

export const patients = defineTable("patients", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    name: text(),
    // Found by equality, and kept unique: { lookup: true } keeps a keyed hash beside it.
    national_id: text().encrypted({ lookup: true }).unique(),
    // Read and written whole, never searched.
    notes: text().encrypted().nullable(),
  },
});

export default defineSchema("public", { tables: [patients] });
```

```ts
// src/modules/patients/patients.service.ts
import { Database, Injectable } from "palbase/backend";

@Injectable()
export class PatientsService {
  async admit(name: string, nationalId: string) {
    return Database.public.patients.insert({ name, national_id: nationalId, notes: "allergy: penicillin" });
  }

  async byNationalId(nationalId: string) {
    return Database.public.patients.findUnique({ where: { national_id: nationalId } });
  }
}
```

What the database holds:

```text
 name |                       national_id                       |       national_id_lookup
------+---------------------------------------------------------+------------------------------
 Ayşe | pbe1.k1.MzMzMzMzMzMzMzMztbNidvqiRRyDjN1Zkdx-38ei7bu3V…   | pbl1.cypF9YEDilHu_qYJy15Snch…
```

## What an encrypted column is asked

The database holds the column's ciphertext, not its value, so it can compare nothing there. An encrypted column takes text; what a query may ask of it is fixed by its type:

| | `.encrypted()` | `.encrypted({ lookup: true })` |
|---|---|---|
| Read and write the value | yes | yes |
| `isNull`, `null` | yes | yes |
| Equality: `{ col: v }`, `in`, `neq`, `findUnique` | — | yes, through the lookup |
| `.unique()`, `onConflict` | — | yes, kept on the lookup |
| `orderBy`, `gt`/`lt`, `contains`/`startsWith`, `search`, `min`/`max`, `groupBy`, an index | — | — |

What is refused is a compile error in a typed query, and an error naming the column when the query is built otherwise. The lookup is a keyed hash (HMAC-SHA256) of the value, kept in `<column>_lookup`, which your code never names; equal values have equal lookups, so a lookup tells which rows hold the same value — keep it off a column whose few possible values that would give away.

An encrypted column is not a default, a primary key, a foreign key, a generated column or a search column, and has no codec: `defineTable` refuses each, naming the column.

## Keys

Each environment has its own field keys, kept by the platform's secrets module and derived from the environment's data key, which the platform's key-encryption key (Azure Key Vault) wraps. Your app reads them with its secret key when it starts and every minute after; a schema without an encrypted column never reads them. The secrets audit trail (`palbase secrets:audit`) has each app key's first read in the hour, and every download by a developer.

A value is bound to its column — `table.column`, or `schema.table.column` outside public: moved to another column, or into another environment, it does not open, and a value changed in the database is refused when read, as is a plain value where an encrypted one belongs.

## Encrypting a column that holds rows

Add `.encrypted()` to the column and deploy. The release migrates beside the version that serves, as every [schema change](/docs/backend/migrations) does:

- While both versions run, the column keeps the form the old version reads — plain — and the new version reads either form.
- Once the old version is gone, the release seals every row, in batches, and from then on a plain value in the column is refused.

Taking `.encrypted()` off goes the same way the other way round. An encrypted column, or its table, is not renamed while it holds rows: its values are bound to its name.

## Rotating the keys

```bash
palbase fields:rotate
```

The new key comes into force five minutes later — every running app has fetched it by then. New values are sealed with it from then on, and a `palbase/backend` app seals the older values again with it in the background. The older keys go on opening what they sealed. An owner or an admin rotates; `palbase fields:list` shows the keys and which is in force.

## In Studio

The database's **Tables** screen shows an encrypted value masked. An owner or an admin of the organization opens one with **Show**: the secrets module opens it — the keys never reach Studio — and records who opened which column in the audit trail. A member sees the mask alone.

## Copying, dumping and leaving

- `palbase db:copy --from production --to staging` copies every encrypted value as `•••`, sealed with the target's keys: one environment's values never land readable in another.
- A dump (`palbase db:dump`) holds ciphertext. The environment's owner downloads the keys that open it — `palbase fields:keys --out keys.json` writes them into a file readable by its owner alone, and the download is in the audit trail. Keep the file as you keep the database's password.

## Without palbase/backend

A server with another way to its database — NestJS with TypeORM or Prisma, plain SQL — seals and opens a column itself with `palbase/server`, in the same format: a column one app writes, the other reads.

```ts
// src/patients/fields.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

/** Awaited at startup: after it, the calls below are synchronous. */
export const fieldsLoaded = palbase.fields.load();

/** What an INSERT writes: the sealed value, and the lookup it is found by. */
export function sealNationalId(value: string) {
  return {
    national_id: palbase.fields.encrypt("patients.national_id", value),
    national_id_lookup: palbase.fields.lookup("patients.national_id", value),
  };
}

export const nationalIdLookup = (value: string) => palbase.fields.lookup("patients.national_id", value);
export const openNationalId = (sealed: string) => palbase.fields.decrypt("patients.national_id", sealed);
```

```ts
// src/patients/patients.repository.ts
import { nationalIdLookup, openNationalId, sealNationalId } from "./fields";

/** Your Postgres client (pg's Pool, postgres.js), down to the one call used here. */
export interface Db {
  query(text: string, values: unknown[]): Promise<{ rows: { national_id: string }[] }>;
}

export async function admit(db: Db, id: string, name: string, nationalId: string): Promise<void> {
  const sealed = sealNationalId(nationalId);
  await db.query("INSERT INTO patients (id, name, national_id, national_id_lookup) VALUES ($1, $2, $3, $4)", [id, name, sealed.national_id, sealed.national_id_lookup]);
}

export async function nationalIdOf(db: Db, wanted: string): Promise<string | undefined> {
  const { rows } = await db.query("SELECT national_id FROM patients WHERE national_id_lookup = $1", [nationalIdLookup(wanted)]);
  return rows[0] && openNationalId(rows[0].national_id);
}
```

The first argument is the column's address. A TypeORM column transformer is the same two calls:

<!-- fragment: a property shown out of its TypeORM entity -->

```ts
@Column({ transformer: { to: (v: string) => palbase.fields.encrypt("patients.national_id", v), from: (v: string) => palbase.fields.decrypt("patients.national_id", v) } })
national_id!: string;
```

`palbase.fields` needs Node's crypto: Node, Bun or Deno.

## Tests

`palbase/server/testing`'s `testFields()` gives keys of no project, held in the test's process. Pass them where the project's would go — `createRequestDatabase(sql, identity, { schemas, fields })` from `palbase/backend/engine`, or palgres' `createDatabase({ …, fields })` — for a test that runs an encrypted schema against a database of its own:

```ts
// test/fields.test.ts
import { expect, it } from "bun:test";
import { testFields } from "palbase/server/testing";

it("opens what it seals, at the same column alone", async () => {
  const fields = await testFields();
  const sealed = fields.encrypt("patients.national_id", "10000000146");
  expect(sealed.startsWith("pbe1.")).toBe(true);
  expect(fields.decrypt("patients.national_id", sealed)).toBe("10000000146");
  expect(() => fields.decrypt("patients.phone", sealed)).toThrow();
});
```

`palbase/backend/test`'s in-memory database keeps an encrypted column as a plain one, and does not refuse what the engine refuses on it.



<!-- ===== backend/request-encryption ===== -->

# Encrypted Requests

A field your route marks `encrypted()` is sealed by the app before the request leaves the device, and a field your route answers with `encrypt()` is opened by the app when the answer arrives. Your handler and the app's code see the value; everything between them — the network, the edge, a proxy, the logs, a debugging proxy, the browser's network panel — sees ciphertext. It is on every plan, at no cost.

It protects a field from whatever sits between the app and your code. It does not protect it from the device that typed it, nor from your backend, which opens it. To keep it sealed in the database too, store it in an [encrypted column](/docs/backend/encryption).

## Quick example

The backend: `tc` (a national ID) is encrypted in the request and in the answer.

```ts
// server/src/patients/patients.controller.ts
import { Body, Controller, encrypt, encrypted, Get, NotFound, Param, Post, z, type Encrypted } from "palbase/backend";

const CreatePatient = z.object({
  name: z.string().min(1).max(200),
  // Sealed by the app; opened before validation, so the handler and the schema see the value.
  tc: encrypted(z.string().regex(/^\d{11}$/)),
});
type CreatePatient = z.infer<typeof CreatePatient>;

interface Patient {
  id: string;
  name: string;
  tc: string;
}

@Controller("/patients")
export class PatientsController {
  private readonly patients = new Map<string, Patient>();

  @Post("")
  create(@Body(CreatePatient) body: CreatePatient): { id: string; name: string; tc: Encrypted<string> } {
    const patient = { id: crypto.randomUUID(), name: body.name, tc: body.tc };
    this.patients.set(patient.id, patient);
    // Sealed with the request's own key: only the app that asked opens it.
    return { id: patient.id, name: patient.name, tc: encrypt(patient.tc) };
  }

  @Get("/:id")
  get(@Param("id") id: string): { id: string; name: string; tc: Encrypted<string> } {
    const patient = this.patients.get(id);
    if (!patient) throw new NotFound("no such patient");
    return { id: patient.id, name: patient.name, tc: encrypt(patient.tc) };
  }
}
```

Once it is deployed, `palbase apps:sync` writes the app's client with the fields marked, and the app's calls are what they would be without them:

<!-- fragment: the app's module is the one palbase apps:sync writes for your project -->
```ts
// src/patients.ts
import { pb } from "../palbase/clinic-web";

const patient = await pb.backend.patients.create({ name: "Ada", tc: "10000000146" });
console.log(patient.tc); // "10000000146"
```

What went over the wire:

```text
POST /patients
Palbase-Encryption: 1.t1.gZlVWWADouVFMPA7e26mzk8OCPWBYEEnrr9VqRsqSgA.z-X3bStZx8D0K24F90qhbcbUTIIHDxZYWwnMIeFjZWcMqHk5nHmy7ZYKGyb8Idvo
{"name":"Ada","tc":"pbt1.fCnMiPfNbStaAugZD5anhbAszYy170oluQ_30omSb7lSOGzhJACqpVg"}

200
{"id":"a71f381e-b849-4ccd-9e0d-224a1fc80f2c","name":"Ada","tc":"pbt1.yrbQ_0Qhe_p0R7HXOgHgkXJKaeniFL8N9Jd1xNmZ50C_ckFf5tCPF7o"}
```

Each request has a key of its own, sealed to the project's key in use and bound to the project, the method, the route and its path's values; each field is bound to its place. A value moved to another field, a request replayed against another route or another record, does not open, and the backend answers 400.

## Marking a field

**In a request**, `encrypted(schema)` marks a field of the body or of the query, wherever it sits in the body: a nested object's field, every item of an array (`items: z.array(z.object({ tc: encrypted(z.string()) }))`), an optional field. A query's field is one of the query's own names. A path parameter or a header is not marked: it is part of the address the request is routed by.

**In an answer**, the handler returns the value through `encrypt(value)`, typed `Encrypted<T>`. The build reads the route's return type and writes the mark into the contract, as it writes every other answer's type: `{ tc: Encrypted<string> }` is a `string` the app opens. An answer the route declares as a named schema holds no mark — the build refuses it, naming the route — and a streamed answer and an upload carry no encrypted field.

A request that comes without its key to a route that marks its request is refused before the handler runs. A route that marks only its answer runs its handler and is then refused, since the answer cannot be sealed: keep such a route free of side effects, or mark a field of its request too.

## In the apps

The web, iOS and Android clients `palbase apps:sync` writes seal and open the marked fields themselves. The first call that carries one fetches the project's list of keys with the app's publishable key, and checks that the project signed it with the signing key `apps:sync` wrote into the app, and that it answers this call's fresh nonce: a list that does not verify is not sealed to, and the call fails with `encryption_keys_unverified` before anything is sent. A marked field that comes back plain fails with `field_not_encrypted`.

The [iOS](/docs/ios/debug-console) and [Android](/docs/android/debug-console) debug consoles record a backend call as it went: an encrypted field is shown sealed, and **Reveal** beside it shows its value. Nothing is recorded while the console is off.

## Keys

Each project has its own keys, and apps seal to the newest. An owner or an admin of the organization lists and rotates them:

```bash
palbase transit:list                      # the keys, the one in use, who made and retired each
palbase transit:rotate                    # a new key, in use at once; the older ones still open what is sealed to them
palbase transit:rotate --retire-previous  # a new key, and every older one refused from now on
palbase transit:retire t1                 # refuse one older key
```

A key thought exposed is rotated with `--retire-previous`. A request sealed to a retired key is refused at once, before it reaches your backend (which also refuses it on its own once it next fetches the keys, within a minute), and an app that sealed to it is told so: it fetches the list again and sends the call once more, sealed to the new key — the user sees nothing. An app fetches the list again every hour in any case. The secrets audit trail (`palbase secrets:audit`) has every rotation and retirement.

## Errors

A request the format refuses is answered `400`, with its code in `error`:

| Code | When | `data` |
|---|---|---|
| `encryption_required` | A marked field came plain, or the request has no `Palbase-Encryption` header. | `field`, `current` |
| `encryption_unopenable` | The request's key or a field does not open: changed, moved from another field, sealed for another project, route or record. | `field` |
| `encryption_key_retired` | The request is sealed to a key the project retired. The app's client fetches the list again and sends once more. | `current` |
| `encryption_key_unknown` | The request is sealed to a key the project has not made. The same. | `current` |

## Trying a route

curl and Postman send the field plain, and are refused. `palbase machines:call` calls a route as the app does — its marked fields sealed to the key in use, its answer's opened — and prints the answer:

```bash
palbase machines:call backend POST /patients --data '{"name":"Ada","tc":"10000000146"}'
```

Studio's **Try it** on a machine's endpoint seals and opens them the same way.

## Without palbase/backend

A server built another way — NestJS, Express, Hono, a route handler — opens a request and seals its answer with `palbase/server`'s `transit`, in the same format. Its contract marks the fields `x-palbase-encrypted: true`; served by its app (a machine made with `--openapi-path`), it is what `palbase apps:sync` writes the apps' clients from.

```ts
// src/transit.ts
import { createServer } from "palbase/server";

export const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

/** Awaited at startup: the project's keys, fetched again every minute and when a request names one not held. */
export const transitLoaded = palbase.transit.load();
```

```ts
// src/patients.ts
import { TransitRefusal } from "palbase/server";
import { palbase } from "./transit";

const patients = new Map<string, { id: string; name: string; tc: string }>();

/** POST /patients and GET /patients/{id}, as a fetch handler (Hono, Bun.serve, a route handler) takes them. */
export async function handle(request: Request): Promise<Response> {
  const key = request.headers.get("palbase-encryption");
  const id = new URL(request.url).pathname.split("/")[2];
  try {
    if (request.method === "POST") {
      // The route as the contract writes it: a key sealed for another route does not open here.
      const req = await palbase.transit.request({ header: key, method: "POST", path: "/patients" });
      const input = (await req.open(await request.json(), "/body", ["/body/tc"])) as { name: string; tc: string };
      const patient = { id: crypto.randomUUID(), name: input.name, tc: input.tc };
      patients.set(patient.id, patient);
      return Response.json(await req.seal(patient, ["/response/tc"]));
    }
    // A path's values are part of what the key is sealed for, in order.
    const req = await palbase.transit.request({ header: key, method: "GET", path: "/patients/{id}", params: [id ?? ""] });
    const patient = patients.get(id ?? "");
    if (!patient) return Response.json({ error: "not_found" }, { status: 404 });
    return Response.json(await req.seal(patient, ["/response/tc"]));
  } catch (e) {
    // Answered as palbase/backend answers it, so the apps' clients know a retired key when they meet one.
    if (e instanceof TransitRefusal) return Response.json({ error: e.code, error_description: e.message, data: e.data }, { status: e.status });
    throw e;
  }
}
```

In a NestJS controller the same calls go in its methods: the header through `@Headers("palbase-encryption")`, `open()` on the `@Body()`, the answer returned through `seal()`, and an exception filter that answers a `TransitRefusal` as above.



<!-- ===== backend/migrations ===== -->

# Schema changes

There are no migration files. Your [schema files](/docs/backend/schema) are the declaration, and every release of your machine migrates its database to what they say — **beside the version still serving**, so no request waits for a migration and no request of the old version meets a table it cannot read. You change `src/db/public.ts`, commit and push. You run nothing yourself: the platform runs your new image once to **start** the migration, rolls the new version out next to the old one while both read and write the same tables, and runs it again to **complete** once the old one is gone. A change that both versions cannot run through is refused before anything changes, and the version serving keeps serving.

## The workflow at a glance

```bash
# 1. Edit the declaration: add a column, rename one, tighten one.
#    src/db/public.ts
# 2. Regenerate the types, so Database.public.* matches what you wrote.
bun run scripts/palbase-env.ts
# 3. Commit and push to the machine's branch. That push is the release.
git commit -am "notes: pinned, and title is called subject"
git push
```

The machine builds the commit, and because it is given its database with **migrations on** (Studio: the machine's *Database* setting, "runs its migrations"), the release goes:

1. **start** — the new image runs once with `PALBASE_DB_MIGRATE=start` and the database owner's address. Everything the new version needs is added next to what the running version uses. The new version is not rolled out until start succeeds.
2. **rollout** — the new version comes up beside the old one. Both read and write the same tables.
3. **complete** — once the new version has served and no copy of the old one is left, the image runs with `PALBASE_DB_MIGRATE=complete`. Whatever only the old version used is removed; a renamed column takes its new name, a retyped one takes its place.

A version that is abandoned before complete — its start failed, it did not come up, or a newer push took its place — gets **rollback**, which removes what start added and restores what it loosened. Data written meanwhile stays.

A database's migrations are one machine's: a second machine that asks to run them is refused (`409 database_migrated_elsewhere`). Another machine may be given the same database without migrations; it binds to the schema version its own files describe, so it carries the same schema files and is released after the one that migrates.

## The app migrates itself

The migration is not the platform's code. It is Palgres — the same library that serves your queries — inside your own image. `PalbaseFactory.create` reads `PALBASE_DB_MIGRATE`: set, it migrates the database to the `schemas` it was given and exits; unset, it serves.

```ts
// src/main.ts
import { PalbaseFactory } from "palbase/backend";
import { AppModule } from "./app.module";
import schema from "./db/public";

// Serves on $PORT. Run with PALBASE_DB_MIGRATE=start|complete|rollback by a
// release, it migrates the database as its owner (PALBASE_DB_OWNER_URL) and exits.
await PalbaseFactory.create(AppModule, { db: { schemas: [schema] } });
```

```ts
// src/app.module.ts
import { Module } from "palbase/backend";

// The app's modules, listed here as ever: a migration run builds none of them.
@Module({ imports: [] })
export class AppModule {}
```

The schema the engine plans from and the engine that applies it are always the same version, because they are in the same image, and a migration run sees nothing but its own image. The run connects as the database's **owner** (`PALBASE_DB_OWNER_URL`, given to migration runs alone); the version that serves connects as the app's login (`PALBASE_DB_URL`) and cannot alter a table.

How a run exits is all the platform reads of it:

| Exit | What it says | What happens |
|---|---|---|
| `0` | done, or nothing to do | the release goes on: rollout after start, and so on |
| `1` | the migration's own verdict — it is refused, or the rows do not fit it (two rows where a new unique index wants one). Run again, it would end the same | the release stops. What start began is taken back, the version serving stays, and the build says why |
| anything else | it was cut off — the database restarting, a lock not had in the tries it has, the run's node drained, its memory out (`75` when the app says so) | the run is made again, and picks up where it stopped |

A run's lines are in the machine's logs, marked as a migration run's, and its last line is the reason the build shows — see [Builds, Logs & Rollback](/docs/machines/builds). A migration the process dies in picks up where it stopped: each step is recorded when it commits, and copying a large table records its place with every batch. A step has a day, its attempts together — not a measure of the work, only the end of a run that would never end.

Only one migration is open at a time. A push that comes while one is open waits for its complete — or, when the version it belongs to has not rolled out yet, takes its place: that one is rolled back first.

## What start does, so nothing waits

- New tables and columns are added; **indexes are built `CONCURRENTLY`**.
- `CHECK`s and foreign keys are added `NOT VALID`, then validated while writes go on.
- `NOT NULL` is set through a validated `CHECK`.
- A type change adds a second column of the new type that the two versions write through each other.
- Each step takes the locks its statements need, waits at most 500 ms for them, then gives way and tries again — so a request queued behind it never waits longer than that. A writer is never the one sacrificed to break a lock cycle.
- A table is filled in batches that take only rows no writer holds (`SKIP LOCKED`); a write never waits for a batch longer than its commit.

## Adding things

Adding a table, a nullable column, a column with a default, an index, a unique index, a `CHECK` or a foreign key is an ordinary release — declare it and push. Two things to know:

- **A new `NOT NULL` column needs `.default(…)` or `.fillWith(sql)`**: the version still serving inserts rows without it.
- **Constraints apply at start.** A `CHECK`, unique index or foreign key added by a migration holds for every write once start is done — the old version's writes included. A row the old version writes that a new constraint refuses is refused.

## Renaming a column

A diff shown two names for one column cannot tell a rename from a drop and an add — and the second loses every value. Say which it is:

```ts
// src/db/public.ts
import { defineSchema, defineTable, ownedByUser, policy, text, timestamp, uuid } from "palbase/backend";

const notes = defineTable("notes", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    owner: ownedByUser(),
    title: text(),
    created_at: timestamp().defaultNow(),
  },
  policies: (p) => [policy("notes_own").for("all").using(p.col("owner").eq(p.auth.uid())).withCheck(p.col("owner").eq(p.auth.uid()))],
});

export default defineSchema("public", { tables: [notes] });
```

The next release renames `title` and adds `pinned`:

```ts
// src/db/public.ts
import { boolean, defineSchema, defineTable, ownedByUser, policy, text, timestamp, uuid } from "palbase/backend";

const notes = defineTable("notes", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    owner: ownedByUser(),
    subject: text().renamedFrom("title"),
    created_at: timestamp().defaultNow(),
    pinned: boolean().default(false),
  },
  policies: (p) => [policy("notes_own").for("all").using(p.col("owner").eq(p.auth.uid())).withCheck(p.col("owner").eq(p.auth.uid()))],
});

export default defineSchema("public", { tables: [notes] });
```

```ts
// src/notes/notes.service.ts
import { Database, Injectable } from "palbase/backend";

@Injectable()
export class NotesService {
  // The new version writes `subject`; the old one, still serving, writes `title` — the same column.
  create(owner: string, subject: string) {
    return Database.public.notes.insert({ owner, subject });
  }
}
```

```ts
// src/notes/notes.module.ts
import { Module } from "palbase/backend";
import { NotesService } from "./notes.service";

@Module({ providers: [NotesService] })
export class NotesModule {}
```

While both versions run, the table keeps its old names and the new version reads and writes through its version's views, which hold the new names; at complete the column takes its new name. The typed tables work this way already. In the new version's **raw SQL** during that window, name tables bare (`notes`, not `public.notes` — a qualified name reaches the table under its old names), and name an `ON CONFLICT` target by its columns rather than its constraint (a view has none). Tools outside the app — psql, a BI tool — see the table itself: the old names until complete.

Once complete has run, `renamedFrom` is inert — the old name is gone — so delete it whenever you next touch the file.

## Changing a column's type

A type change is planned as a second column of the new type, which both versions write through each other by Postgres' cast both ways (an enum renamed, by its labels); at complete it takes the old column's place. Each version's own writes are cast across, so neither version's values are lost. What both versions cannot run through is refused — see the table below — and for those the way is a new column. A later release's `src/db/public.ts`:

```ts
import { boolean, defineSchema, defineTable, enumType, ownedByUser, policy, text, timestamp, uuid } from "palbase/backend";

const notes = defineTable("notes", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    owner: ownedByUser(),
    subject: text(),
    created_at: timestamp().defaultNow(),
    // `pinned` becomes a three-way visibility. Postgres has no cast from a
    // boolean to an enum, so it is a new column filled from the old one, and
    // `pinned` is ignored until the next release removes it.
    pinned: boolean().default(false).ignored(),
    visibility: enumType("note_visibility", ["normal", "pinned", "hidden"])
      .fillWith("(CASE WHEN pinned THEN 'pinned' ELSE 'normal' END)::public.note_visibility"),
  },
  policies: (p) => [policy("notes_own").for("all").using(p.col("owner").eq(p.auth.uid())).withCheck(p.col("owner").eq(p.auth.uid()))],
});

export default defineSchema("public", { tables: [notes] });
```

## Making a column `NOT NULL`

A nullable column with rows cannot just become `NOT NULL`: some rows are `NULL`, and the version still serving goes on writing `NULL`. `.fillWith(sql)` says what such a row gets — the rows already there and every write of the old version while both run — and the column is made `NOT NULL` only after. In this release's `src/db/public.ts`, `summary` was `text().nullable()` until now:

```ts
import { defineSchema, defineTable, ownedByUser, policy, text, timestamp, uuid } from "palbase/backend";

const notes = defineTable("notes", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    owner: ownedByUser(),
    subject: text(),
    summary: text().fillWith("left(subject, 80)"),
    created_at: timestamp().defaultNow(),
  },
  policies: (p) => [policy("notes_own").for("all").using(p.col("owner").eq(p.auth.uid())).withCheck(p.col("owner").eq(p.auth.uid()))],
});

export default defineSchema("public", { tables: [notes] });
```

The fill is for the rows the new code does not write: the ones already there, and the old version's. The new version's own inserts must give the column — in its `palbase-env.d.ts` it is required, like any `NOT NULL` column without a default — so the release that adds the fill also changes the code that inserts.

`fillWith` is one SQL scalar expression over the row's own columns. A table, function or type it names is schema-qualified (`public.accounts`): it runs with a pinned `search_path`. It reads past RLS, and what it writes is readable by anyone who can read the row. It goes only on a `NOT NULL` column with no default that is not ignored — a constant is a `.default()` — and the value stays after a rollback, so make it one the old version reads correctly.

## Removing a column or a table

The release that drops a column must not be the release that stops reading it: the version still serving reads it until complete. So a column or a table **with data** goes in two releases:

1. Mark it — `.ignored()` on a column, `{ ignored: true }` on a table — and push. Nothing changes in the database; this release's code no longer names it, and the typed tables leave it out of every row and every statement.
2. Remove it from the schema and push. Its data goes at that release's complete.

A dropped or ignored `NOT NULL` column with no default needs one in the release that ignores it — the new version inserts rows without it, and the old version reads that value in them. Palgres does not make such a column nullable for you: the old version would then read it empty, and after a rollback go on doing so.

## Changing data once

A value a column can be worked out from — the rows already there, and each write of the version still serving — is a fill: `.fillWith(sql)`, run in batches beside both versions with nothing held. Every other change of data that is made once — a catalog's rows, data moved into a new shape, a repair — is a [task](/docs/backend/tasks), not part of the migration: it runs on your machine once the release is out, in your own code, and its progress shows in Studio.

```ts
// src/modules/people/split-full-names.task.ts
import { Database, Task, z } from "palbase/backend";

// Picks up only what is still to do: run again, it does nothing twice.
@Task({ name: "split-full-names", payload: z.object({}) })
export class SplitFullNames {
  async run(): Promise<void> {
    await Database.$asService().$query(
      "update people set first_name = split_part(full_name, ' ', 1) where first_name is null and full_name is not null",
    );
  }
}
```

Put it once the release is out, under a key, so a second put is the first one answered:

```sh
palbase machines:tasks:enqueue split-full-names --key split-full-names-1
```

A key holds for a day after the task is over: write the task so a later run finds nothing left to do, as above, rather than counting on the key. A change that is too large for one statement does a share of the rows each run, and puts itself again (`Tasks.enqueue`, with the next key) until none is left.

There is no `backfill(name, sql)` here: a bare `UPDATE` run as part of a release would race the writes of the version still serving, and stay in the schema file for good.

## What is refused, and what to do instead

A refused migration changes nothing, and the version serving keeps serving. The build says what was refused and the way through:

| Change | Instead |
|---|---|
| A column or table with data is removed from the schema | Mark it `.ignored()` / `{ ignored: true }` and release; remove it in the next release |
| A nullable column becomes `NOT NULL` | Give `.fillWith(sql)` |
| A new `NOT NULL` column has no default | `.default(…)` or `.fillWith(sql)` |
| A dropped or ignored `NOT NULL` column has no default | Give it a default in that release |
| The type of a column a `CHECK`, a policy, an expression or partial index, the primary key or another table's foreign key uses | Add a column of the new type with `.fillWith("old::newtype")`, move what uses it, then ignore the old column |
| A type Postgres has no cast to, either way (boolean to an enum, a timestamp to a boolean), or an enum to one whose labels differ | Add a column of the new type with `.fillWith(sql)`, move to it, then ignore the old column — refused on an empty table too |
| The primary key changes | Add a unique constraint |
| An enum loses a value | Add a new enum type and move the column to it |
| An identity column is added to a table with rows | Add a `bigint` column with a default, and fill it |
| A column of a domain with a `CHECK` is added to a table with rows | Add it as the domain's base type with a `CHECK` |
| A column changes type and becomes `NOT NULL` in one release | Change its type in this release, make it `NOT NULL` in the next |
| A raw unit that is a trigger, a rule or a view has no `drop` | Give it one: `raw(name, up, { drop })` |
| A raw index, domain, type or sequence changes under its name | An index: give the new one its own name. A domain, type or sequence: say the change as an `ALTER …` in a unit of its own |
| A policy reads a column (or a table) the same release renames | Rename in this release, change the policy in the next |

## What to know while both versions run

- **Constraints and policies apply at start**, for both versions: Postgres keeps one set of policies per table, and a new constraint holds for every write.
- **A unique the new version drops holds until complete** — the old version's upserts need it — so while both run, the new version cannot write what it forbids. A unique or index changed under its name is built beside the old one, and takes its name at complete.
- **A type change keeps both versions' values.** A value one version wrote is not cast back over when the other updates another column.
- **A stored generated column made plain** is computed for the old version's writes until complete; a rollback leaves it plain.
- **An enum value start added stays after a rollback** — Postgres cannot drop one — and so does a fill.

## Taking over a database Palgres did not make

A database another tool left — Prisma, Drizzle, a team's hand-written SQL — comes over as it is. Palgres writes schema files from it, read only; the address is an environment variable, not an argument, because it holds a password:

```bash
PALGRES_DATABASE_URL='postgresql://…' bun node_modules/palgres/src/cli.ts pull src
# wrote src/db/public.ts
#   column public.orders.user_id may hold a user's id: mark it ownedByUser() or userRef() so user.deleted reaches it
```

What the DSL's builders say is written with them; a default, check or policy they cannot say is written as its SQL. An index the typed form cannot say, and what the database holds besides tables — domains, types, sequences, functions, views, triggers — are raw units in Postgres' own words. The command prints what to look at: columns that may hold a user's id, and what it leaves as it is (a partitioned table, a view over one).

The first release with those files takes the database over. The declared schema is made in a shadow database — the owner has `CREATEDB` for it — and the two are compared the way Postgres writes them. Held as declared, the database becomes version 1 and nothing in it changes; held otherwise, it becomes version 1 as it is, and the ordinary migration to the declared schema does exactly the difference, with the same refusals. A refused take-over writes nothing. Row-level security forced on the owner is turned off — Palgres migrates as the owner, and the app never connects as it — and a database whose own `auth.uid()`, `auth.jwt()` or `auth.role()` reads its caller another way is refused until you rename yours.

## Related

- [Schema](/docs/backend/schema) — the declarations a release migrates to
- [Database](/docs/backend/database) — the typed tables, and raw SQL while a rename is open
- [Row-Level Security](/docs/backend/row-level-security) — policies, which apply at start
- [Builds, Logs & Rollback](/docs/machines/builds) — what a push does, and the migration run's lines
- [Databases](/docs/machines/databases) — giving a machine its database, with migrations on



<!-- ===== backend/storage ===== -->

# Storage

Every project has storage: **buckets** of files, read and written by your backend with the secret key. In a `palbase/backend` app the module is `Palbase.storage`; from any other server it is `createServer({ url, secretKey }).storage` — the same client, generated from the storage contract. A client app never holds the secret key, so it reaches files in two ways only: a **public** bucket's objects, which anyone may read, and **signed URLs** your backend hands out — one to read an object, or one to upload it ([Direct Uploads](/docs/backend/direct-uploads)). An AI chat message holds to the same: a client attaches only a public bucket's file, and a private one is attached by your server ([AI](/docs/backend/ai)).

## Quick example

```ts
// src/modules/avatars/avatars.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class AvatarsService {
  /** Stores the picture as the user's: it goes when they are deleted. */
  async save(userId: string, png: Blob): Promise<string> {
    const path = `${userId}/avatar.png`;
    await Palbase.storage.putObject({
      path: { bucket: "avatars", path },
      query: { owner_id: userId },
      body: png,
      contentType: "image/png",
    });
    return path;
  }

  /** A link that reads the object for ten minutes, by anyone holding it. */
  async link(path: string): Promise<string> {
    const signed = await Palbase.storage.createSignedUrl({ path: { bucket: "avatars" }, body: { path, expires_in: 600 } });
    return signed.data.url;
  }
}
```

## Buckets

A bucket is declared, and declaring it again makes it so. `PUT /storage/buckets/{bucket}` creates the bucket or changes it to what the body says:

| Field | Default | What it says |
|---|---|---|
| `public` | `false` | Anyone may read its objects at `/storage/public/{bucket}/{path}`, with no credential. |
| `file_size_limit` | the platform's, 5 GiB | The largest object it takes, in bytes. |
| `allowed_mime_types` | any | The content types it takes; `image/*` names a family. 64 at most. |
| `variants` | none | The renditions made of every picture put in it (below); 16 at most. |

A bucket's name is a lowercase letter, then lowercase letters, digits and `-`, 2 to 63 characters.

```ts
// src/modules/avatars/buckets.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class BucketsService {
  // A provider's onStart() runs at boot, before the app serves: the bucket
  // is as this code says on every machine that runs it.
  async onStart(): Promise<void> {
    await Palbase.storage.putBucket({
      path: { bucket: "avatars" },
      body: {
        public: true,
        file_size_limit: 5 * 1024 * 1024,
        allowed_mime_types: ["image/*"],
        variants: [
          { name: "thumb", width: 128, height: 128, fit: "cover", format: "webp", quality: 80 },
          { name: "large", width: 1024, height: 0, fit: "inside", format: "jpeg", quality: 0 },
        ],
      },
    });
  }
}
```

The write carries an `Idempotency-Key` the client makes, so its own retry never declares twice; a declaration a renderer cannot honour is refused here (`400`), not at the first upload. `GET /storage/buckets` lists the project's buckets, `GET /storage/buckets/{bucket}` reads one, and `DELETE /storage/buckets/{bucket}` deletes an **empty** bucket — one that still holds objects is refused with `409 bucket_not_empty`, so no file goes by surprise.

Studio's **Storage › Buckets** screen lists the buckets, deletes them, and uploads and deletes files in one.

## Writing an object

`putObject` stores its body at the path, replacing what is there.

```ts
// src/modules/reports/reports.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class ReportsService {
  async publish(month: string, csv: string) {
    const written = await Palbase.storage.putObject({
      path: { bucket: "reports", path: `monthly/${month}.csv` },
      headers: { "If-None-Match": "*" }, // create only: an object already there is 412
      body: csv,
      contentType: "text/csv",
    });
    return written.data; // the StorageObject: path, size, content_type, checksum_sha256 …
  }
}
```

- **Its type is sniffed from the bytes**, not taken from `contentType`, which is used only when the bytes cannot tell (HEIC, say). The bucket's ceiling and its types are enforced while the bytes stream in (`413 payload_too_large`, `415 unsupported_media_type`).
- **`owner_id`** makes the object a user's: it is deleted when they are.
- **`If-None-Match: *`** creates only (`412 object_exists`); **`X-Checksum-Sha256`** (hex) refuses bytes that do not match (`400 checksum_mismatch`), keeping nothing.
- **A picture** gets its `width`, `height`, a `thumbhash` placeholder and the bucket's renditions, made inside the upload — the object answered is complete.
- **It emits `file.uploaded`** to the project's webhook ([Webhooks](/docs/server/webhooks)).

A route of a `palbase/backend` app reads its body as JSON, a megabyte by default, so a client's file does not come through your backend to get here: the client PUTs it straight to storage at a URL your backend signed. See [Direct Uploads](/docs/backend/direct-uploads).

### What an object looks like

| Field | What it is |
|---|---|
| `bucket`, `path` | Where it is. |
| `size`, `content_type` | Its bytes and the type they were sniffed as. |
| `checksum_sha256` | The bytes' sha256, hex. |
| `owner_id` | The user it belongs to, if any. |
| `width`, `height`, `thumbhash` | A picture's dimensions and placeholder. |
| `variants` | Its renditions, by name: each with its `content_type` and `size`. |
| `created_at`, `updated_at` | When an object was first stored at the path, and when its bytes or path last changed. |

## Reading an object

`getObject` answers the bytes as the `Response` itself, so a large file is never read into memory unless you do so:

```ts
// src/modules/reports/download.service.ts
import { Injectable, NotFound, Palbase } from "palbase/backend";

@Injectable()
export class DownloadService {
  async text(path: string): Promise<string> {
    const reply = await Palbase.storage.getObject({ path: { bucket: "reports", path } });
    if (reply.status === 304 || !reply.data) throw new NotFound(`no report at ${path}`);
    return reply.data.text();
  }

  async thumbnail(path: string): Promise<ArrayBuffer> {
    const reply = await Palbase.storage.getObject({ path: { bucket: "avatars", path }, query: { variant: "thumb" } });
    if (reply.status === 304 || !reply.data) throw new NotFound(`no avatar at ${path}`);
    return reply.data.arrayBuffer();
  }
}
```

A missing object is a `404` refusal (a `PalbaseError`). `Range` (one byte range, answered `206`) and `If-None-Match` (answered `304`, with no body) are honoured, and `headObject` reads the headers without the bytes. A read with the secret key names the object's owner in `X-Owner-Id`; a public or signed URL never does. What is served is made inert — `nosniff`, a sandboxing CSP, and a download for any type a browser does not render safely — and every read counts toward the project's egress.

## Three ways a client reads a file

| URL | Who may read it | Made by |
|---|---|---|
| `https://<ref>.palbase.studio/storage/public/{bucket}/{path}` | Anyone, with no credential — an `<img src>`, a CDN. A private bucket's object is `403`. | Nothing to make: the bucket is `public`. |
| `https://<ref>.palbase.studio/storage/signed/{bucket}/{path}?…&sig=…` | Anyone holding the URL, until it expires (7 days at most). | `createSignedUrl` |
| `GET /storage/buckets/{bucket}/objects/{path}` | Your backend, with the secret key. | — |

The `{path}` in a URL is **one** percent-encoded segment: `a/b.jpg` is `a%2Fb.jpg`. `?variant=thumb` reads a rendition on all three.

```ts
// src/modules/avatars/urls.ts
const PROJECT = "https://<ref>.palbase.studio";

/** A public bucket's object, as an <img src> takes it. */
export function publicUrl(bucket: string, path: string, variant?: string): string {
  // The path is ONE segment: a/b.jpg goes as a%2Fb.jpg.
  const [b, p] = [encodeURIComponent(bucket), encodeURIComponent(path)];
  const url = new URL(`/storage/public/${b}/${p}`, PROJECT);
  if (variant) url.searchParams.set("variant", variant);
  return url.toString();
}
```

A signed URL is absolute, at the project's own address, and opens nothing at another project's. Every parameter of it is covered by its signature: a URL changed by one character, expired, or naming another object is `403`. The object must exist when the URL is signed.

## Image renditions

A bucket's `variants` are made from every picture put in it, inside the upload, and kept beside the original:

| Field | Values | Default |
|---|---|---|
| `name` | a lowercase letter, then lowercase letters, digits and `_` (32 at most) | — |
| `width`, `height` | pixels; `0` derives one from the other and the picture's aspect | — |
| `fit` | `cover` fills the box and crops; `contain` and `inside` keep the whole picture inside it (`inside` never enlarges) | `contain` |
| `format` | `jpeg`, `png`, `webp` | `jpeg` |
| `quality` | 1 to 100 for jpeg and webp; `0` is the format's default | `0` |

A rendition is read by its name (`?variant=`), and served whole — a byte range applies to the original only. A copy carries the original's renditions with it.

## Listing, copying, moving, deleting

```ts
// src/modules/reports/archive.service.ts
import { Injectable, Palbase } from "palbase/backend";
import { pages } from "palbase/server";

@Injectable()
export class ArchiveService {
  /** Every report of a year, newest first, a page at a time. */
  async year(year: string): Promise<string[]> {
    const paths: string[] = [];
    for await (const page of pages((cursor) =>
      Palbase.storage.listObjects({ path: { bucket: "reports" }, query: { prefix: `monthly/${year}-`, limit: 1000, cursor } }),
    )) {
      paths.push(...page.objects.map((o) => o.path));
    }
    return paths;
  }

  async retire(path: string): Promise<void> {
    await Palbase.storage.moveObject({ path: { bucket: "reports" }, body: { from: path, to: `retired/${path}` } });
  }

  async duplicate(path: string, to: string): Promise<void> {
    await Palbase.storage.copyObject({ path: { bucket: "reports" }, body: { from: path, to, overwrite: true } });
  }

  async remove(path: string): Promise<void> {
    await Palbase.storage.deleteObject({ path: { bucket: "reports", path } });
  }
}
```

- **A move** gives the object a new path and copies no byte; **a copy** writes a new object with the original's bytes and renditions. Either refuses an object already at `to` (`409 object_exists`) unless `overwrite`.
- **A delete** removes the object and its renditions; the bytes are swept from the store after.
- They emit `file.moved`, `file.uploaded` and `file.deleted`.

## Reacting to storage events

Every write emits an event — `file.uploaded`, `file.deleted`, `file.moved` — with `{ bucket, path, size, content_type, owner_id }`. A `palbase/backend` app handles them with `@On("file.uploaded")` ([Event Hooks](/docs/backend/hooks)); any other server verifies the delivery with `palbase/server` ([Webhooks](/docs/server/webhooks)).

## The `Storage` service

A backend reaches a bucket with `Storage`: `Storage.buckets.<name>` for a bucket the project holds (its renditions in the type), `Storage.bucket(name)` for a name made while it runs. Each call answers `{ data, error, status }` and never throws for the platform's sake: a refusal is its `error` (`{ code, message }`), and a platform that could not be reached is `status: 0`.

| Call | What it does |
|---|---|
| `upload(path, file, { contentType?, upsert? })` | Writes the object. Without `upsert` it only creates: an object already there is `409 already_exists`. |
| `download(path)` | The object's bytes, as a `Blob` |
| `getPublicUrl(path, { variant? })` | Its URL at the project's address — a public bucket's objects are read there by anyone; no call is made |
| `createSignedUrl(path, { expiresIn })` | A URL that reads it until it expires: `"90s"`, `"15m"`, `"1h"`, `"7d"`, a week at most |
| `list(prefix?, { limit?, offset? })` | Its objects whose path starts with `prefix`, newest first (100 when no `limit`) |
| `remove(paths)` | Deletes each, in order; the first refusal ends it |
| `move(from, to)`, `copy(from, to)` | Within the bucket |

```ts
// palbase/palbase-env.d.ts
declare module "palbase/backend/stack" {
  interface Buckets {
    avatars: { variants: "thumb" | "card" };
  }
}

export {};
```

```ts
// src/modules/avatars/avatar-urls.service.ts
import { Injectable, Storage } from "palbase/backend";

@Injectable()
export class AvatarUrls {
  async save(userId: string, png: Blob): Promise<{ full: string; thumb: string } | null> {
    const path = `${userId}/avatar.png`;
    const { error } = await Storage.buckets.avatars.upload(path, png, { contentType: "image/png", upsert: true });
    if (error) return null;
    return { full: Storage.buckets.avatars.getPublicUrl(path), thumb: Storage.buckets.avatars.getPublicUrl(path, { variant: "thumb" }) };
  }
}
```

## From the CLI

```sh
palbase storage:buckets:set avatars --public --max-size 5MB --types image/*
palbase storage:buckets:list
palbase storage:cp ./avatar.png avatars:users/42/avatar.png   # up; bucket:path names an object
palbase storage:cp avatars:users/42 ./backup -r                # down, every object under the prefix
palbase storage:ls avatars:users/
palbase storage:url documents:invoices/7.pdf --expires 600      # a signed download URL
palbase storage:rm avatars:tmp/ -r
```

What `storage:buckets:set` is not given stays as it was; a new bucket is private, takes any type and has no renditions until `--variants-file` gives them. `storage:buckets:delete` removes an empty bucket only. See the [CLI reference](/docs/cli/reference#storage).


- [Direct Uploads](/docs/backend/direct-uploads) — signed upload URLs, and the client's `PUT`
- [Web Uploads](/docs/web/uploads) — the browser's side of an upload URL
- [Server SDK Overview](/docs/server/overview) — calls, refusals, retries and paging
- [Event Hooks](/docs/backend/hooks) — `@On("file.uploaded")` in your backend



<!-- ===== backend/direct-uploads ===== -->

# Direct Uploads

A file a user uploads goes from their device **straight to storage**, never through your backend. Your backend decides what may be uploaded — which bucket and path, how large, of which types, belonging to whom — in one of two ways:

- **A signed upload URL.** Your backend signs a URL that grants exactly that, and the client `PUT`s the bytes to it. The signature is the credential: the client needs no key, and the URL opens one object, once its conditions hold, until it expires. This page's quick example.
- **An upload route.** A route declared with `@Upload` takes the file in the client's call: storage asks the route where the file goes before it writes a byte, and runs the route's handler once the file is stored. See [Upload routes](#upload-routes).

## Quick example

```ts
// src/modules/avatars/dto.ts
import { z } from "palbase/backend";

export const UploadRequest = z.object({ contentType: z.enum(["image/png", "image/jpeg", "image/webp"]) });
export type UploadRequest = z.infer<typeof UploadRequest>;

export interface UploadGrant {
  url: string;
  expiresAt: string;
  path: string;
}
```

```ts
// src/modules/avatars/avatars.controller.ts
import { Body, Controller, Palbase, Post, User, type UserT } from "palbase/backend";
import { UploadRequest, type UploadGrant } from "./dto";

@Controller("/avatars")
export class AvatarsController {
  // The user asks; the backend decides the path, the ceiling and the owner.
  @Post("/upload-url", { rateLimit: { max: 10, window: 60 } })
  async uploadUrl(@Body(UploadRequest) body: UploadRequest, @User() user: UserT): Promise<UploadGrant> {
    const ext = body.contentType.split("/")[1];
    const path = `${user.id}/avatar-${Date.now()}.${ext}`;
    const signed = await Palbase.storage.createUploadUrl({
      path: { bucket: "avatars" },
      body: { path, expires_in: 300, max_bytes: 2 * 1024 * 1024, owner_id: user.id },
    });
    return { url: signed.data.url, expiresAt: signed.data.expires_at, path };
  }
}
```

The client then sends the file to that URL:

```ts
// upload.ts
export async function upload(grant: { url: string }, file: Blob): Promise<void> {
  const res = await fetch(grant.url, {
    method: "PUT",
    headers: { "content-type": file.type, "if-none-match": "*" },
    body: file,
  });
  if (!res.ok) throw new Error(`the upload was refused: ${res.status}`);
}
```

## The flow

1. **The client asks your backend** for a grant — a route of your own, with whatever the upload needs to say (the kind of file, which record it belongs to).
2. **Your backend signs it** with `POST /storage/buckets/{bucket}/upload-urls` (`Palbase.storage.createUploadUrl`) and answers the URL.
3. **The client `PUT`s the bytes** to the URL — `PUT /storage/signed/{bucket}/{path}`, with the signature in its query.
4. **Storage checks the grant while the bytes stream**, stores the object, answers it (`200`, or `201` for a new one), and emits `file.uploaded`.

Your backend is not on the upload's path, so it learns of the upload from the event: an `@On("file.uploaded")` handler ([Event Hooks](/docs/backend/hooks)), or a route the client calls once its `PUT` is answered.

## What the URL grants

`createUploadUrl` takes:

| Field | What it pins |
|---|---|
| `path` | The object's path, chosen by your backend, never by the client. |
| `expires_in` | Seconds the URL works: 1 to 604800 (7 days). |
| `max_bytes` | A ceiling below the bucket's own `file_size_limit`. |
| `owner_id` | The user the object will belong to; it is deleted with them. |

The bucket's `allowed_mime_types` are pinned too. It answers `{ url, expires_at }`: an absolute URL at the project's own address, `https://<ref>.palbase.studio/storage/signed/{bucket}/{path}?…`. Every one of its query parameters — the bucket, the path, the expiry, the ceiling, the types, the owner — is covered by its signature, so a client that edits one holds a URL that opens nothing.

## The `PUT`

| Header | What it does |
|---|---|
| `Content-Type` | Used only when the bytes cannot say what they are (HEIC): the type is sniffed from the bytes. |
| `If-None-Match: *` | Create only: an object already at the path is refused with `412`. |
| `X-Checksum-Sha256` | The bytes' sha256, hex: bytes that do not match are refused, and nothing is kept. |

| Answer | Why |
|---|---|
| `200` / `201` | Stored — the object, as JSON: `path`, `size`, `content_type`, `width`, `height`, `thumbhash`, `variants`. |
| `400 checksum_mismatch` | The bytes do not have the sha256 `X-Checksum-Sha256` named. |
| `403` | The signature is wrong, expired, another project's, or a download signature. |
| `412 object_exists` | `If-None-Match: *` and an object is already there. |
| `413 payload_too_large` | Larger than the URL's ceiling or the bucket's. |
| `415 unsupported_media_type` | A type the bucket, or the URL, does not take. |
| `422 unreadable_picture` | A picture the bucket's renditions cannot be made from: truncated, or a format storage does not read. |
| `429 quota_exceeded` | The project's storage for the period is used up under its quota (with `Retry-After`). |

A picture's renditions are made inside the upload, so the object the `PUT` answers already carries them.

> **Note:** A browser page on any site can make this `PUT`: it is preflighted, and the project's address answers the preflight. See [Web Uploads](/docs/web/uploads) for the browser.

## Upload routes

An upload route is one method that both decides where a file goes and runs once it is there. The client sends the file with the route's input in one call to the project's storage; storage asks your machine whether this caller may upload and where to, writes the bytes under the bucket's rules, then hands the route's handler the stored object. What the handler answers is the client's answer. Nothing is signed, the client makes no second call to say it is done, and the bytes still never pass through your machine.

```ts
// src/modules/profile/profile.controller.ts
import { Controller, PalError, Upload, UploadedObject, User, type UserT } from "palbase/backend";

interface Avatar {
  owner: string;
  path: string;
  size: number;
  contentType: string;
  thumbhash?: string;
}

@Controller("/profile")
export class ProfileController {
  // Into the avatars bucket, under a folder of the user's: the client never names the path.
  @Upload("/avatar", { bucket: "avatars", pathTemplate: "{userId}/{uploadId}-{filename}", rateLimit: { max: 10, window: 60 } })
  avatar(@UploadedObject() file: UploadedObject, @User() user: UserT): Avatar {
    // Runs once the file is stored. A refusal thrown here deletes it.
    if ((file.width ?? 0) < 128) throw new PalError(422, "picture_too_small", "An avatar is 128 pixels wide at least");
    return { owner: user.id, path: file.path, size: file.size, contentType: file.contentType, thumbhash: file.thumbhash };
  }
}
```

The client calls it through the module `palbase apps:sync` writes, the file after the route's input: `pb.backend.profile.avatar(file, { onProgress })` in a browser ([Web Uploads](/docs/web/uploads#an-upload-route)).

`@Upload(subpath, options)` is a `POST` route of its controller, and takes:

| Option | What it is |
|---|---|
| `bucket` | The bucket its files go to: lowercase letters, digits and dashes, starting with a letter, 2 to 63 long. Its rules (the largest file, the types it takes, its renditions) hold every upload as storage writes it. |
| `pathTemplate` | The path each file is stored under, made for each upload from the tokens below. Segments separated by `/`, none empty, `.` or `..`, no control character, 1024 bytes at most. |
| `auth` | Who may upload, as any route's `auth`: a signed-in user unless `auth: false`. |
| `rateLimit` | How many uploads a caller may start per window, as any route's `rateLimit`. Spent as an upload is asked for, before a byte is written. |

| Token | What it becomes |
|---|---|
| `{userId}` | The signed-in user's id; `anonymous` for no one, on a route with `auth: false`. |
| `{uploadId}` | The upload's own id, made by storage: `file.uploadId` in the handler. |
| `{filename}` | The name the client gave its file, made one path segment: control and invisible characters dropped, `/` and `\` a dash, a run of dots one dot, no leading dot or space, 200 characters at most; `file` when it gave none. |

A template that names another token, or is no path storage keeps, stops the app as it starts. Storage writes an upload's object only where none is: put `{uploadId}` in the template, or a second upload to the same path is refused `412 object_exists`.

The handler takes the stored object with `@UploadedObject()`, and what any route takes: the input the client sent beside the file with `@Body(schema)`, the caller with `@User()` or `@OptionalUser()`, `@Param` and `@QueryParams`. It runs as the caller does, their row-level security included. The caller is the one storage names, their id and session, not their token: an upload route cannot ask for a verified email, and `@Headers()`, `@Req()` and `@Client()` stop the app as it starts, because storage forwards none of the client's headers. A method is an upload route or another route, never both.

| `@UploadedObject()` | What it is |
|---|---|
| `uploadId` | The upload's id, the same as in its path. |
| `bucket`, `path` | Where it was stored, as `pathTemplate` made it. |
| `size` | Bytes, as storage counted them. |
| `contentType` | The type storage found in the bytes, not the file's name or what the client claimed. |
| `checksum` | The stored bytes' SHA-256, hex. |
| `width`, `height`, `thumbhash` | A picture's size in pixels, and its placeholder (ThumbHash). Absent for anything else. |
| `variants` | The renditions the bucket declares, by name, each its address: a public bucket's. None for a private bucket. |

### What storage does

1. **The client's call.** `POST /storage/upload/<machine>/<route>` at the project's address, with the publishable key and the user's token when someone is signed in. `<route>` is the route's path as one percent-encoded segment (`profile%2Favatar`), and the request's query is the route's. The body is `multipart/form-data`: a JSON `body` part of 1 MiB at most (the route's input), then the `file`.
2. **The machine authorizes it**, within 30 seconds. The route's `auth` and `rateLimit` are held as a request of the caller's would meet them, its `@Resolve` parameters and guards run, its query and the `body` are checked against their schemas, and `pathTemplate` is made into the path. A refusal is the client's answer, as the app gave it, and no byte is written.
3. **Storage writes the bytes** to the bucket under its rules, and measures them: size, checksum, the type the bytes are, a picture's size, placeholder and renditions. The object belongs to the signed-in user, and is deleted with them.
4. **The handler runs** with the stored object, within two minutes. Its answer (`200` with JSON, `204`, a `Response` it built, a refusal) is relayed to the client as it gave it. A refusal, or no answer in two minutes, deletes the object. A kept one is told as `file.uploaded` ([Event Hooks](/docs/backend/hooks)).

What the client can be answered besides the route's own:

| Status | Why |
|---|---|
| `400` | Not an upload: not multipart, no `file` part, a `body` that is not JSON or is over 1 MiB, a route or machine name that is none; or a file name that makes the path longer than storage keeps. |
| `401` | The route needs a signed-in user, and no one is. |
| `404` | No such machine, no upload route at that path, or the bucket the route names is none. |
| `412 object_exists` | An object is already at the path the template made. |
| `413` | Larger than the bucket takes. |
| `415` | A type the bucket does not take. |
| `429` | The route's `rateLimit` for this caller (`Retry-After`), the project's storage used up under its quota, or its machine calls all under way. |
| `502` | The app did not answer, or its authorize named no bucket and path an object can have. |
| `503` | The machine is waking or building. Sending again is safe. |

## Why the backend asks first

There is no client-side object API: the publishable key opens nothing in storage, so a client cannot write a file anywhere your code did not name. Putting the decision in your backend gives it the whole say:

- **The path is yours.** A user cannot overwrite another's file, because they never choose the path.
- **The size and type are yours,** per upload, below the bucket's.
- **The owner is yours.** `owner_id` ties the object to the user it is for, and deleting the user deletes it.
- **The rate is yours.** The grant is a route of your own: `rateLimit` on it holds how often a user may upload.

## Uploading from your backend

When the bytes are already on your server — a generated report, a file fetched from elsewhere — write them with `putObject` and skip the URL: see [Storage](/docs/backend/storage).

## Related

- [Storage](/docs/backend/storage) — buckets, objects, renditions and signed download URLs
- [Web Uploads](/docs/web/uploads) — the browser's side, for a signed URL and for an upload route
- [Event Hooks](/docs/backend/hooks) — acting on `file.uploaded`
- [Controllers & Routing](/docs/backend/controllers) — the grant's route and its `rateLimit`



<!-- ===== backend/secrets ===== -->

# Secrets

A project keeps its application secrets — a payment provider's key, a signing secret, the project's own secret key for its backend — in its **secrets**, sealed with the project's own key, versioned, and audited on every read and write. They are kept in two sets, `production` and `development`. A machine is started with one set: every secret in it is in the machine's environment by name, so your code reads `process.env.STRIPE_KEY` and nothing else. A program that wants a value while it runs — or one that is not a machine — reads it with the secret key through the secrets module, `Palbase.secrets`.

## Quick example

In Studio, open the environment's **Secrets** screen and add `STRIPE_KEY`. In the machine's settings (**Backend › Machines › the machine › Edit settings**), choose the set its **Secrets** start with. The machine rolls out with the value, and the code reads it:

```ts
// src/modules/billing/billing.service.ts
import { Injectable } from "palbase/backend";

@Injectable()
export class BillingService {
  // Read once, at boot: a secret that changes rolls the machine out with the new value.
  private readonly stripeKey = required("STRIPE_KEY");

  authorization(): string {
    return `Bearer ${this.stripeKey}`;
  }
}

function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is not set: add it to the project's secrets and start the machine with them`);
  return value;
}
```

## The two sets

| Set | What it is for |
|---|---|
| `production` | What the machines that serve your users start with. |
| `development` | A second set, for machines and programs that must not see production's values. |

A machine names the set it starts with (`secrets`: `production`, `development`, or none) — in Studio on the machine's settings, or through the machines module (`PATCH /machines/{name}`). Studio's **Secrets** screen manages the set the environment's machines start with: `production` when none names one yet, and it refuses to choose for you when machines start with different sets.

## How a machine reads them

- **By name, in its environment.** Each secret of the set is an environment variable of the machine. A name the machine's own `env` also sets wins over the secret — keep a value in one place.
- **A change rolls the machine out.** Writing, rolling back or deleting a secret of the set starts the machine's new version with the new values beside the version that serves; nothing restarts in place, and no request meets a gap.
- **A build can wait for them.** A machine's `.env.example` names what it needs: a build whose names the machine's env and secrets do not hold waits (`waiting_config`, with `missing_env`) and rolls out once they are there. See [Builds, Logs & Rollback](/docs/machines/builds).

A `palbase/backend` app on a machine needs none of its own keys here: the platform starts every machine with its own secret key (`PALBASE_SECRET_KEY`, listed under **Settings › API keys** as `machine: <name>`) and its webhook secret (`PALBASE_WEBHOOK_SECRET`), beside `PALBASE_URL` and `PALBASE_PROJECT_ID`. A secret of the same name set by hand gives way to them. A value missing or malformed stops the boot, naming it.

## Names and sizes

| Rule | Limit |
|---|---|
| Name | An environment-variable name: `A-Z`, `0-9` and `_`, starting with a letter, 128 characters at most. |
| Value | 64 KiB. |
| Secrets per set | 1000. |

## Reading a value while it runs

`Palbase.secrets` (or `createServer(…).secrets`) reads and writes the secrets with the project's secret key:

```ts
// src/modules/billing/rotation.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class RotationService {
  /** The current value, read now rather than at boot. */
  async current(name: string): Promise<string> {
    return (await Palbase.secrets.getSecret({ path: { environment: "production", name } })).data.value;
  }

  /** Every value of the set, in one call: what a program outside a machine reads at startup. */
  async all(): Promise<Record<string, string>> {
    return (await Palbase.secrets.getEnvironmentValues({ path: { environment: "production" } })).data.values;
  }
}
```

| Call | What it does |
|---|---|
| `listSecrets({ path: { environment } })` | The set's secrets by name, with their version — never their values. |
| `getSecret({ path: { environment, name } })` | One secret's current value and version. |
| `getEnvironmentValues({ path: { environment } })` | Every value of the set, and every version, in one call. |
| `putSecret({ path: { environment, name }, body: { value } })` | Writes the value as the secret's next version, creating it if it is new. |
| `listSecretVersions({ path: { environment, name } })` | Its versions, newest first, with the key that wrote each — never their values. |
| `rollbackSecret({ path: { environment, name }, body: { version } })` | Makes an earlier version's value the next version; the history stays whole. |
| `deleteSecret({ path: { environment, name } })` | Forgets the secret and every version of it. |
| `listSecretAudit({ query: { environment?, name? } })` | Every read and write, newest first, with the key that made it and the request id. |

Every write is a new version, so a rotation that goes wrong is a rollback away. A write, a rollback and a delete each emit `secret.changed` — the set, the name, the version and the change, **never the value** — to the project's webhook, so a receiver learns what changed and reads it with its own key ([Webhooks](/docs/server/webhooks)).

## Who can read them

Only the secret key. A publishable key ships in apps and is refused by every secrets route; a user's token opens none of them. Every read — a list, one value, the whole set — is in the audit trail with the id of the key that made it, which is one more reason to give each server its own secret key: the audit then says which one read what, and revoking one shuts out only that server.

## The `Secrets` service

A backend reads a secret with `await Secrets.get("NAME")`: the value or `null`. It reads the machine's environment — the set the machine starts with — so a changed secret arrives with the machine rolled out again. A name the platform puts there itself (`PALBASE_URL`, `PALBASE_SECRET_KEY`, `PALBASE_DB_URL` …) is not the project's secret, and answers `null`.

The names it takes are the ones the project holds: the CLI's `types:pull` writes them into `palbase/palbase-env.d.ts`, and a name the project does not hold does not compile.

```ts
// palbase/palbase-env.d.ts
declare module "palbase/backend/stack" {
  interface Secrets {
    STRIPE_KEY: true;
  }
}

export {};
```

```ts
// src/modules/billing/stripe-key.service.ts
import { Injectable, Secrets } from "palbase/backend";

@Injectable()
export class StripeKey {
  async get(): Promise<string> {
    const key = await Secrets.get("STRIPE_KEY");
    if (!key) throw new Error("STRIPE_KEY is not among the secrets this machine started with");
    return key;
  }
}
```

## From the CLI

```sh
printf %s "$STRIPE_KEY" | palbase secrets:set STRIPE_KEY   # production: the value is read from stdin
printf %s "sk_test_…" | palbase secrets:set STRIPE_KEY --dev
palbase secrets:list                                       # names and versions, never values
palbase secrets:versions STRIPE_KEY
palbase secrets:rollback STRIPE_KEY --version 3            # a new version with version 3's value
palbase secrets:audit --name STRIPE_KEY                    # who read and wrote it, and when
```

`--dev` acts on the development set — what a backend run on your computer with `palbase run` or `palbase env:pull` reads — and its absence on production. A value is never taken from the command line, where the shell's history would keep it. `palbase secrets:get <NAME>` prints one value, for an admin; `palbase secrets:unset <NAME>` takes a secret away. Every command is in the [CLI reference](/docs/cli/reference#secrets).

## Related

- [Machines](/docs/machines/overview) — a machine's environment, and the secret set it starts with
- [Builds, Logs & Rollback](/docs/machines/builds) — `.env.example`, and a build that waits for its settings
- [Server SDK Overview](/docs/server/overview) — the secret key and `createServer`
- [Webhooks](/docs/server/webhooks) — `secret.changed`



<!-- ===== backend/flags ===== -->

# Flags

Every project has feature flags and remote configuration: typed values, targeted by conditions, given to single users, read by its apps and kept up to date in them as they change. Apps **read** flags with the publishable key ([Web Flags](/docs/web/flags)). Your backend **defines** them, gives users their own values, and reads what any user would see — with the secret key: `Palbase.flags` in a `palbase/backend` app, `createServer(…).flags` anywhere else.

## Quick example

```ts
// src/modules/checkout/checkout.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class CheckoutService {
  /** Turns the new checkout on for one user — a beta tester, a support case. */
  async enableNewFlow(userId: string): Promise<void> {
    await Palbase.flags.putUserValue({ path: { user_id: userId, key: "checkout.new_flow" }, body: { value: true } });
  }

  /** What that user's app reads for the flag now. */
  async newFlowFor(userId: string): Promise<boolean> {
    const { data } = await Palbase.flags.getUserValues({ path: { user_id: userId } });
    return data.values["checkout.new_flow"] === true;
  }
}
```

## How a value is resolved

For each flag, a reader gets, in order:

1. **its own value**, if the user has one (`source: "override"`);
2. else the value of the **first condition that matches**;
3. else the flag's **default**.

A reader with no signed-in user has no values of its own and no percentile, so only the conditions that need neither can match it.

## Defining a flag

`PUT /flags/system/{key}` (`putDefinition`) defines a flag, or changes one:

```ts
// src/modules/checkout/flags.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class FlagsService {
  async onStart(): Promise<void> {
    await Palbase.flags.putDefinition({
      path: { key: "checkout.new_flow" },
      body: {
        value_type: "bool",
        value: false,
        description: "The one-page checkout",
        conditions: [
          { when: "client.platform == 'ios' && client.app_version >= '2.10.0'", value: true },
          { when: "percentile <= 10", value: true },
        ],
      },
    });
    await Palbase.flags.putDefinition({
      path: { key: "home.theme" },
      body: { value_type: "string", value: "light", variants: ["light", "dark", "contrast"] },
    });
  }
}
```

| Field | What it says |
|---|---|
| `value_type` | `bool`, `number`, `string` or `object`. |
| `value` | The default (8 KB at most). |
| `variants` | A string flag's allowed choices: every value — the default, a condition's, a user's — is one of them. |
| `conditions` | Targeting, in order, first match wins; 8 at most, each `{ when, value }`. |
| `description` | What the flag is for. |

A key is dot-separated segments, each a letter then letters, digits and underscores, 128 characters at most. A project defines **200 flags** at most. A write that would change the type under users' values, or leave a user's value outside the choices, is refused; so is a direct write while publishing is on (below). `listDefinitions`, `getDefinition` and `deleteDefinition` read and remove them; deleting a flag removes every user's value of it. Every reader is told of a change at once.

Studio's **Feature flags** screens edit the same definitions and users' values.

### Conditions

A condition's `when` is a small expression language: comparisons over a fixed set of variables, combined with `&&`, `||` and parentheses — no functions, no arithmetic. 512 characters and 16 comparisons at most.

| Variable | Where it comes from | Compared as |
|---|---|---|
| `client.platform` | the `X-Platform` header the app sends | a string |
| `client.locale` | the first language of `Accept-Language` | a string |
| `client.app_version` | `X-Palbase-Client-Version` | a version (`'2.10.0'` is above `'2.9.0'`) |
| `client.os_version` | `X-OS-Version` | a version |
| `percentile` | the signed-in user, hashed with the flag's key: 1 to 100 | a number |
| `server.country` | the country of the address the edge saw | a string (`'TR'`) |
| `server.now` | the server's clock | a time (`'2026-01-01T00:00:00Z'`) |

Operators: `==`, `!=`, `<`, `<=`, `>`, `>=`, `in ['ios', 'android']`, and for strings `startsWith`, `endsWith`, `contains`.

- **A variable outside the table** (`client.foo`) is refused when the flag is written — it could never match.
- **A variable the client did not send** does not match, and the flag falls back to its default.
- **`client.*` is what the client says.** Anyone can send any header, so a `client.*` condition chooses an experience, never access.
- **`percentile` is per flag:** `percentile <= 10` is a different tenth of users for each flag, so one unlucky user is not outside every experiment. It needs a signed-in user.
- **An unresolved country matches nothing**, `!=` included: "not Turkey" is never true of a caller whose country is unknown.
- **`server.now`** cannot be moved by a client's clock, which is what makes a scheduled change real.

## Users' own values

| Call | What it does |
|---|---|
| `putUserValue({ path: { user_id, key }, body: { value } })` | Gives one user their own value for one flag. |
| `putUserValues({ path: { user_id }, body: { values } })` | Many flags for one user (1000 at most). |
| `batchUserValues({ body: { operations: [{ user_id, values }] } })` | Many users at once, 1000 operations at most: all of them, or none. |
| `deleteUserValue({ path: { user_id, key } })` | Removes one; the answer is what resolves for them now. |
| `deleteUserValues({ path: { user_id } })` | Removes all of theirs; their flags resolve as anyone's again. |

Each value is checked against the flag's type and choices. The user's apps are told at once, on the user's own channel (`flags:<ref>:<user_id>`); everyone's are told of a definition change on `flags:<ref>`. The web SDK side of that is in [Web Flags](/docs/web/flags).

## Reading as a user

```ts
// src/modules/checkout/preview.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class PreviewService {
  /** What an iOS 2.10 user would read — the conditions see this request's headers as the client's. */
  async asIosUser(userId: string): Promise<Record<string, unknown>> {
    const { data } = await Palbase.flags.getUserValues({
      path: { user_id: userId },
      headers: { "X-Platform": "ios", "X-Palbase-Client-Version": "2.10.0" },
    });
    return data.values;
  }
}
```

`getUserValues` resolves every flag for one user, as their client would read it: their own values and their percentiles, with the client context taken from the call's headers. `getValues` with the secret key resolves for nobody in particular — the defaults and the conditions that need no user.

## Publishing

By default a definition changes the moment it is written. A project that wants changes reviewed turns **publishing** on, once and for good: the live flags become version 1, and from then on a definition changes only through a published draft — a direct `putDefinition` is refused with `409 publish_required`.

| Step | Call |
|---|---|
| Turn publishing on | `activateTemplates({ body: {} })` |
| Start the shared draft from the active version | `createTemplateDraft({ headers: { "If-Match": "flags-active-<version>" }, body: {} })` |
| Write or remove a parameter | `putTemplateParameter` / `removeTemplateParameter`, each with the draft's `If-Match` |
| See what publishing would do | `reviewTemplateDraft()` — each change, how many users' values it touches, and the issues that block it |
| Publish | `publishTemplate({ headers: { "If-Match": "<draft etag>", "Idempotency-Key": "<key>" }, body: { note } })` |
| Go back | `restoreTemplateVersion({ path: { version }, … })` starts a draft from an earlier version |

Every step names the revision it read (`If-Match`), so two people editing the one shared draft never overwrite each other. A draft with issues is refused with `409 template_validation_failed` and the issues. The same `Idempotency-Key` answers the first publication again, and `getPublishReceipt` reads a publication's answer back for a client that lost it.

## Palbase-managed flags

Flags under `palbase.` are the platform's: their type is fixed and they are not deleted.

## Which builds are in use

Apps' reads are counted by installation: `getCurrentInstallations()` answers the builds that read their flags in the last day, by platform and app version, and `getInstallationsDaily({ query: { days } })` the curve, kept 90 days.

## The `Flags` service

A backend reads flags with `Flags`, **for the request's user**: the signed-in caller a handler serves, or a gateway's member. Their own value comes first, then the flag's. `isEnabled` is a plain boolean — a flag that cannot be read is off, and why is logged — and the other reads answer `{ data, error, status }`. A context names another user (`{ userId }`), or nobody (`{ userId: null }`): the flag's own value.

| Call | What it answers |
|---|---|
| `isEnabled(key, context?)` | Whether its value is truthy |
| `get(key, default?, context?)` | Its value; the default stands in when it is absent or cannot be read |
| `getVariant(key, context?)` | `{ name }` of a string value |
| `getAll(context?)` | Every flag: `{ name, enabled, variant? }` |
| `setOverride(key, value)` | The request's user's own value (400 without one) |
| `$asService().setOverrideForUser(userId, key, value)` … | Any user's, by id: `setOverridesForUser`, `clearOverrideForUser`, `clearAllOverridesForUser`, `batchSetOverrides` |

```ts
// palbase/palbase-env.d.ts
declare module "palbase/backend/stack" {
  interface Flags {
    new_checkout: true;
  }
}

export {};
```

```ts
// src/modules/checkout/checkout-flow.controller.ts
import { Controller, Flags, Get } from "palbase/backend";

@Controller("/checkout")
export class CheckoutFlowController {
  @Get("/flow")
  async flow(): Promise<{ flow: "new" | "classic" }> {
    return { flow: (await Flags.isEnabled("new_checkout")) ? "new" : "classic" };
  }
}
```

## Related

- [Web Flags](/docs/web/flags) — reading flags in the browser, and their live updates
- [Realtime](/docs/backend/realtime) — the socket the updates travel on
- [Server SDK Overview](/docs/server/overview) — calls, refusals and retries
- [Test Users](/docs/backend/test-users) — users to give values to while you try a flag



<!-- ===== backend/notifications ===== -->

# Notifications

Every project has notify: email, push, SMS and WhatsApp to its users, one-time codes by text, topics users follow, and each user's preferences about what they take. Your backend sends with the secret key — `Palbase.notify` in a `palbase/backend` app, `createServer(…).notify` anywhere else. Apps only register their own devices and set their own user's preferences and topics, with the publishable key and the user's token.

## Quick example

```ts
// src/modules/orders/notify.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class OrderNotices {
  async shipped(userId: string, email: string, orderId: string): Promise<void> {
    // Through the project's own email provider: a message composed whole.
    await Palbase.notify.sendEmail({
      body: { to: email, user_id: userId, subject: `Order ${orderId} has shipped`, text: "It is on its way." },
    });
    // To every device of the user's, through the project's own push account.
    await Palbase.notify.sendPush({
      body: { to: { user_ids: [userId] }, title: "Shipped", body: `Order ${orderId} is on its way`, deep_link: `myapp://orders/${orderId}` },
    });
  }
}
```

A send is **queued**, not delivered: it answers `202` with the message's id, and the message ends `sent` or `failed` later — each emits `notification.sent` or `notification.failed` to the project's webhook ([Webhooks](/docs/server/webhooks)).

## Every channel but one needs a provider of yours

| Channel | Goes through |
|---|---|
| Email | The platform's **shared sender**, within the project's limits — for the platform's templates only (the auth emails: verify, reset, magic link, codes …, as the project overrode them). Anything else — a message composed whole, a template of your own — goes through **your own email provider**: Azure Communication Services, Amazon SES, SendGrid or SMTP. |
| Push | Your own FCM, APNs or Expo account — a browser's through its own push service, with the project's Web Push key (nothing to set up). |
| Inbox, in-app messages | Palbase itself: nothing to set up. |
| SMS | Your own SMS providers — Twilio, Vonage or Azure Communication Services — in failover order. |
| One-time codes | Your own verification service (Twilio Verify), or your SMS providers. |
| WhatsApp | Your own WhatsApp Business account (Meta). |

An email the shared sender may not send is refused with `403 own_provider_required`; past the shared sender's limits a send is `429 send_limit_reached`. A project with an active email provider sends all its email through it.

Providers are set in Studio (**Notifications › Providers**) or with `putNotifyProvider({ path: { channel, provider }, body: { credentials, priority, active } })`: the credentials are sealed with the project's own key, checked as the sender will use them, and never answered back. `getDeliverability()` says, per channel, whether it can send now, through what, why not and what to do.

From the CLI, the credentials are piped in as JSON — never written on the command line, where the shell would keep them:

```sh
palbase notify:providers:set email sendgrid < sendgrid.json   # {"api_key": "…", "from_domain": "example.com"}
palbase notify:providers:set sms twilio --priority 1 < twilio.json
palbase notify:deliverability                                  # can each channel send now, and through what
palbase notify:send email ada@example.com --template welcome --var name=Ada
palbase notify:messages --limit 20                             # what was sent, and what became of it
```

**Apple (APNs).** The credential is a team-scoped APNs key — `{ "private_key": "-----BEGIN PRIVATE KEY-----…", "team_id": "…", "key_id": "…" }`, the `.p8` from Apple's Certificates, Identifiers & Profiles → Keys with Apple Push Notifications service on — and one key serves every app of the team, in both of Apple's environments. As it is saved, notify asks Apple about it, with a token no device holds, for each iOS app registered in the environment: a key Apple refuses (another team's, a revoked one, one not allowed for the app) is refused with `400 invalid_credentials`, saying Apple's answer; Apple not answering is `502 apns_unreachable`, and nothing is saved.

```sh
palbase notify:providers:set push apns < apns.json   # {"private_key": "…", "team_id": "ABCDE12345", "key_id": "3PSQ7G27A3"}
```

With an [Apple ID signed in](/docs/distribution/app-store#keys-made-for-you), Palbase makes the APNs keys for you instead: one for production and one for the sandbox, each scoped to the environment's iOS apps, and notify takes them as its provider — `key_id` signs production's pushes, `sandbox_key_id` (with `sandbox_private_key`) the sandbox's, and `made_by` is `"palbase"`. A key you set yourself is never replaced so.

A push to an iOS device goes **to the bundle of the app it was registered from** — the app whose publishable key registered it ([Client Apps](/docs/apps/overview)) — and **through the APNs environment its token is for**, which the iOS SDK says: `sandbox` for an app run from Xcode or signed for development, `production` for TestFlight, the App Store and ad hoc. So one environment reaches the development build (`com.example.app.dev`, sandbox), its TestFlight build (`com.example.app.dev`, production) and the App Store app (`com.example.app`, production), each app registered in it with its own key. A device that did not say (an older SDK) is tried in production when the key says `is_production`, else sandbox, then — Apple calling the token bad — the other; a key made for one environment alone, asked in the other, is asked in its own. The environment that reached a device is kept. A device whose app is not known (registered before its app was) goes to the environment's one iOS app, or to the key's optional `bundle_id`. Each push's delivery says where it went: `route` — `production com.example.app`.

**A provider that stops working** — an APNs key revoked, one not allowed for an app — fails every push alike. notify keeps it failing (`GET /notify/providers`: `failing_since`, `last_error`), Studio's **Notifications › Providers** shows it, and the organization's owners get an email — at most one a day a provider — as `notification.push_failing` (`{ project_id, channel, provider, error, failing_since }`) goes to your webhook. A push to the app it failed for that goes through, or the provider saved anew, ends it: a key that reaches one of your apps and not another stays failing for the other.

Templates (`notify:templates:*`), topics (`notify:topics:*`) and the message settings (`notify:settings:*`) have their commands too; every one is in the [CLI reference](/docs/cli/reference#notify).

## Email

```ts
// src/modules/accounts/welcome.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class WelcomeService {
  async send(userId: string, email: string, name: string, locale: string): Promise<string | undefined> {
    const queued = await Palbase.notify.sendEmail({
      body: {
        to: email,
        user_id: userId, // the user's preferences hold, and deleting them deletes the message
        template: "welcome", // a template of your own: your own provider
        variables: { name },
        locale,
        category: "news", // only users who did not turn "news" off get it
      },
    });
    return queued.data.skipped ? undefined : queued.data.message_id;
  }
}
```

| Field | What it says |
|---|---|
| `to` | One address. |
| `template`, `variables` | A template and what fills it — or `subject` with `html` and/or `text` (own provider only). Without a text part, the html's text is sent as one. |
| `locale`, `locales` | The language to render in; `locales` are more it would take, most wanted first: each, then its language alone, then the project's default and English. |
| `category` | `transactional` (the default) reaches every user; any other — `marketing`, `news` — only users who did not turn it off on this channel. |
| `user_id` | The user the message is for. |
| `from`, `reply_to` | The send's own sender (own provider only). |
| `priority` | `high` is tried again sooner when it could not leave. |
| `metadata` | Your own data about the message (a JSON object, 4 KiB), kept with its report. |

A send that the user's preferences turn off answers `{ skipped: true }`: nothing was queued or counted.

### Templates

Templates are Handlebars — `{{name}}`, `{{#if}}`, `{{#each}}` …; in an HTML body `{{name}}` is escaped and `{{{name}}}` is not. `listEmailTemplates()` answers every template the project's email renders from — the platform's defaults and your overrides — with the variables each uses. `putEmailTemplate({ path: { slug, locale }, body: { subject, html_body, text_body } })` overrides one in a locale, and `deleteEmailTemplate` brings the default back. SMS templates work the same way (`putSmsTemplate`), and WhatsApp slugs map to templates approved on your Meta account (`putWhatsAppTemplate`). Studio's **Notifications › Templates** screen edits them.

## Push

```ts
// src/modules/chat/push.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class ChatPush {
  async newMessage(to: string[], from: string): Promise<void> {
    const queued = await Palbase.notify.sendPush({
      body: {
        to: { user_ids: to },
        // A text, or one per locale: each device gets the one in its language.
        title: { en: "New message", tr: "Yeni mesaj" },
        body: { en: "{{from}} wrote to you", tr: "{{from}} size yazdı" },
        variables: { from },
        category: "chat",
        data: { kind: "message" },
      },
    });
    console.log(`queued ${queued.data.message_ids.length}, skipped ${queued.data.skipped_user_ids.length}`);
  }
}
```

A push is one message per user, delivered to **every device of theirs** — an Expo token through Expo, a VoIP token through APNs, an iOS token through APNs if the project has it (else FCM), Android through FCM, a browser through its own push service (Web Push, below). `to: { topic }` sends one message to a topic's followers instead. Fields beyond the title and body: `data` (4 KiB for the app), `deep_link`, `image` (https), `badge`, `sound`, `silent`, `content_available`, `mutable_content`, `collapse_key`, `ttl`, `priority`, and `push_type: "voip"` for a call ring to `ios_voip` devices.

**Devices are the app's to register**, and the iOS and Android SDKs do it for you: `POST /notify/devices` with the token its push SDK gave it (`device_id`, `platform` — `android`, `ios`, `ios_voip` or `web` — `token`, the install's `installation_id`, and an iOS token's `apns_environment`: `sandbox` or `production`). With no one signed in, the publishable key alone registers it as the install's, proven with the install's secret (`X-Palbase-Installation-Secret`): a push that names the install — `to: { installation_ids }` — reaches it, so an app reaches people who never signed up. When someone signs in, their registration takes the device and it is theirs; signed out, the app registers it as the install's again. A user's device is the session's it was registered in: when the session ends — the user signed out or ended it from another device, its refresh token was revoked, an admin revoked it — the device is forgotten, and no push of theirs reaches it. A token another device held moves to this one. Your backend reads a user's devices (never their tokens) with `listUserDevices({ path: { user_id } })`.

**An app taken off a phone** shows when its next push goes: APNs answers `410`, FCM `UNREGISTERED`. The device is forgotten, and `notification.uninstalled` (`{ platform, provider, device_id, installation_id, user_id }`) goes into the person's timeline and to your webhook — the uninstall you can count and reach back for by other means.

**How a push went on each device** is the app's to say, and the SDKs say it: every push carries a sealed receipt (`pb_receipt` in its data), and the app reports with it, no sign-in needed (`POST /notify/receipts`): it reached the phone (`delivered` — on iOS from the app's Notification Service Extension, even with the app closed; on Android as the app draws the notification), it could not be shown (`not_shown`: the app's notifications or its channel are off), it was `opened`, `dismissed`, or a button tapped (`action`). A push no device reported on by the time it expired (its `ttl`, or the providers' four weeks) is `unconfirmed`: the phone may have been off, or its report lost — not "not delivered". Each stage reached for the first time is an event (`notification.delivered`, `notification.opened` …) in the person's timeline. On Android a push goes to FCM as data only (`pb_title`, `pb_body`, `pb_receipt` and your own keys), and the app's own messaging service draws it ([Android notifications](/docs/android/notifications)): a system-drawn notification runs no app code, and nothing of it could be told.

### Push templates

A push written once — a title and a body per language (Handlebars, as a push's own), a picture and a link — and sent by name: `PUT /notify/templates/push/{slug}/{locale}` (Studio: Notifications → Templates → Push), then `template` in place of a title and a body. Each device gets its person's language; one the template does not have gets the project's default language, else the template's first.

```ts
// src/modules/orders/shipped.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class OrderShipped {
  async tell(userId: string, order: string): Promise<void> {
    await Palbase.notify.sendPush({
      body: { to: { user_ids: [userId] }, template: "order.shipped", variables: { order }, category: "transactional" },
    });
  }
}
```

A send that names a template names no title or body of its own (`400 invalid_push`), and one the project has not is refused (`404 template_not_found`).

## Web push

A browser takes the project's pushes through **its own push service** (Chrome's, Firefox's, Safari's), with the standard Web Push and a VAPID key of the project's own — made as the first browser asks for it, sealed, nothing for you to set up or pay for. The web app subscribes with `pb.notify.push.subscribe()` (from a tap: browsers allow the prompt only then) and serves the SDK's service worker, `palbase/web/push-sw.js`, which shows each push, opens its link when it is tapped, and reports how it went — `delivered`, `opened`, `dismissed` — as the native SDKs do. A browser is a device like any other (`platform: "web"`): it is the signed-in user's, or the install's while no one is, and a push to the user reaches it with their phones. A subscription that ended — the person blocked the site, cleared it — is forgotten as it is next pushed, and `notification.uninstalled` goes into the timeline. `GET /notify/webpush` (Studio: Notifications → Providers) says how many browsers are subscribed.

## Inbox

Each person has an inbox: the messages your backend puts there, and — when a push says so (`inbox: true`), or the project's `inbox.push_copy` setting does — a copy of a push as it is delivered (once, however many devices took it). It is **the same on every device of theirs**: read on one, it is read on each; deleted, it is gone from each. A message stays its days — the project's `inbox.days` (90 unless set), or `expires_in_days` (1 to 365) — and an inbox keeps its newest 250. When the user is deleted, their inbox goes with them.

```ts
// src/modules/orders/inbox.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class OrderInbox {
  async receipt(userId: string, order: string): Promise<void> {
    await Palbase.notify.sendInbox({
      body: {
        to: { user_ids: [userId] },
        title: { en: "Your receipt", tr: "Fişiniz" },
        body: { en: "Order {{order}} is paid.", tr: "{{order}} numaralı sipariş ödendi." },
        variables: { order },
        deep_link: `myapp://orders/${order}`,
        expires_in_days: 30,
      },
    });
  }
}
```

A message is a title and a body (a text, or one per language: each reader gets theirs), with a picture, a link and `data` — or a designed card (`card`, a message definition as the in-app messages' below, `presentation: { type: "card" }`), drawn by the SDKs' renderer. The apps read the signed-in person's inbox (`GET /notify/inbox`, how many are unread with it), mark messages read (`POST /notify/inbox/read`, some or all) and delete one (`DELETE /notify/inbox/{id}`); the iOS, Android and web SDKs draw it ready (`InboxView`, `pb.notify.inbox.mount`). Your backend reads anyone's with `listInboxMessages({ query: { user_id } })` (Studio: Notifications → Log → Inbox).

## In-app messages

A message shown **in the app** — over it (a modal), across the whole screen, or as a banner at an edge — when something happens there. A campaign is what it shows, what shows it, whom it is for and how often:

```ts
// src/modules/growth/cart-reminder.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class CartReminder {
  async create(audienceId: string): Promise<string> {
    const { data } = await Palbase.notify.listInAppTemplates();
    const welcome = data.templates.find((t) => t.key === "welcome");
    if (!welcome) throw new Error("no welcome template");
    const { data: campaign } = await Palbase.notify.createInAppCampaign({
      body: {
        name: "Cart reminder",
        status: "active",
        definition: welcome.definition,
        // An event the app records — session_start as it opens — with properties it must have.
        trigger: { event: "cart_viewed", where: { plan: "pro" } },
        // None: everyone. An audience: its people who allowed personalization.
        audience_id: audienceId,
        // Beside the project's caps: at most this often for this campaign.
        limits: { per_day: 1, max_total: 3 },
        // The person's event within its hours of seeing it: counted as its conversion.
        conversion: { event: "purchase", hours: 24 },
      },
    });
    return campaign.id;
  }
}
```

- **What it shows** is a definition, the same kind as a paywall's: a theme and a free layout of components, in every language it has, drawn natively by the iOS, Android and web SDKs with their paywall renderer. Start from the module's designed messages (`listInAppTemplates`; Studio's editor shows each as the apps draw it). Its buttons go to a link, ask for push (the system's prompt, after the message's own ask; allowed, the device registers for pushes), show a paywall, or call the app's own code.
- **What shows it** is an event of the app's: one analytics records (`capture`, screens, page views) or the app names (`inApp.trigger`). Triggers are matched **on the device**: no event leaves it for them, whatever the person chose of analytics.
- **Whom it is for**: everyone, or an audience — and then only its people who **allowed personalization** (`personalization` consent). A message to everyone needs no consent to be shown.
- **How often**: the project's caps hold across every campaign — one a session, three a day, ten minutes apart unless its `in_app` settings say otherwise — and a campaign adds its own (`per_session`, `per_day`, `min_minutes`, `max_total`). The server counts each showing on every device of the person and refuses one past a cap (`409 frequency_capped`): two phones do not show it twice.
- **What it did**: each showing, button tapped and conversion is an event in the person's timeline (`notification.in_app_shown`, `notification.in_app_clicked`, `notification.in_app_converted`) and in the campaign's counts (`getInAppCampaignStats`: shown, people, clicked, dismissed, converted). A conversion is reported by the app while the person allows analytics.

The apps fetch the person's campaigns as each session starts (`GET /notify/in-app/messages`) and ask before showing one (`POST /notify/in-app/impressions`); the SDKs do both: `.palbaseInAppMessages(pb)` on iOS, `PalbaseInAppMessages(pb) { … }` on Android, `pb.notify.inApp.start()` on the web.

## Topics

```ts
// src/modules/teams/topics.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class TeamTopics {
  async create(teamId: string, members: string[]): Promise<void> {
    await Palbase.notify.createTopic({ body: { name: `team.${teamId}`, self_subscribe: false } });
    await Palbase.notify.addTopicSubscribers({ path: { name: `team.${teamId}` }, body: { user_ids: members } });
  }

  async announce(teamId: string, text: string): Promise<void> {
    await Palbase.notify.sendPush({ body: { to: { topic: `team.${teamId}` }, title: "Team", body: text } });
  }
}
```

A topic is **closed** unless `self_subscribe`: only your backend adds its followers, and a user asking is refused (`403 topic_closed`). An open topic is followed from the app — `POST /notify/topics/{name}/subscription` with the user's token — and any user may leave any topic. `changeTopic` opens or closes one, `removeTopicSubscriber` takes a user off, `deleteTopic` deletes it and who follows it.

## Preferences

A user's preferences are channel → category → whether they take it. `transactional` is always on and not theirs to turn off; a category they never set is on. The app reads and sets its own user's (`GET` and `PUT /notify/preferences`); your backend reads and sets anyone's with `getUserPreferences` and `setUserPreferences({ path: { user_id }, body: { email: { marketing: false } } })`. Every send with a `user_id` and a `category` honours them.

## When a message goes

A send may say when it goes, with `schedule`: `at`, a moment for everyone, or `local_time`, an hour on each recipient's own clock — a date and time with no zone. A recipient's clock is their newest device's time zone, which the iOS and Android SDKs register with the push token (`timezone` on `POST /notify/devices`); for one whose devices say none, it is the project's `default_timezone`. A local time already past on someone's clock goes to them at once.

```json
{
  "to": { "user_ids": ["usr_01a1…", "usr_01a2…"] },
  "title": { "en": "Good morning", "tr": "Günaydın" },
  "category": "marketing",
  "schedule": { "local_time": "2026-10-15T10:00" }
}
```

That push goes at 10:00 in New York to a user whose phone is in New York, and at 10:00 in Istanbul to one in Istanbul. Until then each message is `scheduled`, with `send_at` saying when.

A message that is not transactional also keeps to the project's **send rules**, set with `putNotifySettings` or in Studio (**Notifications › Settings › When marketing goes**). A settings write that names none of the three keeps them as they are, so a client written before them does not wipe them; one named `null` is taken off:

| Setting | What it does |
|---|---|
| `default_timezone` | The clock of a recipient whose devices say none, an IANA name (`Europe/Istanbul`); UTC when unset. |
| `quiet_hours` | `{ start, end }`, `HH:MM` on the recipient's clock (`22:00` to `08:00` spans midnight; on the night the clocks change they still end at `08:00`). A message that would arrive in them is `held` until they end, then sent. |
| `marketing_cap` | `{ count, hours }`: how many such messages one recipient gets at most in a window. One more is `skipped`, with `skip_reason: "frequency_cap"`. |

Transactional messages — codes, receipts, security notices — go at once, whatever the hour and however many. When a waiting message's time comes it is decided again: what the user chose meanwhile holds (a category turned off skips it, `preferences`), and it waits out quiet hours and keeps to the cap like a new send.

| Status | What it means |
|---|---|
| `scheduled` | Waiting for its time (`send_at`). |
| `held` | Waiting out its recipient's quiet hours (`send_at`: when they end). |
| `skipped` | Not sent, and never will be. `skip_reason` says why: `consent` (they refused this channel's marketing), `frequency_cap`, `preferences`, `iys` (İYS holds no consent for it). |
| `canceled` | Taken back while it waited. |

`POST /notify/messages/{id}/cancel` takes back a `scheduled` or `held` message; one already on its way answers `409 message_not_waiting`. Studio's **Notifications › Log** shows each waiting message with when it goes, and takes it back.

An email, text or WhatsApp message a rule skips answers `{ message_id, skipped: true, skip_reason }` — its message is in the log; one the user's preferences turned off answers `{ skipped: true }` alone, and nothing was queued. A skipped text does not count against its number's one text a minute and ten a day.

## To an audience

`to: { audience: "<id>" }` sends a push to each member of an analytics audience once ([Analytics › Audiences](/docs/web/analytics#audiences)): a member who signed in, as their user; one who never did, on each install of theirs. Each member's push keeps to their own clock, quiet hours, the cap and what they allowed, like a send to them alone. The audience's members are taken as the send is worked through, so a push to a large audience goes out over a little while rather than in one burst.

A push to an audience or a topic with `schedule.at` waits whole until that moment and is spread then; with `schedule.local_time` it is spread at once, each member's push waiting for their own hour. Either way, taking back the push (`POST /notify/messages/{id}/cancel`, its own id) takes it back whole: its spreading stops, and every member's push still waiting goes with it.

## Consent, İYS and texts that say stop

What a person allowed in the app ([consent](/docs/web/analytics#consent)) holds for messages too: a send that is not transactional to someone who refused this channel's marketing — `marketing_push`, `marketing_email`, `marketing_sms`, `marketing_whatsapp` — is skipped (`consent`).

**A text that says stop.** Point your Twilio number's "A message comes in" webhook at `https://<ref>.<domain>/notify/webhooks/sms/twilio/inbound`. A text that is `STOP`, `STOPALL`, `UNSUBSCRIBE`, `CANCEL`, `END` or `QUIT` alone, or `DUR`, `İPTAL`, `IPTAL` or `RET` alone or with one word after it (your brand: `RET ACME`), in any case, is the refusal — "Cancel my order" is a question, not a refusal — of marketing texts of the user whose verified phone number sent it: recorded as their choice (`marketing_sms`, source `sms_stop`), it reaches their apps and your backend as any choice does, and their next marketing text is skipped. Twilio signs each call with your auth token and an unsigned one is refused; nothing is replied to the sender.

**İYS.** A brand that sends commercial messages in Turkey must hold each recipient's consent in İYS (İleti Yönetim Sistemi). Give notify your brand's own İYS API user — `putNotifyProvider({ path: { channel: "iys", provider: "iys" }, body: { credentials, priority: 0, active: true } })`, with `credentials` `{ username, password, iys_code, brand_code, recipient_type }` (`recipient_type` is `BIREYSEL` unless your recipients are traders, `TACIR`) — and then:

- a text to a Turkish number (`+90…`) or an email that is not transactional goes only where İYS holds an `ONAY`; one it does not is skipped (`iys`), and so is one İYS refuses to answer about as it stands. İYS out of reach, the message waits and is tried again. A number abroad is not İYS's, and is not asked about.
- each choice a user makes of `marketing_sms` or `marketing_email` from then on — in the app, by a stop text, through your server — is written to İYS as `ONAY` or `RET`, with where it was made (`HS_MOBIL` in the app, `HS_MESAJ` by a text, `HS_EPOSTA` by an email's link, `HS_CAGRI_MERKEZI` through your support), for their verified Turkish number (`+90…`) or their verified address. The choice holds for your messages at once; İYS is told by a job of your project's, tried again for about three days while İYS is out of reach.

Palbase is not an İYS integrator: the account is yours, and İYS's records are your brand's.

## SMS, codes and WhatsApp

| Call | What it does |
|---|---|
| `sendSms({ body: { to, body } })` | A text to one number in E.164 form (`+14155551212`): a body, or a `template` with `variables`. A number gets one text a minute and ten a day. It answers the segments and encoding the text takes. |
| `startVerification({ body: { to } })` | Has your verification service generate a one-time code and text it. |
| `checkVerification({ body: { to, code } })` | `{ approved }`: whether the code is the one it sent. |
| `sendWhatsApp({ body: { to, template_slug, variables } })` | A WhatsApp message: a text inside a conversation the user opened in the last 24 hours, a template approved on your Meta account, or one of your slugs. |

The project's message settings say where texts may go: `putNotifySettings` sets the default locale, the sender of email through your own provider, the countries texts may (`sms_countries`) and may not (`sms_blocked_countries`) reach, and the send rules ([When a message goes](#when-a-message-goes)).

## Reports

`listNotifyMessages({ query })` answers the project's messages, newest first — their delivery reports, never what they said — filtered by channel, status, user, category or a window. `getNotifyMessage({ path: { id } })` reads one: its status, attempts, provider, and what the provider reported after it left (delivered, bounced, opened …) when its credential lets it report — and, a push, how it went on each device and when it got to each stage. `getMetricsSummary()` counts them per channel, status and day. Studio's **Notifications** screens show the same reports, devices and metrics.

## The `Notifications` service

A backend sends with `Notifications`, and each send answers `{ data, error, status }`:

- `Notifications.email.send({ to, subject?, html?, text?, templateSlug?, locale?, variables?, from?, reply_to?, category? })` — `to` one address, or several: one message each, in order, the first refusal ending them.
- `Notifications.push.send({ to, title?, body?, data?, deep_link?, category?, priority?, … })` — `to` a user's id, several, or `{ topic }`.

```ts
// src/modules/invites/invite-mail.service.ts
import { Injectable, Log, Notifications } from "palbase/backend";

@Injectable()
export class InviteMail {
  async send(to: string, link: string): Promise<boolean> {
    const { error } = await Notifications.email.send({ to, subject: "You're invited", html: `<a href="${link}">Join</a>`, category: "invite" });
    if (error) Log.warn("the invitation was not sent", { code: error.code });
    return error === null;
  }
}
```

## Journeys

A journey sends a person messages over time after something they did — a welcome over their first week, a win-back after they stopped buying — with waits, branches and A/B splits between them: [Journeys](/docs/backend/journeys).

## Related

- [Webhooks](/docs/server/webhooks) — `notification.sent`, `notification.failed`, `notification.received`, `notification.uninstalled`, `notification.push_failing`
- [Analytics](/docs/web/analytics#audiences) — the audiences a push can go to, and each person's consent
- [Server SDK Overview](/docs/server/overview) — calls, refusals, retries and `Idempotency-Key`
- [Secrets](/docs/backend/secrets) — the values your own code reads (a provider's credentials are kept by notify, sealed)
- [Test Users](/docs/backend/test-users) — users to send to while you try a flow



<!-- ===== backend/journeys ===== -->

# Journeys

A journey takes each person who does something — signs up, stops opening the app, buys, joins an audience — through the steps you set: messages, waits, branches, A/B splits, coupons and grants. It is built in Studio's **Journeys** or kept as a JSON file and handled with the CLI, tried on a test user, published, and then reported on: who entered, what each step came to, how many reached its goal.

Journeys are the project's server's: their API takes the secret key (or a member's session in Studio), never the publishable key.

## Quick example

A journey that welcomes a new user, checks a day later whether they finished setting up, and A/B tests the reminder for those who did not:

```json
{
  "name": "Onboarding",
  "entry": { "event": { "name": "sign_up" } },
  "goal": { "event": { "name": "onboarding_completed" }, "within": "P7D" },
  "start": "welcome",
  "steps": {
    "welcome": { "inbox": { "title": { "en": "Welcome aboard" }, "body": { "en": "Here is how to get the most out of the app." } }, "next": "wait_1d" },
    "wait_1d": { "wait": { "for": "P1D" }, "next": "finished" },
    "finished": { "branch": { "if": { "event": { "name": "onboarding_completed" } }, "then": "end", "else": "tip" } },
    "tip": { "split": [{ "name": "push", "weight": 50, "next": "tip_push" }, { "name": "inbox", "weight": 50, "next": "tip_inbox" }] },
    "tip_push": { "push": { "title": { "en": "One step left" }, "body": { "en": "Finish setting up in under a minute." } }, "next": "end" },
    "tip_inbox": { "inbox": { "title": { "en": "One step left" }, "body": { "en": "It is all in one place." } }, "next": "end" }
  }
}
```

```bash
palbase journeys:validate onboarding.json            # every problem, at its path, with what to do about it
palbase journeys:push onboarding.json --publish      # save it as a draft (key: the file's name) and publish it
palbase journeys:stats onboarding                    # who entered, each step, the goal's conversions, each A/B way
```

## A journey

A definition has who enters (`entry`), the steps by id with the first one (`start`), what the journey is for (`goal`), what takes a person out early (`exit`) and whether a person enters again (`reentry`). Each step does one thing and names the step after it in `next`; `end`, or no `next`, ends the person's run. A person is in a journey once at a time.

| Who enters (`entry`, one of) | |
|---|---|
| `event: { name, where }` | A person who does the event — an app's own (`sign_up`), or a module's: `purchases.purchase.completed`, `purchases.coupon.redeemed`, `audience.entered` — with the properties `where` names, each equal. |
| `audience: "<id>"` | A person who comes to be in an analytics audience. |
| `inactive: { event, for }` | A person who has not done the event for a while (1 hour to 90 days): the moment it passes since their last one. `$session_start` is someone who has not opened the app. |
| `members_of: "<id>"` | An audience's members, once, as the journey is published. |

`goal: { event, within }` — a run that sees the event within `within` of entering (30 days unless it says, 90 at most) ends **converted**; a run that completed before it is counted converted too. `exit: { events, audience_left }` takes a person out when they do one of the events or leave the audience. `reentry.mode` is `once` (the default: never again), `always` (each time, once their run ended) or `after` (once `after` has passed since they last entered). Whatever it says, a person enters one journey 20 times a day at most, so a journey whose own steps cause its entry event does not loop.

Durations are ISO 8601: `PT30M`, `PT2H`, `P2D`, `P1W`.

## Steps

| Step | What it does |
|---|---|
| `push` | A push to the person's devices: `title` and `body` by locale (`en`, `tr`, `pt-BR`), or one of the project's push `template`s; `deep_link`, `image`, `data`, `category`; `inbox: true` keeps a copy in their inbox. |
| `inbox` | A message in the person's inbox: `title` and `body` by locale, `deep_link`, `image`, `expires_in_days`. |
| `email` | An email from one of the project's email templates, with its `variables`. |
| `in_app` | One of the project's in-app campaigns made for journeys, shown the next time it is triggered in their app (waiting up to `days`, 7 unless it says). |
| `coupon` | Gives the person their code of one of the project's coupons; `{{coupon}}` in the messages after it is that code. |
| `offer` | Gives the person one of the catalog's grant offers: an entitlement for a while. |
| `set` | Writes properties of the person's (analytics' people): 1 to 20. |
| `event` | Tells your backend: a `journey.event` with the step's `name` and `data` — a webhook, or an `@On`. |
| `wait` | Holds the person: `for` a while (1 minute to 90 days), `until` a time of day where they are (`"09:00"`, in their `$timezone`), or until they do an `event`, at most `timeout` — then `next`, or `timeout_next` when it timed out. |
| `branch` | Sends the person to `then` when `if` holds of them, else to `else`. A condition asks a `property` of theirs (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `exists`, `missing`), whether they are in an `audience`, whether they did an `event` (since entering, or `within` a while), or `all`, `any` or `not` of others. |
| `split` | An A/B split: 2 to 5 ways whose `weight`s add up to 100. Each person takes one way by chance — the same one every time — and the report counts each way's conversions. |

A message step is sent by the project's send rules ([Notifications › When a message goes](/docs/backend/notifications#when-a-message-goes)): quiet hours, the marketing cap and what the person allowed. A message they did not allow is skipped and the run goes on. A journey has 100 steps at most, every one reachable from `start`, and no way back to a step already taken but through a wait.

## From your backend

A step your backend sees — a document approved, a first upload — moves a journey when your server tells it as the user's event: `POST /analytics/capture` with the secret key and `user_id`. It enters them into a journey of that event, takes them past a wait for it, counts toward a goal, and answers a branch that asks whether they did it, as an event their app sent would.

```bash
curl -s -X POST "https://<ref>.palbase.studio/analytics/capture" \
  -H "apikey: $PALBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "crew_verified", "user_id": "usr_123", "properties": {"airline": "TK"}}'
```

## In Studio

**Journeys** lists the environment's journeys with their status and who enters. **New journey** starts one from a template — *Onboarding*, *Win back* (a customer who has not bought for 30 days) or *Didn't come back* (a user who has not opened the app for a week) — or from a blank page.

A journey's page draws it top to bottom: who enters at the top, each step under the one before, a branch's or a split's ways side by side until they meet, the goal at the bottom. A step opens its form in the side panel; the **+** between two steps adds one there. The module checks the draft a moment after each change, and each problem shows under the field it is about (`steps.welcome.inbox.title.en` under the welcome step's English title) and in the problems list, which takes you to it. **JSON** shows the definition the CLI pushes; a change there is the flow. **Preview** walks a made-up person through what is on screen — their properties, audiences, time zone and what they do after entering — and shows each step they would take and when; nothing is sent.

## Trying a journey on a test user

`POST /journeys/{key}/test` with `{ "user_id": "…" }` runs the saved journey — a draft too — for one of the project's [test users](/docs/backend/test-users) from its first step. Its messages really go to that user, each wait is a minute long, and the try is counted in no report and no month's people; its `journey.*` events carry `test: true`. Studio's **Try on a test user** does the same, and follows the run beside what landed in the person's inbox. A user who is not a test user is refused (`422 not_a_test_user`), and so is a stopped journey (`409 journey_stopped`). A new try of the same journey ends that user's try still running.

## Publishing, stopping and copying

`POST /journeys/{key}/publish` makes a draft live: people enter it from then on (a `members_of` journey enrolls the audience's members now). A live journey does not change (`409 journey_published`): copy it into a new draft (`POST /journeys/{key}/copy` with `{ "key": "…", "name": "…" }`), publish that, and stop the old one. `POST /journeys/{key}/stop` lets no one in any more and ends the runs in it; its report stays. `DELETE /journeys/{key}` deletes a journey with its runs and its report.

A project keeps 500 journeys and runs 50 at once. An environment without its paid rights — on Free, out of credit, or at its monthly limit — runs 2 at once (`402 live_journeys_limit`); on Pay as you go, the people who enter its journeys are billed by the month ([Billing](/docs/getting-started/billing)): the first 1,000 people a month are free, then $2 for each 1,000 more.

## The report

`GET /journeys/{key}/stats` answers who entered (`entered`), how many reached the goal (`converted`), who is in it now (`in_progress`: `active`, `waiting`, `held`), how the runs ended (`ended`: `completed`, `converted`, `exited`, `stopped`, `failed`, `erased`), each step's outcomes from the start (`steps[].outcomes`: `sent`, `skipped`, `waited`, `then`, `else`, a split's way …) and, for a split, each way's conversions (`steps[].converted`). `GET /journeys/{key}/runs` pages each person's run — its state, the step it is at, each step it took and what came of it — filtered by `user_id` or `state`; `GET /journeys/people/{user_id}` is one person's runs in every journey. Studio's **Report** shows the same.

People who enter while the organization's monthly people are used up are held (`held`) until it has them again.

## Events

Each run tells the project's backend as it goes — a [webhook](/docs/server/webhooks#the-events), or an `@On`:

| Type | Sent when |
|---|---|
| `journey.entered` | A person entered a journey. |
| `journey.step` | A person's run took a step. |
| `journey.event` | A journey's `event` step told the project's backend. |
| `journey.converted` | A person's run reached the journey's goal. |
| `journey.ended` | A person's run ended: completed, converted, exited, stopped. |

## The API

| Call | What it does |
|---|---|
| `GET /journeys` | The project's journeys, newest first: `status`, `limit`, `cursor`. |
| `POST /journeys` | A new draft: `{ key, definition }`. |
| `GET /journeys/{key}` | A journey whole, with its definition. |
| `PUT /journeys/{key}` | A draft's definition, written whole: `{ definition }`. |
| `DELETE /journeys/{key}` | Deletes it with its runs and its report. |
| `POST /journeys/validate` | Every problem of a definition, each at its path: `{ definition }` → `{ valid, problems }`. Nothing is kept. |
| `POST /journeys/simulate` | A made-up person's way through a journey — the project's (`key`) or one not saved (`definition`) — with each step and when. Nothing is sent. |
| `POST /journeys/{key}/test` | Tries the saved journey on a test user: `{ user_id }`. |
| `POST /journeys/{key}/publish` | Makes a draft live. |
| `POST /journeys/{key}/stop` | Stops a live journey. |
| `POST /journeys/{key}/copy` | Copies a journey into a new draft. |
| `GET /journeys/{key}/stats` | Its report. |
| `GET /journeys/{key}/runs` | Each person's run. |
| `GET /journeys/people/{user_id}` | One person's runs in every journey. |

```bash
curl -s -X POST "https://<ref>.palbase.studio/journeys/onboarding/test" \
  -H "apikey: $PALBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "usr_test_1"}'
```

## From the CLI

A journey is kept as a file and handled with the CLI: saved as a draft, published, then followed.

```bash
palbase journeys:validate winback.json             # every problem, at its path, with what to do about it
palbase journeys:simulate winback.json --event purchases.purchase.completed@P1D   # walk a made-up person through it; nothing is sent
palbase journeys:push winback.json --publish       # save it as a draft (key: the file's name) and publish it
palbase journeys                                   # the environment's journeys: key, name, status, way in
palbase journeys:stats winback                     # who entered, how their runs ended, the goal's conversions
palbase journeys:runs winback                      # each person's run: its state, the step it is at
palbase journeys:stop winback                      # no one enters it any more, the runs in it end
```

`journeys:get` prints a journey's definition to edit and push again, `journeys:copy` copies one into a new draft, `journeys:publish` publishes a draft, and `journeys:delete` deletes one with its runs and its report. Every command is in the [CLI reference](/docs/cli/reference#journeys).

## Related

- [Notifications](/docs/backend/notifications) — the send rules a journey's messages keep to, push templates and inboxes
- [Analytics › Audiences](/docs/web/analytics#audiences) — the audiences a journey enters people from, and asks about
- [Test Users](/docs/backend/test-users) — the users a journey is tried on
- [Webhooks](/docs/server/webhooks) — `journey.entered`, `journey.step`, `journey.event`, `journey.converted`, `journey.ended`



<!-- ===== backend/realtime ===== -->

# Realtime

Every project has realtime: **channels** its clients join over one socket, a **broadcast** on a channel that reaches every subscriber, and a **shared state** per channel — keyed entries every subscriber with state access reads, a snapshot when it joins and the changes after. Clients join and listen ([Web Realtime](/docs/web/realtime)). Your backend publishes as the project's server, with the secret key: `Palbase.realtime` in a `palbase/backend` app, `createServer(…).realtime` anywhere else. Who may join which channel is the project's [channel declaration](/docs/backend/channels).

## Quick example

```ts
// src/modules/orders/live.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class OrderLive {
  /** Tells the order's owner, on their own channel, that its status changed. */
  async statusChanged(userId: string, orderId: string, status: string): Promise<void> {
    await Palbase.realtime.broadcast({
      body: { messages: [{ topic: `orders:${userId}`, event: "status", payload: { orderId, status } }] },
    });
  }
}
```

With `orders:{uid}` declared as an `owner` channel ([Channels](/docs/backend/channels)), the signed-in user — and only they — joins `orders:<their id>` and hears it as a `broadcast`:

```ts
// watch.ts
import { createClient } from "palbase/web";

const pb = createClient({ url: "https://<ref>.palbase.studio", publishableKey: "pb_<ref>_c…" });

export async function watch(userId: string, onStatus: (change: unknown) => void): Promise<() => void> {
  const channel = pb.socket.channel(`orders:${userId}`);
  const off = channel.on("broadcast", (frame) => {
    if (frame.event === "status") onStatus(frame.payload);
  });
  await channel.join(); // refused unless the declaration lets this user join
  return () => {
    off();
    channel.leave();
  };
}
```

## Broadcast

`POST /realtime/broadcast` publishes 1 to 100 events in one call, each `{ topic, event, payload }`:

| Field | What it is |
|---|---|
| `topic` | The channel's name, such as `orders:usr_123` — without the `realtime:` prefix the socket carries. |
| `event` | The event's name, which the client reads as the frame's `event`. |
| `payload` | Any JSON. |

It answers `202` with how many were published. A broadcast reaches every subscriber on every replica of realtime, but the one that sent it — and the server is no subscriber, so a server broadcast reaches them all.

**A broadcast is delivered at most once.** A client that was not on the channel at that moment — offline, reconnecting, not joined yet — does not get it later, and nothing is kept. That makes a broadcast a *nudge*: "order 42 changed, look again". What a client must not miss belongs in your database, or in the channel's state.

## Revalidate

`POST /realtime/revalidate` asks every replica to decide again, now, who may be on channels whose decision may no longer hold, and drops the members who may not. It names one channel (`topic`), or every channel of a pattern whose named parameters have the values given (`pattern` and `params`), and optionally one user's memberships alone (`user`). With a `topic` and no `user`, `end: true` ends the channel instead: every member is dropped without being asked, and what a durable channel kept is forgotten. It answers `202`. A dropped member's client is told the channel closed, and its rejoin is decided on the merits. Without it, a decision holds until the user's token runs out, fifteen minutes at most.

## Shared state

Each channel has a keyed state that outlives any one connection. Your backend writes it with `POST /realtime/state`, 1 to 100 operations a call:

```ts
// src/modules/boards/board-state.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class BoardState {
  async setCard(boardId: string, cardId: string, card: { title: string; column: string }): Promise<void> {
    await Palbase.realtime.writeState({ body: { ops: [{ topic: `board:${boardId}`, key: cardId, value: card }] } });
  }

  async removeCard(boardId: string, cardId: string): Promise<void> {
    await Palbase.realtime.writeState({ body: { ops: [{ topic: `board:${boardId}`, key: cardId, delete: true }] } });
  }
}
```

- **Durable.** Entries the server writes stay until they are removed. A subscriber that joins gets the whole state (a `state_snapshot` frame), then what changed as it changes (`state_diff`); a client that lost the thread asks for it all again (`state_resync`).
- **Small.** A value is any JSON, 16 KiB at most, and each channel has a budget: a write past it is refused with `422`, and the operations before it in the call stay applied.
- **Read by subscribers with state access.** Who has it is the declaration's `state_read` (and who may write from the client, `state_write`) — see [Channels](/docs/backend/channels).

Clients may also write **ephemeral** entries — their own presence — which are gone when they leave.

## Limits

`getLimits()` reads the limits the project holds its clients to, and the platform's above them; `putLimits({ body })` sets them: connections open at once (`max_connections`), broadcasts and state writes per second (`max_events_per_second`), joins per second (`max_joins_per_second`), and channels on one connection (`max_channels_per_connection`). `null` is the platform's own, and a value above the platform's has no effect beyond it. Studio's **Realtime** screen shows and sets the same limits, and can send a test message.

## The socket, from the client's side

The socket is `GET /realtime/v1/websocket` at the project's address — Phoenix Channels v2 frames, one socket per client for every channel it is on. The publishable key opens it; a client says who it is with the access token each join carries, so the user's rights on a channel are decided per join and again when the declaration changes. The web SDK speaks it for you (`pb.socket`): it opens on the first join, sends a heartbeat every 25 s, reconnects with growing pauses, and joins its channels again after a drop.

Your backend never subscribes: `palbase/server` has no socket. What a client sends that the server must act on is a call to one of your backend's routes.

## Channel names

A channel is `:`-separated segments: `orders:<user_id>`, `board:7f3a`, `game:42:chat`, 255 bytes at most. The namespaces `roles:`, `flags:`, `messaging:` and `debug:` are the platform's — flags' live updates travel on `flags:<ref>` and `flags:<ref>:<user_id>`, a user's permission set on `roles:<ref>:<user_id>`. A channel the declaration does not match belongs to no one, and no client may join it.

## The `Realtime` service

A backend broadcasts with `Realtime`: `Realtime.broadcast(channel, event, payload?)`, and a channel's state with `Realtime.state.set(channel, key, value)` and `Realtime.state.clear(channel, key)`. Each answers `{ data, error, status }`: the platform taking it, not every subscriber receiving it; it never fails the handler.

```ts
// src/modules/projects/project-signal.service.ts
import { Injectable, Realtime } from "palbase/backend";

@Injectable()
export class ProjectSignal {
  async changed(projectId: string, what: string): Promise<void> {
    await Realtime.broadcast(`project:${projectId}`, what, {});
  }
}
```

## Related

- [Gateways](/docs/backend/gateways) — a `palbase/backend` app's own realtime channels
- [Channels](/docs/backend/channels) — who may join, publish and write state
- [Web Realtime](/docs/web/realtime) — joining and listening in the browser
- [Server SDK Overview](/docs/server/overview) — calls, refusals and retries
- [Flags](/docs/backend/flags) — the live updates that ride the same socket



<!-- ===== backend/gateways ===== -->

# Gateways

A gateway is a realtime channel of your app: a class marked `@Gateway(pattern, options)` and listed in a module's `providers`. Its pattern names the channels it is: `room:{roomId}` is the gateway of `room:42`, `room:43`, …, each a channel of its own. The class says who may join, the events it sends, the messages its members may send and the ack each one is answered with, and it is told when a channel fills and when it empties.

A gateway is the one way an app talks realtime to your backend. `palbase apps:sync` writes each app a typed client of the backend's gateways ([Web Gateways](/docs/web/gateways)): the app joins `RoomGateway` with `{ roomId }`, and writes no channel name, event name or payload type of its own.

## Quick example

The rooms, and who is in each:

```ts
// src/modules/rooms/rooms.service.ts
import { Injectable } from "palbase/backend";

export interface RoomMessage {
  id: string;
  from: string;
  text: string;
}

// Kept in memory to keep the example small; a real app keeps its rooms in its database.
@Injectable()
export class RoomsService {
  private readonly members = new Map<string, Set<string>>();

  add(roomId: string, userId: string): void {
    this.members.set(roomId, (this.members.get(roomId) ?? new Set()).add(userId));
  }

  isMember(roomId: string, userId: string): boolean {
    return this.members.get(roomId)?.has(userId) === true;
  }

  post(from: string, text: string): RoomMessage {
    return { id: crypto.randomUUID(), from, text };
  }
}
```

The gateway:

```ts
// src/modules/rooms/room.gateway.ts
import { Authorize, Gateway, GatewayRefusal, OnConnect, Subscribe, z } from "palbase/backend";
import type { GatewayAuthorizeContext, GatewayContext, GatewayGrant, GatewayMessageContext } from "palbase/backend";
import { RoomsService } from "./rooms.service";

export const Say = z.object({ text: z.string().min(1).max(2000) });
export const Said = z.object({ id: z.string() });
export const Message = z.object({ id: z.string(), from: z.string(), text: z.string() });
export const Welcome = z.object({ members: z.number() });

// room:<id>, one channel per room. Its members hear `message`; they send `say`.
@Gateway("room:{roomId}")
export class RoomGateway {
  static readonly events = { message: Message, welcome: Welcome };

  constructor(private readonly rooms: RoomsService) {}

  // Who may join: the room's members, and no one else.
  @Authorize()
  enter(ctx: GatewayAuthorizeContext): GatewayGrant {
    return this.rooms.isMember(ctx.params.roomId, ctx.user.id);
  }

  // Said to the member who joined, alone.
  @OnConnect()
  joined(ctx: GatewayContext): void {
    ctx.emit("welcome", { members: ctx.count });
  }

  // A member's message, checked against Say before this runs. What it returns is the member's ack.
  @Subscribe("say", Say, { reply: Said })
  say(ctx: GatewayMessageContext<z.infer<typeof Say>>): z.infer<typeof Said> {
    if (ctx.payload.text.startsWith("/")) throw new GatewayRefusal("no_commands");
    const message = this.rooms.post(ctx.user.id, ctx.payload.text);
    ctx.emit("message", message);
    return { id: message.id };
  }
}
```

A route that makes the user a member, and one that posts to a room from outside it:

```ts
// src/modules/rooms/rooms.controller.ts
import { Body, Controller, Forbidden, Palbase, Param, Post, User, type UserT } from "palbase/backend";
import { RoomGateway, Say } from "./room.gateway";
import { RoomsService } from "./rooms.service";

@Controller("/rooms")
export class RoomsController {
  constructor(private readonly rooms: RoomsService) {}

  // From now on the gateway lets this user into room:<roomId>.
  @Post("/{roomId}/members")
  join(@Param("roomId") roomId: string, @User() user: UserT): void {
    this.rooms.add(roomId, user.id);
  }

  // A message posted over HTTP reaches the room's members as one said in it.
  @Post("/{roomId}/messages")
  post(@Param("roomId") roomId: string, @Body(Say) body: { text: string }, @User() user: UserT): { id: string } {
    if (!this.rooms.isMember(roomId, user.id)) throw new Forbidden("not a member of this room");
    const message = this.rooms.post(user.id, body.text);
    Palbase.gateways.to(RoomGateway, { roomId }).emit("message", message);
    return { id: message.id };
  }
}
```

```ts
// src/modules/rooms/rooms.module.ts
import { Module } from "palbase/backend";
import { RoomGateway } from "./room.gateway";
import { RoomsController } from "./rooms.controller";
import { RoomsService } from "./rooms.service";

@Module({ controllers: [RoomsController], providers: [RoomsService, RoomGateway] })
export class RoomsModule {}
```

A gateway is a provider like any other: its module lists it in `providers`, it takes its dependencies by constructor, and it is built once, so what one method starts another can stop. A `@Gateway` that no module lists stops the boot by name, and so does a class that is both a controller and a gateway.

## Options

| Option | What it is | Default |
|---|---|---|
| `access` | Who may join, with no method of yours: `"owner"`, the signed-in user whose id the pattern's one `{param}` is; `"public"`, any signed-in user. Left out, an `@Authorize` method decides. | none |
| `durable` | Keeps what it sends: `true` for a day, or `{ keepSeconds }` from 1 to 604800 (a week). See [Durable gateways](#durable-gateways). | not kept |
| `graceMs` | How long the channel is held after its last member left before it is empty (`@OnEmpty`), in milliseconds. | 60000 |
| `publish` | Its members may broadcast to one another on the channel. A gateway with no method only: one with methods takes its members' messages itself (`@Subscribe`). | `false` |
| `chat` | It carries a chat of the project's agents: its event `chat` is the platform's, and every generated client holds the chat's state. Kept a day unless `durable` says how long. See [AI](/docs/backend/ai#a-chat-in-an-app). | `false` |

Who may join is said once: `access` or an `@Authorize` method, never both and never neither. The boot refuses either mistake by name.

## Patterns

A pattern is `:`-separated segments, as a channel's name is. A segment written `{name}` takes exactly one non-empty segment of the channel, and the method is given it in `ctx.params`. Any other segment matches itself.

| Pattern | Its channels | Not its channels |
|---|---|---|
| `lobby` | `lobby` | `lobby:2` |
| `room:{roomId}` | `room:42` | `room`, `room:42:chat` |
| `game:{gameId}:team:{team}` | `game:7:team:red` | `game:7:team` |

A pattern is 255 bytes at most, has no `/` and no control character, and names each `{param}` once. The namespaces `roles:`, `flags:`, `messaging:` and `debug:` are the platform's. A pattern that breaks one of these rules is refused when its class is declared.

When two of an app's patterns match one channel, the more specific one decides it: a named segment beats a `{param}`, from the left, so `lobby:staff` decides `lobby:staff` and `lobby:{id}` every other lobby. Two gateways of the same channels (`room:{roomId}` and `room:{id}`) are refused at boot. Two of the project's machines that declare the same channels have neither: the channel is refused until one of them gives it up.

The class's name is the gateway's name in every generated client (`RoomGateway`), so it is an identifier and one of a kind in the app.

## Who may join

Only a signed-in user joins a gateway. The access token the client's socket carries is who they are.

With `access: "owner"`, the pattern's one `{param}` must be the joining user's id: `inbox:{userId}` is joined by that user alone. With `access: "public"`, any signed-in user of the project joins. Either way no code of yours decides it.

Otherwise its `@Authorize` method decides, at each join. It is given the user and the channel's parameters, and it runs as that user, in a transaction of its own: `Database` is theirs, and [row-level security](/docs/backend/row-level-security) holds. It answers a grant:

| Answer | Means |
|---|---|
| `true` | In, to hear and to send. |
| `{ write: false }` | In, to hear. A message they send is refused (`forbidden`). |
| `{ read: false }`, `false`, `null`, `undefined` | Not in. |

Anything else lets no one in: `{}`, a row, a number, or `{ read: member?.canRead }` when there is no member (`undefined` is no answer). So does a method that throws. Each of these is in the app's log, without the value it answered. A refused join reaches the client as `unauthorized`; a join the app could not be asked about, as `unavailable`, which is worth trying again.

A grant holds until the user's token runs out, fifteen minutes at most — a minute for a gateway declared with `chat: true` — and then `@Authorize` is asked again. When a decision stops being true before that (a member taken off a team, a document unshared), say so: `POST /realtime/revalidate` with the secret key, naming the channel (`{ "topic": "board:42" }`) or a pattern's channels by some of their parameters (`{ "pattern": "board:{boardId}:user:{userId}", "params": { "userId": "usr_…" } }`), optionally one user's memberships alone (`"user"`). Every replica asks `@Authorize` again for those memberships at once, and a member it no longer lets in is told the channel closed; their rejoin is refused. A chat gateway needs none of this: the platform revalidates its channel itself when a member is taken out of the chat, and ends it when the chat is deleted.

## Events

What a gateway sends is declared on its class: `static readonly events = { name: schema }`, each a [Standard Schema](https://standardschema.dev) of the payload. The generated clients type each event by it.

From a gateway's own methods, `ctx.emit(event, payload)` sends to every member of the channel. In `@OnConnect` it sends to the member who joined, and no one else. From anywhere else in the app (a route, a service, a [task](/docs/backend/tasks), an [`@On`](/docs/backend/hooks)) `Palbase.gateways.to(Gateway, params)` names one channel, and its `emit` is typed by the gateway's events:

```ts
// src/modules/rooms/room-notices.service.ts
import { Injectable, Palbase } from "palbase/backend";
import { RoomGateway } from "./room.gateway";

@Injectable()
export class RoomNotices {
  /** The room hears it as a message from no one in particular. */
  closingSoon(roomId: string, minutes: number): void {
    Palbase.gateways.to(RoomGateway, { roomId }).emit("message", { id: crypto.randomUUID(), from: "", text: `This room closes in ${minutes} minutes.` });
  }
}
```

- **In order.** Events to one channel are sent in the order they were emitted. Those emitted while one is on its way go together in the next send.
- **Never thrown.** `emit` returns at once and does not fail the method. An event the gateway does not declare, or a payload that is not JSON, is not sent, and the app's log says so. So is an event that could not be sent.
- **At most once,** unless the gateway is [durable](#durable-gateways): a member that was not on the channel when an event was sent does not get it later.

A member hears only what the gateway sends. Members' own messages go to the backend, never to one another: what the others should hear, the method emits.

## Messages and acks

`@Subscribe(name, schema, { reply })` marks the method that takes one message its members send. The payload is checked against `schema` before the method runs. One that does not fit never reaches it, and the member is told the schema's issues.

The method is given a `GatewayMessageContext`: the channel, its `params`, the member as `ctx.user`, and the payload as the schema made it (`ctx.payload`). It runs as the member, in a transaction of its own, committed when it returns and rolled back when it throws. What it returns is the member's **ack**, which their `send` resolves with. `reply` is the ack's schema, which the generated clients type it by and which the ack is checked against.

What a member's `send` is answered:

| The method | The member is told |
|---|---|
| Returns a value | The value, as JSON carries it. Past 64 KiB, `reply_too_large`. |
| Returns nothing | `ok`, with no ack. |
| Throws `new GatewayRefusal("muted")` | The refusal, with your reason: `muted`. What the method wrote is rolled back. |
| Throws anything else | `handler_failed`. The error is in the app's log, never in the member's answer. |
| Returns an ack its `reply` refuses | `handler_failed`, and the log says why. |

A `GatewayRefusal`'s reason is a word your app acts on: `not_your_turn`, `too_many_messages`, `muted`. It is 256 bytes at most. A message the gateway does not declare is refused with its name.

## Moments

A gateway with methods is told of its channels' moments:

| Decorator | When | Runs as |
|---|---|---|
| `@OnFirst()` | The channel has a member and is held by no one. Told once, however many members come at once, and before the first of them is answered. | The app |
| `@OnConnect()` | A member joined, after they were answered. What it emits goes to them alone. | The member |
| `@OnDisconnect()` | A member left. | The member |
| `@OnEmpty()` | Nobody has been on the channel for its `graceMs`. | The app |

"The app" is the service role, as a [cron](/docs/backend/cron)'s work is: every row in reach. Each moment's `GatewayContext` carries `channel`, `params`, `count` (its members now), `user` (`id` is `""` in `@OnFirst` and `@OnEmpty`, which no one in particular caused), `emit`, `pipe`, `signal` and `owner`.

`ctx.signal` is the channel's own. It aborts when the channel empties, before `@OnEmpty` runs, so what `@OnFirst` started stops on it without a method to remember it. `ctx.owner.hold(work)` runs `work` past the method, until that signal aborts. A failure of it is logged, never the app's crash. `ctx.owner.release()` gives the channel up at once: its signal aborts, and the next member to come finds it held by no one, so `@OnFirst` runs again.

```ts
// src/modules/prices/prices.gateway.ts
import { Gateway, Log, OnEmpty, OnFirst, z } from "palbase/backend";
import type { GatewayContext } from "palbase/backend";

export const Tick = z.object({ symbol: z.string(), price: z.number() });

// prices:<symbol>: a price read from the exchange only while someone watches it.
@Gateway("prices:{symbol}", { access: "public", graceMs: 30_000 })
export class PricesGateway {
  static readonly events = { tick: Tick };

  // The first watcher came: read the price every second until the channel empties.
  @OnFirst()
  open(ctx: GatewayContext): void {
    const symbol = ctx.params.symbol;
    ctx.owner.hold(async (signal) => {
      while (!signal.aborted) {
        const res = await fetch(`https://quotes.example.com/v1/${encodeURIComponent(symbol)}`, { signal });
        const { price } = (await res.json()) as { price: number };
        ctx.emit("tick", { symbol, price });
        await new Promise((resolve) => setTimeout(resolve, 1000));
      }
    });
  }

  // Thirty seconds with nobody watching: the loop above has stopped already.
  @OnEmpty()
  closed(ctx: GatewayContext): void {
    Log.info("nobody watches", { symbol: ctx.params.symbol });
  }
}
```

A moment whose method throws is told again 1, 5 and 15 seconds later. A join or a leave told again is run once.

## Durable gateways

A durable gateway keeps what it sends: every event is kept and numbered as it is sent, for a day (`durable: true`) or for `{ keepSeconds }`, a week at most. A member that comes back, a phone that walked out of range or a socket that dropped, is sent everything after the last event it had, in order and once. A member that joins is sent what the gateway keeps first, unless it asks for only what comes next ([Web Gateways](/docs/web/gateways#durable-gateways)).

```ts
// src/modules/orders/order-updates.gateway.ts
import { Gateway, z } from "palbase/backend";

export const Status = z.object({ orderId: z.string(), status: z.enum(["paid", "packed", "shipped", "delivered"]) });

// orders:<user id>: a user's own order updates, kept a week.
@Gateway("orders:{userId}", { access: "owner", durable: { keepSeconds: 604_800 } })
export class OrderUpdates {
  static readonly events = { status: Status };
}
```

```ts
// src/modules/orders/order-status.service.ts
import { Injectable, Palbase } from "palbase/backend";
import { OrderUpdates } from "./order-updates.gateway";

@Injectable()
export class OrderStatus {
  shipped(userId: string, orderId: string): void {
    Palbase.gateways.to(OrderUpdates, { userId }).emit("status", { orderId, status: "shipped" });
  }
}
```

Every event delivered to a member counts toward the project's realtime messages, the ones sent again to a member that came back included. What a project's durable gateways keep is bounded: an event past the bound is not kept or sent, and the app's log says so. Keep a durable gateway for what members must not miss while they are away. What must outlive the conversation belongs in your database.

## Pipes

`ctx.pipe(source)` has the platform write `source` into the gateway's channel from then on. `Palbase.gateways.to(Gateway, params).pipe(source)` does the same from anywhere in the app. The backend is not in the stream: after the call, what the source says reaches the channel's members without passing through the machine.

The source today is a chat of the project's agents, `Palbase.ai.chats.events(chatId)`, piped into a gateway declared with `chat: true`. See [AI](/docs/backend/ai#a-chat-in-an-app).

## A gateway with no method

A gateway that has no method, only its access, its events and perhaps `publish`, never wakes the machine. Realtime decides its joins from the app's contract alone, and `Palbase.gateways.to(…).emit` sends to it from wherever the app runs. `OrderUpdates` above is one: a user's app can hold `orders:<their id>` open all day while the machine sleeps.

A gateway with a method is the machine's. Its joins, its members' messages and its moments are signed calls the platform makes to the machine, waking it if it sleeps. A join or a message is answered within 8 seconds and a moment within 30, or realtime gives up on it: a join is then `unavailable`, and a moment is told again.

A release's gateways are what realtime goes by within 30 seconds of it serving.

## Limits

| | |
|---|---|
| A pattern, a channel, an event's or a message's name | 255 bytes |
| An ack | 64 KiB of JSON |
| A refusal's reason | 256 bytes |
| What a durable gateway keeps | a week |
| An `@Authorize` or a message, answered | within 8 seconds |
| A moment, answered | within 30 seconds |

What the project's clients may use (connections, joins and events per second, channels per connection) is set with `putLimits` ([Realtime](/docs/backend/realtime#limits)).

## On your computer

Off the platform (the app started on your computer, or in a test) nothing joins a gateway: realtime is what calls a machine about one. `Palbase.gateways.to(…).emit` sends as the app, to the project its `PALBASE_URL` names. Test a gateway's methods as plain methods of a class ([Testing](/docs/backend/testing)).

## Gateways and the channel declaration

A channel a gateway matches is the gateway's, whatever the project's [channel declaration](/docs/backend/channels) says. The declaration (`Palbase.realtime.putChannels`, Studio's **Realtime › Channels**) is the realtime module's own list, for a backend that is not a `palbase/backend` app: a server that broadcasts with the secret key ([Realtime](/docs/backend/realtime)) and channels its clients join by name. A `palbase/backend` app declares its channels as gateways.

## Related

- [Web Gateways](/docs/web/gateways): joining a gateway from an app, its events, messages and acks
- [AI](/docs/backend/ai): a chat of the project's agents, carried by a gateway
- [Realtime](/docs/backend/realtime): the project's realtime from any server
- [Modules & Dependency Injection](/docs/backend/modules): providers, and what is refused at boot



<!-- ===== backend/channels ===== -->

# Channels

> **Note:** A `palbase/backend` app declares its channels as [gateways](/docs/backend/gateways): `@Gateway` classes, typed end to end, which the generated clients join. This page is the realtime module's own declaration, `Palbase.realtime.putChannels`, for a backend that is not a `palbase/backend` app. A channel a gateway matches is the gateway's, whatever this declaration says.

A channel's name is a string a client chooses. Proving who you are says nothing about which channels are yours — a chat's `dm:alice:bob` must not be readable by every signed-in user who can spell it — so only the project says what its channel names mean. It **declares** them: a list of patterns, each saying who may join the channels it matches and what they may do there. **A channel no pattern matches belongs to no one**, and no client may join it.

## Quick example

```ts
// src/modules/realtime/channels.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class ChannelsService {
  // Declared at boot, from code: the declaration is what this code says.
  async onStart(): Promise<void> {
    await Palbase.realtime.putChannels({
      body: {
        channels: [
          // A user's own inbox: only they may join, and they may do everything on it.
          { pattern: "inbox:{uid}", kind: "owner" },
          // A board any signed-in user may watch and edit.
          { pattern: "board:{id}", kind: "public", publish: true, state_read: true, state_write: true },
          // A lobby anyone signed in may listen to, where only the server speaks.
          { pattern: "lobby", kind: "public" },
        ],
      },
    });
  }
}
```

`PUT /realtime/channels` replaces the whole declaration, in its order; `GET /realtime/channels` reads it back. Studio's **Realtime › Channels** screen edits the same list.

## Patterns

A pattern is `:`-separated segments, 255 bytes at most. A segment written `{name}` matches exactly **one** non-empty segment; any other segment matches itself.

| Pattern | Matches | Does not match |
|---|---|---|
| `lobby` | `lobby` | `lobby:2` |
| `board:{id}` | `board:7f3a` | `board`, `board:7f3a:cards` |
| `game:{id}:chat` | `game:42:chat` | `game:42`, `game::chat` |

The segment counts must be equal — so `user:{uid}` never swallows `user:42:secrets` below it — and a capture name appears once in a pattern.

## The two kinds

| Kind | Who may join | What they may do |
|---|---|---|
| `owner` | The signed-in user the pattern's **one** `{name}` names, and no one else. | Everything: listen, publish, read and write the state. |
| `public` | Any signed-in user of the project. | Listen; and what the rule grants — `publish` (broadcast on it), `state_read` (receive its state), `state_write` (write its state). |

An `owner` pattern has exactly one capture: `inbox:{uid}` is the user `uid`'s, so `inbox:usr_123` is joined by `usr_123` alone. Both kinds need a **signed-in user**: the access token each join carries is who the user is, and a client with no one signed in joins none of the project's declared channels.

Your backend is never refused: what it publishes and writes with the secret key ([Realtime](/docs/backend/realtime)) reaches every subscriber of the channel, whatever the declaration lets clients do there.

## First match wins

The declaration is matched in order, and the **first** pattern that matches a channel decides it — including deciding no:

```ts
// src/modules/realtime/rooms.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class RoomsService {
  async onStart(): Promise<void> {
    await Palbase.realtime.putChannels({
      body: {
        channels: [
          // The announcements room: everyone listens, nobody but the server speaks.
          { pattern: "room:announcements", kind: "public" },
          // Every other room: everyone may talk.
          { pattern: "room:{name}", kind: "public", publish: true },
        ],
      },
    });
  }
}
```

Put the narrow patterns before the wide ones: written the other way round, `room:{name}` would match `room:announcements` first and let everyone publish there. A channel an `owner` pattern matches for a different user is refused there and then — it does not fall through to a later pattern.

## The platform's channels

Four namespaces are the platform's and cannot be declared: `roles:`, `flags:`, `messaging:` and `debug:`. Of them, clients join:

| Channel | Who | What it carries |
|---|---|---|
| `flags:<ref>` | Any client of the project, signed in or not. | The notice that the project's flags changed ([Flags](/docs/backend/flags)). |
| `flags:<ref>:<user_id>` | That user. | The notice that their own values changed. |
| `roles:<ref>:<user_id>` | That user. | Their permission set. |

All three are read-only: only the platform writes them.

## When it changes

- **Open sockets are decided again within a heartbeat** of a new declaration: a client whose channel is no longer theirs is put off it.
- **A decision is trusted for at most 15 minutes**, or until the user's token expires if that is sooner: a revoked user, or one whose token is no longer valid, is noticed within that time.
- **A refused join** answers the client with its reason — `unauthorized` when the declaration says no, `unavailable` when it could not be read just then (worth retrying; `unauthorized` is final).

## Limits

The declaration holds **100 patterns** at most. What the project's clients may use — connections, joins and events per second, channels per connection — is set with `putLimits` ([Realtime](/docs/backend/realtime)).

## From the CLI

```sh
palbase realtime:channels:get --json > channels.json   # the declaration, as the document to edit
palbase realtime:channels:set --file channels.json     # replace it; open sockets are decided again within a heartbeat
palbase realtime:limits:set max_connections=500
palbase realtime:broadcast room:42 message '{"text":"hello"}'
```

Each entry of the file is a channel: `{"pattern": "room:{id}", "kind": "public", "publish": true, "state_read": true, "state_write": false}`, or `{"pattern": "user:{uid}", "kind": "owner"}`. See the [CLI reference](/docs/cli/reference#realtime).

## Related

- [Realtime](/docs/backend/realtime) — broadcasting and writing state from your backend
- [Web Realtime](/docs/web/realtime) — joining a channel in the browser
- [Flags](/docs/backend/flags) — what `flags:<ref>` carries
- [Authentication](/docs/backend/authentication) — the user a join's token names



<!-- ===== backend/ai ===== -->

# AI

`Palbase.ai` is the project's models and agents, from your backend. It answers one-shot questions (`ask`, `generate`, `stream`, `embed`, `image`), gives an agent tools that run on your machine, defines agents from each turn's context, and runs **chats**: conversations of the project's agents with the members your backend names. Every call is made with the app's secret key and is recorded with its cost. The models are the platform's, and nothing is configured to use them.

A model call is billed to the project, so no app makes one. There is no AI client in `palbase/web` or the mobile SDKs: an app reaches a chat through one of your backend's [gateways](/docs/backend/gateways), and asks your routes for anything else.

## Quick example

```ts
// src/modules/reviews/reviews.controller.ts
import { Body, Controller, Palbase, Post, z } from "palbase/backend";

const Review = z.object({ text: z.string().min(1).max(4000) });
const Verdict = z.object({ sentiment: z.enum(["positive", "neutral", "negative"]), summary: z.string() });

@Controller("/reviews")
export class ReviewsController {
  // A document of Verdict's shape, checked against it before it is returned.
  @Post("/verdict")
  verdict(@Body(Review) body: z.infer<typeof Review>): Promise<z.infer<typeof Verdict>> {
    return Palbase.ai.generate({
      schema: Verdict,
      instructions: "Classify the customer review and summarize it in one sentence.",
      prompt: body.text,
      model: "fast",
    });
  }
}
```

## One-shot answers

| Call | What it answers |
|---|---|
| `ask(prompt, options?)` | The answer as text. |
| `generate({ schema, prompt })` | A document of the schema's shape, checked against it. With `background: true`, the response's id at once; its end is the event `ai.response.completed` (or `ai.response.failed`, see [Event Hooks](/docs/backend/hooks)), and `result(id, schema)` reads it. |
| `stream({ prompt })` | The answer as the model writes it: `textStream`, then `text` and `response` at the end. With a `schema`, `partialObjectStream` and `object`. |
| `embed(text)`, `embed(texts)` | A vector per text, in order. `dimensions` asks for a shorter one. |
| `image({ prompt })` | Pictures, waited for. `save(bucket, path)` writes one into the project's storage. |

Each takes `instructions`, `model`, `messages` (the conversation so far, in place of `prompt`), `metadata` (labels of your own, returned with the response) and `signal`. A `model` is a role, `"fast"`, `"default"` or `"strong"`, or a catalogue model as `provider:model` (`Palbase.ai.models()`). `images` gives the question up to 4 pictures, each a file of the project's storage (`{ bucket, path }`), an https address (`{ url }`) or its bytes (`{ mediaType, data }`: base64 png, jpeg, webp or gif, up to 5 MiB each and 6 MiB together, kept in the project's storage while the question is answered, then deleted). A tool's pictures reach the model too. Once a response has ended, its `usage` says what it cost: `cost_nano_usd`, `usd`, and `cost_final` once nothing more of it can be settled. The question is asked with the secret key, so the model can be shown any file of the project's: check that a file is the user's own before you name it. `tools` and `maxToolCalls` give a one-shot answer the tools below, except a client tool, which only a chat has an app to answer.

`stream(…).toResponse()` is the stream as a route's answer to a browser, as server-sent events: `data: {"text": "…"}` for each fragment, `event: reset` with `{"offset": n}` when the model went back (keep the first `n` characters), and a last `event: done` with the answer. A failure is `event: error` with its code alone.

```ts
// src/modules/reviews/replies.controller.ts
import { Body, Controller, Palbase, Post, z } from "palbase/backend";

const Draft = z.object({ review: z.string().min(1).max(4000) });

@Controller("/replies")
export class RepliesController {
  // The browser reads the reply as it is written.
  @Post("/draft")
  draft(@Body(Draft) body: z.infer<typeof Draft>): Response {
    return Palbase.ai.stream({ instructions: "Draft a short, polite reply to this review.", prompt: body.review }).toResponse();
  }
}
```

`usage()` lists the project's uses of models and what each cost. Each use carries its labels (`metadata`): the caller's, and for a chat's turn, the chat's labels and the chat. `usage({ metadata: { product: "p1" } })` lists only the uses that carry those labels, such as a product's spend or a task's. This works after the chat is deleted too. `connectProvider(provider, key)` sends the project's calls to a provider with the project's own key from then on.

## What it costs

The models answer with Palbase's own provider keys, unless the project connected a key of its own for the model's provider (`connectProvider`, or Studio's **AI › Models & keys**). A call under the project's own key is billed to it by the provider, and Palbase charges nothing for it.

- **Each month brings $1.00 of Palbase's models free**, to each environment: its own dollar, whatever its plan and its organization's other environments ([Billing](/docs/getting-started/billing)).
- **Past it**, an environment on Pay as you go pays from its own credit, at the provider's price and 10%. One on Free, one whose credit ran out, or one at its monthly limit is refused (`402 ai_payment_required`) until the month ends (UTC), or until it is on Pay as you go with credit: a top-up serves it again within a minute.
- **A monthly budget.** An owner or an admin of the organization may set the most a project spends on Palbase's models in a month, in Studio's **AI › Settings** or with the CLI. Past it, calls to them are refused (`402 ai_budget_reached`) until the month ends or the budget is raised, and the organization's owners are emailed, once a month and budget. The project's key and its environment tokens cannot set it: what spends the money does not raise its own limit.
- A Free project's dollar and a budget hold as each use ends: a response is admitted with what the project has left, and one that would cost more, or is still running when it is reached, stops there with the error `ai_limit_reached` (a project with less than a cent left is at its limit: `402`). Responses running at once may each spend what was left, so the month may pass the limit by a little.
- **Pay as you go.** A paying environment's responses are held, the same way, to what it can still pay: its own credit — no more than its monthly limit still allows — and what is left of its free dollar. When less than a cent is left, calls are `402 ai_payment_required` until a top-up; usage of the last moments before it ran out is taken from the next top-up.
- **Voice.** A voice session's model runs for as long as the session is open: an environment on Free opens one on Palbase's models no more (`402 ai_payment_required`), one on Pay as you go needs a dollar left of its budget and of its credit for each voice open, and an open one is closed (`ai_limit_reached`) when the environment's free dollar, budget or credit runs out. On the project's own OpenAI key it runs regardless.
- **A call cut before its answer** (a turn stopped, a stream given up): its provider says what its tokens were only at the end. A reasoning model's hidden thinking, which the provider bills as output, is then estimated from how long it thought at the model's measured speed, rounded down, and the use is marked `estimated` (Studio: **Estimate**).

`GET /ai/spend` says the month's spend at what it is billed, what is left of a Free project's dollar, the budget, and whether Palbase's models serve the project now (and if not, why). Studio shows the same on **AI › Models & keys**.

## Tools

An agent is given tools from five sources:

| Source | Made with | Runs |
|---|---|---|
| Your backend | `Palbase.ai.tool({ name, description, input, run })` | On your machine, when the agent calls it. |
| The app | `Palbase.ai.clientTool({ name, description, input })` | In the app the chat is open in. The turn waits for the answer, which reaches the chat through your gateway. |
| An HTTPS tool | `Palbase.ai.endpoints.put(name, { kind: "https", url, … })`, then `{ source: "https", name }` | At that address: a signed `POST`. |
| An MCP server | `Palbase.ai.endpoints.put(name, { kind: "mcp", url })`, then `{ source: "mcp", name, only? }` | At that address, over streamable HTTP. |
| The platform | `{ source: "platform", name }`: `web.search`, `web.fetch`, `workspace.fetch_archive` | On the platform. `web.search` searches the web, `web.fetch` reads a page of it, `workspace.fetch_archive` downloads an archive from a URL and unpacks it into the chat's workspace (a workspace chat has it already). They belong to the agent; its subagents use the agent's. |

A tool answers within 110 seconds; past that the agent is told it did not answer. A tool whose work takes longer (a review that takes minutes) answers `{ deferred: true, expires_in_seconds? }` at once, and the call waits. Your server gives the answer later with `chats.answer(chatId, callId, output)` (`POST /ai/chats/{id}/tool-outputs/{callId}` with the secret key), within the time the tool named: a minute to a day, an hour by default. A call nobody answers by then is told to the agent as unanswered. No member answers such a call. The tool is told the call's `callId` and the chat in its context.

A chat that works in a workspace gives its agent the workspace's own tools as well:

| Tool | Does |
|---|---|
| `palai.workspace.file`, `str_replace_based_edit_tool` | Read, write and edit a file. |
| `palai.workspace.glob`, `palai.workspace.grep` | Find files by name, and lines by pattern. |
| `palai.workspace.shell`, `palai.workspace.background_status`, `palai.workspace.background_kill` | Run a command — it reaches the internet over HTTP, HTTPS, SSH and git (a package install, a clone, Palbase's own docs), never a private address or a mail server — keep one running in the background, read it and stop it. `xcodebuild`, `xcrun`, `swift` and `simuse` run on the platform's Mac, and what they write under `artifacts/` and `scratch/` comes back into the workspace. |
| `palai.workspace.fetch_archive` | Download an archive from a URL and unpack it into the workspace. |
| `palai.workspace.commit`, `palai.publish.push` | Commit, as the member the turn is for, and push to the chat's branch. |
| `palai.artifact.publish`, `palai.artifact.open`, `palai.artifact.read`, `palai.artifact.list` | Publish a file as the turn's output, and read the ones published. |
| `palai.agent.spawn`, `palai.agent.status`, `palai.agent.send`, `palai.agent.stop` | Hand work to a subagent, follow it, message it and stop it. |

The table a backend tool reads:

```ts
// src/db/public.ts
import { defineSchema, defineTable, ownedByUser, policy, text, uuid } from "palbase/backend";

export const orders = defineTable("orders", {
  columns: {
    id: uuid().primaryKey().defaultRandom(),
    owner: ownedByUser(),
    status: text(),
  },
  // A customer reads their own orders, and no one else's.
  policies: (p) => [policy("orders_own").for("select").to("authenticated").using(p.col("owner").eq(p.auth.uid()))],
});

export default defineSchema("public", { tables: [orders] });
```

```ts
// src/modules/support/support.tools.ts
import { Database, Palbase, z } from "palbase/backend";
import { ToolError } from "palbase/ai";

// Run on this machine when the agent calls it, its input checked against the schema first.
export const lookupOrder = Palbase.ai.tool({
  name: "lookup_order",
  description: "Tells an order's status by its id.",
  input: z.object({ orderId: z.string().uuid() }),
  run: async ({ orderId }) => {
    // As the chat's member: the orders policy decides what is found.
    const order = await Database.public.orders.findUnique({ where: { id: orderId } });
    if (!order) throw new ToolError(`No order ${orderId} of this customer.`);
    return { orderId, status: order.status };
  },
});

// Every call waits for a person's yes before it runs.
export const refundOrder = Palbase.ai.tool({
  name: "refund_order",
  description: "Refunds an order. A person approves each call.",
  input: z.object({ orderId: z.string().uuid() }),
  approval: true,
  run: ({ orderId }) => `Refund started for ${orderId}.`,
});

// The app answers it: the customer picks a city on their screen.
export const pickCity = Palbase.ai.clientTool({
  name: "pick_city",
  description: "Has the customer pick a city in the app, and answers the city's name.",
  input: z.object({ reason: z.string() }),
});
```

A tool is made once, at a module's top level: the framework serves every tool its process declared, and the platform calls the machine for one by its name. Its `run` is given the input and a context: `chatId`, `agent`, `callId` (the same for every attempt at one call), the chat's `metadata`, `signal`, and `user`.

- **Whose rights.** A chat that has only ever had one member is theirs: the tool runs in a transaction as that member, and `ctx.user` is them. In a chat that has had several members, a tool runs for no member and `ctx.user` is `null`, so no member has the agent act with another's rights. Reach past the caller's rights only by saying so (`Database.$asService()`).
- **What it answers.** A string, an object (said to the agent as JSON), pictures (`{ mediaType, bytes }`) or a list of them, 4 MiB at most in all.
- **When it fails.** A `ToolError`'s message is what the agent and the chat's members are told. Anything else thrown is told as "The tool failed", and the error is in the app's log.
- **`approval: true`.** Every call waits for a person's yes: the member whose message began the turn, or the server.

An HTTPS tool is any server's route. The platform calls it with `POST {tool, call_id, input, context}`, signed with the endpoint's secret in `Palbase-Signature`, and it answers `{ output, is_error }`. `endpoints.put` answers that secret once (`signing_secret`), and putting the endpoint again makes a new one. Keep it in the project's [secrets](/docs/backend/secrets):

```ts
// src/modules/rates/rates.controller.ts
import { Controller, Post, Req } from "palbase/backend";
import { verifySignature, WebhookSignatureError } from "palbase/server";

// put once: Palbase.ai.endpoints.put("convert", { kind: "https", url: "https://<ref>.app.palbase.studio/tools/convert", description, parameters })
@Controller("/tools", { auth: false })
export class RatesController {
  @Post("/convert")
  async convert(@Req() req: Request): Promise<Response> {
    const secret = process.env.CONVERT_TOOL_SECRET;
    if (!secret) throw new Error("CONVERT_TOOL_SECRET is not set");
    const raw = new Uint8Array(await req.arrayBuffer());
    try {
      await verifySignature({ secret, signature: req.headers.get("palbase-signature"), body: raw });
    } catch (e) {
      if (e instanceof WebhookSignatureError) return Response.json({ error: "invalid_signature" }, { status: 401 });
      throw e;
    }
    const call = JSON.parse(new TextDecoder().decode(raw)) as { input: { usd: number } };
    return Response.json({ output: [{ type: "text", text: `${(call.input.usd * 0.92).toFixed(2)} EUR` }], is_error: false });
  }
}
```

A project holds 32 endpoints. `endpoints.list()` and `endpoints.delete(name)` read and remove them.

## Agents

`Palbase.ai.agent(name, define)` is an agent your backend defines at the start of each turn, from the turn's context: the chat's `chatId`, `metadata` and `user` (the member, in a chat that has only ever had one).

```ts
// src/modules/support/support.agent.ts
import { Palbase } from "palbase/backend";
import { lookupOrder, pickCity, refundOrder } from "./support.tools";

export const support = Palbase.ai.agent("support", (ctx) => ({
  model: "fast",
  instructions: [
    "You are the shop's support assistant. Answer briefly.",
    ctx.user ? `The customer is ${ctx.user.name}.` : "Several people are in this chat: each message says who wrote it.",
  ].join(" "),
  tools: [lookupOrder, refundOrder, pickCity, { source: "mcp", name: "shop-docs" }],
  subagents: [{ name: "researcher", description: "Looks a question up in the shop's documents, step by step.", tools: [{ source: "mcp", name: "shop-docs" }] }],
  maxToolCalls: 12,
}));
```

The agent is your build's: the build writes it into its contract (`x-palbase-agents`, with its tools in `x-palbase-ai-tools`), and the platform reads it from the build your machine serves. Nothing is registered at start. It is changed in the code and shipped with a deploy. Studio lists it as defined in code, with its tools and what its last turn was defined as, and offers no edit. `Palbase.ai.agent(name, define, { description, machine })` says what the agent is for and, when one code runs as several machines, which of them declares it.

| Field | What it is |
|---|---|
| `instructions` | What the agent is told before the chat. |
| `model` | A role or a catalogue model. |
| `tools` | 64 at most, an MCP server's tools counted. |
| `subagents` | 16 at most: each a `name`, a `description` the agent reads to hand it work, and its own `instructions`, `model` and `tools`. `required: true` fails the turn when its part fails. |
| `maxToolCalls` | The turn's tool calls, 1 to 10 000. Past it the agent is told it has no tools left, and answers. |
| `thinking` | `visible` shows the model's reasoning in the chat's stream as `thinking` parts. `hidden` does not ask for it. When the model's provider will not give it, the turn says so once: a `thinking` part with `unavailable: true`, the `model` and the provider's `reason`. One cause is an OpenAI organization not verified for reasoning summaries; Anthropic's models (`strong`) show theirs. |

### Agents the project keeps

An agent can also be made in Studio (**AI › Agents**), with the CLI (`palbase ai:agents:create`) or with the API, without a deploy. It is changed as a **draft**: the draft is tried (Studio's **Try**) and **published** as a version that never changes. Chats and one-shot answers by its name talk to the version published; `"helper@3"` stays on version 3. An older version is published again with `rollback`.

```ts
import { Palbase } from "palbase/backend";

await Palbase.ai.agents.saveDraft("helper", { instructions: "Answer in one sentence.", model: "fast" });
await Palbase.ai.agents.publish("helper");
const answer = await Palbase.ai.ask("What does the return policy say?", { agent: "helper" });
```

| Call | What it does |
|---|---|
| `agents.list()`, `agents.get(name)` | The project's agents: those its build declares (`source: "code"`) and those it keeps (`source: "platform"`). |
| `agents.saveDraft(name, definition, { revision })` | Saves the draft. A draft saved since the `revision` you read is refused (`409 draft_changed`), so a change made meanwhile is not lost. |
| `agents.publish(name, { revision })` | Publishes the draft as the next version. |
| `agents.rollback(name, version)`, `agents.versions(name)` | Publishes an older version again, and lists the versions. |
| `agents.delete(name)`, `agents.tools()` | Deletes the agent with its versions, and lists the tools an agent can be given. |

A kept agent is given the same tools a backend's is. A backend or client tool named by its name alone (`{ source: "backend", name: "lookup_order" }`) is your build's: what it does, what it takes and whether it waits for a person's yes are filled in from the build at every turn, so the agent follows your code.

`output` is the shape of the agent's one-shot answers, a JSON Schema of an object: `generate({ agent: "classify" })` returns a document of it, and a call's own `schema` replaces it for that call. `description` says what the agent is for.

**One name is one agent's.** The platform refuses a kept agent by a name your build declares (`409 agent_defined_in_code`), and a build that declares a name the project keeps fails its deploy, the version before it serving on. `chats.create({ definition })` gives one chat a definition of its own, with no name kept.

**An agent from a description.** Studio's **Create with AI**, or `palbase ai:agents:generate "helps customers who ask where their order is"`, writes a draft: its instructions, model and tools, chosen from the project's own tools. Palbase pays for the model that writes it. A person writes 20 drafts an hour in a project.

## Chats

A chat is the project server's. Only your backend starts one (a user's own call is refused `403 server_only`), and it names the chat's members:

```ts
// src/modules/support/support.controller.ts
import { Body, Controller, Palbase, Post, User, z, type UserT } from "palbase/backend";
import { support } from "./support.agent";

const StartChat = z.object({ title: z.string().max(256).optional() });

@Controller("/support")
export class SupportController {
  // The signed-in user asks for a chat with support, and is its owner.
  @Post("/chats")
  async start(@Body(StartChat) body: z.infer<typeof StartChat>, @User() user: UserT): Promise<{ id: string }> {
    const chat = await Palbase.ai.chats.create({ agent: support, title: body.title, members: [{ userId: user.id, owner: true }] });
    return { id: chat.id };
  }
}
```

| Call | What it does |
|---|---|
| `chats.create({ agent, members, title, metadata, workspace })` | Starts a chat with a named agent (or `definition`). 64 members at most, each `{ userId, name, owner }`: `name` is how the agent and the others are told who wrote. |
| `chats.get(id)`, `chats.list({ member })`, `chats.delete(id)` | Reads a chat, lists them (a member's, or all), deletes one. A turn still running is stopped. |
| `chats.members.put(id, userId, { name, owner })`, `chats.members.delete(id, userId)` | Adds or changes a member, removes one. |
| `chats.send(id, { text, clientId, delivery, as, budget, images, files })` | A message for the agent: a turn of its own when none runs. |
| `chats.messages(id)` | What was written, newest first, a page at a time. |
| `chats.stop(id)` | Stops the turn the agent is on. What it wrote stays. Answers the turn's id, or `null` when none ran. |
| `chats.approve(id, approvalId, { reason, as })`, `chats.deny(…)` | A call that waits for a person's yes, made or not. Denied, the agent is told the reason and goes on. |
| `chats.answer(id, callId, output, { isError, as })` | A client tool's answer: `true` when it is the one taken, `false` when another came first. |
| `chats.sendToSubagent(id, runId, text, { as })` | A message for a subagent at work, at its next step. |
| `chats.turnCost(id, responseId)` | What a turn cost so far, its subagents counted: tokens, `costNanoUsd` (and `usd`), and `final` once nothing more of it is settled. `runs` breaks it down run by run: the turn's own and each subagent's, by name, model and state. A turn still at work is read as it spends. |
| `chats.events(id)` | The chat as a source a gateway pipes into its channel. See [A chat in an app](#a-chat-in-an-app). |

`send` keys a message on its `clientId`: the same id sent again, a retry, is the same message, delivered once. One is made when you give none. `delivery` is for a message that comes while the agent works: `"next"` (the default) gives it the message at its next step, `"now"` cuts the step it is in.

**Writing as a member.** Without `as`, the server writes as itself, and decides any approval or tool call. With `as: userId`, it writes as that member and is held to their rules. The message is theirs and counts toward their messages a minute (`429 too_many_messages`). A turn another member began is theirs alone to decide or answer (`403 not_your_turn`). A user who is not a member is refused (`403 not_a_member`). A gateway does all of a member's work this way, as the member who sent the message.

**Events.** Every turn of a chat is an event of the project's: `ai.response.started` as it begins, whoever opened it (a member's message, the server's, the chat's goal), and `ai.response.completed` or `ai.response.failed` as it ends. A turn's event carries the chat (`chat_id`, its labels as `metadata`), the member it ran for (`user_id`, `null` for the server's), the labels of the message that opened it (`message_metadata`), whether it was the goal's (`goal_turn`, `goal_id`), and how it ended: `completed`, `failed` (its `error`: a `code`, a `message`, and whether asking again may help, `retryable`), `stopped`, or `budget_exceeded`. Take them with `@On("ai.response.completed")` ([Event Hooks](/docs/backend/hooks)). The chat's stream says the same on the turn's last part (`end`, `error`).

**Pictures and files.** A message carries files of the project's storage. `images: [{ bucket, path }]` are pictures the model is shown with it: up to 4 (as many as the model is shown at once), up to 5 MiB each, png, jpeg, webp or gif. A picture's type is read from its bytes, not its label, and anything else is `415 unsupported_image`. `files: [{ bucket, path, filename, contentType }]` are put in the chat's workspace before the agent reads the message, at `.palbase/attachments/<message id>/<filename>`: up to 8, up to 15 MiB each. The agent is told what each one is and where. `filename` defaults to the path's last segment, and `contentType` to what storage says. A chat that works in no workspace takes images alone (`409 no_workspace`). Each one is copied for the chat as the message is written, so the agent reads what was sent whatever later happens to the file, and the copy is deleted with the chat. The same bytes are kept once, and an object named twice (a picture that is also a file) is read once. Your server attaches any file of the project's storage, writing `as` a member or not: the decision is yours. A client, a member with their own session, attaches only a public bucket's files; a private bucket's file, even their own (`owner_id`), is attached by your server. Any other is `404 attachment_not_found`, the same answer as for a file that is not there. A message shows what it carries as `attachments` (images first): `kind` (`image` or `file`), `bucket`, `path`, `name`, `contentType`, `size`, `sha256`, and a file's `workspacePath`. The chat's members, and your server, read each one back at `GET /ai/chats/{id}/messages/{messageId}/attachments/{position}`. A fork begins with copies of what its history's messages carried, and its first turn shows the model the history's 4 newest pictures again.

**Budgets.** `send(id, { text, budget: { maxCostUsd: 0.5 } })` bounds what the turn that message starts may cost, its subagents' calls counted. Past it the turn stops and ends `budget_exceeded`. A message into a turn already running takes that turn's budget.

**Settings.** `Palbase.ai.settings.put({ … })` sets what the project allows its chats: `userMessagesPerMinute` (1 to 600, 20 unless set), and `historyLimitBytes`, the chat history the project keeps: a free project at most 500 MiB, less if it says so; a project with paid rights keeps all of it (`historyLimitBytes` is `null`) unless it says a limit of its own, up to 1 TiB. Past it, a message is refused (`409 history_full`) until chats are deleted. `settings.get()` also says how much is kept now. `clients`, off unless set, lets a user's own session read and write the chats they are in at the project's address. The app SDKs read through it what a gateway does not carry — a chat's older history (`loadOlder`), a tool call's whole answer (`chatToolCall`), a workspace file or an attachment — and a chat's live messages still come through its gateway.

## Voice

A chat can be talked to out loud. The app opens a WebRTC peer connection, sends its offer to `POST /ai/chats/{id}/voice`, and sets the answer it gets back; the audio then goes between the app and the platform's voice provider, whose key never leaves the platform. The voice speaks as the chat's agent, with its instructions.

A voice is its member's: the user who starts it, or the member your server starts it for (`as`). They and your server read it (`GET …/voice/{voiceId}`: live or closed, how many seconds, why it ended), tell it (`…/commands`: `speak`, `tell`, `know`, `instruct`, your server's alone) and close it (`DELETE`); no other member does (`403 not_your_voice`). A member starts at most 5 voices an hour, the ones your server starts for them counted with their own (`429 too_many_voices`). One voice talks in a chat at a time: a member's new voice ends the one they left open, and another member's live voice is refused (`409 voice_active`). A voice closes when its member is taken out of the chat (`member_removed`) or the chat is deleted (`chat_deleted`).

Your server can give the voice, with its start, how it speaks (`instructions`, after the chat's agent's own) and what it knows as the talk opens (`context`). Both are your server's alone, as `know` and `instruct` are (`403 server_only` from an app), and are at most 48 KiB together. Given with the start, the voice speaks with them from its first second. Told after the start, piece by piece, the voice talks without them until the last piece is in, which for a long opening is many seconds.

`speak` says its `text` exactly and nothing else, with no words of the voice's own before or after it. It waits until the voice finishes what it is saying, so a speak never cuts into the voice's answer, and speaks are said one at a time in the order they came. With `interrupt: true` it cuts what the voice is saying and is said at once. `tell` gives the voice something to say in its own words, `know` gives it something to keep in mind, and `instruct` changes how it behaves. Up to 16 speaks can wait at a time. Past that, a speak is refused with `429 voice_busy`.

What the person asks for out loud is handed over, as the voice's `delegation` says:

| `delegation` | What happens |
|---|---|
| `"chat"` (the default) | The request is a message of the voice's member to the chat's agent — a turn of its own, or into the one at work — with what was said before it given to the agent as context. When that turn ends, the voice says its answer back. No code of yours is needed. |
| `"events"` | Your backend is told: `ai.voice.delegated` carries the request's `delegation_id`, its `text` and what was said before it (`earlier`). Have it done, and answer with a `speak` command naming the `delegation_id`. |

What was said either way is the chat's: a `transcript` part of its stream for each line, and the same line in its history (`messages`, of `kind: "voice"`, with `voice: { id, role }`). The stream's `voice` part says when it began and when it ended. The end is told once, with its `close_reason` and `seconds`, whatever ended the voice: the person's connection was lost, the voice was closed, or the platform lost it (`lost`). A chat whose voice is live has its pipe written whether or not a turn is at work. A voice's start and end are the events `ai.voice.started` and `ai.voice.closed` (its `seconds` and `close_reason`).

## Workspaces

A chat can work in GitHub repositories: its turns run with them checked out, and what its agent commits is pushed to the branch. The tokens are your backend's to give, at each clone and each push.

```ts
// src/modules/builds/app.repo.ts
import { Palbase } from "palbase/backend";

// A token for one clone or one push, asked of this machine each time and kept nowhere: here a
// fine-grained token for this repository's contents, from the machine's secrets.
export const shopApp = Palbase.ai.repo({
  name: "shop-app",
  repository: "acme/shop-app",
  defaultBranch: "main",
  token: () => {
    const token = process.env.SHOP_APP_GITHUB_TOKEN;
    if (!token) throw new Error("SHOP_APP_GITHUB_TOKEN is not set");
    return token;
  },
});
```

```ts
// src/modules/builds/builds.service.ts
import { Injectable, Palbase } from "palbase/backend";
import { shopApp } from "./app.repo";

@Injectable()
export class BuildChats {
  async onStart(): Promise<void> {
    await Palbase.ai.repos.put(shopApp);
  }

  /** A chat that works on a branch of the app; each push waits for its owner's yes. */
  async start(userId: string, branch: string): Promise<string> {
    const chat = await Palbase.ai.chats.create({
      definition: { instructions: "You work on the shop's app. Make small commits.", model: "strong" },
      members: [{ userId, owner: true }],
      workspace: { repos: [{ repo: shopApp, branch }], autoPush: false },
    });
    return chat.id;
  }

  /** What a turn published: a build's product, a screenshot, a report. */
  async firstArtifact(chatId: string, responseId: string): Promise<Response | null> {
    const [first] = await Palbase.ai.chats.artifacts(chatId, responseId);
    return first ? Palbase.ai.chats.artifact(chatId, responseId, first.id) : null;
  }
}
```

With `autoPush: false` a push waits for a member's approval, as an `approval: true` tool does. With `autoPush: true` the agent pushes without one, and what the chat's members write then reaches the repository. A project puts 10,000 repositories, and a chat works in 8 of them at most. `repos.list()` and `repos.delete(name)` read and remove them.

**A repository for a chat at work.** `chats.workspace.addRepo(chatId, { repo, branch? })` (`POST /ai/chats/{id}/workspace/repos`) puts one more of the project's repositories in an open chat's workspace, beside its others. A repository born while the work goes on is put first with `repos.put`. The engine clones it into the workspace before the chat's next turn, and every chat working in the workspace (a fork, too) has it. Your server alone does this.

**Whose commits, and what they carry.** Each commit the agent makes is written as the member its turn is for: their name in the chat and their address, as an author and as a committer. This holds for the platform's commit tool and for a plain `git commit` the agent runs in the shell. Each turn writes its member into the repositories' own git config and installs a `commit-msg` hook that adds the chat's trailers. A hook, or a hooks path, the repository already has is left alone. Give the address with the member (`members: [{ userId, name, email }]`, or `PUT /ai/chats/{id}/members/{userId} { email }`). A member's own session gives it again, verified, whenever they write. It is never served to the chat's other members. A member with no address commits under one of the platform's that names them and reaches no one. A turn that is no member's (your server's own) commits as the platform. `workspace: { trailers: [{ key, value }] }` are git trailers every commit of the chat carries at the end of its message: a task (`PalCore-Task: #12`), a link back to the conversation, a co-author (`Co-authored-by: …`). Up to 16, each one line. The agent's work is pushed only to the chat's branch. On a protected or default branch (`main`, `master`, the repository's default) it goes to a branch of its own, `agent/<workspace>/<run>`.

**What the workspace did, as events.** The workspace's machine publishes its tree whenever the files are quiet for a moment, so mid-turn, as a build writes its product. It publishes once more as it lets the workspace go. Each tree is `ai.workspace.published`, with the files it changed against the tree it replaced (`changed: [{ path, change: added|modified|removed, size_bytes }]`, 1000 at most). Read one of its files, as that tree left it, at `GET /ai/chats/{id}/workspace/files?path=<path>&manifest=<manifest_id>` (without `manifest`, from the tree the workspace is at now). Files are served up to 64 MiB (`413 file_too_large` past it), with their digest in `Content-Digest`; publish a larger one as the turn's artifact. A project reads 4 files at once (`429 too_many_reads`, with `Retry-After`), and a file is written for no longer than its bytes take at 256 KiB/s plus a minute. A tree's changes are named 1000 at a time in the event (`changed_truncated` past that). A push is `ai.workspace.pushed`, with the commits it brought (`commits: [{ sha, subject, author_name, author_email }]`, 100 at most), the repository by your name for it, the branch and the member. The chat's members see the push in the stream with each commit's author by name, never by address. Each event is told once, from the turn's start until 20 minutes after its end, whoever is watching the chat.

## A chat in an app

A chat reaches its members through a gateway declared with `chat: true`. When its first member joins, the gateway pipes the chat into its channel. From then on the **platform** writes the chat there itself: the members' messages, each answer as it is written, the tool calls, the approvals and the subagents' work. The backend is not in the stream. The channel keeps the chat a day (or what `durable` says), so a member who joins later, or was away, has all of it. What a member does in the chat (a message, a yes or a no, a client tool's answer, stop) comes to the gateway as one of its messages, and the backend does it **as them**.

The channel keeps a day of the chat. A chat opened later is read back at `GET /ai/chats/{id}/parts?limit=&cursor=`, a page at a time from its newest end back: the same parts the stream told, in their order, each under the id the channel told it (`part_id`). A client that holds the channel's parts and pages of these keeps each one once. An answer's text is placed by its offset, as in the stream. The last page reaches the chat's start and begins where a fork began. A client that already holds the channel's day passes the `id` of the oldest part it holds as `before=<id>`, and the first page starts just before that part, so the day is not read twice. Each page after it is read by its `next_cursor`. A call with both `cursor` and `before` is refused (`400`). A voice's end is in the pages under the id the channel told it (`vclosed:<voice>`). For a voice the engine lost, whose end its journal never says, it comes right after the voice's last part. Reading a page changes nothing. A client's `loadOlder()` reads the page before the oldest it holds.

A tool call's answer is in the stream by its end: its last 16 KiB, with `omitted_bytes` saying what was left out. A build's log ends with what failed. A member who opens the call reads it whole at `GET /ai/chats/{id}/tool-calls/{callId}`, with secrets masked as the stream masks them. Your server reads a turn's tool calls as the engine committed them, arguments and results as they were, a page at a time, at `GET /ai/chats/{id}/tool-calls?turn=<responseId>&limit=&cursor=`. That is what a diff of the files the turn wrote is made of. A subagent's calls are read by its response (an agent part's `response_id`). A project reads two of these, or of a chat's past pages, at once (`429 too_many_reads`).

```ts
// src/modules/support/support.gateway.ts
import { Authorize, Gateway, GatewayRefusal, OnFirst, Palbase, PalbaseError, Subscribe, z } from "palbase/backend";
import type { GatewayAuthorizeContext, GatewayContext, GatewayGrant, GatewayMessageContext } from "palbase/backend";

export const Say = z.object({ text: z.string().min(1).max(8000), clientId: z.string().max(64).optional(), delivery: z.enum(["next", "now"]).optional() });
export const Said = z.object({ clientId: z.string() });
export const Decide = z.object({ approvalId: z.string(), approve: z.boolean(), reason: z.string().max(1024).optional() });
export const Answer = z.object({ callId: z.string(), output: z.string().max(16_000) });
export const Stopped = z.object({ stopped: z.string().nullable() });

// The ai module's refusals that are the member's own to act on, said to them by their code.
async function asMember<T>(work: () => Promise<T>): Promise<T> {
  try {
    return await work();
  } catch (e) {
    if (e instanceof PalbaseError && [403, 404, 409, 429].includes(e.status)) throw new GatewayRefusal(e.code);
    throw e;
  }
}

@Gateway("support:{chatId}", { chat: true })
export class SupportGateway {
  // The chat's members, and no one else. A chat that is not there lets no one in.
  @Authorize()
  async enter(ctx: GatewayAuthorizeContext): Promise<GatewayGrant> {
    const chat = await Palbase.ai.chats.get(ctx.params.chatId).catch((e: unknown) => {
      if (e instanceof PalbaseError && e.status === 404) return null;
      throw e;
    });
    return chat?.members.some((m) => m.user_id === ctx.user.id) === true;
  }

  // The chat into the channel, from its start.
  @OnFirst()
  async open(ctx: GatewayContext): Promise<void> {
    await ctx.pipe(Palbase.ai.chats.events(ctx.params.chatId));
  }

  @Subscribe("say", Say, { reply: Said })
  async say(ctx: GatewayMessageContext<z.infer<typeof Say>>): Promise<z.infer<typeof Said>> {
    const { text, clientId, delivery } = ctx.payload;
    const m = await asMember(() => Palbase.ai.chats.send(ctx.params.chatId, { text, clientId, delivery, as: ctx.user.id }));
    return { clientId: m.client_id };
  }

  // A call that waits for a person's yes: the member whose message began the turn says it.
  @Subscribe("decide", Decide)
  async decide(ctx: GatewayMessageContext<z.infer<typeof Decide>>): Promise<void> {
    const { approvalId, approve, reason } = ctx.payload;
    const as = ctx.user.id;
    await asMember(() => (approve ? Palbase.ai.chats.approve(ctx.params.chatId, approvalId, { reason, as }) : Palbase.ai.chats.deny(ctx.params.chatId, approvalId, { reason, as })));
  }

  // A client tool's answer, from the app of the member whose turn it is.
  @Subscribe("answer", Answer)
  async answer(ctx: GatewayMessageContext<z.infer<typeof Answer>>): Promise<void> {
    await asMember(() => Palbase.ai.chats.answer(ctx.params.chatId, ctx.payload.callId, ctx.payload.output, { as: ctx.user.id }));
  }

  // Any member stops the agent. What it wrote stays.
  @Subscribe("stop", z.object({}), { reply: Stopped })
  async stop(ctx: GatewayMessageContext<Record<string, never>>): Promise<z.infer<typeof Stopped>> {
    return { stopped: await asMember(() => Palbase.ai.chats.stop(ctx.params.chatId)) };
  }
}
```

```ts
// src/modules/support/support.module.ts
import { Module } from "palbase/backend";
import { SupportController } from "./support.controller";
import { SupportGateway } from "./support.gateway";

// The agent and its tools are values, declared as their files load: the controller's import brings them.
@Module({ controllers: [SupportController], providers: [SupportGateway] })
export class SupportModule {}
```

In the app, the member joins `SupportGateway` with the chat's id, and the handle holds the chat's state (`handle.chat`), which the generated client folds from what the platform writes: the messages and answers in order, the last turn, and what waits for this user. The member sends `say`, `decide`, `answer` and `stop` through the gateway, and a refusal arrives as its reason: `not_your_turn`, `too_many_messages`, `history_full`. See [Web Gateways](/docs/web/gateways#chat-gateways).

## Refusals

| Status | `error` | When |
|---|---|---|
| 403 | `server_only` | A user started a chat, or asked for what only the server reads (a turn's cost, a chat's pipe). |
| 403 | `not_a_member` | `as` names a user who is not a member of the chat. |
| 403 | `not_your_turn` | `as` decides or answers a turn another member began. |
| 404 | `attachment_not_found` | A message attaches a file that is not there, or one its writer may not attach. |
| 402 | `ai_payment_required` | The environment used this month's free AI and has no credit to pay past it — it is on Free, its credit ran out or its month is at its limit — and it has no key of its own for the model's provider ([What it costs](#what-it-costs)). |
| 402 | `ai_budget_reached` | The project's monthly AI budget is spent, and it has no key of its own for the model's provider. |
| 403 | `forbidden` | A key or a token named `monthly_budget_usd` in the settings: an owner or an admin sets it, in Studio or with the CLI. |
| 409 | `history_full` | The project keeps as much chat history as it may. Delete chats to write again. |
| 409 | `no_workspace` | A message carries `files` into a chat that works in no workspace. |
| 409 | `attachment_changed` | A file changed while it was attached. Send the message again. |
| 409 | `too_many_members` | A chat holds 64 members. |
| 409 | `too_many_endpoints`, `too_many_repos` | A project holds 32 of each. |
| 413 | `attachment_too_large` | A message's picture is over 5 MiB, or its file over 15 MiB. |
| 415 | `unsupported_image` | A message's picture is not a png, jpeg, webp or gif by its bytes. |
| 429 | `too_many_messages` | The member sent as many messages this minute as the project allows. `Retry-After` says when to write again. |
| 503 | `billing_unavailable` | Palbase could not check the project's use of its models just now. `Retry-After` says when to try again. |

Each arrives as a `PalbaseError` with its `status` and `code`, its message said in words the caller can act on. A gateway turns the ones a member can act on into a `GatewayRefusal` with the same code, as `asMember` does above.

## Related

- [Gateways](/docs/backend/gateways): the channel a chat reaches its members on
- [Web Gateways](/docs/web/gateways): a chat's state in the browser
- [Event Hooks](/docs/backend/hooks): `ai.response.started`, `ai.response.completed` and `ai.response.failed` (a background response's end, and every chat turn's start and end), `ai.goal.updated`, `ai.voice.started`, `ai.voice.closed`, `ai.voice.delegated`
- [Secrets](/docs/backend/secrets): an HTTPS tool's signing secret, a repository's token
- [Row-Level Security](/docs/backend/row-level-security): what a tool finds as the chat's member



<!-- ===== backend/webhooks ===== -->

# Webhooks

Stripe, GitHub, Slack and the rest tell your app what happened by POSTing to a URL you give them. A `@Webhook` class receives those deliveries at `POST /webhooks/<name>` on your machine: the framework checks each one's signature against the bytes **as they arrived**, under a secret it reads from the machine's environment, and hands it to the `@On` method of its event type. A delivery that is not signed with that secret never reaches your code.

This page is about a **third party's** deliveries. The platform's own events (`user.deleted`, `file.uploaded`, …) arrive at `/webhooks/palbase` and are handled by `@On` on an ordinary provider class: see [Event Hooks](/docs/backend/hooks). A server that is not a `palbase/backend` app receives the platform's events with `verifyWebhook`: see [Server SDK: Webhooks](/docs/server/webhooks).

## Quick example

```ts
// src/modules/billing/stripe.webhook.ts
import { Database, Log, On, Webhook, type WebhookMeta } from "palbase/backend";

interface StripeEvent<T> {
  id: string;
  type: string;
  data: { object: T };
}

interface Invoice {
  id: string;
  customer: string;
  amount_paid: number;
}

@Webhook({ name: "stripe", provider: "stripe", secret: { env: "STRIPE_WEBHOOK_SECRET" } })
export class StripeWebhook {
  @On("invoice.paid")
  async invoicePaid(event: StripeEvent<Invoice>, meta: WebhookMeta): Promise<void> {
    const invoice = event.data.object;
    // A delivery runs as no user: what it writes, it writes as the service.
    await Database.$asService().$query("update accounts set paid_until = now() + interval '1 month' where stripe_customer = $1", [invoice.customer]);
    Log.info("invoice paid", { invoice: invoice.id, delivery: meta.requestId });
  }

  @On("customer.subscription.deleted")
  async cancelled(event: StripeEvent<{ customer: string }>): Promise<void> {
    await Database.$asService().$query("update accounts set paid_until = null where stripe_customer = $1", [event.data.object.customer]);
  }
}
```

```ts
// src/modules/billing/billing.module.ts
import { Module } from "palbase/backend";
import { StripeWebhook } from "./stripe.webhook";

@Module({ providers: [StripeWebhook] })
export class BillingModule {}
```

Then, in Stripe's dashboard, add an endpoint at `https://<ref>.app.palbase.studio/webhooks/stripe` for `invoice.paid` and `customer.subscription.deleted`, and copy its signing secret (`whsec_…`) into the environment's secrets as `STRIPE_WEBHOOK_SECRET` ([The secret](#the-secret)). From the next deploy on, a paid invoice runs `invoicePaid`.

## `@Webhook(options)`

| Option | What it is |
|---|---|
| `name` | The last segment of the URL, `/webhooks/<name>`: what the sender is configured with. Lowercase letters, digits and dashes, starting and ending with a letter or digit. Not `palbase`, which is the platform's own. Two `@Webhook` classes of one app cannot share a name. |
| `provider` | A sender whose signature scheme the framework knows: `stripe`, `github`, `slack`, `discord`, `twilio`, `sendgrid` or `livekit` ([Providers](#providers)). |
| `signature` | A scheme spelled out, for any other sender ([A signature of your own](#a-signature-of-your-own)). |
| `secret` | `{ env: "VAR_NAME" }`: the environment variable that holds the signing secret. Its name, never its value. |

A webhook takes exactly one of `provider` and `signature`: one with neither would take forged deliveries, and one with both would verify with one and leave the other unread. It needs at least one `@On`, and an event type is taken by one method. Every one of these mistakes throws where the class is declared.

The class is a provider: its module lists it in `providers`, and it takes its dependencies by constructor, as a controller does ([Modules & Dependency Injection](/docs/backend/modules)). It needs no `@Injectable()`.

## Providers

Each provider's scheme is the one its own documentation describes. What it is checked with, what the framework reads as the event's type (the name an `@On` takes), and what it remembers a delivery by ([Duplicates and replays](#duplicates-and-replays)):

| `provider` | Signature | The secret is | Event type | Remembered by | Sender's largest body |
|---|---|---|---|---|---|
| `stripe` | `Stripe-Signature`: HMAC-SHA256 of `"<t>.<body>"`, any of its `v1`s; `t` within five minutes | the endpoint's signing secret (`whsec_…`) | the body's `type`: `invoice.paid` | the body's `id` | 512 KiB |
| `github` | `X-Hub-Signature-256`: `sha256=` HMAC-SHA256 of the body | the webhook's secret | `X-GitHub-Event` (unsigned, see below) and the body's `action`: `pull_request.opened`; the event alone when there is no action: `push`, `ping` | `X-GitHub-Delivery` with the body's SHA-256 | 25 MB |
| `slack` | `X-Slack-Signature`: `v0=` HMAC-SHA256 of `"v0:<ts>:<body>"`; `X-Slack-Request-Timestamp` within five minutes | the app's signing secret | the body's `type`: `url_verification`, `event_callback`; an interactivity form's `payload.type`: `block_actions`, `view_submission`; `""` for a slash command | the body's `event_id` | 64 KiB |
| `discord` | `X-Signature-Ed25519`: Ed25519 of `"<X-Signature-Timestamp><body>"`; the timestamp within five minutes | the application's **public key** (64 hex characters) | `PING` for type 1, `INTERACTION_CREATE` for type 2, `type_<n>` for any other | the body's `id` | 64 KiB |
| `twilio` | `X-Twilio-Signature`: base64 HMAC-SHA1 of the URL Twilio called and its signed parameters; no time | the account's auth token | the `EventType` parameter; `""` when there is none (a plain incoming message or call) | `I-Twilio-Idempotency-Token` with the SHA-256 of the URL and parameters signed | 64 KiB |
| `sendgrid` | `X-Twilio-Email-Event-Webhook-Signature`: ECDSA P-256 of `"<timestamp><body>"`; the timestamp within five minutes | the Event Webhook's **verification key** (the base64 public key SendGrid shows) | always `event_batch` | each event's `sg_event_id` | 1 MiB |
| `livekit` | `Authorization`: a JWT signed HS256 with the API secret, unexpired (with a minute's leeway), whose `sha256` claim is the body's hash | the API secret | the body's `event`: `room_started` | the body's `id` | 512 KiB |

**A delivery's body is capped** at the smaller of its sender's largest (the last column) and the app's own `bodyLimit` (`PalbaseFactory.create(…, { bodyLimit })`, 1 MiB unless you set it). With the default, a Stripe, LiveKit, Slack, Discord or Twilio delivery is held to what that sender sends, and a GitHub or SendGrid one to 1 MiB: an app that takes GitHub's larger pushes raises its `bodyLimit`, which raises it for every route too. A body over the cap is refused `413 payload_too_large`, before more of it is read than the cap.

The secrets of `discord` and `sendgrid` are public keys, which cannot forge a delivery. One that is not a key of the right kind stops the boot, naming the variable.

**Twilio signs the URL it called.** The framework rebuilds it as `https://` with the host the request came to, its path and its query, so give Twilio the machine's address exactly as it serves it. It tries the URL with and without the port, as Twilio's own library does. A form body's parameters, decoded and sorted, are part of what is signed, and the handler is given those same parameters: `{ From: "+1555…", Body: "hi", … }`, a name sent twice as an array. A JSON body is signed through the `bodySHA256` parameter of the URL instead.

Twilio's signed string has nothing between a name and its value, or between one parameter and the next. So a captured request can be split again into other parameters that verify just the same (`Body=HiFrom+1555` for `Body=Hi&From=+1555`). Twilio's own libraries accept such a request too, and no check can tell it from the original. A Twilio handler checks what it acts on, such as a `MessageSid` or `CallSid` it can look up, before trusting the parameters' split.

**GitHub's event name is not signed.** `X-GitHub-Event` is a header, outside what GitHub's signature covers, so whoever holds a GitHub delivery can send it again under another event's name, to that event's `@On`. GitHub signs nothing else that names the event, and every receiver routes on that header, Octokit's included. A GitHub handler checks that the payload is the one it takes: a `pull_request` has a `pull_request`, a `push` has its `ref` and `commits`.

**Slack's form or JSON is read from the signed bytes.** A body that is not JSON but is a form with a `payload` field is an interactivity payload, whatever its `Content-Type`, because no signature covers that header.

## A signature of your own

A sender with no preset is described by its scheme: an HMAC over a template of the body and, optionally, a timestamp.

```ts
// src/modules/shipping/carrier.webhook.ts
import { Log, On, Webhook } from "palbase/backend";

interface Shipment {
  type: string;
  tracking_number: string;
  status: string;
}

@Webhook({
  name: "carrier",
  signature: {
    header: "x-carrier-signature",
    prefix: "sha256=",
    algo: "hmac-sha256",
    encoding: "hex",
    // What the HMAC covers: {body} is the bytes as they arrived, {ts} the timestamp header.
    signs: "{ts}.{body}",
    timestampHeader: "x-carrier-timestamp",
  },
  secret: { env: "CARRIER_WEBHOOK_SECRET" },
})
export class CarrierWebhook {
  @On("shipment.delivered")
  delivered(event: Shipment): void {
    Log.info("delivered", { tracking: event.tracking_number });
  }
}
```

| `signature` field | What it is |
|---|---|
| `header` | The header the signature arrives in. A delivery without it is refused before its body is read. |
| `prefix` | Text before the signature in that header (`sha256=`): stripped before comparing. A header without it is refused. |
| `algo` | `hmac-sha256` or `hmac-sha1`. |
| `encoding` | `hex` or `base64`. |
| `signs` | The template the HMAC covers. It must contain `{body}`; `{ts}` puts in the timestamp header's value; everything else is literal text. |
| `timestampHeader` | Where `{ts}` is read. With `{ts}` in the template, the timestamp is whole seconds and must be within five minutes of the machine's clock. |

The event's type is the body's `type`. A body may be as large as the app's own `bodyLimit` (1 MiB unless you set it): there is no sender's largest to hold it to. A spelled-out scheme names no delivery id, so the framework cannot recognise a delivery sent again: every one runs. Without `{ts}` in `signs`, a captured delivery also verifies whenever it is sent again, at any time ([Duplicates and replays](#duplicates-and-replays)). Use the sender's timestamp when it sends one.

## The secret

`secret: { env }` names an environment variable, and the framework reads it when the app is built. Keep it with the project's other secrets:

1. **Environment › Variables**, **Add secret**: the name you gave `env` (`STRIPE_WEBHOOK_SECRET`), and the sender's secret as its value.
2. **Backend › Machines**, the machine, **Edit settings**: start it with the set that holds it (**Secrets: Production secrets**). A machine already started with it rolls out with the new value.
3. List the name in the machine's `.env.example`. A build whose variables the machine does not have waits for them instead of rolling out an app that cannot start ([Builds, Logs & Rollback](/docs/machines/builds)).

An app whose webhook's variable is unset, or does not hold a key its provider can use, does not start, and says which:

```text
[palbase] the app cannot start:
  - @Webhook "stripe" (StripeWebhook) reads its signing secret from STRIPE_WEBHOOK_SECRET, which is not set
```

This is not `PALBASE_WEBHOOK_SECRET`. That one is the platform's endpoint secret for [its own events](/docs/backend/hooks); an app with `@Webhook` classes and no platform `@On` does not need it.

## Events and `@On`

Inside a `@Webhook` class, `@On("<type>")` takes that sender's events, under whatever name the sender gives them: `invoice.paid`, `pull_request.opened`, `PING`, `block_actions`. (Outside one, `@On` takes the platform's events, whose types are dotted lowercase words; [Event Hooks](/docs/backend/hooks).) A handler is called as `(event, meta)`:

| Argument | What it is |
|---|---|
| `event` | The body's JSON. A body that is not JSON is given as its text. For Slack's interactivity (a form of one field, `payload=<json>`), the parsed `payload`. For Twilio's form, the signed parameters. |
| `meta.requestId` | The delivery's request id: the app's log lines of it carry it. |
| `meta.env` | The app's environment as it started, without `PALBASE_SECRET_KEY`, `PALBASE_WEBHOOK_SECRET` and `PALBASE_PLATFORM_SECRET`. |
| `meta.environmentId` | The project's id. |

```ts
// src/modules/slack/slack.webhook.ts
import { Log, On, Webhook } from "palbase/backend";

@Webhook({ name: "slack", provider: "slack", secret: { env: "SLACK_SIGNING_SECRET" } })
export class SlackWebhook {
  // Slack checks the URL once when it is set, and expects the challenge back.
  @On("url_verification")
  verify(event: { challenge: string }): { challenge: string } {
    return { challenge: event.challenge };
  }

  @On("event_callback")
  message(event: { event: { type: string; user?: string; text?: string } }): void {
    Log.info("slack event", { type: event.event.type, user: event.event.user });
  }

  // A button: Slack's interactivity form, its payload already parsed.
  @On("block_actions")
  clicked(event: { user: { id: string }; actions: { action_id: string }[] }): void {
    Log.info("clicked", { user: event.user.id, action: event.actions[0]?.action_id });
  }
}
```

A delivery whose type no `@On` takes is acknowledged with `200 { ok: true, handled: false }` and runs nothing: answering an error would make the sender retry it, and some senders turn off an endpoint that keeps failing.

**`@On("")` takes the deliveries that name no type.** Two senders' deliveries name none:

- Twilio's plain incoming message or call: a form with no `EventType`. The handler is given its signed parameters.
- A Slack slash command: a form with no `payload`. The handler is given the form's text, which `new URLSearchParams(event)` reads.

`@On("")` is a `@Webhook`'s alone. On any other class, `@On` takes the platform's events, which always name their type, and an empty one stops the boot.

A SendGrid delivery is a batch: its one event type is `event_batch`, and the handler is given the array of events.

The event is the sender's data: the database takes values from it, never a filter's structure ([Database](/docs/backend/database)). A delivery runs inside one database transaction, as no user (`anon`), as the platform's events do: what it writes, it writes through `Database.$asService()`. All of it commits when the handler returns, or none of it when it throws.

## What a handler returns

What the handler returns is what the sender gets:

| The handler returns | The sender gets |
|---|---|
| nothing (`undefined` or `null`) | `200 { ok: true, handled: true }` |
| a `Response` | that response, as it is: its status, headers and body |
| a string | `200` with it as the body: `text/xml` for `twilio` (TwiML), `text/plain` for any other |
| anything else | `200` with it as JSON: Slack's `{ challenge }`, Discord's `{ type: 1 }` to a `PING` |

```ts
// src/modules/discord/discord.webhook.ts
import { On, Webhook } from "palbase/backend";

@Webhook({ name: "discord", provider: "discord", secret: { env: "DISCORD_PUBLIC_KEY" } })
export class DiscordWebhook {
  // Discord pings the URL when it is set, and keeps it only if it answers a PONG.
  @On("PING")
  ping(): { type: number } {
    return { type: 1 };
  }

  @On("INTERACTION_CREATE")
  interaction(event: { data?: { name?: string } }): { type: number; data: { content: string } } {
    return { type: 4, data: { content: `You ran /${event.data?.name ?? "?"}` } };
  }
}
```

A Twilio number's incoming messages carry no `EventType`, so `@On("")` takes them, and a string it returns goes back to Twilio as TwiML (`text/xml`):

```ts
// src/modules/sms/sms.webhook.ts
import { Log, On, Webhook } from "palbase/backend";

interface IncomingSms {
  MessageSid: string;
  From: string;
  Body: string;
}

@Webhook({ name: "sms", provider: "twilio", secret: { env: "TWILIO_AUTH_TOKEN" } })
export class SmsWebhook {
  // A plain incoming message names no event type: "" takes it.
  @On("")
  incoming(event: IncomingSms): string {
    Log.info("sms in", { sid: event.MessageSid, from: event.From });
    return '<?xml version="1.0" encoding="UTF-8"?><Response><Message>Thanks, we got it.</Message></Response>';
  }
}
```

Give Twilio `https://<ref>.app.palbase.studio/webhooks/sms` as the number's **A message comes in** webhook, method `POST`.

## What the sender sees

The sender decides from the status whether to deliver again, so every answer says what happened:

| Status | When | The sender |
|---|---|---|
| `200` | Handled; or no `@On` takes its type (`handled: false`); or a delivery already run (`handled: false, duplicate: true`) | stops |
| `401 invalid_signature` | The signature does not check: its `error_description` ends with `missing_signature`, `malformed_signature`, `stale_timestamp` or `signature_mismatch` | retries, and a forger gets nowhere |
| `405 method_not_allowed` | Not a `POST` | — |
| `409 in_progress` | The same delivery (by its id) is being handled right now; `Retry-After: 5` | delivers it again |
| `413 payload_too_large` | The body is over its cap: the smaller of what that sender sends and the app's `bodyLimit` ([Providers](#providers)) | — |
| `500 handler_failed` | The handler threw | delivers it again, later |
| `503` | What the handler needed of the platform did not answer: `auth_unavailable`, `service_unavailable` (a module call that answered 429, 502, 503 or 504, or never arrived), or the database's `database_unavailable`; with `Retry-After` | delivers it again, after the wait |

A delivery needs no API key and no user token: the signature is its only credential, and nothing else is checked. A missing signature header is refused before a byte of the body is read.

The reason for a failure stays in the app's log, under the request id: the `500` says only `The event could not be handled`, because a sender may show its answers to anyone who can open its dashboard. Refusals are counted, and the counts logged at most once a minute per webhook, so a stream of forged deliveries cannot fill the log.

## Duplicates and replays

Senders deliver **at least once**: a delivery whose answer was lost is sent again. The framework remembers the deliveries it ran, up to the last 10,000 per webhook, and acknowledges one sent again with `duplicate: true` instead of running it twice. What it remembers a delivery by comes from **what the sender signed**, never from a header alone:

| Sender | Remembered by | A captured delivery sent again by someone else |
|---|---|---|
| Stripe, Slack, Discord, LiveKit, SendGrid | the id inside the signed body (`id`, `event_id`, each event's `sg_event_id`), when it has one: a Slack interactivity payload or `url_verification` has none | is not run again within five minutes, and is refused after: they sign a time |
| GitHub | `X-GitHub-Delivery` with the SHA-256 of the body | is **run again** under a fresh `X-GitHub-Delivery`: GitHub signs neither a time nor an id |
| Twilio | `I-Twilio-Idempotency-Token` with the SHA-256 of the URL and parameters signed | is **run again** under a fresh token: Twilio signs neither a time nor an id |
| a spelled-out `signature` | nothing | is run again every time, and without `{ts}` it verifies whenever it is sent |

So the sender's own retry is run once: GitHub keeps the delivery's GUID on a redelivery, and Twilio's token is there to tell its retries apart. A delivery replayed under another id by whoever holds a copy of it, from a log or a proxy, is run again for GitHub, Twilio and a template without `{ts}`. For a SendGrid batch the framework keeps the events it has not run and hands the handler those alone.

That memory is one copy's, in its memory. Another copy of the machine, or the same one after a restart, runs a delivery again. So:

- **Write handlers to be idempotent.** Key what they write on the event's own ids (`invoice.id`, a `MessageSid`, a payload's ids) with a unique constraint or an upsert, so a second run changes nothing.
- **Check what a handler acts on.** For GitHub and Twilio, a delivery's authenticity does not say it is new, and their event name or parameters are not wholly signed ([Providers](#providers)). Look up the object the event names before you act on it.

## The contract

A `@Webhook` is part of the app's contract — written by its build, kept by the platform with it — which Studio's backend screens read: `POST /webhooks/<name>`, with `x-palbase-webhook` saying who sends it (`provider`, or the `signatureHeader` of a spelled-out scheme), the variable its secret is read from (`secretEnv`, the name alone) and the event types its `@On` take (`events`).

## The `webhooks` path segment

`webhooks` is the platform's first path segment, never a controller's. `@Controller` refuses a base path that starts with it, the app does not start with a route whose path begins with it, and a request to a `/webhooks/<name>` no `@Webhook` has answers `404`. `/webhooks/palbase` is the platform's own events ([Event Hooks](/docs/backend/hooks)); every other `/webhooks/<name>` belongs to the `@Webhook` of that name.

## Testing

A delivery is a signed `POST`, so a test signs one the way the sender does and hands it to the app. With the webhook's secret in the app's `env`:

```ts
// src/modules/billing/stripe.webhook.test.ts
import { createHmac } from "node:crypto";
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { Module, On, PalbaseFactory, Webhook, type PalbaseApplication } from "palbase/backend";

const seen: string[] = [];

@Webhook({ name: "stripe", provider: "stripe", secret: { env: "STRIPE_WEBHOOK_SECRET" } })
class TestStripeWebhook {
  @On("invoice.paid")
  paid(event: { id: string }): void {
    seen.push(event.id);
  }
}

@Module({ providers: [TestStripeWebhook] })
class TestModule {}

const secret = "whsec_test_0123456789";
const env = {
  PALBASE_URL: "https://abcd1234.palbase.studio",
  PALBASE_PROJECT_ID: "11111111-2222-3333-4444-555555555555",
  PALBASE_SECRET_KEY: "pb_abcd1234_s0123456789abcdef0123456789abcdef",
  STRIPE_WEBHOOK_SECRET: secret,
};

/** A delivery as Stripe signs one: HMAC-SHA256 of "<t>.<body>". */
function stripeDelivery(event: { id: string; type: string }, key = secret): Request {
  const body = JSON.stringify(event);
  const t = Math.floor(Date.now() / 1000);
  const v1 = createHmac("sha256", key).update(`${t}.${body}`).digest("hex");
  return new Request("http://app.test/webhooks/stripe", { method: "POST", body, headers: { "stripe-signature": `t=${t},v1=${v1}` } });
}

let app: PalbaseApplication;
beforeAll(async () => {
  app = await PalbaseFactory.create(TestModule, { env, port: 0, host: "127.0.0.1", exitOnFatal: false });
});
afterAll(() => app.close());

describe("the Stripe webhook", () => {
  it("runs a paid invoice once, however often it is delivered", async () => {
    expect((await app.handle(stripeDelivery({ id: "evt_1", type: "invoice.paid" }))).status).toBe(200);
    const again = await app.handle(stripeDelivery({ id: "evt_1", type: "invoice.paid" }));
    expect(await again.json()).toMatchObject({ handled: false, duplicate: true });
    expect(seen).toEqual(["evt_1"]);
  });

  it("refuses a delivery signed with another secret", async () => {
    const res = await app.handle(stripeDelivery({ id: "evt_2", type: "invoice.paid" }, "whsec_someone_else"));
    expect(res.status).toBe(401);
    expect(await res.json()).toMatchObject({ error: "invalid_signature" });
  });
});
```

`getWebhookManifest(StripeWebhook)` reads what a class declares (its `name`, `provider`, `secretEnv` and `events`) without building it, for a test that pins the wiring. See [Testing](/docs/backend/testing) for the rest of a backend's tests.

## Related

- [Event Hooks](/docs/backend/hooks) — the platform's own events, at `/webhooks/palbase`
- [Server SDK: Webhooks](/docs/server/webhooks) — the platform's events delivered to any other server
- [Secrets](/docs/backend/secrets) — where a webhook's signing secret is kept
- [Database](/docs/backend/database) — `$asService()` and the delivery's transaction
- [Controllers & Routing](/docs/backend/controllers) — the paths that are the platform's
- [Testing](/docs/backend/testing) — building the app in a test



<!-- ===== backend/hooks ===== -->

# Event Hooks

The project's modules announce what happens in them as **events**: a user deleted, a file uploaded, a secret changed, a message sent. A backend handles one with `@On("<type>")` on a method of a provider class. The platform delivers each event to the project's webhook endpoint as a signed `POST`. `palbase/backend` receives it at `/webhooks/palbase`, checks the signature, and runs every handler of that type once, inside one database transaction.

These are the **platform's** events. A third party's — Stripe, GitHub, Slack — arrive at `/webhooks/<name>` and are taken by `@On` inside a `@Webhook` class: see [Webhooks](/docs/backend/webhooks).

## Quick example

```ts
// src/modules/accounts/account-events.ts
import { Injectable, Log, On, Palbase, type WebhookEvent } from "palbase/backend";
import { pages } from "palbase/server";

@Injectable()
export class AccountEvents {
  @On("user.deleted")
  async userDeleted(event: WebhookEvent<{ user_id: string }>, meta: { requestId: string }): Promise<void> {
    // The user's files go with them: every page of their prefix, then each object.
    const prefix = `users/${event.data.user_id}/`;
    const paths: string[] = [];
    for await (const page of pages((cursor) => Palbase.storage.listObjects({ path: { bucket: "uploads" }, query: { prefix, cursor } }))) {
      paths.push(...page.objects.map((o) => o.path));
    }
    for (const path of paths) await Palbase.storage.deleteObject({ path: { bucket: "uploads", path } });
    Log.info("removed a deleted user's uploads", { user: event.data.user_id, files: paths.length, delivery: meta.requestId });
  }
}
```

```ts
// src/modules/accounts/accounts.module.ts
import { Module } from "palbase/backend";
import { AccountEvents } from "./account-events";

@Module({ providers: [AccountEvents] })
export class AccountsModule {}
```

The class is a provider like any other: its module lists it in `providers`, and it takes its dependencies by constructor. `@On` marks it as a handler class, so it may also stand without `@Injectable()`. Add `@Injectable()` whenever it has constructor parameters, because TypeScript emits their types only for a decorated class.

## What a handler is given

```ts
// src/modules/files/file-events.ts
import { Injectable, Log, On, type WebhookEvent } from "palbase/backend";

@Injectable()
export class FileEvents {
  @On("file.uploaded")
  uploaded(event: WebhookEvent, meta: { requestId: string }): void {
    Log.info("a file arrived", { event: event.id, type: event.type, at: event.created_at, delivery: meta.requestId, data: event.data });
  }
}
```

| Field of `WebhookEvent<T>` | What it is |
|---|---|
| `id` | The event's id. The same id twice is the same event, delivered again. |
| `type` | Dotted lowercase words: `user.deleted` |
| `project_id` | The project it happened in |
| `created_at` | When it happened |
| `data` | What the module says of it, typed `T` when you give one |

`meta.requestId` is the delivery's request id: every `Log` line the handler writes carries it. `@On(type)` takes the type as dotted lowercase words (`user.deleted`). Anything else throws when the class is declared. One method handles one type. A type may have handlers in several classes, and they all run.

## Events

Each module's contract names what it emits. Among them:

| Event | From |
|---|---|
| `user.deleted` | auth: `data` is `{ user_id }` |
| `file.uploaded`, `file.deleted`, `file.moved` | storage |
| `secret.changed` | secrets (its name, never its value) |
| `notification.sent`, `notification.failed` | notify |
| `machine.created`, `machine.updated`, `machine.deleted` | machines |
| `database.created`, `database.deleted`, `database.password_changed`, … | machines |

Type `data` for the events you handle: `WebhookEvent<{ user_id: string }>`. The framework checks only the envelope (`id`, `type`, `project_id`, `created_at`, `data`).

## How a delivery runs

1. **The signature.** The platform signs each delivery with the endpoint's secret: `Palbase-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>`. The app checks it against `PALBASE_WEBHOOK_SECRET` over the body exactly as it arrived, with `t` within five minutes of now. Anything else is `401 invalid_signature`, naming `missing_signature`, `malformed_signature`, `stale_timestamp` or `signature_mismatch`, and no handler runs. A request that is not a `POST` is `405`.
2. **Once.** An event already handled by this process is acknowledged again (`204`) and not run again. One whose first delivery is still running is answered `409 in_progress` with `Retry-After: 5`.
3. **One transaction.** Every handler of the type runs in order, inside **one** database transaction when the app has a database. Either all their work commits, or none of it does.
4. **The answer.** All handlers returned: `204`. One threw: the transaction is rolled back, the error is logged with the handler's name, and the answer is `500 handler_failed`. The platform then delivers the event again, with a growing delay, up to twelve attempts. A type with no handler is acknowledged with `204`.

The payload is data, like a request's body: the database takes values from `event.data`, never a filter's structure.

> **Note:** "Once" is per process, for the last 10,000 events. A machine with several copies, or one that restarted, can run an event a second time. Make a handler safe to run twice, keyed on `event.id` or on what the event names, as deleting what is already deleted is.

### The database inside a delivery

A delivery has no caller, so its transaction is `anon` with no claims, and no policy that reads `auth.uid()` admits it. Work that writes users' rows goes through `Database.$asService()`:

```ts
// src/modules/accounts/forget.ts
import { Database, Injectable, On, type WebhookEvent } from "palbase/backend";

@Injectable()
export class ForgetAudit {
  @On("user.deleted")
  async record(event: WebhookEvent<{ user_id: string }>): Promise<void> {
    await Database.$asService().$query("insert into deletion_log (user_id, event_id) values ($1, $2)", [event.data.user_id, event.id]);
  }
}
```

### `user.deleted` and the tables that keep users

An app whose schema keeps users' ids (columns declared with `ownedByUser()` or `userRef()`) handles `user.deleted` without writing a handler. The framework's own handler runs first, in the same transaction: it deletes the rows the user owned and clears the references to them. Your `@On("user.deleted")` handlers run after it. See [Schema](/docs/backend/schema).

## What the app needs to receive events

An app that has an `@On` handler, or whose schema keeps users' ids, must know the endpoint's secret. On a machine the platform gives it as `PALBASE_WEBHOOK_SECRET`; anywhere else the app reads it from there (`whsec_` and 64 hex characters), or from `PalbaseFactory.create(…, { palbase: { webhookSecret } })`. Without it the app does not start:

```text
[palbase] the app cannot start:
  - palbase.webhookSecret / PALBASE_WEBHOOK_SECRET is the project's webhook endpoint secret (whsec_…): the platform delivers this app events — its @On handlers', or user.deleted for the users its tables keep
```

The platform keeps the machine's endpoint itself: the machine's address followed by `/webhooks/palbase`, for example `https://<name>-<ref>.app.palbase.studio/webhooks/palbase`, sent exactly the events the app takes — its `@On` types, and `user.deleted` when its schema keeps users' ids. It reads them from the app's contract once a version serves alone, so a push or a rollback that changes what the app takes changes the endpoint with it. The endpoint is listed under **Settings › Webhooks** as the machine's; it cannot be changed or deleted there, and it goes with the machine. A machine whose app takes no events has none.

Any other server receives the same deliveries with `palbase/server`'s `verifyWebhook`. See [Webhooks](/docs/server/webhooks).

## Testing a handler

A delivery is an ordinary signed request, so a test can make one and hand it to the app. See [Testing](/docs/backend/testing) for building the app in a test. The signature is the HMAC of `"<t>.<body>"`:

```ts
// test/deliver.ts
import { createHmac } from "node:crypto";

export function delivery(secret: string, event: { id: string; type: string; data: unknown }): Request {
  const body = JSON.stringify({ ...event, project_id: "11111111-2222-3333-4444-555555555555", created_at: new Date().toISOString() });
  const t = Math.floor(Date.now() / 1000);
  const v1 = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
  return new Request("http://app.test/webhooks/palbase", {
    method: "POST",
    body,
    headers: { "content-type": "application/json", "palbase-signature": `t=${t},v1=${v1}` },
  });
}
```

## Related

- [Webhooks](/docs/backend/webhooks): a third party's deliveries, with `@Webhook`
- [Server SDK: Webhooks](/docs/server/webhooks): the same deliveries, to any server
- [Database](/docs/backend/database): `$asService()` and the request's transaction
- [Schema](/docs/backend/schema): `ownedByUser()` and `userRef()`
- [Modules & Dependency Injection](/docs/backend/modules): providers
- [Testing](/docs/backend/testing): building the app in a test



<!-- ===== backend/cron ===== -->

# Cron

A cron is a class the platform runs on a schedule: a nightly report, an hourly cleanup, a digest every Monday at 9 in the morning, Istanbul time. Mark a provider with `@Cron({ name, schedule })` and give it a `run(meta)` method. When the machine's version comes up, the platform asks it which crons it has. It then calls each one when it is due, waking the machine if it sleeps.

Work that comes from something that happened — an order paid, a file uploaded — is not a cron that looks every minute for what to do: put it on the machine's queue as a [task](/docs/backend/tasks), and it runs once, as soon as it is put, with the machine asleep in between.

## Quick example

The tables the cron works on:

```ts
// src/db/public.ts
import { defineSchema, defineTable, integer, ownedByUser, policy, text, timestamp, uuid } from "palbase/backend";

export const profiles = defineTable("profiles", {
  columns: { id: uuid().primaryKey().defaultRandom(), owner: ownedByUser(), name: text(), created_at: timestamp().defaultNow() },
  policies: (p) => [policy("profiles_own").for("all").using(p.col("owner").eq(p.auth.uid())).withCheck(p.col("owner").eq(p.auth.uid()))],
});

export const upload_sessions = defineTable("upload_sessions", {
  columns: { id: uuid().primaryKey().defaultRandom(), owner: ownedByUser(), expires_at: timestamp() },
  policies: (p) => [policy("uploads_own").for("all").using(p.col("owner").eq(p.auth.uid())).withCheck(p.col("owner").eq(p.auth.uid()))],
});

// The app's own: no policy lets a user reach it, the service role does.
export const daily_reports = defineTable("daily_reports", {
  columns: { run_id: text().primaryKey(), signups: integer(), made_at: timestamp().defaultNow() },
});

export default defineSchema("public", { tables: [profiles, upload_sessions, daily_reports] });
```

```ts
// src/modules/reports/daily-signups.cron.ts
import { Cron, Database, Log, type CronMeta } from "palbase/backend";
import { ago } from "palgres";

// Every day at 06:00 in Istanbul: the last day's sign-ups, counted into one row.
@Cron({ name: "daily-signups", schedule: "0 6 * * *", timeZone: "Europe/Istanbul", timeout: 120, retry: 3 })
export class DailySignups {
  async run(meta: CronMeta): Promise<void> {
    const signups = await Database.public.profiles.count({ where: { created_at: { gte: ago({ days: 1 }) } } });
    // Keyed on the run: an attempt made again finds its row there, and writes no second one.
    await Database.public.daily_reports.insertMany([{ run_id: meta.runId, signups }], { action: "ignore", returning: false });
    Log.info("daily sign-ups", { signups, run: meta.runId, attempt: meta.attempt });
  }
}
```

```ts
// src/modules/reports/upload-sweep.cron.ts
import { Cron, Database, Log } from "palbase/backend";
import { now } from "palgres";

// Every 15 minutes: the upload sessions that expired, removed.
@Cron({ name: "upload-sweep", schedule: "*/15 * * * *" })
export class UploadSweep {
  async run(): Promise<void> {
    const gone = await Database.public.upload_sessions.deleteMany({ where: { expires_at: { lt: now() } } });
    Log.info("expired upload sessions removed", { gone });
  }
}
```

```ts
// src/modules/reports/reports.module.ts
import { Module } from "palbase/backend";
import { DailySignups } from "./daily-signups.cron";
import { UploadSweep } from "./upload-sweep.cron";

@Module({ providers: [DailySignups, UploadSweep] })
export class ReportsModule {}
```

A cron is a provider like any other: its module lists it in `providers`, and it takes its dependencies by constructor — a service whose method does the work, for one. A class is one cron. A controller that is a `@Cron` is refused at boot, because a controller is not where crons live.

## The schedule

Five fields, as cron's, on the clocks of the cron's time zone — **UTC** unless `timeZone` names one: minute, hour, day of the month, month, day of the week.

| Field | Values |
|---|---|
| minute | 0–59 |
| hour | 0–23 |
| day of the month | 1–31 |
| month | 1–12 |
| day of the week | 0–7 (0 and 7 are Sunday) |

Each field is `*`, a number, a list (`1,15`), a range (`1-5`), or a step (`*/10`, `10/20`, `8-18/2`). When both day fields are given, a day that matches either one counts, as in classic cron. There are no seconds and no `@daily`-style names.

A schedule the platform would not run is refused where `@Cron` is written: six fields, `@daily`, `60 * * * *`, or a date that never comes (`0 0 31 2 *`).

### Time zones

`timeZone` is a time zone's IANA name — `Europe/Istanbul`, `America/New_York`, `Asia/Kolkata` — and the schedule is read on its clocks. Where they change for summer time, the platform keeps to one rule, so a cron is never run twice for one time:

- A time the clocks **skip** (02:30 on the night they go from 02:00 to 03:00) is not run that day.
- A time the clocks **show twice** (02:30 on the night they go back from 03:00 to 02:00) is run the first time only.

A cron that must run every so often, whatever the clocks do, is written in UTC.

## Options

| Option | What it is | Default |
|---|---|---|
| `name` | What the platform calls the cron and keeps its runs under. Letters, digits, `.`, `_` and `-`, at most 64. | required |
| `schedule` | Five fields of cron's | required |
| `timeZone` | The IANA time zone whose clocks the schedule is on | `UTC` |
| `timeout` | Seconds one run may take before it is a failed attempt: 1–900 | 30 |
| `retry` | Attempts after a failed one: 0–10 | 5 |

Renaming the cron starts a new one: the old name's runs stay under it. Two crons of one name are refused at boot, naming both. A machine runs at most 50 crons.

## How a run goes

1. **Due.** The platform calls the cron at its minute, waking the machine if it is asleep, on one of its copies. One run of a cron is open at a time: a cron due again while its last run is still going is skipped for that minute. While the machine is held at the call, it is not put to sleep.
2. **Signed.** The call is `POST /_palbase/crons/<name>`, signed with the machine's `PALBASE_PLATFORM_SECRET` in `Palbase-Signature`, as the platform's other calls into a machine are. Anything not signed by the platform is `401`, and nothing runs. A request for these paths from the internet never reaches the machine: its edge answers `404`.
3. **One transaction, as the service role.** `run` runs in a database transaction of its own, given its `CronMeta`. A cron has no caller, so its transaction is the **service role's**: every row is in reach and no policy filters it. That differs from a [delivery](/docs/backend/hooks), which runs as `anon`.
4. **Done or failed.** `run` returned: the run succeeded (`204`). It threw — anything, a `NotFound` too: the transaction is rolled back, the error is logged with the cron's name, the run and the attempt, and the attempt failed (`500`). It ran past its `timeout`: the platform hangs up, and what the attempt wrote is rolled back even if it returns later. A failed attempt is tried again after 10 s, 20 s, 40 s, … five minutes at most, until `retry` is spent.
5. **Once.** An attempt that ended is answered `204` if the same call comes again; one still running is answered `409` and is not run beside itself.

A cron this version no longer has is answered `404`: the platform skips the run and does not try it again. A project whose machine time for the period is used up runs no cron: its runs are skipped until the time comes back.

## Run now, pause and resume

From the machine's **Crons** tab in Studio, or the CLI — an admin's, as every change is:

| | Studio | CLI |
|---|---|---|
| Run a cron now, apart from its schedule | Run now | `palbase machines:crons:run <cron>` |
| Pause it: it is not run until resumed, whatever version of the machine comes up meanwhile | Pause | `palbase machines:crons:pause <cron>` |
| Resume it: due at its next time from now — the runs it missed are not made up | Resume | `palbase machines:crons:resume <cron>` |

A run asked for now is marked as such among the runs, and waits its turn behind a run still going (`409` while one is). A pause is the project's, not the program's: a deploy does not undo it.

## What a cron is given

| Field of `CronMeta` | What it is |
|---|---|
| `env` | The app's environment variables as it started, the platform's keys left out |
| `environmentId` | The project's id |
| `cron` | The cron's name |
| `runId` | The run's id. It is the same for every attempt of one run. |
| `scheduledAt` | The minute it was due (or was asked to run now), as a `Date` |
| `attempt` | 1 for the first, then one more for each attempt made again |

> **Note:** An attempt can run and still be counted as failed: the machine finished, but its answer never reached the platform. The next attempt runs it again. Make a cron safe to run twice, keyed on `runId` or on what it works on, as the report above is.

## Seeing the runs

The crons a machine's running version declared, and each one's runs, are on its **Crons** tab in Studio and in the CLI (`palbase machines:crons`, `palbase machines:crons:runs <cron>`). They are also in the API: `GET /machines/<machine>/crons` and `GET /machines/<machine>/crons/<name>/runs`, with the project's secret key.

## On your computer

Off the platform there is no `PALBASE_PLATFORM_SECRET`, so `/_palbase/crons` is not served and nothing calls a cron. The app says how many crons it has when it starts. To run one, call its `run` from a test:

```ts
// src/modules/reports/upload-sweep.cron.test.ts
import { describe, expect, it } from "vitest";
import { UploadSweep } from "./upload-sweep.cron";

describe("UploadSweep", () => {
  it("is a class like any other", () => {
    expect(typeof new UploadSweep().run).toBe("function");
  });
});
```

The database work in a cron needs a request's database, as a handler's does: see [Testing](/docs/backend/testing).

## Related

- [Tasks](/docs/backend/tasks): work put on the machine's queue, run once, now or later
- [Event Hooks](/docs/backend/hooks): the platform's events, delivered as they happen
- [Database](/docs/backend/database): the transaction a cron runs in
- [Modules & Dependency Injection](/docs/backend/modules): providers and their modules



<!-- ===== backend/tasks ===== -->

# Tasks

A task is work your backend puts on its machine's queue to be done once, now or later: a receipt mailed when an order is paid, a reminder a day after sign-up, a report built in the background. Mark a provider with `@Task({ name })` and give it a `run(payload, meta)` method; put a task with `Tasks.enqueue(TheClass, payload)`. The platform keeps the queue. When a task is due it wakes the machine and calls `run`; an attempt that fails is made again later, and a task with no attempt left is kept, to be tried again from Studio or the CLI.

Nothing polls: a machine with no task due sleeps. A [cron](/docs/backend/cron) that wakes every minute to look in a table for work keeps it awake for nothing, and takes up to a minute to notice.

## Quick example

The table the task works on:

```ts
// src/db/public.ts
import { defineSchema, defineTable, text, timestamp, uuid } from "palbase/backend";

// The app's own: no policy lets a user reach it, the service role does.
export const orders = defineTable("orders", {
  columns: { id: uuid().primaryKey().defaultRandom(), email: text(), receipt_sent_at: timestamp().nullable() },
});

export default defineSchema("public", { tables: [orders] });
```

```ts
// src/modules/orders/send-receipt.task.ts
import { Database, Log, Notifications, Task, TaskFailure, z, type TaskMeta } from "palbase/backend";
import { now } from "palgres";

const Receipt = z.object({ orderId: z.string().uuid() });

// Mail an order's receipt. A failed attempt is made again: up to five more, 10 s, 20 s, 40 s… apart.
@Task({ name: "send-receipt", payload: Receipt, retry: 5, concurrency: 10 })
export class SendReceipt {
  async run(payload: z.infer<typeof Receipt>, meta: TaskMeta): Promise<void> {
    const order = await Database.public.orders.findUnique({ where: { id: payload.orderId } });
    // The order is gone: no attempt will ever find it.
    if (!order) throw new TaskFailure(`order ${payload.orderId} is gone`);
    if (order.receipt_sent_at) return; // an attempt made again after one that finished
    await Notifications.email.send({ to: order.email, templateSlug: "receipt", variables: { order: order.id } });
    await Database.public.orders.update({ where: { id: order.id }, set: { receipt_sent_at: now() } });
    Log.info("receipt sent", { order: order.id, task: meta.id, attempt: meta.attempt });
  }
}
```

```ts
// src/modules/orders/orders.controller.ts
import { Controller, Param, Post, Tasks } from "palbase/backend";
import { SendReceipt } from "./send-receipt.task";

@Controller("/orders")
export class OrdersController {
  @Post("/{id}/paid")
  async paid(@Param("id") id: string) {
    // Put once per order: the same key again answers the task already put.
    const task = await Tasks.enqueue(SendReceipt, { orderId: id }, { key: `receipt:${id}` });
    return { receipt: task.id };
  }
}
```

```ts
// src/modules/orders/orders.module.ts
import { Module } from "palbase/backend";
import { OrdersController } from "./orders.controller";
import { SendReceipt } from "./send-receipt.task";

@Module({ controllers: [OrdersController], providers: [SendReceipt] })
export class OrdersModule {}
```

A task type is a provider like any other: its module lists it in `providers`, and it takes its dependencies by constructor. A class is one task type.

## Putting a task

```ts
// src/modules/users/reminders.ts
import { Task, Tasks, type TaskMeta } from "palbase/backend";
import { SendReceipt } from "../orders/send-receipt.task";

@Task({ name: "remind" })
export class Remind {
  async run(payload: { userId: string }, meta: TaskMeta): Promise<void> {
    console.log(`remind ${payload.userId} (task ${meta.id})`);
  }
}

export async function put(orderId: string, userId: string, trialEnds: string): Promise<void> {
  await Tasks.enqueue(SendReceipt, { orderId });                       // due now
  await Tasks.enqueue(Remind, { userId }, { delay: 24 * 3600 });       // in a day
  await Tasks.enqueue(Remind, { userId }, { runAt: new Date(trialEnds) });
  await Tasks.enqueue(SendReceipt, { orderId }, { key: `receipt:${orderId}` });
}
```

What `Tasks.enqueue` takes is checked as it is written: the payload is what the class's `run` takes, and anything else does not compile. It answers the task as it was put — `id`, `state`, `runAt` — and `duplicate: true` when a task of the type was put already under the same key.

| Option | What it is |
|---|---|
| `delay` | Due this many seconds from now: 30 days at most |
| `runAt` | Due at this time: 30 days from now at most; a time past is now |
| `key` | Put once: another task of the type under the same key, until a day after the first is over, is not put — the first is answered |

A task carries 64 KiB of JSON at most, kept and handed to `run` as the bytes it was given: name what it works on — an id — and read it where it runs. A project's queues hold 100,000 tasks not yet done, or 256 MiB of what the tasks kept carry; past that, `Tasks.enqueue` is refused (`429`, `queue_full`) until some are done.

`Tasks.cancel(id)` takes a task that is waiting off the queue; `Tasks.get(id)` reads one as it is now. A task of another of the project's machines is put by its type's name: `Tasks.enqueue("rebuild-index", payload, { machine: "search" })`.

## Options

| Option | What it is | Default |
|---|---|---|
| `name` | The task type: what its tasks are put under, kept under and called by. Letters, digits, `.`, `_` and `-`, at most 64. | required |
| `payload` | A schema (zod, valibot, arktype — any Standard Schema) what a task carries is checked against before `run`; `run` is given what it gives | none |
| `timeout` | Seconds one attempt may take before it is a failed one: 1–900 | 60 |
| `retry` | Attempts after a failed one: 0–20 | 5 |
| `concurrency` | How many of its tasks the machine runs at once, however many copies it has: 1–50 | 5 |

A machine has at most 50 task types; two of one name are refused at boot.

## How a task goes

1. **Due.** When its time comes, the platform calls the machine for it — waking it if it sleeps — once the type has room under its `concurrency` (and the project under 50 at once). Tasks are taken type by type, oldest first: one type's backlog holds no other's back.
2. **Signed.** The call is `POST /_palbase/tasks/<name>`, signed with the machine's `PALBASE_PLATFORM_SECRET`, as the platform's other calls into a machine are. Nothing from the internet reaches it.
3. **Checked, then run in one transaction, as the service role.** What it carries is checked against `payload`, then `run` runs in a database transaction of its own, given its `TaskMeta`, with every row in reach as a [cron](/docs/backend/cron)'s is.
4. **Done, failed for good, or made again.**
   - `run` returned: the task succeeded.
   - What it carries is not what `payload` takes, or `run` threw a `TaskFailure`: the task **failed** at once and is not tried again — no attempt would do better.
   - `run` threw anything else, or ran past its `timeout`: the attempt failed and its transaction is rolled back. The next one is made after 10 s, then 20 s, 40 s, … an hour apart at most, until `retry` is spent; then the task **failed**.

A task that succeeded lets go of what it carried; only a task that may be tried again keeps it.

A task is delivered **at least once**: its `id` is the same through every attempt, and an attempt can run and still be counted as failed (the machine finished, its answer was lost). Key the work on the task's `id`, or on what it works on, as the receipt above does with `receipt_sent_at`.

A project whose machine time for the period is used up runs no task: a task due then fails ("its machine time for the period is used up"), and none is put meanwhile (`429`, `quota_exceeded`). Once the time comes back, the failed ones are tried again by hand — not run in a heap the moment it does.

## What a task is given

| Field of `TaskMeta` | What it is |
|---|---|
| `env` | The app's environment variables as it started, the platform's keys left out |
| `environmentId` | The project's id |
| `task` | The task type's name |
| `id` | The task's id: the same for every attempt of it |
| `attempt` | 1 for the first, then one more for each attempt made again |
| `createdAt` | When it was put on the queue |

## Failed tasks

A task that succeeded or was cancelled is kept a day; one that failed, 30 — with why its last attempt failed. On the machine's **Tasks** tab in Studio, or with the CLI:

| | Studio | CLI |
|---|---|---|
| The types, and what each one's queue holds | Task types | `palbase machines:tasks:types` |
| The tasks, of one state or type | Tasks, with Show | `palbase machines:tasks --state failed` |
| A task, with what it carries | | `palbase machines:tasks:get <id>` |
| Try a failed task again: due now, with as many attempts again as its type gives — its attempts counted on, not from zero | Retry | `palbase machines:tasks:retry <id>` |
| Take a waiting task off the queue: it is not run, nor tried again, and what it carried is let go | Cancel | `palbase machines:tasks:cancel <id>` |
| Put a task by hand | | `palbase machines:tasks:enqueue <type> --payload '<json>'` |

Trying again and cancelling are an admin's, as every change is; so is reading what a task carries — a member sees the queue, not what is in it.

## On your computer

Off the platform — the app started on your computer, or in a test — it runs its own tasks, in its own process, as the platform would: each when it is due, its type's `concurrency` kept, a failed attempt made again later, a key held a day. Nothing of that queue outlives the process. `Tasks.enqueue` of another machine's type is refused there.

## Without palbase/backend

Any program a machine runs takes tasks by answering two signed calls, as it takes [crons](/docs/machines/overview#crons-and-tasks); anything with the project's secret key puts them: `POST /machines/<machine>/tasks` with `{"task", "payload", "delay" | "run_at", "key"}`.

## Related

- [Cron](/docs/backend/cron): work on a schedule
- [Event Hooks](/docs/backend/hooks): the platform's events, delivered as they happen
- [Database](/docs/backend/database): the transaction a task runs in



<!-- ===== backend/cache ===== -->

# Cache

Every project has a cache: short-lived entries, each a value a server worked out and wants again, kept by the platform rather than in your machine's memory. Every copy of a machine reads the same entries, a push does not empty them, and a machine that slept finds them when it wakes. In a `palbase/backend` app it is `Cache`; from any other server it is `createServer({ url, secretKey }).cache`, the cache module's calls as its contract states them. Only the secret key reaches it: an app never reads or writes the cache.

A cache is not a database. Every entry runs out, after thirty days at most, and an entry may be gone before its time, dropped to make room. What must not be lost belongs in a [database](/docs/backend/database).

## Quick example

```ts
// src/modules/products/products.service.ts
import { Cache, Database, Injectable } from "palbase/backend";

type Product = { id: string; name: string; price_cents: number };

@Injectable()
export class ProductsService {
  /** The catalog, read from the database at most once every five minutes. */
  async catalog(): Promise<Product[]> {
    return Cache.getOrSet("catalog", 300, () => Database.$query<Product>("select id, name, price_cents from products order by name"));
  }

  /** After a change, the next read goes to the database again. */
  async changed(): Promise<void> {
    await Cache.del("catalog");
  }
}
```

## The `Cache` service

| Call | What it does |
|---|---|
| `get<T>(key)` | The value, or `null` when there is none, or when the cache could not be reached |
| `set(key, value, ttl?)` | Writes the value for `ttl` seconds, replacing what was there and its time left. Without a `ttl` it lasts thirty days |
| `getOrSet(key, ttl, fn)` | Reads through: on a hit the value; on a miss `fn`'s, kept for `ttl` seconds |
| `incr(key)` | Adds one to the key's count and answers the new count |
| `del(key)` | Deletes the entry. Deleting what is not there is not an error |

- **A key** is UTF-8 text, 1 to 512 bytes. Every project has keys of its own: no key reaches another project's entries, so a key needs no prefix for that.
- **A value** is JSON, 512 KiB at most. What is kept is what `JSON.stringify` makes of it: a `Date` comes back as its ISO string, a class instance as its fields, `undefined` as `null`. A value written as `null` reads as `null` from `get`, the same as a miss; `getOrSet` counts it as a hit.
- **A `ttl`** is in seconds. A fraction is rounded up; none, `0` or less is thirty days, and more than thirty days is thirty days (`CACHE_MAX_TTL`, which `palbase/backend` exports).

### When the cache cannot be reached

The app is not stopped by a cache that is away. A call that cannot reach it, or that is refused for now (`429`, `503`), is treated by what it is for:

| Call | When the cache is away |
|---|---|
| `get` | A miss: `null`, and a warning in the machine's log |
| `set` | The write is let go, with a warning |
| `getOrSet` | `fn` runs and its value is answered, not kept |
| `del` | Throws: the old value would come back after the delete said it was done |
| `incr` | Throws: there is no number to make up |

A read is sent again first, as every read of the server SDK is, waiting the `Retry-After` the cache asks for. Any other refusal, such as a key longer than 512 bytes or a value larger than 512 KiB, throws a `PalbaseError` from every call ([Server SDK](/docs/server/overview)).

### Reading through: `getOrSet`

On a miss, `fn` is called and its value kept for `ttl` seconds. Misses on the same key that arrive while `fn` runs, in the same process, wait for that one call: a hundred requests that miss at once work the value out once. The sharing is a process's own, so two copies of a machine that miss at the same moment each call `fn`. When `fn` throws, every caller waiting on it gets that error, and nothing is kept.

### Counting: `incr`

`incr` is atomic across every copy of the machine: two callers never get the same number.

```ts
// src/modules/exports/exports.service.ts
import { Cache, Injectable, TooManyRequests } from "palbase/backend";

@Injectable()
export class ExportsService {
  /** A user's exports today, the fifth the last. */
  async allow(userId: string): Promise<void> {
    const day = new Date().toISOString().slice(0, 10);
    const n = await Cache.incr(`exports:${userId}:${day}`);
    if (n > 5) throw new TooManyRequests({ retryAfter: 3600 }, "five exports a day");
  }
}
```

- An entry that is not there, or holds something other than a whole number, counts from zero.
- A count keeps the time its entry had left; a new count lasts thirty days. A count started with `set(key, 0, ttl)` ends with that `ttl`.
- A count stops at fifteen digits: one more is refused (`409 count_too_large`) and nothing is counted.
- `incr` is never sent again by the client. When the cache was reached but did not answer, the count may have been taken: read the entry before counting again.

For a route's own limit on how often a caller may call it, use the route's `rateLimit` ([Controllers & Routing](/docs/backend/controllers)), not a count of your own.

## Room in the cache

An entry weighs what the cache keeps for it: its value plus three times its key, a quarter more, and 320 bytes. A project's entries together weigh at most its quota, 25 MiB.

A write past the quota does not fail. The project's own entries nearest their end are dropped to make room, and the write's answer says how many (`evicted`). When the cache as a whole is full, the project that weighs the most gives back first; a project under its share keeps its entries. One entry larger than the whole quota is refused (`413 entry_too_large`).

A project reads and writes so many bytes a second (8 MiB read, 2 MiB written; the second's first call is taken whatever its size), and makes at most its requests per second of calls to the cache. Past either, a call is `429 rate_limited` with `Retry-After`.

The cache's calls are not counted as the project's API requests, and they are not lines of its request [log](/docs/getting-started/logs). What the project's entries weigh is metered as **Cache memory**, and the bytes its reads carry out as **Cache reads**, on the project's **Settings › Usage** in Studio ([Usage & Limits](/docs/getting-started/usage-and-limits)). A deleted environment's entries are deleted with it.

## From any server

`createServer(...).cache` is the cache module's calls, with the secret key:

```ts
// server/cache.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

const written = await palbase.cache.putCacheEntry({ query: { key: "greeting" }, body: { value: { text: "hello" }, ttl: 600 } });
console.log(written.data.expires_in, written.data.evicted);

const read = await palbase.cache.getCacheEntry({ query: { key: "greeting" } });
if (read.data.found) console.log(read.data.value, read.data.expires_in);

const usage = await palbase.cache.getCacheUsage();
console.log(usage.data.bytes, usage.data.limit_bytes, usage.data.entries);
```

| Call | HTTP | Answers |
|---|---|---|
| `getCacheEntry({ query: { key } })` | `GET /cache/entry?key=` | `{ found, value?, expires_in? }`: a key with no entry is `found: false`, not an error |
| `putCacheEntry({ query: { key }, body: { value, ttl? } })` | `PUT /cache/entry?key=` | `{ expires_in, evicted }`. A `ttl` is 1 to 2592000 seconds; outside it, `400` |
| `deleteCacheEntry({ query: { key } })` | `DELETE /cache/entry?key=` | `{ deleted }`: whether there was an entry |
| `incrementCacheEntry({ query: { key } })` | `POST /cache/entry/increment?key=` | `{ value }`: the new count |
| `getCacheUsage()` | `GET /cache/usage` | `{ bytes, limit_bytes, entries }`: what the live entries weigh, the quota, how many there are |

The key is a query parameter, which the request's log line does not keep. A publishable key is refused (`403 secret_key_required`), and so is the secret key sent with a user's token beside it. A cache that could not be reached is `503 cache_unavailable`, and one that takes no more at this moment `503 cache_busy`; both carry `Retry-After`.

## In tests

`withServices({ Cache: … })` gives the code a cache of the test's own ([Testing](/docs/backend/testing#the-services-the-code-reads-withservices)). A test that does not give one, and runs code that reads `Cache`, is refused by name: the real calls would reach a platform no test serves.

## Related

- [Database](/docs/backend/database) — what must be kept
- [Machines](/docs/machines/overview) — copies, sleep, and what a copy keeps in its own memory
- [Server SDK Overview](/docs/server/overview) — calls, refusals, retries
- [Usage & Limits](/docs/getting-started/usage-and-limits) — what is metered



<!-- ===== backend/translations ===== -->

# Translations

Write the sentences your backend says to people in one language, and `t()` answers each request in the language its caller reads: the first of their languages your app has a translation for, and the language you wrote it in otherwise.

```ts
import { Controller, Post, t } from "palbase/backend";

@Controller("/payments")
export class PaymentsController {
  @Post("/charge")
  charge() {
    // …
    return { message: t("Kartınız reddedildi ({{amount}} ₺)", { amount: 50 }) };
  }
}
```

The sentence itself is the key. `{{name}}` takes a value from the second argument; `{{{name}}}` is left as it is.

## How a request's language is chosen

Every request says its user's languages in `Accept-Language`, best first: a browser sends them, and the iOS and Android SDKs send the device's languages in its order. For each sentence, `t()` takes the first of them your app has a translation of, then the language the sentences are written in.

Each language is matched as a table names it, from the most specific down: `pt-BR` reads `pt-BR.json`, then `pt.json`; `zh-TW` reads `zh-TW.json`, then `zh-Hant.json`, then `zh.json`. A device's regional preferences (`fr-FR-u-mu-celsius`) are not part of the language.

The answer says which: `Content-Language: en` (a list when one answer mixes languages; unless your handler set it). An app with `palbase/strings/` answers every request with `Vary: Accept-Language`, so a cache never hands one user's language to another.

`t()` outside a request — a scheduled job, an event hook, a gateway, the app's start — has no caller to ask, and says the sentence as it is written.

## palbase/strings/

The translations live in your repository, next to the code, one file per language:

```text
palbase/strings/
  _meta.json   { "version": 3, "source": "tr" }
  en.json      { "Kartınız reddedildi ({{amount}} ₺)": "Your card was declined ({{amount}} ₺)" }
  de.json      { "Kartınız reddedildi ({{amount}} ₺)": "" }
```

- `_meta.json` names the language the sentences are written in (`source`). It has no file of its own: its text is the key.
- Each other language is `<language>.json`, named as the language is written (`en`, `de`, `pt-BR`): `"sentence": "translation"`.
- An empty translation is not one yet: that sentence is said in the source language.

Correct a translation in the file and deploy, as any change to your app: the machine reads the table when it starts. The build checks it too: a table that breaks a rule — a file named `EN.json`, a translation that is not a string, a file for the source language, a table still in the earlier format below — stops the build before it takes traffic, and the log names the file and the rule.

Dockerfiles made by `palbase init` 0.3.1 or later copy `palbase/` into the image; check yours, or one you wrote, for `COPY palbase ./palbase`. An app that started without a table says so, with where it looked, the first time `t()` is called.

## Keep the files with the code

Run it in your backend's directory (or below it: it works in the nearest directory up with a `package.json`):

```bash
npx palbase strings --source tr --add en   # start the table: the sentences are in Turkish; en.json is made, empty
npx palbase strings --translate            # fill what is empty
npx palbase strings                        # after a change to the code
npx palbase strings --add de               # one more language
```

`palbase strings` reads every `t("…")` your backend calls — `t` imported from `palbase/backend`, or from a module of your app that re-exports it — with the TypeScript compiler. A sentence new in the code is added to every language's file, empty; a translation is kept. A sentence the code no longer calls is kept too, with its translations, and listed: `--prune` takes it out of every file. Run it again and it changes nothing.

What it cannot read is pointed out, with its file and line: a `t()` whose sentence is not written out (`t(message)` — no file can hold its translation: write the sentence itself, its values as `{{name}}`), and a `t` imported from a module it does not follow (a path alias such as `@/lib/i18n`). If it reads no sentence at all while the table has some, it changes nothing.

A table in the format of the earlier Palbase (`"version": 2`, a `{"value", "state"}` object for each sentence) is written in this one the first time you run it, every translation kept; until then the app does not start with it.

## Translate with your AI module

```bash
npx palbase strings --translate
```

Each empty translation of a sentence the code calls is sent to your environment's AI module — the same models, usage and cost as any other call your project makes, under your own key on this computer — and written into the file as it comes back. On the production environment it asks first: its AI budget is the one your app's own calls use. A translation that does not keep every `{{placeholder}}` of its sentence, or comes back empty, is not taken: it is listed, and stays empty. The command ends with what it cost, from your environment's AI usage (or says when not every call is there yet).

A translation is used as it is written: read the files' diff before you commit it, and correct it there.



<!-- ===== backend/test-users ===== -->

# Test Users

A **test user** is a real user of the project — it signs in, gets tokens, owns rows and files — made with the project's secret key for testing, and marked as such everywhere it goes. Test users are created email-verified, skip the breach check and the password's minimum length, are not counted as active users, and only test users can be deleted through the test-user route, so a cleanup that goes wrong cannot take a real account with it. Your backend sees the mark: `user.test` is `true` on a test user's requests.

## Quick example

```ts
// scripts/make-test-users.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

// Three users with generated credentials, and an access token each.
const made = await palbase.auth.adminCreateTestUsers({ body: { count: 3, with_tokens: true } });
for (const u of made.data.users) {
  // The password is shown once: keep what you need now.
  console.log(u.user_id, u.email, u.password, u.access_token?.slice(0, 16));
}
```

## Making them

`POST /admin/test-users` (`auth.adminCreateTestUsers`) creates up to 1000 at a time — **all of them, or none** — and answers their credentials once: a password is never retrievable afterwards.

| Body | What it makes |
|---|---|
| `{ count: n }` | `n` users with generated emails and passwords. |
| `{ users: [{ email, password }] }` | Users with exactly these credentials; `users` wins when both are sent. |
| `{ users: [{ email, password, phone, otp }] }` | Also a verified phone, and the fixed six-digit code that phone accepts at sign-in — so a phone sign-in can be tested without a text being sent. |
| `with_tokens: true` | Also an access token per user, for calls made as them. |

Each answered user carries `user_id`, `email`, `password` and, with `with_tokens`, `access_token`.

| Refusal | Why |
|---|---|
| `409 user_exists` | An email is already taken (nothing was made). |
| `409 test_user_cap_exceeded` | The batch would take the project past its test-user cap. |
| `400 invalid_request` | Neither a positive `count` nor complete `users`; a phone without its six-digit code. |

Send an `Idempotency-Key` header to make the creation safe to retry: the same key and the same request answer the first result again instead of creating twice. A fixture made with chosen emails is easy to make *if missing* — treat `409 user_exists` as "already there".

`PUT /admin/test-users/phone` (`adminSetTestUserPhone`) gives an existing test user, found by email, a verified phone and its fixed code; setting the same again succeeds, and an email that is not a test user's is `404 test_user_not_found`.

## In a route

A test user's token says `test: true`, and `palbase/backend` hands it to the route as `user.test`:

```ts
// src/modules/admin/reset.controller.ts
import { Controller, Forbidden, Post, User, type UserT } from "palbase/backend";

@Controller("/admin")
export class ResetController {
  // A route only the suite may call: every other user is turned away.
  @Post("/reset-demo")
  reset(@User() user: UserT): { reset: true } {
    if (!user.test) throw new Forbidden("this route serves test users only");
    return { reset: true };
  }
}
```

The flag is the platform's, set when the user was made with the secret key: a user who signs up cannot give it to themselves.

## Calling your backend as one

With `with_tokens`, each user's `access_token` goes on a call to your machine as `Authorization: Bearer …`, exactly as a signed-in app's does:

```ts
// scripts/call-as-test-user.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });
const [user] = (await palbase.auth.adminCreateTestUsers({ body: { count: 1, with_tokens: true } })).data.users;

const res = await fetch("https://<ref>.app.palbase.studio/notes", {
  headers: { authorization: `Bearer ${user.access_token}` },
});
console.log(res.status, await res.json());

await palbase.auth.adminDeleteTestUser({ path: { uid: user.user_id } });
```

They sign in like anyone else, too — with `palbase/web`'s `pb.auth.signIn(email, password)`, or by phone with their fixed code.

## Listing and removing them

| Call | What it does |
|---|---|
| `adminListTestUsers()` | Every test user of the project, newest first, whole: their number is capped, so the list is one answer. Each carries `is_test: true`. |
| `adminDeleteTestUser({ path: { uid } })` | Deletes a test user and everything that belongs to it. A user who is not a test user is refused, `403 not_a_test_user`. |

Deleting a test user is a user deletion like any other: it emits `user.deleted` (with `is_test: true`), so your backend forgets them as it forgets anyone ([Event Hooks](/docs/backend/hooks)), and storage objects owned by them go with them.

## Made for a test run

A test run makes the users its tests act as, and deletes them when it ends: `palbase test --users alice,bob` on your computer, a machine's `test_users` on the platform before each new build takes traffic. Each is a test user like these, at an address of the run's own, with its access token; a test acts as one with `api.signInAs("alice")` ([Testing](/docs/backend/testing#over-http-api-as-test-users)).

## From Studio

Studio's **Test accounts** tab under Authentication makes test logins, lists them, and searches them, for the environment you are in.

## Related

- [Authentication](/docs/backend/authentication) — `@User()`, `user.test`, and how a token is checked
- [Testing](/docs/backend/testing) — testing a backend, with and without a network
- [Server SDK Overview](/docs/server/overview) — `createServer`, refusals and `Idempotency-Key`
- [Web Auth](/docs/web/auth) — signing in as one from an app



<!-- ===== backend/testing ===== -->

# Testing

A backend is tested where it runs, and the same tests run in three places: on your computer (`bun test`), against your app as test users made for the run (`palbase test`), and on the platform against **each new build before it takes traffic**. `palbase/backend/test` is the kit they are written with:

| Name | What it is for |
|---|---|
| `isolated()` | a service built with the dependencies the test chooses, nothing else |
| `withServices()` | the services the code reads (`Database`, `Cache`, `Storage`, …) given by the test |
| `fakeDatabase()` | a database in memory, for `withServices({ Database })` |
| `api`, `testRun` | the app over HTTP, as the run's test users (`api.signInAs("alice")`) |
| `createTestApi`, `TestApiError` | a client of your own; what a refusal throws |

The HTTP half is `palbase/server/testing` — the same names, for a backend written with any framework (NestJS, Express, …). The tests run with **Bun's test runner** (`bun:test`), as the platform runs them: Bun keeps the decorator metadata `isolated()` reads a constructor's dependencies from. `palbase init` starts a backend with its tests in `tests/` and `"test": "bun test ./tests"`.

## Unit tests: `isolated()`

A service takes its dependencies by constructor. `isolated()` builds the class the test asks for, with what `.with()` gives in place of a dependency — however deep it is — and every other one built as the app builds it:

```ts
// src/modules/mail/mailer.ts
import { Injectable, Log } from "palbase/backend";

export abstract class Mailer {
  abstract send(to: string, subject: string): Promise<void>;
}

@Injectable()
export class LogMailer extends Mailer {
  async send(to: string, subject: string): Promise<void> {
    Log.info("mail", { to, subject });
  }
}
```

```ts
// src/modules/mail/welcome.service.ts
import { BadRequest, Injectable } from "palbase/backend";
import { Mailer } from "./mailer";

@Injectable()
export class WelcomeService {
  constructor(private readonly mailer: Mailer) {}

  async welcome(email: string): Promise<void> {
    if (!email.includes("@")) throw new BadRequest({ fields: [{ field: "email", message: "not an address" }] });
    await this.mailer.send(email, "Welcome");
  }
}
```

```ts
// tests/welcome.test.ts
import { describe, expect, it } from "bun:test";
import { BadRequest } from "palbase/backend";
import { isolated } from "palbase/backend/test";
import { Mailer } from "../src/modules/mail/mailer";
import { WelcomeService } from "../src/modules/mail/welcome.service";

class RecordingMailer extends Mailer {
  readonly sent: string[] = [];
  async send(to: string): Promise<void> {
    this.sent.push(to);
  }
}

describe("WelcomeService", () => {
  it("mails the address it is given", async () => {
    const mailer = new RecordingMailer();
    await isolated().with(Mailer, mailer).get(WelcomeService).welcome("ada@example.com");
    expect(mailer.sent).toEqual(["ada@example.com"]);
  });

  it("refuses what is not an address, naming the field", async () => {
    const welcome = isolated().with(Mailer, new RecordingMailer()).get(WelcomeService);
    await expect(welcome.welcome("ada")).rejects.toBeInstanceOf(BadRequest);
  });
});
```

Each `isolated()` is a container of its own: one instance of each class within it, nothing shared with another test or with the app. Two classes that need each other to be built are refused, naming the circle; `.with()` one of them and there is none.

## The services the code reads: `withServices()`

`Database`, [`Cache`](/docs/backend/cache), `Secrets`, `Storage`, `Notifications`, `Flags`, `Realtime` and `Log` are read where the code needs them, not passed in. `withServices(given, fn)` runs `fn` as a request does, with the services given: `Database` is the client given (`fakeDatabase().raw`), each other service the object given. A service the code reads and the test did not give is refused **by name** — its real calls would reach a platform no test serves — and `Log` writes as it always does.

```ts
// src/modules/notes/notes.service.ts
import { Cache, Database, Injectable } from "palbase/backend";

@Injectable()
export class NotesService {
  async count(owner: string): Promise<number> {
    const cached = await Cache.get<number>(`notes:${owner}`);
    if (cached !== null) return cached;
    const n = await Database.$count("notes", { owner });
    await Cache.set(`notes:${owner}`, n, 60);
    return n;
  }
}
```

```ts
// tests/notes.service.test.ts
import { describe, expect, it } from "bun:test";
import { fakeDatabase, isolated, withServices, type RuntimeServices } from "palbase/backend/test";
import { NotesService } from "../src/modules/notes/notes.service";

describe("NotesService", () => {
  it("counts a user's notes, and keeps the count for a minute", async () => {
    const db = fakeDatabase();
    db.seed("notes", [
      { id: "n1", owner: "ada", title: "one" },
      { id: "n2", owner: "ada", title: "two" },
      { id: "n3", owner: "bob", title: "three" },
    ]);
    const kept = new Map<string, unknown>();
    const cache = {
      get: async (key: string) => kept.get(key) ?? null,
      set: async (key: string, value: unknown) => void kept.set(key, value),
    } as unknown as RuntimeServices["Cache"];

    const n = await withServices({ Database: db.raw, Cache: cache }, () => isolated().get(NotesService).count("ada"));
    expect(n).toBe(2);
    expect(kept.get("notes:ada")).toBe(2);
  });
});
```

`withServices` also carries a string table for `t()` ([Translations](/docs/backend/translations)): `withServices(given, fn, { strings, acceptLanguage: "en" })`, with `loadStringsTable(root)` reading the project's `palbase/strings`.

### A database in memory: `fakeDatabase()`

`fakeDatabase()` answers the engine's operations with the engine's filters and refusals: `seed(table, rows)` puts rows in, `inserted`, `updated` and `deleted` say what the code wrote, and raw SQL is recorded in `queries`, not run. What it cannot answer as Postgres would — a unique key, a relation, a cursor, search, an `$atomic`'s isolation — it refuses by name. It has no schema (no column's default, type or constraint is applied), it reads text of digits as the number it spells, it gives rows in the order they were written unless `orderBy` says otherwise, and there is no row-level security. What depends on those is tested against the app over HTTP, or against a Postgres of your own (below).

## Over HTTP: `api`, as test users

`api` calls the app under test where the run says it answers (`PALBASE_TEST_BASE_URL`), as the test users the run made for it (`PALBASE_TEST_IDENTITIES`, each with its access token). `testRun.stack` says whether an app answers: an HTTP test skips itself where none does, so `bun test` passes on a computer with no app started.

```ts
// tests/notes.http.test.ts
import { describe, expect, it } from "bun:test";
import { api, TestApiError, testRun } from "palbase/backend/test";

describe.skipIf(!testRun.stack)("notes, over HTTP", () => {
  it("are each user's own", async () => {
    const title = `a test run's note ${crypto.randomUUID()}`;
    await api.signInAs("alice");
    const note = await api.post<{ id: string }>("/notes", { title });
    expect((await api.get<{ title: string }>(`/notes/${note.id}`)).title).toBe(title);

    await api.signInAs("bob");
    const refused = await api.get(`/notes/${note.id}`).catch((e: unknown) => e);
    expect(refused).toBeInstanceOf(TestApiError);
    expect((refused as TestApiError).status).toBe(404);
  });

  it("refuses a caller with no token", async () => {
    api.asAnonymous();
    const refused = await api.post("/notes", { title: "x" }).catch((e: unknown) => e);
    expect((refused as TestApiError).status).toBe(401);
  });
});
```

- `api.signInAs(name)` acts as the run's test user of that name; `api.asAnonymous()` as no one. `api.signIn({ email, password })` signs in at the project's auth (it needs a publishable key: `PALBASE_TEST_API_KEY`).
- A refusal throws `TestApiError`: its `status`, its code (`error`), its `data` and the whole `body`, the platform's envelope.
- `testRun.minted("alice")` says whether the run made that user. `createTestApi({ baseUrl, identities, … })` is a client of your own, for a test that calls two apps.

## Running them

| Where | How | What runs |
|---|---|---|
| Your computer | `bun test` | the unit tests; the HTTP tests skip themselves |
| Your computer, against your app | `palbase test --users alice,bob --base-url http://localhost:8080 -- bun test ./tests` | all of them, as test users made for this run in the environment you use, deleted when the command ends — Ctrl-C too |
| As a machine runs them | `palbase test --machine backend --base-url http://localhost:8080` | the machine's own test command, as its test users (it shows the command and asks before running it; `-y` says yes) |
| The platform | `palbase machines:update backend --test-command "bun test ./tests" --test-users alice,bob` | every new build, against the new version itself, before it takes traffic |

On the platform the tests run against the new version **as it will run** — its env, its secrets, its database, after its migration has started: they pass and it takes traffic; one fails and the build fails, naming the test, while the machine keeps serving the version it runs (see [Builds](/docs/machines/builds#tests-before-it-takes-traffic)). The tests write where the app writes, so write them as a real user's session: a note of their own, not a table they expect empty. What a test user owns goes with them — the run deletes its users, and a deleted user's rows are erased (`ownedByUser()`, on `user.deleted`).

The image has to carry the tests: `palbase init`'s `Dockerfile` copies `tests/`, and Bun's types are a dev dependency the image does not install.

## Without the network

The kit tests the app as it is deployed. The app can also be tested inside the test's own process — its routes, auth, validation and refusals answering a `Request` through `handle()`, no port opened.

### The app in the process: `handle()`

`PalbaseFactory.create` answers a `Request` through the app's `handle()`, the same path a request from the network takes. A test builds the app with its own environment, on a free port, without exiting on a crash:

```ts
// src/modules/notes/notes.controller.ts
import { Body, Controller, Get, Post, User, z, type UserT } from "palbase/backend";

export const CreateNote = z.object({ title: z.string().min(1).max(200) });
export type CreateNote = z.infer<typeof CreateNote>;

@Controller("/notes")
export class NotesController {
  @Post("")
  create(@Body(CreateNote) body: CreateNote, @User() user: UserT): { owner: string; title: string } {
    return { owner: user.id, title: body.title };
  }

  @Get("/health", { auth: false })
  health(): { ok: true } {
    return { ok: true };
  }
}
```

```ts
// src/modules/notes/notes.module.ts
import { Module } from "palbase/backend";
import { NotesController } from "./notes.controller";

@Module({ controllers: [NotesController] })
export class NotesModule {}
```

```ts
// tests/notes.handle.test.ts
import { afterAll, beforeAll, describe, expect, it } from "bun:test";
import { PalbaseFactory, type PalbaseApplication } from "palbase/backend";
import { NotesModule } from "../src/modules/notes/notes.module";

const env = {
  PALBASE_URL: "https://abcd1234.palbase.studio",
  PALBASE_PROJECT_ID: "11111111-2222-3333-4444-555555555555",
  PALBASE_SECRET_KEY: "pb_abcd1234_s0123456789abcdef0123456789abcdef",
};

let app: PalbaseApplication;
beforeAll(async () => {
  app = await PalbaseFactory.create(NotesModule, { env, port: 0, host: "127.0.0.1", exitOnFatal: false });
});
afterAll(() => app.close());

const call = (path: string, init?: RequestInit) => app.handle(new Request(`http://app.test${path}`, init));

describe("notes over HTTP", () => {
  it("serves a public route", async () => {
    const res = await call("/notes/health");
    expect(res.status).toBe(200);
    expect(await res.json()).toEqual({ ok: true });
  });

  it("refuses a caller with no token, in the envelope", async () => {
    const res = await call("/notes", { method: "POST", body: JSON.stringify({ title: "x" }) });
    expect(res.status).toBe(401);
    expect(await res.json()).toMatchObject({ error: "unauthorized", status: 401 });
  });

  it("lists the routes it serves", () => {
    expect(app.routes).toEqual(["POST /notes", "GET /notes/health"]);
  });
});
```

- `env` stands in for what the platform and the project's Secrets give a machine. Nothing is called with these values until a route needs the project: a route with no token never asks for the project's keys.
- `port: 0` takes a free port, so tests can run side by side. `exitOnFatal: false` leaves a crash to the test runner instead of exiting the process.
- `app.close()` stops it and runs every `onShutdown()`.

### Signed-in requests, without the network

A signed-in route needs a token the app verifies against a key set. In a test the key set is the test's own: `createApp` (the engine `PalbaseFactory` serves) takes a `TokenVerifier` you build, and `createServer` takes a `fetch` that answers the project's module calls however the test says. A helper that makes all three:

```ts
// tests/project.ts
import { createServer } from "palbase/server";
import { TokenVerifier } from "palbase/backend";

export const url = "https://abcd1234.palbase.studio";
export const projectId = "11111111-2222-3333-4444-555555555555";

const b64 = (bytes: Uint8Array | string): string =>
  Buffer.from(typeof bytes === "string" ? new TextEncoder().encode(bytes) : bytes).toString("base64url");

/** A signing key of the test's own, the key set that publishes it, and tokens it signs. */
export async function testProject(answer: (url: URL, init: RequestInit) => Response = () => Response.json({})) {
  const pair = (await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"])) as CryptoKeyPair;
  const jwk = { ...(await crypto.subtle.exportKey("jwk", pair.publicKey)), kid: "test", alg: "ES256", use: "sig" };

  const verifier = new TokenVerifier({
    issuer: url,
    projectId,
    fetch: async () => Response.json({ keys: [jwk] }),
    // Every session stands; a test of sign-out answers false for its session.
    standing: async () => true,
  });

  async function token(userId: string, claims: Record<string, unknown> = {}): Promise<string> {
    const now = Math.floor(Date.now() / 1000);
    const body = {
      iss: url, aud: [url], sub: userId, exp: now + 900, iat: now, auth_time: now,
      email: `${userId}@example.com`, email_verified: true, role: "authenticated",
      session_id: `ses_${userId}`, project_id: projectId, ...claims,
    };
    const head = b64(JSON.stringify({ alg: "ES256", kid: "test", typ: "JWT" }));
    const payload = b64(JSON.stringify(body));
    const signature = await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, pair.privateKey, new TextEncoder().encode(`${head}.${payload}`));
    return `${head}.${payload}.${b64(new Uint8Array(signature))}`;
  }

  // `Palbase.*` inside the app: each call answered by `answer`, sent once.
  const server = createServer({
    url,
    secretKey: "pb_abcd1234_s0123456789abcdef0123456789abcdef",
    fetch: async (input, init) => answer(new URL(String(input)), init ?? {}),
    retry: { attempts: 1, maxWaitSeconds: 0 },
  });

  return { verifier, token, server };
}
```

```ts
// tests/notes.signed-in.test.ts
import { describe, expect, it } from "bun:test";
import { createApp } from "palbase/backend";
import { testProject } from "./project";
import { NotesModule } from "../src/modules/notes/notes.module";

describe("notes for a signed-in user", () => {
  it("takes the user from the token", async () => {
    const project = await testProject();
    const app = createApp({ modules: [NotesModule], verifier: project.verifier, server: project.server });
    await app.start();

    const res = await app.handle(
      new Request("http://app.test/notes", {
        method: "POST",
        headers: { authorization: `Bearer ${await project.token("usr_ada")}` },
        body: JSON.stringify({ title: "Ship it" }),
      }),
    );
    expect(res.status).toBe(200);
    expect(await res.json()).toEqual({ owner: "usr_ada", title: "Ship it" });

    // A refusal the schema makes, with the field it names.
    const bad = await app.handle(
      new Request("http://app.test/notes", {
        method: "POST",
        headers: { authorization: `Bearer ${await project.token("usr_ada")}` },
        body: JSON.stringify({ title: "" }),
      }),
    );
    expect(bad.status).toBe(400);
    expect(await bad.json()).toMatchObject({ error: "bad_request", data: { fields: [{ field: "title" }] } });
    await app.stop();
  });
});
```

`createApp` takes the same settings the bootstrap does (`auth`, `rateLimit`, `maxBodyBytes`, `cors`, `webhookSecret`) and builds the container at once, so a wiring mistake throws right there. `start()` runs every `onStart()`, and `stop()` runs every `onShutdown()`. It opens no port. To test an [`@On` handler](/docs/backend/hooks), give it a `webhookSecret` and hand it a signed delivery.

> **Note:** Classes are recorded process-wide when their files are imported. Build each test file's app from modules that own every `@Controller`, `@Injectable()` and `@On` class that file's imports bring in, or the build stops with `unowned class`.

### Against a Postgres of your own

`Database` is the request's transaction against a real Postgres, so a test that reaches it needs one: Postgres 18, with the roles the platform's databases have, and the app's schema migrated into it. The roles, made once:

```sql
CREATE ROLE anon NOLOGIN;
CREATE ROLE authenticated NOLOGIN;
CREATE ROLE service_role NOLOGIN BYPASSRLS;
CREATE ROLE app_owner LOGIN CREATEDB;
CREATE ROLE app_login LOGIN NOINHERIT;
GRANT anon, authenticated, service_role TO app_login;
```

Migrate it with the app itself, as a release does: run it once with `PALBASE_DB_MIGRATE=start` and once with `PALBASE_DB_MIGRATE=complete`, each with `PALBASE_DB_OWNER_URL` naming the owner. Then build the app with `db: { schemas }` and `PALBASE_DB_URL` naming `app_login`. A migration run exits the process, so run it before the tests, not inside them. The default database driver is Bun's SQL: tests that run on Node give the app a driver of their own. See [Database](/docs/backend/database) and [Schema changes](/docs/backend/migrations).

## Related

- [Builds](/docs/machines/builds#tests-before-it-takes-traffic): tests before a version takes traffic
- [Modules & Dependency Injection](/docs/backend/modules): the constructor seam
- [Event Hooks](/docs/backend/hooks): signing a delivery in a test
- [Test Users](/docs/backend/test-users): users made for tests
- [Responses & Errors](/docs/backend/errors): what a refusal looks like



<!-- ===== web/overview ===== -->

# Overview

`palbase/web` is the Palbase client for web and JavaScript apps. One function, `createClient`, makes the client for one project, and the client holds every module an app uses: `auth` signs a person in and keeps them signed in, `flags` holds the flags' values for them, `analytics` records what they do, `consent` keeps what they allowed, `notify` takes the project's pushes, inbox and in-app messages, `purchases` holds what they bought, and `socket` is the project's one realtime connection. Your own backend's routes and gateways join it as `pb.<backend>` once `palbase apps:sync` has written the app its module. Every call goes through the client's one transport, which carries the publishable key, the signed-in user's access token, refreshes and retries.

The client is built with the **publishable** key, the one that ships in an app. It refuses a secret key outright, and the secret key belongs in [`palbase/server`](/docs/server/overview).

## Quick example

```ts
// src/lib/palbase.ts
import { createClient } from "palbase/web";

// The project's address. The browser calls it directly, from a page on any site.
export const pb = createClient({
  url: "https://k3xq81w4m.palbase.studio",
  // The environment's publishable key, from Studio's Settings › API keys.
  publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5",
});
```

```ts
// src/main.ts
import { pb } from "./lib/palbase";

const result = await pb.auth.signIn("ada@example.com", "correct-horse-battery-staple");
if (result.mfaRequired) {
  console.log("a second factor is needed:", result.mfaRequired.factors);
} else {
  console.log("signed in as", result.user.id);
}

pb.auth.onAuthStateChange((event, session) => {
  console.log(event, session?.userId ?? "nobody");
});

// The flags' values for whoever is signed in now, kept current as they change.
if (pb.flags.bool("new_checkout", false)) console.log("the new checkout is on");
```

`signIn` puts the session in the client's store, and from then on every call that acts for the user carries the user's access token. The client refreshes that token before it lapses, once, however many calls ask at the same moment and however many tabs share the session.

## Install

The web SDK is `palbase/web`, a part of the npm package `palbase`: `npm install palbase` (or `bun add palbase`).

```json
{
  "dependencies": {
    "palbase": "^0.10.0"
  }
}
```

A caret on a `0.x` version stays within that minor version: `^0.10.0` takes `0.10.1`, never `0.11.0`.

It is compiled JavaScript with its type declarations: any bundler takes it as it is (Next.js, Vite, esbuild — no setting). A browser or React Native bundle that imports `palbase/server`, `palbase/ai` or `palbase/backend` gets a module that throws: those parts hold the project's secret key or run a server, and never go into an app.

The package's web entry points:

| Import | What it is |
|---|---|
| `palbase/web` | `createClient` and everything it returns. |
| `palbase/web/ssr` | The session in cookies, for an app whose server renders its pages: `createServerClient`, `createBrowserClient`, `keepSession`. See [Next.js](/docs/web/nextjs). |
| `palbase/web/vite` | The Vite plugin: builds each mode against the environment you name for it, from what `palbase apps:sync` wrote, and type-checks the app against that environment's backend first. See [Calling Your Backend](/docs/web/backend-calls#building-for-an-environment). |
| `palbase/web/palbe` | What the module `palbase apps:sync` writes registers your backend with. Your own code does not import it. |
| `palbase/web/push-sw.js` | The service worker that shows the project's pushes. See [Notifications](/docs/web/notifications#the-service-worker). |
| `palbase/web/paywall` | A paywall's definition resolved and drawn in the page (`renderPaywall`), and its prices formatted: what `pb.purchases.paywall(placement)` draws with (its `render(container, options)`), for an app that draws one itself. |
| `palbase/web/message` | An in-app message's definition resolved and drawn: over the page (`presentMessage`) or as an inbox card (`renderMessage`). What `pb.notify` draws with, for an app that draws one itself. |

## `createClient(options)`

| Option | Type | What it is |
|---|---|---|
| `url` | `string` | The project's address, `https://<ref>.palbase.studio`: where the client sends its calls and opens its socket. It is an origin alone: `https`, or `http` for a loopback address, no path, query or fragment. |
| `publishableKey` | `string` | The project's publishable key, `pb_<ref>_c…`. A secret key (`pb_<ref>_s…`) throws `TypeError` before anything is sent, and so does anything that is not a publishable key. |
| `storage` | `SessionStore` | Where the session is kept. Default: `localStorage` under `palbase.session.<origin>` in a browser, memory anywhere else. |
| `refresh` | `"behind" \| "before" \| "never"` | When the access token is renewed. `behind` (the default): in the background while it still works, so no call waits. `before`: in front of the call that finds it about to lapse. `never`: not at all. `palbase/web/ssr` sets it for a server. |
| `fetch` | `typeof fetch` | The `fetch` the transport calls. Default: the global one. |
| `webSocket` | `typeof WebSocket` | The WebSocket constructor the socket uses. Default: the global one. |
| `xmlHttpRequest` | `typeof XMLHttpRequest` | What an upload that reports its progress is sent with, since `fetch` tells nothing of a body as it goes. Default: the page's own, unless you gave a `fetch`. |
| `webauthn` | `CredentialsLike` | What passkeys call. Default: `navigator.credentials`. |
| `retry` | `RetryPolicy` | `{ attempts, maxWaitSeconds }`. Default: 3 attempts, and a `Retry-After` longer than 30 s is not waited for. See [Error Handling](/docs/web/errors). |
| `analytics` | `boolean \| AnalyticsOptions` | Starts the browser's own measures: a page view per address (`pageViews`), web vitals (`webVitals`) and each `fetch` the page makes (`network`), all on once started; `appVersion` is kept with every event. Left out, none of them starts, and `pb.analytics.capture` still sends what you capture. See [Analytics](/docs/web/analytics). |
| `consent` | `ConsentOptions` | What is collected before the person chooses (`start`), the version of the consent text the app shows (`textVersion`), and the app's own keys (`customKeys`). See [Consent](/docs/web/consent). |
| `appVersion` | `string` | The app's version as its users see it (`"2.4.1"`), sent with flag reads and paywall requests for the conditions that read it. Nothing is sent without one. |
| `appId` | `string` | The registered app's id, a UUID, as `palbase apps:sync` writes it into the app's settings: sent with paywall requests for placement rules that name an app. A slug throws `TypeError`. |
| `language` | `string \| string[]` | The language the app shows itself in (`"tr"`, `["pt-BR", "pt"]`), sent with every request as `Accept-Language`: what auth's emails, a flag's conditions, a paywall's rules and your backend's translations read. Default: the browser's own. |

What comes back:

| Member | What it is |
|---|---|
| `pb.auth` | Sign-up, sign-in, the session, second factors, passkeys, magic links, phone codes, password and email flows. Every client operation of the auth contract is also there, typed, as `pb.auth.api`. See [Auth](/docs/web/auth). |
| `pb.flags` | The project's flags and remote configuration, resolved for this app and whoever is signed in, kept current as they change. See [Flags](/docs/web/flags). |
| `pb.analytics` | Events the app captures, page views, the person's properties, and the browser's own measures once started. See [Analytics](/docs/web/analytics). |
| `pb.consent` | What the person allowed, key by key: their choices, kept in the browser and sent to the project. See [Consent](/docs/web/consent). |
| `pb.notify` | This browser's pushes (`push`), the signed-in person's inbox (`inbox`) and the project's in-app campaigns (`inApp`). See [Notifications](/docs/web/notifications). |
| `pb.purchases` | What the signed-in customer has, kept current; the catalog's offerings and paywalls; buying on the web with Stripe Checkout. See [Purchases on the web](/docs/purchases/web). |
| `pb.installation` | This browser's install of the app: `pb.installation.id`, the same until the site's storage is cleared. Analytics, flags, consent and pushes say it with what they send. |
| `pb.socket` | The project's realtime socket. It is opened the first time a channel is joined, never before. See [Realtime](/docs/web/realtime). |
| `pb.transport` | The transport every call above goes through. See [Calls the client has no method for](#calls-the-client-has-no-method-for). |
| `pb.setLanguage(language)` | Changes the language every request says from now on; `null` goes back to the browser's. |
| `pb.chatToolCall(chatId, callId)`, `pb.chatWorkspaceFile(chatId, path)` | A chat's whole tool answer, and a file of its workspace, read with the member's own session. See [Gateways](/docs/web/gateways#chat-gateways). |
| `pb.<backend>` | Your backend's routes and gateways, typed: `pb.backend.notes.create({ title })`, from the module `palbase apps:sync` writes the app. See [Calling Your Backend](/docs/web/backend-calls) and [Gateways](/docs/web/gateways). |

A client is one project. Make it once and import it where you need it: each client keeps its own socket and its own copy of the session. An app whose checkout runs `palbase apps:sync` has its client made for it: it imports `pb` from `palbase/<app>`, made with its environment's address and key, and gives it the options above with `connect(options)` ([Calling Your Backend](/docs/web/backend-calls#the-generated-module)).

## Calling the project from a browser

A page on any site calls the project's address directly, as a page calls Supabase or Firebase. Give `createClient` the project's address as `url`, and the client's calls and its socket go there from the browser.

What the address answers a browser:

- **A preflight** (`OPTIONS` with `Access-Control-Request-Method`) is answered `204` and needs no key. It allows `GET`, `HEAD`, `POST`, `PUT`, `PATCH` and `DELETE`, and the headers the browser asks for: `apikey`, `authorization`, `content-type`, `idempotency-key` and any other. The browser may keep the answer for a day (`Access-Control-Max-Age: 86400`).
- **Every answer** carries `Access-Control-Allow-Origin: *`: the module's own, and the platform's refusals too (`401`, `403`, `429`, `404 no_route`), so your code reads an error's status and body. These response headers are exposed to your code: `retry-after`, `x-request-id`, `etag`, `idempotent-replayed`, `www-authenticate`, `location`, `link`, `content-range`, `content-disposition`, `dpop-nonce`, `x-thumbhash`, `x-message-id`, `x-ratelimit-remaining` and `x-ratelimit-reset`.
- **No cookie** is read. A call carries the publishable key in the `apikey` header and the user's access token as `Authorization: Bearer …`. Leave `fetch`'s `credentials` at its default: a browser refuses `credentials: "include"` against an answer that allows any origin. A session kept in cookies (`palbase/web/ssr`) is still sent this way: the cookie is where the session is kept, for your own server to read, not how a call proves it.

**Call the project from the browser, not through your server.** The address the project counts is the caller's. Auth's limits are per address: so many sign-in attempts from one address in a few minutes, and a burst of failed sign-ins from one address blocks it for a while. Auth's proof-of-work is asked of an address that looks like a bot. Analytics and flags read the country from the address. A server that passes every user's calls on to the project makes all of its users one address: one person's failed sign-ins then lock everyone out, and every event is given the server's country.

Your own backend is different. A machine answers at its own address (`https://<name>-<ref>.app.palbase.studio`, or `https://<ref>.app.palbase.studio` for the machine named `backend`), and the platform adds no CORS there: a `palbase/backend` app answers browsers itself, for the origins it names in `PalbaseFactory.create(AppModule, { cors: { origins: ["https://app.example.com"] } })`. See [Calling Your Backend](/docs/web/backend-calls#cross-origin-calls).

## Calls the client has no method for

The client has a method for what an app does most. A few calls a browser may make have none: the signed-in user's notification preferences (`GET`/`PUT /notify/preferences`) and the topics they follow (`POST`/`DELETE /notify/topics/{name}/subscription`). Make them through `pb.transport`, the client's own transport: it sends the publishable key and the user's current access token, refreshes a token refused before its time and sends the call again, waits out a "not now" on a read, and throws a `PalbaseError` for a refusal, as the client's own calls do.

```ts
// src/settings.ts
import { pb } from "./lib/palbase";

type Preferences = Record<string, Record<string, boolean>>;

// Which categories the signed-in user takes on which channel.
const reply = await pb.transport.send({
  op: "notify.getMyPreferences",
  method: "GET",
  path: "/notify/preferences",
  // The publishable key with the user's access token.
  auth: [["ApiKeyAuth", "userJWT"]],
  // The answers the call has; any other is thrown as a PalbaseError.
  answers: { 200: "json" },
});
const prefs = reply.data as Preferences;
console.log(prefs.email);
```

[Notifications](/docs/web/notifications#preferences-and-topics) shows both calls in full. Storage has no other client door: listing, writing and deleting objects is the secret key's, and so is everything that changes a module's settings. Those calls are made from a server, with [`palbase/server`](/docs/server/overview) or from your machine as `Palbase.<module>`. A browser uploads through your backend: to its upload route, or to a URL it signed. See [Uploads](/docs/web/uploads).

## Sessions and storage

The session is `{ accessToken, refreshToken, expiresAt, userId, user? }`, kept by a `SessionStore`:

- **`localStore(key)`** is the browser default, under `palbase.session.<origin of url>`. Tabs share it: a refresh takes a lock across them (`navigator.locks`), a tab that finds the session already refreshed by another takes that one instead of spending a used refresh token, and a sign-out in one tab signs the user out of every tab. Storage that cannot be written (full, blocked, a private window) keeps the session in this page's memory rather than losing it.
- **`memoryStore()`** is the default anywhere without `localStorage`: one process, one session.
- **Cookies**, for an app whose server renders its pages and needs to know who is signed in: `createBrowserClient` and `createServerClient` from `palbase/web/ssr` keep the session in a cookie the page and the server both read. See [Next.js](/docs/web/nextjs).
- Your own store implements `load`, `save` and `clear`, and, if tabs share it, `shared: true` and `watch(onChange)`.

The default key is built from the `url` you give, so each project's session is kept apart from another's in the same browser. An app that gave `createClient` its own origin as `url` finds its users' sessions under that origin's key. To keep them signed in when it moves to the project's address, give that key: `storage: localStore("palbase.session.https://app.example.com")`.

A session belongs to one user. When a tab finds another user's session in the shared store, it says `SIGNED_OUT` and then `SIGNED_IN` and never carries one user's work into the other's account. The socket closes on every sign-in and sign-out for the same reason, and the client's flags, consent choices and push registration follow the new user by themselves. See [Auth](/docs/web/auth#listening-for-changes).

## Outside the browser

`createClient` runs anywhere `fetch` does: a Node or Bun script, a test, a React Native app. With no `localStorage` the session lives in memory, and nothing keeps it between runs unless you give a `storage`. A script gives the project's address as `url`, as a page does.

A server is a different job. It acts for the project, not for one signed-in person, and it holds the secret key. That is [`palbase/server`](/docs/server/overview), and `createClient` will not take its key. A server that renders one signed-in person's pages uses `createServerClient` from `palbase/web/ssr`, with the publishable key and the request's cookies: see [Next.js](/docs/web/nextjs#on-the-server).

## Related

- [Auth](/docs/web/auth) — every sign-in flow, the session, passkeys and second factors
- [Calling Your Backend](/docs/web/backend-calls) — your machine's routes, typed, with the user's access token
- [Flags](/docs/web/flags) — the flags' values for this reader, kept current
- [Analytics](/docs/web/analytics) and [Consent](/docs/web/consent) — events, and what the person allowed
- [Notifications](/docs/web/notifications) — web push, the inbox and in-app messages
- [Error Handling](/docs/web/errors) — `PalbaseError`, retries and proof-of-work
- [Realtime](/docs/web/realtime) — channels over the project's socket
- [Gateways](/docs/web/gateways) — your backend's realtime channels, and a chat's state
- [Next.js](/docs/web/nextjs) — the session in cookies, client components and server code
- [Server SDK](/docs/server/overview) — the secret key's client



<!-- ===== web/auth ===== -->

# Auth

`pb.auth` signs a person in and keeps them signed in. Every flow that ends in tokens puts them in the client's session and tells your app, and every call that acts for the user carries the access token from then on. The flows an app writes most are methods here: email and password, second factors, passkeys, magic links, phone codes, password and email changes, the user's sessions. Every other client operation of the auth module is reachable typed as `pb.auth.api`.

## Quick example

```ts
// src/lib/palbase.ts
import { createClient } from "palbase/web";

export const pb = createClient({ url: "https://k3xq81w4m.palbase.studio", publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5" });
```

```ts
// src/signin.ts
import { pb } from "./lib/palbase";

// Create the account. When the project signs new users in at once, the session starts too.
const created = await pb.auth.signUp({ email: "ada@example.com", password: "correct-horse-battery-staple" });
console.log("account", created.user.id, created.access_token ? "signed in" : "confirm your email first");

// Sign in. A second factor, when the account has one, comes back as mfaRequired.
const result = await pb.auth.signIn("ada@example.com", "correct-horse-battery-staple");
if (result.mfaRequired) {
  const code = window.prompt("The code from your authenticator app") ?? "";
  await pb.auth.mfa.challenge(result.mfaRequired.mfaToken, "totp", code);
}

const me = await pb.auth.getUser();
console.log(me.id, me.email_verified, me.has_mfa);
```

The client is built with the project's address as `url`: the browser calls auth there directly, so auth's limits count each user's own address. See [Overview](/docs/web/overview#calling-the-project-from-a-browser).

## The session

```ts
// src/session.ts
import { pb } from "./lib/palbase";

const session = await pb.auth.currentSession();
if (session) {
  console.log(session.userId, new Date(session.expiresAt));
}
```

| Member | What it does |
|---|---|
| `currentSession()` | The session, `{ accessToken, refreshToken, expiresAt, userId, user? }`, or `null` when no one is signed in. It waits for the store to load, so call it at boot. |
| `getUser()` | Reads the signed-in user's profile fresh (`GET /auth/me`): id, email, whether it is verified, whether they have a password and a second factor, their linked providers and language. |
| `refreshSession()` | Refreshes now, rather than when the token is about to lapse. |
| `setSession({ access_token, refresh_token, expires_in })` | Starts the session from a token pair your app has from a flow of its own (the social sign-in below, a ceremony you run step by step). The session held before is gone. |
| `onAuthStateChange(listener)` | Tells you every change. Returns the unsubscribe. |

The access token is refreshed a minute before it lapses, in the background while it still works, so no call waits for a refresh until the token is dead. A call refused with a 401 that is about the token (`invalid_token`, `token_expired`, `session_expired`, `session_revoked`, `missing_token`) is refreshed once and sent again, and only for the user whose session sent it. Every other 401, such as a wrong password or a wrong code, is the caller's answer and is never sent again. A refresh the server refuses ends the session (`SESSION_EXPIRED`).

## Email and password

`signUp(body)` creates the account (`POST /auth/signup`). The body is `{ email, password, locale?, redirect_to? }`. `redirect_to` is where the verification link lands, and it must be on the project's redirect allow-list (see [Where email links land](#where-email-links-land)). What comes back is `{ user, access_token?, refresh_token?, expires_in? }`: the tokens are there, and the session starts, only when the project lets a new account sign in before it confirms its address. With email confirmation required, the user confirms first and then signs in.

`signIn(email, password)` (`POST /auth/login`) answers one of two shapes:

```ts
// src/login.ts
import { pb } from "./lib/palbase";

export async function login(email: string, password: string): Promise<string> {
  const result = await pb.auth.signIn(email, password);
  if (result.mfaRequired) {
    // { mfaToken, factors }: finish with pb.auth.mfa.challenge(...) or .recovery(...)
    return `second factor: one of ${result.mfaRequired.factors.join(", ")}`;
  }
  return `signed in as ${result.user.id}`;
}
```

The password rules (the shortest length, whether an email must be confirmed first) are the project's auth settings: Studio's Auth screens, or `PUT /admin/auth-settings` with the secret key from a server. A password the policy refuses, or one known from a breach, is a `PalbaseError` with status 400 and a code that says which.

### Confirming an email

The confirmation email carries a link, or a code when the project uses codes:

```ts
// src/verify.ts
import { pb } from "./lib/palbase";

const token = new URLSearchParams(window.location.search).get("token");
if (token) {
  await pb.auth.email.verify({ token }); // the link's token
} else {
  await pb.auth.email.verify({ email: "ada@example.com", code: "482913" }); // or the code with the address
}

// The email did not arrive:
await pb.auth.email.resendVerification("ada@example.com");
```

## Where email links land

A link in an auth email (confirm the address, choose a new password, a magic link) is built from the project's auth settings, in this order:

1. the request's `redirect_to`, with `?token=` added, when it is on the allow-list: the auth settings' `redirect_urls`, together with the redirects of the project's web apps (`palbase apps:env:set <app> --redirect <url>`). Any other `redirect_to` is refused with `invalid_redirect`;
2. the project's site URL (`site_url`) with the action's page: `https://app.example.com/auth/verify-email?token=…`, `https://app.example.com/auth/reset-password?token=…`, `https://app.example.com/auth/magic-link?token=…`;
3. with neither, the page auth serves itself at the project's address, for confirming an email and choosing a password. A magic link has no such page, because it ends in a session that only your app can take: a project that sends magic links needs a site URL.

Those three pages are yours to build at your site. Each reads `token` from its query and calls the method below.

## Second factors

A sign-in that needs a second factor answers `mfaRequired: { mfaToken, factors }`. Finish it with one of these:

| Method | What it does |
|---|---|
| `mfa.challenge(mfaToken, "totp" \| "sms" \| "email", code)` | Completes the sign-in with a code. Returns the user. |
| `mfa.recovery(mfaToken, code)` | Completes it with a recovery code instead. |
| `mfa.sendSmsCode(mfaToken)` / `mfa.sendEmailCode(mfaToken)` | Sends the sign-in code; then `challenge(mfaToken, "sms" \| "email", code)`. |

Enrolling, for the signed-in user:

```ts
// src/mfa.ts
import { pb } from "./lib/palbase";

// TOTP: the secret for the authenticator app, a QR code, and the recovery codes, shown once.
const totp = await pb.auth.mfa.enrollTotp();
console.log(totp.otpUrl, totp.recoveryCodes);
await pb.auth.mfa.verifyTotp("123456"); // the first code the app shows confirms it

const factors = await pb.auth.mfa.factors();
console.log(factors);

// Removing a factor asks for the account's password.
await pb.auth.mfa.removeFactor("fac_01", "correct-horse-battery-staple");
```

`enrollSms(phone)` and `verifySms(code)` enroll a phone, `enrollEmail()` the account's address, and `regenerateRecoveryCodes()` replaces the recovery codes.

### Stepping up

A backend route that asks for a second factor (`auth: { aal: "aal2" }`), or for a recent one (`maxAge`), refuses a password sign-in with `kind: "stepUpRequired"` (`data.acr_values`, `data.max_age`). Step the signed-in user up and call again:

```ts
// src/approve.ts
import { pb } from "./lib/palbase";

await pb.auth.mfa.stepUp("123456"); // the code the authenticator app shows
// or, with one of the user's passkeys: await pb.auth.passkey.stepUp();
// or by text: await pb.auth.mfa.sendStepUpSmsCode(); then
//   await pb.auth.mfa.stepUpWithSms(codeFromTheText);
// the route called again now gets the aal2 token
```

Each returns the session, which holds the token at the new level from here on; its refreshes stay at that level (`TOKEN_REFRESHED` is told). The step-up is the session's last authentication, so a route's `maxAge` counts from it. An email code is not a way up: it is not a second factor ([Second factors and their strength](/docs/backend/authentication#second-factors-and-their-strength)).

## Passkeys

```ts
// src/passkeys.ts
import { pb } from "./lib/palbase";

// Create an account with a passkey and no password, and sign in with it.
const user = await pb.auth.passkey.signUp("ada@example.com", "Ada");

// Add another passkey to the signed-in user.
await pb.auth.passkey.register("Work laptop");

// Sign in: any passkey of the site (discoverable), or one user's.
await pb.auth.signOut();
const again = await pb.auth.passkey.signIn();
console.log(user.id === again.id);

console.log(await pb.auth.passkey.list());
```

The ceremony runs through `navigator.credentials`, or the `webauthn` you give `createClient`. Outside a browser with neither, a passkey method throws once the ceremony's first call has answered.

The passkey's relying party is the project's own host, and a page on your origin uses it through WebAuthn's related origins: the project publishes its registered web apps' origins at `GET /.well-known/webauthn`, and the same list decides which origins a ceremony is accepted from. Register your site as a web app of the environment, with its origin (`https://app.example.com`): at most five registrable domains across the environment's web apps. A browser without related-origin support refuses a passkey from an origin that is not the project's host.

`passkey.remove(id)` removes one. Renaming is `pb.auth.api.webauthnRenameCredential(...)`.

## Magic links

```ts
// src/magic.ts
import { pb } from "./lib/palbase";

await pb.auth.magicLink.send("ada@example.com");

// On the page the link opened (https://app.example.com/auth/magic-link?token=…):
const token = new URLSearchParams(window.location.search).get("token");
if (token) await pb.auth.magicLink.verify(token);
```

## Phone codes

```ts
// src/phone.ts
import { pb } from "./lib/palbase";

await pb.auth.phone.sendCode("+905551234567");
const result = await pb.auth.phone.verifyCode("+905551234567", "482913");
if (result.mfaRequired) console.log("a second factor is needed");
else console.log("signed in", result.user.id);
```

Phone sign-in must be enabled for the project (`provider_not_enabled` otherwise). A code is texted through the project's own SMS provider, or its verification service when the phone settings say so (`PUT /admin/providers/phone/settings`). The answer is the same whether or not the number has an account, and sending is limited per number and per address.

## Social sign-in

Google, Apple, GitHub and Microsoft sign-in in a browser is a transaction the auth module keeps (`/auth/oauth/transactions`). The client has no one-call method for it. The steps are four calls, all on `pb.auth.api`:

1. `socialConfig` (`GET /auth/oauth/config`) answers the browser clients one application may use. `application_key` and `variant` are the ones the provider's browser client was set up with in Studio's Auth providers, and its return URIs are where the provider sends the user back.
2. `socialBegin` (`POST /auth/oauth/transactions`) takes the client's key, the return URI and a challenge made from a secret only this tab holds, and answers the provider's `authorization_url`.
3. The provider sends the user to the project's callback, which sends them on to your return URI with `?transaction_id=…&result_code=…`.
4. `socialComplete` (`POST /auth/oauth/transactions/{id}/complete`) takes the result code and the secret, and answers the session.

```ts
// src/social.ts
import { pb } from "./lib/palbase";

function base64url(bytes: ArrayBuffer | Uint8Array): string {
  const u = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
  return btoa(String.fromCharCode(...u)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}

/** On the sign-in page: open the provider. */
export async function startGoogle(): Promise<void> {
  const config = await pb.auth.api.socialConfig({ query: { application_key: "web", platform: "web", variant: "production" } });
  const google = config.data.clients.find((c) => c.provider === "google" && "mode" in c && c.mode === "browser");
  if (!google) throw new Error("no Google browser client is set up for this application");

  const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
  const challenge = base64url(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier)));
  const begun = await pb.auth.api.socialBegin({
    body: {
      client_key: google.key,
      completion_challenge: challenge,
      completion_challenge_method: "S256",
      purpose: "sign_in",
      return_uri: "https://app.example.com/signin/callback",
    },
  });
  sessionStorage.setItem(`social:${begun.data.transaction_id}`, verifier);
  if (begun.data.authorization_url) window.location.assign(begun.data.authorization_url);
}

/** On the return URI's page: finish it. */
export async function finishSocial(): Promise<string> {
  const q = new URLSearchParams(window.location.search);
  const id = q.get("transaction_id") ?? "";
  const verifier = sessionStorage.getItem(`social:${id}`) ?? "";
  sessionStorage.removeItem(`social:${id}`);
  const done = await pb.auth.api.socialComplete({
    path: { id },
    body: { completion_verifier: verifier, result_code: q.get("result_code") ?? "" },
  });
  const result = done.data;
  if (result.status === "signed_in") {
    await pb.auth.setSession(result.session);
    return result.is_new_user ? "welcome" : "welcome back";
  }
  if (result.status === "mfa_required") {
    // Finish with pb.auth.mfa.challenge(result.mfa_token, …)
    return `second factor: ${result.factors.join(", ")}`;
  }
  return "linked";
}
```

What the provider reported, a refusal or a cancel included, comes back from `socialComplete` as a `PalbaseError`. The callback itself always sends the user back. A transaction expires (`auth_transaction_expired`, 410), and the result code is good for a minute after the provider sends the user back. Completing again with the same body answers the same result. `socialCancel` abandons one that has not completed.

## Passwords

```ts
// src/password.ts
import { pb } from "./lib/palbase";

// Forgot it: the email's link lands on https://app.example.com/auth/reset-password?token=…
await pb.auth.password.requestReset("ada@example.com");
const token = new URLSearchParams(window.location.search).get("token");
if (token) await pb.auth.password.confirmReset(token, "a-new-long-passphrase");

// Signed in: change it, or add one to an account that has none (passkey or social).
await pb.auth.password.change({ current_password: "a-new-long-passphrase", new_password: "another-long-passphrase" });
const me = await pb.auth.getUser();
if (!me.has_password) await pb.auth.password.set({ new_password: "a-first-long-passphrase" });
```

## The user's sessions

```ts
// src/devices.ts
import { pb } from "./lib/palbase";

console.log(await pb.auth.sessions.list());
await pb.auth.sessions.revoke("ses_01"); // one of them
await pb.auth.sessions.revokeAll(); // signed out everywhere
```

## Listening for changes

```ts
// src/listen.ts
import { pb } from "./lib/palbase";

const stop = pb.auth.onAuthStateChange((event, session) => {
  if (event === "SIGNED_OUT" || event === "SESSION_EXPIRED") window.location.assign("/login");
  if (event === "SIGNED_IN") console.log("hello", session?.userId);
});
// later: stop();
void stop;
```

| Event | When |
|---|---|
| `SIGNED_IN` | A flow started a session, or another tab signed someone in. |
| `TOKEN_REFRESHED` | The access token was refreshed, here or in another tab. |
| `USER_UPDATED` | `getUser()` read the profile, and it was stored with the session. |
| `SIGNED_OUT` | `signOut()`, or a sign-out in another tab. |
| `SESSION_EXPIRED` | The refresh token was refused (revoked, reused, expired). |

`pb.auth.sessionEndReason` says why a session ended without the app signing out, set before `SESSION_EXPIRED` is told so a listener reads it: `expired`, `revoked`, `userDeleted` (the account was deleted) or `userBanned` (it was suspended). It is `null` again once someone signs in or the app signs out.

A tab that finds a different user's session in the shared store says `SIGNED_OUT` and then `SIGNED_IN`, and a call it had in flight is not sent again as the new user.

## Signing out and deleting the account

`signOut()` ends the session on the server (`POST /auth/logout`) and here. A failed call still signs out locally.

`deleteAccount(password?)` deletes the account (`DELETE /auth/user`), everything tied to it and its sessions, and ends the session here. An account with a password gives it — `has_password` on `getUser()` says whether it has one — and auth asks for it again: a password missing or wrong is `401 reauth_required`, and the session is kept. An account without one (passkey, social, phone) is deleted on the strength of its session, and a password sent for it is ignored:

```ts
// src/delete-account.ts
import { pb } from "./lib/palbase";

/** Whether the confirmation asks for the password: only an account that has one gives it. */
export async function asksForPassword(): Promise<boolean> {
  return (await pb.auth.getUser()).has_password;
}

/** A missing or wrong password is a PalbaseError, 401 reauth_required, and the user stays signed in. */
export async function deleteAccount(password?: string): Promise<void> {
  await pb.auth.deleteAccount(password);
}
```

## `pb.auth.api`

Every client operation of the auth contract, typed, through the session's transport. A few an app reaches for:

| Call | Path |
|---|---|
| `pb.auth.api.updateMe({ body: { locale: "tr" } })` | `PATCH /auth/me` |
| `pb.auth.api.listIdentities()` | `GET /auth/identities` |
| `pb.auth.api.unlinkIdentity({ path: { id } })` | `DELETE /auth/identities/{id}` |
| `pb.auth.api.webauthnRenameCredential({ path: { id }, body })` | `PUT /auth/webauthn/credentials/{id}` |

The `/admin/*` operations are in the same client, and every one of them needs the secret key. From an app they are refused before anything is sent (`missing_credential`). Make them from a server with [`palbase/server`](/docs/server/overview).

## Proof of work

The auth module may answer a sign-in, a sign-up or a code request with `403 pow_required` and a challenge when the address looks like a bot. The client solves it (a SHA-256 search, longer the harder the challenge) and sends the same request once more with the answer. You never see the challenge. One the client cannot solve comes back as `pow_unsolved`.

## Related

- [Overview](/docs/web/overview) — `createClient`, sessions and calling the project from a browser
- [Error Handling](/docs/web/errors) — the codes these flows answer
- [Calling Your Backend](/docs/web/backend-calls) — the access token on your own routes
- [Next.js](/docs/web/nextjs) — the client in a Next.js app
- [Authentication in your backend](/docs/backend/authentication) — how a machine checks the token
- [Test Users](/docs/backend/test-users) — accounts made with the secret key



<!-- ===== web/backend-calls ===== -->

# Calling Your Backend

Your own backend runs on a machine, at an address of its own: `https://<ref>.app.palbase.studio` for the machine named `backend`, `https://<name>-<ref>.app.palbase.studio` for any other. The app calls it through its client. `palbase apps:sync` reads the contract the backend serves (a `palbase/backend` app writes one of its routes, their schemas and the errors they throw; another program serves its own OpenAPI document) and writes the app a module in which each route is a typed method: `pb.backend.notes.create({ title })`. The call goes from the browser to the machine's address with the signed-in user's access token. A machine asks for no API key, and the client never sends it one: your routes are the gate.

## Quick example

The backend: a route, and the origins its browsers come from.

```ts
// server/src/notes/notes.controller.ts
import { Body, Controller, Get, Post, User, z, type UserT } from "palbase/backend";

const CreateNote = z.object({ title: z.string().min(1).max(200) });
type CreateNote = z.infer<typeof CreateNote>;

interface Note {
  id: string;
  owner: string;
  title: string;
}

@Controller("/notes")
export class NotesController {
  private readonly notes: Note[] = [];

  @Get("")
  list(@User() user: UserT): Note[] {
    return this.notes.filter((n) => n.owner === user.id);
  }

  @Post("")
  create(@Body(CreateNote) body: CreateNote, @User() user: UserT): Note {
    const note = { id: crypto.randomUUID(), owner: user.id, title: body.title };
    this.notes.push(note);
    return note;
  }
}
```

```ts
// server/src/app.module.ts
import { Module } from "palbase/backend";
import { NotesController } from "./notes/notes.controller";

@Module({ controllers: [NotesController] })
export class AppModule {}
```

```ts
// server/src/main.ts
import { PalbaseFactory } from "palbase/backend";
import { AppModule } from "./app.module";

// Browsers on this origin may call the machine: preflights are answered, CORS headers are sent.
await PalbaseFactory.create(AppModule, { cors: { origins: ["https://app.example.com"] } });
```

Once the backend is deployed, write the app its module from the checkout's root:

```sh
palbase apps:sync shop-web
```

The app imports `pb` from it, and the backend is `pb.backend`:

```ts
// src/notes.ts
import { pb } from "../palbase/shop-web";

// The user signs in with the project's auth; the backend's calls carry their token.
await pb.auth.signIn("ada@example.com", "correct-horse-battery-staple");

const created = await pb.backend.notes.create({ title: "Ship the docs" });
const mine = await pb.backend.notes.list();
console.log(created.id, mine.length);
```

What `palbase apps:sync` wrote, cut to this page's routes and put in one file:

```ts
// palbase/shop-web.ts
// Code generated by palbase apps:sync — DO NOT EDIT. (Cut to this page's routes.)
import { createClient, type BackendBase, type CallOptions, type ClientOptions, type PalbaseClient } from "palbase/web";
import { __registerBackend } from "palbase/web/palbe";

export interface NotesCreateRequest {
  title: string;
}

export interface NotesCreateResponse {
  id: string;
  owner: string;
  title: string;
}

export interface NotesListResponseItem {
  id: string;
  owner: string;
  title: string;
}

export type NotesListResponse = NotesListResponseItem[];

// The routes, for the clients of this environment's project alone.
__registerBackend("https://k3xq81w4m.palbase.studio", "backend", "backend", "https://k3xq81w4m.app.palbase.studio", {
  notes: {
    create: { method: "POST", path: "/notes" },
    list: { method: "GET", path: "/notes", input: "none" },
  },
});

export interface Backend extends BackendBase {
  notes: {
    create(input: NotesCreateRequest, options?: CallOptions): Promise<NotesCreateResponse>;
    list(options?: CallOptions): Promise<NotesListResponse>;
  };
}

export const settings = {
  url: "https://k3xq81w4m.palbase.studio",
  publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5",
  environment: "staging",
  app: "shop-web",
  appId: "0b6f2c1e-8d4a-4f7b-9c3e-5a1d2e3f4b6c",
} as const;

/** The app's client: its project's modules (pb.auth, …) and its backends, pb.backend. */
export type Client = PalbaseClient & { backend: Backend };

let client: Client | undefined;

/** The app's client, made once with these settings — and with options, when connect(options) is called before anything uses the client (pb). */
export function connect(options: Omit<ClientOptions, "url" | "publishableKey"> = {}): Client {
  if (client) {
    if (Object.keys(options).length > 0) throw new Error("palbase: connect(options) comes before the client is first used — call it as the app starts");
    return client;
  }
  client = createClient({ ...options, url: settings.url, publishableKey: settings.publishableKey, appId: settings.appId }) as Client;
  return client;
}

/** The app's client, made when it is first used: pb.<backend>.<controller>.<method>(), pb.auth, … */
export const pb: Client = new Proxy({} as Client, {
  get(_, key) {
    const c = connect();
    const value: unknown = Reflect.get(c, key, c);
    return typeof value === "function" ? value.bind(c) : value;
  },
  has: (_, key) => Reflect.has(connect(), key),
});
```

## The generated module

`palbase apps:sync` writes under `palbase/`, from what the project serves now, and touches nothing else in the checkout. For a web app, `palbase/<app>.ts` is what the app imports: its `settings`, `connect()` and `pb`, typed with each backend of the environment, and with one backend that backend's types, typed errors and gateways too (with several, each one's are in `palbase/palbe/<machine>.ts`). Each environment's own files sit beside them, which a build for that environment imports instead ([Building for an environment](#building-for-an-environment)). Every file it writes, the editor's environment, CI's `--check` and its refusals are in [Syncing an App's Settings](/docs/apps/sync#what-it-writes); registering the app is [Client Apps](/docs/apps/overview).

Run it again when the backend's routes change: a call the backend no longer takes is then a compile error in the app. To try a route no machine serves yet, `--backend <machine>=<dir>` makes the client from the backend's checkout on this computer ([`palbase apps:sync`](/docs/cli/reference#palbase-appssync)).

**The backend's name.** `pb.<backend>` is the machine's name camelCased: `pb.backend` for the machine named `backend`, `pb.shopApi` for `shop-api`. `palbase apps:sync --as shop-api=shop` names it otherwise, the same in every environment. A name the client already has (`auth`, `flags`, `storage`, …) is refused.

**A route's method.** A `palbase/backend` route is its controller's name without `Controller`, then its method's: `NotesController.create` is `pb.backend.notes.create`. The arguments are, in order: each path parameter (`/notes/{id}` takes `id` first), the input (the body, or for a `GET` the query its schema declares), then the options:

| Option | What it is |
|---|---|
| `headers` | Headers of your own, sent with the call. |
| `signal` | An `AbortSignal` that cancels it. |

A route the generated types do not have yet is `pb.backend.call("notes/create", input, options?)`: it `POST`s the input as JSON and answers the route's JSON, untyped.

**Options of the client.** `pb` makes its client the first time it is used, with the settings of its environment. Give it options of [`createClient`](/docs/web/overview#createclientoptions) (`analytics`, `consent`, `language`, `appVersion`, …) with `connect(options)` as the app starts, before anything reads `pb`:

```ts
// src/main.ts
import { connect } from "../palbase/shop-web";

connect({ analytics: true, appVersion: "2.4.1", consent: { start: { analytics: "denied", performance: "denied" } } });
```

A backend is its own project's: the module registers it for the clients of its environment's project alone. A client made for another project that reads `pb.backend` throws a `TypeError` before anything is sent, so one project's users never send their token to another project's machine.

## Building for an environment

Each environment's backend has its own routes and its own address, so an app is built against one environment. In a Vite app, `palbase/web/vite` picks it by the build's mode:

```ts
// vite.config.ts
import { palbase } from "palbase/web/vite";

export default {
  plugins: [
    // vite (development) is built against staging; vite build (production) against main.
    palbase({ app: "shop-web", environments: { development: "staging", production: "main" } }),
  ],
};
```

In each mode the app's imports of `palbase/<app>` and `palbase/palbe/<machine>` are that environment's files. A mode the plugin is given no environment for fails the build and says so. Before `vite build`, the plugin type-checks the app against its environment with the app's own TypeScript and tsconfig, so a route that environment's backend does not have, or a call that no longer fits its types, fails the build instead of the app.

| Option | What it is |
|---|---|
| `app` | The app's slug, as `palbase apps:list` shows it. |
| `environments` | Each mode the app is built in (`vite --mode`), and the environment it is built against. |
| `dir` | Where `palbase apps:sync` writes. Default: `palbase`. |
| `tsconfig` | The app's tsconfig, from its root. Default: `tsconfig.app.json` where there is one, else `tsconfig.json`. |
| `typecheck` | Type-check the app before a build. Default: `true`. |

With another bundler, `palbase/<app>.ts` is the `--types` environment's, and `palbase/<app>.<env>.ts` is each environment's to import for a build of that environment.

## The token

Every call carries the signed-in user's access token as `Authorization: Bearer …`, and nothing when no one is signed in: the route decides whom it answers. The token is the session's, the one `pb.auth` keeps and refreshes. A token the machine refuses before its time is refreshed once and the call is sent again.

A write (`POST`, `PUT`, `PATCH`, `DELETE`) carries an `Idempotency-Key` the client makes, the same one on every attempt of that call. The client sends a call again on its own as it does the project's calls ([Error Handling](/docs/web/errors#what-the-client-retries)): a read, or a write whose route keeps the key, never another.

A `palbase/backend` app checks the token on every call that sends one: the signature against the project's keys, and that the session still stands. A route that needs a user answers:

| Answer | When |
|---|---|
| `401 unauthorized` | No token. |
| `401 invalid_token` | A token that is not valid, or an `Authorization` header that is not a Bearer token. `data.reason` says which. |
| `403 email_not_verified` | The route asks for a verified email (`auth: { verifiedEmail: true }`) and the user's is not. |
| `503 auth_unavailable` | The token could not be checked just now. `Retry-After: 1`, and sending again is safe. |

A route marked open (`{ auth: false }`) answers anyone. On such a route a bad token is no one, not a refusal. See [Authentication](/docs/backend/authentication).

## What comes back

A route's answer is its JSON, typed by its contract, or `undefined` for a route that answers nothing (`204`). A refusal rejects the call with a `BackendError`:

| Field | What it is |
|---|---|
| `kind` | `validation` (a `400` with the fields that failed, or a call the client refused before sending it), `unauthorized` (`401`), `rateLimited` (`429`), `network` (no answer came), `decode` (an answer that is not JSON), `server` (every other refusal). |
| `code` | The envelope's `error`: `bad_request`, `not_found`, your own `note_locked`, … |
| `status` | The HTTP status; `0` when no answer came. |
| `message` | The envelope's `error_description`. |
| `fields` | A `400`'s fields: `{ field, message }` for each. |
| `retryAfter` | Seconds to wait, when the answer said. |
| `requestId` | The request's id. Quote it to find the call in the machine's logs. |
| `data` | The envelope's `data`, as the route sent it. |

An error the route throws that its contract names (palbase/backend reads them from the route's source as it writes the contract) comes as its own generated class instead, with its `code`, `status`, typed `data` and the `BackendError` as its `cause`. See [Responses & Errors](/docs/backend/errors).

```ts
// src/create-note.ts
import { isBackendError } from "palbase/web";
import { pb } from "../palbase/shop-web";

export async function createNote(title: string): Promise<string> {
  try {
    const note = await pb.backend.notes.create({ title });
    return `created ${note.id}`;
  } catch (e) {
    if (!isBackendError(e)) throw e;
    switch (e.kind) {
      case "validation":
        return e.fields?.map((f) => `${f.field}: ${f.message}`).join(", ") ?? e.message;
      case "unauthorized":
        return "sign in again";
      case "rateLimited":
        return `too many notes; try again in ${e.retryAfter ?? 1} s`;
      default:
        return `not created: ${e.code} (${e.requestId ?? "no request id"})`;
    }
  }
}
```

`isBackendError(e)` holds where `instanceof BackendError` would not: two copies of the package loaded side by side make two classes.

A call the client refuses before anything is sent is a `BackendError` of kind `validation` with status `0`: a path parameter that is missing, empty, `.` or `..` (`missing_path_param`, `invalid_path_parameter`), an input for a route that takes none (`unexpected_argument`), a body for a `GET` (`unsupported_get_input`), a query value that is an object or an array (`invalid_query_value`), an upload's file that is not a `Blob` (`invalid_file`).

Every refusal of a `palbase/backend` app is the platform's envelope, whatever the route:

```json
{
  "error": "bad_request",
  "error_description": "Request body failed validation",
  "status": 400,
  "request_id": "req_6f1c2b9e-…",
  "data": { "fields": [{ "field": "title", "message": "Invalid input: expected string, received undefined" }] }
}
```

| Status | `error` | What it means |
|---|---|---|
| 400 | `bad_request` | A parameter failed its schema. `data.fields` names each, 20 at most, and `data.more` counts the rest. |
| 401, 403 | `permission_denied` | The database refused the caller: a row-level security policy, or a table their role has no grant on. 403 to a signed-in user, 401 to no one, for whom signing in may be what is missing. See [Row-Level Security](/docs/backend/row-level-security). |
| 404 | `not_found` | No route for the method and path, or the handler said so. |
| 413 | `payload_too_large` | A body over the app's limit (1 MiB unless the app says more). |
| 429 | `too_many_requests` | Over the route's limit for this caller. `Retry-After` and `data.retryAfter` say when to try again. |
| 503 | `service_unavailable`, `database_unavailable`, `auth_unavailable` | Something the route needs did not answer. `Retry-After` says when to come back. |
| 500 | `internal_error` | The handler threw something that is not a refusal. The details are in the machine's logs under the `request_id`. |

## Encrypted fields

A field your route marks `encrypted()` — or answers through `encrypt()` — the module seals before the call leaves the browser and opens when its answer arrives: the network panel shows `pbt1.…`, your code the value, and the calls are written as any other. The module holds the project's id and signing key for it, which `palbase apps:sync` writes. What can be marked, the keys and their rotation, and the errors are in [Encrypted Requests](/docs/backend/request-encryption).

## Cross-origin calls

A machine's address is not your app's origin, so the browser sends a preflight before each call that carries a token or a JSON body. A `palbase/backend` app answers it for the origins of the project's web apps by itself: those you give with `palbase apps:env:set <app> --origin`. Name any others in `PalbaseFactory.create(…, { cors })`:

| `cors` | Effect |
|---|---|
| `{ origins: ["https://app.example.com"] }` | Exact origins: `https://host[:port]`, `http` only for `localhost` and `127.0.0.1`. A preflight from another origin is answered 403. |
| `{ origins: "*" }` | Any origin. The credential is a bearer token, not a cookie, so `*` hands nothing to another site by itself. |
| `maxAge` | Seconds a browser keeps a preflight's answer (default 600). |
| left out | The project's web apps' origins alone. With no web app in the project, no CORS at all: a browser on another origin cannot call the machine. |

The machine is started with the web apps' origins in `PALBASE_WEB_ORIGINS` (comma-separated), so a backend without `palbase/backend` can read them too. A web app's origin added or taken away rolls the machine out again with no downtime, within about 15 seconds.

The answer exposes `retry-after` and `x-request-id` to your code. Requested headers are allowed as asked, so a header of your own needs no setting.

This is the backend's own CORS: the platform adds no header at a machine's address. The project's address is a separate matter: it answers a page on any site by itself. See [Overview](/docs/web/overview#calling-the-project-from-a-browser).

## A backend without a contract

`palbase apps:sync` makes a client from the contract the machine serves. A `palbase/backend` app writes its own; a program built another way that serves an OpenAPI document names where with [`palbase machines:update <machine> --openapi-path <path>`](/docs/cli/reference#palbase-machinesupdate). A machine with no contract gets no client, and the app calls it with `fetch` and the user's token:

```ts
// src/lib/api.ts
import { pb } from "./palbase";

const BACKEND = "https://k3xq81w4m.app.palbase.studio";

/** One call to the machine, as the signed-in user. */
export async function api<T>(method: string, path: string, body?: unknown): Promise<T> {
  const token = (await pb.auth.currentSession())?.accessToken;
  const res = await fetch(`${BACKEND}${path}`, {
    method,
    headers: {
      ...(token ? { authorization: `Bearer ${token}` } : {}),
      ...(body !== undefined ? { "content-type": "application/json" } : {}),
    },
    body: body !== undefined ? JSON.stringify(body) : undefined,
  });
  if (!res.ok) throw new Error(`${method} ${path} answered ${res.status}`);
  return (res.status === 204 ? undefined : await res.json()) as T;
}
```

```ts
// src/lib/palbase.ts
import { createClient } from "palbase/web";

export const pb = createClient({ url: "https://k3xq81w4m.palbase.studio", publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5" });
```

`currentSession()` answers the session the client holds, which it refreshes before it lapses. A token the backend refuses with `401` before its time (revoked, refreshed in another tab) is worth `pb.auth.refreshSession()` and one more try.

## A machine that sleeps

A machine of a shared size sleeps when it is idle, and the next request wakes it. That request waits while the machine starts, so the first call after a quiet spell is slower than the rest. A machine of a dedicated size never sleeps. See [Machines](/docs/machines/overview).

## Related

- [Overview](/docs/web/overview) — the client, the session and calling the project from a browser
- [Gateways](/docs/web/gateways) — your backend's realtime channels, from the same module
- [Uploads](/docs/web/uploads) — sending a file to your backend's upload route
- [Auth](/docs/web/auth) — signing the user in
- [Error Handling](/docs/web/errors) — `PalbaseError`, and what the client retries
- [Controllers & Routing](/docs/backend/controllers) — the routes this page calls
- [Authentication](/docs/backend/authentication) — how the machine checks the token
- [Machines](/docs/machines/overview) — addresses, sizes, sleep and wake



<!-- ===== web/errors ===== -->

# Error Handling

Every call through the client returns its answer or throws. There is no `{ data, error }` pair to unpack. What it throws for a refusal is a `PalbaseError`, the one error class of the Palbase SDKs, exported from `palbase/web` and `palbase/server` alike. It carries the HTTP status, the module's machine-readable code, its words, the request's id and, when the server said so, how long to wait. Before it throws, the client has already done what can be done without your code: it refreshed a token that was refused before its time, solved auth's proof-of-work, and waited out a "not now" on a call that is safe to send twice.

## Quick example

```ts
// src/lib/palbase.ts
import { createClient } from "palbase/web";

export const pb = createClient({ url: "https://k3xq81w4m.palbase.studio", publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5" });
```

```ts
// src/login.ts
import { PalbaseError } from "palbase/web";
import { pb } from "./lib/palbase";

export async function login(email: string, password: string): Promise<string> {
  try {
    const result = await pb.auth.signIn(email, password);
    return result.mfaRequired ? "enter your second factor" : "signed in";
  } catch (e) {
    if (!(e instanceof PalbaseError)) throw e;
    if (e.status === 401) return "wrong email or password";
    if (e.status === 429) return `too many tries; wait ${e.retryAfter ?? 60} seconds`;
    if (e.status === 0) return "you are offline";
    console.error(e.op, e.status, e.code, e.message, e.requestId);
    return "something went wrong";
  }
}
```

## `PalbaseError`

| Field | What it is |
|---|---|
| `status` | The HTTP status. `0` for a call that never got an answer (see below). |
| `code` | The envelope's `error`: `invalid_token`, `rate_limited`, `pow_required`, … When the answer carried no envelope it is `http_<status>`. |
| `message` | The envelope's `error_description`, in words a person can read. |
| `requestId` | The request's id (`request_id`, or the `x-request-id` header). Quote it to find the call in logs. |
| `retryAfter` | Seconds the server asked to wait (`Retry-After`, or the envelope's `retry_after`), when it asked. |
| `body` | The refusal's body as sent, read up to 64 KiB. Useful for answers that are not the envelope (OAuth errors, a proof-of-work challenge). |
| `op` | The operation that was refused (`Login`, `RefreshToken`, `WebauthnLoginFinish`, …). |
| `cause` | The underlying error, for a call that failed before an answer. |

Check it with `instanceof PalbaseError`. The modules' typed calls (`pb.auth.api`, `pb.flags.api`) throw the same class. A call to your own backend through `pb.<backend>` refuses with a `BackendError` instead: the same envelope's `code`, `status`, `requestId` and `retryAfter`, with a `kind` to switch on and the fields that failed. See [Calling Your Backend](/docs/web/backend-calls#what-comes-back).

## The envelope

Every module and every `palbase/backend` app refuses in one shape:

```json
{
  "error": "rate_limited",
  "error_description": "Too many attempts; try again later",
  "status": 429,
  "request_id": "req_4b1f0c7e-…",
  "retry_after": 60
}
```

`status` mirrors the response's status. `retry_after` is there on a refusal that ends with time, and the `Retry-After` header says the same. A `palbase/backend` app may add `data`, such as the fields that failed their schema. `PalbaseError` keeps the whole body in `body`.

## What the client retries

A call is sent again only when sending it again cannot do the work twice:

- **Which calls.** Reads (`GET`, `HEAD`), and writes whose contract takes an `Idempotency-Key`. For those the client makes one key per call and every attempt carries the same one, so the server answers a repeat with the first answer and changes nothing. A write without one, a sign-in for example, is never sent twice by the client.
- **Which answers.** `429`, `502`, `503`, `504`, and a call that never reached the server (`network_error`). Every other answer is yours.
- **How long.** Three attempts in all, the first included. When the server said how long to wait, the client waits exactly that, and a `Retry-After` over 30 seconds is not waited for: the error comes to you with `retryAfter` set. When it said nothing, the client waits 0.5 s, then 1 s, with a little jitter.

Change it per client:

```ts
// src/lib/patient.ts
import { createClient } from "palbase/web";

// Five attempts, and wait up to two minutes when the server asks.
export const pb = createClient({
  url: "https://k3xq81w4m.palbase.studio",
  publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5",
  retry: { attempts: 5, maxWaitSeconds: 120 },
});
```

`{ attempts: 1 }` turns retries off. A call you abort is not retried.

## A refused token

A call that acts for the user and is refused `401` with a code that means "this token is not good any more" (`invalid_token`, `token_expired`, `session_expired`, `session_revoked`, `missing_token`) gets one refresh of the session, and is sent once more, only if the session is still the same user's. Every other 401, such as a wrong password, a wrong code or a wrong current password, is the answer and goes to you as it came.

When the refresh itself is refused, because the refresh token was used twice, revoked or expired, the session is over. The client clears it, tells your app `SESSION_EXPIRED` through `pb.auth.onAuthStateChange`, and the call's error reaches you. Send the user to sign in from the listener, not from every `catch`. See [Auth](/docs/web/auth#listening-for-changes).

A session that changed under a refresh (another tab signed out, or signed in as someone else) throws an error whose `code` is `session_changed`, and the call that asked is not sent again. Read it by `code`: it is not a `PalbaseError`.

## Proof of work

Auth may answer a sign-in, a sign-up or a code request `403 pow_required` with a challenge, when the address it comes from looks like a bot. The client solves it and sends the same request once more with the answer. You see nothing of it unless solving fails, which comes back as `403 pow_unsolved`. A request whose body cannot be read twice (a stream) is not sent again, and the `pow_required` error comes to you.

## Errors the client makes itself

These never came from a server:

| `status` | `code` | When |
|---|---|---|
| 0 | `network_error` | The request did not reach the project: offline, DNS, a refused connection, or a cross-origin call the browser blocked. Retried like a 503. |
| 0 | `missing_credential` | The operation needs what the client does not hold: a signed-in user, or the secret key for an `/admin/*` call. Nothing was sent. |
| 0 | `invalid_path`, `invalid_path_parameter` | A path parameter that is empty, `.` or `..`, or a path that would leave the project's address. Nothing was sent. |
| 2xx | `undeclared_answer` | The server answered a success the contract does not declare. The request may have taken effect. |
| 3xx | `undeclared_redirect` | The server answered a redirect. The client never follows one, because a redirect would carry the key to whatever host it names. |
| any | `invalid_json` | An answer the contract says is JSON was not. |

`createClient` itself throws a `TypeError`, not a `PalbaseError`, for a secret key, for anything that is not a publishable key, and for a `url` that is not an `https` origin (`http` only for a loopback address).

`network_error` is also what a browser's CORS refusal looks like from code: the browser hides why. The project's address answers a page on any site, its refusals included, so a call the client makes is not refused this way (see [Overview](/docs/web/overview#calling-the-project-from-a-browser)). A machine's address answers only the origins its backend names: see [Calling Your Backend](/docs/web/backend-calls#cross-origin-calls).

## Codes worth handling by name

| Where | `status` / `code` | What to do |
|---|---|---|
| Sign-in | `401` | Wrong email or password. Say so without saying which. |
| Sign-in | `429` with `retryAfter` | The account is locked for a while after repeated failures, or the address is limited. Show the wait. |
| Sign-up, password | `400` | A password the policy refuses or one known from a breach; `message` says which. |
| A code (MFA, phone, email) | `401` | A wrong or used code. |
| Social sign-in | `410 auth_transaction_expired` | The transaction expired. Start again. |
| Any module | `429` | Over the project's request rate or a module's quota. Honour `retryAfter`. |
| Any module | `503` | The platform could not answer now. The client already retried a safe call. |

## Related

- [Overview](/docs/web/overview) — the client and its options
- [Auth](/docs/web/auth) — the flows and their answers
- [Calling Your Backend](/docs/web/backend-calls) — your backend's refusals as a `BackendError`
- [Responses & Errors](/docs/backend/errors) — what a `palbase/backend` app sends
- [Server SDK](/docs/server/overview) — the same error from a server



<!-- ===== web/uploads ===== -->

# Uploads

A browser sends a file to the project's storage, never through your machine, in one of two ways, and your backend decides in both. With a **signed upload URL**, your backend asks storage for a grant of one object (its path, a size ceiling, the content types the bucket takes, the user it will belong to) and the browser `PUT`s the bytes to it. With an **upload route** of your backend, the app's call sends the file and storage asks the machine first ([An upload route](#an-upload-route)). A publishable key alone cannot write, list or delete objects: the grant, or the route's yes, always comes from your backend.

## Quick example

The backend half, a route that grants the signed-in user one upload into the `avatars` bucket:

```ts
// server/src/uploads/uploads.controller.ts
import { Body, Controller, Palbase, Post, User, z, type UserT } from "palbase/backend";

const UploadRequest = z.object({ name: z.string().min(1).max(200) });
type UploadRequest = z.infer<typeof UploadRequest>;

@Controller("/uploads")
export class UploadsController {
  @Post("/avatar")
  async avatar(@Body(UploadRequest) body: UploadRequest, @User() user: UserT): Promise<{ url: string; path: string }> {
    const path = `${user.id}/${crypto.randomUUID()}-${body.name}`;
    const grant = await Palbase.storage.createUploadUrl({
      path: { bucket: "avatars" },
      // Ten minutes, 5 MB at most, and the object is the user's: it goes when they are deleted.
      body: { path, expires_in: 600, max_bytes: 5_000_000, owner_id: user.id },
    });
    return { url: grant.data.url, path };
  }
}
```

```ts
// server/src/app.module.ts
import { Module } from "palbase/backend";
import { UploadsController } from "./uploads/uploads.controller";

@Module({ controllers: [UploadsController] })
export class AppModule {}
```

The browser half:

```ts
// src/lib/palbase.ts
import { createClient } from "palbase/web";

export const pb = createClient({ url: "https://k3xq81w4m.palbase.studio", publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5" });
```

```ts
// src/upload.ts
import { pb } from "./lib/palbase";

const BACKEND = "https://k3xq81w4m.app.palbase.studio";

interface StoredObject {
  bucket: string;
  path: string;
  size: number;
  content_type: string;
}

export async function uploadAvatar(file: File): Promise<StoredObject> {
  const token = (await pb.auth.currentSession())?.accessToken ?? "";
  const asked = await fetch(`${BACKEND}/uploads/avatar`, {
    method: "POST",
    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
    body: JSON.stringify({ name: file.name }),
  });
  if (!asked.ok) throw new Error(`the backend refused the upload: ${asked.status}`);
  const { url } = (await asked.json()) as { url: string };

  // The URL is at the project's address: send the bytes to it as it is.
  const res = await fetch(url, {
    method: "PUT",
    headers: { "content-type": file.type || "application/octet-stream" },
    body: file,
  });
  if (!res.ok) throw new Error(`storage refused the upload: ${res.status}`);
  return (await res.json()) as StoredObject;
}
```

## An upload route

A route your `palbase/backend` app declares with `@Upload`, naming its bucket and a path template (`{userId}/{uploadId}-{filename}`), takes the file itself. The app calls it as any route, the file after its input, and the call goes to the project's storage in one request (`POST /storage/upload/<machine>/<route>`), with the user's token when someone is signed in. Storage asks the machine whether this caller may upload, writes the file where the template says (held to the bucket's size and types), then runs the route's handler with the stored object. What the handler answers is the call's answer; a refusal deletes the object. The app asks for no grant first, and the path is never the browser's to choose. The backend's side, its options and storage's steps are in [Upload routes](/docs/backend/direct-uploads#upload-routes).

The backend half:

```ts
// server/src/profile/profile.controller.ts
import { Controller, Upload, UploadedObject, User, type UserT } from "palbase/backend";

@Controller("/profile")
export class ProfileController {
  // Into the avatars bucket, under a folder of the user's.
  @Upload("/avatar", { bucket: "avatars", pathTemplate: "{userId}/{uploadId}-{filename}" })
  avatar(@UploadedObject() file: UploadedObject, @User() user: UserT): { path: string; size: number; contentType: string } {
    console.log(`${user.id} uploaded ${file.size} bytes`);
    return { path: file.path, size: file.size, contentType: file.contentType };
  }
}
```

The browser half, with what `palbase apps:sync` writes for that route:

```ts
// palbase/shop-web.ts
// Code generated by palbase apps:sync — DO NOT EDIT. (Cut to this page's route.)
import { createClient, type BackendBase, type PalbaseClient, type UploadOptions } from "palbase/web";
import { __registerBackend } from "palbase/web/palbe";

export interface ProfileAvatarResponse {
  path: string;
  size: number;
  contentType: string;
}

__registerBackend("https://k3xq81w4m.palbase.studio", "backend", "backend", "https://k3xq81w4m.app.palbase.studio", {
  profile: {
    avatar: { method: "POST", path: "/profile/avatar", input: "none", upload: true },
  },
});

export interface Backend extends BackendBase {
  profile: {
    avatar(file: Blob, options?: UploadOptions): Promise<ProfileAvatarResponse>;
  };
}

export const pb = createClient({ url: "https://k3xq81w4m.palbase.studio", publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5" }) as PalbaseClient & { backend: Backend };
```

```ts
// src/avatar.ts
import { isBackendError } from "palbase/web";
import { pb } from "../palbase/shop-web";

export async function changeAvatar(file: File, bar: HTMLProgressElement): Promise<string> {
  try {
    // Told as the bytes go out, and once more when the answer is in.
    const stored = await pb.backend.profile.avatar(file, { onProgress: ({ loaded, total }) => { bar.value = loaded / total; } });
    return `saved as ${stored.path}`;
  } catch (e) {
    if (isBackendError(e)) return `not saved: ${e.code}`;
    throw e;
  }
}
```

| Argument | What it is |
|---|---|
| path parameters, input | As the route takes them ([Calling Your Backend](/docs/web/backend-calls#the-generated-module)). The input goes as JSON beside the file. |
| `file` | A `Blob`; a `File` is one, and its name is the template's `{filename}`. |
| `onProgress` | Told `{ loaded, total }` as the bytes go out, through `XMLHttpRequest` where the page has one. |
| `signal` | An `AbortSignal` that cancels the upload. |

An upload is never sent again on its own: a lost answer can follow a file that was kept and a handler that ran. Its refusals reject with a `BackendError`, the route's own and storage's alike (`413` past the bucket's size, `415` a type it does not take).

## The grant

`POST /storage/buckets/{bucket}/upload-urls` takes the secret key, so it is made by your backend (`Palbase.storage.createUploadUrl` on a machine, `createServer(…).storage.createUploadUrl` anywhere else):

| Field | What it pins |
|---|---|
| `path` | The object's path in the bucket. Your code chooses it: put the user's id in it, never a name the browser chose alone. |
| `expires_in` | Seconds the URL works, 1 to 604800 (7 days). |
| `max_bytes` | A ceiling below the bucket's own. |
| `owner_id` | The user the object belongs to. It is deleted with them. |

The content types are the bucket's. A bucket declared to take `image/*` refuses a PDF whatever the grant says. Declare buckets in Studio's Storage screens, or with `Palbase.storage.putBucket` from a server. See [Storage](/docs/backend/storage).

What comes back is `{ url, expires_at }`. The URL is `https://<ref>.palbase.studio/storage/signed/{bucket}/{path}?…`, and every parameter in its query is covered by its signature: change one and storage answers 403. The object's path is one percent-encoded segment (`a/b.jpg` is `a%2Fb.jpg`), so pass the URL on as it is.

## Sending the bytes

`PUT /storage/signed/{bucket}/{path}` needs no key: the signature is the credential. A `PUT` with a file's content type is preflighted by the browser, and the project's address answers the preflight from a page on any site, so the browser sends the bytes to the URL as it is. See [Overview](/docs/web/overview#calling-the-project-from-a-browser).

| Header | Effect |
|---|---|
| `content-type` | What the bytes are. Storage also sniffs the type from the bytes and keeps that one. |
| `if-none-match: *` | Create only: an object already at the path is refused with 412. |
| `x-checksum-sha256` | The bytes' SHA-256 in hex: bytes that do not match are refused and nothing is kept. |

The answer is the stored object: `201` when it was created, `200` when it replaced one. It is `{ bucket, path, size, content_type, checksum_sha256, owner_id?, width?, height?, thumbhash?, variants, created_at, updated_at }`, with a picture's size, its placeholder (ThumbHash) and the renditions the bucket made of it. An upload emits `file.uploaded` to the project's webhook, so your backend can [react to it](/docs/backend/hooks).

## Progress

`fetch` reports no upload progress. `XMLHttpRequest` does:

```ts
// src/progress.ts
export function putWithProgress(url: string, file: File, onProgress: (fraction: number) => void): Promise<unknown> {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.open("PUT", url);
    xhr.setRequestHeader("content-type", file.type || "application/octet-stream");
    xhr.upload.onprogress = (e) => {
      if (e.lengthComputable) onProgress(e.loaded / e.total);
    };
    xhr.onload = () => (xhr.status === 200 || xhr.status === 201 ? resolve(JSON.parse(xhr.responseText)) : reject(new Error(`storage answered ${xhr.status}`)));
    xhr.onerror = () => reject(new Error("the upload did not reach storage"));
    xhr.send(file);
  });
}
```

Cancel with `xhr.abort()`, or with an `AbortController`'s signal on `fetch`. Nothing is kept of an upload that did not finish.

## What can go wrong

| Status | Why |
|---|---|
| 403 | The signature does not hold: expired, edited, another project's, or a download grant used for an upload. Ask the backend for a new one. |
| 412 | `if-none-match: *` and an object is already at the path. |
| 413 | Larger than the grant's `max_bytes` or the bucket's ceiling. |
| 415 | A content type the bucket does not take. |
| 400 `checksum_mismatch` | The bytes did not match `x-checksum-sha256`. Nothing was kept. |
| 422 `unreadable_picture` | A picture storage cannot decode: truncated, or a format it does not read. |
| 429 | The project's storage quota or request rate. Honour `Retry-After`. |

Check the size and type in the browser before you ask for a grant, so the user is told at once, but the grant and the bucket are what storage enforces.

## Showing what was uploaded

Reading needs no key either:

- **A public bucket**: `GET /storage/public/{bucket}/{path}`, with `?variant=<name>` for a rendition. Put it in an `<img src>` straight from the project's address: an image load is not preflighted.
- **A private bucket**: your backend signs a download URL, `Palbase.storage.createSignedUrl({ path: { bucket }, body: { path, expires_in } })`, which answers at `GET /storage/signed/{bucket}/{path}`. The same applies: an `<img src>` loads it, and a `fetch` from the page reads its bytes.

## Related

- [Storage](/docs/backend/storage) — buckets, objects, signed URLs and renditions from the server
- [Direct Uploads](/docs/backend/direct-uploads) — the grant and upload routes, in full
- [Calling Your Backend](/docs/web/backend-calls) — the generated module, and the call that asks for the grant
- [Overview](/docs/web/overview) — what the project's address answers a browser



<!-- ===== web/flags ===== -->

# Flags

`pb.flags` holds the project's feature flags and remote configuration as this browser's reader sees them: every flag's value resolved by the project for this app and whoever is signed in, kept current as the flags change. A read takes no network: the client answers from the values it holds, which it keeps in the browser between visits, and brings them up to date behind your code. Flags are defined in Studio's flags screens or by a server, never from the browser (see [Flags in your backend](/docs/backend/flags)).

## Quick example

```ts
// src/lib/palbase.ts
import { createClient } from "palbase/web";

export const pb = createClient({
  url: "https://k3xq81w4m.palbase.studio",
  publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5",
  // What a flag's conditions on the app's version read.
  appVersion: "2.4.1",
});
```

```ts
// src/checkout.ts
import { pb } from "./lib/palbase";

// The values the client holds now: last visit's for this reader, or the fallback before the first read.
const newCheckout = pb.flags.bool("new_checkout", false);
const banner = pb.flags.string("banner_text", "");
const limit = pb.flags.number("cart_limit", 20);
const theme = pb.flags.json<{ accent: string }>("theme", { accent: "#2f6feb" });
console.log(newCheckout, banner, limit, theme.accent);

// Told the keys whose values changed: a change in Studio, a sign-in, a sign-out.
const stop = pb.flags.onChange((keys) => {
  if (keys.includes("new_checkout")) console.log("the checkout is now", pb.flags.bool("new_checkout", false));
});

// Wait for the values to be current before the first render, when that matters more than speed.
await pb.flags.refresh();
console.log(pb.flags.all());
stop();
```

The client starts on first use: the first read, listener or `refresh()` reads the values for whoever is signed in and joins the flags' change channels. The read goes from the browser straight to the project's address, which answers a page on any site. See [Overview](/docs/web/overview#calling-the-project-from-a-browser).

## Reading values

| Member | What it answers |
|---|---|
| `bool(key, fallback)` | A boolean flag's value, or `fallback` when there is none or it is not a boolean. |
| `string(key, fallback)` | A string flag's value, or `fallback`. |
| `number(key, fallback)` | A number flag's value (a finite one), or `fallback`. |
| `json<T>(key, fallback)` | An object flag's value as your type, or `fallback`. The shape is not checked. |
| `value(key)` | A flag's value, any JSON, or `undefined` when there is none yet. |
| `all()` | Every flag's value by key. |
| `source(key)` | Where a value came from: `system` (the flag's), `override` (the user's own), or `experiment` (an experiment's variant). |
| `version` | The version the values are current as of. |
| `onChange(listener)` | Calls `listener(keys)` with the keys whose values changed. Returns the unsubscribe. |
| `refresh()` | Brings the values up to date now. It resolves when they are. |

Every read answers at once, from what the client holds. Before the first read has come back, a reader the browser has seen before gets the values it had last time, and a new one gets the fallback. Give every read a fallback the app works with.

## A signed-in user's values

The values are one reader's: the signed-in user's, or, with no one signed in, this browser's. When someone signs in or out, the values held go (and a listener is told their keys), the new reader's are read, and the listener is told again. One reader's values are never read out to another, even for the moment the new ones take to arrive. A signed-in user's values follow the order below: their own values first, then their experiment's variant, then the flag's conditions.

## What a value is resolved from

Every read is resolved by the project for its reader, in this order:

1. **The user's own value**, when a signed-in user has one. A server gives users their values with the secret key (see [Flags in your backend](/docs/backend/flags#users-own-values)).
2. **The variant of an experiment** running on the flag, when the reader is one of its people.
3. **The flag's first condition that matches.** Conditions read what the client says about itself, the share of users a percentile picks (signed-in users only), the country of the address the request came from, the server's clock, and the analytics audiences the reader is in when they allowed personalization ([Consent](/docs/web/consent)).
4. **The flag's default.**

What the client says about itself, with every read:

| Header | Sent as | Read as |
|---|---|---|
| `X-Platform` | `web` | `client.platform` |
| `X-Palbase-Client-Version` | `createClient`'s `appVersion`, when given | `client.app_version` |
| `Accept-Language` | `createClient`'s `language`, or the browser's own | `client.locale`, its first language |
| `X-Palbase-Installation` | `pb.installation.id` | Counted toward which versions of your app are in use. |
| `X-Palbase-Installation-Secret` | The install's secret, kept in the browser, with no one signed in | Proves the install, so audiences and experiments can place a reader who is not signed in. |

The country is the one of the address the request came from: the user's own, because the browser calls the project directly.

A value is any JSON the flag's type allows: a boolean, a number, a string (one of the choices a string flag declares) or an object.

## Experiments

A value an experiment gave says so: `source(key)` is `experiment`. When the app reads such a flag by its key (`bool`, `string`, `number`, `json` or `value`), the client records the analytics event `$flag_exposure` with `{ flag, experiment, variant }`, once per analytics session for each flag and experiment, and only while the person allows analytics. That event is what an experiment's results count. `all()` records none, so read a flag in an experiment by its key where the person sees it.

## Keeping up to date

The client keeps the values current by itself. The project announces every change on two realtime channels, which the client joins on the project's socket:

| Channel | Who may join | What it says |
|---|---|---|
| `flags:<ref>` | Anyone reading the project's flags, with no one signed in too | The project's flags changed. |
| `flags:<ref>:<user_id>` | That user only | That user's own values changed. |

Told of a newer version, the client asks for what changed since the one it holds (`GET /flags/delta`). When the delta can no longer bring its values up to date (the reader's context, country or audiences changed, a time condition turned, or the deletions it would need are older than the 30 days kept), the project answers `410`, and the client reads a whole snapshot instead (`GET /flags/snapshot`, sent with the `ETag` of what it holds, answered `304` when nothing changed). A channel the project refuses, with realtime off, still leaves the reads: `refresh()` brings the values up to date.

Every read a client makes — `GET /flags`, a snapshot or a delta, a `304` among them — is metered against the project's flag reads.

## The calls under it

Every client call of the flags module is also on `pb.flags.api`, typed, through the client's session:

| Call | Method | What it answers |
|---|---|---|
| `GET /flags/snapshot` | `api.getSnapshot()` | `{ values, sources, experiments?, sync_version, context_hash, fetched_at }`, `304` with `If-None-Match` when unchanged. |
| `GET /flags/delta?since=<sync_version>` | `api.getDelta({ query: { since } })` | `{ ops: [{ op: "put" \| "delete", key, value?, source, experiment?, version }], sync_version }`, `304` when nothing changed, `410` when a snapshot is needed. |
| `GET /flags` | `api.getValues()` | Every flag's value for this reader, alone. |

An app that reads flags with `pb.flags` makes none of them itself.

## Errors

A read never throws: it answers the fallback. `refresh()` rejects with a `PalbaseError` when the read it waits for fails:

| Status | When |
|---|---|
| 401 | A key of another project, or a token that is not valid. |
| 429 | The project's request rate, or its flag reads for the period, are used up. `Retry-After` says when to try again. |
| 503 | The platform could not answer now. The read is made again with the next change, or the next `refresh()`. |

## Related

- [Flags in your backend](/docs/backend/flags) — defining flags and giving users their own values
- [Realtime](/docs/web/realtime) — the socket the change notices travel on
- [Consent](/docs/web/consent) — personalization, which audience conditions need
- [Overview](/docs/web/overview) — the client's options, `appVersion` and `language`



<!-- ===== web/realtime ===== -->

# Realtime

`pb.socket` is the project's one realtime connection, shared by every channel the page is on. It opens the first time a channel is joined and never before, so a page that only signs in or reads flags opens none. On it, a channel delivers what is published to it: broadcasts, and the channel's shared state when the channel has one. The client listens, and broadcasts on a channel declared to let it. The project's server broadcasts and writes state with the secret key.

> **Note:** Your own backend's realtime channels are its [gateways](/docs/web/gateways), joined through the module `palbase apps:sync` writes: typed events, and messages the backend answers with an ack. This page is the socket under them, and the channels a server declares by name.

## Quick example

```ts
// src/lib/palbase.ts
import { createClient } from "palbase/web";

export const pb = createClient({ url: "https://k3xq81w4m.palbase.studio", publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5" });
```

```ts
// src/room.ts
import { pb } from "./lib/palbase";

const room = pb.socket.channel("room:42");

const stop = room.on("broadcast", (frame) => {
  // { type: "broadcast", event, payload }
  console.log(frame.event, frame.payload);
});

try {
  await room.join();
} catch (e) {
  // The server's reason: not declared, not yours, too many channels, …
  console.error(e instanceof Error ? e.message : e, room.refusal);
}

// later:
stop();
room.leave();
```

And the backend that publishes to it:

```ts
// server/src/rooms/rooms.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class RoomsService {
  /** Every subscriber of room:<id> hears it. */
  async announce(roomId: string, text: string): Promise<void> {
    await Palbase.realtime.broadcast({
      body: { messages: [{ topic: `room:${roomId}`, event: "message", payload: { text } }] },
    });
  }
}
```

## Channels

`pb.socket.channel(name)` returns the channel of that name, the same object each time it is asked for. A channel is joined once however many listeners it has.

| Member | What it does |
|---|---|
| `join()` | Joins and resolves once the server took it. Rejects with the server's reason when it did not. |
| `leave()` | Leaves the channel and forgets it: a later `channel(name)` is a new one. |
| `on(event, listener)` | Listens to one event. Returns the unsubscribe. A listener that throws does not take the socket down. |
| `push(event, payload)` | Sends one event on the joined channel and resolves with what became of it, `{ status, response }`: `ok`, `error` with the server's `reason`, or `timeout` (`no reply`) when nothing answered in ten seconds. It never rejects. On a channel that is not joined it sends nothing and resolves `error`, `not joined`. |
| `onClosed(listener)` | Told when what was joined ends for good: a sign-out, or another user's sign-in. Not a drop, after which the channel is joined again. Returns the unsubscribe. |
| `state` | `closed`, `joining`, `joined` or `refused`. |
| `refusal` | Why the server refused the last join, when it did. |

The events a channel delivers:

| Event | Payload |
|---|---|
| `broadcast` | `{ type: "broadcast", event, payload }`: one published event. A broadcast reaches every subscriber but the one that sent it. |
| `state_snapshot` | `{ seq, entries }`: the channel's whole state, on join. Each entry is `{ v, life }`. |
| `state_diff` | `{ from_seq, seq, set, del }`: what changed since `from_seq`. A client holding exactly `from_seq` applies it. |

State is a keyed map per channel that outlives the connections reading it. A server writes it with `Palbase.realtime.writeState`, and a channel declared with `state_read` hands it to its subscribers. A `durable` entry stays until it is removed. An `ephemeral` one is its writer's presence, gone when the writer leaves.

Names are `:`-separated segments, 255 bytes at most. On the wire each carries a `realtime:` prefix, and the client adds it for you.

## Who may join

A channel name is a string a client chooses, so proving who you are says nothing about which channels are yours. The project's server **declares** its channels (`PUT /realtime/channels` with the secret key, or `Palbase.realtime.putChannels`), and a channel no declaration matches belongs to no one:

| Declared `kind` | Who joins |
|---|---|
| `owner` | The pattern's one `{name}` segment is the joining user: `user:{uid}` is joined by that user alone, who may do everything on it. |
| `public` | Any signed-in user of the project, with the rights the declaration gives: `publish`, `state_read`, `state_write`. |

Patterns match in their order, the first one deciding. A declared channel is joined only by a signed-in user, whose access token travels in each join. See [Channels](/docs/backend/channels).

Some namespaces are the platform's, and no declaration can claim them:

| Channel | Who joins | What it carries |
|---|---|---|
| `flags:<ref>` | Anyone, signed in or not | The project's flags changed. See [Flags](/docs/web/flags). |
| `flags:<ref>:<user_id>` | That user | Their own flag values changed. |
| `roles:<ref>:<user_id>` | That user | Their permissions, as state. |

A refused join rejects with the server's reason: `unauthorized`, `forbidden`, `invalid_topic`, `rate_limited`, `too_many_channels`, `state_budget` or `unavailable`. Only `unavailable` is worth trying again. A user who is turned away mid-connection, because a declaration changed or their session ended, gets the channel closed under them (`state` becomes `closed`). Ask again and the server answers on its merits.

A client broadcasts on a channel declared with `publish`:

```ts
// src/typing.ts
import { pb } from "./lib/palbase";

export async function sayTyping(roomId: string): Promise<void> {
  const room = pb.socket.channel(`room:${roomId}`);
  await room.join();
  // Every other subscriber hears { type: "broadcast", event: "typing", payload }; the sender does not.
  const reply = await room.push("broadcast", { type: "broadcast", event: "typing", payload: { typing: true } });
  // A refusal is answered (not declared with publish, over the rate); a broadcast the server took is answered by no one.
  if (reply.status === "error") console.warn("not sent:", reply.response.reason);
}
```

A broadcast the server took is not answered, so its `push` resolves `timeout` after ten seconds: do not hold the page on it. The channel's state is the server's to write. What a client must not be able to say, publish from your backend, which decides what reaches a channel.

## One socket, one user

The socket opens at `wss://<url's host>/realtime/v1/websocket` with the publishable key in its `apikey` parameter, because a browser cannot set a header on a WebSocket. Who the client is, is the access token each join carries. When the session is refreshed, the new token goes to every joined channel without leaving it.

The socket is one person's. When someone signs in, signs out, or the session expires, the client closes it, and every channel with it. Join again for the user who is there now:

```ts
// src/rejoin.ts
import { pb } from "./lib/palbase";

async function joinMine(): Promise<void> {
  const session = await pb.auth.currentSession();
  if (!session) return;
  const mine = pb.socket.channel(`user:${session.userId}`);
  mine.on("broadcast", (frame) => console.log("for me:", frame.event, frame.payload));
  await mine.join();
}

pb.auth.onAuthStateChange((event) => {
  if (event === "SIGNED_IN") void joinMine();
});
await joinMine();
```

## When the connection drops

The socket sends a heartbeat every 25 seconds. One that goes unanswered closes the socket, because a network that went away without a close leaves a socket half-open. A socket that drops is opened again after 0.5, 1, 2, 5, 10, then every 30 seconds, each pause jittered by ±20%, and every channel that was joined is joined again. A broadcast published while the socket was down is not delivered: broadcasts are delivered at most once. A channel's state comes back whole with the snapshot of the new join. `pb.socket.reconnects` counts the reopens, for your own diagnostics.

`pb.socket.disconnect()` closes it for good. The next `join()` opens a new one.

## Where the socket opens

The socket's address is built from the client's `url`: `wss://k3xq81w4m.palbase.studio/realtime/v1/websocket`, at the project's address, with the publishable key in its query. A WebSocket is not preflighted, and the project's address takes a socket from a page on any site, so the browser opens it there directly. See [Overview](/docs/web/overview#calling-the-project-from-a-browser).

## Limits

The project holds its clients to limits the platform sets and the project may lower (`PUT /realtime/limits` from a server): connections open at once, broadcasts and state writes per second, joins per second, channels per connection. A frame over 1 MiB closes the socket. A project over its connection limit, or whose realtime quota is used up, is refused a new socket.

## Related

- [Gateways](/docs/web/gateways) — your backend's channels, typed, with messages and acks
- [Channels](/docs/backend/channels) — declaring who may join what
- [Realtime in your backend](/docs/backend/realtime) — broadcasting and writing state
- [Flags](/docs/web/flags) — the change notices on `flags:<ref>`
- [Auth](/docs/web/auth) — the session the socket belongs to
- [Overview](/docs/web/overview) — the client, and calling the project from a browser



<!-- ===== web/messaging ===== -->

# Messaging

`pb.messaging` is the signed-in person's conversations in the browser: their list, each conversation's timeline and its threads, kept in IndexedDB between visits and current over the project's socket. An app subscribes to what it draws and writes; it opens no socket, appends nothing and syncs nothing itself. What the module is — history, encryption, files, timers, moderation, prices — is [Messaging](/docs/messaging/overview).

## Quick example

```ts
// src/lib/palbase.ts
import { createClient } from "palbase/web";

export const pb = createClient({
  url: "https://k3xq81w4m.palbase.studio",
  publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5",
  // What the browser keeps of the person's conversations when they sign out: dropped unless true.
  messaging: { keepOnSignOut: false },
});
```

```ts
// src/inbox.ts
import { pb } from "./lib/palbase";

// The person's conversations, the latest first: drawn from the device at once, then kept current.
const list = pb.messaging.conversations();
const stopList = list.subscribe(() => {
  const { items, unread, synced } = list.state;
  console.log(`${unread} unread in ${items.length} conversations`, synced ? "" : "(catching up)");
});

// The direct conversation with someone: the one there is, or a new one (it shows to them with its first message).
const chat = await pb.messaging.direct("usr_01a1684c796e7394aa8ec75d893a8fe2");
const stopChat = chat.subscribe(() => {
  for (const entry of chat.state.entries) {
    if (entry.kind === "message") console.log(entry.message.sender_id, entry.message.text);
    else console.log("sending…", entry.item.request.text, entry.item.state);
  }
});

// Drawn at once, sent now or when the network is back — once.
await chat.send("Hi!");
await chat.markRead();

stopChat();
stopList();
```

## Conversations

| Call | What it is |
|---|---|
| `conversations()` | The person's conversations, the latest first: `items`, `unread` across them, and `synced` once the device's copy caught up |
| `conversation(id)` | One conversation: `conversation`, `entries` (its timeline, the oldest first, then what is on its way), `members`, `typing`, `hasEarlier` |
| `direct(userId)` | The direct conversation with someone |
| `group({ title, memberIds, description, photo, settings })` | A new group, the person its owner; `notAdded` names whom the project's hook kept out |
| `thread(conversationId, rootId)` | A message's thread: `root`, `entries`, `thread` (its count, its last answer, who answered, its unread count) |
| `threads()` | The threads the person follows |
| `scheduled()` | The person's messages for later |

Each view (`conversations()`, `conversation(id)`, `thread(…)`, `scheduled()`) is an `Observed`: `state` now and `subscribe(listener)`, which returns the call that stops it. It reads the device's copy while subscribed and as long as the person stays the same; when another person signs in, it reads theirs. `loadEarlier()` reads the page before the oldest message drawn.

```ts
// src/team.ts
import { pb } from "./lib/palbase";

const team = await pb.messaging.group({ title: "Design", memberIds: ["usr_01a1684c796e7394aa8ec75d893a8fe2"] });
const view = team.conversation;
view.subscribe(() => console.log(view.state.members.length, "members,", view.state.typing.length, "typing"));
if (view.state.hasEarlier) await view.loadEarlier();
await pb.messaging.update(view.id, { title: "Design team" });
```

## Writing

`send(conversationId, input)` — or a view's own `send(input)` — takes text or what a message carries:

```ts
// src/compose.ts
import { pb } from "./lib/palbase";

const conversationId = "0199f0c2-6a3e-7b1d-9f4e-2d1c8b7a6e50";
const input = document.querySelector<HTMLInputElement>("input[type=file]")!;
const photo = input.files![0];

// Answers a message inline, mentions someone, carries a file encrypted on this device before it is uploaded.
await pb.messaging.send(conversationId, {
  text: "Here it is, @bob",
  replyTo: "0199f0c2-7c11-7e2f-8a3b-4c5d6e7f8091",
  files: [{ data: photo, contentType: photo.type, name: photo.name }],
});

// In a thread, shown in the conversation too; gone a day after everyone read it.
await pb.messaging.send(conversationId, { text: "Agreed", threadId: "0199f0c2-7c11-7e2f-8a3b-4c5d6e7f8091", alsoInConversation: true, expiresIn: 86_400, expiresFrom: "read" });

// Seen once: its photo opens for ten seconds, once.
await pb.messaging.send(conversationId, { files: [{ data: photo, contentType: photo.type }], viewOnce: { limit: 1, seconds: 10 } });

// Sent tomorrow at nine by the server, the browser closed or not: scheduled() lists it until then.
const nine = new Date();
nine.setDate(nine.getDate() + 1);
nine.setHours(9, 0, 0, 0);
await pb.messaging.send(conversationId, { text: "Good morning", sendAt: nine });
```

A message waits in the outbox while the browser is offline or the server is away and goes once it can, once; an entry of kind `pending` is one on its way. `edit`, `remove` (for `everyone` or `me`), `react` and `unreact`, `markRead`, `typing`, `cancelScheduled` and `editScheduled` change what was said. `open(message, attachmentId)` downloads a file and decrypts it in the browser; a message seen once gives its files by `viewOnce(message)` alone, and the app holds them — the device keeps none.

## A message while the app is open

A push for a message is not shown as the browser's notification while a page of the app is in front: the service worker leaves it to the page. `onIncoming` tells the page a new message from someone else as it arrives, so it draws its own banner — skip the conversation already on the screen:

```ts
// src/banner.ts
import type { Message } from "palbase/web";
import { pb } from "./lib/palbase";

let open: string | null = null; // the conversation on the screen

const stop = pb.messaging.onIncoming((message: Message) => {
  if (message.conversation_id === open) return;
  console.log("banner:", message.sender_id, message.text ?? "sent a file");
});
stop();
```

## The person

`me()` and `updateMe({ name, image, read_receipts, show_last_seen, default_timer_seconds })` are the person's own profile and settings; `profiles(userIds)` others' names and pictures. `block(userId)`, `unblock(userId)` and `report({ … })` are theirs to use. `notifications(conversationId, { notify_level, muted_until })` mutes a conversation, or keeps only its mentions.

## A deleted group

When a group's owner or an admin deletes it — or its last member leaves — it goes from everyone's `conversations()` at once, and those who were in it can still report it for 14 days ([Messaging](/docs/messaging/overview#moderation)). `deletedGroups()` lists them while they can, the latest to stop first: `state.items` are `{ id, title, deletedBy, reportableUntil }`, and one goes at its `reportableUntil`. `report` names it by its id with no message; the last 30 messages the person saw in it go with the report. A group the project's server deleted is not among them.

```ts
// src/deleted.ts
import { pb } from "./lib/palbase";

const deleted = pb.messaging.deletedGroups();
const stop = deleted.subscribe(() => {
  for (const g of deleted.state.items) console.log(g.title ?? "a group", "reportable until", g.reportableUntil);
});

const [group] = deleted.state.items;
if (group) await pb.messaging.report({ conversation_id: group.id, reason: "harassment", user_id: group.deletedBy ?? undefined });
stop();
```

The title is the one the device had; it is null when the device no longer had the group as the word came — on the deleter's own device now and then.

## Vanish mode and screenshots

A direct conversation in vanish mode (`update(id, { settings: { vanish: true } })`) drops what the person read when they leave it: call `close(conversationId)` as its screen goes. A browser cannot know of a screenshot; the phone apps tell the others ([Messaging](/docs/messaging/overview#screenshots)).

## Signing out

When the person signs out, what the browser kept of their conversations is dropped and nothing of theirs is followed — unless `keepOnSignOut` is true, when it is theirs again the next time they sign in here, and no one else who signs in reads it. `storage` replaces where it is kept (IndexedDB, unless given).



<!-- ===== web/gateways ===== -->

# Gateways

Your backend's [gateways](/docs/backend/gateways) are its realtime channels, and an app joins them through the module `palbase apps:sync` writes for it. `pb.<backend>.join(Gateway, params)` resolves once the backend let the user in, with a handle: the gateway's events arrive on it, typed, and its messages go out through it, each answered with the backend's ack. The app writes no channel name, event name or payload type of its own, and a gateway that carries a chat holds the chat's state for the app to render.

## Quick example

```ts
// src/room.ts
import { GatewayError } from "palbase/web";
import { pb, RoomGateway } from "../palbase/shop-web";

// Rejects with a GatewayError (unauthorized) when the backend does not let this user in.
const room = await pb.backend.join(RoomGateway, { roomId: "42" });

room.on("welcome", (w) => console.log(`${w.members} in the room`));
room.on("message", (m) => console.log(`${m.from}: ${m.text}`));

try {
  // Resolves with the ack the backend's @Subscribe returned.
  const { id } = await room.send("say", { text: "hello" });
  console.log("taken as", id);
} catch (e) {
  // The backend's own word (no_commands), or the platform's: forbidden, unavailable, …
  if (e instanceof GatewayError) console.error("not taken:", e.reason);
}

// When the view goes:
room.leave();
```

`RoomGateway` is the backend's class of that name, as the generated module describes it: its pattern `room:{roomId}`, the events it sends and the messages it takes. See the backend's side in [Gateways](/docs/backend/gateways#quick-example).

## The generated module

`palbase apps:sync <app>` writes the checkout's apps their settings and their backends' clients under `palbase/`, from what the project serves now ([The generated module](/docs/web/backend-calls#the-generated-module)). For a web app it writes `palbase/<app>.ts`, which exports the app's `pb`, and a module for each backend the app reaches. With one backend, `palbase/<app>.ts` exports that backend's types and gateways too; with several, each backend's are in `palbase/palbe/<machine>.ts`. Each gateway is a descriptor named by its class. Run the sync again when the backend changes a gateway, and a payload the backend no longer takes is a compile error in the app.

`pb.<backend>` is the machine's name camelCased: `pb.backend` for the machine named `backend`, `pb.shopApi` for `shop-api`. `palbase apps:sync --as shop-api=shop` names it otherwise.

What the app imports from it, cut to the gateways this page uses:

```ts
// palbase/shop-web.ts
// Code generated by palbase apps:sync — DO NOT EDIT. (Cut to this page's gateways.)
import { createClient, type BackendBase, type PalbaseClient } from "palbase/web";
import { __registerBackend } from "palbase/web/palbe";

export interface OrderUpdatesStatusEvent {
  orderId: string;
  status: "paid" | "packed" | "shipped" | "delivered";
}

export type OrderUpdatesEvent =
  | { event: "status"; payload: OrderUpdatesStatusEvent };

export interface OrderUpdatesParams { userId: string }
export const OrderUpdates = {
  name: "OrderUpdates",
  pattern: "orders:{userId}",
  params: ["userId"] as const,
  durable: true,
  events: ["status"] as const,
  messages: [] as const,
  send: {} as {},
  reply: {} as {},
  event: {} as OrderUpdatesEvent,
} as const;

export interface RoomGatewayMessageEvent {
  from: string;
  id: string;
  text: string;
}

export interface RoomGatewayWelcomeEvent {
  members: number;
}

export interface RoomGatewaySayMessage {
  text: string;
}

export interface RoomGatewaySayReply {
  id: string;
}

export type RoomGatewayEvent =
  | { event: "message"; payload: RoomGatewayMessageEvent }
  | { event: "welcome"; payload: RoomGatewayWelcomeEvent };

export interface RoomGatewayParams { roomId: string }
export const RoomGateway = {
  name: "RoomGateway",
  pattern: "room:{roomId}",
  params: ["roomId"] as const,
  durable: false,
  events: ["message", "welcome"] as const,
  messages: ["say"] as const,
  send: {} as { say: RoomGatewaySayMessage },
  reply: {} as { say: RoomGatewaySayReply },
  event: {} as RoomGatewayEvent,
} as const;

export interface SupportGatewayChatEvent {
  data: Record<string, unknown>;
  id?: number;
  type: string;
}

export interface SupportGatewayAnswerMessage {
  callId: string;
  output: string;
}

export interface SupportGatewayDecideMessage {
  approvalId: string;
  approve: boolean;
  reason?: string;
}

export interface SupportGatewaySayMessage {
  clientId?: string;
  delivery?: "next" | "now";
  text: string;
}

export interface SupportGatewaySayReply {
  clientId: string;
}

export type SupportGatewayStopMessage = Record<string, unknown>;

export interface SupportGatewayStopReply {
  stopped: string | null;
}

export type SupportGatewayEvent =
  | { event: "chat"; payload: SupportGatewayChatEvent };

export interface SupportGatewayParams { chatId: string }
export const SupportGateway = {
  name: "SupportGateway",
  pattern: "support:{chatId}",
  params: ["chatId"] as const,
  durable: true,
  chat: true,
  events: ["chat"] as const,
  messages: ["answer", "decide", "say", "stop"] as const,
  send: {} as { answer: SupportGatewayAnswerMessage; decide: SupportGatewayDecideMessage; say: SupportGatewaySayMessage; stop: SupportGatewayStopMessage },
  reply: {} as { answer: unknown; decide: unknown; say: SupportGatewaySayReply; stop: SupportGatewayStopReply },
  event: {} as SupportGatewayEvent,
} as const;

// The backend, for the clients of this environment's project alone. Its routes are in the tree too: see Calling Your Backend.
__registerBackend("https://k3xq81w4m.palbase.studio", "backend", "backend", "https://k3xq81w4m.app.palbase.studio", {});

export interface Backend extends BackendBase {}

export const settings = { url: "https://k3xq81w4m.palbase.studio", publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5" } as const;

/** The app's client: the project's modules (pb.auth, …) and its backend, pb.backend. The module makes it on first use (connect). */
export const pb = createClient({ url: settings.url, publishableKey: settings.publishableKey }) as PalbaseClient & { backend: Backend };
```

`send`, `reply` and `event` carry types alone: a `send` is checked against the message's shape and resolves with its ack's, and an event handler is typed by the event. The lists of names are there for a JavaScript caller, which has no compiler: a message or an event the gateway does not declare throws a `TypeError` before anything is sent.

`palbase apps:sync` writes an iOS or Android app in the checkout the same gateways: `pb.backend.join(…)` in Swift and in Kotlin, and in both a chat gateway's handle holds `handle.chat` ([iOS](/docs/ios/gateways), [Android](/docs/android/gateways)).

## Joining

`join(Gateway, params, options?)` takes the gateway's descriptor and a value for each of its pattern's `{param}`s, each one segment of the channel's name: empty, or holding a `:`, it throws a `TypeError`. It opens the project's socket if it is not open, and resolves once the backend let the signed-in user in.

| Member of the handle | What it does |
|---|---|
| `on(event, handler)` | Listens to one event, its payload typed. Returns the function that stops it. |
| `on(handler)` | Listens to every event the gateway declares, as a union to `switch` over. |
| `off(subscription)` | Stops one listener, as calling it does. |
| `send(message, payload)` | Sends one message and waits for the backend to take it: its ack, or a `GatewayError`. |
| `leave()` | Drops the handle's listeners and lets go of the channel. |
| `topic` | The channel: `room:42`. |
| `seq` | A durable gateway's number of the last event the handle was sent. |
| `chat` | A chat gateway's chat. See [Chat gateways](#chat-gateways). |

Hold a handle for as long as its view is on screen, and leave it when the view goes: a gateway with members is one its backend still runs for (what its `@OnFirst` started stops when the last member leaves). Two handles of the same channel share one membership, and the channel is left with the last of them.

Only a signed-in user joins: the access token the socket carries is who they are. The socket is one person's, and it closes when someone signs in or out ([Realtime](/docs/web/realtime#one-socket-one-user)).

## Events

```ts
// src/room-feed.ts
import { pb, RoomGateway, type RoomGatewayEvent } from "../palbase/shop-web";

export async function follow(roomId: string, render: (line: string) => void): Promise<() => void> {
  const room = await pb.backend.join(RoomGateway, { roomId });
  room.on((e: RoomGatewayEvent) => {
    switch (e.event) {
      case "message":
        render(`${e.payload.from}: ${e.payload.text}`);
        break;
      case "welcome":
        render(`${e.payload.members} in the room`);
        break;
    }
  });
  return () => room.leave();
}
```

An event the generated module does not know, from a backend that moved ahead of it, is not delivered. A listener that throws does not take the socket down.

## Messages and acks

`send` resolves with what the backend's `@Subscribe` returned, as its `reply` schema types it, or with nothing when it returned nothing. It rejects with a `GatewayError` whose `reason` says why the message was not taken:

| `reason` | What it means |
|---|---|
| The backend's own word | Its method threw `GatewayRefusal("…")`: `no_commands`, `not_your_turn`, `too_many_messages`. Act on it. |
| `handler_failed` | The method threw something else. The details are in the backend's log. |
| `reply_too_large` | The ack was past 64 KiB. |
| The schema's issues | The payload did not fit the message's schema, said as text (`text: Too small: …`). |
| `forbidden` | The user may only listen on this channel, or the platform refused with no reason given. |
| `rate_limited` | Past the project's events per second. |
| `unavailable` | The backend could not be asked just then. Worth trying again. |
| `no reply`, `socket closed` | No answer came. The message may have been taken. |
| `not joined` | Nothing was sent: the handle was left, its socket closed for good, or the socket is being opened again. |

A join that is refused rejects with a `GatewayError` too: `unauthorized` when the backend did not let the user in (final), `unavailable` when it could not be asked (worth trying again), and `rate_limited` or `too_many_channels` past the project's limits.

A message goes to the backend alone, never to the other members. They hear what the backend emits.

## Durable gateways

A [durable gateway](/docs/backend/gateways#durable-gateways) keeps what it sends. A handle that joins one is sent what it keeps first, in order, then what comes after. `{ history: false }` asks for only what comes after the join:

```ts
// src/orders.ts
import { OrderUpdates, pb } from "../palbase/shop-web";

export async function watchOrders(userId: string, onStatus: (orderId: string, status: string) => void): Promise<() => void> {
  // Only what happens from now: the page reads the orders' current state from the backend's routes.
  const orders = await pb.backend.join(OrderUpdates, { userId }, { history: false });
  orders.on("status", (s) => onStatus(s.orderId, s.status));
  return () => orders.leave();
}
```

The channel's first handle decides: a second handle of the same channel gets the events from where it joins. `handle.seq` is the number of the last event the handle was sent. When the socket drops, the channel is joined again after that number: the handle is sent what it missed, in order, and nothing twice.

## When the connection drops

The socket reconnects by itself ([Realtime](/docs/web/realtime#when-the-connection-drops)), and every gateway that was joined is joined again with it. Meanwhile a `send` answers `not joined`. An event a gateway that is not durable sent while the socket was down is not delivered.

When the socket closes for good (a sign-out, or another user's sign-in) every handle on it ends: its listeners are dropped, and `send` answers `not joined`. Join again, as the user who is there now.

## Chat gateways

A gateway declared with `chat: true` carries a chat of the project's agents, which the platform writes into its channel ([AI](/docs/backend/ai#a-chat-in-an-app)). Its handle has `chat`, the chat's state folded from what the platform writes there: from the chat's start, since the channel keeps it, and then each change as it comes.

| Member of `handle.chat` | What it is |
|---|---|
| `state` | The chat now. The same object until something changes. |
| `subscribe(listener)` | Told each time the state changes, at most once a microtask. Returns the unsubscribe. |
| `for await (const state of handle.chat)` | The state now, then each change, until the gateway is left. |
| `hasOlder`, `loadOlder({ limit? })` | The channel keeps a day of the chat. `loadOlder` reads the page before what the state holds, with the member's own session, and folds it in; it resolves with `hasOlder`, `false` once a page reaches the chat's start. |

What `state` holds:

| Field | What it is |
|---|---|
| `items` | The conversation in order, each one of four types: `{ type: "message", message }`, `{ type: "response", response }`, `{ type: "goal", goal }` (a word of the chat's goal: set, changed, a turn of it begun, judged or checked, its status, cleared) and `{ type: "voice", voice }` (the chat's voice began or ended). A subagent's answer is a part of its parent's. |
| `messages` | Each member's (or the server's) message: `clientId`, `text`, `author` (`null`: the server), `authorName`, `status` (`pending` until the agent has it, then `delivered`, or `failed` with its `error`), `kind` (`text`, or `voice` for a line said in the chat's voice), `attachments` (its pictures and files), `metadata`, `createdAt`, and `mine`. |
| `responses` | Each answer, the subagents' too: `id`, `status` (`running`, `waiting`, `completed`, `failed`, `canceled`, `timed_out`, `budget_exceeded`), `end` and `error` once it ended, `text` so far, `parts`, `thinking` (the model's reasoning step by step, when the agent shows it), `goal` (the goal's turn it is, or `null`), `startedBy`, and `mine`. |
| `turn` | The last turn's state, and what it waits for: `approval`, `tool_output`, `subagents` or `message`. |
| `waiting` | What waits for the signed-in user: `approvals`, the tool calls of their own turns waiting for their yes, and `outputs`, their own turns' client tool calls waiting for their app's answer. Another member's turn is theirs. |
| `goal` | The chat's goal once one was set: `objective`, `status` (`active`, `paused`, `blocked`, `budget_limited`, `achieved`, or `cleared`), its stop code and reason, and its `events`. `null` without one. |
| `voice` | The chat's voice, the last that began in it, live or ended: `status` (`started`, `closed`), `mine`, `seconds` and `closeReason` once it closed. `null` without one. |
| `forkedFrom` | A fork's: `{ chatId, beforeMessage }`, the chat it was forked from. `null` for a chat of its own. |

An answer's `parts` are its pieces in order, each one of four types: `{ type: "text", text }`; `{ type: "tool", tool }`, a tool call; `{ type: "agent", agent }`, a subagent handed work (or refused it, `status: "denied"` with its `reason`); and `{ type: "thinking", thinking }`, a step's reasoning (`text`, or `unavailable: true` with the provider's `reason` when the agent shows its reasoning and the provider gave none). A render that leaves a type out leaves that piece of the conversation out.

`mine` is the signed-in user's: a message they wrote, an answer to a turn they began. A tool call (a `tool` part, or one of `waiting`) has `call_id`, `name`, `status`, `input`, `output` and, while it waits for a yes, `approval_id`. Its `output` is the answer's last 16 KiB: `omittedBytes` says how much came before it, and `pb.chatToolCall(chatId, callId)` reads the whole answer.

What the member does in the chat goes through the gateway's own messages, and the backend does it as them: `say`, `decide` (an approval's yes or no), `answer` (a client tool's output) and `stop`, in the backend of [AI](/docs/backend/ai#a-chat-in-an-app). A refusal is its reason: `not_your_turn`, `too_many_messages`, `history_full`.

A chat in React:

```tsx
// src/support/SupportChat.tsx
import { useEffect, useState, useSyncExternalStore } from "react";
import { GatewayError, type ChatItem, type ChatPart, type ChatResponse, type ChatState, type GatewayChat } from "palbase/web";
import { pb, SupportGateway } from "../../palbase/shop-web";

const joinSupport = (chatId: string) => pb.backend.join(SupportGateway, { chatId });
type Support = Awaited<ReturnType<typeof joinSupport>>;

function useChat(chat: GatewayChat): ChatState {
  return useSyncExternalStore((changed) => chat.subscribe(changed), () => chat.state);
}

export function SupportChat({ chatId }: { chatId: string }) {
  const [support, setSupport] = useState<Support | null>(null);
  const [refused, setRefused] = useState<string | null>(null);
  useEffect(() => {
    let gone = false;
    let held: Support | undefined;
    joinSupport(chatId).then(
      (h) => (gone ? h.leave() : setSupport((held = h))),
      (e: unknown) => setRefused(e instanceof GatewayError ? e.reason : "unavailable"),
    );
    return () => {
      gone = true;
      held?.leave();
    };
  }, [chatId]);
  if (refused) return <p>The chat did not open: {refused}</p>;
  return support ? <Conversation support={support} /> : <p>Opening…</p>;
}

function Conversation({ support }: { support: Support }) {
  const state = useChat(support.chat);
  const [draft, setDraft] = useState("");
  const [problem, setProblem] = useState<string | null>(null);
  const act = (work: Promise<unknown>) => work.catch((e: unknown) => setProblem(e instanceof GatewayError ? e.reason : "unavailable"));
  return (
    <section>
      {support.chat.hasOlder && <button onClick={() => void support.chat.loadOlder()}>Earlier messages</button>}
      {state.goal && <p className="goal">Goal: {state.goal.objective} ({state.goal.status})</p>}
      {state.items.map((item, i) => <Item key={keyOf(item, i)} item={item} />)}
      {state.waiting.approvals.map((call) => {
        const approvalId = call.approval_id;
        return approvalId ? (
          <p key={call.call_id}>
            The assistant asks to run {call.name}.
            <button onClick={() => act(support.send("decide", { approvalId, approve: true }))}>Allow</button>
            <button onClick={() => act(support.send("decide", { approvalId, approve: false, reason: "Not now." }))}>Deny</button>
          </p>
        ) : null;
      })}
      {problem && <p role="alert">{problem}</p>}
      <form
        onSubmit={(e) => {
          e.preventDefault();
          setProblem(null);
          void act(support.send("say", { text: draft }).then(() => setDraft("")));
        }}
      >
        <input value={draft} onChange={(e) => setDraft(e.target.value)} />
        <button type="submit">Send</button>
        <button type="button" onClick={() => act(support.send("stop", {}))}>Stop</button>
      </form>
    </section>
  );
}

function keyOf(item: ChatItem, i: number): string {
  switch (item.type) {
    case "message":
      return `m:${item.message.clientId}`;
    case "response":
      return `r:${item.response.id}`;
    case "goal":
      return `g:${item.goal.seq}:${i}`;
    case "voice":
      return `v:${item.voice.voice_id}:${item.voice.status}`;
  }
}

function Item({ item }: { item: ChatItem }) {
  switch (item.type) {
    case "message": {
      const m = item.message;
      return (
        <p className={m.mine ? "mine" : "theirs"}>
          <b>{m.authorName || "Support"}</b> {m.kind === "voice" ? "(said) " : ""}
          {m.text}
          {m.attachments.map((a) => <small key={a.position}> [{a.name}]</small>)}
          {m.status === "pending" ? " …" : m.status === "failed" ? ` (not delivered: ${m.error ?? "failed"})` : ""}
        </p>
      );
    }
    case "response":
      return <Answer response={item.response} />;
    case "goal":
      return <small className="goal">Goal: {item.goal.kind}{item.goal.goal ? `, ${item.goal.goal.status}` : ""}</small>;
    case "voice":
      return <small>{item.voice.status === "started" ? "A voice call began" : `The voice call ended after ${item.voice.seconds ?? 0} s`}</small>;
  }
}

function Part({ part }: { part: ChatPart }) {
  switch (part.type) {
    case "text":
      return <p>{part.text}</p>;
    case "thinking":
      return part.thinking.unavailable ? (
        <small>No reasoning shown: {part.thinking.reason ?? "the provider gave none"}</small>
      ) : (
        <details>
          <summary>Thinking</summary>
          {part.thinking.text}
        </details>
      );
    case "tool":
      return <small>{part.tool.name}: {part.tool.status}</small>;
    case "agent":
      return <small>{part.agent.name}: {part.agent.status === "denied" ? `refused (${part.agent.reason ?? ""})` : "working"}</small>;
  }
}

function Answer({ response }: { response: ChatResponse }) {
  return (
    <div className="answer">
      {response.parts.map((part, i) => <Part key={i} part={part} />)}
      {response.end === "budget_exceeded" && <small>This answer reached its budget.</small>}
      {response.end === "failed" && <small>This answer failed.</small>}
    </div>
  );
}
```

A client tool's call waits in `state.waiting.outputs` until the app answers it, once:

```ts
// src/support/pick-city.ts
import type { ChatState } from "palbase/web";
import { pb, SupportGateway } from "../../palbase/shop-web";

export async function answerCities(chatId: string, pick: (reason: string) => Promise<string>): Promise<() => void> {
  const support = await pb.backend.join(SupportGateway, { chatId });
  const answering = new Set<string>();
  const stop = support.chat.subscribe((state: ChatState) => {
    for (const call of state.waiting.outputs) {
      if (call.name !== "pick_city" || answering.has(call.call_id)) continue;
      answering.add(call.call_id);
      const { reason } = call.input as { reason: string };
      void pick(reason).then((city) => support.send("answer", { callId: call.call_id, output: city }));
    }
  });
  return () => {
    stop();
    support.leave();
  };
}
```

## Related

- [Gateways](/docs/backend/gateways): declaring one in your backend
- [AI](/docs/backend/ai): the chats a chat gateway carries
- [Realtime](/docs/web/realtime): the project's one socket, and how it reconnects
- [Auth](/docs/web/auth): the user a gateway lets in



<!-- ===== web/analytics ===== -->

# Analytics

`pb.analytics` sends the project's analytics module what the app's people do: the events it captures, page views, and what it knows of the person. It holds events and sends them together, a few seconds apart or twenty at a time, and a page that closes sends what it holds as it goes. With the `analytics` option of `createClient` it also records the browser's own measures: a page view per address, web vitals and the page's request timings. Nothing is collected that the person has not allowed: events, page views and person properties go only with the `analytics` key granted, the browser's timings only with `performance` ([Consent](/docs/web/consent)). What the project reads back (summaries, event lists, funnels, retention, people) is the secret key's, and Studio's Analytics screens show it.

## Quick example

```ts
// src/lib/palbase.ts
import { createClient } from "palbase/web";

export const pb = createClient({
  url: "https://k3xq81w4m.palbase.studio",
  publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5",
  // Page views, web vitals and request timings, recorded by the client; the app's version kept with every event.
  analytics: { appVersion: "2.4.1" },
  // Collected before the person chooses. Where the law asks first, start them denied and ask: see Consent.
  consent: { start: { analytics: "granted", performance: "granted" } },
});
```

```ts
// src/checkout.ts
import { pb } from "./lib/palbase";

pb.analytics.capture("checkout_started", { plan: "pro", items: 3 });

// What is known of the person: the signed-in user, or this browser's anonymous visitor.
await pb.analytics.people.set({ plan: "pro" });
await pb.analytics.people.setOnce({ first_plan: "pro" });
await pb.analytics.people.add({ checkouts: 1 });

// A view the address does not show (a dialog, a step of a wizard).
pb.analytics.page({ title: "Checkout: payment" });
```

The calls go from the browser straight to the project's address, which answers a page on any site. See [Overview](/docs/web/overview#calling-the-project-from-a-browser).

## `pb.analytics`

| Member | What it does |
|---|---|
| `capture(event, properties?)` | Records an event: a name (a letter or `$`, then letters, digits and `_.:-$`, 64 at most) and its properties. |
| `page({ url?, title?, referrer?, properties? })` | Records a `$pageview`: the page's address unless given, its title, where the visitor came from. |
| `people.set`, `people.setOnce`, `people.unset`, `people.add` | Sets the person's properties, sets the ones not set already, removes some, adds to numbers. |
| `identify(traits?)` | Ties this browser's anonymous events to the signed-in user, with their traits. The client does it on its own when someone signs in. |
| `reset()` | Forgets this browser's anonymous id and session: the next visitor is someone new. The client does it on its own when someone signs out. |
| `flush()` | Sends what is held now. |
| `start(options?)` | Starts the browser's own measures, as the `analytics` option does: `pageViews`, `webVitals`, `network`, each on unless turned off. Returns what stops them. |
| `onEvent(listener)` | Told of each event the app captures, here in the page, whatever the person chose: what in-app messages are triggered by. Nothing leaves the page for it. |

An event is the signed-in user's when someone is signed in, and this browser's anonymous visitor's otherwise; once they sign in, their anonymous history is theirs. A session is half an hour without an event.

What the client reads on its own goes as the page's **route**, not its address: no query, no fragment, and a path segment that is not a word of the route (a number, an id, an email, a token) becomes `:id`. `/orders/8f1c…/receipt?token=…` is sent as `/orders/:id/receipt`. The browser's referrer is cut the same way, since on a same-site arrival it is the whole previous address. What your code passes to `page()` is sent as you passed it.

The browser's own measures, once started:

| Measure | What it is | Key |
|---|---|---|
| Page views | A `$pageview` for the first page and each navigation after it (history and back/forward). | `analytics` |
| Web vitals | LCP, CLS, INP, FCP and TTFB, as `web_vital` samples. | `performance` |
| Request timings | Each `fetch` the page makes: method, address without its query, status, time. | `performance` |

A timing goes without the person's id unless `analytics` is granted too. Refusing a key drops what was held of it at once.

## What an app sends

The client makes these calls for you. They are the analytics module's, with the publishable key over HTTPS, and a signed-in user's token makes what they send theirs:

| Call | What it is | Body |
|---|---|---|
| `POST /analytics/capture` | One event | `{ event, distinct_id, properties?, session_id?, app_version?, timestamp?, sent_at? }` |
| `POST /analytics/batch` | Up to 100 events, 3 MiB | `{ events: [<capture bodies>] }` |
| `POST /analytics/page` | A `$pageview` | `{ distinct_id, url, title?, referrer?, properties?, session_id?, … }` |
| `POST /analytics/screen` | A `$screen` | `{ distinct_id, screen_name, properties?, session_id?, … }` |
| `POST /analytics/identify` | An `$identify`: who the user is | `{ distinct_id, anonymous_id?, traits? }` |
| `POST /analytics/alias` | An `$alias`: two ids are one user | `{ from, to }` |
| `POST /analytics/people` | The person's properties | `{ set?, set_once?, unset?, add? }` |
| `POST /analytics/perf` | Up to 100 samples, 512 KiB: web vitals, request timings | `{ items: [ … ] }` |

- **`event`**: a letter or `$`, then letters, digits and `_.:-$`, 64 characters at most.
- **`distinct_id`**: who did it, 256 characters at most, with no NUL character. With a user's token the user's id is the distinct id, whatever the body says, so a signed-in user's events are theirs however the app wrote them.
- **`properties`** and **`traits`**: 100 at most, 8 KiB each as JSON, 32 KiB in all.
- **`timestamp`** and **`sent_at`**: unix milliseconds on the device's clock. The difference between `sent_at` and the server's clock is the device clock's error, and it is taken off `timestamp`. An event queued offline keeps its own `timestamp` and gets a fresh `sent_at` when it goes out.
- **`identify`'s `anonymous_id`**: the id the user had before signing in. Their anonymous history goes with them, and if they are deleted, it goes too.
- **`user_id`** (capture and batch): your server, with its secret key, says whose an event is — something a user did that your backend saw (a document approved, an order shipped). The event is that user's, as if their app had sent it signed in: on their timeline (source `server`), in their funnels, and acted on by their [journeys](/docs/backend/journeys#from-your-backend). `distinct_id` may be left out then. An app's event is its signed-in user's: one that names `user_id` is refused (`400 invalid_user_id`).

The headers say what the server cannot tell from the body:

| Header | Effect |
|---|---|
| `idempotency-key` | The same key sent again within two minutes is not kept twice. Send one per event, and send it again with a retry. |
| `x-platform` | `web`, `ios` or `android`, kept with the event. |
| `x-palbase-client-version` | Your app's version, kept with the event. |
| `x-os-version` | The operating system's version. |
| `x-palbase-installation` | The install it came from (`pb.installation.id`): the platform's events about the install — a push that reached it while no one was signed in — are its person's. Sent only with `analytics` granted. |

## What comes back

A call is answered once what it sent is kept: on the platform's stream, written to the store within seconds, even while the store restarts. So a `202` means the event will be there.

| Status | When |
|---|---|
| `202` | Kept. A batch answers it when every event was kept. |
| `207` | A batch with some events refused: `{ accepted, rejected: [{ index, error, error_description }] }`. The rest were kept. |
| `400` | The body does not fit the rules above. A batch none of whose events was kept answers its first refusal. |
| `413` | Over the size limits. |
| `429` | Over what the project may send per second, all kinds together. `Retry-After` says when. |
| `503` | Not kept: send again with the same `idempotency-key`. |

What an app sends is counted against its own budget, per project per second, not against the requests the rest of the project's calls may make.

## Consent

Analytics follows what the person allowed, kept by `pb.consent`: events, page views, `identify` and person properties go only with `analytics` granted; web vitals and request timings with `performance`, and without the person's id unless `analytics` is granted too. A key with neither the person's choice nor a starting value collects nothing. Every call that carries the person's data says the install it came from, `X-Palbase-Installation`. See [Consent](/docs/web/consent) for the keys, the starting values and a consent screen.

A user's analytics go when the user is deleted — everything under any id they went by, and the install's events from while no one was signed in. The project's analytics settings (`PUT /analytics/settings`, with the secret key) say how long events are kept: 90 days unless changed.

## People

The anonymous id an app had before its person signed up is that person once `identify` names it: their events before and after are one person's in funnels, retention and their timeline. Properties are set of a person with `POST /analytics/people` (`{ set?, set_once?, unset?, add? }`; the client's `pb.analytics.people.set`, `setOnce`, `unset` and `add`): a signed-in user's are theirs, an anonymous visitor's are their anonymous id's. Where an install came from (`$initial_utm_source`, `$initial_referrer` …) is set once of the person who installed.

The project's server reads them with the secret key: `GET /analytics/people?query=…` finds a person by any id they went by or their email, `GET /analytics/people/{person_id}` is their profile — with where they were last ([Where a person is](#where-a-person-is)) — and `GET /analytics/people/{person_id}/events` their timeline, newest first — what their apps sent, what their backend sent, and what Palbase did for them (a purchase, a push that reached their phone, a consent changed). `GET /analytics/catalog` lists every event a timeline can hold: Palbase's, with their fields, and the app's own as they arrived; `PUT /analytics/catalog/{name}` describes or hides one. Studio's **People** and **Event catalog** screens show the same.

## Where a person is

Each event is given the place of the address it came from — the user's own, because the browser sends it to the project directly: its `country` (ISO 3166-1 alpha-2), its `region` (a province or state, by its English name) and its `city` (a city or district). A person's profile says where their newest event that had a place came from; a summary breaks down by each of the three; an audience can pick people by them. Places come from DB-IP's IP to City Lite database: IP geolocation by [DB-IP](https://db-ip.com), CC BY 4.0. An address says where its network is, not the device: a phone on mobile data is often placed in its carrier's city.

## Audiences

An audience is the people a rule picks, among those behind the project's events. Its members are worked out when it is made or changed, then every minute, and each person who enters or leaves it from then on is told: `audience.entered` and `audience.exited` (`{ audience_id, audience_name, person_id, user_id }`) go into their timeline, to your webhook and to your backend's `@On` handlers. Its first members are not told they entered — the rule came to them, they did nothing — and neither is anyone when it is deleted. A push can go to an audience's members ([Notifications](/docs/backend/notifications#to-an-audience)).

The secret key's calls:

| Call | What it does |
|---|---|
| `POST /analytics/audiences` | Makes one: `{ name, description?, rule }`. A project keeps 100 at most. |
| `POST /analytics/audiences/preview` | Who a rule would pick now, without keeping it: how many, and the first twenty. A rule that takes longer than 20 seconds to work out answers `422 preview_too_slow`. |
| `GET /analytics/audiences`, `GET /analytics/audiences/{id}` | Each audience with its rule, how many are in it, when it was last worked out, and `state`: `ready`, or `pending` while a rule made or changed is worked out. |
| `PATCH /analytics/audiences/{id}` | Changes its name, description or rule. A changed rule is worked out anew, and, like a new one, tells no one at once. |
| `GET /analytics/audiences/{id}/members` | A page of its members: each one's person id, the user they signed in as, and the installs their events came from. |
| `DELETE /analytics/audiences/{id}` | Deletes it and its members. |

A rule is one to twenty conditions, every one of which holds (`match: "all"`, unless said) or at least one (`"any"`):

```json
{
  "match": "all",
  "conditions": [
    { "type": "event", "event": "purchase", "did": false, "within": { "amount": 7, "unit": "days" } },
    { "type": "event", "event": "app_opened", "did": true, "at_least": 3, "within": { "amount": 30, "unit": "days" } },
    { "type": "property", "key": "plan", "op": "neq", "value": "pro" },
    { "type": "place", "field": "city", "op": "in", "value": ["Istanbul", "Kadıköy"] },
    { "type": "platform", "op": "eq", "value": "ios" }
  ]
}
```

| Condition | Picks a person who… |
|---|---|
| `event` | did (`did: true`, `at_least` times, 1 unless said) or did not (`did: false`) an event in the last `within`: `amount` `minutes`, `hours` or `days`, a year at most. The event is an app's own or one of Palbase's (`purchases.purchase.completed`, `notification.opened` …). |
| `property` | has a property: `eq`, `neq`, `gt`, `gte`, `lt`, `lte` (numbers), `contains` (text, any case), `set`, `not_set`. |
| `place` | was last in a `country`, `region` or `city`: `eq`, `neq`, or `in` a list of up to 50. |
| `platform` | last sent from `ios`, `android` or `web`: `eq`, `neq` or `in`. |

`neq` holds for a person the value is not known of, as not `eq`. A user who is deleted leaves every audience and never comes back to one. Studio's **Analytics › Audiences** screen builds a rule a condition at a time, previews it, and lists each audience's people.

## From the CLI

The secret key's reads and the analytics settings are also commands of the CLI, for the environment it is pointed at (`-E <env>`):

```sh
palbase analytics:summary --window 7d
palbase analytics:events --name checkout_started --window 24h --limit 20
palbase analytics:settings:set retention_days=30
```

| Command | What it does |
|---|---|
| [`palbase analytics:summary`](/docs/cli/reference#palbase-analyticssummary) | What analytics counted over a window (`30m`, `24h`, `7d`): events, users, sessions, the top events. |
| [`palbase analytics:events`](/docs/cli/reference#palbase-analyticsevents) | The events recorded, newest first: by name, by user (their distinct id), over a window. |
| [`palbase analytics:settings:get`](/docs/cli/reference#palbase-analyticssettingsget), [`palbase analytics:settings:set`](/docs/cli/reference#palbase-analyticssettingsset) | How long events are kept (`retention_days`), the share of performance samples kept (`perf_sample_pct`), whether bodies are kept (`console_bodies`). A shorter retention removes what is older within minutes. |

## Related

- [Overview](/docs/web/overview) — the client's options, and calling the project from a browser
- [Consent](/docs/web/consent) — the keys analytics follows
- [Auth](/docs/web/auth) — the session whose token makes events the user's
- [Reading analytics](/docs/analytics/reading) — summaries, breakdowns, funnels and retention, in Studio and through the API
- [Server SDK](/docs/server/overview) — reading summaries, events and funnels with the secret key



<!-- ===== web/consent ===== -->

# Consent

`pb.consent` keeps what the person allowed the app to collect and use, key by key. A choice stands in the browser the moment it is made — a key refused stops its data at once, before anything else is sent — and goes to the project with when it was made, later if the browser is offline. The project keeps every choice with when and where it was made, and what the SDKs collect follows the keys: [analytics](/docs/web/analytics) sends events only with `analytics` granted, a flag's audience condition and an in-app campaign to an audience reach only who allowed `personalization`, and the project's marketing messages skip whoever refused a channel's marketing key.

## Quick example

```ts
// src/lib/palbase.ts
import { createClient } from "palbase/web";

export const pb = createClient({
  url: "https://k3xq81w4m.palbase.studio",
  publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5",
  analytics: true,
  consent: {
    // What is collected before the person chooses: nothing, until they say.
    start: { analytics: "denied", performance: "denied" },
    // The version of the consent text this app shows.
    textVersion: "2026-10",
    // The app's own keys, listed after the platform's.
    customKeys: ["custom.chat_transcripts"],
  },
});
```

```ts
// src/consent-banner.ts
import type { ConsentState } from "palbase/web";
import { pb } from "./lib/palbase";

/** Draws a choice for every key the person is still to be asked about. */
export async function showConsentBanner(root: HTMLElement): Promise<void> {
  const ask = new Set(await pb.consent.needsAsking());
  if (ask.size === 0) return;
  const keys = (await pb.consent.keys()).filter((k) => ask.has(k.key));
  const lang = navigator.language.startsWith("tr") ? "tr" : "en";
  const choices: Record<string, ConsentState> = {};
  for (const k of keys) {
    const box = document.createElement("input");
    box.type = "checkbox";
    box.addEventListener("change", () => { choices[k.key] = box.checked ? "granted" : "denied"; });
    choices[k.key] = "denied";
    const label = document.createElement("label");
    // The platform's keys come with their words; the app words its own.
    label.append(box, ` ${k.title[lang] ?? k.key}`);
    root.append(label);
  }
  const save = document.createElement("button");
  save.textContent = "Save";
  // One screen's choices, made together.
  save.addEventListener("click", () => { pb.consent.setMany(choices); root.replaceChildren(); });
  root.append(save);
}
```

```ts
// src/main.ts
import { pb } from "./lib/palbase";
import { showConsentBanner } from "./consent-banner";

await showConsentBanner(document.querySelector<HTMLElement>("#consent")!);

// Told of every change: here, in another tab, on another of the person's devices, or by the project.
pb.consent.onChange((key, state) => console.log(key, state ?? "not chosen"));
```

## The keys

The keys a consent screen lists come from the project, the same list for every SDK:

| Key | Category | What it covers |
|---|---|---|
| `analytics` | measurement | Events, page views, `identify` and person properties. |
| `performance` | measurement | Web vitals and request timings. |
| `diagnostics` | measurement | What went wrong when the app failed: errors and crashes. |
| `personalization` | personalization | Tailoring what the app shows by what the person does: a flag's audience condition, an in-app campaign to an audience. |
| `marketing_push`, `marketing_email`, `marketing_sms`, `marketing_whatsapp` | marketing | Messages that are not transactional, on that channel. |
| `ads_measurement`, `ads_personalization` | advertising | What US laws call selling or sharing (`ads: true`). |

`keys()` answers them in the order a screen shows them, each `{ key, category, title, description, ads }` with its words in English and Turkish (`title.en`, `title.tr`), then the app's own `customKeys` (`custom.<name>`: a–z, 0–9 and `_`, 48 at most), whose words are the app's (`category: "custom"`). The platform's list is read from the project once (`GET /auth/consents/keys`).

## `pb.consent`

| Member | What it does |
|---|---|
| `keys()` | The platform's keys with their words, then the app's own. |
| `state(key)` | `"granted"`, `"denied"`, or `undefined` when the person has not chosen and the app gave no starting value. While the person's choices are still to be read from the project, it answers `"denied"`. |
| `set(key, state)`, `setMany({ … })` | Records the person's choice, or a screen's choices together. It stands at once and goes to the project with when it was made. |
| `onChange(listener)` | Calls `listener(key, state)` for each key whose state changed: here, in another tab, on another of the person's devices, or by the project on their word. Returns the unsubscribe. |
| `region()` | `{ country?, jurisdiction }`, where `jurisdiction` is `gdpr` (the EU, the EEA, the UK, Switzerland: asked before anything is collected), `us` (collected until refused) or `other`, from the person's address. |
| `lastDeniedAt(key)` | When the key was last refused: here, on another of the person's devices, or by the project. |
| `needsAsking(keys?)` | The keys to ask about: never chosen, or chosen on the app's screen under another `textVersion`. In the US, an advertising key refused within the last twelve months is not asked again. |

## Starting values

`createClient({ consent: { start } })` says what is collected before the person chooses, key by key. The starting values are the app's, and they never leave the browser: only the person's own choices are sent, so a starting value can never undo a refusal the project holds. A key the SDK collects for with neither a choice nor a starting value collects nothing: give `analytics` and `performance` when the app uses them.

Where the law asks first — `region()` answers `gdpr` — start those keys `denied` and ask. An app whose people are all where data is collected until refused may start them `granted`, and still offers the choice. A choice made under one `textVersion` is asked again once the app shows a new text with a new version.

## Whose the choices are

The device's while no one is signed in. On sign-in the device's newer choices become the account's and the device takes the account's: the newest explicit choice wins, never a starting value. On sign-out the device goes back to the app's starting values, and the next person here is asked anew. A refusal made elsewhere — an unsubscribe link, another of the person's devices, the project on their word — reaches the signed-in person's open pages at once, and their keys change here.

A browser that sends Global Privacy Control refuses the advertising keys for the person once, recorded as `gpc`. A choice the person makes in the app after it is theirs.

## The calls under it

`pb.consent` makes these calls for you; an app that makes them itself sends what the client does:

| Call | What it is |
|---|---|
| `GET /auth/consents/keys` | The platform's keys with their words. |
| `GET /auth/consents?installation_id=…` | The choices and the region: the account's with a user's token, the device's with the publishable key alone. |
| `PUT /auth/consents` | `{ installation_id, text_version?, choices: [{ key, state, chosen_at }] }`: records choices, the account's or the device's as above. |
| `POST /auth/consents/link` | On sign-in: the device's newer choices become the account's. |

The last three name the install and prove they hold it with `X-Palbase-Installation-Secret`: the secret the client keeps in the browser, from which the install's id is made (`pb.installation.id`). The device's own choices, asked for or written without the secret it first named itself with, are refused `403 not_the_device`.

The project's server can only refuse, never grant: `POST /admin/consents/refuse` with the secret key (`{ user_id | installation_id, keys, reason }`, reason `email_unsubscribe`, `sms_stop` or `support`) records a refusal the person made elsewhere, and it reaches their apps at once. `GET /admin/users/{uid}/consents` and `GET /admin/installations/{installation_id}/consents` read the state and the proof of each choice. A deleted user's choices go with them.

## Related

- [Analytics](/docs/web/analytics) — what the `analytics` and `performance` keys hold back
- [Flags](/docs/web/flags) — audience conditions, which need `personalization`
- [Notifications](/docs/web/notifications) — in-app campaigns and the marketing keys
- [Notifications in your backend](/docs/backend/notifications) — sends the marketing keys skip



<!-- ===== web/notifications ===== -->

# Notifications

`pb.notify` is what a browser takes of the project's messages: its pushes (`pb.notify.push`, Web Push through the browser's own push service), the signed-in person's inbox (`pb.notify.inbox`), and the project's in-app campaigns shown in the page (`pb.notify.inApp`). The signed-in person's preferences and the topics they follow are two more calls. Sending is your backend's ([Notifications](/docs/backend/notifications)); the browser subscribes, reads and shows.

## Web push

```ts
// src/lib/palbase.ts
import { createClient } from "palbase/web";

export const pb = createClient({ url: "https://k3xq81w4m.palbase.studio", publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5" });
```

```ts
// src/push-button.ts
import { pb } from "./lib/palbase";

export async function turnOnPush(): Promise<string> {
  // From a tap: a browser shows its prompt only then.
  if (pb.notify.push.permission() === "unsupported") return "This browser takes no notifications";
  const on = await pb.notify.push.subscribe();
  return on ? "Notifications are on" : "Notifications were not allowed";
}
```

```ts
// src/main.ts
import { pb } from "./lib/palbase";

// As the app starts: the browser's subscription registered again, without a prompt, when it has one.
await pb.notify.push.refresh();
```

| Member of `pb.notify.push` | What it does |
|---|---|
| `supported()` | Whether the browser takes pushes at all: a service worker, the Push API and notifications. |
| `permission()` | `granted`, `denied`, `default` (not asked yet) or `unsupported`. |
| `subscribe(options?)` | Asks the person (call it from a tap), registers the service worker, subscribes the browser with the project's key through its own push service, and registers the subscription as a device. `true` when the browser takes pushes now, `false` when the person refused or the browser has none. `options`: `serviceWorker`, the worker's path (`/palbase-sw.js` unless given), and `scope`. |
| `unsubscribe()` | Ends the browser's subscription. The project forgets the device as it next pushes it. |
| `refresh()` | Registers the subscription again, without a prompt, when the person allowed it and there is one. |

The device is the signed-in user's, or this install's (`pb.installation.id`) while no one is signed in: a push that names the install reaches it then. It is registered again by itself as people sign in and out, and a subscription that cannot be registered again ends, so one person's pushes are never shown to the next. The project's key for Web Push (VAPID) is its own, made as the first browser asks for it: no account of another provider is needed.

### The service worker

The pushes are shown by the SDK's service worker, served from your site's own origin. Copy `node_modules/palbase/dist/web/push-sw.js` (the package exports it as `palbase/web/push-sw.js`) into the folder your site serves as it is, as `palbase-sw.js`: `public/palbase-sw.js` in Next.js or Vite. Copy it again when you update `palbase`. To serve it elsewhere, name its path: `subscribe({ serviceWorker: "/sw/palbase.js" })`.

`subscribe()` registers it with the project's address and publishable key in its URL, which it reports with. The worker shows each push, opens its link when it is tapped (an `https` address, or one of your site's; a tab of your app at that address is focused rather than opened again), and tells the project how each went — delivered, opened, dismissed — with the push's own receipt as the credential. It tells your open pages too:

```ts
// src/push-events.ts
// What the service worker tells each open page of the app.
navigator.serviceWorker?.addEventListener("message", (e: MessageEvent) => {
  const m = e.data as { type?: string; event?: "received" | "opened"; url?: string; data?: Record<string, string> };
  if (m.type === "palbase.push" && m.event === "received") console.log("a push arrived", m.data);
});
```

## Inbox

```ts
// src/inbox.ts
import { pb } from "./lib/palbase";

const badge = document.querySelector<HTMLElement>("#inbox-badge")!;
const view = pb.notify.inbox.mount(document.querySelector<HTMLElement>("#inbox")!, {
  onUnread: (n) => { badge.textContent = n ? String(n) : ""; },
  onOpen: (_item, link) => { window.location.assign(link); },
  labels: { empty: "No messages yet" },
});

// Or its calls, for a list of your own:
const page = await pb.notify.inbox.list({ limit: 20 });
await pb.notify.inbox.markRead(page.items.filter((m) => !m.read_at).map((m) => m.id));
await pb.notify.inbox.markRead("all");
if (page.items[0]) await pb.notify.inbox.remove(page.items[0].id);
view.destroy();
```

The signed-in person's inbox is the same on every device of theirs: read here, it is read on their phone; deleted, it is gone there. `mount()` draws it ready — newest first, the unread marked, a designed card drawn by its definition — and asks for it again as the page comes back into view and as people sign in and out. A tap marks a message read and opens its link (an https address in a new tab, your app's in this page, unless `onOpen` takes it). No one signed in: an empty list.

| Member of `pb.notify.inbox` | What it does |
|---|---|
| `list({ limit?, cursor?, locale? })` | A page of the inbox, newest first, with how many of it all are unread; `next_cursor` reads the next page. |
| `unread()` | How many messages are unread. |
| `markRead(ids \| "all")` | Marks messages read on every device of the person's; answers how many became read. |
| `remove(id)` | Deletes a message from every device of the person's. |
| `mount(container, options?)` | Draws the inbox into an element and keeps it current. `options`: `locale`, `appearance`, `limit` (50), `onOpen`, `onCustom` (a designed card's own buttons), `onUnread`, `labels`. |

## In-app messages

```ts
// src/in-app.ts
import { pb } from "./lib/palbase";

pb.notify.inApp.start({
  // A button's link of your app's: your router's, not a page load.
  onDeepLink: (link) => { window.history.pushState(null, "", new URL(link).pathname); },
  // A button that shows a placement's paywall: drawn here, bought through Stripe Checkout.
  onShowPaywall: async (placement) => {
    const paywall = await pb.purchases.paywall(placement);
    paywall?.render(document.querySelector<HTMLElement>("#paywall")!, {
      successUrl: "https://app.example.com/thanks",
      cancelUrl: window.location.href,
    });
  },
});

// Events analytics records come by themselves; name one of your own:
pb.analytics.capture("cart_viewed", { plan: "pro" });
pb.notify.inApp.trigger("level_completed", { level: 3 });
```

Once started, the person's campaigns are asked for as each session starts — the first page of one, the page back in view after half an hour away, a sign-in or out — and an event shows the first campaign it triggers that the caps let: the project's (one a session, three a day, ten minutes apart unless its settings say otherwise) and the campaign's own. The server counts each showing on every device of the person, so two tabs or a tab and a phone do not show it twice. The message is drawn by the SDK's screen renderer, the one paywalls are drawn with (`palbase/web/message` for an app that draws one itself), as a modal (the browser's own modal dialog), the whole page, or a banner at an edge that goes by itself when it says so.

Triggers are matched **in the page**: no event leaves it for them, and a message is shown whatever the person chose of analytics. A campaign to an audience reaches only who allowed personalization ([Consent](/docs/web/consent)), which the server holds to. A button that asks for push shows the browser's prompt and subscribes it (`pb.notify.push.subscribe()`) unless `onRequestPush` does it. A button that takes an offer claims it, or opens Stripe Checkout with it, unless `onOffer` does it. A tap is reported as a click and a close as a dismissal; a conversion — the campaign's event after it was seen — only while the person allows analytics.

`stop()` stops showing campaigns, `refresh()` asks for them again, and `settled()` waits for the events given so far to be taken, which a test or a page about to navigate awaits.

## Preferences and topics

The signed-in person chooses which kinds of message they take on which channel, and follows the topics the project opened to them. The client has no method for these four calls: make them through the client's own transport, which sends the user's access token and refreshes it as the client's own calls do (see [Overview](/docs/web/overview#calls-the-client-has-no-method-for)).

```ts
// src/lib/as-user.ts
import { pb } from "./palbase";

/** A notify call as the signed-in user; a refusal is thrown as a PalbaseError. */
export async function asUser<T>(method: "GET" | "PUT" | "POST" | "DELETE", path: string, body?: unknown): Promise<T> {
  const reply = await pb.transport.send({
    op: `${method} ${path}`,
    method,
    path,
    auth: [["ApiKeyAuth", "userJWT"]],
    answers: { 200: "json", 204: "empty" },
    body: body === undefined ? undefined : { kind: "json", contentType: "application/json", value: body },
  });
  return reply.data as T;
}
```

```ts
// src/settings.ts
import { asUser } from "./lib/as-user";

/** channel (email, sms, whatsapp, push) → category → whether they take it. */
type Preferences = Record<string, Record<string, boolean>>;

const prefs = await asUser<Preferences>("GET", "/notify/preferences");
console.log(prefs.email?.marketing);

// Stop marketing email. The answer is all of their preferences.
await asUser<Preferences>("PUT", "/notify/preferences", { email: { marketing: false } });

// Follow a topic, and stop following it.
await asUser<void>("POST", "/notify/topics/product-updates/subscription");
await asUser<void>("DELETE", "/notify/topics/product-updates/subscription");
```

| Call | What it does |
|---|---|
| `GET /notify/preferences` | `{ channel: { category: on } }` for each channel (`email`, `sms`, `whatsapp`, `push`): `transactional` (always on), `marketing`, and every other category set for them. A category the user never set is on. |
| `PUT /notify/preferences` | Sets the ones it names, 100 at most in a write, and answers all of them. `transactional` is not theirs to turn off and is left as it is. A user keeps 50 categories. |
| `POST /notify/topics/{name}/subscription` | Follows a topic the project opened to its users (`self_subscribe`). `403` for any other. |
| `DELETE /notify/topics/{name}/subscription` | Stops following it. |

They are the signed-in user's: with no one signed in, the transport throws before anything is sent (`missing_credential`). What the person allowed in the app ([Consent](/docs/web/consent)) holds as well: a send that is not transactional is skipped for someone who refused that channel's marketing key (`marketing_push`, `marketing_email`, `marketing_sms`, `marketing_whatsapp`).

## Related

- [Notifications](/docs/backend/notifications) — sending pushes, inbox messages and in-app campaigns from your backend.
- [Analytics](/docs/web/analytics) — the events that trigger in-app messages.
- [Consent](/docs/web/consent) — the marketing keys, and personalization for audiences.



<!-- ===== web/nextjs ===== -->

# Next.js

A Next.js app uses Palbase in two places. In the browser, `palbase/web` signs the user in and calls the project's address directly. On the server (the proxy, server components, server actions, route handlers), the same client reads who is signed in from the request's cookies, and `palbase/server` acts as the project with the secret key. `palbase/web/ssr` joins the two: it keeps the session in a cookie the page and your server both read, as `@supabase/ssr` does for Supabase.

## Quick example

The browser's client keeps its session in the page's cookies:

```ts
// src/lib/palbase.ts
"use client";

import type { PalbaseClient } from "palbase/web";
import { createBrowserClient } from "palbase/web/ssr";

// The environment's address and publishable key, from Studio. Public: they go into the bundle.
export const PROJECT = process.env.NEXT_PUBLIC_PALBASE_URL ?? "https://k3xq81w4m.palbase.studio";
export const PUBLISHABLE_KEY = process.env.NEXT_PUBLIC_PALBASE_PUBLISHABLE_KEY ?? "pb_k3xq81w4m_cZ8yX7wV6uT5";

let client: PalbaseClient | undefined;

/** The browser's client, made on first use: from an effect or an event handler, which run in the browser. */
export function palbase(): PalbaseClient {
  client ??= createBrowserClient({ url: PROJECT, publishableKey: PUBLISHABLE_KEY });
  return client;
}
```

```tsx
// src/app/signin/page.tsx
"use client";

import { useRouter } from "next/navigation";
import { useState } from "react";
import { palbase } from "../../lib/palbase";

export default function SignInPage() {
  const router = useRouter();
  const [problem, setProblem] = useState<string | null>(null);

  async function submit(form: FormData) {
    // From the browser: auth's limits count this person's own address.
    const result = await palbase().auth.signIn(String(form.get("email")), String(form.get("password")));
    if (result.mfaRequired) return setProblem("a second factor is needed");
    // The session is in the cookie now: the server's pages see it.
    router.push("/account");
    router.refresh();
  }

  return (
    <form action={(form) => void submit(form).catch(() => setProblem("those details were not accepted"))}>
      <input name="email" type="email" />
      <input name="password" type="password" />
      <button type="submit">Sign in</button>
      {problem && <p role="alert">{problem}</p>}
    </form>
  );
}
```

A server component reads who it is from the request:

```ts
// src/lib/palbase-server.ts
import { cookies } from "next/headers";
import type { PalbaseClient } from "palbase/web";
import { createServerClient } from "palbase/web/ssr";

const PROJECT = process.env.NEXT_PUBLIC_PALBASE_URL ?? "https://k3xq81w4m.palbase.studio";
const PUBLISHABLE_KEY = process.env.NEXT_PUBLIC_PALBASE_PUBLISHABLE_KEY ?? "pb_k3xq81w4m_cZ8yX7wV6uT5";

/** A server component's client: it reads the request's cookies and never writes them. */
export async function readingClient(): Promise<PalbaseClient> {
  const jar = await cookies();
  return createServerClient({ url: PROJECT, publishableKey: PUBLISHABLE_KEY, cookies: { getAll: () => jar.getAll() } });
}

/** A server action's or a route handler's client: it may renew the session and write it back. */
export async function writingClient(): Promise<PalbaseClient> {
  const jar = await cookies();
  return createServerClient({
    url: PROJECT,
    publishableKey: PUBLISHABLE_KEY,
    cookies: {
      getAll: () => jar.getAll(),
      setAll: (cs) => cs.forEach((c) => jar.set(c.name, c.value, c.options)),
    },
  });
}
```

```tsx
// src/app/account/page.tsx
import { redirect } from "next/navigation";
import { keepSession } from "palbase/web/ssr";
import { readingClient } from "../../lib/palbase-server";

export default async function AccountPage() {
  // Auth's answer for the token in the cookie: never the cookie's word alone.
  const user = await keepSession(await readingClient());
  if (!user) redirect("/signin");
  return <p>Signed in as {user.email ?? user.id}</p>;
}
```

## The browser calls the project directly

The browser calls `https://<ref>.palbase.studio` itself. The project's address answers a page on any site, preflights included, so the app needs no rewrite of the modules' paths, and should have none. Through a rewrite every user's call reaches the project from your Next.js server's address, and what the project decides from a caller's address is then decided from yours, for all your users at once: auth's limits on sign-in attempts, the proof-of-work it asks of a busy address, the country a flag's condition reads and an analytics event is given. See [Overview](/docs/web/overview#calling-the-project-from-a-browser).

For the same reason, sign the user in **in the browser**, as the example does, and not in a server action: a sign-in your server makes for every user comes from one address.

## The session cookie

`createBrowserClient` keeps the session in a cookie named `pb-<ref>-session`, split into `pb-<ref>-session.0`, `.1`, … when it is longer than a cookie holds. It is written for the whole site (`path=/`), `SameSite=Lax` so a link from elsewhere (a sign-in email) opens the page signed in, `Secure` (the browser's client leaves it off on a page served over http, such as `http://localhost:3000`, and the server's needs `cookieOptions: { secure: false }` there), and readable by the page's script, because the browser's client reads it there. The browser keeps it as long as it keeps any cookie (400 days); the session itself ends when its refresh token does. `cookieOptions` changes any of that, for the browser's client and the server's alike: `{ domain: ".example.com" }` shares the session with the site's other subdomains.

The cookie is where the session is kept, not how a call proves it. Every call still carries the access token as `Authorization: Bearer …`, and the project reads no cookie. What a cookie says is what the browser wrote, and a browser can write anything: `keepSession` asks auth whose the token is before your code acts on it.

## On the server

`createServerClient({ url, publishableKey, cookies })` is one request's client: its session is the request's cookies. Give it `getAll`, which reads them, and, where the server can write the response's cookies, `setAll`.

Who renews the session matters. A renewal hands out a new refresh token and the old one stops working, so a renewal whose new token cannot be written back ends the session at the next one. The client follows what you gave it:

| Where | `cookies` | What the client does |
|---|---|---|
| The proxy (`src/proxy.ts`) | `getAll` and `setAll` | Renews a session with five minutes or less left on the way in, before any page renders. |
| A server action, a route handler | `getAll` and `setAll` | Renews before a call that finds the token about to lapse, and writes the new session back. |
| A server component | `getAll` only | Never renews: Next.js lets a server component read cookies, not write them. Run the proxy before the pages that read the session, so none renders with a token that has lapsed. |

`keepSession(pb)` is who is signed in, as auth says: it renews first when the client can and the session has little left, then asks auth whose the access token is (`GET /auth/user`). It answers the user, or `null` when no one is signed in, the session is over, or auth does not take the token. When auth cannot be asked, it throws a `PalbaseError`: the network failed, or a server component's token lapsed with no proxy to renew it (`missing_credential`). It writes nothing but a renewal, so it never puts back an older session over one the browser renewed meanwhile.

The proxy keeps the session fresh for every page it runs before:

```ts
// src/proxy.ts
import { NextResponse, type NextRequest } from "next/server";
import { createServerClient, keepSession } from "palbase/web/ssr";

export async function proxy(request: NextRequest) {
  let response = NextResponse.next({ request });
  const pb = createServerClient({
    url: process.env.NEXT_PUBLIC_PALBASE_URL ?? "https://k3xq81w4m.palbase.studio",
    publishableKey: process.env.NEXT_PUBLIC_PALBASE_PUBLISHABLE_KEY ?? "pb_k3xq81w4m_cZ8yX7wV6uT5",
    cookies: {
      getAll: () => request.cookies.getAll(),
      setAll: (cookies, headers) => {
        // The pages rendered after this see the renewed session...
        for (const c of cookies) request.cookies.set(c.name, c.value);
        response = NextResponse.next({ request });
        // ...and so does the browser.
        for (const c of cookies) response.cookies.set(c.name, c.value, c.options);
        // An answer that writes one person's session is kept by no cache.
        for (const [name, value] of Object.entries(headers)) response.headers.set(name, value);
      },
    },
  });

  const user = await keepSession(pb);
  if (!user && request.nextUrl.pathname.startsWith("/account")) {
    return NextResponse.redirect(new URL("/signin", request.url));
  }
  return response;
}

export const config = {
  // Every page, not the build's static files.
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};
```

`setAll` is given the cookies and the headers to send with them: `Cache-Control: private, no-cache, no-store, must-revalidate, max-age=0`, `Expires: 0` and `Pragma: no-cache`. An answer that writes a session is one person's, and a cache between your server and the browser that kept it would hand it to the next person. Set them on the response with the cookies.

The redirect is a convenience for the reader, not the check: a page that shows one person's data asks `keepSession` itself, as the account page above does.

## Acting as the project

A route handler that does what only the project may, such as sending an email, checks who is asking with the request's client and then acts with the secret key:

```ts
// src/lib/server.ts
import { createServer } from "palbase/server";

const PROJECT = process.env.NEXT_PUBLIC_PALBASE_URL ?? "https://k3xq81w4m.palbase.studio";

/** The project, with its secret key: server code only. */
export const server = createServer({ url: PROJECT, secretKey: process.env.PALBASE_SECRET_KEY ?? "" });
```

```ts
// src/app/api/invite/route.ts
import { keepSession } from "palbase/web/ssr";
import { writingClient } from "../../../lib/palbase-server";
import { server } from "../../../lib/server";

export async function POST(request: Request): Promise<Response> {
  const user = await keepSession(await writingClient());
  if (!user) return Response.json({ error: "unauthorized" }, { status: 401 });
  const { to } = (await request.json()) as { to: string };
  await server.notify.sendEmail({
    body: { to, subject: "You're invited", text: `${user.email ?? "A friend"} invited you.`, category: "transactional" },
  });
  return new Response(null, { status: 204 });
}
```

```ts
// src/invite.ts
"use client";

export async function invite(to: string): Promise<void> {
  // Same origin: the browser sends the session cookie with it.
  const res = await fetch("/api/invite", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ to }),
  });
  if (!res.ok) throw new Error(`the invite was refused: ${res.status}`);
}
```

A message composed whole like this one goes out through the project's own email provider. A template goes through the platform's shared sender too. See [Notifications](/docs/backend/notifications).

`createServer` takes the same address as the browser's client. It refuses to run where there is a `document`, and its package resolves to an error in a browser bundle, so the secret key cannot ship to the client by accident.

A larger backend, with its own database and routes, is a machine of its own rather than route handlers, and the browser calls it with the user's token. See [Calling Your Backend](/docs/web/backend-calls).

## Without cookies

`createClient` from `palbase/web` keeps the session in the browser's `localStorage` instead. Then the server sees no session of its own, and an app renders what is the user's in client components and keeps server components for what is the same for everyone. A client made with `createClient` belongs in client components (`"use client"`), made on first use as `palbase()` above is: a module that called it at import would run on the server too while Next renders the client component's first HTML, where there is no `localStorage`.

Everything in [Auth](/docs/web/auth) and [Realtime](/docs/web/realtime) works with either client as written.

## Environment variables

| Variable | Where | What |
|---|---|---|
| `NEXT_PUBLIC_PALBASE_URL` | Build, browser and server | The environment's address, `https://<ref>.palbase.studio`. Read by the browser's client and by the server. |
| `NEXT_PUBLIC_PALBASE_PUBLISHABLE_KEY` | Build, browser and server | The publishable key, `pb_<ref>_c…`. Public by design. |
| `PALBASE_SECRET_KEY` | Server only | A secret key, `pb_<ref>_s…`, from Studio's Settings › API keys. Never `NEXT_PUBLIC_`. |

A `NEXT_PUBLIC_` value is built into the bundle, so the address and the key are fixed at build time: build once per environment.

## Related

- [Overview](/docs/web/overview) — the client, and what the project's address answers a browser
- [Auth](/docs/web/auth) — the flows, and the pages auth's emails link to
- [Realtime](/docs/web/realtime) — channels over the project's socket
- [Uploads](/docs/web/uploads) — sending a file to a signed URL
- [Server SDK](/docs/server/overview) — `createServer` and the secret key



<!-- ===== ios/overview ===== -->

# iOS SDK

Palbase's iOS SDK is Swift. Its core product, `Palbase`, holds the project's address and publishable key, the transport every call goes through, the signed-in user's session, the realtime socket and the person's consent, with auth in it. Every other module is a product of its own that the app links or leaves out: an app that sends no push carries none of push's code.

The SDK is distributed compiled, as binary XCFrameworks, from [github.com/palgroup/palbase-swift](https://github.com/palgroup/palbase-swift). It needs **iOS 18** and **Xcode 16** or newer, and its API is Swift 6 concurrency throughout: `async` calls, `Sendable` types, and observable state for SwiftUI.

## Quick example

```swift
import Palbase
import SwiftUI

/// The app's one client: the environment its build configuration names.
let pb = PalbaseClient(.environment)

struct RootView: View {
    var body: some View {
        // Drawn again on every sign-in and sign-out.
        if let user = pb.auth.state.user {
            Text("Signed in as \(user.email ?? user.id)")
        } else {
            Button("Sign in") {
                Task { _ = try? await pb.auth.signIn(email: "ada@example.com", password: "correct-horse-battery-staple") }
            }
        }
    }
}
```

`.environment` is not typed by you: `palbase apps:sync` writes it, and the build compiles in the one its configuration names (below).

## Install

In Xcode, **File › Add Package Dependencies…**, enter `https://github.com/palgroup/palbase-swift`, and add the products the app uses to its target. In a `Package.swift`:

```swift
.package(url: "https://github.com/palgroup/palbase-swift", from: "0.4.0")
```

| Product | What it is |
|---|---|
| `Palbase` | The core: configuration, transport, session, [auth](/docs/ios/auth), the realtime socket, [consent](/docs/ios/consent). Every app links it. |
| `PalbaseFlags` | [Feature flags](/docs/ios/flags), kept live. |
| `PalbaseAnalytics` | [Events, screens, the person's properties](/docs/ios/analytics), timings and reports, as the person allowed. |
| `PalbaseRealtime` | [Channels](/docs/ios/realtime): broadcasts and a state the members share. |
| `PalbaseNotify` | [Push](/docs/ios/notifications): this install's token, preferences, topics, the inbox, in-app messages. |
| `PalbaseNotificationService` | The app's notification service extension: each push reported delivered, its picture shown. |
| `PalbaseStorage` | [Files](/docs/ios/storage): uploads and downloads at URLs your backend signs. |
| `PalbasePurchases` | [Buying in the App Store](/docs/ios/purchases), and what the signed-in customer has bought in any store. |
| `PalbaseUI` | The renderer of the screens a project designs (paywalls, in-app messages, inbox cards), in SwiftUI. The two products below bring it. |
| `PalbasePurchasesUI` | The paywall the project publishes, drawn natively. |
| `PalbaseNotifyUI` | In-app messages shown over the app, and the person's inbox, drawn natively. |
| `PalbaseDebug` | The [in-app debug console](/docs/ios/debug-console)'s screens. |
| `Palbe` | What the [backend clients](/docs/ios/backend-calls) `palbase apps:sync` generates compile against. Link it when the project has a backend. |

A chat's live voice is a package of its own, [palbase-swift-voice](https://github.com/palgroup/palbase-swift-voice), because it brings WebRTC: see [Voice](/docs/ios/voice).

## Connect the app to the project

The app never holds a URL or a key you type. The CLI writes each environment's settings into the app's repository, and the Xcode build compiles in the environment its configuration names. Debug can build against `staging` and Release against `main`, the project's first environment and its production one, from one source tree.

**1. Register the app**, once per project, with its Apple team, and give it its bundle in each environment it runs in:

```sh
palbase apps:create ios "Shop" --slug shop --team-id ABCDE12345
palbase apps:env:set shop --bundle com.example.shop -E staging
palbase apps:env:set shop --bundle com.example.shop -E main
```

The team is the 10 characters under **Apple Developer › Membership**. The app's widgets and extensions are not apps of their own: they share its sign-in. See [`apps:create`](/docs/cli/reference#palbase-appscreate) and [`apps:env:set`](/docs/cli/reference#palbase-appsenvset).

**2. Write its settings into the repository**, from the repository's root:

```sh
palbase apps:sync shop
```

It writes `palbase/` and nothing outside it:

| File | What it holds |
|---|---|
| `palbase/environments/<env>/shop.json` | The environment's client document: its address, the app's publishable key, the keychain group, auth's passkey domain, the backends' addresses. |
| `palbase/environments/<env>/contracts/<machine>.openapi.json` | Each backend's contract, as its machine serves it. |
| `palbase/shop.palbase` | Each environment's Swift: `PalbaseConfiguration.environment` and every backend's typed client (`pb.<name>`). |
| `palbase/project.json` | The checkout's project and its apps. |

Commit them. Run `palbase apps:sync` again when the project changes (a new environment, a backend's routes); `palbase apps:sync --check` exits 1 in CI when the committed files are not what the project gives now. `palbase apps:sdkconfig shop` prints the client document without writing anything. See [`apps:sync`](/docs/cli/reference#palbase-appssync).

**3. Set up the Xcode project.** Three steps, no plugin, and nothing reaches the network at build time:

1. Add `palbase/shop.palbase` to the **Compile Sources** of every target that uses Palbase: the app, and each widget or extension.
2. In each of those targets, **Build Rules › +**: *Source files with names matching* `*.palbase`, *Custom script* with the script below, and one output file, `$(DERIVED_FILE_DIR)/$(INPUT_FILE_BASE)-palbase.swift`. Leave *Run once per architecture* off. The script reads only its input, so it runs under Xcode's user script sandboxing.
3. Add a user-defined build setting, `PALBASE_ENVIRONMENT`, on every build configuration, its value the environment's slug: `staging` for Debug and `main` for Release, as the project names them.

```sh
[ -n "${PALBASE_ENVIRONMENT:-}" ] || { echo "error: Palbase: the build configuration $CONFIGURATION names no environment: set PALBASE_ENVIRONMENT"; exit 1; }
plutil -extract "environments.$PALBASE_ENVIRONMENT.swift" raw -o "$SCRIPT_OUTPUT_FILE_0" "$INPUT_FILE_PATH" || { echo "error: Palbase: no environment $PALBASE_ENVIRONMENT in $INPUT_FILE_NAME (run palbase apps:sync)"; exit 1; }
```

A configuration that names no environment, or one the app is not set in, stops the build with that message.

**4. Give the targets their capabilities**, from what the client document names:

| Capability | Value | Who needs it |
|---|---|---|
| **Keychain Sharing** | the document's `keychain_group` without its team prefix (`com.example.shop.palbase`; Xcode adds `$(AppIdentifierPrefix)`) | The app and every extension that uses Palbase: they share the session, the device's key, the install and the consent choices through it. |
| **Associated Domains** | each entry of `auth.associated_domains` (`webcredentials:<ref>.palbase.studio`) | An app that signs in with [passkeys](/docs/ios/auth#passkeys). |
| **Push Notifications** | — | An app that registers for [push](/docs/ios/notifications). |

## The client

```swift
import Palbase

let pb = PalbaseClient(.environment)
```

Make one client for the app and keep it: every module hangs off it (`pb.auth`, `pb.flags`, `pb.notify`, …), made once on first use and sharing its transport and its socket. A module's property exists once its product is imported: `pb.flags` needs `import PalbaseFlags`.

| Member | What it is |
|---|---|
| `pb.auth` | Sign-in, the session and the user: [Auth](/docs/ios/auth). |
| `pb.consent` | What the person allowed, key by key: [Consent](/docs/ios/consent). |
| `pb.socket` | The project's one realtime socket, opened the first time a channel is joined. `pb.socket.status.state` is observable: `idle`, `connecting`, `connected`, `reconnecting`, `disconnected`. |
| `pb.installation` | This install of the app: `id`, which push, consent and analytics name it by. |
| `pb.debug` | The [debug console](/docs/ios/debug-console)'s recording. |
| `pb.configuration` | The configuration it was made with: `url`, `publishableKey`, `environmentInfo` (`ref`, `slug`, `name`, `production`), `backends`. |
| `pb.currentSession()` | The session now, or `nil`. |
| `pb.setPreferredLanguages(_:)` | The languages every request says (`Accept-Language`), when the app has a language setting of its own; `nil` for the device's. Auth's emails, flag and paywall rules and a backend's translations read them. |

`PalbaseClient(_:sessionStorage:retry:)` takes two more settings. `sessionStorage: .memory` keeps the session in this process alone instead of the keychain. `retry:` is a `RetryPolicy` (below).

### What the app adds to the configuration

The generated `.environment` holds what the project says. What is the app's own is added with `with(consent:analytics:appGroup:)`:

```swift
import Palbase

let pb = PalbaseClient(try! .environment.with(
    consent: ConsentOptions(start: ["analytics": .granted, "performance": .granted], textVersion: "2026-10"),
    analytics: AnalyticsOptions(appBackground: false),
    appGroup: "group.com.example.shop"
))
```

- `consent`: what the app starts with until the person chooses, and the version of the text its consent screen shows ([Consent](/docs/ios/consent)).
- `analytics`: which of analytics' own events it makes ([Analytics](/docs/ios/analytics#the-apps-own-events)).
- `appGroup`: the app group the app shares with its notification service extension, where the extension leaves a report it could not send ([Notifications](/docs/ios/notifications#the-notification-service-extension)).

A configuration given in code, for a test or a tool, is `PalbaseConfiguration(url:publishableKey:keychainGroup:backends:passkeyRelyingParty:consent:analytics:appGroup:)`. The address must be `https` (plain `http` only for `localhost`) and the project's origin alone, and the key must be the publishable one (`pb_<ref>_c…`): a secret key is refused with a `ConfigurationError`, because it never goes in an app.

## The session

The session is kept in the keychain, readable after the device's first unlock and never moved to another device, in the group the app shares with its extensions: a widget or a notification service extension reads the same signed-in user. The access token is renewed ahead of its end while the app is in the foreground, and a call refused for a dead token is renewed once and sent again, only for the user whose session sent it.

A sign-in is sent with a proof made by a key that is created on the device and kept in its keychain. A session the project binds to that key (DPoP, RFC 9449) is sent with a fresh proof on every call that carries its token, to the project and to your backend alike, so a token copied off the device opens nothing on its own. Nothing in the app's code changes for it.

## Errors

A module's call that fails throws a `PalbaseError`:

| Field | What it is |
|---|---|
| `status` | The HTTP status; `0` when no answer came, or the refusal was made on the device. |
| `code` | A stable code: the server's (`invalid_credentials`, `rate_limited`, …) or the client's (`network_error`, `timeout`, `passkey_cancelled`, …). |
| `message` | What happened, in English, for a log. |
| `op` | The operation that failed, as the contract names it (`Login`, `GetMe`). |
| `requestId` | The request's id, when the server answered: the line to find in Studio's Logs. |
| `retryAfter` | The seconds the server asked to wait, when it did. |
| `body` | The refusal's body as sent, as `JSONValue`. |
| `isNetworkError` | True when the request was never answered (no network, the host unreachable, no answer in time). Ask this rather than `status == 0`. |

```swift
import Palbase

func signIn(email: String, password: String) async -> String {
    do {
        _ = try await pb.auth.signIn(email: email, password: password)
        return "Welcome back"
    } catch let e as PalbaseError where e.isNetworkError {
        return "You are offline"
    } catch let e as PalbaseError where e.code == "invalid_credentials" {
        return "Wrong email or password"
    } catch {
        return "Something went wrong: \(error)"
    }
}
```

A call to your own backend throws its route's typed error instead: see [Calling Your Backend](/docs/ios/backend-calls#errors).

### Retries

A call is sent again only when that cannot do its work twice: a read (`GET`, `HEAD`, `QUERY`), or a write its contract takes an `Idempotency-Key` on, with one key made for the call and carried by every attempt. What is retried is an answer that says "not now" (`429`, `502`, `503`, `504`) and a request that never reached the server, waiting what the server's `Retry-After` asks, or 0.5 s, 1 s, 2 s with jitter when it says nothing. Everything else is the caller's at once.

```swift
import Palbase

// Five attempts, and a Retry-After of up to a minute waited for.
let patient = PalbaseClient(.environment, retry: RetryPolicy(attempts: 5, maxWaitSeconds: 60))
```

The default is `RetryPolicy.default`: three attempts in all, and a `Retry-After` longer than 30 seconds is not waited for (the error goes to the caller). `RetryPolicy.once` sends each call once.

## Related

- [Auth](/docs/ios/auth): sign-in, passkeys, Sign in with Apple, the session
- [Calling Your Backend](/docs/ios/backend-calls): the generated clients and their errors
- [Introduction](/docs/getting-started/introduction): the project's modules, keys and environments
- [CLI reference](/docs/cli/reference#apps): every `apps` command



<!-- ===== ios/auth ===== -->

# Auth

`pb.auth` signs a person in and keeps them signed in. It is in the core product, `Palbase`. Every flow that ends in tokens starts the session, and every call that acts for the user carries it from then on: to the project's modules, to your backend, and on the realtime socket. The flows an app writes most are methods here: email and password, guests, passkeys, Sign in with Apple, Google, second factors, magic links, phone codes, passwords, the user's sessions. Every other client operation of the auth module is reachable, typed, as `pb.auth.api`.

## Quick example

```swift
import Palbase
import SwiftUI

struct SignInView: View {
    @State private var email = ""
    @State private var password = ""
    @State private var problem = ""
    @State private var mfaToken: String?

    var body: some View {
        Form {
            TextField("Email", text: $email).textContentType(.username).textInputAutocapitalization(.never)
            SecureField("Password", text: $password).textContentType(.password)
            Button("Sign in") { Task { await signIn() } }
            Button("Sign in with a passkey") { Task { await passkey() } }
            if let reason = pb.auth.state.sessionEndReason, reason == .userBanned {
                Text("This account is suspended.")
            }
            Text(problem)
        }
    }

    private func signIn() async {
        do {
            switch try await pb.auth.signIn(email: email, password: password) {
            case .signedIn: problem = ""
            case .mfaRequired(let token, _): mfaToken = token // finish with pb.auth.mfa.challenge(...)
            }
        } catch {
            problem = "\(error)"
        }
    }

    private func passkey() async {
        do {
            try await pb.auth.passkeys.signIn()
        } catch let error where pb.auth.wasCancelled(error) {
            // The sheet was dismissed: nothing to show.
        } catch {
            problem = "\(error)"
        }
    }
}
```

## Who is signed in

`pb.auth.state` is an `@Observable` object on the main actor. A SwiftUI view that reads it is drawn again when it changes, with no listener to write:

```swift
import Palbase
import SwiftUI

struct Root: View {
    var body: some View {
        if let user = pb.auth.state.user {
            Text("Hello \(user.email ?? user.id)")
        } else {
            SignInView()
        }
    }
}
```

| Member | What it is |
|---|---|
| `isSignedIn` | Whether someone is signed in. It does not change when the token is refreshed. |
| `userId` | The signed-in user's id, or `nil`. |
| `user` | The user as auth last answered (`AuthAPI.User`: `id`, `email`, `emailVerified`, `isAnonymous`, `roles`, `metadata`, …), or `nil`. |
| `session` | The `Session` (`accessToken`, `refreshToken`, `expiresAt`, `userId`, `user`); it changes with every refresh. Printed or logged, it shows no token. |
| `sessionEndReason` | Why the last session ended without the app signing out: `.expired`, `.revoked`, `.userDeleted` or `.userBanned`; `nil` once someone signs in or the app signs out. |

It holds the session kept on the device from the first frame: the keychain is read when the client is made. It follows a sign-out in another process too, such as the app's widget, and a session that auth ended (the account deleted or suspended, signed out everywhere) is seen within one token's lifetime while the app is in the foreground, even when it makes no call.

Outside SwiftUI:

| Member | What it does |
|---|---|
| `currentSession()` | The session now, or `nil`. |
| `currentUser()` | The user as auth last answered, without a call. |
| `getUser()` | Reads the profile fresh (`GET /auth/me`): `AuthAPI.MeProfile`, with `emailVerified`, `hasPassword`, `hasMfa`, `isAnonymous`, `providers` and `locale`. |
| `refreshSession()` | Renews the session now. |
| `changes` | An `AsyncStream<AuthEvent>` of every change: `.signedIn`, `.tokenRefreshed`, `.userUpdated`, `.signedOut`, `.sessionExpired`. |
| `sessionEndReason()` | The same reason as `state.sessionEndReason`, read from any thread. |

```swift
import Palbase

func followSession() async {
    for await event in pb.auth.changes where event == .sessionExpired {
        let why = await pb.auth.sessionEndReason()
        print("signed out by the project:", why.map { "\($0)" } ?? "unknown")
    }
}
```

When someone signs out, or someone else signs in, the realtime socket closes and every module forgets what it held for the last user: the next user's flags, inbox and purchases are read for them.

## Email and password

```swift
import Palbase

func createAccount() async throws {
    let created = try await pb.auth.signUp(email: "ada@example.com", password: "correct-horse-battery-staple")
    if created.accessToken == nil {
        // The project asks for the address to be confirmed before a sign-in.
        print("check your email")
    }
}
```

`signUp(email:password:locale:)` creates the account (`POST /auth/signup`), and starts the session when the project lets a new account sign in before it confirms its address. `locale` is the language auth writes this user's emails in; with none given, it is the language the app itself is shown in, so an English app on a Turkish phone gets English mail. `signUp(_:)` takes the whole `AuthAPI.SignupRequest`, with its `redirectTo`.

`signIn(email:password:)` (`POST /auth/login`) answers a `SignInResult`: `.signedIn(user)`, or `.mfaRequired(mfaToken:factors:)` when the account has a second factor.

The password rules, and whether an email must be confirmed first, are the project's auth settings: Studio's Auth screens, or [`palbase auth:settings:set`](/docs/cli/reference#palbase-authsettingsset).

### Confirming an email

```swift
import Palbase

func confirm(code: String) async throws {
    try await pb.auth.email.verify(.init(code: code, email: "ada@example.com"))
}

func resend() async throws {
    _ = try await pb.auth.email.resendVerification(email: "ada@example.com")
}
```

`email.verify(_:)` takes the link's `token`, or the `code` with the `email`, as the project sends them.

## Guests

```swift
import Palbase

func continueAsGuest() async throws {
    let guest = try await pb.auth.signInAnonymously()
    print(guest.id, guest.isAnonymous) // a real user id, true
}
```

`signInAnonymously(locale:)` (`POST /auth/anonymous`) makes an account with no email or password and signs it in on this device. Its session is held and renewed like any other, and what the guest buys or writes is theirs. The project turns guests on (the auth setting `anonymous_sign_ins`); off, the call is refused with `403 anonymous_sign_ins_disabled`.

A guest becomes an account, keeping its id, with an address and a password: `pb.auth.api.convertAnonymousUser(body: .init(email:password:))` mails a code to the address (`POST /auth/anonymous/convert`), and `pb.auth.api.verifyAnonymousConversion(body: .init(code:))` confirms it.

## Passkeys

A passkey signs in with Face ID or Touch ID, and nothing is typed. The app needs the **Associated Domains** capability with the `webcredentials:` entry its client document names (`auth.associated_domains` in `palbase/environments/<env>/<app>.json`, `webcredentials:<ref>.palbase.studio`). The project publishes the app at `/.well-known/apple-app-site-association` once its bundle is set in the environment ([`apps:env:set`](/docs/cli/reference#palbase-appsenvset)); Apple caches that file, so a device can take a day to see a change.

```swift
import Palbase

func passkeyAccount() async throws {
    // A new account whose only credential is a passkey, then a sign-in with it.
    switch try await pb.auth.passkeys.signUp(email: "ada@example.com", displayName: "Ada") {
    case .signedIn(let user): print("signed in", user.id)
    case .confirmationRequired(let userId): print("confirm the address first", userId)
    }
}

func addPasskey() async throws {
    // For the signed-in user: the next sign-in is one tap.
    let credential = try await pb.auth.passkeys.register(name: "iPhone")
    print(credential.id, credential.isPasskey)
}
```

| Method | What it does |
|---|---|
| `passkeys.signIn()` | Signs in with any passkey this device, the user's iCloud Keychain or a phone nearby holds for the project: the sheet lists them. |
| `passkeys.signUp(email:displayName:)` | Opens an account with a passkey and no password, then signs in with that passkey. `email` is the account's identifier, an address or a phone number as the project's passkey settings ask, or `nil` when it asks for none (then `displayName` is required). Answers `.signedIn(user)`, or `.confirmationRequired(userId:)` when the project asks for the address to be confirmed before a sign-in. |
| `passkeys.register(name:userName:)` | Adds a passkey to the signed-in account. Auth asks for a recent sign-in (`reauthentication_required` otherwise). `userName` is what the sheet shows, needed only by an account with no address or phone. |

The user's passkeys are listed with `pb.auth.api.webauthnListCredentials()`, renamed with `webauthnRenameCredential(id:body:)` and removed with `webauthnDeleteCredential(id:)`. A sheet the user dismisses throws `passkey_cancelled`; a relying party that is not the one the client document names throws `passkey_relying_party_mismatch`, and running `palbase apps:sync` again fixes it.

## Sign in with Apple and Google

```swift
import Palbase

func apple() async {
    do {
        if case .mfaRequired(let token, let factors) = try await pb.auth.signInWithApple() {
            print("second factor needed", token, factors)
        }
    } catch let error where pb.auth.wasCancelled(error) {
        // The sheet was dismissed.
    } catch {
        print(error)
    }
}
```

`signInWithApple(variant:)` shows Apple's own sheet; `signInWithGoogle(variant:)` opens Google's page in the system's browser sheet and exchanges its code on the device, with no client secret in the app. Each starts the session, or answers `.mfaRequired`. The provider must be on for the project, with a **native client** for this app in Studio's **Auth › Providers**:

| Field | Value |
|---|---|
| Application key | The app's slug (`shop`), as `palbase apps:create` registered it. |
| Platform | `ios` |
| Variant | `release`, or a label of the build's own: the `variant:` the app passes (default `"release"`). |
| Flow | Native OAuth |
| Apple | **Bundle ID**: the app's bundle. The app also needs the **Sign in with Apple** capability. |
| Google | **Bundle ID**, the Google Cloud **iOS Client ID**, and the **Native redirect URI**: a URI whose scheme is that client's iOS URL scheme (`com.googleusercontent.apps.1234-abcd:/oauth2redirect`). |

The SDK signs in with the native client alone. With no native client for the app, platform and variant, or one set up for another bundle than the running app's, the call throws `auth_client_not_configured` or `auth_client_mismatch` before any sheet opens. A sheet the user dismisses throws `oauth_cancelled`; `wasCancelled(_:)` is true for it, for a dismissed passkey sheet and for a cancelled task.

Once the provider has answered, the SDK keeps the answer in the keychain until auth has taken it, and sends it again while the answer is "not now". A sign-in interrupted before then is never finished into a later one: the next sign-in with that provider cancels it.

## Second factors

A sign-in that needs a second factor answers `.mfaRequired(mfaToken:factors:)`, `factors` being among `totp`, `sms`, `email` and `webauthn`. Finish it:

```swift
import Palbase

func finish(mfaToken: String, code: String) async throws {
    try await pb.auth.mfa.challenge(mfaToken: mfaToken, type: .totp, code: code)
}
```

| Method | What it does |
|---|---|
| `mfa.challenge(mfaToken:type:code:)` | Completes the sign-in with a code: `type` is `.totp`, `.sms` or `.email`. |
| `mfa.recovery(mfaToken:code:)` | Completes it with a recovery code. |
| `mfa.sendSmsCode(mfaToken:)`, `mfa.sendEmailCode(mfaToken:)` | Sends the code first, for `.sms` and `.email`. |

For the signed-in user:

| Method | What it does |
|---|---|
| `mfa.enrollTotp()` | Starts a TOTP factor: `secret`, `otpUrl`, a `qrCode` and the `recoveryCodes`, shown once. |
| `mfa.verifyTotp(code:)` | Confirms it with the first code the authenticator shows. |
| `mfa.enrollSms(phone:)`, `mfa.verifySms(code:)` | Adds a phone: auth texts it a code, which confirms it. |
| `mfa.enrollEmail()` | Adds the account's address. |
| `mfa.factors()` | The factors: each one's `id`, `type`, `verified`. |
| `mfa.removeFactor(id:currentPassword:)` | Removes one; it asks for the account's password. |
| `mfa.stepUp(code:)` | Steps the session up to aal2 with the authenticator's code: what a route that answers `stepUpRequired` asks. Returns the session. |
| `mfa.sendStepUpSmsCode()`, `mfa.stepUp(smsCode:)` | The same by text: the first sends the code to the user's SMS factor, the second steps up with it. |
| `passkeys.stepUp()` | The same with one of the account's passkeys: Face ID or Touch ID. |

A step-up keeps the session's refresh token; its refreshes stay at the new level, and a route's `maxAge` counts from the step-up. An email code is not a way up ([Second factors and their strength](/docs/backend/authentication#second-factors-and-their-strength)).

New recovery codes are `pb.auth.api.mfaRegenerateRecoveryCodes()`.

## Magic links and phone codes

```swift
import Palbase

func magicLink(token: String?) async throws {
    if let token {
        try await pb.auth.magicLink.verify(token: token) // the token the email's link carried
    } else {
        try await pb.auth.magicLink.send(email: "ada@example.com")
    }
}

func phone(code: String?) async throws {
    if let code {
        if case .mfaRequired = try await pb.auth.phone.verifyCode(phone: "+905551234567", code: code) {
            print("a second factor is needed")
        }
    } else {
        _ = try await pb.auth.phone.sendCode(phone: "+905551234567")
    }
}
```

A magic link lands where the project's links land ([Where email links land](/docs/web/auth#where-email-links-land)), with its `token` in the query: an app that sends them opens that address as a universal link and passes the token to `verify(token:)`. Phone sign-in must be on for the project (`provider_not_enabled` otherwise); `sendCode(phone:)` texts a code through the project's SMS provider and answers the same whether or not the number has an account.

## Passwords

```swift
import Palbase

func passwords() async throws {
    // Forgot it: the email's link carries a token for confirmReset.
    try await pb.auth.password.requestReset(email: "ada@example.com")

    // Signed in: change it, or add a first one to an account that has none (passkey, guest, social).
    let me = try await pb.auth.getUser()
    if me.hasPassword {
        try await pb.auth.password.change(.init(currentPassword: "old-long-passphrase", newPassword: "a-new-long-passphrase"))
    } else {
        try await pb.auth.password.set(.init(newPassword: "a-first-long-passphrase"))
    }
}
```

`password.confirmReset(token:newPassword:)` finishes a reset with the link's token.

## The user's sessions

```swift
import Palbase

func devices() async throws {
    let list = try await pb.auth.sessions.list()
    for s in list.sessions { print(s.id, s.current, s.userAgent ?? "", s.lastActivity) }
    try await pb.auth.sessions.revokeAll() // signed out everywhere
}
```

`sessions.revoke(id:)` ends one of them.

## Signing out and deleting the account

`signOut()` ends the session on the server (`POST /auth/logout`) and on the device; a failed call still signs out here. If another process of the app (its extension) signed someone else in meanwhile, theirs is the session that ends.

`deleteAccount(password:)` deletes the account (`DELETE /auth/user`) and ends the session. An account with a password gives it (`getUser().hasPassword` says whether it has one): missing or wrong, the call is refused with `401 reauth_required` and the user stays signed in. An account without one is deleted on the strength of its session.

## A session from tokens of your own

`setSession(accessToken:refreshToken:expiresIn:)` starts the session from a token pair the app has from a flow it runs itself, step by step, through `pb.auth.api`.

## `pb.auth.api`

Every client operation of the auth contract, typed, through the session's transport. A few an app reaches for:

| Call | Path |
|---|---|
| `pb.auth.api.updateMe(body: .init(locale: "tr"))` | `PATCH /auth/me` |
| `pb.auth.api.listIdentities()` | `GET /auth/identities` |
| `pb.auth.api.unlinkIdentity(id:)` | `DELETE /auth/identities/{id}` |
| `pb.auth.api.webauthnListCredentials()` | `GET /auth/webauthn/credentials` |

An operation of the contract that needs the secret key cannot be made from an app.

## Proof of work

Auth may answer a sign-up, a sign-in or a code request with a proof-of-work challenge when the address looks like a bot. The SDK solves it on the device and sends the request once more; the app never sees it.

## Related

- [Overview](/docs/ios/overview): the client, the session in the keychain, errors
- [Calling Your Backend](/docs/ios/backend-calls): the user's token on your own routes
- [Web Auth](/docs/web/auth): the same flows in a browser, and where email links land
- [Authentication in your backend](/docs/backend/authentication): how a machine checks the token
- [Test Users](/docs/backend/test-users): accounts made with the secret key



<!-- ===== ios/backend-calls ===== -->

# Calling Your Backend

Your own backend runs on a machine, and an iOS app calls it through a typed client that `palbase apps:sync` generates from the backend's contract: every route is a Swift method with its own request, response and error types, and every call carries the signed-in user's session. The client is compiled into the app with the environment's configuration (`palbase/<app>.palbase`, see [Overview](/docs/ios/overview#connect-the-app-to-the-project)), and it compiles against the `Palbe` product: link `Palbe` in each target that compiles the file.

## Quick example

The backend, a `palbase/backend` app on the machine named `backend`:

```ts
// src/modules/notes/notes.controller.ts
import { Body, Controller, Get, Param, Post, User, z, type UserT } from "palbase/backend";

const CreateNote = z.object({ title: z.string().min(1).max(200) });
type CreateNote = z.infer<typeof CreateNote>;

interface Note {
  id: string;
  owner: string;
  title: string;
}

@Controller("/notes")
export class NotesController {
  private readonly notes: Note[] = [];

  @Post("")
  create(@Body(CreateNote) body: CreateNote, @User() user: UserT): Note {
    const note = { id: crypto.randomUUID(), owner: user.id, title: body.title };
    this.notes.push(note);
    return note;
  }

  @Get("/{id}")
  read(@Param("id") id: string, @User() user: UserT): Note | null {
    return this.notes.find((n) => n.id === id && n.owner === user.id) ?? null;
  }
}
```

The app, after `palbase apps:sync`:

```swift
import Palbase
import Palbe

func addNote(title: String) async {
    do {
        let note = try await pb.backend.notes.create(.init(title: title))
        print("saved", note.id)
    } catch .other(let failure) {
        print("refused:", failure.code, failure.errorDescription ?? "")
    } catch {
        print(error)
    }
}
```

`pb.backend` is the machine named `backend`; `notes.create` is `NotesController`'s `create`. The request is `NotesCreateRequest`, the answer `NotesCreateResponse`, and the call throws `NotesCreateError`, typed.

## The generated client

`palbase apps:sync` reads each backend's contract, the OpenAPI document its machine serves, and writes the client into `palbase/<app>.palbase` for every environment the app is set in. Run it again when the backend's routes change: a route the backend no longer has, or a field it no longer takes, is then a compile error in the app.

| What the backend has | What the app calls |
|---|---|
| The machine `backend` | `pb.backend`. A machine's name is camelCased (`shop-api` is `pb.shopApi`), unless `palbase apps:sync --as shop-api=shop` names it, the same in every environment. |
| `NotesController` | `pb.backend.notes`: the class's name without `Controller`, its first letter lowercased. |
| Its method `create` | `pb.backend.notes.create(…)` |
| A path parameter `{id}` | An argument: `read(id: "n_1")` |
| A `@Body` | The request type, first and unlabelled: `create(.init(title: "Milk"))` |
| `@QueryParams` | A `query:` argument of its own type |
| The method's return | The response type, decoded. A route that answers `204` returns nothing. |

The types are named by the route's operation: `NotesCreateRequest`, `NotesCreateResponse`, `NotesCreateError`, `NotesReadResponse`. Everything is `Codable` and `Sendable`. The names the client gives backends never collide with the client's own (`auth`, `flags`, `storage`, …): `apps:sync` refuses one that would.

A backend the environment does not name is not a build error: each of its calls throws `.transport`, saying which backends the environment has.

## What a call carries

| | |
|---|---|
| The user | The signed-in user's access token, when there is one; nothing when no one is signed in, and the route says whether it needs one ([Authentication](/docs/backend/authentication)). A session bound to the device's key is sent with its proof. The publishable key is not sent: a machine asks for none. |
| A dead token | Refreshed once and the call sent again, only for the user whose session sent it. |
| "Not now" | A read (`GET`, `QUERY`) answered `429`, `502`, `503` or `504`, or never answered, is sent again after the server's `Retry-After`. A write is sent again only when the backend keeps its idempotency key (its contract declares the header); otherwise a write that reached the backend before its answer was lost could be done twice. |
| Languages | `Accept-Language`: the device's, or what `pb.setPreferredLanguages(_:)` named. A backend's `t()` reads it ([Translations](/docs/backend/translations)). |
| Redirects | Never followed: the user's token stays with the backend's own address. |
| Encrypted fields | A field the route marks `encrypted()` is sealed before the call leaves the device, and one it answers through `encrypt()` is opened when the answer arrives: the client `palbase apps:sync` wrote holds the project's id and signing key for it ([Encrypted Requests](/docs/backend/request-encryption)). A call sent again is the same sealed request. |

A path parameter is sent as exactly one path segment, percent-encoded. A value that would not stay one however a server reads it (empty, `.` or `..`, or one that hides them between slashes, `a/../b`) is refused before anything is sent, as `.encode`.

## Errors

A generated method throws its own error type, so a `do`/`catch` switches on named outcomes:

```swift
import Palbase
import Palbe

func read(_ id: String) async -> String {
    do {
        let note = try await pb.backend.notes.read(id: id)
        return note.title
    } catch .other(let failure) {
        switch failure {
        case .unauthorized: return "Sign in again"
        case .validation(let v): return v.fields.map { "\($0.field): \($0.message)" }.joined(separator: "\n")
        case .rateLimited(let r): return "Try again in \(r.retryAfter ?? 1) s"
        case .network: return "You are offline"
        case .server(let s): return "\(s.code) (\(s.requestId ?? "no request id"))"
        default: return failure.errorDescription ?? "Something went wrong"
        }
    } catch {
        return "\(error)"
    }
}
```

A code the route's contract declares is a case of its own (`NotesCreateError.forbidden` for a route that declares `403 forbidden`); every other failure is `.other(BackendError)`. `BackendError` is the backend's error envelope, classified:

| Case | When |
|---|---|
| `.server(ServerFailure)` | The backend refused: `code`, `status`, `message`, `requestId`, `details` and `data`, the error's payload (`decodeData(_:)` reads it as a type of yours). |
| `.validation(ValidationFailure)` | `400`, the input failed the route's schema: `fields`, each a `field` and its `message`. |
| `.rateLimited(RateLimitInfo)` | `429`, the route's limit: `retryAfter` in seconds. |
| `.unauthorized(AuthFailure)` | `401`, after the client already refreshed the token once. |
| `.stepUpRequired(StepUpFailure)` | `401 insufficient_user_authentication`: the route asks for a stronger sign-in (`acrValues`, e.g. `["aal2"]`; `maxAge`). The session is fine and is not refreshed: step the user up with their second factor — `pb.auth.mfa.stepUp(code:)` with an authenticator code, `pb.auth.mfa.stepUp(smsCode:)` after `sendStepUpSmsCode()`, or `pb.auth.passkeys.stepUp()` with one of the account's passkeys — then call again (`maxAge` counts from the step-up); the session holds the aal2 token from then on, refreshes included. |
| `.appAttestRequired(AuthFailure)` | `401 app_attest_required` the device's proof could not settle: the SDK enrolled, proved and sent the call again, and the backend still refused ([Device attestation](#device-attestation)). |
| `.attestationUnavailable(AttestationFailure)` | The route asks for the device's proof and this device cannot give one now: `reason` says why (`unsupported_device`, a Simulator or hardware without App Attest; `enrolment_rate_limited` with `retryAfter`; `app_attest_not_configured`, no iOS app registered). Nothing more is sent. |
| `.network(TransportFailure)` | No answer: no network, the connection lost, a timeout. |
| `.transport(TransportFailure)` | Not sent: a backend the environment does not name. |
| `.decode(CodecFailure)`, `.encode(CodecFailure)` | The answer is not the type the contract declares; the input could not be encoded, or a path parameter is not one segment. |

`code`, `statusCode`, `requestId` and `failure` (the envelope, whichever case it is) are on every `BackendError`. The `requestId` is the line to look for in the machine's logs ([Builds, Logs & Rollback](/docs/machines/builds)).

## Device attestation

A route the backend marks `attest: true` is called only by your app on a genuine iPhone or iPad ([Device attestation](/docs/backend/authentication#device-attestation)). The SDK proves each call by itself with Apple's App Attest:

- once per install it makes an App Attest key and enrols it: auth checks Apple's attestation of it for your registered app (team and bundle);
- each call to the backend then carries an assertion over the call's method, path, body and a short-lived challenge, with the key's counter, so a captured call cannot be sent again or changed;
- a `401 app_attest_required` is answered by itself: enrol if needed, prove, send once more.

What only you set: Xcode's **App Attest** capability on the app target. It writes `com.apple.developer.devicecheck.appattest-environment` = `development`, Apple's sandbox, for a build run from Xcode; a TestFlight or App Store build uses Apple's production environment whatever the value says, so one entitlements file serves Debug and Release. `palbase apps:sync` reminds you when an environment's backend has an attested route. A Simulator cannot attest: under enforce its calls end in `.attestationUnavailable`.

## Files

A route your backend declares as an upload (palbase/backend's `Upload`, with a bucket and a path template) is a generated method that takes the file: `file: PBFileSource`, the route's input, and an `onProgress` closure. The bytes go straight to storage at a URL the backend signs, never through the backend, and the method returns what the route's handler answered once the file is stored.

```swift
import Foundation
import Palbase
import Palbe

func setAvatar(_ png: Data) async throws {
    // posts.photo: an upload route of PostsController, with a path parameter.
    _ = try await pb.backend.posts.photo(postId: "p_1", file: .data(png, contentType: "image/png")) { progress in
        switch progress.phase {
        case .authorizing: print("starting")
        case .uploading: print("\(Int(progress.fraction * 100))%")
        case .processing: print("the backend is handling it")
        }
    }
}
```

`PBFileSource.url(_:filename:contentType:)` streams a file from disk; `.data(_:filename:contentType:)` sends bytes in memory, its type read from the bytes when none is given (a photo from `PhotosPicker` is HEIC, PNG or JPEG). The type matters: storage holds every upload to its bucket's types and size. `BackendUploadProgress` says the `phase` (`authorizing`, `uploading`, `processing`), `sentBytes`, `totalBytes` and `fraction`. The upload route's own name and arguments are your backend's; the example's are an illustration.

To store a file the app has without a route of its own for it, see [Storage](/docs/ios/storage).

## Gateways

A backend's gateways, its realtime channels, are in the same client: `pb.backend.join(RoomGateway(roomId: "42"))`. See [Gateways](/docs/ios/gateways).

## Calls the contract does not type

`call(_:_:as:method:headers:)` calls a route by its path with an `Encodable` input and a `Decodable` answer, and `call(_:as:method:headers:)` one with no input; the method is `POST` unless `method:` says otherwise. It throws `BackendError`.

```swift
import Palbase
import Palbe

struct Ping: Decodable, Sendable { let ok: Bool }

func ping() async throws -> Bool {
    let pong: Ping = try await pb.backend.call("health/ping", method: .get)
    return pong.ok
}
```

## A backend on your computer

`palbase apps:sync --backend ../server` generates the client from a backend checkout on this computer, before any machine serves its routes: its `palbase/backend` app writes its contract and exits, and nothing is connected to. `pb.palbe(url:)` is a client of a backend at an address of its own, such as `http://localhost:8080` in the simulator, for its untyped calls and its gateways; the address must be `https`, or `http` on `localhost`.

## Related

- [Overview](/docs/ios/overview): setting up the app, `apps:sync` and the build
- [Gateways](/docs/ios/gateways): a backend's realtime channels, and chats
- [Controllers & Routing](/docs/backend/controllers): the routes the client is made from
- [Responses & Errors](/docs/backend/errors): the error envelope a refusal is read from
- [`apps:sync`](/docs/cli/reference#palbase-appssync): its flags



<!-- ===== ios/gateways ===== -->

# Gateways

Your backend's [gateways](/docs/backend/gateways) are its realtime channels, and an iOS app joins them through the client `palbase apps:sync` generates ([Calling Your Backend](/docs/ios/backend-calls)). `pb.backend.join(RoomGateway(roomId: "42"))` returns once the backend let the signed-in user in, with a handle: the gateway's events arrive on it as a Swift enum, and its messages go out through it, each answered with the backend's ack. The app writes no channel name, event name or payload type of its own, and a gateway that carries a chat holds the chat's state for SwiftUI.

## Quick example

The backend's `RoomGateway` ([Gateways](/docs/backend/gateways#quick-example)): its pattern `room:{roomId}`, the events `message` and `welcome`, and the message `say`, answered with the new message's id.

```swift
import Palbase
import Palbe

func enterRoom(_ roomId: String) async {
    do {
        // Throws PBGatewayError.unauthorized when the backend does not let this user in.
        let room = try await pb.backend.join(RoomGateway(roomId: roomId))

        let listener = await room.on { event in
            switch event {
            case .message(let m): print("\(m.from): \(m.text)")
            case .welcome(let w): print("\(w.members) in the room")
            }
        }

        // The ack the backend's @Subscribe returned, as the message's case.
        if case .say(let said) = try await room.send(.say(.init(text: "hello"))) {
            print("taken as", said.id)
        }

        // When the screen goes:
        await room.off(listener)
        await room.leave()
    } catch let e as PBGatewayError {
        print("not taken:", e.reason) // the backend's own word, or the platform's: forbidden, unavailable, …
    } catch {
        print(error)
    }
}
```

## The generated types

Each gateway of the backend is a struct named by its class, `RoomGateway`, made with a value for each `{param}` of its pattern: `RoomGateway(roomId: "42")` is the channel `room:42`. Inside it:

| Member | What it is |
|---|---|
| `Event` | The events it sends, one case each, with its payload type: `.message(RoomGatewayMessageEvent)`, `.welcome(RoomGatewayWelcomeEvent)`. |
| `Send` | The messages a member may send: `.say(RoomGatewaySayMessage)`. |
| `Reply` | The acks, one case per message: `.say(RoomGatewaySayReply)`. |
| `pattern`, `durable`, `topic` | Its pattern, whether it keeps what it sends, and the channel this value names. |

An event the generated code does not know, from a backend that moved ahead of the app, is not delivered. Run `palbase apps:sync` again when the backend changes a gateway: a payload it no longer takes is then a compile error.

## Joining

`join(_:history:)` takes the generated value, opens the project's socket if it is not open, and returns a `GatewayHandle` once the backend let the user in. A param that is empty or holds a `:` would name another channel, and is refused before anything is sent (`invalid params`).

| Member of the handle | What it does |
|---|---|
| `on(_:)` | Listens to every event the gateway declares, as its `Event` enum. Returns a token. |
| `off(_:)` | Stops the listener the token names. |
| `send(_:)` | Sends one message and waits for the backend to take it: returns its `Reply`, or throws `PBGatewayError`. |
| `leave()` | Drops the handle's listeners and lets go of the channel. |
| `topic` | The channel: `room:42`. |
| `seq` | A durable gateway's number of the last event the handle was sent; `nil` on one that keeps nothing. |
| `chat` | A chat gateway's chat: see [Chat gateways](#chat-gateways). |

`GatewayHandle` is an actor: its methods are awaited. Hold a handle for as long as its screen is on screen, and leave it when the screen goes (`.onDisappear`, or the end of a `.task`): a gateway with members is one its backend still runs for. Two handles of the same channel share one membership, and the channel is left with the last of them.

Only a signed-in user joins: the session the socket carries is who they are. The socket is one person's, and it closes when someone signs out or someone else signs in.

## Messages and acks

`send(_:)` returns what the backend's `@Subscribe` returned, as the message's `Reply` case. It throws `PBGatewayError`, whose `reason` says why the message was not taken:

| `reason` | What it means |
|---|---|
| The backend's own word | Its method threw `GatewayRefusal("…")`: `no_commands`, `not_your_turn`. Act on it. |
| `forbidden` (`.forbidden`) | The user may only listen on this channel, or the platform refused with no reason given. |
| `rate_limited` (`.rateLimited`) | Past the project's events per second. |
| `unavailable` (`.unavailable`) | The backend could not be asked just then. Worth trying again. |
| `no reply`, `socket closed` | No answer came. The message may have been taken. |
| `not joined` (`.notJoined`) | Nothing was sent: the handle was left, its socket closed for good, or the socket is being opened again. |
| `undecodable reply` | The backend took it, but its ack is not what the app's generated code reads: run `palbase apps:sync`. |

A join that is refused throws too: `unauthorized` when the backend did not let the user in, `unavailable` when it could not be asked (worth trying again). The values are static members of `PBGatewayError` to compare with: `catch let e as PBGatewayError where e == .unauthorized`.

A message goes to the backend alone, never to the other members. They hear what the backend emits.

## Durable gateways

A [durable gateway](/docs/backend/gateways#durable-gateways) keeps what it sends. A handle that joins one is sent what it keeps first, in order, then what comes after; `join(_:history: false)` asks for only what comes after the join. The channel's first handle decides: a second handle of the same channel gets the events from where it joins.

When the socket drops, it is opened again by itself and every gateway joined again; a durable one after its `seq`, so the handle is sent what it missed, in order, and nothing twice. Meanwhile `send` throws `not joined`. When the socket closes for good (a sign-out, another user's sign-in) every handle on it ends: its listeners are dropped, and `send` throws `not joined`. Join again as the user who is there now.

## Chat gateways

A gateway declared with `chat: true` carries a chat of the project's agents, which the platform writes into its channel ([AI](/docs/backend/ai#a-chat-in-an-app)). Its handle's `chat` is a `PBChat`, the chat's state folded from what the platform writes: from the chat's start, since the channel keeps it, and then each change as it comes. In SwiftUI, hold it as a `PBChatModel`, an `@Observable` on the main actor:

```swift
import Palbase
import Palbe
import SwiftUI

struct SupportChat: View {
    let chatId: String
    @State private var support: GatewayHandle<SupportGateway>?
    @State private var chat: PBChatModel?
    @State private var text = ""

    var body: some View {
        List {
            if let chat {
                ForEach(chat.state.items) { item in
                    switch item {
                    case .message(let m): Text(m.text).frame(maxWidth: .infinity, alignment: m.mine ? .trailing : .leading)
                    case .response(let r): Text(r.text)
                    case .goal, .voice: EmptyView()
                    }
                }
                TextField("Message", text: $text)
                Button("Send") {
                    Task { _ = try? await support?.send(.say(.init(text: text))); text = "" }
                }
            }
        }
        .task {
            guard let joined = try? await pb.backend.join(SupportGateway(chatId: chatId)) else { return }
            support = joined
            chat = PBChatModel(joined.chat)
        }
        .onDisappear { Task { [support] in await support?.leave() } }
    }
}
```

`SupportGateway` and its `say` message are the backend's own, as [AI](/docs/backend/ai#a-chat-in-an-app) declares them. What the member does in the chat goes through the gateway's messages, and the backend does it as them: `say`, `decide` (an approval's yes or no), `answer` (a client tool's output) and `stop`.

| Member of `PBChat` | What it is |
|---|---|
| `state` | The chat now: the same value until something changes. |
| `onChange(_:)` | Told each time the state changes; a burst of parts is one change. Returns what stops it. |
| `updates` | An `AsyncStream` of the state now, then each change (the newest, for a reader that falls behind), until the gateway is left. |
| `hasOlder`, `loadOlder(_:chatId:limit:)` | The channel keeps a day of the chat. `loadOlder(pb, chatId:)` reads the page before what the state holds, with the member's own session (the project's AI settings let its users' sessions reach their chats: `clients`), and folds it in front; it returns whether there is more, `false` once a page reached the chat's start. `loadOlder(limit:load:)` reads the page through your backend instead: `load` is given a `PBChat.PartsQuery` and returns a `PBChat.PartsPage`. |

What `state` holds:

| Field | What it is |
|---|---|
| `items` | The conversation in order, an `Item` each: `.message(Message)`, `.response(Response)`, `.goal(GoalEvent)` and `.voice(VoiceEvent)`. Each has an `id` for `ForEach`. A subagent's answer is a part of its parent's. |
| `messages` | Each member's (or the server's) message: `clientId`, `id`, `text`, `author` (`nil`: the server), `authorName`, `status` (`.pending` until the agent has it, then `.delivered`, or `.failed` with its `error`), `kind` (`.text`, or `.voice` for a line said in the chat's voice), `attachments`, `metadata`, `createdAt`, and `mine`. |
| `responses` | Each answer, the subagents' too: `id`, `status` (`running`, `waiting`, `completed`, `failed`, `canceled`, `timed_out`, `budget_exceeded`), `end` and `error` once it ended, `text` so far, `parts`, `thinking`, `goal`, `startedBy`, and `mine`. |
| `turn` | The last turn's state: its `status`, and in `waiting.reason` what it waits for: `approval`, `tool_output`, `subagents` or `message`. |
| `waiting` | What waits for the signed-in user: `approvals`, the tool calls of their own turns waiting for their yes, and `outputs`, their client tool calls waiting for the app's answer. |
| `goal` | The chat's goal once one was set: `objective`, `status`, its stop code and reason, and its `events`. |
| `voice` | The chat's live voice, the last that began, live or ended: `status` (`started`, `closed`), `mine`, `seconds`, `closeReason`. See [Voice](/docs/ios/voice). |
| `forkedFrom` | A fork's: the `chatId` it was forked from and the message it was cut before. |

An answer's `parts` are its pieces in order: `.text(String)`, `.tool(Tool)` (a tool call: `callId`, `name`, `status`, `input`, `output`, and `approvalId` while it waits for a yes), `.agent(Agent)` (a subagent handed work) and `.thinking(Thinking)` (a step's reasoning, when the agent shows it). A tool call's `output` is its last 16 KiB, `omittedBytes` how much came before; `pb.chatToolCall(chatId:callId:)` reads the whole answer.

A picture or a file a message carries is read back with `pb.chatAttachment(chatId:message:_:)`, as `Data` of the attachment's `contentType`. A file is attached by your backend, which sends the message naming it. Both reads go with the member's own session, as `loadOlder(pb, chatId:)` does.

`PBChat(parts:me:)` makes a chat from parts you give it, through the same fold: what a SwiftUI preview or a test shows a chat with.

## Related

- [Calling Your Backend](/docs/ios/backend-calls): the generated client the gateways are in
- [Gateways in your backend](/docs/backend/gateways): patterns, who may join, events, messages, durable gateways
- [AI](/docs/backend/ai): the chats a chat gateway carries
- [Realtime](/docs/ios/realtime): the project's channels, and the socket they share
- [Voice](/docs/ios/voice): a chat's live voice



<!-- ===== ios/realtime ===== -->

# Realtime

`pb.realtime` (the `PalbaseRealtime` product) is the project's channels on its one realtime socket: what members broadcast, and a state every member sees the same. The socket, `pb.socket`, is in the core: it opens the first time a channel is joined and never before, so an app that only signs in or captures analytics opens none. Flags' live updates, consent and your backend's [gateways](/docs/ios/gateways) ride the same socket.

> **Note:** Your own backend's realtime channels are its [gateways](/docs/ios/gateways), joined through the client `palbase apps:sync` generates: typed events, and messages the backend answers with an ack. This page is the channels the project declares by name.

## Quick example

```swift
import Palbase
import PalbaseRealtime

func follow(roomId: String) async throws {
    let room = pb.realtime.channel("room:\(roomId)")

    let stopMessages = await room.onBroadcast("message") { payload in
        if case .string(let text)? = payload["text"] { print("message:", text) }
    }
    room.onState { entries in
        print("\(entries.count) here")
    }

    // Throws the server's reason when it does not let the user in.
    try await room.join()

    // Presence: an ephemeral entry lives as long as this connection.
    try await room.set("typing:me", .bool(true), life: .ephemeral)
    try await room.broadcast("message", ["text": .string("hello")])

    // When the screen goes:
    await stopMessages()
    await room.leave()
}
```

Payloads and values are `JSONValue`: `.string`, `.number`, `.bool`, `.object`, `.array`, `.null`, and `decode(_:)` reads one as a `Decodable` type of yours.

## Channels

`pb.realtime.channel(_:)` returns a `RealtimeChannel` for that name. A channel is joined once however many listeners it has.

| Member | What it does |
|---|---|
| `join()` | Joins; returns once the server let the user in, throws its reason when it did not. |
| `leave()` | Leaves, and forgets the state it held. |
| `onBroadcast(_:_:)` | Listens to one event's broadcasts, a member's or the project's server's. Returns what stops it (an `async` closure). |
| `broadcast(_:_:)` | Sends an event to the channel's other members; the sender does not hear its own. The call does not wait for the server: one it refuses comes to `onRefused`. |
| `onRefused(_:)` | Listens to the server refusing a broadcast: `{event, reason}`, with `forbidden`, `rate_limited`, … Returns what stops it. |
| `entries` | The channel's state as the server last told it: `[String: Entry]`, each an `Entry` with its `value` and its `life`. |
| `onState(_:)` | Told the whole state each time it changes. Returns what stops it. |
| `set(_:_:life:)` | Writes one entry. The state changes when the server says so, for every member alike. |
| `deleteOwn(_:)` | Removes one entry this membership wrote: every other entry is its writer's. |
| `name` | The channel's name. |

An entry's `life` is `.durable` (the default), which stays until it is removed, or `.ephemeral`, which is its writer's presence and goes when the writer's connection does. A member that joins is handed the whole state, and each change after it; one that missed a change asks for the whole state again by itself.

Names are `:`-separated segments, 255 bytes at most.

## Who may join

A channel name is a string the app chooses, so being signed in says nothing about which channels are the user's. The project's server **declares** its channels ([Channels](/docs/backend/channels), `PUT /realtime/channels` with the secret key), and a channel no declaration matches belongs to no one:

| Declared `kind` | Who joins |
|---|---|
| `owner` | The pattern's one `{name}` segment is the joining user: `user:{uid}` is joined by that user alone, who may do everything on it. |
| `public` | Any signed-in user of the project, with the rights the declaration gives: `publish` (broadcast), `state_read`, `state_write`. |

A refused join throws the server's reason: `unauthorized`, `forbidden`, `invalid_topic`, `rate_limited`, `too_many_channels`, `state_budget` or `unavailable`. Only `unavailable` is worth trying again. Some namespaces are the platform's, and no declaration can claim them: `flags:<ref>` and `flags:<ref>:<user>` carry [flag](/docs/ios/flags) changes, and the SDK joins them itself.

## The socket

`pb.socket.status` is an `@Observable` on the main actor. A view that reads `state` is drawn again when it changes:

```swift
import Palbase
import SwiftUI

struct ConnectionBadge: View {
    var body: some View {
        let state = pb.socket.status.state
        Label(state.rawValue, systemImage: state == .connected ? "bolt.fill" : "bolt.slash")
    }
}
```

| `state` | What it means |
|---|---|
| `idle` | Never opened: nothing has joined a channel yet. |
| `connecting` | Being opened. |
| `connected` | Open; the channels wanted are joined on it. |
| `reconnecting` | Dropped (the network went, a heartbeat went unanswered), and opened again after a pause. |
| `disconnected` | Closed by the client: someone signed out or in, or no channel is wanted. |

`status.since` is when it last changed, and `status.changes` is an `AsyncStream` of every change in order, where a view reading `state` is drawn with the newest only.

The socket sends a heartbeat every 25 seconds. One that goes unanswered closes the socket, and a socket that drops is opened again after 0.5, 1, 2, 5, 10, then every 30 seconds, each pause jittered, with every channel still wanted joined again. A broadcast sent while the socket was down is not delivered; a channel's state comes back whole with the new join. When the session is refreshed, the new token goes to every joined channel without leaving it.

The socket is one person's. When someone signs in, signs out, or the session ends, the client closes it, and every channel with it, and a channel forgets the state it held. Join again for the user who is there now, for example from `pb.auth.changes` or a SwiftUI `.task(id: pb.auth.state.userId)`.

## Limits

The project holds its clients to limits the platform sets and the project may lower (`PUT /realtime/limits` from a server): connections open at once, broadcasts and state writes per second, joins per second, channels per connection. A project over its connection limit, or whose realtime quota is used up, is refused a new socket.

## Related

- [Gateways](/docs/ios/gateways): your backend's channels, typed, with messages and acks
- [Channels](/docs/backend/channels): declaring who may join what
- [Realtime in your backend](/docs/backend/realtime): broadcasting and writing state from a server
- [Web Realtime](/docs/web/realtime): the same channels in a browser



<!-- ===== ios/messaging ===== -->

# Messaging

`pb.messaging` is the signed-in person's conversations on iOS: their list, each conversation's timeline and its threads, as `@Observable` objects SwiftUI draws, kept in the app's SQLite between launches and current over the project's socket. The app writes; it opens no socket, appends nothing and syncs nothing itself. With the notification service extension, a message that arrives while the app is closed is already on the phone when it opens. What the module is — history, encryption, timers, moderation, prices — is [Messaging](/docs/messaging/overview).

## Install

Add `https://github.com/palgroup/palbase-swift` with Swift Package Manager, at 0.7.2 or later:

- the app's target: `Palbase` and `PalbaseMessaging`;
- the notification service extension's target (below): `PalbaseMessagingNotificationService`.

## Quick example

```swift
import Palbase
import PalbaseMessaging
import SwiftUI

struct Inbox: View {
    let pb: PalbaseClient
    // The person's conversations, the latest first: drawn from the phone at once, then kept current.
    @State private var list: ConversationList?

    var body: some View {
        List(list?.items ?? [], id: \.id) { conversation in
            NavigationLink(conversation.title ?? "Chat") { Chat(view: pb.messaging.conversation(conversation.id)) }
        }
        .navigationTitle("Chats (\(list?.unread ?? 0))")
        .task { list = pb.messaging.conversations() }
    }
}

struct Chat: View {
    let view: ConversationView
    @State private var text = ""

    var body: some View {
        VStack {
            List(view.entries) { entry in
                switch entry {
                case .message(let m): Text(m.text ?? "a file")
                case .pending(let item): Text(item.request.text ?? "a file").foregroundStyle(.secondary) // on its way
                }
            }
            TextField("Message", text: $text)
                .onSubmit {
                    let words = text
                    text = ""
                    // Drawn at once, sent now or when the network is back — once.
                    Task { _ = try? await view.send(words) }
                }
        }
        .onAppear { view.onScreen(true) }
        .onDisappear { view.onScreen(false) }
        .task { try? await view.markRead() }
    }
}
```

`pb.messaging.direct(with: userId)` is the direct conversation with someone (the one there is, or a new one, shown to them with its first message); `group(title:memberIds:)` makes a group. `ConversationView` has `entries`, `members`, `typing`, `hasEarlier` and `loadEarlier()`; `thread(_:)` is a message's thread, `scheduled()` the person's messages for later.

## Writing

`send(_:_:)` takes text, or `SendOptions`: `replyTo`, `threadId` and `alsoInConversation`, `mentions`, `files` (encrypted on the phone before they are uploaded), `expiresIn` with `expiresFrom`, `viewOnce`, and `sendAt` for a message the server sends later. A message waits in the outbox while the phone is offline and goes once it can, once. `edit`, `remove`, `react`, `unreact`, `markRead`, `typing`, `cancelScheduled` and `editScheduled` change what was said; `open(_:attachment:)` downloads and decrypts a file, and a message seen once gives its files by `viewOnce(_:)` alone — held by the app, never by the phone's copy.

## A message while the app is open

A message's push is not drawn as the system's banner while the app is in front: the message is synced, and `incoming()` gives it to the app to draw its own banner. Answer the system with what `Messaging.foregroundPresentation` says:

```swift
import Palbase
import PalbaseMessaging
import UIKit
import UserNotifications

final class AppDelegate: NSObject, UIApplicationDelegate, UNUserNotificationCenterDelegate {
    let pb = PalbaseClient(try! PalbaseConfiguration.environment.with(appGroup: "group.com.example.chat"))

    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        Task { try? await pb.notify.register(apnsToken: deviceToken) }
    }

    func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification,
                                withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
        pb.notify.willPresent(notification)
        // A message's push: none (the app draws its own); any other push: as the app wants.
        completionHandler(Messaging.foregroundPresentation(for: notification, of: pb) ?? [.banner, .sound])
    }
}
```

`incoming()` gives each message someone else wrote that is new to the phone once, whether the socket or the push brought it first — never what a sync or a page read, the person's own messages, or a muted conversation's. `onScreen` is true for the conversation on the screen:

```swift
.task {
    for await m in pb.messaging.incoming() where !m.onScreen {
        banner = m // m.message, m.conversation: draw it; a tap opens pb.messaging.conversation(m.message.conversationId)
    }
}
```

## Messages that arrive while the app is closed

The `PalbaseMessagingNotificationService` extension shows a message's push and, while it does, brings that conversation's new messages into the phone's copy: open the app without a network and they are there.

1. **Add the extension.** *File › New › Target › Notification Service Extension*; give it `PalbaseMessagingNotificationService`, and replace its `NotificationService.swift`:

   ```swift
   import PalbaseMessagingNotificationService

   final class NotificationService: PalbaseMessagingNotificationService {}
   ```

2. **Share the copy and the session.** In *Signing & Capabilities*, give the app and the extension the same:
   - **App Groups**: one group, such as `group.<bundle id>` — where the conversations are kept;
   - **Keychain Sharing**: `<bundle id>.palbase`, the `keychain_group` `palbase apps:sync` writes to the environment's file — where the extension reads the session, and writes it back when it renews it.

   The app alone has **Push Notifications**.

3. **Give the app the group** (above): `PalbaseConfiguration.environment.with(appGroup: "group.<bundle id>")`, so it reads what the extension wrote. The extension reads the app's configuration from the shared keychain: the app must have been opened once.

The extension's `Info.plist` is Xcode's: `NSExtensionPointIdentifier` `com.apple.usernotifications.service`, `NSExtensionPrincipalClass` `$(PRODUCT_MODULE_NAME).NotificationService`. iOS gives an extension about 30 seconds, enough for a conversation's new messages. A muted conversation sends no push: its messages come when the app opens.

## Screenshots

iOS cannot stop a screenshot. A conversation's screen says it is shown (`onScreen(true)` as it appears, `onScreen(false)` as it goes): when a screenshot is taken while it shows a conversation in vanish mode or a message seen once, the others are told. A conversation in vanish mode drops what the person read when they leave it: call `close()` as its screen goes.

## A deleted group

When a group's owner or an admin deletes it — or its last member leaves — it goes from everyone's `conversations()` at once, and those who were in it can still report it for 14 days ([Messaging](/docs/messaging/overview#moderation)). `pb.messaging.deletedGroups()` is `@Observable`: its `items` are the groups the person can still report, the latest to stop first, each with `id`, `title`, `deletedBy` and `reportableUntil`, and one goes at its `reportableUntil`. `report(_:)` names it by its id with no message; the last 30 messages the person saw in it go with the report. A group the project's server deleted is not among them.

```swift
let deleted = pb.messaging.deletedGroups()
for group in deleted.items {
    print(group.title ?? "a group", group.reportableUntil)
}
if let group = deleted.items.first {
    try await pb.messaging.report(.init(conversationId: group.id, reason: .harassment, userId: group.deletedBy))
}
```

The title is the one the device had; it is nil when the device no longer had the group as the word came — on the deleter's own device now and then.

## Signing out

When the person signs out, what the phone kept of their conversations is dropped, unless `pb.messaging.keepOnSignOut` is true — then it is theirs again when they sign back in. Kept or not, no one else who signs in on the phone reads it.



<!-- ===== ios/flags ===== -->

# Flags

`pb.flags` (the `PalbaseFlags` product) holds the project's feature flags and remote configuration as this app's reader sees them: every flag's value resolved by the project for the app's platform, version and language and for whoever is signed in, kept current as the flags change. A read takes no network: it answers from the values held, which are kept on the device between launches, and brings them up to date behind your code. Flags are defined in Studio's flags screens or by a server, never from the app ([Flags in your backend](/docs/backend/flags)).

## Quick example

```swift
import Palbase
import PalbaseFlags
import SwiftUI

struct Checkout: View {
    var body: some View {
        // Drawn again when one of these flags changes: in Studio, the user's own value, another user signing in.
        let flags = pb.flags.state
        VStack {
            Text(flags.string("banner_text", default: "Welcome"))
            if flags.bool("new_checkout", default: false) {
                Text("Up to \(flags.int("cart_limit", default: 20)) items")
            }
        }
    }
}
```

The module starts on first use: the values held on the device are read at once, the latest are fetched for whoever is signed in, and the flags' change channels are joined on the project's socket.

## Reading values

The same reads are on `pb.flags.state`, an `@Observable` on the main actor for SwiftUI, and on `pb.flags` itself, from any thread:

| Member | What it answers |
|---|---|
| `bool(_:default:)` | A boolean flag's value, or the default when there is none or it is not a boolean. |
| `string(_:default:)` | A string flag's value, or the default. |
| `number(_:default:)` | A number flag's value as a `Double`, or the default. |
| `int(_:default:)` | A number flag's value when it is a whole number, or the default. |
| `decode(_:as:)` | An object flag's value as your `Decodable` type, or `nil`. |
| `value(_:)` | A flag's value as `JSONValue`, or `nil` when there is none. |
| `all` | Every flag's value by key. |

A view that reads one flag from `state` is drawn again when that flag's value changes, and only then; a view that reads `all` is drawn again on any change. Every read answers at once. Before the first fetch has answered, the app reads the values it held at its last launch, or the default on its first. Give every read a default the app works with.

On `pb.flags`:

| Member | What it does |
|---|---|
| `source(_:)` | Where a value came from: `system` (the flag's), `override` (the user's own) or `experiment` (an experiment's variant). |
| `version` | The version the values are current as of. |
| `holds(reader:)` | Whether the values held are this user's (`nil`: no one signed in). |
| `onChange(_:)` | Calls the listener with the keys whose values changed. Returns what stops it. |
| `changes` | The same, as an `AsyncStream<Set<String>>`. |
| `refresh()` | Brings the values up to date now, and returns when they are. It throws a `PalbaseError` when the read fails. |

```swift
import Palbase
import PalbaseFlags

struct Theme: Decodable { let accent: String }

func applyFlags() async {
    // Wait for current values before a first screen that depends on them.
    try? await pb.flags.refresh()
    let theme = pb.flags.decode("theme", as: Theme.self)
    print(theme?.accent ?? "default accent", pb.flags.source("theme") ?? "none")

    for await keys in pb.flags.changes where keys.contains("maintenance") {
        print("maintenance is now", pb.flags.bool("maintenance", default: false))
    }
}
```

## A signed-in user's values

The values are one reader's: the signed-in user's, or with no one signed in, this install's, proven with its secret. When someone signs in or out, the values held go, and listeners are told their keys; the new reader's are read, and listeners are told again. One reader's values are never read out to another, even for the moment the new ones take to arrive: a gate on a flag closes for the next user rather than staying open with the last one's value.

## What a value is resolved from

Every read is resolved by the project for its reader, in this order:

1. **The user's own value**, when a signed-in user has one. A server gives users their values with the secret key ([Flags in your backend](/docs/backend/flags#users-own-values)), and so does [`palbase flags:users:set`](/docs/cli/reference#palbase-flagsusersset).
2. **The variant of an experiment** running on the flag, when the reader is one of its people.
3. **The flag's first condition that matches.** Conditions read what the app says about itself, the share of users a percentile picks, the country of the address the request came from, the server's clock, and the analytics audiences the reader is in, when they allowed personalization ([Consent](/docs/ios/consent)).
4. **The flag's default.**

What the app says about itself, with every read:

| Header | Sent as | Read as |
|---|---|---|
| `X-Platform` | `ios` | `client.platform` |
| `X-Palbase-Client-Version` | The app's `CFBundleShortVersionString` | `client.app_version` |
| `X-OS-Version` | The system's version (`18.6.2`) | `client.os_version` |
| `Accept-Language` | The device's languages, or what `pb.setPreferredLanguages(_:)` named | `client.locale`, its first language |
| `X-Palbase-Installation` | `pb.installation.id` | Counted toward which versions of your app are in use. |
| `X-Palbase-Installation-Secret` | The install's secret, with no one signed in | Proves the install, so audiences and experiments can place a reader who is not signed in. |

## Experiments

A value an experiment gave says so: `source(_:)` is `experiment`. When the app reads such a flag by its key (`bool`, `string`, `number`, `int`, `decode` or `value`, on `pb.flags` or `state`), the SDK records the analytics event `$flag_exposure` with `{ flag, experiment, variant }`, once per analytics session for each flag and experiment, through `pb.analytics` while the person allows analytics. That event is what an experiment's results count, so the app links `PalbaseAnalytics` and has used `pb.analytics` once. `all` records none: read a flag in an experiment by its key where the person sees it.

## Keeping up to date

The SDK keeps the values current by itself. The project announces every change on two realtime channels, which it joins on the project's socket:

| Channel | Who may join | What it says |
|---|---|---|
| `flags:<ref>` | Anyone reading the project's flags, with no one signed in too | The project's flags changed. |
| `flags:<ref>:<user_id>` | That user only | That user's own values changed. |

Told of a newer version, the SDK asks for what changed since the one it holds (`GET /flags/delta`). When the delta can no longer bring its values up to date (the reader's context or audiences changed, or the deletions it would need are older than the project keeps), the project answers `410`, and the SDK reads a whole snapshot instead (`GET /flags/snapshot`, sent with the `ETag` of what it holds). A channel the project refuses, with realtime off, still leaves the reads: `refresh()` brings the values up to date.

## The debug console

The flag `palbase.debug_console`, given to one user as their own value, opens the [debug console](/docs/ios/debug-console) for them.

## Related

- [Flags in your backend](/docs/backend/flags): defining flags and giving users their own values
- [Analytics](/docs/ios/analytics): `$flag_exposure`, and the audiences conditions read
- [Realtime](/docs/ios/realtime): the socket the change notices travel on
- [Web Flags](/docs/web/flags): the same flags in a browser



<!-- ===== ios/analytics ===== -->

# Analytics

`pb.analytics` (the `PalbaseAnalytics` product) records what the app's users do, how its screens and requests perform, and its log when something goes wrong, each behind its own consent key: `analytics` for events, screens and the person's properties, `performance` for timings and request traces, `diagnostics` for the log sent with a report. Nothing waits on it: what is collected is held, sent together a few seconds later, and a send that fails is let go. What the project makes of it (people, funnels, retention, audiences) is in Studio's Analytics screens.

## Quick example

```swift
import Palbase
import PalbaseAnalytics
import UIKit

final class AppDelegate: NSObject, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
        // Touched at launch: from here it makes the app's own events ($install, $app_open, …).
        _ = pb.analytics
        return true
    }
}

func checkedOut(total: Double) {
    pb.analytics.capture("checkout_completed", properties: ["total": .number(total), "currency": .string("EUR")])
}
```

Nothing is collected for a key the person has not granted, and nothing for one with no choice and no starting value: give the app's starting values in [Consent](/docs/ios/consent), or ask first.

## Events and screens

| Method | What it does |
|---|---|
| `capture(_:properties:)` | Records an event: a name (a letter or `$`, then letters, digits and `_.:-$`, 64 at most) and its properties. |
| `screen(_:properties:)` | Records a screen the user saw. |
| `identify(traits:)` | Ties this device's anonymous events to the signed-in user, with their traits. It is done by itself after each sign-in. |
| `flush()` | Sends what is held now. |

An event is held for up to 5 seconds, or until 20 are held, and they go together; what is held when the app goes to the background goes then, and what is held when it closes offline is kept on disk and sent at the next launch. With no one signed in, events are an anonymous id's, made the first time one is needed; after a sign-in they are the user's, and the anonymous id's are tied to them. A session is a run of events with no gap of 30 minutes.

## The person's properties

```swift
import Palbase
import PalbaseAnalytics

func onboarded(plan: String) async {
    await pb.analytics.people.set(["plan": .string(plan)])
    await pb.analytics.people.setOnce(["first_seen_plan": .string(plan)])
    await pb.analytics.people.add(["projects_created": 1])
}
```

`people` is the signed-in user, or with no one signed in this device's anonymous id, whose properties become the user's once they sign in. `set`, `setOnce` (only where none is set), `unset` and `add` (to a number) are sent at once, while `analytics` is granted.

## The app's own events

From the moment `pb.analytics` is first touched, it records these by itself, each while `analytics` is granted:

| Event | When |
|---|---|
| `$install` | Once per install, timed at the first launch even when analytics is allowed later. `$reinstall: true` when the keychain kept the install from before the app was deleted; `$apple_ads_token`, Apple's attribution token, while `ads_measurement` is granted. |
| `$app_open` | Each time the app comes to the foreground; `$cold: true` on a launch. |
| `$app_background` | Each time it goes to the background. |
| `$session_start` | Each time a session begins, after 30 minutes without an event. |
| `$app_updated` | When the app's version is not the one it last ran as: `$previous_version`, `$version`. |
| `$timezone` | The person's time zone, a property, set when it is not the one last set. |

Each one can be turned off in the configuration: `PalbaseConfiguration.environment.with(analytics: AnalyticsOptions(appBackground: false))` ([Overview](/docs/ios/overview#what-the-app-adds-to-the-configuration)). An app extension (a widget, a notification service) makes none of them.

## Performance

```swift
import Palbase
import PalbaseAnalytics

func loadFeed() async {
    let trace = pb.analytics.startTrace("feed_load")
    // … load it …
    trace.stop(attributes: ["source": "network"])
    pb.analytics.measure("feed_items", value: 42)
}
```

| Method | What it does |
|---|---|
| `startTrace(_:)` | Starts timing something; the trace's `stop(attributes:)` records how long it took, in milliseconds. |
| `measure(_:value:kind:attributes:)` | Records one measurement. `kind` is `.custom` (the default), `.screen`, `.appStart` or `.network`. |
| `recordRequest(method:endpoint:status:durationMs:requestId:error:)` | Records a request the app made and how it ended. |

They are collected while `performance` is granted. While `analytics` is not, a timing goes with the publishable key alone: no user's token, no person's id, no install's id.

## Diagnostics

`log(_:level:)` keeps a line of the app's log in memory (the last 200, levels `.debug`, `.info`, `.warning`, `.error`), and `report(_:)` sends what it kept as what led to an error: `.error` (the default), `.crash` or `.userReport`. Both work while `diagnostics` is granted, and nothing of it is written to disk.

## When consent changes

While a key is not granted, nothing of it is made: no event, no queue, no file, no request, and no anonymous id. When it is withdrawn, what was held of it is deleted, on disk too, and with `analytics` the anonymous ids. When someone signs out, the next person on the device is someone new: the anonymous ids go. See [Consent](/docs/ios/consent).

## App Tracking Transparency

`pb.tracking` reads App Tracking Transparency's answer and shows its prompt when the app asks:

```swift
import Palbase
import PalbaseAnalytics

func askToTrack() async {
    if pb.tracking.status == .notDetermined {
        let answer = await pb.tracking.requestAuthorization()
        print(answer) // .authorized, .denied, .restricted
    }
}
```

The prompt's words are the app's `NSUserTrackingUsageDescription`. Palbase never asks on its own and never reads the advertising identifier: what the app does with the answer is its own. Ad measurement is a consent key of its own (`ads_measurement`).

## Related

- [Consent](/docs/ios/consent): the keys analytics collects behind
- [Flags](/docs/ios/flags#experiments): `$flag_exposure`, what an experiment's results count
- [Web Analytics](/docs/web/analytics): the same events from a browser
- [Debug Console](/docs/ios/debug-console): what the SDK records on the device, apart from analytics



<!-- ===== ios/consent ===== -->

# Consent

`pb.consent` is what the person allowed the app to collect and use, key by key. It is in the core product, and every module that collects asks it first: analytics records nothing for a key that is not granted, and a marketing message goes only where its channel's key is. A choice is kept on the device and stands the moment it is made, and it goes to the project with when it was made. The app's starting values never leave the device, so they can never override a refusal the project holds.

## Quick example

```swift
import Palbase

// What the app starts with until the person chooses, and the version of the text its screen shows.
let pb = PalbaseClient(try! .environment.with(consent: ConsentOptions(
    start: ["analytics": .granted, "performance": .granted, "diagnostics": .granted],
    textVersion: "2026-10",
    customKeys: ["custom.newsletter"]
)))

func consentScreen() async throws {
    let region = try await pb.consent.region()     // .gdpr asks first; .us collects until refused
    let ask = try await pb.consent.needsAsking()   // never chosen, or chosen under another text
    if region.jurisdiction == .gdpr || !ask.isEmpty {
        // … show the screen, then:
        try pb.consent.setMany(["analytics": .granted, "marketing_push": .denied, "custom.newsletter": .granted])
    }
    print(pb.consent.state("analytics")?.rawValue ?? "no choice and no starting value")
}
```

## The keys

| Key | What it allows |
|---|---|
| `analytics` | Events, screens, identify and the person's properties ([Analytics](/docs/ios/analytics)). |
| `performance` | Timings and request traces. |
| `diagnostics` | The log sent with a report. |
| `personalization` | Placing the person in analytics audiences, which flag conditions and in-app campaigns read. |
| `marketing_push`, `marketing_email`, `marketing_sms`, `marketing_whatsapp` | Marketing messages on each channel ([Notifications](/docs/backend/notifications)). |
| `ads_measurement` | Measuring ads: Apple's attribution token with `$install`. |
| `ads_personalization` | Personalized ads. |
| `custom.<name>` | The app's own (`a`–`z`, `0`–`9` and `_`, 48 at most), named in `customKeys`. |

`keys()` lists them in the order a consent screen shows them: the platform's with their words, in English and Turkish (`title` and `description` by language), then the app's own, which the app words itself. Each `ConsentKeyInfo` has its `key`, its `category` (`measurement`, `personalization`, `marketing`, `advertising`, or `custom`) and `ads`, true for what the US laws call selling or sharing.

## Reading and choosing

| Member | What it does |
|---|---|
| `state(_:)` | The key's state: `.granted` or `.denied`, the person's choice, else the app's starting value; `nil` when there is neither, and a module collects nothing then. |
| `set(_:_:)` | Records one choice: it stands at once and is sent to the project. |
| `setMany(_:)` | Records the choices of one screen, made together. A key that is not one throws `invalid_consent_key`. |
| `onChange(_:)` | Told every key whose state changes: the person's choice, a refusal from the project, a sign-in or a sign-out. Returns what stops it. |
| `lastDeniedAt(_:)` | When the key was last refused: here, on another of the person's devices, or by the project on their word. |
| `region()` | Where the person is, as the project tells from their address: `country`, and `jurisdiction`, `.gdpr` (the EU, the EEA, the UK, Switzerland), `.us` or `.other`. |
| `needsAsking(_:)` | The keys the app is to ask about (all, unless given): those never chosen, and those chosen on the app's screen under another `textVersion`; in the US, not an ads key the person refused within twelve months. |

What the app starts with until the person chooses is the app's to say, through `ConsentOptions.start`: where the law asks first (`region()` is `.gdpr`), start the collecting keys denied or not at all, and ask. A key the SDK collects for with no starting value and no choice collects nothing.

A choice that cannot be sent now is sent later, still saying when it was made: after 5 seconds, 30 seconds, 2 minutes, then every 10 minutes, and when the app returns to the foreground or the network comes back. A choice the project refuses never stands: the key is read again, and until it can be, reads `.denied`, as it does while what the device kept cannot be read.

## Whose the choices are

- With no one signed in, the choices are the device's: this install's, which proves itself with a secret kept in the keychain.
- On sign-in, the device's newer choices become the account's, and the device takes the account's.
- Signed in, a refusal made elsewhere (an unsubscribe link, an SMS STOP, another of the person's devices) arrives on the person's own realtime channel and stands at once.
- On sign-out, the device goes back to the app's starting values.

The app's extensions read the same choices through the keychain group the app shares with them ([Overview](/docs/ios/overview#connect-the-app-to-the-project)).

## The install

`pb.installation.id` is the install's id: the first 16 bytes of the SHA-256 of a secret made on the device (32 random bytes, kept in the keychain), base64url. The secret goes only with the device's own consent calls, its push registration and its flag reads with no one signed in. A keychain that outlived the app's deletion keeps the install, and analytics' `$install` says `$reinstall`.

## Related

- [Analytics](/docs/ios/analytics): what the measurement keys hold back
- [Notifications](/docs/ios/notifications): marketing push, and the person's preferences
- [Web Consent](/docs/web/consent): the same keys in a browser



<!-- ===== ios/notifications ===== -->

# Notifications

`pb.notify` (the `PalbaseNotify` product) is what the app does for the project's messages: it registers this device's push token, reads and sets the signed-in user's preferences and topics, reports how each push went on the device, reads the person's inbox, and shows the project's in-app campaigns. Sending is your server's, with the secret key ([Notifications](/docs/backend/notifications)), never the app's. `PalbaseNotificationService` is the app's notification service extension, and `PalbaseNotifyUI` draws in-app messages and the inbox natively in SwiftUI.

## Push

The app needs the **Push Notifications** capability, and the project needs a push provider: its APNs key, or Firebase Cloud Messaging ([Notifications](/docs/backend/notifications#every-channel-but-one-needs-a-provider-of-yours)). Each build of the app registered in the environment — the development app, its TestFlight build, the App Store app — is pushed to its own bundle, through the APNs environment its token is for: the SDK reads it from the build's provisioning profile (`sandbox` from Xcode and the simulator, `production` from TestFlight and the App Store) and says it as it registers the token ([Apple (APNs)](/docs/backend/notifications#every-channel-but-one-needs-a-provider-of-yours)).

```swift
import Palbase
import PalbaseNotify
import UIKit
import UserNotifications

final class AppDelegate: NSObject, UIApplicationDelegate, UNUserNotificationCenterDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
        // Set before launch ends, or a tap that launched the app is missed.
        UNUserNotificationCenter.current().delegate = self
        // The device's token, at every launch: the prompt is asked for apart, from a tap of the person's.
        application.registerForRemoteNotifications()
        return true
    }

    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        Task { try? await pb.notify.register(apnsToken: deviceToken) }
    }

    // Opened, dismissed, or a button of it tapped.
    nonisolated func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse,
                                            withCompletionHandler completionHandler: @escaping () -> Void) {
        pb.notify.didReceive(response)
        completionHandler()
    }

    // Arrived while the app was in front: the extension does not run for it then.
    nonisolated func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification,
                                            withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
        pb.notify.willPresent(notification)
        completionHandler([.banner, .sound])
    }
}
```

Ask the person from a tap of theirs, at the moment it makes sense:

```swift
import Palbase
import PalbaseNotify

@MainActor
func turnOnNotifications() async {
    // The system's prompt; allowed, it registers for remote notifications, and the delegate gets the token.
    let allowed = await pb.notify.requestPushAuthorization()
    print(allowed ? "on" : "off")
}
```

| Method | What it does |
|---|---|
| `register(apnsToken:locale:)` | Records the APNs token, at every launch and whenever it changes, with the device's time zone and the app's version: a push for the person's own hour goes at that hour here, and their quiet hours are on this clock. |
| `requestPushAuthorization(options:)` | Shows the system's prompt (`.alert`, `.badge`, `.sound` by default) and, allowed, registers for remote notifications. The app's alone: an extension has no application to register. |
| `didReceive(_:)` | Reports a push opened, dismissed (a category with `.customDismissAction`), or a button tapped. It returns at once. |
| `willPresent(_:)` | Reports a push delivered while the app was in the foreground. |
| `unregister()` | Forgets this device for the signed-in user: it receives nothing until registered again. |
| `devices()` | The signed-in user's devices. |
| `deviceId` | This install's device, as the project names it: `ios-<installation id>`. |

**The token is the install's, then the user's.** With no one signed in it is registered with the publishable key and the install's secret, and a push that names the install reaches it, so an app reaches people who never signed up. When someone signs in it is registered again with their session, and it is theirs. When their session ends (they sign out, or it is ended anywhere) the project forgets their device, and the app registers it as the install's again: the next person on a phone does not get the last one's notifications. The SDK does each of these by itself once it has a token.

A report that cannot go now is kept and sent at the next launch. A report is the push's own word, its receipt, and goes with the publishable key alone.

## Preferences and topics

```swift
import Palbase
import PalbaseNotify

func noMarketingEmail() async throws {
    var preferences = try await pb.notify.preferences()   // channel → category → whether they take it
    preferences["email", default: [:]]["marketing"] = false
    try await pb.notify.setPreferences(preferences)
    try await pb.notify.follow(topic: "release-notes")
}
```

A user's preferences are channel (`email`, `sms`, `whatsapp`, `push`) → category → whether they take it. `transactional` is always on; a category they never set is on. Every send with a category honours them. `follow(topic:)` and `unfollow(topic:)` add and remove the signed-in user from a topic of the project's. Marketing on a channel also needs the person's consent for it ([Consent](/docs/ios/consent)).

## The notification service extension

The extension tells the project that each push reached the phone, with the app closed too, and shows the push's picture. Add a **Notification Service Extension** target to the app, link `PalbaseNotificationService`, and make its class a subclass with nothing in it:

```swift
import PalbaseNotificationService

final class NotificationService: PalbaseNotificationService {}
```

The target's `NSExtensionPrincipalClass` names it (`$(PRODUCT_MODULE_NAME).NotificationService`, as Xcode's template does). Give the extension the **Keychain Sharing** capability with the app's group: the app keeps the configuration it runs with there (the project's address, its publishable key, its app group), and the extension reads it. An extension that compiles the app's environment in (`palbase/<app>.palbase` in its Compile Sources, with the build rule) can name it instead:

```swift
import Palbase
import PalbaseNotificationService

final class NotificationService: PalbaseNotificationService {
    override var configuration: PalbaseConfiguration? { .environment }
}
```

For each push, it reports `delivered` (five seconds at most) while it downloads the push's `image` (https only, 10 MB and fifteen seconds at most; JPEG, PNG or GIF) and attaches it. The project marks every push a person sees so that the extension runs for it. A report that could not go is kept in the app group, when the app has one, and the app sends it at its next launch: give both targets the **App Groups** capability with the same group, and the app's configuration `with(appGroup:)` ([Overview](/docs/ios/overview#what-the-app-adds-to-the-configuration)). When the system ends the extension's time first, the push is shown as it came.

An extension that does more overrides `didReceive(_:withContentHandler:)`, calls `super` with a handler of its own, and finishes with the content `super` handed it (the picture attached). It can call the project or your backend as the signed-in user: it reads the app's session through the shared keychain group.

## The inbox

The signed-in person's inbox holds the messages your backend put there and the copies of pushes it chose to keep, the same on every device of theirs: read on one, it is read on each; deleted, it is gone from each. A message stays its days (90 unless the project said) and an inbox keeps its newest 250.

`InboxView` (the `PalbaseNotifyUI` product) draws it ready:

```swift
import Palbase
import PalbaseNotifyUI
import SwiftUI

struct InboxScreen: View {
    @State private var unread = 0

    var body: some View {
        InboxView(pb, onUnread: { unread = $0 })
            .navigationTitle(unread > 0 ? "Inbox (\(unread))" : "Inbox")
    }
}
```

`InboxView(_:locale:onOpen:onCustom:onOffer:onUnread:empty:)` takes the language to write it in (the person's chosen one unless given), what a tap on a message's link does (the system opens it unless given), a designed card's own buttons, its offer button (the purchases module takes the offer unless given, once the app uses `pb.purchases`), the unread count as it changes, and what an empty inbox says.

An app that draws its own uses `pb.notify.inbox`:

| Method | What it does |
|---|---|
| `list(limit:cursor:locale:)` | A page, newest first: `items`, `nextCursor` and `unread`. Each `Inbox.Item` has `id`, `title`, `body`, `image`, `deepLink`, `category`, `data`, `card` (a designed card's definition), `createdAt`, `expiresAt` and `readAt`. |
| `unread()` | How many are unread: what a badge shows. |
| `markRead(_:)`, `markAllRead()` | Marks messages read, on every device of the person's. |
| `remove(_:)` | Deletes a message, from every device. |

## In-app messages

The project's in-app campaigns (a modal, a banner or a whole screen, designed in Studio) are shown over the app once started. `palbaseInAppMessages(_:handlers:)` on the app's root view starts them and draws them natively:

```swift
import Palbase
import PalbaseNotifyUI
import SwiftUI

@main
struct ShopApp: App {
    var body: some Scene {
        WindowGroup {
            NavigationStack { InboxScreen() }
                .palbaseInAppMessages(pb, handlers: InAppHandlers(
                    onDeepLink: { url in print("open", url) },
                    onShowPaywall: { placement in print("show the paywall of", placement) }
                ))
        }
    }
}
```

The person's campaigns are asked for as each session of theirs starts (the launch, a return after half an hour away, a sign-in or out). An event the app records with `pb.analytics` (its captures and screens), or names with `pb.notify.inApp.trigger(_:properties:)`, shows the first campaign it triggers, the highest priority first, that its caps let: the project's (in a session, in a day, the least time between two) and the campaign's own. Triggers are matched on the device, so no event leaves it for them, and a message is shown whatever the person chose of analytics; a campaign to an audience reaches only people who allowed personalization.

`InAppHandlers` says what the app does with a message's buttons: `onDeepLink` (the system opens the link unless given), `onShowPaywall` (a placement's paywall), `onCustom` (the app's own code: a name and a value), `onRequestPush` (the push ask; the SDK's prompt and registration unless given) and `onOffer` (one of the catalog's offers; the purchases module takes it unless given, once the app uses it). A button whose action the app does not take is not drawn: a paywall button without `onShowPaywall`, a custom one without `onCustom`.

An app that draws its own calls `pb.notify.inApp.start(presenting:)`, which hands it each `InAppPresentation` to show (its `definition`, its `variables`) and `nil` when what is shown must go. The app tells back `clicked(_:)`, `dismissed()` or `closed()`. `stop()` stops them, and `refresh()` asks for the person's campaigns again.

## Related

- [Notifications in your backend](/docs/backend/notifications): sending push, email, SMS and WhatsApp, templates, topics, the inbox, campaigns
- [Consent](/docs/ios/consent): the marketing keys
- [Overview](/docs/ios/overview): the keychain group and app group the extension shares
- [Web Notifications](/docs/web/notifications): web push and the inbox in a browser



<!-- ===== ios/storage ===== -->

# Storage

`pb.storage` (the `PalbaseStorage` product) carries a file's bytes to and from the project's storage. What it may write or read is your backend's to decide: an app holds no key that opens storage, so it writes an object only at an **upload URL** your backend signed, reads a private one only at a **download URL** your backend signed, and reads a **public** bucket's objects as anyone may. The backend chooses the bucket, the path, how large, of which types and whose; the app carries the bytes, straight to storage and never through your backend.

## Quick example

The backend signs an upload for the signed-in user ([Direct Uploads](/docs/backend/direct-uploads)):

```ts
// src/modules/avatars/avatars.controller.ts
import { Body, Controller, Palbase, Post, User, z, type UserT } from "palbase/backend";

const UploadRequest = z.object({ contentType: z.string().max(100) });
type UploadRequest = z.infer<typeof UploadRequest>;

@Controller("/avatars")
export class AvatarsController {
  // The user asks; the backend decides the path, the ceiling and the owner.
  @Post("/upload-url", { rateLimit: { max: 10, window: 60 } })
  async uploadUrl(@Body(UploadRequest) body: UploadRequest, @User() user: UserT): Promise<{ url: string; path: string }> {
    const ext = body.contentType === "image/png" ? "png" : "jpg";
    const path = `${user.id}/avatar-${Date.now()}.${ext}`;
    const signed = await Palbase.storage.createUploadUrl({
      path: { bucket: "avatars" },
      body: { path, expires_in: 300, max_bytes: 2 * 1024 * 1024, owner_id: user.id },
    });
    return { url: signed.data.url, path };
  }
}
```

The app asks for the URL through its [generated client](/docs/ios/backend-calls), then sends the bytes to it:

```swift
import Foundation
import Palbase
import Palbe
import PalbaseStorage

func uploadAvatar(_ png: Data) async throws {
    let grant = try await pb.backend.avatars.uploadUrl(.init(contentType: "image/png"))
    guard let url = URL(string: grant.url) else { return }
    let stored = try await pb.storage.upload(png, to: url, contentType: "image/png")
    print(stored.path, stored.size, stored.width ?? 0, stored.thumbhash ?? "")
}
```

## The calls

| Method | What it does |
|---|---|
| `upload(_:to:contentType:)` | Writes the bytes at an upload URL your backend signed, and returns the stored object (`StorageAPI.StorageObject`). |
| `download(from:)` | Reads an object at a download URL your backend signed (`Palbase.storage.createSignedUrl`). |
| `publicObject(bucket:path:)` | Reads an object of a public bucket. |
| `publicURL(bucket:path:)` | A public object's address, for an `AsyncImage`, a share sheet, or a cache of the app's own. |

A signed URL is taken only at the project's own address: one that names another host is refused before anything is sent (`foreign_signed_url`), and one that is not a signed object URL is `invalid_signed_url`.

## What an upload answers

The stored object: `bucket`, `path`, `size`, `contentType` (sniffed from the bytes, not taken from what the app said), `checksumSha256`, `ownerId`, a picture's `width`, `height` and `thumbhash` placeholder, its `variants` (the renditions the bucket declares, made inside the upload) and `createdAt`, `updatedAt`.

`contentType` is used only when the bytes cannot say what they are (HEIC, which a stock iPhone camera makes). Storage holds the upload to the URL's grant and the bucket's rules while the bytes stream in, and a refusal is a `PalbaseError`:

| Status | Why |
|---|---|
| `403` | The signature is wrong, expired, another project's, or a download signature. |
| `413 payload_too_large` | Larger than the URL's ceiling or the bucket's. |
| `415 unsupported_media_type` | A type the bucket, or the URL, does not take. |
| `422 unreadable_picture` | A picture the bucket's renditions cannot be made from. |
| `429 quota_exceeded` | The project's storage for the period is used up, with `Retry-After`. |

Your backend learns of the upload from the `file.uploaded` event ([Event Hooks](/docs/backend/hooks)), or from a route the app calls once the upload is answered.

## A route that takes the file

A route your backend declares as an upload takes the file in one generated call, with the upload URL made and used inside it and the progress told by phase: see [Calling Your Backend](/docs/ios/backend-calls#files).

## Related

- [Direct Uploads](/docs/backend/direct-uploads): what an upload URL grants, and why the backend asks first
- [Storage in your backend](/docs/backend/storage): buckets, objects, public reads, signed download URLs, renditions
- [Calling Your Backend](/docs/ios/backend-calls): the generated client the grant comes through



<!-- ===== ios/purchases ===== -->

# Purchases

`pb.purchases` (the `PalbasePurchases` product) is what the signed-in customer has bought, in any store, as one answer, and buying in the App Store with StoreKit 2. A Pro bought on the web or on Google Play is this app's Pro too. `PalbasePurchasesUI` draws the paywall the project publishes, natively in SwiftUI, priced by the App Store. The catalog (products, plans, entitlements, offers) is the project's ([Catalog](/docs/purchases/catalog)), and the environment verifies every transaction with Apple ([App Store](/docs/purchases/app-store)).

## Quick example

```swift
import Palbase
import PalbasePurchases
import PalbasePurchasesUI
import SwiftUI

struct Settings: View {
    @State private var showPaywall = false

    var body: some View {
        List {
            // Drawn again when it changes: a purchase in any store, a renewal or its end, a refund.
            if pb.purchases.state.isEntitled("pro") {
                Text("Pro is on")
            } else {
                Button("Go Pro") { showPaywall = true }
            }
        }
        .paywall(placement: "settings", isPresented: $showPaywall)
    }
}

@main
struct ShopApp: App {
    init() {
        // Touched at launch: what the App Store hands over (a renewal, an approved Ask to Buy, an unfinished
        // purchase) is reported for whoever is signed in.
        _ = pb.purchases
    }

    var body: some Scene {
        WindowGroup {
            Settings()
                .palbasePurchases(pb.purchases)   // once, at the root: the paywalls below buy through it
                .paywallLinks(terms: URL(string: "https://example.com/terms"), privacy: URL(string: "https://example.com/privacy"))
        }
    }
}
```

## What the customer has

`CustomerInfo` is the same answer the web and your backend read: `entitlements` by key (each with `active`, `expiresAt`, `willRenew`, `store`, `billingIssue`, `isSandbox`, `periodType`, `manage`), `subscriptions`, one-time `purchases`, `credits` and `limits`, and whether the customer is a `guest`.

| Member | What it does |
|---|---|
| `state` | An `@Observable` on the main actor: `state.customerInfo`, and `state.isEntitled(_:)`. Read once, it keeps listening while the app runs. |
| `customerInfo()` | Reads it now. Throws `session_changed` when the signed-in user changed while it was read. |
| `isEntitled(_:at:)` | Whether the customer has the entitlement now, from what was last read: active and, unless it is for life, ending after now. `CustomerInfo.isEntitled(_:at:)` is the same rule, the one `palbase/server`'s `isEntitled` reads on a backend. |
| `latest` | What listeners were last told, without a call. |
| `onCustomerInfo(_:)` | Told what the customer has, once read and each time it changes; `nil` while no one is signed in. Returns what stops it. |
| `customerInfoUpdates` | The same as an `AsyncStream`, the newest when the reader falls behind. |

It is kept current over the customer's own realtime channel, theirs alone and read-only: when what they have changes anywhere, it is read again. When another user signs in, `nil` is told until theirs is read, so one user's is never shown as the next one's. Check the entitlement on your server too, where the content is served ([Entitlements, Credits & Limits](/docs/purchases/entitlements#checking-an-entitlement)).

## Buying in the App Store

```swift
import Palbase
import PalbasePurchases

func buyFirst() async {
    do {
        let products = try await pb.purchases.products()
        if let d = products.diagnosis { print(d) } // why some of the catalog is missing
        guard let pro = products.first else { return }
        switch try await pb.purchases.purchase(pro) {
        case .purchased(let info): print("pro:", info.isEntitled("pro"))
        case .alreadyEntitled(let store, let entitlement, _): print("\(entitlement) is already on, from \(store)")
        case .pending: print("waiting for approval")
        case .cancelled: break
        }
    } catch let e as PurchasesError {
        print(e.message, e.code)
    } catch {
        print(error)
    }
}
```

| Method | What it does |
|---|---|
| `products()` | The catalog's iOS plans as the App Store has them for this user, in the catalog's order, as `StoreProduct`s: StoreKit's `product` (its `displayName`, `displayPrice`, subscription), the catalog's `offering` and `plan`, and the `entitlements` it gives. When the App Store returned fewer than the catalog sells on iOS, `diagnosis` names the missing ids and the likely causes. |
| `purchase(_:)` | Buys a product for the signed-in customer. |
| `restore()` | "Restore purchases", the user's own action, never automatic: the App Store is synced (it may ask the user to sign in), and what this Apple ID owns is reported as restored. Answers what the customer has now. |
| `offerings(channel:)` | The paywall's catalog on a channel, iOS unless another is named. |

`purchase(_:)` reads what the customer has first: when an entitlement the product gives is already on from another store, it answers `.alreadyEntitled(store:entitlement:manage:)` and the App Store is never opened, so nothing is charged twice. Otherwise the App Store sells it with the customer's account token, the transaction is reported to the environment, and it is finished only once the environment has it: a report that fails leaves it unfinished, and the App Store hands it over again. `.pending` is Ask to Buy or the bank's approval: the transaction is reported when it comes, and listeners are told.

A purchase needs someone signed in (`session_required`); a guest from `signInAnonymously()` is someone, and what a guest buys stays theirs when they become an account. StoreKit's failures throw `PurchasesError`, one sentence each, with a `code`: `.cancelled`, `.productUnavailable`, `.purchaseNotAllowed`, `.notAvailableInStorefront`, `.ineligibleForOffer`, `.invalidOffer`, `.networkError`, `.systemError`, `.unverifiedTransaction` (never reported, never finished) and others. The environment's refusals throw `PalbaseError`.

On an Apple ID shared with another of the app's accounts, a purchase made here moves the subscription to this customer, who paid; one that would move it a fourth time in 30 days leaves it where it is, and `purchase(_:)` throws `PalbaseError` with `restore_limit`. A restore moves a purchase to this customer only when StoreKit signed its transaction for this device. When one stays where it was, the rest is still applied, and `restore()` throws `PalbaseError` with `restore_not_this_device`, `restore_account_owned` (a guest restoring an account's: sign in to that account) or `restore_limit`.

## The paywall

The paywall the project publishes at a **placement** ([Paywalls](/docs/purchases/paywalls)), designed in Studio, is drawn natively by `PaywallView`: its theme, components, packages, tabs, carousels, videos and fonts, with the App Store's prices for this user in their currency, its texts in the app's language, Dynamic Type, Reduce Motion and VoiceOver. Its purchase button buys with `purchase(_:)`, with an offer while the customer may take it; a restore button is `restore()`; an offer code button opens the App Store's sheet.

| | What it does |
|---|---|
| `.palbasePurchases(pb.purchases)` | Once, at the root: the purchases module the paywalls below buy through. |
| `.paywall(placement:attributes:isPresented:onPurchased:)` | Shows the placement's paywall over the screen while `isPresented`. |
| `.presentPaywallIfNeeded(entitlement:placement:attributes:onPurchased:)` | Shows it once what the customer has is known, only when they do not have the entitlement, and closes it when they come to have it. |
| `PaywallView(placement:attributes:onPurchased:onClose:)` | The paywall as a view of your own layout. |
| `.paywallLinks(terms:privacy:)` | The app's terms and privacy policy, which a paywall's links open. |
| `.paywallComponent(_:_:)` | Draws your own view in place of the component Studio names `id`, in every paywall below. |

The paywall is asked for the signed-in customer (or this install, so an experiment's variant is the same every time) and kept on the device: asked again with its ETag, and shown as it was when the project cannot be asked. With nothing published at the placement, the SDK draws its own from the catalog. `attributes` is what the app says of the person to the placement's targeting rules (`["plan": "free"]`); the rules also read the app's version, the SDK's, the App Store's country and the person's languages. `pb.purchases.preloadPaywall(placement:attributes:)` at launch makes a placement shown early open at once, and offline.

An app that draws its own reads `pb.purchases.paywall(placement:attributes:)`, which answers the definition, its offerings, its files and offers, and calls `paywallShown(_:)` each time it puts one on screen.

## Offers and codes

Offers and coupons are the catalog's ([Offers & Coupons](/docs/purchases/offers)).

| Method | What it does |
|---|---|
| `offers()` | The catalog's offers the customer may take now: a `discount` or a `trial` bought with the offer, or a `grant`, an entitlement for a while with no store. |
| `purchase(_:offer:)` | Buys a product with a discount or a free trial, under Apple's signature of the promotional offer, which the environment makes with its In-App Purchase key: no key is in the app. |
| `claim(_:)` | Claims a grant offer: its entitlement, for its duration, from now. |
| `take(offer:)` | Takes an offer by its key: claims a grant, or buys with a discount or trial. What an in-app message's offer button does. |
| `redeem(code:)` | Redeems a coupon code the customer typed. A refusal throws `CouponError` (`coupon_not_found`, `coupon_redeemed`, `coupon_ended`, `sign_in_required`, `too_many_attempts`, …); an App Store offer code is `.redeemAtAppStore`. |
| `presentOfferCodeRedemption()` | Shows the App Store's sheet for an offer code App Store Connect made. |
| `offerShown(_:)` | Counts an offer shown, as the app puts it in front of the customer. |

## Buying on the web from the app

In the App Store's United States storefront, an app may link out to buy on the web beside In-App Purchase (App Review Guideline 3.1.1(a)). `canOpenWebCheckout()` says whether the customer's storefront is one where it may; show the web button only then, no more prominent than the In-App Purchase. `openWebCheckout(product:plan:successURL:cancelURL:)` opens Stripe Checkout in the system browser for the signed-in customer, a guest too, and records where it was opened. Elsewhere it throws `web_checkout_not_allowed` and asks nothing. Stripe sends the customer back to the app's own scheme, its bundle id (`<bundle>://palbase/checkout?result=…`), and what they have is read again when the app is in front. See [Web Purchases](/docs/purchases/web#from-a-native-app).

What someone bought on the web with no account waits for the app user who redeems it: its one-time link opens the app, and `redeem(_:)` takes it for the signed-in user.

```swift
import Palbase
import PalbasePurchases
import SwiftUI

struct Root: View {
    var body: some View {
        Text("Shop")
            .onOpenURL { url in
                guard Purchases.redemptionToken(in: url) != nil else { return }
                Task { _ = try? await pb.purchases.redeem(url) }
            }
    }
}
```

## Testing

In Xcode with a StoreKit file made from the catalog, or in the App Store sandbox with a tester: see [Test Apple Purchases](/docs/purchases/testing-apple). A test purchase is marked: `isSandbox` is true on what it gives.

## Related

- [Purchases](/docs/purchases/overview): the catalog, the stores and how a purchase becomes access
- [App Store](/docs/purchases/app-store): connecting it, and what the environment does with a transaction
- [Test Apple Purchases](/docs/purchases/testing-apple): buying before anyone pays
- [Web Purchases](/docs/purchases/web): Stripe Checkout, and a buyer with no account
- [Paywalls](/docs/purchases/paywalls) · [Offers & Coupons](/docs/purchases/offers) · [Entitlements, Credits & Limits](/docs/purchases/entitlements)
- [Notifications](/docs/ios/notifications#in-app-messages): an in-app message's paywall and offer buttons



<!-- ===== ios/voice ===== -->

# Voice

A chat of the project's agents can be talked to out loud ([AI › Voice](/docs/backend/ai#voice)). `PBVoice` (the `PalbaseVoice` product) is that voice on the device: the microphone goes to the platform's voice provider and its voice comes back, over WebRTC. The app makes the WebRTC offer, the app's own backend starts the voice with it, and the provider's key never leaves the platform.

## Install

`PalbaseVoice` is a package of its own, [github.com/palgroup/palbase-swift-voice](https://github.com/palgroup/palbase-swift-voice), because it brings WebRTC (LiveKit's build, [livekit/webrtc-xcframework](https://github.com/livekit/webrtc-xcframework)): an app that talks to no voice resolves none of it. Add it at the same version as `palbase-swift`:

```swift
.package(url: "https://github.com/palgroup/palbase-swift-voice", exact: "0.4.0")
```

Link `PalbaseVoice`; it brings the `Palbase` core of the same version. An app that also takes LiveKit's SDK resolves the one WebRTC package. The app's Info.plist says why it asks for the microphone, in `NSMicrophoneUsageDescription`.

## Quick example

The backend starts the voice for the signed-in member, from a route of its own:

```ts
// src/modules/support/voice.controller.ts
import { Body, Controller, Palbase, Param, Post, User, z, type UserT } from "palbase/backend";

const Offer = z.object({ sdp: z.string().min(1) });

@Controller("/voice")
export class VoiceController {
  // The app's WebRTC offer in; the voice's id and the provider's answer out.
  @Post("/{chatId}")
  async start(@Param("chatId") chatId: string, @Body(Offer) body: z.infer<typeof Offer>, @User() user: UserT): Promise<{ id: string; sdp: string }> {
    const voice = await Palbase.ai.chats.voice.start(chatId, { sdp: body.sdp, as: user.id });
    return { id: voice.id, sdp: voice.sdp };
  }

  @Post("/{chatId}/{voiceId}/close")
  async close(@Param("chatId") chatId: string, @Param("voiceId") voiceId: string, @User() user: UserT): Promise<{ seconds: number }> {
    const voice = await Palbase.ai.chats.voice.close(chatId, voiceId, { as: user.id });
    return { seconds: voice.seconds };
  }
}
```

The app connects, after `palbase apps:sync` wrote the backend's client:

```swift
import Palbase
import Palbe
import PalbaseVoice

@MainActor
func talk(chatId: String) async throws -> PBVoice {
    try await PBVoice.connect(start: { sdp in
        // The offer through the app's own backend; the voice it started and the provider's answer back.
        let started = try await pb.backend.voice.start(chatId: chatId, .init(sdp: sdp))
        return PBStartedVoice(id: started.id, sdp: started.sdp)
    }, onState: { state in
        print("voice:", state.rawValue)
    })
}
```

## Connecting

`PBVoice.connect(start:audioSession:iceTimeout:onError:onState:)` asks the person for their microphone, sets up the audio session, makes the peer connection and its offer, gathers its network candidates (for `iceTimeout`, 10 seconds at most by default), and hands the offer to `start`. `start` is the round trip to your backend; it returns a `PBStartedVoice(id:sdp:)`, the voice's id and the provider's answer. `connect` returns once the answer is set.

| Parameter | What it says |
|---|---|
| `start` | The offer (an SDP) in, the voice and its answer out, through your backend. |
| `audioSession` | `.managed` (the default): the voice sets the audio session up for voice chat, on the speaker unless something else is connected, and turns it off on close, letting other apps' sound come back. `.app`: the app set it up already and keeps it. |
| `iceTimeout` | How long the offer's candidates are gathered at most. |
| `onError` | The provider's word that something went wrong in the voice. |
| `onState` | The connection's state each time it changes. |

A microphone the person refuses throws `microphone_denied`. A refusal from your backend, or the connecting task cancelled, closes whatever was opened.

## The voice

`PBVoice` is on the main actor:

| Member | What it does |
|---|---|
| `id` | The voice your backend started: what it reads, tells and closes it by. |
| `state` | The connection's state: `new`, `connecting`, `connected`, `disconnected`, `failed` or `closed`. |
| `mute(_:)`, `muted` | Stops the provider hearing the microphone, and says whether it does not. |
| `close()` | Ends it here: the connection, the microphone, and the audio session it set up. |

Call `close()` when the voice is done, and close it on your backend too (`Palbase.ai.chats.voice.close`). A `PBVoice` the app lets go of without closing it is closed as it goes, so the microphone does not stay open behind it.

## What was said

What is said either way is the chat's. A member who has the chat's gateway joined sees it in the chat's state ([Gateways](/docs/ios/gateways#chat-gateways)): each line as a message of kind `.voice`, with `voice.role` `.user` or `.assistant`, and `state.voice` (its `status`, `started` or `closed`, `mine`, `seconds` and `closeReason`), with an item when it begins and when it ends.

## Related

- [AI › Voice](/docs/backend/ai#voice): starting, telling and closing a voice from your backend
- [Gateways](/docs/ios/gateways): the chat's state, where what was said arrives
- [Calling Your Backend](/docs/ios/backend-calls): the generated client the offer goes through



<!-- ===== ios/debug-console ===== -->

# Debug Console

Every app records from launch, on the device: the SDK's own requests and realtime frames, its modules' lines, and whatever the app adds. The `PalbaseDebug` product shows it, in an in-app console the project turns on for **one user at a time**. A build that already shipped can open it for the one person reporting a bug, with no release and no `#if DEBUG`.

## Quick example

```swift
import Palbase
import PalbaseDebug
import SwiftUI

struct SettingsView: View {
    @State private var showingConsole = false

    var body: some View {
        List {
            // False until the project turns it on for this user; drawn again when it flips.
            if pb.debug.isEnabled {
                Button("Debug console") { showingConsole = true }
            }
        }
        .sheet(isPresented: $showingConsole) { pb.debug.view }
    }
}
```

Turn it on for the user who reports the bug:

```sh
palbase flags:users:set <user id> palbase.debug_console true
```

It is the flag `palbase.debug_console`, given to that user as their own value ([Flags](/docs/ios/flags)). `pb.debug.isEnabled` is false until that value is known to be `true`: before the flags load, when their read fails, and for every other user. `pb.debug.view` shows nothing while it is false. Recording is not gated: what was recorded before the flag was turned on is there the moment it is.

## What it records

| What | How |
|---|---|
| The SDK's requests | Every request to the project and to your backend, with its timing, its status and its bodies. Credentials are masked before a record exists: tokens, keys, DPoP proofs, cookies. |
| Realtime | The socket's frames, opening and closing, and each channel's. |
| The modules | Each module's own lines, under `palbase.<module>` labels: a sign-in, a token refreshed, a flag change. |
| The app's lines | `pb.debug.log(_:level:label:metadata:)`, and `pb.debug.error(_:label:)` for an `Error` with its domain and code. |
| The app's own requests | Through `pb.debug.session(configuration:label:)`, a `URLSession`-shaped `PBDebugSession`, or `pb.debug.urlSessionDelegate(wrapping:label:)` around a delegate of the app's. |
| Anything else | `pb.debug.record(request:response:data:label:)` (and `error:`) for an exchange the SDK did not make. |

```swift
import Foundation
import Palbase

func checkout(items: Int) async throws {
    pb.debug.log("checkout tapped", level: .warning, label: "checkout", metadata: ["items": "\(items)"])

    // The app's own traffic, recorded beside the SDK's under its label.
    let (_, response) = try await pb.debug.session(label: "app").data(from: URL(string: "https://example.com/ping")!)
    print((response as? HTTPURLResponse)?.statusCode ?? 0)
}
```

A backend call's [encrypted field](/docs/backend/request-encryption) is recorded as it went, sealed (`pbt1.…`); **Reveal** beside it in the body shows its value. The values are kept in memory alone, only while the console is on for the user and recording, and are gone when the console is cleared, another user signs in or the console is turned off.

`label` is the category the console filters by. Levels are `.trace`, `.debug`, `.info`, `.notice`, `.warning`, `.error` and `.critical`. The SDK does not swizzle `URLSession`: traffic it did not make is recorded only through these calls.

## Where it is kept

On the device alone: nothing of the console is sent anywhere. It keeps the last 20 launches, within 32 MB, the oldest swept first; a body over 5 MB keeps its first 5 MB and says how large it was. The console is the signed-in user's: when someone else signs in, the last user's records are wiped.

| Member | What it does |
|---|---|
| `pb.debug.isRecording` | Whether it is recording. It is from launch. |
| `pb.debug.stop()`, `pb.debug.start()` | Stops recording, and starts it again. What was recorded is kept. |
| `pb.debug.clear()` | Discards every record, on disk and in the screens. |

## The screens

`pb.debug.view` is a `PalbaseConsoleView`, to place in a sheet, a tab or a pushed screen: the timeline of every record, filters by label and level, each request's headers, bodies (as JSON, text, a cURL command or a hex dump) and timing, the realtime inspector, metrics, and the launches kept.

## Related

- [Flags](/docs/ios/flags): `palbase.debug_console`, a user's own value
- [Logs](/docs/getting-started/logs): what the project records on its side, in Studio
- [`flags:users:set`](/docs/cli/reference#palbase-flagsusersset)



<!-- ===== android/overview ===== -->

# Android SDK

The Android SDK is `studio.palbase:palbase` and one artifact per module, in Kotlin, with coroutines. `palbase` holds the project's address and publishable key, the transport every call goes through, the signed-in user's session, the realtime socket, consent and auth. Each module (flags, analytics, realtime, notify, storage, purchases) is an artifact of its own that hangs off the same client, as `pb.flags`, `pb.notify` and so on. A backend of yours is a typed client that `palbase apps:sync` writes into the app, and it calls through the same client too.

The version on this page is **0.4.0**.

## Requirements

- `minSdk` 26.
- Kotlin 2.2 or newer in the app, the version AGP 9 builds an app with. The SDK is compiled for it.
- Java 17 in the app's `compileOptions`, as the SDK's own example app sets.

The SDK ships compiled, under the Palbase SDK License. Every file in the repository is signed, and the public key is the repository's `KEYS` file.

## Installing

The artifacts are in a Maven repository of their own, `https://palgroup.github.io/palbase-android/`, under the group `studio.palbase`. No account or credential is needed to read it. Take `studio.palbase` from there alone:

```kotlin
// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        exclusiveContent {
            forRepository { maven("https://palgroup.github.io/palbase-android/") }
            filter { includeGroup("studio.palbase") }
        }
    }
}
```

The BOM gives every artifact one version. Add `palbase`, then the modules the app uses:

```kotlin
// app/build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.plugin.serialization") // the backend clients are kotlinx.serialization types
}

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

dependencies {
    implementation(platform("studio.palbase:palbase-bom:0.4.0"))
    implementation("studio.palbase:palbase")
    implementation("studio.palbase:palbase-flags")     // and the other modules the app uses
    implementation("studio.palbase:palbase-palbe")     // when the app calls a backend of yours
}
```

| Artifact | What it is | In the app |
|---|---|---|
| `palbase` | The address and key, the transport, the session, the realtime socket, consent, auth, the debug console's recording | `PalbaseClient`, `pb.auth`, `pb.socket`, `pb.consent`, `pb.debug` |
| `palbase-flags` | The project's flags, kept current | `pb.flags` ([Flags](/docs/android/flags)) |
| `palbase-analytics` | Events, screens, timings and diagnostics, each behind its consent | `pb.analytics(startingConsent)` ([Analytics](/docs/android/analytics)) |
| `palbase-realtime` | Channels: broadcasts and a shared state | `pb.realtime` ([Realtime](/docs/android/realtime)) |
| `palbase-notify` | This device's push token for the user, their preferences and topics, the inbox, in-app messages | `pb.notify` ([Notifications](/docs/android/notifications)) |
| `palbase-notify-ui` | The inbox and in-app messages, drawn in Compose | `InboxView`, `PalbaseInAppMessages` ([Notifications](/docs/android/notifications#the-inbox)) |
| `palbase-storage` | Files through URLs your backend signed, and public buckets | `pb.storage` ([Storage](/docs/android/storage)) |
| `palbase-purchases` | What the customer has, in any store, and buying on Google Play (Play Billing 9) | `pb.purchases` ([Purchases](/docs/android/purchases)) |
| `palbase-palbe` | Your backends' generated clients, their gateways and chats | `pb.<name>` ([Calling Your Backend](/docs/android/backend-calls), [Gateways](/docs/android/gateways)) |
| `palbase-debug` | The debug console's screens, in Compose | `PalbaseConsole(pb.debug)` ([Debug Console](/docs/android/debug-console)) |
| `palbase-voice` | A chat's live voice over WebRTC | `PBVoice.connect(…)` ([Voice](/docs/android/voice)) |
| `palbase-runtime` | The types every generated client calls into; `palbase` brings it | — |
| `palbase-bom` | One version for all of them | `platform(…)` |

WebRTC comes only with `palbase-voice`, Play Billing only with `palbase-purchases` and Compose only with `palbase-debug`, so an app that takes none of them carries none of them.

Each module is an extension of the client (a property, and for analytics a function), imported from the module's package: `import studio.palbase.flags.flags`, `studio.palbase.notify.notify`, `studio.palbase.storage.storage`, `studio.palbase.realtime.realtime`, `studio.palbase.purchases.purchases`, `studio.palbase.analytics.analytics`.

## Registering the app

An Android app is registered once in the project, and then set in each environment with its application ID and the SHA-256 of every certificate it is signed with:

```sh
palbase apps:create android "Shop" --slug shop-android
palbase apps:env:set shop-android --package com.example.shop --sha256 debug=AB:CD:… --sha256 play_signing=12:34:… -E staging
```

The slug is the app's name in a checkout. The certificates are labelled. Google's app signing key is in Play Console › App signing (not the upload key), and `./gradlew signingReport` prints a debug key's. The environment publishes them in its Digital Asset Links file (`GET /.well-known/assetlinks.json`), which Android's Credential Manager reads before the app may use the project's passkeys. See [`apps:create`](/docs/cli/reference#palbase-appscreate) and [`apps:env:set`](/docs/cli/reference#palbase-appsenvset).

## The environment in the build

Nobody types a URL or a key into the app. `palbase apps:sync`, run at the root of the app's repository, writes `palbase/` there and nothing else:

```text
palbase/
├── project.json                          the checkout's project and apps
└── environments/
    └── staging/
        ├── shop-android.json             the app's settings: address, publishable key, backends
        ├── contracts/backend.openapi.json each backend's contract
        └── palbe/backend.kt              each backend's Kotlin client (pb.backend)
```

There is a directory for every environment the app is set in. Commit it; `palbase apps:sync --check` exits 1 in CI when it is not what the project gives now ([`apps:sync`](/docs/cli/reference#palbase-appssync)).

The app's build compiles one environment into each build variant. There is no Gradle plugin: this task, in `app/build.gradle.kts`, reads `palbase/environments/` and writes the variant's sources. It reaches nothing on the network. Map each variant to an environment, and set `app` to the app's slug:

```kotlin
// app/build.gradle.kts — the environment each build variant compiles in.
val palbaseEnvironments = mapOf(
    "debug" to "staging",
    "release" to "main",
)

abstract class PalbaseEnvironment : DefaultTask() {
    /** palbase/environments: what `palbase apps:sync` writes, a directory per environment. */
    @get:InputFiles abstract val environments: ConfigurableFileCollection
    @get:Input abstract val app: Property<String>
    @get:Input abstract val variant: Property<String>
    @get:Input @get:Optional abstract val environment: Property<String>
    @get:OutputDirectory abstract val out: DirectoryProperty

    @TaskAction
    fun write() {
        val root = environments.singleFile
        val known = root.listFiles().orEmpty().filter { it.resolve("${app.get()}.json").isFile }.map { it.name }.sorted()
        if (known.isEmpty()) throw GradleException("palbase/environments has no environment of ${app.get()}: run `palbase apps:sync` (it writes palbase/)")
        val name = environment.orNull
            ?: throw GradleException("the build variant ${variant.get()} names no Palbase environment: map it in palbaseEnvironments (build.gradle.kts) to one of ${known.joinToString()}")
        if (name !in known) throw GradleException("no environment $name of ${app.get()} in palbase/environments (it has ${known.joinToString()}): register the app in $name and run `palbase apps:sync`")
        val dir = root.resolve(name)
        val target = out.get().asFile.apply { deleteRecursively(); mkdirs() }
        // The environment's client document, as the build's PalbaseConfiguration.environment.
        val document = buildString {
            append('"')
            for (c in dir.resolve("${app.get()}.json").readText()) when (c) {
                '\\' -> append("\\\\")
                '"' -> append("\\\"")
                '$' -> append("\\$")
                '\n' -> append("\\n")
                '\r' -> append("\\r")
                '\t' -> append("\\t")
                else -> append(c)
            }
            append('"')
        }
        target.resolve("PalbaseEnvironment.kt").writeText(
            """
            |// Written by the build from palbase/environments/$name/${app.get()}.json — DO NOT EDIT.
            |package palbase
            |
            |import studio.palbase.PalbaseConfiguration
            |
            |/** The environment this build was made for: $name. */
            |public val PalbaseConfiguration.Companion.environment: PalbaseConfiguration
            |    get() = environmentConfiguration
            |
            |private val environmentConfiguration: PalbaseConfiguration by lazy {
            |    try {
            |        PalbaseConfiguration.fromClientDocument($document)
            |    } catch (e: Exception) {
            |        throw IllegalStateException("palbase/environments/$name: " + e.message, e)
            |    }
            |}
            |""".trimMargin(),
        )
        // The environment's backends' Palbe clients: pb.<name>.
        dir.resolve("palbe").listFiles { f -> f.extension == "kt" }.orEmpty().forEach { it.copyTo(target.resolve(it.name)) }
    }
}

androidComponents.onVariants { variant ->
    val task = tasks.register<PalbaseEnvironment>("palbaseEnvironment${variant.name.replaceFirstChar { it.uppercase() }}") {
        environments.from(rootProject.layout.projectDirectory.dir("palbase/environments"))
        app = "shop-android"
        this.variant = variant.name
        palbaseEnvironments[variant.name]?.let { environment = it }
    }
    variant.sources.kotlin?.addGeneratedSourceDirectory(task, PalbaseEnvironment::out)
}
```

A variant that names no environment, or one the app is not set in, stops the build and says which environments there are. The variant then has `PalbaseConfiguration.environment` (package `palbase`) and the backends' clients as `apps:sync` wrote them.

## The client

Make one client for the process, with the application context:

```kotlin
// app/src/main/kotlin/com/example/shop/ShopApp.kt
package com.example.shop

import android.app.Application
import palbase.environment
import studio.palbase.PalbaseClient
import studio.palbase.PalbaseConfiguration

lateinit var pb: PalbaseClient

class ShopApp : Application() {
    override fun onCreate() {
        super.onCreate()
        pb = PalbaseClient(this, PalbaseConfiguration.environment)
    }
}
```

`PalbaseClient(context, configuration, sessionStorage, retry)` takes two more arguments with defaults:

| Argument | Default | What it is |
|---|---|---|
| `sessionStorage` | `PalbaseClient.SessionStorage.DEVICE` | Where the session is kept between launches: encrypted with an AES key the Android keystore holds, in the app's no-backup files, so a backup restored on another device carries no session. `PalbaseClient.SessionStorage.MEMORY` keeps it for this process alone. |
| `retry` | `RetryPolicy.DEFAULT` (`studio.palbase.transport.RetryPolicy`) | How a call is sent again when the answer says "not now" ([Errors and retries](#errors-and-retries)). |

`PalbaseConfiguration.environment` reads the document `apps:sync` wrote: the address, the publishable key, the passkeys' relying party and the environment's backends. `environmentInfo` says which environment it is (`ref`, `slug`, `name`, `production`). A configuration can also be given in code, for a test or a tool:

```kotlin
val configuration = PalbaseConfiguration.of(url = "https://k3xq81w4m.palbase.studio", publishableKey = "pb_k3xq81w4m_cZ8yX7wV6uT5")
```

The configuration is refused with a `ConfigurationException` when the key is a secret key (`pb_<ref>_s…`): a secret key never goes into an app. The address must be an origin with no path. A release build reaches the project and its backends over https only. A debuggable build may also use http to this machine: `localhost`, `127.0.0.1`, `::1`, or `10.0.2.2`, the emulator's address for the computer it runs on.

### Languages

Every request says the user's languages in `Accept-Language`, the device's in their order. Auth's emails and pages, flags' and paywalls' rules and a backend's translations read them. An app with a language setting of its own names its languages instead:

```kotlin
pb.setPreferredLanguages(listOf("tr", "en"))   // null goes back to the device's
```

Requests also carry `X-Palbase-SDK: android/0.4.0` (`PalbaseClient.VERSION`).

### Observable state

What an app shows is collected from the SDK's `StateFlow`s. A composable that collects one with `collectAsState()` is drawn again when it changes, so no listener is needed:

| State | What it holds |
|---|---|
| `pb.auth.isSignedIn`, `pb.auth.userId`, `pb.auth.user`, `pb.auth.state` | Who is signed in, and their session ([Auth](/docs/android/auth#who-is-signed-in)) |
| `pb.flags.values` | Every flag's value ([Flags](/docs/android/flags)) |
| `pb.socket.status` | The realtime socket's connection ([Realtime](/docs/android/realtime#the-socket)) |
| `pb.debug.isEnabled` | Whether the debug console is on for this user — with `palbase-debug`, whose extension it is ([Debug Console](/docs/android/debug-console)) |

```kotlin
@Composable
fun Account() {
    val signedIn by pb.auth.isSignedIn.collectAsState()
    val user by pb.auth.user.collectAsState()
    Text(if (signedIn) "Signed in as ${user?.email ?: "a guest"}" else "Signed out")
}
```

### Consent and the installation

`pb.consent` is what the user allowed the app to collect, by category: `Consent.Category.ANALYTICS`, `PERFORMANCE` and `DIAGNOSTICS`. Every module that collects asks it, and while a category is not granted nothing of it is made. [Analytics](/docs/android/analytics#consent) shows it at work.

`pb.installation.id` is this install of the app: 16 random bytes, kept across launches and updates, that carry nothing of the device or the user. Flags' percentages and a push token are an installation's.

## Errors and retries

A module call that is refused throws `PalbaseError` (package `studio.palbase.runtime`):

| Member | What it is |
|---|---|
| `status` | The HTTP status; `0` when the request was never answered. |
| `code` | A stable code: the server's (`invalid_credentials`, `rate_limited`, …) or the client's (`network_error`, `missing_credential`, …). |
| `message` | What happened, for a log. |
| `requestId` | The request's id, to find it in the environment's [Logs](/docs/getting-started/logs). |
| `retryAfter` | The seconds the server asked to wait, when it said. |
| `body` | The refusal's body as it was sent. |

`error.isNetworkError` (`import studio.palbase.isNetworkError`) says whether the request was never answered: no network, the host unreachable, no answer in time. A refusal made on the device, such as a bad configuration, also has status `0` and is not one, so ask this rather than `status == 0`.

The client sends a call again only when that cannot do the work twice: a read, or a write whose contract takes an `Idempotency-Key`, which the client makes once and sends with every attempt. It is sent again on a `429`, `502`, `503` or `504`, or when it never reached the server: after the server's `Retry-After` when it gave one, and otherwise after half a second, then a second, then twice that, each jittered. `RetryPolicy(attempts = 3, maxWaitSeconds = 30.0)` is the default: three attempts in all, the first included. A `Retry-After` longer than `maxWaitSeconds` is not waited for: the error goes to the caller. Every other write is sent once.

A call refused with a `401` about the token (`invalid_token`, `token_expired`, `session_expired`, `session_revoked`, `missing_token`) is refreshed once and sent again, and only for the user whose session sent it.

Your backend's refusals are a typed error of their own: [Calling Your Backend](/docs/android/backend-calls#errors).

## The pages of this section

- [Auth](/docs/android/auth): sign-up, sign-in, second factors, magic links, phone codes, guests and the session
- [Calling Your Backend](/docs/android/backend-calls): the generated client, its typed errors and retries
- [Gateways](/docs/android/gateways): a backend's realtime gateways, and the chats piped into them
- [Realtime](/docs/android/realtime): the project's channels, broadcasts and a shared state
- [Flags](/docs/android/flags): flags read without waiting, kept current
- [Analytics](/docs/android/analytics): events, screens, timings and diagnostics behind consent
- [Notifications](/docs/android/notifications): FCM push for the signed-in user, preferences and topics
- [Storage](/docs/android/storage): files through signed URLs, and public buckets
- [Purchases](/docs/android/purchases): what the customer has, and buying on Google Play
- [Voice](/docs/android/voice): a chat's live voice over WebRTC
- [Debug Console](/docs/android/debug-console): the in-app console, opened for one user

## Related

- [Introduction](/docs/getting-started/introduction): the modules, the keys and the environments
- [CLI](/docs/cli/overview): `apps:create`, `apps:env:set` and `apps:sync`
- [Machines](/docs/machines/overview): where the backends the app calls run



<!-- ===== android/auth ===== -->

# Auth

`pb.auth` signs a person in and keeps them signed in. Every flow that ends in tokens starts the client's session, and every call that acts for the user carries the access token from then on. The flows an app writes most are methods here: email and password, guests, second factors, magic links, phone codes, password and email changes, the user's sessions. Every other client call of the auth module is reachable typed as `pb.auth.api`.

Every method that reaches the server is a `suspend` function: call it from a coroutine (`lifecycleScope`, `viewModelScope`, `rememberCoroutineScope()`).

## Quick example

```kotlin
import studio.palbase.Auth
import studio.palbase.AuthAPI

// Create the account. When the project signs new users in at once, the session starts too.
val created = pb.auth.signUp("ada@example.com", "correct-horse-battery-staple")
println(if (created.accessToken != null) "signed in" else "confirm your email first")

// Sign in. A second factor, when the account has one, comes back as MfaRequired.
when (val result = pb.auth.signIn("ada@example.com", "correct-horse-battery-staple")) {
    is Auth.SignInResult.SignedIn -> println("signed in as ${result.user.id}")
    is Auth.SignInResult.MfaRequired -> {
        val code = askForCode() // the code from the authenticator app
        pb.auth.mfa.challenge(result.mfaToken, AuthAPI.MFAChallengeRequest.Type.TOTP, code)
    }
}
```

`AuthAPI` (package `studio.palbase.generated`) holds the auth module's request and answer types, generated from its contract.

## Email and password

`signUp(email, password, locale)` creates the account. `signUp(AuthAPI.SignupRequest(…))` takes the whole body, with `redirectTo`, the address the verification link lands on. What comes back is an `AuthAPI.SignupResult`: its `user`, and its tokens only when the project lets a new account sign in before it confirms its address. With email confirmation required, the user confirms first and then signs in.

`signIn(email, password)` answers one of two:

| Result | What it is |
|---|---|
| `Auth.SignInResult.SignedIn(user)` | Signed in: the session has started. |
| `Auth.SignInResult.MfaRequired(mfaToken, factors)` | The account has a second factor: finish with `mfa.challenge` or `mfa.recovery` ([Second factors](#second-factors)). `factors` names the ones it has (`totp`, `sms`, `email`, `webauthn`). |

A wrong password is a `PalbaseError` with status 401. After 10 failures in 30 minutes the account is locked for a while: `429` with `retryAfter`. The password rules are the project's auth settings, in Studio's Auth screens or `palbase auth:settings:set`.

### Confirming an email

The confirmation email carries a link, or a code when the project uses codes:

```kotlin
// The link's token, from the link the app was opened with:
pb.auth.email.verify(AuthAPI.VerifyEmailRequest(token = token))
// Or the code, with the address:
pb.auth.email.verify(AuthAPI.VerifyEmailRequest(email = "ada@example.com", code = "482913"))

// The email did not arrive:
pb.auth.email.resendVerification("ada@example.com")
```

Where an email's link lands is the project's auth settings, the same for every app: [Where email links land](/docs/web/auth#where-email-links-land).

## Guests

A guest is an account with no email or password, signed in on this device. Its session is kept and renewed like any other, and what the guest does or buys stays theirs when they become an account:

```kotlin
val guest = pb.auth.signInAnonymously()
println(guest.isAnonymous) // true

// Later: become an account under the same id. A code is mailed to the address.
pb.auth.api.convertAnonymousUser(AuthAPI.AnonymousConvertRequest(email = "ada@example.com", password = "correct-horse-battery-staple"))
pb.auth.api.verifyAnonymousConversion(AuthAPI.AnonymousConvertVerifyRequest(code = "482913"))
pb.auth.refreshSession() // the next tokens no longer say is_anonymous
```

The project must have turned guests on (its `anonymous_sign_ins` setting): otherwise sign-in is refused with `403 anonymous_sign_ins_disabled`. Until the code is redeemed the account is still a guest, and five wrong codes end the conversion.

## Second factors

A sign-in that needs a second factor answers `MfaRequired(mfaToken, factors)`. Finish it with one of these, each of which starts the session and returns the user:

| Method | What it does |
|---|---|
| `mfa.challenge(mfaToken, type, code)` | Completes the sign-in with a code. `type` is `AuthAPI.MFAChallengeRequest.Type.TOTP`, `.SMS` or `.EMAIL`. |
| `mfa.recovery(mfaToken, code)` | Completes it with a recovery code instead. |
| `mfa.sendSmsCode(mfaToken)` / `mfa.sendEmailCode(mfaToken)` | Sends the sign-in code; then `challenge(mfaToken, …SMS or …EMAIL, code)`. |

Enrolling, for the signed-in user:

```kotlin
// TOTP: the secret for the authenticator app, its otpauth:// URL and a QR code, and the recovery codes, shown once.
val totp = pb.auth.mfa.enrollTotp()
showQr(totp.otpUrl)
showOnce(totp.recoveryCodes)
pb.auth.mfa.verifyTotp("123456") // the first code the app shows confirms it

val factors = pb.auth.mfa.factors()

// Removing a factor asks for the account's password.
pb.auth.mfa.removeFactor("fac_01", currentPassword = "correct-horse-battery-staple")
```

`enrollSms(phone)` and `verifySms(code)` enroll a phone, and `enrollEmail()` the account's address.

### Stepping up

A backend route that asks for a second factor (`auth { aal: "aal2" }`), or for a recent one (`maxAge`), refuses a password sign-in with `StepUpRequired(acrValues, maxAge, …)`. Step the signed-in user up and call again:

| Method | What it does |
|---|---|
| `mfa.stepUp(code)` | With the authenticator app's code. Returns the session. |
| `mfa.sendStepUpSmsCode()`, `mfa.stepUpWithSms(code)` | By text: the first sends the code to the user's SMS factor, the second steps up with it. |
| `passkeys.stepUp(context)` | With one of the account's passkeys: the fingerprint, the face or the screen lock. |

Each keeps the session's refresh token; its refreshes stay at the new level (`TOKEN_REFRESHED` is told), and a route's `maxAge` counts from the step-up. An email code is not a way up ([Second factors and their strength](/docs/backend/authentication#second-factors-and-their-strength)).

## Passkeys

`pb.auth.passkeys` runs the system's passkey sheet through Credential Manager: the fingerprint, the face or the device's screen lock. The project publishes its registered Android apps' certificates for it ([Registering the app](/docs/android/overview#registering-the-app)).

```kotlin
// Adds a passkey to the signed-in account.
pb.auth.passkeys.register(context)

// Signs in with one of the device's passkeys for the project.
val user = pb.auth.passkeys.signIn(context)

// Opens an account with a passkey (an email is optional when the project allows it).
when (val result = pb.auth.passkeys.signUp(context, email = "ada@example.com")) {
    is Auth.Passkeys.SignUpResult.SignedIn -> showHome(result.user)
    is Auth.Passkeys.SignUpResult.ConfirmationRequired -> askToConfirm(result.userId)
}
```

| Method | What it does |
|---|---|
| `passkeys.register(context, name, userName)` | Adds a passkey to the signed-in account; asks for a recent sign-in. Returns the registered credential. |
| `passkeys.signIn(context)` | Signs in with a passkey the device holds for the project. Returns the user. |
| `passkeys.signUp(context, email, displayName)` | Opens an account with a passkey: `SignedIn(user)`, or `ConfirmationRequired(userId)` when the address is to be confirmed first. |
| `passkeys.stepUp(context)` | Steps the signed-in session up ([Stepping up](#stepping-up)). |

A sheet the user dismisses throws `passkey_cancelled` (`pb.auth.wasCancelled(e)` is true); `passkey_unavailable` is a device with no passkey or no credential provider; `passkey_exists`, a passkey the account already has on this device; `passkey_failed`, one the system refused (the app's certificate not in the project's `assetlinks.json`, most often).

## Magic links

```kotlin
pb.auth.magicLink.send("ada@example.com")

// The token from the link the email carried:
val user = pb.auth.magicLink.verify(token)
```

`send` answers the same whether or not the address has an account.

## Phone codes

```kotlin
pb.auth.phone.sendCode("+905551234567")
when (val result = pb.auth.phone.verifyCode("+905551234567", "482913")) {
    is Auth.SignInResult.SignedIn -> println("signed in as ${result.user.id}")
    is Auth.SignInResult.MfaRequired -> println("a second factor is needed")
}
```

Phone sign-in must be enabled for the project (`provider_not_enabled` otherwise). The code is texted through the project's own SMS provider.

## Passwords

```kotlin
// Forgot it: the email's link carries a token.
pb.auth.password.requestReset("ada@example.com")
pb.auth.password.confirmReset(token, "a-new-long-passphrase")

// Signed in: change it, or add one to an account that has none.
pb.auth.password.change(AuthAPI.PasswordChangeRequest(currentPassword = "a-new-long-passphrase", newPassword = "another-long-passphrase"))
if (!pb.auth.getUser().hasPassword) {
    pb.auth.password.set(AuthAPI.PasswordSetRequest(newPassword = "a-first-long-passphrase"))
}
```

## Who is signed in

The session is observable. Each of these is a `StateFlow`, so a composable that collects one is drawn again when it changes: a sign-in, a sign-out, a session auth ended (the user deleted, suspended, signed out everywhere), another process of the app signing out.

| Member | What it holds |
|---|---|
| `isSignedIn` | Whether someone is signed in. It does not change when the token is refreshed. |
| `userId` | The signed-in user's id; `null` when no one is. |
| `user` | The signed-in user as auth last answered (`AuthAPI.User`: `id`, `email`, `emailVerified`, `isAnonymous`, `roles`, `metadata`). |
| `state` | The `Session` itself: `accessToken`, `refreshToken`, `expiresAt` (epoch milliseconds), `userId`, `user`. It changes with every refresh. |
| `sessionEndReason` | Why the last session ended without the app signing out: `EXPIRED`, `REVOKED`, `USER_DELETED` or `USER_BANNED`. Set before the change is told, and `null` again once someone signs in or the app signs out. |

```kotlin
@Composable
fun Root() {
    val signedIn by pb.auth.isSignedIn.collectAsState()
    val ended by pb.auth.sessionEndReason.collectAsState()
    if (signedIn) Home() else SignIn(notice = ended?.let { "You were signed out: ${it.name.lowercase()}" })
}
```

The same changes come as events: `pb.auth.changes` is a `Flow<AuthEvent>`, and `pb.auth.onChange { event, session -> }` calls a listener and returns what stops it.

| Event | When |
|---|---|
| `SIGNED_IN` | A flow started a session. |
| `TOKEN_REFRESHED` | The access token was refreshed. |
| `USER_UPDATED` | The user's profile was read and kept with the session. |
| `SIGNED_OUT` | `signOut()`, `deleteAccount()`, or a sign-out in another process of the app. |
| `SESSION_EXPIRED` | The refresh token was refused: `sessionEndReason` says why. |

`currentSession()` reads the session without waiting. `currentUser()` is the user as auth last answered. `getUser()` reads the profile fresh (`GET /auth/me`, an `AuthAPI.MeProfile`): whether the email is verified, whether the account has a password and a second factor, its linked providers and its language. `refreshSession()` refreshes now rather than when the token is about to lapse.

### How the session is kept

The session is kept encrypted, with an AES key the Android keystore holds, in the app's no-backup files ([The client](/docs/android/overview#the-client)). While the app is in the foreground the access token is renewed a minute before it lapses, so no call waits for a refresh, and a session that auth ended is noticed within a token's lifetime without a call. In the background nothing is renewed ahead: a process woken for a push renews only when a call needs it. Before renewing, the store is read again, because another process of the app (a widget's, a push handler's) may have renewed it or signed out.

A session is bound to this device. The calls that start or renew it carry a proof signed by a key the Android keystore holds (DPoP, RFC 9449), and auth refuses to renew the session without one. A refresh token copied off the device renews nothing, and the key never leaves it.

## Signing out and deleting the account

`signOut()` ends the session on the server and here. A failed call still signs out locally. What a module must undo while the user can still be named runs first. For example, [notify](/docs/android/notifications) forgets this device for them.

`deleteAccount(password)` deletes the account, everything tied to it and its sessions, and ends the session here. An account with a password gives it, and a password missing or wrong is `401 reauth_required` with the session kept. An account without one (a guest, a phone or social account) passes nothing:

```kotlin
val me = pb.auth.getUser()
pb.auth.deleteAccount(if (me.hasPassword) askForPassword() else null)
```

## `pb.auth.api`

Every client call of the auth contract, typed (`AuthAPI.Client`), through the session's transport. A few an app reaches for:

| Call | Path |
|---|---|
| `pb.auth.api.updateMe(AuthAPI.MeUpdateRequest(locale = "tr"))` | `PATCH /auth/me` |
| `pb.auth.api.listIdentities()` | `GET /auth/identities` |
| `pb.auth.api.unlinkIdentity(id)` | `DELETE /auth/identities/{id}` |
| `pb.auth.sessions.list()`, `.revoke(id)`, `.revokeAll()` | The user's sessions on every device |

Google's sign-in is one call, `pb.auth.signInWithGoogle(context, variant)` (Google's sheet through Credential Manager). Apple, GitHub and Microsoft have none in the Android SDK at this version: their calls are in `pb.auth.api` (`socialConfig`, `socialBegin`, `socialComplete`), and a token pair a flow of the app's own ends in starts the session with `setSession(accessToken, refreshToken, expiresIn)`.

## Proof of work

The auth module may answer a sign-in, a sign-up or a code request with `403 pow_required` and a challenge when the address looks like a bot. The client solves it and sends the same request once more with the answer. You never see the challenge. One the client cannot solve comes back as `pow_unsolved`.

## Related

- [Overview](/docs/android/overview): the client, its errors and retries
- [Calling Your Backend](/docs/android/backend-calls): the access token on your own routes
- [Authentication in your backend](/docs/backend/authentication): how a machine checks the token
- [Test Users](/docs/backend/test-users): accounts made with the secret key



<!-- ===== android/backend-calls ===== -->

# Calling Your Backend

Your own backend runs on a machine at an address of its own. An Android app calls it through a client generated from the backend's contract: `palbase apps:sync` writes it into the app as `palbase/environments/<env>/palbe/<machine>.kt`, and the build compiles the variant's environment in ([The environment in the build](/docs/android/overview#the-environment-in-the-build)). Each route is a typed `suspend` function, each error the route can throw is a typed case, and every call carries the signed-in user's token.

The client needs `studio.palbase:palbase-palbe` and the kotlinx.serialization Gradle plugin, because its types are `@Serializable` classes:

```kotlin
// app/build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.plugin.serialization")
}

dependencies {
    implementation(platform("studio.palbase:palbase-bom:0.4.0"))
    implementation("studio.palbase:palbase")
    implementation("studio.palbase:palbase-palbe")
}
```

## Quick example

The backend, a `palbase/backend` app on the machine named `backend`:

```ts
// src/modules/notes/notes.controller.ts
import { Body, Controller, Get, NotFound, Param, Post, User, z, type UserT } from "palbase/backend";

const CreateNote = z.object({ title: z.string().min(1).max(200) });
type CreateNote = z.infer<typeof CreateNote>;

interface Note {
  id: string;
  owner: string;
  title: string;
}

@Controller("/notes")
export class NotesController {
  private readonly notes = new Map<string, Note>();

  @Post("")
  create(@Body(CreateNote) body: CreateNote, @User() user: UserT): Note {
    const note = { id: crypto.randomUUID(), owner: user.id, title: body.title };
    this.notes.set(note.id, note);
    return note;
  }

  @Get("/{id}")
  read(@Param("id") id: string, @User() user: UserT): Note {
    const note = this.notes.get(id);
    if (!note || note.owner !== user.id) throw new NotFound("no such note");
    return note;
  }
}
```

The app, after `palbase apps:sync`:

```kotlin
import studio.palbase.generated.*   // the backends' clients and their types

val note = pb.backend.notes.create(NotesCreateRequest(title = "Groceries"))

val again = try {
    pb.backend.notes.read(note.id)
} catch (e: NotesReadError) {
    when (e) {
        NotesReadError.NotFound -> null                 // the route's own error, typed
        is NotesReadError.Other -> throw e.backend      // anything else: a BackendError
    }
}
```

## The generated client

`apps:sync` writes one Kotlin file for each backend of each environment the app is set in, in the package `studio.palbase.generated`:

- **The backend** is a property of the client: `pb.<name>`. The name is the machine's, camelCased (`pb.shopApi` for the machine `shop-api`), unless `palbase apps:sync --as shop-api=shop` names it. It is the same in every environment.
- **A namespace per controller, a function per route.** `NotesController`'s `create` is `pb.backend.notes.create(…)`, as the backend's contract names it.
- **Its types** are named after the route: `NotesCreateRequest` (the body), `NotesCreateQuery` (the query string), `NotesCreateResponse` (the answer) and `NotesCreateError`. A path parameter is a `String` argument.
- **Its gateways** are classes the app joins: [Gateways](/docs/android/gateways).

A backend the environment does not name is not a build error: each of its calls fails with `BackendError.NotConfigured`, in the route's `Other`. Run `palbase apps:sync` again when the backend's routes change. `palbase apps:sync --backend <dir>` makes the client from a backend's checkout on this computer, to call an endpoint before any machine serves it ([`apps:sync`](/docs/cli/reference#palbase-appssync)).

## What a call carries

A call goes to the address the environment names for the machine, with:

- the signed-in user's access token, when someone is signed in. When the session is bound to the device ([Auth](/docs/android/auth#how-the-session-is-kept)), the request also carries a proof signed by the device's key. When no one is signed in, the call goes without a token, and the route decides whether it needs one;
- no API key: a machine asks for none;
- `Accept-Language`, the user's languages, which the backend's translations read;
- an `Idempotency-Key` on every write;
- a field the route marks `encrypted()` sealed, and one it answers through `encrypt()` opened when the answer arrives: the client `palbase apps:sync` wrote holds the project's id and signing key for it ([Encrypted Requests](/docs/backend/request-encryption)). A call sent again is the same sealed request.

A call refused with a `401` about the token is refreshed once and sent again, for the same user. A read is sent again when the answer says "not now" (`429`, `502`, `503`, `504`) or the request never got an answer, as the project's calls are ([Errors and retries](/docs/android/overview#errors-and-retries)). A write is sent again only when the backend's contract says the route keeps its idempotency key, and always with the same key. Any other write is sent once, because one that reached the backend before its answer was lost would be done twice. No redirect is followed.

## Errors

Each generated function throws its route's own error type: a sealed class with a case for every error the backend's contract says the route can throw, and `Other` for the rest.

```kotlin
// palbase/environments/staging/palbe/backend.kt, as apps:sync wrote it (shortened)
sealed class NotesReadError(message: String, cause: Throwable? = null) : Exception(message, cause) {
    data object NotFound : NotesReadError("not_found")   // 404 not_found: the route throws NotFound
    data class Other(val backend: BackendError) : NotesReadError("Backend error", backend)
}
```

The contract's errors are what the route throws, as the backend's build reads them from its code: the framework's error classes and your own. A case is matched on the answer's status and code.

`Other` carries a `BackendError` (package `studio.palbase.backend`):

| Case | What it is |
|---|---|
| `Http(status, code, description, requestId, details, data)` | An answer that is not 2xx, as the backend sent it in its error envelope. `decodeData(serializer)` reads `data` as a type of yours. |
| `Validation(fields, …)` | A `400` that names fields: each `FieldError(field, message)`. |
| `Unauthorized(…)` | A `401` after the refresh did not mend it. |
| `RateLimited(retryAfter, …)` | A `429`, with the seconds to wait. |
| `IntegrityRequired(code, …)` | A `401 app_attest_required` the device's proof could not settle: the SDK enrolled, proved and sent the call again, and the backend still refused ([Device attestation](#device-attestation)). |
| `AttestationUnavailable(reason, …)` | The route asks for the device's proof and this device cannot give one: an emulator or a key that is not in secure hardware (`hardware_key_unavailable`, `software_key`), an unlocked bootloader (`device_not_locked`), the keystore not answering now (`keystore_unavailable`, asked again later). Nothing more is sent. |
| `StepUpRequired(acrValues, maxAge, …)` | A `401 insufficient_user_authentication`: the route asks for a stronger sign-in (`acrValues`, e.g. `urn:nist:800-63:aal2`). The session is fine and is not refreshed: step the user up with their second factor — `pb.auth.mfa.stepUp(code)` with an authenticator code, `pb.auth.mfa.stepUpWithSms(code)` after `sendStepUpSmsCode()`, or `pb.auth.passkeys.stepUp(context)` with a passkey — then call again (`maxAge` counts from the step-up); the session holds the aal2 token from then on, refreshes included. |
| `Network(ioCause)` | No answer: no network, the host unreachable. |
| `Decoding(decodeCause)` | A 2xx whose body is not what the contract declares. |
| `Encoding(encodeCause)` | The request could not be written; it was not sent. |
| `NotConfigured` | The environment names no such backend: run `palbase apps:sync`. |

`Http`, `Validation`, `Unauthorized` and `RateLimited` have the answer behind them in `envelope`: the status, the code, the message and the request id, whatever they were classified as. A generated error matches its cases against it, so a route that declares a `401` or a `429` of its own still gets its typed case.

## Device attestation

A route the backend marks `attest: true` is called only by your app on a genuine phone ([Device attestation](/docs/backend/authentication#device-attestation)). The SDK proves each call by itself:

- once per install, it makes a key in the phone's secure hardware and enrols it: auth checks the key's attestation chain against Google's roots and revocation list, that the phone is locked with a verified boot, and that the app is your registered package signed with one of its registered certificates;
- each call to the backend then carries a signature with that key over the call's method, path, body and a short-lived challenge, and a counter, so a captured call cannot be sent again or changed;
- a `401 app_attest_required` is answered by itself: enrol if needed, prove, send once more.

What only you set: the SHA-256 of the certificates your releases are signed with, registered with the app (`palbase apps:env:set <app> --sha256 play_signing=AB:CD:…`; Play's app signing key and your upload key). Do not register a debug key where attestation is enforced: a debug build can be driven over adb to sign requests. An emulator cannot attest: under enforce its calls end in `AttestationUnavailable`.

## Uploads

A route the backend declares with `@Upload` takes the file in the app's call: the call goes to the project's storage, which writes the file where the route's template says and then runs the route's handler with it ([Upload routes](/docs/backend/direct-uploads#upload-routes)). Its generated function takes the bytes, a file name, an optional content type and a progress callback:

```kotlin
// ProfileController's @Upload("/avatar", …) avatar route, with no body of its own:
val avatar = pb.backend.profile.avatar(
    file = bytes,
    filename = "me.jpg",
    contentType = "image/jpeg",
    onProgress = { p -> progress = p.fraction },   // UploadProgress: phase, bytesSent, totalBytes
)
```

A route with path parameters, a body or a query string takes them first, in that order, as any generated call does, and then the file.

`UploadProgress.phase` is `UPLOADING` while the bytes go, then `PROCESSING` while the backend's handler runs, with `fraction` at 1. A content type left out is read from the bytes, then from the file name's extension. What the handler answers is the call's answer (`ProfileAvatarResponse` here), and a refusal it throws deletes the file. A file a backend signed an upload URL for goes through [Storage](/docs/android/storage) instead.

## Untyped calls

A route the generated client does not have yet can be called by its path, with types of yours: a `POST`, its body as JSON.

```kotlin
import studio.palbase.backend.call
import kotlinx.serialization.Serializable

@Serializable data class Todo(val id: String, val title: String)
@Serializable data class NewTodo(val title: String)

val todo = pb.backend.call<NewTodo, Todo>("todos/create", NewTodo("Milk"))   // POST /todos/create
```

A path built from a value is held to plain path segments, and anything else is refused before it is sent.

## A backend on your computer

`pb.palbe(URI("http://10.0.2.2:8080"))` (`import studio.palbase.backend.palbe`) is a client of a backend at an address of its own: in a debug build, one running on the computer the emulator runs on. It carries the user's token as the environment's backends do. The generated namespaces hang on the backend's own type, `PB<Name>Backend`, which the app's module can make around it:

```kotlin
val local = PBBackendBackend(pb.palbe(URI("http://10.0.2.2:8080")))
val note = local.notes.create(NotesCreateRequest(title = "Groceries"))
```

## Related

- [Gateways](/docs/android/gateways): a backend's realtime gateways, and the chats piped into them
- [Controllers & Routing](/docs/backend/controllers): the routes a client is generated from
- [Responses & Errors](/docs/backend/errors): the error envelope and the error classes
- [Authentication](/docs/backend/authentication): how a machine checks the token



<!-- ===== android/gateways ===== -->

# Gateways

A [gateway](/docs/backend/gateways) is a realtime channel of your backend: a `@Gateway` class that says who may join, the events it sends, the messages its members may send and the ack each one is answered with. `palbase apps:sync` writes each of the backend's gateways into the app's generated client ([Calling Your Backend](/docs/android/backend-calls)) as a class of its own. The app joins it with the pattern's values, and writes no channel name, event name or payload type of its own.

## Quick example

For the backend's `RoomGateway` (`@Gateway("room:{roomId}")`, with the events `message` and `welcome` and the message `say`, in [Gateways](/docs/backend/gateways#quick-example)), the generated client has `RoomGateway(roomId)`, its events as `RoomGatewayEvent`, and its messages as `RoomGatewaySend`:

```kotlin
import studio.palbase.backend.join
import studio.palbase.generated.*

val room = pb.backend.join(RoomGateway(roomId = "42"))   // returns once the backend let the user in

val listening = room.on { event ->
    when (event) {
        is RoomGatewayEvent.Message -> show("${event.payload.from}: ${event.payload.text}")
        is RoomGatewayEvent.Welcome -> show("${event.payload.members} in the room")
    }
}

// The backend's ack, typed: what its @Subscribe("say") returned.
val said: RoomGatewaySayReply = room.send(RoomGatewaySend.Say(RoomGatewaySayMessage(text = "hello")))

room.off(listening)
room.leave()
```

In Compose, hold the handle while the screen is on screen and leave it when the screen goes:

```kotlin
@Composable
fun Room(roomId: String) {
    val lines = remember { mutableStateListOf<String>() }
    LaunchedEffect(roomId) {
        val room = pb.backend.join(RoomGateway(roomId = roomId))
        room.on { event -> if (event is RoomGatewayEvent.Message) lines += event.payload.text }
        try { awaitCancellation() } finally { room.leave() }
    }
    LazyColumn { items(lines) { Text(it) } }
}
```

## Joining

`pb.<name>.join(gateway, history = true)` opens the project's socket if it is not open, and returns once the backend let the signed-in user in. Each `{param}` of the pattern is a constructor argument: a value that is empty or holds a `:` would name another channel, and is refused with `invalid params` before anything is sent.

| Member of the handle | What it does |
|---|---|
| `on { event -> }` | Listens to every event the gateway declares, as its sealed type. Returns a `GatewayRegistration`. |
| `off(registration)` | Stops one listener. |
| `send(message)` | Sends one message and waits for the backend to take it. It returns the ack, typed as the message says, or throws `PBGatewayError`. |
| `leave()` | Drops the handle's listeners and lets go of the channel. |
| `topic` | The channel: `room:42`. |
| `seq` | A durable gateway's number of the last event its channel was sent; `null` on one that keeps nothing. |

Only a signed-in user joins: the access token the socket carries is who they are. Two handles of the same channel share one membership, and the channel is left with the last of them. A gateway with members is one its backend still runs for, so leave a handle when its screen goes.

An event the generated client does not know, from a backend that moved ahead of it, is not delivered, and a listener that throws does not take the socket down. A listener is called on the socket's thread, not the main thread: hand what it gets to state a composable reads, or to the main thread.

## Messages and acks

`send` returns what the backend's `@Subscribe` returned. A message goes to the backend alone, never to the other members, who hear what the backend emits. It throws `PBGatewayError`, whose `reason` says why the message was not taken:

| `reason` | What it means |
|---|---|
| The backend's own word | Its method threw `GatewayRefusal("…")`: `no_commands`, `not_your_turn`. Act on it. |
| `forbidden` | The user may only listen on this channel, or the platform refused with no reason given. |
| `rate_limited` | Past the project's events per second. |
| `unavailable` | The backend could not be asked just then. Worth trying again. |
| `no reply`, `socket closed` | No answer came. The message may have been taken. |
| `not joined` | Nothing was sent: the handle was left, or its socket closed for good. |
| `undecodable reply` | The backend took it, but its ack is not what this client reads: a backend that moved ahead of the app. |

A join that is refused throws `PBGatewayError` too: `unauthorized` when the backend did not let the user in, `unavailable` when it could not be asked, and `rate_limited` past the project's limits. `PBGatewayError` has the reasons the client names as constants: `PBGatewayError.UNAUTHORIZED`, `FORBIDDEN`, `NOT_JOINED`, and the others.

## Durable gateways

A [durable gateway](/docs/backend/gateways#durable-gateways) keeps what it sends. A handle that joins one is sent what it keeps first, in order, then what comes after. `join(gateway, history = false)` asks for only what comes after the join. The channel's first handle decides: a second handle of the same channel gets the events from where it joins.

When the socket drops, the channel is joined again after `seq`: the handle is sent what it missed, in order, and nothing twice.

## When the connection drops

The socket reconnects by itself ([Realtime](/docs/android/realtime#the-socket)), and every gateway that was joined is joined again with it. An event that a gateway that is not durable sent while the socket was down is not delivered.

When the socket closes for good, every handle on it ends: its listeners are dropped, and `send` throws `not joined`. That happens on a sign-out, or when another user signs in. Join again, as the user who is there now.

## Chat gateways

A gateway declared with `chat: true` carries a chat of the project's agents, which the platform writes into its channel ([AI](/docs/backend/ai#a-chat-in-an-app)). Its generated class is a `PBChatGateway`, and joining it returns a `ChatGatewayHandle`. That handle is the gateway's own (`on`, `send`, `leave`) and also has `chat`: the chat's state, folded from what the platform writes there, from the chat's start, then each change as it comes.

```kotlin
@Composable
fun Support(support: ChatGatewayHandle<SupportGatewayEvent, SupportGatewaySend>) {
    val chat by support.chat.state.collectAsState()
    LazyColumn {
        items(chat.items, key = { it.key }) { item ->
            when (item) {
                is PBChat.Item.Message -> Text(item.message.text)
                is PBChat.Item.Response -> Text(item.response.text)
                is PBChat.Item.Goal -> Text(item.event.kind.value)
                is PBChat.Item.Voice -> Text(item.event.status.value)
            }
        }
    }
}
```

What the user does in the chat (a message, a yes or a no, stop) is the gateway's own typed messages, which its backend acts on: `support.send(SupportGatewaySend.Say(SupportGatewaySayMessage(text = "Merhaba")))`. The chat's state says what is, and never sends.

`support.chat.state` is a `StateFlow<PBChat.State>`, and `support.chat.updates` the same states as a flow that ends when the gateway is left. A change is told after the parts that made it: a run of an answer's text is one change.

| Member of `PBChat.State` | What it is |
|---|---|
| `items` | The conversation in order: `PBChat.Item.Message`, `.Response`, `.Goal` (a word of the chat's goal) and `.Voice` (the chat's voice began or ended). Each has a stable `key`. |
| `messages` | Each member's (or the server's) message: `text`, `author` (`null`: the server), `authorName`, `status` (pending until the agent has it, then delivered or failed), `kind` (text, or voice for a line said in the chat's voice), `attachments`, and `mine`. |
| `responses` | Every answer, a subagent's too, as it began. An answer's `parts` split its text at its tools (`PBChat.Part.Tool`), its subagents (`.Agent`) and the model's reasoning (`.Thinking`). |
| `turn` | The last turn: its `status`, and its `error` or what it is `waiting` on. |
| `waiting` | What waits for the signed-in user: `approvals`, tool calls of their own turns waiting for their yes, and `outputs`, client tools waiting for the app's answer. |
| `goal` | The chat's goal, once one was set. |
| `voice` | The chat's voice, the last that began in it, live or ended. See [Voice](/docs/android/voice). |
| `forkedFrom` | A fork's: the chat it was forked from, and the message it was cut before. |

### The chat's past

The channel keeps a day of the chat. `chat.loadOlder(pb, chatId)` reads the page before what the state holds (`GET /ai/chats/{id}/parts`) and folds it in front, each part once. It reads with the member's own session, which the project allows its app's users with its AI settings' `clients` (`Palbase.ai.settings.put`, [AI](/docs/backend/ai#chats)). It returns whether there is more before it, and `chat.hasOlder` says the same without reading.

```kotlin
while (support.chat.loadOlder(pb, chatId)) {
    if (enoughShown()) break
}
```

When the project's app reaches no chat of its own, the app's backend can read the page for it: `support.chat.loadOlder { query -> … }` hands the lambda the page asked for (`PBChat.PartsQuery`: `before`, `cursor`, `limit`), and the lambda answers it as a `PBChat.PartsPage(parts, nextCursor)` read through a route of yours.

### Attachments, tool calls and workspace files

A message's pictures and files are read back with the member's session:

```kotlin
import studio.palbase.realtime.chatAttachment

val picture = message.attachments.first { it.kind == PBChat.AttachmentKind.IMAGE }
val bytes = pb.chatAttachment(chatId, message, picture)
val bitmap = BitmapFactory.decodeByteArray(bytes, 0, bytes.size)
```

`pb.chatToolCall(chatId, callId)` reads a tool call's whole answer, where the channel shows its last 16 KiB. `pb.chatWorkspaceFile(chatId, path)` reads a file of the chat's workspace. Both throw `PalbaseError` like any project call. Attaching a file is the backend's: the app uploads it, and the backend sends the message naming it.

## Related

- [Gateways](/docs/backend/gateways): declaring one in the backend
- [AI](/docs/backend/ai): chats, their agents and their voice
- [Realtime](/docs/android/realtime): the socket the gateways share
- [Calling Your Backend](/docs/android/backend-calls): the generated client



<!-- ===== android/realtime ===== -->

# Realtime

`pb.realtime` (`studio.palbase:palbase-realtime`) is the project's channels: what members broadcast on them, and a state each channel's members share. The channels go over the project's one realtime socket, `pb.socket`, which every module that needs one shares. It opens the first time a channel is joined and never before, so an app that only signs in or captures analytics opens none.

> **Note:** Your own backend's realtime channels are its gateways, joined through the generated client: typed events, and messages the backend answers with an ack ([Gateways](/docs/android/gateways)). This page is the socket under them, and the channels the project declares by name.

## Quick example

```kotlin
import studio.palbase.realtime.realtime
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

val room = pb.realtime.channel("room:42")

val stop = room.onBroadcast("message") { payload ->
    println("${payload["from"]}: ${payload["text"]}")
}
room.onRefused { refusal -> println("refused: $refusal") }   // {event, reason}

room.join()   // throws the server's reason when it does not let the user in
room.broadcast("message", buildJsonObject { put("from", "ada"); put("text", "hello") })

// later:
stop()
room.leave()
```

## Channels

`pb.realtime.channel(name)` is the channel of that name. Names are `:`-separated segments.

| Member | What it does |
|---|---|
| `join()` | Joins, and returns once the server let the user in. Throws `PalbaseError` when it did not ([Who may join](#who-may-join)). |
| `leave()` | Leaves the channel. |
| `onBroadcast(event) { payload -> }` | Listens to one broadcast event, a member's or the platform's. Returns what stops it. |
| `broadcast(event, payload)` | Sends an event to the channel's other members; the sender does not hear its own. The server says nothing of one it takes. |
| `onRefused { refusal -> }` | Listens to the server refusing a broadcast: `{event, reason}`, with reasons such as `forbidden` and `rate_limited`. |
| `entries` | The channel's state as the server last told it: a `Map<String, RealtimeChannel.Entry>`, each a `value` and its `life`. |
| `onState { entries -> }` | Called with the whole state each time it changes. Returns what stops it. |
| `set(key, value, life)` | Writes one entry, and returns once the server took it; a refusal is thrown. The state changes when the server says so (its next change), for every member alike. |
| `deleteOwn(key)` | Removes an entry this membership wrote, as `set` does. Every other member's entry stays theirs. |

A channel's state is a keyed map that outlives the connections reading it. A `Life.DURABLE` entry (the default) stays until it is removed. A `Life.EPHEMERAL` one is its writer's presence, gone when the writer leaves:

```kotlin
import kotlinx.serialization.json.JsonPrimitive

room.onState { entries ->
    val here = entries.filterValues { it.life == RealtimeChannel.Life.EPHEMERAL }.keys
    println("in the room: $here")
}
room.join()
room.set("presence:${pb.auth.userId.value}", JsonPrimitive("online"), RealtimeChannel.Life.EPHEMERAL)
```

The state arrives whole as a snapshot when the channel is joined, then as changes. A change that does not follow from the state held means something was missed, and the client asks for the whole state again. While the channel is not joined, `entries` is empty. Listeners are called on the socket's thread.

## Who may join

A channel name is a string a client chooses, so proving who you are says nothing about which channels are yours. The project **declares** its channels, and a channel that no declaration matches belongs to no one. A server declares them with `PUT /realtime/channels` and the secret key, or from a terminal:

```sh
palbase realtime:channels:set --file channels.json
```

```json
{
  "channels": [
    { "pattern": "user:{uid}", "kind": "owner" },
    { "pattern": "room:{id}", "kind": "public", "publish": true, "state_read": true, "state_write": true }
  ]
}
```

| `kind` | Who joins |
|---|---|
| `owner` | The pattern's one `{name}` segment is the joining user: `user:{uid}` is joined by that user alone, who may do everything on it. |
| `public` | Any signed-in user of the project, with the rights the declaration gives: `publish` (broadcast), `state_read`, `state_write`. |

Patterns match in their order, and the first one decides. A declared channel is joined only by a signed-in user, whose access token goes with each join. See [Channels](/docs/backend/channels).

A refused join throws `PalbaseError` with the code `join_refused` and the server's reply in its `body`: `unauthorized`, `forbidden`, `invalid_topic`, `rate_limited`, `too_many_channels`, `state_budget` or `unavailable`. Only `unavailable` is worth trying again. A join that got no answer at all is `join_failed`.

## The socket

`pb.socket.status` is the socket's connection as a `StateFlow`, and `pb.socket.statusChanges` every change in order:

| `RealtimeSocket.ConnectionState` | What it means |
|---|---|
| `IDLE` | Never opened: nothing has joined a channel yet. |
| `CONNECTING` | Being opened. |
| `CONNECTED` | Open, and the channels wanted are joined on it. |
| `RECONNECTING` | Dropped (the network went, a heartbeat was not answered), and opened again after a pause. |
| `DISCONNECTED` | Closed by the client: the user signed out, or no channel is wanted any more. |

```kotlin
@Composable
fun Connection() {
    val status by pb.socket.status.collectAsState()
    if (status == RealtimeSocket.ConnectionState.RECONNECTING) Text("Reconnecting…")
}
```

The socket sends a heartbeat every 25 seconds. A socket that drops is opened again after 0.5, 1, 2, 5, 10, then every 30 seconds, each pause jittered, and every channel still wanted is joined again. A broadcast sent while the socket was down is not delivered: broadcasts are delivered at most once. A channel's state comes back whole with the snapshot of the new join. `pb.socket.reconnects` counts the reopens.

### One socket, one user

The socket opens at `wss://<ref>.palbase.studio/realtime/v1/websocket`, the project's address. The publishable key goes in its `x-api-key` header, never in the address. When the session is bound to the device, the user's token and a proof signed by the device's key go there instead. Who the user is, is the access token each join carries, and a refreshed token is pushed to the joined channels without leaving them.

The socket is one person's. When the user signs out, someone else signs in, or the session ends, the client closes it, and every channel with it. Join again for the user who is there now:

```kotlin
import studio.palbase.session.AuthEvent

suspend fun joinMine() {
    val user = pb.auth.userId.value ?: return
    val mine = pb.realtime.channel("user:$user")
    mine.onBroadcast("note") { payload -> println("for me: $payload") }
    mine.join()
}

// scope: a CoroutineScope of the app's own.
pb.auth.onChange { event, _ ->
    if (event == AuthEvent.SIGNED_IN) scope.launch { joinMine() }
}
```

`pb.socket.disconnect()` closes the socket. The next join opens a new one.

## Limits

The project holds its clients to limits the platform sets and the project may lower (`PUT /realtime/limits` from a server, or `palbase realtime:limits:set`): connections open at once, broadcasts and state writes per second, joins per second, channels per connection. A frame over 1 MiB closes the socket. A project over its connection limit, or whose realtime quota is used up, is refused a new socket.

## Related

- [Gateways](/docs/android/gateways): your backend's channels, typed, with messages and acks
- [Channels](/docs/backend/channels): declaring who may join what
- [Realtime in your backend](/docs/backend/realtime): broadcasting and writing state from a server
- [Flags](/docs/android/flags): kept current over the same socket



<!-- ===== android/messaging ===== -->

# Messaging

`pb.messaging` is the signed-in person's conversations on Android: their list, each conversation's timeline and its threads as `StateFlow`s Compose collects, kept in the app's own SQLite between launches and current over the project's socket. The app writes; it opens no socket, appends nothing and syncs nothing itself. A message's push brings its conversation onto the phone even while the app is closed. What the module is — history, encryption, timers, moderation, prices — is [Messaging](/docs/messaging/overview).

## Install

Palbase's packages come from its own repository; let the `studio.palbase` group come from there alone:

```kotlin
// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        exclusiveContent {
            forRepository { maven("https://palgroup.github.io/palbase-android/") }
            filter { includeGroup("studio.palbase") }
        }
    }
}
```

```kotlin
// app/build.gradle.kts
dependencies {
    implementation(platform("studio.palbase:palbase-bom:0.7.0"))
    implementation("studio.palbase:palbase")
    implementation("studio.palbase:palbase-notify")     // pushes: the FCM token, and the service that draws them
    implementation("studio.palbase:palbase-messaging")  // pb.messaging
}
```

## Quick example

```kotlin
@Composable
fun Inbox(pb: PalbaseClient, open: (String) -> Unit) {
    // The person's conversations, the latest first: drawn from the phone at once, then kept current.
    val list by remember { pb.messaging.conversations() }.state.collectAsState()
    Text("${list.unread} unread")
    LazyColumn {
        items(list.items, key = { it.id }) { c -> Text(c.title ?: "Chat", Modifier.clickable { open(c.id) }) }
    }
}

@Composable
fun Chat(pb: PalbaseClient, id: String) {
    val chat = remember(id) { pb.messaging.conversation(id) }
    val state by chat.state.collectAsState() // entries: its messages and those on their way; members; typing
    val scope = rememberCoroutineScope()
    var text by remember { mutableStateOf("") }
    LazyColumn { items(state.entries) { e -> Text(e.toString()) } }
    TextField(text, { text = it })
    Button(onClick = {
        val words = text
        text = ""
        scope.launch { chat.send(words) } // drawn at once; with no network, sent once it is back
    }) { Text("Send") }
}
```

`pb.messaging.direct(userId)` is the direct conversation with someone (the one there is, or a new one, shown to them with its first message). A message waits in the outbox while the phone is offline and goes once it can, once. Files are encrypted on the phone (AES-256-GCM) before they are uploaded; `pb.messaging.open(message, attachment)` downloads and decrypts one, and a message seen once gives its files by `pb.messaging.viewOnce(message)` alone.

## Pushes

The app uses its own Firebase project:

- put `app/google-services.json` in the app and apply the `com.google.gms.google-services` plugin;
- connect the same Firebase project to the Palbase project as its FCM push provider ([Notifications](/docs/android/notifications));
- touch `pb.notify` at launch: the installation's token is registered — the installation's while no one is signed in, the person's once someone is;
- on Android 13 and later, the app asks for `POST_NOTIFICATIONS` (the permission is in the module's manifest; asking is the app's).

`palbase-notify` brings its FCM service with its manifest: nothing more to declare. The project sends data messages, and the SDK draws them.

## Messages that arrive while the app is closed

Nothing to set up. While the app is closed or in the background, a message's push is drawn, and the same push reads its conversation into the phone's copy: open the app with no network and it is there.

## A message while the app is open

While the app is in front, a message's push is not drawn in the tray: its conversation is synced, and `pb.messaging.incoming` — a `SharedFlow<Message>` — gives the app each message someone else wrote that is new to the phone, once, whether the socket or the push brought it first. A sync, a page read, the person's own messages, system messages and removed ones never come through it. Skip the conversation on the screen:

```kotlin
var banner by remember { mutableStateOf<Message?>(null) }
LaunchedEffect(Unit) {
    pb.messaging.incoming.collect { m -> if (m.conversationId != openConversationId) banner = m }
}
banner?.let { m -> IncomingBanner(m) { banner = null; openConversationId = m.conversationId } }
```

## Screenshots

While a photo or a video seen once is shown, keep the window out of screenshots and recordings (`FLAG_SECURE`): they come out black.

```kotlin
DisposableEffect(Unit) {
    val release = pb.messaging.protectViewOnce(activity)
    onDispose { release() }
}
```

In vanish mode, a screenshot taken while the conversation is open is told to the others (Android 14 and later; `DETECT_SCREEN_CAPTURE` is in the module's manifest):

```kotlin
DisposableEffect(id) {
    val stop = pb.messaging.watchScreenshots(activity, id)
    onDispose { stop() }
}
```

## A deleted group

When a group's owner or an admin deletes it — or its last member leaves — it goes from everyone's `conversations()` at once, and those who were in it can still report it for 14 days ([Messaging](/docs/messaging/overview#moderation)). `pb.messaging.deletedGroups` is a `StateFlow<List<DeletedGroup>>` of the groups the person can still report, the latest to stop first, each with `id`, `title`, `deletedBy` and `reportableUntil`; one goes at its `reportableUntil`. `report` names it by its id with no message; the last 30 messages the person saw in it go with the report. A group the project's server deleted is not among them.

```kotlin
val deleted by pb.messaging.deletedGroups.collectAsState()
deleted.forEach { group -> Text(group.title ?: "a group") }

deleted.firstOrNull()?.let { group ->
    pb.messaging.report(MessagingAPI.ReportRequest(conversationId = group.id, reason = MessagingAPI.ReportRequest.Reason.HARASSMENT, userId = group.deletedBy))
}
```

The title is the one the device had; it is null when the device no longer had the group as the word came — on the deleter's own device now and then.

## Signing out

The phone's copy is kept in the app's own SQLite, in files not backed up. When the person signs out it is dropped, unless `pb.messaging.keepOnSignOut = true` — then it is theirs again when they come back. Whoever signs in next never reads it; and unless copies are kept, the person who signs in drops any other's left there.



<!-- ===== android/flags ===== -->

# Flags

`pb.flags` (`studio.palbase:palbase-flags`) is the project's flags as this reader sees them: each value resolved by the project for the app's platform, version and language, the signed-in user and their own values. It is read without waiting, because the values the app last had are kept on the device and are what it starts with. It is kept current: a change made in Studio reaches the app over the project's socket within moments, with no call of yours.

## Quick example

```kotlin
import studio.palbase.flags.flags

// Read now, with a default for a flag the app does not have (yet).
if (pb.flags.bool("checkout.new_flow", default = false)) showNewCheckout()
val greeting = pb.flags.string("home.greeting", default = "Hello")
val limit = pb.flags.int("cart.max_items", default = 20)
```

In Compose, collect the values, and the screen is drawn again when one changes:

```kotlin
import kotlinx.serialization.json.JsonPrimitive

@Composable
fun Greeting() {
    val flags by pb.flags.values.collectAsState()
    val text = (flags["home.greeting"] as? JsonPrimitive)?.takeIf { it.isString }?.content ?: "Hello"
    Text(text)
}
```

## Reading values

| Member | What it returns |
|---|---|
| `bool(key, default)`, `string(key, default)`, `number(key, default)`, `long(key, default)`, `int(key, default)` | The flag's value as that type, or `default` when there is no such flag or its value is another type. |
| `decode<T>(key)` | An object flag as a `@Serializable` type of yours; `null` when it is missing or does not fit. `decode(key, deserializer)` takes the serializer. |
| `value(key)` | The value as JSON (`JsonElement`), or `null`. |
| `all` | Every flag's value by key. |
| `values` | The same, as a `StateFlow<Map<String, JsonElement>>`. |
| `source(key)` | Where the value came from, as the project says: `override` for the user's own value. |
| `version` | The version the values are current as of. |

```kotlin
import kotlinx.serialization.Serializable

@Serializable
data class Banner(val title: String, val color: String)

val banner = pb.flags.decode<Banner>("home.banner")
```

A value is any JSON the flag's type allows: a boolean, a number, a string or an object.

## A signed-in user's values

The values are one reader's: the signed-in user's, or, with no one signed in, this app's. The values kept on the device are read at launch only when they are the same reader's. When someone signs in or out, the values held go (`values` is empty, and a listener is told their keys), the new reader's are read, and the listener is told again. One reader's values are never shown to another, even for the moment the new ones take to arrive.

## What a value is resolved from

Every read is resolved by the project for its reader, in this order: the user's own value when a signed-in user has one ([Users' own values](/docs/backend/flags#users-own-values)), then the variant of an experiment running on the flag, then the flag's first condition that matches, then its default ([How a value is resolved](/docs/backend/flags#how-a-value-is-resolved)).

What the client says about itself, with every read:

| Header | Sent as |
|---|---|
| `X-Platform` | `android` |
| `X-OS-Version` | The device's Android version (`Build.VERSION.RELEASE`) |
| `X-Palbase-Client-Version` | The app's `versionName` |
| `Accept-Language` | The user's languages ([Languages](/docs/android/overview#languages)) |
| `X-Palbase-Installation` | `pb.installation.id`, with each snapshot: the install a percentage places, counted toward which versions of your app are in use |

The country a condition reads is that of the address the request came from: the device's own, because the app calls the project directly.

At this version the Android SDK records no `$flag_exposure` analytics event when it reads a value an experiment gave.

## Keeping up to date

The flags start being kept current the first time `pb.flags` is used: the latest values are read, and the client joins the project's two flags channels on its socket.

| Channel | Who joins | What it says |
|---|---|---|
| `flags:<ref>` | Anyone reading the project's flags, with no one signed in too | The project's flags changed. |
| `flags:<ref>:<user_id>` | That user only | That user's own values changed. |

Told of a newer version, the client asks for what changed since the one it holds (`GET /flags/delta`). When the delta can no longer bring its values up to date, the project answers `410`, and the client reads a whole snapshot instead (`GET /flags/snapshot`, sent with the `ETag` of what it holds, answered `304` when nothing changed). A sign-in or a sign-out reads the values again for whoever is signed in now.

To hear which flags changed:

```kotlin
val stop = pb.flags.onChange { keys -> println("changed: $keys") }
// or, in a coroutine: pb.flags.changes.collect { keys -> … }
```

`pb.flags.refresh()` brings the values up to date now: what changed since the version held, or a snapshot. It throws `PalbaseError` when the project could not be read, and the values held stay as they are.

## Turning a flag on for one user

A user's own value wins over the flag's conditions: give one from a server ([Users' own values](/docs/backend/flags#users-own-values)) or from a terminal, and it reaches their device on their channel:

```sh
palbase flags:users:set <user-id> checkout.new_flow true
palbase flags:users:get <user-id>
```

The debug console is opened for one user the same way ([Debug Console](/docs/android/debug-console)).

## Related

- [Flags in your backend](/docs/backend/flags): defining flags, conditions and users' own values
- [Realtime](/docs/android/realtime): the socket the changes come over
- [Overview](/docs/android/overview): the client and its observable state



<!-- ===== android/analytics ===== -->

# Analytics

`pb.analytics(startingConsent)` (`studio.palbase:palbase-analytics`) is the app's analytics, performance samples and diagnostics, each behind its consent category: events the app captures and screens it shows (analytics), timings (performance), and its log and failed requests (diagnostics). Nothing waits on it. What is collected is held and sent together, and a send that fails is let go.

## Quick example

```kotlin
import studio.palbase.Consent
import studio.palbase.analytics.analytics
import kotlinx.serialization.json.JsonPrimitive

// Nothing is collected until the person says yes.
val analytics = pb.analytics(startingConsent = Consent.State.DENIED)

// The person's choice, from the app's consent screen:
pb.consent.set(Consent.Category.ANALYTICS, Consent.State.GRANTED)

analytics.screen("Checkout")
analytics.capture("checkout_started", mapOf("items" to JsonPrimitive(3), "plan" to JsonPrimitive("pro")))
```

`pb.analytics(…)` is made once. The first call's starting consent is the one kept, so make it at launch, with the starting consent the app's users need.

## Consent

`pb.consent` is the one gate every collecting module asks. While a category is not granted, nothing of it is made: no event, no queue, no file, no request, and no anonymous id.

| `Consent.Category` | What it covers |
|---|---|
| `ANALYTICS` | Events the app captures, and screens viewed |
| `PERFORMANCE` | Timings: launches, screens, requests |
| `DIAGNOSTICS` | The app's log, its reports and its failed requests |

There is no default. The app says what it starts with when it makes analytics (`startingConsent`), because whether its users must opt in is the app's to know. That applies to every category until the user's own choice is recorded, which then wins:

```kotlin
pb.consent.set(Consent.Category.PERFORMANCE, Consent.State.DENIED)
val chosen: Consent.State? = pb.consent.state(Consent.Category.ANALYTICS)   // null: not chosen yet
val stop = pb.consent.onChange { category, state -> println("$category is now $state") }
pb.consent.reset()   // forget the choices: the starting consent applies again
```

When a category is withdrawn, what was held of it is deleted, on the device too, and with analytics the anonymous id and the session go as well. A store that cannot be read counts as a refusal, never as the starting value. The choices are kept on the device: at this version the Android SDK does not send them to the project.

## Events and screens

| Method | What it does |
|---|---|
| `capture(event, properties)` | Records an event. The name is a letter or `$`, then letters, digits and `_.:-$`, 64 at most. `properties` is a `Map<String, JsonElement>`. |
| `screen(name, properties)` | Records a screen the user saw. |
| `identify(traits)` | Ties this device's anonymous events to the signed-in user, with their traits. It is done by itself at sign-in, with the next send. |
| `flush()` | Sends what is held now, of the categories granted now. |

An event is sent as the signed-in user, or, with no one signed in, under an anonymous id the device keeps (`anon_…`). A session is the events with no more than 30 minutes between them. When the user signs out, the anonymous id goes, and the next person on the device is someone new.

What is held goes together: 5 seconds after the first of it, as soon as 20 events, screens and timings are held, and when the app's screens are hidden. What is held when the app closes is kept on the device and sent at the next launch.

## Timings

```kotlin
import studio.palbase.analytics.Analytics

val trace = analytics.startTrace("load_feed")
loadFeed()
trace.stop(mapOf("source" to "network"))

analytics.measure("image_decode", 12.5, Analytics.Measure.CUSTOM, mapOf("format" to "webp"))   // milliseconds
```

`Analytics.Measure` is the kind of a measurement: `CUSTOM`, `SCREEN`, `APP_START` or `NETWORK`. Each is collected only with `PERFORMANCE` granted.

## Diagnostics

```kotlin
analytics.log("cart is empty at checkout", Analytics.Level.WARNING)   // kept in memory, the last 200 lines
analytics.report()                                                     // sends the lines kept, as what led to an error

analytics.recordRequest(method = "GET", endpoint = "/v1/feed", status = 500, durationMs = 840, requestId = "req_01")
```

`log` keeps a line in memory and sends nothing, so the lines go only with a `report()`, which sends them as what led to an error (or, with another `trigger`, what the user reported). `recordRequest` records a request the app made and how it ended. Each is collected only with `DIAGNOSTICS` granted.

Studio's Analytics screens show what the app sent: its events, people, funnels and retention.

## Related

- [Overview](/docs/android/overview): the client, consent and the installation
- [Debug Console](/docs/android/debug-console): what the SDK records on the device for a bug report
- [Web Analytics](/docs/web/analytics): the same events from a browser, and what the project reads back



<!-- ===== android/notifications ===== -->

# Notifications

`pb.notify` (`studio.palbase:palbase-notify`) is what the app does for the project's messages: it records this device's push token for the signed-in user, and reads and writes the user's own preferences and topics. Sending is the project's server's, with the secret key ([Notifications](/docs/backend/notifications)), never the app's.

A push reaches an Android device through Firebase Cloud Messaging, with the project's own FCM account.

## Setting up push

1. **The app's Firebase project.** Add the app to a Firebase project, put its `google-services.json` in the app module, and apply the `com.google.gms.google-services` plugin with `com.google.firebase:firebase-messaging`, as Firebase's setup says.
2. **The project sends with it.** Give the environment the Firebase project's service account, the JSON key of an account that may send with FCM:

   ```sh
   palbase notify:providers:set push fcm < service-account.json -E staging
   ```

   The credentials are read from stdin, checked as the sender will use them, and never shown again.
3. **Ask to notify.** On Android 13 and newer, the app asks for `POST_NOTIFICATIONS` at runtime and declares it in its manifest.
4. **Record the token** for the signed-in user, and **show what arrives**, both from the app's `FirebaseMessagingService` (below).

## Recording the token

```kotlin
// app/src/main/kotlin/com/example/shop/Push.kt
import com.google.firebase.messaging.FirebaseMessaging
import studio.palbase.notify.notify

// appScope: a CoroutineScope of the app's own, as long as the process.
fun startPush() {
    FirebaseMessaging.getInstance().token.addOnSuccessListener { token ->
        appScope.launch { runCatching { pb.notify.register(fcmToken = token) } }
    }
}
```

`register(fcmToken, locale)` records the token for the signed-in user and returns the device as the project has it. The token is this install's, and the device row is the user's:

- **Signed out**, `register` throws `PalbaseError` `missing_credential`, and the token is kept: it is recorded for whoever signs in next, with no call of yours.
- **Signing out** forgets the device for that user while they can still be named. The call is left with the client for that moment, and made even by a later process that never loaded `pb.notify`. The next person on the phone does not get the last one's notifications.
- **Someone else signing in** gets the token the app last gave.

`pb.notify.deviceId` is how the project names this device: `android-` and the installation's id. `unregister()` forgets it for the signed-in user, and it receives nothing until it is registered again. `devices()` lists the user's devices.

## Showing a push

A push reaches an Android app as an FCM data message, never as a notification the system draws by itself. Its parts are in the message's data, beside the push's own `data`:

| Key | What it is |
|---|---|
| `pb_title`, `pb_body` | The push's title and body. |
| `pb_image`, `pb_sound` | Its image's https address and its sound, when it has them. |
| `deep_link` | Its deep link, when it has one. |
| `pb_receipt` | The push's sealed receipt for this device. |

A silent push (`silent: true`) carries none of the title, body, image and sound: it wakes the app with its data alone.

At this version the SDK draws nothing, so the app's own service shows it:

```kotlin
// app/src/main/kotlin/com/example/shop/PushService.kt
import android.app.NotificationChannel
import android.app.NotificationManager
import androidx.core.app.NotificationCompat
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage
import studio.palbase.notify.notify

class PushService : FirebaseMessagingService() {
    // A token FCM changed goes to the project for whoever is signed in.
    override fun onNewToken(token: String) {
        appScope.launch { runCatching { pb.notify.register(fcmToken = token) } }
    }

    override fun onMessageReceived(message: RemoteMessage) {
        val title = message.data["pb_title"] ?: return   // a silent push: data alone
        val manager = getSystemService(NotificationManager::class.java)
        manager.createNotificationChannel(NotificationChannel("messages", "Messages", NotificationManager.IMPORTANCE_DEFAULT))
        val notification = NotificationCompat.Builder(this, "messages")
            .setSmallIcon(R.drawable.ic_notification)
            .setContentTitle(title)
            .setContentText(message.data["pb_body"])
            .setAutoCancel(true)
            .build()
        manager.notify(message.messageId.hashCode(), notification)
    }
}
```

```xml
<!-- app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<application>
    <service android:name=".PushService" android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>
</application>
```

`onMessageReceived` runs in the background too, so a process the push woke makes the client as the app's `Application` does. A call it makes as the user, to your backend for example, renews the session only if the call needs it.

The project counts how each push went on each device from what the device reports with `pb_receipt` (`POST /notify/receipts`). The Android SDK at this version reports nothing, so a push sent to an Android device is `unconfirmed` unless the app reports it itself.

## Preferences and topics

```kotlin
// channel → category → whether they take it
val preferences: Map<String, Map<String, Boolean>> = pb.notify.preferences()
pb.notify.setPreferences(mapOf("push" to mapOf("marketing" to false)))

pb.notify.follow("release-notes")
pb.notify.unfollow("release-notes")
```

A write sets some of the user's preferences and answers all of them. A category the user never set is on, and `transactional` is always on: it is not theirs to turn off. A topic's followers get what the server sends to it with `to: { topic }`.

## The inbox

The signed-in person's inbox holds the messages your backend put there and the copies of pushes it chose to keep, the same on every device of theirs: read on one, it is read on each; deleted, it is gone from each. A message stays its days (90 unless the project said) and an inbox keeps its newest 250.

`InboxView` (`studio.palbase:palbase-notify-ui`) draws it ready, in Compose:

```kotlin
import studio.palbase.notify.ui.InboxView

@Composable
fun InboxScreen() {
    var unread by remember { mutableLongStateOf(0L) }
    Scaffold(topBar = { TopAppBar(title = { Text(if (unread > 0) "Inbox ($unread)" else "Inbox") }) }) { pad ->
        InboxView(pb, Modifier.padding(pad).fillMaxSize(), onUnread = { unread = it }, empty = "No messages yet")
    }
}
```

`InboxView(client, modifier, locale, onOpen, onCustom, onUnread, empty, deleteLabel, onOffer, onOfferError)` takes the language to write it in (the person's chosen one unless given), what a tap on a message's link does (the system opens it unless given), a designed card's own buttons, the unread count as it changes, what an empty inbox says, and a designed card's offer button (the purchases module takes the offer unless given, once the app uses `pb.purchases`).

An app that draws its own uses `pb.notify.inbox`:

| Method | What it does |
|---|---|
| `list(limit, cursor, locale)` | A page, newest first: `items`, `nextCursor` and `unread`. Each `Inbox.Item` has its id, title, body, image, deep link, category, data, designed card, and when it was made, ends and was read. |
| `unread()` | How many are unread: what a badge shows. |
| `markRead(ids)`, `markAllRead()` | Marks messages read, on every device of the person's. |
| `remove(id)` | Deletes a message, from every device. |

## In-app messages

The project's in-app campaigns (a modal, a banner or a whole screen, designed in Studio) are shown over the app once started. `PalbaseInAppMessages` around the app's root starts them and draws them in Compose:

```kotlin
import studio.palbase.notify.ui.InAppHandlers
import studio.palbase.notify.ui.PalbaseInAppMessages

setContent {
    PalbaseInAppMessages(pb, InAppHandlers(
        onDeepLink = { url -> startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(url))) },
        onShowPaywall = { placement -> showPaywall(placement) },
    )) {
        AppNavigation()
    }
}
```

The person's campaigns are asked for as each session of theirs starts (the launch, a return after half an hour away, a sign-in or out). An event the app records with `pb.analytics` (its captures and screens), or names with `pb.notify.inApp.trigger(event, properties)`, shows the first campaign it triggers, the highest priority first, that its caps let: the project's (in a session, in a day, the least time between two) and the campaign's own. Triggers are matched on the device, so no event leaves it for them, and a message is shown whatever the person chose of analytics; a campaign to an audience reaches only people who allowed personalization. A [journey](/docs/backend/journeys)'s in-app step opens one of these campaigns for its person, shown the next time it is triggered.

`InAppHandlers` says what the app does with a message's buttons: `onDeepLink`, `onShowPaywall` (a placement's paywall), `onCustom` (the app's own code: a name and a value), `onRequestPush` (the push ask) and `onOffer` (one of the catalog's offers; the purchases module takes it unless given, once the app uses it). A button whose action the app does not take is not drawn.

An app that draws its own calls `pb.notify.inApp.start { presentation -> … }`, which hands it each `InAppPresentation` to show (its `definition`, its `variables`) and `null` when what is shown must go. The app tells back `clicked(action)`, `dismissed()` or `closed()`. `stop()` stops them, and `refresh()` asks for the person's campaigns again.

## Related

- [Notifications in your backend](/docs/backend/notifications): sending push, email, SMS and WhatsApp
- [Auth](/docs/android/auth): the sign-in the device row follows
- [CLI reference](/docs/cli/reference#palbase-notifyprovidersset): `notify:providers:set`



<!-- ===== android/storage ===== -->

# Storage

`pb.storage` (`studio.palbase:palbase-storage`) carries files between the app and the project's storage. The app writes and reads a file through a URL the project's backend signed, which says which object, for how long, how large and whose: the backend decides, and the app carries the bytes. A public bucket's objects are anyone's to read.

## Uploading

The backend signs an upload URL for one object (`Palbase.storage.createUploadUrl`, [Direct Uploads](/docs/backend/direct-uploads)) and answers it from a route of its own. The app sends the bytes to it:

```kotlin
import studio.palbase.storage.storage

// grantUrl: what your backend's route answered, an upload URL it signed.
val stored = pb.storage.upload(bytes, signedUrl = grantUrl, contentType = "image/jpeg")
println("${stored.bucket}/${stored.path}: ${stored.size} bytes, ${stored.contentType}")
```

`upload(data, signedUrl, contentType)` returns the object as storage stored it (`StorageAPI.StorageObject`: `bucket`, `path`, `size`, `contentType`, `checksumSha256`, `width` and `height` for an image, `ownerId`). The content type is used only when the bytes cannot say what they are, since storage reads the type from the bytes. Storage checks the grant while the bytes stream: a file past the URL's `max_bytes`, of a type the bucket does not take, or sent after the URL expired is refused with a `PalbaseError`.

The URL's conditions (the bucket, the path, the expiry, the ceiling, the types, the owner) are all covered by its signature, so a URL changed on the device opens nothing.

## Downloading

A private object is read with a download URL the backend signed (`Palbase.storage.createSignedUrl`, [Storage](/docs/backend/storage)):

```kotlin
val bytes: ByteArray = pb.storage.download(signedUrl)
val bitmap = BitmapFactory.decodeByteArray(bytes, 0, bytes.size)
```

## Public buckets

A public bucket's objects need no URL of the backend's:

```kotlin
val logo: ByteArray = pb.storage.publicObject("public-assets", "logo.png")

// The address itself, for an image loader or a share sheet:
val address: java.net.URI = pb.storage.publicUrl("public-assets", "logo.png")
```

`publicUrl` is `https://<ref>.palbase.studio/storage/public/{bucket}/{path}`, with each part encoded as one path segment.

## Signed URLs stay at the project's address

A signed URL is taken only at the project's own address, the configuration's `url`. A URL that names another host is refused before anything is sent (`foreign_signed_url`), so a URL from somewhere else never takes the user's request away from the project. A URL that is not a signed object URL is `invalid_signed_url`.

## Through your backend's upload routes

A backend route declared with `@Upload` takes the file in the same call as its body, and its generated function reports progress ([Calling Your Backend](/docs/android/backend-calls#uploads)). Use one when the backend's code must run with the file. Use a signed URL when the backend only grants the write.

## Related

- [Direct Uploads](/docs/backend/direct-uploads): signing an upload URL
- [Storage in your backend](/docs/backend/storage): buckets, objects, public reads and signed URLs
- [Calling Your Backend](/docs/android/backend-calls): the route that answers the URL



<!-- ===== android/purchases ===== -->

# Purchases

`pb.purchases` (`studio.palbase:palbase-purchases`) is what the signed-in customer has, whatever store they bought in, and buying on Google Play. What they have is one answer, `CustomerInfo`, the same the web, the iOS app and the project's backend read: a Pro bought on the web is this app's Pro too. Buying goes through Google Play Billing 9, which the artifact brings with it.

Google Play is connected to the environment first: the service account Play Console invites, the Android app linked, and Play's notifications ([Google Play](/docs/purchases/google-play)). The catalog's `android` plans are what the app sells ([Catalog](/docs/purchases/catalog)).

## Quick example

```kotlin
import studio.palbase.purchases.PurchaseResult
import studio.palbase.purchases.StoreProduct
import studio.palbase.purchases.isEntitled
import studio.palbase.purchases.purchases

class PaywallViewModel : ViewModel() {
    val products = MutableStateFlow<List<StoreProduct>>(emptyList())
    val isPro = MutableStateFlow(false)
    val message = MutableStateFlow("")

    init {
        viewModelScope.launch {
            val found = pb.purchases.products()
            products.value = found.products
            found.diagnosis?.let { Log.w("Paywall", it.toString()) }   // why Play returned fewer
        }
        viewModelScope.launch {
            // Kept current: a purchase on another device or in another store, a renewal, a refund.
            pb.purchases.customerInfoUpdates.collect { info -> isPro.value = info?.isEntitled("pro") ?: false }
        }
    }

    fun buy(activity: Activity, product: StoreProduct) = viewModelScope.launch {
        when (val result = pb.purchases.purchase(activity, product)) {
            is PurchaseResult.Purchased -> isPro.value = result.customerInfo.isEntitled("pro")
            is PurchaseResult.AlreadyEntitled -> message.value = "${result.entitlement} is already yours, from ${result.store.value}"
            PurchaseResult.Pending -> message.value = "Waiting for the payment"
            PurchaseResult.Cancelled -> Unit
        }
    }

    fun restore() = viewModelScope.launch {
        isPro.value = pb.purchases.restore().isEntitled("pro")
    }
}
```

Touch `pb.purchases` at launch, in the `Application`, even before a paywall is shown. What Play holds unreported (a report that failed, a pending purchase since paid, one made outside the app) is reported then, as whoever is signed in.

## What the customer has

| Member | What it is |
|---|---|
| `customerInfo()` | Everything the signed-in customer has, read now. |
| `latest` | The newest known: what listeners were last told, or the app's own last read. `null` before any, and for anyone but who is signed in now. |
| `isEntitled(key)` | Whether the customer has the entitlement now, from `latest`. `false` when nothing is known. |
| `onCustomerInfo { info -> }` | Called once it is read, then each time it changes, and with `null` while no one is signed in. Returns what stops it. Called on a background thread. |
| `customerInfoUpdates` | The same, as a `Flow<CustomerInfo?>`; the newest when the collector falls behind. |
| `offerings(channel)` | The paywall's catalog: each product's text and price on a channel, this app's (`OfferingsChannel.ANDROID`) unless another is named. |

`CustomerInfo` holds `entitlements` (by key: `active`, `expiresAt`, `willRenew`, `billingIssue`, `store`, `isSandbox`, `manage`), `subscriptions`, one-time `purchases`, `credits` balances, `limits` and their use, and `guest` for a guest customer. `info.isEntitled("pro")` is the entitlement active and, unless it is for life, ending after now: the rule the backend's `isEntitled` reads.

What the customer has is kept current while it is listened to. The customer's own realtime channel says when it changed, and it is read again then. When another user signs in, their channel is followed, and listeners hear `null` until theirs is read: one user's is never shown as the next one's. A read that fails is asked again a few times, then on the next change or the app's return to the foreground. A listener is told what is, never an error.

## Buying on Google Play

`products()` returns the catalog's Android plans as Google Play has them for this user, in the catalog's order: a subscription once per base plan. A product Play does not return is left out, never silently: `diagnosis` names it, with Play's reason and the likely causes (also logged, tag `Palbase`). It throws `PurchasesException` when Play Billing fails, and `PalbaseError` when the catalog cannot be read.

| `StoreProduct` | What it is |
|---|---|
| `id`, `basePlanId`, `offerId` | Google Play's product id, a subscription's base plan, and the offer it is bought with (its introductory offer, when the catalog's plan has one and Play says the user may take it). |
| `name`, `title`, `description` | As Google Play has them, in the user's language. |
| `formattedPrice`, `priceAmountMicros`, `priceCurrencyCode` | The price for the user's country: a one-time product's, or the price a subscription renews at. |
| `billingPeriod` | A subscription's period, ISO 8601 (`P1M`, `P1Y`). |
| `entitlements` | What buying it gives. |
| `offering`, `plan` | The catalog's product and plan it was paired with. |
| `productDetails` | Play's own `ProductDetails`: its offers and every pricing phase. |

`purchase(activity, product, planChange)` opens Google Play's purchase sheet over `activity`. What the customer has is read first: an entitlement it gives that is already on from another store answers `AlreadyEntitled` without opening Play, so nothing is charged twice. Otherwise Play sells it with the customer's obfuscated account id, and the purchase is reported to the environment, which reads it from Play and acknowledges it (a consumable's is consumed). The SDK never acknowledges a purchase itself. A report that fails leaves the purchase unacknowledged, and it is reported again at the next start.

| `PurchaseResult` | What it means |
|---|---|
| `Purchased(customerInfo)` | Bought, and the environment has it. |
| `AlreadyEntitled(store, entitlement, manage)` | An entitlement it gives is already on, from another store or from this Google account on Play. `manage` is where it is managed: the web's is the Stripe portal. |
| `Cancelled` | The user closed the sheet. |
| `Pending` | Waiting for the payment, or a parent's approval. Once it is paid, Play hands the purchase over, it is reported, and listeners are told. |

Play's failures throw `PurchasesException`, whose `code` is one of `PurchasesException.Code`: `PRODUCT_UNAVAILABLE`, `ALREADY_OWNED`, `BILLING_UNAVAILABLE`, `SERVICE_UNAVAILABLE` (try again in a moment), `NETWORK_ERROR`, `DEVELOPER_ERROR`, `PAYMENT_DECLINED`, `INELIGIBLE_FOR_OFFER`, `PURCHASE_IN_PROGRESS`, `PLAN_CHANGE_NOT_ALLOWED` and others. Its message is one sentence, and `responseCode` and `debugMessage` are Play's own, for a log. The environment's refusals throw `PalbaseError`, and so do `session_required` (no one signed in) and `session_changed` (the signed-in user changed meanwhile).

### Changing plans

A subscription bought while the customer has another plan of its group on Google Play replaces it. Play moves the customer over as `planChange` says, and the environment ends the old purchase. `PlanChange.DEFAULT` is Google's recommendation for the change:

| Between | An upgrade | A downgrade |
|---|---|---|
| Two subscriptions | Now: `CHARGE_PRORATED_PRICE` when the new plan costs more per day, `WITH_TIME_PRORATION` when it does not | At the old plan's renewal: `DEFERRED` |
| Two base plans of one subscription | Now, at the full price: `CHARGE_FULL_PRICE` | From the next billing date: `WITHOUT_PRORATION` |

To a prepaid plan the change is always `CHARGE_FULL_PRICE`. A mode Play does not take for the change throws `PLAN_CHANGE_NOT_ALLOWED`, naming the ones it does, before Play is opened. The plan the customer already has is not bought again: `AlreadyEntitled`.

### Restoring

`restore()` is "Restore purchases", the user's own action, never automatic. Everything this Google account owns on Play is reported as restored, so a purchase made while signed in as another of the app's accounts may move to this one. It answers what the customer has now. When a purchase stays where it was, the rest is still applied and it throws `PalbaseError`: `restore_account_owned` (403: a guest restoring an account's purchase must sign in to that account), `restore_other_account` (403: another account bought it — Play's obfuscated account id names that one), `restore_other_environment` (403: another environment of the project made it) or `restore_limit` (409: moved too often lately).

## Web purchases bought without an account

Someone who bought on the web without an account is sent a link that gives the purchase to whoever opens it in the app: `<package>://palbase/redeem?token=…`, or its page's `https://…/purchases/redeem?token=…`. The app redeems the link it was opened with, for the signed-in user (a guest too):

```kotlin
import studio.palbase.purchases.redemptionToken

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    val link = intent.dataString ?: return
    if (redemptionToken(link) != null) lifecycleScope.launch { pb.purchases.redeem(link) }
}
```

A link works once (`409 already_redeemed`). One past its hour (`410 redemption_expired`) sends a new one to the buyer's email. `redemptionToken(link)` says whether a link is one, without asking anything.

## Paywalls

The Android SDK at this version draws no paywall, and asks for no placement: the app shows its own screen, from `products()`, which carries Play's prices, and from `offerings()`, which carries the catalog's text. The paywalls the project publishes are drawn by the iOS and web SDKs ([Paywalls › In the app](/docs/purchases/paywalls#in-the-app)).

## On your server

Check the entitlement where the content is served, not only in the app: `Palbase.purchases.getCustomer` and `isEntitled` from `palbase/server`, and the `purchases.entitlement.changed` event ([Checking an entitlement](/docs/purchases/entitlements#checking-an-entitlement)). The app's answer decides what the app shows; what a purchase opens on your server is checked there.

## Related

- [Purchases](/docs/purchases/overview): the catalog, the stores and how a purchase becomes access
- [Google Play](/docs/purchases/google-play): connecting the environment to Google Play
- [Catalog](/docs/purchases/catalog): the products and plans the app sells
- [Entitlements, Credits & Limits](/docs/purchases/entitlements): what `CustomerInfo` holds, and spending credits
- [Paywalls](/docs/purchases/paywalls): the paywalls the project publishes
- [Auth](/docs/android/auth#guests): guests, whose purchases stay theirs when they become an account



<!-- ===== android/voice ===== -->

# Voice

A chat of the project's agents can be talked to out loud ([AI › Voice](/docs/backend/ai#voice)). `PBVoice` (`studio.palbase:palbase-voice`) is that voice on the device: the microphone goes to the platform's voice provider and its voice comes back, over WebRTC. The app makes the WebRTC offer, the app's own backend starts the voice with it, and the provider's key never leaves the platform.

WebRTC comes with this artifact alone, so an app that takes no voice carries none of it. Its native library is about 12 MB for each ABI.

## Quick example

The backend starts the voice for the signed-in member, from a route of its own:

```ts
// src/modules/support/voice.controller.ts
import { Body, Controller, Palbase, Param, Post, User, z, type UserT } from "palbase/backend";

const Offer = z.object({ sdp: z.string().min(1) });

@Controller("/voice")
export class VoiceController {
  // The app's WebRTC offer in; the voice's id and the provider's answer out.
  @Post("/{chatId}")
  async start(@Param("chatId") chatId: string, @Body(Offer) body: z.infer<typeof Offer>, @User() user: UserT): Promise<{ id: string; sdp: string }> {
    const voice = await Palbase.ai.chats.voice.start(chatId, { sdp: body.sdp, as: user.id });
    return { id: voice.id, sdp: voice.sdp };
  }

  @Post("/{chatId}/{voiceId}/close")
  async close(@Param("chatId") chatId: string, @Param("voiceId") voiceId: string, @User() user: UserT): Promise<{ seconds: number }> {
    const voice = await Palbase.ai.chats.voice.close(chatId, voiceId, { as: user.id });
    return { seconds: voice.seconds };
  }
}
```

The app connects, after `palbase apps:sync` wrote the backend's client:

```kotlin
import studio.palbase.generated.*
import studio.palbase.voice.PBStartedVoice
import studio.palbase.voice.PBVoice

// The person allowed RECORD_AUDIO first.
val voice = PBVoice.connect(context, start = { sdp ->
    val started = pb.backend.voice.start(chatId, VoiceStartRequest(sdp = sdp))
    PBStartedVoice(started.id, started.sdp)
})

voice.mute(true)
voice.mute(false)

// Done: here, then on the backend.
voice.close()
pb.backend.voice.close(chatId, voice.id)
```

## Connecting

`PBVoice.connect(context, start, audio, iceTimeoutMillis, onError, onState)` makes the offer, hands it to `start`, sets the answer it gets back and returns the voice. Its `state` then says when the connection is up:

| Argument | What it is |
|---|---|
| `start` | The round trip to the app's own backend: the offer (an SDP) in, the voice's id and the provider's answer out, as a `PBStartedVoice(id, sdp)`. |
| `audio` | Who holds the device's audio while the voice talks. `PBVoice.Audio.MANAGED` (the default): the voice sets it up (in communication, through the speaker unless a headset is connected, with the audio focus taken) and gives it back as it found it on close. `PBVoice.Audio.APP`: the app set it up already, and the voice leaves it as it is. |
| `iceTimeoutMillis` | How long the offer's network candidates are gathered at most before it is sent: 10 seconds by default, then `PalbaseError` `ice_timeout`. |
| `onError` | The provider's word that something went wrong in the voice, on WebRTC's thread. |
| `onState` | The connection's state each time it changes, on WebRTC's thread. |

The app asks the person for the microphone first: `RECORD_AUDIO` is a runtime permission, and without it `connect` throws `PalbaseError` `microphone_denied`. The artifact declares `RECORD_AUDIO` and `MODIFY_AUDIO_SETTINGS` in its manifest. When the coroutine that connects is cancelled, or the backend refuses, whatever was opened is closed.

A member starts at most 5 voices an hour, and one voice talks in a chat at a time: the backend's `start` throws `429 too_many_voices` or `409 voice_active` ([AI › Voice](/docs/backend/ai#voice)).

## The voice

| Member | What it is |
|---|---|
| `id` | The voice the backend started: what it reads, tells and closes it by. |
| `state` | The connection's state as a `StateFlow<PBVoice.State>`: `NEW`, `CONNECTING`, `CONNECTED`, `DISCONNECTED`, `FAILED`, `CLOSED`. |
| `muted`, `mute(on)` | Whether the microphone is heard. |
| `close()` | Ends it here: the connection, the microphone, and the audio it set up. Callable from any thread. |

Call `close()` when the voice is done, in a screen's `onDispose` or a ViewModel's `onCleared`. Ending it is the app's, and its backend's (`Palbase.ai.chats.voice.close`). A voice the app lets go of without closing it is closed once the garbage collector takes it, but not at once: the microphone stays open until then.

## What was said

Nothing of the conversation is read on the device. What is said either way is the chat's: on a [chat gateway](/docs/android/gateways#chat-gateways), the chat's state has the voice (`PBChat.State.voice`: when it began and ended), and each line said in it is among the messages, of kind voice, the person's and the voice's own.

## Related

- [AI › Voice](/docs/backend/ai#voice): starting, telling and closing a voice from the backend
- [Gateways](/docs/android/gateways#chat-gateways): the chat the voice talks in
- [Calling Your Backend](/docs/android/backend-calls): the generated client the offer goes through



<!-- ===== android/debug-console ===== -->

# Debug Console

Every app records what happened on the device from launch: the SDK's own requests and realtime frames, its modules' lines, and whatever the app adds. `studio.palbase:palbase-debug` shows that record, in Compose, and only while the project has turned the console on for the signed-in user. So a build that already shipped can open it for the one person reporting a bug, and what it shows includes everything recorded before it was turned on.

## Quick example

```kotlin
import studio.palbase.debug.PBLogLevel
import studio.palbase.debug.ui.PalbaseConsole
import studio.palbase.debug.ui.enabled

@Composable
fun Settings() {
    var showing by remember { mutableStateOf(false) }
    val on by pb.debug.enabled.collectAsState()          // followed as the flag flips

    if (showing && on) {
        // A whole screen: its round × and system back close it.
        PalbaseConsole(pb.debug, Modifier.fillMaxSize(), onClose = { showing = false })
        return
    }
    if (on) Button({ showing = true }) { Text("Debug console") }
    Button({ pb.debug.log("cart is empty", PBLogLevel.WARNING, label = "checkout") }) { Text("Log a line") }
}
```

Turn it on for one user:

```sh
palbase flags:users:set <user-id> palbase.debug_console true
```

## What is recorded

Recording runs from launch whether or not the console is on, and stays on the device: in the app's no-backup files, up to 32 MB, the last 20 launches. Credentials are masked before anything is written. When someone else signs in, the last user's records are wiped.

| What | How it gets there |
|---|---|
| The SDK's requests to the project and to your backends | By itself, measured in full: the phases (DNS, connect, TLS, waiting), the connection, the bytes. |
| The realtime socket | By itself: the connection, the channels and the last frames, on the console's Realtime tab. |
| The modules' own lines | By itself, under `palbase.<module>`: a sign-in, a flag change, a purchase reported. |
| The app's log | `pb.debug.log(message, level, label, metadata)` and `pb.debug.error(throwable, label)`. The `label` is the line's category, any word the app likes, and the console filters by it. |
| The app's own OkHttp traffic | `pb.debug.client(appClient, label)` returns a client that records and measures each request like the SDK's own, keeping `appClient`'s settings and connection pool. `pb.debug.interceptor(label)` goes in a client built by hand, and records without the phases. |
| Anything else | `pb.debug.record(method, url, requestHeaders, requestBody, statusCode, responseHeaders, responseBody, error, durationMs, label)`: an exchange the SDK did not make, masked on the way in like a captured one. |

A backend call's [encrypted field](/docs/backend/request-encryption) is recorded as it went, sealed (`pbt1.…`); **Reveal** beside it in the body shows its value. The values are kept in memory alone, only while the console is on for the user and recording, and are gone when the console is cleared, another user signs in or the console is turned off.

`PBLogLevel` is `TRACE`, `DEBUG`, `INFO`, `NOTICE`, `WARNING`, `ERROR` or `CRITICAL`.

```kotlin
import okhttp3.OkHttpClient
import okhttp3.Request

// One client for the app's own requests: recorded beside the SDK's, under the label "app".
val http: OkHttpClient = pb.debug.client(OkHttpClient(), label = "app")
// Off the main thread, as any OkHttp call:
http.newCall(Request.Builder().url("https://api.example.com/v1/feed").build()).execute().use { println(it.code) }
```

| Member of `pb.debug` | What it does |
|---|---|
| `isRecording`, `start()`, `stop()` | Whether it records. Recording is on from launch, and `stop()` keeps what was recorded. |
| `clear()` | Discards every record, on the device and in the console's screens. |
| `export()` | This launch's records as JSON lines, already masked: what to attach to a bug report. |
| `sessions()` | Every launch on the device, newest first. |
| `realtime` | The socket, inspected, as a `StateFlow`: the connection, the channels and the last frames. |

## Who sees it

`PalbaseConsole(pb.debug)` draws nothing unless the project has turned the console on for the signed-in user: the flag `palbase.debug_console`, given to that user as their own value. It is decided by the project, never by the build. `pb.debug.isEnabled` is the same answer (`import studio.palbase.debug.ui.isEnabled`), and `pb.debug.enabled` follows it as it changes. Gate your own way in on it: a row in a settings screen, a long press. It is `false` until it is shown to be true: before the flags load, when they cannot be read, and when nobody turned it on.

Turning it off again is `palbase flags:users:unset <user-id> palbase.debug_console`. The flag reaches the device on the user's own flags channel, so the console opens or shuts without a relaunch ([Flags](/docs/android/flags#keeping-up-to-date)).

## The screens

The console has two tabs, Console and Realtime, under a floating tab bar, each with its own back stack: the list of records, a network inspector, a body viewer, filters, the launches, and the realtime inspector. It draws edge to edge and keeps its own bars clear of the system's, so give it the whole screen. With `onClose`, each tab's root shows a round ×, and system back (predictive on Android 14 and newer) walks a tab's pages before it closes the console. Without `onClose`, there is no close button, and back at a root is the host's.

`palbase-debug` brings Compose and `palbase-flags` with it. Compose is in no other artifact of the SDK, so an app that never shows the console does not take it, and its recording is the core's either way.

## Related

- [Flags](/docs/android/flags): the per-user value that opens the console
- [Analytics](/docs/android/analytics#diagnostics): the diagnostics a project collects, with consent
- [Logs](/docs/getting-started/logs): the environment's own record of every request



<!-- ===== server/overview ===== -->

# Overview

`palbase/server` is Palbase for servers: one client, made with the project's **secret key**, that reaches every module's server calls — auth's user management, storage, notify, secrets, flags, analytics, realtime's broadcast and channel declaration, and machines. Use it from anything that runs on a server you control: a Next.js route handler, a worker, a script, a backend that is not a Palbase machine. A `palbase/backend` app does not construct one: its `Palbase` is this same client, built from the machine's environment (see [Backend SDK Overview](/docs/backend/overview)).

## Quick example

```ts
// server.ts
import { createServer } from "palbase/server";

const palbase = createServer({
  url: process.env.PALBASE_URL!, // https://<ref>.palbase.studio
  secretKey: process.env.PALBASE_SECRET_KEY!, // pb_<ref>_s…
});

// Every call takes { path, query, headers, body } as its operation needs them,
// and answers { status, data, headers }.
const { data } = await palbase.storage.listBuckets();
console.log(data.buckets.map((b) => b.name));

// Give one user their own value of a flag; their apps are told at once.
await palbase.flags.putUserValue({ path: { user_id: "usr_123", key: "checkout.new_flow" }, body: { value: true } });
```

## The secret key

An environment has publishable keys (`pb_<ref>_c…`, for apps — each [registered app](/docs/apps/overview) has its own) and any number of named secret keys (`pb_<ref>_s…`, for servers). Make a secret key in Studio under **Settings › API keys › Create secret key**: it is shown **once**, and each one can be revoked on its own without touching the others — one per server is the habit that makes a leak cheap to shut out.

A secret key opens the whole project: every user, every file, every secret. `createServer` refuses to run where one could reach a browser:

| Where | What happens |
|---|---|
| A bundle built for a browser or React Native | The package's export conditions resolve `palbase/server` to a module that **throws when the bundle loads** — before a key can ship in it. |
| A page (`document` exists), a browser worker (`navigator.userAgent` starts `Mozilla/`), or React Native | `createServer` throws a `TypeError` naming `palbase/web` as what apps use. |
| A publishable key passed as `secretKey` | `createServer` throws: a publishable key belongs in `palbase/web`. |

Node, Bun, Deno, Cloudflare Workers and edge runtimes resolve the real client.

## `createServer(options)`

| Option | Default | What it is |
|---|---|---|
| `url` | — | The project's address, `https://<ref>.palbase.studio`. https only (http only for a loopback address); the origin alone, with no path. |
| `secretKey` | — | The project's secret key, from the server's environment. |
| `retry` | `{ attempts: 3, maxWaitSeconds: 30 }` | How a call that was answered "not now" is sent again (below). |
| `fetch` | `globalThis.fetch` | The fetch the calls go through. |
| `solveProofOfWork` | `false` | Solve auth's proof-of-work challenge here and send the call again. Left off, a sign-in a server makes for a user answers `403 pow_required` with the challenge, for the user's own device to solve. |

It answers a `PalbaseServer`:

| Member | Module | Contract |
|---|---|---|
| `auth` | users, sessions, test users, auth settings (`/admin/…`) | auth |
| `storage` | buckets, objects, signed URLs | storage |
| `notify` | email, push, SMS, WhatsApp, templates, topics | notify |
| `secrets` | the project's secrets, by environment | secrets |
| `flags` | definitions, users' values, publishing | flags |
| `analytics` | captures, and reading events back | analytics |
| `realtime` | broadcast, state, the channel declaration, limits | realtime |
| `machines` | machines, builds, logs, databases | machines |
| `transport` | the one transport every call goes through | — |

Each module's methods are generated from its contract, one per operation, named by its operation id in camelCase: `PUT /storage/buckets/{bucket}` is `storage.putBucket`, `GET /admin/users` is `auth.adminListUsers`. The module pages say what each module does: [Storage](/docs/backend/storage), [Secrets](/docs/backend/secrets), [Flags](/docs/backend/flags), [Notifications](/docs/backend/notifications), [Realtime](/docs/backend/realtime), [Channels](/docs/backend/channels), [Test Users](/docs/backend/test-users), and [Machines](/docs/machines/overview) for machines and databases.

## The shape of a call

A call takes one object with the parts its operation has — `path` for the path's parameters, `query`, `headers`, `body` — and answers a `Reply`: the `status` the module answered, its `data` (the JSON body, parsed), and its `headers`.

```ts
// users.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

const created = await palbase.auth.adminCreateUser({
  body: { email: "grace@example.com", password: "a long passphrase of her own", email_verified: true },
});
console.log(created.status, created.data.id); // 201 usr_…

const user = await palbase.auth.adminGetUser({ path: { uid: created.data.id } });
await palbase.auth.adminUpdateUser({ path: { uid: user.data.id }, body: { metadata: { plan: "pro" } } });
```

A path parameter is always **one** URL segment: the client percent-encodes it, so a storage path `avatars/ada.png` travels as `avatars%2Fada.png`, and an empty value, `.` or `..` is refused before anything is sent (`invalid_path_parameter`). An answer the module sends as bytes — an object's contents — arrives as the `Response` itself, for you to read as you need (`await reply.data.arrayBuffer()`).

The types of every request and answer are exported, by module, as `types`:

```ts
// report.ts
import type { types } from "palbase/server";

export function describe(object: types.storage.StorageObject): string {
  return `${object.path}: ${object.size} bytes of ${object.content_type}`;
}
```

## Refusals are `PalbaseError`

Every answer the contract calls a refusal throws a `PalbaseError` carrying the module's envelope:

| Field | What it is |
|---|---|
| `status` | The HTTP status; `0` when the request never got an answer. |
| `code` | The envelope's `error` (`user_exists`, `bucket_not_empty`, `own_provider_required` …). |
| `message` | The envelope's `error_description`. |
| `requestId` | The request's id, for the module's logs. |
| `retryAfter` | Seconds the module asked to wait (`Retry-After`, or the envelope's `retry_after`). |
| `body` | The body as sent, for the answers that are not the envelope. |
| `op` | The operation, such as `PutBucket`. |

```ts
// make-user.ts
import { createServer, PalbaseError } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

export async function ensureUser(email: string, password: string): Promise<string | null> {
  try {
    return (await palbase.auth.adminCreateUser({ body: { email, password } })).data.id;
  } catch (e) {
    if (e instanceof PalbaseError && e.code === "user_exists") return null;
    throw e;
  }
}
```

A few codes are the client's own, with `status: 0`: `network_error` (the request did not reach the project), `missing_credential`, `invalid_path` and `invalid_path_parameter`. Two more are about answers the contract does not have: `undeclared_answer` (a 2xx the operation does not declare — the request **may have taken effect**) and `undeclared_redirect`.

The client never follows a redirect. The key goes to the project's origin and nowhere else: a request URL that would leave it is refused, and a 3xx is a refusal rather than a hop that would carry the key to whatever host it names.

## Retries

A call is sent again only when doing so cannot do the work twice:

- **What is retried:** `429`, `502`, `503` and `504`, and a request that never reached the server (`network_error`).
- **Which calls:** reads (`GET`, `HEAD`), and the writes whose contract takes an `Idempotency-Key`. For those the client makes one key per call and every attempt carries it, so the module answers a retry with the first answer (`Idempotent-Replayed: true`) instead of doing the work again. Pass your own `Idempotency-Key` header to make a write safe across your own retries too — a job that runs again after a crash, say.
- **How long:** what the module's `Retry-After` asks, never more than `maxWaitSeconds`; with no word from the module, 0.5 s, 1 s, 2 s … with a little jitter. A wait longer than `maxWaitSeconds` is not waited for: the error reaches you.

Everything else is yours: a `400`, a `409`, a `404` is the module's answer, and sending it again would only get it again. A body that can be read only once (a stream) is not sent twice.

```ts
// strict.ts
import { createServer } from "palbase/server";

// One attempt, no waiting: the caller decides.
export const strict = createServer({
  url: process.env.PALBASE_URL!,
  secretKey: process.env.PALBASE_SECRET_KEY!,
  retry: { attempts: 1, maxWaitSeconds: 0 },
});
```

## Listings, a page at a time

Listings answer a page and a `next_cursor`; the next page is the same call with that cursor, until a page carries none. `pages(call)` walks them for you:

```ts
// sweep.ts
import { createServer, pages } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

let banned = 0;
for await (const page of pages((cursor) => palbase.auth.adminListUsers({ query: { limit: 200, cursor, banned: true } }))) {
  banned += page.users.length;
}
console.log(`${banned} banned users`);
```

A listing that answers a cursor it has answered before is a loop, and `pages` throws rather than page forever.

## From a Palbase machine

A `palbase/backend` app reaches the same client as `Palbase`, imported, never constructed: it is built at boot from `PALBASE_URL` (which the platform sets on every machine) and `PALBASE_SECRET_KEY` (a project secret you add — see [Secrets](/docs/backend/secrets)). Everything on this page holds for it: `Palbase.storage.putBucket(…)` is `createServer(…).storage.putBucket(…)`.

## Related

- [Webhooks](/docs/server/webhooks) — the project's events delivered to your server, and `verifyWebhook`
- [Backend SDK Overview](/docs/backend/overview) — `Palbase`, `Database` and `Log` inside a machine
- [Storage](/docs/backend/storage) · [Notifications](/docs/backend/notifications) · [Flags](/docs/backend/flags) · [Secrets](/docs/backend/secrets) — the modules, from a server
- [Web SDK Overview](/docs/web/overview) — the publishable-key client for apps



<!-- ===== server/webhooks ===== -->

# Webhooks

When something happens in a project — a user is deleted, a file is uploaded, a secret changes, an email bounces — the platform POSTs an **event** to each of the project's webhook endpoints that takes its type, signed with that endpoint's secret. `palbase/server` checks the signature: `verifyWebhookRequest(request, secret)` answers the event, or throws. A `palbase/backend` app does not call it at all — its `@On` handlers receive the events already checked (see [Event Hooks](/docs/backend/hooks)).

## Quick example

```ts
// server.ts
import { verifyWebhookRequest, WebhookSignatureError } from "palbase/server";

const secret = process.env.PALBASE_WEBHOOK_SECRET!; // whsec_…, shown once when the endpoint was made
const handled = new Set<string>();

export async function handle(request: Request): Promise<Response> {
  let event;
  try {
    event = await verifyWebhookRequest<{ user_id?: string }>(request, secret);
  } catch (e) {
    if (e instanceof WebhookSignatureError) return new Response(e.code, { status: 401 });
    throw e;
  }
  // A delivery may come twice: the event's id says it is the same one.
  if (handled.has(event.id)) return new Response(null, { status: 204 });
  if (event.type === "user.deleted") {
    console.log(`forget everything about ${event.data.user_id}`);
  }
  handled.add(event.id);
  return new Response(null, { status: 204 });
}
```

Any `2xx` is delivery. Anything else — another status, a timeout, a refused connection — and the platform sends the event again.

## Endpoints

An endpoint is an `https` URL on the public internet and the event types it takes — up to 50 of them, each dotted lowercase words such as `user.deleted`; an endpoint that names none takes every type. A project has **5 endpoints at most**, besides the ones the platform keeps for its machines. When an endpoint is made, its secret (`whsec_` and 64 hex characters) is answered **once**; keep it in the receiving server's secrets.

Manage a project's endpoints in Studio, under an environment's **Settings › Webhooks**: add an endpoint (its secret is shown once, with a copy button), change its address or events, or delete it. Reading the list is open to the organization's members; adding, changing and deleting are an admin's — a person, or an admin [access token](/docs/getting-started/access-tokens). Each endpoint shows who made it: a person, an access token or an environment token, by the name it had then. An endpoint stays when the token that made it is deleted. Palbase's own environment is shown read-only. A `palbase/backend` app on a machine needs none of this: the platform gives the machine its `PALBASE_WEBHOOK_SECRET` and keeps an endpoint for exactly the events its app takes, listed as the machine's — not changed or deleted from here, and gone with the machine ([Event Hooks](/docs/backend/hooks)).

The CLI does the same:

```sh
palbase webhooks:create https://api.example.com/palbase --events user.deleted,file.uploaded --secret-to RECEIVER_WEBHOOK_SECRET
palbase webhooks:list
palbase webhooks:update <id> --events user.deleted
palbase webhooks:delete <id>
```

`--secret-to` keeps the new endpoint's secret in the environment's secrets (production, or development with `--dev`) instead of printing it, so a receiver that is itself a machine of the environment reads it by name. See the [CLI reference](/docs/cli/reference#webhooks).

### Failed deliveries

A delivery is tried 12 times, the wait growing up to five minutes between tries. When the endpoint still has not taken it, Palbase gives up and keeps the delivery for **30 days** under **Settings › Webhooks › Failed deliveries**: the event, the endpoint, how many times it was tried and why the last try failed. **Redeliver** sends the same event, with the same `Palbase-Event-Id` and body, to that endpoint again within seconds, signed afresh, as Stripe's *Resend* does. Your receiver already handles an event more than once by its id, so a redelivery is safe. Members read the list; an admin redelivers, and the redelivery is written to the organization's audit log. Studio's API does the same: `GET /v1/environments/{ref}/webhooks/deliveries?failed=true` and `POST /v1/environments/{ref}/webhooks/deliveries/{id}/redeliver`. A delivery whose endpoint was deleted is sent nowhere (`409 endpoint_gone`).

## What a delivery is

A delivery is a `POST` with a JSON body — the event — and three headers:

| Header | What it carries |
|---|---|
| `Palbase-Signature` | `t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>` |
| `Palbase-Event-Id` | The event's id (also in the body): the same id twice is the same event delivered again. |
| `Palbase-Event-Type` | The event's type (also in the body). |

```json
{
  "id": "6f2c1c9e-…",
  "type": "file.uploaded",
  "project_id": "2b7d…",
  "created_at": "2026-10-08T09:41:22Z",
  "data": { "bucket": "avatars", "path": "usr_123/face.png", "size": 48211, "content_type": "image/png", "owner_id": "usr_123" }
}
```

The platform waits **10 seconds** for an answer, follows no redirect, and tries an event up to **12 times**, waiting 1 s, 2 s, 4 s … up to five minutes between attempts. One project's slow or silent receiver holds back only that project's events.

**Delivery is at least once.** An event that reached your endpoint may be sent again — a retry after a timeout your server answered too late, or the platform's sender starting again — so key the work on the event's `id`, not on its arrival. An event is never dropped because an endpoint was down for a while: it is retried until it is taken or its attempts run out.

## The events

| Type | Sent when | `data` |
|---|---|---|
| `user.deleted` | A user is deleted — by themselves, or with the secret key. | `{ user_id, is_test, deleted_at }` |
| `session.ended` | A user's session ends — they signed out, ended it from another device, it was revoked (by an admin, a ban, a password reset, its refresh token used twice), it ran out with no one back to renew it (`ended_at` is then the moment its time was up), or the user was deleted. | `{ user_id, session_id, ended_at }` |
| `file.uploaded` | An object is written: a `PUT`, a copy, an upload through a signed URL. | `{ bucket, path, size, content_type, owner_id }` |
| `file.deleted` | An object is deleted. | the same fields |
| `file.moved` | An object is given another path. | the same fields |
| `secret.changed` | A secret is written, rolled back or deleted. The value is never in the event. | `{ environment, name, version, change }` |
| `notification.sent` / `notification.failed` | A message ended sent, or failed. | `{ message_id, channel, rail, template, … }` |
| `notification.received` | A user sent a WhatsApp message to the project's number. | the message |
| `notification.uninstalled` | A push service said no app holds a device's token any more: the app was taken off the phone. The device is forgotten. | `{ platform, provider, device_id, installation_id, user_id }` |
| `notification.push_failing` | A push provider started failing for its own fault — its APNs key refused, a topic the key may not send to: every push through it fails until its setting is fixed ([Apple (APNs)](/docs/backend/notifications#every-channel-but-one-needs-a-provider-of-yours)). At most once a day a provider. | `{ project_id, channel, provider, error, failing_since }` |
| `journey.entered` / `journey.converted` | A person entered a journey, or their run reached its goal. A try on a test user's events carry `test: true` ([Journeys](/docs/backend/journeys#events)). | `{ journey, journey_id, run_id, user_id, test }` |
| `journey.step` | A person's run took a step. | `{ journey, journey_id, run_id, user_id, step, kind, outcome, test }` |
| `journey.event` | A journey's `event` step told the project's backend. | `{ journey, journey_id, run_id, user_id, step, name, data, test }` |
| `journey.ended` | A person's run ended: `completed`, `converted`, `exited`, `stopped`. | `{ journey, journey_id, run_id, user_id, reason, test }` |
| `messaging.report.created` | A person reported a conversation, someone in it or messages of it. Read what it carries with the secret key (`GET /messaging/admin/reports/{report_id}`); an organization that runs its customers' apps passes it on to them from here ([Messaging](/docs/messaging/overview#moderation)). | `{ report_id, conversation_id, reporter_id, reported_user_id, reason, message_count }` |
| `messaging.conversation.created` / `messaging.conversation.deleted` | A conversation was made — by a person, or the project's server — or deleted for everyone. | `{ conversation_id, kind, created_by, member_ids }` / `{ conversation_id, deleted_by }` |
| `audience.entered` / `audience.exited` | A person came to be in an analytics audience, or left it. | `{ audience_id, audience_name, person_id, user_id }` |
| `machine.created` / `machine.updated` / `machine.deleted` | A machine was opened, changed, or taken away. | `{ name, source, size, replicas, port, version }` |
| `stores.apple.changed` | The Apple account was connected, checked (and Apple's answer changed) or disconnected. The key is never in the event. | `{ change, issuer_id, key_id, status, capabilities }` |
| `stores.app.changed` | An app was linked to its store. | `{ change, app_id, bundle_id, asc_app_id }` |
| `stores.package.changed` | A package was made, or its build arrived. | `{ change, package_id, app_id, build_number, version }` |
| `stores.delivery.requested` | A delivery to TestFlight was sent, or sent again. | `{ package_id, channel }` |
| `stores.delivery.changed` | A delivery moved: `queued`, `signing`, `uploading`, `processing`, `compliance`, `ready` or `failed`. | `{ package_id, channel, status, asc_build_id, error_code, error }` |
| `stores.group.changed` | A tester group was made, renamed, deleted, its testers set, or a build given to it. | `{ change, group_id, app_id, name, testers, package_id }` |
| `stores.action.changed` | A planned action (Beta App Review, export compliance, expiring a build, an App Store page or version step) was done, declined or failed. | `{ action_id, kind, package_id, app_id, status, summary }` |
| `stores.version.changed` | An app's App Store version came to a new state: sent to App Review, in review, approved, rejected, withdrawn or released. `result` is App Review's answer, `approved` or `rejected`, or `null`; `source` who told it: `apple_webhook`, `poll` or `action`. | `{ app_id, bundle_id, name, version, asc_version_id, previous_state, state, result, source }` |
| `stores.google.changed` | The Play connection was made, checked (and Play's answer changed) or disconnected. | `{ change, service_account, status, capabilities }` |
| `stores.webhook.changed` / `stores.build.changed` / `stores.beta_review.changed` / `stores.feedback.received` / `stores.product.changed` / `stores.play_release.changed` / `stores.vitals.changed` | An app's App Store Connect webhook, its build uploads, Beta App Review, testers' feedback, its in-app purchases' review, its Play releases and its crash data — each one is in [App Health](/docs/distribution/health#the-events). | the event's own |
| `database.created` / `database.updated` / `database.deleted` / `database.undeleted` / `database.purged` / `database.password_changed` / `database.restoring` | A database's life. | `{ name, size }` |
| `purchases.*` | A purchase, a renewal, a refund, an entitlement or credits changing — each one is in [Purchases › Entitlements](/docs/purchases/entitlements#events). | the event's own |
| `ai.response.started` | A chat's turn began: a member's message, the server's, the chat's goal, or the late messages of the turn before opened it. | `{ response_id, status: "running", model, metadata, chat_id, user_id, message_metadata, goal_id, goal_turn }` |
| `ai.response.completed` / `ai.response.failed` | A response started with `background: true` ended, or a chat's turn did. A turn's `status` is `completed`, `failed`, `stopped` or `budget_exceeded`, its `metadata` the chat's labels, and one that failed says why in `error`. | `{ response_id, status, model, metadata, cost_nano_usd, error?: { code, message, retryable } }`, a turn's with `chat_id, user_id, message_metadata, goal_id, goal_turn` |
| `ai.goal.updated` | A chat's goal was set, its status changed, or it was cleared. | `{ chat_id, goal_id, status, previous_status, stop_code, stop_reason, set_by, metadata }` |
| `ai.voice.started` / `ai.voice.closed` | A chat's voice began, or ended (closed, replaced, its member taken out, its chat deleted, lost). | `{ chat_id, voice_id, user_id, delegation, status, seconds, close_reason, metadata }` |
| `ai.voice.delegated` | A person asked a voice of `delegation: "events"` for something out loud: have it done, and answer with the voice's `speak`, naming the delegation. | `{ chat_id, voice_id, delegation_id, text, earlier, user_id, metadata }` |
| `ai.workspace.published` | A chat's workspace published a tree (mid-turn, as a build writes its product, and once more as its machine lets it go): what changed against the tree it replaced. Read a file of it with `GET /ai/chats/{id}/workspace/files?path=&manifest=`. | `{ chat_id, manifest_id, previous_manifest_id?, changed: [{ path, change, size_bytes }], changed_count, changed_truncated, metadata }` |
| `ai.workspace.pushed` | A chat's agent pushed its work to the chat's branch. | `{ chat_id, repo, repository, branch, head_sha, commits: [{ sha, subject, author_name, author_email }], commits_truncated, response_id, user_id, metadata }` |

The modules' contracts say which of their operations emit which event; each is noted on the operation (for example, `PUT /storage/buckets/{bucket}/objects/{path}` "Emits file.uploaded").

## Checking a delivery

The signature is an HMAC of the body **exactly as it arrived** — the bytes, before any JSON parsing. A parsed and re-serialised body is a different string and never verifies, so read the raw body first.

| Function | Use it for |
|---|---|
| `verifyWebhookRequest(request, secret, { toleranceSeconds?, now?, maxBytes? })` | A fetch `Request` (Node, Bun, Deno, Workers, a Next.js route handler): reads its body — 1 MiB at most unless `maxBytes` says — and its header. |
| `verifyWebhook({ secret, signature, body, toleranceSeconds?, now? })` | A body you already hold, as a string or bytes, and the header's value. |
| `verifySignature({ secret, signature, body, … })` | The check alone, for a signed call whose body is not an event (see below). |

Each throws a `WebhookSignatureError` whose `code` says why:

| `code` | Why |
|---|---|
| `missing_signature` | No `Palbase-Signature` header. |
| `malformed_signature` | The header is not `t=…,v1=…`. |
| `stale_timestamp` | `t` is more than `toleranceSeconds` (300 by default) from now: an old delivery sent again is not taken. |
| `signature_mismatch` | No `v1` is this body signed with this secret — a changed body, or another endpoint's secret. |
| `invalid_body` | The signed body is not JSON, or not an event (`id`, `type`, `project_id`, `created_at`, `data`). |
| `body_too_large` | The body is larger than `maxBytes`. |

`verifyWebhook` takes only an endpoint secret (`whsec_…`): an API key passed by mistake is a `TypeError`, not a check that quietly fails.

```ts
// app/api/palbase/route.ts
import { verifyWebhook, WebhookSignatureError } from "palbase/server";

export async function POST(request: Request): Promise<Response> {
  const body = await request.text(); // the raw body, before anything parses it
  try {
    const event = await verifyWebhook({
      secret: process.env.PALBASE_WEBHOOK_SECRET!,
      signature: request.headers.get("palbase-signature"),
      body,
    });
    console.log(event.type, event.id);
    return new Response(null, { status: 204 });
  } catch (e) {
    if (e instanceof WebhookSignatureError) return new Response(e.code, { status: 401 });
    throw e;
  }
}
```

## The platform's own calls to a machine

The platform signs what it asks of a machine the same way, with the key it starts every machine with in `PALBASE_PLATFORM_SECRET`: the crons' and tasks' lists and calls (`GET /_palbase/crons`, `POST /_palbase/crons/<name>`, `GET /_palbase/tasks`, `POST /_palbase/tasks/<name>`). Those paths are reached only by the platform: a request from outside whose path names them never gets to the machine. A program that serves them checks the call with `verifySignature`, whose body is the request's (empty for a `GET`). See [Machines](/docs/machines/overview).

## Related

- [Event Hooks](/docs/backend/hooks) — `@On` handlers in a `palbase/backend` app
- [Backend Webhooks](/docs/backend/webhooks) — a third party's deliveries (Stripe, GitHub, …) to a `palbase/backend` app, with `@Webhook`
- [Server SDK Overview](/docs/server/overview) — `createServer`, refusals and retries
- [Storage](/docs/backend/storage) — what emits `file.uploaded`, `file.deleted` and `file.moved`
- [Secrets](/docs/backend/secrets) — where a receiving server keeps its endpoint secret



<!-- ===== auth/overview ===== -->

# Auth

Every environment has its own auth: its users, their sessions, the ways they may sign in, and the rules for all three. Nothing of it is shared with another environment, and nothing in it needs code of yours. This section is about setting it up and running it. Signing a person in from an app is [Web Auth](/docs/web/auth), and checking their token in a backend is [Authentication](/docs/backend/authentication).

## Where it is configured

Three places change the same configuration, and each sees what the others did:

- **Studio**, under the environment's **Auth** section: **Overview** (sign-ups and sign-ins over time), **Users**, **Providers**, **Sessions**, **Audit**, **Test accounts**, **Templates** and **Settings**.
- **The CLI**: its `auth:*` commands act on the environment chosen with `palbase use`, or the one `-E` names. A change to a production environment asks for confirmation first ([CLI](/docs/cli/overview#choosing-an-environment)).
- **The auth module's admin calls**, `/admin/*` at the project's address, with a secret key: `createServer({ url, secretKey }).auth` on any server, `Palbase.auth` in a `palbase/backend` app. An app's publishable key reaches none of them.

| What | Studio | CLI | Admin call |
|---|---|---|---|
| The settings | **Auth › Settings** (passwords, email confirmation, passkeys, email links, token lifetimes, security emails) | [`auth:settings:get`](/docs/cli/reference#palbase-authsettingsget), [`auth:settings:set`](/docs/cli/reference#palbase-authsettingsset) | `GET`/`PUT /admin/auth-settings` |
| Sign-in providers | **Auth › Providers** | `auth:providers:*` | `/admin/providers`, `/admin/social-auth` |
| Users | **Auth › Users** | `auth:users:*`, `auth:import` | `/admin/users` |
| Sessions | **Auth › Sessions** | `auth:users:sign-out` | `/admin/sessions` |
| Roles | — | `auth:roles:*` | `/admin/roles` |
| Blocking hooks | — | `auth:hooks:*` | `/admin/hooks` |
| OAuth clients | — | `auth:oauth-clients:*` | `/admin/oauth-clients` |
| Signing keys | — | `auth:signing-keys`, `auth:signing-keys:rotate` | `/admin/signing-keys` |
| The audit trail | **Auth › Audit** | `auth:audit`, `auth:audit:export`, `auth:audit:verify` | `/admin/audit` |
| Test users | **Auth › Test accounts** | `auth:test-users:*` | `/admin/test-users` |
| Auth's emails | **Auth › Templates** | `notify:templates:*` | `/notify/templates/email/{slug}/{locale}` |

The pages of this section:

- [Sign-in Providers](/docs/auth/providers): email, phone, Google, Apple, GitHub and Microsoft, and guest accounts.
- [Users & Roles](/docs/auth/users): the users list, banning, signing out, deleting and exporting a user, roles, and bringing users over from another project.
- [Blocking Hooks](/docs/auth/hooks): an endpoint of yours that auth asks, and waits for, before a sign-up, a sign-in or a token.
- [Audit Trail](/docs/auth/audit): who did what, chained so a change to the record shows.
- [OpenID Provider](/docs/auth/openid-provider): other apps signing in with your users' accounts, service accounts, and sign-in tokens your server makes.

## The settings

```sh
palbase auth:settings:get
palbase auth:settings:set password_min_length=12 confirm_email_required=true
palbase auth:settings:set redirect_urls='["https://app.example.com/**","myapp://callback"]'
```

`auth:settings:set` takes `key=value` pairs. A value that reads as JSON is taken as JSON (`12`, `true`, a list); any other is text, so `site_url=https://app.example.com` needs no quotes. Only the keys given change.

A change is made against the revision it was read at. `GET /admin/auth-settings` answers the revision in its `ETag` header, and `PUT /admin/auth-settings` needs it back in `If-Match`: without it the answer is `428 settings_revision_required`, and with a revision that is no longer current, `412 settings_revision_conflict`. A change someone made in the meantime, in Studio or another terminal, is never overwritten; the CLI and Studio do this for you. From a server:

```ts
// scripts/auth-settings.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

const current = await palbase.auth.adminGetAuthSettings();
const saved = await palbase.auth.adminUpdateAuthSettings({
  headers: { "If-Match": current.headers.get("etag") ?? "" },
  // Only the fields sent change; an unknown field is refused.
  body: { password_min_length: 12, confirm_email_required: true },
});
console.log(saved.data.password_min_length, saved.headers.get("etag"));
```

Every field is checked against the values that will be in force together, so a maximum password length below the minimum, or a refresh token shorter-lived than the access token, is refused (`400`).

### New users

`signups_enabled` (default `true`) lets your apps create accounts. Off, every way a client opens one answers `403 signups_closed`: a sign-up with a password, a passkey sign-up, a guest, a phone's first code and a provider's first sign-in. People who have an account sign in as before, and your server still creates users with the secret key (`POST /admin/users`, imports, test users): it is how a closed app lets someone in.

```sh
palbase auth:settings:set signups_enabled=false
```

### Passwords and email

| Key | Default | What it says |
|---|---|---|
| `password_min_length` | `8` | The shortest password accepted, 6 to 64. |
| `password_max_length` | `64` | The longest, never below the shortest. |
| `confirm_email_required` | `false` | A new email account confirms its address before it signs in. With it on, a sign-up answers no session, and a sign-in before the confirmation is `403 email_not_confirmed`. |
| `email_verification_method` | `code` | How an address is confirmed: a one-time `code` in the email, or a `link`. |

A password found in a known breach is refused at sign-up and on every change (`400 password_breached`). Users created with the secret key can skip that check (`skip_password_hibp`).

### Links in auth emails

| Key | Default | What it says |
|---|---|---|
| `site_url` | none | The base of the links in auth emails: `https://app.example.com/auth/verify-email?token=…`, and the same for `reset-password` and `magic-link`. Empty: the pages auth serves itself. |
| `redirect_urls` | `[]` | Where a request's `redirect_to` may send a link instead: up to 100 URLs, wildcards and app schemes (`myapp://callback`) allowed. |

The order in which they are used, and the pages your site needs, are in [Where email links land](/docs/web/auth#where-email-links-land). A web app registered with `palbase apps:env:set <app> --redirect <url>` adds its redirects to the allow-list too.

### Sessions and tokens

| Key | Default | What it says |
|---|---|---|
| `access_token_ttl_seconds` | 1800 (30 minutes) | The access token's lifetime, 60 to 86400. |
| `refresh_token_ttl_seconds` | 2592000 (30 days) | The refresh token's, 3600 to 7776000: how long a user stays signed in without using the app. |
| `max_concurrent_sessions` | `0` | The most live sessions one user may hold; `0` is no limit. |
| `concurrent_session_strategy` | `revoke_oldest` | Past the limit: end the user's oldest sessions (`revoke_oldest`), or refuse the new sign-in with `409 max_sessions_reached` (`deny_new`). |
| `session_device_binding` | `false` | A session belongs to the device it was opened on: a refresh from another device, browser or operating system ends it. A change of network is only recorded in the audit trail. |
| `inactive_user_days` | `0` | Ban accounts with no sign-in, refresh or session activity for this many days, with the reason `inactive`: `0` is never, otherwise 30 to 3650. Test users are left alone; unbanning lets them back in. |

A refresh token is used once: each refresh answers a new pair. The same refresh token presented again, past a 30-second allowance for a retry, ends the session: someone else holds a copy of it.

### Passkeys

| Key | Default | What it says |
|---|---|---|
| `passkey_require_identifier` | `true` | A passkey sign-up carries an identifier. With it off, an account can be only its passkey. |
| `passkey_identifier_kind` | `email` | Which identifier that is: `email` or `phone`. |

The origins a passkey is accepted from are the environment's web apps; see [Passkeys](/docs/web/auth#passkeys).

### Guests

`anonymous_sign_ins` (default `false`) lets a visitor have an account and a session without signing up. See [Guests](/docs/auth/providers#guests).

### Risk

| Key | Default | What it says |
|---|---|---|
| `risk_engine_enabled` | `false` | Score every sign-up and sign-in for risk, from 0 to 1. |
| `risk_step_up` | `0.3` | At this score a sign-in asks for a second factor: an email code when the account has none (it proves the inbox; the session it opens is `aal1`, as an email code is not a second factor). |
| `risk_strict_step_up` | `0.6` | At this score it asks for a strong one, an authenticator app or a passkey, when the account has one. |
| `risk_block` | `0.8` | At this score the sign-up or sign-in is refused, answered as a wrong password or a failed sign-up would be, so the refusal does not tell anyone the account exists. |

The three scores are set together, in that order (step up < strict step up < block). The score is made from the device's attestation, the account's own sign-in history, and, when the environment connects its own account with them, [Fingerprint](https://fingerprint.com) and [MaxMind](https://www.maxmind.com). A risk engine that cannot answer refuses a sign-up with `503` rather than letting it through.

Those two, and [Have I Been Pwned](https://haveibeenpwned.com), are connected with the environment's own credentials, from a server:

| Call | What it does |
|---|---|
| `PUT /admin/integrations/fingerprint` | `{ api_key, region? }`: a Server API key, and `us`, `eu` or `ap`. The app sends the agent's visitor id as `fingerprint_visitor_id` with a sign-in. |
| `PUT /admin/integrations/maxmind` | `{ account_id, license_key }` |
| `PUT /admin/integrations/hibp` | `{ api_key, requests_per_minute? }`: turns on the breached-account watch. Each user's address is checked every 30 days, and an account found in a breach must reset its password at its next sign-in (`403 password_reset_required`). `GET /admin/breach-watch` says how many it checked and found. |

`GET /admin/integrations` says which are connected; the credentials are never answered. `DELETE /admin/integrations/{name}` disconnects one.

### Security emails

`security_notifications` lists the changes a user is emailed about: `password_changed`, `email_changed` (told to the old address), `identity_linked`, `identity_unlinked`, `mfa_factor_enrolled`, `mfa_factor_removed`, `passkey_added`, `passkey_removed`. A second factor or a passkey added or removed (`mfa_factor_enrolled`, `mfa_factor_removed`, `passkey_added`, `passkey_removed`) is mailed by default, in every project: a change to what a user signs in with that they did not make is how a stolen password shows. The others are off until the project turns them on. Each is sent only to a confirmed address, in the user's language, with its own template (`auth.security_<kind>`). **Auth › Settings › Security notifications** turns each on and off.

### The OpenID provider

`oauth_login_url` and `fapi_enabled` are the environment's [OpenID Provider](/docs/auth/openid-provider#its-sign-in-page)'s.

### App Attest

`app_attest_mode` is `off` (the default), `monitor` or `enforce`: the switch of the backend routes marked `attest: true` ([Device attestation](/docs/backend/authentication#device-attestation)), read by the environment's machines every 30 seconds. `monitor` and `enforce` need an iOS or Android app registered with the environment (`palbase apps:env:set`).

Auth enrols a device when the app proves it: an iOS device's App Attest key (`POST /auth/devices/attest/ios`), or an Android device's Keystore key, whose attestation chain must end in one of Google's hardware attestation roots with no certificate on Google's revocation list, the key in the phone's secure hardware, the phone locked with a verified boot, and the app the registered package signed with a registered certificate (`POST /auth/devices/attest/android`). Both take the challenge of `POST /auth/devices/challenge` and need no session. The three are limited to 10 calls in 15 minutes per installation (or signed-in user) at an address, and 600 per address over every installation behind it: one install retrying does not stop the next phone behind the same carrier's address. Past either: `429 rate_limit_exceeded` with `Retry-After`, which the SDKs report as `enrolment_rate_limited`. Auth verifies a request's proof when a server asks it to (`POST /admin/attest/devices/assert`, with the secret key; a passing verdict names the device, its `device_id` and `platform`), and answers the mode at `GET /admin/attest/devices/attest-policy` and the last hours' counts at `GET /admin/attest/devices/observations`. Palbase's iOS and Android SDKs do the enrolment and the proofs by themselves.

## Signing keys

The environment's tokens are signed with its own keys, `ES256`, and its key set is public at `https://<ref>.palbase.studio/.well-known/jwks.json`. That is how a backend checks a token without asking auth ([How the token is verified](/docs/backend/authentication#how-the-token-is-verified)).

```sh
palbase auth:signing-keys
palbase auth:signing-keys:rotate
```

Keys rotate on their own every 90 days. A key is published in the key set a day before it starts signing, so a verifier that reads the key set once a day already holds it. A key that stops signing goes on verifying the tokens it signed until the longest of them has expired, and is then retired. Its status says where it is: `next` (published, not signing), `active` (signs), `grace` and `verification_only` (verify only), `retired` (gone from the key set).

`auth:signing-keys:rotate` (`POST /admin/signing-keys/rotate`) makes the change now: the published next key, or a new one, signs from then on. Tokens already issued keep working. Rotate when you think a key may have been exposed; a verifier that sees the new `kid` reads the key set again.

## Auth's emails and texts

Auth sends its emails through the project's notifications, from templates that belong to the environment: `auth.email_verify` and `auth.email_verify_code` (confirming an address), `auth.password_reset`, `auth.magic_link`, `auth.mfa_otp` (a sign-in code by email), and the security emails above. A phone code is the SMS template `auth.sms_otp`.

**Auth › Templates** edits them in each language and sends a test. Until the environment has its own email provider, auth's mail goes through the platform's shared sender with the default text; your edits are used once your own provider is connected ([Notifications](/docs/backend/notifications#every-channel-but-one-needs-a-provider-of-yours)). The same templates are reachable as any others: `palbase notify:templates:set`, or `PUT /notify/templates/email/{slug}/{locale}` ([Templates](/docs/backend/notifications#templates)).

## Between environments

```sh
palbase config:diff --from staging --to main
palbase config:copy --from staging --to main
```

The auth part of `config:copy` makes the target's settings, phone sign-in, social providers, roles, blocking hooks and OAuth clients equal to the source's. Secrets are not copied: a provider secret the target lacks is named, with the command that sets it, and a hook or confidential OAuth client made in the target gets a secret of its own, printed once.

## Related

- [Web Auth](/docs/web/auth): the sign-in flows in an app
- [Authentication](/docs/backend/authentication): the token in a backend
- [Test Users](/docs/backend/test-users): accounts for tests
- [Webhooks](/docs/server/webhooks): `user.deleted`, `session.ended` and the other events auth sends
- [CLI reference](/docs/cli/reference#auth): every `auth:*` command



<!-- ===== auth/providers ===== -->

# Sign-in Providers

An environment's users sign in with email, a phone number, or an account at Google, Apple, GitHub or Microsoft, and visitors can have a guest account before they sign up. Email is always on. Every other way is off until you turn it on, in Studio's **Auth › Providers** or with `palbase auth:providers:set`.

```sh
palbase auth:providers:list
```

`auth:providers:list` prints each provider, whether it is on, its clients, and the secrets it keeps (by name; a secret is never printed).

## Email

Email sign-in cannot be turned off, and has no switch of its own: an account with an address signs in with its password, a magic link or a passkey, as the app offers. Its rules are the environment's [auth settings](/docs/auth/overview#passwords-and-email): password lengths, whether an address is confirmed before the first sign-in, whether the confirmation is a code or a link, and where the links in its emails land.

The emails are sent through the environment's notifications ([Auth's emails and texts](/docs/auth/overview#auths-emails-and-texts)).

## Phone

A phone number signs in with a code texted to it (`POST /auth/otp`, then `POST /auth/otp/verify`), and a text can be a second factor. Phone sign-in needs a way to send texts: the environment's own SMS provider, or its verification service, set up in the notifications module ([SMS, codes and WhatsApp](/docs/backend/notifications#sms-codes-and-whatsapp)).

```sh
palbase auth:providers:set phone --enable
palbase auth:providers:set phone otp_ttl_seconds=120 otp_max_attempts=5 allow_signups=false
palbase auth:providers:disable phone
```

| Setting | Default | What it says |
|---|---|---|
| `allow_signups` | `true` | A code sent to a number no account has makes an account. With it off, only existing accounts sign in by phone. |
| `otp_ttl_seconds` | `300` | How long a code is good for, 1 to 300 seconds. |
| `otp_max_attempts` | `5` | Wrong codes allowed before the code is spent, 3 to 10. |
| `sender` | `sms` | Who makes the code: `sms` (auth makes it, and texts it through your SMS provider with the template `auth.sms_otp`) or `verify` (your verification service makes and checks it). |
| `sms_second_factor` | `true` | Whether a text may be a user's second factor. Turn it off if you hold texts too weak for one. |

Studio sets them under **Auth › Providers**, the phone row's settings. Which countries a text may reach is the notifications settings' (`sms_countries`, `sms_blocked_countries`). A phone sign-in that is off answers `provider_not_enabled`.

## Google, Apple, GitHub and Microsoft

Social sign-in has three parts, set up per provider:

- **The switch.** A provider that is off signs no one in, whatever its clients say.
- **Clients.** A client is one app's way in: its `key`, the `application_key`, `platform` (`web`, `ios`, `macos`, `android`) and `variant` (a build: `release`, `debug` …) it serves, and the provider's own identifiers for it. An app asks for the clients of its application, platform and variant (`GET /auth/oauth/config`) and gets what a sign-in button needs, with nothing secret in it. A **browser client** sends the person to the provider's page and back; a **native client** signs in with the platform's own sheet (Sign in with Apple, Google's and Microsoft's SDKs) and hands auth the provider's ID token.
- **Secrets.** A browser client names the stored secret it uses (`credential_ref`). Secrets are kept by a name you choose, encrypted, and never answered. A native client needs none.

### What each provider needs

Register this callback with the provider, for every browser client:

```text
https://<ref>.palbase.studio/auth/oauth/callback/<provider>
```

`<provider>` is `google`, `apple`, `github` or `microsoft`. Studio shows it, ready to copy, as **Backend callback URL** in the provider's settings. After the provider sends the person back there, auth sends them on to your app's **return URI**: one of the client's `return_uris`, exactly as listed, or the sign-in is refused (`invalid_return_uri`).

| Provider | Browser client | Its secret | Native clients |
|---|---|---|---|
| Google | `web_client_id`: the OAuth client id of a **Web application** client in Google Cloud | That client's secret | iOS and macOS: `bundle_id`, `ios_client_id`, `redirect_uri`. Android: `package_name`, `android_client_id`, `server_client_id` (the Web application client's id), `signing_certificate_sha1` |
| Apple | `services_id`: a **Services ID** with Sign in with Apple turned on | A Sign in with Apple **key** (the `.p8` file), with your Team ID and the key's Key ID | iOS and macOS: `bundle_id` |
| GitHub | `oauth_client_id`: an **OAuth App**'s client id | The OAuth App's client secret | — (browser only) |
| Microsoft | `application_id`: an app registration's **Application (client) ID**, and the `directory` it takes accounts from | A client secret of that registration | iOS, macOS and Android: `application_id`, `bundle_id` or `package_name`, `redirect_uri`, `directory` |

A Microsoft `directory` is `common` (work, school and personal accounts), `organizations` (work and school), `consumers` (personal), or the id of one organization's directory, for its accounts alone. Apple on Android signs in through the browser.

### From the CLI

```sh
# Google: a browser client named web, its return URI, and its secret from stdin.
palbase auth:providers:set google --client-id 1234567890-abc.apps.googleusercontent.com \
  --return-uri https://app.example.com/signin/callback --secret-stdin < google-secret.txt
palbase auth:providers:set google --enable

# Apple: the Services ID, and the .p8 key with its team and key ids.
palbase auth:providers:set apple --client-id com.example.web --return-uri https://app.example.com/signin/callback \
  --secret-stdin --team-id ABCDE12345 --key-id XYZ987WVU6 < AuthKey_XYZ987WVU6.p8
palbase auth:providers:set apple --enable

# Microsoft, for work and school accounts only.
palbase auth:providers:set microsoft --client-id 00000000-0000-0000-0000-000000000000 --directory organizations \
  --return-uri https://app.example.com/signin/callback --secret-stdin < microsoft-secret.txt
```

- `--client-id` sets the browser client that `--client` names (`web` by default), making it when the provider has none of that name. `--application` and `--variant` say what it serves (`app` and `release` by default); `--return-uri`, repeated, replaces its return URIs.
- `--secret-stdin` reads the secret from standard input, never from the command line, and keeps it under `--credential` (the provider's name by default).
- `--clients-file clients.json` replaces the provider's clients with a file's `{ "browser_clients": […], "native_clients": […] }`: the way to set native clients, and several at once.
- `palbase auth:providers:disable <provider>` turns a provider off and keeps its clients and secrets. `palbase auth:providers:secret:delete <name>` deletes a stored secret; one a client still uses is refused.

### In Studio

**Auth › Providers** lists every provider with its switch. A social provider's settings hold its clients (**Add client**: the client key, application key, platform, variant, browser or native, and the fields the table above names) and its **Browser credentials**: a secret saved under a credential key, which a browser client then selects. A Google client JSON or an Apple `.p8` file can be imported instead of pasting.

A change is made against the configuration read when the form opened: one saved elsewhere in the meantime is refused, and the form asks you to reopen it. The admin calls are the same: `GET /admin/social-auth` answers an `ETag`, and `PATCH /admin/social-auth/providers/{provider}` and `PUT /admin/social-auth/credentials/{key}` take it in `If-Match`.

### When the address is an existing account's

A provider account that is already linked signs in to its user. One that is not:

- **links to the account that holds its email address**, and signs in to it, when the provider hosts that address (Google for Gmail and Workspace addresses, Apple for iCloud addresses) and the account's address was confirmed and it has no second factor;
- **is refused** with `409 identity_link_required` when another account holds the address on any other terms: the person signs in to that account and links the provider from there;
- **makes a new account** when no account holds the address.

A signed-in user links another provider to their own account with the same flow (`purpose: "link"`). The app's side of the browser flow is in [Social sign-in](/docs/web/auth#social-sign-in).

## Guests

A guest is an account with no address, password or credential: only its session. A visitor can use your app as a guest and sign up later, and the account keeps its id, so what they did as a guest stays theirs. Turn guests on in the settings:

```sh
palbase auth:settings:set anonymous_sign_ins=true
```

Off, a guest sign-in answers `403 anonymous_sign_ins_disabled`. A guest is held to what holds a sign-up: the environment's user limit, proof of work, the risk engine and your `before.user.create` [hook](/docs/auth/hooks) (told `is_anonymous: true`), and 30 guests an hour from one address. Its access token says `is_anonymous: true`.

```ts
// src/lib/palbase.ts
import { createClient } from "palbase/web";

export const pb = createClient({ url: "https://k3xq81w4m.palbase.studio", publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5" });
```

```ts
// src/guest.ts
import { pb } from "./lib/palbase";

/** A visitor's first visit: a guest account and its session. */
export async function startAsGuest(): Promise<string> {
  const current = await pb.auth.currentSession();
  if (current) return current.userId;
  const { data } = await pb.auth.api.signInAnonymously({ body: { locale: navigator.language } });
  if (!data.access_token || !data.refresh_token || !data.expires_in) throw new Error("the guest has no session");
  await pb.auth.setSession({ access_token: data.access_token, refresh_token: data.refresh_token, expires_in: data.expires_in });
  return data.user.id;
}

/** Later: the guest becomes an account with an address and a password, under the same id. */
export async function keepAccount(email: string, password: string): Promise<void> {
  await pb.auth.api.convertAnonymousUser({ body: { email, password } });
}

/** With the code the email carried. */
export async function confirmAccount(code: string): Promise<void> {
  await pb.auth.api.verifyAnonymousConversion({ body: { code } });
  await pb.auth.refreshSession(); // the new tokens no longer say is_anonymous
}
```

The address is the account's only once its owner confirms it: with the emailed code (`POST /auth/anonymous/convert/verify`, in the guest's own session) or, when the environment confirms by link, the link's token (`POST /auth/verify-email`). Until then the account is still a guest. An address another account holds is `409 email_exists`, and the guest stays signed in. A guest also becomes an account by adding a passkey, or by linking a social provider with its session; either way it keeps its id. Your backends hear `user.converted`.

## Related

- [Overview](/docs/auth/overview): the auth settings
- [Web Auth](/docs/web/auth): the sign-in flows in a browser
- [Blocking Hooks](/docs/auth/hooks): approving a sign-up or a sign-in from your own code
- [Notifications](/docs/backend/notifications): the email and SMS providers auth sends through
- [CLI reference](/docs/cli/reference#palbase-authprovidersset): `auth:providers:set` and its flags



<!-- ===== auth/users ===== -->

# Users & Roles

An environment's users are its auth module's: each has an id (`usr_…`), and any of an email address, a phone number, a password, linked provider accounts, passkeys and second factors. People make their own accounts from your app ([Web Auth](/docs/web/auth)). This page is about the other side: finding them, helping them, stopping them, and the roles your app gives them.

## Finding a user

Studio's **Auth › Users** lists the environment's users, newest first: their address or phone, whether they are active or banned, a test user, or have a second factor, which addresses are confirmed, when they signed up and last signed in. **Account status** shows the banned alone. A user's page has their contact details, how they sign in, their second factors, their sessions and their metadata, and the actions below.

```sh
palbase auth:users:list --limit 500
palbase auth:users:list --banned
palbase auth:users:get usr_01J…
```

`auth:users:get` adds how they sign in and the roles they hold. From a server, `GET /admin/users` pages through them (`limit`, `cursor`, `banned`) and `GET /admin/users/{uid}` reads one, with the email and phone in clear.

## Making one

```sh
palbase auth:users:create ada@example.com --verified < password.txt
```

The password is read from standard input, never from the command line. The account is made at once, with no email sent: share the password through a channel you trust. **Auth › Users › Create user** does the same. `POST /admin/users` takes `{ email, password, email_verified?, metadata?, skip_password_hibp? }`; it skips the self-service sign-up's rate limits and bot checks, but still holds the password to the environment's policy and, unless told not to, to the known-breaches check.

`PATCH /admin/users/{uid}` changes a user's `email`, `email_verified` and `metadata`. A new address is unconfirmed unless `email_verified` is sent with it, and one another user has is `409 user_exists`. `metadata` is merged into what the user has: a key set to `null` is removed.

## Helping someone back in

| Studio (the user's page) | CLI | Admin call | What it does |
|---|---|---|---|
| **Create reset token** | — | `POST /admin/users/{uid}/reset-password` | A one-hour password reset token, answered to you, with no email sent. The person sets a new password with it (`pb.auth.password.confirmReset(token, …)`). |
| **Reset MFA** | — | `DELETE /admin/users/{uid}/mfa` | Removes every second factor and recovery code, for someone who lost their authenticator: they sign in with their first factor and enroll again. |
| **Revoke all sessions** | `auth:users:sign-out` | `POST /admin/users/{uid}/sessions/revoke-all` | Ends every session: each device signs in again. |
| — | — | `POST /admin/users/{uid}/credentials/revoke-all` | Ends every session and refresh token, and revokes the user's attested and trusted devices and pending transactions, at once. The account stays. |

## Banning

```sh
palbase auth:users:ban usr_01J… --reason "chargeback fraud"
palbase auth:users:unban usr_01J…
```

A banned user's sessions end, and their sign-ins are refused with `403 user_banned` until they are unbanned. The reason is kept as `ban_reason`, and Studio shows it. **Ban user** and **Unban user** on the user's page do the same; the admin calls are `POST /admin/users/{uid}/ban` (`{ reason? }`) and `POST /admin/users/{uid}/unban`.

The environment can ban idle accounts by itself: `inactive_user_days` in the [auth settings](/docs/auth/overview#sessions-and-tokens).

## Sessions

Studio's **Auth › Sessions** lists the environment's live sessions: whose, the device and browser, the address, the authentication level, when each started and was last used. One can be revoked there. From a server, `GET /admin/sessions` (with `user_id` for one user's) and `DELETE /admin/sessions/{id}`.

Revoking a session deletes its refresh tokens, so it is never renewed. An access token it already issued is valid until it expires, but a `palbase/backend` app stops taking it within 15 seconds ([How the token is verified](/docs/backend/authentication#how-the-token-is-verified)). Backends hear `session.ended`.

## Deleting a user

```sh
palbase auth:users:delete usr_01J…
```

The user and everything auth holds for them go in one step: sessions, tokens, second factors, passkeys, linked providers, consents, roles. It cannot be undone. The project's other modules delete what is the user's too (a file stored with their `owner_id`, their flag values, their devices and messages), and your backends hear `user.deleted` to delete what is theirs in your own tables ([Event Hooks](/docs/backend/hooks)). **Delete user** on the user's page, and `DELETE /admin/users/{uid}`, do the same. A person deletes their own account from your app with `deleteAccount` ([Web Auth](/docs/web/auth#signing-out-and-deleting-the-account)).

## A user's own data

```sh
palbase auth:users:export usr_01J… --out ada.json
```

Everything auth holds about one person, as they may ask for it under the GDPR (articles 15 and 20), as JSON: their profile with the email and phone in clear, linked providers, sessions, consents, second factors, passkeys, devices, and their part of the audit trail. It holds no secrets: no password hash, no factor secret, no token. The export is itself recorded in the [audit trail](/docs/auth/audit). The file `--out` writes is readable by you alone. **Export user data** on the user's page, and `GET /admin/users/{uid}/export`, answer the same.

## Roles

A role is a name your app gives users, with the permissions it stands for. Roles are defined in the environment and given to users with the secret key; your code decides what they allow.

```sh
palbase auth:roles:set editor --permissions posts.publish,posts.delete_any --description "Edits everyone's posts"
palbase auth:roles:set member --permissions posts.write --default yes
palbase auth:roles:list
palbase auth:roles:delete editor --force
```

- A role's name is lowercase letters, digits and `_`, 64 at most. `anon`, `authenticated`, `service_role` and names starting `backend_` are the platform's.
- A permission is `resource.action`: lowercase, one dot, no wildcard (`posts.delete_any`). `--permissions` replaces the role's list; `""` empties it. Users who hold the role have the new list at once.
- `--default yes` gives the role to every new user. One role at most is the default.
- A role users hold is deleted only with `--force`, which takes it from them; without it the answer is `409`.

There is no CLI command that gives a user a role: that is your app's decision, made from your server.

| Admin call | What it does |
|---|---|
| `PUT /admin/users/{uid}/roles/{role}` | Gives the user the role. A role that is not defined is `400 role_not_defined`. |
| `DELETE /admin/users/{uid}/roles/{role}` | Takes it from them. |
| `GET /admin/users/{uid}/roles` | The roles they hold. |
| `PUT /admin/roles/{name}`, `DELETE /admin/roles/{name}` | What `auth:roles:set` and `auth:roles:delete` call. |

The roles a user holds are in the `user` of every sign-in answer, as `roles`, not in their access token. A backend asks for them where it decides (the [Roles](/docs/backend/authentication#roles) section of Authentication shows how), and hears `user.permissions_changed`, with the user's whole permission list, each time a role is given, taken or changed. `palbase types:pull` writes the environment's role names into `palbase/palbase-env.d.ts`.

## Bringing users over

`auth:import` brings users from another Palbase project, or from any source written as import bodies, with what they sign in with, so they notice nothing:

```sh
palbase auth:import users.ndjson --pepper-stdin < pepper.txt
palbase auth:import ./export/        # users-0001.json, users-0002.json … in order
```

A file is one import body (`{ "hash": { … }, "users": [ … ] }`, with no pepper in it), JSON lines with a user a line, or one JSON array of users. Each user keeps:

| Field | What is kept |
|---|---|
| `id` | Their id, `usr_` and a lowercase UUID. |
| `email`, `phone`, `email_verified`, `phone_verified`, `email_confirmed_by` | Their addresses, and who confirmed the email (`email`, `admin`, `google`, `apple`). |
| `password_hash`, `recovery_code_hashes` | Their password and recovery codes, as the source hashed them: `palbase-argon2id` only. Verified with the source's pepper until the user's next sign-in hashes the password again with this environment's. |
| `identities` | Their linked provider accounts: `provider` and the provider's `subject`. |
| `mfa_factors` | Second factors, at most one of each type: an authenticator app's secret, a phone, an email. |
| `passkeys` | Their WebAuthn credentials. A passkey signs in here when the environment's passkey host is the one it was registered for. |
| `sessions` | Their open sessions: the refresh token their app holds goes on working, here. An ended session, or a banned user's, is left behind. |
| `metadata`, `locale`, `banned`, `ban_reason`, `created_at`, `last_login_at` | As they were. |

The source's pepper, which the hashes were made with, is read from standard input (`--pepper-stdin`), never from a file or the command line. Auth keeps it sealed and uses it only to verify.

Users go 1000 to a call, and each is written whole or not at all. One user refused does not stop the others: the command lists each by id and why. A user whose id, address, phone, provider account, passkey or session the environment already has is refused (`user_exists`, `email_exists` …), never overwritten, so running the same import again writes only what the first run did not. The admin call is `POST /admin/users/import`, 1000 users and 1 MiB a call.

## Test users

Accounts made for tests, marked `test: true` in their tokens and left out of the counts, are [Test Users](/docs/backend/test-users): `palbase auth:test-users:create`, and Studio's **Auth › Test accounts**.

## Related

- [Overview](/docs/auth/overview): the environment's auth settings
- [Audit Trail](/docs/auth/audit): what was done to each user, and by whom
- [Authentication](/docs/backend/authentication): the user in a backend route
- [Webhooks](/docs/server/webhooks): `user.deleted`, `session.ended` and the other events
- [CLI reference](/docs/cli/reference#palbase-authuserslist): the `auth:users:*` commands



<!-- ===== auth/hooks ===== -->

# Blocking Hooks

A blocking hook is an endpoint of yours that auth calls, and waits for, before it does something: creating an account, signing someone in, issuing a token. The endpoint answers `allow` or `deny`, and auth goes on or refuses. An allow before a token can also put claims of yours in it. The call and the answer are both signed with the hook's own secret, so auth knows the answer is yours and you know the call is auth's.

What happens *after* an operation is not a hook: it is an event, delivered to the project's webhooks (`user.deleted`, `session.ended`, `user.converted` …), and it cannot change what happened ([Webhooks](/docs/server/webhooks)).

## Quick example

Register the hook. Its signing secret is printed this once:

```sh
palbase auth:hooks:create --event before.user.create --url https://hooks.example.com/auth
```

```text
Registered hook_01J…: before.user.create → https://hooks.example.com/auth.
signing secret (shown this once): whsec_…
```

Keep it where the endpoint reads it, here `AUTH_HOOK_SECRET`. Then the endpoint: any server that answers HTTPS at a public address. This one is Node with nothing installed:

```ts
// hooks/server.ts
import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";

// whsec_ and the key in base64, as auth:hooks:create printed it.
const key = Buffer.from(process.env.AUTH_HOOK_SECRET!.replace(/^whsec_/, ""), "base64");

function sign(id: string, timestamp: string, body: string): string {
  return createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64");
}

interface HookCall {
  event: string;
  user?: { id?: string; email?: string; email_verified?: boolean; is_anonymous?: boolean };
  context?: { ip?: string; user_agent?: string; risk_score?: number };
}

interface HookAnswer {
  verdict: "allow" | "deny";
  reason?: string;
  custom_claims?: Record<string, unknown>;
}

function decide(call: HookCall): HookAnswer {
  if (call.event === "before.user.create" && call.user?.email && !call.user.email.endsWith("@example.com")) {
    return { verdict: "deny", reason: "Sign-ups are open to example.com addresses only." };
  }
  if (call.event === "before.token.issue") {
    // Your own data about the user goes into the token they are about to get.
    return { verdict: "allow", custom_claims: { plan: "pro" } };
  }
  return { verdict: "allow" };
}

createServer((req, res) => {
  const chunks: Buffer[] = [];
  req.on("data", (chunk: Buffer) => chunks.push(chunk));
  req.on("end", () => {
    // The signature is over the bytes as they arrived: read them before parsing anything.
    const body = Buffer.concat(chunks).toString("utf8");
    const id = String(req.headers["webhook-id"] ?? "");
    const timestamp = String(req.headers["webhook-timestamp"] ?? "");
    const expected = Buffer.from(`v1,${sign(id, timestamp, body)}`);
    const given = String(req.headers["webhook-signature"] ?? "").split(" ").map((s) => Buffer.from(s));
    const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
    if (!fresh || !given.some((s) => s.length === expected.length && timingSafeEqual(s, expected))) {
      res.writeHead(401).end();
      return;
    }

    // The answer is signed the same way, with an id and a time of its own.
    const answer = JSON.stringify(decide(JSON.parse(body) as HookCall));
    const answerId = `msg_${randomUUID()}`;
    const answerTimestamp = String(Math.floor(Date.now() / 1000));
    res.writeHead(200, {
      "content-type": "application/json",
      "webhook-id": answerId,
      "webhook-timestamp": answerTimestamp,
      "webhook-signature": `v1,${sign(answerId, answerTimestamp, answer)}`,
    });
    res.end(answer);
  });
}).listen(Number(process.env.PORT ?? 8080));
```

A sign-up with any other address is now refused with `403 hook_denied`, and its message is your `reason`.

## The events

| Event | Auth calls it before | It is sent |
|---|---|---|
| `before.user.create` | An account is made: an email sign-up, a passkey sign-up, a social sign-up, a guest, a guest becoming an account | `user.email`, `user.email_verified`, `user.is_anonymous` (no id yet) |
| `before.login` | A password, magic-link, passkey or social sign-in | `user.id`, `context.ip`, `context.user_agent`, `context.risk_score` |
| `before.password.reset` | A password reset email is sent | `user.id` |
| `before.mfa.verify` | An authenticator-app or text code is checked as a second factor | `user.id` |
| `before.social.link` | A provider account is linked to a user | `user.id` |
| `before.token.issue` | A user's access token: at every sign-in, whatever its way, and at every refresh | `user.id` |
| `before.token.refresh` | A session is refreshed | `user.id`, `context.ip`, `context.user_agent` |
| `before.transaction.approve` | A user approves a transaction | `user.id` |
| `before.device_grant.initiate` | A device asks for a code ([OpenID Provider](/docs/auth/openid-provider#signing-in-a-device)) | — |
| `before.device_grant.authorize` | A user approves a device's code | `user.id` |

The body is `{ event, user?, context?, client_metadata? }`; a social sign-in or sign-up also sends `client_metadata.transaction_id`. A phone-code sign-in, or a phone sign-up, calls `before.token.issue` alone.

## The call and the answer

Auth POSTs the JSON body to the hook's URL with three headers, as [Standard Webhooks](https://www.standardwebhooks.com) has them:

| Header | What it is |
|---|---|
| `webhook-id` | The call's id, `msg_…`. |
| `webhook-timestamp` | When it was sent, in Unix seconds. |
| `webhook-signature` | `v1,` and the base64 HMAC-SHA256, under the secret's key, of `<webhook-id>.<webhook-timestamp>.<body>`. |

The key is the secret's part after `whsec_`, decoded from base64. An endpoint checks the signature against the body's bytes before it reads them, and refuses a timestamp more than a few minutes away.

The answer is `2xx` with a JSON body, **signed the same way**: its own `webhook-id`, a `webhook-timestamp` within five minutes of auth's clock, and a `webhook-signature` over that id, that time and the answer's body, with the same key.

| Field | What it says |
|---|---|
| `verdict` | `allow` or `deny`. |
| `reason` | Why, for a deny. A sign-up, a guest and a guest's conversion pass it to the person refused, as the message of their `403 hook_denied`; other operations answer `hook_denied` in their own words. |
| `custom_claims` | On an allow of `before.token.issue`: claims put in the access token under its `custom_claims` claim. A `palbase/backend` route reads them as the user's `metadata` ([The `UserT` shape](/docs/backend/authentication#the-usert-shape)). |

A token's claims are asked for again at each refresh, so they are never older than the token. A `before.password.reset` that denies sends no email, and the request answers as it always does, so no one learns from it whether the address has an account.

Several hooks on one event are called one after another, oldest first. The first deny refuses; the `custom_claims` of the allows are merged, a later hook's key winning.

## Timeouts and failures

`--timeout` is how long auth waits for an answer, 100 to 5000 ms (5000 by default). A hook **fails** when it does not answer in that time, or answers with a status other than `2xx`, without a valid signature, or with a body that is not JSON. What auth does then is the hook's `--failure-mode`:

| `failure_mode` | When the hook fails |
|---|---|
| `deny` (the default) | The operation fails, as an error rather than as `hook_denied`: a sign-up or a password sign-in answers `500 internal_error`. |
| `allow` | The operation goes on as if the hook had allowed it, with no claims added. |

The two device-grant events go on when their hook fails, whatever its failure mode.

Choose `deny` for a hook that is a rule (who may sign up, who may sign in), and `allow` for one that only adds something. Every sign-in waits for its hooks, so put the endpoint where it answers at once: a [machine](/docs/machines/overview) of a size that sleeps makes the first sign-in after it fell asleep wait for it to wake.

The URL is `https`, and it must not resolve to a private address.

## Managing hooks

```sh
palbase auth:hooks:list
palbase auth:hooks:update hook_01J… --timeout 2000 --failure-mode allow
palbase auth:hooks:update hook_01J… --disable
palbase auth:hooks:delete hook_01J…
```

`auth:hooks:update` changes the event, the URL, the timeout, the failure mode or the switch; the secret stays. A hook registered with `--disable`, or turned off, is not called. Deleting one stops the calls at once. The admin calls are `GET`/`POST /admin/hooks` and `PUT`/`DELETE /admin/hooks/{id}`; `PUT` replaces the hook whole, and an optional field it leaves out takes its default, not its current value.

`GET /admin/hooks/{id}/executions` lists a hook's calls, newest first, for thirty days: what it was sent (without the email address), what it answered, how long it took, and the verdict auth took (`allow`, `deny`, `timeout` or `error`). Deleting the hook deletes them.

## Related

- [Overview](/docs/auth/overview): the rest of an environment's auth
- [Webhooks](/docs/server/webhooks): the events auth sends after an operation
- [Authentication](/docs/backend/authentication): the token, and its claims, in a backend
- [CLI reference](/docs/cli/reference#palbase-authhookscreate): `auth:hooks:create` and its flags



<!-- ===== auth/audit ===== -->

# Audit Trail

Auth records what happens in it as events: sign-ins that worked and ones that did not, sign-ups, password and email changes, second factors, sessions and tokens, and every change made with the secret key, to a user or to the settings. Each event names who acted, from which address, what it was done to, and whether it worked. Events are chained: each carries a hash of itself and of the one before it, so an event changed, removed or put out of order breaks the chain where it happened, and verifying the trail finds it.

## Reading it

Studio's **Auth › Audit** shows the latest 100 events with a chart of failed sign-ins per day (the last 7, 30 or 90 days), filtered by result and searched by event, actor, target or metadata. An event's details hold its code, actor, target and metadata. A change made with a secret key is shown as **Admin (secret key)**.

```sh
palbase auth:audit
palbase auth:audit --event auth.login.failure --limit 200
```

`auth:audit` prints the events newest first: when, the event, the result, who, from where, and on what. From a server, `GET /admin/audit` pages through them (`limit` up to 100, `cursor`, `event_type`).

| Field | What it is |
|---|---|
| `event_type` | What happened, as a dotted name (below). |
| `result` | `success` or `failure`. |
| `actor` | `{ user_id, email?, ip? }`: the user who acted, or `service_role` for a call made with a secret key. |
| `target_type`, `target_id` | What it was done to: a user, a session, a setting. |
| `auth_method` | How the user signed in, for a sign-in. |
| `risk_score` | The score the [risk engine](/docs/auth/overview#risk) gave, when it scored. |
| `metadata` | What else the event says: a failure's reason, the setting that changed. |
| `event_hash`, `prev_hash` | Its place in the chain. |

The actor and the metadata are kept encrypted. When a user is deleted, their part of the record stays in the chain, and its actor and metadata can no longer be read.

### Event types

| Kind | Types |
|---|---|
| Signing up and in | `auth.signup`, `auth.login.success`, `auth.login.failure`, `auth.social.login`, `auth.magic_link.request`, `auth.magic_link.verify`, `auth.phone.signup`, `auth.phone.login`, `sms.otp.send`, `webauthn.login`, `auth.step_up.success`, `auth.step_up.failure` |
| Passwords and addresses | `auth.password.change`, `auth.password.reset.request`, `auth.password.reset.complete`, `auth.email.verify` |
| Second factors and passkeys | `mfa.enroll`, `mfa.remove`, `mfa.verify.success`, `mfa.verify.failure`, `mfa.recovery.used`, `webauthn.register`, `webauthn.remove`, `webauthn.clone_detected` |
| Linked providers | `social.link`, `social.unlink` |
| Sessions and tokens | `session.create`, `session.revoke`, `session.device_change`, `token.issue`, `token.refresh`, `token.revoke`, `trusted_device.register`, `trusted_device.used`, `trusted_device.revoke` |
| With the secret key | `admin.user.create`, `admin.user.update`, `admin.user.delete`, `admin.user.import`, `admin.user.deactivate_inactive`, `admin.mfa.reset`, `admin.config.change`, `admin.key.rotate`, `admin.audit.export` |
| Abuse and breaches | `bot.pow.challenge`, `bot.stuffing.detected`, `bot.ip.blocked`, `breach.detected`, `breach.forced_reset` |
| Personal data | `gdpr.export`, `gdpr.erasure`, `gdpr.consent.revoke` |
| Service accounts | `serviceaccount.create`, `serviceaccount.rotate`, `serviceaccount.revoke` |

`--event` and `event_type` take one type exactly.

## Exporting it

```sh
palbase auth:audit:export --out audit.ndjson
palbase auth:audit:export --format csv --from 2026-10-01T00:00:00Z --to 2026-11-01T00:00:00Z --out october.csv
palbase auth:audit:export --event admin.config.change --out config-changes.ndjson
```

The export is the whole trail, or the span `--from` (inclusive) to `--to` (exclusive), oldest first: JSON lines, an event a line in the shape above, or CSV. Its size is not limited. The file `--out` writes is readable by you alone. An export that fails halfway breaks off rather than ending as if it were whole, and the export is itself recorded (`admin.audit.export`). The admin call is `GET /admin/audit/export`, with `format`, `from`, `to` and `event_type`.

## Verifying it

```sh
palbase auth:audit:verify
```

```text
The audit trail is whole: 18342 events, each chained to the one before.
```

`auth:audit:verify` (`GET /admin/audit/verify`) computes every event's hash again and checks each link to the event before it, oldest first. A trail that is not whole is an error naming the first event where the chain breaks, and the command exits with `audit_trail_broken`: there, an event was changed or taken out. The answer of the admin call is `{ valid, total, broken_at? }`.

## Related

- [Users & Roles](/docs/auth/users): the changes a user's record shows
- [Overview](/docs/auth/overview): the settings `admin.config.change` records
- [Logs](/docs/getting-started/logs): every request to the environment, and auth's events among them
- [CLI reference](/docs/cli/reference#palbase-authaudit): `auth:audit`, `auth:audit:export`, `auth:audit:verify`



<!-- ===== auth/openid-provider ===== -->

# OpenID Provider

Every environment is an OAuth 2.0 authorization server and OpenID Connect provider for its own users. Another app (a partner's site, a CLI, a TV app, a tool of your own) signs a person in with their account in your app, the way apps offer "Sign in with Google", and gets an access token and an ID token for them. You register each such app as an **OAuth client** of the environment. This is not how your own app signs its users in: that is [Web Auth](/docs/web/auth).

The provider's issuer is the project's address, and everything about it is in its discovery document:

```text
https://<ref>.palbase.studio/.well-known/openid-configuration
```

| Endpoint | What it is |
|---|---|
| `GET /oauth/authorize` | The authorization endpoint: the browser leg of the authorization code flow, with PKCE (`S256`). |
| `POST /oauth/token` | Tokens for the grants `authorization_code`, `refresh_token`, `client_credentials` and `urn:ietf:params:oauth:grant-type:device_code`. |
| `POST /oauth/par` | Pushed authorization requests (RFC 9126). |
| `POST /oauth/device` | Device authorization (RFC 8628). |
| `GET /oauth/userinfo` | The claims of the token's scopes: `sub`, `email`, `email_verified`, `name`, `preferred_username`. |
| `POST /oauth/introspect` | Introspection (RFC 7662), for the secret key or a confidential client. |
| `POST /oauth/revoke` | Revocation (RFC 7009). |
| `GET /oauth/logout` | RP-initiated logout, with `id_token_hint` and a registered `post_logout_redirect_uri`. |
| `GET /.well-known/jwks.json` | The keys tokens are signed with ([Signing keys](/docs/auth/overview#signing-keys)). |

A client talks to these with its own credentials, never with a Palbase key. The scopes are `openid`, `profile`, `email` and `offline_access`.

## Registering a client

```sh
# A web app with a server: a confidential client, its secret printed once.
palbase auth:oauth-clients:create "Partner Portal" --redirect-uri https://partner.example.com/callback --grant authorization_code --grant refresh_token

# A CLI or a mobile app: a public client, with no secret, signing in with PKCE.
palbase auth:oauth-clients:create "Acme CLI" --public --redirect-uri http://127.0.0.1:8976/callback

palbase auth:oauth-clients:list
palbase auth:oauth-clients:delete oidc_7f3a…
```

| Flag | What it says |
|---|---|
| `--public` | A public client (a CLI, a mobile app, a single-page app) has no secret. Without it the client is confidential, and its secret is printed this once. |
| `--redirect-uri` | Where the browser may be sent back with the code; repeat it for several. `https`, or, for a public client, its own scheme or `http` on the loopback address. |
| `--grant` | `authorization_code` (the default), `refresh_token`, `client_credentials`, `urn:ietf:params:oauth:grant-type:device_code`. |
| `--scope` | What it may ask for; `openid`, `profile` and `email` by default. |
| `--client-id` | A `client_id` of your choosing, kept as it is; a random `oidc_…` one by default. |

The admin calls hold more: `POST /admin/oauth-clients` takes `token_endpoint_auth_method` (`client_secret_basic`, the default for a confidential client, `client_secret_post`, `private_key_jwt` with the client's `jwks`, or `none` for a public one), `post_logout_redirect_uris`, `id_token_lifetime_secs` (3600 by default) and `dpop_bound_access_tokens` (every token request proves a key, RFC 9449). `PATCH /admin/oauth-clients/{id}` changes any of them but whether the client is public. A secret client can move to `private_key_jwt`, giving up its secret, and never back.

## Its sign-in page

The provider has no sign-in page of its own: the person signs in on a page of yours, which you name in the auth settings.

```sh
palbase auth:settings:set oauth_login_url=https://app.example.com/oauth/login
```

Without it, `/oauth/authorize` refuses: there is nowhere to sign the person in. With it, the flow is:

1. The client sends the browser to `GET /oauth/authorize` with its `client_id`, `redirect_uri`, `scope`, `state` and PKCE challenge.
2. The provider sends the browser to your page with `?auth_request_id=…`.
3. Your page signs the person in with `POST /auth/login`, sending the `auth_request_id` with the email and password. The answer's `oidc_callback_url` is where the browser goes next.
4. From there, the provider sends the browser back to the client's `redirect_uri` with the `code`, the `state` and the issuer (`iss`). The client exchanges the code at `POST /oauth/token`.

```ts
// src/lib/palbase.ts
import { createClient } from "palbase/web";

export const pb = createClient({ url: "https://k3xq81w4m.palbase.studio", publishableKey: "pb_k3xq81w4m_cZ8yX7wV6uT5" });
```

```ts
// src/oauth-login.ts
import { pb } from "./lib/palbase";

/** The form on https://app.example.com/oauth/login?auth_request_id=… */
export async function signInForClient(email: string, password: string): Promise<string> {
  const authRequestId = new URLSearchParams(window.location.search).get("auth_request_id") ?? "";
  const { data } = await pb.auth.api.login({ body: { email, password, auth_request_id: authRequestId } });
  if ("mfa_required" in data) return "This account signs in with a second factor, which this page does not complete.";
  if (data.oidc_callback_url) window.location.assign(data.oidc_callback_url);
  return "Signed in";
}
```

The request is completed by a password sign-in: a sign-in that answers `mfa_required` does not complete it.

## Signing in a device

A device with no keyboard, a TV or a terminal, signs in with the device flow, when its client has the `urn:ietf:params:oauth:grant-type:device_code` grant:

1. The device calls `POST /oauth/device` with its `client_id`, and shows the person the `user_code` it is answered.
2. The person opens a page of your app on their phone or computer, signed in, and enters the code. The page shows what asked (`GET /auth/device/requests/{user_code}`: the client's name, the address and user agent it asked from) and approves or denies it (`POST /auth/device/verify`).
3. The device polls `POST /oauth/token` with its `device_code` every `interval` seconds; until the person decides, the answer is `authorization_pending`.

Auth has no approval page to show: the `verification_uri` it answers is its own, and answers JSON. Show the person your page's address.

```ts
// src/device.ts
import { pb } from "./lib/palbase";

/** What the approval page shows before the person decides: a code someone else sent names a device they do not know. */
export async function describeDevice(userCode: string): Promise<string> {
  const { data } = await pb.auth.api.devicePendingRequest({ path: { user_code: userCode } });
  return `${data.client_name}, from ${data.ip ?? "an unknown address"} (${data.user_agent ?? "unknown device"})`;
}

export async function decideDevice(userCode: string, approve: boolean): Promise<void> {
  await pb.auth.api.deviceVerifySubmit({ body: { user_code: userCode, action: approve ? "approve" : "deny" } });
}
```

The [blocking hooks](/docs/auth/hooks) `before.device_grant.initiate` and `before.device_grant.authorize` can refuse either step.

## FAPI 2.0

```sh
palbase auth:settings:set fapi_enabled=true
```

`fapi_enabled` holds the provider to the FAPI 2.0 Security Profile, for clients that need it (open banking, payments): an authorization request is taken only as a push (`POST /oauth/par`) and names its `redirect_uri`, PKCE is `S256`, clients are confidential and authenticate with `private_key_jwt`, every token is DPoP-bound, access tokens live five minutes at most, refresh tokens are not rotated, and the device flow is off.

## Service accounts

A service account is a machine's identity in the environment: a `client_id` and a secret, for `grant_type=client_credentials` at `POST /oauth/token`. Its token has no user and no session behind it: a `palbase/backend` route refuses it, since its routes take users. It is for services of your own that verify it against the key set or with `POST /oauth/introspect`.

| Admin call | What it does |
|---|---|
| `POST /admin/service-accounts` | `{ name, scopes?, credential_ttl_days? }`: makes one, and answers its `client_secret` once. |
| `GET /admin/service-accounts`, `GET /admin/service-accounts/{id}` | Lists them, reads one; never the secret. |
| `POST /admin/service-accounts/{id}/rotate` | A new secret, answered once. The old one keeps working for 30 seconds, so a deployment can switch. |
| `DELETE /admin/service-accounts/{id}` | Revokes it at once: its secrets stop working and no token is issued to it again. |

`credential_ttl_days` (1 to 3650) is how long a secret lives before the account must be rotated; without it a secret does not expire.

## Signing in with your own server

When your server decides who a person is in a way of its own (an employee directory, a game console's account, a sign-in your company already has), it can sign them in to the environment as one of its users. The user must exist: make them first with `POST /admin/users`, or [import](/docs/auth/users#bringing-users-over) them.

1. Your server mints a custom token for the user: `POST /admin/token/custom` with the secret key, `{ user_id, expires_in? }` (at most an hour, the default).
2. It hands the token to the app, which exchanges it for a session at `POST /auth/token/exchange` (`{ custom_token }`).

The token is good once (`401 token_used` a second time); a banned user's is refused (`403 user_banned`).

```ts
// server/sign-in-as.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

/** After your own check of who they are: a token the app trades for their session. */
export async function customTokenFor(userId: string): Promise<string> {
  const { data } = await palbase.auth.adminCreateCustomToken({ body: { user_id: userId, expires_in: 300 } });
  return data.custom_token;
}
```

```ts
// src/exchange.ts
import { pb } from "./lib/palbase";

export async function signInWith(customToken: string): Promise<string> {
  const { data } = await pb.auth.api.exchangeCustomToken({ body: { custom_token: customToken } });
  await pb.auth.setSession({ access_token: data.access_token, refresh_token: data.refresh_token, expires_in: data.expires_in });
  return data.user.id;
}
```

## Related

- [Overview](/docs/auth/overview): the auth settings and signing keys
- [Blocking Hooks](/docs/auth/hooks): approving a sign-in, a token or a device from your own code
- [Audit Trail](/docs/auth/audit): `token.issue`, `serviceaccount.*` and the rest
- [CLI reference](/docs/cli/reference#palbase-authoauth-clientscreate): `auth:oauth-clients:create` and its flags



<!-- ===== purchases/overview ===== -->

# Purchases

Every project has a purchases module. It holds **one catalog** of what the app sells — subscriptions, one-time products, packs of credits — sold in the **App Store**, on **Google Play** and on the **web** through the environment's own Stripe account. And it gives **one answer** to "what does this customer have", whatever store they bought in: a Pro bought on the web is Pro in the iOS app.

Apps buy with each store's own machinery — StoreKit on iOS, Play Billing on Android, Stripe Checkout on the web — through Palbase's SDKs. Palbase verifies every purchase with the store, keeps it in the project's **ledger**, and keeps each customer's entitlements, credits and quotas current: in the apps, live, and on your server, by a read or an event.

## Quick example

The app hears what the signed-in customer has, and sends them to buy on the web:

```ts
// app/pro.ts
import { createClient } from "palbase/web";

const pb = createClient({ url: "https://<ref>.palbase.studio", publishableKey: "pb_<ref>_c…" });

// Told now, and again whenever it changes: a purchase in any store, a renewal, a refund.
pb.purchases.onCustomerInfo((info) => {
  const pro = info?.entitlements["pro"]?.active === true;
  document.body.classList.toggle("pro", pro);
});

export async function buyYearly(): Promise<void> {
  const url = await pb.purchases.checkout({
    product: "pro",
    plan: "yearly",
    successUrl: "https://app.example.com/thanks",
    cancelUrl: "https://app.example.com/pricing",
  });
  location.assign(url); // Stripe Checkout
}
```

The server checks the entitlement where the content is served, with the secret key:

```ts
// server/pro.ts
import { createServer, isEntitled } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

export async function isPro(userId: string): Promise<boolean> {
  // A user who has bought nothing reads as a customer with nothing.
  const { data } = await palbase.purchases.getCustomer({ path: { customer_id: userId } });
  return isEntitled(data, "pro");
}
```

## The parts

| | What it is |
|---|---|
| **Catalog** | The project's one definition of what it sells, saved in revisions: each product once, with its kind, its plans and prices, its name in each language, the channels it is sold on (`ios`, `android`, `web`) and what it gives. See [Catalog](/docs/purchases/catalog). |
| **Product** | One thing sold: a `subscription` (renews until canceled), a `non_consumable` (bought once, kept), a `consumable` (bought again and again, for credits) or a `non_renewing` period. |
| **Plan** | How a product is paid for: a subscription's period and price (`monthly`, `yearly`), or the one price of anything else. The stores know a plan as `<product>.<plan>`. |
| **Entitlement** | Something a customer has or not: `pro`. Products give entitlements, and apps and servers check entitlements — never products — so a plan can change without the checks changing. |
| **Credits** | A balance the customer spends: `tokens`. A consumable gives them per purchase, a subscription per period. |
| **Limit** | A quota counted in a window: `ai_requests` a month, with a free tier, and what each product gives on top. |
| **Offerings** | The catalog as a paywall shows it: each channel's text and price, and the id each store sells a plan by. Any of the project's keys reads it. |
| **Customer** | A user of the project, a guest included: the customer's id is the user's id. What they have is **`CustomerInfo`**: each entitlement (on or off, until when, whether it renews, which store gives it), their subscriptions and one-time purchases, credit balances and quota use. |
| **Paywall**, **placement** | What an app draws to sell the catalog, designed in Studio and published without an app update; a placement is the place in the app that shows one. See [Paywalls](/docs/purchases/paywalls). |
| **Offer**, **coupon** | A discount, a longer free trial or a grant, for an audience or everyone, once a customer; a coupon is a code that opens one. See [Offers & Coupons](/docs/purchases/offers). |

## The stores

| Channel | Store | The app buys with | The environment needs | Page |
|---|---|---|---|---|
| `ios` | The App Store | StoreKit 2, through `PalbasePurchases` | An In-App Purchase key; an App Store Connect API key to write the catalog | [App Store](/docs/purchases/app-store) |
| `android` | Google Play | Play Billing, through `palbase-purchases` | A service account your Play Console invites, and the app's notifications topic in Play Console | [Google Play](/docs/purchases/google-play) |
| `web` | Stripe | Stripe Checkout, through `pb.purchases.checkout()` | The environment's own Stripe account | [Connect Stripe](/docs/purchases/connect-stripe), [Web](/docs/purchases/web) |

Each environment connects its own stores: `staging` can sell through Stripe's test mode while `production` takes live payments.

## How a purchase becomes access

1. **The app buys**, naming the customer to the store: StoreKit with the customer's `appAccountToken`, Play Billing with their obfuscated account id, Checkout with the customer's session. The SDKs do this; nothing personal goes to Apple or Google.
2. **The purchase reaches Palbase.** The iOS and Android apps report what the store gave them; Stripe reports its own. Nothing is taken on the device's word: an App Store transaction is checked against Apple's signature and the subscription read from Apple with the environment's key, a Play purchase is read from Play by its token, a Stripe object is read again from Stripe.
3. **The ledger applies it**, and the customer's entitlements, credits and quotas follow. A Google Play purchase is acknowledged once the ledger has it — the SDK never does.
4. **Everyone hears it.** The customer's apps are told at once (each customer has a realtime channel of their own, `purchases:<ref>:<user id>`, read-only), and your backend receives `purchases.*` events.
5. **The stores keep it current.** Apple's App Store Server Notifications, Google Play's real-time developer notifications and Stripe's events bring renewals, cancellations, billing issues and refunds into the ledger, with the app closed.

An entitlement already on from one store is not sold again in another: the iOS and Android SDKs answer `alreadyEntitled` without opening the store, and a web checkout is refused (`409 already_entitled`), naming the store it is managed in. A free trial is given once per customer, across every channel.

## Who calls what

| Caller | Key | What it does |
|---|---|---|
| A customer's app | The publishable key and the user's session (a guest's too) | Reads the offerings and a placement's paywall; reads what the customer has (`GET /purchases/me`); buys, reports, restores; redeems web purchases and coupons; takes offers; opens the Stripe portal; moves a guest's purchases to an account. |
| Your server | A secret key | Everything else: the catalog and its plans, the stores' connections, every customer, grants, credits and limits, paywalls, placements and experiments, offers' figures and coupons, charts, settings. |
| The stores | None: each signs its own | Their notifications, at the environment's own address. |

In a `palbase/backend` app the module is `Palbase.purchases`; from any other server it is `createServer({ url, secretKey }).purchases` — the same client, generated from the purchases contract, one method per operation (`GET /purchases/customers/{customer_id}` is `getCustomer`).

## Test purchases

Purchases nobody pays for are **test purchases**: the App Store's sandbox (where TestFlight and App Review buy), Xcode's StoreKit Testing, Google Play's license testers and Stripe's test mode. Each is marked `is_sandbox` — in what the customer has and in the purchase events — and the environment's settings say whether they open entitlements: for **everyone** (the default), only for customers on an allowlist, or for **nobody**. App Review buys in the sandbox: on the environment a build in review uses, a test purchase that opens nothing gets the app rejected. See [Customers](/docs/purchases/customers#settings).

Test the iOS side end to end with [Test Apple Purchases](/docs/purchases/testing-apple).

## Setting up, in order

1. **Write the catalog** — in Studio, **Purchases › Catalog**, or as a file with `palbase purchases:catalog:put`. [Catalog](/docs/purchases/catalog)
2. **Connect the stores you sell in** — the [App Store](/docs/purchases/app-store), [Google Play](/docs/purchases/google-play), [Stripe](/docs/purchases/connect-stripe).
3. **Bring the stores to the catalog** — plan it, read what each store will get, and confirm: `palbase purchases:catalog:plan`, then `palbase purchases:catalog:confirm`. Palbase creates the products and prices in each store.
4. **Buy from the apps** — [iOS](/docs/ios/purchases), [Android](/docs/android/purchases), [the web](/docs/purchases/web).
5. **Check access where the content is served** — [Entitlements, Credits & Limits](/docs/purchases/entitlements).
6. When the app needs them: [paywalls](/docs/purchases/paywalls) designed in Studio, [offers and coupons](/docs/purchases/offers), and [charts](/docs/purchases/charts) of what sold.

## In Studio

Each environment's **Purchases** has these screens:

| Screen | What it does |
|---|---|
| **Catalog** | The products, each with its plans, text, channels and what it gives. |
| **Stores** | The Stripe account, Google Play purchases, and the plans that bring the stores to the catalog, each store's part shown before you confirm it. |
| **App Store** | The In-App Purchase key, what selling in the App Store still needs, Xcode's test purchases and the team's sandbox testers. |
| **Paywalls** | The paywalls, their drafts and versions, and the placements that show them, with their targeting rules. |
| **Experiments** | Paywalls tried against each other on a placement, and which sells best. |
| **Offers**, **Coupons** | The catalog's discounts, trials and grants, and the codes that open them. |
| **Charts** | Revenue, subscriptions, conversion and retention, from the ledger. |
| **Customers** | What a customer has, from every store; an entitlement or credits given, saying why. |
| **Settings** | What test purchases open, a deleted user's web subscriptions, the quotas' time zone, and how charts count money. |

## The CLI

The `purchases` commands cover the catalog, the stores' connections, paywalls, placements, experiments, charts and customers; the `stores` commands connect the App Store Connect and Google Play accounts the catalog is written with. Every one is in the [CLI reference](/docs/cli/reference#purchases).

## Related

- [Catalog](/docs/purchases/catalog) · [App Store](/docs/purchases/app-store) · [Google Play](/docs/purchases/google-play) · [Connect Stripe](/docs/purchases/connect-stripe) · [Web](/docs/purchases/web)
- [Paywalls](/docs/purchases/paywalls) · [Offers & Coupons](/docs/purchases/offers)
- [Entitlements, Credits & Limits](/docs/purchases/entitlements) · [Customers](/docs/purchases/customers) · [Charts](/docs/purchases/charts)
- [Test Apple Purchases](/docs/purchases/testing-apple)



<!-- ===== purchases/catalog ===== -->

# Catalog

The catalog is the project's one definition of what it sells. Each product is written **once** — its kind, its plans and prices, its name in each language, the channels it is sold on and what it gives — and each channel adds only what is its own there: the App Store's shorter name, a web price without the stores' commission.

It is one JSON document, saved in **revisions**. Edit it in Studio (**Purchases › Catalog**) or keep it as a file in your repository and save it with the CLI. Saving a revision writes nothing to a store: a **plan** brings the App Store, Google Play and Stripe to it, store by store, after you have read what each will get and confirmed it.

Each environment has its own catalog.

## Quick example

A subscription sold on all three channels, and a pack of credits sold in the App Store and on the web:

```json
{
  "base_locale": "en",
  "entitlements": [{ "key": "pro", "name": "Pro" }],
  "credits": [{ "key": "tokens", "name": "Tokens", "low_at": 10 }],
  "limits": [{ "key": "ai_requests", "name": "AI requests", "window": "calendar_month", "free": 10 }],
  "products": [
    {
      "key": "pro",
      "type": "subscription",
      "group": "membership",
      "tier": 1,
      "locales": {
        "en": { "name": "Pro", "description": "Everything, every month" },
        "tr": { "name": "Pro", "description": "Her şey, her ay" }
      },
      "plans": [
        { "key": "monthly", "period": "P1M", "price": { "currency": "USD", "amount": 999 }, "intro": { "mode": "free_trial", "duration": "P1W" } },
        { "key": "yearly", "period": "P1Y", "price": { "currency": "USD", "amount": 7999 } }
      ],
      "channels": {
        "ios": { "family_shareable": true },
        "android": { "locales": { "en": { "benefits": ["No ads", "Every feature"] } } },
        "web": { "prices": { "monthly": { "currency": "USD", "amount": 799 } } }
      },
      "entitlements": ["pro"],
      "credits": { "currency": "tokens", "amount": 100, "rollover": "none" },
      "quota": [{ "limit": "ai_requests", "max": 500 }]
    },
    {
      "key": "tokens_100",
      "type": "consumable",
      "locales": { "en": { "name": "100 tokens", "description": "A pack of tokens" } },
      "plans": [{ "key": "once", "price": { "currency": "USD", "amount": 499 } }],
      "channels": { "ios": {}, "web": {} },
      "credits": { "currency": "tokens", "amount": 100 }
    }
  ]
}
```

`pro` gives the `pro` entitlement, 100 tokens each period and 500 AI requests a month; on the web its monthly plan costs 7.99 instead of 9.99. `tokens_100` gives 100 tokens each time it is bought.

## The catalog as a file

```sh
palbase purchases:catalog:get --out catalog.json -E staging
```

It writes the newest revision and prints its number. Edit the file, then check it and save it on the revision it was edited from:

```sh
palbase purchases:catalog:validate --file catalog.json -E staging
palbase purchases:catalog:put --file catalog.json --revision 3 -E staging
```

`validate` lists every problem with its path in the file (`products[0].channels.ios.locales.en.name`) and the store whose rule it breaks; it saves nothing. `put` checks the same way and saves nothing when a problem is left (`422 invalid_catalog`, every problem listed); a **warning** — something a store goes without — does not stop it. Of two people editing at once, the second is told the catalog moved past the revision they edited (`412 catalog_changed`) and nothing is saved over the first: read it again, make the edit on it, save that. The first save is on revision `0`.

Each environment's catalog is its own. To give `production` what `staging` has, get it from one and put it on the other's revision:

```sh
palbase purchases:catalog:get --out catalog.json -E staging
palbase purchases:catalog:get -E production   # prints production's revision
palbase purchases:catalog:put --file catalog.json --revision 7 -E production
```

## Revisions, and putting one back

Every revision is kept. **Purchases › Catalog › Revisions** lists them, the newest first — who saved each, when, what it defines, and when a confirmed plan of it was written to the stores — and opens any of them. **Put this revision back** saves an older revision's catalog as the next revision, the way an edit is saved: on the revision on screen (`If-Match`; `412 catalog_changed` when someone saved since), checked against the catalog's rules today (an older revision may break one added since: `422 invalid_catalog`, every problem listed), and keeping what customers bought. Nothing is written to a store until a plan of the new revision is made and confirmed, as for any edit.

```sh
palbase purchases:catalog:revisions -E production
palbase purchases:catalog:revision 4 --out catalog-4.json -E production
palbase purchases:catalog:restore 4 -E production   # saved as the next revision
palbase purchases:catalog:plan -E production        # then the stores
```

From a server: `GET /purchases/catalog/revisions` (`next_cursor`, sent back as `cursor`, is the next page), `GET /purchases/catalog/revisions/{revision}` and `POST /purchases/catalog/revisions/{revision}/restore` with `If-Match`.

A saved revision emits `purchases.catalog.changed`; one put back says which it came from (`restored_from`). See [`purchases:catalog:get`](/docs/cli/reference#palbase-purchasescatalogget), [`purchases:catalog:put`](/docs/cli/reference#palbase-purchasescatalogput) and [`purchases:catalog:validate`](/docs/cli/reference#palbase-purchasescatalogvalidate).

## Bringing the stores to the catalog

A plan is what writing the newest revision to each store takes, worked out before anything is written:

```sh
palbase purchases:catalog:plan -E staging
```

It prints each store's part, step by step, and the plan's **hash**. Read it, then write it by naming that hash:

```sh
palbase purchases:catalog:confirm <plan id> --hash <hash> -E staging
```

The CLI shows what will be written and asks first, in every environment (`-y` confirms without asking); `palbase purchases:catalog:decline <plan id>` drops a plan unwritten. In Studio, **Purchases › Stores › Apply the catalog** plans it, shows each store's part, and writes it when you confirm.

| Store | What its part writes | What to know |
|---|---|---|
| Stripe | A product for each web product, a price for each plan, on the environment's [Stripe account](/docs/purchases/connect-stripe) — written as you confirm. | A Stripe price never changes: a new amount is a new price, which takes over the plan's lookup key, while customers on the old one keep paying it. |
| The App Store | A subscription group for each group, a subscription or an in-app purchase for each plan, with its text, price and introductory offer — written to App Store Connect with the environment's [App Store Connect API key](/docs/purchases/app-store#connect-the-app-store). | The price is the App Store's price point nearest to it in the currency's storefront; Apple prices the other storefronts. A product id, once made, is never free again. |
| Google Play | A subscription for each subscription product, with a base plan for each plan, and a one-time product for each other product — written for the app [Google Play purchases](/docs/purchases/google-play) are connected for. | Google converts the price to every region. A product id, once made, stays Google's. |

The plan's hash is its Stripe part's; with no Stripe account connected, its App Store part's; with neither, its Google Play part's. A plan is written only as it was shown: once the catalog is saved again, an older plan goes **stale** and is refused, and you plan again.

A plan writes only what changed since a store last took the catalog: a product it already has gets an update step with its new text, price or review details, and a product that did not change has no step. The App Store gives a subscription its new price from the day after tomorrow (UTC) on, in every storefront — App Store Connect schedules a price change a day or two ahead — and its subscribers keep the price they pay; an in-app purchase gets its new price at once; Google Play gives a base plan its new price for new subscribers. A language a store has that the catalog does not is left there. When a store did not answer a confirmed plan written — it stopped part way, or has not answered yet — what it holds of that plan's products is not known: the next plan writes each of them again, all of it, whatever changed.

The Stripe part is written as you confirm: the plan is **applied**, with what the account holds now, or **failed**, with what Stripe said — a new plan picks up where it stopped. The App Store and Google Play parts are written after the answer: the plan in Studio, and `palbase purchases:catalog:plan <plan id>`, show what App Store Connect and Google Play hold once they have answered — each product's state, its price, and a subscription's new price with the day it starts — and `palbase purchases:doctor` says when App Store Connect took its part. From the confirmation on, a purchase of what the plan sells maps to the catalog's product and plan. Each store's answer emits `purchases.catalog.applied`.

| Status | Means |
|---|---|
| `planned` | Shown, waiting to be confirmed or declined. |
| `applying` | Confirmed; a store's part is being written. |
| `applied` | Written. |
| `failed` | A store refused a step; plan again. |
| `stale` | The catalog was saved since: plan again. |
| `declined` | Never written. |

### What the stores know a plan by

| Store | Id |
|---|---|
| The App Store | `<product>.<plan>` (`pro.monthly`), each plan a product of its own; the group's reference name is the group's key. |
| Google Play | The product's key (`pro`) and, for a subscription, the plan's key as its base plan, `_` written `-` (`pro` / `monthly`). |
| Stripe | The price's lookup key `palbase:<ref>:<product>.<plan>`. The ref keeps two environments that share a Stripe account apart. |

`<product>.<plan>` is 40 characters at most.

### Products a store already sells

A product you made in App Store Connect or the Play Console, by hand or with another tool, joins the catalog by its id: give its plan the store's id under `store_ids`, and the plan **links** it — nothing is made or changed at the store.

```json
"channels": {
  "ios": { "store_ids": { "monthly": { "product": "com.acme.app.pro.monthly" } } },
  "android": { "store_ids": { "monthly": { "product": "pro_sub", "base_plan": "monthly-1" } } }
}
```

In Studio, a product's **iOS** and **Android** tabs hold these ids under **Sold at App Store Connect already** and **Sold at the Play Console already**. On Google Play a subscription's plans are base plans of one product: map every plan of it, to the same product. Once the plan is confirmed, the purchases made before the catalog knew the product open what the catalog gives, and their buyers hear `purchases.entitlement.changed`. A store id stays once a plan linked it: a catalog that leaves it out is refused (`store_id_kept`), because the next plan would make a second product at the store.

### What a customer bought stays

A product, a plan, an entitlement or a credit that someone holds cannot leave the catalog, and changing a key is leaving it: the save is refused (`product_has_buyers`, `plan_has_buyers`, `entitlement_has_holders`, `credit_has_holders`, `limit_has_holders`). A product a confirmed plan wrote to a store stays too (`product_at_store`): the store keeps selling it, to an older build of your app or from its own resubscribe button. To stop selling one, retire it: `"retired": true` on the product or on a plan — in Studio, the product's **On sale** switch, or a plan's **Off sale** box. A retired product is not offered, not sold on the web, not given an offer, and no plan writes it to a store, while everyone who bought it keeps what it gives. Renaming it keeps their access; it is the key that counts.

What a store never changes of a product it sells stays as it was made: its type, its subscription group and a plan's period (`store_terms_fixed`). Retire it and make a new one instead.

## The document

Unknown fields are refused: the catalog is read strictly.

| Field | What it is |
|---|---|
| `base_locale` | The language every product names itself in (`en`, `pt-BR`); the others are translations. Stripe keeps one name: this one's. |
| `entitlements` | What a customer has or not: each a `key` and a `name`. |
| `credits` | The kinds of credit the project counts: each a `key`, a `name`, and `low_at`, the balance under which your backend hears `purchases.credits.low`. |
| `limits` | The metered quotas: each a `key`, a `name`, a `window` and `free`, what a customer gets with nothing that gives more. `overflow` (`{ "currency": "tokens", "per_unit": 2 }`) spends credits past the limit instead of refusing. |
| `products` | The products (below). |
| `offers` | Discounts, trials and grants for a while: see [Offers & Coupons](/docs/purchases/offers). |

A key is lowercase letters, digits and `_`, starting with a letter, 40 at most.

A limit's `window` is `calendar_month` or `calendar_day` — from midnight in the project's time zone ([settings](/docs/purchases/customers#settings)) — or `billing_period`: the period of the subscription that gives it, a calendar month without one.

### A product

| Field | What it is |
|---|---|
| `key` | Its key. |
| `type` | `subscription` (renews until canceled), `non_consumable` (bought once, kept), `consumable` (bought again and again: it gives credits) or `non_renewing` (a period bought once). |
| `locales` | Its `name` and `description` by language: the base locale's at least. |
| `plans` | How it is paid for (below): a subscription's plans, one plan for anything else. |
| `channels` | Where it is sold — `ios`, `android`, `web` — each with what is its own there; `{}` when it is sold there as it is. At least one. |
| `entitlements` | The entitlements it gives. A consumable gives none. |
| `credits` | The credits it gives: per purchase for a consumable, per period for a subscription — `{ "currency", "amount" }`, and for a subscription `rollover`: `none` (a period's credits end with it) or `all` (they stay). Credits bought never end. |
| `quota` | How much of each limit it gives in each window: `[{ "limit", "max" }]`. A customer holding several products gets the largest. |
| `group`, `tier` | A subscription's group — the subscriptions a customer moves between — and its level in it, 1 or more, higher is more. The App Store sells every subscription in a group. |
| `retired` | Off sale: [what a customer bought stays](#what-a-customer-bought-stays). A plan can be retired on its own. |

### A plan

| Field | What it is |
|---|---|
| `key` | Its key. |
| `price` | `{ "currency": "USD", "amount": 999 }`: the amount in the currency's minor units (999 is 9.99). Each store prices the other currencies its own way; `overrides` (`{ "EUR": 999 }`) sets amounts by hand. |
| `period` | A subscription's billing period, ISO 8601: `P1W`, `P1M`, `P2M`, `P3M`, `P6M`, `P1Y` in every store; Google Play also sells `P4W`, `P4M`, `P8M`; Stripe bills at most once a year. |
| `duration` | A non-renewing product's: how long it lasts (`P1M`). |
| `intro` | A subscription plan's introductory offer, once per customer across every channel: `mode` `free_trial`, `pay_as_you_go` (a `price` for a number of `periods`) or `pay_up_front` (one `price` for the whole `duration`; the web sells the plan without it). The App Store's free trials last `P3D`, `P1W`, `P2W`, `P1M`, `P2M`, `P3M`, `P6M` or `P1Y`. |

### A channel

| Field | Channel | What it is |
|---|---|---|
| `locales` | any | Its own text, field by field, where a store's limits call for it: `name`, `description`, and Google Play's `benefits`. |
| `prices` | any | Its own price for a plan, by the plan's key: a web price without the stores' commission. |
| `family_shareable` | `ios` | Family Sharing for the purchase. |
| `review` | `ios` | What App Review sees: a `note` and the `screenshot` of the product in the app. |
| `store_ids` | `ios`, `android` | The store's own ids of the plans, by plan key: [products a store already sells](#products-a-store-already-sells). |
| `tax_code` | `web` | Stripe's tax code for the product. |

### Review screenshots

The App Store reviews every product with a screenshot and a note: without them the catalog warns (`review_missing`). Upload the screenshot, a PNG or JPEG at one of the App Store's screenshot sizes (1290x2796 for a 6.9-inch iPhone, 2064x2752 for a 13-inch iPad, or turned) — Apple fails any other size — and name it by the SHA-256 the command prints:

```sh
palbase stores:review-screenshot <app id> pro-paywall.png -E main
```

```json
"ios": { "review": { "screenshot": "sha256:9f86d081…", "note": "Settings → Pro" } }
```

In Studio, the product's **iOS** tab uploads it (**Review screenshot › Upload**) and names it for you. The next plan gives both to App Store Connect, and the product is then `READY_TO_SUBMIT`: it goes to App Review [with a version](/docs/distribution/app-store#send-it-to-app-review). A changed screenshot replaces Apple's.

## The stores' rules

`validate` checks each channel against its store, and a rule one store has is a problem on that channel alone — never a silent cut:

| Store | Its rules |
|---|---|
| The App Store | A name of 2 to 30 characters, a description of 45 at most; no emoji or symbols in a subscription's name; the six periods above; every subscription in a group. |
| Google Play | A name of 55 characters at most, a description of 200, 4 benefits of 40 characters each. |
| Stripe | A period of a year at most; a pay-up-front introductory offer is left out on the web (a warning). |

When the shared text is too long for one store, give that channel its own (`"ios": { "locales": { "en": { "name": "Pro Family" } } }`): the other channels keep the full text.

## Related

- [Purchases](/docs/purchases/overview): how the catalog, the stores and the customers fit together
- [Offers & Coupons](/docs/purchases/offers): the catalog's `offers`, and the codes that open them
- [Entitlements, Credits & Limits](/docs/purchases/entitlements): what the catalog's entitlements, credits and limits do for a customer
- [App Store](/docs/purchases/app-store) · [Google Play](/docs/purchases/google-play) · [Connect Stripe](/docs/purchases/connect-stripe)



<!-- ===== purchases/app-store ===== -->

# App Store

The catalog's `ios` products are sold in the App Store with StoreKit 2: the app buys through `PalbasePurchases`, Apple takes the payment, and the environment verifies each transaction with Apple and keeps it in the ledger. Apple's App Store Server Notifications bring renewals, cancellations, billing issues and refunds to the environment, with the app closed.

An environment that sells in the App Store holds two of Apple's keys:

| Key | Made in App Store Connect | What the environment does with it |
|---|---|---|
| **App Store Connect API key** | **Users and Access › Integrations › App Store Connect API**, role App Manager | Writes the catalog to App Store Connect, points the app's server notifications at the environment, and runs the readiness checks. It is the same key Studio's **App Distribution** connects, for TestFlight and releases. |
| **In-App Purchase key** | **Users and Access › Integrations › In-App Purchase** | Verifies the app's purchases, reads its subscriptions from Apple, and signs promotional offers. |

Each goes from your computer (or a page of the environment's) straight to the environment, never through Studio.

## Connect the App Store

**1. Register the iOS app** with its bundle in the environment, if it is not yet — [iOS SDK › Connect the app to the project](/docs/ios/overview#connect-the-app-to-the-project):

```sh
palbase apps:create ios "Shop" --slug shop --team-id ABCDE12345
palbase apps:env:set shop --bundle com.example.shop -E staging
```

**2. Connect the App Store Connect API key:**

```sh
palbase stores:apple:connect --key-file AuthKey_ABC123DEF4.p8 --issuer-id 57246542-96fe-1a63-e053-0824d011072a -E staging
```

**3. Connect the In-App Purchase key**, for the app:

```sh
palbase purchases:apple:connect --key-file SubscriptionKey_XYZ987WVU6.p8 --app shop -E staging
```

Apple is asked, with a call that changes nothing, whether it takes the key for the app; then the environment keeps it, and has App Store Connect send the app's notifications — sandbox and production — to the environment's address. The key's id is read from the file's name, and the issuer is the one step 2 connected. In Studio, **Purchases › App Store** connects it. `--print-link` prints a link that takes the key in a browser instead, once, for 30 minutes. A key connected again replaces the one before.

**4. Bring App Store Connect to the catalog:** plan the catalog and confirm it ([Catalog › Bringing the stores to the catalog](/docs/purchases/catalog#bringing-the-stores-to-the-catalog)). Your subscription groups, subscriptions and in-app purchases are created in App Store Connect, with their text, prices and introductory offers.

**5. Check what selling still needs:**

```sh
palbase purchases:doctor -E staging
```

Apple is asked now. Each line is one check — ✓ holds, ✗ does not, `i` only informs — with the command or the place in App Store Connect that fixes it, and the command exits 1 until every check that is not informational holds. Studio's **Purchases › App Store** shows the same list.

| Check | Holds when |
|---|---|
| The In-App Purchase key | Apple takes it for the app. |
| Where the App Store reports | App Store Connect sends the app's notifications to this environment. |
| The TEST notification | Apple's TEST notification arrived: the address works. |
| The catalog confirmed | The newest revision of the catalog was confirmed for the stores. |
| The catalog in App Store Connect | App Store Connect holds that revision's products, each step's error said when it does not. |
| Test purchases | Informs: what test purchases open here ([settings](/docs/purchases/customers#settings)). |
| Xcode's purchases | Informs: whether Xcode's StoreKit Testing purchases are taken ([Test Apple Purchases](/docs/purchases/testing-apple)). |

When the app's notifications already go to another server, the environment does not take them over: the check says so. Clear both addresses in App Store Connect (**Apps › the app › App Information › App Store Server Notifications**), then run `palbase purchases:apple:connect` again.

`palbase purchases:apple` shows the connection as it is: the app, the key's id, the app's Apple ID once known, and where the App Store reports — never the key.

## Buying in the app

The app links `PalbasePurchases`, and `PalbasePurchasesUI` for paywalls drawn natively. `pb.purchases.products()` returns the catalog's iOS plans as the App Store has them for this user; `purchase(_:)` buys one; `restore()` is the user's own "Restore purchases". The SDK names the customer to StoreKit with their `appAccountToken`, reports each transaction to the environment and finishes it only once the environment has it, and listens to StoreKit's updates for whoever is signed in — so a renewal, an approved Ask to Buy or an interrupted purchase is reported too. See [iOS › Purchases](/docs/ios/purchases), and [Test Apple Purchases](/docs/purchases/testing-apple) for the whole flow in Xcode and the sandbox.

When `products()` returns fewer products than the catalog sells on iOS, its `diagnosis` says which and the likely causes: a product not ready in App Store Connect, the Paid Apps agreement not active, a bundle id that is not the project's, a StoreKit configuration file that lacks them. `palbase purchases:doctor` checks each.

## What the environment does with a transaction

**It verifies it.** A transaction counts only as the App Store signed it, for the connected app, in the sandbox or production. A subscription's state is never taken from the device: it is read from Apple with the environment's key. One sent again applies nothing twice.

**It gives it to a customer.** A purchase nobody has is the customer's its `appAccountToken` names, or the reporting customer's; one another customer has stays theirs, unless one of two things moves it:

- **A new purchase on it** — a switch of plan, a resubscription, an offer bought — whose `appAccountToken` names another customer moves it to them, whoever reports it, the app or Apple's notification. On an Apple ID shared among the app's accounts (a family's iPhone), the subscription follows who paid, and so does the offer it was bought with. A purchase with no token, a renewal, and a transaction reported again or late move nothing.
- **A restore** moves a purchase to the restoring customer only from the device StoreKit signed it for, and never from an account to a guest.

A purchase moves at most 3 times in 30 days, restores and new purchases counted together. A restore, or a customer's own new purchase, that leaves a purchase where it was is refused with `403 restore_not_this_device`, `403 restore_account_owned` or `409 restore_limit`, after the rest of it is applied. A move emits `purchases.ownership.transferred`, whose `via` is `purchase` or `restore`.

**It follows Apple.** A notification about a purchase applies what Apple signed — the transaction, the renewal info, the subscription's status — and the newest by Apple's time is the state. A refund, a revoked Family Sharing purchase or a chargeback turns the entitlement off and takes back the credits it gave (`purchases.refund.changed`). A subscription the App Store could not renew keeps its access through Apple's grace period, with `billing_issue` on the entitlement.

**Production waits for the app's Apple ID.** Production purchases and notifications are taken once the app's Apple ID is known; the environment reads it when it sets the notification address.

## Offers and offer codes

A catalog offer on an iOS subscription is written to App Store Connect as a **promotional offer**, and the app buys with it — `purchase(_:offer:)` — under a signature the environment makes with the In-App Purchase key: no key is ever in the app. An **App Store offer code** is a coupon of Apple's, redeemed in the App Store's own sheet. See [Offers & Coupons](/docs/purchases/offers).

## Buying on the web from the iOS app

In the App Store's United States storefront, an app may link out to buy on the web beside In-App Purchase (App Review Guideline 3.1.1(a)). The SDK opens Stripe Checkout there for the signed-in customer and records the link with the checkout. See [Web › From a native app](/docs/purchases/web#from-a-native-app).

## Disconnecting

```sh
palbase purchases:apple:disconnect -E staging
```

The environment forgets the In-App Purchase key: the App Store's notifications and the app's reports are refused from then on, and purchases already made stay in the ledger. It emits `purchases.store.changed`, as connecting does.

## Related

- [Test Apple Purchases](/docs/purchases/testing-apple): buying before anyone pays, in Xcode and in the sandbox
- [iOS › Purchases](/docs/ios/purchases): `pb.purchases` in a Swift app
- [Catalog](/docs/purchases/catalog) · [Offers & Coupons](/docs/purchases/offers)
- [Entitlements, Credits & Limits](/docs/purchases/entitlements): checking access on your server
- CLI: [`purchases:apple:connect`](/docs/cli/reference#palbase-purchasesappleconnect), [`purchases:doctor`](/docs/cli/reference#palbase-purchasesdoctor), [`stores:apple:connect`](/docs/cli/reference#palbase-storesappleconnect)



<!-- ===== purchases/testing-apple ===== -->

# Test Apple Purchases

There are two ways to buy your app's products before anyone pays for them. Both use the catalog you already have, and Palbase writes nothing into your Xcode project.

| | A. In Xcode | B. In the App Store sandbox |
|---|---|---|
| What sells the product | Xcode, from a file made from your catalog | The App Store, with your products in App Store Connect |
| What you need from Apple | Nothing | A developer account, its agreements, two keys, a sandbox tester |
| Where it runs | Simulator or a device, run from Xcode | A device (or TestFlight) |
| Steps | **5**, about two minutes | **7**, the first time |
| Use it for | Building the paywall, every purchase flow, renewals in seconds | The last check before release: real App Store products, real server notifications |

Start with A. Move to B once your products are in App Store Connect.

Both run against a **test environment** of your project (`staging`, say), never the production one: production takes only purchases the App Store itself signed.

In Studio, **Purchases › App Store** shows the environment's In-App Purchase key, the readiness list, Xcode's certificate and the team's sandbox testers: each step below that has a command can be done there too.

## A. In Xcode, with no App Store (5 steps)

**1. Make the StoreKit file from your catalog.**

```sh
palbase purchases:storekit -E staging
```

It reads the environment's iOS offerings and writes one file, `palbase/environments/staging/<app>.storekit`: every iOS plan as the App Store product its store id names, with its text in each language the catalog has, its price, its subscription group and level, and its introductory offer. Nothing outside `palbase/` is written.

**2. Point the scheme at it.** In Xcode, **Product › Scheme › Edit Scheme… › Run › Options › StoreKit Configuration**, choose the file. If it is not listed, add it from that same menu.

**3. Save Xcode's certificate.** Select the `.storekit` file in the Project navigator, then **Editor › Save Public Certificate**. Purchases in this mode are signed by Xcode, not by Apple, with this certificate.

**4. Let the environment take Xcode's purchases.**

```sh
palbase purchases:apple:xcode-certificate ~/Desktop/StoreKitTestCertificate.cer -E staging
```

The environment now takes purchases signed with that certificate and records them as test purchases. Studio does the same under **Purchases › App Store › Xcode StoreKit Testing**. On the production environment both refuse.

**5. Run the app and buy.** Xcode shows its own payment sheet; no Apple account is asked for. The customer has the entitlement as soon as the app reports the purchase:

```sh
palbase purchases:customer:get <user id> -E staging
```

### When the catalog changes

Run `palbase purchases:storekit -E staging` again. The same catalog makes the same file. What you set from Xcode's **Editor** menu while the file is open (the storefront, the subscription renewal rate, Ask to Buy, an error to force) is kept.

The prices are in one storefront's currency: the price you entered, or the amount you set by hand for that currency. `--storefront DEU` makes the file for another storefront; a plan with no price in its currency keeps its own amount, and the command says which.

### Renewals, refunds and errors

- **Renewals in seconds:** open the `.storekit` file and choose **Editor › Subscription Renewal Rate**.
- **Refund, expire, cancel a purchase:** while the app runs, **Debug › StoreKit › Manage Transactions…**, select the transaction, then **Refund Purchase**. StoreKit hands the refunded transaction to the app, the app reports it, and the entitlement turns off as it would after an App Store refund.
- **Ask to Buy, failed payments, StoreKit errors:** the **Editor** menu of the open `.storekit` file.

## B. In the App Store sandbox (7 steps)

**1. Connect App Store Connect.** In App Store Connect, **Users and Access › Integrations › App Store Connect API**, make a key with the App Manager role and download it once.

```sh
palbase stores:apple:connect --key-file AuthKey_ABC123DEF4.p8 --issuer-id 57246542-96fe-1a63-e053-0824d011072a -E staging
```

Studio connects it under **App Distribution**.

**2. Connect the In-App Purchase key.** In the same place, the **In-App Purchase** tab, make a key. The environment verifies purchases and reads subscriptions with it.

```sh
palbase purchases:apple:connect --key-file SubscriptionKey_XYZ987WVU6.p8 -E staging
```

The issuer is the one step 1 connected; the key's id is read from the file's name. Studio connects it under **Purchases › App Store**. Both keys go from your computer straight to the environment, never through Studio.

**3. Put the catalog in App Store Connect.** In Studio, **Purchases › Stores**, plan the stores and confirm the plan; or from a terminal:

```sh
palbase purchases:catalog:plan -E staging
palbase purchases:catalog:confirm <plan id> --hash <hash> -E staging
```

Your products, subscription groups, prices and introductory offers are created in App Store Connect, and what Apple holds of each is shown under the plan. Apple can take up to an hour to show a new product in the sandbox.

**4. Check everything is ready.**

```sh
palbase purchases:doctor -E staging
```

Each line is one check: ✓ holds, ✗ does not, and `i` only says how things are. Under each ✗ is the command or the place in App Store Connect that fixes it. Run it again until every ✗ is gone. Studio's **Purchases › App Store** shows the same list.

**5. Make a sandbox tester.** In App Store Connect, **Users and Access › Sandbox**, click **+**, and give a name, an email address that is not an Apple Account yet, a password and a country or region.

**6. Sign in on the device.** Run the app from Xcode with the scheme's **StoreKit Configuration** set to **None**, and start a purchase. When the App Store asks you to sign in, use the tester. From then on the tester is under **Settings › Developer › Sandbox Apple Account**; your own Apple Account stays signed in.

**7. Buy.** The App Store's sheet says **[Environment: Sandbox]**. Nothing is charged. Apple's server notification about the purchase reaches the environment too; it is still one purchase.

### Renewals, history and interruptions

A sandbox subscription renews on a short clock and stops after 12 renewals. Make it faster:

```sh
palbase stores:apple:sandbox-testers -E staging
palbase stores:apple:sandbox-testers:set tester@example.com --renewal 3m -E staging
```

To buy the same products again, or to be eligible for an introductory offer again, clear the tester's history:

```sh
palbase stores:apple:sandbox-testers:clear tester@example.com -E staging
```

Then sign out of the sandbox account on the device and in again. `--interrupt on` makes the tester's next purchases stop halfway, as when a bank asks for a confirmation. Studio's **Purchases › App Store › Sandbox testers** changes the same settings and clears the same history.

The device has the same settings under **Settings › Developer › Sandbox Apple Account › Manage**.

### Refunds

Ask for one from the app, with StoreKit's refund sheet (`refundRequestSheet(for:isPresented:)` in SwiftUI). In the sandbox, any reason approves the refund. For a declined one, choose **Other** and type `DECLINE`; for a partial one, `GRANT_PRORATED`. The entitlement turns off and the refund's event reaches your backend.

## The app's code

The same code runs in both ways; StoreKit decides where the purchase goes. `pb` is the app's `PalbaseClient`.

```swift
import Palbase
import PalbasePurchases
import SwiftUI

struct Paywall: View {
    @State private var products: [Purchases.StoreProduct] = []
    @State private var isPro = false
    @State private var message = ""

    var body: some View {
        List {
            ForEach(products) { p in
                Button("\(p.product.displayName) — \(p.product.displayPrice)") {
                    Task { await buy(p) }
                }
            }
            Button("Restore purchases") {
                Task { isPro = (try? await pb.purchases.restore())?.isEntitled("pro") ?? isPro }
            }
            Text(isPro ? "Pro is on" : message)
        }
        .task { products = (try? await pb.purchases.products())?.products ?? [] }
        .task {
            // Kept current: a purchase on another device, a renewal, a refund.
            for await info in pb.purchases.customerInfoUpdates {
                isPro = info?.isEntitled("pro") ?? false
            }
        }
    }

    private func buy(_ product: Purchases.StoreProduct) async {
        do {
            switch try await pb.purchases.purchase(product) {
            case .purchased(let info): isPro = info.isEntitled("pro")
            case .alreadyEntitled(_, let entitlement, _): message = "\(entitlement) is already yours, bought elsewhere"
            case .pending: message = "Waiting for approval"
            case .cancelled: break
            }
        } catch {
            message = "\(error)"
        }
    }
}
```

`products()` returns only what the App Store (or Xcode) has. When some of the catalog's iOS products are missing, `products()` says why in `diagnosis`: a product id Xcode's file or App Store Connect does not have, or a bundle id that is not the app's.

## On your server

Check the entitlement where the content is served, not only in the app:

```ts
// src/modules/premium/premium.controller.ts
import { Controller, Forbidden, Get, Palbase, User, type UserT } from "palbase/backend";
import { isEntitled } from "palbase/server";

@Controller("/premium")
export class PremiumController {
  @Get("")
  async premium(@User() user: UserT): Promise<{ pro: true }> {
    // A user who has bought nothing is read as a customer with nothing.
    const { data } = await Palbase.purchases.getCustomer({ path: { customer_id: user.id } });
    if (!isEntitled(data, "pro")) throw new Forbidden("Pro is needed", "entitlement_required");
    return { pro: true };
  }
}
```

And act when something changes, with a typed event:

```ts
// src/modules/premium/purchase-events.ts
import { Log, On, type PlatformEvent } from "palbase/backend";

export class PurchaseEvents {
  @On("purchases.entitlement.changed")
  changed(event: PlatformEvent<"purchases.entitlement.changed">): void {
    const { customer_id, entitlement, active, is_sandbox } = event.data;
    Log.info("entitlement changed", { customer_id, entitlement, active, test: is_sandbox });
  }

  @On("purchases.refund.changed")
  refunded(event: PlatformEvent<"purchases.refund.changed">): void {
    Log.info("payment taken back", { customer_id: event.data.customer_id, share: event.data.share_milli / 1000 });
  }
}
```

```ts
// src/modules/premium/premium.module.ts
import { Module } from "palbase/backend";
import { PremiumController } from "./premium.controller";
import { PurchaseEvents } from "./purchase-events";

@Module({ controllers: [PremiumController], providers: [PurchaseEvents] })
export class PremiumModule {}
```

A test purchase is marked: `is_sandbox` is `true` in its events and in what the customer has.

## When something is missing

| What you see | Why, and what to do |
|---|---|
| `products()` is empty in Xcode | The scheme has no StoreKit Configuration, or the file is older than the catalog: run `palbase purchases:storekit` again. |
| The purchase works in Xcode but the customer has nothing | The environment does not take Xcode's certificate yet: step A4. |
| `products()` is empty on a device | `palbase purchases:doctor` names it: the catalog is not in App Store Connect yet, an agreement is not signed, or the product is less than an hour old. |
| No **[Environment: Sandbox]** on the sheet | The scheme still points at the `.storekit` file: set it to **None** (B6). |
| The tester cannot buy again | Clear its history (`palbase stores:apple:sandbox-testers:clear`), then sign out and in on the device. |

## Related

- [App Store](/docs/purchases/app-store): the keys, the server notifications, and what the environment does with each transaction
- [Catalog](/docs/purchases/catalog): the products the StoreKit file is made from
- [Entitlements, Credits & Limits](/docs/purchases/entitlements): `CustomerInfo`, `isEntitled` and every `purchases.*` event
- [Event Hooks](/docs/backend/hooks): `@On` handlers in a `palbase/backend` app
- [Webhooks](/docs/server/webhooks): the same events in any server, with `palbase/server`
- [Server SDK Overview](/docs/server/overview): `createServer`, refusals and retries



<!-- ===== purchases/google-play ===== -->

# Google Play

The catalog's `android` products are sold on Google Play with Play Billing: the app buys through `palbase-purchases`, Google takes the payment, and the environment reads each purchase from Play, keeps it in the ledger and acknowledges it. Play's real-time developer notifications tell the environment when a purchase changes — a renewal, a cancellation, a refund — with the app closed.

No key changes hands. Palbase makes a service account for the environment, your Play Console invites it, and the environment reads and acknowledges the app's purchases as that account.

## Connect Google Play

**1. Register the Android app** with its package and signing certificates in the environment, if it is not yet — [Android SDK › Registering the app](/docs/android/overview#registering-the-app):

```sh
palbase apps:create android "Shop" --slug shop-android
palbase apps:env:set shop-android --package com.example.shop --sha256 play_signing=AB:CD:… -E staging
```

**2. Connect the environment to Google Play:**

```sh
palbase stores:google:connect -E staging
```

It prints the service account Palbase made. In Play Console, **Users and permissions**, invite it with the app and, for purchases, **View financial data** and **Manage orders and subscriptions**. Link the Android app to Google Play (`palbase stores:apps:link <app id>`), then check what the account reaches:

```sh
palbase stores:google:check -E staging
```

Studio's **App Distribution** does the same.

**3. Sell on Google Play in the app:**

```sh
palbase purchases:google:connect --app shop-android -E staging
```

Palbase makes the app's notifications topic, which Play's own account may publish to, and has it pushed to this environment's address. It prints the topic. In Studio, **Purchases › Stores › Google Play purchases** connects it and shows the topic.

**4. Name the topic in Play Console:** **Monetize with Play › Monetization setup › Real-time developer notifications**, paste the topic, **Save**, then **Send test notification**.

```sh
palbase purchases:google -E staging
```

It says when the test notification arrived — the topic is set — and what is left to do. Every environment of the project that sells in the app reads the same topic.

**5. Bring Google Play to the catalog:** plan the catalog and confirm it ([Catalog › Bringing the stores to the catalog](/docs/purchases/catalog#bringing-the-stores-to-the-catalog)). Each subscription product is created on Play with a base plan per plan, each other product as a one-time product, for the app connected in step 3.

## Buying in the app

The app takes `studio.palbase:palbase-purchases`, which brings Play Billing with it. `pb.purchases.products()` returns the catalog's Android plans as Play has them for this user — a subscription once per base plan — with a `diagnosis` when Play returned fewer than the catalog sells; `purchase(activity, product)` opens Play's purchase sheet; `restore()` is the user's own "Restore purchases". Touch `pb.purchases` at launch: what Play holds unreported — a report that failed, a pending purchase since paid, one made outside the app — is reported then. See [Android › Purchases](/docs/android/purchases).

Buying a subscription while the customer has another plan of its group on Play replaces it, as `PlanChange` says: by default an upgrade now and a downgrade at the renewal, as Google recommends.

## What the environment does with a purchase

**It reads it from Play.** Nothing of the device's word is taken: each purchase is read from Play by its token, as the environment's service account, and applied to the ledger. One reported again applies nothing twice.

**It gives it to a customer.** A purchase nobody has is the customer's its obfuscated account id names — the SDK buys with it, and nothing personal goes to Google — or the reporting customer's. Play makes each new purchase a purchase token of its own, so what each of the app's accounts buys on a Google account they share is theirs from the start. One another customer has stays theirs, unless restored: a restore moves it to the restoring customer, never from an account to a guest, and at most 3 times in 30 days. A purchase that stays where it was is answered, after the rest is applied, with `403 restore_account_owned` (a guest restoring an account's), `403 restore_other_account` (another account's obfuscated id names it: sign in to that account), `403 restore_other_environment` (another environment of the project made it) or `409 restore_limit`.

**It acknowledges it** once the ledger has it, and consumes a consumable: the SDK never does. Play refunds a purchase not acknowledged in three days. A purchase the catalog does not map gives nothing and is not acknowledged.

**It follows Play.** A notification only says something changed: the purchase is read again from Play, and a voided one from the app's voided purchases. A refund turns the entitlement off and takes back the credits it gave (`purchases.refund.changed`).

**Test purchases** are Google Play's license testers': `is_sandbox`, opening entitlements as the [settings](/docs/purchases/customers#settings) say.

## Offers

A catalog offer on an Android subscription is written to Play as a developer-determined offer of the subscription's base plans, tagged `palbase`. The Android SDK buys a plan with its introductory offer when the catalog's plan has one and Play says the user may take it. See [Offers & Coupons](/docs/purchases/offers).

## Disconnecting

```sh
palbase purchases:google:disconnect -E staging
```

Play's notifications stop reaching the environment and the app's reports are refused; purchases already made stay in the ledger. The app's topic stays, for the other environments that read it. `palbase stores:google:disconnect` deletes the environment's service account at Google: Play Console's invite of it then reaches nothing.

Connecting, a test notification arriving and disconnecting each emit `purchases.store.changed`.

## Related

- [Android › Purchases](/docs/android/purchases): `pb.purchases` in a Kotlin app
- [Catalog](/docs/purchases/catalog) · [Offers & Coupons](/docs/purchases/offers)
- [Entitlements, Credits & Limits](/docs/purchases/entitlements): checking access on your server
- CLI: [`stores:google:connect`](/docs/cli/reference#palbase-storesgoogleconnect), [`purchases:google:connect`](/docs/cli/reference#palbase-purchasesgoogleconnect), [`purchases:google`](/docs/cli/reference#palbase-purchasesgoogle)



<!-- ===== purchases/connect-stripe ===== -->

# Connect Stripe

Your project sells its catalog on the web through your own Stripe account: Checkout, the customer portal, renewals and refunds all happen on it, and Palbase keeps each user's access in your app in step with them. Connect the account once per environment.

There are two ways. Use the first.

| | A. With one click | B. With a restricted key |
|---|---|---|
| What you do | Pick the account at Stripe and accept | Make a restricted key in the Stripe Dashboard and paste it |
| What Palbase holds | The access of Palbase's Stripe App, *Subscriptions by Palbase* | The key |
| Where Stripe's events go | Palbase's own endpoint, for every account that installed the App | An endpoint Palbase makes on your account |
| How to stop | Disconnect in Studio; uninstall the App in the Stripe Dashboard | Disconnect in Studio |

## A. With one click (Palbase's Stripe App)

**1. Open the environment's Stripe account.** In Studio, open the project and the environment, then **Purchases › Stores** and its Stripe account panel, and choose **Connect with one click**. From the command line:

```sh
palbase purchases:stripe:install -E staging
```

**2. Choose the mode.** Test mode sells in Stripe's sandbox, live mode takes real payments (`--live` on the command line). Connect a test environment in test mode first.

**3. Open Palbase's install page.** It names the Palbase project and environment the account will be connected to, then sends you to Stripe. The link works once, for 30 minutes.

**4. Pick the Stripe account and accept.** Stripe lists the accounts you can install apps on and shows what the App may do: write products, prices, customers, Checkout Sessions, subscriptions, customer portal sessions, coupons and promotion codes; read invoices, payment intents, charges, refunds, disputes and events. Coupons carry your offers' discounts to the web, and promotion codes your coupon codes. Accept, and Stripe sends you back to Palbase, which connects the account and says so.

**5. Check it.** Studio shows the account as active, connected through Palbase's Stripe App:

```sh
palbase purchases:stripe -E staging
```

Then bring the account to your catalog (Studio's catalog page, or `palbase purchases:catalog:plan` and `palbase purchases:catalog:confirm`): Palbase creates the catalog's products and prices on the account.

Nothing is made on your account for Stripe's events: they come to Palbase through the App.

## B. With a restricted key

In Studio, **Purchases › Stores** and its Stripe account panel, choose **Use a restricted key instead**, or run `palbase purchases:stripe:grant`. Make a restricted key in the Stripe Dashboard (**Developers › API keys › Create restricted key**) with **Write** on Products, Prices, Customers, Checkout Sessions, Customer portal, Subscriptions, Coupons, Promotion Codes and Webhook Endpoints, and **Read** on Invoices, Payment Intents, Charges, Disputes, Events and Account; open the page Palbase gives you and paste it there. Without Coupons and Promotion Codes the key still connects, but your offers' web discounts and your coupon codes cannot reach the account. A key that cannot read its account is refused with `422 stripe_permission_missing`, and so is one missing a permission Palbase checks for — the answer names it. The key goes from that page straight to Palbase, never through Studio. A secret key that can do anything is refused.

## Disconnecting

**Disconnect** in Studio stops selling through the account; purchases already made stay. With the App, uninstall it from the account too in the Stripe Dashboard (**Settings › Installed apps**); uninstalling it alone disconnects every environment connected through it.

## Related

- [Web](/docs/purchases/web): selling on the web with `pb.purchases` — Checkout, the customer portal, redemption links
- [Catalog](/docs/purchases/catalog): the products and prices a plan writes to the account
- [Purchases](/docs/purchases/overview): how the catalog, the stores and the customers fit together



<!-- ===== purchases/web ===== -->

# Web

The catalog's `web` products are sold through the environment's own Stripe account: Stripe Checkout takes the payment, Stripe's customer portal manages what was bought, and Stripe's events keep the ledger current — renewals, cancellations, refunds, disputes. Connect the account first: [Connect Stripe](/docs/purchases/connect-stripe).

In a browser, `pb.purchases` — the `palbase/web` client's purchases module — reads the offerings, opens Checkout and the portal, and keeps what the signed-in customer has current. Every call here takes the publishable key; what is the customer's takes their session too.

## Quick example

A pricing page: the web's plans with their prices, a button that buys one, and the page kept in step with what the customer has.

```ts
// app/pricing.ts
import { createClient } from "palbase/web";
import { formatPrice } from "palbase/web/paywall";

const pb = createClient({ url: "https://<ref>.palbase.studio", publishableKey: "pb_<ref>_c…" });

/** Every plan the web sells, priced in the catalog's currency. */
export async function plans(locale: string): Promise<{ product: string; plan: string; label: string }[]> {
  const { products } = await pb.purchases.offerings("web");
  return products.flatMap((p) =>
    (p.channels.web?.plans ?? []).map((plan) => ({
      product: p.key,
      plan: plan.key,
      label: `${p.channels.web?.locales[locale]?.name ?? p.key} — ${formatPrice(plan.price.amount, plan.price.currency, locale)}`,
    })),
  );
}

export async function buy(product: string, plan: string): Promise<void> {
  const url = await pb.purchases.checkout({
    product,
    plan,
    successUrl: "https://app.example.com/thanks",
    cancelUrl: "https://app.example.com/pricing",
  });
  location.assign(url);
}

// Told what the customer has once it is read, then whenever it changes; null while no one is signed in.
export const stop = pb.purchases.onCustomerInfo((info) => {
  document.body.dataset.pro = String(info?.entitlements["pro"]?.active === true);
});
```

## The offerings

`pb.purchases.offerings(channel)` is the catalog as a paywall shows it — each product's text in every language, its plans and their prices on a channel (the web's unless another is named), and the id each store sells a plan by. Nobody's purchases are in it: the publishable key reads it with no one signed in. Amounts are in the currency's minor units (`999` is 9.99); `formatPrice(amount, currency, locale)` from `palbase/web/paywall` writes one as the language writes it.

## Buying

`pb.purchases.checkout({ product, plan, successUrl, cancelUrl })` opens a Stripe Checkout session for one of the catalog's web plans, at its price on the environment's Stripe account, and answers its URL: send the buyer there. Stripe sends them back to `successUrl` once they paid, or to `cancelUrl`.

Both addresses go back to one of the project's registered apps — a web app's origin (`palbase apps:env:set <app> --origin https://app.example.com`), or a native app's own scheme — and nowhere else.

With a customer signed in — a guest too — the purchase is theirs once Stripe reports it, and `onCustomerInfo` hears it then: the success page shows the change when it arrives, not before.

| Refusal | Why |
|---|---|
| `409 already_entitled` | The customer already has the product, or a subscription of its group, from any store. Nothing is charged twice; the error's body names the `store` it is managed in. Credits can always be bought again. |
| `429 too_many_checkouts` | Checkouts are limited per address and per project with the publishable key alone, per customer and per address with a session. |

A free trial is given once per customer, across every channel — and on the web not to a guest, nor to a buyer with no account.

### A buyer with no account

With no one signed in, the buyer is no one yet: Checkout asks their email, and what they buy waits for the app user who redeems it. Put `{CHECKOUT_SESSION_ID}` in `successUrl` — Stripe writes the session's id there — and the success page asks for the purchase's **redemption link**:

```ts
// app/thanks.ts
import { createClient } from "palbase/web";

const pb = createClient({ url: "https://<ref>.palbase.studio", publishableKey: "pb_<ref>_c…" });

// successUrl was "https://app.example.com/thanks?session={CHECKOUT_SESSION_ID}".
const session = new URLSearchParams(location.search).get("session");
if (session) {
  // Stripe may not have told of the payment yet: it is asked again for up to 20 seconds.
  const link = await pb.purchases.redemptionLink(session);
  document.querySelector("#redeem")!.setAttribute("href", link.url);
}
```

The link works once, within an hour; the buyer is emailed one too. Opened on a phone, its page hands it to the app (`<scheme>://palbase/redeem?token=…`); opened on a computer, it shows a QR code to scan with the phone. The app — signed in, or a guest — redeems it, and the purchase is that customer's:

```ts
// app/redeem.ts
import { createClient, PalbaseError } from "palbase/web";

const pb = createClient({ url: "https://<ref>.palbase.studio", publishableKey: "pb_<ref>_c…" });

export async function redeem(link: string): Promise<string> {
  try {
    const info = await pb.purchases.redeem(link);
    return info.entitlements["pro"]?.active ? "Pro is yours" : "Redeemed";
  } catch (e) {
    if (e instanceof PalbaseError && e.code === "redemption_expired") {
      // Past its hour: a new link goes to the buyer's email, once.
      const resent = (e.body as { resent?: boolean } | undefined)?.resent === true;
      return resent ? "That link expired: a new one is on its way to your email" : "That link expired";
    }
    if (e instanceof PalbaseError && e.code === "already_redeemed") return "That link was used already";
    throw e;
  }
}
```

`redemptionLink` keeps the key it needs in the tab's `sessionStorage` from the checkout on; the redirect to Stripe and back keeps it. Each call makes a new link, ten at most within an hour of the payment; past it, the email's is the one. Your server can make one for a buyer whose email went astray, with the secret key (`createCheckoutRedemption`, any time).

## What the customer has

`pb.purchases.me()` reads everything the signed-in customer has now — entitlements, subscriptions, one-time purchases, credits, quota use — whatever store they bought in. The first read makes the user a customer.

`pb.purchases.onCustomerInfo(listener)` tells the listener once it is read, then each time it changes — a purchase in any store, a renewal or its end, a refund, credits spent — and `null` while no one is signed in; it answers the function that stops it. The first listener joins the customer's own realtime channel, the last one's stop leaves it. A new user signing in is read anew.

What a page shows from it is for the page. The content a purchase opens is served by your server, which checks the entitlement itself: [Entitlements, Credits & Limits](/docs/purchases/entitlements).

## Managing what was bought

```ts
// app/account.ts
import { createClient } from "palbase/web";

const pb = createClient({ url: "https://<ref>.palbase.studio", publishableKey: "pb_<ref>_c…" });

export async function manage(): Promise<void> {
  const info = await pb.purchases.me();
  const pro = info.entitlements["pro"];
  if (pro?.manage?.store === "stripe") {
    location.assign(await pb.purchases.portal("https://app.example.com/account"));
  } else if (pro?.manage?.url) {
    location.assign(pro.manage.url); // the App Store's or Google Play's own page
  }
}
```

`portal(returnUrl)` opens Stripe's customer portal for the signed-in customer, where they change, cancel or renew what they bought on the web and how they pay. A subscription bought in the App Store or on Google Play is managed there: its `manage.url` is the store's page.

## A paywall on the web

`pb.purchases.paywall(placement)` is the paywall the project published at a placement — designed in Studio, drawn by the SDK — and `render()` puts it in the page:

```ts
// app/upgrade.ts
import { createClient } from "palbase/web";

const pb = createClient({ url: "https://<ref>.palbase.studio", publishableKey: "pb_<ref>_c…" });

export async function showPaywall(container: HTMLElement): Promise<void> {
  const paywall = await pb.purchases.paywall("settings", { attributes: { plan: "free" } });
  if (!paywall) return; // the web sells nothing
  const view = paywall.render(container, {
    successUrl: "https://app.example.com/thanks",
    cancelUrl: "https://app.example.com/settings",
    links: { terms: "https://example.com/terms", privacy: "https://example.com/privacy" },
    onClose: () => view.destroy(),
  });
}
```

Its purchase button opens Checkout for the package selected. The web has no restore button: a web purchase is the account's, wherever it signs in. See [Paywalls](/docs/purchases/paywalls).

## Offers and coupons

`pb.purchases.offers()` lists the catalog's offers the signed-in customer may take now. A discount or a free trial is bought with `checkout({ …, offer: key })`; a grant is taken with `claimOffer(key)`; a code the customer typed is `redeemCoupon(code)`; `offerShown(key)` counts an offer seen. See [Offers & Coupons](/docs/purchases/offers).

## Guests

A guest — a user signed in with no account yet — buys like anyone else, and what it buys goes with it:

- A guest that **becomes** an account keeps its id, and its purchases with it: nothing to do.
- A guest that **signs in to an existing account** hands its purchases over. Before signing in, ask for the proof (`pb.purchases.mergeGrant()`, good for 5 minutes); once signed in, spend it (`pb.purchases.merge(grant)`): everything the guest bought goes to the account, for good.

See [Customers › Guests](/docs/purchases/customers#guests).

## From a native app

**On iOS**, an app may link out to buy on the web beside In-App Purchase in the App Store's United States storefront (App Review Guideline 3.1.1(a)). `PalbasePurchases` checks the storefront and opens Checkout in the system browser for the signed-in customer; back in the app, what they have is read again:

```swift
import PalbasePurchases

// Show the web button only where Apple lets the app link out.
if await pb.purchases.canOpenWebCheckout() {
    try await pb.purchases.openWebCheckout(product: "pro", plan: "yearly")
}
```

Elsewhere `openWebCheckout` throws `web_checkout_not_allowed` and asks nothing. Stripe sends the customer back to the app's own scheme, its bundle id. The checkout records where it was opened — iOS and the storefront — so the [charts](/docs/purchases/charts) can take off what the App Store may charge on such a purchase (nothing today).

**A redemption link** opens the app with `<scheme>://palbase/redeem?token=…`: hand it to `pb.purchases.redeem(_:)` on iOS, `pb.purchases.redeem(link)` on Android, and the web purchase is the app user's.

## Related

- [Connect Stripe](/docs/purchases/connect-stripe): the environment's Stripe account
- [Paywalls](/docs/purchases/paywalls) · [Offers & Coupons](/docs/purchases/offers)
- [Entitlements, Credits & Limits](/docs/purchases/entitlements): checking access on your server
- [Web SDK](/docs/web/overview): `createClient` and its options



<!-- ===== purchases/paywalls ===== -->

# Paywalls

A **paywall** is what an app shows to sell the catalog. It is designed once, as one JSON definition, and drawn natively from it — in SwiftUI on iOS (`PalbasePurchasesUI`), in the page on the web (`palbase/web`) — with each store's own prices filled in on the device.

A **placement** is a place in the app that shows a paywall: `onboarding`, `settings`, `out_of_credits`. The app asks for the placement, never for a paywall, so what it shows is decided in Studio or with the CLI — a new design, targeting rules, an experiment — and reaches the apps with no app update.

## Quick example

From a template to a placement the app asks for:

```sh
palbase purchases:paywalls:templates -E staging
palbase purchases:paywalls:new spring --template <key> -E staging
palbase purchases:paywalls:validate --file palbase/paywalls/spring.json -E staging
palbase purchases:paywalls:preview --file palbase/paywalls/spring.json --all -E staging
palbase purchases:paywalls:put spring --file palbase/paywalls/spring.json --revision 0 --publish -E staging
palbase purchases:placements:set settings --paywall spring -E staging
```

The web app draws it:

```ts
// app/settings.ts
import { createClient } from "palbase/web";

const pb = createClient({ url: "https://<ref>.palbase.studio", publishableKey: "pb_<ref>_c…" });

export async function upgrade(container: HTMLElement): Promise<void> {
  const paywall = await pb.purchases.paywall("settings");
  paywall?.render(container, { successUrl: "https://app.example.com/thanks", cancelUrl: "https://app.example.com/settings" });
}
```

And the iOS app:

```swift
import PalbasePurchasesUI
import SwiftUI

struct SettingsView: View {
    @State private var showPaywall = false

    var body: some View {
        Button("Go Pro") { showPaywall = true }
            .paywall(placement: "settings", isPresented: $showPaywall)
    }
}

// Once, at the root of the app:
// RootView().palbasePurchases(pb.purchases).paywallLinks(terms: termsURL, privacy: privacyURL)
```

In Studio, **Purchases › Paywalls** does all of it: start from a template, edit its components, texts and colors with a live preview, publish, and give a placement its paywall.

## The definition

A paywall is a design system and a free layout of components that name it:

- **`theme`** — colors by name for light and dark (at least `background`, `surface`, `text`, `muted`, `accent` and `on_accent`), a type scale, radii and spacing.
- **`root`** — the part that scrolls, between a fixed **`header`** and **`footer`**; **`sheets`** it opens.
- **Components** — stacks, texts, icons, images, videos, dividers, spacers, buttons, packages, the purchase button, tabs, a switch, carousels, a countdown, a timeline, a features list, an HTML block — each with a style, a condition to be shown, a style for when it is selected, and an entrance animation.
- **Texts** — in each language the paywall has (`locales`), falling back to `default_locale`. A text holds variables the app fills from its store: `{{price}}`, `{{price_per_month}}`, `{{period}}`, `{{trial}}`, `{{savings}}`, `{{product_name}}`, `{{offer_price}}`. Prices are never in the definition. A text naming a variable its package has no value for — no trial, no savings — is not drawn.
- **Packages** — the catalog's plans it sells, as `product` and `plan`.

The least a paywall is — a title, a package that says its own price, the button that buys it, and the links App Review expects:

```json
{
  "schema": 2,
  "name": "Simple",
  "default_locale": "en",
  "theme": {
    "colors": {
      "light": { "background": "#FFFFFF", "surface": "#F2F2F7", "text": "#111114", "muted": "#6B6B70", "accent": "#5B5BD6", "on_accent": "#FFFFFF" },
      "dark": { "background": "#000000", "surface": "#1C1C1E", "text": "#F5F5F7", "muted": "#9A9AA0", "accent": "#8E8EF5", "on_accent": "#000000" }
    }
  },
  "root": {
    "type": "stack",
    "spacing": 16,
    "align": "stretch",
    "style": { "padding": 24, "background": "background" },
    "children": [
      { "type": "text", "text": "Go Pro", "size": 28, "weight": 700 },
      { "type": "spacer" },
      {
        "type": "package",
        "product": "pro",
        "plan": "monthly",
        "selected": true,
        "style": { "padding": 16, "corners": 14, "background": "surface" },
        "children": [{ "type": "text", "text": "{{product_name}} — {{price}} / {{period}}", "weight": 600 }]
      },
      {
        "type": "purchase_button",
        "style": { "height": 52, "corners": 14, "background": "accent" },
        "content": { "type": "text", "text": "Continue", "color": "on_accent", "weight": 600 }
      },
      {
        "type": "stack",
        "axis": "horizontal",
        "spacing": 24,
        "distribution": "center",
        "children": [
          { "type": "button", "action": { "type": "restore" }, "visible": { "platform": ["ios", "android"] }, "content": { "type": "text", "text": "Restore", "size": 13, "color": "muted" } },
          { "type": "button", "action": { "type": "terms" }, "content": { "type": "text", "text": "Terms", "size": 13, "color": "muted" } },
          { "type": "button", "action": { "type": "privacy" }, "content": { "type": "text", "text": "Privacy", "size": 13, "color": "muted" } }
        ]
      }
    ]
  }
}
```

Every component and field, their bounds and two more examples to start from are in the CLI's guide — `palbase purchases:paywalls:guide`, made from the definition's JSON Schema, which `palbase purchases:paywalls:schema` writes for an editor to check a file against. A definition is held to bounds: 128 KiB of JSON, 400 components, 16 deep, 500 characters a text, 40 languages.

## Drafts and versions

A paywall has a **draft** and its **published versions**. The apps see only what is published.

| Command | What it does |
|---|---|
| `palbase purchases:paywalls` | The paywalls: each one's draft revision, the version published, and the placements that show it. |
| `palbase purchases:paywalls:get <name>` | Writes the draft — or `--version <n>` — to `palbase/paywalls/<name>.json`, with its revision. The file's first line names its JSON Schema, written beside it. |
| `palbase purchases:paywalls:validate --file <file>` | Checks it as publishing would, saving nothing: every rule of the schema, and every package against the catalog. |
| `palbase purchases:paywalls:put <name> --file <file> --revision <n>` | Saves it as the draft, on the revision it was edited from; `--revision 0` makes a new paywall. `--publish` publishes it too. |
| `palbase purchases:paywalls:publish <name>` | Publishes the draft as the next version. |
| `palbase purchases:paywalls:delete <name>` | Deletes the paywall and its versions — not one a placement or a running experiment shows. |

A problem's path is where it is in the file (`root.children[2].content.text`). A **warning** — what App Review expects of a subscription's paywall: a restore button, the legal links — does not stop a save or a publish; a broken rule does (`422 invalid_paywall`, every problem listed). Of two people editing at once, the second is told (`412 paywall_changed`), never overwritten. Publishing checks the paywall as the apps will get it: every package must be one the catalog sells, every asset still the bytes registered. A draft the same as the newest version publishes nothing new.

The newest 50 versions are kept. Each publish emits `purchases.paywall.published`; the apps asking for a placement that shows the paywall get the new version at once.

**Look before saving.** `palbase purchases:paywalls:preview` draws the file with the SDK's own renderer in a headless browser — Chrome, Chromium, Edge or Brave — as a PNG of the platform's screen; `--all` draws every platform in both appearances at both text sizes. `palbase purchases:paywalls:check` measures what is drawn on every screen and lists what is wrong — text cut off, a purchase button not on the first screen, contrast under WCAG's, targets too small — and exits 1 while anything is.

## Assets

A definition names the project's images, videos, fonts and HTML blocks as `asset:<id>`:

```sh
palbase purchases:paywalls:assets:upload hero.webp --kind image -E staging
```

The file goes to the project's public bucket `paywall-assets` — made when there is none — and is registered: the environment reads it there, says what it is by its bytes, and keeps their SHA-256. An app draws an asset only when what it downloaded is those bytes, and a paywall naming an asset whose file was since changed or removed is refused when published.

| Kind | Formats | At most |
|---|---|---|
| `image` | PNG, JPEG, WebP | 2 MiB |
| `video` | MP4, MOV | 50 MiB |
| `font` | TTF, OTF, WOFF2 | 5 MiB |
| `html` | A zip with `index.html` at its root | 5 MiB |

`palbase purchases:paywalls:assets` lists them; `:assets:delete` forgets one no paywall names. A project has at most 500 assets and 100 paywalls.

## Placements

```sh
palbase purchases:placements:set onboarding --paywall spring -E staging
```

gives a placement its **default paywall** — what it shows whoever none of its rules holds for — and makes the placement when it is new. A placement's key is lowercase letters, digits, `_` and `-`, 64 at most; a project has at most 200.

When an app asks for a placement, what it gets is decided in this order:

1. An **experiment** running for everyone at the placement: the viewer's variant.
2. The placement's **rules**, in order: the first in effect whose conditions all hold shows its paywall, or the variant of the experiment it sends to.
3. The placement's **default** paywall.

Each app gets the newest version it can draw: it says the newest paywall schema its SDK draws, and an app on an older SDK keeps getting the last version written in one it knows. With nothing published there — or no such placement — the SDK draws its own paywall from the catalog: every plan the store sells (the first six) with its price and period, the purchase button, the legal links and — in an app — restore, in the system's colors.

`palbase purchases:placements` lists them; `palbase purchases:placements:delete <placement>` forgets one, and the apps asking for it draw their own.

### Targeting rules

A placement's rules are one file, every rule in the order they are read:

```sh
palbase purchases:placements:rules:get onboarding --out palbase/onboarding-rules.json -E staging
```

```json
{
  "rules": [
    {
      "name": "Turkey, not yet Pro",
      "state": "live",
      "conditions": [
        { "field": "country", "op": "in", "values": ["TR"] },
        { "field": "entitlement", "op": "lacks", "values": ["pro"] }
      ],
      "target": { "paywall_id": "<a published paywall's id>" }
    },
    {
      "name": "Black Friday",
      "state": "scheduled",
      "starts_at": "2026-11-27T00:00:00Z",
      "ends_at": "2026-12-01T00:00:00Z",
      "conditions": [{ "field": "app_version", "op": "gte", "value": "2.4.0" }],
      "target": { "paywall_id": "<a published paywall's id>" }
    }
  ]
}
```

```sh
palbase purchases:placements:rules:put onboarding --file palbase/onboarding-rules.json --revision 4 -E staging
```

A rule is `live`, `scheduled` (in effect from `starts_at`, until `ends_at`) or `inactive`. Its target is a published paywall (`paywall_id`) or the experiment running on the placement for the rules (`experiment_id`). At most 50 rules of at most 10 conditions; a rule with none holds for everyone.

| `field` | `op` | What it reads |
|---|---|---|
| `country` | `in`, `not_in` | The store's country the app sends, else the country of the request's address. ISO 3166-1 codes. |
| `platform` | `in`, `not_in` | `ios`, `android`, `web`. |
| `app` | `in`, `not_in` | The registered app's id. |
| `app_version` | `eq`, `neq`, `gt`, `gte`, `lt`, `lte` | The app's version, ordered as Semantic Versioning orders them. |
| `sdk_version` | the same, with `sdk` | The version of the SDK named (`palbase-swift`): a viewer on another SDK does not meet it. |
| `locale` | `in`, `not_in` | The first language the request asks for: `tr` covers `tr-TR`, `en-GB` covers `en-GB` alone. |
| `entitlement` | `has` (any of `values`), `lacks` (none of them) | The signed-in user's active entitlements, as the server knows them. |
| `first_seen_days` | `gt`, `gte`, `lt`, `lte` | Whole days since the user was first seen, as the server knows it. |
| `attribute` | `in`, `not_in`, `exists`, `not_exists`, `gt`, `gte`, `lt`, `lte`, with `key` | What the app says of the viewer: `pb.purchases.paywall("onboarding", { attributes: { plan: "free", sessions: 12 } })`. |

A value the request does not carry meets no condition on it, `not_in` included (`not_exists` aside). An app sends at most 20 attributes — texts, numbers or yes/no — of 2 KiB together.

**Targeting picks what to show; it is not access control.** The country, the attributes and the versions are what the app says of itself: no price or entitlement may hang on them.

| Command | What it does |
|---|---|
| `palbase purchases:placements:preview <placement>` | What the placement shows a viewer and why — the experiment, the rule that decided with every rule condition by condition, or the default — for `--platform`, `--country`, `--app-version`, `--locale`, `--attr`, `--user`, at `--at`; `--rules <file>` tries rules not yet saved. Nothing is counted. |
| `palbase purchases:placements:results <placement>` | What each rule, each variant and the default showed, and what its viewers did: exposures, viewers, purchases, conversion, revenue. |
| `palbase purchases:placements:attributes` | The attribute keys the apps sent, the most used first: suggestions for conditions. The keys are kept, never the values. |

## Experiments

An experiment splits a placement between 2 to 4 published paywalls, by weight. Each viewer — the signed-in user, a guest included, else the installation — sees the same variant every time, and the results say which sells best.

```sh
palbase purchases:experiments:start onboarding --variants spring=50,classic=50 -E staging
palbase purchases:experiments:results <experiment> -E staging
palbase purchases:experiments:winner <experiment> --variant a -E staging
```

| Audience | Who is in it |
|---|---|
| `placement` (the default) | Everyone at the placement, decided before its rules. The placement keeps its default for when the experiment ends. |
| `rules` | Only the viewers the placement's rules send to it: a rule's target names the experiment. |

One experiment runs on a placement at a time. Variants are keyed `a`, `b`, `c`, `d` unless `--variants` names them (`control:classic=50`); the **first** is what a stop keeps.

**The results** count, for each variant, its exposures and viewers, and the purchases its viewers made within the window after first seeing it (7 days unless `--window-days` says): the purchases the stores confirmed, never what an app reports — each counted once, for the first variant its buyer saw. Revenue is what was paid to date, renewals in, refunds out. Each variant's chance to convert best is Bayesian; the leader is called **confident** once every variant has been seen enough and its chance is high enough, and until then the results say why not. Test purchases count with `--sandbox`.

| Command | What it does |
|---|---|
| `palbase purchases:experiments:stop <experiment>` | Stops it at once: what it showed becomes its first variant's paywall. |
| `palbase purchases:experiments:winner <experiment> --variant <key>` | Ends it with a winner: for everyone at the placement, the winner becomes the placement's default — or, `--as-rule`, a live rule at the top of its rules shows it to everyone, to narrow later. For the rules, the rules that sent to it show the winner. |

Results stay after an experiment ends. In Studio, **Purchases › Experiments** starts one, shows its results and gives the winner to everyone in one step.

## In the app

The SDK asks for the placement in the newest schema it draws, with the app's version, its platform, its language and the attributes it is given; keeps the answer on the device, to ask again with its ETag and to show offline; downloads the assets and checks each; and counts the paywall shown, for the results. Purchases are never reported with it: the results read the ledger.

| Platform | How |
|---|---|
| Web | `pb.purchases.paywall(placement, { attributes })`, then `render(container, { successUrl, cancelUrl, links, onClose })`. The purchase button opens Stripe Checkout; the web has no restore button. See [Web › A paywall on the web](/docs/purchases/web#a-paywall-on-the-web). |
| iOS | `PaywallView(placement:)`, `.paywall(placement:isPresented:)`, or `.presentPaywallIfNeeded(entitlement:placement:)`, under `.palbasePurchases(pb.purchases)`. Its purchase button buys with StoreKit, its restore button restores, and it closes after a purchase. `.paywallComponent(id)` draws the app's own view in place of a component Studio named. See [iOS › Purchases](/docs/ios/purchases). |
| Android | The Android SDK does not draw paywalls: an Android app shows the products from `pb.purchases.products()` in its own screen. |

Any other client reads the placement with the publishable key: `GET /purchases/placements/{placement}/paywall` answers the definition and what it sells, or `204` when the app is to draw its own.

## Related

- [Catalog](/docs/purchases/catalog): the packages a paywall sells
- [Offers & Coupons](/docs/purchases/offers): a package sold with an offer shows `{{offer_price}}`
- [Charts](/docs/purchases/charts): revenue and subscriptions by paywall and experiment
- CLI: [`purchases:paywalls`](/docs/cli/reference#palbase-purchasespaywalls), [`purchases:placements`](/docs/cli/reference#palbase-purchasesplacements), [`purchases:experiments`](/docs/cli/reference#palbase-purchasesexperiments)



<!-- ===== purchases/offers ===== -->

# Offers & Coupons

An **offer** is a price for a while, given to whom the project chooses — the members of an analytics audience, or everyone — and once to each customer. It gives one of three things:

| Kind | What the customer gets | Where it is sold |
|---|---|---|
| `discount` | A percentage off a subscription's plans, for a number of billing periods | Each store, as its own offer |
| `trial` | A free trial of a subscription's plans | Each store, as its own offer |
| `grant` | An entitlement for a time, with no store and no payment | Nowhere: the customer claims it |

A **coupon** is a code that opens an offer to whoever types it: a code many share, or a batch of one-time codes to give out.

## Offers are part of the catalog

An offer is written in the catalog's `offers`, and goes to the stores with the rest of it when a plan is confirmed ([Catalog](/docs/purchases/catalog#bringing-the-stores-to-the-catalog)): a discount or a trial becomes the App Store's **promotional offer**, Google Play's **developer-determined offer** (tagged `palbase`) and a **Stripe coupon**, each by the offer's key. In Studio, **Purchases › Offers** adds and edits them, and shows how many customers were shown each and took it, by store.

```json
{
  "offers": [
    {
      "key": "winback_50",
      "name": "Win-back: half off for 3 months",
      "product": "pro",
      "plans": ["monthly"],
      "discount": { "percent": 50, "periods": 3 },
      "audience": "<an analytics audience's id>",
      "starts_at": "2026-11-01T00:00:00Z",
      "ends_at": "2026-12-01T00:00:00Z"
    },
    { "key": "long_trial", "name": "One month free", "product": "pro", "trial": "P1M" },
    { "key": "pro_week", "name": "A week of Pro", "grant": { "entitlement": "pro", "duration": "P7D" } }
  ]
}
```

| Field | What it is |
|---|---|
| `key` | Its key, and its id at every store (hyphenated at Google Play). |
| `name` | Its name, 1 to 64 characters: the App Store's reference name. |
| `product`, `plans` | The subscription a discount or a trial is on, and its plans; no `plans`, every plan. A grant names no product. |
| `discount` | `{ "percent": 1–99, "periods": 1–12 }`. |
| `trial` | A free trial's length, ISO 8601: in the App Store `P3D`, `P1W`, `P2W`, `P1M`, `P2M`, `P3M`, `P6M` or `P1Y`. |
| `grant` | `{ "entitlement", "duration" }`: the catalog's entitlement, for `P7D`, `P1M` … from the moment it is claimed. |
| `audience` | The id of the analytics audience whose members are given it — those who allowed personalization; none, everyone. |
| `starts_at`, `ends_at` | When it is first given, and when it no longer is. |

On a product sold on the web, a discount of more than one period is one Stripe coupon, which lasts whole months: every plan it is on must bill by whole months, and by the same number of them — make one offer per plan length.

## Taking an offer in the app

The apps list the offers the signed-in customer may take now — live, not taken before, for everyone or for an audience they are in, or opened to them by a coupon they redeemed — each with what every store sells it as:

```ts
// app/offers.ts
import { createClient } from "palbase/web";

const pb = createClient({ url: "https://<ref>.palbase.studio", publishableKey: "pb_<ref>_c…" });

export async function takeBestOffer(): Promise<string | null> {
  const offers = await pb.purchases.offers();
  const offer = offers[0];
  if (!offer) return null;
  await pb.purchases.offerShown(offer.key); // counted the first time

  if (offer.kind === "grant") {
    const grant = await pb.purchases.claimOffer(offer.key);
    return `${grant.entitlement} until ${grant.expires_at}`;
  }
  // A discount or a trial is bought with the offer, on one of its web plans.
  const plan = offer.web?.plans[0];
  if (!offer.product || !plan) return null;
  return pb.purchases.checkout({
    product: offer.product,
    plan,
    offer: offer.key,
    successUrl: "https://app.example.com/thanks",
    cancelUrl: "https://app.example.com/pricing",
  });
}
```

| | Web | iOS |
|---|---|---|
| The offers | `pb.purchases.offers()` | `pb.purchases.offers()` |
| Counted as shown | `offerShown(key)` | `offerShown(_:)` |
| Buy with a discount or a trial | `checkout({ …, offer })` | `purchase(_:offer:)` |
| Claim a grant | `claimOffer(key)` | `claim(_:)` |
| Take one by its key, whatever it is | — | `take(offer:)` |

A paywall's package sold with an offer the customer may take shows the offer's price as `{{offer_price}}`, and its purchase button buys with it.

**In the App Store**, a promotional offer is bought under Apple's signature for this customer, which the environment makes with the In-App Purchase key when the app asks — the app holds no key. The signature names an App Store transaction of the Apple account the app runs on, so it buys the offer for that Apple account alone: passed to someone else, it buys nothing. The iOS SDK sends the newest transaction of the group StoreKit holds on the device; without one, the customer's own newest subscription the environment knows is named. Apple gives a promotional offer only to a customer who subscribes, or subscribed, in the group: anyone else's purchase fails as `ineligibleForOffer`, and a customer with neither is signed none (`no_app_store_purchase`). On an Apple ID shared among the app's accounts, the second account is signed on the first's subscription, and what it buys with the offer is its own ([Customers](/docs/purchases/customers#restores-and-moved-purchases)). In Xcode, the StoreKit configuration's own Subscription Offers Key signs it ([Test Apple Purchases](/docs/purchases/testing-apple)). **On Google Play**, the Android SDK buys a plan with its introductory offer when Play says the user may take it. **On the web**, the checkout carries the offer's coupon.

A grant is claimed with an account: a guest is refused (`403 account_required`) unless a coupon opened the offer to it. An offer taken once is not taken again (`409 offer_taken`); one that is not the customer's to take now is `403 offer_not_open`. Taking one emits `purchases.offer.redeemed`.

## Coupons

A coupon opens one of the catalog's offers to whoever redeems its code, once a customer. Make one in Studio (**Purchases › Coupons › New coupon**) or from your server:

```ts
// server/coupons.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

// One code anyone may type, 500 times at most.
await palbase.purchases.createCoupon({
  body: { key: "launch", name: "Launch week", kind: "palbase", offer: "long_trial", code: "LAUNCH26", max_redemptions: 500 },
});

// 1,000 codes of one use each, to give out.
await palbase.purchases.createCoupon({
  body: { key: "partners", name: "Partner codes", kind: "palbase", offer: "pro_week", one_time_codes: 1000, signed_in_only: true },
});
```

| Field | What it is |
|---|---|
| `kind` | `palbase`: Palbase takes the code. `apple`: an App Store offer code, made in App Store Connect on one `plan` of the offer's product and redeemed in the App Store's own sheet. |
| `code`, `max_redemptions` | A code many share, 3 to 32 letters and digits, and how many times it is taken. On the web, a shared code of a discount is the Stripe promotion code of the offer's coupon too. |
| `one_time_codes` | Instead of `code`: how many codes of one use each to make, 1 to 25,000. |
| `signed_in_only` | A guest cannot redeem it. |
| `expires_at` | When it ends. An App Store batch's codes must end. |

`listCouponCodes` (`GET /purchases/coupons/{coupon_key}/codes`) lists a batch's codes — whom each was given to, who redeemed it — and answers a CSV file to hand out when asked for `text/csv`. `revokeCoupon` ends one: no code of it is redeemed from then on, and what was redeemed stays. An App Store coupon's `apple.state` says how App Store Connect took it: `pending`, `applied` or `failed`.

### Redeeming a code

The customer types the code in the app, in any case:

```ts
// app/redeem-code.ts
import { createClient, PalbaseError } from "palbase/web";

const pb = createClient({ url: "https://<ref>.palbase.studio", publishableKey: "pb_<ref>_c…" });

export async function redeemCode(code: string): Promise<string> {
  try {
    const { offer, grant } = await pb.purchases.redeemCoupon(code);
    return grant ? `${grant.entitlement} is yours` : `${offer.name} is yours to take`;
  } catch (e) {
    if (e instanceof PalbaseError && e.code === "redeem_at_app_store") return "Redeem this code in the App Store";
    if (e instanceof PalbaseError) return e.message;
    throw e;
  }
}
```

A grant is given at once; a discount or a trial is the customer's to buy from then on — `offers()` lists it, with the coupon. On iOS, `redeem(code:)` does the same and throws `CouponError`; an App Store offer code is redeemed in the App Store's sheet, `presentOfferCodeRedemption()`, and what it gives arrives as any App Store transaction does.

| Refusal | Why |
|---|---|
| `404 coupon_not_found` | No coupon has this code. |
| `409 coupon_redeemed`, `409 code_used` | The customer redeemed it or took its offer already; the one-time code was used. |
| `410 coupon_ended`, `410 coupon_exhausted`, `410 offer_ended` | The coupon ended or was taken as many times as it may be; its offer ended. |
| `403 sign_in_required` | A coupon for signed-in customers, and a guest typed it. |
| `422 redeem_at_app_store` | An App Store offer code: redeemed in the App Store. |
| `429 too_many_attempts` | Too many codes tried by this customer or from this network: try again after `retryAfter`. |

Redeeming emits `purchases.coupon.redeemed`, and `purchases.offer.redeemed` for a grant.

## Related

- [Catalog](/docs/purchases/catalog): where offers are written
- [Paywalls](/docs/purchases/paywalls): packages sold with an offer
- [Web](/docs/purchases/web) · [App Store](/docs/purchases/app-store) · [Google Play](/docs/purchases/google-play)
- [Web Analytics](/docs/web/analytics): the audiences an offer is for



<!-- ===== purchases/entitlements ===== -->

# Entitlements, Credits & Limits

What a customer has is one answer, `CustomerInfo`, whatever store they bought in: their **entitlements** (`pro`), their **credits** (`tokens`) and their use of each **limit** (`ai_requests` a month). The apps read it to decide what to show; your server reads it to decide what to serve — and spends credits and quota, which only a server does.

## Quick example

A route only Pro customers reach, and one that is paid for in tokens:

```ts
// src/modules/summaries/summaries.controller.ts
import { Body, Controller, Forbidden, Get, Headers, PalError, Palbase, Post, User, z, type UserT } from "palbase/backend";
import { PalbaseError, isEntitled, withReservation } from "palbase/server";

const Summarize = z.object({ text: z.string().min(1).max(20000) });
type Summarize = z.infer<typeof Summarize>;
const Retried = z.object({ "idempotency-key": z.string().min(1).max(255) });
type Retried = z.infer<typeof Retried>;

@Controller("/summaries")
export class SummariesController {
  @Get("/archive")
  async archive(@User() user: UserT): Promise<{ pro: true }> {
    const { data } = await Palbase.purchases.getCustomer({ path: { customer_id: user.id } });
    if (!isEntitled(data, "pro")) throw new Forbidden("Pro is needed", "entitlement_required");
    return { pro: true };
  }

  @Post("")
  async create(@Body(Summarize) body: Summarize, @Headers(Retried) headers: Retried, @User() user: UserT): Promise<{ summary: string }> {
    try {
      // 10 tokens are held while the job runs and taken once it returns; if it throws, they are released.
      // The same Idempotency-Key again (a retried request) is the same hold, never a second charge.
      return await withReservation(Palbase, user.id, { credits: "tokens", amount: 10, idempotencyKey: headers["idempotency-key"] }, async () => {
        const summary = await Palbase.ai.ask(`Summarize in three sentences:\n\n${body.text}`);
        return { summary };
      });
    } catch (e) {
      if (e instanceof PalbaseError && e.code === "credits_insufficient") throw new PalError(402, "credits_insufficient", "Not enough tokens");
      throw e;
    }
  }
}
```

A customer without 10 tokens available is refused before the job runs: the purchases module answers `409 credits_insufficient`, and the route answers `402`. A module's refusal the handler does not catch answers `500` ([Responses & Errors](/docs/backend/errors#errors-from-the-projects-modules)).

## What a customer has

`CustomerInfo` is what `GET /purchases/me` answers the customer's app and `GET /purchases/customers/{customer_id}` answers your server — the same document:

| Field | What it is |
|---|---|
| `customer_id` | The user's id. A guest merged into an account reads as the account. |
| `entitlements` | Every entitlement the customer has or had, by key (below). |
| `subscriptions` | Their subscriptions and non-renewing periods, oldest first: `product`, `plan`, `store`, `state`, `active`, `expires_at`, `will_renew`, `is_sandbox`, `manage`. |
| `purchases` | Their one-time purchases, oldest first: `product`, `store`, `state`, `purchased_at`, `is_sandbox`. |
| `credits` | Their balance in each credit (below). |
| `limits` | Their use of each limit in its current window (below). |
| `guest` | Whether the user is a guest. |
| `revision` | Rises with every change of what they have; `0` while they have nothing. |
| `requested_at` | When it was computed: what was active is as of then. |

An entitlement:

| Field | What it is |
|---|---|
| `active` | Whether the customer has it now. |
| `expires_at` | When it ends; `null` for life. |
| `will_renew` | Whether what gives it renews. |
| `store` | Where it comes from: `app_store`, `play_store`, `stripe`, or `promotional` (a grant). |
| `product`, `plan` | The catalog's product and plan that give it. |
| `period_type` | `normal`, `trial` (a free trial) or `promotional` (a grant). |
| `billing_issue` | The store could not charge the renewal: the customer keeps access through its grace period. |
| `is_sandbox` | A test purchase gives it. |
| `manage` | Where it is managed: the store, and its page (`url`) — none for Stripe, whose portal is opened on request. |
| `sources` | Everything that gives it, active ones first. |

An entitlement is read from the source that gives it longest: one for life wins, a real purchase wins over a test one.

A subscription's `state` is `trial`, `active` or `grace` while it gives access, and `pending`, `billing_retry`, `paused`, `expired`, `revoked` (refunded) or `replaced` (another purchase took it over) when it does not.

## Checking an entitlement

**On your server**, read the customer and ask `isEntitled(info, key)` from `palbase/server`: the entitlement is active and, unless it is for life, ends after now. It reads the `CustomerInfo` alone, so one kept a while still ends when its entitlement does. In a `palbase/backend` app the module is `Palbase.purchases`; from any server, `createServer({ url, secretKey }).purchases`. Reading a customer writes nothing: a user who has bought nothing reads as a customer with nothing — and with every limit's free tier.

**In the app**, what the customer has is kept current on its own:

| Platform | |
|---|---|
| Web | `pb.purchases.onCustomerInfo((info) => …)`; `info.entitlements["pro"]?.active`. |
| iOS | `pb.purchases.isEntitled("pro")`; in SwiftUI, `pb.purchases.state.isEntitled("pro")` draws the view again when it changes. |
| Android | `pb.purchases.isEntitled("pro")`; `pb.purchases.customerInfoUpdates`, a `Flow`. |

The app's answer decides what the app shows. What a purchase opens on your server — content, an API, a download — is checked on the server: the app's word is the app's.

## Credits

A customer's credits come from the catalog's products — a consumable per purchase, a subscription per period — and from grants your support gives. Each lot keeps its own end: a subscription period's credits end with the period unless the product rolls them over (`rollover: "all"`), credits bought never end, and a grant's may.

| Field of a balance | What it is |
|---|---|
| `currency` | The credit. |
| `balance` | What the live lots hold, less what the customer owes. |
| `available` | What a spend can take now: the balance less what open holds keep. |
| `reserved` | What open holds keep. |
| `debt` | What the customer owes: a refund took back credits already spent. The next credits pay it first. |
| `next_expiry` | When credits next expire; `null` when none do. |

### Spending

Credits are spent by your server, with the secret key, in one of two ways.

**In one step**, for work that is done or cannot fail:

```ts
// src/modules/exports/exports.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class ExportsService {
  /** Takes 5 tokens for the export: the same exportId again is the same spend, never a second. */
  async charge(userId: string, exportId: string): Promise<number> {
    const { data } = await Palbase.purchases.spend({
      path: { customer_id: userId },
      headers: { "Idempotency-Key": `export-${exportId}` },
      body: { credits: "tokens", amount: 5, metadata: { export: exportId } },
    });
    return data.balance_after ?? 0;
  }
}
```

**Held for a job, then committed.** A hold keeps the credits — still the customer's, but no other spend can take them — until it is committed (the job ran: `commitSpend`, all of it or `amount` of it), released (it did not: `releaseSpend`) or runs out (`ttl_seconds`, 10 minutes unless said, 24 hours at most; `extendHold` gives it more). `withReservation(server, customerId, reservation, fn)` from `palbase/server` does the three: it holds, runs `fn`, commits when `fn` returns and releases when it throws. Asked again with an `idempotencyKey` whose hold is already over, it throws `ReservationSettled`, and the job does not run again.

`reverseSpend` hands back what a committed spend took — the job failed afterwards — to the lots it came from.

Credits are taken from the lots that expire first, bought ones last. The **Idempotency-Key** names a spend for good: sent again, a minute or a month later, it answers the same spend (`200`, `Idempotent-Replayed`), never a second. Every movement — given, spent, expired, taken back by a refund, forgiven — is listed by `listCreditEntries`, newest first: support's answer to "where did my credits go".

| Refusal | Why |
|---|---|
| `409 credits_insufficient` | Not that many available. |
| `409 hold_expired` | The hold ran out before it was committed: what it kept is free again. |

### Giving credits

```ts
// src/modules/support/support.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class SupportService {
  async apologize(userId: string, ticket: string): Promise<void> {
    await Palbase.purchases.grantCredits({
      path: { customer_id: userId },
      headers: { "Idempotency-Key": `ticket-${ticket}` },
      body: { credits: "tokens", amount: 50, source: "support", reason: `Ticket ${ticket}: export failed twice`, expires_at: "2027-01-01T00:00:00Z" },
    });
  }
}
```

A grant pays what the customer owes first. `source` is `promotion` or `support`, and `reason` is the record. `forgiveCredits` takes a debt off — all of it, or `amount` of it — when support lets a refunded spend go. Studio's **Purchases › Customers** gives credits too.

A balance that falls under its credit's `low_at` emits `purchases.credits.low`, once until it is back above; one that comes to nothing, `purchases.credits.depleted`.

## Limits

A limit is a quota counted in a window — `calendar_month`, `calendar_day` (from midnight in the project's time zone) or `billing_period` — with a free tier for everyone, and what each product gives on top: a customer gets the largest of their products'.

| Field of a limit's use | What it is |
|---|---|
| `limit` | The limit. |
| `max` | What this window allows them: the largest of their products, or the free tier — their own limit instead when one is set — plus what was granted them in the window. |
| `used`, `remaining`, `reserved` | What they used, what is left, what open holds keep. |
| `resets_at` | When the window ends. |

A limit is spent as credits are — `spend`, `holdSpend`, `withReservation` — naming `limit` instead of `credits`:

```ts
// src/modules/ai/quota.ts
import { Palbase } from "palbase/backend";

export async function countRequest(userId: string, requestId: string): Promise<void> {
  await Palbase.purchases.spend({
    path: { customer_id: userId },
    headers: { "Idempotency-Key": requestId },
    body: { limit: "ai_requests", amount: 1 },
  });
}
```

Past the window's `max`, a limit with `overflow` takes credits instead (`per_unit` of them a unit), and one without is refused: `409 limit_reached`. A hold counts in the window it was made in, even when it is committed after the window ends.

The refusal says what would give the customer more, for the app to offer: `upgrades` lists the entitlements whose products give more of the limit than the customer has now, the smallest step up first — empty when no product gives more.

```json
{
  "error": "limit_reached",
  "error_description": "the customer used this window's limit",
  "status": 409,
  "request_id": "req_…",
  "limit": "ai_requests",
  "upgrades": [{ "entitlement": "pro", "name": "Pro", "product": "pro", "max": 500 }]
}
```

`setCustomerLimit` gives one customer their own `max` — more for a customer support looks after, less for one who abuses it — until `expires_at` or `clearCustomerLimit`; `grantLimit` gives more units in the window it is in now. Each says why (`reason`).

A window used to 80% emits `purchases.quota.threshold`, and used to the end `purchases.quota.exhausted`, each once a window.

## Events

Each change of what a customer has emits an event to the project's webhooks and to a `palbase/backend` app's `@On` handlers ([Event Hooks](/docs/backend/hooks), [Webhooks](/docs/server/webhooks)):

```ts
// src/modules/premium/purchase-events.ts
import { Log, On, type PlatformEvent } from "palbase/backend";

export class PurchaseEvents {
  @On("purchases.subscription.changed")
  changed(event: PlatformEvent<"purchases.subscription.changed">): void {
    const { customer_id, product, change, store, expires_at } = event.data;
    if (change === "billing_issue") Log.warn("renewal not charged", { customer_id, product, store, expires_at });
  }
}
```

| Type | Sent when | `data` |
|---|---|---|
| `purchases.customer.changed` | Anything a customer has changed, and their revision rose. | `{ customer_id, revision }` |
| `purchases.entitlement.changed` | An entitlement turned on or off. | `{ customer_id, entitlement, active, expires_at, store, product, is_sandbox }` |
| `purchases.purchase.completed` | A purchase new to the ledger: a subscription's start or a one-time product, in any store. | `{ customer_id, chain_id, product, plan, store, is_sandbox }` |
| `purchases.subscription.changed` | A subscription `started`, `renewed`, was `canceled` or `uncanceled`, had a `billing_issue` or `recovered`, `expired`, or moved to another product (`product_changed`). | `{ customer_id, chain_id, change, product, plan, store, state, expires_at, will_renew, is_sandbox }` |
| `purchases.refund.changed` | A store took a payment back — a `refund`, a `chargeback`, Family Sharing ended (`family`) — or reversed that; its credits are taken back, or given back. | `{ customer_id, chain_id, transaction_id, kind, share_milli, reversed }` |
| `purchases.ownership.transferred` | A purchase moved to another customer: a restore, or another customer's new purchase on a store account they share (`via`). | `{ chain_id, from_customer_id, to_customer_id, product, store, via }` |
| `purchases.credits.low`, `purchases.credits.depleted` | A balance fell under its low mark, or to nothing. | `{ customer_id, currency, balance, available, debt, low_at }` |
| `purchases.quota.threshold`, `purchases.quota.exhausted` | A window was used to 80%, or to the end. | `{ customer_id, limit, used, max, percent, resets_at, window_id }` |
| `purchases.offer.redeemed` | A customer took an offer. | `{ customer_id, offer, kind, store, product, plan, chain_id, coupon, entitlement }` |
| `purchases.coupon.redeemed` | A customer redeemed a coupon. | `{ customer_id, coupon, offer, store, one_time }` |
| `purchases.customer.merged` | A guest's purchases went to the account it signed in to. | `{ from, into }` |
| `purchases.customer.erased` | A deleted user's purchases record was erased. | `{ customer_id }` |
| `purchases.catalog.changed` | A revision of the catalog was saved. | `{ revision }` |
| `purchases.catalog.applied` | A store's part of a plan was written, or failed. | `{ plan_id, revision, store, status }` |
| `purchases.paywall.published` | A paywall's draft was published. | `{ paywall_id, name, version, schema }` |
| `purchases.store.changed` | A store's connection was made, verified, checked or removed — never its key. | `{ store, change, … }` |

The customer's own apps hear of their changes on their realtime channel and read what they have again; the SDKs do it for you.

## Related

- [Customers](/docs/purchases/customers): one customer's page, grants, guests and settings
- [Catalog](/docs/purchases/catalog): the entitlements, credits and limits a product gives
- [Server SDK](/docs/server/overview): `createServer`, refusals as `PalbaseError`, retries
- [Event Hooks](/docs/backend/hooks): `@On` in a `palbase/backend` app



<!-- ===== purchases/customers ===== -->

# Customers

A **customer** is a user of the project — a guest included — and the customer's id is the user's id. There is nothing to create: a user becomes a customer when something is theirs, a purchase, a grant or credits, or when their app first reads what they have. What they have is the same answer in every app and on your server, whatever store they bought in ([Entitlements, Credits & Limits](/docs/purchases/entitlements#what-a-customer-has)).

## Finding a customer

A person writing in rarely has their user id. In Studio, **Purchases › Customers**, find them by what they do have:

- their user id;
- an id their store gave a purchase: Apple's original transaction id or any transaction id from their receipt, a Google Play order id (`GPA.…`, a renewal's `..0` or not), a Stripe subscription, payment intent, invoice or customer id;
- the email a buyer with no account gave at checkout on the web, written whole (case and spaces around it do not matter). The address itself is not kept: an HMAC of it under the project's key is, so it is found by the whole address and by nothing less. A purchase whose link no one has redeemed yet is found too, as no one's.

One customer found opens them; several are listed. From a terminal:

```sh
palbase purchases:customers 2000000873521946 -E production
palbase purchases:customers buyer@example.com -E production
```

From your server, `GET /purchases/customers?q=…` answers the same list (`customer_id`, `matched_by`, the store and product of the purchase found).

## Looking a customer up

Their record shows their entitlements and where each is managed, their subscriptions, one-time purchases, credits and quota, test purchases marked. From a terminal:

```sh
palbase purchases:customer:get 3f6c2a1e-8d4b-4c1a-9b7e-2a5d8c0f1b3e -E production
```

From your server, `getCustomer`:

```ts
// server/support.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

export async function describe(userId: string): Promise<string[]> {
  const { data } = await palbase.purchases.getCustomer({ path: { customer_id: userId } });
  return Object.entries(data.entitlements).map(
    ([key, e]) => `${key}: ${e.active ? "on" : "off"} (${e.store}${e.is_sandbox ? ", test" : ""}) until ${e.expires_at ?? "for life"}`,
  );
}
```

A guest merged into an account reads as the account. A user never seen here reads as a customer with nothing, and the read writes nothing.

## What happened to them

Their **History**, the newest first, a page at a time: each payment and renewal, a refund (and its kind: refund, chargeback, family sharing), the subscription's renewal turned off or back on, a failed charge, its end, the grants given and taken back, the credits given, taken back, expired and forgiven, the purchases that moved to or from them, what support did at a store (`extension`, `refund_issued`, `cancel_requested`, with its days, the expiry it left, the refund's kind and support's note), and a refund they asked the App Store for (`refund_requested`, with what Apple was told: `answer`) — each with when, who did it (`store`, `customer`, the developer whose Studio or CLI call it was as `developer:…`, or the key as `key:…`) and why. Credits spent are the credits' own entries (**Credits** on the record, or `GET …/credits/entries`).

```sh
palbase purchases:customer:history <user id> -E production
```

`GET /purchases/customers/{customer_id}/history` answers it to your server; `next_cursor`, sent back as `cursor`, is the next page.

## Giving an entitlement

Support gives one of the catalog's entitlements — for a promotion, a support case, a tester — for a while or for life, saying why:

```sh
palbase purchases:customer:grant <user id> pro --reason "Ticket 4821: billing mix-up" --for 30d -E production
```

The reason is the record (500 characters at most). Without `--for` or `--until` the grant is for life. Nothing is charged in any store, and a customer not seen before is made. Every grant a customer was given — active, ended and revoked, with who gave it, why, and who revoked it — is listed with its id, which ends it:

```sh
palbase purchases:customer:grants <user id> -E production
palbase purchases:customer:revoke <user id> <grant id> -E production
```

What the customer bought is not touched: the entitlement stays on while a purchase still gives it. Studio's **Purchases › Customers** lists, gives and revokes grants too — **Revoke** on a grant of the list; from a server they are `GET /purchases/customers/{customer_id}/grants`, `grantEntitlement` and `revokeGrant`.

In Studio every member of the project reads a customer, their history and their grants; giving or revoking a grant and giving credits is an admin's or the owner's. A grant shows as `store: "promotional"`, `period_type: "promotional"`; turning the entitlement on or off emits `purchases.entitlement.changed`.

Credits and quota are given the same way, saying why — [Entitlements, Credits & Limits › Giving credits](/docs/purchases/entitlements#giving-credits).

## A subscription, at its store

Support moves a subscription's renewal later, refunds it or turns its renewal off from the customer's page (the buttons on a row of **Subscriptions**), from a terminal, or from your server with the secret key. The subscription's id is the one the record lists (`subscriptions[].id`). The store is asked to do it, then read again: the answer is the subscription as its store holds it after, and the history keeps what was done, by whom, and the note.

| | App Store | Google Play | Web (Stripe) |
|---|---|---|---|
| **Extend** (1–90 days, for free) | Apple's renewal-date extension: a paid, active subscription, at most twice a year | The next renewal deferred | The next charge moved later |
| **Refund** (the latest payment, in full or what is left of its period) | Apple decides: `409 store_decides_refunds` | Revoked, refunded | Refunded, the subscription cancelled |
| **Turn the renewal off** | The customer's, in their Apple account: `409 customer_cancels` | Cancelled at the period's end | Cancelled at the period's end |

A refund ends the subscription and the customer's access as it answers; turning the renewal off leaves them the period they paid for.

```sh
palbase purchases:customer:get <user id> -E production            # the subscription's id
palbase purchases:customer:extend <user id> <subscription id> --days 7 --reason service_issue --note "Outage of the 21st" -E production
palbase purchases:customer:refund <user id> <subscription id> --mode prorated -E production
palbase purchases:customer:cancel <user id> <subscription id> -E production
```

`--reason` is `customer_satisfaction`, `service_issue` or `other`, as Apple asks it. From your server they are `extendSubscription`, `refundSubscription` and `cancelSubscription` (`POST /purchases/customers/{customer_id}/subscriptions/{subscription_id}/extend|refund|cancel`), each under an `Idempotency-Key`: sent again with it, it is done once. A store that refuses answers `409 store_refused` with what it said; one that cannot be reached, `502 store_unreachable` — sending again with the same key is safe.

## A refund the customer asks the App Store for

In the App Store the customer asks Apple for a refund (in the app with `Transaction.beginRefundRequest`, or at reportaproblem.apple.com). Apple then asks the app, within 12 hours, what they had of the purchase, and weighs the answer. The environment answers it for you — whether it gave what was bought, whether a free trial came first, how much of a pack of credits was spent — and says nothing of its own wish: the decision is Apple's.

It answers only for a customer who allowed it in the app; Apple takes no answer without that. Ask them once, where your app speaks of refunds or privacy, and record what they said:

```ts
// app/settings.ts
import { createClient } from "palbase/web";

const pb = createClient({ url: "https://<ref>.palbase.studio", publishableKey: "pb_<ref>_c…" });

export async function rememberRefundChoice(allowed: boolean): Promise<void> {
  await pb.purchases.setRefundDataConsent(allowed); // PUT /purchases/me/refund-data-consent
}
```

On iOS it is `pb.purchases.setRefundDataConsent(true)`, on Android `pb.purchases.setRefundDataConsent(true)`; the latest word counts, for every app of the project. Never asked, or `false`: Apple is told nothing. The customer's page shows what they said and when (`refund_data_consent` on the record), and the history every question Apple asked, with its `answer`: `sent`, `pending`, `not_consented`, or `expired` when Apple could not be reached in its 12 hours.

## Credit entries, debts and limits

The customer's page lists every move of their credits — given, spent, taken back by a refund, expired, forgiven — with who did each and why (`GET /purchases/customers/{customer_id}/credits/entries`). A refund of credits already spent leaves a debt, paid first from what they get next; support forgives it, all of it or an amount, saying why. A limit's maximum is set for one customer — above or below the catalog's, for a while or until cleared — and more of it given for its current period:

```sh
palbase purchases:customer:credits <user id> -E production
palbase purchases:customer:credits:give <user id> tokens 50 --reason "Ticket 4821" -E production
palbase purchases:customer:credits:forgive <user id> tokens --reason "Goodwill" -E production
palbase purchases:customer:limit:set <user id> ai_requests 500 --reason "Pilot" --for 30d -E production
palbase purchases:customer:limit:give <user id> ai_requests 20 --reason "A failed job" -E production
palbase purchases:customer:limit:clear <user id> ai_requests -E production
```

In Studio every member reads these; extending, refunding or cancelling a subscription, giving or forgiving credits and setting or giving a limit is an admin's or the owner's.

## Guests

A guest — a user signed in with no account, on one device — buys like anyone else: in the App Store, on Google Play, on the web, with a coupon. What a guest buys is theirs, and goes with them:

- **The guest becomes an account** (it signs up, adds a passkey, links a provider): it keeps its id, and everything it bought with it. Nothing to do.
- **The guest signs in to an account that already exists:** its purchases are handed over in two calls. With the guest's session, before signing in, the app asks for a proof (`POST /purchases/me/merge-grant`, good for 5 minutes); with the account's session, after, it spends it (`POST /purchases/me/merge`).

```ts
// app/sign-in.ts
import { createClient } from "palbase/web";

const pb = createClient({ url: "https://<ref>.palbase.studio", publishableKey: "pb_<ref>_c…" });

export async function signInKeepingPurchases(email: string, password: string): Promise<void> {
  const info = await pb.purchases.me();
  const grant = info.guest ? await pb.purchases.mergeGrant() : null;
  await pb.auth.signIn(email, password);
  if (grant) await pb.purchases.merge(grant); // the guest's subscriptions, purchases, grants, credits and quota use
}
```

The merge is one step and cannot be undone; asked again with the same proof, it is the same merge. From then on the guest's id points to the account: its session reads `409 customer_merged`. It emits `purchases.customer.merged`. The store ids the guest bought with — its `appAccountToken`, its obfuscated account id — go with it, so the stores' later notifications reach the account.

A guest may restore purchases, but never takes an account's (`403 restore_account_owned`): it signs in to that account instead. A grant offer is an account's unless a coupon opened it, and a coupon may be for signed-in customers alone.

## Restores and moved purchases

A store purchase stays the customer's it was bought by. Two things move it:

- **A new purchase on it by another customer.** When the app's accounts share one store account (a family's iPhone), a subscription follows who paid: in the App Store, a new purchase on it (a switch of plan, a resubscription, an offer bought) made with another customer's account token moves it to that customer, with the offer it was bought with. On Google Play every new purchase is a purchase of its own, so it is its buyer's from the start.
- **Restore purchases**, the customer's own action in the app, moves the store account's purchases to whoever restores, so a purchase made while signed in to another of the app's accounts follows the person. In the App Store this works only from the device StoreKit signed the purchase for, and never moves a purchase from an account to a guest.

One purchase moves at most 3 times in 30 days, the two counted together. Each move emits `purchases.ownership.transferred`. The project's backend reads a customer's moves, newest first, with what they have (`GET /purchases/customers/{customer_id}`, its `transfers`: who had the purchase, who has it since, how and when), and Studio shows them on the customer's page under **Purchases › Customers**. The customer's own apps never read them: `GET /purchases/me` names no other customer. See [App Store](/docs/purchases/app-store#what-the-environment-does-with-a-transaction) and [Google Play](/docs/purchases/google-play#what-the-environment-does-with-a-purchase).

## When a user is deleted

The user's purchases record is erased — and the guests merged into them — and their id is never a customer again (`purchases.customer.erased`). Their renewing web subscriptions stop renewing, keeping the period they paid, unless the settings say otherwise. A subscription bought in the App Store or on Google Play is the customer's to cancel there: no one else can.

## Settings

The project's choices for its customers' purchases, in Studio under **Purchases › Settings**, or with the secret key:

```ts
// server/settings.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

// Only the team's testers get anything from test purchases here; quotas' days begin in Istanbul.
await palbase.purchases.updateSettings({
  body: { sandbox_access: "allowlist", sandbox_allowlist: ["3f6c2a1e-8d4b-4c1a-9b7e-2a5d8c0f1b3e"], time_zone: "Europe/Istanbul" },
});
```

| Setting | Default | What it says |
|---|---|---|
| `sandbox_access` | `everyone` | Whether test purchases — the App Store's sandbox (where TestFlight and App Review buy), Xcode's, Google Play's license testers', Stripe's test mode — open entitlements and credits: for `everyone`, only the customers on `sandbox_allowlist` (`allowlist`, 1,000 at most), or `nobody`. App Review buys in the sandbox: limit them only while no build of the app is in review against this environment. |
| `cancel_on_delete` | `true` | Whether a deleted user's renewing web subscriptions stop renewing. |
| `time_zone` | `UTC` | Where the quotas' calendar days and months begin: an IANA name such as `Europe/Istanbul`. |
| `reporting_currency`, `store_commission`, `stripe_fee_bps`, `stripe_fee_fixed_micros`, `stripe_fee_fixed_currency`, `app_store_link_fee_bps`, `app_store_link_attribution_days` | `USD`, `standard`, 2.9% + 0.30 USD, 0%, 7 days | How the charts count money: see [Charts › Settings](/docs/purchases/charts#settings). |

`getSettings` reads them; a change touches only the fields it gives.

## Related

- [Entitlements, Credits & Limits](/docs/purchases/entitlements): what a customer has, and spending it
- [Charts](/docs/purchases/charts): what customers bought, over time
- CLI: [`purchases:customer:get`](/docs/cli/reference#palbase-purchasescustomerget), [`purchases:customer:grant`](/docs/cli/reference#palbase-purchasescustomergrant), [`purchases:customer:revoke`](/docs/cli/reference#palbase-purchasescustomerrevoke), [`purchases:customer:extend`](/docs/cli/reference#palbase-purchasescustomerextend), [`purchases:customer:refund`](/docs/cli/reference#palbase-purchasescustomerrefund), [`purchases:customer:cancel`](/docs/cli/reference#palbase-purchasescustomercancel)



<!-- ===== purchases/charts ===== -->

# Charts

The purchases module draws the project's revenue and subscription charts from its ledger — every purchase from every store, as the stores confirmed it. Each chart is computed when it is read, so a refund that arrives late, a renewal, a product change, a guest merged into an account or a change of the settings is in the next answer. Money is in one reporting currency.

In Studio, **Purchases › Charts** shows them, each with its definition, and the views of them the organization saved.

## Quick example

```sh
palbase purchases:charts:overview -E production
palbase purchases:charts:get mrr --resolution month --segment store -E production
palbase purchases:charts:get revenue --from 2026-09-01 --to 2026-09-30 --filter country:TR --revenue-type proceeds --csv --out palbase/revenue-tr.csv -E production
```

The overview is the project's figures at a glance: MRR, active subscriptions and active trials now; revenue, new customers and active customers over the last 28 days. From a server:

```ts
// server/report.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

const { data } = await palbase.purchases.getChart({
  path: { chart: "mrr" },
  query: { resolution: "month", segment: "store" },
});
console.log(data);
```

## The charts

`palbase purchases:charts` lists every chart with its definition — what it counts, over which period, and how refunds, product changes, resubscriptions and test purchases count — and the dimensions it is split by.

| | Charts |
|---|---|
| Revenue | `revenue`, `mrr`, `mrr_movement`, `arr`, `non_subscription_purchases`, `refunds`, `refund_rate` |
| Subscriptions | `active_subscriptions`, `active_subscriptions_movement`, `active_trials`, `active_trials_movement`, `new_trials`, `paid_subscriptions`, `churn`, `subscription_status`, `subscription_retention` |
| Customers | `new_customers`, `active_customers`, `initial_conversion`, `conversion_to_paying`, `trial_conversion`, `realized_ltv_per_customer`, `realized_ltv_per_paying_customer`, `cohort_explorer` |

A **flow** counts what happened in a period; a **snapshot** is the state at its end (now, for the period now is in); a **ratio** divides its measures; a **cohort** follows what began in a period over its ages. A period marked `*` in the CLI is not over: its value may still change.

## Reading a chart

| Flag | Parameter | What it does |
|---|---|---|
| `--from`, `--to` | `from`, `to` | The first and last day, `YYYY-MM-DD`, both included, at most two years apart. By default the last 30 days, 12 weeks or 12 months. |
| `--resolution` | `resolution` | `day` (the default), `week` (ISO weeks, Monday to Sunday) or `month`. Days are UTC. |
| `--segment` | `segment` | Splits the chart by `store`, `platform`, `country`, `product`, `plan`, `duration`, `sandbox`, `paywall` or `experiment`: the 20 largest values each a segment, the rest together as `(other)`. |
| `--filter` | `filter` | Keeps what has one of the values given, one `dimension:value` each: `--filter store:app_store --filter country:TR`. |
| `--revenue-type` | `revenue_type` | `gross` (what customers paid, the default), `net_of_taxes`, or `proceeds` (net of taxes and of the store's commission or Stripe's fee). |
| `--currency` | `currency` | Money in another currency, for this answer. |
| `--window-days` | `window_days` | The conversion charts' timeframe and the lifetime charts' customer lifetime, in days from a customer's first day. |
| `--cohort` | `cohort` | The cohort explorer's cohorts: `new_customers` (by their first day) or `new_paying_customers` (by their first payment). |
| `--sandbox` | `sandbox` | Counts test purchases too; segment or filter by `sandbox` to tell them apart. |
| `--csv` | `Accept: text/csv` | The chart as CSV, a row a segment and period; `--out` writes it under `palbase/`. A value that would start a spreadsheet formula (`=`, `+`, `-`, `@`) begins with a quote. |

**Money** is converted to the reporting currency at the European Central Bank's reference rate of the day it was paid; an amount in a currency the Bank does not publish is left out, and named. The ledger keeps what was paid as it was paid. The stores' commission and Stripe's fee are not in the ledger: proceeds are estimated with the [settings](#settings), and so are taxes a store did not state — the answer says what was estimated.

**Paywalls and experiments.** The `paywall` and `experiment` dimensions credit each subscription once, when its first purchase is recorded: to the paywall — and the experiment's variant — its owner saw first within the 7 days before buying. One that followed none is `none`, its renewals included.

A cohort chart follows at most 120 cohorts. A customer holding more than 20,000 transactions makes a chart refuse (`422 chart_too_large`).

### How often

The same request within a minute is answered from a cache, which a change of the settings clears. A project's charts are computed 20 in a row, then one every 2 seconds; past that a chart is refused with `429 too_many_charts` and `Retry-After` — an answer from the cache is not counted. A chart that takes longer than 15 seconds to compute is refused with `503 charts_busy` and `Retry-After`.

## Settings

How the charts count money:

```sh
palbase purchases:charts:settings --currency EUR --commission small_business -E production
```

| Flag | Setting | Default | What it is |
|---|---|---|---|
| `--currency` | `reporting_currency` | `USD` | The currency the charts report money in: one the European Central Bank published a rate for in the last ten days. Changing it redraws every chart from its first day. |
| `--commission` | `store_commission` | `standard` | What proceeds take off App Store and Google Play payments: `standard` (30%; 15% of a subscription's renewals after its first paid year in the App Store, and of every Google Play subscription) or `small_business` (15%: the App Store Small Business Program, Google Play's first million). |
| `--stripe-percent`, `--stripe-fixed`, `--stripe-fixed-currency` | `stripe_fee_bps`, `stripe_fee_fixed_micros`, `stripe_fee_fixed_currency` | 2.9% + 0.30 USD | Stripe's fee of a web payment, its share and its fixed part. |
| `--app-store-link-percent`, `--app-store-link-days` | `app_store_link_fee_bps`, `app_store_link_attribution_days` | 0%, 7 days | What the App Store takes of a web purchase bought through a link out of an iOS app in its United States storefront, and for how many days after the link a purchase owes it. Nothing today; set it once Apple charges one. |

Without flags, the command prints the settings. They are the purchases module's settings, also read and changed in Studio (**Purchases › Settings**) and with `updateSettings` ([Customers › Settings](/docs/purchases/customers#settings)).

## Related

- [Customers](/docs/purchases/customers): one customer's purchases
- [Paywalls](/docs/purchases/paywalls): a placement's and an experiment's own results
- CLI: [`purchases:charts:get`](/docs/cli/reference#palbase-purchaseschartsget), [`purchases:charts:settings`](/docs/cli/reference#palbase-purchaseschartssettings)



<!-- ===== messaging/overview ===== -->

# Messaging

Messaging is chat between a project's people: direct conversations and groups, with answers, threads, reactions, mentions, files, messages for later, messages that go after a while, photos seen once and vanish mode. It is a module every project has, like auth: there is no server to run. The web, iOS and Android clients keep each person's conversations on the device, current over the project's socket, so an app draws them and writes — sending, syncing and catching up are the client's.

- **Web**: `pb.messaging` ([Web Messaging](/docs/web/messaging))
- **iOS**: the `PalbaseMessaging` product ([iOS Messaging](/docs/ios/messaging))
- **Android**: `studio.palbase:palbase-messaging` ([Android Messaging](/docs/android/messaging))

## A person's history is their account's

What a person said and read is kept by the project, not by a phone. Signing out, deleting the app or opening it on a new phone loses nothing: when they sign in again, every conversation comes back from the server.

- **On the device.** Each client keeps a copy of the signed-in person's conversations so the app opens on them at once, without the network. When the person signs out, the copy is dropped, unless the app asks to keep it (`keepOnSignOut`). Kept or not, it is that person's alone: whoever signs in next on the same device never reads it — and, unless copies are kept, a person who signs in drops any another left there.
- **Written offline.** A message written without the network is drawn at once and waits in the device's outbox; it goes once the network is back — once, however often the app retries (each message carries its own `client_message_id`).
- **The socket drops.** What came meanwhile is read from the server's record of what changed for the person (`GET /messaging/sync`) as the socket comes back: nothing is missed.

## Kept encrypted

Every conversation has a key of its own, kept wrapped by the project's key: its messages' words, its title and its files' keys are stored sealed, and a copy of the database or a backup holds none of them in the clear. A file is encrypted on the device, with a key of its own, before it is uploaded: storage holds only what it cannot read. This is not end-to-end encryption: Palbase opens a conversation's messages to deliver them, your server reads them with the secret key, and your organization's owners and admins read them in Studio — each read recorded, with who read it ([Your server](#your-server)). Your team's members see the conversations and the reports, not what was said.

## What people do

- **Direct conversations and groups.** The direct conversation of two people is one, whoever opens it (`POST /messaging/conversations/direct`); a group has up to 1,000 members, an owner, admins, and policies for who writes, who adds people and who changes it.
- **Answers and threads.** A message answers another inline, or in its thread: one level deep, with its count of answers, its last one and who answered, each thread's unread count, and the threads a person follows (`GET /messaging/threads`). A thread's answer may be shown in the conversation too.
- **Changing what was said.** A message is edited within 15 minutes, and removed for everyone by its writer within 48 hours (by a group's admin at any time), or for oneself.
- **Reactions**, several a person to a message; **mentions**; **read receipts** and **typing**; **presence** (online, last seen).
- **Files**: pictures, videos, voice notes and any file, encrypted on the device.
- **For later.** A message scheduled for a time is sent then by the server, the writer's phone off or not; until then only its writer sees it, and may change or take it back. A scheduled message carries text alone.
- **Messages that go.** A conversation's timer (a day, a week, 90 days or any number of days) makes each new message go after it; a message of its own goes after its seconds, counted from when it was sent or from when everyone it was for read it. When a message's time is up it goes from the server and from every device.
- **Seen once.** A photo or a video sent to be seen once (or twice) opens for its seconds and is gone: its file's key is dropped on the server, and the app holds the opened bytes, never the device's copy.
- **Vanish mode** (a direct conversation's): a message read goes once its reader leaves the conversation.
- **Muting** a conversation, or its mentions alone: a muted one sends no push.
- **Blocking** a person: what they send does not reach whoever blocked them (to their writer it looks sent). **Reporting** a conversation, a person or messages: the report is the project's ([Moderation](#moderation)).

**Kept for a report.** What goes from people's screens without their choosing is kept on the server for 14 days, sealed as it was, for a report alone — Messenger reviews a deleted message reported within 14 days, Instagram keeps a vanish-mode message as long:

- a message seen once, its time up, in vanish mode, or taken back by its writer or a group's admin: one who saw it can still report it, and what it said, its files too, goes with the report. Only someone who was in the conversation when it went — and, for a photo or video seen once, who opened it — reports what it said;
- what an edited message said before each change: a report of the message shows its earlier versions, those changed while the reporter was in the conversation. The people in it see the last version alone;
- a group a person deleted — its owner or an admin, or the last to leave: it goes from everyone's list at once, and stays sealed 14 days; those who were in it, when it went or before, report it (the app has it as deleted until then), and the last 30 messages each saw go with their report. Then it is gone.

Nothing else reads what is kept, and after 14 days it is gone — even when the project's retention or a deleted account takes the message sooner: with `deleted_user_messages: delete`, a person deleting their account does not wipe what they took back before. Say so in your app's privacy policy. What the project itself removes — its server, its retention — is kept for nothing: a conversation the project's server deletes goes at once, a group still sealed too.

A person may hide their read receipts (`PATCH /messaging/me`, `read_receipts: false`): in direct conversations they then show no one what they read and see no one's; in groups receipts are always shown.

## Screenshots

A browser does not say when someone takes a screenshot, and a phone cannot always stop one:

| | A photo or video seen once | Vanish mode |
|---|---|---|
| **Android** | The screen is kept out of screenshots and recordings (`FLAG_SECURE`): they come out black | Taken, and the others are told |
| **iOS** | Taken (iOS cannot stop one), and the others are told | Taken, and the others are told |
| **Web** | Not known | Not known |

"Told" is a line in the conversation, as WhatsApp's and Instagram's (`POST /messaging/conversations/{conversation_id}/screenshot`). No app can stop a second phone's camera.

## Pushes and the app in front

A message to someone who is not in the app reaches them as a push, through the project's notifications ([Notifications](/docs/backend/notifications)): set up an APNs key and Firebase for the apps first. The push says who wrote and what (`push_preview: false` for "a new message" alone), the app's badge is the person's unread count, and a conversation's messages group together.

While the app is in front, a message's push is not drawn as the system's banner: the client tells the app instead (web `onIncoming`, iOS `incoming()`, Android `incoming`), and the app draws its own banner — none for the conversation already on the screen.

On iOS and Android, the push also brings the message into the device's copy while the app is closed: open it with no network and it is there. On iOS this is the `PalbaseMessagingNotificationService` extension and an App Group ([iOS Messaging](/docs/ios/messaging#messages-that-arrive-while-the-app-is-closed)); on Android, the push itself ([Android Messaging](/docs/android/messaging#messages-that-arrive-while-the-app-is-closed)).

## Your server

With the secret key, your server makes conversations for people, adds and removes them, says something in a conversation (a booking's confirmation, a support agent), removes a message, and reads what was said — for moderation, support or an export (`GET /messaging/admin/conversations/{conversation_id}/messages`; a file's link: `GET …/messages/{message_id}/attachments/{attachment_id}`, the file opened with the key in its message).

Your organization's owners and admins read the same in Studio (**Messaging › Conversations**, a person's conversations by their user ID) and with the CLI (`palbase messaging:conversations:list --user <id>`, `palbase messaging:messages:list <conversation_id>`). A member of your team sees the conversations, not what was said: the platform refuses them. Every read of people's messages — a file opened too — is recorded with who read it: a developer by name, a key or a token by its id. Studio's **Access log** and `GET /messaging/admin/access-log` (`palbase messaging:access-log`) list them, 400 days.

**Who may write to whom** is everyone, unless the project's hook says otherwise: set `hook` in the settings and the project's endpoint is asked, signed as a webhook is, before a direct conversation is opened or someone is added to a group — `messaging.can_message`, answering whether they may. When it does not answer, `on_error` says what happens: deny (the default; the app tries again) or allow.

## Moderation

A person reports a message, someone or a conversation from your app. What the reported messages say when reported — their files too, and a message already gone from the screen while it is kept for a report — is copied into the report, sealed, and kept with it whatever becomes of the message.

- **You hear of it**: the `messaging.report.created` event reaches your webhook, and your organization's owners and admins are mailed — at most once an hour for the whole organization, one mail with each environment's reports of the hour. The mail says how many and why, never what was reported; an organization that runs its customers' apps passes each report on to them from the event.
- **Studio**: **Messaging › Reports** lists them. An owner or admin opens one — its reporter's words, the messages and their files — removes the messages for everyone, and marks it resolved in their own words; a member sees the list alone. App stores expect reports to be looked at in good time.
- **The CLI**: `palbase messaging:reports:list`, `palbase messaging:reports:get <id>`, `palbase messaging:reports:resolve <id> --resolution removed`.
- **Your server**: `GET /messaging/admin/reports`, `GET /messaging/admin/reports/{report_id}` (a file's link: `…/attachments/{attachment_id}`), `POST /messaging/admin/reports/{report_id}/resolve`.

A report is kept 190 days once resolved — the EU's Digital Services Act keeps a decision open to complaint at least six months, and six calendar months reach 184 days — and two years when never resolved; its copies and files go with it.

## The project's settings

In Studio (**Messaging**), with the CLI (`palbase messaging:settings:set`, `palbase messaging:hook:set`; `palbase config:diff` and `palbase config:copy` compare and copy them between environments), or with the secret key (`GET` and `PUT /messaging/settings`):

| Setting | What it does |
|---|---|
| `retention_days` | Messages older are removed; none (the default): kept for good |
| `push_preview` | Pushes say what a message says (the default), or only that one came |
| `deleted_user_messages` | A deleted user's messages: `keep` (the default), their writer shown as a deleted user with nothing personal kept, or `delete` — save what went from screens before, kept its 14 days for a report |
| `hook` | Who may write to whom (above); none: anyone to anyone |

## What it costs

| | Free each month | Past it |
|---|---|---|
| Messages sent | 1 million | $5.25 a million |
| What the messages weigh where they are kept | 1 GiB | $1.05 a GiB-month |

A message weighs its sealed text and 768 bytes for its row and indexes: a GiB holds over a million short messages. Its files are the project's storage, its deliveries to people's sockets realtime messages, and its pushes push notifications — each on the bill as they are ([Usage & Limits](/docs/getting-started/usage-and-limits)). A message sent again with the same `client_message_id` is one.

A free project past either is slowed, never stopped: its messages go at about one a second, all its people together. A send waits its turn, 10 seconds at the most; one that would wait longer is `429 slowed` with `Retry-After`, and the clients keep it in their outbox and send it again. Reading, syncing and everything else go on at full speed.



<!-- ===== analytics/overview ===== -->

# Analytics

Every project has analytics: what people do in its apps, kept as events, and read back as counts, breakdowns, funnels, retention tables and each person's timeline. An app sends with the publishable key, through its SDK; a server sends and reads with the secret key; and Studio's **Analytics** screens show what was kept. Beside the events, analytics keeps how the apps run: timings measured on the devices, the requests they made, and a device's recent console history when something went wrong ([Performance](/docs/analytics/performance)).

Nothing needs to be turned on. The project's address takes events from its first request, and what an app may collect follows what its person allowed ([Consent](/docs/web/consent)).

## What is kept

| Kind | What it is | Sent by | Counted on the usage page as |
|---|---|---|---|
| Events | A capture (a name and its properties), a page view (`$pageview`), a screen view (`$screen`), an identify (`$identify`), an alias (`$alias`), and a person's properties set | An app's SDK; a server with the secret key | Analytics events (`analytics.events`) — all but setting a person's properties, which is not counted |
| Performance samples | App starts, screens, network calls, web vitals and custom measures, each a number | An app's SDK | `analytics.perf` |
| Request traces | One request as the app or a backend saw it: path, method, status, duration, error | An app's SDK; a `palbase/backend` app, one for each request it answers | `analytics.traces` |
| Console history | A device's recent log lines and network exchanges, sent when something went wrong: an error, a crash, a person's report | An app's SDK | `analytics.console` |

The platform adds events of its own to a person's timeline: a purchase, a push that reached their phone, a consent they changed, an audience they entered or left. `GET /analytics/catalog` lists every event a timeline can hold, the platform's with their fields and the app's own as they arrived.

Each event is given the place of the address it came from: its `country`, `region` and `city`. Places come from DB-IP's IP to City Lite database: IP geolocation by [DB-IP](https://db-ip.com), CC BY 4.0. An address says where its network is, not where the device is.

## Who did it

Every event is someone's, by a **distinct id**:

- **A signed-in user.** With the user's token beside the publishable key, the distinct id is the user's id, whatever the body says: a signed-in user's events are theirs however the app wrote them.
- **An anonymous visitor.** With no one signed in, the SDK makes an anonymous id for the browser or the install, and sends under it.
- **What a server names.** With the secret key, the distinct id is what the body says.

An **identify** ties the anonymous id a person had to the user they signed in as: their events before and after are one person's in funnels, retention and their timeline. The web SDK identifies on its own when someone signs in, and forgets the anonymous id when they sign out ([Web Analytics](/docs/web/analytics#pbanalytics)). An **alias** says two ids are one user (`POST /analytics/alias`, `{ from, to }`, the event kept under `to`).

A **person** is a user, with the anonymous ids identified as them, or an anonymous id no one has identified. `GET /analytics/people?query=…` finds one by any id they went by or their email, and `GET /analytics/people/{person_id}` is what is known of them: the ids, the installs their events came from, their properties, when they were first and last seen, and where their newest event came from. See [People](/docs/web/analytics#people) and [Audiences](/docs/web/analytics#audiences).

A **session** is the SDK's: half an hour without an event ends one, and each event carries its `session_id`.

## Sending from a server

A server sends with the secret key, naming whose the event is:

```ts
// server/orders.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

/** Kept in the person's timeline beside what their apps sent. */
export async function orderShipped(userId: string, orderId: string, items: number): Promise<void> {
  await palbase.analytics.capture({ body: { event: "order_shipped", distinct_id: userId, properties: { order_id: orderId, items } } });
}
```

In a `palbase/backend` app the same calls are `Palbase.analytics`. An event's name is a letter or `$`, then letters, digits and `_.:-$`, 64 characters at most; its properties are 100 at most, 8 KiB each as JSON and 32 KiB in all. The calls an app's SDK makes, their headers and their answers are on [Web Analytics](/docs/web/analytics#what-an-app-sends).

A `palbase/backend` app sends a request trace for every request it answers, in batches behind the answers, with the signed-in caller as its distinct id. Nothing is to be written for it: Studio's **Analytics › Network** shows them beside the apps' own ([Performance](/docs/analytics/performance#requests)).

## Consent

What an app's SDK collects follows the person's choices, key by key: events, page views, identifies and person properties go only with `analytics` granted; performance samples and request timings with `performance`, and without the person's id unless `analytics` is granted too. A key with neither the person's choice nor a starting value collects nothing. See [Consent](/docs/web/consent).

The choices are kept by the SDK, which holds back what was not allowed before it is sent; the analytics module keeps what it is sent. A server that sends about a person with the secret key sends what they agreed to.

## How long it is kept

| Setting | What it says | Default | Range |
|---|---|---|---|
| `retention_days` | How long events, performance samples and request traces are kept | 90 | 1 to 365 |
| `console_retention_days` | How long console history is kept | 14 | 1 to 30 |
| `perf_sample_pct` | The share of performance samples kept: the SDK samples at it before it sends, and the server again | 100 | 0 to 100 |
| `console_bodies` | Whether console history keeps request and response bodies; without it they are removed before anything is kept | `false` | |

A shorter retention removes what is older within minutes; a longer one keeps what is still there for longer. Every read is bounded by it: a window that reaches past the retention reads what is kept.

```sh
palbase analytics:settings:get
palbase analytics:settings:set retention_days=30 perf_sample_pct=10
```

A server reads them with `GET /analytics/settings` and changes them with `PUT /analytics/settings`, which takes all four ([CLI reference](/docs/cli/reference#analytics)).

**A deleted user's analytics go with them**: everything under any id they went by — their own, the anonymous ids identified as them, the ids aliased to those — and the events of their installs from while no one was signed in. They leave every audience and come back to none.

## Limits

- A project takes 1,000 events, samples, traces and console records a second, all kinds together. Past it, a send is `429 rate_limited` with `Retry-After`. What an app sends is counted against this, not against the project's requests per second.
- A batch of events is 100 at most and 3 MiB; of performance samples, 100 and 512 KiB; of console history, 500 records, 64 KiB each and 2 MiB in all.
- A send is answered once what it sent is kept: a `202` means the event will be there within seconds. A `503` kept nothing, and is sent again with the same `Idempotency-Key`, which keeps it once.
- When an environment has a limit set on one of the four kinds and the month's are used up, sending that kind is `429 quota_exceeded`, with `Retry-After` until the month ends ([Usage & Limits](/docs/getting-started/usage-and-limits)).

## Related

- [Reading Analytics](/docs/analytics/reading) — Studio's screens, summaries, breakdowns, funnels and retention
- [Performance](/docs/analytics/performance) — web vitals, app starts, requests and debug history
- [Web Analytics](/docs/web/analytics) — sending from the browser, people and audiences
- [Consent](/docs/web/consent) — the keys analytics follows



<!-- ===== analytics/reading ===== -->

# Reading Analytics

What a project's analytics kept is read in two places: Studio's **Analytics** screens, for the people of the organization, and the analytics module's read calls, with the project's secret key, for a server, a report or an agent. Both read the same rows, and neither reads past the project's retention ([How long it is kept](/docs/analytics/overview#how-long-it-is-kept)).

## In Studio

Each screen reads the environment it is opened in, over the period chosen at its top: the last 24 hours, 7, 30 or 90 days.

| Screen | What it shows |
|---|---|
| **Analytics** | The period's events, people, page views and events per person, its activity over time, then its most viewed pages and where their views came from, its most recorded events, its events by platform, OS version and app version, and by country |
| **Events** | How often the events you choose were recorded, hour by hour or day by day, and the latest events as they arrive, each with its person, session, time and properties |
| **People** | A person found by any id they went by or their email: every id, what they allowed, their properties and their whole timeline |
| **Audiences** | The people a rule picks, built a condition at a time, previewed before it is kept ([Audiences](/docs/web/analytics#audiences)) |
| **Event catalog** | Every event a timeline can hold: the platform's with their fields, and those your apps and backend sent in the last 30 days, each with a description your team writes |
| **Funnels** | Events in order, and how many people get from the first to the last within the time to convert, and where they leave |
| **Retention** | People by when they first did one event, and how many came back to do another, period by period |
| **Network** | Every request your apps and backend reported ([Performance](/docs/analytics/performance#requests)) |
| **Debug history** | What a device logged and sent before something went wrong ([Performance](/docs/analytics/performance#debug-history)) |

A member of the organization reads every screen; changing an audience or the catalog's descriptions is an admin's ([Organizations](/docs/getting-started/organizations#roles)).

## From a server

```ts
// server/weekly-report.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });
const WEEK = 7 * 24 * 3600;

const summary = await palbase.analytics.getSummary({ query: { window_seconds: WEEK } });
console.log(`${summary.data.total} events by ${summary.data.unique_users} people`);
for (const e of summary.data.events.slice(0, 5)) console.log(e.name, e.count);

const countries = await palbase.analytics.getEventBreakdown({ query: { by: "country", event: "purchase", window_seconds: WEEK, limit: 5 } });
for (const row of countries.data.rows) console.log(row.value || "unknown", row.events, row.users);

const funnel = await palbase.analytics.runFunnel({
  body: { steps: ["signup_started", "signup_completed", "checkout_started"], window_seconds: WEEK, conversion_window_seconds: 24 * 3600 },
});
for (const step of funnel.data.steps) console.log(step.step, step.name, step.users, step.conversion_rate);

const retention = await palbase.analytics.runRetention({
  body: { first_event: "signup_completed", return_event: "app_opened", period: "week", periods: 8, window_seconds: 8 * WEEK },
});
for (const row of retention.data.rows) console.log(row.cohort_start, row.cohort_size, row.returns);
```

In a `palbase/backend` app the same calls are `Palbase.analytics`. A publishable key is refused every read (`403`): an app sends, and only the project's server reads.

Every read takes `window_seconds`, how far back to look: an hour unless said, 400 days at most, and never past the project's retention. The answers that page say `next_cursor`, which the next call passes as `cursor`; the last page has none.

### Summary

`GET /analytics/summary` (`getSummary`): the window's events — `total`, by how many distinct ids (`unique_users`) — and its 50 most frequent names with their `count`. `window_seconds` in the answer is the window read, after the retention bounded it.

### Events

| Call | HTTP | Answers |
|---|---|---|
| `listEvents` | `GET /analytics/events` | A page of the window's events, newest first, each with its `event_id`, `name`, `distinct_id`, `session_id`, `timestamp` (corrected for the device's clock) and `properties`. `name`, `distinct_id` and `session_id` narrow it; `limit` is 100 unless said, 500 at most |
| `getEventTimeline` | `GET /analytics/events/timeline` | The window's events bucket by bucket, oldest first: `events` and `users` in each, `bucket_ms` its start (unix milliseconds, UTC). `bucket` is `hour` or `day`: hours for two days or less, days beyond, unless said; `name` narrows it to one event. A bucket with no event is not a row |
| `listEventNames` | `GET /analytics/event-names` | Every name the window's events had, 1,000 at most |

### Breakdown

`GET /analytics/breakdown` (`getEventBreakdown`) splits the window's events by one dimension, the most frequent value first: for each `value`, how many `events` had it and by how many distinct ids (`users`).

| `by` | Splits by |
|---|---|
| `platform`, `app_version`, `os_version` | What the app said of itself |
| `country`, `region`, `city` | Where the event came from: an ISO 3166-1 alpha-2 country, a province or state, a city or district |
| `event` | The event's name |
| `property:<key>` | One of the events' properties: letters, digits and `_ . $ -`, 64 at most |

An absent or empty value is `""`; a property that is not a string is its JSON (a number, `true`, an array). `event` narrows it to one event; `limit` is 10 unless said, 100 at most.

### Funnels

`POST /analytics/funnel` (`runFunnel`) counts how many people took each step, in order, each within `conversion_window_seconds` of their first step.

| Field | What it says | Default |
|---|---|---|
| `steps` | 2 to 10 event names, in order | — |
| `window_seconds` | How far back the first step may be | an hour |
| `conversion_window_seconds` | How long after the first step the last may be | an hour |
| `strict_order` | Any other of the funnel's events between two steps breaks the chain | `false` |

Each step answers its place (`step`, from 1), its `name`, the `users` who reached it and its `conversion_rate`: its share of the first step's. A person's anonymous events count with their signed-in ones once an identify joined them.

### Retention

`POST /analytics/retention` (`runRetention`) puts people in a cohort by the period in which they first did `first_event`, and counts how many of them did `return_event` in each period after.

| Field | What it says | Default |
|---|---|---|
| `first_event` | The event that puts a person in a cohort | — |
| `return_event` | The event that counts as coming back | — |
| `period` | `day`, `week` or `month` | `week` |
| `periods` | Periods followed after the cohort, 1 to 31 | 8 |
| `window_seconds` | How far back the cohorts start | 30 days |

The answer's `rows` are the cohorts, newest first: `cohort_start`, `cohort_size`, and `returns`, where `returns[0]` is the cohort's size and `returns[k]` the people back `k` periods later. `observable` says how many of the periods after have fully passed: a period still under way is not counted, so a young cohort's later columns are not zeros but not yet.

### People, the catalog and audiences

`GET /analytics/people`, `GET /analytics/people/{person_id}` and `GET /analytics/people/{person_id}/events` find a person, read what is known of them and their timeline; `GET /analytics/catalog` lists the events a timeline can hold; the audience calls make and read audiences. See [Web Analytics](/docs/web/analytics#people).

## From the CLI

```sh
palbase analytics:summary --window 7d
palbase analytics:events --name purchase --window 24h --limit 20
palbase analytics:events --user 3f2c9a1e-…    # one person's, newest first
```

`--window` takes `30m`, `24h`, `7d`; both commands read the environment chosen with `palbase use` or `-E` ([CLI reference](/docs/cli/reference#analytics)).

## Errors

| Status | When |
|---|---|
| `400` | A field breaks its rule: a funnel of one step, a `by` that is not one of the dimensions, a `periods` past 31 |
| `403` | Not the project's secret key |
| `429` | Over the project's requests per second; `Retry-After` says when |
| `503` | The read could not be answered now; asking again is safe |

## Related

- [Analytics](/docs/analytics/overview) — what is kept, whose it is, and for how long
- [Performance](/docs/analytics/performance) — timings, requests and debug history
- [Web Analytics](/docs/web/analytics) — sending, people and audiences
- [Server SDK Overview](/docs/server/overview) — calls, refusals, retries and paging



<!-- ===== analytics/performance ===== -->

# Performance

Beside its events, a project's analytics keeps how its apps run on real devices and browsers: **performance samples** (how long an app took to start, a page's web vitals, a request's time), **request traces** (each request as the app or your backend saw it), and **console history** (what a device logged and sent just before something went wrong). Studio shows them on three screens: **Performance**, **Analytics › Network** and **Analytics › Debug history**. They are kept, read and limited as events are ([Analytics](/docs/analytics/overview)), with console history kept for a time of its own.

## Performance samples

A sample is one number: a duration in milliseconds, or a web vital's own unit.

| Type | What it measures | Sent by |
|---|---|---|
| `web_vital` | A page's LCP, INP, CLS, FCP and TTFB | The web SDK, with `performance` allowed ([Web Analytics](/docs/web/analytics)) |
| `network` | One request the app made: its method and route, its time | The web SDK (each `fetch`), the mobile SDKs |
| `app_start` | How long a mobile app took to open | The mobile SDKs |
| `screen` | How long a screen took | The mobile SDKs |
| `custom` | Anything your code measures | The mobile SDKs |

A network sample's address is kept as its route: no query, and an id in the path is `:id`. Samples go without the person's id unless `analytics` is allowed too.

`perf_sample_pct` keeps a share of the samples, 100 unless changed. The SDKs read it (`GET /analytics/perf/config`, answered `304` while it has not changed) and sample at it before they send, and the module samples again, so a share of 10 sends and keeps about one sample in ten. A send answers how many samples were kept and how many dropped (`{ accepted, dropped }`): a bad shape, a time more than 7 days off, or one not sampled in is dropped, and that is not an error.

### In Studio

**Performance** has a tab for each type: **Network**, **App start**, **Web vitals** and **Custom**. Each lists the type's samples by name with their median (p50), p95, p99 and how many there were; a name chosen draws its percentiles over the period. A web vital is banded as Google bands it — LCP is good at 2.5 s or less and poor past 4 s, INP at 200 ms and 500 ms, CLS at 0.1 and 0.25, FCP at 1.8 s and 3 s, TTFB at 800 ms and 1.8 s — and the screen breaks the slowest 5% down by OS and by app version, and compares the same sample with another environment of the project.

### From a server

| Call | HTTP | Answers |
|---|---|---|
| `listPerfGroups` | `GET /analytics/perf/client` | The window's samples grouped by type and name and one more dimension (`group_by`: `name`, `app_version`, `platform` or `os_version`): `p50`, `p75`, `p95`, `p99` and `sample_count`, the most sampled first. `trace_type` and `name` narrow it |
| `getPerfTimeline` | `GET /analytics/perf/timeline` | One type's samples (`trace_type`, required) bucket by bucket, oldest first: `p50`, `p75`, `p95` and `sample_count`. A percentile is always of one type: an app start's milliseconds and a CLS score are never added together |

```ts
// server/vitals.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

const lcp = await palbase.analytics.listPerfGroups({ query: { trace_type: "web_vital", name: "LCP", group_by: "app_version", window_seconds: 7 * 86400 } });
for (const row of lcp.data.rows) console.log(row.key, Math.round(row.p75), "ms at p75 over", row.sample_count, "samples");
```

## Requests

A request trace is one request as one side saw it: its `endpoint`, `method`, `status`, `duration_ms`, its error when it failed, and the request id the platform gave it. `source` says whose report it is:

- **`client`**: the app's. The mobile SDKs report each request they make; the web SDK's network samples are read here too, in the same shape.
- **`backend`**: your backend's. A `palbase/backend` app reports every request it answers, with its route as declared (`/orders/{id}`) and the signed-in caller, in batches behind the answers ([Analytics](/docs/analytics/overview#sending-from-a-server)).

The app's report and the backend's of one request share its request id, so the two sides of a request are read together, and the difference between them is often where the time went.

**Analytics › Network** lists the requests newest first, filtered by status, method, endpoint, latency, source and user (**Errors only**, **Server errors** and **Slow >100ms** are ready-made), with the period's requests, its share of server and client errors, its median and its slowest 5%, and the requests by status and latency over time. A request opens with its hops, every report of it from either side; a session opens as a waterfall of its requests in order. **Live on** follows new requests as they arrive.

| Call | HTTP | Answers |
|---|---|---|
| `listTraces` | `GET /analytics/traces` | A page of the window's requests, newest first. `endpoint`, `source`, `method`, `status`, `status_class` (`2xx` … `5xx`), `duration_min_ms`, `duration_max_ms`, `distinct_id` and `request_id` narrow it |
| `getTraceSummary` | `GET /analytics/traces/summary` | The whole window's requests with the same filters, not a page's: counts by status class, `error_rate`, and the median, p95 and p99 durations |
| `getTraceTimeline` | `GET /analytics/traces/timeline` | The summary bucket by bucket, an hour's or a day's, oldest first |
| `getTraceHops` | `GET /analytics/traces/by-trace` | Every report of one request, by its trace id or its request id, in order; 500 at most |
| `listSessionTraces` | `GET /analytics/traces/session` | A page of one session's requests, in the order they happened |

These are what your apps and backend reported. Every request to the project's address, as the platform answered it, is in [Logs](/docs/getting-started/logs), and a machine's requests over time are on its page ([Machines](/docs/machines/overview)).

## Debug history

When something goes wrong on a device — an error, a crash, or the person reporting a problem — the mobile SDKs send what the app logged and the network exchanges it made just before: up to 500 records, 64 KiB each, 2 MiB in all, kept whole or not at all. Nothing is sampled away. **Analytics › Debug history** shows the records newest first, logs and requests in one stream, filtered by person and session; each says what made the device send it (`error`, `crash` or `user_report`).

Request and response **bodies** are kept only when the project says so (`console_bodies`, off unless changed): otherwise they are removed before anything is kept, and the record says they were. Console history is kept 14 days unless changed (`console_retention_days`, 1 to 30).

```sh
palbase analytics:settings:set console_bodies=true console_retention_days=7
```

Keep bodies only when you need them: a request's body can carry what a person typed, a token, a card's last digits.

| Call | HTTP | Answers |
|---|---|---|
| `listConsoleRecords` | `GET /analytics/console-records` | A page of the window's records, newest first, each as the SDK wrote it (JSON), and `retention_days`. `user` and `session` narrow it |
| `getConsoleConfig` | `GET /analytics/console-breadcrumbs/config` | Whether bodies are kept now (`bodies_enabled`) and why (`enabled`, `disabled`, or `unavailable`: the setting could not be read, and bodies are not kept), and an upload's limits |

## Related

- [Analytics](/docs/analytics/overview) — what is kept, for how long, and the settings
- [Reading Analytics](/docs/analytics/reading) — events, funnels and retention
- [Web Analytics](/docs/web/analytics) — the browser's own measures
- [Logs](/docs/getting-started/logs) — every request to the project's address



<!-- ===== apps/overview ===== -->

# Client Apps

An app is one product on one platform that calls the project: an iOS app, an Android app or a web app. You register it once in the project, then say what it is in each environment: its bundle on iOS, its package and signing certificates on Android, its origins on the web. From that, each environment gives the app a publishable key of its own, publishes the files Apple and Google read before an app may use the environment's passkeys, and learns which sites may call it and where a sign-in may return to.

Apps are registered with the CLI, or with Studio's API as the CLI does. Studio lists each app's key, by its last characters, under **Settings › API keys**, but has no screen to register an app.

## Quick example

```sh
# Once per project.
palbase apps:create ios "Shop" --team-id ABCDE12345
palbase apps:create android "Shop Android" --slug shop-android
palbase apps:create web "Shop Web"

# In each environment the app runs against.
palbase apps:env:set shop --bundle com.acme.shop -E main
palbase apps:env:set shop --bundle com.acme.shop.staging -E staging
palbase apps:env:set shop-android --package com.acme.shop --sha256 play_signing=AB:CD:EF:… --sha256 debug=12:34:56:… -E main
palbase apps:env:set shop-web --origin https://shop.example.com --redirect https://shop.example.com/auth/callback -E main

# Write the settings into the app's repository, from its root.
palbase apps:sync shop
```

The first `apps:env:set` in an environment prints the app's publishable key there. `palbase apps:sync` writes the app's settings and its backends' clients under `palbase/` in its repository: [Syncing an App's Settings](/docs/apps/sync).

## Registering an app

```sh
palbase apps:create ios|android|web <name> [--slug <slug>] [--team-id <id>] [--app-id-prefix <prefix>]
```

| | |
|---|---|
| Name | What it is called, 1 to 100 characters. `palbase apps:update <app> --name <name>` renames it. |
| Slug | Its name in a checkout and on the command line: `palbase/environments/<env>/<slug>.json`. Lower-case letters, digits and dashes, starting with a letter, 2 to 40 characters; made from the name unless `--slug` gives it. One per project. |
| Platform | `ios`, `android` or `web`, for good. The same product on another platform is another app. |
| Apple team | An iOS app's: `--team-id`, the 10 characters under **Apple Developer › Membership**. Required. `--app-id-prefix` only when the app's App ID prefix is not the team's: an app made before 2011, or one moved from another team. |

An app's widgets, notification service and other extensions are not apps of their own. Apple gives them bundles under the app's, and they share its sign-in.

A registered app is in no environment yet. `palbase apps:list` lists the project's apps with what each is in every environment; `palbase apps:get <app>` shows one, with its publishable key in each. The `apps:` commands name an app by its slug or its id. The id is a UUID, printed with `--json` and kept in the app's settings; the [App Distribution](/docs/distribution/overview) commands take it.

## What an app is in an environment

```sh
palbase apps:env:set <app> [--bundle <id> [--app-clip <id>] [--watch <id>]] [--package <id> --sha256 <label>=<fingerprint>…] [--origin <url>… --redirect <url>…] -E <env>
```

| Platform | Flags | What is checked |
|---|---|---|
| iOS | `--bundle`; `--app-clip`, `--watch` | A bundle identifier (`com.acme.shop`). An App Clip's and a watch app's bundle is the app's followed by one more part (`com.acme.shop.Clip`): Apple installs them under no other. |
| Android | `--package`; `--sha256 <label>=<fingerprint>`, once per certificate | The application ID, and the SHA-256 of every certificate the app is signed with, as Play Console and `keytool` print it (hex, with or without colons). A label is a short lower-case name: `play_signing`, `upload`, `debug`. At most 20 certificates. |
| Web | `--origin`, `--redirect`, each given again for more (or comma-separated) | 1 to 20 origins and at most 20 redirects. |

On Android, the certificate that matters on a device is the one the installed build is signed with: Google's app signing key for a build from Play (**Play Console › App signing**, not the upload key), and your debug key for a build from your computer (`./gradlew signingReport`). Give each.

A web origin is `https://` and a domain name a passkey can be used from: a registrable one, written in ASCII (punycode for an international name), with a port when it is not 443 and no path. `http://` is taken only for `localhost` or a loopback address. A redirect is an `https` address (`http` only on this computer) without a fragment; a wildcard in its host names part of one site's names, `https://*-preview.example.com/**`, never a whole site.

Setting an app again replaces what it is in that environment; its key stays. A value that is not one of these is refused with the field and why (`400 invalid_app`). The environment also refuses:

- a bundle, package or origin another app of the same platform has in the environment (`409 identity_taken`): Apple, Google and the browser could not tell the two apart;
- web origins across the environment's web apps on more than five registrable domains (`409 too_many_web_domains`): a browser takes related origins from five at most and skips the rest without a word;
- a 51st app in the environment (`409 too_many_apps`).

The same bundle, package or origin in two environments is said, not refused. Two builds can then not be installed side by side, and a device with both mixes their sign-ins: Apple and Google suggest a bundle of its own per environment.

`palbase apps:env:unset <app> -E <env>` takes the app out of one environment: its key there is revoked, and the environment's files stop naming it.

## Its publishable key

Each app has its own publishable key in each environment it is set in, `pb_<ref>_c…`, made the first time it is set there. It is a publishable key like any other: it ships in the app, its role is `anon`, and the signed-in user's token decides whose data a request reaches ([The keys](/docs/getting-started/introduction#the-keys)).

- **It is kept, not shown once.** Every copy of the app carries it, so `palbase apps:get <app>` prints it, `palbase apps:sdkconfig <app> -E <env>` prints the environment's settings with it, and `palbase apps:sync` writes it into the checkout.
- **An app has one live key.** `palbase keys:list` names it `app: <name>`. Revoking it (`palbase keys:revoke <key id>`) refuses the old key from then on and gives the app a new one in the same step, which `apps:sync` and `apps:sdkconfig` hand out. A build that carries the old key stops reaching the environment until it is rebuilt.
- One app's key is replaced, or taken out of an environment, without touching another app's.

The environment also has the publishable key it was made with, and any made under **Settings › API keys › Create publishable key** (`palbase keys:create --kind publishable`). Those are shown once, when they are made.

## What the environment publishes

Every environment serves three files at its address, `https://<ref>.palbase.studio`, with no key, the way Apple, Google and browsers fetch them:

| Path | What it holds | Who reads it |
|---|---|---|
| `GET /.well-known/apple-app-site-association` | `webcredentials.apps`: `<App ID prefix>.<bundle>` for each iOS app, its App Clip and its watch app | iOS, before the app may use the environment's passkeys |
| `GET /.well-known/assetlinks.json` | One statement per Android app with a certificate: `delegate_permission/common.get_login_creds` for its package and the SHA-256 of each certificate | Android's Credential Manager, before the app may use the environment's passkeys and saved passwords |
| `GET /.well-known/webauthn` | `origins`: the web apps' `https` origins, sorted | A browser on one of those sites, before it uses a passkey whose relying party is the environment's address |

Each answers `200` with `application/json` and `Cache-Control: public, max-age=300`, and an empty list when the environment has no such app, so a device that is not associated says "not associated" rather than failing to fetch. Universal Links and App Links are not claimed: links on the environment's address are not an app's to open.

Apple's CDN caches its file: an iOS device sees a change in a day or so. Android 15 checks again within a week. The app's own half on iOS is the **Associated Domains** entitlement `webcredentials:<ref>.palbase.studio`, which its settings name in `auth.associated_domains` ([iOS SDK](/docs/ios/overview#connect-the-app-to-the-project)).

## What else an app decides

| Platform | What the environment does with it |
|---|---|
| iOS | Accepts App Attest keys from the app and its watch app (an App Clip attests as its app). Matches an App Store purchase, and a purchase made in Xcode with its StoreKit file, to the registered bundle. The app's settings name the keychain group its sign-in is kept in: `<App ID prefix>.<bundle>.palbase`. |
| Android | Accepts a passkey ceremony from the app as signed with one of its certificates, and a device's attested key from the app as signed with one of them ([Device attestation](/docs/backend/authentication#device-attestation)). Reads a Google Play purchase the app reports from Play under its package. |
| Web | Accepts a passkey ceremony from its `https` origins. Starts every [machine](/docs/machines/overview) of the environment with its origins, and a `palbase/backend` app answers their browsers' cross-origin requests by itself ([Calling Your Backend](/docs/web/backend-calls)); a change rolls the machines out again with the new list. Adds its redirects to the addresses an auth email's link may return to ([Web Auth](/docs/web/auth#where-email-links-land)). |
| Every platform | A web checkout's `success_url` and `cancel_url` return to a web app's origin, or to an iOS or Android app's own scheme: its bundle or its package. |

While App Attest is in `monitor` or `enforce` in an environment, its last iOS or Android app cannot leave it, by `apps:env:unset` or `apps:delete`: a gate with no app would refuse every client. Turn App Attest off there first (`palbase auth:settings:set app_attest_mode=off -E <env>`).

## Deleting and restoring an app

```sh
palbase apps:delete shop
palbase apps:restore shop
```

A deleted app is suspended in every environment for 30 days: its keys are refused and the environments stop publishing it, so every build of it stops reaching the project at once. `apps:delete` asks first; `-y` confirms without asking. `palbase apps:restore` brings it back as it was, with the same keys, until the 30 days are out. Then it is removed for good, its keys revoked. `apps:list` shows a deleted app with the day it is removed, and `apps:sync` refuses to write a checkout that builds it meanwhile.

`palbase apps:update <app> --team-id <id>` moves an iOS app to another Apple team, and `--app-id-prefix ""` sets its prefix back to the team's; every environment it is in is told.

## Who can do what

| | Registers, changes, deletes apps | Reads apps and their settings |
|---|---|---|
| A member of the organization | — | Yes |
| An admin, signed in or with an admin [access token](/docs/getting-started/access-tokens) | Yes | Yes |
| An environment token | — | Its own environment's alone, with the `apps:sync` scope or none |

An admin access token registers a product's apps with no one signed in, as a Firebase service account adds an app. Studio's API, which the CLI calls:

| Call | What it does |
|---|---|
| `GET /v1/projects/{id}/apps` | The project's apps, each with what it is and its key in every environment |
| `POST /v1/projects/{id}/apps` | Registers one: `{ "platform", "name", "slug"?, "team_id"?, "app_id_prefix"? }` |
| `GET`, `PATCH`, `DELETE /v1/projects/{id}/apps/{app}` | Reads, changes (`name`, `team_id`, `app_id_prefix`) or deletes one |
| `POST /v1/projects/{id}/apps/{app}/restore` | Restores a deleted one |
| `PUT /v1/environments/{ref}/apps/{app}` | What it is in the environment: `{ "ios": { "bundle", "app_clip"?, "watch"? } }`, `{ "android": { "package", "fingerprints": [{ "label", "sha256" }] } }` or `{ "web": { "origins": [], "redirects"? } }`; the answer has its key and any `warnings` |
| `DELETE /v1/environments/{ref}/apps/{app}` | Takes it out of the environment |
| `GET /v1/environments/{ref}/apps/{app}/config` | Its settings in the environment, as `apps:sdkconfig` prints them |

`{id}` is the project's id, `{ref}` the environment's, `{app}` the app's id.

## Related

- [Syncing an App's Settings](/docs/apps/sync): what `palbase apps:sync` writes into the app's repository
- [App Distribution](/docs/distribution/overview): an app's builds to TestFlight and Google Play
- [Web Auth](/docs/web/auth#passkeys): passkeys from a web app
- [CLI reference: `apps`](/docs/cli/reference#apps)



<!-- ===== apps/sync ===== -->

# Syncing an App's Settings

`palbase apps:sync` writes into an app's repository what the app is built with in each environment it is set in: the environment's address, the app's [publishable key](/docs/apps/overview#its-publishable-key), what the modules tell a client, and a typed client of each backend the environment runs. It writes under `palbase/` and touches nothing outside it. The build reads those files, so nothing reaches the network when the app is built, and a URL or key is never typed into the app.

## Running it

From the repository's root, name the apps it builds:

```sh
palbase apps:sync shop-web
```

The apps named join the checkout's, which `palbase/project.json` records. After that, `palbase apps:sync` with no name syncs them all. One checkout may build several apps: a web app and its admin site, or an iOS and an Android app side by side.

Run it again whenever the project changes: the app set in a new environment, its key replaced, a machine added, a backend's routes or gateways changed. Each file is made whole from what the project gives now and compared with the one on disk; only a file that differs is written. A file it made that the project no longer gives, such as an environment the app left or a machine removed, is deleted. Commit what it writes.

Each run prints what it added, changed and removed, and notes what needs you: an app in no environment yet, a machine with no contract to make a client from, the keychain entitlement an iOS app needs.

## What it writes

```text
palbase/
├── project.json
├── shop-web.ts                     web: the editor's environment
├── shop-web.main.ts                web: one per environment
├── shop-web.staging.ts
├── shop.palbase                    iOS: every environment, as Swift
├── palbe/
│   ├── backend.ts                  web: the editor's environment
│   ├── backend.main.ts
│   └── backend.staging.ts
└── environments/
    ├── main/
    │   ├── shop-web.json
    │   ├── shop-web.ts
    │   ├── shop.json
    │   ├── contracts/backend.openapi.json
    │   └── palbe/backend.ts
    └── staging/
        └── …
```

| File | For | What it holds |
|---|---|---|
| `palbase/project.json` | every checkout | The project's id and name; the checkout's apps (id, slug, name, platform); the editor's environment (`types_environment`); the backends' names in the apps (`clients`) |
| `palbase/environments/<env>/<app>.json` | every app | [The app's settings](#the-apps-settings) in that environment |
| `palbase/environments/<env>/contracts/<machine>.openapi.json` | an environment with a backend | The contract the machine's serving build answers |
| `palbase/environments/<env>/palbe/<machine>.ts` | a web app | The backend's typed client, in TypeScript |
| `palbase/environments/<env>/palbe/<machine>.kt` | an Android app | The backend's typed client, in Kotlin |
| `palbase/<app>.palbase` | an iOS app | Each environment's configuration and its backends' clients, in Swift: one file, which the Xcode build rule reads for the build's environment |
| `palbase/environments/<env>/<app>.ts` | a web app | The app's settings module: `settings`, `connect()` and `pb`, the client typed with the environment's backends |
| `palbase/<app>.ts`, `palbase/palbe/<machine>.ts` | a web app | The editor's environment, re-exported |
| `palbase/<app>.<env>.ts`, `palbase/palbe/<machine>.<env>.ts` | a web app | Each environment's, which a build made for it is type-checked against |

`palbase/environments/` and `palbase/palbe/` are the sync's own: a file there that it would not write is removed, except a `.storekit` file, which [`palbase purchases:storekit`](/docs/purchases/testing-apple) makes. At the top of `palbase/` it touches only `project.json`, `.palbase` files and files that start with its header, `// Code generated by palbase apps:sync`. When `palbase/`, or a folder or file in it, is a symbolic link, it writes nothing.

## The app's settings

`palbase/environments/<env>/<app>.json` is the document `palbase apps:sdkconfig <app> -E <env>` prints:

```json
{
  "schema": 1,
  "project": { "id": "0b9c4e7a-…", "name": "Shop" },
  "environment": { "ref": "k3xq81w4m", "slug": "staging", "name": "Staging", "production": false },
  "app": { "id": "4f6c2d10-…", "name": "Shop Web", "slug": "shop-web", "platform": "web", "web": { "origins": ["https://staging.shop.example.com"] } },
  "url": "https://k3xq81w4m.palbase.studio",
  "publishable_key": "pb_k3xq81w4m_c…",
  "auth": { "rp_id": "k3xq81w4m.palbase.studio", "associated_domains": ["webcredentials:k3xq81w4m.palbase.studio"] },
  "realtime": { "url": "wss://k3xq81w4m.palbase.studio/realtime/v1" },
  "backends": [{ "machine": "backend", "url": "https://k3xq81w4m.app.palbase.studio", "contract_digest": "9e1f…" }],
  "digest": "sha256:5b2a…"
}
```

| Field | What it is |
|---|---|
| `environment.production` | `true` for the project's first environment, `main` |
| `app` | The app, with what it is in this environment (`ios`, `android` or `web`) |
| `url`, `publishable_key` | What the app's client is made with: the environment's address and the app's own key |
| `keychain_group` | An iOS app's: `<App ID prefix>.<bundle>.palbase`, the keychain access group the app and its extensions keep the sign-in in |
| `auth` | The passkeys' relying party, and the iOS app's Associated Domains entry |
| `backends` | The environment's machines: each one's address, and the digest of the contract its serving build answers (none while it is unread) |
| `digest` | The SHA-256 of the document without this field: a build made with another digest is not current |

An iOS app needs the **Keychain Sharing** capability with the group `$(AppIdentifierPrefix)$(PRODUCT_BUNDLE_IDENTIFIER).palbase` in every target that uses Palbase: without it the SDK keeps no session, and sign-in fails with `keychain_unavailable`. The sync reminds you each run.

`--format env` prints the address and key alone, for a build that does not read `palbase/` (another framework, a game engine):

```sh
palbase apps:sdkconfig shop-web --format env -E staging
```

```text
PALBASE_URL=https://k3xq81w4m.palbase.studio
PALBASE_PUBLISHABLE_KEY=pb_k3xq81w4m_c…
```

The publishable key is public: it ships in the app. A secret key never does, and no file the sync writes holds one.

## A build and its environment

The settings of every environment are in the checkout; the build picks one.

- **Web.** An app imports `pb` from `palbase/<app>.ts`. For the editor, that is one environment's: `--types <env>` names it, `palbase/project.json` remembers it, and without one it is the first environment the app is in that is not `main`. A build imports its own environment's instead: the Vite plugin from `palbase/web/vite`, `palbase({ app: "shop-web", environments: { development: "staging", production: "main" } })`, maps each `vite --mode` to an environment and type-checks the app against that environment's backends first. See [Calling Your Backend](/docs/web/backend-calls).
- **iOS.** The Xcode build rule extracts the Swift of the environment its configuration's `PALBASE_ENVIRONMENT` names from `palbase/<app>.palbase`; a configuration that names none, or one the app is not set in, stops the build. See [iOS SDK](/docs/ios/overview#connect-the-app-to-the-project).
- **Android.** The app's `build.gradle.kts` maps each build variant to an environment and compiles that environment's `<app>.json` and Kotlin clients into the variant's sources; a variant that names no environment, or one the app is not set in, stops the build. See [Android SDK](/docs/android/overview#the-environment-in-the-build).

## Backends

Each machine of the environment becomes `pb.<name>` in its apps, typed from the contract its serving build answers: its routes, their models and typed errors, and its [gateways](/docs/web/gateways). The name is the machine's camelCased, `pb.shopApi` for the machine `shop-api`, unless `--as shop-api=shop` names it otherwise. A name is the checkout's, the same in every environment, kept in `palbase/project.json`, and never one of the client's own (`auth`, `flags`, `storage`, …).

- A machine whose contract has not been read yet gets no client, and the run says so. A contract is read once the build's version alone serves: a `palbase/backend` app writes its own; for another program, [`palbase machines:update <machine> --openapi-path <path>`](/docs/cli/reference#palbase-machinesupdate) names where it serves one.
- When a push's version did not roll out (its contract was refused, its tests failed), the client is made from the build that serves, and the run says so.
- Two backends of one environment that declare the same type, both with a `HealthController` say, cannot share one Swift or Kotlin target: the run stops (`backends_collide`) and names it.

`--backend [<machine>=]<dir>` makes a backend's client from its checkout on this computer instead, to call a route before any machine serves it. The CLI runs `bun --no-env-file run src/main.ts` there with `PALBASE_CONTRACT_OUT` set: the `palbase/backend` app writes its contract and exits, connecting to nothing and reading no `.env` file. Sync again without `--backend` once the backend is deployed.

## In CI

```sh
palbase apps:sync --check
```

`--check` writes nothing. It exits 1 when the committed files are not what the project gives now, and lists each file as missing, differing or no longer given.

An environment token sees its own environment alone, so a sync made with one writes that environment's files and counts every other environment's as no longer given. For a checkout of several environments, run the check with an organization's [access token](/docs/getting-started/access-tokens) of the member role.

## When it refuses

| Code | Why |
|---|---|
| `another_project` | The checkout's `palbase/` is another project's. Run it for that project (`-P`), or in this project's own checkout. |
| `app_deleted` | The app is [deleted](/docs/apps/overview#deleting-and-restoring-an-app); `palbase apps:restore` brings it back. |
| `no_such_app` | The project has no app by that slug or id; the answer lists its apps. |
| `environments_collide` | Two environments' slugs differ only in letter case: their folders would be one on macOS and Windows. |
| `linked_path` | `palbase/` or a folder in it is a symbolic link. |
| `unusable_contract` | A backend's contract makes no client in the app's language: fix the backend, deploy it, and sync again. |
| `invalid_backend_name` | An `--as` name is a word the client or the language keeps. |

## Related

- [Client Apps](/docs/apps/overview): registering an app and setting it in an environment
- [Calling Your Backend](/docs/web/backend-calls) and [Web Gateways](/docs/web/gateways): `pb.<backend>` in a web app
- [CLI reference: `apps:sync`](/docs/cli/reference#palbase-appssync) and [`apps:sdkconfig`](/docs/cli/reference#palbase-appssdkconfig)



<!-- ===== distribution/overview ===== -->

# App Distribution

App Distribution takes the builds your build machine makes to your testers: an iOS app's to TestFlight, an Android app's to Google Play's internal testing track. Your build machine makes an unsigned build with a build number the environment gives it and uploads it. Palbase signs it, hands it to Apple or Play with your own account, follows it until testers can install it, and gives it to the groups you name. No signing certificate, provisioning profile or keystore lives on the build machine, and no Apple ID signs in there.

It is the environment's stores module. Studio shows it under **App Distribution**, and the CLI's `stores` commands do the same: `palbase stores:deliver`, `palbase stores:groups`, …

## How a build reaches testers

1. **Register the app** and set it in the environment: [Client Apps](/docs/apps/overview).
2. **Connect the store**, once per environment: an App Store Connect API key ([TestFlight](/docs/distribution/testflight#connect-app-store-connect)), or a service account Palbase makes for you to invite in Play Console ([Google Play](/docs/distribution/google-play#connect-google-play)).
3. **Link the app to its store** (`palbase stores:apps:link <app id>`). An iOS app's bundle id is registered with Apple and its App Store Connect record looked up; an Android app gets the upload key Palbase signs its builds with.
4. **Make a package** (`palbase stores:packages:create`). It answers the build number to build with and a token to upload the build.
5. **Build and upload it** (`palbase stores:packages:upload`): the unsigned `.ipa`, or the `.aab`.
6. **Deliver it** (`palbase stores:deliver`). It is signed, handed to Apple or Play, processed, and given to the testers.

Steps 1 to 3 are done once. A build machine runs 4 to 6 on every build.

## From a build machine

A CI job with an organization's [access token](/docs/getting-started/access-tokens) of the admin role as `PALBASE_TOKEN`:

```sh
set -euo pipefail
APP_ID=4f6c2d10-…   # palbase apps:get shop --json prints it

pkg=$(npx palbase stores:packages:create "$APP_ID" --command-id "$CI_RUN_ID" --notes "$GIT_SHA" \
  --entitlements-file entitlements.json -E main -y --json)
PACKAGE=$(echo "$pkg" | jq -r .id)
BUILD_NUMBER=$(echo "$pkg" | jq -r .build_number)
export PALBASE_UPLOAD_TOKEN=$(echo "$pkg" | jq -r .upload.token)

# Your build, unsigned, with that number: CFBundleVersion on iOS, versionCode on Android.
# TestFlight and Google Play below show one each.
./build-unsigned.sh "$BUILD_NUMBER"   # writes build/Shop.ipa

npx palbase stores:packages:upload "$PACKAGE" --file build/Shop.ipa -E main -y
npx palbase stores:deliver "$PACKAGE" --groups "Beta" --what-to-test "$(git log -1 --format=%s)" -E main -y
```

- **The command id** names the request: the CI run's id. The same id again answers the same package, with a new upload token while it still waits for its build, so a job that is run again does not use up another build number.
- **The upload token** is printed once, works for six hours and no longer than the access token, and only the newest one handed out works. `PALBASE_UPLOAD_TOKEN` keeps it out of the process list. The file goes straight to the environment's address with it; a second upload of the same build counts as uploaded.
- **`-y`** confirms a change to the project's production environment, `main`, without asking. Every command that changes it asks first, and in a job that cannot answer it refuses (`confirmation_needed`).

Reading the module is a member's; making a package, uploading, delivering and every other change is an admin's. The few steps Apple cannot undo wait for a person: see [Actions](#actions).

## Packages

A package is one build of one app: the build number the environment handed out, the build once it arrived, and its deliveries.

| Field | What it is |
|---|---|
| `build_number` | Above every build number App Store Connect or Play has for the app, and every one the environment handed out for it. The build must say it: an iOS build's `CFBundleVersion`, an Android build's `versionCode`. |
| `status` | `awaiting_upload` until the build arrives, then `uploaded` |
| `version` | What the build says it is, once it arrived: `CFBundleShortVersionString`, or the Android `versionName` |
| `bundles` | An iOS build's app and each extension, App Clip and watch app in it, by bundle id |
| `sha256`, `size` | The uploaded file's |
| `notes` | What `--notes` kept with it: a commit, a branch |
| `deliveries` | Where it went, and where each delivery is now |

A package is made for a linked app (`404 app_not_linked` otherwise), and an iOS app's needs its App Store Connect record (`409 app_record_missing`): the build number is read from App Store Connect, or from Play once the environment is connected to it.

An upload is refused, and the package keeps waiting for the right file, when the build is not the app's (another bundle id or package, `wrong_bundle`) or says another build number (`wrong_build_number`). An `.ipa` is 2 GiB at most. One upload of a package runs at a time, and two of an environment's at once; the CLI waits and sends again when the module says it is busy. An upload ends within an hour and keeps up 256 KiB a second on average after its first minute.

A build is kept 90 days, as long as TestFlight keeps one. `palbase stores:packages` lists the newest packages (`--app` for one app's), and `palbase stores:packages:get <package id>` shows one.

## Deliveries

`palbase stores:deliver <package id>` sends a package to its app's channel: `testflight` for an iOS app, `play_internal` for an Android app. It answers at once; `palbase stores:deliveries <package id>` and Studio follow it.

| Status | What is happening |
|---|---|
| `queued` | Waiting its turn: an environment's builds are signed and handed over one at a time |
| `signing` | Palbase signs the build |
| `uploading` | Palbase hands it to App Store Connect, or to Play |
| `processing` | Apple processes it |
| `compliance` | Apple waits for the build's [export compliance](/docs/distribution/testflight#export-compliance) answer |
| `ready` | Testers can install it: TestFlight gave it to the groups named, or Play took it on the internal testing track |
| `failed` | It stopped. `error_code` says why and `error` what to do |

Sending a package again restarts a delivery that failed and changes nothing about one under way. An environment has 10 deliveries under way at most (`429 too_many_deliveries`).

What stops a delivery, by `error_code`, is on [TestFlight](/docs/distribution/testflight#when-a-delivery-fails) and [Google Play](/docs/distribution/google-play#when-a-delivery-fails). Beside those:

| `error_code` | What to do |
|---|---|
| `build_changed` | The kept build is not the one uploaded: upload it again as a new package. |
| `build_gone` | The build is no longer kept (90 days): upload it again as a new package. |
| `step_timed_out` | Signing or handing it over took more than 45 minutes: send it again. |
| `gave_up` | Several tries in a row failed; `error` names the reference the cause is kept under. |

## Actions

What changes something at Apple for good is planned first and runs only when a person confirms it: sending a build to Beta App Review, answering a build's export compliance question, expiring a build, and on the [App Store](/docs/distribution/app-store) writing an app's page, sending its version to App Review, withdrawing it, releasing it and changing its phased release. A plan holds a summary of exactly what it does and a hash of it.

```sh
palbase stores:beta-review <package id>        # plans it, prints its id and hash
palbase stores:actions --status planned
palbase stores:actions:confirm <action id> --hash <hash>
palbase stores:actions:decline <action id>
```

A confirmation names the hash of the plan that was shown, runs it once, and only within a day of planning. It is a person's: a signed-in CLI or Studio's **App Distribution › Actions**, where planned actions wait under **Waiting for you**. An access token, an environment token or the secret key alone is refused (`403 person_required`), so a build machine plans and a person confirms. The CLI shows what the action does and asks before it runs, in every environment; `-y` confirms without asking. Declining needs no person.

## In Studio

**App Distribution**, under **Release** in an environment:

| Tab | What it holds |
|---|---|
| Overview | The Apple account and the Google Play connection (connect, check again, disconnect), the linked apps (**Link an app**), and packages made per week |
| Packages | Every package, newest first. A package's page sends it (**Send to TestFlight**, **Send to internal testing**, **Send again**), follows its deliveries, gives it to a group (**Give to a group**), changes what testers read (**Edit what to test**), plans **Send to Beta App Review**, **Answer export compliance** and **Expire the build**, and downloads an Android package's **Signed bundle** |
| Groups | An iOS app's groups of testers: make, rename, delete, set their testers |
| Actions | What waits for a person's yes, and what was done, declined or failed |
| TestFlight | An iOS app's test information for Beta App Review, and what testers sent back |
| Health | An iOS app's App Store Connect webhook (**Ping**, **Make again**), testers' crashes and screenshots, and the App Store's crash data; an Android app's Play vitals ([App Health](/docs/distribution/health)) |
| App Store | An iOS app's App Store page (each language's text, its categories and screenshots), planned and confirmed, and the version App Review gets: what is missing, **Send to App Review**, **Withdraw from App Review**, **Release** and the phased release |

## Events

Every change emits a `stores.*` event to the environment's [webhooks](/docs/server/webhooks) and to a backend's [`@On` handlers](/docs/backend/hooks):

| Event | When |
|---|---|
| `stores.apple.changed` | The Apple account was connected, checked (and Apple's answer changed) or disconnected. Never the key. |
| `stores.google.changed` | The Play connection was made, checked (and Play's answer changed) or disconnected |
| `stores.app.changed` | An app was linked to its store, or its App Store Connect record made or removed with the [Apple ID](/docs/distribution/app-store#an-apple-id) |
| `stores.package.changed` | A package was made, or its build arrived |
| `stores.delivery.requested` | A delivery was sent, or sent again |
| `stores.delivery.changed` | A delivery moved: `queued`, `signing`, `uploading`, `processing`, `compliance`, `ready` or `failed` |
| `stores.group.changed` | A group was made, renamed or deleted, its testers set, or a build given to it |
| `stores.action.changed` | An action was planned, done, declined or failed |
| `stores.version.changed` | An app's App Store version came to a new state: sent to App Review, in review, approved, rejected, withdrawn, released. `source` says who told it: `apple_webhook`, `poll` or `action` |
| `stores.apple.session.changed` | An [Apple ID](/docs/distribution/app-store#an-apple-id) was signed in, or signed out. Never the session. |
| `stores.apple.session.expired` | Apple ended the Apple ID's session: sign in again |
| `stores.review.message` | App Review wrote in the app's Resolution Center: the text, the guidelines it names, its attachments (with an Apple ID signed in) |

What the stores tell of an app — its App Store Connect webhook, its build uploads, Beta App Review, testers' feedback, its in-app purchases' review, its Play releases and its crash data — is on [App Health](/docs/distribution/health#the-events).

```ts
// src/modules/releases/release-events.ts
import { Log, On, type PlatformEvent } from "palbase/backend";

export class ReleaseEvents {
  @On("stores.delivery.changed")
  moved(event: PlatformEvent<"stores.delivery.changed">): void {
    const { package_id, channel, status, error_code, error } = event.data;
    if (status === "failed") Log.warn("a delivery stopped", { package_id, channel, error_code, error });
    if (status === "compliance") Log.info("a build waits for its export compliance answer", { package_id });
  }
}
```

```ts
// src/modules/releases/releases.module.ts
import { Module } from "palbase/backend";
import { ReleaseEvents } from "./release-events";

@Module({ providers: [ReleaseEvents] })
export class ReleasesModule {}
```

## From a server

The module's API is the environment's, at its address under `/stores`, with the secret key: `createServer(…).stores` in any server, `Palbase.stores` in a `palbase/backend` app, the same calls the CLI makes (`listPackages`, `getPackage`, `deliver`, `listDeliveries`, …). Confirming an action is the one call it cannot make: that is a person's.

## Related

- [TestFlight](/docs/distribution/testflight): the Apple account, signing, groups, Beta App Review
- [App Store](/docs/distribution/app-store): the App Store page, the version, App Review and the release
- [Google Play](/docs/distribution/google-play): the Play connection, the upload key, internal testing
- [App Health](/docs/distribution/health): the App Store Connect webhook, testers' crashes, the stores' crash data and their events
- [Test Apple Purchases](/docs/purchases/testing-apple): sandbox testers and purchases in TestFlight
- [CLI reference: `stores`](/docs/cli/reference#stores)



<!-- ===== distribution/testflight ===== -->

# TestFlight

An iOS app's builds go to TestFlight with your own Apple account. Your build machine uploads an unsigned `.ipa`. Palbase registers each bundle's id, turns on the capabilities its entitlements need, makes its App Store profile, signs it with the account's distribution certificate, uploads it to App Store Connect, waits for Apple to process it, and gives it to your groups of testers. The certificate's private key never leaves Palbase, and no Apple ID signs in on the build machine.

The steps that change something at Apple for good (Beta App Review, the export compliance answer, expiring a build) are planned and wait for a person to confirm them: [Actions](/docs/distribution/overview#actions).

## Connect App Store Connect

In App Store Connect, **Users and Access › Integrations › App Store Connect API**, make a key with the **App Manager** role or above, and download its `.p8` file (Apple lets you once). The page shows the issuer id.

```sh
palbase stores:apple:connect --key-file AuthKey_ABC123DEF4.p8 --issuer-id 57246542-96fe-1a63-e053-0824d011072a -E main
```

The key's id is read from the file's name. The CLI asks Studio for a one-time grant alone and posts the key with it to the environment's own address: the key never goes through Studio. `--print-link` prints a page that takes the key in a browser instead, good for 30 minutes and once. In Studio, **App Distribution › Overview › Connect Apple account** opens the same page.

The environment checks the key with Apple and keeps it sealed with its own data key. `palbase stores:apple` then shows the account:

| | |
|---|---|
| Status | `active`; `agreement` — Apple refuses every call until the Account Holder accepts the account's agreements in **App Store Connect › Business**; `refused` — Apple does not accept the key |
| Reaches | What the key's role reached when it was last checked: `apps`, `certificates`, `testflight`, `users`. Apple refuses whatever needs a missing one. |

After the agreements are accepted, or the key's role changed, `palbase stores:apple:check` asks Apple again. `palbase stores:apple:disconnect` forgets the key for good; Apple keeps the apps and builds.

The key is the environment's, connected once per environment. The same key puts a [purchases](/docs/purchases/testing-apple) catalog in App Store Connect and manages the team's sandbox testers.

## Link the app

```sh
palbase stores:apps:link 4f6c2d10-… --name "Shop" -E main
```

The app is one of the project's [registered apps](/docs/apps/overview), by its id, set in this environment with its bundle. Linking registers the bundle id on the Apple account when it is not, under `--name` (folded to letters, digits and spaces; the bundle id when absent), and looks up the app's App Store Connect record.

Apple's API cannot make that record. Make it once at **App Store Connect › Apps › +** with the same bundle id, then link the app again: `palbase stores:apps` shows `no record yet` until then, and a package cannot be made for the app (`409 app_record_missing`). Linking again also refreshes the bundle id.

## Make the build

```sh
pkg=$(palbase stores:packages:create 4f6c2d10-… --command-id "$CI_RUN_ID" --entitlements-file entitlements.json -E main -y --json)
```

Its answer holds the package's `id`, its `build_number` and the upload token (`upload.token`), read as [the build machine's script](/docs/distribution/overview#from-a-build-machine) reads them. The build number is above every build App Store Connect has for the app. Build with it as `CFBundleVersion`, for the app and every extension in it, and leave the build unsigned. One way, with Xcode:

```sh
xcodebuild archive -project Shop.xcodeproj -scheme Shop -configuration Release \
  -destination 'generic/platform=iOS' -archivePath build/Shop.xcarchive \
  CURRENT_PROJECT_VERSION="$BUILD_NUMBER" CODE_SIGNING_ALLOWED=NO
mkdir -p build/Payload
cp -R build/Shop.xcarchive/Products/Applications/Shop.app build/Payload/
(cd build && zip -qry Shop.ipa Payload)
```

`CURRENT_PROJECT_VERSION` becomes `CFBundleVersion` when the targets' Info.plist takes it from that setting, as Xcode's projects do. The `.ipa` holds exactly one `Payload/<name>.app`.

```sh
palbase stores:packages:upload "$PACKAGE" --file build/Shop.ipa -E main -y
```

The upload is checked before it is taken, and refused otherwise: one app in `Payload/` (`not_an_ipa`), the app's bundle id, with every bundle inside it under it (`com.acme.shop.widget`, `wrong_bundle`), the package's build number as `CFBundleVersion` (`wrong_build_number`), and a `CFBundleShortVersionString` (`no_version`), whose value is yours to set.

### Entitlements

An unsigned build carries no entitlements, so the build machine says what each bundle asks for, by bundle id, in `--entitlements-file`: the app and each extension, App Clip and watch app.

```json
{
  "com.acme.shop": {
    "aps-environment": "production",
    "com.apple.developer.associated-domains": ["webcredentials:k3xq81w4m.palbase.studio"],
    "keychain-access-groups": ["$(AppIdentifierPrefix)com.acme.shop.palbase"]
  },
  "com.acme.shop.widget": {
    "keychain-access-groups": ["$(AppIdentifierPrefix)com.acme.shop.palbase"]
  }
}
```

A target's `.entitlements` file is that object in another form: `plutil -convert json -o - Shop/Shop.entitlements` prints it. `$(AppIdentifierPrefix)` and `$(TeamIdentifierPrefix)` are resolved as Xcode resolves them when it signs.

The bundle is signed with what it asks for, bounded by what its profile grants:

- Palbase turns on each capability an entitlement needs on the bundle id (Push Notifications, Associated Domains, Sign in with Apple, App Groups, iCloud, HealthKit, …) and makes the profile again when one was added.
- What Apple's API cannot assign is yours to assign once at developer.apple.com: an App Group, an iCloud container, a merchant id or a pass type id on the bundle id. Until then the delivery fails with `manual_step`, naming the bundle and the value.
- `application-identifier`, the team identifier, `get-task-allow`, `beta-reports-active` and `aps-environment` always come from the profile.

### The certificate

The first delivery makes an Apple Distribution certificate on the account, with a private key Palbase keeps sealed. It is the account's: every environment connected to the same account uses that one certificate, each after reading it from Apple with its own key. When Apple revokes it, or it is about to expire, a new one is made.

Apple lets an account hold only a few distribution certificates. When it holds as many as Apple allows, made elsewhere, the delivery fails with `certificate_limit`: revoke one you no longer use at **developer.apple.com › Certificates**, and send the package again.

## Send it to TestFlight

```sh
palbase stores:deliver "$PACKAGE" --groups Beta --what-to-test "The new checkout" -E main
palbase stores:deliveries "$PACKAGE" -E main
```

The delivery goes `queued`, `signing`, `uploading`, `processing`, then `ready`, when TestFlight has the build and the groups named have it. Studio's package page shows the same, and **Send to TestFlight** sends it from there.

### Export compliance

TestFlight gives a build to no tester until its export compliance question is answered. A build whose Info.plist sets `ITSAppUsesNonExemptEncryption` has answered it; for any other, the delivery stops at `compliance`. The answer is the person's legal statement:

```sh
palbase stores:export-compliance "$PACKAGE" --uses-non-exempt-encryption no -E main
palbase stores:actions:confirm <action id> --hash <hash> -E main
```

`no` says the app uses no encryption beyond HTTPS and what iOS provides. Once the plan is confirmed, the delivery goes on to `ready`. In Studio, **Answer export compliance** on the package's page plans it, and **Actions** confirms it.

### What testers read

`--what-to-test` sets the note with the delivery. `palbase stores:what-to-test:set <package id> --text <text>` changes it once Apple holds the build (`409 build_not_at_apple` before), in the app's primary locale or `--locale`'s: 4000 characters at most.

## Groups and testers

A group is an app's testers, as a pair of TestFlight groups: an internal one for the account's App Store Connect users, who get a build at once, and an external one for everyone else, who get it after Beta App Review.

```sh
palbase stores:groups:create 4f6c2d10-… Beta -E main
palbase stores:groups:testers:set <group id> --emails ada@example.com,grace@example.com -E main
palbase stores:groups:add-build <group id> "$PACKAGE" -E main
```

| Command | What it does |
|---|---|
| `palbase stores:groups <app id>` | The app's groups, with how many testers each holds |
| `palbase stores:groups:testers:set <group id>` | Who the group holds, whole: those not named leave it. `--emails`, or `--file` with one tester a line (`email` or `email,First,Last`) or a JSON array; `-` reads stdin. 100 at most. Apple mails each new tester. |
| `palbase stores:groups:testers <group id>` | Its testers, and which TestFlight group serves each (`internal` or `external`) |
| `palbase stores:groups:add-build <group id> <package id>` | Gives the group a package TestFlight has. `stores:deliver --groups` does it as the delivery is ready. |
| `palbase stores:groups:rename <group id> <name>` | Renames it and its TestFlight groups |
| `palbase stores:groups:delete <group id>` | Deletes it and its TestFlight groups: its testers keep what other groups gave them |

## Beta App Review

External testers get a build only after Apple's Beta App Review. Apple reads the app's test information first:

```sh
palbase stores:review-info 4f6c2d10-… -E main
printf '%s' "$DEMO_PASSWORD" | palbase stores:review-info:set 4f6c2d10-… \
  --description "Sign in, add an item to the cart and check out." --feedback-email beta@example.com \
  --contact-first-name Ada --contact-last-name Lovelace --contact-phone "+44 20 7946 0000" --contact-email ada@example.com \
  --demo-account-name reviewer@example.com --demo-password-stdin -E main
```

`stores:review-info` shows what App Store Connect holds, in the app's primary locale or `--locale`'s, and what is still missing: `beta_description`, `feedback_email`, `contact_first_name`, `contact_last_name`, `contact_phone`, `contact_email`, `demo_account`. Only the fields given are written. The demo account's password is read from stdin, never the command line, and never read back: only whether it is set. Studio's **App Distribution › TestFlight** holds the same form.

Then plan the review of a package TestFlight has, and confirm it:

```sh
palbase stores:beta-review "$PACKAGE" -E main
palbase stores:actions:confirm <action id> --hash <hash> -E main
```

A plan is refused, with what is missing, while the test information is incomplete.

## Expiring a build, and feedback

`palbase stores:expire <package id>` plans expiring the package's build in TestFlight: once confirmed, no tester can install it.

`palbase stores:feedback <app id>` lists the newest feedback testers sent from TestFlight: screenshots with their comments, and crashes. Studio shows it under **App Distribution › TestFlight**.

## When a delivery fails

| `error_code` | What to do |
|---|---|
| `apple_agreement` | The Account Holder accepts the account's agreements in **App Store Connect › Business**; then `palbase stores:apple:check` and send again. |
| `apple_key_refused` | Apple no longer accepts the connected key: connect a new one. |
| `certificate_limit` | The account holds as many distribution certificates as Apple allows, made elsewhere: revoke one at developer.apple.com and send again. |
| `app_record_missing` | Make the app's record in App Store Connect with its bundle id, link the app again and send again. |
| `manual_step` | Assign the App Group, iCloud container, merchant id or pass type id it names to the bundle id at developer.apple.com, then send again. |
| `capability_missing` | A bundle asks for an entitlement its profile does not allow: add the capability to the bundle id at developer.apple.com, then send again. |
| `not_an_ipa` | The file is not one app in `Payload/`: build it again and upload it as a new package. |
| `build_number_taken` | App Store Connect has a build of this version and number that this delivery did not upload, from Xcode or another environment on the account: make a new package, which takes the next number. |
| `upload_failed`, `processing_failed` | App Store Connect did not take the build; `error` has Apple's words, and Apple's email to the account says why. |
| `apple_refused` | Apple refused a step; `error` has its words. |

The general ones (`build_changed`, `build_gone`, `step_timed_out`, `gave_up`) are on the [overview](/docs/distribution/overview#deliveries).

## Related

- [App Distribution](/docs/distribution/overview): packages, deliveries, actions and events
- [Test Apple Purchases](/docs/purchases/testing-apple): sandbox testers, and buying in TestFlight
- [iOS SDK](/docs/ios/overview): the app's settings, capabilities and client
- [CLI reference: `stores`](/docs/cli/reference#stores)



<!-- ===== distribution/app-store ===== -->

# App Store

An iOS app's App Store page and the version App Review gets are managed from the environment, with your own Apple account. You keep the page as a draft, language by language, with its screenshots. Palbase plans what changes at App Store Connect, and writes it only once you confirm the plan. You prepare the version (its build, release, review details), send it to App Review, and release it. Each of those steps is a plan you confirm too.

You need an iOS app [linked to the App Store](/docs/distribution/testflight#link-the-app), with its App Store Connect record, and the environment's [App Store Connect key](/docs/distribution/testflight#connect-app-store-connect) with the **App Manager** role or above. Studio shows all of it under **App Distribution › App Store**.

## The page

The draft is the environment's: what you want the page to be. Nothing in it is at Apple until a plan of it is confirmed.

```sh
palbase stores:listing:get 4f6c2d10-… --out palbase/store/listing.json -E main
```

```json
{
  "primary_category": "PRODUCTIVITY",
  "secondary_category": "UTILITIES",
  "locales": {
    "en-US": {
      "name": "Shop",
      "subtitle": "Groceries in a tap",
      "description": "Shop keeps your list and orders from the store near you.",
      "keywords": "groceries,list,shopping",
      "promotional_text": "Same-day delivery is here.",
      "whats_new": "A faster checkout.",
      "privacy_policy_url": "https://shop.example.com/privacy",
      "support_url": "https://shop.example.com/help",
      "marketing_url": "https://shop.example.com",
      "screenshots": { "iphone_6_9": ["screens/home.png", "screens/cart.png"] }
    }
  }
}
```

Edit the file, then save it on the revision `stores:listing:get` printed:

```sh
palbase stores:listing:put 4f6c2d10-… --file palbase/store/listing.json --revision 3 -E main
```

A language is App Store Connect's code (`en-US`, `tr`, `de-DE`). A field you leave empty is not written, and a language the draft does not have is left as App Store Connect holds it.

| Field | What it is |
|---|---|
| `name` | The app's name in the language, 2 to 30 characters |
| `subtitle` | Under the name, 30 characters at most |
| `description` | What the app does, 4000 characters at most |
| `keywords` | Comma-separated search words, 100 bytes at most |
| `promotional_text` | Above the description, 170 characters at most. It changes without a new version. |
| `whats_new` | An update's notes. The app's first version has none. |
| `privacy_policy_url`, `support_url`, `marketing_url` | http(s) addresses |
| `primary_category`, `secondary_category` | App Store categories: `PRODUCTIVITY`, `UTILITIES`, `GAMES` … |

Two people can edit the page at once. The second save is refused (`409 listing_moved`), never written over the first: read the page again, make your edit on it, and save with its revision.

### Screenshots

Each display takes up to 10 screenshots, PNG or JPEG, 10 MB at most, in the order the App Store shows them:

| Display | Sizes (portrait, or turned) |
|---|---|
| `iphone_6_9` | 1320×2868, 1290×2796 or 1260×2736 |
| `iphone_6_5` | 1242×2688 or 1284×2778 |
| `ipad_13` | 2064×2752 or 2048×2732 |

The draft names a screenshot by its SHA-256. `stores:listing:put` takes a file instead, a path from the draft's file under `palbase/`: it uploads each one first and saves its SHA-256 in its place. To upload without saving:

```sh
palbase stores:screenshots:upload 4f6c2d10-… screens/home.png screens/cart.png -E main
```

It prints each image's SHA-256 and the displays its size fits. An image of another size is refused (`422 screenshot_size`).

### Plan and confirm

```sh
palbase stores:listing:plan 4f6c2d10-… -E main
palbase stores:actions:confirm <action id> --hash <hash> -E main
```

The plan compares the saved draft with the page of the app's version that can still change, and lists each change: the categories, the age rating, each language's name, subtitle and privacy policy, its description, keywords and links, and each display's screenshots. When App Store Connect already holds the page, there is nothing to confirm.

A confirmation is a person's, as every [action](/docs/distribution/overview#actions) is. The text is written while the confirmation answers. The screenshots are uploaded after it: the action is `running`, then `done` or `failed`. `palbase stores:actions` shows where it is, and Studio's page says when it ends. Planned again after a failure, it writes what is left.

In Studio, **App Store** shows the page for each language, takes screenshots for each display, and saves the draft. **Plan the changes** lists the steps; **Confirm and write** writes them.

## The version

```sh
palbase stores:version 4f6c2d10-… -E main
```

It shows the version App Review would get: its number, its state, its build, how it is released, its phased release, the price, the content rights statement and App Review's contact and demo account. The demo account's password is never shown: only whether Apple holds one.

Prepare it:

```sh
palbase stores:version:prepare 4f6c2d10-… --version 1.3.0 --build 42 --copyright "2026 Acme" \
  --release manual --phased --no-third-party-content --review-file review.json -E main
```

```json
{
  "contact_first_name": "Ada",
  "contact_last_name": "Lovelace",
  "contact_email": "ada@example.com",
  "contact_phone": "+44 20 7946 0000",
  "demo_account_required": true,
  "demo_account_name": "reviewer@example.com",
  "demo_account_password": "…",
  "notes": "Sign in with the demo account, then add an item to the cart."
}
```

| Flag | What it does |
|---|---|
| `--version` | The version's number. When the app has no version that can change, this makes the next one. |
| `--build` | The TestFlight build App Review gets, by its build number. Its version is this version: [deliver it to TestFlight](/docs/distribution/testflight#send-it-to-testflight) first. |
| `--release` | `manual` (you release it), `after_approval`, or `scheduled` with `--release-at` |
| `--phased`, `--no-phased` | Release it over seven days, or to everyone at once |
| `--third-party-content`, `--no-third-party-content` | Apple's content rights question |
| `--free` | Makes an app with no price free in every country. A paid price is set in App Store Connect. |
| `--territories all` | Sells an app that is sold nowhere in every country and region, and in those Apple opens later. An app sold somewhere keeps its countries: choose them in App Store Connect. |
| `--app-privacy published` | Says you published the app's privacy details in App Store Connect. Apple has no API for them, so the missing list asks until you say so. `unpublished` takes it back. |
| `--review-file` | App Review's details. A field the file leaves out stays as it is. The password goes to Apple and is never printed or kept. |

What you prepare is written to App Store Connect at once: it is no plan. Studio's **Version** panel holds the same form, with **Sell the app in every country and region** and the **App Privacy** switch.

### What is missing

`stores:version` lists what App Review would refuse the version for, one line each, as App Store Connect holds it now: a processed build with its export compliance answer, the copyright, a primary category, the content rights statement, a price, the age rating, App Review's contact and demo account, and each language's name, description, keywords, privacy policy and support URLs, What's New and screenshots. A draft page you saved but did not write yet does not count: plan it and confirm it first. Sending the version is refused while the list is not empty (`409 version_incomplete`).

The list also names what is not the version's own:

- **The countries the app is sold in**, when it is sold in none. `--territories all` sells it everywhere.
- **iPad screenshots**, when the version's build runs on the iPad (its `UIDeviceFamily`, read from the package you uploaded).
- **App Privacy.** Its questions are answered in App Store Connect, and Apple has no API for them. Answer them there, then run `stores:version:prepare <app id> --app-privacy published`. If Apple still refuses the version for App Privacy, the line comes back.

### Send it to App Review

```sh
palbase stores:version:submit 4f6c2d10-… -E main
palbase stores:actions:confirm <action id> --hash <hash> -E main
```

An app's first in-app purchases and subscriptions go to App Review with a version, as Apple requires. Name them by their product ids:

```sh
palbase stores:version:submit 4f6c2d10-… --with com.acme.app.pro.monthly,com.acme.app.coins -E main
```

In Studio, **Send with the version** lists the catalog's App Store products above **Send to App Review**: tick the ones to send. Each is sent only if Apple holds it as `READY_TO_SUBMIT`: its text, price, availability and [review screenshot](/docs/purchases/catalog#review-screenshots) are complete. A subscription's group goes with it until Apple has approved the group. The plan names them, and when you confirm it, Palbase checks that they are still what was planned. The action's result shows each one's state at Apple (`WAITING_FOR_REVIEW`), and withdrawing the version withdraws them too. Apple takes a withdrawal in a few seconds: the withdrawal's result says it is under way, and `stores:version` shows the version's state once Apple has it.

Once the plan is confirmed, the version waits for review. Palbase reads its state every two minutes while App Review has it, and while it waits for its release. `stores:version` shows the state it saw last (`watched`) and since when.

| Command | What it plans |
|---|---|
| `palbase stores:version:withdraw <app id>` | Takes the version out of App Review. You can edit it again, and you send it again from the start. |
| `palbase stores:version:release <app id>` | Releases an approved version that waits for you (`PENDING_DEVELOPER_RELEASE`). A release cannot be taken back. |
| `palbase stores:version:phased <app id> paused` | Pauses a phased release, for 30 days at most in all |
| `palbase stores:version:phased <app id> active` | Resumes it |
| `palbase stores:version:phased <app id> complete` | Gives the update to everyone now |

Each waits for your confirmation, as sending it does. In Studio, the **Version** panel shows the steps the version can take now: **Send to App Review**, **Withdraw from App Review**, **Release**, and the phased release's. Each opens the plan for you to confirm, and closing it declines the plan.

### Phased release

A phased release gives an update to a growing share of the users who have automatic updates, a day each over seven days: 1%, 2%, 5%, 10%, 20%, 50%, then 100%. Anyone can download it from the App Store at once. It starts when the version is released. It applies to an update, never to the app's first version.

## App Review's answer

When App Review approves or rejects the version, the owners of the environment's organization get an email from Palbase. An approved version is released as you set it: one that waits for you is released from Studio's **App Store** page, or with `stores:version:release`. Apple gives no reason for a rejection over its API. With an [Apple ID signed in](#an-apple-id) for the environment, Palbase reads it for you: the Resolution Center's message, the guidelines it names and its attachments. Without one, read it in App Store Connect's **Resolution Center**. Fix what it names, and send the version again.

Every state the version comes to is the environment's `stores.version.changed` event: sent to App Review, in review, approved, rejected, withdrawn, released. It goes to the environment's [webhooks](/docs/server/webhooks) and to a backend's [`@On` handlers](/docs/backend/hooks):

```ts
// src/modules/releases/version-events.ts
import { Log, On, type WebhookEvent } from "palbase/backend";

interface VersionChanged {
  app_id: string;
  name: string;
  version: string;
  previous_state: string | null;
  state: string;
  result: "approved" | "rejected" | null;
}

export class VersionEvents {
  @On("stores.version.changed")
  changed(event: WebhookEvent<VersionChanged>): void {
    const { name, version, state, result } = event.data;
    if (result === "rejected") Log.warn("App Review rejected a version", { name, version, state });
    if (state === "READY_FOR_DISTRIBUTION") Log.info("a version is on the App Store", { name, version });
  }
}
```

```ts
// src/modules/releases/releases.module.ts
import { Module } from "palbase/backend";
import { VersionEvents } from "./version-events";

@Module({ providers: [VersionEvents] })
export class ReleasesModule {}
```

`result` is App Review's answer, set only in a state that is one: `approved` from `PENDING_DEVELOPER_RELEASE` on, `rejected` in `REJECTED`, `METADATA_REJECTED` or `INVALID_BINARY`.

## An Apple ID

Apple's API leaves some of App Store Connect to a person on its website: App Review's messages in the Resolution Center and the answer to them, the App Privacy details, and making an app's record. Sign in with an Apple ID of your team, and Palbase does them with the session App Store Connect's own pages use, as fastlane does. It is optional; the [App Store Connect key](/docs/distribution/testflight#connect-app-store-connect) does everything else.

An Apple ID is signed in to the environment's team: the team of its App Store Connect key or, with no key yet, the team its iOS apps are in. When the Apple ID is in that team, Palbase chooses it for you; when it is in other teams alone, the sign-in is refused with `422 apple_team_mismatch`, naming the Apple ID's teams and the environment's, and nothing is kept.

An Apple ID's session serves the environment it was signed in for. A project's other environments sign in once with it: share it with them. It is shared with the project's own environments alone: no environment of another project uses it — of your organization and your Apple team or not — and an environment added to the project later is shared nothing until someone shares it.

`PUT /stores/apple/session/shares/{environment}`, called on the environment that signed in, shares its session with another environment of the same project (`environment` is that one's ref). It is a person's call, an owner or an admin of both environments: a secret key gets `403 person_required`, an environment's token `403 token_out_of_scope`, one who is no owner or admin of the other environment `403 admin_required`, an environment of another project `403 other_project`. An environment whose App Store Connect key or iOS apps are another team's is refused with `422 apple_team_mismatch`. `DELETE /stores/apple/session/shares/{environment}` takes it back. From a terminal: `palbase stores:apple:share <environment>` on the environment that signed in (`-E`), with the other environment's slug or ref, and `palbase stores:apple:unshare <environment>`; Studio offers the project's other environments ticked after the sign-in, and an environment with no Apple ID offers the one of its project with one tap. A share holds the sign-in it was given: signed out, or signed in again, the session serves none of the environments it was shared with before — share it again.

`GET /stores/apple/session` on an environment it was shared with says so with `shared_from`. A shared session is lent to a person who is an owner or an admin of the environment it was signed in for: Studio, and the CLI with your sign-in. A secret key, or an environment's token, reaches its own environment's session alone. Signing out, by such a person, signs it out for every environment that uses it. Each keeps its session until Apple ends it.

Sign in from Studio, under **App Distribution › Apple ID**, or ask for the link yourself with `POST /stores/apple/session/grants` and open its `connect_url`. Studio asks for a one-time link and opens Palbase's own sign-in page. You type the password there, and the page seals it to a key only the environment's stores module opens: nothing on its way reads it. The module hands it to Apple and keeps it nowhere: Palbase keeps only the session Apple gives back, sealed with the environment's own key.

From a terminal, `palbase stores:apple:connect --apple-id you@example.com` reads the password there, seals it the same way, then asks for Apple's code, and for the team when the Apple ID is in more than one of the environment's (`--team` names it). With `--print-link` it prints the one-time link instead, for a browser to open. `palbase stores:apple` shows the session, `stores:apple:check --apple-id` asks Apple about it again, and `stores:apple:disconnect --apple-id` signs it out.

A client of your own signs in the same way. The link's answer carries `seal_key`, the environment's X25519 public key. Seal the password to it with HPKE (RFC 9180, base mode, DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, AES-128-GCM), its info `palbase/stores/apple-id/password/1`, a NUL byte, then the link's `grant`, and post `{"grant", "apple_id", "password_sealed"}` to `POST /stores/connect/apple-id`, where `password_sealed` is the base64url of the encapsulated key and the ciphertext. A password in the clear is refused. Then you type the code Apple sends to your devices and, if the Apple ID is in more than one team, choose the one the environment's apps are in. A link takes three passwords and three codes, and an environment six passwords an hour, so that Apple does not lock the Apple ID. Signing an Apple ID in, and out, is an owner's or an admin's.

Apple ends a session after a few weeks, and when the Apple ID's password changes. Palbase checks it every six hours. When it has ended, the person who signed it in gets an email (the organization's owners, if they are no longer an owner or an admin), the environment gets the `stores.apple.session.expired` event, and what needs the Apple ID answers `409 apple_id_expired` until someone signs in again. Studio's **Apple ID** panel, or `GET /stores/apple/session`, shows whose it is, its team and whether Apple still takes it; **Sign out**, or `DELETE /stores/apple/session`, signs it out, at Apple too.

### Keys, made for you

With an Apple ID signed in, Palbase makes the keys the environment lacks at Apple and connects them, so no one downloads a `.p8` and carries it over:

- **The App Store Connect API key**: Admin, every app. Connected as one you upload would be, and asked of Apple's API first. Disconnecting it (`DELETE /stores/apple`) revokes it at Apple.
- **APNs keys**: two, one for production and one for the sandbox, each scoped to the environment's iOS apps of the Apple ID's team (Apple makes a key scoped to apps for one environment; an app of another team is none of its). The notify module takes them as the environment's APNs provider: each environment's pushes are signed with its own key.
- **The In-App Purchase key**: for one of the environment's iOS apps (name it when there is more than one). The purchases module connects it, and asks the App Store Server API with it first.

In Studio, **App Distribution › Apple ID** lists them under **Keys**, what the environment lacks ticked: **Make and connect** makes them, with one confirmation. From a terminal, `palbase stores:apple:keys` says what Palbase made and what the environment lacks, and `palbase stores:apple:keys:make` makes every missing key (`--asc`, `--apns`, `--iap` for some; `--bundle` for the In-App Purchase key's app). Over the API, `POST /stores/apple/keys` makes one kind a request: `{"kind": "asc" | "apns" | "iap", "bundle"}`; `GET /stores/apple/keys` lists them and where each stands (`waiting` for its module, `taken`, `refused`, `revoked`).

A key the environment connected itself is kept: making one is refused with `409 key_connected`, and the module that has one of its own refuses the one made, which is revoked at Apple at once. Each key's `.p8` is read from Apple once, sealed with the environment's key, and handed to its module over Palbase's internal network; once taken, the stores module drops its copy. `DELETE /stores/apple/keys/{key_id}`, **Revoke** beside it in Studio, or `palbase stores:apple:keys:revoke <key-id>`, revokes an APNs or In-App Purchase key Palbase made.

Apple makes keys for an Admin or the Account Holder of the team: an Apple ID of another role is told `409 apple_role_insufficient`. Making and revoking keys is an owner's or an admin's of the environment, never an environment's token's (`403 token_out_of_scope`): a key outlives it. The App Store Connect key is made with the Admin role, as the key you would connect yourself is: it reaches the team's users too, so revoke it if you stop using Palbase for the app.

### App Review's messages

`GET /stores/apps/{app_id}/review` is the app's Resolution Center: each thread with its messages as plain text, the guidelines each rejection names, its attachments and the answer not sent yet. An attachment is read with `GET /stores/apps/{app_id}/review/threads/{thread_id}/attachments/{attachment_id}`. You answer with a draft, `PUT /stores/apps/{app_id}/review/threads/{thread_id}/draft`, which App Store Connect keeps as its website's, then send it with `POST /stores/apps/{app_id}/review/threads/{thread_id}/draft/send`. From a terminal: `palbase stores:app-review <app id>`, and `stores:app-review:answer` writes the draft (`--send` sends it).

While a version of the app is in App Review, or was rejected in the last 30 days, Palbase reads its Resolution Center every ten minutes. Each message it has not told yet is the environment's `stores.review.message` event, with its text, the guidelines (`reasons`) and the attachments. Your own answer is not told back.

### App Privacy

`GET /stores/apps/{app_id}/privacy` is the app's privacy details as App Store Connect has them. `PUT` writes them, in Apple's words, one line per kind of data and purpose, or `DATA_NOT_COLLECTED` alone. The lines it lacks are made and the ones not asked for removed, and `"publish": true` publishes them. Once published, the version's missing list stops asking for App Privacy. From a terminal: `palbase stores:privacy <app id>`, and `stores:privacy:set <app id> --file usages.json --publish` with the lines as a list.

```json
{
  "usages": [
    { "category": "USER_ID", "purpose": "APP_FUNCTIONALITY", "data_protection": "DATA_LINKED_TO_YOU" },
    { "category": "PURCHASE_HISTORY", "purpose": "APP_FUNCTIONALITY", "data_protection": "DATA_LINKED_TO_YOU" }
  ],
  "publish": true
}
```

### The app's record

An app [linked to the App Store](/docs/distribution/testflight#link-the-app) without its App Store Connect record gets one with `POST /stores/apps/{app_id}/record` and its App Store name (`{"name": "Shop"}`): Palbase makes the record and links the app to it. The team's first app also needs `company_name`, the seller's name. `DELETE` removes the record, as App Store Connect's **Remove App** does: Apple takes it for an app never approved. Each is the environment's `stores.app.changed` event (`record_made`, `record_removed`). From a terminal: `palbase stores:apps:record <app id> --name Shop`, and `stores:apps:record:remove <app id>`.

## Related

- [App Distribution](/docs/distribution/overview): packages, deliveries, actions and events
- [TestFlight](/docs/distribution/testflight): the Apple account, the build App Review gets, Beta App Review
- [CLI reference: `stores`](/docs/cli/reference#stores)



<!-- ===== distribution/google-play ===== -->

# Google Play

An Android app's builds go to Google Play's internal testing track, for the testers that track lists in Play Console. Your build machine uploads the Android App Bundle (`.aab`). Palbase signs it with the app's upload key, which it made and keeps, uploads it to Play, puts it on the track and commits the release. Play then signs what devices install with Google's app signing key, as it does for every app enrolled in Play App Signing. No keystore lives on the build machine, and no Google key changes hands.

## Connect Google Play

```sh
palbase stores:google:connect -E main
```

Palbase makes a service account for the environment in its own Google Cloud project and prints it. It holds no key: Palbase acts as it. Connecting again answers the same account. In Studio, **App Distribution › Overview › Connect Google Play** does the same.

Then, in Play Console:

1. **Users and permissions › Invite new users**: invite the service account's address.
2. Give it the app, with **Release apps to testing tracks**. For the app's Google Play purchases, give it **View financial data** and **Manage orders and subscriptions** too.
3. [Link the Android app](#link-the-app), then ask Play what the account reaches: `palbase stores:google:check`.

`palbase stores:google` shows the connection:

| | |
|---|---|
| Status | `invited`: made, and no app answered it yet. `active`: Play answers it for an app. `refused`: it answered once, and no app does any more. |
| Reaches | Per app: `releases` (uploading builds, changing tracks), `products` (reading its subscriptions), or the reason Play gave for not letting it reach the app |

An invite given in Play Console just now takes a while to reach Play's API: check again in a few minutes. `palbase stores:google:disconnect` deletes the service account at Google, and Play Console's invite of it reaches nothing any more.

The app must exist in Play Console, under its package name: Play's API makes none.

## Link the app

```sh
palbase stores:apps:link 7d21e9b4-… -E main
```

The app is one of the project's [registered apps](/docs/apps/overview), by its id, set in this environment with its package. Linking makes the app's **upload key**: the key Palbase signs its builds with, the first release in Play Console among them. Linking again keeps it, and asks Play about the app again.

```sh
palbase stores:apps:upload-key 7d21e9b4-… --out upload-certificate.pem -E main
```

`stores:apps:upload-key` prints the upload key's SHA-256, as Play Console shows an upload key, and `--out` writes its certificate. Its private key never leaves Palbase.

- **A new app**, never uploaded to Play: its first release, signed by Palbase, makes Palbase's key the app's upload key.
- **An app that has an upload key already**: ask Play to change it to Palbase's, from Play Console's **App signing** page (an upload key reset), with the certificate above. Or keep yours: upload bundles you signed with it, and Palbase hands them to Play as they are.

## Make the build

```sh
pkg=$(palbase stores:packages:create 7d21e9b4-… --command-id "$CI_RUN_ID" -E main -y --json)
```

Its answer holds the package's `id`, its `build_number` and the upload token, as on [the build machine](/docs/distribution/overview#from-a-build-machine). The build number is above every version code Play has seen for the app, once the environment is connected to Play, and every one the environment handed out. Build the release bundle with it as `versionCode`:

```kotlin
// app/build.gradle.kts
android {
    defaultConfig {
        versionCode = (findProperty("buildNumber") as String?)?.toInt() ?: 1
    }
}
```

```sh
./gradlew :app:bundleRelease -PbuildNumber="$BUILD_NUMBER"
palbase stores:packages:upload "$PACKAGE" --file app/build/outputs/bundle/release/app-release.aab -E main -y
```

Leave the release build unsigned, or sign it with the app's upload key. The upload is checked before it is taken:

| Refusal | Why |
|---|---|
| `not_an_aab` | Not an Android App Bundle that can be read: build the release bundle (`bundleRelease`) |
| `wrong_bundle` | The bundle is another package's |
| `wrong_build_number` | Its `versionCode` is not the package's build number |
| `bad_signature` | It is signed, but its signature does not hold: upload it unsigned |

A bundle signed by its maker is kept as it came, with its certificate's fingerprint (`signer_fingerprint`), for Play to compare with the app's upload key.

## Send it to internal testing

```sh
palbase stores:deliver "$PACKAGE" -E main
palbase stores:deliveries "$PACKAGE" -E main
```

The delivery goes `queued`, `signing`, `uploading`, then `ready`, once Play took it: its `play_version_code` is the version code Play took, and its `play_release_status` is `completed` when testers get it, or `draft` on an app never published, which only Play Console rolls out. Groups are TestFlight's: on Play, the testers are the ones the internal testing track lists in Play Console. Studio's package page shows the same, and **Send to internal testing** sends it from there.

### The first release

Play may take an app's first release only in Play Console. The delivery then fails with `first_release_manual`: download the bundle as Palbase signed it, and upload it once yourself.

```sh
palbase stores:packages:bundle "$PACKAGE" --out app-signed.aab -E main
```

In Play Console, **Testing › Internal testing › Create new release**, upload that file: it is signed with the app's upload key. The next package is delivered by Palbase. The bundle comes from the environment's address on a link sealed for it, valid 15 minutes; Studio's package page downloads it with **Signed bundle**.

## When a delivery fails

| `error_code` | What to do |
|---|---|
| `google_not_connected` | Connect Google Play (`palbase stores:google:connect`), invite the service account, and send again. |
| `google_no_access` | Play Console has not invited the service account with this app: invite it, then send again. |
| `google_not_allowed` | Play lets the account reach the app but not release it. An invite given just now takes a while to reach Play's API: send again in a while; otherwise give it **Release apps to testing tracks** for the app. |
| `play_app_missing` | Play has no app by this package that the account may reach: create it in Play Console and invite the account with it. |
| `first_release_manual` | Upload the signed bundle in Play Console once ([The first release](#the-first-release)), then send the next package. |
| `no_upload_key` | The app has no upload key: link it again. |
| `not_an_aab` | The build could not be read to be signed: build it again and upload it as a new package. |
| `google_refused` | Play refused a step; `error` has Play's words. |

A package cannot be made at all once Play has seen the highest version code it takes (`409 version_codes_spent`). The general failures (`build_changed`, `build_gone`, `step_timed_out`, `gave_up`) are on the [overview](/docs/distribution/overview#deliveries).

## Related

- [App Distribution](/docs/distribution/overview): packages, deliveries, actions and events
- [Client Apps](/docs/apps/overview): an Android app's package and the certificates its passkeys trust
- [CLI reference: `stores`](/docs/cli/reference#stores)



<!-- ===== distribution/health ===== -->

# App Health

Palbase follows each linked app in its store. An iOS app's App Store Connect webhook tells the environment each change of the app's version, builds and testers' feedback the moment it happens; an Android app's Play releases are read every 10 minutes; and both stores' crash data is read as they publish it. Each change is an event to the environment's [webhooks](/docs/server/webhooks) and to a backend's [`@On` handlers](/docs/backend/hooks).

Studio shows it under **App Distribution › Health**, for each linked app.

## The App Store Connect webhook

When an iOS app is linked and has its App Store Connect record, Palbase makes the app's webhook in App Store Connect, named `Palbase`, pointed at the environment's own address. Apple tells it:

| Apple's event | What Palbase tells |
|---|---|
| `APP_STORE_VERSION_APP_VERSION_STATE_UPDATED` | `stores.version.changed` |
| `BUILD_UPLOAD_STATE_UPDATED` | `stores.build.changed` |
| `BUILD_BETA_DETAIL_EXTERNAL_BUILD_STATE_UPDATED` | `stores.beta_review.changed` |
| `BETA_FEEDBACK_CRASH_SUBMISSION_CREATED`, `BETA_FEEDBACK_SCREENSHOT_SUBMISSION_CREATED` | `stores.feedback.received` |

Every delivery is checked against Apple's signature with the webhook's own secret, and one Apple sends again is told once.

**Making a webhook needs the connected key's Admin or App Manager role.** A key with another role is refused: the webhook is `refused`, and Palbase tries again every day. Give the key the role in App Store Connect (**Users and Access › Integrations**), then make it again: Studio's **Make again**, or `POST /stores/apps/{app_id}/webhook`. A webhook Apple refused for another reason, or that it did not answer for, is `failed`: Palbase tries it again by itself, and **Make again** tries now.

**Palbase's reads stay behind it.** While App Review has a version, or it waits for its release, Palbase reads its state every two minutes, webhook or not, and an in-app purchase's while App Review has it: a change the webhook did not tell still reaches the same event, minutes later. Each new state is told once, whichever learned it first; a read in the two minutes after a delivery does not tell the state before it again. The build, Beta App Review and feedback events come from the webhook alone.

| `state` | What it means |
|---|---|
| `on` | Apple tells the webhook each change |
| `refused` | The connected key's role may not make webhooks (Admin or App Manager may); `error` says so |
| `failed` | Apple refused it otherwise, or could not be reached; `error` says why |
| `none` | Not made yet |

`GET /stores/apps/{app_id}/webhook` reads it: its `state`, `error`, `url`, the `event_types` Apple tells it, when it was made (`installed_at`) and last checked (`checked_at`), and Apple's last delivery (`last_delivery_type`, `last_delivery_at`). `POST /stores/apps/{app_id}/webhook/ping` asks Apple to send it a ping (`202`); its arrival is the webhook's `pinged_at`. Studio's **Ping** does the same and reads the webhook again until the ping shows. From a terminal:

```bash
palbase stores:webhook <app id>           # its state, where it reports, Apple's last delivery
palbase stores:webhook <app id> --ping    # asks Apple for a ping and waits for it to arrive
palbase stores:webhook <app id> --make    # makes it again, with a new secret
```

Each change of the webhook's state is `stores.webhook.changed`: `{ app_id, state, asc_webhook_id, error }`, `state` one of `on`, `refused` or `failed`.

## Who said it: `source`

The events a store can tell carry `source`, where the change was learned:

| `source` | From |
|---|---|
| `apple_webhook` | App Store Connect's webhook, the moment it happened |
| `poll` | Palbase's own read of the store |
| `action` | One of Palbase's own [actions](/docs/distribution/overview#actions), as it ran: a version sent to App Review, withdrawn or released |

`stores.version.changed` has it beside its other fields: `{ app_id, bundle_id, name, version, asc_version_id, previous_state, state, result, source }`.

## The events

| Event | When | `data` |
|---|---|---|
| `stores.webhook.changed` | An app's App Store Connect webhook came on, or was refused (the key's role) or failed | `{ app_id, state, asc_webhook_id, error }` |
| `stores.version.changed` | An app's App Store version came to a new state: sent to App Review, in review, approved, rejected, withdrawn, released | `{ app_id, bundle_id, name, version, asc_version_id, previous_state, state, result, source }` |
| `stores.build.changed` | A build upload of the app came to a new state at App Store Connect (processing, complete, failed): a delivery's, or a build uploaded any other way | `{ app_id, asc_upload_id, asc_build_id, version, build_number, state, package_id, source }` |
| `stores.beta_review.changed` | A build's TestFlight state for external testers changed: in Beta App Review, approved, rejected, ready for testing… | `{ app_id, asc_build_id, state, previous_state, package_id, source }` |
| `stores.feedback.received` | A tester sent TestFlight feedback: a crash with its log, or a screenshot | `{ app_id, kind, feedback_id, created_at, comment, device_model, os_version, locale, asc_build_id, package_id, crash_log, crash_log_cut, screenshots, source }` |
| `stores.product.changed` | An in-app purchase's or a subscription's App Store state changed: sent to App Review with a version, approved, rejected, back to ready to submit | `{ app_id, store, product_id, apple_id, kind, state, previous_state, source }` |
| `stores.play_release.changed` | A release on one of an Android app's Play tracks came to a new state: draft, in review, approved, not approved, published | `{ app_id, package_name, track, release_name, version_codes, state, previous_state, source }` |
| `stores.vitals.changed` | The store published a new day of an app's crash data | `{ app_id, platform, through, store, versions, anomalies, issues, crash_days, testflight_crashes }` |

- **`package_id`** is the package a delivery of Palbase's sent the build of, and `null` for a build uploaded another way.
- **`stores.feedback.received`** never carries the tester's address. A crash's `crash_log` is cut at 32 KiB, the exception and the crashed thread first (`crash_log_cut` says it was), and a screenshot's `screenshots` are Apple's links to its images, `{ url, width, height, expires_at }`, which stop working at `expires_at`.
- **`stores.vitals.changed`** carries the day: an App Store app's `crash_days` (crashes by version) and how many TestFlight crashes Apple keeps; an Android app's `versions` (the newest ten version codes' rates), and how many `issues` and `anomalies`. The rest is read with the call below.

## Testers' feedback

`GET /stores/apps/{app_id}/feedback` lists the app's newest TestFlight feedback, newest first. `GET /stores/apps/{app_id}/feedback/{kind}/{feedback_id}` reads one, `kind` being `crash` or `screenshot`: the tester's comment and address, the device (`device_model`, Apple's model id such as `iPhone17,1`), `os_version`, `locale`, the build the tester ran (`asc_build_id`, `bundle_id`), and a crash's `crash_log` or a screenshot's `screenshots`. Both read Apple now, with the secret key:

```bash
curl -s "https://<ref>.palbase.studio/stores/apps/${APP_ID}/feedback/crash/${FEEDBACK_ID}" \
  -H "apikey: $PALBASE_SECRET_KEY"
```

```json
{
  "kind": "crash",
  "id": "AJ3k…",
  "created_at": "2026-10-21T08:12:40Z",
  "comment": "It closed when I opened the cart",
  "device_model": "iPhone17,1",
  "os_version": "26.0.1",
  "asc_build_id": "8d1c…",
  "crash_log": "Exception Type:  EXC_CRASH (SIGABRT)\n…",
  "crash_log_cut": false
}
```

Studio's **Health** lists them under **Testers' crashes and screenshots**; opening one shows its device, system, build and log, or its images. The CLI reads the same:

```bash
palbase stores:feedback <app id>                          # the newest, with their ids
palbase stores:feedback:get <app id> crash <feedback id>  # one, with its log
```

## An app's health

`GET /stores/apps/{app_id}/vitals` reads the app's health from its store now. `through` is the last day the store's crash data is of, and `null` while it has none.

```bash
curl -s "https://<ref>.palbase.studio/stores/apps/${APP_ID}/vitals" \
  -H "apikey: $PALBASE_SECRET_KEY"
```

or `palbase stores:vitals <app id>`, which prints the same as tables.

An iOS app's answer has `apple`. An app not yet on the App Store has its TestFlight counts alone: Apple publishes the App Crashes report and the metrics for App Store versions only, once enough people who share their data ran them (the report needs at least five).


| Field | What it is |
|---|---|
| `crash_days` | The App Store's crashes by day and version, the last 30 days, newest first: `{ date, version, crashes, devices }`, from Apple's App Crashes report |
| `metrics` | Its App Store versions' terminations, hangs and launches: `{ category, identifier, version, value, unit, device, percentile }`, published by Apple once enough people who share their data ran a version |
| `testflight_crashes` | The newest crashes testers sent from TestFlight; read one with its log as above |
| `testflight_builds` | The newest five builds' TestFlight counts, newest first: `{ asc_build_id, version, build_number, uploaded_at, expired, from, to, installs, sessions, crashes, feedback, invites }`, what Apple counted of each over `from`–`to` (its window, at most a year); a build Apple counted nothing of has no `from` |
| `crash_counts` | Whether the App Crashes report can be read: see below |

| `crash_counts` | What it means |
|---|---|
| `ok` | The report is read |
| `none_yet` | Apple's report has no day yet |
| `requested` | Palbase asked Apple for the report now; its first days come in a day or two |
| `not_requested` | Palbase asks for it with its next round |
| `admin_key_needed` | Only an Admin key may ask Apple for an app's analytics reports, and the connected key is not one: an App Manager key makes the webhook and reads the rest, not this |

An Android app's answer has `play`, Google Play's Android vitals:

| Field | What it is |
|---|---|
| `through` | The last whole day the rates are of, in Play's time zone (America/Los_Angeles); `null` while Play has none (the app has too few users) |
| `versions` | Each version code's `crash_rate`, `user_perceived_crash_rate`, `anr_rate` and `user_perceived_anr_rate`, fractions of its `users` over the seven days to `through`, weighted by users; a rate is `null` where Play has too few users |
| `issues` | The app's errors of the last day, most reports first: `{ type, cause, location, users, reports, last_report_at, first_version_code, last_version_code, uri }`, `type` being `CRASH`, `ANR` or `NON_FATAL` and `uri` the error in Play Console |
| `anomalies` | The rates Play saw go wrong against the 28 days before: `{ metric, value, version_code, from, to }` |

What to do about a rate is the project's: the answer is the store's.

## Google Play

Play sends no notifications of a release's review, so Palbase reads each linked Android app's releases on Play's tracks every 10 minutes. A release's new state is `stores.play_release.changed`, with `source: "poll"`; one Play no longer lists is forgotten.

The stores publish a day's crash data once a day. Palbase reads each app's health every six hours, and a day newer than the last one told is `stores.vitals.changed`, for an iOS app and an Android app alike.

## In Studio

**App Distribution › Health**, for each linked app:

| Panel | What it holds |
|---|---|
| Apple webhook | An iOS app's webhook: its state, why it is not on, its address, Apple's last delivery and the last ping; **Ping** and **Make again** |
| Testers' crashes and screenshots | What testers sent from TestFlight, newest first; one opens with its device, system, build and crash log, or its images |
| App Store health | The newest builds' TestFlight counts, the day the App Store's crash data is of, crashes by day and version, and Apple's metrics |
| Play vitals | An Android app's rates by version code, its errors of the last day and Play's anomalies |

## Related

- [App Distribution](/docs/distribution/overview): packages, deliveries, actions and the other `stores.*` events
- [TestFlight](/docs/distribution/testflight): the App Store Connect key and its role
- [App Store](/docs/distribution/app-store): the version App Review gets, and its states
- [Google Play](/docs/distribution/google-play): the Play connection
- [Webhooks](/docs/server/webhooks): receiving the events



<!-- ===== machines/overview ===== -->

# Machines

A **machine** is your own code running on Palbase: a small sandboxed computer that runs one image of your project's, built from a branch of a GitHub repository, and answers HTTPS at an address of its own. A [`palbase/backend`](/docs/backend/overview) app is the usual thing to run on one, but a machine runs whatever its build makes — a Next.js site, a Go service, a worker that only serves a health check.

You never deploy a machine by hand. You [connect GitHub](/docs/machines/github), open the machine on a repository, a branch and a directory, and from then on **a push to that branch is the deploy**: it is built, rolled out beside the version that serves, and only then takes traffic. See [Builds, Logs & Rollback](/docs/machines/builds).

In Studio, machines live under **Backend › Machines**. Everything Studio does there is the machines module's API, which takes the project's secret key — every step on these pages names the call beside the click.

## What a machine is

| | |
|---|---|
| Name | Lowercase letters, digits and dashes, starting with a letter, 32 characters at most. `backend` when left out. Not `github`, `network` or `sizes`, which are the API's own paths. |
| Source | A repository, a branch and a directory of it ([Connecting GitHub](/docs/machines/github)) |
| Size | How much CPU and memory it has, and whether it sleeps (below) |
| Port | The TCP port it listens on, `8080` unless you say otherwise. It also finds it in `PORT`. |
| Copies | How many copies run while it is awake, 1 to 5 |
| Health check | A path that answers 2xx while it serves |
| Environment | Variables of your own, and the project secret set it starts with |
| Database | One of the project's [databases](/docs/machines/databases), or none |

A project has **5 machines at most**, and a machine's name is that machine's alone. Deleting a machine frees its name at once.

## Its address

The machine named `backend` is the project's backend and answers at the project's own name under the app domain; any other machine answers at its name and the project's ref:

```text
https://<ref>.app.palbase.studio          the machine named backend
https://<name>-<ref>.app.palbase.studio   any other machine
```

The `url` field of the machine (Studio shows it as **Address**, with an **Open** button) is the address to use. A request there is your customers' own: no API key is asked for and none is added. Who may call a route is the app's to decide — a `palbase/backend` app checks the caller's access token on every route that needs one ([Authentication](/docs/backend/authentication)).

What the platform answers itself, before your program sees anything:

| Answer | When | Safe to send again |
|---|---|---|
| `404 no_such_machine` | The host names no machine (deleted, or never made) | — |
| `429 quota_exceeded` | The project has used its machine time for the period; `Retry-After` says until when | at that time |
| `429 rate_limited` | The project's machines are over its requests-per-second limit; `Retry-After: 1` | yes |
| `503 machine_waking` | The machine was asleep and is still coming up; the request did not reach it; `Retry-After: 5` | yes |
| `503 machine_unavailable` | The machine could not be woken or reached; `Retry-After: 2` | yes |

Every request to the address is counted where it arrives, whatever program answers it: Studio's machine page draws the machine's **Requests** by status class and its **Response time** (median and p95) over the period chosen — the platform's answers above among them, as your customers saw them. Thirty days are kept; of a request, only its time, status and duration — nothing of who sent it or what it asked.

A path whose first segment is `_palbase` — `/_palbase/health`, `/_palbase/crons` — is never sent to a machine from outside. It is the platform's own way in (its health checks, its [crons and tasks](#crons-and-tasks)), and a request for it from the internet is answered `404`. A backend's contract is not asked of it: its build writes it, and the platform keeps it with the build.

## Sizes

| Size | CPU | Memory | Sleeps |
|---|---|---|---|
| `shared-256` | 0.2 vCPU | 256 MiB | yes |
| `shared-512` | 0.5 vCPU | 512 MiB | yes |
| `shared-1024` | 1 vCPU | 1024 MiB | yes |
| `dedicated-1x` | 1 vCPU of its own | 2048 MiB | never |
| `dedicated-2x` | 2 vCPU of its own | 4096 MiB | never |

A **shared** size has a fraction of a CPU as its ceiling and is **put to sleep when it is idle** — after 15 minutes without a request — and woken by the next request, which waits for it. A request that waits longer than the wake allows is answered `503 machine_waking` with `Retry-After`, and asking again is what brings the answer. A **dedicated** size has whole CPUs of its own and never sleeps.

Sleeping has consequences for code: a machine that sleeps runs nothing while it sleeps. A timer, an in-memory cache or a background loop stops with it, and a request that wakes it pays the start-up. Work that must happen on a schedule is a [cron](#crons-and-tasks), and work to be done once, now or later, a [task](#crons-and-tasks): the platform wakes the machine for either.

`shared-256` is the size every project may open. The others are sizes that are paid for: open to an environment on Pay as you go with credit ([Billing](/docs/getting-started/billing)); for another, opening a machine at one, or moving one to it, is refused with `403 size_not_available`; `palbase machines:sizes` lists the sizes the environment may open now ([Usage & Limits](/docs/getting-started/usage-and-limits)).

What a project's machines and databases reserve between them is held to the project's limit: a size or a number of copies that does not fit is refused with `409 machines_over_limit`.

## Copies

A machine runs **one copy** unless you give it more (`replicas`, **Copies** in Studio, 1 to 5). Each copy runs on a node of its own, a request goes to one of them, and a copy or a node that goes leaves the others serving. Every copy is of the machine's size and counts as one against the project's limits and its machine time.

What a copy keeps in its own memory or on its own disk, the others do not see — a session, a counter, a cache, a rate-limit window. A machine with more than one copy keeps those where every copy reaches them: its database, or the project's [cache](/docs/backend/cache). A long-lived connection (a WebSocket) stays with the copy that took it. The machine finds its number of copies in `PALBASE_REPLICAS`.

## The health check

A machine says it is well at a **health path**: a path on its port that answers 2xx while it serves. While it starts it has 90 seconds to answer there; once it serves, one that stops answering for about 6 seconds is started again.

Leave the path empty and the build says it: a directory whose `package.json` depends on `palbase/backend` is asked at `/_palbase/health`, which the framework answers `200` while it serves and `503` while it stops. A machine that says nowhere is asked only whether it listens on its port.

## Its environment

The platform starts every machine with these, whatever else it is given:

| Variable | What it holds |
|---|---|
| `PORT` | The port it listens on |
| `PALBASE_URL` | The project's address, `https://<ref>.palbase.studio` |
| `PALBASE_PROJECT_ID` | The project's id |
| `PALBASE_REPLICAS` | How many copies of it run |
| `PALBASE_PLATFORM_SECRET` | The key the platform signs its own calls to this machine with ([crons and tasks](#crons-and-tasks), a backend's contract) |
| `PALBASE_MACHINE` | The machine's own name: what its program puts its tasks on the queue of |
| `PALBASE_DB_URL` | Given a database: where it answers, as the application's login |
| `PALBASE_DB_CONNECTIONS` | Given a database: how many connections to it one copy may hold |

Besides those, a machine has two sources of its own:

- **Environment variables** — settings, not secrets: one `NAME=value` a line in Studio's **Edit settings**, `env` in the API. 100 variables and 64 KiB at most. `PORT` is refused there, and a name the platform sets gives way to the platform's.
- **Secrets** — the project keeps its secrets in two sets, `production` and `development`, and a machine names the set it starts with (**Secrets** in **Edit settings**: *No secrets*, *Production secrets* or *Development secrets*). Every secret of the set is in the machine's environment by its name; a name in `env` wins over the same secret. When a secret of the set changes, the machine rolls out with the new value beside the version that serves. Studio's **Environment › Variables** screen holds the set the environment's machines start with — see [Secrets](/docs/backend/secrets).

A `palbase/backend` app also needs `PALBASE_SECRET_KEY` — the project's secret key, which nothing puts there for you. Make a secret key in **Settings › API keys** (it is shown once), add it as the secret `PALBASE_SECRET_KEY`, and start the machine with that set. Name it in the app's `.env.example` and a build waits for it instead of rolling out an app that cannot start ([Builds](/docs/machines/builds)).

A change of size, port, copies, environment, secrets or health path rolls out beside the version that serves; a change of source is built first and rolls out once its build is up.

## Opening one

In Studio: **Backend › Machines › New machine**. The sheet asks for the repository (only those the connected accounts can push to), the branch, the directory, the name, the size, the port and, optionally, a database and whether this machine runs its migrations. The branch's head is built at once; the machine answers at its address once that build is up.

From a server, with the secret key, it is one call — the same module Studio calls:

```ts
// scripts/open-machine.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

const { data: machine } = await palbase.machines.createMachine({
  body: {
    name: "backend",
    size: "shared-512",
    port: 8080,
    source: { repository: "acme/notes", branch: "main", path: "server" },
    secrets: "production",
  },
});

console.log(machine.state, machine.url); // building https://<ref>.app.palbase.studio
```

Inside a `palbase/backend` app the same client is `Palbase.machines`. The calls:

| Call | HTTP | What it does |
|---|---|---|
| `createMachine` | `POST /machines` | Opens a machine; its state is `building` |
| `listMachines` | `GET /machines` | The project's machines, by name |
| `getMachine` | `GET /machines/{name}` | What was asked for, and what runs |
| `updateMachine` | `PATCH /machines/{name}` | Changes its source, size, port, copies, env, secrets, health path or database |
| `deleteMachine` | `DELETE /machines/{name}` | Takes it away; its address stops answering |

A machine's `state` is `building` (no build of it runs yet), `starting`, `awake`, `asleep` or `failed` — `state_reason` says why it failed, or why a new version is not up. `version` counts the changes asked for and `running_version` the one that runs: they are equal once a change has rolled out.

## Crons and tasks

A machine that sleeps cannot keep a timer, and a timer in a machine with three copies fires three times. So the schedule — and the queue of work to be done once — are the platform's: the program **says** what crons and task types it has, and the platform **calls** it when a cron is due or a task's time comes — waking the machine for it, and calling one copy.

> **Note:** A backend on `palbase/backend` answers these calls itself: mark a provider with `@Cron` — see [Cron](/docs/backend/cron) — or `@Task` — see [Tasks](/docs/backend/tasks). Any other program answers the calls below.

The calls, all on the machine's own port, all signed with the key in `PALBASE_PLATFORM_SECRET`:

| Call | The program answers |
|---|---|
| `GET /_palbase/crons` | `{"crons": [{"name", "schedule", "time_zone", "timeout", "retry"}]}` — asked once each version comes up; `404` means it has none |
| `POST /_palbase/crons/<name>` | Runs the cron. The body is `{"cron", "run_id", "scheduled_at", "attempt"}`; the call is held open until it is done |
| `GET /_palbase/tasks` | `{"tasks": [{"name", "timeout", "retry", "concurrency"}]}` — asked with the crons; `404` means it has none |
| `POST /_palbase/tasks/<name>` | Does one attempt of a task. The body is `{"task", "id", "attempt", "payload", "created_at"}`; the call is held open until it is done |

A cron's `schedule` is five cron fields — minute, hour, day of month, month, day of week — on the clocks of `time_zone` (an IANA name; UTC when left out). `timeout` is the seconds an attempt has (30 when left out, 900 at most) and `retry` the attempts a run has after its first fails (5 when left out, 10 at most). A task type's `timeout` is 60 when left out (900 at most), its `retry` 5 (20 at most) and its `concurrency` — how many of its tasks are with the machine at once — 5 (50 at most). A name is letters, digits, `.`, `_` and `-`, 64 characters at most; a machine has 50 crons and 50 task types at most. What the platform cannot run (a bad schedule or zone, a value out of range) is left out of the list.

A `2xx` answer is done. For a cron, `404` is "no such cron in this version", and the run is skipped; anything else — or no answer within the timeout — is a failed attempt, made again after 10 s, 20 s, … up to five minutes apart. One run of a cron runs at a time: a cron due again while its last run is still going is **skipped**, not queued. For a task, `422` is "this task can never be done" — it fails at once — and anything else that is not `2xx` is a failed attempt, made again after 10 s, 20 s, … up to an hour apart.

Every call carries `Palbase-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(key, "<t>.<body>")>` — a webhook's signature, with the machine's key. `verifySignature` from `palbase/server` checks it:

```ts
// crons/server.ts
import { createServer } from "node:http";
import { verifySignature, WebhookSignatureError } from "palbase/server";

const key = process.env.PALBASE_PLATFORM_SECRET ?? "";

const crons = [{ name: "nightly-digest", schedule: "0 3 * * *", time_zone: "Europe/Istanbul", timeout: 120, retry: 3 }];

async function nightlyDigest(runId: string): Promise<void> {
  console.log(JSON.stringify({ msg: "digest", run_id: runId }));
}

createServer(async (req, res) => {
  const chunks: Buffer[] = [];
  for await (const chunk of req) chunks.push(chunk as Buffer);
  const body = Buffer.concat(chunks);
  const path = new URL(req.url ?? "/", "http://machine").pathname;

  if (path !== "/_palbase/crons" && !path.startsWith("/_palbase/crons/")) {
    res.writeHead(200).end("ok");
    return;
  }
  try {
    // A GET is signed over "<t>." and an empty body; a POST over its bytes as they arrived.
    const signature = req.headers["palbase-signature"];
    await verifySignature({ secret: key, signature: Array.isArray(signature) ? signature[0] : signature, body });
  } catch (e) {
    res.writeHead(e instanceof WebhookSignatureError ? 401 : 500).end();
    return;
  }

  if (req.method === "GET" && path === "/_palbase/crons") {
    res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ crons }));
    return;
  }
  if (req.method === "POST" && path === "/_palbase/crons/nightly-digest") {
    const run = JSON.parse(body.toString("utf8")) as { run_id: string; attempt: number };
    await nightlyDigest(run.run_id);
    res.writeHead(204).end();
    return;
  }
  res.writeHead(404).end();
}).listen(Number(process.env.PORT ?? 8080));
```

The same `run_id` comes with every attempt of one run, and the same `id` with every attempt of one task: key the work on it, and an attempt made again after a lost answer does not do it twice.

What the platform keeps of them, with the secret key:

| Call | HTTP | What it answers |
|---|---|---|
| `listCrons` | `GET /machines/{name}/crons` | The crons the running version said, each with its zone, when it is next due, whether it is paused, and its latest run |
| `listCronRuns` | `GET /machines/{name}/crons/{cron}/runs` | A cron's latest 50 runs, newest first: `running`, `waiting`, `succeeded`, `failed` or `skipped`, with the attempts each took, why one failed, and whether it was asked to run now. Runs are kept 7 days. |
| `runCron` | `POST /machines/{name}/crons/{cron}/run` | Runs it now, apart from its schedule (`409` while a run of it is not over) |
| `pauseCron` / `resumeCron` | `POST /machines/{name}/crons/{cron}/pause`, `…/resume` | Paused, it is not run until resumed, whatever version comes up; resumed, it is due at its next time |
| `enqueueTask` | `POST /machines/{name}/tasks` | Puts a task — `{"task", "payload", "delay" \| "run_at", "key"}` — of a type the running version declares |
| `listTasks` | `GET /machines/{name}/tasks` | Its tasks, newest first, of one `state` and `task` type or all; a task that succeeded or was cancelled is kept a day, one that failed 30 |
| `getTask` | `GET /machines/{name}/tasks/{task}` | One task, with its payload |
| `retryTask` / `cancelTask` | `POST /machines/{name}/tasks/{task}/retry`, `…/cancel` | A failed task back on the queue, its attempts counted on; a waiting one taken off it |
| `listTaskTypes` | `GET /machines/{name}/task-types` | The task types the running version declared, with what each one's queue holds |

## Reaching the internet

A machine reaches the internet as any server does — a payment provider's API, a webhook of yours, a package registry — on any port but 25: send mail through a provider's API or its submission port (587). It reaches nothing of the platform's own network: not another project's machine and not the platform's services, except at the platform's public address, as any client of it does.

What a project's machines send to the internet is counted, in bytes, as **Machine internet traffic** on the project's usage page (`machines.egress`). What they send to the platform at its public address, what goes to their databases, and what they take from the internet is not. What the project's answers send its clients — its machines' answers, its modules' (files storage hands out among them) — is counted as **Response traffic** (`edge.egress`), in bytes on the wire.

A free project sends 5 GB a month at full speed: its machines' internet traffic and its response traffic together. Past it, until the month ends (UTC), it is slowed, never stopped — every byte still goes:
- its machines send to the internet at about 256 kbit/s between them — each copy of a machine its share; requests still go out, connections open at once and downloads keep going; what they send takes longer;
- its machines' answers to their clients go at about 256 kbit/s between them, as do the files its storage hands out (about 256 kbit/s for the project); its other answers — the API's JSON, realtime — are counted but not slowed.

Each machine's log says so when the slowing begins (`palbase: this project has sent 5 GB …`). What its machines send the project's databases and the platform at its public address is never slowed, DNS questions to the machine's resolvers keep a pace of their own, and a project that may use paid sizes is not slowed at all.

### Its outbound range

Every machine reaches the internet from one small range of addresses, the platform's, written as a CIDR (such as `203.0.113.8/29`). Studio shows it on the **Machines** page, under **Outbound address**. Add the whole range to a provider's allowlist when the provider — a bank, a payment or an SMS provider — lets in only the addresses it knows: a connection may leave from any address in it.

**The range is shared by every Palbase machine**, of every project. An allowlist of it lets in all of Palbase, not your project alone, so a provider must still know you by your own credentials, such as an API key. The range stays the same as the platform changes; a change of it is announced before it is made.

| Call | HTTP | What it answers |
|---|---|---|
| `getMachineNetwork` | `GET /machines/network` | `outbound_ips`: where machines reach the internet from, as ranges (CIDR); `shared`: `true`, every project's machines leave from them |

## Limits

| | |
|---|---|
| Machines per project | 5 |
| Copies per machine | 1 to 5 |
| What machines and databases reserve between them | 2 vCPU and 4096 MiB a project (a shared size reserves a quarter of its CPU ceiling, a dedicated one all of it; memory is reserved whole) |
| Builds | 50 a day (UTC) per project; one build at a time; 20 minutes at most each |
| Idle before a shared size sleeps | 15 minutes |
| Environment variables | 100, 64 KiB in all |
| Logs kept | 7 days, up to 1,200 lines a minute per machine |
| Traffic, free project | 5 GB a month at full speed, machine internet traffic and response traffic together; then machines' traffic and answers, and storage's files, at about 256 kbit/s until the month ends (UTC); see [Reaching the internet](#reaching-the-internet) |
| Connections to the internet open at once | Per copy of a machine, by its memory: 4,096 for 256 MiB, twice that for each doubling — 8,192 (`shared-512`), 16,384 (`shared-1024`), 32,768 (`dedicated-1x` and larger). One more is refused at once (`connection refused` / a reset). Connections to the platform, to your databases and DNS questions to the machine's resolvers are not counted. The cap keeps one machine from taking a server's whole connection table from the machines beside it: close connections you no longer use, and pool those you reuse |

## Related

- [Connecting GitHub](/docs/machines/github) — the repository, branch and directory a machine is built from
- [Builds, Logs & Rollback](/docs/machines/builds) — what a push does, and how to go back
- [Databases](/docs/machines/databases) — Postgres of your own, and giving one to a machine
- [Backend SDK](/docs/backend/overview) — the framework most machines run
- [Secrets](/docs/backend/secrets) — the secret sets a machine starts with
- [Server SDK](/docs/server/overview) — `createServer`, the client every call on this page goes through



<!-- ===== machines/github ===== -->

# Connecting GitHub

A machine is built from GitHub: a **repository**, a **branch** of it and a **directory** in it. The platform reaches your repositories through its GitHub App, **Palbase Cloud**, installed on the GitHub account that owns them. Once an installation is connected to the project, every push to a machine's branch that changes what the machine is built from is built and rolled out — there is no other deploy step, and no command to run.

## Connect the App

In Studio: **Backend › Machines › New machine › Connect GitHub**. Studio opens GitHub in a new tab:

1. GitHub asks who you are, and where to install **Palbase Cloud** — on your own account or an organization's, on every repository or the ones you choose.
2. GitHub brings you back to Palbase, which shows the accounts Palbase Cloud is installed on that you can push to, and where to install it on another.
3. You connect the one you choose by writing the project's ref. That is the confirmation that this installation is for this project.
4. Back in Studio, **Refresh**: the sheet lists the repositories you can push to.

The link Studio opens holds for 15 minutes. Studio is not on GitHub's way back — it hears nothing of it — which is why the sheet asks you to refresh rather than waiting for a reply.

With the secret key, the same steps are calls of the machines module (`createServer(...).machines` from [`palbase/server`](/docs/server/overview), or `Palbase.machines` inside a backend):

| Call | HTTP | What it does |
|---|---|---|
| `connectGitHub` | `POST /machines/github/connect` | Answers the address where the project's owner installs and connects Palbase Cloud (`url`, and `expires_at` 15 minutes on) |
| `listInstallations` | `GET /machines/github/installations` | The project's installations: the account each is on, and who connected it |
| `linkInstallation` | `POST /machines/github/installations` | Connects an installation with the user's own GitHub token for the App — a device flow's way, for a tool that is not a browser |
| `unlinkInstallation` | `DELETE /machines/github/installations/{installation}` | Disconnects one; refused while a machine is built from it |
| `listRepositories` | `GET /machines/github/repositories` | Every repository the installations reach: what a machine may be built from |

The CLI connects it the same way, and from a computer with no browser too:

```sh
palbase github:connect            # opens GitHub; back from it, you link the account by writing the environment's ref
palbase github:connect --device   # GitHub's device flow: a code you enter at github.com/login/device on any device
palbase github:list               # the accounts linked to the environment, and who linked each
palbase github:repos              # the repositories its machines may be built from
```

`--all-envs` links every environment of the project at once, and `--from <env>` links the installation another environment of the organization linked, with no GitHub sign-in. See the [CLI reference](/docs/cli/reference#github).

## Whose repositories

An installation reaches the repositories **the user who connected it can push to** — read when they connected it. A repository they could only read is not offered; connecting again picks up what they can push to now. Two consequences:

- A repository that does not appear in the sheet is either outside the installation (add it on GitHub, under the App's configuration) or one the connector cannot push to. Connect again as someone who can.
- A user who takes their authorization of the App back on GitHub disconnects what they connected.

Installations are a project's own, and in Studio every environment is a project of its own: connect GitHub in each environment whose machines are built from it. The machines of two environments may be built from one repository — a `staging` environment from the `staging` branch, `main` from `main`.

## Repository, branch, directory

A machine's `source`:

| Field | What it is |
|---|---|
| `repository` | The repository's full name, `owner/name` — one `listRepositories` answers |
| `branch` | The branch whose pushes are built and rolled out. Studio fills in the repository's default branch. |
| `path` | The directory the machine is built from, relative to the repository's root — the root when left out. Its `Dockerfile`, `package.json` and `.env.example` are read here. |
| `context` | What the build is given, when that is not `path` itself: a directory above `path`, or `.` for the root |

In Studio's **New machine** sheet these are **Repository**, **Branch** and **Directory**; the branch can be changed later in **Edit settings**, and a new branch is built before it rolls out.

### One repository, several machines

A monorepo holds several apps, and each can be its own machine — a `backend` built from `server/`, a `web` machine built from `web/`:

```text
acme/notes
├── server/          ← machine "backend": path "server"
│   ├── Dockerfile
│   ├── package.json
│   └── src/
├── web/             ← machine "web": path "web"
│   └── …
└── packages/shared/ ← read by both
```

An app that needs a sibling package — `server/` importing `packages/shared/` — is built with the repository's root as its context: `path: "server"`, `context: "."`. Its `Dockerfile`, which stays in `server/`, then copies from the root (`COPY packages/shared ./packages/shared`); without a Dockerfile, the build plans the whole context.

## Which pushes build which machines

A push to the branch is built for a machine **when it changes a file in what that machine's build is given**: its `context`, else its `path`, matched by whole directory names, case-sensitively. With the layout above:

| The push changes | `backend` (`server`) | `web` (`web`) | a machine with `context: "."` |
|---|---|---|---|
| `server/src/notes.ts` | built | — | built |
| `web/app/page.tsx` | — | built | built |
| `packages/shared/x.ts` | — | — | built |
| `README.md` | — | — | built |
| `serverless/x.ts` | — (not `server/`) | — | built |

A push that changes nothing a machine is built from leaves it as it runs, and does not count against the project's builds for the day. A machine built from the repository's root is built by every push.

Where GitHub's account of a push may not be everything it changed, every machine built from the branch is built: a forced push, a branch's first push, a push of 2,048 commits or more, and a commit that names no files (an empty commit among them) or 3,000 or more.

## What GitHub shows

Each build puts a check on its commit, named **Palbase Cloud · `<ref>`** for the `backend` machine and **Palbase Cloud · `<name>-<ref>`** for another: *Queued*, *Building*, *Waiting for configuration*, then *Rolled out*, *Build failed* or *Did not come up* — or *Left behind* when a newer commit of the branch is built first. The commit's checks are the quickest way to see what a push did; Studio's machine page has the same builds with their logs ([Builds, Logs & Rollback](/docs/machines/builds)).

## Disconnecting

Disconnect an installation (`unlinkInstallation`, `DELETE /machines/github/installations/{installation}`) once no machine is built from it — it is refused while one is. Delete or move the machines built from it first.

## Related

- [Machines](/docs/machines/overview) — sizes, addresses, environment and jobs
- [Builds, Logs & Rollback](/docs/machines/builds) — what a push does once it is built
- [Project Structure](/docs/getting-started/project-structure) — what a backend's directory holds
- [Quickstart](/docs/getting-started/quickstart) — connect GitHub and push a backend, end to end



<!-- ===== machines/builds ===== -->

# Builds, Logs & Rollback

Code reaches a machine one way: **a push to its branch**. The push is built into an image, the image is rolled out **beside the version that serves**, and traffic moves to it once it is up — so a request never meets a gap, and a version that does not come up never takes one. There is no deploy command, and nothing to run on your machine but `git push`.

This page follows one push from GitHub to traffic, then covers what you read on the way — the build's log, the machine's own lines — and how to go back.

## What a push does

```text
git push origin main
  └─ a build per machine whose directory the push changed   (Connecting GitHub)
       queued → building
         ├─ failed              the build's log says why
         ├─ waiting_config      .env.example names a variable the machine lacks
         └─ the image is ready
              └─ (a database's migrations, when this machine runs them: start)
                   ├─ testing           its tests run against the new version (test_command)
                   │    └─ failed       a test failed: the reason names it; it never takes traffic,
                   │                    the old one keeps serving, the migration is taken back
                   └─ the new version starts beside the old one
                        ├─ it answers its health check → traffic moves; the old one stops
                        │    └─ (migrations: complete, once nothing of the old version is left)
                        └─ it does not come up → the old one keeps serving
```

Each commit of the branch is built once for a machine, however often it is pushed. A project builds one thing at a time; a newer commit that arrives while an older one waits takes its place, and the older build ends `cancelled` (*Left behind* on its GitHub check).

A machine that deploys only after its commit's checks pass (`deploy_after_checks`, as Render's *After CI Checks Pass*) lets every push wait for its own checks, side by side. The first whose checks pass is built and leaves the older ones behind, so the machine only ever moves to a newer commit: an older push whose checks pass later is not built. A push whose checks fail ends `skipped`; the others keep waiting.

### Tests before it takes traffic

A machine that names a **test command** (`test_command`, as Render's pre-deploy command or a CI's test step) has every new build tested before it takes traffic — the build is `testing` meanwhile. Once its database's migration has started, the new version comes up beside the one that serves, **as it will run**: its env, its secrets, its database. The build's own image then runs the command in a shell (`bun test`, `npm test`) against it:

- `PALBASE_TEST_BASE_URL` is where the new version answers; `PALBASE_TEST_AUTH_URL` the project's auth;
- **test users** the run makes for its tests (`test_users`), each with its access token, are in `PALBASE_TEST_IDENTITIES` — `api.signInAs("alice")` from `palbase/backend/test` (or `palbase/server/testing`, whatever the backend is written with) acts as one; they are deleted when the run ends, however it ends.

The tests reach what the machine reaches — its database, the project's storage, mail and the rest — so they write as the machine does: write tests that leave the data as a real user's session would, and that do not depend on an empty database.

They pass, and the version takes traffic. One fails, and the build fails: its `reason` names the tests that failed, its GitHub check shows the end of what they printed (what the run was given that is secret written over), the version never takes traffic, the machine keeps the version it runs, and the migration is taken back. A run has 20 minutes. A build is tested as the machine named its tests when the build was released to it. `palbase test --machine <name>` runs the same command, as the same test users, on your computer.

### How the image is made

The build reads the machine's directory (its `path`):

- **With a `Dockerfile`** there, the build uses it, with the build context the machine names (its `context`, else its `path`).
- **Without one**, [Railpack](https://railpack.com) detects what the directory is — Node, Bun, Go, Python, … — and plans the image from it.

A `palbase/backend` app ships a `Dockerfile` (see [Project Structure](/docs/getting-started/project-structure)): its decorators need the TypeScript compiler options that Bun reads from `tsconfig.json`, and a Dockerfile says exactly how it is run. A build has 20 minutes, and a repository is built from at most 1 GiB and 100,000 files.

### `.env.example`: what the program must be given

A `.env.example` in the machine's directory is read as **the list of variables the program needs**: every `NAME=` line is a name (comments, blank lines and `PORT` are skipped; a value after `=` is ignored).

```text
# .env.example — the names this backend reads; their values live in Palbase.
PALBASE_URL=
PALBASE_PROJECT_ID=
PALBASE_SECRET_KEY=
```

When the build is done, every name is looked for among what the machine will start with: its own environment variables, its secret set, and what the platform gives it (`PALBASE_URL`, `PALBASE_PROJECT_ID`, `PALBASE_REPLICAS`, `PALBASE_PLATFORM_SECRET`, and with a database `PALBASE_DB_URL` and `PALBASE_DB_CONNECTIONS`). A name found nowhere stops the rollout: the build waits as **`waiting_config`** (*Waiting for variables* in Studio, *Waiting for configuration* on GitHub), its `missing_env` lists the names, and it **rolls out by itself once the machine has them** — add the secret, or the variable, and nothing has to be pushed again.

Without this file nothing is checked, and an app missing a setting is rolled out to fail at start. The version before it keeps serving either way, but the waiting build says what is wrong by name; the failed start says it in its logs.

## The rollout

The new version starts beside the one that serves, and is held to its [health check](/docs/machines/overview#the-health-check): 90 seconds to answer `2xx` at its health path. Up, it takes the traffic and the old version is stopped — a `palbase/backend` app finishes the requests in flight first (20 seconds at most), then runs its `onShutdown()`. Not up, it never takes a request: the old version keeps serving, the build's check on GitHub says *Did not come up*, and the machine's `state_reason` says why.

A change that is not a push rolls out the same way: a new size, port, number of copies, environment, secret set or health path, a changed secret of the machine's set, and a rollback.

**`SIGTERM` can come more than once.** A machine runs in a sandbox of its own (a small VM), and a version being stopped is sent `SIGTERM` twice, a few milliseconds apart. A `palbase/backend` app handles that. An app of your own should stop on the first and keep its handler for the rest: in Node and Bun `process.on("SIGTERM", …)`, not `process.once`. A process listening once dies of the second signal (exit 143), and its requests still in flight are cut (`503 machine_interrupted`).

### When a release migrates its database

A machine given a database with **Run migrations** on (`database.migrations: true`) migrates it as part of every release, with no step of yours:

1. **start** — before the new version starts, its image runs once with `PALBASE_DB_MIGRATE=start` and the owner's address: what the new version needs is added beside what the running version uses. The version rolls out only once start succeeded.
2. **rollout** — both versions run against the same tables.
3. **complete** — once the new version has served and nothing of the old one is left, the image runs once more with `PALBASE_DB_MIGRATE=complete`, and what only the old version used is removed.

A start the app itself refuses — a change the schema cannot make while both versions run, or rows that do not fit it — ends the release: the machine stays on the build that serves, and what start began is taken back (`rollback`). A start that was only cut off (the database restarting, a lock not had in time) is run again and picks up where it stopped. What these runs write is in the machine's logs, marked `migration`. The schema side of all this is [Schema changes](/docs/backend/migrations); the database side is [Databases](/docs/machines/databases).

One migration is open at a time, and a database's migrations are one machine's: a second machine asking to run them is refused (`409 database_migrated_elsewhere`).

## Builds

Studio's machine page (**Backend › Machines › `<name>`**) lists its **Builds**, newest first — every commit of the branch built for it, its state, and a **Running** badge on the one that serves. **Log** opens a build's log; **Roll back** is on every build that succeeded and does not run.

| State | What it means |
|---|---|
| `waiting_checks` | Waiting for its commit's checks on GitHub (`deploy_after_checks`); `reason` names what it waits for |
| `queued` | Waiting its turn: one build at a time per project |
| `building` | Being built |
| `testing` | Released to its machine; its tests (`test_command`) run against it before it takes traffic — they fail and it fails, `reason` naming them, and the machine runs what it ran |
| `waiting_config` | Built, waiting for what `.env.example` names (`missing_env`); rolls out once the machine has it |
| `succeeded` | Built and rolled out — or a newer build already had |
| `failed` | Not built, or not up; `reason` says which |
| `cancelled` | A newer commit was built first, the head of the branch was asked for (a deploy, or a change of source), or the machine was deleted |
| `skipped` | Its commit's checks did not pass, or did not end in time; nothing of it was built (`reason`) |

| Call | HTTP | What it answers |
|---|---|---|
| `listBuilds` | `GET /machines/{name}/builds` | A page of builds, newest first (20 by default, `next_cursor` for the next) |
| `getBuild` | `GET /machines/{name}/builds/{build}` | One build: its commit and message, state, reason, `missing_env`, whether it runs |
| `getBuildLog` | `GET /machines/{name}/builds/{build}/log` | The build's log, its last MiB — where a failure is. `404 log_not_ready` before the build has started; `404 no_log` for one that ended before it ran (its `reason` says why) |

## Logs

What the machine writes to stdout and stderr is kept — every copy, every version (one that never came up too), and its migration runs — for **7 days**, up to 1,200 lines a minute per machine; past that, the rest of that minute is not kept. Write one JSON object a line and each is one line to read back: `Log` from `palbase/backend` does exactly that, with the request's id on every line ([Backend SDK](/docs/backend/overview)).

Studio's machine page shows the last hour, the last 100, 500 or 2,000 lines of it. From a server, `readMachineLogs` (`GET /machines/{name}/logs`) answers NDJSON, one line object a line, oldest first:

| Query | |
|---|---|
| `since` | From when, inclusive (RFC 3339); an hour ago when left out, a week ago at most |
| `until` | Until when, exclusive; now when left out. Not with `follow`. |
| `lines` | How many lines at most, 1 to 5,000 (500 by default) — for a followed read, before it follows |
| `follow` | `true` holds the answer open and sends what the machine writes next |

Each line carries `ts` (to the nanosecond), `id` (ids sort as lines do, and the same line read twice has the same id), `stream` (`stdout` or `stderr`), `generation` (the machine's version that wrote it), `source` (`machine`, or `migration` for a migration run), `line` (what was written) and which copy wrote it.

```ts
// scripts/tail.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

type LogLine = { ts: string; id: string; stream: "stdout" | "stderr"; generation: number; source: "machine" | "migration"; line: string };

const since = new Date(Date.now() - 10 * 60_000).toISOString();
const { data } = await palbase.machines.readMachineLogs({ path: { name: "backend" }, query: { since, lines: 200 } });

for (const raw of (await data.text()).split("\n")) {
  if (!raw) continue;
  const l = JSON.parse(raw) as LogLine;
  console.log(l.ts, `v${l.generation}`, l.source, l.stream, l.line);
}
```

A followed read is held open for 5 minutes at most (and ends when the machine is deleted). A project holds 5 followed reads open at once; a sixth is `429 too_many_follows`. A reader whose connection ends goes on with `since=` the time of the last line it had — a line may then come twice, and its `id` says so.

## Rollback

**Roll back** returns the machine to one of its builds that succeeded: a **new version** of the machine, running that build's image, rolled out beside the one that serves like any other. It is the only change of what a machine runs that is not made by a push. The images of a machine's last 10 successful builds are kept; an older build is refused (`409 build_not_deployable`).

```ts
// scripts/rollback.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

// The build that ran before the one that serves.
const { data: page } = await palbase.machines.listBuilds({ path: { name: "backend" } });
const previous = page.builds.find((b) => b.state === "succeeded" && !b.running);
if (previous) {
  const { data: machine } = await palbase.machines.rollbackMachine({ path: { name: "backend" }, body: { build: previous.id } });
  console.log(`rolling out version ${machine.version}: ${previous.commit}`);
}
```

The next push to the branch is built and rolled out as usual, so a rollback holds until then. To keep a machine off a bad commit, revert it on the branch — or point the machine at another branch in **Edit settings**.

> **Note:** A rollback changes code, never data. Once a release's migration has completed, the build you return to reads the tables as that migration left them — a column it dropped is gone. A migration still open when its version is abandoned is taken back instead. Make a change an older build cannot read in two releases, so the one before keeps working: [Schema changes](/docs/backend/migrations).

## Related

- [Connecting GitHub](/docs/machines/github) — which pushes build which machines
- [Machines](/docs/machines/overview) — sizes, the health check, environment and secrets
- [Databases](/docs/machines/databases) — giving a machine a database, and its migrations
- [Schema changes](/docs/backend/migrations) — what start and complete do to your tables
- [Project Structure](/docs/getting-started/project-structure) — the Dockerfile and `.env.example` of a backend



<!-- ===== machines/databases ===== -->

# Databases

A project's **database** is Postgres 18 of its own, with pgvector and PostGIS, reached from anywhere over TLS with a password. Give one to a [machine](/docs/machines/overview) and the machine starts with its address; connect to it from anything else — `psql`, a migration tool, a BI tool, a server of your own — with the credentials Studio shows once.

A database is the project's, not a machine's. One may be given to several machines, and one machine — the one that runs its migrations — owns its schema. A [`palbase/backend`](/docs/backend/database) app declares that schema in TypeScript and migrates it on every release; anything else that connects is an ordinary Postgres client.

In Studio, databases live under **Database › Databases**. Each step below names the machines module's call beside the click, for a script that holds the secret key.

## Opening one

**Database › Databases › New database** asks for:

| Field | API | |
|---|---|---|
| **Name** | `name` | Lowercase letters, digits and dashes, starting with a letter, 32 at most; `main` when left out. It answers at `<name>-<ref>.db.palbase.studio`. |
| **Size** | `size` | One of the sizes below; `free` when left out. It can be changed later ([below](#changing-and-removing-one)) |
| **Allowed addresses** | `allow` | Who may connect, as addresses or CIDRs (`203.0.113.7`, `203.0.113.0/24`), 50 at most. Empty: anyone with the password. |
| **Backups kept** | `backup_days` | 1 to 35 days: how far back a [restore](/docs/machines/backups) reaches |

The database's volume is made and it starts; it answers once its state is `awake`. **The answer that opens it holds both of its passwords — the owner's and the application's — and no answer holds them again.** Studio shows them on the database's page once; copy them then. A password you did not keep is made new, not read back ([below](#passwords)).

```ts
// scripts/open-database.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

const { data: db } = await palbase.machines.createDatabase({
  body: { name: "main", size: "free", backup_days: 7 },
});
console.log(db.host, db.state); // main-<ref>.db.palbase.studio starting
```

A project has **3 databases** at most — a deleted one counts until it is purged — and **one of a free size** at a time.

## Sizes

| Size | CPU | Memory | Storage | Sleeps |
|---|---|---|---|---|
| `free` | 0.25 vCPU | 512 MiB | 1 GB | yes — and awake 400 hours a month at most |
| `hobby` | 0.25 vCPU | 512 MiB | 5 GB | yes |
| `shared-1g` | up to 1 vCPU | 1 GiB | 10 GB | never |
| `shared-2g` | up to 2 vCPU | 2 GiB | 25 GB | never |
| `shared-4g` | up to 2 vCPU | 4 GiB | 50 GB | never |
| `dedicated-1x` | 1 vCPU of its own | 4 GiB | 25 GB | never |
| `dedicated-2x` | 2 vCPU of its own | 8 GiB | 50 GB | never |

`free` is the size every project may open. The others are sizes that are paid for: open to an environment on Pay as you go with credit ([Billing](/docs/getting-started/billing)); another is refused one with `403 size_not_available`.

A size that sleeps is put to sleep when it is idle and **woken by the next connection**, in about 10 seconds; the client's connection waits for it. A `free` database awake for its 400 hours sleeps until the month ends, and a client is told so; one asleep for a week is **archived**, and its next connection brings it back from its backup. The other sizes never sleep and live on a disk of their own.

The size is chosen when the database is opened and can be changed later ([below](#changing-and-removing-one)). What a project's machines and databases reserve between them is held to its limit, and a size that does not fit is refused with `409 machines_over_limit`.

### When it is full

A database holding its size's storage turns **read-only**: a transaction takes no writes unless it asks to, and reads go on. `read_only`, `used_bytes` and `quota_bytes` on the database say where it stands. To make room, write in a transaction that asks for it — `BEGIN READ WRITE`, then `DROP`, `TRUNCATE`, or `DELETE` followed by `VACUUM FULL` (a `DELETE` alone frees no room). Once it holds less than 95% of its quota it takes writes again, within a minute.

## Connecting

Every database has two logins:

| Login | Who it is | What it is for |
|---|---|---|
| **Owner** | Owns the database and its tables | Migrations, `psql`, a tool that changes the schema (Prisma, …) |
| **App** | What a machine given the database connects as | Your app's queries. It cannot bypass row-level security; it may `SET ROLE anon`, `authenticated` or `service_role`. |

and two ways in:

| Port | Through | Use it for |
|---|---|---|
| `5432` | Postgres itself | Anything; the only choice for migrations, `LISTEN`, advisory locks and session settings |
| `6543` | PgBouncer, transaction pooling | Clients that open a connection per request (serverless functions). A session's `SET`, `LISTEN` and advisory locks do not hold here. |

TLS is required, and the URLs Studio gives check the server's name (`sslmode=verify-full`). A client that sends no TLS server name — libpq before 14, some drivers — connects as the user shown as **User for clients without SNI**, which carries the database's name in it.

**How to connect** (`getDatabaseCredentials`, `GET /databases/{name}/credentials`) answers everything but the passwords, ready to paste, for each login: a direct URL, a pooled URL, a `psql` command, a JDBC URL and the two lines of a Prisma schema's env (`DATABASE_URL` pooled for queries, `DIRECT_URL` for migrations). `[YOUR-PASSWORD]` stands where the password goes.

```text
postgresql://<owner-user>:[YOUR-PASSWORD]@main-<ref>.db.palbase.studio:5432/<database>?sslmode=verify-full
```

## Giving it to a machine

In the machine's **New machine** sheet or **Edit settings**, choose the **Database**, and whether this machine **runs its migrations**. Through the API it is the machine's `database`:

```ts
// scripts/give-database.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

await palbase.machines.updateMachine({
  path: { name: "backend" },
  body: { database: { name: "main", migrations: true } },
});
```

The machine is rolled out with two more variables:

- **`PALBASE_DB_URL`** — the database's address, as the **app** login. A `palbase/backend` app reads it by itself; any other program connects with it.
- **`PALBASE_DB_CONNECTIONS`** — how many connections to it **one copy** may hold. The database's connections are shared out among the copies of every machine given it, counted twice (a new version comes up beside the one that serves) and with a migration run's share apart. A `palbase/backend` app holds itself to it; a program of your own should size its pool by it. Copies the database could not serve are refused (`409 database_connections_short`), and the other machines given it roll out to their new share.

A machine's connection is a client like any other: it wakes a database that sleeps and keeps it awake while it holds one.

**Run migrations** (`migrations: true`) makes every release of the machine migrate the database before it serves — as the **owner**, with `PALBASE_DB_MIGRATE=start` before the rollout and `=complete` after ([Builds, Logs & Rollback](/docs/machines/builds#when-a-release-migrates-its-database)). A database's migrations are one machine's: a second machine asking for them is refused with `409 database_migrated_elsewhere`. The other machines given the database read and write it as the app login, and must read the schema the migrating machine declares.

A change of `database` gives it whole: `migrations` left out is `false`. `{ name: "" }` gives the machine none. A database that is not the project's is refused (`400 database_not_found`).

## Passwords

A password is shown once — when the database is opened, and when it is made new. **Make a new password** on the database's page (**New owner password**, **New app password**), or `changeDatabasePassword` (`POST /databases/{name}/password` with `role: "owner"` or `"app"`), answers the credentials with the new one; the other login carries `[YOUR-PASSWORD]`. The new password works once the database has taken it, a few seconds later.

- **Owner**: its current password stops working. Migrations, `psql` and anything else that connects as the owner need the new one — the machine that runs migrations is given it by the platform.
- **App**: the new password is set on a second app login, and the machines given the database move to it with **none of their connections refused**. The old login keeps working until the next change — so to shut out a leaked app password, make it new **twice**.

A change waits for the one before it to reach the database: `409 password_change_pending` with `Retry-After`, and the same while a database first starts.

## The SQL console

**Database › SQL** runs read-only SQL against a database — `SELECT`, `EXPLAIN`, `SHOW` — with autocomplete from its tables, a history and saved queries. It is `queryDatabase` (`POST /databases/{name}/sql`), and its rules are the module's:

- One statement, 64 KiB at most; two are refused (SQLSTATE `42601`).
- It runs as the **owner**, in a transaction that takes no writes and is always rolled back: a write is refused by Postgres (`25006`).
- It has 15 seconds (`57014`) and 5 seconds for a lock (`55P03`).
- It answers the columns and the first rows (1 to 1,000, `limit`), `truncated` when there were more, and how long it took. Values come as JSON: a timestamp in RFC 3339, `numeric` as a string, `bytea` as `\x` and its hex, `json` and `jsonb` as the JSON they hold.
- A statement Postgres refuses is `400 query_failed` with its message and its `sqlstate`.

`GET /databases/{name}/schema` answers what the console's autocomplete reads: every table outside Postgres' own schemas and Palgres', its columns in order — type as Postgres writes it, nullable, part of the primary key, the column a foreign key points at — and whether row-level security is on.

A sleeping database is woken for the console, the call held a few seconds (`503 database_waking` with `Retry-After` past that). A database being restored, or one that cannot start, is refused with `409`. A database runs a few console calls at once; past that, `429 too_many_queries`.

## Changing and removing one

`updateDatabase` (`PATCH /databases/{name}`, **Edit access and backups** in Studio) changes who may connect (`allow`), how many days of backups are kept (`backup_days`) and the database's size (`size`). Deleting one, taking it back and purging it are on [Backups & Restore](/docs/machines/backups#deleting-a-database).

A new size is answered at once with `202`: the database moves to it while it serves. Its sessions on the direct port end once, when it moves, and new logins wait a few seconds then. A change of size is refused with `409` when the database is already moving to another size (`database_resizing`), being brought back to a moment (`database_restoring`) or failed (`database_failed`), or when it holds more than the new size's storage (`database_too_large`); a smaller size waits until what the database holds has been measured, within minutes of its start (`database_not_measured`). A size that is paid for is refused with `403 size_not_available` while those sizes are not open.

| Call | HTTP | |
|---|---|---|
| `listDatabases` | `GET /databases` | The project's databases by name — deleted ones that may still be taken back among them |
| `getDatabase` | `GET /databases/{name}` | Its host and ports, size, `allow`, `backup_days`, state, how much it holds and how long it has been awake this month |
| `createDatabase` | `POST /databases` | Opens one; the answer holds both passwords, once |
| `updateDatabase` | `PATCH /databases/{name}` | Who may connect, and its backup days |
| `getDatabaseCredentials` | `GET /databases/{name}/credentials` | How to connect, without the passwords |
| `changeDatabasePassword` | `POST /databases/{name}/password` | A new owner or app password, shown once |

A database's `state` is `starting`, `awake`, `asleep`, `archived`, `restoring` or `failed` (`state_reason` says why).

## From the CLI

```sh
palbase databases:create main --size free --backup-days 7   # its passwords are kept on this computer
palbase databases:list
palbase db:url main --pooled                                 # a connection address for any tool
palbase db:shell main                                        # psql on it (it wakes if asleep)
palbase db:dump main --file main.dump                        # pg_dump's custom format, as its owner
palbase databases:update main --allow 203.0.113.0/24        # who may connect; --size moves it to another size
palbase db:copy --from main --to staging                     # one environment's data into another's
```

`palbase databases:sizes` lists the sizes, `palbase databases:password:reset <name> --role owner|app` makes a login's password new, and `palbase databases:restore <name> --to <time>` brings a database back to a moment ([Backups & Restore](/docs/machines/backups)). The schema commands — `db:plan`, `db:push`, `db:migrate`, `db:pull`, `db:seed`, `db:types` — work on the schema of a `palbase/backend` app ([Schema changes](/docs/backend/migrations)). Every command is in the [CLI reference](/docs/cli/reference#databases).

## Related

- [Backups & Restore](/docs/machines/backups) — point-in-time restore, and deleting, taking back and purging a database
- [Database](/docs/backend/database) — the queries a `palbase/backend` app runs against it
- [Schema](/docs/backend/schema) · [Schema changes](/docs/backend/migrations) — the schema a release migrates
- [Row-Level Security](/docs/backend/row-level-security) — what the app login cannot bypass
- [Machines](/docs/machines/overview) — the machines a database is given to



<!-- ===== machines/backups ===== -->

# Backups & Restore

Every database is backed up continuously: a base backup, and its write-ahead log archived once a minute. You choose how many days of it are kept, and within those days you can **bring the database back to any moment** — the state it held at 14:02:37 last Tuesday, before the migration or the `DELETE` that went wrong. A database you delete is kept, with its backups, for 7 days, and can be taken back until then.

There is nothing to schedule and nothing to turn on: the backups are part of the database, at every size.

## How long backups are kept

A database keeps its backups for **`backup_days`** days — 1 to 35, **7** when left out. In Studio it is **Backups kept** on **New database**, and on the database's page under **Edit access and backups**; through the API, `backup_days` on `createDatabase` or `updateDatabase` (`PATCH /databases/{name}`).

A restore reaches back as far as its backups do. Shortening the days shortens how far back you can go from then on.

## Bringing a database back to a moment

On the database's page (**Database › Databases › `<name>`**), **Point-in-time restore** takes a moment — **Restore to** — and brings the database back to it. Through the API it is `restoreDatabase` (`POST /databases/{name}/restore`) with the moment as an RFC 3339 time:

```ts
// scripts/restore.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

// Back to the moment before the bad deploy.
const { status, data: db } = await palbase.machines.restoreDatabase({
  path: { name: "main" },
  body: { to: "2026-10-06T14:02:37Z" },
});
console.log(status, db.state); // 202 restoring
```

What a moment can be:

- one since the database was opened — or since it was last brought back,
- within its backup days,
- and **not of the last two minutes**: the log is archived once a minute, and the newest of it is not in a backup yet.

A moment outside that is refused with `400 invalid_restore_point`, whose description names the earliest and the latest moment you can ask for. A database already being brought back is refused with `409 database_restoring`.

What a restore does:

- The answer is `202`, and the database's state is **`restoring`**. It is **down meanwhile**: it does not answer, and its clients are told it is being restored.
- It starts again with the data it held at that moment — every database in it, the ones its owner made too.
- Its logins' **passwords are as they are now**, not as they were then: nothing that connects needs a new one.
- The machines given it reconnect when it is back. A `palbase/backend` app answers its requests meanwhile with `503 database_unavailable` and `Retry-After`.

> **Note:** A restore brings the **data** back, not the code. The schema at that moment is the one the machine that migrates the database had then. If a release since then migrated it, the version that serves now may expect columns the restored database does not have: return the machine to the build of that moment too ([Rollback](/docs/machines/builds#rollback)), or push the schema it needs.

A restore emits `database.restoring` to the project's webhook. After it, the database's history starts again: the next restore reaches back to when this one was made, and not before.

## Deleting a database

**Delete database** on the database's page (`deleteDatabase`, `DELETE /databases/{name}`) takes it away: **it stops answering at once.** Its volume and its backups are kept for **7 days**, and until then it can be taken back. Its name stays taken until it is purged, and it counts toward the project's 3 databases.

A database a machine is given cannot be deleted — `409 database_in_use`. Give that machine another database or none first (`updateMachine` with `database: { name: "" }`, or **Database: No database** in **Edit settings**).

### Taking it back

**Undelete** on its page (`undeleteDatabase`, `POST /databases/{name}/undelete`) takes a deleted database back within its 7 days: it starts again on the volume and backups it had, with the data it had. A database that is not deleted is refused with `409 database_not_deleted`.

### Purging it now

**Purge database** (`purgeDatabase`, `POST /databases/{name}/purge`) takes a deleted database away **for good, now**, instead of at the end of its 7 days: its volume and its backups are removed, it no longer counts toward the project's databases, and its name is free once it has gone (`409 database_purging` for a new database of that name until then). **It cannot be taken back.** A database that is not deleted is refused (`409 database_not_deleted`); one purged already is answered `204` again.

`listDatabases` (`GET /databases`) lists the deleted databases that may still be taken back beside the others, each with its `deleted_at` and `purge_after` — when its volume and backups go for good.

| What you do | Its data | Its name | Counts toward the 3 |
|---|---|---|---|
| Delete | kept 7 days, with its backups | taken | yes, until purged |
| Undelete (within 7 days) | back, as it was | — | yes |
| Purge | gone, now | free once it has gone | no |
| 7 days pass | gone | free | no |

The events: `database.deleted`, `database.undeleted` and `database.purged`.

## Related

- [Databases](/docs/machines/databases) — sizes, logins, connecting, and the SQL console
- [Builds, Logs & Rollback](/docs/machines/builds) — returning a machine to an earlier build
- [Schema changes](/docs/backend/migrations) — what a release does to the tables
- [Webhooks](/docs/server/webhooks) — the project's events, `database.*` among them