Concepts
The shape of the SDK, the job of each subpath, and the line where the SDK ends and the Sifa AppView begins.
The SDK is deliberately not a client. It does not manage your auth, does not store tokens, does not 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 that calls the HTTP API of the Sifa AppView.
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 that writes id.sifa.* records | @atproto/api@^0 (you supply the agent) |
The root subpath has no dependencies. You can pull it into a CLI, an analytics worker, an SSR backend, or a browser bundle. React and TanStack Query stay out of the bundle.
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 calls the AppView through its /query layer. For a read, it never calls a user PDS directly, because the AppView index answers faster and stays consistent. For a write, it does call the user PDS directly through the /atproto layer. A write has to land on the home server of the user, not on the Sifa 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, and it sits below 1.0 today. An additive change, such as a new export or a new type, gets a patch bump. A substantial milestone gets a minor bump. Below 1.0, treat every 0.x minor bump as a possible break. Read the CHANGELOG before you upgrade.
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 names the version behind the pages you read now.
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.