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) | | Testing | Anonymized profile responses and sample export details, via @singi-labs/sifa-sdk/testing (tests only) |

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