SDK overview

The Sifa SDK (@singi-labs/sifa-sdk) lives on public npm under the MIT licence. It contains:

• Types and Zod schemas for every id.sifa.* record.
• Taxonomies that decide what counts as "Made" vs "Did" activity (the same data behind the Activity feed allow-list).
• Formatters and predicates that work on profile data and never touch the network.
• A TanStack Query layer under /query with fetchers and React hooks for the Sifa AppView API.
• Design tokens under /tokens (Flexoki primary/secondary colours, typography settings).
• An AT Protocol service wrapper under /atproto that takes an authenticated agent and turns it into Sifa-flavoured read/write operations.

Current published version: @singi-labs/sifa-sdkv0.12.70.

When to use it

• You build a third-party Sifa client (mobile, desktop, alternative web) and you want the same business logic that Sifa Web ships.
• You build automation or analytics on top of Sifa records and you want type-safe parsing.
• You integrate a non-Sifa app with the id.sifa.* lexicons, such as a Tangled-style code host or a Leaflet-style publisher. You want the canonical schemas, not your own copy of them.

You do not need the SDK to read a Sifa profile in HTML, JSON-LD, or Atom: every doc page is already crawlable. The SDK matters when your code needs typed access.

Where this section comes from

Every page in this section renders against a pinned version of the SDK. At build time, fumadocs-typescript reads the TypeScript source and produces the API reference. Every code example is a real .ts file, and CI typechecks it on every run. If sifa-sdk publishes a breaking change and we do not update an example, the build fails.

When the SDK ships a new release on npm, a cross-repo workflow tells this docs site to rebuild. The reference pages here reflect whatever the pinned version exposes.

Want to go deeper

• Getting started: install, configure, fetch your first record.
• Concepts: the shape of the SDK and its boundary with the AppView.
• Activity taxonomy: the canonical Made/Did/filtered classification.
• Brand tokens: colors, typography, icons, and where to find logos.

User-facing docs (how Sifa works, account creation, profile features) live in the User docs section.