Statusphere Example App

The Statusphere example app demonstrates several core AT Protocol patterns:

• Authentication: Signing in via OAuth.
• Profile Management: Fetching information about users (profiles).
• Data Consumption: Listening to the network firehose for new data via Tap.
• Data Publication: Publishing data on a user's account using a custom schema.

This project is built using Next.js and uses Tap for syncing data from the Atmosphere.

To set up the Statusphere example app locally, clone the repository, configure your environment variables from the template, install dependencies using pnpm, and start the development server.

1. Clone the repository.
2. Copy env.template to .env.local.
3. Run pnpm install.
4. Run pnpm dev.
5. Access the application at http://127.0.0.1:3000.

git clone https://github.com/bluesky-social/statusphere-example-app.git
cd statusphere-example-app
cp env.template .env.local
pnpm install
pnpm dev

The Statusphere app requires an instance of Tap to read data from the network. Tap watches the xyz.statusphere.status collection, allowing the app to automatically pick up status updates from any account using this schema without manual repository registration.

For the quickest local setup, use Docker Compose:

docker compose up -d

Data is persisted in the .tap-data/ directory between restarts. For advanced configurations, such as running from source or securing webhooks with TAP_ADMIN_PASSWORD, refer to the Tap repository documentation.

The connection endpoint for the Tap client is determined by the TAP_URL environment variable. If this variable is not provided, the client defaults to http://localhost:2480.

# Example: setting a custom Tap URL
export TAP_URL="http://your-atmosphere-sync-service:2480"
npm start

Inserts a new status into the database. If a status with the same uri already exists, it performs an update on the status, createdAt, and indexedAt fields. This operation is wrapped in a transaction that also updates the user's current status flag.

import { StatusTable } from ".";

await insertStatus({
  uri: 'at://bsky.social/post/123',
  authorDid: 'did:plc:example',
  status: 'Hello world!',
  createdAt: new Date(),
  indexedAt: new Date(),
  current: 1
} as StatusTable);

Performs a cascading delete by removing the specified account record and all status records associated with that account's did.

await deleteAccount('did:plc:example');

Resolves an AT Protocol handle from a Decentralized Identifier (DID). It first attempts to look up the handle in the local database. If not found, it uses the getTap identity cache to resolve the DID via the AT Protocol. Returns null if the handle cannot be resolved.

const handle = await getAccountHandle('did:plc:example');

Use getDb() to obtain a singleton Kysely instance configured for SQLite. The function automatically initializes the connection using better-sqlite3 and sets the pragma journal_mode = WAL for improved concurrency. The database file path is determined by the DATABASE_PATH environment variable, defaulting to app.db if not provided.

import { getDb } from './lib/db';

const db = getDb();
// Use db with Kysely methods
const account = await db
  .selectFrom('account')
  .selectAll()
  .executeTakeFirst();

Use getTap() to retrieve a singleton instance of the Tap client. This client is used to interact with the Atmosphere data sync service. By default, it attempts to connect to the URL specified in the TAP_URL environment variable, falling back to http://localhost:2480 if the variable is not set.

import { getTap } from './lib/tap';

const tap = getTap();
// Use the tap instance to interact with Atmosphere data sync

Retrieves the most frequent status messages currently marked as current. It groups by the status text and counts occurrences to determine popularity. Defaults to the top 10.

// Returns the top 10 trending statuses
const top = await getTopStatuses();

// Returns the top 50 trending statuses
const topLarge = await getTopStatuses(50);