atproto_codegen

Alpha. Pre-1.0 and evolving alongside at-record; expect breaking changes between 0.x releases.

Generate Gleam types, JSON codecs, and a typed XRPC client from atproto lexicon files. Parses through the full-fidelity atproto_lexicon AST, lowers to a codegen-friendly view, and runs a small plugin pipeline (types, decode-json, optional xrpc-client) over it. Unsupported defs are reported and skipped, never emitted wrong.

Usage

gleam run -m atproto_codegen -- <lexicons_dir> <out_dir> <out_module> <nsid_prefix>[,...] [client_module]
# types + codecs only:
gleam run -m atproto_codegen -- ./lexicons ./src/my_app/gen my_app/gen com.example.myapp.,com.atproto.
# additionally generate a typed XRPC client module:
gleam run -m atproto_codegen -- ./lexicons ./src/my_app/gen my_app/gen com.example.myapp.,com.atproto. client

lexicons_dir is walked recursively for *.json lexicon files. Vendor any external lexicons you reference (e.g. com.atproto.repo.strongRef) into it.
out_module is the module prefix the generated code imports itself under; it must match where out_dir sits in your src/.
nsid_prefixes are stripped from NSIDs when deriving module paths, so com.example.myapp.shelf.entry emits <out_dir>/shelf/entry.gleam.
client_module (optional) enables the xrpc-client plugin: one module of typed query/procedure functions over atproto_client's primitives, with a params record, generated encoders/decoders, and a per-method error union (one variant per lexicon-declared error plus transport/unknown catch-alls). Omit it and output is exactly the pre-0.2 shape.

Generated blob fields use atproto/blob from atproto_client, so projects consuming generated code with blobs need that dependency.

Lexicon coverage

record and object defs for codecs; query and procedure defs for the client plugin (subscriptions are skipped). Refs resolve across lexicons (a bare NSID ref points at that lexicon's main def). knownValues string sets map to plain String; unknown round-trips through a Dynamic passthrough.