L3 Application BFF SDK — Developer Documentation
Overview
TypeScript SDK for the Sovereign OS L3 Application BFF (port 3030). Generated from OpenAPI 3.1.0 spec at apps/agent-bff/openapi/bff-v1.json.
SDK Location
- Source:
packages/sovereign-sdk/src/L3BffClient.ts - Compiled output:
packages/sovereign-sdk/dist/ - TypeScript:
npx tsc --noEmit— clean compile, 23 methods
SDK Methods (23 total)
| Method | Endpoint | HTTP | Description |
|---|---|---|---|
health() | /health | GET | Service health check (unauthenticated) |
ready() | /ready | GET | Service readiness |
live() | /live | GET | Service liveness |
login(email, password) | /v1/auth/login | POST | Authenticate user |
register(email, password, name) | /v1/auth/register | POST | Register new user |
me() | /v1/auth/me | GET | Get current user profile |
verifyToken() | /v1/auth/verify | POST | Verify JWT token (POST variant) |
validateTokenGet() | /v1/auth/validate-token | GET | Verify JWT token (GET variant) |
upsertPresence(userId, body) | /v1/users/:userId/presence | PUT | Update user presence |
getPresence(userId) | /v1/users/:userId/presence | GET | Get user presence |
scopePresence(scope, scopeId, limit?, offset?) | /v1/presence/:scope/:scopeId | GET | List presence entries |
enqueueNotification(body) | /v1/notifications | POST | Enqueue notification |
getNotifications(userId, limit?, offset?, status?) | /v1/notifications/:userId | GET | Get user notifications |
getProvenance(messageId) | /v1/provenance/:messageId | GET | Get provenance record |
verifyProvenance(messageId) | /v1/provenance/:messageId/verify | GET | Verify provenance |
query(action, table, filters?, limit?, offset?, sort?) | /v1/query | POST | Generic query proxy |
sql(rawSql) | /v1/sql | POST | Raw SurrealQL execution |
getUsers(role?, limit?, offset?) | /v1/users | GET | List users (NEW) |
sendPresenceHeartbeat(userId, {scopeContext}) | /v1/users/:userId/presence/heartbeat | POST | Send presence heartbeat (NEW) |
Error Handling
- All methods throw
L3BffErroron non-2xx responses - Error codes:
{400, 401, 404, 409, 422, 500, 501, 502, 503} - Error format:
{ message, code, status } - Never synthesizes success — fail-closed
Types Exported
HealthCheckResponse,AuthLoginResponse,AuthMeResponse,AuthVerifyResponseAuthRegisterBody,PresenceUpdateBody,PresenceResponse,PresenceLocationNotificationEnqueueBody,NotificationEntry,FormSchemaDetail,FormFieldFormSubmissionBody,FormAttestationResponse,QueryBody,QueryResponseErrorResponseplus all inline response types from each method
Example Usage
import { L3BffClient } from './L3BffClient'
const client = new L3BffClient({
baseURL: 'http://127.0.0.1:3030',
token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
})
// Health check (unauthenticated)
const health = await client.health()
console.log('Service OK:', health.status === 'ok')
// Login
const loginResp = await client.login('user@example.com', 'password123')
console.log('Logged in as:', loginResp.user.email)
// Get presence
const presence = await client.upsertPresence('user:123', { online: true, status: 'online' })
// List users with role filter
const users = await client.getUsers('project_manager', 50, 0)
console.log('Found', users.total, 'users')
// Validate token via GET
const valid = await client.validateTokenGet()
console.log('Token valid:', valid.valid)
// Enqueue notification
const notif = await client.enqueueNotification({
user_id: 'user:123',
type: 'general',
title: 'New message',
body: 'You have a new message from support',
})AGENTS.md Compliance
- ✅ No bespoke tables — types derived from OpenAPI spec
- ✅ No runtime filesystem reads — pure fetch-based client
- ✅ No synthetic payloads — all types from API reference
- ✅ Fail-closed error handling — never invents success
- ✅ Types compile cleanly with
tsc --noEmit