@atproto/lex 0.0.22 → 0.0.23

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @atproto/lex
 
+## 0.0.23
+
+### Patch Changes
+
+- Updated dependencies [[`527f5d4`](https://github.com/bluesky-social/atproto/commit/527f5d4c5d0c9264c2ff6f23ad06a41163fc6809), [`527f5d4`](https://github.com/bluesky-social/atproto/commit/527f5d4c5d0c9264c2ff6f23ad06a41163fc6809), [`c4df84c`](https://github.com/bluesky-social/atproto/commit/c4df84cd78df68ee8cb7289e7b61b3a032ad484e), [`527f5d4`](https://github.com/bluesky-social/atproto/commit/527f5d4c5d0c9264c2ff6f23ad06a41163fc6809), [`a99dd58`](https://github.com/bluesky-social/atproto/commit/a99dd58b5fe1995e571cf5e7b0105355583efa93), [`e5e5bcf`](https://github.com/bluesky-social/atproto/commit/e5e5bcf85fbc0d418f05724d684e7265be6a0be9), [`ac6bd18`](https://github.com/bluesky-social/atproto/commit/ac6bd18f1dc3397dd29008eff2a1e40702a4e138), [`c5c6c7d`](https://github.com/bluesky-social/atproto/commit/c5c6c7dac3b08e5f63cc918f57705573028ad797)]:
+  - @atproto/lex-schema@0.0.17
+  - @atproto/lex-client@0.0.18
+  - @atproto/lex-builder@0.0.20
+  - @atproto/lex-installer@0.0.23
+
 ## 0.0.22
 
 ### Patch Changes

package/README.md

@@ -10,7 +10,7 @@ Type-safe Lexicon tooling for AT Protocol data.
 - Tree-shaking and composition friendly
 
 ```typescript
-// Build data with generated builders and validators
+// Build and validate data with generated utilities
 
 const newPost = app.bsky.feed.post.$build({
   text: 'Hello, world!',
@@ -222,7 +222,7 @@ function renderPost(p: app.bsky.feed.post.Main) {
 
 ### Building data
 
-It is recommended to use the generated builders to create data that conforms to the schema. This ensures that all required fields are present.
+It is recommended to use the generated builders to create data that conforms to the schema. TypeScript ensures that all required fields are present at compile time.
 
 ```typescript
 import { l } from '@atproto/lex'
@@ -234,6 +234,10 @@ const post = app.bsky.feed.post.$build({
   text: 'Hello, world!',
   createdAt: l.toDatetimeString(new Date()),
 })
+
+// For runtime validation, use $parse()/$validate() instead
+const postWithDefaults = app.bsky.feed.post.$parse(post)
+app.bsky.feed.post.$validate(post)
 ```
 
 ### Validation Helpers
@@ -359,7 +363,7 @@ app.bsky.feed.post.$safeParse(data, { strict: false })
 
 #### `$build(data)` - Build with Defaults
 
-Builds data without needing to specify the `$type` property, and properly types the result:
+Builds data by adding the `$type` property and properly types the result. Note that `$build()` does not perform validation - use `$parse()` if you need validation:
 
 ```typescript
 import { l } from '@atproto/lex'
@@ -662,7 +666,8 @@ console.log(result.cid)
 Options:
 
 - `rkey` - Custom record key (auto-generated if not provided)
-- `validate` - Validate record against schema before creating
+- `validate` - Asks the PDS to validate the record against schema when processing the request
+- `validateRequest` - Validate the record locally against schema before submitting the request
 - `swapCommit` - CID for optimistic concurrency control
 
 #### `client.get()`
@@ -703,6 +708,8 @@ await client.put(app.bsky.actor.profile, {
 Options:
 
 - `rkey` - Record key (required for non-literal keys)
+- `validate` - Validate record against schema before updating (falls back to `validateRequest` option if not specified)
+- `validateRequest` - Alternative way to enable validation (used if `validate` is not specified)
 - `swapCommit` - Expected repo commit CID
 - `swapRecord` - Expected record CID
 
@@ -759,7 +766,7 @@ The `xrpcSafe()` method returns a union type that includes the success case (`Xr
 import {
   Client,
   XrpcResponseError,
-  XrpcUpstreamError,
+  XrpcInvalidResponseError,
   XrpcInternalError,
 } from '@atproto/lex'
 import * as com from './lexicons/com.js'
@@ -777,20 +784,26 @@ if (result.success) {
 } else {
   // Handle failure - result is an XrpcFailure
   if (result instanceof XrpcResponseError) {
-    // The server returned a valid XRPC error response
-    result.error // string (e.g. "HandleNotFound", "AuthenticationRequired", etc.)
+    // The server responded with an error status code (4xx or 5xx).
+    // This is used for all error responses, whether or not they have a valid XRPC error payload.
+
+    result.error // string (e.g. "HandleNotFound", "AuthenticationRequired", "UpstreamFailure", etc.)
     result.message // string
     result.response.status // number
     result.response.headers // Headers
-    result.payload // { body: { error: string, message?: string }; encoding: string }
-  } else if (result instanceof XrpcUpstreamError) {
-    // The response was not a valid XRPC response (e.g. malformed JSON,
-    // data does not match schema, connection dropped)
+    result.payload // undefined | { body: unknown; encoding: string }
+
+    // Coerce to a valid XRPC error payload using toJSON():
+    result.toJSON() // { error: string, message?: string }
+  } else if (result instanceof XrpcInvalidResponseError) {
+    // The response was truly invalid (3xx redirect, malformed JSON, schema mismatch, etc.).
+    // This is a more specific error for responses that are not processable.
+
     result.error // "UpstreamFailure"
     result.message // string
     result.response.status // number
     result.response.headers // Headers
-    result.payload // null | { body: unknown; encoding: string }
+    result.payload // undefined | { body: unknown; encoding: string }
   } else if (result instanceof XrpcInternalError) {
     // Something went wrong on the client side (network error, etc.)
     result.error // "InternalServerError"
@@ -810,9 +823,9 @@ if (result.success) {
 
 The `XrpcFailure<M>` type is a union of three error classes:
 
-1. **`XrpcResponseError`** - The server returned a valid XRPC error response (non-2xx with proper error payload)
+1. **`XrpcResponseError`** - The server responded with a 4xx/5xx error status code. This is used for all error responses from the upstream server.
 
-2. **`XrpcUpstreamError`** - The response was invalid or unprocessable (malformed JSON, schema mismatch, incomplete response)
+2. **`XrpcInvalidResponseError`** - The upstream server returned a 2xx/3xx that does not comply with XRPC specifications for successful responses. A sub-class, `XrpcResponseValidationError`, is used for payload schema validation failures specifically.
 
 3. **`XrpcInternalError`** - Client-side errors (network failures, timeouts, etc.)
 
@@ -947,7 +960,7 @@ 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`:
+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 0 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "license": "MIT",
   "description": "Lexicon tooling for AT",
   "keywords": [
@@ -38,19 +38,20 @@
   "dependencies": {
     "tslib": "^2.8.1",
     "yargs": "^17.0.0",
-    "@atproto/lex-builder": "^0.0.19",
-    "@atproto/lex-client": "^0.0.17",
+    "@atproto/lex-builder": "^0.0.20",
+    "@atproto/lex-client": "^0.0.18",
     "@atproto/lex-data": "^0.0.14",
     "@atproto/lex-json": "^0.0.14",
-    "@atproto/lex-installer": "^0.0.22",
-    "@atproto/lex-schema": "^0.0.16"
+    "@atproto/lex-installer": "^0.0.23",
+    "@atproto/lex-schema": "^0.0.17"
   },
   "devDependencies": {
     "@types/yargs": "^17.0.33",
     "vitest": "^4.0.16"
   },
   "scripts": {
-    "prebuild": "./bin/lex build --clear --lexicons ./lexicons --out ./tests/lexicons --lib @atproto/lex-schema -- ignore additional npm args",
+    "codegen": "./bin/lex build --override --indexFile --lexicons ./lexicons --out ./tests/lexicons --lib @atproto/lex-schema",
+    "prebuild": "pnpm run codegen",
     "build": "tsc --build tsconfig.build.json",
     "test": "vitest run"
   }