@atproto/lex 0.0.18 → 0.0.20

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @atproto/lex
 
+## 0.0.20
+
+### Patch Changes
+
+- [#4689](https://github.com/bluesky-social/atproto/pull/4689) [`f7c2610`](https://github.com/bluesky-social/atproto/commit/f7c26103a6d4e24e5bedbb6fd908be140420e0dd) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Update readme
+
+- Updated dependencies [[`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`f7c2610`](https://github.com/bluesky-social/atproto/commit/f7c26103a6d4e24e5bedbb6fd908be140420e0dd), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7)]:
+  - @atproto/lex-schema@0.0.14
+  - @atproto/lex-data@0.0.13
+  - @atproto/lex-client@0.0.15
+  - @atproto/lex-installer@0.0.20
+  - @atproto/lex-builder@0.0.17
+  - @atproto/lex-json@0.0.13
+
+## 0.0.19
+
+### Patch Changes
+
+- [#4672](https://github.com/bluesky-social/atproto/pull/4672) [`38852f0`](https://github.com/bluesky-social/atproto/commit/38852f0ddfa9fbce8036233dc6af87614e9ae4b2) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Improve readme
+
+- Updated dependencies [[`38852f0`](https://github.com/bluesky-social/atproto/commit/38852f0ddfa9fbce8036233dc6af87614e9ae4b2)]:
+  - @atproto/lex-client@0.0.14
+  - @atproto/lex-installer@0.0.19
+
 ## 0.0.18
 
 ### Patch Changes

package/README.md

@@ -1,48 +1,47 @@
-# @atproto/lex
+> [!IMPORTANT]
+>
+> This package is currently in **preview**. The API and features are subject to change before the stable release. See the [Changelog](./CHANGELOG.md) for version history.
 
-Type-safe Lexicon tooling for creating great API clients. See the [Changelog](./CHANGELOG.md) for version history.
+Type-safe Lexicon tooling for AT Protocol data.
 
-```bash
-npm install -g @atproto/lex
-lex --help
-```
+- Fetch and manage Lexicon schemas, generate TypeScript validators
+- Compile-time and runtime type safety for AT Protocol data structures
+- Fully typed XRPC client with authentication support
+- Tree-shaking and composition friendly
 
-- Install and manage Lexicon schemas
-- Generate TypeScript client and data validators
-- Handle common tasks like OAuth
+```typescript
+// Build data with generated builders and validators
 
-> [!IMPORTANT]
->
-> This package is currently in **preview**. The API and features are subject to change before the stable release.
+const newPost = app.bsky.feed.post.$build({
+  text: 'Hello, world!',
+  createdAt: new Date().toISOString(),
+})
 
-**What is this?**
+app.bsky.actor.profile.$validate({
+  $type: 'app.bsky.actor.profile',
+  displayName: 'Ha'.repeat(32) + '!',
+}) // Error: grapheme too big (maximum 64) at $.displayName (got 65)
+```
 
-Working directly with XRPC endpoints requires manually tracking schema definitions, validation data structures, and managing authentication. `@atproto/lex` automates this by:
+```typescript
+// Trivially make type-safe XRPC requests towards a service
 
-1. Fetching lexicons from the network and generating TypeScript types
-2. Providing runtime validation to ensure data matches schemas
-3. Offering a type-safe client that knows which parameters each endpoint expects
-4. Support modern patterns like tree-shaking and composition
+const profile = await xrpc('https://api.bsky.app', app.bsky.actor.getProfile, {
+  params: { actor: 'pfrazee.com' },
+})
+```
 
 ```typescript
-const profile = await client.call(app.bsky.actor.getProfile, {
-  actor: 'atproto.com',
-})
+// Manipulate records with the Client API in the context of an authenticated session
+
+const client = new Client(oauthSession)
 
 await client.create(app.bsky.feed.post, {
   text: 'Hello, world!',
   createdAt: new Date().toISOString(),
 })
 
-const posts = await client.list(app.bsky.feed.post, {
-  limit: 10,
-  repo: 'atproto.com',
-})
-
-app.bsky.actor.profile.$validate({
-  $type: 'app.bsky.actor.profile',
-  displayName: 'Ha'.repeat(32) + '!',
-}) // { success: false, error: Error: grapheme too big (maximum 64) at $.displayName (got 65) }
+const posts = await client.list(app.bsky.feed.post, { limit: 10 })
 ```
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
@@ -59,6 +58,7 @@ app.bsky.actor.profile.$validate({
   - [Types](#types)
   - [JSON Encoding](#json-encoding)
   - [CBOR Encoding](#cbor-encoding)
+- [Making simple XRPC Requests](#making-simple-xrpc-requests)
 - [Client API](#client-api)
   - [Creating a Client](#creating-a-client)
   - [Core Methods](#core-methods)
@@ -67,6 +67,7 @@ app.bsky.actor.profile.$validate({
   - [Labeler Configuration](#labeler-configuration)
   - [Low-Level XRPC](#low-level-xrpc)
 - [Utilities](#utilities)
+  - [Datetime Strings](#datetime-strings)
 - [Advanced Usage](#advanced-usage)
   - [Workflow Integration](#workflow-integration)
   - [Tree-Shaking](#tree-shaking)
@@ -135,15 +136,11 @@ This generates TypeScript files in `./src/lexicons` (by default) with type-safe
 **4. Use in your code**
 
 ```typescript
-import { Client } from '@atproto/lex'
-import * as app from './lexicons/app.js'
+import { xrpc } from '@atproto/lex'
+import { app } from './lexicons/index.js'
 
-// Create a client instance
-const client = new Client('https://public.api.bsky.app')
-
-// Start making requests using generated schemas
-const response = await client.call(app.bsky.actor.getProfile, {
-  actor: 'pfrazee.com',
+const profile = await xrpc('https://api.bsky.app', app.bsky.actor.getProfile, {
+  params: { actor: 'pfrazee.com' },
 })
 ```
 
@@ -227,13 +224,14 @@ function renderPost(p: app.bsky.feed.post.Main) {
 It is recommended to use the generated builders to create data that conforms to the schema. This ensures that all required fields are present.
 
 ```typescript
+import { l } from '@atproto/lex'
 import * as app from './lexicons/app.js'
 
 // variable type will be inferred as "app.bsky.feed.post.Main"
 const post = app.bsky.feed.post.$build({
   // No need to specify $type when using $build
   text: 'Hello, world!',
-  createdAt: new Date().toISOString(),
+  createdAt: l.toDatetimeString(new Date()),
 })
 ```
 
@@ -267,12 +265,13 @@ console.log(app.bsky.actor.defs.profileViewBasic.$type) // 'app.bsky.actor.defs#
 Returns `true` if data matches the schema, `false` otherwise. Acts as a TypeScript type guard:
 
 ```typescript
+import { l } from '@atproto/lex'
 import * as app from './lexicons/app.js'
 
 const data = {
   $type: 'app.bsky.feed.post',
   text: 'Hello!',
-  createdAt: new Date().toISOString(),
+  createdAt: l.toDatetimeString(new Date()),
 }
 
 if (app.bsky.feed.post.$check(data)) {
@@ -286,13 +285,14 @@ if (app.bsky.feed.post.$check(data)) {
 Validates and returns typed data, throwing an error if validation fails:
 
 ```typescript
+import { l } from '@atproto/lex'
 import * as app from './lexicons/app.js'
 
 try {
   const post = app.bsky.feed.post.$main.$parse({
     $type: 'app.bsky.feed.post',
     text: 'Hello!',
-    createdAt: new Date().toISOString(),
+    createdAt: l.toDatetimeString(new Date()),
   })
   // post is now typed and validated
   console.log(post.text)
@@ -310,12 +310,13 @@ try {
 Validates an existing value against a schema, returning the value itself if, and only if, it already matches the schema (ie. without applying defaults or coercion).
 
 ```typescript
+import { l } from '@atproto/lex'
 import * as app from './lexicons/app.js'
 
 const value = {
   $type: 'app.bsky.feed.post',
   text: 'Hello!',
-  createdAt: new Date().toISOString(),
+  createdAt: l.toDatetimeString(new Date()),
 }
 
 // Throws if no valid
@@ -329,12 +330,13 @@ value === result // true
 Returns a detailed validation result object without throwing:
 
 ```typescript
+import { l } from '@atproto/lex'
 import * as app from './lexicons/app.js'
 
 const result = app.bsky.feed.post.$safeParse({
   $type: 'app.bsky.feed.post',
   text: 'Hello!',
-  createdAt: new Date().toISOString(),
+  createdAt: l.toDatetimeString(new Date()),
 })
 
 if (result.success) {
@@ -349,6 +351,7 @@ if (result.success) {
 Builds data without needing to specify the `$type` property, and properly types the result:
 
 ```typescript
+import { l } from '@atproto/lex'
 import * as app from './lexicons/app.js'
 
 // The type of the "like" variable will be "app.bsky.feed.like.Main"
@@ -357,7 +360,7 @@ const like = app.bsky.feed.like.$build({
     uri: 'at://did:plc:abc/app.bsky.feed.post/123',
     cid: 'bafyrei...',
   },
-  createdAt: new Date().toISOString(),
+  createdAt: l.toDatetimeString(new Date()),
 })
 ```
 
@@ -414,7 +417,7 @@ if (isTypedLexMap(data)) {
 In JSON, CIDs are represented as `{"$link": "bafyrei..."}` and bytes as `{"$bytes": "base64..."}`. This package provides utilities to parse and stringify data model values to/from JSON:
 
 ```typescript
-import { lexParse, lexStringify, jsonToLex, lexToJson } from '@atproto/lex'
+import { Cid, lexParse, lexStringify, jsonToLex, lexToJson } from '@atproto/lex'
 
 // Parse JSON string → data model (decodes $link and $bytes)
 const parsed = lexParse<{
@@ -425,6 +428,9 @@ const parsed = lexParse<{
   "data": { "$bytes": "SGVsbG8sIHdvcmxkIQ==" }
 }`)
 
+assert(isCid(parsed.ref))
+assert(parsed.data instanceof Uint8Array)
+
 const someCid = lexParse<Cid>('{"$link": "bafyrei..."}')
 const someBytes = lexParse<Uint8Array>('{"$bytes": "SGVsbG8sIHdvcmxkIQ=="}')
 
@@ -458,8 +464,53 @@ const cborBytes = encode(someLexValue)
 const lexValue: LexValue = decode(cborBytes)
 ```
 
+## Making simple XRPC Requests
+
+[XRPC](https://atproto.com/specs/xrpc) (short for "Lexicon RPC") is the set of HTTP conventions used by AT Protocol for client-server and server-server communication. Endpoints follow the pattern `/xrpc/<nsid>`, where the NSID maps to a Lexicon schema that defines the request and response types. XRPC has three method types: **queries** (HTTP GET) for read operations, **procedures** (HTTP POST) for mutations and **subscriptions** (WebSockets) for real-time updates.
+
+The `xrpc()` and `xrpcSafe()` functions can be used to make simple XRPC requests. They are typically used in places that don't require an authenticated session, or when more granular control over the request/response is needed. For most use cases, the `Client` API provides a more ergonomic way to work with XRPC in the context of an authenticated session.
+
+```typescript
+import { xrpc, xrpcSafe } from '@atproto/lex'
+import * as com from './lexicons/com.js'
+
+const response = await xrpc(
+  'https://bsky.network',
+  com.atproto.identity.resolveHandle,
+  {
+    params: { handle: 'atproto.com' },
+    headers: { 'user-agent': 'MyApp/1.0.0' },
+  },
+)
+
+response.status // number
+response.headers // Headers
+response.body.did // `did:${string}:${string}`
+
+// Or use the safe variant (returns errors instead of throwing)
+const result = await xrpcSafe(
+  'https://bsky.network',
+  com.atproto.identity.resolveHandle,
+  {
+    params: { handle: 'atproto.com' },
+    signal: AbortSignal.timeout(5000), // Abort after 5 seconds
+  },
+)
+
+if (result.success) {
+  console.log(result.body)
+} else {
+  console.error(result.error) // XRPC error code
+  console.error(result.message) // Error message
+}
+```
+
 ## Client API
 
+The `Client` class provides high-level helpers for common AT Protocol "repo" operations: `create()`, `get()`, `put()`, `delete()`, `list()`, `uploadBlob()`, and more. A `Client` instance is typically useful for making requests in the context of an authenticated user session, as it automatically handles headers and provides default values based on the authenticated user's DID.
+
+A `Client` instance is also useful to encapsulate configuration for a specific service, by specifying the `service` option (for proxying) and `labelers` option (for content labeling). Additionally, a `Client` can be used as an `Agent` for another `Client`, allowing you to compose headers and configuration across multiple services.
+
 ### Creating a Client
 
 #### Unauthenticated Client
@@ -558,14 +609,15 @@ const timeline = await client.call(
 
 #### `client.create()`
 
-Create a new record.
+Create a new record un the authenticated user's repo.
 
 ```typescript
+import { l } from '@atproto/lex'
 import * as app from './lexicons/app.js'
 
 const result = await client.create(app.bsky.feed.post, {
   text: 'Hello, world!',
-  createdAt: new Date().toISOString(),
+  createdAt: l.toDatetimeString(new Date()),
 })
 
 console.log(result.uri) // at://did:plc:...
@@ -585,6 +637,7 @@ Retrieve a record.
 ```typescript
 import * as app from './lexicons/app.js'
 
+// No need to specify the "rkey" for records with literal keys (e.g. profile)
 const profile = await client.get(app.bsky.actor.profile)
 
 console.log(profile.displayName)
@@ -712,7 +765,7 @@ if (result.success) {
   // All XrpcFailure types have these properties:
   result.shouldRetry() // boolean - whether the error is transient
 
-  if (result.matchesSchema()) {
+  if (result.matchesSchemaErrors()) {
     // Check if the error matches a declared error in the schema.
     // TypeScript knows this is a declared error for the method.
     result.error // "HandleNotFound"
@@ -805,7 +858,7 @@ console.log(response.body)
 
 ## Utilities
 
-Various utilities for working with CIDs, string lengths, language tags, and low-level JSON encoding are exported from the package:
+Various utilities for working with CIDs, datetime strings, string lengths, language tags, and low-level JSON encoding are exported from the package:
 
 ```typescript
 import {
@@ -814,6 +867,12 @@ import {
   ifCid, // Coerce to Cid or null
   isCid, // Type guard for Cid values
 
+  // Datetime string utilities
+  toDatetimeString, // Convert Date to DatetimeString (throws on invalid)
+  asDatetimeString, // Cast string to DatetimeString (throws on invalid)
+  isDatetimeString, // Type guard for DatetimeString
+  ifDatetimeString, // Returns DatetimeString or undefined
+
   // Blob references
   BlobRef, // { $type: 'blob', ref: Cid, mimeType: string, size: number }
   isBlobRef, // Type guard for BlobRef objects
@@ -841,6 +900,35 @@ utf8Len('👨‍👩‍👧‍👦') // 25
 isLanguageString('en-US') // true
 ```
 
+### Datetime Strings
+
+Many AT Protocol records (such as posts, likes, and follows) include a `createdAt` field that expects a valid `DatetimeString`. While `new Date().toISOString()` produces a string that looks like a valid datetime, it is not guaranteed to always conform to the AT Protocol's [datetime format requirements](https://atproto.com/specs/lexicon#datetime) (for example, `Date` objects representing dates before year 10 or after year 9999 will produce non-conforming strings). To ensure correctness and type safety, use the `DatetimeString` utilities exported from `@atproto/lex`:
+
+- **`toDatetimeString(date: Date)`** - Converts a `Date` object into a valid `DatetimeString`, throwing an `InvalidDatetimeError` if the date cannot be represented as a valid AT Protocol datetime.
+- **`asDatetimeString(input: string)`** - Validates and casts an arbitrary string to `DatetimeString`, throwing an `InvalidDatetimeError` if the string does not conform.
+- **`isDatetimeString(input)`** - Type guard that returns `true` if the input is a valid `DatetimeString`.
+- **`ifDatetimeString(input)`** - Returns the input as a `DatetimeString` if valid, or `undefined` otherwise.
+- **`currentDatetimeString()`** - Returns the current date and time as `DatetimeString`.
+
+```typescript
+import { l } from '@atproto/lex'
+
+// Convert a Date object to a DatetimeString (or throws)
+const someDate = new Date('2024-01-15T12:30:00Z')
+const now = l.toDatetimeString(someDate)
+
+// Get the current datetime as a DatetimeString
+const now = l.currentDatetimeString()
+
+// Validate and cast an existing string
+const dt = l.asDatetimeString('2024-01-15T12:30:00.000Z')
+
+// Type guard for conditional checks
+if (l.isDatetimeString(someString)) {
+  // someString is now typed as DatetimeString
+}
+```
+
 ## Advanced Usage
 
 ### Workflow Integration
@@ -946,7 +1034,7 @@ Actions receive:
 Actions are called using `client.call()`, the same method used for XRPC queries and procedures:
 
 ```typescript
-import { Action, Client } from '@atproto/lex'
+import { Action, Client, l } from '@atproto/lex'
 import * as app from './lexicons/app.js'
 
 // Define an action
@@ -960,7 +1048,7 @@ export const likePost: Action<
     app.bsky.feed.like,
     {
       subject: { uri, cid },
-      createdAt: new Date().toISOString(),
+      createdAt: l.toDatetimeString(new Date()),
     },
     options,
   )
@@ -1161,7 +1249,7 @@ Actions enable you to create high-level, convenience APIs similar to [@atproto/a
 #### Creating Posts
 
 ```typescript
-import { Action } from '@atproto/lex'
+import { Action, l } from '@atproto/lex'
 import * as app from './lexicons/app.js'
 
 type PostInput = Partial<app.bsky.feed.post.Main> &
@@ -1176,7 +1264,7 @@ export const post: Action<PostInput, { uri: string; cid: string }> = async (
     app.bsky.feed.post,
     {
       ...record,
-      createdAt: record.createdAt || new Date().toISOString(),
+      createdAt: record.createdAt || l.currentDatetimeString(),
     },
     options,
   )
@@ -1192,7 +1280,7 @@ await client.call(post, {
 #### Following Users
 
 ```typescript
-import { Action } from '@atproto/lex'
+import { Action, l } from '@atproto/lex'
 import { AtUri } from '@atproto/syntax'
 import * as app from './lexicons/app.js'
 
@@ -1204,7 +1292,7 @@ export const follow: Action<
     app.bsky.graph.follow,
     {
       subject: did,
-      createdAt: new Date().toISOString(),
+      createdAt: l.currentDatetimeString(),
     },
     options,
   )

package/dist/index.d.ts

@@ -3,30 +3,35 @@
  * lexicons, including data types, JSON encoding/decoding, schema validation,
  * and HTTP client functionality.
  *
- * ## `@atproto/lex-client`
- *
- * - {@link client.Client} - Type-safe XRPC client for making ATProtocol API calls
- * - {@link client.XrpcError} - Base error class for XRPC request failures
- * - {@link client.Agent} - Interface used by {@link client.Client} for making HTTP requests
- * - {@link client.xrpc} - Utility function for making XRPC requests
- *
- * ## `@atproto/lex-data`
- *
- * - {@link data.LexValue} - Union type representing any valid Lexicon value
- * - {@link data.LexMap} - Object type with string keys and {@link data.LexValue} values
- * - {@link data.Cid} - Content Identifier for referencing data by hash
- * - {@link data.BlobRef} - Reference to binary data (images, videos, etc.)
- *
- * ## `@atproto/lex-json`
- *
- * - {@link json.lexStringify} - Serialize Lex values to JSON strings
- * - {@link json.lexParse} - Parse JSON strings into Lex values
- * - {@link json.lexToJson} - Convert Lex values to plain JSON objects
- * - {@link json.jsonToLex} - Convert plain JSON objects to Lex values
- *
- * ## `@atproto/lex-schema`
- *
- * The {@link l} namespace provides a fluent API for building schemas:
+ * @packageDocumentation
+ */
+export { 
+/**
+ * The Client class is the primary interface for interacting with AT Protocol
+ * services though an authenticated session. It provides methods for making
+ * XRPC requests, handling records, and managing blobs.
+ */
+Client, 
+/**
+ * The `xrpc` function is a low-level utility for making XRPC requests towards
+ * a specific service. It allows for detailed control over the request,
+ * including custom parameters, body, and headers. This function is useful for
+ * advanced use cases where the higher-level `Client` methods may not provide
+ * enough flexibility.
+ */
+xrpc, 
+/**
+ * The `xrpcSafe` function is a wrapper around `xrpc` that provides additional
+ * safety checks and error handling. It ensures that the request is properly
+ * formed and that any errors are caught and handled gracefully. This function
+ * is recommended for most use cases, as it provides a safer interface for
+ * making XRPC requests.
+ */
+xrpcSafe, } from '@atproto/lex-client';
+export * from '@atproto/lex-client';
+export { 
+/**
+ * The {@link l} namespace (from `@atproto/lex-schema`) provides an imperative API for building schemas:
  *
  * ### Primitive Types
  * - {@link l.string | l.string()} - String values with optional format/length constraints
@@ -57,11 +62,50 @@
  * - {@link l.query | l.query()} - Define a Lexicon query method
  * - {@link l.procedure | l.procedure()} - Define a Lexicon procedure method
  * - {@link l.subscription | l.subscription()} - Define a Lexicon subscription method
- *
- * @packageDocumentation
  */
+l, } from '@atproto/lex-schema';
+export * from '@atproto/lex-schema';
+export { 
+/**
+ * The `LexMap` type represents an object with string keys and `LexValue` values.
+ * It is used to represent arbitrary objects in Lexicon schemas, where the
+ * properties are not predefined. This type allows for flexible data structures
+ * while still ensuring that all values conform to the `LexValue` type.
+ */
+type LexMap, 
+/**
+ * The `LexValue` type represents any valid value that can be used in a
+ * Lexicon schema. It is a union of all the primitive and composite types
+ * defined in `@atproto/lex-data`, including strings, integers, booleans,
+ * bytes, CIDs, blob references, objects, arrays, and maps. This type is used
+ * throughout the library to represent data that conforms to Lexicon schemas.
+ */
+type LexValue, } from '@atproto/lex-data';
 export * from '@atproto/lex-data';
+export { 
+/**
+ * The `jsonToLex` function takes a plain JavaScript object (typically parsed from
+ * JSON) and converts it back into a LexValue, reconstructing any complex types as needed. This is useful
+ * for processing data received from the network or loaded from JSON storage.
+ */
+jsonToLex, 
+/**
+ * The `lexParse` function takes a JSON string and parses it into a LexValue. It
+ * performs the necessary conversions to reconstruct complex LexValue types from
+ * their JSON representations.
+ */
+lexParse, 
+/**
+ * The `lexStringify` function takes a LexValue and serializes it to a JSON string.
+ * It handles the conversion of complex LexValue types (like BlobRef and Cid) into
+ * a JSON-friendly format.
+ */
+lexStringify, 
+/**
+ * The `lexToJson` function converts a LexValue into a plain JavaScript object
+ * that can be safely serialized to JSON. This is useful for preparing data to be
+ * sent over the network or stored in a JSON format.
+ */
+lexToJson, } from '@atproto/lex-json';
 export * from '@atproto/lex-json';
-export * from '@atproto/lex-schema';
-export * from '@atproto/lex-client';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AACjC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO;AACL;;;;GAIG;AACH,MAAM;AACN;;;;;;GAMG;AACH,IAAI;AACJ;;;;;;GAMG;AACH,QAAQ,GACT,MAAM,qBAAqB,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AAEnC,OAAO;AACL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,CAAC,GACF,MAAM,qBAAqB,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AAEnC,OAAO;AACL;;;;;GAKG;AACH,KAAK,MAAM;AACX;;;;;;GAMG;AACH,KAAK,QAAQ,GACd,MAAM,mBAAmB,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AAEjC,OAAO;AACL;;;;GAIG;AACH,SAAS;AACT;;;;GAIG;AACH,QAAQ;AACR;;;;GAIG;AACH,YAAY;AACZ;;;;GAIG;AACH,SAAS,GACV,MAAM,mBAAmB,CAAA;AAC1B,cAAc,mBAAmB,CAAA"}

package/dist/index.js

@@ -1,36 +1,41 @@
 "use strict";
-/* eslint-disable @typescript-eslint/no-unused-vars */
-Object.defineProperty(exports, "__esModule", { value: true });
-const tslib_1 = require("tslib");
 /**
  * The `@atproto/lex` package provides utilities for working with ATProtocol
  * lexicons, including data types, JSON encoding/decoding, schema validation,
  * and HTTP client functionality.
  *
- * ## `@atproto/lex-client`
- *
- * - {@link client.Client} - Type-safe XRPC client for making ATProtocol API calls
- * - {@link client.XrpcError} - Base error class for XRPC request failures
- * - {@link client.Agent} - Interface used by {@link client.Client} for making HTTP requests
- * - {@link client.xrpc} - Utility function for making XRPC requests
- *
- * ## `@atproto/lex-data`
- *
- * - {@link data.LexValue} - Union type representing any valid Lexicon value
- * - {@link data.LexMap} - Object type with string keys and {@link data.LexValue} values
- * - {@link data.Cid} - Content Identifier for referencing data by hash
- * - {@link data.BlobRef} - Reference to binary data (images, videos, etc.)
- *
- * ## `@atproto/lex-json`
- *
- * - {@link json.lexStringify} - Serialize Lex values to JSON strings
- * - {@link json.lexParse} - Parse JSON strings into Lex values
- * - {@link json.lexToJson} - Convert Lex values to plain JSON objects
- * - {@link json.jsonToLex} - Convert plain JSON objects to Lex values
- *
- * ## `@atproto/lex-schema`
- *
- * The {@link l} namespace provides a fluent API for building schemas:
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lexToJson = exports.lexStringify = exports.lexParse = exports.jsonToLex = exports.l = exports.xrpcSafe = exports.xrpc = exports.Client = void 0;
+const tslib_1 = require("tslib");
+var lex_client_1 = require("@atproto/lex-client");
+/**
+ * The Client class is the primary interface for interacting with AT Protocol
+ * services though an authenticated session. It provides methods for making
+ * XRPC requests, handling records, and managing blobs.
+ */
+Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return lex_client_1.Client; } });
+/**
+ * The `xrpc` function is a low-level utility for making XRPC requests towards
+ * a specific service. It allows for detailed control over the request,
+ * including custom parameters, body, and headers. This function is useful for
+ * advanced use cases where the higher-level `Client` methods may not provide
+ * enough flexibility.
+ */
+Object.defineProperty(exports, "xrpc", { enumerable: true, get: function () { return lex_client_1.xrpc; } });
+/**
+ * The `xrpcSafe` function is a wrapper around `xrpc` that provides additional
+ * safety checks and error handling. It ensures that the request is properly
+ * formed and that any errors are caught and handled gracefully. This function
+ * is recommended for most use cases, as it provides a safer interface for
+ * making XRPC requests.
+ */
+Object.defineProperty(exports, "xrpcSafe", { enumerable: true, get: function () { return lex_client_1.xrpcSafe; } });
+tslib_1.__exportStar(require("@atproto/lex-client"), exports);
+var lex_schema_1 = require("@atproto/lex-schema");
+/**
+ * The {@link l} namespace (from `@atproto/lex-schema`) provides an imperative API for building schemas:
  *
  * ### Primitive Types
  * - {@link l.string | l.string()} - String values with optional format/length constraints
@@ -61,11 +66,34 @@ const tslib_1 = require("tslib");
  * - {@link l.query | l.query()} - Define a Lexicon query method
  * - {@link l.procedure | l.procedure()} - Define a Lexicon procedure method
  * - {@link l.subscription | l.subscription()} - Define a Lexicon subscription method
- *
- * @packageDocumentation
  */
+Object.defineProperty(exports, "l", { enumerable: true, get: function () { return lex_schema_1.l; } });
+tslib_1.__exportStar(require("@atproto/lex-schema"), exports);
 tslib_1.__exportStar(require("@atproto/lex-data"), exports);
+var lex_json_1 = require("@atproto/lex-json");
+/**
+ * The `jsonToLex` function takes a plain JavaScript object (typically parsed from
+ * JSON) and converts it back into a LexValue, reconstructing any complex types as needed. This is useful
+ * for processing data received from the network or loaded from JSON storage.
+ */
+Object.defineProperty(exports, "jsonToLex", { enumerable: true, get: function () { return lex_json_1.jsonToLex; } });
+/**
+ * The `lexParse` function takes a JSON string and parses it into a LexValue. It
+ * performs the necessary conversions to reconstruct complex LexValue types from
+ * their JSON representations.
+ */
+Object.defineProperty(exports, "lexParse", { enumerable: true, get: function () { return lex_json_1.lexParse; } });
+/**
+ * The `lexStringify` function takes a LexValue and serializes it to a JSON string.
+ * It handles the conversion of complex LexValue types (like BlobRef and Cid) into
+ * a JSON-friendly format.
+ */
+Object.defineProperty(exports, "lexStringify", { enumerable: true, get: function () { return lex_json_1.lexStringify; } });
+/**
+ * The `lexToJson` function converts a LexValue into a plain JavaScript object
+ * that can be safely serialized to JSON. This is useful for preparing data to be
+ * sent over the network or stored in a JSON format.
+ */
+Object.defineProperty(exports, "lexToJson", { enumerable: true, get: function () { return lex_json_1.lexToJson; } });
 tslib_1.__exportStar(require("@atproto/lex-json"), exports);
-tslib_1.__exportStar(require("@atproto/lex-schema"), exports);
-tslib_1.__exportStar(require("@atproto/lex-client"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,sDAAsD;;;AAOtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,4DAAiC;AACjC,4DAAiC;AACjC,8DAAmC;AACnC,8DAAmC","sourcesContent":["/* eslint-disable @typescript-eslint/no-unused-vars */\n\nimport type * as client from '@atproto/lex-client'\nimport type * as data from '@atproto/lex-data'\nimport type * as json from '@atproto/lex-json'\nimport { l } from '@atproto/lex-schema'\n\n/**\n * The `@atproto/lex` package provides utilities for working with ATProtocol\n * lexicons, including data types, JSON encoding/decoding, schema validation,\n * and HTTP client functionality.\n *\n * ## `@atproto/lex-client`\n *\n * - {@link client.Client} - Type-safe XRPC client for making ATProtocol API calls\n * - {@link client.XrpcError} - Base error class for XRPC request failures\n * - {@link client.Agent} - Interface used by {@link client.Client} for making HTTP requests\n * - {@link client.xrpc} - Utility function for making XRPC requests\n *\n * ## `@atproto/lex-data`\n *\n * - {@link data.LexValue} - Union type representing any valid Lexicon value\n * - {@link data.LexMap} - Object type with string keys and {@link data.LexValue} values\n * - {@link data.Cid} - Content Identifier for referencing data by hash\n * - {@link data.BlobRef} - Reference to binary data (images, videos, etc.)\n *\n * ## `@atproto/lex-json`\n *\n * - {@link json.lexStringify} - Serialize Lex values to JSON strings\n * - {@link json.lexParse} - Parse JSON strings into Lex values\n * - {@link json.lexToJson} - Convert Lex values to plain JSON objects\n * - {@link json.jsonToLex} - Convert plain JSON objects to Lex values\n *\n * ## `@atproto/lex-schema`\n *\n * The {@link l} namespace provides a fluent API for building schemas:\n *\n * ### Primitive Types\n * - {@link l.string | l.string()} - String values with optional format/length constraints\n * - {@link l.integer | l.integer()} - Integer values with optional min/max constraints\n * - {@link l.boolean | l.boolean()} - Boolean values\n * - {@link l.bytes | l.bytes()} - Binary data (Uint8Array)\n * - {@link l.cid | l.cid()} - Content Identifier values\n * - {@link l.blob | l.blob()} - Blob references with mime type and size\n *\n * ### Composite Types\n * - {@link l.object | l.object()} - Objects with defined property schemas\n * - {@link l.array | l.array()} - Arrays with element type validation\n * - {@link l.union | l.union()} - Union of multiple possible types\n * - {@link l.ref | l.ref()} - Reference to another schema definition\n * - {@link l.literal | l.literal()} - Literal constant values\n * - {@link l.enum | l.enum()} - Enum of allowed string values\n * - {@link l.typedRef | l.typedRef()} - Reference to a {@link l.typedObject | l.typedObject()}\n * - {@link l.typedUnion | l.typedUnion()} - Discriminated union between multiple {@link l.typedRef | l.typedRef()} or {@link l.typedObject | l.typedObject()} types\n *\n * ### Modifiers\n * - {@link l.optional | l.optional()} - Mark a property as optional\n * - {@link l.nullable | l.nullable()} - Allow null values\n * - {@link l.withDefault | l.withDefault()} - Provide a default value\n *\n * ### Lexicon Definitions\n * - {@link l.typedObject | l.typedObject()} - Define a typed object with a `$type` property\n * - {@link l.record | l.record()} - Define a Lexicon record type\n * - {@link l.query | l.query()} - Define a Lexicon query method\n * - {@link l.procedure | l.procedure()} - Define a Lexicon procedure method\n * - {@link l.subscription | l.subscription()} - Define a Lexicon subscription method\n *\n * @packageDocumentation\n */\n\nexport * from '@atproto/lex-data'\nexport * from '@atproto/lex-json'\nexport * from '@atproto/lex-schema'\nexport * from '@atproto/lex-client'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;AAEH,kDAuB4B;AAtB1B;;;;GAIG;AACH,oGAAA,MAAM,OAAA;AACN;;;;;;GAMG;AACH,kGAAA,IAAI,OAAA;AACJ;;;;;;GAMG;AACH,sGAAA,QAAQ,OAAA;AAEV,8DAAmC;AAEnC,kDAmC4B;AAlC1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,+FAAA,CAAC,OAAA;AAEH,8DAAmC;AAmBnC,4DAAiC;AAEjC,8CAyB0B;AAxBxB;;;;GAIG;AACH,qGAAA,SAAS,OAAA;AACT;;;;GAIG;AACH,oGAAA,QAAQ,OAAA;AACR;;;;GAIG;AACH,wGAAA,YAAY,OAAA;AACZ;;;;GAIG;AACH,qGAAA,SAAS,OAAA;AAEX,4DAAiC","sourcesContent":["/**\n * The `@atproto/lex` package provides utilities for working with ATProtocol\n * lexicons, including data types, JSON encoding/decoding, schema validation,\n * and HTTP client functionality.\n *\n * @packageDocumentation\n */\n\nexport {\n  /**\n   * The Client class is the primary interface for interacting with AT Protocol\n   * services though an authenticated session. It provides methods for making\n   * XRPC requests, handling records, and managing blobs.\n   */\n  Client,\n  /**\n   * The `xrpc` function is a low-level utility for making XRPC requests towards\n   * a specific service. It allows for detailed control over the request,\n   * including custom parameters, body, and headers. This function is useful for\n   * advanced use cases where the higher-level `Client` methods may not provide\n   * enough flexibility.\n   */\n  xrpc,\n  /**\n   * The `xrpcSafe` function is a wrapper around `xrpc` that provides additional\n   * safety checks and error handling. It ensures that the request is properly\n   * formed and that any errors are caught and handled gracefully. This function\n   * is recommended for most use cases, as it provides a safer interface for\n   * making XRPC requests.\n   */\n  xrpcSafe,\n} from '@atproto/lex-client'\nexport * from '@atproto/lex-client'\n\nexport {\n  /**\n   * The {@link l} namespace (from `@atproto/lex-schema`) provides an imperative API for building schemas:\n   *\n   * ### Primitive Types\n   * - {@link l.string | l.string()} - String values with optional format/length constraints\n   * - {@link l.integer | l.integer()} - Integer values with optional min/max constraints\n   * - {@link l.boolean | l.boolean()} - Boolean values\n   * - {@link l.bytes | l.bytes()} - Binary data (Uint8Array)\n   * - {@link l.cid | l.cid()} - Content Identifier values\n   * - {@link l.blob | l.blob()} - Blob references with mime type and size\n   *\n   * ### Composite Types\n   * - {@link l.object | l.object()} - Objects with defined property schemas\n   * - {@link l.array | l.array()} - Arrays with element type validation\n   * - {@link l.union | l.union()} - Union of multiple possible types\n   * - {@link l.ref | l.ref()} - Reference to another schema definition\n   * - {@link l.literal | l.literal()} - Literal constant values\n   * - {@link l.enum | l.enum()} - Enum of allowed string values\n   * - {@link l.typedRef | l.typedRef()} - Reference to a {@link l.typedObject | l.typedObject()}\n   * - {@link l.typedUnion | l.typedUnion()} - Discriminated union between multiple {@link l.typedRef | l.typedRef()} or {@link l.typedObject | l.typedObject()} types\n   *\n   * ### Modifiers\n   * - {@link l.optional | l.optional()} - Mark a property as optional\n   * - {@link l.nullable | l.nullable()} - Allow null values\n   * - {@link l.withDefault | l.withDefault()} - Provide a default value\n   *\n   * ### Lexicon Definitions\n   * - {@link l.typedObject | l.typedObject()} - Define a typed object with a `$type` property\n   * - {@link l.record | l.record()} - Define a Lexicon record type\n   * - {@link l.query | l.query()} - Define a Lexicon query method\n   * - {@link l.procedure | l.procedure()} - Define a Lexicon procedure method\n   * - {@link l.subscription | l.subscription()} - Define a Lexicon subscription method\n   */\n  l,\n} from '@atproto/lex-schema'\nexport * from '@atproto/lex-schema'\n\nexport {\n  /**\n   * The `LexMap` type represents an object with string keys and `LexValue` values.\n   * It is used to represent arbitrary objects in Lexicon schemas, where the\n   * properties are not predefined. This type allows for flexible data structures\n   * while still ensuring that all values conform to the `LexValue` type.\n   */\n  type LexMap,\n  /**\n   * The `LexValue` type represents any valid value that can be used in a\n   * Lexicon schema. It is a union of all the primitive and composite types\n   * defined in `@atproto/lex-data`, including strings, integers, booleans,\n   * bytes, CIDs, blob references, objects, arrays, and maps. This type is used\n   * throughout the library to represent data that conforms to Lexicon schemas.\n   */\n  type LexValue,\n} from '@atproto/lex-data'\nexport * from '@atproto/lex-data'\n\nexport {\n  /**\n   * The `jsonToLex` function takes a plain JavaScript object (typically parsed from\n   * JSON) and converts it back into a LexValue, reconstructing any complex types as needed. This is useful\n   * for processing data received from the network or loaded from JSON storage.\n   */\n  jsonToLex,\n  /**\n   * The `lexParse` function takes a JSON string and parses it into a LexValue. It\n   * performs the necessary conversions to reconstruct complex LexValue types from\n   * their JSON representations.\n   */\n  lexParse,\n  /**\n   * The `lexStringify` function takes a LexValue and serializes it to a JSON string.\n   * It handles the conversion of complex LexValue types (like BlobRef and Cid) into\n   * a JSON-friendly format.\n   */\n  lexStringify,\n  /**\n   * The `lexToJson` function converts a LexValue into a plain JavaScript object\n   * that can be safely serialized to JSON. This is useful for preparing data to be\n   * sent over the network or stored in a JSON format.\n   */\n  lexToJson,\n} from '@atproto/lex-json'\nexport * from '@atproto/lex-json'\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "license": "MIT",
   "description": "Lexicon tooling for AT",
   "keywords": [
@@ -38,12 +38,12 @@
   "dependencies": {
     "tslib": "^2.8.1",
     "yargs": "^17.0.0",
-    "@atproto/lex-builder": "^0.0.16",
-    "@atproto/lex-client": "^0.0.13",
-    "@atproto/lex-data": "^0.0.12",
-    "@atproto/lex-json": "^0.0.12",
-    "@atproto/lex-installer": "^0.0.18",
-    "@atproto/lex-schema": "^0.0.13"
+    "@atproto/lex-builder": "^0.0.17",
+    "@atproto/lex-client": "^0.0.15",
+    "@atproto/lex-data": "^0.0.13",
+    "@atproto/lex-json": "^0.0.13",
+    "@atproto/lex-installer": "^0.0.20",
+    "@atproto/lex-schema": "^0.0.14"
   },
   "devDependencies": {
     "@types/yargs": "^17.0.33",