Concepts
How the SDK is structured, what each subpath is for, and where the SDK ends and the Sifa AppView begins.
The SDK is deliberately not a client. It doesn't manage your auth, doesn't store tokens, doesn't make decisions about what to render. What it does:
- Defines the shapes of every
id.sifa.*record (Zod schemas + TypeScript types). - Defines the taxonomies that decide how records get classified.
- Provides pure functions that operate on those shapes (formatters, predicates, normalisers).
- Exposes a thin AT Protocol wrapper that takes your agent and gives you typed read/write operations.
- Exposes a TanStack Query layer for talking to the Sifa AppView's HTTP API.
Everything else (OAuth, browser vs Expo storage, routing, UI) belongs to your app.
Subpaths
| Subpath | Purpose | Peer deps |
|---|---|---|
@singi-labs/sifa-sdk (root) | Types, Zod schemas, taxonomies, formatters, predicates | none |
@singi-labs/sifa-sdk/query | TanStack Query fetchers + React hooks for the Sifa AppView | @tanstack/react-query@^5, react@^18 or react@^19 |
@singi-labs/sifa-sdk/tokens | Design tokens (colors, typography) | none |
@singi-labs/sifa-sdk/atproto | Typed wrapper over @atproto/api for writing id.sifa.* records | @atproto/api@^0 (you supply the agent) |
The root subpath is dependency-free, so you can pull it into a CLI, an analytics worker, an SSR backend, or a browser bundle without dragging React or TanStack Query along.
Where the SDK ends
The SDK is one of three layers in a typical Sifa-aware app:
- The SDK (this thing): types and pure logic, plus optional fetchers and writers.
- The Sifa AppView at
sifa.id: indexes the AT Protocol firehose into a database and exposes HTTP endpoints. See Apps, AppViews, and the firehose for what an AppView is in this protocol. - Your app: the UI, the OAuth client, the storage strategy, the moderation decisions.
The SDK talks to the AppView via its /query layer. It does not talk directly to user PDSes for read operations (the AppView's index is faster and consistent). It does talk directly to user PDSes for write operations via the /atproto layer (writes have to land on the user's home server, not on Sifa's index).
Why no client?
Two reasons:
- Auth varies by platform. Browser apps use OAuth, mobile apps use the same OAuth flow but with MMKV storage, server apps may use app passwords. Bundling auth into the SDK forces a choice; leaving it out lets each platform pick.
- State management varies by app. Some apps want TanStack Query, some want SWR, some want raw fetch. The SDK ships TanStack Query as one option (
/query) and exposes the underlying fetchers so other state libraries can wrap them.
Versioning
The SDK follows semver, but it's currently pre-1.0. Patch bumps are the default for additive changes (new exports, new types). Minor bumps for substantial milestones. Until 1.0, treat 0.x minor bumps as potentially-breaking and read the CHANGELOG before upgrading.
When the SDK publishes a new version, sifa-sdk's release workflow dispatches an event to this docs repo to rebuild. The version stamp on the SDK overview page shows what's currently rendered against.
Want to go deeper
- Getting started: install + first calls.
- Activity taxonomy: the Made/Did/filtered classification.
- Brand tokens: colors, typography, icons, and where to find logos.