+2 -2

packages/docs/docs/README.md

reviewed

··· 2 2 3 3 HappyView is the best way to build an [AppView](https://atproto.com/guides/glossary#app-view) for the [AT Protocol](https://atproto.com). Upload your [lexicon](reference/glossary.md#at-protocol-terms) schemas and get a fully functional AppView, complete with [XRPC](reference/glossary.md#at-protocol-terms) endpoints, OAuth, real-time network sync, and historical [backfill](guides/backfill.md), without writing a single line of server code. 4 4 5 5 - Building an AppView from scratch means wiring up firehose connections, record storage, XRPC routing, OAuth flows, and PDS write proxying before you can even think about your application. HappyView handles all of that. Define your data model with lexicons, add custom logic with Lua scripts when you need it, and ship your app. 5 5 + Building an AppView from scratch means wiring up real-time event streams, record storage, XRPC routing, OAuth flows, and PDS write proxying before you can even think about your application. HappyView handles all of that. Define your data model with lexicons, add custom logic with Lua scripts when you need it, and ship your app. 6 6 7 7 ## Features 8 8 ··· 16 16 17 17 - **Schema-first**: Your Lexicons are the source of truth. Upload a schema and HappyView derives endpoints, indexing rules, and network sync from it. You describe _what_ your data looks like; HappyView figures out the rest. 18 18 19 19 - - **Zero boilerplate**: HappyView handles AppView infrastructure (firehose, backfill, OAuth, PDS proxying) for you. You should be writing application logic from minute one, not plumbing. 19 19 + - **Zero boilerplate**: HappyView handles AppView infrastructure (Jetstream, backfill, OAuth, PDS proxying) for you. You should be writing application logic from minute one, not plumbing. 20 20 21 21 - **Runtime-configurable**: Lexicons can be added, updated, and removed without restarting the server. New endpoints and sync rules take effect immediately, so you can iterate on your data model in real time. 22 22

+30 -31

packages/docs/docs/getting-started/authentication.md

reviewed

··· 3 3 HappyView has two distinct authentication surfaces: 4 4 5 5 - **XRPC** (`/xrpc/*`) — client-level identification via an **API client key** on every request, plus optional user-level AT Protocol OAuth for endpoints that need a specific user's identity (e.g. procedures that write to a PDS). 6 6 - - **Admin API** (`/admin/*`) — user-level authentication via session cookies, admin API keys, or service auth JWTs, gated by [permissions](../guides/permissions.md). 6 6 + - **Admin API** (`/admin/*`) — user-level authentication via admin API keys or service auth JWTs, gated by [permissions](../guides/permissions.md). 7 7 8 8 ## Which endpoints require what? 9 9 10 10 - | Endpoint type | Client identification | User authentication | 11 11 - | ----------------------------------- | ------------------------ | ------------------------------------------------------------------------------------ | 12 12 - | Queries (`GET /xrpc/{method}`) | `X-Client-Key` required | Optional — DPoP auth if the query needs to know who the user is | 13 13 - | Procedures (`POST /xrpc/{method}`) | `X-Client-Key` required | Required — DPoP auth so HappyView can proxy writes to the user's PDS | 14 14 - | Admin API (`/admin/*`) | — | Required — session cookie, admin API key, or service auth JWT with the right [permissions](../guides/permissions.md) | 15 15 - | Health check (`GET /health`) | — | — | 10 10 + | Endpoint type | Client identification | User authentication | 11 11 + | ---------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------ | 12 12 + | Queries (`GET /xrpc/{method}`) | `X-Client-Key` required | Optional — DPoP auth if the query needs to know who the user is | 13 13 + | Procedures (`POST /xrpc/{method}`) | `X-Client-Key` required | Required — DPoP auth so HappyView can proxy writes to the user's PDS | 14 14 + | Admin API (`/admin/*`) | — | Required — admin API key or service auth JWT with the right [permissions](../guides/permissions.md) | 15 15 + | Health check (`GET /health`) | — | — | 16 16 17 17 ## XRPC: API client identification 18 18 ··· 22 22 23 23 HappyView resolves the client key from the first of: 24 24 25 25 - 1. The session cookie, if the user logged in through this client's OAuth flow (the cookie carries the `client_key` that minted it). 26 26 - 2. The `X-Client-Key` request header. 27 27 - 3. A `client_key` query-string parameter. 25 25 + 1. The `X-Client-Key` request header. 26 26 + 2. A `client_key` query-string parameter. 28 27 29 28 On top of the client key, HappyView does best-effort validation that the caller actually controls the client: 30 29 ··· 52 51 53 52 Queries that don't care who is calling need nothing more than the client key. Procedures — and queries whose Lua scripts read the caller's DID — need a real AT Protocol OAuth session. 54 53 55 55 - XRPC routes only accept **DPoP auth** (`Authorization: DPoP <token>` + `DPoP` proof header + `X-Client-Key`). Bearer tokens, service auth JWTs, and session cookies are not accepted on XRPC endpoints. 54 54 + XRPC routes only accept **DPoP auth** (`Authorization: DPoP <token>` + `DPoP` proof header + `X-Client-Key`). Bearer tokens and service auth JWTs are not accepted on XRPC endpoints. 56 55 57 56 Third-party apps authenticate users through the [DPoP key provisioning](#dpop-key-provisioning-for-third-party-apps) flow: your app gets a DPoP keypair from HappyView, runs a standard OAuth flow with the user's PDS using that keypair, then registers the resulting tokens back with HappyView. 58 57 ··· 86 85 87 86 For procedures, HappyView proxies the write to the user's PDS using the stored OAuth session (see [Proxying procedures](#proxying-procedures-to-the-users-pds) below). 88 87 89 89 - :::note 90 90 - The HappyView dashboard uses a separate cookie-based OAuth flow where HappyView itself acts as the OAuth server. This is only for the dashboard — third-party apps always use DPoP key provisioning. 91 91 - ::: 92 92 - 93 88 ## Admin API: user authentication 94 89 95 95 - Admin endpoints don't use API clients. They require a real HappyView user, identified by one of three methods: 96 96 - 97 97 - ### Session cookie (dashboard) 98 98 - 99 99 - When you log in to the dashboard via AT Protocol OAuth, HappyView sets a signed, HttpOnly session cookie containing your DID. That cookie is honored on admin endpoints as long as the DID is a HappyView user with the required permission for the call. 90 90 + Admin endpoints don't use API clients. They require a real HappyView user, identified by one of two methods: 100 91 101 92 ### Admin API key 102 93 ··· 125 116 126 117 ### Admin access and the first user 127 118 128 128 - On a fresh deployment, the `users` table is empty. The first authenticated request to any admin endpoint auto-bootstraps that user as the **super user** with all permissions granted — so the first handle to log in owns the instance. 119 119 + On a fresh deployment, the `users` table is empty. The first authenticated request to any admin endpoint auto-bootstraps that user as the **super user** with all permissions granted. This includes logging in to the dashboard — the dashboard makes admin API calls on your behalf, so the first person to log in becomes the super user. 129 120 130 130 - To add more users after that, use `POST /admin/users` or the [dashboard](dashboard.md). You can assign permissions individually or use a template (`viewer`, `operator`, `manager`, `full_access`). See [Admin API](../reference/admin-api.md#user-management) for details. 121 121 + To add more users after that, use `POST /admin/users` or the [dashboard](dashboard.md). You can assign permissions individually or use a template (`viewer`, `operator`, `manager`, `full_access`). See [Admin API — Users](../reference/admin/users.md) for details. 131 122 132 123 ## Proxying procedures to the user's PDS 133 124 134 134 - When a client calls an XRPC procedure that writes a record, HappyView proxies the write to the user's PDS. There are two auth paths that support this: 125 125 + When a client calls an XRPC procedure that writes a record, HappyView proxies the write to the user's PDS. This requires a DPoP-authenticated session — the app must have gone through the [DPoP key provisioning](#dpop-key-provisioning-for-third-party-apps) flow and registered tokens for the user. HappyView uses the app's provisioned DPoP key to generate fresh proofs and attach the stored access token to the outbound PDS request. 135 126 136 136 - - **Cookie auth (dashboard)** — `atrium-oauth` attaches a DPoP proof and a DPoP-bound access token to the outbound request automatically. 137 137 - - **DPoP key provisioning (third-party apps)** — HappyView uses the app's provisioned DPoP key to generate fresh proofs and attach the stored access token (see below). 138 138 - 139 139 - A request that only carries an `X-Client-Key` header (no session cookie or DPoP token) can hit queries but can't proxy writes — there's no user to write as. Service auth JWTs and admin API keys similarly don't carry a user session. 127 127 + A request that only carries an `X-Client-Key` header (no DPoP token) can hit queries but can't proxy writes — there's no user to write as. 140 128 141 129 ## DPoP key provisioning for third-party apps 142 130 143 143 - Third-party apps that want HappyView to make PDS writes on behalf of their users use the **DPoP key provisioning** flow instead of cookie auth. This avoids browser-based redirects through HappyView's domain, which can be blocked by Firefox's Bounce Tracker Protection. 131 131 + Third-party apps that want HappyView to make PDS writes on behalf of their users use the **DPoP key provisioning** flow. This avoids browser-based redirects through HappyView's domain, which can be blocked by Firefox's Bounce Tracker Protection. 144 132 145 133 The idea: the app gets a DPoP keypair from HappyView, uses that keypair during its own OAuth flow with the user's PDS, then registers the resulting tokens back with HappyView. From that point on, XRPC requests authenticated with `Authorization: DPoP <access_token>` plus a `DPoP` proof header and `X-Client-Key` will have HappyView proxy writes using the stored session. 146 134 ··· 184 172 ```json 185 173 { 186 174 "provision_id": "hvp_...", 187 187 - "dpop_key": { "kty": "EC", "crv": "P-256", "x": "...", "y": "...", "d": "..." } 175 175 + "dpop_key": { 176 176 + "kty": "EC", 177 177 + "crv": "P-256", 178 178 + "x": "...", 179 179 + "y": "...", 180 180 + "d": "..." 181 181 + } 188 182 } 189 183 ``` 190 184 ··· 223 217 "provision_id": "hvp_...", 224 218 "pkce_verifier": "...", 225 219 "did": "did:plc:user123", 226 226 - ... 220 220 + "access_token": "...", 221 221 + "refresh_token": "...", 222 222 + "expires_at": "2026-04-17T00:00:00Z", 223 223 + "scopes": "atproto transition:generic", 224 224 + "pds_url": "https://bsky.social", 225 225 + "issuer": "https://bsky.social" 227 226 } 228 227 ``` 229 228 ··· 283 282 - [JavaScript SDK](../sdk/overview.md) — authenticate and make XRPC calls from JavaScript 284 283 - [Permissions](../guides/permissions.md) — full list of permissions and what each one grants 285 284 - [API Keys](../guides/api-keys.md) — create scoped admin API keys for automation 286 286 - - [Admin API — API Clients](../reference/admin-api.md#api-clients) — register API clients and configure rate limits 285 285 + - [Admin API — API Clients](../reference/admin/api-clients.md) — register API clients and configure rate limits

+1 -1

packages/docs/docs/getting-started/configuration.md

reviewed

··· 9 9 | `DATABASE_URL` | yes | --- | Database connection string. SQLite (`sqlite://path/to/db?mode=rwc`) or Postgres (`postgres://user:pass@host/db`) | 10 10 | `DATABASE_BACKEND` | no | auto-detected | Force `sqlite` or `postgres`. Auto-detected from `DATABASE_URL` scheme if not set | 11 11 | `PUBLIC_URL` | yes | --- | Public-facing URL for HappyView (used for OAuth callbacks, e.g. `https://happyview.example.com`) | 12 12 - | `SESSION_SECRET` | no | dev default | Secret key for signing session cookies. **Must be set in production** | 12 12 + | `SESSION_SECRET` | no | dev default | Secret key for signing session cookies (at least 64 characters). **Must be set in production** | 13 13 | `HOST` | no | `0.0.0.0` | Bind host | 14 14 | `PORT` | no | `3000` | Bind port | 15 15 | `JETSTREAM_URL` | no | `wss://jetstream1.us-east.bsky.network` | Jetstream WebSocket URL for real-time record streaming |

+61 -4

packages/docs/docs/getting-started/dashboard.md

reviewed

··· 1 1 # Dashboard 2 2 3 3 - HappyView ships with a web dashboard that provides a visual interface for everything the [admin API](../reference/admin-api.md) offers: managing lexicons, viewing indexed records, and monitoring backfill jobs. It runs as a separate Next.js application alongside the Rust backend and authenticates via AT Protocol OAuth. 3 3 + HappyView ships with a web dashboard that provides a visual interface for everything the [admin API](../reference/admin-api.md) offers. It runs as a separate Next.js application alongside the Rust backend and authenticates via AT Protocol OAuth. 4 4 5 5 - On a fresh deployment with no users in the database, the first handle to log in is automatically bootstrapped as the super user with all permissions — so log in with the handle you want to own the instance first. 5 5 + On a fresh deployment with no users in the database, the first person to log in to the dashboard is automatically bootstrapped as the super user with all permissions — so log in with the handle you want to own the instance first. 6 6 7 7 - ## Adding a lexicon 7 7 + ## Lexicons 8 8 9 9 - Navigate to **Lexicons > Add Lexicon** and choose **Local** or **Network**. 9 9 + Navigate to **Lexicons** to see all uploaded lexicons. Each entry shows the NSID, type (record, query, procedure), and whether a Lua script is attached. 10 10 + 11 11 + ### Adding a lexicon 12 12 + 13 13 + Click **Add Lexicon** and choose **Local** or **Network**. 10 14 11 15 **Local** lexicons are defined by you. The editor shows two side-by-side panels (stacked on mobile): 12 16 ··· 35 39 36 40 See [Lua Scripting](../guides/scripting.md) for the full runtime reference and examples. 37 41 42 42 + ## Records 43 43 + 44 44 + Navigate to **Records** to browse all indexed AT Protocol records. Records are grouped by collection and searchable. Each record shows its AT URI, author DID, and the raw record JSON. 45 45 + 46 46 + ## Backfill 47 47 + 48 48 + Navigate to **Backfill** to view and manage backfill jobs. You can start a new backfill for any record-type lexicon to import historical records from the network. The page shows job status, progress (repos processed / total), and record counts. See [Backfill](../guides/backfill.md) for how the process works. 49 49 + 50 50 + ## Users 51 51 + 52 52 + Navigate to **Users** to manage who can access the admin API and dashboard. You can add users by DID, assign permissions individually or via a template (`viewer`, `operator`, `manager`, `full_access`), and remove users. The super user is highlighted and has all permissions by default. See [Permissions](../guides/permissions.md) for what each permission grants. 53 53 + 54 54 + ## Events 55 55 + 56 56 + Navigate to **Events** to view the audit log of admin actions. Events include user creation, lexicon uploads, permission changes, backfill starts, and more. Each entry shows the event type, severity, actor, subject, and timestamp. Events are retained for the number of days configured by `EVENT_LOG_RETENTION_DAYS` (default 30). 57 57 + 58 58 + ## Settings 59 59 + 60 60 + The **Settings** section contains several sub-pages: 61 61 + 62 62 + ### General 63 63 + 64 64 + Configure instance-level settings: application name, logo, terms of service URL, and privacy policy URL. These values appear on OAuth authorization screens and can also be set via environment variables — dashboard values take precedence. 65 65 + 66 66 + ### API Clients 67 67 + 68 68 + Register and manage third-party API clients. Each client gets an `hvc_…` client key and `hvs_…` client secret. You can configure the client type (confidential or public), allowed origins, scopes, and per-client rate limits. See [Authentication — API client identification](authentication.md#xrpc-api-client-identification) for how clients are used. 69 69 + 70 70 + ### API Keys 71 71 + 72 72 + Create and revoke admin API keys for automation. Each key is scoped to specific permissions and tied to the creating user. See [API Keys](../guides/api-keys.md) for details. 73 73 + 74 74 + ### Users 75 75 + 76 76 + An alternative path to the top-level Users page for managing user accounts and permissions. 77 77 + 78 78 + ### Plugins 79 79 + 80 80 + Manage installed plugins and configure plugin secrets. Plugins extend HappyView with additional functionality. Plugin secrets are encrypted at rest when `TOKEN_ENCRYPTION_KEY` is configured. See [Plugins](../guides/plugins.md) for details. 81 81 + 82 82 + ### Labelers 83 83 + 84 84 + Configure labeler subscriptions for content labeling. See [Labelers](../guides/labelers.md) for details. 85 85 + 86 86 + ### Environment Variables 87 87 + 88 88 + View the current values of all environment variables that affect HappyView's behavior. This is a read-only view — values are set via your deployment environment, not the dashboard. 89 89 + 90 90 + ### Accounts 91 91 + 92 92 + Manage connected AT Protocol accounts used by the instance. 93 93 + 38 94 ## Next steps 39 95 40 96 - [Lexicons](../guides/lexicons.md) — how lexicons drive HappyView's indexing and routing 41 97 - [Lua Scripting](../guides/scripting.md) — write custom query and procedure logic 42 98 - [Permissions](../guides/permissions.md) — manage user access to admin features 99 99 + - [Configuration](configuration.md) — full list of environment variables

+1 -1

packages/docs/docs/getting-started/deployment/docker.md

reviewed

··· 14 14 cp .env.example .env 15 15 ``` 16 16 17 17 - Edit `.env` and set at least `PUBLIC_URL` (e.g. `http://localhost:3000`) and `SESSION_SECRET`. The defaults work for everything else. See [Configuration](../configuration.md) for the full list of environment variables. 17 17 + Edit `.env` and set at least `PUBLIC_URL` (e.g. `http://localhost:3000`) and `SESSION_SECRET` (at least 64 characters). The defaults work for everything else. See [Configuration](../configuration.md) for the full list of environment variables. 18 18 19 19 ## 2. Start the stack 20 20

+4 -1

packages/docs/docs/getting-started/deployment/railway.md

reviewed

··· 8 8 9 9 After deploying the template, you'll need to configure a few things before the stack works properly: 10 10 11 11 - 1. **Set your session secret.** In the HappyView service variables, set `SESSION_SECRET` to a strong random value. This is used to sign session cookies. 11 11 + 1. **Set your session secret.** In the HappyView service variables, set `SESSION_SECRET` to a random string of at least 64 characters. This is used to sign session cookies. 12 12 + ```sh 13 13 + openssl rand -base64 48 14 14 + ``` 12 15 13 16 2. **Assign a public domain.** In the Railway dashboard, add a public domain to the HappyView service. The service needs a publicly accessible URL for OAuth callbacks. Set `PUBLIC_URL` to this domain (e.g. `https://happyview-production.up.railway.app`). 14 17 :::note

+3 -3

packages/docs/docs/guides/backfill.md

reviewed

··· 7 7 - **Automatically** when a record-type lexicon is uploaded with `backfill: true` (the default). See [Lexicons - Backfill flag](lexicons.md#backfill-flag). 8 8 - **Manually** via `POST /admin/backfill` or the [dashboard](../getting-started/dashboard.md). You can scope a manual backfill to a specific collection, a specific DID, or both. 9 9 10 10 - See the [admin API](../reference/admin-api.md#backfill) for endpoint details. 10 10 + See the [admin API](../reference/admin/backfill.md) for endpoint details. 11 11 12 12 ## How it works 13 13 ··· 19 19 20 20 ## Job lifecycle 21 21 22 22 - A backfill job moves through `pending → running → completed` (or `failed`). Unlike earlier versions of HappyView, the job is only marked `completed` once every discovered repo has been processed end-to-end — there is no separate downstream queue. Progress is visible in real time on the dashboard's Backfill page. 22 22 + A backfill job moves through `pending → running → completed` (or `failed`). Unlike earlier versions of HappyView that relied on Tap, the job is only marked `completed` once every discovered repo has been processed end-to-end — there is no separate downstream queue. Progress is visible in real time on the dashboard's Backfill page. 23 23 24 24 If a job fails midway, the `error` field contains the failure reason. Re-running the backfill resumes from scratch but is idempotent (records are upserted by URI). 25 25 ··· 34 34 ## Next steps 35 35 36 36 - [Lexicons](lexicons.md#backfill-flag): Control whether lexicons trigger backfill on upload 37 37 - - [Admin API](../reference/admin-api.md#backfill): Full reference for backfill endpoints 37 37 + - [Admin API — Backfill](../reference/admin/backfill.md): Full reference for backfill endpoints

+1

packages/docs/docs/guides/database-setup.md

reviewed

··· 72 72 73 73 ## Next steps 74 74 75 75 + - [SQLite → Postgres migration](sqlite-to-postgres-migration.md) — switch an existing instance from SQLite to Postgres 75 76 - [Postgres → SQLite migration](postgres-to-sqlite-migration.md) — switch an existing instance from Postgres to SQLite 76 77 - [Lua scripting](scripting.md) — write queries that target either backend 77 78 - [Configuration](../getting-started/configuration.md) — `DATABASE_URL` and related variables

+105

packages/docs/docs/guides/developing-plugins.md

reviewed

··· 1 1 + # Developing Plugins 2 2 + 3 3 + This guide covers how to build your own HappyView WASM plugins. For installing and configuring plugins, see the [Plugins guide](plugins.md). 4 4 + 5 5 + See the [happyview-plugins](https://github.com/gamesgamesgamesgames/happyview-plugins) repository for examples and the plugin SDK. 6 6 + 7 7 + ## Plugin Manifest 8 8 + 9 9 + Each plugin has a `manifest.json` that describes its metadata: 10 10 + 11 11 + ```json 12 12 + { 13 13 + "id": "steam", 14 14 + "name": "Steam", 15 15 + "version": "1.0.0", 16 16 + "api_version": "1", 17 17 + "description": "Import your Steam game library and playtime data.", 18 18 + "icon_url": "https://example.com/steam-icon.png", 19 19 + "auth_type": "openid", 20 20 + "wasm_file": "steam.wasm", 21 21 + "required_secrets": [ 22 22 + { 23 23 + "key": "PLUGIN_STEAM_API_KEY", 24 24 + "name": "Steam Web API Key", 25 25 + "description": "Get your API key at steamcommunity.com/dev/apikey" 26 26 + } 27 27 + ] 28 28 + } 29 29 + ``` 30 30 + 31 31 + | Field | Description | 32 32 + | ------------------ | ----------------------------------------------------- | 33 33 + | `id` | Unique plugin identifier | 34 34 + | `name` | Display name | 35 35 + | `version` | Semantic version | 36 36 + | `api_version` | Plugin API version (currently "1") | 37 37 + | `description` | Brief description shown during install | 38 38 + | `icon_url` | Optional icon URL | 39 39 + | `auth_type` | Authentication type: `oauth2`, `openid`, or `api_key` | 40 40 + | `wasm_file` | WASM binary filename (default: `plugin.wasm`) | 41 41 + | `required_secrets` | Array of secrets the plugin needs | 42 42 + 43 43 + ## API Endpoints 44 44 + 45 45 + ### Public Endpoints 46 46 + 47 47 + | Endpoint | Description | 48 48 + | --------------------------------------- | ---------------------------------------------- | 49 49 + | `GET /external-auth/providers` | List available auth providers | 50 50 + | `GET /external-auth/accounts` | List user's linked accounts | 51 51 + | `GET /external-auth/{plugin}/authorize` | Start OAuth flow | 52 52 + | `GET /external-auth/{plugin}/callback` | OAuth callback handler | 53 53 + | `POST /external-auth/{plugin}/sync` | Sync data from linked account | 54 54 + | `POST /external-auth/{plugin}/unlink` | Unlink account | 55 55 + | `POST /external-auth/{plugin}/connect` | Connect with API key (for `api_key` auth type) | 56 56 + 57 57 + ### Admin Endpoints 58 58 + 59 59 + | Endpoint | Description | 60 60 + | --------------------------------------- | ------------------------------------------- | 61 61 + | `GET /admin/plugins` | List installed plugins | 62 62 + | `POST /admin/plugins` | Install a plugin | 63 63 + | `POST /admin/plugins/preview` | Preview plugin before installing | 64 64 + | `GET /admin/plugins/official` | Browse the official plugin registry catalog | 65 65 + | `DELETE /admin/plugins/{id}` | Remove a plugin | 66 66 + | `POST /admin/plugins/{id}/reload` | Reload plugin from source | 67 67 + | `POST /admin/plugins/{id}/check-update` | Check whether a newer version is available | 68 68 + | `GET /admin/plugins/{id}/secrets` | Get configured secrets (masked) | 69 69 + | `PUT /admin/plugins/{id}/secrets` | Update plugin secrets | 70 70 + 71 71 + The dashboard's **Settings > Plugins** page calls `GET /admin/plugins/official` to populate the install browser, and `POST /admin/plugins/{id}/check-update` to display update badges on installed plugins. 72 72 + 73 73 + ## Plugin Exports 74 74 + 75 75 + Plugins must export these functions: 76 76 + 77 77 + | Export | Signature | Description | 78 78 + | ------------------- | ----------------------------- | ---------------------------- | 79 79 + | `alloc` | `(size: u32) -> u32` | Allocate memory | 80 80 + | `dealloc` | `(ptr: u32, size: u32)` | Deallocate memory | 81 81 + | `get_authorize_url` | `(ptr: u32, len: u32) -> i64` | Generate OAuth authorize URL | 82 82 + | `handle_callback` | `(ptr: u32, len: u32) -> i64` | Handle OAuth callback | 83 83 + | `refresh_tokens` | `(ptr: u32, len: u32) -> i64` | Refresh expired tokens | 84 84 + | `get_profile` | `(ptr: u32, len: u32) -> i64` | Get external profile info | 85 85 + | `sync_account` | `(ptr: u32, len: u32) -> i64` | Sync data and return records | 86 86 + 87 87 + ## Host Functions 88 88 + 89 89 + Plugins can import these host functions: 90 90 + 91 91 + | Import | Description | 92 92 + | ------------------- | ----------------------- | 93 93 + | `host_http_request` | Make HTTP requests | 94 94 + | `host_get_secret` | Read configured secrets | 95 95 + | `host_log` | Write to server logs | 96 96 + | `host_kv_get` | Read from KV storage | 97 97 + | `host_kv_set` | Write to KV storage | 98 98 + | `host_kv_delete` | Delete from KV storage | 99 99 + 100 100 + ## Next steps 101 101 + 102 102 + - [Official plugins repository](https://github.com/gamesgamesgamesgames/happyview-plugins) — ready-to-use plugins and the plugin SDK 103 103 + - [Plugins guide](plugins.md) — install and configure plugins 104 104 + - [API Keys](api-keys.md) — authenticate programmatic access to admin endpoints 105 105 + - [Permissions](permissions.md) — configure user access to plugin management

+4 -4

packages/docs/docs/guides/event-logs.md

reviewed

··· 1 1 # Event Logs 2 2 3 3 - HappyView maintains an internal event log that records system activity — lexicon changes, record operations, Lua script executions and errors, user actions, API key events, backfill jobs, and Jetstream connectivity. Events are stored in the database and queryable via the [admin API](../reference/admin-api.md#event-logs). 3 3 + HappyView maintains an internal event log that records system activity — lexicon changes, record operations, Lua script executions and errors, user actions, API key events, backfill jobs, and Jetstream connectivity. Events are stored in the database and queryable via the [admin API](../reference/admin/events.md). 4 4 5 5 ## Event types 6 6 ··· 14 14 | `lexicon.updated` | info | Lexicon NSID | `revision`, `has_script`, `source` | 15 15 | `lexicon.deleted` | info | Lexicon NSID | — | 16 16 17 17 - Logged when lexicons are uploaded, updated, or deleted via the [admin API](../reference/admin-api.md#lexicons). The `actor_did` is the user who performed the action. 17 17 + Logged when lexicons are uploaded, updated, or deleted via the [admin API](../reference/admin/lexicons.md). The `actor_did` is the user who performed the action. 18 18 19 19 ### Record events 20 20 ··· 118 118 curl "http://localhost:3000/admin/events?limit=20&cursor=2026-03-01T11:59:00Z" -H "$AUTH" 119 119 ``` 120 120 121 121 - See the [Admin API reference](../reference/admin-api.md#list-event-logs) for full parameter documentation. 121 121 + See the [Admin API reference](../reference/admin/events.md#list-event-logs) for full parameter documentation. 122 122 123 123 ## Retention 124 124 ··· 130 130 131 131 ## Next steps 132 132 133 133 - - [Admin API — Event Logs](../reference/admin-api.md#event-logs) — full query parameters and response format 133 133 + - [Admin API — Event Logs](../reference/admin/events.md) — full query parameters and response format 134 134 - [Permissions](permissions.md) — control which users can read event logs 135 135 - [Troubleshooting](../reference/troubleshooting.md) — using event logs to diagnose issues

+8 -8

packages/docs/docs/guides/index-hooks.md

reviewed

··· 2 2 3 3 Index hooks are Lua scripts that run automatically whenever a record in a collection is created, updated, or deleted on the network. They run **before** the record is indexed, giving you the ability to filter out unwanted records, transform record data before storage, or trigger side effects like syncing with external services. 4 4 5 5 - Unlike [query and procedure scripts](scripting.md) that run in response to XRPC requests, index hooks are triggered by the firehose. 5 5 + Unlike [query and procedure scripts](scripting.md) that run in response to XRPC requests, index hooks are triggered by incoming Jetstream events. 6 6 7 7 ## Attaching a hook 8 8 9 9 - Each record-type lexicon can have one index hook. You can add it through the [dashboard](../getting-started/dashboard.md) (click "Add Index Hook" on any record lexicon's detail page) or via the [admin API](../reference/admin-api.md#upload--upsert-a-lexicon) by including the `index_hook` field when uploading a lexicon. 9 9 + Each record-type lexicon can have one index hook. You can add it through the [dashboard](../getting-started/dashboard.md) (click "Add Index Hook" on any record lexicon's detail page) or via the [admin API](../reference/admin/lexicons.md#upload--upsert-a-lexicon) by including the `index_hook` field when uploading a lexicon. 10 10 11 11 ## Script structure 12 12 ··· 50 50 | `rkey` | string | The record key | 51 51 | `record` | table? | The full record as a Lua table (nil on delete) | 52 52 53 53 - Index hooks do **not** have access to `caller_did`, `input`, `params`, `method`, or the `Record` API. They run from the firehose, not from a user request. 53 53 + Index hooks do **not** have access to `caller_did`, `input`, `params`, `method`, or the `Record` API. They run from the Jetstream event stream, not from a user request. 54 54 55 55 ## Available APIs 56 56 57 57 Index hooks have access to: 58 58 59 59 - - **[Database API](scripting.md#database-api)** — `db.query`, `db.get`, `db.search`, `db.backlinks`, `db.count`, `db.raw` 60 60 - - **[HTTP API](scripting.md#http-api)** — `http.get`, `http.post`, `http.put`, `http.patch`, `http.delete`, `http.head` 61 61 - - **[JSON API](scripting.md#json-api)** — `json.encode`, `json.decode` 59 59 + - **[Database API](../reference/lua/database-api.md)** — `db.query`, `db.get`, `db.search`, `db.backlinks`, `db.count`, `db.raw` 60 60 + - **[HTTP API](../reference/lua/http-api.md)** — `http.get`, `http.post`, `http.put`, `http.patch`, `http.delete`, `http.head` 61 61 + - **[JSON API](../reference/lua/json-api.md)** — `json.encode`, `json.decode` 62 62 - **[Utility globals](scripting.md#utility-globals)** — `log()`, `now()`, `TID()`, `toarray()` 63 63 64 64 ## Error handling and retries ··· 73 73 74 74 ### Performance considerations 75 75 76 76 - Because hooks run synchronously before indexing, they block the firehose consumer while executing. With retry logic (1s + 2s + 4s backoff), a persistently failing hook could block for ~7 seconds per record. Keep hook scripts fast and ensure external services they depend on are reliable. 76 76 + Because hooks run synchronously before indexing, they block the Jetstream consumer while executing. With retry logic (1s + 2s + 4s backoff), a persistently failing hook could block for ~7 seconds per record. Keep hook scripts fast and ensure external services they depend on are reliable. 77 77 78 78 ### Dead letter table 79 79 ··· 218 218 219 219 - [Lua Scripting](scripting.md): Full reference for the sandbox, APIs, and debugging 220 220 - [Lexicons](lexicons.md): Understand how record, query, and procedure lexicons work together 221 221 - - [Admin API](../reference/admin-api.md#upload--upsert-a-lexicon): Upload lexicons with index hooks via the API 221 221 + - [Admin API — Lexicons](../reference/admin/lexicons.md#upload--upsert-a-lexicon): Upload lexicons with index hooks via the API

+3 -3

packages/docs/docs/guides/labelers.md

reviewed

··· 65 65 66 66 Self-labels (applied by the record author) use an outline badge style to distinguish them from external labels. Hover over a badge to see the source labeler's DID. 67 67 68 68 - Labels are also available in the records API response and in Lua scripts via the `get_labels` and `get_labels_batch` functions. See the [Scripting guide](scripting.md) for details. 68 68 + Labels are also available in the records API response and in Lua scripts via the [`atproto.get_labels` and `atproto.get_labels_batch`](../reference/lua/atproto-api.md#atprotoget_labels) functions. 69 69 70 70 ## Permissions 71 71 ··· 77 77 78 78 ## Next steps 79 79 80 80 - - [Admin API reference](../reference/admin-api.md#labelers) — full endpoint documentation 81 81 - - [Scripting](scripting.md) — access labels in Lua scripts with `get_labels` and `get_labels_batch` 80 80 + - [Admin API — Labelers](../reference/admin/labelers.md) — full endpoint documentation 81 81 + - [AT Protocol API](../reference/lua/atproto-api.md) — access labels in Lua scripts with `get_labels` and `get_labels_batch` 82 82 - [Permissions](permissions.md) — manage user access to labeler operations

+10 -10

packages/docs/docs/guides/lexicons.md

reviewed

··· 2 2 3 3 Lexicons are the core building block of HappyView. They're [AT Protocol schema definitions](https://atproto.com/specs/lexicon) that describe your data model, and HappyView uses them to decide which records to index from the network and what XRPC endpoints to serve. 4 4 5 5 - You don't write route handlers or database queries; you upload a lexicon and HappyView generates the infrastructure from it. There are two ways to add lexicons: uploading them via the [admin API](../reference/admin-api.md#lexicons) or [dashboard](../getting-started/dashboard.md), or fetching them directly from the AT Protocol network via [DNS authority resolution](#network-lexicons). 5 5 + You don't write route handlers or database queries; you upload a lexicon and HappyView generates the infrastructure from it. There are two ways to add lexicons: uploading them via the [admin API](../reference/admin/lexicons.md) or [dashboard](../getting-started/dashboard.md), or fetching them directly from the AT Protocol network via [DNS authority resolution](#network-lexicons). 6 6 7 7 ## Supported lexicon types 8 8 ··· 21 21 22 22 For example, a query lexicon `xyz.statusphere.listStatuses` would set `target_collection` to `xyz.statusphere.status` to read from that record collection. 23 23 24 24 - See the [admin API](../reference/admin-api.md#upload--upsert-a-lexicon) for how to set `target_collection` when uploading. 24 24 + See the [admin API](../reference/admin/lexicons.md#upload--upsert-a-lexicon) for how to set `target_collection` when uploading. 25 25 26 26 :::note 27 27 The `target_collection` is available in Lua scripts as the `collection` global, but it is not required if your endpoint uses a Lua script. ··· 35 35 36 36 When record-type lexicons change (uploaded or deleted), HappyView reconnects to Jetstream with an updated collection filter. HappyView always includes `com.atproto.lexicon.schema` in the filter to track network lexicon updates. 37 37 38 38 - Deleting a lexicon stops live indexing for that collection but does **not** remove previously indexed records from the database. To fully reset a collection's state, delete the lexicon and the associated records, re-add the lexicon, and run a [backfill](backfill.md). 38 38 + Deleting a lexicon stops live indexing for that collection but does **not** remove previously indexed records from the database. If you want to start fresh, you'll need to delete the records separately (e.g. via the admin API or directly in the database) before re-adding the lexicon and running a [backfill](backfill.md). 39 39 40 40 ## Network lexicons 41 41 ··· 67 67 68 68 ### Live updates via Jetstream 69 69 70 70 - The Jetstream subscription always includes `com.atproto.lexicon.schema` alongside the dynamic record collections. When a record event arrives: 70 70 + HappyView's Jetstream subscription always includes the `com.atproto.lexicon.schema` collection, so it receives real-time events whenever a lexicon schema record is created, updated, or deleted on the network. When an event arrives, HappyView checks whether the record's DID and rkey (the NSID) match any tracked network lexicon: 71 71 72 72 - - **create/update**: If the event's DID and rkey match a tracked network lexicon (`authority_did` and `nsid`), the lexicon is parsed, upserted into the `lexicons` table and in-memory registry, and collection filters are updated if it's a record type. 73 73 - - **delete**: The lexicon is removed from the `lexicons` table and registry. 72 72 + - **create/update**: The new schema is parsed and upserted into the `lexicons` table and the in-memory registry. If it's a record-type lexicon, Jetstream collection filters are updated to include the new collection. 73 73 + - **delete**: The lexicon is removed from the `lexicons` table and registry, and collection filters are updated accordingly. 74 74 75 75 ### Startup re-fetch 76 76 ··· 78 78 79 79 ## XRPC routing for unknown methods 80 80 81 81 - When a client calls `/xrpc/{method}` and HappyView has a local lexicon (with a handler or Lua script) for that NSID, the request is served locally. Otherwise, HappyView proxies the request to the method's **home authority** using the same DNS-based authority resolution described above: 81 81 + When a client calls `/xrpc/{method}` and HappyView has a local lexicon for that NSID, the request is handled by the lexicon's Lua script (or HappyView's default behavior if no script is attached). Otherwise, HappyView attempts to proxy the request to the method's **home authority** using the same DNS-based authority resolution described above: 82 82 83 83 1. Extract the authority from the NSID (all segments except the last). `com.example.foo.getBar` → authority `com.example.foo`. 84 84 2. Reverse it to form a domain: `foo.example.com`. ··· 90 90 91 91 - HappyView does **not** proxy to the reversed hostname directly. `foo.example.com` is only the DNS host for the TXT record — the actual XRPC request goes to whatever PDS endpoint the authority DID resolves to. 92 92 - Proxying applies equally to queries and procedures. For procedures, HappyView uses the caller's OAuth session to attach a DPoP-bound access token (see [Authentication](../getting-started/authentication.md#proxying-procedures-to-the-users-pds)). 93 93 - - If authority resolution fails — no TXT record, unresolvable DID, or the target PDS 404s the method — the client gets an error back. HappyView does not fall back to any other routing strategy. 94 94 - - "Network lexicons" (lexicons you've explicitly tracked via the dashboard) are only about **indexing** record collections and keeping the schema up to date. They don't add handler logic. An unknown query against a tracked network lexicon still proxies out — it doesn't run against your local record table unless you also upload a local query lexicon with a matching `target_collection`. 93 93 + - If authority resolution fails — no TXT record, unresolvable DID, or the target PDS doesn't support the method — the client gets an error back. HappyView does not fall back to any other routing strategy. 94 94 + - Tracking a network lexicon does **not** make HappyView handle requests for that NSID locally. Network lexicons are only about indexing record collections and keeping the schema up to date. If a client calls a query NSID that you've tracked as a network lexicon but haven't uploaded a local query lexicon for, HappyView still proxies the request out — it won't query your local record table. To serve a method locally, upload a local query or procedure lexicon with a matching `target_collection`. 95 95 96 96 - In short: if you want to serve an XRPC method on your instance, you need a local lexicon for it. Otherwise HappyView acts as a pass-through to the method's home PDS. 96 96 + In short: if you want to serve an XRPC method on your instance, you need a local lexicon for it. Otherwise HappyView attempts to proxy to the method's home authority. 97 97 98 98 ## Next steps 99 99

+31 -31

packages/docs/docs/guides/permissions.md

reviewed

··· 8 8 9 9 ### Lexicons 10 10 11 11 - | Permission | Description | 12 12 - |---|---| 11 11 + | Permission | Description | 12 12 + | ----------------- | ---------------------------------------------- | 13 13 | `lexicons:create` | Upload and upsert lexicons (local and network) | 14 14 - | `lexicons:read` | List and view lexicon details | 15 15 - | `lexicons:delete` | Delete lexicons | 14 14 + | `lexicons:read` | List and view lexicon details | 15 15 + | `lexicons:delete` | Delete lexicons | 16 16 17 17 ### Records 18 18 19 19 - | Permission | Description | 20 20 - |---|---| 21 21 - | `records:read` | List and view indexed records | 22 22 - | `records:delete` | Delete individual records | 19 19 + | Permission | Description | 20 20 + | --------------------------- | --------------------------------------- | 21 21 + | `records:read` | List and view indexed records | 22 22 + | `records:delete` | Delete individual records | 23 23 | `records:delete-collection` | Bulk-delete all records in a collection | 24 24 25 25 ### Script Variables 26 26 27 27 - | Permission | Description | 28 28 - |---|---| 29 29 - | `script-variables:create` | Create and update script variables | 30 30 - | `script-variables:read` | List script variables (values are masked) | 31 31 - | `script-variables:delete` | Delete script variables | 27 27 + | Permission | Description | 28 28 + | ------------------------- | ----------------------------------------- | 29 29 + | `script-variables:create` | Create and update script variables | 30 30 + | `script-variables:read` | List script variables (values are masked) | 31 31 + | `script-variables:delete` | Delete script variables | 32 32 33 33 ### Users 34 34 35 35 - | Permission | Description | 36 36 - |---|---| 37 37 - | `users:create` | Add new users | 38 38 - | `users:read` | List and view user details | 39 39 - | `users:update` | Modify user permissions | 40 40 - | `users:delete` | Remove users | 35 35 + | Permission | Description | 36 36 + | -------------- | -------------------------- | 37 37 + | `users:create` | Add new users | 38 38 + | `users:read` | List and view user details | 39 39 + | `users:update` | Modify user permissions | 40 40 + | `users:delete` | Remove users | 41 41 42 42 ### API Keys 43 43 44 44 - | Permission | Description | 45 45 - |---|---| 44 44 + | Permission | Description | 45 45 + | ----------------- | ------------------- | 46 46 | `api-keys:create` | Create new API keys | 47 47 - | `api-keys:read` | List API keys | 48 48 - | `api-keys:delete` | Revoke API keys | 47 47 + | `api-keys:read` | List API keys | 48 48 + | `api-keys:delete` | Revoke API keys | 49 49 50 50 ### Operations 51 51 52 52 - | Permission | Description | 53 53 - |---|---| 54 54 - | `backfill:create` | Start backfill jobs | 55 55 - | `backfill:read` | View backfill job status | 56 56 - | `stats:read` | View record statistics | 57 57 - | `events:read` | Query the event log | 52 52 + | Permission | Description | 53 53 + | ----------------- | ------------------------ | 54 54 + | `backfill:create` | Start backfill jobs | 55 55 + | `backfill:read` | View backfill job status | 56 56 + | `stats:read` | View record statistics | 57 57 + | `events:read` | Query the event log | 58 58 59 59 ## Permission templates 60 60 ··· 91 91 - Cannot be deleted 92 92 - Cannot have their permissions modified by other users 93 93 94 94 - There is always exactly one super user. Super status can be transferred to another user via the transfer endpoint. 94 94 + There is always exactly one super user. Super status can be transferred to another user via the dashboard or transfer endpoint in the Admin API. 95 95 96 96 ## Escalation guards 97 97 ··· 132 132 - `PATCH /admin/users/{id}/permissions` — grant or revoke individual permissions 133 133 - `POST /admin/users/transfer-super` — transfer super user status (super user only) 134 134 135 135 - See the [Admin API reference](../reference/admin-api.md#user-management) for full details. 135 135 + See the [Admin API — Users](../reference/admin/users.md) for full details. 136 136 137 137 ## Next steps 138 138

+4 -99

packages/docs/docs/guides/plugins.md

reviewed

··· 1 1 # Plugins 2 2 3 3 - HappyView uses WASM plugins to integrate with external platforms. Auth plugins enable users to link their accounts from platforms like Steam, Xbox, itch.io, and others, then sync data (like game libraries) to their AT Protocol identity. 3 3 + HappyView uses WASM plugins to extend its functionality. Plugins can integrate with external platforms, sync data to users' AT Protocol identities, and more. Auth plugins — the first supported plugin type — enable users to link accounts from platforms like Steam, Xbox, itch.io, and others, then sync data like game libraries. 4 4 5 5 Official plugins for Steam, Xbox, itch.io, and other platforms are available in the [happyview-plugins](https://github.com/gamesgamesgamesgames/happyview-plugins) repository. 6 6 ··· 46 46 **Requires:** `TOKEN_ENCRYPTION_KEY` environment variable (base64-encoded 32-byte key). 47 47 48 48 Generate one with: 49 49 + 49 50 ```bash 50 51 openssl rand -base64 32 51 52 ``` ··· 60 61 PLUGIN_XBOX_CLIENT_SECRET=your-client-secret 61 62 ``` 62 63 63 63 - Dashboard-configured secrets take precedence over environment variables. 64 64 - 65 65 - ## Plugin Manifest 66 66 - 67 67 - Each plugin has a `manifest.json` that describes its metadata: 68 68 - 69 69 - ```json 70 70 - { 71 71 - "id": "steam", 72 72 - "name": "Steam", 73 73 - "version": "1.0.0", 74 74 - "api_version": "1", 75 75 - "description": "Import your Steam game library and playtime data.", 76 76 - "icon_url": "https://example.com/steam-icon.png", 77 77 - "auth_type": "openid", 78 78 - "wasm_file": "steam.wasm", 79 79 - "required_secrets": [ 80 80 - { 81 81 - "key": "PLUGIN_STEAM_API_KEY", 82 82 - "name": "Steam Web API Key", 83 83 - "description": "Get your API key at steamcommunity.com/dev/apikey" 84 84 - } 85 85 - ] 86 86 - } 87 87 - ``` 88 88 - 89 89 - | Field | Description | 90 90 - |-------|-------------| 91 91 - | `id` | Unique plugin identifier | 92 92 - | `name` | Display name | 93 93 - | `version` | Semantic version | 94 94 - | `api_version` | Plugin API version (currently "1") | 95 95 - | `description` | Brief description shown during install | 96 96 - | `icon_url` | Optional icon URL | 97 97 - | `auth_type` | Authentication type: `oauth2`, `openid`, or `api_key` | 98 98 - | `wasm_file` | WASM binary filename (default: `plugin.wasm`) | 99 99 - | `required_secrets` | Array of secrets the plugin needs | 100 100 - 101 101 - ## API Endpoints 102 102 - 103 103 - ### Public Endpoints 104 104 - 105 105 - | Endpoint | Description | 106 106 - |----------|-------------| 107 107 - | `GET /external-auth/providers` | List available auth providers | 108 108 - | `GET /external-auth/accounts` | List user's linked accounts | 109 109 - | `GET /external-auth/{plugin}/authorize` | Start OAuth flow | 110 110 - | `GET /external-auth/{plugin}/callback` | OAuth callback handler | 111 111 - | `POST /external-auth/{plugin}/sync` | Sync data from linked account | 112 112 - | `POST /external-auth/{plugin}/unlink` | Unlink account | 113 113 - | `POST /external-auth/{plugin}/connect` | Connect with API key (for `api_key` auth type) | 114 114 - 115 115 - ### Admin Endpoints 116 116 - 117 117 - | Endpoint | Description | 118 118 - |----------|-------------| 119 119 - | `GET /admin/plugins` | List installed plugins | 120 120 - | `POST /admin/plugins` | Install a plugin | 121 121 - | `POST /admin/plugins/preview` | Preview plugin before installing | 122 122 - | `GET /admin/plugins/official` | Browse the official plugin registry catalog | 123 123 - | `DELETE /admin/plugins/{id}` | Remove a plugin | 124 124 - | `POST /admin/plugins/{id}/reload` | Reload plugin from source | 125 125 - | `POST /admin/plugins/{id}/check-update` | Check whether a newer version is available | 126 126 - | `GET /admin/plugins/{id}/secrets` | Get configured secrets (masked) | 127 127 - | `PUT /admin/plugins/{id}/secrets` | Update plugin secrets | 128 128 - 129 129 - The dashboard's **Settings > Plugins** page calls `GET /admin/plugins/official` to populate the install browser, and `POST /admin/plugins/{id}/check-update` to display update badges on installed plugins. 64 64 + These are only necessary if you can't configure variables via the dashboard. Dashboard-configured secrets take precedence over environment variables. 130 65 131 66 ## Security 132 67 ··· 136 71 - **Scoped storage**: Plugin KV storage is isolated per-plugin and per-user 137 72 - **No filesystem access**: Plugins cannot access the host filesystem 138 73 139 139 - ## Developing Plugins 140 140 - 141 141 - See the [happyview-plugins](https://github.com/gamesgamesgamesgames/happyview-plugins) repository for examples and the plugin SDK. 142 142 - 143 143 - ### Plugin Exports 144 144 - 145 145 - Plugins must export these functions: 146 146 - 147 147 - | Export | Signature | Description | 148 148 - |--------|-----------|-------------| 149 149 - | `alloc` | `(size: u32) -> u32` | Allocate memory | 150 150 - | `dealloc` | `(ptr: u32, size: u32)` | Deallocate memory | 151 151 - | `get_authorize_url` | `(ptr: u32, len: u32) -> i64` | Generate OAuth authorize URL | 152 152 - | `handle_callback` | `(ptr: u32, len: u32) -> i64` | Handle OAuth callback | 153 153 - | `refresh_tokens` | `(ptr: u32, len: u32) -> i64` | Refresh expired tokens | 154 154 - | `get_profile` | `(ptr: u32, len: u32) -> i64` | Get external profile info | 155 155 - | `sync_account` | `(ptr: u32, len: u32) -> i64` | Sync data and return records | 156 156 - 157 157 - ### Host Functions 158 158 - 159 159 - Plugins can import these host functions: 160 160 - 161 161 - | Import | Description | 162 162 - |--------|-------------| 163 163 - | `host_http_request` | Make HTTP requests | 164 164 - | `host_get_secret` | Read configured secrets | 165 165 - | `host_log` | Write to server logs | 166 166 - | `host_kv_get` | Read from KV storage | 167 167 - | `host_kv_set` | Write to KV storage | 168 168 - | `host_kv_delete` | Delete from KV storage | 169 169 - 170 74 ## Next steps 171 75 76 76 + - [Developing Plugins](developing-plugins.md) — create your own plugins with the WASM plugin API 172 77 - [Official plugins repository](https://github.com/gamesgamesgamesgames/happyview-plugins) — ready-to-use plugins for Steam, Xbox, itch.io, and more 173 78 - [API Keys](api-keys.md) — authenticate programmatic access to admin endpoints 174 79 - [Permissions](permissions.md) — configure user access to plugin management

+9 -10

packages/docs/docs/guides/postgres-to-sqlite-migration.md

reviewed

··· 46 46 47 47 ### What the codemod converts automatically 48 48 49 49 - - `$1`, `$2`, etc. parameter placeholders to `?` positional parameters 50 50 - - `jsonb` operators (`->`, `->>`, `@>`, `?`) to SQLite `json_extract()` calls 49 49 + - `$1`, `$2`, etc. parameter placeholders to `?` 50 50 + - JSON operators (`->`, `->>`) and `::jsonb` casts to `json_extract()` calls 51 51 - `ILIKE` to `LIKE` (SQLite `LIKE` is case-insensitive for ASCII by default) 52 52 - `NOW()` to `datetime('now')` 53 53 - - `::text`, `::integer`, etc. type casts to SQLite equivalents (`CAST(... AS ...)`) 54 54 - - `COALESCE` and other standard SQL functions (no change needed) 53 53 + - `NOW() + INTERVAL '...'` / `NOW() - INTERVAL '...'` to `datetime('now', '...')` 55 54 - `TRUE`/`FALSE` literals to `1`/`0` 56 56 - - `RETURNING *` clauses (removed, as SQLite has limited RETURNING support) 57 55 58 56 ### What it flags for manual review 59 57 60 58 The tool prints warnings for patterns it cannot convert automatically: 61 59 62 62 - - Complex Postgres-specific functions (`array_agg`, `string_agg`, `generate_series`, etc.) 63 63 - - Window functions with Postgres-specific syntax 64 64 - - `ON CONFLICT` clauses with complex conditions 65 65 - - CTEs (`WITH` queries) that use Postgres-specific features 66 66 - - Any SQL that the parser cannot confidently transform 60 60 + - JSONB `?` (contains-key) operator — consider using `json_each()` with an `EXISTS` subquery 61 61 + - `make_interval()` — Postgres-specific, needs manual conversion 62 62 + - `SIMILAR TO` — use `LIKE` or `GLOB` instead 63 63 + - `ANY()` / `ALL()` array operators — no direct SQLite equivalent 64 64 + - Type casts other than `::jsonb` (e.g., `::text`, `::integer`) — may need manual conversion to `CAST(... AS ...)` 67 65 68 66 Review the flagged lines and update them manually. 69 67 ··· 87 85 88 86 ## Next steps 89 87 88 88 + - [SQLite → Postgres migration](sqlite-to-postgres-migration.md) — migrate in the opposite direction 90 89 - [Database setup](database-setup.md) — choose between SQLite and Postgres for new instances 91 90 - [Backfill](backfill.md) — re-index records from the network after switching backends 92 91 - [Lua scripting](scripting.md) — write SQL that works against either backend

+21 -417

packages/docs/docs/guides/scripting.md

reviewed

··· 35 35 36 36 An instruction limit of 1,000,000 prevents infinite loops. Exceeding it terminates the script with an error. 37 37 38 38 + See the [Standard Libraries](../reference/lua/standard-libraries.md) reference for the full list of available Lua modules and builtins. 39 39 + 38 40 ## Context globals 39 41 40 42 These globals are set automatically before `handle()` is called. ··· 85 87 86 88 The `Record` API is only available in **procedure** scripts. It handles creating, updating, loading, and deleting AT Protocol records. Writes are proxied to the caller's PDS and indexed locally. 87 89 88 88 - ### Constructor 89 89 - 90 90 - ```lua 91 91 - local r = Record("xyz.statusphere.status", { status = "\ud83d\ude0a", createdAt = now() }) 92 92 - ``` 93 93 - 94 94 - Creates a new record instance for the given collection. The optional second argument sets initial field values. The record's `_key_type` is automatically set from the lexicon's `key` definition. Default values from the schema are populated for any missing fields. 90 90 + See the full [Record API reference](../reference/lua/record-api.md) for constructor, static methods, instance methods, fields, schema validation, and save behavior. 95 91 96 96 - ### Static methods 92 92 + Quick example: 97 93 98 94 ```lua 99 99 - -- Save multiple records in parallel 100 100 - Record.save_all({ record1, record2, record3 }) 101 101 - 102 102 - -- Load a record from the local database by AT URI 103 103 - local r = Record.load("at://did:plc:abc/xyz.statusphere.status/abc123") 104 104 - -- Returns nil if not found 105 105 - 106 106 - -- Load multiple records in parallel 107 107 - local records = Record.load_all({ uri1, uri2 }) 108 108 - -- Returns nil entries for URIs not found 95 95 + function handle() 96 96 + local r = Record(collection, input) 97 97 + r:save() 98 98 + return { uri = r._uri, cid = r._cid } 99 99 + end 109 100 ``` 110 101 111 111 - ### Instance methods 112 112 - 113 113 - ```lua 114 114 - -- Save (creates or updates depending on whether _uri is set) 115 115 - r:save() 116 116 - 117 117 - -- Delete from PDS and local database 118 118 - r:delete() 119 119 - 120 120 - -- Set the record key type (tid, any, nsid, or literal:*) 121 121 - r:set_key_type("tid") 122 122 - 123 123 - -- Set a specific record key 124 124 - r:set_rkey("my-key") 125 125 - 126 126 - -- Auto-generate a record key based on _key_type 127 127 - local key = r:generate_rkey() 128 128 - ``` 129 129 - 130 130 - **Key type behavior for `generate_rkey()`:** 131 131 - 132 132 - | Key type | Generated rkey | 133 133 - | --------------- | --------------------------------- | 134 134 - | `tid` | Sortable timestamp-based ID | 135 135 - | `any` | Same as `tid` | 136 136 - | `literal:value` | The literal value after the colon | 137 137 - | `nsid` | Error — use `set_rkey()` instead | 138 138 - 139 139 - ### Instance fields 140 140 - 141 141 - These fields are set automatically and are read-only (writes raise an error): 142 142 - 143 143 - | Field | Type | Description | 144 144 - | ------------- | ------- | ----------------------------------------------------------- | 145 145 - | `_uri` | string? | AT URI — set after `save()`, cleared after `delete()` | 146 146 - | `_cid` | string? | Content hash — set after `save()`, cleared after `delete()` | 147 147 - | `_key_type` | string? | Record key type from the lexicon definition | 148 148 - | `_rkey` | string? | Record key — set via `set_rkey()` or `generate_rkey()` | 149 149 - | `_collection` | string | Collection NSID (always set) | 150 150 - | `_schema` | table? | Schema definition from the lexicon (used for validation) | 151 151 - 152 152 - ### Schema validation 153 153 - 154 154 - When a record has a schema (loaded from the lexicon): 155 155 - 156 156 - - **On save:** required fields are checked, and missing required fields raise an error 157 157 - - **On construction:** default values from schema properties are auto-populated 158 158 - - **On save:** only fields defined in the schema's `properties` are sent to the PDS 159 159 - 160 160 - ### Save behavior 161 161 - 162 162 - `r:save()` auto-detects create vs update: 163 163 - 164 164 - - If `_uri` is nil → calls `createRecord` on the PDS 165 165 - - If `_uri` is set → calls `putRecord` on the PDS 166 166 - 167 167 - After a successful save, `_uri` and `_cid` are updated on the record instance. 168 168 - 169 102 ## Database API 170 103 171 104 The `db` table provides access to the database. Available in both queries and procedures. 172 105 173 173 - ### db.query 106 106 + See the full [Database API reference](../reference/lua/database-api.md) for `db.query`, `db.get`, `db.search`, `db.backlinks`, `db.count`, and `db.raw`. 174 107 175 175 - ```lua 176 176 - local result = db.query({ 177 177 - collection = "xyz.statusphere.status", -- required 178 178 - did = "did:plc:abc", -- optional: filter by DID 179 179 - limit = 20, -- optional: max 100, default 20 180 180 - offset = 0, -- optional: for pagination 181 181 - sort = "name", -- optional: field to sort by, default "indexed_at" 182 182 - sortDirection = "asc", -- optional: "asc" or "desc", default "desc" 183 183 - }) 184 184 - 185 185 - -- result.records — array of record tables (each includes a "uri" field) 186 186 - -- result.cursor — present when more records exist 187 187 - ``` 188 188 - 189 189 - The `sort` field can be a top-level column (`indexed_at`, `did`, `uri`) or any field inside the record's `value` object (e.g. `name`, `createdAt`). Field names must contain only alphanumeric characters and underscores. 190 190 - 191 191 - ### db.get 108 108 + Quick example: 192 109 193 110 ```lua 194 194 - local record = db.get("at://did:plc:abc/xyz.statusphere.status/abc123") 195 195 - -- Returns the record table or nil 196 196 - -- The returned table includes a "uri" field 197 197 - ``` 198 198 - 199 199 - ### db.search 200 200 - 201 201 - ```lua 202 202 - local result = db.search({ 203 203 - collection = "xyz.statusphere.status", -- required 204 204 - field = "displayName", -- required: record field to search 205 205 - query = "alice", -- required: search term 206 206 - limit = 10, -- optional: max 100, default 10 207 207 - }) 208 208 - 209 209 - -- result.records — array of matching records, ranked by relevance: 210 210 - -- exact match > prefix match > contains match, then alphabetical 211 211 - ``` 212 212 - 213 213 - ### db.backlinks 214 214 - 215 215 - Find records that reference a given AT URI anywhere in their data. Useful for finding likes on a post, replies to a thread, or any record that links to another. 216 216 - 217 217 - ```lua 218 218 - local result = db.backlinks({ 219 219 - collection = "xyz.statusphere.status", -- required 220 220 - uri = "at://did:plc:abc/xyz.statusphere.status/foo", -- required: the URI to find references to 221 221 - did = "did:plc:abc", -- optional: filter by DID 222 222 - limit = 20, -- optional: max 100, default 20 223 223 - offset = 0, -- optional: for pagination 224 224 - }) 225 225 - 226 226 - -- result.records — array of records whose data contains the given URI 227 227 - -- result.cursor — present when more records exist 228 228 - ``` 229 229 - 230 230 - The search checks the full record data, so it works regardless of which field holds the reference (`subject`, `parent`, `reply.root`, etc.). 231 231 - 232 232 - ### db.count 233 233 - 234 234 - ```lua 235 235 - local n = db.count("xyz.statusphere.status") 236 236 - local n = db.count("xyz.statusphere.status", "did:plc:abc") -- filter by DID 237 237 - ``` 238 238 - 239 239 - ### db.raw 240 240 - 241 241 - Run a raw SQL query against the database. Supports `SELECT`, `INSERT`, `UPDATE`, `DELETE`, and `CREATE TABLE` statements. 242 242 - 243 243 - ```lua 244 244 - -- Read query 245 245 - local rows = db.raw( 246 246 - "SELECT uri, did, record FROM records WHERE collection = $1 AND did = $2 LIMIT $3", 247 247 - { "xyz.statusphere.status", "did:plc:abc", 10 } 248 248 - ) 249 249 - 250 250 - for _, row in ipairs(rows) do 251 251 - -- row.uri, row.did, row.record (JSONB is returned as a Lua table) 111 111 + function handle() 112 112 + local result = db.query({ collection = collection, limit = 20 }) 113 113 + return { records = result.records, cursor = result.cursor } 252 114 end 253 253 - 254 254 - -- Write query (returns affected rows, if any) 255 255 - db.raw("CREATE TABLE IF NOT EXISTS my_table (id TEXT PRIMARY KEY, value TEXT NOT NULL)") 256 256 - db.raw("INSERT INTO my_table (id, value) VALUES ($1, $2) ON CONFLICT (id) DO UPDATE SET value = $2", 257 257 - { "key1", "hello" }) 258 115 ``` 259 116 260 260 - Parameters are passed as an array and bound to `$1`, `$2`, etc. Supported parameter types: strings, integers, numbers, booleans, and nil. 261 261 - 262 262 - Column types are mapped automatically: 263 263 - 264 264 - | Postgres type | Lua type | 265 265 - | ---------------------- | -------- | 266 266 - | `TEXT`, `VARCHAR` | string | 267 267 - | `INT4`, `INT8` | integer | 268 268 - | `FLOAT4`, `FLOAT8` | number | 269 269 - | `BOOL` | boolean | 270 270 - | `JSON`, `JSONB` | table | 271 271 - | `TIMESTAMPTZ` | string (ISO 8601) | 272 272 - | Other | string (fallback) | 273 273 - 274 117 ## HTTP API 275 118 276 119 The `http` table provides async HTTP client functions. Available in both queries and procedures. 277 120 278 278 - ### Methods 279 279 - 280 280 - All methods take a URL and an optional options table, and return a [response table](#response). 281 281 - 282 282 - ```lua 283 283 - http.get(url, opts?) 284 284 - http.post(url, opts?) 285 285 - http.put(url, opts?) 286 286 - http.patch(url, opts?) 287 287 - http.delete(url, opts?) 288 288 - http.head(url, opts?) 289 289 - ``` 290 290 - 291 291 - ### Options 292 292 - 293 293 - The optional second argument is a table with: 121 121 + See the full [HTTP API reference](../reference/lua/http-api.md) for all methods, options, and response format. 294 122 295 295 - | Field | Type | Description | 296 296 - | --------- | ------ | ---------------------------------------------- | 297 297 - | `headers` | table | Request headers as key-value string pairs | 298 298 - | `body` | string | Request body (ignored for GET and HEAD) | 299 299 - 300 300 - ### Response 301 301 - 302 302 - Every method returns a table with: 303 303 - 304 304 - | Field | Type | Description | 305 305 - | --------- | ------- | ---------------------------------------------------- | 306 306 - | `status` | integer | HTTP status code | 307 307 - | `body` | string | Response body text (empty string for HEAD) | 308 308 - | `headers` | table | Response headers as key-value pairs (lowercase keys) | 309 309 - 310 310 - ### Examples 123 123 + Quick example: 311 124 312 125 ```lua 313 313 - -- Simple GET 314 126 local resp = http.get("https://api.example.com/data") 315 315 - -- resp.status = 200, resp.body = "...", resp.headers["content-type"] = "application/json" 316 316 - 317 317 - -- GET with custom headers 318 318 - local resp = http.get("https://api.example.com/data", { 319 319 - headers = { ["authorization"] = "Bearer token123" } 320 320 - }) 321 321 - 322 322 - -- POST with JSON body 323 323 - local resp = http.post("https://api.example.com/hook", { 324 324 - body = '{"key": "value"}', 325 325 - headers = { ["content-type"] = "application/json" } 326 326 - }) 327 327 - 328 328 - -- PUT, PATCH, DELETE, HEAD follow the same pattern 329 329 - local resp = http.put(url, { body = data, headers = { ... } }) 330 330 - local resp = http.patch(url, { body = data, headers = { ... } }) 331 331 - local resp = http.delete(url, { headers = { ... } }) 332 332 - local resp = http.head(url) 127 127 + local data = json.decode(resp.body) 333 128 ``` 334 129 335 130 ## AT Protocol API 336 131 337 337 - The `atproto` table provides AT Protocol utility functions. Available in queries, procedures, and [index hooks](index-hooks.md). 338 338 - 339 339 - ### atproto.resolve_service_endpoint 340 340 - 341 341 - ```lua 342 342 - local endpoint = atproto.resolve_service_endpoint(did) 343 343 - ``` 344 344 - 345 345 - Resolves a DID to its AT Protocol service endpoint URL by fetching the DID document. Supports both `did:plc:*` (via the PLC directory) and `did:web:*` (via `.well-known/did.json`). 346 346 - 347 347 - | Parameter | Type | Description | 348 348 - | --------- | ------ | ------------------------ | 349 349 - | `did` | string | The DID to resolve | 350 350 - 351 351 - **Returns:** The service endpoint URL as a string, or `nil` if resolution fails (DID not found, no PDS service in document, network error). 352 352 - 353 353 - ### Examples 354 354 - 355 355 - ```lua 356 356 - -- Resolve a did:plc DID 357 357 - local endpoint = atproto.resolve_service_endpoint("did:plc:abc123") 358 358 - -- endpoint = "https://pds.example.com" 359 359 - 360 360 - -- Resolve a did:web DID 361 361 - local endpoint = atproto.resolve_service_endpoint("did:web:example.com") 362 362 - -- endpoint = "https://example.com" 363 363 - 364 364 - -- Handle resolution failure 365 365 - local endpoint = atproto.resolve_service_endpoint("did:plc:unknown") 366 366 - if not endpoint then 367 367 - return { error = "Could not resolve DID" } 368 368 - end 369 369 - 370 370 - -- Use with HTTP API to call a remote XRPC endpoint 371 371 - local endpoint = atproto.resolve_service_endpoint(did) 372 372 - if endpoint then 373 373 - local resp = http.get(endpoint .. "/xrpc/com.example.method") 374 374 - local data = json.decode(resp.body) 375 375 - end 376 376 - ``` 377 377 - 378 378 - ### atproto.get_labels 379 379 - 380 380 - ```lua 381 381 - local labels = atproto.get_labels(uri) 382 382 - ``` 383 383 - 384 384 - Returns an array of labels for a single AT URI. Merges external labels (from subscribed labelers) with self-labels (from the record's `labels.values[]` field). 385 385 - 386 386 - | Parameter | Type | Description | 387 387 - | --------- | ------ | ------------------------------ | 388 388 - | `uri` | string | AT URI of the record to query | 132 132 + The `atproto` table provides AT Protocol utility functions like DID resolution and label queries. 389 133 390 390 - Each label in the array is a table with: 391 391 - 392 392 - | Field | Type | Description | 393 393 - | ----- | ------ | ---------------------------------------- | 394 394 - | `src` | string | DID of the labeler (or record author) | 395 395 - | `uri` | string | AT URI this label applies to | 396 396 - | `val` | string | Label value (e.g. "nsfw", "!hide") | 397 397 - | `cts` | string | Timestamp when the label was created | 398 398 - 399 399 - Expired labels are automatically filtered out. Returns an empty array if no labels exist. 400 400 - 401 401 - ### atproto.get_labels_batch 402 402 - 403 403 - ```lua 404 404 - local labels_by_uri = atproto.get_labels_batch(uris) 405 405 - ``` 406 406 - 407 407 - Batch version of `get_labels`. Takes an array of AT URIs and returns a table keyed by URI, where each value is an array of labels. 408 408 - 409 409 - | Parameter | Type | Description | 410 410 - | --------- | ----- | ------------------------ | 411 411 - | `uris` | table | Array of AT URI strings | 412 412 - 413 413 - **Returns:** A table keyed by URI. Each value is an array of label tables (same shape as `get_labels`). URIs with no labels have an empty array. 414 414 - 415 415 - ### Label Examples 416 416 - 417 417 - ```lua 418 418 - -- Get labels for a single game 419 419 - local labels = atproto.get_labels("at://did:plc:abc/games.gamesgamesgamesgames.game/rkey1") 420 420 - for _, label in ipairs(labels) do 421 421 - if label.val == "!hide" then 422 422 - -- skip this game in feed results 423 423 - end 424 424 - end 425 425 - 426 426 - -- Batch fetch labels for multiple games (efficient for feed hydration) 427 427 - local uris = {} 428 428 - for _, item in ipairs(skeleton) do 429 429 - uris[#uris + 1] = item.game 430 430 - end 431 431 - 432 432 - local labels_by_uri = atproto.get_labels_batch(uris) 433 433 - for _, uri in ipairs(uris) do 434 434 - local labels = labels_by_uri[uri] 435 435 - for _, label in ipairs(labels) do 436 436 - if label.val == "!hide" then 437 437 - -- filter out this game 438 438 - end 439 439 - end 440 440 - end 441 441 - ``` 134 134 + See the full [AT Protocol API reference](../reference/lua/atproto-api.md) for `atproto.resolve_service_endpoint`, `atproto.get_labels`, and `atproto.get_labels_batch`. 442 135 443 136 ## JSON API 444 137 445 445 - The `json` global provides JSON serialization and deserialization. Available in queries, procedures, and [index hooks](index-hooks.md). 446 446 - 447 447 - ### json.encode 448 448 - 449 449 - ```lua 450 450 - local str = json.encode({ key = "value", items = { 1, 2, 3 } }) 451 451 - -- '{"key":"value","items":[1,2,3]}' 452 452 - ``` 138 138 + The `json` global provides JSON serialization and deserialization. 453 139 454 454 - Converts a Lua table to a JSON string. 455 455 - 456 456 - ### json.decode 457 457 - 458 458 - ```lua 459 459 - local tbl = json.decode('{"key": "value"}') 460 460 - -- tbl.key == "value" 461 461 - ``` 462 462 - 463 463 - Parses a JSON string into a Lua table. Returns an error if the input is not valid JSON. 464 464 - 465 465 - ## Standard libraries 466 466 - 467 467 - The following Lua 5.4 standard library modules are available: 468 468 - 469 469 - <details> 470 470 - <summary> 471 471 - `string` 472 472 - </summary> 473 473 - - [`byte`](https://lua.org/manual/5.4/manual.html#pdf-string.byte) 474 474 - - [`char`](https://lua.org/manual/5.4/manual.html#pdf-string.char) 475 475 - - [`find`](https://lua.org/manual/5.4/manual.html#pdf-string.find) 476 476 - - [`format`](https://lua.org/manual/5.4/manual.html#pdf-string.format) 477 477 - - [`gmatch`](https://lua.org/manual/5.4/manual.html#pdf-string.gmatch) 478 478 - - [`gsub`](https://lua.org/manual/5.4/manual.html#pdf-string.gsub) 479 479 - - [`len`](https://lua.org/manual/5.4/manual.html#pdf-string.len) 480 480 - - [`lower`](https://lua.org/manual/5.4/manual.html#pdf-string.lower) 481 481 - - [`match`](https://lua.org/manual/5.4/manual.html#pdf-string.match) 482 482 - - [`rep`](https://lua.org/manual/5.4/manual.html#pdf-string.rep) 483 483 - - [`reverse`](https://lua.org/manual/5.4/manual.html#pdf-string.reverse) 484 484 - - [`sub`](https://lua.org/manual/5.4/manual.html#pdf-string.sub) 485 485 - - [`upper`](https://lua.org/manual/5.4/manual.html#pdf-string.upper) 486 486 - </details> 487 487 - 488 488 - <details> 489 489 - <summary> 490 490 - `table` 491 491 - </summary> 492 492 - - [`concat`](https://lua.org/manual/5.4/manual.html#pdf-table.concat) 493 493 - - [`insert`](https://lua.org/manual/5.4/manual.html#pdf-table.insert) 494 494 - - [`remove`](https://lua.org/manual/5.4/manual.html#pdf-table.remove) 495 495 - - [`sort`](https://lua.org/manual/5.4/manual.html#pdf-table.sort) 496 496 - - [`unpack`](https://lua.org/manual/5.4/manual.html#pdf-table.unpack) 497 497 - </details> 498 498 - 499 499 - <details> 500 500 - <summary> 501 501 - `math` 502 502 - </summary> 503 503 - - [`abs`](https://lua.org/manual/5.4/manual.html#pdf-math.abs) 504 504 - - [`ceil`](https://lua.org/manual/5.4/manual.html#pdf-math.ceil) 505 505 - - [`floor`](https://lua.org/manual/5.4/manual.html#pdf-math.floor) 506 506 - - [`max`](https://lua.org/manual/5.4/manual.html#pdf-math.max) 507 507 - - [`min`](https://lua.org/manual/5.4/manual.html#pdf-math.min) 508 508 - - [`random`](https://lua.org/manual/5.4/manual.html#pdf-math.random) 509 509 - - [`sqrt`](https://lua.org/manual/5.4/manual.html#pdf-math.sqrt) 510 510 - - [`huge`](https://lua.org/manual/5.4/manual.html#pdf-math.huge) 511 511 - - [`pi`](https://lua.org/manual/5.4/manual.html#pdf-math.pi) 512 512 - </details> 513 513 - 514 514 - <details> 515 515 - <summary> 516 516 - Standard builtins 517 517 - </summary> 518 518 - - [`print`](https://lua.org/manual/5.4/manual.html#pdf-print) 519 519 - - [`tostring`](https://lua.org/manual/5.4/manual.html#pdf-tostring) 520 520 - - [`tonumber`](https://lua.org/manual/5.4/manual.html#pdf-tonumber) 521 521 - - [`type`](https://lua.org/manual/5.4/manual.html#pdf-type) 522 522 - - [`pairs`](https://lua.org/manual/5.4/manual.html#pdf-pairs) 523 523 - - [`ipairs`](https://lua.org/manual/5.4/manual.html#pdf-ipairs) 524 524 - - [`next`](https://lua.org/manual/5.4/manual.html#pdf-next) 525 525 - - [`select`](https://lua.org/manual/5.4/manual.html#pdf-select) 526 526 - - [`unpack`](https://lua.org/manual/5.4/manual.html#pdf-table.unpack) 527 527 - - [`error`](https://lua.org/manual/5.4/manual.html#pdf-error) 528 528 - - [`pcall`](https://lua.org/manual/5.4/manual.html#pdf-pcall) 529 529 - - [`xpcall`](https://lua.org/manual/5.4/manual.html#pdf-xpcall) 530 530 - - [`assert`](https://lua.org/manual/5.4/manual.html#pdf-assert) 531 531 - - [`setmetatable`](https://lua.org/manual/5.4/manual.html#pdf-setmetatable) 532 532 - - [`getmetatable`](https://lua.org/manual/5.4/manual.html#pdf-getmetatable) 533 533 - - [`rawget`](https://lua.org/manual/5.4/manual.html#pdf-rawget) 534 534 - - [`rawset`](https://lua.org/manual/5.4/manual.html#pdf-rawset) 535 535 - - [`rawequal`](https://lua.org/manual/5.4/manual.html#pdf-rawequal) 536 536 - </details> 140 140 + See the full [JSON API reference](../reference/lua/json-api.md) for `json.encode` and `json.decode`. 537 141 538 142 ## Debugging 539 143

+88

packages/docs/docs/guides/sqlite-to-postgres-migration.md

reviewed

··· 1 1 + # Migrating from SQLite to Postgres 2 2 + 3 3 + This guide covers migrating an existing HappyView deployment from SQLite to Postgres. If you are staying on SQLite, no action is required. 4 4 + 5 5 + ## Overview 6 6 + 7 7 + HappyView writes all internal SQL in SQLite syntax and translates to Postgres automatically at runtime. This means your **Lua scripts do not need any changes** when switching from SQLite to Postgres — they continue to work as-is. 8 8 + 9 9 + The main steps are: set up the Postgres database, update your environment variables, and re-index your data. 10 10 + 11 11 + ## Step 1: Set up Postgres 12 12 + 13 13 + Create a Postgres database for HappyView: 14 14 + 15 15 + ```sh 16 16 + createdb happyview 17 17 + ``` 18 18 + 19 19 + If you are using Docker Compose, uncomment the `postgres` service and `pgdata` volume in your `docker-compose.yml`. See the [database setup guide](database-setup.md#docker-compose) for details. 20 20 + 21 21 + ## Step 2: Back up your SQLite database 22 22 + 23 23 + Copy your SQLite database file before making any changes: 24 24 + 25 25 + ```sh 26 26 + cp data/happyview.db data/happyview.db.backup 27 27 + ``` 28 28 + 29 29 + ## Step 3: Update environment variables 30 30 + 31 31 + Change your `.env` to use Postgres: 32 32 + 33 33 + ```sh 34 34 + # Before 35 35 + DATABASE_URL=sqlite://data/happyview.db?mode=rwc 36 36 + 37 37 + # After 38 38 + DATABASE_URL=postgres://happyview:happyview@localhost/happyview 39 39 + ``` 40 40 + 41 41 + If you had `DATABASE_BACKEND` set, update it as well: 42 42 + 43 43 + ```sh 44 44 + DATABASE_BACKEND=postgres 45 45 + ``` 46 46 + 47 47 + ## Step 4: Start HappyView 48 48 + 49 49 + Start HappyView with the new `DATABASE_URL`. It will connect to Postgres and run migrations automatically, creating all necessary tables. 50 50 + 51 51 + ## Step 5: Re-index your data 52 52 + 53 53 + Since HappyView indexes records from the AT Protocol network, the simplest way to populate your new Postgres database is to re-run the backfill: 54 54 + 55 55 + 1. Upload your lexicons via the dashboard or admin API (or they will already be there if you exported and re-imported them) 56 56 + 2. Run a backfill for each collection (dashboard or `POST /admin/backfill`) 57 57 + 58 58 + Backfill fetches all records fresh from the network, so no data transfer between databases is needed. 59 59 + 60 60 + :::tip 61 61 + If you have many lexicons, you can export them from the old instance before switching. Use `GET /admin/lexicons` to list them and `POST /admin/lexicons` to re-upload after switching to Postgres. 62 62 + ::: 63 63 + 64 64 + ## Step 6: Re-create admin settings 65 65 + 66 66 + Instance settings (app name, logo, TOS/privacy URIs), API keys, users, and labeler subscriptions are stored in the database and are not carried over automatically. Re-create these via the dashboard or admin API after switching. 67 67 + 68 68 + ## Lua scripts 69 69 + 70 70 + No changes needed. Lua scripts use SQLite syntax by default, and HappyView translates to Postgres automatically at runtime. This includes: 71 71 + 72 72 + - `?` placeholders (translated to `$1`, `$2`, etc.) 73 73 + - `json_extract()` calls (translated to Postgres JSON operators) 74 74 + - `datetime('now')` (translated to `NOW()`) 75 75 + - Boolean literals `1`/`0` (work in both backends) 76 76 + 77 77 + If you have scripts that already use Postgres-native syntax (e.g., from direct `db.raw()` calls), they will **not** work after switching — HappyView expects SQLite syntax. Use the [codemod tool](postgres-to-sqlite-migration.md#run-the-codemod-tool) to convert them. 78 78 + 79 79 + ## Rollback 80 80 + 81 81 + To switch back to SQLite, revert your `DATABASE_URL` to the SQLite connection string. Your SQLite database file remains unchanged — HappyView does not modify it during the migration to Postgres. 82 82 + 83 83 + ## Next steps 84 84 + 85 85 + - [Postgres → SQLite migration](postgres-to-sqlite-migration.md) — migrate in the opposite direction 86 86 + - [Database setup](database-setup.md) — choose between SQLite and Postgres for new instances 87 87 + - [Backfill](backfill.md) — re-index records from the network after switching backends 88 88 + - [Lua scripting](scripting.md) — write SQL that works against either backend

+78 -1199

packages/docs/docs/reference/admin-api.md

reviewed

··· 4 4 5 5 ## Auth 6 6 7 7 - The admin API supports three authentication methods: 7 7 + The admin API supports two authentication methods: 8 8 9 9 - 1. **Session cookie** (web UI) — Set during the OAuth login flow. The signed cookie contains the user's DID. 10 10 - 2. **API keys** — read/write tokens starting with `hv_`, passed as `Authorization: Bearer hv_...`. See the [API Keys guide](../guides/api-keys.md) for details. 11 11 - 3. **Service auth JWT** — AT Protocol inter-service authentication via signed JWTs. 9 9 + 1. **API keys** — read/write tokens starting with `hv_`, passed as `Authorization: Bearer hv_...`. See the [API Keys guide](../guides/api-keys.md) for details. 10 10 + 2. **Service auth JWT** — AT Protocol inter-service authentication via signed JWTs. 12 11 13 12 In all cases the resolved DID is checked against the `users` table, and the user's permissions are loaded to authorize the request. 14 13 ··· 16 15 17 16 Non-user DIDs receive a `403 Forbidden` response. Users without the required permission for a specific endpoint also receive `403 Forbidden`. 18 17 18 18 + ## Errors 19 19 + 19 20 All error responses return JSON with an `error` field: 20 21 21 22 ```json ··· 24 25 } 25 26 ``` 26 27 27 27 - | Status | Meaning | 28 28 - | ------------------ | -------------------------------------------------------------------------------------------------------------- | 29 29 - | `400 Bad Request` | Invalid input (missing required fields, malformed lexicon JSON) | 30 30 - | `401 Unauthorized` | Missing or invalid session cookie, API key, or service auth JWT | 31 31 - | `403 Forbidden` | Authenticated DID is not in the users table, or user lacks the required permission | 32 32 - | `404 Not Found` | Lexicon, user, or backfill job not found | 28 28 + | Status | Meaning | 29 29 + | ------------------ | -------------------------------------------------------------------------------------- | 30 30 + | `400 Bad Request` | Invalid input (missing required fields, malformed lexicon JSON) | 31 31 + | `401 Unauthorized` | Missing or invalid API key or service auth JWT | 32 32 + | `403 Forbidden` | Authenticated DID is not in the users table, or user lacks the required permission | 33 33 + | `404 Not Found` | Lexicon, user, or backfill job not found | 33 34 34 35 ```sh 35 36 # All examples assume $TOKEN is an API key (hv_...) 36 37 AUTH="Authorization: Bearer $TOKEN" 37 38 ``` 38 39 39 39 - ## Lexicons 40 40 - 41 41 - ### Upload / upsert a lexicon 42 42 - 43 43 - ``` 44 44 - POST /admin/lexicons 45 45 - ``` 46 46 - 47 47 - ```sh 48 48 - curl -X POST http://localhost:3000/admin/lexicons \ 49 49 - -H "$AUTH" \ 50 50 - -H "Content-Type: application/json" \ 51 51 - -d '{ 52 52 - "lexicon_json": { "lexicon": 1, "id": "xyz.statusphere.status", "defs": { "main": { "type": "record", "key": "tid", "record": { "type": "object", "required": ["status", "createdAt"], "properties": { "status": { "type": "string", "maxGraphemes": 1 }, "createdAt": { "type": "string", "format": "datetime" } } } } } }, 53 53 - "backfill": true, 54 54 - "target_collection": null 55 55 - }' 56 56 - ``` 57 57 - 58 58 - | Field | Type | Required | Description | 59 59 - | ------------------- | ------- | -------- | --------------------------------------------------------------------- | 60 60 - | `lexicon_json` | object | yes | Raw lexicon JSON (must have `lexicon: 1` and `id`) | 61 61 - | `backfill` | boolean | no | Whether uploading triggers historical backfill (default `true`) | 62 62 - | `target_collection` | string | no | For query/procedure lexicons, the record collection they operate on | 63 63 - | `script` | string | no | Lua script for query/procedure endpoints | 64 64 - | `index_hook` | string | no | [Index hook](../guides/index-hooks.md) Lua script for record lexicons | 65 65 - 66 66 - **Response**: `201 Created` (new) or `200 OK` (upsert) 67 67 - 68 68 - ```json 69 69 - { 70 70 - "id": "xyz.statusphere.status", 71 71 - "revision": 1 72 72 - } 73 73 - ``` 74 74 - 75 75 - ### List lexicons 76 76 - 77 77 - ``` 78 78 - GET /admin/lexicons 79 79 - ``` 80 80 - 81 81 - ```sh 82 82 - curl http://localhost:3000/admin/lexicons -H "$AUTH" 83 83 - ``` 84 84 - 85 85 - **Response**: `200 OK` 86 86 - 87 87 - ```json 88 88 - [ 89 89 - { 90 90 - "id": "xyz.statusphere.status", 91 91 - "revision": 1, 92 92 - "lexicon_type": "record", 93 93 - "backfill": true, 94 94 - "created_at": "2025-01-01T00:00:00Z", 95 95 - "updated_at": "2025-01-01T00:00:00Z" 96 96 - } 97 97 - ] 98 98 - ``` 99 99 - 100 100 - ### Get a lexicon 101 101 - 102 102 - ``` 103 103 - GET /admin/lexicons/{id} 104 104 - ``` 105 105 - 106 106 - ```sh 107 107 - curl http://localhost:3000/admin/lexicons/xyz.statusphere.status -H "$AUTH" 108 108 - ``` 109 109 - 110 110 - **Response**: `200 OK` with full lexicon details including raw JSON. 111 111 - 112 112 - ### Delete a lexicon 113 113 - 114 114 - ``` 115 115 - DELETE /admin/lexicons/{id} 116 116 - ``` 117 117 - 118 118 - ```sh 119 119 - curl -X DELETE http://localhost:3000/admin/lexicons/xyz.statusphere.status -H "$AUTH" 120 120 - ``` 121 121 - 122 122 - **Response**: `204 No Content` 123 123 - 124 124 - ## Network Lexicons 125 125 - 126 126 - Network lexicons are fetched from the AT Protocol network via DNS TXT resolution and kept updated via the Jetstream subscription. See [Lexicons - Network lexicons](../guides/lexicons.md#network-lexicons) for background. 127 127 - 128 128 - ### Add a network lexicon 129 129 - 130 130 - ``` 131 131 - POST /admin/network-lexicons 132 132 - ``` 133 133 - 134 134 - ```sh 135 135 - curl -X POST http://localhost:3000/admin/network-lexicons \ 136 136 - -H "$AUTH" \ 137 137 - -H "Content-Type: application/json" \ 138 138 - -d '{ 139 139 - "nsid": "xyz.statusphere.status", 140 140 - "target_collection": null 141 141 - }' 142 142 - ``` 143 143 - 144 144 - | Field | Type | Required | Description | 145 145 - | ------------------- | ------ | -------- | ------------------------------------------------------------------- | 146 146 - | `nsid` | string | yes | The NSID of the lexicon to watch | 147 147 - | `target_collection` | string | no | For query/procedure lexicons, the record collection they operate on | 148 148 - 149 149 - HappyView resolves the NSID authority via DNS TXT, fetches the lexicon from the authority's PDS, parses it, and stores it. 150 150 - 151 151 - **Response**: `201 Created` 152 152 - 153 153 - ```json 154 154 - { 155 155 - "nsid": "xyz.statusphere.status", 156 156 - "authority_did": "did:plc:authority", 157 157 - "revision": 1 158 158 - } 159 159 - ``` 160 160 - 161 161 - ### List network lexicons 162 162 - 163 163 - ``` 164 164 - GET /admin/network-lexicons 165 165 - ``` 166 166 - 167 167 - ```sh 168 168 - curl http://localhost:3000/admin/network-lexicons -H "$AUTH" 169 169 - ``` 170 170 - 171 171 - **Response**: `200 OK` 172 172 - 173 173 - ```json 174 174 - [ 175 175 - { 176 176 - "nsid": "xyz.statusphere.status", 177 177 - "authority_did": "did:plc:authority", 178 178 - "target_collection": null, 179 179 - "last_fetched_at": "2025-01-01T00:00:00Z", 180 180 - "created_at": "2025-01-01T00:00:00Z" 181 181 - } 182 182 - ] 183 183 - ``` 184 184 - 185 185 - ### Remove a network lexicon 186 186 - 187 187 - ``` 188 188 - DELETE /admin/network-lexicons/{nsid} 189 189 - ``` 190 190 - 191 191 - ```sh 192 192 - curl -X DELETE http://localhost:3000/admin/network-lexicons/xyz.statusphere.status \ 193 193 - -H "$AUTH" 194 194 - ``` 195 195 - 196 196 - Removes the network lexicon tracking and also deletes the lexicon from the `lexicons` table and in-memory registry. 197 197 - 198 198 - **Response**: `204 No Content` 199 199 - 200 200 - ## Stats 201 201 - 202 202 - ### Record counts 203 203 - 204 204 - ``` 205 205 - GET /admin/stats 206 206 - ``` 207 207 - 208 208 - ```sh 209 209 - curl http://localhost:3000/admin/stats -H "$AUTH" 210 210 - ``` 211 211 - 212 212 - **Response**: `200 OK` 213 213 - 214 214 - ```json 215 215 - { 216 216 - "total_records": 12345, 217 217 - "collections": [{ "collection": "xyz.statusphere.status", "count": 500 }] 218 218 - } 219 219 - ``` 220 220 - 221 221 - ## Backfill 222 222 - 223 223 - ### Create a backfill job 224 224 - 225 225 - ``` 226 226 - POST /admin/backfill 227 227 - ``` 228 228 - 229 229 - ```sh 230 230 - curl -X POST http://localhost:3000/admin/backfill \ 231 231 - -H "$AUTH" \ 232 232 - -H "Content-Type: application/json" \ 233 233 - -d '{ "collection": "xyz.statusphere.status" }' 234 234 - ``` 235 235 - 236 236 - | Field | Type | Required | Description | 237 237 - | ------------ | ------ | -------- | ---------------------------------------------------------- | 238 238 - | `collection` | string | no | Limit to a single collection (backfills all if omitted) | 239 239 - | `did` | string | no | Limit to a single DID (discovers all via relay if omitted) | 240 240 - 241 241 - **Response**: `201 Created` 242 242 - 243 243 - ```json 244 244 - { 245 245 - "id": "550e8400-e29b-41d4-a716-446655440000", 246 246 - "status": "pending" 247 247 - } 248 248 - ``` 249 249 - 250 250 - ### List backfill jobs 251 251 - 252 252 - ``` 253 253 - GET /admin/backfill/status 254 254 - ``` 255 255 - 256 256 - ```sh 257 257 - curl http://localhost:3000/admin/backfill/status -H "$AUTH" 258 258 - ``` 259 259 - 260 260 - **Response**: `200 OK` 261 261 - 262 262 - ```json 263 263 - [ 264 264 - { 265 265 - "id": "550e8400-e29b-41d4-a716-446655440000", 266 266 - "collection": "xyz.statusphere.status", 267 267 - "did": null, 268 268 - "status": "completed", 269 269 - "total_repos": 42, 270 270 - "processed_repos": 42, 271 271 - "total_records": 1000, 272 272 - "error": null, 273 273 - "started_at": "2025-01-01T00:01:00Z", 274 274 - "completed_at": "2025-01-01T00:05:00Z", 275 275 - "created_at": "2025-01-01T00:00:00Z" 276 276 - } 277 277 - ] 278 278 - ``` 279 279 - 280 280 - ## Event Logs 281 281 - 282 282 - HappyView records an audit trail of system events: lexicon changes, record operations, Lua script executions and errors, user actions, backfill jobs, and Jetstream connectivity. See the [Event Logs guide](../guides/event-logs.md) for details on event types and retention. 283 283 - 284 284 - ### List event logs 285 285 - 286 286 - ``` 287 287 - GET /admin/events 288 288 - ``` 289 289 - 290 290 - ```sh 291 291 - curl "http://localhost:3000/admin/events?severity=error&limit=10" -H "$AUTH" 292 292 - ``` 293 293 - 294 294 - | Param | Type | Required | Description | 295 295 - | ------------ | ------ | -------- | --------------------------------------------------------------------- | 296 296 - | `event_type` | string | no | Filter by exact event type (e.g. `script.error`) | 297 297 - | `category` | string | no | Filter by category prefix (e.g. `lexicon` matches all lexicon events) | 298 298 - | `severity` | string | no | Filter by severity: `info`, `warn`, or `error` | 299 299 - | `subject` | string | no | Filter by subject (lexicon ID, record URI, admin DID, etc.) | 300 300 - | `cursor` | string | no | Pagination cursor (ISO 8601 timestamp from previous response) | 301 301 - | `limit` | number | no | Results per page (default `50`, max `100`) | 40 40 + ## Endpoint groups 302 41 303 303 - **Response**: `200 OK` 304 304 - 305 305 - ```json 306 306 - { 307 307 - "events": [ 308 308 - { 309 309 - "id": "550e8400-e29b-41d4-a716-446655440000", 310 310 - "event_type": "script.error", 311 311 - "severity": "error", 312 312 - "actor_did": "did:plc:abc123", 313 313 - "subject": "com.example.feed.like", 314 314 - "detail": { 315 315 - "error": "attempt to index nil value", 316 316 - "script_source": "function handle() ... end", 317 317 - "input": { "status": "hello" }, 318 318 - "caller_did": "did:plc:abc123", 319 319 - "method": "com.example.feed.like" 320 320 - }, 321 321 - "created_at": "2026-03-01T12:00:00Z" 322 322 - } 323 323 - ], 324 324 - "cursor": "2026-03-01T11:59:00Z" 325 325 - } 326 326 - ``` 327 327 - 328 328 - Events are returned in reverse chronological order (newest first). Pass the `cursor` value from the response to fetch the next page. 329 329 - 330 330 - ## API Keys 331 331 - 332 332 - Manage API keys for programmatic access. See the [API Keys guide](../guides/api-keys.md) for usage details. 333 333 - 334 334 - ### Create an API key 335 335 - 336 336 - ``` 337 337 - POST /admin/api-keys 338 338 - ``` 339 339 - 340 340 - Requires `api-keys:create` permission. 341 341 - 342 342 - ```sh 343 343 - curl -X POST http://localhost:3000/admin/api-keys \ 344 344 - -H "$AUTH" \ 345 345 - -H "Content-Type: application/json" \ 346 346 - -d '{ 347 347 - "name": "CI Deploy", 348 348 - "permissions": ["lexicons:read", "lexicons:create", "backfill:create"] 349 349 - }' 350 350 - ``` 351 351 - 352 352 - | Field | Type | Required | Description | 353 353 - | ------------- | -------- | -------- | -------------------------------------------------------------------------------------------- | 354 354 - | `name` | string | yes | A label to identify this key's usage | 355 355 - | `permissions` | string[] | yes | Permissions to grant the key (must be a subset of the creating user's own permissions) | 356 356 - 357 357 - **Response**: `201 Created` 358 358 - 359 359 - ```json 360 360 - { 361 361 - "id": "550e8400-e29b-41d4-a716-446655440000", 362 362 - "name": "CI Deploy", 363 363 - "key": "hv_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", 364 364 - "key_prefix": "hv_a1b2c3d4", 365 365 - "permissions": ["lexicons:read", "lexicons:create", "backfill:create"] 366 366 - } 367 367 - ``` 368 368 - 369 369 - The `key` field contains the full API key. It is only returned in this response — store it securely. The key's effective permissions are the **intersection** of the permissions specified here and the creating user's permissions at the time of each request. 370 370 - 371 371 - ### List API keys 372 372 - 373 373 - ``` 374 374 - GET /admin/api-keys 375 375 - ``` 376 376 - 377 377 - Requires `api-keys:read` permission. 378 378 - 379 379 - ```sh 380 380 - curl http://localhost:3000/admin/api-keys -H "$AUTH" 381 381 - ``` 382 382 - 383 383 - **Response**: `200 OK` 384 384 - 385 385 - ```json 386 386 - [ 387 387 - { 388 388 - "id": "550e8400-e29b-41d4-a716-446655440000", 389 389 - "name": "CI Deploy", 390 390 - "key_prefix": "hv_a1b2c3d4", 391 391 - "permissions": ["lexicons:read", "lexicons:create", "backfill:create"], 392 392 - "created_at": "2026-03-01T00:00:00Z", 393 393 - "last_used_at": "2026-03-06T12:00:00Z", 394 394 - "revoked_at": null 395 395 - } 396 396 - ] 397 397 - ``` 398 398 - 399 399 - Only returns keys belonging to the authenticated user. The full key is never included — only the prefix. 400 400 - 401 401 - ### Revoke an API key 402 402 - 403 403 - ``` 404 404 - DELETE /admin/api-keys/{id} 405 405 - ``` 406 406 - 407 407 - Requires `api-keys:delete` permission. 408 408 - 409 409 - ```sh 410 410 - curl -X DELETE http://localhost:3000/admin/api-keys/550e8400-e29b-41d4-a716-446655440000 \ 411 411 - -H "$AUTH" 412 412 - ``` 413 413 - 414 414 - Sets `revoked_at` on the key. The key remains in the database for audit purposes but can no longer authenticate. 415 415 - 416 416 - **Response**: `204 No Content` 417 417 - 418 418 - ## User Management 419 419 - 420 420 - ### Create a user 421 421 - 422 422 - ``` 423 423 - POST /admin/users 424 424 - ``` 425 425 - 426 426 - Requires `users:create` permission. You cannot grant permissions you don't have yourself (escalation guard). 427 427 - 428 428 - ```sh 429 429 - curl -X POST http://localhost:3000/admin/users \ 430 430 - -H "$AUTH" \ 431 431 - -H "Content-Type: application/json" \ 432 432 - -d '{ 433 433 - "did": "did:plc:newuser", 434 434 - "template": "operator" 435 435 - }' 436 436 - ``` 437 437 - 438 438 - | Field | Type | Required | Description | 439 439 - | ------------- | -------- | -------- | ------------------------------------------------------------------------------------------------- | 440 440 - | `did` | string | yes | The AT Protocol DID of the user to add | 441 441 - | `template` | string | no | Permission template: `viewer`, `operator`, `manager`, or `full_access` | 442 442 - | `permissions` | string[] | no | Explicit list of permissions to grant (used instead of or in addition to `template`) | 443 443 - 444 444 - If neither `template` nor `permissions` is provided, the user is created with no permissions. 445 445 - 446 446 - **Response**: `201 Created` 447 447 - 448 448 - ```json 449 449 - { 450 450 - "id": "550e8400-e29b-41d4-a716-446655440000", 451 451 - "did": "did:plc:newuser", 452 452 - "is_super": false, 453 453 - "permissions": ["lexicons:read", "records:read", "script-variables:read", "users:read", "api-keys:read", "api-keys:create", "api-keys:delete", "backfill:read", "backfill:create", "stats:read", "events:read"] 454 454 - } 455 455 - ``` 456 456 - 457 457 - ### List users 458 458 - 459 459 - ``` 460 460 - GET /admin/users 461 461 - ``` 462 462 - 463 463 - Requires `users:read` permission. 464 464 - 465 465 - ```sh 466 466 - curl http://localhost:3000/admin/users -H "$AUTH" 467 467 - ``` 468 468 - 469 469 - **Response**: `200 OK` 470 470 - 471 471 - ```json 472 472 - [ 473 473 - { 474 474 - "id": "550e8400-e29b-41d4-a716-446655440000", 475 475 - "did": "did:plc:admin", 476 476 - "is_super": true, 477 477 - "permissions": ["lexicons:create", "lexicons:read", "lexicons:delete", "records:read", "records:delete", "records:delete-collection", "script-variables:create", "script-variables:read", "script-variables:delete", "users:create", "users:read", "users:update", "users:delete", "api-keys:create", "api-keys:read", "api-keys:delete", "backfill:create", "backfill:read", "stats:read", "events:read"], 478 478 - "created_at": "2025-01-01T00:00:00Z", 479 479 - "last_used_at": "2025-01-02T12:00:00Z" 480 480 - } 481 481 - ] 482 482 - ``` 483 483 - 484 484 - ### Get a user 485 485 - 486 486 - ``` 487 487 - GET /admin/users/{id} 488 488 - ``` 489 489 - 490 490 - Requires `users:read` permission. 491 491 - 492 492 - ```sh 493 493 - curl http://localhost:3000/admin/users/550e8400-e29b-41d4-a716-446655440000 -H "$AUTH" 494 494 - ``` 495 495 - 496 496 - **Response**: `200 OK` with the same shape as a single item from the list response. 497 497 - 498 498 - ### Update user permissions 499 499 - 500 500 - ``` 501 501 - PATCH /admin/users/{id}/permissions 502 502 - ``` 503 503 - 504 504 - Requires `users:update` permission. You cannot grant permissions you don't have yourself, and you cannot modify the super user's permissions. 505 505 - 506 506 - ```sh 507 507 - curl -X PATCH http://localhost:3000/admin/users/550e8400-e29b-41d4-a716-446655440000/permissions \ 508 508 - -H "$AUTH" \ 509 509 - -H "Content-Type: application/json" \ 510 510 - -d '{ 511 511 - "grant": ["lexicons:create", "lexicons:delete"], 512 512 - "revoke": ["records:delete"] 513 513 - }' 514 514 - ``` 515 515 - 516 516 - | Field | Type | Required | Description | 517 517 - | -------- | -------- | -------- | ------------------------------ | 518 518 - | `grant` | string[] | no | Permissions to add | 519 519 - | `revoke` | string[] | no | Permissions to remove | 520 520 - 521 521 - **Response**: `200 OK` with the updated user object. 522 522 - 523 523 - ### Transfer super user 524 524 - 525 525 - ``` 526 526 - POST /admin/users/transfer-super 527 527 - ``` 528 528 - 529 529 - Only the current super user can call this endpoint. Transfers super user status to another existing user. 530 530 - 531 531 - ```sh 532 532 - curl -X POST http://localhost:3000/admin/users/transfer-super \ 533 533 - -H "$AUTH" \ 534 534 - -H "Content-Type: application/json" \ 535 535 - -d '{ "target_user_id": "550e8400-e29b-41d4-a716-446655440000" }' 536 536 - ``` 537 537 - 538 538 - | Field | Type | Required | Description | 539 539 - | ---------------- | ------ | -------- | ---------------------------------------- | 540 540 - | `target_user_id` | string | yes | The ID of the user to receive super status | 541 541 - 542 542 - **Response**: `200 OK` 543 543 - 544 544 - ### Delete a user 545 545 - 546 546 - ``` 547 547 - DELETE /admin/users/{id} 548 548 - ``` 549 549 - 550 550 - Requires `users:delete` permission. You cannot delete the super user or yourself. 551 551 - 552 552 - ```sh 553 553 - curl -X DELETE http://localhost:3000/admin/users/550e8400-e29b-41d4-a716-446655440000 \ 554 554 - -H "$AUTH" 555 555 - ``` 556 556 - 557 557 - **Response**: `204 No Content` 558 558 - 559 559 - ## Labelers 560 560 - 561 561 - Manage external labeler subscriptions. See the [Labelers guide](../guides/labelers.md) for background. 562 562 - 563 563 - ### Add a labeler 564 564 - 565 565 - ``` 566 566 - POST /admin/labelers 567 567 - ``` 568 568 - 569 569 - Requires `labelers:create` permission. 570 570 - 571 571 - ```sh 572 572 - curl -X POST http://localhost:3000/admin/labelers \ 573 573 - -H "$AUTH" \ 574 574 - -H "Content-Type: application/json" \ 575 575 - -d '{ "did": "did:plc:ar7c4by46qjdydhdevvrndac" }' 576 576 - ``` 577 577 - 578 578 - | Field | Type | Required | Description | 579 579 - | ----- | ------ | -------- | ---------------------- | 580 580 - | `did` | string | yes | The labeler's AT Protocol DID | 581 581 - 582 582 - **Response**: `201 Created` (empty body) 583 583 - 584 584 - ### List labelers 585 585 - 586 586 - ``` 587 587 - GET /admin/labelers 588 588 - ``` 589 589 - 590 590 - Requires `labelers:read` permission. 591 591 - 592 592 - ```sh 593 593 - curl http://localhost:3000/admin/labelers -H "$AUTH" 594 594 - ``` 595 595 - 596 596 - **Response**: `200 OK` 597 597 - 598 598 - ```json 599 599 - [ 600 600 - { 601 601 - "did": "did:plc:ar7c4by46qjdydhdevvrndac", 602 602 - "status": "active", 603 603 - "cursor": 1234, 604 604 - "created_at": "2026-03-15T00:00:00Z", 605 605 - "updated_at": "2026-03-15T00:00:00Z" 606 606 - } 607 607 - ] 608 608 - ``` 609 609 - 610 610 - | Field | Type | Description | 611 611 - | ------------ | ------------ | ------------------------------------------------ | 612 612 - | `did` | string | The labeler's DID | 613 613 - | `status` | string | `active` or `paused` | 614 614 - | `cursor` | number\|null | Last processed event cursor (null if never synced) | 615 615 - | `created_at` | string | ISO 8601 creation timestamp | 616 616 - | `updated_at` | string | ISO 8601 last-updated timestamp | 617 617 - 618 618 - ### Update a labeler 619 619 - 620 620 - ``` 621 621 - PATCH /admin/labelers/{did} 622 622 - ``` 623 623 - 624 624 - Requires `labelers:create` permission. 625 625 - 626 626 - ```sh 627 627 - curl -X PATCH http://localhost:3000/admin/labelers/did:plc:ar7c4by46qjdydhdevvrndac \ 628 628 - -H "$AUTH" \ 629 629 - -H "Content-Type: application/json" \ 630 630 - -d '{ "status": "paused" }' 631 631 - ``` 632 632 - 633 633 - | Field | Type | Required | Description | 634 634 - | -------- | ------ | -------- | ---------------------------- | 635 635 - | `status` | string | yes | New status: `active` or `paused` | 636 636 - 637 637 - **Response**: `200 OK` 638 638 - 639 639 - ### Delete a labeler 640 640 - 641 641 - ``` 642 642 - DELETE /admin/labelers/{did} 643 643 - ``` 644 644 - 645 645 - Requires `labelers:delete` permission. Removes the subscription and all labels emitted by this labeler. 646 646 - 647 647 - ```sh 648 648 - curl -X DELETE http://localhost:3000/admin/labelers/did:plc:ar7c4by46qjdydhdevvrndac \ 649 649 - -H "$AUTH" 650 650 - ``` 651 651 - 652 652 - **Response**: `204 No Content` 653 653 - 654 654 - ## Instance Settings 655 655 - 656 656 - Instance settings are key/value entries used to override environment-variable defaults at runtime (for example, the application name, terms-of-service URL, privacy policy URL, and uploaded logo). Settings stored here take precedence over the corresponding environment variables. All endpoints require the `settings:manage` permission. 657 657 - 658 658 - ### List settings 659 659 - 660 660 - ``` 661 661 - GET /admin/settings 662 662 - ``` 663 663 - 664 664 - ```sh 665 665 - curl http://localhost:3000/admin/settings -H "$AUTH" 666 666 - ``` 667 667 - 668 668 - Returns all key/value pairs stored in the `instance_settings` table. 669 669 - 670 670 - ### Upsert a setting 671 671 - 672 672 - ``` 673 673 - PUT /admin/settings/{key} 674 674 - ``` 675 675 - 676 676 - ```sh 677 677 - curl -X PUT http://localhost:3000/admin/settings/app_name \ 678 678 - -H "$AUTH" \ 679 679 - -H "Content-Type: application/json" \ 680 680 - -d '{ "value": "My HappyView" }' 681 681 - ``` 682 682 - 683 683 - ### Delete a setting 684 684 - 685 685 - ``` 686 686 - DELETE /admin/settings/{key} 687 687 - ``` 688 688 - 689 689 - Removes the override; the corresponding environment variable (if any) takes effect again. 690 690 - 691 691 - ### Upload / delete logo 692 692 - 693 693 - ``` 694 694 - PUT /admin/settings/logo 695 695 - DELETE /admin/settings/logo 696 696 - ``` 697 697 - 698 698 - `PUT` accepts a binary image body and stores it as the instance logo (served via the public dashboard). `DELETE` removes the stored logo. 699 699 - 700 700 - ## Domain Management 701 701 - 702 702 - Manage the domains a HappyView instance serves. Each domain gets its own AT Protocol OAuth client identity. The primary domain is auto-seeded from `PUBLIC_URL` on first boot. All endpoints require the `settings:manage` permission. 703 703 - 704 704 - ### List domains 705 705 - 706 706 - ``` 707 707 - GET /admin/domains 708 708 - ``` 709 709 - 710 710 - ```sh 711 711 - curl http://localhost:3000/admin/domains -H "$AUTH" 712 712 - ``` 713 713 - 714 714 - **Response**: `200 OK` 715 715 - 716 716 - ```json 717 717 - [ 718 718 - { 719 719 - "id": "550e8400-e29b-41d4-a716-446655440000", 720 720 - "url": "https://gamesgamesgamesgames.games", 721 721 - "is_primary": true, 722 722 - "created_at": "2026-04-16T00:00:00Z", 723 723 - "updated_at": "2026-04-16T00:00:00Z" 724 724 - } 725 725 - ] 726 726 - ``` 727 727 - 728 728 - ### Add a domain 729 729 - 730 730 - ``` 731 731 - POST /admin/domains 732 732 - ``` 733 733 - 734 734 - ```sh 735 735 - curl -X POST http://localhost:3000/admin/domains \ 736 736 - -H "$AUTH" \ 737 737 - -H "Content-Type: application/json" \ 738 738 - -d '{ "url": "https://api.cartridge.dev" }' 739 739 - ``` 740 740 - 741 741 - | Field | Type | Required | Description | 742 742 - | ----- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | 743 743 - | `url` | string | yes | Valid origin (scheme + host, no path or trailing slash). Must be `https` unless `PUBLIC_URL` is a loopback address. | 744 744 - 745 745 - Returns `400 Bad Request` if the URL is invalid or already registered. 746 746 - 747 747 - **Response**: `201 Created` 748 748 - 749 749 - ```json 750 750 - { 751 751 - "id": "550e8400-e29b-41d4-a716-446655440001", 752 752 - "url": "https://api.cartridge.dev", 753 753 - "is_primary": false, 754 754 - "created_at": "2026-04-16T00:00:00Z", 755 755 - "updated_at": "2026-04-16T00:00:00Z" 756 756 - } 757 757 - ``` 758 758 - 759 759 - Side effects: builds an OAuth client for the domain, updates the in-memory domain cache. 760 760 - 761 761 - ### Remove a domain 762 762 - 763 763 - ``` 764 764 - DELETE /admin/domains/{id} 765 765 - ``` 766 766 - 767 767 - ```sh 768 768 - curl -X DELETE http://localhost:3000/admin/domains/550e8400-e29b-41d4-a716-446655440001 \ 769 769 - -H "$AUTH" 770 770 - ``` 771 771 - 772 772 - Returns `400 Bad Request` if the domain is primary — set a different domain as primary first. Returns `404 Not Found` if the domain doesn't exist. 773 773 - 774 774 - **Response**: `204 No Content` 775 775 - 776 776 - Side effects: removes the domain's OAuth client and cache entry. 777 777 - 778 778 - ### Set primary domain 779 779 - 780 780 - ``` 781 781 - POST /admin/domains/{id}/primary 782 782 - ``` 783 783 - 784 784 - ```sh 785 785 - curl -X POST http://localhost:3000/admin/domains/550e8400-e29b-41d4-a716-446655440001/primary \ 786 786 - -H "$AUTH" 787 787 - ``` 788 788 - 789 789 - Sets the target domain as the primary. Unsets the current primary in a single operation. Returns `404 Not Found` if the domain doesn't exist. 790 790 - 791 791 - **Response**: `204 No Content` 792 792 - 793 793 - Side effects: updates the in-memory cache and the OAuth client registry's primary client reference. 794 794 - 795 795 - ## Script Variables 796 796 - 797 797 - Script variables are encrypted key/value pairs available to Lua scripts via the `vars` global. Use them for secrets like API tokens. 798 798 - 799 799 - ### List script variables 800 800 - 801 801 - ``` 802 802 - GET /admin/script-variables 803 803 - ``` 804 804 - 805 805 - Requires `script-variables:read`. Returns a list of variable keys (values are not returned). 806 806 - 807 807 - ### Upsert a script variable 808 808 - 809 809 - ``` 810 810 - POST /admin/script-variables 811 811 - ``` 812 812 - 813 813 - Requires `script-variables:create`. 814 814 - 815 815 - ```sh 816 816 - curl -X POST http://localhost:3000/admin/script-variables \ 817 817 - -H "$AUTH" \ 818 818 - -H "Content-Type: application/json" \ 819 819 - -d '{ "key": "ALGOLIA_API_KEY", "value": "..." }' 820 820 - ``` 821 821 - 822 822 - The value is encrypted at rest using `TOKEN_ENCRYPTION_KEY`. 823 823 - 824 824 - ### Delete a script variable 825 825 - 826 826 - ``` 827 827 - DELETE /admin/script-variables/{key} 828 828 - ``` 829 829 - 830 830 - Requires `script-variables:delete`. 831 831 - 832 832 - ## API Clients 833 833 - 834 834 - API clients represent third-party applications that call HappyView's XRPC endpoints. **Every XRPC request** — including unauthenticated queries — must identify itself with a registered client via the `X-Client-Key` header (or session cookie, or `client_key` query param). The client key is HappyView's rate-limit bucket and caller identity; a request without one gets `401 Unauthorized`. 835 835 - 836 836 - Each client has an `hvc_`-prefixed client key and an `hvs_`-prefixed client secret. The secret is only returned once (at creation) and is sha256-hashed in the database. Server-to-server callers pass the secret as `X-Client-Secret`; browser callers rely on the `Origin` header matching the client's registered `client_uri`. Both checks currently log warnings on mismatch rather than rejecting the request, but the rate-limit bucket is applied either way. See [Authentication — XRPC](../getting-started/authentication.md#xrpc-api-client-identification) for the client-side view, and the [API Keys guide](../guides/api-keys.md) for how admin API keys differ from API clients. 837 837 - 838 838 - ### List API clients 839 839 - 840 840 - ``` 841 841 - GET /admin/api-clients 842 842 - ``` 843 843 - 844 844 - Requires `api-clients:view`. Returns clients ordered by `created_at` descending. Secrets are never returned. 845 845 - 846 846 - ```sh 847 847 - curl http://localhost:3000/admin/api-clients -H "$AUTH" 848 848 - ``` 849 849 - 850 850 - **Response**: `200 OK` 851 851 - 852 852 - ```json 853 853 - [ 854 854 - { 855 855 - "id": "01J9...", 856 856 - "client_key": "hvc_a1b2c3...", 857 857 - "name": "My Game Client", 858 858 - "client_id_url": "https://example.com/client-metadata.json", 859 859 - "client_uri": "https://example.com", 860 860 - "redirect_uris": ["https://example.com/callback"], 861 861 - "scopes": "atproto", 862 862 - "rate_limit_capacity": 200, 863 863 - "rate_limit_refill_rate": 5.0, 864 864 - "is_active": true, 865 865 - "created_by": "did:plc:...", 866 866 - "created_at": "2026-04-13T12:00:00Z", 867 867 - "updated_at": "2026-04-13T12:00:00Z" 868 868 - } 869 869 - ] 870 870 - ``` 871 871 - 872 872 - ### Create an API client 873 873 - 874 874 - ``` 875 875 - POST /admin/api-clients 876 876 - ``` 877 877 - 878 878 - Requires `api-clients:create`. Generates a fresh `client_key` and `client_secret`. **The secret is only returned in this response** — store it immediately. 879 879 - 880 880 - ```sh 881 881 - curl -X POST http://localhost:3000/admin/api-clients \ 882 882 - -H "$AUTH" \ 883 883 - -H "Content-Type: application/json" \ 884 884 - -d '{ 885 885 - "name": "My Game Client", 886 886 - "client_id_url": "https://example.com/client-metadata.json", 887 887 - "client_uri": "https://example.com", 888 888 - "redirect_uris": ["https://example.com/callback"], 889 889 - "scopes": "atproto", 890 890 - "rate_limit_capacity": 200, 891 891 - "rate_limit_refill_rate": 5.0 892 892 - }' 893 893 - ``` 894 894 - 895 895 - | Field | Type | Required | Description | 896 896 - | ------------------------ | -------- | -------- | -------------------------------------------------------------------------------------- | 897 897 - | `name` | string | yes | Human-readable display name | 898 898 - | `client_id_url` | string | yes | URL to the client's published OAuth client metadata document | 899 899 - | `client_uri` | string | yes | The client's home/landing URL | 900 900 - | `redirect_uris` | string[] | yes | Allowed OAuth redirect URIs | 901 901 - | `scopes` | string | no | Space-separated OAuth scopes (default `"atproto"`) | 902 902 - | `rate_limit_capacity` | integer | no | Per-client token bucket capacity. Falls back to `DEFAULT_RATE_LIMIT_CAPACITY` if unset | 903 903 - | `rate_limit_refill_rate` | number | no | Tokens added per second. Falls back to `DEFAULT_RATE_LIMIT_REFILL_RATE` if unset | 904 904 - 905 905 - **Response**: `201 Created` 906 906 - 907 907 - ```json 908 908 - { 909 909 - "id": "01J9...", 910 910 - "client_key": "hvc_a1b2c3...", 911 911 - "client_secret": "hvs_d4e5f6...", 912 912 - "name": "My Game Client", 913 913 - "client_id_url": "https://example.com/client-metadata.json" 914 914 - } 915 915 - ``` 916 916 - 917 917 - The new client is immediately registered with the OAuth registry and rate limiter, so it can authenticate without restarting HappyView. 918 918 - 919 919 - ### Get an API client 920 920 - 921 921 - ``` 922 922 - GET /admin/api-clients/{id} 923 923 - ``` 924 924 - 925 925 - Requires `api-clients:view`. Returns the same `ApiClientSummary` shape as the list endpoint, or `404 Not Found`. 926 926 - 927 927 - ### Update an API client 928 928 - 929 929 - ``` 930 930 - PUT /admin/api-clients/{id} 931 931 - ``` 932 932 - 933 933 - Requires `api-clients:edit`. All fields are optional — only provided fields are changed. Updating either rate-limit field re-registers the client with the rate limiter using the new values. 934 934 - 935 935 - | Field | Type | Description | 936 936 - | ------------------------ | -------- | ------------------------------------------------------------------------ | 937 937 - | `name` | string | New display name | 938 938 - | `client_uri` | string | New home URL | 939 939 - | `redirect_uris` | string[] | Replace the allowed redirect URIs | 940 940 - | `scopes` | string | Replace the OAuth scopes | 941 941 - | `rate_limit_capacity` | integer | New bucket capacity. Pass `null` to clear the override | 942 942 - | `rate_limit_refill_rate` | number | New refill rate. Pass `null` to clear the override | 943 943 - | `is_active` | boolean | Disable (`false`) or re-enable (`true`) the client without deleting it | 944 944 - 945 945 - **Response**: `204 No Content` 946 946 - 947 947 - The OAuth registry is updated in place. The `client_id_url` is immutable — to change it, delete and recreate the client. 948 948 - 949 949 - ### Delete an API client 950 950 - 951 951 - ``` 952 952 - DELETE /admin/api-clients/{id} 953 953 - ``` 954 954 - 955 955 - Requires `api-clients:delete`. Removes the client from the OAuth registry, the rate limiter, and the client identity store. 956 956 - 957 957 - **Response**: `204 No Content` 958 958 - 959 959 - ## Plugins 960 960 - 961 961 - Plugins extend HappyView with WebAssembly modules sourced from the [official plugin registry](../guides/plugins.md) or any URL serving a `manifest.json`. Most endpoints take a plugin manifest URL and load (or reload) the plugin in place — no restart needed. Encrypted plugin secrets require `TOKEN_ENCRYPTION_KEY` to be configured. 962 962 - 963 963 - ### List installed plugins 964 964 - 965 965 - ``` 966 966 - GET /admin/plugins 967 967 - ``` 968 968 - 969 969 - Requires `plugins:read`. Returns every loaded plugin with its source, required secrets, configuration status, and any pending updates from the official registry cache. 970 970 - 971 971 - ```sh 972 972 - curl http://localhost:3000/admin/plugins -H "$AUTH" 973 973 - ``` 974 974 - 975 975 - **Response**: `200 OK` 976 976 - 977 977 - ```json 978 978 - { 979 979 - "encryption_configured": true, 980 980 - "plugins": [ 981 981 - { 982 982 - "id": "steam", 983 983 - "name": "Steam", 984 984 - "version": "1.2.0", 985 985 - "source": "url", 986 986 - "url": "https://example.com/plugins/steam/manifest.json", 987 987 - "sha256": null, 988 988 - "enabled": true, 989 989 - "auth_type": "openid", 990 990 - "required_secrets": [ 991 991 - { 992 992 - "key": "PLUGIN_STEAM_API_KEY", 993 993 - "name": "Steam Web API Key", 994 994 - "description": "Get your API key at steamcommunity.com/dev/apikey" 995 995 - } 996 996 - ], 997 997 - "secrets_configured": true, 998 998 - "loaded_at": null, 999 999 - "update_available": false, 1000 1000 - "latest_version": "1.2.0", 1001 1001 - "pending_releases": [] 1002 1002 - } 1003 1003 - ] 1004 1004 - } 1005 1005 - ``` 1006 1006 - 1007 1007 - `secrets_configured` is `true` if the plugin has no required secrets, or if a row exists for it in `plugin_configs`. `update_available` and `pending_releases` are populated from the cached official registry — call `POST /admin/plugins/{id}/check-update` to refresh them. 1008 1008 - 1009 1009 - ### Preview a plugin before installing 1010 1010 - 1011 1011 - ``` 1012 1012 - POST /admin/plugins/preview 1013 1013 - ``` 1014 1014 - 1015 1015 - Requires `plugins:create`. Fetches and parses a manifest without installing the plugin, so the dashboard can show what it would register. 1016 1016 - 1017 1017 - ```sh 1018 1018 - curl -X POST http://localhost:3000/admin/plugins/preview \ 1019 1019 - -H "$AUTH" \ 1020 1020 - -H "Content-Type: application/json" \ 1021 1021 - -d '{ "url": "https://example.com/plugins/steam/manifest.json" }' 1022 1022 - ``` 1023 1023 - 1024 1024 - **Response**: `200 OK` 1025 1025 - 1026 1026 - ```json 1027 1027 - { 1028 1028 - "id": "steam", 1029 1029 - "name": "Steam", 1030 1030 - "version": "1.2.0", 1031 1031 - "description": "Import your Steam game library and playtime data.", 1032 1032 - "icon_url": "https://example.com/steam-icon.png", 1033 1033 - "auth_type": "openid", 1034 1034 - "required_secrets": [ 1035 1035 - { "key": "PLUGIN_STEAM_API_KEY", "name": "Steam Web API Key", "description": "..." } 1036 1036 - ], 1037 1037 - "manifest_url": "https://example.com/plugins/steam/manifest.json", 1038 1038 - "wasm_url": "https://example.com/plugins/steam/steam.wasm" 1039 1039 - } 1040 1040 - ``` 1041 1041 - 1042 1042 - Returns `400 Bad Request` if the manifest can't be fetched or parsed. 1043 1043 - 1044 1044 - ### Install a plugin 1045 1045 - 1046 1046 - ``` 1047 1047 - POST /admin/plugins 1048 1048 - ``` 1049 1049 - 1050 1050 - Requires `plugins:create`. Fetches the manifest, downloads the WASM, registers the plugin, and persists it. 1051 1051 - 1052 1052 - ```sh 1053 1053 - curl -X POST http://localhost:3000/admin/plugins \ 1054 1054 - -H "$AUTH" \ 1055 1055 - -H "Content-Type: application/json" \ 1056 1056 - -d '{ 1057 1057 - "url": "https://example.com/plugins/steam/manifest.json", 1058 1058 - "sha256": "abc123..." 1059 1059 - }' 1060 1060 - ``` 1061 1061 - 1062 1062 - | Field | Type | Required | Description | 1063 1063 - | -------- | ------ | -------- | -------------------------------------------------------------------------------------------- | 1064 1064 - | `url` | string | yes | URL to the plugin's `manifest.json` | 1065 1065 - | `sha256` | string | no | Optional sha256 of the WASM binary. If provided, install fails when the downloaded hash mismatches | 1066 1066 - 1067 1067 - **Response**: `200 OK` returning the same `PluginSummary` shape as the list endpoint. `secrets_configured` will be `false` if the plugin requires any secrets — call `PUT /admin/plugins/{id}/secrets` to configure them before the plugin can run. 1068 1068 - 1069 1069 - ### List official plugins 1070 1070 - 1071 1071 - ``` 1072 1072 - GET /admin/plugins/official 1073 1073 - ``` 1074 1074 - 1075 1075 - Requires `plugins:read`. Returns the cached catalog of plugins from the official registry. The cache is refreshed periodically by the server; use `POST /admin/plugins/{id}/check-update` to force-refresh a single entry. 1076 1076 - 1077 1077 - **Response**: `200 OK` 1078 1078 - 1079 1079 - ```json 1080 1080 - { 1081 1081 - "last_refreshed_at": "2026-04-13T11:00:00Z", 1082 1082 - "plugins": [ 1083 1083 - { 1084 1084 - "id": "steam", 1085 1085 - "name": "Steam", 1086 1086 - "description": "Import your Steam game library and playtime data.", 1087 1087 - "icon_url": "https://example.com/steam-icon.png", 1088 1088 - "latest_version": "1.2.0", 1089 1089 - "manifest_url": "https://example.com/plugins/steam/manifest.json" 1090 1090 - } 1091 1091 - ] 1092 1092 - } 1093 1093 - ``` 1094 1094 - 1095 1095 - ### Remove a plugin 1096 1096 - 1097 1097 - ``` 1098 1098 - DELETE /admin/plugins/{id} 1099 1099 - ``` 1100 1100 - 1101 1101 - Requires `plugins:delete`. Unregisters the plugin from the runtime and deletes its row from the `plugins` table. Plugin secrets in `plugin_configs` are not removed automatically — they're available again if you reinstall the same plugin. 1102 1102 - 1103 1103 - **Response**: `204 No Content`. Returns `404 Not Found` if no plugin with that id is loaded. 1104 1104 - 1105 1105 - ### Reload a plugin 1106 1106 - 1107 1107 - ``` 1108 1108 - POST /admin/plugins/{id}/reload 1109 1109 - ``` 1110 1110 - 1111 1111 - Requires `plugins:create`. Re-fetches the plugin from its current source URL and re-registers it. Useful after publishing a new version of a plugin you host yourself. 1112 1112 - 1113 1113 - The body is optional. To point the plugin at a new URL, pass: 1114 1114 - 1115 1115 - ```json 1116 1116 - { "url": "https://example.com/plugins/steam/manifest.json" } 1117 1117 - ``` 1118 1118 - 1119 1119 - When a new URL is provided, the stored `sha256` is cleared (the new version has its own hash). File-based plugins cannot be reloaded via this endpoint and return `400 Bad Request`. 1120 1120 - 1121 1121 - **Response**: `200 OK` with the refreshed `PluginSummary`. 1122 1122 - 1123 1123 - ### Check for plugin updates 1124 1124 - 1125 1125 - ``` 1126 1126 - POST /admin/plugins/{id}/check-update 1127 1127 - ``` 1128 1128 - 1129 1129 - Requires `plugins:create`. Forces a cache refresh for one plugin from the official registry, then returns the updated `PluginSummary` with `update_available`, `latest_version`, and `pending_releases` reflecting the latest catalog state. 1130 1130 - 1131 1131 - **Response**: `200 OK` with a `PluginSummary`. 1132 1132 - 1133 1133 - ### Get plugin secrets 1134 1134 - 1135 1135 - ``` 1136 1136 - GET /admin/plugins/{id}/secrets 1137 1137 - ``` 1138 1138 - 1139 1139 - Requires `plugins:read`. Returns the plugin's configured secrets with values masked (last 4 characters shown for values longer than 8 characters, otherwise fully masked). Requires `TOKEN_ENCRYPTION_KEY` to be configured. 1140 1140 - 1141 1141 - **Response**: `200 OK` 1142 1142 - 1143 1143 - ```json 1144 1144 - { 1145 1145 - "plugin_id": "steam", 1146 1146 - "secrets": { 1147 1147 - "PLUGIN_STEAM_API_KEY": "********ABCD" 1148 1148 - } 1149 1149 - } 1150 1150 - ``` 1151 1151 - 1152 1152 - ### Update plugin secrets 1153 1153 - 1154 1154 - ``` 1155 1155 - PUT /admin/plugins/{id}/secrets 1156 1156 - ``` 1157 1157 - 1158 1158 - Requires `plugins:create`. Encrypts the provided secret values with `TOKEN_ENCRYPTION_KEY` (AES-256-GCM) and upserts them into `plugin_configs`. 1159 1159 - 1160 1160 - ```sh 1161 1161 - curl -X PUT http://localhost:3000/admin/plugins/steam/secrets \ 1162 1162 - -H "$AUTH" \ 1163 1163 - -H "Content-Type: application/json" \ 1164 1164 - -d '{ 1165 1165 - "secrets": { 1166 1166 - "PLUGIN_STEAM_API_KEY": "your-new-api-key" 1167 1167 - } 1168 1168 - }' 1169 1169 - ``` 1170 1170 - 1171 1171 - Special handling: 1172 1172 - 1173 1173 - - Values starting with `********` are treated as masked placeholders and the existing encrypted value is preserved (so you can `GET` then `PUT` without re-typing every secret). 1174 1174 - - Empty string values are not stored — use them to clear a secret. 1175 1175 - 1176 1176 - **Response**: `204 No Content` 42 42 + | Group | Description | 43 43 + | ----- | ----------- | 44 44 + | [Lexicons](admin/lexicons.md) | Upload, list, get, and delete lexicons and network lexicons | 45 45 + | [Stats](admin/stats.md) | Record counts by collection | 46 46 + | [Backfill](admin/backfill.md) | Create and monitor historical backfill jobs | 47 47 + | [Event Logs](admin/events.md) | Query the audit trail of system events | 48 48 + | [API Keys](admin/api-keys.md) | Create, list, and revoke API keys | 49 49 + | [Users](admin/users.md) | Create, list, update, and delete admin users | 50 50 + | [Labelers](admin/labelers.md) | Manage external labeler subscriptions | 51 51 + | [Instance Settings](admin/settings.md) | Configure app name, logo, and policy URLs | 52 52 + | [Domains](admin/domains.md) | Manage domains and their OAuth client identities | 53 53 + | [Script Variables](admin/script-variables.md) | Encrypted key/value pairs for Lua scripts | 54 54 + | [API Clients](admin/api-clients.md) | Register and manage third-party XRPC clients | 55 55 + | [Plugins](admin/plugins.md) | Install, configure, and manage WASM plugins | 1177 56 1178 57 ## Permissions 1179 58 1180 59 Each admin API endpoint requires a specific permission. See the [Permissions guide](../guides/permissions.md) for the full list of permissions and templates. 1181 60 1182 1182 - | Endpoint | Required Permission | 1183 1183 - | ------------------------------------- | ---------------------------- | 1184 1184 - | `POST /admin/lexicons` | `lexicons:create` | 1185 1185 - | `GET /admin/lexicons` | `lexicons:read` | 1186 1186 - | `GET /admin/lexicons/{id}` | `lexicons:read` | 1187 1187 - | `DELETE /admin/lexicons/{id}` | `lexicons:delete` | 1188 1188 - | `POST /admin/network-lexicons` | `lexicons:create` | 1189 1189 - | `GET /admin/network-lexicons` | `lexicons:read` | 1190 1190 - | `DELETE /admin/network-lexicons/{id}` | `lexicons:delete` | 1191 1191 - | `GET /admin/stats` | `stats:read` | 1192 1192 - | `POST /admin/backfill` | `backfill:create` | 1193 1193 - | `GET /admin/backfill/status` | `backfill:read` | 1194 1194 - | `GET /admin/events` | `events:read` | 1195 1195 - | `POST /admin/api-keys` | `api-keys:create` | 1196 1196 - | `GET /admin/api-keys` | `api-keys:read` | 1197 1197 - | `DELETE /admin/api-keys/{id}` | `api-keys:delete` | 1198 1198 - | `POST /admin/users` | `users:create` | 1199 1199 - | `GET /admin/users` | `users:read` | 1200 1200 - | `GET /admin/users/{id}` | `users:read` | 1201 1201 - | `PATCH /admin/users/{id}/permissions`| `users:update` | 1202 1202 - | `DELETE /admin/users/{id}` | `users:delete` | 1203 1203 - | `POST /admin/users/transfer-super` | Super user only | 1204 1204 - | `GET /admin/script-variables` | `script-variables:read` | 1205 1205 - | `POST /admin/script-variables` | `script-variables:create` | 1206 1206 - | `DELETE /admin/script-variables/{key}`| `script-variables:delete` | 1207 1207 - | `POST /admin/labelers` | `labelers:create` | 1208 1208 - | `GET /admin/labelers` | `labelers:read` | 1209 1209 - | `PATCH /admin/labelers/{did}` | `labelers:create` | 1210 1210 - | `DELETE /admin/labelers/{did}` | `labelers:delete` | 1211 1211 - | `GET /admin/settings` | `settings:manage` | 1212 1212 - | `PUT /admin/settings/{key}` | `settings:manage` | 1213 1213 - | `DELETE /admin/settings/{key}` | `settings:manage` | 1214 1214 - | `PUT /admin/settings/logo` | `settings:manage` | 1215 1215 - | `DELETE /admin/settings/logo` | `settings:manage` | 1216 1216 - | `GET /admin/plugins` | `plugins:read` | 1217 1217 - | `POST /admin/plugins` | `plugins:create` | 1218 1218 - | `POST /admin/plugins/preview` | `plugins:read` | 1219 1219 - | `GET /admin/plugins/official` | `plugins:read` | 1220 1220 - | `DELETE /admin/plugins/{id}` | `plugins:delete` | 1221 1221 - | `POST /admin/plugins/{id}/reload` | `plugins:create` | 1222 1222 - | `POST /admin/plugins/{id}/check-update` | `plugins:read` | 1223 1223 - | `GET /admin/plugins/{id}/secrets` | `plugins:read` | 1224 1224 - | `PUT /admin/plugins/{id}/secrets` | `plugins:create` | 1225 1225 - | `GET /admin/domains` | `settings:manage` | 1226 1226 - | `POST /admin/domains` | `settings:manage` | 1227 1227 - | `DELETE /admin/domains/{id}` | `settings:manage` | 1228 1228 - | `POST /admin/domains/{id}/primary` | `settings:manage` | 1229 1229 - | `GET /admin/api-clients` | `api-clients:view` | 1230 1230 - | `POST /admin/api-clients` | `api-clients:create` | 1231 1231 - | `GET /admin/api-clients/{id}` | `api-clients:view` | 1232 1232 - | `PUT /admin/api-clients/{id}` | `api-clients:edit` | 1233 1233 - | `DELETE /admin/api-clients/{id}` | `api-clients:delete` | 61 61 + | Endpoint | Required Permission | 62 62 + | ---------------------------------------- | -------------------------- | 63 63 + | `POST /admin/lexicons` | `lexicons:create` | 64 64 + | `GET /admin/lexicons` | `lexicons:read` | 65 65 + | `GET /admin/lexicons/{id}` | `lexicons:read` | 66 66 + | `DELETE /admin/lexicons/{id}` | `lexicons:delete` | 67 67 + | `POST /admin/network-lexicons` | `lexicons:create` | 68 68 + | `GET /admin/network-lexicons` | `lexicons:read` | 69 69 + | `DELETE /admin/network-lexicons/{id}` | `lexicons:delete` | 70 70 + | `GET /admin/stats` | `stats:read` | 71 71 + | `POST /admin/backfill` | `backfill:create` | 72 72 + | `GET /admin/backfill/status` | `backfill:read` | 73 73 + | `GET /admin/events` | `events:read` | 74 74 + | `POST /admin/api-keys` | `api-keys:create` | 75 75 + | `GET /admin/api-keys` | `api-keys:read` | 76 76 + | `DELETE /admin/api-keys/{id}` | `api-keys:delete` | 77 77 + | `POST /admin/users` | `users:create` | 78 78 + | `GET /admin/users` | `users:read` | 79 79 + | `GET /admin/users/{id}` | `users:read` | 80 80 + | `PATCH /admin/users/{id}/permissions` | `users:update` | 81 81 + | `DELETE /admin/users/{id}` | `users:delete` | 82 82 + | `POST /admin/users/transfer-super` | Super user only | 83 83 + | `GET /admin/script-variables` | `script-variables:read` | 84 84 + | `POST /admin/script-variables` | `script-variables:create` | 85 85 + | `DELETE /admin/script-variables/{key}` | `script-variables:delete` | 86 86 + | `POST /admin/labelers` | `labelers:create` | 87 87 + | `GET /admin/labelers` | `labelers:read` | 88 88 + | `PATCH /admin/labelers/{did}` | `labelers:create` | 89 89 + | `DELETE /admin/labelers/{did}` | `labelers:delete` | 90 90 + | `GET /admin/settings` | `settings:manage` | 91 91 + | `PUT /admin/settings/{key}` | `settings:manage` | 92 92 + | `DELETE /admin/settings/{key}` | `settings:manage` | 93 93 + | `PUT /admin/settings/logo` | `settings:manage` | 94 94 + | `DELETE /admin/settings/logo` | `settings:manage` | 95 95 + | `GET /admin/plugins` | `plugins:read` | 96 96 + | `POST /admin/plugins` | `plugins:create` | 97 97 + | `POST /admin/plugins/preview` | `plugins:read` | 98 98 + | `GET /admin/plugins/official` | `plugins:read` | 99 99 + | `DELETE /admin/plugins/{id}` | `plugins:delete` | 100 100 + | `POST /admin/plugins/{id}/reload` | `plugins:create` | 101 101 + | `POST /admin/plugins/{id}/check-update` | `plugins:read` | 102 102 + | `GET /admin/plugins/{id}/secrets` | `plugins:read` | 103 103 + | `PUT /admin/plugins/{id}/secrets` | `plugins:create` | 104 104 + | `GET /admin/domains` | `settings:manage` | 105 105 + | `POST /admin/domains` | `settings:manage` | 106 106 + | `DELETE /admin/domains/{id}` | `settings:manage` | 107 107 + | `POST /admin/domains/{id}/primary` | `settings:manage` | 108 108 + | `GET /admin/api-clients` | `api-clients:view` | 109 109 + | `POST /admin/api-clients` | `api-clients:create` | 110 110 + | `GET /admin/api-clients/{id}` | `api-clients:view` | 111 111 + | `PUT /admin/api-clients/{id}` | `api-clients:edit` | 112 112 + | `DELETE /admin/api-clients/{id}` | `api-clients:delete` |

+131

packages/docs/docs/reference/admin/api-clients.md

reviewed

··· 1 1 + # Admin API: API Clients 2 2 + 3 3 + API clients represent third-party applications that call HappyView's XRPC endpoints. **Every XRPC request** — including unauthenticated queries — must identify itself with a registered client via the `X-Client-Key` header (or `client_key` query param). The client key is HappyView's rate-limit bucket and caller identity; a request without one gets `401 Unauthorized`. 4 4 + 5 5 + Each client has an `hvc_`-prefixed client key and an `hvs_`-prefixed client secret. The secret is only returned once (at creation) and is sha256-hashed in the database. Server-to-server callers pass the secret as `X-Client-Secret`; browser callers rely on the `Origin` header matching the client's registered `client_uri`. Both checks currently log warnings on mismatch rather than rejecting the request, but the rate-limit bucket is applied either way. See [Authentication — XRPC](../../getting-started/authentication.md#xrpc-api-client-identification) for the client-side view, and the [API Keys guide](../../guides/api-keys.md) for how admin API keys differ from API clients. 6 6 + 7 7 + ```sh 8 8 + # All examples assume $TOKEN is an API key (hv_...) 9 9 + AUTH="Authorization: Bearer $TOKEN" 10 10 + ``` 11 11 + 12 12 + ## List API clients 13 13 + 14 14 + ``` 15 15 + GET /admin/api-clients 16 16 + ``` 17 17 + 18 18 + Requires `api-clients:view`. Returns clients ordered by `created_at` descending. Secrets are never returned. 19 19 + 20 20 + ```sh 21 21 + curl http://localhost:3000/admin/api-clients -H "$AUTH" 22 22 + ``` 23 23 + 24 24 + **Response**: `200 OK` 25 25 + 26 26 + ```json 27 27 + [ 28 28 + { 29 29 + "id": "01J9...", 30 30 + "client_key": "hvc_a1b2c3...", 31 31 + "name": "My Game Client", 32 32 + "client_id_url": "https://example.com/client-metadata.json", 33 33 + "client_uri": "https://example.com", 34 34 + "redirect_uris": ["https://example.com/callback"], 35 35 + "scopes": "atproto", 36 36 + "rate_limit_capacity": 200, 37 37 + "rate_limit_refill_rate": 5.0, 38 38 + "is_active": true, 39 39 + "created_by": "did:plc:...", 40 40 + "created_at": "2026-04-13T12:00:00Z", 41 41 + "updated_at": "2026-04-13T12:00:00Z" 42 42 + } 43 43 + ] 44 44 + ``` 45 45 + 46 46 + ## Create an API client 47 47 + 48 48 + ``` 49 49 + POST /admin/api-clients 50 50 + ``` 51 51 + 52 52 + Requires `api-clients:create`. Generates a fresh `client_key` and `client_secret`. **The secret is only returned in this response** — store it immediately. 53 53 + 54 54 + ```sh 55 55 + curl -X POST http://localhost:3000/admin/api-clients \ 56 56 + -H "$AUTH" \ 57 57 + -H "Content-Type: application/json" \ 58 58 + -d '{ 59 59 + "name": "My Game Client", 60 60 + "client_id_url": "https://example.com/client-metadata.json", 61 61 + "client_uri": "https://example.com", 62 62 + "redirect_uris": ["https://example.com/callback"], 63 63 + "scopes": "atproto", 64 64 + "rate_limit_capacity": 200, 65 65 + "rate_limit_refill_rate": 5.0 66 66 + }' 67 67 + ``` 68 68 + 69 69 + | Field | Type | Required | Description | 70 70 + | ------------------------ | -------- | -------- | -------------------------------------------------------------------------------------- | 71 71 + | `name` | string | yes | Human-readable display name | 72 72 + | `client_id_url` | string | yes | URL to the client's published OAuth client metadata document | 73 73 + | `client_uri` | string | yes | The client's home/landing URL | 74 74 + | `redirect_uris` | string[] | yes | Allowed OAuth redirect URIs | 75 75 + | `scopes` | string | no | Space-separated OAuth scopes (default `"atproto"`) | 76 76 + | `rate_limit_capacity` | integer | no | Per-client token bucket capacity. Falls back to `DEFAULT_RATE_LIMIT_CAPACITY` if unset | 77 77 + | `rate_limit_refill_rate` | number | no | Tokens added per second. Falls back to `DEFAULT_RATE_LIMIT_REFILL_RATE` if unset | 78 78 + 79 79 + **Response**: `201 Created` 80 80 + 81 81 + ```json 82 82 + { 83 83 + "id": "01J9...", 84 84 + "client_key": "hvc_a1b2c3...", 85 85 + "client_secret": "hvs_d4e5f6...", 86 86 + "name": "My Game Client", 87 87 + "client_id_url": "https://example.com/client-metadata.json" 88 88 + } 89 89 + ``` 90 90 + 91 91 + The new client is immediately registered with the OAuth registry and rate limiter, so it can authenticate without restarting HappyView. 92 92 + 93 93 + ## Get an API client 94 94 + 95 95 + ``` 96 96 + GET /admin/api-clients/{id} 97 97 + ``` 98 98 + 99 99 + Requires `api-clients:view`. Returns the same shape as the list endpoint, or `404 Not Found`. 100 100 + 101 101 + ## Update an API client 102 102 + 103 103 + ``` 104 104 + PUT /admin/api-clients/{id} 105 105 + ``` 106 106 + 107 107 + Requires `api-clients:edit`. All fields are optional — only provided fields are changed. Updating either rate-limit field re-registers the client with the rate limiter using the new values. 108 108 + 109 109 + | Field | Type | Description | 110 110 + | ------------------------ | -------- | ---------------------------------------------------------------------- | 111 111 + | `name` | string | New display name | 112 112 + | `client_uri` | string | New home URL | 113 113 + | `redirect_uris` | string[] | Replace the allowed redirect URIs | 114 114 + | `scopes` | string | Replace the OAuth scopes | 115 115 + | `rate_limit_capacity` | integer | New bucket capacity. Pass `null` to clear the override | 116 116 + | `rate_limit_refill_rate` | number | New refill rate. Pass `null` to clear the override | 117 117 + | `is_active` | boolean | Disable (`false`) or re-enable (`true`) the client without deleting it | 118 118 + 119 119 + **Response**: `204 No Content` 120 120 + 121 121 + The OAuth registry is updated in place. The `client_id_url` is immutable — to change it, delete and recreate the client. 122 122 + 123 123 + ## Delete an API client 124 124 + 125 125 + ``` 126 126 + DELETE /admin/api-clients/{id} 127 127 + ``` 128 128 + 129 129 + Requires `api-clients:delete`. Removes the client from the OAuth registry, the rate limiter, and the client identity store. 130 130 + 131 131 + **Response**: `204 No Content`

+92

packages/docs/docs/reference/admin/api-keys.md

reviewed

··· 1 1 + # Admin API: API Keys 2 2 + 3 3 + Manage API keys for programmatic access. See the [API Keys guide](../../guides/api-keys.md) for usage details. 4 4 + 5 5 + ```sh 6 6 + # All examples assume $TOKEN is an API key (hv_...) 7 7 + AUTH="Authorization: Bearer $TOKEN" 8 8 + ``` 9 9 + 10 10 + ## Create an API key 11 11 + 12 12 + ``` 13 13 + POST /admin/api-keys 14 14 + ``` 15 15 + 16 16 + Requires `api-keys:create` permission. 17 17 + 18 18 + ```sh 19 19 + curl -X POST http://localhost:3000/admin/api-keys \ 20 20 + -H "$AUTH" \ 21 21 + -H "Content-Type: application/json" \ 22 22 + -d '{ 23 23 + "name": "CI Deploy", 24 24 + "permissions": ["lexicons:read", "lexicons:create", "backfill:create"] 25 25 + }' 26 26 + ``` 27 27 + 28 28 + | Field | Type | Required | Description | 29 29 + | ------------- | -------- | -------- | ------------------------------------------------------------------------------------- | 30 30 + | `name` | string | yes | A label to identify this key's usage | 31 31 + | `permissions` | string[] | yes | Permissions to grant the key (must be a subset of the creating user's own permissions) | 32 32 + 33 33 + **Response**: `201 Created` 34 34 + 35 35 + ```json 36 36 + { 37 37 + "id": "550e8400-e29b-41d4-a716-446655440000", 38 38 + "name": "CI Deploy", 39 39 + "key": "hv_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", 40 40 + "key_prefix": "hv_a1b2c3d4", 41 41 + "permissions": ["lexicons:read", "lexicons:create", "backfill:create"] 42 42 + } 43 43 + ``` 44 44 + 45 45 + The `key` field contains the full API key. It is only returned in this response — store it securely. The key's effective permissions are the **intersection** of the permissions specified here and the creating user's permissions at the time of each request. 46 46 + 47 47 + ## List API keys 48 48 + 49 49 + ``` 50 50 + GET /admin/api-keys 51 51 + ``` 52 52 + 53 53 + Requires `api-keys:read` permission. 54 54 + 55 55 + ```sh 56 56 + curl http://localhost:3000/admin/api-keys -H "$AUTH" 57 57 + ``` 58 58 + 59 59 + **Response**: `200 OK` 60 60 + 61 61 + ```json 62 62 + [ 63 63 + { 64 64 + "id": "550e8400-e29b-41d4-a716-446655440000", 65 65 + "name": "CI Deploy", 66 66 + "key_prefix": "hv_a1b2c3d4", 67 67 + "permissions": ["lexicons:read", "lexicons:create", "backfill:create"], 68 68 + "created_at": "2026-03-01T00:00:00Z", 69 69 + "last_used_at": "2026-03-06T12:00:00Z", 70 70 + "revoked_at": null 71 71 + } 72 72 + ] 73 73 + ``` 74 74 + 75 75 + Only returns keys belonging to the authenticated user. The full key is never included — only the prefix. 76 76 + 77 77 + ## Revoke an API key 78 78 + 79 79 + ``` 80 80 + DELETE /admin/api-keys/{id} 81 81 + ``` 82 82 + 83 83 + Requires `api-keys:delete` permission. 84 84 + 85 85 + ```sh 86 86 + curl -X DELETE http://localhost:3000/admin/api-keys/550e8400-e29b-41d4-a716-446655440000 \ 87 87 + -H "$AUTH" 88 88 + ``` 89 89 + 90 90 + Sets `revoked_at` on the key. The key remains in the database for audit purposes but can no longer authenticate. 91 91 + 92 92 + **Response**: `204 No Content`

+65

packages/docs/docs/reference/admin/backfill.md

reviewed

··· 1 1 + # Admin API: Backfill 2 2 + 3 3 + Create and monitor historical backfill jobs. See the [Backfill guide](../../guides/backfill.md) for background. 4 4 + 5 5 + ```sh 6 6 + # All examples assume $TOKEN is an API key (hv_...) 7 7 + AUTH="Authorization: Bearer $TOKEN" 8 8 + ``` 9 9 + 10 10 + ## Create a backfill job 11 11 + 12 12 + ``` 13 13 + POST /admin/backfill 14 14 + ``` 15 15 + 16 16 + ```sh 17 17 + curl -X POST http://localhost:3000/admin/backfill \ 18 18 + -H "$AUTH" \ 19 19 + -H "Content-Type: application/json" \ 20 20 + -d '{ "collection": "xyz.statusphere.status" }' 21 21 + ``` 22 22 + 23 23 + | Field | Type | Required | Description | 24 24 + | ------------ | ------ | -------- | ---------------------------------------------------------- | 25 25 + | `collection` | string | no | Limit to a single collection (backfills all if omitted) | 26 26 + | `did` | string | no | Limit to a single DID (discovers all via relay if omitted) | 27 27 + 28 28 + **Response**: `201 Created` 29 29 + 30 30 + ```json 31 31 + { 32 32 + "id": "550e8400-e29b-41d4-a716-446655440000", 33 33 + "status": "pending" 34 34 + } 35 35 + ``` 36 36 + 37 37 + ## List backfill jobs 38 38 + 39 39 + ``` 40 40 + GET /admin/backfill/status 41 41 + ``` 42 42 + 43 43 + ```sh 44 44 + curl http://localhost:3000/admin/backfill/status -H "$AUTH" 45 45 + ``` 46 46 + 47 47 + **Response**: `200 OK` 48 48 + 49 49 + ```json 50 50 + [ 51 51 + { 52 52 + "id": "550e8400-e29b-41d4-a716-446655440000", 53 53 + "collection": "xyz.statusphere.status", 54 54 + "did": null, 55 55 + "status": "completed", 56 56 + "total_repos": 42, 57 57 + "processed_repos": 42, 58 58 + "total_records": 1000, 59 59 + "error": null, 60 60 + "started_at": "2025-01-01T00:01:00Z", 61 61 + "completed_at": "2025-01-01T00:05:00Z", 62 62 + "created_at": "2025-01-01T00:00:00Z" 63 63 + } 64 64 + ] 65 65 + ```

+99

packages/docs/docs/reference/admin/domains.md

reviewed

··· 1 1 + # Admin API: Domains 2 2 + 3 3 + Manage the domains a HappyView instance serves. Each domain gets its own AT Protocol OAuth client identity. The primary domain is auto-seeded from `PUBLIC_URL` on first boot. All endpoints require the `settings:manage` permission. 4 4 + 5 5 + ```sh 6 6 + # All examples assume $TOKEN is an API key (hv_...) 7 7 + AUTH="Authorization: Bearer $TOKEN" 8 8 + ``` 9 9 + 10 10 + ## List domains 11 11 + 12 12 + ``` 13 13 + GET /admin/domains 14 14 + ``` 15 15 + 16 16 + ```sh 17 17 + curl http://localhost:3000/admin/domains -H "$AUTH" 18 18 + ``` 19 19 + 20 20 + **Response**: `200 OK` 21 21 + 22 22 + ```json 23 23 + [ 24 24 + { 25 25 + "id": "550e8400-e29b-41d4-a716-446655440000", 26 26 + "url": "https://gamesgamesgamesgames.games", 27 27 + "is_primary": true, 28 28 + "created_at": "2026-04-16T00:00:00Z", 29 29 + "updated_at": "2026-04-16T00:00:00Z" 30 30 + } 31 31 + ] 32 32 + ``` 33 33 + 34 34 + ## Add a domain 35 35 + 36 36 + ``` 37 37 + POST /admin/domains 38 38 + ``` 39 39 + 40 40 + ```sh 41 41 + curl -X POST http://localhost:3000/admin/domains \ 42 42 + -H "$AUTH" \ 43 43 + -H "Content-Type: application/json" \ 44 44 + -d '{ "url": "https://api.cartridge.dev" }' 45 45 + ``` 46 46 + 47 47 + | Field | Type | Required | Description | 48 48 + | ----- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------ | 49 49 + | `url` | string | yes | Valid origin (scheme + host, no path or trailing slash). Must be `https` unless `PUBLIC_URL` is a loopback address. | 50 50 + 51 51 + Returns `400 Bad Request` if the URL is invalid or already registered. 52 52 + 53 53 + **Response**: `201 Created` 54 54 + 55 55 + ```json 56 56 + { 57 57 + "id": "550e8400-e29b-41d4-a716-446655440001", 58 58 + "url": "https://api.cartridge.dev", 59 59 + "is_primary": false, 60 60 + "created_at": "2026-04-16T00:00:00Z", 61 61 + "updated_at": "2026-04-16T00:00:00Z" 62 62 + } 63 63 + ``` 64 64 + 65 65 + Side effects: builds an OAuth client for the domain, updates the in-memory domain cache. 66 66 + 67 67 + ## Remove a domain 68 68 + 69 69 + ``` 70 70 + DELETE /admin/domains/{id} 71 71 + ``` 72 72 + 73 73 + ```sh 74 74 + curl -X DELETE http://localhost:3000/admin/domains/550e8400-e29b-41d4-a716-446655440001 \ 75 75 + -H "$AUTH" 76 76 + ``` 77 77 + 78 78 + Returns `400 Bad Request` if the domain is primary — set a different domain as primary first. Returns `404 Not Found` if the domain doesn't exist. 79 79 + 80 80 + **Response**: `204 No Content` 81 81 + 82 82 + Side effects: removes the domain's OAuth client and cache entry. 83 83 + 84 84 + ## Set primary domain 85 85 + 86 86 + ``` 87 87 + POST /admin/domains/{id}/primary 88 88 + ``` 89 89 + 90 90 + ```sh 91 91 + curl -X POST http://localhost:3000/admin/domains/550e8400-e29b-41d4-a716-446655440001/primary \ 92 92 + -H "$AUTH" 93 93 + ``` 94 94 + 95 95 + Sets the target domain as the primary. Unsets the current primary in a single operation. Returns `404 Not Found` if the domain doesn't exist. 96 96 + 97 97 + **Response**: `204 No Content` 98 98 + 99 99 + Side effects: updates the in-memory cache and the OAuth client registry's primary client reference.

+54

packages/docs/docs/reference/admin/events.md

reviewed

··· 1 1 + # Admin API: Event Logs 2 2 + 3 3 + HappyView records an audit trail of system events: lexicon changes, record operations, Lua script executions and errors, user actions, backfill jobs, and Jetstream connectivity. See the [Event Logs guide](../../guides/event-logs.md) for details on event types and retention. 4 4 + 5 5 + ```sh 6 6 + # All examples assume $TOKEN is an API key (hv_...) 7 7 + AUTH="Authorization: Bearer $TOKEN" 8 8 + ``` 9 9 + 10 10 + ## List event logs 11 11 + 12 12 + ``` 13 13 + GET /admin/events 14 14 + ``` 15 15 + 16 16 + ```sh 17 17 + curl "http://localhost:3000/admin/events?severity=error&limit=10" -H "$AUTH" 18 18 + ``` 19 19 + 20 20 + | Param | Type | Required | Description | 21 21 + | ------------ | ------ | -------- | --------------------------------------------------------------------- | 22 22 + | `event_type` | string | no | Filter by exact event type (e.g. `script.error`) | 23 23 + | `category` | string | no | Filter by category prefix (e.g. `lexicon` matches all lexicon events) | 24 24 + | `severity` | string | no | Filter by severity: `info`, `warn`, or `error` | 25 25 + | `subject` | string | no | Filter by subject (lexicon ID, record URI, admin DID, etc.) | 26 26 + | `cursor` | string | no | Pagination cursor (ISO 8601 timestamp from previous response) | 27 27 + | `limit` | number | no | Results per page (default `50`, max `100`) | 28 28 + 29 29 + **Response**: `200 OK` 30 30 + 31 31 + ```json 32 32 + { 33 33 + "events": [ 34 34 + { 35 35 + "id": "550e8400-e29b-41d4-a716-446655440000", 36 36 + "event_type": "script.error", 37 37 + "severity": "error", 38 38 + "actor_did": "did:plc:abc123", 39 39 + "subject": "com.example.feed.like", 40 40 + "detail": { 41 41 + "error": "attempt to index nil value", 42 42 + "script_source": "function handle() ... end", 43 43 + "input": { "status": "hello" }, 44 44 + "caller_did": "did:plc:abc123", 45 45 + "method": "com.example.feed.like" 46 46 + }, 47 47 + "created_at": "2026-03-01T12:00:00Z" 48 48 + } 49 49 + ], 50 50 + "cursor": "2026-03-01T11:59:00Z" 51 51 + } 52 52 + ``` 53 53 + 54 54 + Events are returned in reverse chronological order (newest first). Pass the `cursor` value from the response to fetch the next page.

+99

packages/docs/docs/reference/admin/labelers.md

reviewed

··· 1 1 + # Admin API: Labelers 2 2 + 3 3 + Manage external labeler subscriptions. See the [Labelers guide](../../guides/labelers.md) for background. 4 4 + 5 5 + ```sh 6 6 + # All examples assume $TOKEN is an API key (hv_...) 7 7 + AUTH="Authorization: Bearer $TOKEN" 8 8 + ``` 9 9 + 10 10 + ## Add a labeler 11 11 + 12 12 + ``` 13 13 + POST /admin/labelers 14 14 + ``` 15 15 + 16 16 + Requires `labelers:create` permission. 17 17 + 18 18 + ```sh 19 19 + curl -X POST http://localhost:3000/admin/labelers \ 20 20 + -H "$AUTH" \ 21 21 + -H "Content-Type: application/json" \ 22 22 + -d '{ "did": "did:plc:ar7c4by46qjdydhdevvrndac" }' 23 23 + ``` 24 24 + 25 25 + | Field | Type | Required | Description | 26 26 + | ----- | ------ | -------- | ----------------------------- | 27 27 + | `did` | string | yes | The labeler's AT Protocol DID | 28 28 + 29 29 + **Response**: `201 Created` (empty body) 30 30 + 31 31 + ## List labelers 32 32 + 33 33 + ``` 34 34 + GET /admin/labelers 35 35 + ``` 36 36 + 37 37 + Requires `labelers:read` permission. 38 38 + 39 39 + ```sh 40 40 + curl http://localhost:3000/admin/labelers -H "$AUTH" 41 41 + ``` 42 42 + 43 43 + **Response**: `200 OK` 44 44 + 45 45 + ```json 46 46 + [ 47 47 + { 48 48 + "did": "did:plc:ar7c4by46qjdydhdevvrndac", 49 49 + "status": "active", 50 50 + "cursor": 1234, 51 51 + "created_at": "2026-03-15T00:00:00Z", 52 52 + "updated_at": "2026-03-15T00:00:00Z" 53 53 + } 54 54 + ] 55 55 + ``` 56 56 + 57 57 + | Field | Type | Description | 58 58 + | ------------ | ------------ | -------------------------------------------------- | 59 59 + | `did` | string | The labeler's DID | 60 60 + | `status` | string | `active` or `paused` | 61 61 + | `cursor` | number\|null | Last processed event cursor (null if never synced) | 62 62 + | `created_at` | string | ISO 8601 creation timestamp | 63 63 + | `updated_at` | string | ISO 8601 last-updated timestamp | 64 64 + 65 65 + ## Update a labeler 66 66 + 67 67 + ``` 68 68 + PATCH /admin/labelers/{did} 69 69 + ``` 70 70 + 71 71 + Requires `labelers:create` permission. 72 72 + 73 73 + ```sh 74 74 + curl -X PATCH http://localhost:3000/admin/labelers/did:plc:ar7c4by46qjdydhdevvrndac \ 75 75 + -H "$AUTH" \ 76 76 + -H "Content-Type: application/json" \ 77 77 + -d '{ "status": "paused" }' 78 78 + ``` 79 79 + 80 80 + | Field | Type | Required | Description | 81 81 + | -------- | ------ | -------- | -------------------------------- | 82 82 + | `status` | string | yes | New status: `active` or `paused` | 83 83 + 84 84 + **Response**: `200 OK` 85 85 + 86 86 + ## Delete a labeler 87 87 + 88 88 + ``` 89 89 + DELETE /admin/labelers/{did} 90 90 + ``` 91 91 + 92 92 + Requires `labelers:delete` permission. Removes the subscription and all labels emitted by this labeler. 93 93 + 94 94 + ```sh 95 95 + curl -X DELETE http://localhost:3000/admin/labelers/did:plc:ar7c4by46qjdydhdevvrndac \ 96 96 + -H "$AUTH" 97 97 + ``` 98 98 + 99 99 + **Response**: `204 No Content`

+167

packages/docs/docs/reference/admin/lexicons.md

reviewed

··· 1 1 + # Admin API: Lexicons 2 2 + 3 3 + Manage lexicons and network lexicons. See the [Lexicons guide](../../guides/lexicons.md) for background on how lexicons drive indexing and XRPC routing. 4 4 + 5 5 + ```sh 6 6 + # All examples assume $TOKEN is an API key (hv_...) 7 7 + AUTH="Authorization: Bearer $TOKEN" 8 8 + ``` 9 9 + 10 10 + ## Upload / upsert a lexicon 11 11 + 12 12 + ``` 13 13 + POST /admin/lexicons 14 14 + ``` 15 15 + 16 16 + ```sh 17 17 + curl -X POST http://localhost:3000/admin/lexicons \ 18 18 + -H "$AUTH" \ 19 19 + -H "Content-Type: application/json" \ 20 20 + -d '{ 21 21 + "lexicon_json": { "lexicon": 1, "id": "xyz.statusphere.status", "defs": { "main": { "type": "record", "key": "tid", "record": { "type": "object", "required": ["status", "createdAt"], "properties": { "status": { "type": "string", "maxGraphemes": 1 }, "createdAt": { "type": "string", "format": "datetime" } } } } } }, 22 22 + "backfill": true, 23 23 + "target_collection": null 24 24 + }' 25 25 + ``` 26 26 + 27 27 + | Field | Type | Required | Description | 28 28 + | ------------------- | ------- | -------- | --------------------------------------------------------------------- | 29 29 + | `lexicon_json` | object | yes | Raw lexicon JSON (must have `lexicon: 1` and `id`) | 30 30 + | `backfill` | boolean | no | Whether uploading triggers historical backfill (default `true`) | 31 31 + | `target_collection` | string | no | For query/procedure lexicons, the record collection they operate on | 32 32 + | `script` | string | no | Lua script for query/procedure endpoints | 33 33 + | `index_hook` | string | no | [Index hook](../../guides/index-hooks.md) Lua script for record lexicons | 34 34 + 35 35 + **Response**: `201 Created` (new) or `200 OK` (upsert) 36 36 + 37 37 + ```json 38 38 + { 39 39 + "id": "xyz.statusphere.status", 40 40 + "revision": 1 41 41 + } 42 42 + ``` 43 43 + 44 44 + ## List lexicons 45 45 + 46 46 + ``` 47 47 + GET /admin/lexicons 48 48 + ``` 49 49 + 50 50 + ```sh 51 51 + curl http://localhost:3000/admin/lexicons -H "$AUTH" 52 52 + ``` 53 53 + 54 54 + **Response**: `200 OK` 55 55 + 56 56 + ```json 57 57 + [ 58 58 + { 59 59 + "id": "xyz.statusphere.status", 60 60 + "revision": 1, 61 61 + "lexicon_type": "record", 62 62 + "backfill": true, 63 63 + "created_at": "2025-01-01T00:00:00Z", 64 64 + "updated_at": "2025-01-01T00:00:00Z" 65 65 + } 66 66 + ] 67 67 + ``` 68 68 + 69 69 + ## Get a lexicon 70 70 + 71 71 + ``` 72 72 + GET /admin/lexicons/{id} 73 73 + ``` 74 74 + 75 75 + ```sh 76 76 + curl http://localhost:3000/admin/lexicons/xyz.statusphere.status -H "$AUTH" 77 77 + ``` 78 78 + 79 79 + **Response**: `200 OK` with full lexicon details including raw JSON. 80 80 + 81 81 + ## Delete a lexicon 82 82 + 83 83 + ``` 84 84 + DELETE /admin/lexicons/{id} 85 85 + ``` 86 86 + 87 87 + ```sh 88 88 + curl -X DELETE http://localhost:3000/admin/lexicons/xyz.statusphere.status -H "$AUTH" 89 89 + ``` 90 90 + 91 91 + **Response**: `204 No Content` 92 92 + 93 93 + ## Network Lexicons 94 94 + 95 95 + Network lexicons are fetched from the AT Protocol network via DNS TXT resolution and kept updated via the Jetstream subscription. See [Lexicons - Network lexicons](../../guides/lexicons.md#network-lexicons) for background. 96 96 + 97 97 + ### Add a network lexicon 98 98 + 99 99 + ``` 100 100 + POST /admin/network-lexicons 101 101 + ``` 102 102 + 103 103 + ```sh 104 104 + curl -X POST http://localhost:3000/admin/network-lexicons \ 105 105 + -H "$AUTH" \ 106 106 + -H "Content-Type: application/json" \ 107 107 + -d '{ 108 108 + "nsid": "xyz.statusphere.status", 109 109 + "target_collection": null 110 110 + }' 111 111 + ``` 112 112 + 113 113 + | Field | Type | Required | Description | 114 114 + | ------------------- | ------ | -------- | ------------------------------------------------------------------- | 115 115 + | `nsid` | string | yes | The NSID of the lexicon to watch | 116 116 + | `target_collection` | string | no | For query/procedure lexicons, the record collection they operate on | 117 117 + 118 118 + HappyView resolves the NSID authority via DNS TXT, fetches the lexicon from the authority's PDS, parses it, and stores it. 119 119 + 120 120 + **Response**: `201 Created` 121 121 + 122 122 + ```json 123 123 + { 124 124 + "nsid": "xyz.statusphere.status", 125 125 + "authority_did": "did:plc:authority", 126 126 + "revision": 1 127 127 + } 128 128 + ``` 129 129 + 130 130 + ### List network lexicons 131 131 + 132 132 + ``` 133 133 + GET /admin/network-lexicons 134 134 + ``` 135 135 + 136 136 + ```sh 137 137 + curl http://localhost:3000/admin/network-lexicons -H "$AUTH" 138 138 + ``` 139 139 + 140 140 + **Response**: `200 OK` 141 141 + 142 142 + ```json 143 143 + [ 144 144 + { 145 145 + "nsid": "xyz.statusphere.status", 146 146 + "authority_did": "did:plc:authority", 147 147 + "target_collection": null, 148 148 + "last_fetched_at": "2025-01-01T00:00:00Z", 149 149 + "created_at": "2025-01-01T00:00:00Z" 150 150 + } 151 151 + ] 152 152 + ``` 153 153 + 154 154 + ### Remove a network lexicon 155 155 + 156 156 + ``` 157 157 + DELETE /admin/network-lexicons/{nsid} 158 158 + ``` 159 159 + 160 160 + ```sh 161 161 + curl -X DELETE http://localhost:3000/admin/network-lexicons/xyz.statusphere.status \ 162 162 + -H "$AUTH" 163 163 + ``` 164 164 + 165 165 + Removes the network lexicon tracking and also deletes the lexicon from the `lexicons` table and in-memory registry. 166 166 + 167 167 + **Response**: `204 No Content`

+223

packages/docs/docs/reference/admin/plugins.md

reviewed

··· 1 1 + # Admin API: Plugins 2 2 + 3 3 + Plugins extend HappyView with WebAssembly modules sourced from the [official plugin registry](../../guides/plugins.md) or any URL serving a `manifest.json`. Most endpoints take a plugin manifest URL and load (or reload) the plugin in place — no restart needed. Encrypted plugin secrets require `TOKEN_ENCRYPTION_KEY` to be configured. 4 4 + 5 5 + ```sh 6 6 + # All examples assume $TOKEN is an API key (hv_...) 7 7 + AUTH="Authorization: Bearer $TOKEN" 8 8 + ``` 9 9 + 10 10 + ## List installed plugins 11 11 + 12 12 + ``` 13 13 + GET /admin/plugins 14 14 + ``` 15 15 + 16 16 + Requires `plugins:read`. Returns every loaded plugin with its source, required secrets, configuration status, and any pending updates from the official registry cache. 17 17 + 18 18 + ```sh 19 19 + curl http://localhost:3000/admin/plugins -H "$AUTH" 20 20 + ``` 21 21 + 22 22 + **Response**: `200 OK` 23 23 + 24 24 + ```json 25 25 + { 26 26 + "encryption_configured": true, 27 27 + "plugins": [ 28 28 + { 29 29 + "id": "steam", 30 30 + "name": "Steam", 31 31 + "version": "1.2.0", 32 32 + "source": "url", 33 33 + "url": "https://example.com/plugins/steam/manifest.json", 34 34 + "sha256": null, 35 35 + "enabled": true, 36 36 + "auth_type": "openid", 37 37 + "required_secrets": [ 38 38 + { 39 39 + "key": "PLUGIN_STEAM_API_KEY", 40 40 + "name": "Steam Web API Key", 41 41 + "description": "Get your API key at steamcommunity.com/dev/apikey" 42 42 + } 43 43 + ], 44 44 + "secrets_configured": true, 45 45 + "loaded_at": null, 46 46 + "update_available": false, 47 47 + "latest_version": "1.2.0", 48 48 + "pending_releases": [] 49 49 + } 50 50 + ] 51 51 + } 52 52 + ``` 53 53 + 54 54 + `secrets_configured` is `true` if the plugin has no required secrets, or if a row exists for it in `plugin_configs`. `update_available` and `pending_releases` are populated from the cached official registry — call `POST /admin/plugins/{id}/check-update` to refresh them. 55 55 + 56 56 + ## Preview a plugin before installing 57 57 + 58 58 + ``` 59 59 + POST /admin/plugins/preview 60 60 + ``` 61 61 + 62 62 + Requires `plugins:create`. Fetches and parses a manifest without installing the plugin, so the dashboard can show what it would register. 63 63 + 64 64 + ```sh 65 65 + curl -X POST http://localhost:3000/admin/plugins/preview \ 66 66 + -H "$AUTH" \ 67 67 + -H "Content-Type: application/json" \ 68 68 + -d '{ "url": "https://example.com/plugins/steam/manifest.json" }' 69 69 + ``` 70 70 + 71 71 + **Response**: `200 OK` 72 72 + 73 73 + ```json 74 74 + { 75 75 + "id": "steam", 76 76 + "name": "Steam", 77 77 + "version": "1.2.0", 78 78 + "description": "Import your Steam game library and playtime data.", 79 79 + "icon_url": "https://example.com/steam-icon.png", 80 80 + "auth_type": "openid", 81 81 + "required_secrets": [ 82 82 + { "key": "PLUGIN_STEAM_API_KEY", "name": "Steam Web API Key", "description": "..." } 83 83 + ], 84 84 + "manifest_url": "https://example.com/plugins/steam/manifest.json", 85 85 + "wasm_url": "https://example.com/plugins/steam/steam.wasm" 86 86 + } 87 87 + ``` 88 88 + 89 89 + Returns `400 Bad Request` if the manifest can't be fetched or parsed. 90 90 + 91 91 + ## Install a plugin 92 92 + 93 93 + ``` 94 94 + POST /admin/plugins 95 95 + ``` 96 96 + 97 97 + Requires `plugins:create`. Fetches the manifest, downloads the WASM, registers the plugin, and persists it. 98 98 + 99 99 + ```sh 100 100 + curl -X POST http://localhost:3000/admin/plugins \ 101 101 + -H "$AUTH" \ 102 102 + -H "Content-Type: application/json" \ 103 103 + -d '{ 104 104 + "url": "https://example.com/plugins/steam/manifest.json", 105 105 + "sha256": "abc123..." 106 106 + }' 107 107 + ``` 108 108 + 109 109 + | Field | Type | Required | Description | 110 110 + | -------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- | 111 111 + | `url` | string | yes | URL to the plugin's `manifest.json` | 112 112 + | `sha256` | string | no | Optional sha256 of the WASM binary. If provided, install fails when the downloaded hash mismatches | 113 113 + 114 114 + **Response**: `200 OK` returning the same `PluginSummary` shape as the list endpoint. `secrets_configured` will be `false` if the plugin requires any secrets — call `PUT /admin/plugins/{id}/secrets` to configure them before the plugin can run. 115 115 + 116 116 + ## List official plugins 117 117 + 118 118 + ``` 119 119 + GET /admin/plugins/official 120 120 + ``` 121 121 + 122 122 + Requires `plugins:read`. Returns the cached catalog of plugins from the official registry. The cache is refreshed periodically by the server; use `POST /admin/plugins/{id}/check-update` to force-refresh a single entry. 123 123 + 124 124 + **Response**: `200 OK` 125 125 + 126 126 + ```json 127 127 + { 128 128 + "last_refreshed_at": "2026-04-13T11:00:00Z", 129 129 + "plugins": [ 130 130 + { 131 131 + "id": "steam", 132 132 + "name": "Steam", 133 133 + "description": "Import your Steam game library and playtime data.", 134 134 + "icon_url": "https://example.com/steam-icon.png", 135 135 + "latest_version": "1.2.0", 136 136 + "manifest_url": "https://example.com/plugins/steam/manifest.json" 137 137 + } 138 138 + ] 139 139 + } 140 140 + ``` 141 141 + 142 142 + ## Remove a plugin 143 143 + 144 144 + ``` 145 145 + DELETE /admin/plugins/{id} 146 146 + ``` 147 147 + 148 148 + Requires `plugins:delete`. Unregisters the plugin from the runtime and deletes its row from the `plugins` table. Plugin secrets in `plugin_configs` are not removed automatically — they're available again if you reinstall the same plugin. 149 149 + 150 150 + **Response**: `204 No Content`. Returns `404 Not Found` if no plugin with that id is loaded. 151 151 + 152 152 + ## Reload a plugin 153 153 + 154 154 + ``` 155 155 + POST /admin/plugins/{id}/reload 156 156 + ``` 157 157 + 158 158 + Requires `plugins:create`. Re-fetches the plugin from its current source URL and re-registers it. Useful after publishing a new version of a plugin you host yourself. 159 159 + 160 160 + The body is optional. To point the plugin at a new URL, pass: 161 161 + 162 162 + ```json 163 163 + { "url": "https://example.com/plugins/steam/manifest.json" } 164 164 + ``` 165 165 + 166 166 + When a new URL is provided, the stored `sha256` is cleared (the new version has its own hash). File-based plugins cannot be reloaded via this endpoint and return `400 Bad Request`. 167 167 + 168 168 + **Response**: `200 OK` with the refreshed `PluginSummary`. 169 169 + 170 170 + ## Check for plugin updates 171 171 + 172 172 + ``` 173 173 + POST /admin/plugins/{id}/check-update 174 174 + ``` 175 175 + 176 176 + Requires `plugins:create`. Forces a cache refresh for one plugin from the official registry, then returns the updated `PluginSummary` with `update_available`, `latest_version`, and `pending_releases` reflecting the latest catalog state. 177 177 + 178 178 + **Response**: `200 OK` with a `PluginSummary`. 179 179 + 180 180 + ## Get plugin secrets 181 181 + 182 182 + ``` 183 183 + GET /admin/plugins/{id}/secrets 184 184 + ``` 185 185 + 186 186 + Requires `plugins:read`. Returns the plugin's configured secrets with values masked (last 4 characters shown for values longer than 8 characters, otherwise fully masked). Requires `TOKEN_ENCRYPTION_KEY` to be configured. 187 187 + 188 188 + **Response**: `200 OK` 189 189 + 190 190 + ```json 191 191 + { 192 192 + "plugin_id": "steam", 193 193 + "secrets": { 194 194 + "PLUGIN_STEAM_API_KEY": "********ABCD" 195 195 + } 196 196 + } 197 197 + ``` 198 198 + 199 199 + ## Update plugin secrets 200 200 + 201 201 + ``` 202 202 + PUT /admin/plugins/{id}/secrets 203 203 + ``` 204 204 + 205 205 + Requires `plugins:create`. Encrypts the provided secret values with `TOKEN_ENCRYPTION_KEY` (AES-256-GCM) and upserts them into `plugin_configs`. 206 206 + 207 207 + ```sh 208 208 + curl -X PUT http://localhost:3000/admin/plugins/steam/secrets \ 209 209 + -H "$AUTH" \ 210 210 + -H "Content-Type: application/json" \ 211 211 + -d '{ 212 212 + "secrets": { 213 213 + "PLUGIN_STEAM_API_KEY": "your-new-api-key" 214 214 + } 215 215 + }' 216 216 + ``` 217 217 + 218 218 + Special handling: 219 219 + 220 220 + - Values starting with `********` are treated as masked placeholders and the existing encrypted value is preserved (so you can `GET` then `PUT` without re-typing every secret). 221 221 + - Empty string values are not stored — use them to clear a secret. 222 222 + 223 223 + **Response**: `204 No Content`

+41

packages/docs/docs/reference/admin/script-variables.md

reviewed

··· 1 1 + # Admin API: Script Variables 2 2 + 3 3 + Script variables are encrypted key/value pairs available to Lua scripts via the `vars` global. Use them for secrets like API tokens. 4 4 + 5 5 + ```sh 6 6 + # All examples assume $TOKEN is an API key (hv_...) 7 7 + AUTH="Authorization: Bearer $TOKEN" 8 8 + ``` 9 9 + 10 10 + ## List script variables 11 11 + 12 12 + ``` 13 13 + GET /admin/script-variables 14 14 + ``` 15 15 + 16 16 + Requires `script-variables:read`. Returns a list of variable keys (values are not returned). 17 17 + 18 18 + ## Upsert a script variable 19 19 + 20 20 + ``` 21 21 + POST /admin/script-variables 22 22 + ``` 23 23 + 24 24 + Requires `script-variables:create`. 25 25 + 26 26 + ```sh 27 27 + curl -X POST http://localhost:3000/admin/script-variables \ 28 28 + -H "$AUTH" \ 29 29 + -H "Content-Type: application/json" \ 30 30 + -d '{ "key": "ALGOLIA_API_KEY", "value": "..." }' 31 31 + ``` 32 32 + 33 33 + The value is encrypted at rest using `TOKEN_ENCRYPTION_KEY`. 34 34 + 35 35 + ## Delete a script variable 36 36 + 37 37 + ``` 38 38 + DELETE /admin/script-variables/{key} 39 39 + ``` 40 40 + 41 41 + Requires `script-variables:delete`.

+50

packages/docs/docs/reference/admin/settings.md

reviewed

··· 1 1 + # Admin API: Instance Settings 2 2 + 3 3 + Instance settings are key/value entries used to override environment-variable defaults at runtime (for example, the application name, terms-of-service URL, privacy policy URL, and uploaded logo). Settings stored here take precedence over the corresponding environment variables. All endpoints require the `settings:manage` permission. 4 4 + 5 5 + ```sh 6 6 + # All examples assume $TOKEN is an API key (hv_...) 7 7 + AUTH="Authorization: Bearer $TOKEN" 8 8 + ``` 9 9 + 10 10 + ## List settings 11 11 + 12 12 + ``` 13 13 + GET /admin/settings 14 14 + ``` 15 15 + 16 16 + ```sh 17 17 + curl http://localhost:3000/admin/settings -H "$AUTH" 18 18 + ``` 19 19 + 20 20 + Returns all key/value pairs stored in the `instance_settings` table. 21 21 + 22 22 + ## Upsert a setting 23 23 + 24 24 + ``` 25 25 + PUT /admin/settings/{key} 26 26 + ``` 27 27 + 28 28 + ```sh 29 29 + curl -X PUT http://localhost:3000/admin/settings/app_name \ 30 30 + -H "$AUTH" \ 31 31 + -H "Content-Type: application/json" \ 32 32 + -d '{ "value": "My HappyView" }' 33 33 + ``` 34 34 + 35 35 + ## Delete a setting 36 36 + 37 37 + ``` 38 38 + DELETE /admin/settings/{key} 39 39 + ``` 40 40 + 41 41 + Removes the override; the corresponding environment variable (if any) takes effect again. 42 42 + 43 43 + ## Upload / delete logo 44 44 + 45 45 + ``` 46 46 + PUT /admin/settings/logo 47 47 + DELETE /admin/settings/logo 48 48 + ``` 49 49 + 50 50 + `PUT` accepts a binary image body and stores it as the instance logo (served via the public dashboard). `DELETE` removes the stored logo.

+25

packages/docs/docs/reference/admin/stats.md

reviewed

··· 1 1 + # Admin API: Stats 2 2 + 3 3 + ```sh 4 4 + # All examples assume $TOKEN is an API key (hv_...) 5 5 + AUTH="Authorization: Bearer $TOKEN" 6 6 + ``` 7 7 + 8 8 + ## Record counts 9 9 + 10 10 + ``` 11 11 + GET /admin/stats 12 12 + ``` 13 13 + 14 14 + ```sh 15 15 + curl http://localhost:3000/admin/stats -H "$AUTH" 16 16 + ``` 17 17 + 18 18 + **Response**: `200 OK` 19 19 + 20 20 + ```json 21 21 + { 22 22 + "total_records": 12345, 23 23 + "collections": [{ "collection": "xyz.statusphere.status", "count": 500 }] 24 24 + } 25 25 + ```

+147

packages/docs/docs/reference/admin/users.md

reviewed

··· 1 1 + # Admin API: Users 2 2 + 3 3 + Manage admin users and their permissions. See the [Permissions guide](../../guides/permissions.md) for available permissions and templates. 4 4 + 5 5 + ```sh 6 6 + # All examples assume $TOKEN is an API key (hv_...) 7 7 + AUTH="Authorization: Bearer $TOKEN" 8 8 + ``` 9 9 + 10 10 + ## Create a user 11 11 + 12 12 + ``` 13 13 + POST /admin/users 14 14 + ``` 15 15 + 16 16 + Requires `users:create` permission. You cannot grant permissions you don't have yourself (escalation guard). 17 17 + 18 18 + ```sh 19 19 + curl -X POST http://localhost:3000/admin/users \ 20 20 + -H "$AUTH" \ 21 21 + -H "Content-Type: application/json" \ 22 22 + -d '{ 23 23 + "did": "did:plc:newuser", 24 24 + "template": "operator" 25 25 + }' 26 26 + ``` 27 27 + 28 28 + | Field | Type | Required | Description | 29 29 + | ------------- | -------- | -------- | ---------------------------------------------------------------------------------- | 30 30 + | `did` | string | yes | The AT Protocol DID of the user to add | 31 31 + | `template` | string | no | Permission template: `viewer`, `operator`, `manager`, or `full_access` | 32 32 + | `permissions` | string[] | no | Explicit list of permissions to grant (used instead of or in addition to `template`) | 33 33 + 34 34 + If neither `template` nor `permissions` is provided, the user is created with no permissions. 35 35 + 36 36 + **Response**: `201 Created` 37 37 + 38 38 + ```json 39 39 + { 40 40 + "id": "550e8400-e29b-41d4-a716-446655440000", 41 41 + "did": "did:plc:newuser", 42 42 + "is_super": false, 43 43 + "permissions": ["lexicons:read", "records:read", "script-variables:read", "users:read", "api-keys:read", "api-keys:create", "api-keys:delete", "backfill:read", "backfill:create", "stats:read", "events:read"] 44 44 + } 45 45 + ``` 46 46 + 47 47 + ## List users 48 48 + 49 49 + ``` 50 50 + GET /admin/users 51 51 + ``` 52 52 + 53 53 + Requires `users:read` permission. 54 54 + 55 55 + ```sh 56 56 + curl http://localhost:3000/admin/users -H "$AUTH" 57 57 + ``` 58 58 + 59 59 + **Response**: `200 OK` 60 60 + 61 61 + ```json 62 62 + [ 63 63 + { 64 64 + "id": "550e8400-e29b-41d4-a716-446655440000", 65 65 + "did": "did:plc:admin", 66 66 + "is_super": true, 67 67 + "permissions": ["lexicons:create", "lexicons:read", "lexicons:delete", "records:read", "records:delete", "records:delete-collection", "script-variables:create", "script-variables:read", "script-variables:delete", "users:create", "users:read", "users:update", "users:delete", "api-keys:create", "api-keys:read", "api-keys:delete", "backfill:create", "backfill:read", "stats:read", "events:read"], 68 68 + "created_at": "2025-01-01T00:00:00Z", 69 69 + "last_used_at": "2025-01-02T12:00:00Z" 70 70 + } 71 71 + ] 72 72 + ``` 73 73 + 74 74 + ## Get a user 75 75 + 76 76 + ``` 77 77 + GET /admin/users/{id} 78 78 + ``` 79 79 + 80 80 + Requires `users:read` permission. 81 81 + 82 82 + ```sh 83 83 + curl http://localhost:3000/admin/users/550e8400-e29b-41d4-a716-446655440000 -H "$AUTH" 84 84 + ``` 85 85 + 86 86 + **Response**: `200 OK` with the same shape as a single item from the list response. 87 87 + 88 88 + ## Update user permissions 89 89 + 90 90 + ``` 91 91 + PATCH /admin/users/{id}/permissions 92 92 + ``` 93 93 + 94 94 + Requires `users:update` permission. You cannot grant permissions you don't have yourself, and you cannot modify the super user's permissions. 95 95 + 96 96 + ```sh 97 97 + curl -X PATCH http://localhost:3000/admin/users/550e8400-e29b-41d4-a716-446655440000/permissions \ 98 98 + -H "$AUTH" \ 99 99 + -H "Content-Type: application/json" \ 100 100 + -d '{ 101 101 + "grant": ["lexicons:create", "lexicons:delete"], 102 102 + "revoke": ["records:delete"] 103 103 + }' 104 104 + ``` 105 105 + 106 106 + | Field | Type | Required | Description | 107 107 + | -------- | -------- | -------- | --------------------- | 108 108 + | `grant` | string[] | no | Permissions to add | 109 109 + | `revoke` | string[] | no | Permissions to remove | 110 110 + 111 111 + **Response**: `200 OK` with the updated user object. 112 112 + 113 113 + ## Transfer super user 114 114 + 115 115 + ``` 116 116 + POST /admin/users/transfer-super 117 117 + ``` 118 118 + 119 119 + Only the current super user can call this endpoint. Transfers super user status to another existing user. 120 120 + 121 121 + ```sh 122 122 + curl -X POST http://localhost:3000/admin/users/transfer-super \ 123 123 + -H "$AUTH" \ 124 124 + -H "Content-Type: application/json" \ 125 125 + -d '{ "target_user_id": "550e8400-e29b-41d4-a716-446655440000" }' 126 126 + ``` 127 127 + 128 128 + | Field | Type | Required | Description | 129 129 + | ---------------- | ------ | -------- | ------------------------------------------ | 130 130 + | `target_user_id` | string | yes | The ID of the user to receive super status | 131 131 + 132 132 + **Response**: `200 OK` 133 133 + 134 134 + ## Delete a user 135 135 + 136 136 + ``` 137 137 + DELETE /admin/users/{id} 138 138 + ``` 139 139 + 140 140 + Requires `users:delete` permission. You cannot delete the super user or yourself. 141 141 + 142 142 + ```sh 143 143 + curl -X DELETE http://localhost:3000/admin/users/550e8400-e29b-41d4-a716-446655440000 \ 144 144 + -H "$AUTH" 145 145 + ``` 146 146 + 147 147 + **Response**: `204 No Content`

+108 -99

packages/docs/docs/reference/architecture.md

reviewed

··· 31 31 32 32 Reads flow top-down through the query handler to the database (SQLite by default, or Postgres). Writes flow through the procedure handler to the user's PDS, then HappyView indexes the record locally. Real-time record events stream in via [Jetstream](https://github.com/bluesky-social/jetstream); historical records are backfilled in-process by discovering repos via the relay's `listReposByCollection` and fetching records directly from each PDS. 33 33 34 34 - ## Module overview 35 35 - 36 36 - ``` 37 37 - src/ 38 38 - main.rs Startup: config, DB, migrations, build OAuth client, spawn Jetstream worker, start server 39 39 - lib.rs AppState struct (incl. OAuth client + cookie key), module declarations 40 40 - config.rs Environment variable loading 41 41 - dns.rs DNS TXT resolver for atrium handle resolution 42 42 - error.rs AppError enum (Auth, BadRequest, Forbidden, Internal, NotFound, PdsError) 43 43 - server.rs Axum router: fixed routes + admin nest + auth routes + XRPC catch-all + static files 44 44 - lexicon.rs ParsedLexicon, LexiconRegistry (Arc<RwLock<HashMap>>) 45 45 - profile.rs DID document resolution, PDS discovery, profile fetching 46 46 - jetstream.rs Jetstream WebSocket listener, collection filter sync, cursor persistence 47 47 - resolve.rs NSID authority resolution (DNS TXT → DID → PDS) 48 48 - auth/ 49 49 - mod.rs Re-exports, COOKIE_NAME constant 50 50 - middleware.rs Claims extractor (cookie auth, API key, or service auth JWT) 51 51 - routes.rs OAuth endpoints (/auth/login, /auth/callback, /auth/logout, /auth/me) 52 52 - oauth_store.rs Database-backed session and state stores for atrium-oauth 53 53 - service_auth.rs XRPC service-to-service JWT validation (ES256/ES256K) 54 54 - admin/ 55 55 - mod.rs Admin route definitions 56 56 - auth.rs UserAuth extractor (Claims + DID lookup + permission check + auto-bootstrap) 57 57 - users.rs User CRUD handlers (create, list, get, delete, update permissions, transfer super) 58 58 - permissions.rs Permission enum (20 permissions), templates (Viewer, Operator, Manager, FullAccess) 59 59 - api_keys.rs API key CRUD handlers (create, list, revoke) with scoped permissions 60 60 - events.rs Event log query handler 61 61 - settings.rs Instance settings CRUD handlers (list, upsert, delete, logo upload/serve) 62 62 - script_variables.rs Script variable CRUD handlers (list, upsert, delete) 63 63 - lexicons.rs Lexicon CRUD handlers 64 64 - network_lexicons.rs Network lexicon tracking (add, list, remove) 65 65 - records.rs Record listing handler 66 66 - stats.rs Record count stats 67 67 - backfill.rs Backfill job runner (relay discovery + per-PDS listRecords) 68 68 - types.rs Request/response structs for admin endpoints 69 69 - lua/ 70 70 - mod.rs Re-exports 71 71 - context.rs Lua context globals (method, params, input, caller_did, collection) 72 72 - db_api.rs Lua database API (db.query, db.get, db.count) 73 73 - execute.rs Script execution and sandbox setup 74 74 - record.rs Lua Record API (constructor, save, delete, load) 75 75 - sandbox.rs Restricted Lua environment (removed modules, instruction limit) 76 76 - tid.rs TID generation for Lua scripts 77 77 - repo/ 78 78 - mod.rs Re-exports 79 79 - pds.rs PDS proxy helpers (JSON POST, blob POST, response forwarding via OAuth session) 80 80 - session.rs OAuth session restoration from atrium store 81 81 - upload_blob.rs Blob upload handler 82 82 - xrpc/ 83 83 - mod.rs Re-exports 84 84 - query.rs Dynamic GET handler (Lua script or default: single record + list) 85 85 - procedure.rs Dynamic POST handler (Lua script or default: create vs put) 86 86 - ``` 87 87 - 88 34 ## Request flow 89 35 90 36 ### Reads (queries) 91 37 92 92 - ``` 93 93 - Client GET /xrpc/{method}?params 94 94 - -> xrpc::xrpc_get() 95 95 - -> LexiconRegistry lookup (must be Query type) 96 96 - -> If Lua script attached: execute script (has access to db API) 97 97 - -> Else: default SQL query on records table (collection from target_collection) 98 98 - -> JSON response 38 38 + ```mermaid 39 39 + sequenceDiagram 40 40 + participant C as Client 41 41 + participant X as xrpc_get() 42 42 + participant R as LexiconRegistry 43 43 + participant L as Lua Script 44 44 + participant D as Database 45 45 + 46 46 + C->>X: GET /xrpc/{method}?params 47 47 + X->>R: Lookup (must be Query type) 48 48 + alt Lua script attached 49 49 + R->>L: Execute script 50 50 + L->>D: db.query / db.get / db.raw 51 51 + D-->>L: Results 52 52 + L-->>X: Response table 53 53 + else No script 54 54 + R->>D: Default SQL query (collection from target_collection) 55 55 + D-->>X: Results 56 56 + end 57 57 + X-->>C: JSON response 99 58 ``` 100 59 101 60 ### Writes (procedures) 102 61 103 103 - ``` 104 104 - Client POST /xrpc/{method} + session cookie or Bearer token 105 105 - -> Claims extractor (cookie, API key, or service auth JWT) 106 106 - -> xrpc::xrpc_post() 107 107 - -> LexiconRegistry lookup (must be Procedure type) 108 108 - -> If Lua script attached: execute script (has access to Record API) 109 109 - -> Else: default create/update (auto-detect based on uri field) 110 110 - -> Restore OAuth session from atrium store (by DID) 111 111 - -> atrium handles DPoP proof generation and token refresh 112 112 - -> Proxy to user's PDS (createRecord or putRecord) 113 113 - -> Upsert record locally 114 114 - -> Forward PDS response 62 62 + ```mermaid 63 63 + sequenceDiagram 64 64 + participant C as Client 65 65 + participant A as Claims Extractor 66 66 + participant X as xrpc_post() 67 67 + participant R as LexiconRegistry 68 68 + participant L as Lua Script 69 69 + participant S as OAuth Session 70 70 + participant P as User PDS 71 71 + participant D as Database 72 72 + 73 73 + C->>A: POST /xrpc/{method} + DPoP auth + X-Client-Key 74 74 + A->>X: Validated claims 75 75 + X->>R: Lookup (must be Procedure type) 76 76 + alt Lua script attached 77 77 + R->>L: Execute script (Record API) 78 78 + L->>S: Record:save() 79 79 + else No script 80 80 + R->>S: Default create/update (auto-detect from uri field) 81 81 + end 82 82 + S->>P: Proxy write (createRecord or putRecord) 83 83 + P-->>S: PDS response 84 84 + S->>D: Upsert record locally 85 85 + S-->>C: Forward PDS response 115 86 ``` 116 87 117 88 ### Admin endpoints 118 89 119 119 - ``` 120 120 - Client request + session cookie or Bearer token 121 121 - -> AdminAuth extractor: 122 122 - 1. Claims validation (cookie, API key, or service auth JWT) 123 123 - 2. DID lookup in users table (auto-bootstrap super user if empty) 124 124 - 3. Permission check (403 if missing required permission) 125 125 - -> Admin handler 126 126 - -> JSON response 90 90 + ```mermaid 91 91 + sequenceDiagram 92 92 + participant C as Client 93 93 + participant A as AdminAuth Extractor 94 94 + participant U as Users Table 95 95 + participant H as Admin Handler 96 96 + participant D as Database 97 97 + 98 98 + C->>A: Request + Bearer token 99 99 + A->>A: Validate claims (API key or service auth JWT) 100 100 + A->>U: DID lookup 101 101 + alt Users table empty 102 102 + U-->>A: Auto-bootstrap as super user 103 103 + else User found 104 104 + U-->>A: Load permissions 105 105 + end 106 106 + A->>A: Permission check (403 if missing) 107 107 + A->>H: Authorized request 108 108 + H->>D: Database operation 109 109 + D-->>H: Result 110 110 + H-->>C: JSON response 127 111 ``` 128 112 129 113 ## Data flow 130 114 131 115 ### Real-time indexing 132 116 133 133 - ``` 134 134 - Jetstream WebSocket connection (jetstream::spawn) 135 135 - -> Collection filters built from indexed lexicons and applied to subscription URL 136 136 - -> Reconnects on collection filter changes (lexicon add/remove) 137 137 - -> Record commit events: 138 138 - create/update -> UPSERT into records table 139 139 - delete -> DELETE from records table 140 140 - -> Lexicon schema events (com.atproto.lexicon.schema): 141 141 - -> Update tracked network lexicons in DB and registry 142 142 - -> Cursor persisted to instance_settings for resume on reconnect 117 117 + ```mermaid 118 118 + sequenceDiagram 119 119 + participant J as Jetstream WebSocket 120 120 + participant H as HappyView 121 121 + participant D as Database 122 122 + participant R as LexiconRegistry 123 123 + 124 124 + H->>J: Connect (collection filters from indexed lexicons) 125 125 + loop Stream events 126 126 + J->>H: Record commit event 127 127 + alt create / update 128 128 + H->>D: UPSERT into records table 129 129 + else delete 130 130 + H->>D: DELETE from records table 131 131 + end 132 132 + end 133 133 + J->>H: Lexicon schema event (com.atproto.lexicon.schema) 134 134 + H->>D: Update tracked network lexicons 135 135 + H->>R: Update in-memory registry 136 136 + Note over H,D: Cursor persisted to instance_settings for resume on reconnect 137 137 + Note over H,J: Reconnects on collection filter changes (lexicon add/remove) 143 138 ``` 144 139 145 140 ### Backfill 146 141 147 147 - ``` 148 148 - POST /admin/backfill 149 149 - -> Create backfill_jobs record (status = running) 150 150 - -> Relay listReposByCollection -> list of DIDs (paginated) 151 151 - -> For each DID: resolve PDS via PLC, listRecords from that PDS (paginated) 152 152 - -> UPSERT each record into records table 153 153 - -> Update processed_repos / total_records counters 154 154 - -> Mark job as completed (or failed with error message) 142 142 + ```mermaid 143 143 + sequenceDiagram 144 144 + participant A as Admin 145 145 + participant H as HappyView 146 146 + participant D as Database 147 147 + participant Relay as Relay 148 148 + participant PLC as PLC Directory 149 149 + participant PDS as User PDS 150 150 + 151 151 + A->>H: POST /admin/backfill 152 152 + H->>D: Create backfill_jobs record (status = running) 153 153 + H->>Relay: listReposByCollection (paginated) 154 154 + Relay-->>H: List of DIDs 155 155 + loop For each DID 156 156 + H->>PLC: Resolve DID document 157 157 + PLC-->>H: PDS endpoint 158 158 + H->>PDS: listRecords (paginated) 159 159 + PDS-->>H: Records 160 160 + H->>D: UPSERT each record 161 161 + H->>D: Update processed_repos / total_records 162 162 + end 163 163 + H->>D: Mark job completed (or failed) 155 164 ``` 156 165 157 166 ## Database schema

+1 -1

packages/docs/docs/reference/changelog.md

reviewed

··· 22 22 23 23 ## v1.9.0 — Event Logs 24 24 25 25 - - **Event logging** — system-wide audit trail for lexicon changes, record operations, Lua script executions/errors, admin actions, backfill jobs, and firehose connectivity 25 25 + - **Event logging** — system-wide audit trail for lexicon changes, record operations, Lua script executions/errors, admin actions, backfill jobs, and Jetstream connectivity 26 26 - **`GET /admin/events`** — query event logs with filtering by event type, category, severity, and subject, with cursor pagination 27 27 - **Lua error context** — script errors capture full debugging context: error message, script source, input payload, and caller DID 28 28 - **Automatic retention cleanup** — configurable via `EVENT_LOG_RETENTION_DAYS` (default 30 days)

+107

packages/docs/docs/reference/lua/atproto-api.md

reviewed

··· 1 1 + # AT Protocol API 2 2 + 3 3 + The `atproto` table provides AT Protocol utility functions. Available in queries, procedures, and [index hooks](../../guides/index-hooks.md). 4 4 + 5 5 + ## atproto.resolve_service_endpoint 6 6 + 7 7 + ```lua 8 8 + local endpoint = atproto.resolve_service_endpoint(did) 9 9 + ``` 10 10 + 11 11 + Resolves a DID to its AT Protocol service endpoint URL by fetching the DID document. Supports both `did:plc:*` (via the PLC directory) and `did:web:*` (via `.well-known/did.json`). 12 12 + 13 13 + | Parameter | Type | Description | 14 14 + | --------- | ------ | ------------------------ | 15 15 + | `did` | string | The DID to resolve | 16 16 + 17 17 + **Returns:** The service endpoint URL as a string, or `nil` if resolution fails (DID not found, no PDS service in document, network error). 18 18 + 19 19 + ### Examples 20 20 + 21 21 + ```lua 22 22 + -- Resolve a did:plc DID 23 23 + local endpoint = atproto.resolve_service_endpoint("did:plc:abc123") 24 24 + -- endpoint = "https://pds.example.com" 25 25 + 26 26 + -- Resolve a did:web DID 27 27 + local endpoint = atproto.resolve_service_endpoint("did:web:example.com") 28 28 + -- endpoint = "https://example.com" 29 29 + 30 30 + -- Handle resolution failure 31 31 + local endpoint = atproto.resolve_service_endpoint("did:plc:unknown") 32 32 + if not endpoint then 33 33 + return { error = "Could not resolve DID" } 34 34 + end 35 35 + 36 36 + -- Use with HTTP API to call a remote XRPC endpoint 37 37 + local endpoint = atproto.resolve_service_endpoint(did) 38 38 + if endpoint then 39 39 + local resp = http.get(endpoint .. "/xrpc/com.example.method") 40 40 + local data = json.decode(resp.body) 41 41 + end 42 42 + ``` 43 43 + 44 44 + ## atproto.get_labels 45 45 + 46 46 + ```lua 47 47 + local labels = atproto.get_labels(uri) 48 48 + ``` 49 49 + 50 50 + Returns an array of labels for a single AT URI. Merges external labels (from subscribed labelers) with self-labels (from the record's `labels.values[]` field). 51 51 + 52 52 + | Parameter | Type | Description | 53 53 + | --------- | ------ | ------------------------------ | 54 54 + | `uri` | string | AT URI of the record to query | 55 55 + 56 56 + Each label in the array is a table with: 57 57 + 58 58 + | Field | Type | Description | 59 59 + | ----- | ------ | ---------------------------------------- | 60 60 + | `src` | string | DID of the labeler (or record author) | 61 61 + | `uri` | string | AT URI this label applies to | 62 62 + | `val` | string | Label value (e.g. "nsfw", "!hide") | 63 63 + | `cts` | string | Timestamp when the label was created | 64 64 + 65 65 + Expired labels are automatically filtered out. Returns an empty array if no labels exist. 66 66 + 67 67 + ## atproto.get_labels_batch 68 68 + 69 69 + ```lua 70 70 + local labels_by_uri = atproto.get_labels_batch(uris) 71 71 + ``` 72 72 + 73 73 + Batch version of `get_labels`. Takes an array of AT URIs and returns a table keyed by URI, where each value is an array of labels. 74 74 + 75 75 + | Parameter | Type | Description | 76 76 + | --------- | ----- | ------------------------ | 77 77 + | `uris` | table | Array of AT URI strings | 78 78 + 79 79 + **Returns:** A table keyed by URI. Each value is an array of label tables (same shape as `get_labels`). URIs with no labels have an empty array. 80 80 + 81 81 + ### Label examples 82 82 + 83 83 + ```lua 84 84 + -- Get labels for a single game 85 85 + local labels = atproto.get_labels("at://did:plc:abc/games.gamesgamesgamesgames.game/rkey1") 86 86 + for _, label in ipairs(labels) do 87 87 + if label.val == "!hide" then 88 88 + -- skip this game in feed results 89 89 + end 90 90 + end 91 91 + 92 92 + -- Batch fetch labels for multiple games (efficient for feed hydration) 93 93 + local uris = {} 94 94 + for _, item in ipairs(skeleton) do 95 95 + uris[#uris + 1] = item.game 96 96 + end 97 97 + 98 98 + local labels_by_uri = atproto.get_labels_batch(uris) 99 99 + for _, uri in ipairs(uris) do 100 100 + local labels = labels_by_uri[uri] 101 101 + for _, label in ipairs(labels) do 102 102 + if label.val == "!hide" then 103 103 + -- filter out this game 104 104 + end 105 105 + end 106 106 + end 107 107 + ```

+106

packages/docs/docs/reference/lua/database-api.md

reviewed

··· 1 1 + # Database API 2 2 + 3 3 + The `db` table provides access to the database. Available in queries, procedures, and [index hooks](../../guides/index-hooks.md). 4 4 + 5 5 + ## db.query 6 6 + 7 7 + ```lua 8 8 + local result = db.query({ 9 9 + collection = "xyz.statusphere.status", -- required 10 10 + did = "did:plc:abc", -- optional: filter by DID 11 11 + limit = 20, -- optional: max 100, default 20 12 12 + cursor = params.cursor, -- optional: opaque cursor from a previous response 13 13 + sort = "name", -- optional: field to sort by, default "indexed_at" 14 14 + sortDirection = "asc", -- optional: "asc" or "desc", default "desc" 15 15 + }) 16 16 + 17 17 + -- result.records — array of record tables (each includes a "uri" field) 18 18 + -- result.cursor — present when more records exist (opaque string, pass back as-is) 19 19 + ``` 20 20 + 21 21 + The `cursor` is an opaque string returned in a previous response. Pass it through directly — don't parse or modify it. When no `sort` field is specified, `db.query` uses keyset pagination (based on `created_at` and `uri`), which is stable even when records are inserted between pages. When a custom `sort` field is specified, offset-based pagination is used instead. 22 22 + 23 23 + The `sort` field can be a top-level column (`indexed_at`, `did`, `uri`) or any field inside the record's `value` object (e.g. `name`, `createdAt`). Field names must contain only alphanumeric characters and underscores. 24 24 + 25 25 + ## db.get 26 26 + 27 27 + ```lua 28 28 + local record = db.get("at://did:plc:abc/xyz.statusphere.status/abc123") 29 29 + -- Returns the record table or nil 30 30 + -- The returned table includes a "uri" field 31 31 + ``` 32 32 + 33 33 + ## db.search 34 34 + 35 35 + ```lua 36 36 + local result = db.search({ 37 37 + collection = "xyz.statusphere.status", -- required 38 38 + field = "displayName", -- required: record field to search 39 39 + query = "alice", -- required: search term 40 40 + limit = 10, -- optional: max 100, default 10 41 41 + }) 42 42 + 43 43 + -- result.records — array of matching records, ranked by relevance: 44 44 + -- exact match > prefix match > contains match, then alphabetical 45 45 + ``` 46 46 + 47 47 + ## db.backlinks 48 48 + 49 49 + Find records that reference a given AT URI anywhere in their data. Useful for finding likes on a post, replies to a thread, or any record that links to another. 50 50 + 51 51 + ```lua 52 52 + local result = db.backlinks({ 53 53 + collection = "xyz.statusphere.status", -- required 54 54 + uri = "at://did:plc:abc/xyz.statusphere.status/foo", -- required: the URI to find references to 55 55 + did = "did:plc:abc", -- optional: filter by DID 56 56 + limit = 20, -- optional: max 100, default 20 57 57 + cursor = params.cursor, -- optional: opaque cursor from a previous response 58 58 + }) 59 59 + 60 60 + -- result.records — array of records whose data contains the given URI 61 61 + -- result.cursor — present when more records exist (opaque string, pass back as-is) 62 62 + ``` 63 63 + 64 64 + The search checks the full record data, so it works regardless of which field holds the reference (`subject`, `parent`, `reply.root`, etc.). 65 65 + 66 66 + ## db.count 67 67 + 68 68 + ```lua 69 69 + local n = db.count("xyz.statusphere.status") 70 70 + local n = db.count("xyz.statusphere.status", "did:plc:abc") -- filter by DID 71 71 + ``` 72 72 + 73 73 + ## db.raw 74 74 + 75 75 + Run a raw SQL query against the database. Supports `SELECT`, `INSERT`, `UPDATE`, `DELETE`, and `CREATE TABLE` statements. 76 76 + 77 77 + ```lua 78 78 + -- Read query 79 79 + local rows = db.raw( 80 80 + "SELECT uri, did, record FROM records WHERE collection = $1 AND did = $2 LIMIT $3", 81 81 + { "xyz.statusphere.status", "did:plc:abc", 10 } 82 82 + ) 83 83 + 84 84 + for _, row in ipairs(rows) do 85 85 + -- row.uri, row.did, row.record (JSONB is returned as a Lua table) 86 86 + end 87 87 + 88 88 + -- Write query (returns affected rows, if any) 89 89 + db.raw("CREATE TABLE IF NOT EXISTS my_table (id TEXT PRIMARY KEY, value TEXT NOT NULL)") 90 90 + db.raw("INSERT INTO my_table (id, value) VALUES ($1, $2) ON CONFLICT (id) DO UPDATE SET value = $2", 91 91 + { "key1", "hello" }) 92 92 + ``` 93 93 + 94 94 + Parameters are passed as an array and bound to `$1`, `$2`, etc. Supported parameter types: strings, integers, numbers, booleans, and nil. 95 95 + 96 96 + ### Column type mapping 97 97 + 98 98 + | Postgres type | Lua type | 99 99 + | ---------------------- | -------- | 100 100 + | `TEXT`, `VARCHAR` | string | 101 101 + | `INT4`, `INT8` | integer | 102 102 + | `FLOAT4`, `FLOAT8` | number | 103 103 + | `BOOL` | boolean | 104 104 + | `JSON`, `JSONB` | table | 105 105 + | `TIMESTAMPTZ` | string (ISO 8601) | 106 106 + | Other | string (fallback) |

+60

packages/docs/docs/reference/lua/http-api.md

reviewed

··· 1 1 + # HTTP API 2 2 + 3 3 + The `http` table provides async HTTP client functions. Available in queries, procedures, and [index hooks](../../guides/index-hooks.md). 4 4 + 5 5 + ## Methods 6 6 + 7 7 + All methods take a URL and an optional options table, and return a [response table](#response). 8 8 + 9 9 + ```lua 10 10 + http.get(url, opts?) 11 11 + http.post(url, opts?) 12 12 + http.put(url, opts?) 13 13 + http.patch(url, opts?) 14 14 + http.delete(url, opts?) 15 15 + http.head(url, opts?) 16 16 + ``` 17 17 + 18 18 + ## Options 19 19 + 20 20 + The optional second argument is a table with: 21 21 + 22 22 + | Field | Type | Description | 23 23 + | --------- | ------ | ---------------------------------------------- | 24 24 + | `headers` | table | Request headers as key-value string pairs | 25 25 + | `body` | string | Request body (ignored for GET and HEAD) | 26 26 + 27 27 + ## Response 28 28 + 29 29 + Every method returns a table with: 30 30 + 31 31 + | Field | Type | Description | 32 32 + | --------- | ------- | ---------------------------------------------------- | 33 33 + | `status` | integer | HTTP status code | 34 34 + | `body` | string | Response body text (empty string for HEAD) | 35 35 + | `headers` | table | Response headers as key-value pairs (lowercase keys) | 36 36 + 37 37 + ## Examples 38 38 + 39 39 + ```lua 40 40 + -- Simple GET 41 41 + local resp = http.get("https://api.example.com/data") 42 42 + -- resp.status = 200, resp.body = "...", resp.headers["content-type"] = "application/json" 43 43 + 44 44 + -- GET with custom headers 45 45 + local resp = http.get("https://api.example.com/data", { 46 46 + headers = { ["authorization"] = "Bearer token123" } 47 47 + }) 48 48 + 49 49 + -- POST with JSON body 50 50 + local resp = http.post("https://api.example.com/hook", { 51 51 + body = '{"key": "value"}', 52 52 + headers = { ["content-type"] = "application/json" } 53 53 + }) 54 54 + 55 55 + -- PUT, PATCH, DELETE, HEAD follow the same pattern 56 56 + local resp = http.put(url, { body = data, headers = { ... } }) 57 57 + local resp = http.patch(url, { body = data, headers = { ... } }) 58 58 + local resp = http.delete(url, { headers = { ... } }) 59 59 + local resp = http.head(url) 60 60 + ```

+21

packages/docs/docs/reference/lua/json-api.md

reviewed

··· 1 1 + # JSON API 2 2 + 3 3 + The `json` global provides JSON serialization and deserialization. Available in queries, procedures, and [index hooks](../../guides/index-hooks.md). 4 4 + 5 5 + ## json.encode 6 6 + 7 7 + ```lua 8 8 + local str = json.encode({ key = "value", items = { 1, 2, 3 } }) 9 9 + -- '{"key":"value","items":[1,2,3]}' 10 10 + ``` 11 11 + 12 12 + Converts a Lua table to a JSON string. 13 13 + 14 14 + ## json.decode 15 15 + 16 16 + ```lua 17 17 + local tbl = json.decode('{"key": "value"}') 18 18 + -- tbl.key == "value" 19 19 + ``` 20 20 + 21 21 + Parses a JSON string into a Lua table. Returns an error if the input is not valid JSON.

+84

packages/docs/docs/reference/lua/record-api.md

reviewed

··· 1 1 + # Record API 2 2 + 3 3 + The `Record` API is only available in **procedure** scripts. It handles creating, updating, loading, and deleting AT Protocol records. Writes are proxied to the caller's PDS and indexed locally. 4 4 + 5 5 + ## Constructor 6 6 + 7 7 + ```lua 8 8 + local r = Record("xyz.statusphere.status", { status = "\ud83d\ude0a", createdAt = now() }) 9 9 + ``` 10 10 + 11 11 + Creates a new record instance for the given collection. The optional second argument sets initial field values. The record's `_key_type` is automatically set from the lexicon's `key` definition. Default values from the schema are populated for any missing fields. 12 12 + 13 13 + ## Static methods 14 14 + 15 15 + ```lua 16 16 + -- Save multiple records in parallel 17 17 + Record.save_all({ record1, record2, record3 }) 18 18 + 19 19 + -- Load a record from the local database by AT URI 20 20 + local r = Record.load("at://did:plc:abc/xyz.statusphere.status/abc123") 21 21 + -- Returns nil if not found 22 22 + 23 23 + -- Load multiple records in parallel 24 24 + local records = Record.load_all({ uri1, uri2 }) 25 25 + -- Returns nil entries for URIs not found 26 26 + ``` 27 27 + 28 28 + ## Instance methods 29 29 + 30 30 + ```lua 31 31 + -- Save (creates or updates depending on whether _uri is set) 32 32 + r:save() 33 33 + 34 34 + -- Delete from PDS and local database 35 35 + r:delete() 36 36 + 37 37 + -- Set the record key type (tid, any, nsid, or literal:*) 38 38 + r:set_key_type("tid") 39 39 + 40 40 + -- Set a specific record key 41 41 + r:set_rkey("my-key") 42 42 + 43 43 + -- Auto-generate a record key based on _key_type 44 44 + local key = r:generate_rkey() 45 45 + ``` 46 46 + 47 47 + **Key type behavior for `generate_rkey()`:** 48 48 + 49 49 + | Key type | Generated rkey | 50 50 + | --------------- | --------------------------------- | 51 51 + | `tid` | Sortable timestamp-based ID | 52 52 + | `any` | Same as `tid` | 53 53 + | `literal:value` | The literal value after the colon | 54 54 + | `nsid` | Error — use `set_rkey()` instead | 55 55 + 56 56 + ## Instance fields 57 57 + 58 58 + These fields are set automatically and are read-only (writes raise an error): 59 59 + 60 60 + | Field | Type | Description | 61 61 + | ------------- | ------- | ----------------------------------------------------------- | 62 62 + | `_uri` | string? | AT URI — set after `save()`, cleared after `delete()` | 63 63 + | `_cid` | string? | Content hash — set after `save()`, cleared after `delete()` | 64 64 + | `_key_type` | string? | Record key type from the lexicon definition | 65 65 + | `_rkey` | string? | Record key — set via `set_rkey()` or `generate_rkey()` | 66 66 + | `_collection` | string | Collection NSID (always set) | 67 67 + | `_schema` | table? | Schema definition from the lexicon (used for validation) | 68 68 + 69 69 + ## Schema validation 70 70 + 71 71 + When a record has a schema (loaded from the lexicon): 72 72 + 73 73 + - **On save:** required fields are checked, and missing required fields raise an error 74 74 + - **On construction:** default values from schema properties are auto-populated 75 75 + - **On save:** only fields defined in the schema's `properties` are sent to the PDS 76 76 + 77 77 + ## Save behavior 78 78 + 79 79 + `r:save()` auto-detects create vs update: 80 80 + 81 81 + - If `_uri` is nil → calls `createRecord` on the PDS 82 82 + - If `_uri` is set → calls `putRecord` on the PDS 83 83 + 84 84 + After a successful save, `_uri` and `_cid` are updated on the record instance.

+77

packages/docs/docs/reference/lua/standard-libraries.md

reviewed

··· 1 1 + # Standard Libraries 2 2 + 3 3 + The following Lua 5.4 standard library modules and builtins are available in the HappyView sandbox. 4 4 + 5 5 + ## string 6 6 + 7 7 + - [`byte`](https://lua.org/manual/5.4/manual.html#pdf-string.byte) 8 8 + - [`char`](https://lua.org/manual/5.4/manual.html#pdf-string.char) 9 9 + - [`find`](https://lua.org/manual/5.4/manual.html#pdf-string.find) 10 10 + - [`format`](https://lua.org/manual/5.4/manual.html#pdf-string.format) 11 11 + - [`gmatch`](https://lua.org/manual/5.4/manual.html#pdf-string.gmatch) 12 12 + - [`gsub`](https://lua.org/manual/5.4/manual.html#pdf-string.gsub) 13 13 + - [`len`](https://lua.org/manual/5.4/manual.html#pdf-string.len) 14 14 + - [`lower`](https://lua.org/manual/5.4/manual.html#pdf-string.lower) 15 15 + - [`match`](https://lua.org/manual/5.4/manual.html#pdf-string.match) 16 16 + - [`rep`](https://lua.org/manual/5.4/manual.html#pdf-string.rep) 17 17 + - [`reverse`](https://lua.org/manual/5.4/manual.html#pdf-string.reverse) 18 18 + - [`sub`](https://lua.org/manual/5.4/manual.html#pdf-string.sub) 19 19 + - [`upper`](https://lua.org/manual/5.4/manual.html#pdf-string.upper) 20 20 + 21 21 + ## table 22 22 + 23 23 + - [`concat`](https://lua.org/manual/5.4/manual.html#pdf-table.concat) 24 24 + - [`insert`](https://lua.org/manual/5.4/manual.html#pdf-table.insert) 25 25 + - [`remove`](https://lua.org/manual/5.4/manual.html#pdf-table.remove) 26 26 + - [`sort`](https://lua.org/manual/5.4/manual.html#pdf-table.sort) 27 27 + - [`unpack`](https://lua.org/manual/5.4/manual.html#pdf-table.unpack) 28 28 + 29 29 + ## math 30 30 + 31 31 + - [`abs`](https://lua.org/manual/5.4/manual.html#pdf-math.abs) 32 32 + - [`ceil`](https://lua.org/manual/5.4/manual.html#pdf-math.ceil) 33 33 + - [`floor`](https://lua.org/manual/5.4/manual.html#pdf-math.floor) 34 34 + - [`max`](https://lua.org/manual/5.4/manual.html#pdf-math.max) 35 35 + - [`min`](https://lua.org/manual/5.4/manual.html#pdf-math.min) 36 36 + - [`random`](https://lua.org/manual/5.4/manual.html#pdf-math.random) 37 37 + - [`sqrt`](https://lua.org/manual/5.4/manual.html#pdf-math.sqrt) 38 38 + - [`huge`](https://lua.org/manual/5.4/manual.html#pdf-math.huge) 39 39 + - [`pi`](https://lua.org/manual/5.4/manual.html#pdf-math.pi) 40 40 + 41 41 + ## os (safe subset) 42 42 + 43 43 + Only the following safe functions are available from the `os` module: 44 44 + 45 45 + - [`time`](https://lua.org/manual/5.4/manual.html#pdf-os.time) 46 46 + - [`date`](https://lua.org/manual/5.4/manual.html#pdf-os.date) 47 47 + - [`difftime`](https://lua.org/manual/5.4/manual.html#pdf-os.difftime) 48 48 + - [`clock`](https://lua.org/manual/5.4/manual.html#pdf-os.clock) 49 49 + 50 50 + Dangerous functions like `os.execute`, `os.remove`, `os.rename`, and `os.exit` are not available. 51 51 + 52 52 + ## Builtins 53 53 + 54 54 + - [`print`](https://lua.org/manual/5.4/manual.html#pdf-print) 55 55 + - [`tostring`](https://lua.org/manual/5.4/manual.html#pdf-tostring) 56 56 + - [`tonumber`](https://lua.org/manual/5.4/manual.html#pdf-tonumber) 57 57 + - [`type`](https://lua.org/manual/5.4/manual.html#pdf-type) 58 58 + - [`pairs`](https://lua.org/manual/5.4/manual.html#pdf-pairs) 59 59 + - [`ipairs`](https://lua.org/manual/5.4/manual.html#pdf-ipairs) 60 60 + - [`next`](https://lua.org/manual/5.4/manual.html#pdf-next) 61 61 + - [`select`](https://lua.org/manual/5.4/manual.html#pdf-select) 62 62 + - [`unpack`](https://lua.org/manual/5.4/manual.html#pdf-table.unpack) 63 63 + - [`error`](https://lua.org/manual/5.4/manual.html#pdf-error) 64 64 + - [`pcall`](https://lua.org/manual/5.4/manual.html#pdf-pcall) 65 65 + - [`xpcall`](https://lua.org/manual/5.4/manual.html#pdf-xpcall) 66 66 + - [`assert`](https://lua.org/manual/5.4/manual.html#pdf-assert) 67 67 + - [`setmetatable`](https://lua.org/manual/5.4/manual.html#pdf-setmetatable) 68 68 + - [`getmetatable`](https://lua.org/manual/5.4/manual.html#pdf-getmetatable) 69 69 + - [`rawget`](https://lua.org/manual/5.4/manual.html#pdf-rawget) 70 70 + - [`rawset`](https://lua.org/manual/5.4/manual.html#pdf-rawset) 71 71 + - [`rawequal`](https://lua.org/manual/5.4/manual.html#pdf-rawequal) 72 72 + 73 73 + ## Removed modules 74 74 + 75 75 + The following standard Lua modules are **removed** and unavailable in the sandbox: 76 76 + 77 77 + `io`, `debug`, `package`, `require`, `dofile`, `loadfile`, `load`, `collectgarbage`

+2 -2

packages/docs/docs/reference/production-deployment.md

reviewed

··· 4 4 5 5 ## Session secret 6 6 7 7 - Set `SESSION_SECRET` to a strong random value (at least 32 bytes). This signs the session cookies issued during OAuth login; rotating it invalidates every existing session. 7 7 + Set `SESSION_SECRET` to a random string of at least 64 characters. This signs the session cookies issued during OAuth login; rotating it invalidates every existing session. 8 8 9 9 ```sh 10 10 openssl rand -base64 48 ··· 46 46 47 47 HappyView has a per-client token-bucket rate limiter for XRPC endpoints. The defaults (set via `DEFAULT_RATE_LIMIT_CAPACITY` and `DEFAULT_RATE_LIMIT_REFILL_RATE`) apply to any [API client](../guides/api-keys.md) that doesn't have per-client overrides. Raise the defaults cautiously — they exist so one misbehaving integrator can't saturate the server. 48 48 49 49 - Per-client overrides are set at client creation or via `PUT /admin/api-clients/{id}` (see [Admin API — API Clients](admin-api.md#api-clients)). 49 49 + Per-client overrides are set at client creation or via `PUT /admin/api-clients/{id}` (see [Admin API — API Clients](admin/api-clients.md)). 50 50 51 51 ## Logging 52 52

+2 -2

packages/docs/docs/reference/scripts/batch-save.md

reviewed

··· 23 23 24 24 ## How it works 25 25 26 26 - 1. Iterate over `input.items` and create a [`Record`](../../guides/scripting.md#record-api) instance for each item. 27 27 - 2. Call [`Record.save_all()`](../../guides/scripting.md#static-methods) to save all records in parallel, rather than one at a time. 26 26 + 1. Iterate over `input.items` and create a [`Record`](../lua/record-api.md) instance for each item. 27 27 + 2. Call [`Record.save_all()`](../lua/record-api.md#static-methods) to save all records in parallel, rather than one at a time. 28 28 3. Collect the resulting AT URIs and return them. 29 29 30 30 ## Usage

+1 -1

packages/docs/docs/reference/scripts/cascading-delete.md

reviewed

··· 49 49 50 50 1. Load the primary record by URI. Return early if it doesn't exist. 51 51 2. Query for related records, in this example comments by the same user that reference the primary record's URI. 52 52 - 3. Load each related record with [`Record.load`](../../guides/scripting.md#static-methods) to get a deletable `Record` instance. 52 52 + 3. Load each related record with [`Record.load`](../lua/record-api.md#static-methods) to get a deletable `Record` instance. 53 53 4. Delete everything. Each `r:delete()` removes the record from the user's PDS and the local index. 54 54 55 55 ## Usage

+1 -1

packages/docs/docs/reference/scripts/complex-mutations.md

reviewed

··· 56 56 57 57 ## How it works 58 58 59 59 - 1. Load the existing record with [`Record.load`](../../guides/scripting.md#static-methods). This gives you a mutable `Record` instance with all the current field values. 59 59 + 1. Load the existing record with [`Record.load`](../lua/record-api.md#static-methods). This gives you a mutable `Record` instance with all the current field values. 60 60 2. Apply transformations directly on the record's fields: 61 61 - **Increment a counter**: use `or 0` to handle the field being `nil` on first access. 62 62 - **Merge tags**: iterate over `input.tags`, skip duplicates already in `r.tags`, append new ones, then trim the list to 10.

+1 -1

packages/docs/docs/reference/scripts/create-record.md

reviewed

··· 14 14 15 15 ## How it works 16 16 17 17 - 1. Create a new [`Record`](../../guides/scripting.md#record-api) instance from the target collection, populated with the fields from the request body. 17 17 + 1. Create a new [`Record`](../lua/record-api.md) instance from the target collection, populated with the fields from the request body. 18 18 2. Call `r:save()`, which creates the record on the caller's PDS and indexes it locally. 19 19 3. Return the AT URI and CID of the newly created record. 20 20

+4 -4

packages/docs/docs/reference/scripts/expanded-query.md

reviewed

··· 13 13 collection = "xyz.statusphere.status", 14 14 did = params.did, 15 15 limit = limit, 16 16 - offset = tonumber(params.cursor) or 0, 16 16 + cursor = params.cursor, 17 17 }) 18 18 19 19 -- Collect unique DIDs from the statuses ··· 51 51 1. Query statuses from the target collection with pagination, same as a normal list query. 52 52 2. Extract the unique DIDs from the returned status URIs using `string.match`. 53 53 3. Build an AT URI for each DID's `app.bsky.actor.profile/self` record (this is where Bluesky profiles live). 54 54 - 4. Load all profiles in parallel with [`Record.load_all`](../../guides/scripting.md#static-methods). Profiles that aren't indexed locally return `nil` and are skipped. 54 54 + 4. Load all profiles in parallel with [`Record.load_all`](../lua/record-api.md#static-methods). Profiles that aren't indexed locally return `nil` and are skipped. 55 55 5. Return statuses and profiles as separate keys, with the cursor from the status query. 56 56 57 57 ## Usage ··· 59 59 ``` 60 60 GET /xrpc/xyz.statusphere.listStatusesWithProfiles?limit=10 61 61 GET /xrpc/xyz.statusphere.listStatusesWithProfiles?did=did:plc:abc 62 62 - GET /xrpc/xyz.statusphere.listStatusesWithProfiles?cursor=20&limit=20 62 62 + GET /xrpc/xyz.statusphere.listStatusesWithProfiles?cursor=<opaque>&limit=20 63 63 ``` 64 64 65 65 ```json ··· 72 72 { "uri": "at://did:plc:abc/app.bsky.actor.profile/self", "displayName": "Alice", "avatar": "..." }, 73 73 { "uri": "at://did:plc:def/app.bsky.actor.profile/self", "displayName": "Bob", "avatar": "..." } 74 74 ], 75 75 - "cursor": "10" 75 75 + "cursor": "MjAyNi0wMS0wMVQxMjowMDowMFp8YXQ6Ly9kaWQ6..." 76 76 } 77 77 ``` 78 78

+1 -1

packages/docs/docs/reference/scripts/get-record.md

reviewed

··· 22 22 ## How it works 23 23 24 24 1. Check that the `uri` query parameter is present. Return a structured error if missing. 25 25 - 2. Look up the record with [`db.get`](../../guides/scripting.md#dbget), which returns the record table or `nil`. 25 25 + 2. Look up the record with [`db.get`](../lua/database-api.md#dbget), which returns the record table or `nil`. 26 26 3. Return the record wrapped in an object. 27 27 28 28 ## Usage

+3 -3

packages/docs/docs/reference/scripts/list-or-fetch.md

reviewed

··· 18 18 collection = collection, 19 19 did = params.did, 20 20 limit = tonumber(params.limit) or 20, 21 21 - offset = tonumber(params.cursor) or 0, 21 21 + cursor = params.cursor, 22 22 }) 23 23 end 24 24 ``` 25 25 26 26 ## How it works 27 27 28 28 - 1. If a `uri` query parameter is provided, fetch that single record with [`db.get`](../../guides/scripting.md#dbget) and return it. If it doesn't exist, return a structured error (using `error()` would trigger a 500 response). 29 29 - 2. Otherwise, list records from the target collection using [`db.query`](../../guides/scripting.md#dbquery), with optional filtering by `did` and pagination via `limit`/`offset`. Since query parameters arrive as strings, `tonumber()` converts them to numbers. 28 28 + 1. If a `uri` query parameter is provided, fetch that single record with [`db.get`](../lua/database-api.md#dbget) and return it. If it doesn't exist, return a structured error (using `error()` would trigger a 500 response). 29 29 + 2. Otherwise, list records from the target collection using [`db.query`](../lua/database-api.md#dbquery), with optional filtering by `did` and cursor-based pagination. The `cursor` is an opaque string from a previous response — pass it through directly. Since `limit` arrives as a string, `tonumber()` converts it to a number. 30 30 31 31 ## Usage 32 32

+5 -5

packages/docs/docs/reference/scripts/paginated-list.md

reviewed

··· 13 13 collection = collection, 14 14 did = params.did, 15 15 limit = limit, 16 16 - offset = tonumber(params.cursor) or 0, 16 16 + cursor = params.cursor, 17 17 }) 18 18 19 19 return result ··· 23 23 ## How it works 24 24 25 25 1. Parse `limit` from the query string, defaulting to 20 and capping at 100. 26 26 - 2. Call [`db.query`](../../guides/scripting.md#dbquery) with the target collection, optional DID filter, and offset-based pagination. 27 27 - 3. Return the result directly. `db.query` returns `{ records = [...], cursor = "..." }` where `cursor` is present when more records exist. 26 26 + 2. Call [`db.query`](../lua/database-api.md#dbquery) with the target collection, optional DID filter, and cursor for pagination. 27 27 + 3. Return the result directly. `db.query` returns `{ records = [...], cursor = "..." }` where `cursor` is an opaque string present when more records exist. 28 28 29 29 ## Usage 30 30 ··· 32 32 GET /xrpc/xyz.statusphere.listStatuses 33 33 GET /xrpc/xyz.statusphere.listStatuses?limit=50 34 34 GET /xrpc/xyz.statusphere.listStatuses?did=did:plc:abc&limit=10 35 35 - GET /xrpc/xyz.statusphere.listStatuses?cursor=20&limit=20 35 35 + GET /xrpc/xyz.statusphere.listStatuses?cursor=<opaque>&limit=20 36 36 ``` 37 37 38 38 ## Use case 39 39 40 40 - A straightforward list endpoint for feeds, timelines, or browsing records by collection. The `cursor` value returned by `db.query` is an offset. Clients pass it back as the `cursor` parameter to fetch the next page. Since all query parameters arrive as strings, use `tonumber()` to convert `limit` and `cursor` to numbers. 40 40 + A straightforward list endpoint for feeds, timelines, or browsing records by collection. The `cursor` value returned by `db.query` is an opaque string. Clients pass it back as the `cursor` parameter to fetch the next page — don't parse or modify it.

+1 -1

packages/docs/docs/reference/scripts/sidecar-records.md

reviewed

··· 34 34 35 35 1. Generate a single [`TID()`](../../guides/scripting.md#utility-globals) to use as the rkey for both records. 36 36 2. Create a `Record` for each collection and call `r:set_rkey()` with the shared rkey. 37 37 - 3. Save both records in parallel with [`Record.save_all()`](../../guides/scripting.md#static-methods). 37 37 + 3. Save both records in parallel with [`Record.save_all()`](../lua/record-api.md#static-methods). 38 38 4. Return both URIs so the client knows the identity of each record. 39 39 40 40 ## Usage

+2 -2

packages/docs/docs/reference/scripts/update-or-delete.md

reviewed

··· 30 30 31 31 ## How it works 32 32 33 33 - 1. If `input.delete` is truthy and `input.uri` is provided, load the record with [`Record.load`](../../guides/scripting.md#static-methods) and delete it. 34 34 - 2. If only `input.uri` is provided, load the existing record with [`Record.load`](../../guides/scripting.md#static-methods), update its fields, and save it back. Since `_uri` is already set, `r:save()` calls `putRecord` instead of `createRecord`. 33 33 + 1. If `input.delete` is truthy and `input.uri` is provided, load the record with [`Record.load`](../lua/record-api.md#static-methods) and delete it. 34 34 + 2. If only `input.uri` is provided, load the existing record with [`Record.load`](../lua/record-api.md#static-methods), update its fields, and save it back. Since `_uri` is already set, `r:save()` calls `putRecord` instead of `createRecord`. 35 35 3. If neither condition matches, create a new record from the input. 36 36 37 37 ## Usage

+1 -1

packages/docs/docs/reference/scripts/upsert-record.md

reviewed

··· 33 33 ## How it works 34 34 35 35 1. Use the client-provided `input.rkey` if present, otherwise generate a new [`TID()`](../../guides/scripting.md#utility-globals). This means omitting `rkey` always creates, while providing one enables updates. 36 36 - 2. Build the AT URI from the caller's DID, the target collection, and the rkey, then try to load it with [`Record.load`](../../guides/scripting.md#static-methods). 36 36 + 2. Build the AT URI from the caller's DID, the target collection, and the rkey, then try to load it with [`Record.load`](../lua/record-api.md#static-methods). 37 37 3. If the record exists, update its fields and save. Since `_uri` is already set, `r:save()` calls `putRecord`. 38 38 4. If it doesn't exist, create a new record, set the rkey explicitly with `r:set_rkey()`, and save. This calls `createRecord` with the specified rkey. 39 39

+52 -4

packages/docs/docs/reference/troubleshooting.md

reviewed

··· 28 28 29 29 **Causes**: 30 30 31 31 - - No session cookie or `Authorization: Bearer` header is present. 32 32 - - The session cookie has expired or was signed with a different `SESSION_SECRET`. 33 33 - - The API key has been revoked or is invalid. 31 31 + - No `Authorization: DPoP` header or `X-Client-Key` header is present. 32 32 + - The DPoP proof is invalid or expired. 33 33 + - The API client key is not registered or is inactive. 34 34 35 35 ## Admin endpoints return 403 Forbidden 36 36 ··· 86 86 - No record-type lexicon exists for the collection. HappyView only indexes collections that have a corresponding record-type lexicon. 87 87 - The Jetstream subscription hasn't reconnected with the new collection filter after a lexicon change. This should happen automatically. Check server logs for connection errors. 88 88 89 89 + ## Lua script can't find records 90 90 + 91 91 + **Symptom**: `db.query` or `db.get` returns empty results inside a Lua script, even though the admin dashboard shows records exist. 92 92 + 93 93 + **Causes**: 94 94 + 95 95 + - The `collection` global is only set when the lexicon has a `target_collection`. If you're using `db.raw` with a hardcoded collection name, double-check the spelling matches exactly. 96 96 + - `db.get` expects a full AT URI (`at://did:plc:abc/collection/rkey`), not just an rkey. 97 97 + - If querying by DID, make sure you're passing the full DID string including the `did:plc:` or `did:web:` prefix. 98 98 + 99 99 + ## Plugin secrets not working 100 100 + 101 101 + **Symptom**: A plugin fails with authentication errors even though you've configured its secrets. 102 102 + 103 103 + **Causes**: 104 104 + 105 105 + - `TOKEN_ENCRYPTION_KEY` is not set. Plugin secrets are encrypted at rest and cannot be read without this key. See [Plugins - Configuration](../guides/plugins.md#plugin-configuration). 106 106 + - If `TOKEN_ENCRYPTION_KEY` changed since the secrets were saved, the existing encrypted values are unreadable. Re-enter the secrets via the dashboard or `PUT /admin/plugins/{id}/secrets`. 107 107 + - Environment variable secrets (`PLUGIN_<ID>_<KEY>`) are overridden by dashboard-configured secrets. If you've set both, the dashboard values take precedence. 108 108 + 89 109 ## OAuth or login issues 90 110 91 111 HappyView handles AT Protocol OAuth internally via the `atrium-oauth` library. If users can't log in: 92 112 93 113 1. Verify `PUBLIC_URL` is set correctly and the URL is publicly accessible (required for OAuth callbacks). 94 114 2. Check that the user's PDS authorization server is reachable. 95 95 - 3. Verify `SESSION_SECRET` hasn't changed since sessions were created (changing it invalidates all existing session cookies). 115 115 + 3. Verify `SESSION_SECRET` hasn't changed since sessions were created (changing it invalidates all existing dashboard sessions). 96 116 4. Check server logs for OAuth-specific error messages. 97 117 118 118 + ## Third-party app can't authenticate 119 119 + 120 120 + **Symptom**: A third-party app using DPoP authentication gets 401 errors on XRPC endpoints. 121 121 + 122 122 + **Causes**: 123 123 + 124 124 + - The app hasn't registered an API client. Every XRPC request needs an `X-Client-Key` header with a valid `hvc_`-prefixed client key. Register one via **Settings > API Clients** or `POST /admin/api-clients`. 125 125 + - The DPoP proof is malformed or expired. Proofs include a timestamp and are valid for a short window. 126 126 + - The API client has been deactivated (`is_active: false`). Re-enable it via the dashboard or `PUT /admin/api-clients/{id}`. 127 127 + 98 128 ## Database connection errors 99 129 100 130 **Symptom**: HappyView fails to start or returns 500 errors. ··· 106 136 - Postgres version is too old. HappyView requires Postgres 17+. 107 137 108 138 See [Configuration](../getting-started/configuration.md) for environment variable details. 139 139 + 140 140 + ## Switching databases loses data 141 141 + 142 142 + **Symptom**: After changing `DATABASE_URL` from SQLite to Postgres (or vice versa), all records, lexicons, and users are gone. 143 143 + 144 144 + **Explanation**: Each database is independent. Switching `DATABASE_URL` points HappyView at a fresh database. Your old data is still in the previous database file or Postgres instance. 145 145 + 146 146 + **Recovery**: Re-upload your lexicons and run backfills to re-index records from the network. Admin settings, users, and API keys need to be re-created manually. See the [SQLite → Postgres](../guides/sqlite-to-postgres-migration.md) or [Postgres → SQLite](../guides/postgres-to-sqlite-migration.md) migration guides. 147 147 + 148 148 + ## Jetstream disconnects frequently 149 149 + 150 150 + **Symptom**: Server logs show repeated `jetstream.disconnected` / `jetstream.connected` events. 151 151 + 152 152 + **Causes**: 153 153 + 154 154 + - Network instability between HappyView and the Jetstream server. Verify `JETSTREAM_URL` is reachable. 155 155 + - The default Jetstream instance may be under heavy load. Consider pointing `JETSTREAM_URL` at a different instance if available. 156 156 + - HappyView reconnects automatically and resumes from its last cursor, so brief disconnections don't cause data loss. Prolonged outages may require a backfill to catch up on missed records.

+6 -6

packages/docs/docs/reference/xrpc-api.md

reviewed

··· 7 7 ## Auth 8 8 9 9 - **Queries** (`GET /xrpc/{method}`): unauthenticated 10 10 - - **Procedures** (`POST /xrpc/{method}`): require authentication (session cookie, API key, or service auth JWT) 10 10 + - **Procedures** (`POST /xrpc/{method}`): require DPoP authentication (`Authorization: DPoP` + `DPoP` proof header + `X-Client-Key`) 11 11 - **getProfile**: requires auth 12 12 - **uploadBlob**: requires auth 13 13 ··· 101 101 ### List records 102 102 103 103 ``` 104 104 - GET /xrpc/{method}?limit=20&cursor=0&did=optional 104 104 + GET /xrpc/{method}?limit=20&cursor=<opaque>&did=optional 105 105 ``` 106 106 107 107 | Param | Type | Default | Description | 108 108 |-------|------|---------|-------------| 109 109 | `limit` | integer | 20 | Max records to return (max 100) | 110 110 - | `cursor` | string | `0` | Pagination cursor (opaque, pass from previous response) | 110 110 + | `cursor` | string | --- | Opaque pagination cursor from a previous response | 111 111 | `did` | string | --- | Filter records by DID | 112 112 113 113 ```sh ··· 125 125 "createdAt": "2025-01-01T12:00:00Z" 126 126 } 127 127 ], 128 128 - "cursor": "10" 128 128 + "cursor": "MjAyNS0wMS0wMVQxMjowMDowMFp8YXQ6Ly9kaWQ6..." 129 129 } 130 130 ``` 131 131 132 132 - The `cursor` field is present only when more records exist. 132 132 + The `cursor` field is an opaque string present only when more records exist. Pass it back as-is to fetch the next page. 133 133 134 134 ## Dynamic procedure endpoints 135 135 ··· 184 184 | Status | Meaning | Common causes | 185 185 |--------|---------|---------------| 186 186 | `400 Bad Request` | Invalid input | Missing required fields, malformed JSON, invalid AT URI | 187 187 - | `401 Unauthorized` | Authentication failed | Missing or invalid session cookie, API key, or service auth JWT | 187 187 + | `401 Unauthorized` | Authentication failed | Missing or invalid client identification or DPoP authentication | 188 188 | `404 Not Found` | Method or record not found | XRPC method has no matching lexicon, or the requested record doesn't exist | 189 189 | `500 Internal Server Error` | Server-side failure | Lua script error, database error, or upstream PDS failure | 190 190

+3 -3

packages/docs/docs/tutorials/statusphere.md

reviewed

··· 125 125 "createdAt": "2025-01-01T11:30:00Z" 126 126 } 127 127 ], 128 128 - "cursor": "5" 128 128 + "cursor": "MjAyNS0wMS0wMVQxMjowMDowMFp8YXQ6Ly9kaWQ6..." 129 129 } 130 130 ``` 131 131 ··· 149 149 collection = collection, 150 150 did = params.did, 151 151 limit = tonumber(params.limit) or 20, 152 152 - offset = tonumber(params.cursor) or 0, 152 152 + cursor = params.cursor, 153 153 }) 154 154 end 155 155 ``` ··· 190 190 collection = collection, 191 191 did = params.did, 192 192 limit = tonumber(params.limit) or 20, 193 193 - offset = tonumber(params.cursor) or 0, 193 193 + cursor = params.cursor, 194 194 }) 195 195 end' 196 196

