Sifa SDK

Public client library for the Sifa AppView on AT Protocol.

---

Overview

Shared TypeScript SDK consumed by sifa-web (Next.js) and the upcoming sifa-app (Expo / React Native). Holds platform-agnostic logic so both clients stay in feature parity without duplicating code.

Published publicly so third-party developers can build their own AT Protocol clients against the Sifa AppView. Trust and reputation logic stays server-side in sifa-api; the SDK exposes only what is safe to publish.

Pre-1.0 software. The public API is unstable and may change in any minor release.

---

What this package contains

Area	What it provides
Types	TypeScript types for Sifa data structures, generated from sifa-lexicons
Schemas	Zod schemas mirroring lexicon constraints for runtime validation
Query layer	TanStack Query keys, fetchers, and React hooks for calling sifa-api
ATproto	Wrapper around @atproto/api that accepts an authenticated agent
Format	Pure formatters for dates, locations, profile completeness
Logic	Business-logic predicates (display-only; server-side trust logic lives in sifa-api)
Taxonomy	Constants and enums (continents, industries, skill categories, activity tiers)
Tokens	Sifa-brand design tokens, exported via @singi-labs/sifa-sdk/tokens (optional)

---

Quick Start

pnpm add @singi-labs/sifa-sdk

import { SIFA_SDK_VERSION } from '@singi-labs/sifa-sdk';

console.log(SIFA_SDK_VERSION);

Optional design tokens (skip if you have your own brand):

import { colors, spacing } from '@singi-labs/sifa-sdk/tokens';

Classify an AT Protocol NSID into one of three activity tiers (creation, action, filtered). Unknown NSIDs default to filtered:

import { getActivityTier, getTierMeta } from '@singi-labs/sifa-sdk';

getActivityTier('app.bsky.feed.post'); // 'creation'
getActivityTier('app.bsky.feed.like'); // 'action'
getTierMeta('creation'); // { label: 'Made', shownOnPublicProfile: true, ... }

---

For third-party developers

This SDK is the recommended way to build clients against the Sifa AppView. It does not depend on react-dom, react-native, next, or any browser/Node-only storage API -- it runs anywhere TypeScript runs.

If you have a use case the current public surface does not cover, send feedback.

---

Development

pnpm install
pnpm build
pnpm test
pnpm lint
pnpm typecheck

Testing your changes

For SDK logic in isolation (schemas, formatters, taxonomies, fetchers), write a test and run the watcher. No consumer app needed:

pnpm test:watch

To test a change end-to-end inside a consumer (sifa-web, sifa-api), link your local build in. The SDK ships its compiled dist/, not source, so keep a build running while you edit:

pnpm dev   # tsup --watch, rebuilds dist/ on save

Then point the consumer at your checkout. For a pnpm consumer (sifa-web), an override is more reproducible across installs than a bare pnpm link:

// consumer package.json
"pnpm": { "overrides": { "@singi-labs/sifa-sdk": "link:../sifa-sdk" } }

then pnpm install. For an npm consumer (sifa-api), npm link works.

react and @tanstack/react-query are optional peer dependencies. If a linked build throws "Invalid hook call" or a missing QueryClient, the consumer is resolving two copies of them: run pnpm dedupe, or add an override pinning both to a single version. Only the ./query/hooks export needs React, so non-React consumers like sifa-api never hit this.

For a publish-faithful check with no watch, pack a tarball instead of linking:

pnpm build && pnpm pack   # produces singi-labs-sifa-sdk-x.y.z.tgz

then pnpm add ./singi-labs-sifa-sdk-x.y.z.tgz in the consumer. This installs exactly what would publish (respects files: ["dist"]), with no symlink resolution quirks.

Standards:

• Strict TypeScript -- strict: true, no any
• Pinned exact dependency versions
• Conventional commits enforced by commitlint
• Every published-API change requires a changeset (pnpm changeset)

All changes go through Pull Requests. CI must pass before merge.

---

Related Repositories

Repository	Description	License
singi-labs/sifa-api	AppView backend that this SDK consumes	Source-available
singi-labs/sifa-web	Next.js web client (consumes this SDK)	Source-available
singi-labs/sifa-lexicons	AT Protocol lexicon schemas	MIT
singi-labs/sifa-workspace	Project coordination	Public

---

Community

• Website: sifa.id
• Bluesky: @sifa.id
• Issues: Report bugs

---

License

MIT -- permissive, so that third-party developers can build their own ATproto-based professional profile clients on top of this SDK.

See LICENSE for full terms.

---

(c) 2026 Sifa