Atproto Lexicon Contracts Laravel Package

Product Decisions This Supports

• Feature: AT Protocol / Bluesky integration. Any roadmap item that reads or writes AT Protocol records (posts, likes, follows, profiles, custom feeds) or calls XRPC endpoints needs a typed contract layer. This package supplies PHP interfaces and enums generated directly from the official lexicon schemas, so the team isn't hand-transcribing JSON schemas into PHP.
• Build vs. buy (generate). The alternative is writing and maintaining DTOs/enums ourselves per lexicon, then re-syncing them every time upstream lexicons change. Auto-generation converts an ongoing maintenance cost into a one-time adoption plus a regeneration step — a clear "generate, don't hand-roll" decision.
• Schema-drift risk management. Because the artifacts are generated from lexicons, they give us a repeatable way to detect when upstream record shapes change and to version-bump our integration deliberately instead of discovering breakage in production.
• Custom lexicons / feed generators. If we publish our own AT Protocol lexicons (e.g., a bespoke feed or record type), the same generate-from-lexicon pipeline is reusable for our own schemas, not just upstream ones.
• Use cases: Bluesky publishing/reading, moderation and labeling tooling, PDS-adjacent services, ATProto data export/import, and any Laravel app that needs to speak atproto without adopting a heavier SDK.
• Explicitly not supported: runtime validation, HTTP/XRPC transport, auth (app passwords, OAuth), or session handling. This is a contracts package only — the roadmap must budget for a client layer alongside it.

When to Consider This Package

Adopt when all of the following hold:

• We are committing to AT Protocol as a real integration surface, in PHP/Laravel, and want compile-time-ish type safety on record and enum shapes.
• We accept a generated-code dependency: it is pinned to a lexicon version, updated by regeneration, and not something we patch by hand.
• We are prepared to own the supply chain: with 0 stars, 0 dependents, and a single-maintainer profile, treat this as vendorable source (fork or commit the generated output into our repo) rather than a trusted upstream we upgrade blindly.
• We pair it with a transport/validation layer (an XRPC client plus a JSON-schema validator) — the package does not replace either.

Look elsewhere (or generate in-house) when:

• AT Protocol is exploratory only — the cost of a client layer plus contracts exceeds the value of a spike.
• We need runtime guarantees: request validation, hydration, serialization, error mapping. Interfaces and enums alone won't enforce anything at runtime.
• We want a batteries-included SDK with auth, sessions, and XRPC calls — a fuller client is a better fit, and this package can still sit underneath it.
• We're not on PHP, or we're on a PHP version the generated code hasn't targeted.
• Upstream lexicon churn outpaces our willingness to regenerate and retest; the drift-management benefit collapses if nobody owns the regeneration job.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, MIT-licensed, auto-generated PHP contracts package for AT Protocol — the open protocol behind Bluesky. It doesn't add features on its own; it removes the manual work and typo-risk of hand-writing the data shapes our Bluesky/ATProto integration depends on, and it gives us a repeatable way to keep those shapes in sync as the protocol evolves. It is early-stage (no community traction), so the recommendation is to adopt it vendored and pinned — we take the generated code, own it, and regenerate on our schedule. Cost is low, upside is faster, safer delivery of any ATProto roadmap item; the main risk is maintenance, which we mitigate by not depending on the upstream project at runtime.

For engineering (summary): Pure PHP interfaces and enums generated from AT Protocol lexicon JSON. No runtime code, no dependencies to speak of, no validation or transport. Use it as the type contract layer under our own XRPC client; pair with a JSON-schema validator for runtime enforcement. Because it's generated, treat regeneration as a build step: pin the lexicon version, script the regeneration, and diff the output in CI so upstream schema changes surface as reviewable changes rather than surprises. If upstream stalls, we fork — the artifacts are ours either way.