@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