@vinerima/jetstream-types #

Zod schemas and TypeScript types for Bluesky Jetstream events, generated from official AT Protocol lexicon definitions.

Installation #

npm install @vinerima/jetstream-types

Requires zod v4 as a peer dependency.

Usage #

Validate a Jetstream post create event #

import { jetstreamPostCreateSchema, jetstreamToPost } from "@vinerima/jetstream-types";

const parsed = jetstreamPostCreateSchema.parse(rawMessage);
const post = jetstreamToPost(parsed);

Validate any collection's commit events #

import {
  jetstreamCommitCreateSchema,
  jetstreamCommitDeleteSchema,
} from "@vinerima/jetstream-types";

// Typed by collection — record field is fully typed
const likeCreate = jetstreamCommitCreateSchema("app.bsky.feed.like").parse(raw);
// likeCreate.commit.record is { $type: "app.bsky.feed.like", subject: {...}, createdAt: string }

const followCreate = jetstreamCommitCreateSchema("app.bsky.graph.follow").parse(raw);
// followCreate.commit.record is { $type: "app.bsky.graph.follow", subject: string, createdAt: string }

// Delete events have no record field
const deleted = jetstreamCommitDeleteSchema.parse(raw);

Validate identity and account events #

import { jetstreamIdentitySchema, jetstreamAccountSchema } from "@vinerima/jetstream-types";

const identity = jetstreamIdentitySchema.parse(raw);
const account = jetstreamAccountSchema.parse(raw);

Use record schemas standalone #

import { appBskyFeedPost, appBskyActorProfile } from "@vinerima/jetstream-types";

const post = appBskyFeedPost.parse(record);
const profile = appBskyActorProfile.parse(record);

Supported collections #

Collection	Schema
app.bsky.feed.post	appBskyFeedPost
app.bsky.feed.like	appBskyFeedLike
app.bsky.feed.repost	appBskyFeedRepost
app.bsky.feed.threadgate	appBskyFeedThreadgate
app.bsky.feed.postgate	appBskyFeedPostgate
app.bsky.graph.follow	appBskyGraphFollow
app.bsky.graph.block	appBskyGraphBlock
app.bsky.graph.list	appBskyGraphList
app.bsky.graph.listitem	appBskyGraphListitem
app.bsky.graph.listblock	appBskyGraphListblock
app.bsky.actor.profile	appBskyActorProfile

All record schemas include their transitive dependencies (embeds, facets, labels, strongRef, etc.).

Exports #

Envelope schemas #

• jetstreamCommitCreateSchema(collection) -- typed commit create envelope for a given collection
• jetstreamCommitUpdateSchema(collection) -- typed commit update envelope
• jetstreamCommitDeleteSchema -- commit delete envelope (no record field)
• jetstreamIdentitySchema -- identity event envelope
• jetstreamAccountSchema -- account event envelope

Record schemas #

All AT Protocol record types listed above, plus supporting types like comAtprotoRepoStrongRef, appBskyRichtextFacet, comAtprotoLabelDefsSelfLabels, embed schemas, etc.

Each schema has a corresponding TypeScript type export (PascalCase), e.g. AppBskyFeedPost, AppBskyFeedLike.

Utilities #

• collectionSchemas -- mapping from collection NSID string to its Zod record schema
• CollectionNsid -- union type of all supported collection NSID strings
• jetstreamToPost(msg) -- converts a post create event into a flat Post object
• Post -- interface with uri, cid, authorDid, text, rootUri, rootCid

Backward-compatible (v1) #

• jetstreamPostCreateSchema -- equivalent to jetstreamCommitCreateSchema("app.bsky.feed.post")
• JetstreamPostCreate -- inferred type

Regenerating schemas #

Record schemas are generated from official AT Protocol lexicon JSON files. To regenerate after upstream changes:

pnpm codegen
pnpm build

The codegen script fetches lexicons from the bluesky-social/atproto repository and outputs src/generated/lexicons.ts.

Breaking changes from v1 #

• The embed field on app.bsky.feed.post is now a discriminated union of 5 specific embed types instead of z.unknown(). Records with non-standard embed shapes will fail validation.
• The reply field now uses the generated comAtprotoRepoStrongRef schema (structurally identical to the previous hand-written schema).

License #

MIT