Users & Profiles

The public identity surface. A profile is the whole of what one user can see about another — email is never exposed through this API. Profiles are platform-wide (cross-app): one profile per user, resolved the same way from every app.

type Profile = {
  id: string | null          // null for an account-deleted user
  displayName: string | null
  avatarUrl: string | null
  handle: string | null
}

SDK#

await osgarden.auth.getUser()            // → { id, profile } | null (null when signed out)
await osgarden.users(id).profile()       // → Profile
await osgarden.users([id1, id2]).profiles() // → Record<id, Profile>
await osgarden.updateProfile({ displayName, handle, avatarUrl }) // → Profile (your own)

A user with no profile yet resolves to their id with null fields. An account-deleted user resolves to the reserved deleted-user profile ({ id: null, displayName: "Deleted user" }).

Handles are optional and unique: 3–30 characters of a–z, 0–9, _. Claiming a taken handle returns 409 conflict with detail handle_taken.

The author(...) projection#

On mounted (creator-owned) tables, select accepts the reserved author(...) relation, which resolves the row's creator to their profile:

await osgarden.resource(roomId)
  .table("messages")
  .select("body, author(displayName, avatarUrl)")

Each row gains an author object with the requested fields (any of id, displayName, avatarUrl, handle). The gateway resolves all rows' authors in one batched query. Rows whose creator has deleted their account resolve to the deleted-user profile — so every app renders deletion the same way, with no per-app null-checking. author(...) is rejected on private and resource-owned tables (they have no row creator).

Account deletion#

POST /v1/account/delete (dashboard only) deletes the caller's account across every app at once. For each resource the user contributed to, the mount's onOwnerDelete policy decides what the context sees afterward:

• remove (default) — the links vanish; resource queries show no trace.
• tombstone — the rows stay in place, but the deleted profile makes author(...) render "Deleted user". Thread structure survives; authorship is anonymized.
• retain — the rows are reassigned to the resource, which keeps them at its own cost with authorship anonymized.

The user's private rows and all their files are then swept, resources they own are deleted (ownership transfer is a future option), and their profile is marked deleted. The append-only wallet ledger is retained for audit; session revocation is handled by the identity provider.