+114 -2

packages/docs/sidebars.ts

reviewed

··· 191 191 id: "guides/plugins", 192 192 label: "Plugins", 193 193 }, 194 194 + { 195 195 + type: "doc", 196 196 + id: "guides/developing-plugins", 197 197 + label: "Developing Plugins", 198 198 + }, 194 199 ], 195 200 }, 196 201 { ··· 228 233 id: "guides/postgres-to-sqlite-migration", 229 234 label: "Postgres → SQLite Migration", 230 235 }, 236 236 + { 237 237 + type: "doc", 238 238 + id: "guides/sqlite-to-postgres-migration", 239 239 + label: "SQLite → Postgres Migration", 240 240 + }, 231 241 ], 232 242 }, 233 243 ], ··· 268 278 label: "XRPC API", 269 279 }, 270 280 { 271 271 - type: "doc", 272 272 - id: "reference/admin-api", 281 281 + type: "category", 273 282 label: "Admin API", 283 283 + items: [ 284 284 + { 285 285 + type: "doc", 286 286 + id: "reference/admin-api", 287 287 + label: "Overview", 288 288 + }, 289 289 + { 290 290 + type: "doc", 291 291 + id: "reference/admin/lexicons", 292 292 + label: "Lexicons", 293 293 + }, 294 294 + { 295 295 + type: "doc", 296 296 + id: "reference/admin/stats", 297 297 + label: "Stats", 298 298 + }, 299 299 + { 300 300 + type: "doc", 301 301 + id: "reference/admin/backfill", 302 302 + label: "Backfill", 303 303 + }, 304 304 + { 305 305 + type: "doc", 306 306 + id: "reference/admin/events", 307 307 + label: "Event Logs", 308 308 + }, 309 309 + { 310 310 + type: "doc", 311 311 + id: "reference/admin/api-keys", 312 312 + label: "API Keys", 313 313 + }, 314 314 + { 315 315 + type: "doc", 316 316 + id: "reference/admin/users", 317 317 + label: "Users", 318 318 + }, 319 319 + { 320 320 + type: "doc", 321 321 + id: "reference/admin/labelers", 322 322 + label: "Labelers", 323 323 + }, 324 324 + { 325 325 + type: "doc", 326 326 + id: "reference/admin/settings", 327 327 + label: "Instance Settings", 328 328 + }, 329 329 + { 330 330 + type: "doc", 331 331 + id: "reference/admin/domains", 332 332 + label: "Domains", 333 333 + }, 334 334 + { 335 335 + type: "doc", 336 336 + id: "reference/admin/script-variables", 337 337 + label: "Script Variables", 338 338 + }, 339 339 + { 340 340 + type: "doc", 341 341 + id: "reference/admin/api-clients", 342 342 + label: "API Clients", 343 343 + }, 344 344 + { 345 345 + type: "doc", 346 346 + id: "reference/admin/plugins", 347 347 + label: "Plugins", 348 348 + }, 349 349 + ], 350 350 + }, 351 351 + { 352 352 + type: "category", 353 353 + label: "Lua API", 354 354 + items: [ 355 355 + { 356 356 + type: "doc", 357 357 + id: "reference/lua/record-api", 358 358 + label: "Record API", 359 359 + }, 360 360 + { 361 361 + type: "doc", 362 362 + id: "reference/lua/database-api", 363 363 + label: "Database API", 364 364 + }, 365 365 + { 366 366 + type: "doc", 367 367 + id: "reference/lua/http-api", 368 368 + label: "HTTP API", 369 369 + }, 370 370 + { 371 371 + type: "doc", 372 372 + id: "reference/lua/atproto-api", 373 373 + label: "AT Protocol API", 374 374 + }, 375 375 + { 376 376 + type: "doc", 377 377 + id: "reference/lua/json-api", 378 378 + label: "JSON API", 379 379 + }, 380 380 + { 381 381 + type: "doc", 382 382 + id: "reference/lua/standard-libraries", 383 383 + label: "Standard Libraries", 384 384 + }, 385 385 + ], 274 386 }, 275 387 { 276 388 type: "doc",