@atproto/lex-client 0.0.16 → 0.0.18

package/src/xrpc.test.ts

@@ -1,4 +1,6 @@
-import { assert, describe, expect, it, vi } from 'vitest'
+import { assert, describe, expect, expectTypeOf, it, vi } from 'vitest'
+import { parseCid } from '@atproto/lex-data'
+import { lexToJson } from '@atproto/lex-json'
 import { l } from '@atproto/lex-schema'
 import { FetchHandler } from './agent.js'
 import {
@@ -7,13 +9,23 @@ import {
   XrpcInternalError,
   XrpcInvalidResponseError,
   XrpcResponseError,
-  XrpcUpstreamError,
+  XrpcResponseValidationError,
 } from './errors.js'
 import { XrpcResponse } from './response.js'
 import { xrpc, xrpcSafe } from './xrpc.js'
 
 // Fixtures
 
+const rawCid = parseCid(
+  'bafkreifjjcie6lypi6ny7amxnfftagclbuxndqonfipmb64f2km2devei4',
+  { flavor: 'raw' },
+)
+
+const cborCid = parseCid(
+  'bafyreidfayvfuwqa7qlnopdjiqrxzs6blmoeu4rujcjtnci5beludirz2a',
+  { flavor: 'cbor' },
+)
+
 const testQuery = l.query(
   'io.example.testQuery',
   l.params({ limit: l.optional(l.integer()) }),
@@ -48,11 +60,33 @@ const testNoOutputQuery = l.query(
   l.payload(),
 )
 
+const testQueryWithDefaults = l.query(
+  'io.example.testQueryWithDefaults',
+  l.params({ foo: l.optional(l.withDefault(l.string(), 'foo-default')) }),
+  l.jsonPayload({
+    foo: l.string(),
+    bar: l.optional(l.withDefault(l.string(), 'bar-default')),
+  }),
+)
+
+const testQueryGetBlobRef = l.query(
+  'io.example.testQueryGetBlobRef',
+  l.params(),
+  l.jsonPayload({
+    blobRef: l.blob({
+      allowLegacy: false,
+      accept: ['image/png'],
+      maxSize: 10,
+    }),
+  }),
+)
+
 describe(xrpc, () => {
   describe('success paths', () => {
     it('returns parsed JSON body for a query', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ value: 'hello' })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'hello' })
+      })
 
       const response = await xrpc(fetchHandler, testQuery, {
         params: { limit: 10 },
@@ -68,8 +102,9 @@ describe(xrpc, () => {
     })
 
     it('returns parsed JSON body for a procedure', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ id: 'abc123' })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ id: 'abc123' })
+      })
 
       const response = await xrpc(fetchHandler, testProcedure, {
         body: { text: 'hello world' },
@@ -83,10 +118,11 @@ describe(xrpc, () => {
 
     it('returns binary body for a binary query', async () => {
       const bytes = new Uint8Array([1, 2, 3, 4])
-      const fetchHandler: FetchHandler = async () =>
-        new Response(bytes, {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return new Response(bytes, {
           headers: { 'content-type': 'application/octet-stream' },
         })
+      })
 
       const response = await xrpc(fetchHandler, testBinaryQuery)
 
@@ -99,10 +135,11 @@ describe(xrpc, () => {
 
     it('returns binary body for a binary procedure', async () => {
       const bytes = new Uint8Array([10, 20, 30])
-      const fetchHandler: FetchHandler = async () =>
-        new Response(bytes, {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return new Response(bytes, {
           headers: { 'content-type': 'application/octet-stream' },
         })
+      })
 
       const response = await xrpc(fetchHandler, testBinaryProcedure, {
         body: new Uint8Array([99]),
@@ -115,8 +152,9 @@ describe(xrpc, () => {
     })
 
     it('returns no body for a no-output query', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        new Response(null, { status: 200 })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return new Response(null, { status: 200 })
+      })
 
       const response = await xrpc(fetchHandler, testNoOutputQuery)
 
@@ -127,9 +165,9 @@ describe(xrpc, () => {
     })
 
     it('passes query params as URL search params', async () => {
-      const fetchHandler = vi.fn<FetchHandler>(async () =>
-        Response.json({ value: 'ok' }),
-      )
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'ok' })
+      })
 
       await xrpc(fetchHandler, testQuery, { params: { limit: 25 } })
 
@@ -140,9 +178,9 @@ describe(xrpc, () => {
     })
 
     it('sends POST with JSON body for procedures', async () => {
-      const fetchHandler = vi.fn<FetchHandler>(async () =>
-        Response.json({ id: 'new-id' }),
-      )
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ id: 'new-id' })
+      })
 
       await xrpc(fetchHandler, testProcedure, {
         body: { text: 'test content' },
@@ -157,9 +195,9 @@ describe(xrpc, () => {
     })
 
     it('forwards custom headers', async () => {
-      const fetchHandler = vi.fn<FetchHandler>(async () =>
-        Response.json({ value: 'ok' }),
-      )
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'ok' })
+      })
 
       await xrpc(fetchHandler, testQuery, {
         params: { limit: 1 },
@@ -174,22 +212,34 @@ describe(xrpc, () => {
     })
 
     it('accepts optional params as omitted', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ value: 'ok' })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'ok' })
+      })
 
       const response = await xrpc(fetchHandler, testQuery)
 
       expect(response.success).toBe(true)
       expect(response.body).toEqual({ value: 'ok' })
     })
+
+    it('ignores output for no-output queries', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ unexpected: 'data' })
+      })
+
+      const response = await xrpc(fetchHandler, testNoOutputQuery)
+
+      expect(response.success).toBe(true)
+      expect(response.body).toStrictEqual({ unexpected: 'data' })
+    })
   })
 
   describe('error handling', () => {
     describe('fetch errors', () => {
       it('throws XrpcFetchError when fetchHandler throws', async () => {
-        const fetchHandler: FetchHandler = async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
           throw new TypeError('fetch failed')
-        }
+        })
 
         await expect(
           xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
@@ -203,9 +253,9 @@ describe(xrpc, () => {
       })
 
       it('throws XrpcFetchError when fetchHandler rejects', async () => {
-        const fetchHandler: FetchHandler = async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
           throw new Error('network timeout')
-        }
+        })
 
         await expect(
           xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
@@ -220,18 +270,19 @@ describe(xrpc, () => {
 
     describe('response errors', () => {
       it('throws XrpcResponseError for 400 with valid error payload', async () => {
-        const fetchHandler: FetchHandler = async () =>
-          Response.json(
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          return Response.json(
             { error: 'TestError', message: 'bad request' },
             { status: 400 },
           )
+        })
 
         await expect(
           xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
         ).rejects.toSatisfy((err) => {
           assert(err instanceof XrpcResponseError)
           expect(err.status).toBe(400)
-          expect(err.body).toEqual({
+          expect(err.toJSON()).toEqual({
             error: 'TestError',
             message: 'bad request',
           })
@@ -240,11 +291,12 @@ describe(xrpc, () => {
       })
 
       it('throws XrpcAuthenticationError for 401', async () => {
-        const fetchHandler: FetchHandler = async () =>
-          Response.json(
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          return Response.json(
             { error: 'AuthenticationRequired', message: 'Token expired' },
             { status: 401 },
           )
+        })
 
         await expect(
           xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
@@ -256,51 +308,54 @@ describe(xrpc, () => {
         })
       })
 
-      it('throws XrpcUpstreamError for non-XRPC error response', async () => {
-        const fetchHandler: FetchHandler = async () =>
-          new Response('Not Found', {
+      it('throws XrpcResponseError for non-XRPC error response', async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          return new Response('Not Found', {
             status: 404,
             headers: { 'content-type': 'text/plain' },
           })
+        })
 
         await expect(
           xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
         ).rejects.toSatisfy((err) => {
-          assert(err instanceof XrpcUpstreamError)
-          expect(err.message).toBe('Invalid response payload')
+          assert(err instanceof XrpcResponseError)
+          expect(err.message).toBe('Upstream server responded with a 404 error')
           return true
         })
       })
 
-      it('throws XrpcUpstreamError for 500 without valid error payload', async () => {
-        const fetchHandler: FetchHandler = async () =>
-          new Response('Internal Server Error', {
+      it('throws XrpcResponseError for 500 without valid error payload', async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          return new Response('Internal Server Error', {
             status: 500,
             headers: { 'content-type': 'text/html' },
           })
+        })
 
         await expect(
           xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
         ).rejects.toSatisfy((err) => {
-          assert(err instanceof XrpcUpstreamError)
-          expect(err.message).toBe('Upstream server encountered an error')
+          assert(err instanceof XrpcResponseError)
+          expect(err.message).toBe('Upstream server responded with a 500 error')
           return true
         })
       })
 
       it('Reflects upstream 5xx errors with valid XRPC payload', async () => {
-        const fetchHandler: FetchHandler = async () =>
-          Response.json(
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          return Response.json(
             { error: 'ServerError', message: 'Something went wrong' },
             { status: 502 },
           )
+        })
 
         await expect(
           xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
         ).rejects.toSatisfy((err) => {
           assert(err instanceof XrpcResponseError)
           expect(err.status).toBe(502)
-          expect(err.body).toEqual({
+          expect(err.toJSON()).toEqual({
             error: 'ServerError',
             message: 'Something went wrong',
           })
@@ -310,32 +365,34 @@ describe(xrpc, () => {
     })
 
     describe('invalid response errors', () => {
-      it('throws XrpcInvalidResponseError when response body fails validation', async () => {
+      it('throws XrpcResponseValidationError when response body fails validation', async () => {
         // Schema expects { value: string } but we return { value: 123 }
-        const fetchHandler: FetchHandler = async () =>
-          Response.json({ value: 123 })
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          return Response.json({ value: 123 })
+        })
 
         await expect(
           xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
         ).rejects.toSatisfy((err) => {
-          assert(err instanceof XrpcInvalidResponseError)
-          expect(err).toBeInstanceOf(XrpcUpstreamError)
+          assert(err instanceof XrpcResponseValidationError)
+          expect(err).toBeInstanceOf(XrpcInvalidResponseError)
           expect(err.cause).toBeInstanceOf(Error)
           return true
         })
       })
 
-      it('throws XrpcUpstreamError when response has wrong content-type', async () => {
-        const fetchHandler: FetchHandler = async () =>
-          new Response('binary data', {
+      it('throws XrpcInvalidResponseError when response has wrong content-type', async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          return new Response('binary data', {
             status: 200,
             headers: { 'content-type': 'text/plain' },
           })
+        })
 
         await expect(
           xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
         ).rejects.toSatisfy((err) => {
-          assert(err instanceof XrpcUpstreamError)
+          assert(err instanceof XrpcInvalidResponseError)
           expect(err.message).toContain('application/json')
           return true
         })
@@ -344,8 +401,9 @@ describe(xrpc, () => {
 
     describe('content-type header errors', () => {
       it('throws XrpcInternalError when content-type header is set', async () => {
-        const fetchHandler: FetchHandler = async () =>
-          Response.json({ value: 'ok' })
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          return Response.json({ value: 'ok' })
+        })
 
         await expect(
           xrpc(fetchHandler, testQuery, {
@@ -361,64 +419,54 @@ describe(xrpc, () => {
     })
 
     describe('response payload parsing', () => {
-      it('throws XrpcUpstreamError when error response body cannot be parsed', async () => {
-        const fetchHandler: FetchHandler = async () =>
-          new Response('not valid json', {
+      it('throws XrpcInvalidResponseError when error response body cannot be parsed', async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          return new Response('not valid json', {
             status: 400,
             headers: { 'content-type': 'application/json' },
           })
+        })
 
         await expect(
           xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
         ).rejects.toSatisfy((err) => {
-          assert(err instanceof XrpcUpstreamError)
-          expect(err.message).toBe('Unable to parse response payload')
+          assert(err instanceof XrpcInvalidResponseError)
+          expect(err.message).toMatch('Unable to parse response payload')
           assert(err.cause instanceof Error)
           expect(err.cause.message).toContain('Unexpected token')
           return true
         })
       })
 
-      it('throws XrpcUpstreamError when success response body cannot be parsed', async () => {
-        const fetchHandler: FetchHandler = async () =>
-          new Response('not valid json', {
+      it('throws XrpcInvalidResponseError when success response body cannot be parsed', async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          return new Response('not valid json', {
             status: 200,
             headers: { 'content-type': 'application/json' },
           })
+        })
 
         await expect(
           xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
         ).rejects.toSatisfy((err) => {
-          assert(err instanceof XrpcUpstreamError)
-          expect(err.message).toBe('Unable to parse response payload')
+          assert(err instanceof XrpcInvalidResponseError)
+          expect(err.message).toMatch('Unable to parse response payload')
           assert(err.cause instanceof Error)
           expect(err.cause.message).toContain('Unexpected token')
           return true
         })
       })
 
-      it('throws XrpcUpstreamError when schema expects no payload but got one', async () => {
-        const fetchHandler: FetchHandler = async () =>
-          Response.json({ unexpected: 'data' })
-
-        await expect(xrpc(fetchHandler, testNoOutputQuery)).rejects.toSatisfy(
-          (err) => {
-            assert(err instanceof XrpcUpstreamError)
-            expect(err.message).toContain('no body')
-            return true
-          },
-        )
-      })
-
-      it('throws XrpcUpstreamError when schema expects payload but response is empty', async () => {
-        const fetchHandler: FetchHandler = async () =>
-          new Response(null, { status: 200 })
+      it('throws XrpcInvalidResponseError when schema expects payload but response is empty', async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          return new Response(null, { status: 200 })
+        })
 
         await expect(
           xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
         ).rejects.toSatisfy((err) => {
-          assert(err instanceof XrpcUpstreamError)
-          expect(err.message).toContain('non-empty response')
+          assert(err instanceof XrpcInvalidResponseError)
+          expect(err.message).toContain('got no payload')
           return true
         })
       })
@@ -426,11 +474,12 @@ describe(xrpc, () => {
 
     describe('content-type handling', () => {
       it('parses content-type with charset parameter', async () => {
-        const fetchHandler: FetchHandler = async () =>
-          new Response(JSON.stringify({ value: 'hello' }), {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          return new Response(JSON.stringify({ value: 'hello' }), {
             status: 200,
             headers: { 'content-type': 'application/json; charset=utf-8' },
           })
+        })
 
         const response = await xrpc(fetchHandler, testQuery, {
           params: { limit: 10 },
@@ -464,15 +513,15 @@ describe(xrpc, () => {
     })
 
     describe('non-2xx non-4xx/5xx responses', () => {
-      it('throws XrpcUpstreamError for 3xx status codes', async () => {
+      it('throws XrpcInvalidResponseError for 3xx status codes', async () => {
         const fetchHandler: FetchHandler = async () =>
           Response.json({ value: 'redirect' }, { status: 302 })
 
         await expect(
           xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
         ).rejects.toSatisfy((err) => {
-          assert(err instanceof XrpcUpstreamError)
-          expect(err.message).toBe('Invalid response status code')
+          assert(err instanceof XrpcInvalidResponseError)
+          expect(err.message).toBe('Unexpected status code 302')
           return true
         })
       })
@@ -481,8 +530,9 @@ describe(xrpc, () => {
 
   describe('validateRequest', () => {
     it('rejects invalid query params when enabled', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ value: 'ok' })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'ok' })
+      })
 
       await expect(
         xrpc(fetchHandler, testQuery, {
@@ -498,8 +548,9 @@ describe(xrpc, () => {
     })
 
     it('rejects invalid procedure body when enabled', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ id: 'abc' })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ id: 'abc' })
+      })
 
       await expect(
         xrpc(fetchHandler, testProcedure, {
@@ -528,8 +579,9 @@ describe(xrpc, () => {
     })
 
     it('succeeds with valid body when enabled', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ id: 'valid' })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ id: 'valid' })
+      })
 
       const response = await xrpc(fetchHandler, testProcedure, {
         body: { text: 'hello' },
@@ -544,22 +596,24 @@ describe(xrpc, () => {
   describe('validateResponse', () => {
     it('rejects invalid response body by default', async () => {
       // Schema expects { value: string } but server returns { value: 123 }
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ value: 123 })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 123 })
+      })
 
       await expect(
         xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
       ).rejects.toSatisfy((err) => {
-        assert(err instanceof XrpcInvalidResponseError)
-        expect(err).toBeInstanceOf(XrpcUpstreamError)
+        assert(err instanceof XrpcResponseValidationError)
+        expect(err).toBeInstanceOf(XrpcInvalidResponseError)
         return true
       })
     })
 
     it('accepts invalid response body when disabled', async () => {
       // Schema expects { value: string } but server returns { value: 123 }
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ value: 123 })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 123 })
+      })
 
       const response = await xrpc(fetchHandler, testQuery, {
         params: { limit: 10 },
@@ -571,8 +625,9 @@ describe(xrpc, () => {
     })
 
     it('succeeds with valid response body when enabled', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ value: 'hello' })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'hello' })
+      })
 
       const response = await xrpc(fetchHandler, testQuery, {
         params: { limit: 10 },
@@ -583,13 +638,174 @@ describe(xrpc, () => {
       expect(response.body).toEqual({ value: 'hello' })
     })
   })
+
+  describe('strictResponseProcessing', () => {
+    // Helper: returns a JSON response containing a float (invalid lex data)
+    const validWithFloatHandler: FetchHandler = async () => {
+      return Response.json({ value: 'hello', extra: 1.5 }, { status: 200 })
+    }
+
+    // Helper: returns a JSON error response containing a float
+    const errorWithFloatHandler: FetchHandler = async () => {
+      return Response.json(
+        { error: 'TestError', message: 'test-error-description', extra: 1.5 },
+        { status: 400 },
+      )
+    }
+
+    it('rejects response with invalid lex data by default (strict parsing)', async () => {
+      await expect(
+        xrpc(validWithFloatHandler, testQuery, { params: { limit: 10 } }),
+      ).rejects.toSatisfy((err) => {
+        assert(err instanceof XrpcInvalidResponseError)
+        expect(err.message).toMatch('Unable to parse response payload')
+        expect(err.cause).toBeInstanceOf(TypeError)
+        return true
+      })
+    })
+
+    it('accepts response with invalid lex data when strict processing is disabled', async () => {
+      const response = await xrpc(validWithFloatHandler, testQuery, {
+        params: { limit: 10 },
+        strictResponseProcessing: false,
+      })
+
+      expect(response.success).toBe(true)
+      expect(response.body).toEqual({ value: 'hello', extra: 1.5 })
+    })
+
+    it('rejects response with invalid lex data when strict processing is explicitly enabled', async () => {
+      await expect(
+        xrpc(validWithFloatHandler, testQuery, {
+          strictResponseProcessing: true,
+        }),
+      ).rejects.toSatisfy((err) => {
+        assert(err instanceof XrpcInvalidResponseError)
+        expect(err.message).toMatch('Unable to parse response payload')
+        expect(err.cause).toBeInstanceOf(TypeError)
+        return true
+      })
+    })
+
+    it('rejects error response with invalid lex data by default', async () => {
+      await expect(xrpc(errorWithFloatHandler, testQuery)).rejects.toSatisfy(
+        (err) => {
+          assert(err instanceof XrpcResponseError)
+          expect(err.message).toBe('test-error-description')
+          return true
+        },
+      )
+    })
+
+    it('parses error response with invalid lex data when strict processing is disabled', async () => {
+      await expect(
+        xrpc(errorWithFloatHandler, testQuery, {
+          params: { limit: 10 },
+          strictResponseProcessing: false,
+        }),
+      ).rejects.toSatisfy((err) => {
+        // Error response is still an error, but it should be parsed successfully
+        assert(err instanceof XrpcResponseError)
+        expect(err.status).toBe(400)
+        expect(err.payload?.body).toEqual({
+          error: 'TestError',
+          message: 'test-error-description',
+          extra: 1.5,
+        })
+        return true
+      })
+    })
+
+    it('with strictResponseProcessing: false and validateResponse: true, schema validation still runs', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 3, unknownValue: 1.5 }, { status: 200 })
+      })
+
+      await expect(
+        xrpc(fetchHandler, testQuery, {
+          params: { limit: 10 },
+          strictResponseProcessing: false,
+          validateResponse: true,
+        }),
+      ).rejects.toSatisfy((err) => {
+        assert(err instanceof XrpcResponseValidationError)
+        expect(err).toBeInstanceOf(XrpcInvalidResponseError)
+        return true
+      })
+    })
+
+    it('with strictResponseProcessing: false and validateResponse: false, schema validation is skipped', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json(
+          {
+            // Invalid value
+            value: 3,
+            // Non-strict Lex Data values:
+            unknownValue: 1.2,
+            foo: { $bytes: 3 },
+          },
+          { status: 200 },
+        )
+      })
+
+      const response = await xrpc(fetchHandler, testQuery, {
+        params: { limit: 10 },
+        strictResponseProcessing: false,
+        validateResponse: false,
+      })
+
+      expect(response.success).toBe(true)
+      expect(response.body).toEqual({
+        value: 3,
+        unknownValue: 1.2,
+        foo: { $bytes: 3 },
+      })
+
+      // @NOTE "validateResponse: false" basically acts as type casting
+      expectTypeOf(response.body).toMatchObjectType<{
+        value: string
+      }>()
+    })
+
+    it('with strictResponseProcessing: true and validateResponse: false, strict parsing still applies', async () => {
+      await expect(
+        xrpc(validWithFloatHandler, testQuery, {
+          params: { limit: 10 },
+          strictResponseProcessing: true,
+          validateResponse: false,
+        }),
+      ).rejects.toSatisfy((err) => {
+        assert(err instanceof XrpcInvalidResponseError)
+        expect(err.message).toMatch('Unable to parse response payload')
+        return true
+      })
+    })
+
+    it('does not affect binary responses', async () => {
+      const bytes = new Uint8Array([1, 2, 3])
+
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return new Response(bytes, {
+          headers: { 'content-type': 'application/octet-stream' },
+        })
+      })
+
+      const response = await xrpc(fetchHandler, testBinaryQuery, {
+        strictResponseProcessing: false,
+      })
+
+      expect(response.success).toBe(true)
+      expect(response.body).toEqual(bytes)
+    })
+  })
 })
 
 describe(xrpcSafe, () => {
   describe('success paths', () => {
     it('returns successful result for a JSON query', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ value: 'hello' })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'hello' })
+      })
 
       const result = await xrpcSafe(fetchHandler, testQuery, {
         params: { limit: 5 },
@@ -603,8 +819,9 @@ describe(xrpcSafe, () => {
     })
 
     it('returns successful result for a JSON procedure', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ id: 'new-id' })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ id: 'new-id' })
+      })
 
       const result = await xrpcSafe(fetchHandler, testProcedure, {
         body: { text: 'hello' },
@@ -616,10 +833,11 @@ describe(xrpcSafe, () => {
 
     it('returns successful result for a binary query', async () => {
       const bytes = new Uint8Array([5, 6, 7])
-      const fetchHandler: FetchHandler = async () =>
-        new Response(bytes, {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return new Response(bytes, {
           headers: { 'content-type': 'application/octet-stream' },
         })
+      })
 
       const result = await xrpcSafe(fetchHandler, testBinaryQuery)
 
@@ -631,10 +849,11 @@ describe(xrpcSafe, () => {
 
     it('returns successful result for a binary procedure', async () => {
       const bytes = new Uint8Array([42])
-      const fetchHandler: FetchHandler = async () =>
-        new Response(bytes, {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return new Response(bytes, {
           headers: { 'content-type': 'application/octet-stream' },
         })
+      })
 
       const result = await xrpcSafe(fetchHandler, testBinaryProcedure, {
         body: new Uint8Array([1, 2]),
@@ -646,8 +865,9 @@ describe(xrpcSafe, () => {
     })
 
     it('returns successful result for a no-output query', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        new Response(null, { status: 200 })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return new Response(null, { status: 200 })
+      })
 
       const result = await xrpcSafe(fetchHandler, testNoOutputQuery)
 
@@ -660,9 +880,9 @@ describe(xrpcSafe, () => {
   describe('error handling', () => {
     describe('fetch errors', () => {
       it('returns XrpcFetchError when fetchHandler throws', async () => {
-        const fetchHandler: FetchHandler = async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
           throw new TypeError('fetch failed')
-        }
+        })
 
         const result = await xrpcSafe(fetchHandler, testQuery, {
           params: { limit: 10 },
@@ -674,9 +894,9 @@ describe(xrpcSafe, () => {
       })
 
       it('returns XrpcFetchError when fetchHandler rejects', async () => {
-        const fetchHandler: FetchHandler = async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
           throw new Error('network timeout')
-        }
+        })
 
         const result = await xrpcSafe(fetchHandler, testQuery, {
           params: { limit: 10 },
@@ -702,8 +922,8 @@ describe(xrpcSafe, () => {
 
         assert(!result.success)
         assert(result instanceof XrpcResponseError)
-        expect(result.status).toBe(400)
-        expect(result.body).toEqual({
+        expect(result.response.status).toBe(400)
+        expect(result.toJSON()).toEqual({
           error: 'TestError',
           message: 'bad request',
         })
@@ -723,10 +943,10 @@ describe(xrpcSafe, () => {
         assert(!result.success)
         assert(result instanceof XrpcResponseError)
         expect(result).toBeInstanceOf(XrpcAuthenticationError)
-        expect(result.status).toBe(401)
+        expect(result.response.status).toBe(401)
       })
 
-      it('returns XrpcUpstreamError for non-XRPC error response', async () => {
+      it('returns XrpcResponseError for non-XRPC error response', async () => {
         const fetchHandler: FetchHandler = async () =>
           new Response('Not Found', {
             status: 404,
@@ -738,10 +958,10 @@ describe(xrpcSafe, () => {
         })
 
         assert(!result.success)
-        expect(result).toBeInstanceOf(XrpcUpstreamError)
+        expect(result).toBeInstanceOf(XrpcResponseError)
       })
 
-      it('returns XrpcUpstreamError for 500 without valid error payload', async () => {
+      it('returns XrpcResponseError for 500 without valid error payload', async () => {
         const fetchHandler: FetchHandler = async () =>
           new Response('Internal Server Error', {
             status: 500,
@@ -753,12 +973,16 @@ describe(xrpcSafe, () => {
         })
 
         assert(!result.success)
-        expect(result).toBeInstanceOf(XrpcUpstreamError)
+        expect(result).toBeInstanceOf(XrpcResponseError)
+        expect(result.error).toBe('InternalServerError')
+        expect(result.message).toMatch(
+          'Upstream server responded with a 500 error',
+        )
       })
     })
 
     describe('invalid response errors', () => {
-      it('returns XrpcInvalidResponseError when response body fails validation', async () => {
+      it('returns XrpcResponseValidationError when response body fails validation', async () => {
         const fetchHandler: FetchHandler = async () =>
           Response.json({ value: 123 })
 
@@ -767,11 +991,11 @@ describe(xrpcSafe, () => {
         })
 
         assert(!result.success)
+        expect(result).toBeInstanceOf(XrpcResponseValidationError)
         expect(result).toBeInstanceOf(XrpcInvalidResponseError)
-        expect(result).toBeInstanceOf(XrpcUpstreamError)
       })
 
-      it('returns XrpcUpstreamError when response has wrong content-type', async () => {
+      it('returns XrpcInvalidResponseError when response has wrong content-type', async () => {
         const fetchHandler: FetchHandler = async () =>
           new Response('binary data', {
             status: 200,
@@ -783,7 +1007,7 @@ describe(xrpcSafe, () => {
         })
 
         assert(!result.success)
-        expect(result).toBeInstanceOf(XrpcUpstreamError)
+        expect(result).toBeInstanceOf(XrpcInvalidResponseError)
       })
     })
 
@@ -806,8 +1030,9 @@ describe(xrpcSafe, () => {
 
   describe('validateRequest', () => {
     it('returns XrpcInternalError for invalid query params when enabled', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ value: 'ok' })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'ok' })
+      })
 
       const result = await xrpcSafe(fetchHandler, testQuery, {
         // @ts-expect-error intentionally passing invalid params
@@ -818,11 +1043,13 @@ describe(xrpcSafe, () => {
       assert(!result.success)
       expect(result).toBeInstanceOf(XrpcInternalError)
       expect(result).not.toBeInstanceOf(XrpcFetchError)
+      expect(fetchHandler).not.toHaveBeenCalled()
     })
 
     it('returns XrpcInternalError for invalid body when enabled', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ id: 'abc' })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ id: 'abc' })
+      })
 
       const result = await xrpcSafe(fetchHandler, testProcedure, {
         // @ts-expect-error intentionally passing invalid body
@@ -848,8 +1075,9 @@ describe(xrpcSafe, () => {
     })
 
     it('succeeds with valid body when enabled', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ id: 'valid' })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ id: 'valid' })
+      })
 
       const result = await xrpcSafe(fetchHandler, testProcedure, {
         body: { text: 'hello' },
@@ -862,22 +1090,24 @@ describe(xrpcSafe, () => {
   })
 
   describe('validateResponse', () => {
-    it('returns XrpcInvalidResponseError for invalid body by default', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ value: 123 })
+    it('returns XrpcResponseValidationError for invalid body by default', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 123 })
+      })
 
       const result = await xrpcSafe(fetchHandler, testQuery, {
         params: { limit: 10 },
       })
 
       assert(!result.success)
+      expect(result).toBeInstanceOf(XrpcResponseValidationError)
       expect(result).toBeInstanceOf(XrpcInvalidResponseError)
-      expect(result).toBeInstanceOf(XrpcUpstreamError)
     })
 
     it('accepts invalid response body when disabled', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ value: 123 })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 123 })
+      })
 
       const result = await xrpcSafe(fetchHandler, testQuery, {
         params: { limit: 10 },
@@ -889,8 +1119,9 @@ describe(xrpcSafe, () => {
     })
 
     it('succeeds with valid response body when enabled', async () => {
-      const fetchHandler: FetchHandler = async () =>
-        Response.json({ value: 'hello' })
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'hello' })
+      })
 
       const result = await xrpcSafe(fetchHandler, testQuery, {
         params: { limit: 10 },
@@ -900,5 +1131,323 @@ describe(xrpcSafe, () => {
       assert(result.success)
       expect(result.body).toEqual({ value: 'hello' })
     })
+
+    it('applies defaults', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async (path) => {
+        const url = new URL(path, 'http://localhost')
+        const foo = url.searchParams.get('foo')
+
+        // default applied while building the request
+        expect(foo).toBe('foo-default')
+
+        return Response.json({ foo: 'foo-value' })
+      })
+
+      const result = await xrpcSafe(fetchHandler, testQueryWithDefaults, {
+        params: {},
+        validateResponse: true,
+      })
+
+      expect(fetchHandler).toHaveBeenCalled()
+      assert(result.success)
+      expect(result.body).toEqual({
+        bar: 'bar-default', // default applied while parsing the response
+        foo: 'foo-value',
+      })
+    })
+  })
+
+  describe('blob constraints', () => {
+    it('rejects invalid blob refs', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        // missing properties jere
+        return Response.json({ blobRef: { $type: 'blob' } })
+      })
+
+      const result = await xrpcSafe(fetchHandler, testQueryGetBlobRef)
+      assert(!result.success)
+      expect(result).toBeInstanceOf(XrpcInvalidResponseError)
+      expect(result.message).toMatch('Unable to parse response payload')
+      assert(result.cause instanceof TypeError)
+      expect(result.cause.message).toBe('Invalid blob object')
+    })
+
+    it('rejects blob-refs with cbor data CIDs', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json(
+          lexToJson({
+            blobRef: {
+              $type: 'blob',
+              // ref should be a "raw" CID to be strictly valid
+              ref: cborCid,
+              mimeType: 'image/png',
+              size: 1,
+            },
+          }),
+        )
+      })
+
+      const result = await xrpcSafe(fetchHandler, testQueryGetBlobRef)
+      assert(!result.success)
+      expect(result).toBeInstanceOf(XrpcInvalidResponseError)
+      expect(result.message).toMatch('Unable to parse response payload')
+      assert(result.cause instanceof TypeError)
+      expect(result.cause.message).toBe('Invalid blob object')
+    })
+
+    it('enforces blob mime-type constraint by default', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json(
+          lexToJson({
+            blobRef: {
+              $type: 'blob',
+              ref: rawCid,
+              mimeType: 'invalid/mime',
+              size: 10,
+            },
+          }),
+        )
+      })
+
+      const result = await xrpcSafe(fetchHandler, testQueryGetBlobRef)
+      assert(!result.success)
+      expect(result).toBeInstanceOf(XrpcInvalidResponseError)
+      expect(result.message).toBe(
+        'Invalid response payload: Expected "image/png" (got "invalid/mime") at $.blobRef.mimeType',
+      )
+    })
+
+    it('enforces blob size constraint by default', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json(
+          lexToJson({
+            blobRef: {
+              $type: 'blob',
+              ref: rawCid,
+              mimeType: 'image/png',
+              size: 100,
+            },
+          }),
+        )
+      })
+
+      const result = await xrpcSafe(fetchHandler, testQueryGetBlobRef)
+      assert(!result.success)
+      expect(result).toBeInstanceOf(XrpcInvalidResponseError)
+      expect(result.message).toBe(
+        'Invalid response payload: blob too big (maximum 10, got 100) at $.blobRef',
+      )
+    })
+
+    it('ignores blob constraints in non-strict mode', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json(
+          lexToJson({
+            blobRef: {
+              $type: 'blob',
+              ref: rawCid,
+              mimeType: 'invalid/mime',
+              size: 100,
+            },
+          }),
+        )
+      })
+
+      const result = await xrpcSafe(fetchHandler, testQueryGetBlobRef, {
+        strictResponseProcessing: false,
+      })
+
+      assert(result.success)
+      expectTypeOf(result.body).toMatchObjectType<{ blobRef: l.BlobRef }>()
+      expect(result.body).toEqual({
+        blobRef: {
+          $type: 'blob',
+          ref: rawCid,
+          mimeType: 'invalid/mime',
+          size: 100,
+        },
+      })
+    })
+
+    it('transforms legacy blobs in non-strict mode', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({
+          blobRef: {
+            cid: rawCid.toString(),
+            mimeType: 'invalid/mime',
+          },
+        })
+      })
+
+      const result = await xrpcSafe(fetchHandler, testQueryGetBlobRef, {
+        strictResponseProcessing: false,
+      })
+
+      assert(result.success)
+      expectTypeOf(result.body).toMatchObjectType<{ blobRef: l.BlobRef }>()
+      expect(result.body).toEqual({
+        blobRef: {
+          $type: 'blob',
+          ref: rawCid,
+          mimeType: 'invalid/mime',
+          size: -1,
+        },
+      })
+    })
+
+    it('allows blob-refs with negative size in non-strict mode', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({
+          blobRef: {
+            $type: 'blob',
+            ref: { $link: rawCid.toString() },
+            mimeType: 'invalid/mime',
+            size: -1,
+          },
+        })
+      })
+
+      const result = await xrpcSafe(fetchHandler, testQueryGetBlobRef, {
+        strictResponseProcessing: false,
+      })
+
+      assert(result.success)
+      expectTypeOf(result.body).toMatchObjectType<{ blobRef: l.BlobRef }>()
+      expect(result.body).toEqual({
+        blobRef: {
+          $type: 'blob',
+          ref: rawCid,
+          mimeType: 'invalid/mime',
+          size: -1,
+        },
+      })
+    })
+  })
+
+  describe('strictResponseProcessing', () => {
+    const jsonResponseWithFloat: FetchHandler = async () => {
+      return Response.json({ value: 'hello', extra: 1.5 }, { status: 200 })
+    }
+
+    const jsonErrorResponseWithFloat: FetchHandler = async () => {
+      return Response.json(
+        { error: 'TestError', message: 'test-error-description', extra: 1.5 },
+        { status: 400 },
+      )
+    }
+
+    it('returns error for invalid lex data by default (strict parsing)', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(jsonResponseWithFloat)
+
+      const result = await xrpcSafe(fetchHandler, testQuery, {
+        params: { limit: 10 },
+      })
+
+      assert(!result.success)
+      expect(result).toBeInstanceOf(XrpcInvalidResponseError)
+      expect(result.message).toMatch('Unable to parse response payload')
+      assert(result.cause instanceof TypeError)
+      expect(result.cause.message).toBe('Invalid non-integer number: 1.5')
+    })
+
+    it('accepts response with invalid lex data when strict processing is disabled', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(jsonResponseWithFloat)
+
+      const result = await xrpcSafe(fetchHandler, testQuery, {
+        params: { limit: 10 },
+        strictResponseProcessing: false,
+      })
+
+      assert(result.success)
+      expect(result.body).toEqual({ value: 'hello', extra: 1.5 })
+    })
+
+    it('returns error for invalid lex data when strict processing is explicitly enabled', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(jsonResponseWithFloat)
+
+      const result = await xrpcSafe(fetchHandler, testQuery, {
+        params: { limit: 10 },
+        strictResponseProcessing: true,
+      })
+
+      assert(!result.success)
+      expect(result).toBeInstanceOf(XrpcInvalidResponseError)
+      expect(result.message).toMatch('Unable to parse response payload')
+      assert(result.cause instanceof TypeError)
+      expect(result.cause.message).toBe('Invalid non-integer number: 1.5')
+    })
+
+    it('returns error for error response with invalid lex data by default', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(jsonErrorResponseWithFloat)
+
+      const result = await xrpcSafe(fetchHandler, testQuery, {
+        params: { limit: 10 },
+      })
+
+      assert(!result.success)
+      expect(result).toBeInstanceOf(XrpcResponseError)
+      expect(result.message).toBe('test-error-description')
+    })
+
+    it('parses error response with invalid lex data when strict processing is disabled', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(jsonErrorResponseWithFloat)
+
+      const result = await xrpcSafe(fetchHandler, testQuery, {
+        params: { limit: 10 },
+        strictResponseProcessing: false,
+      })
+
+      assert(!result.success)
+      assert(result instanceof XrpcResponseError)
+      expect(result.response.status).toBe(400)
+      expect(result.message).toBe('test-error-description')
+    })
+
+    it('with strictResponseProcessing: false and validateResponse: true, schema validation still runs', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 1.5 }, { status: 200 })
+      })
+
+      const result = await xrpcSafe(fetchHandler, testQuery, {
+        params: { limit: 10 },
+        strictResponseProcessing: false,
+        validateResponse: true,
+      })
+
+      assert(!result.success)
+      expect(result).toBeInstanceOf(XrpcResponseValidationError)
+      expect(result).toBeInstanceOf(XrpcInvalidResponseError)
+    })
+
+    it('with strictResponseProcessing: false and validateResponse: false, schema validation is skipped', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 1.5 }, { status: 200 })
+      })
+
+      const result = await xrpcSafe(fetchHandler, testQuery, {
+        params: { limit: 10 },
+        strictResponseProcessing: false,
+        validateResponse: false,
+      })
+
+      assert(result.success)
+      expect(result.body).toEqual({ value: 1.5 })
+    })
+
+    it('with strictResponseProcessing: true and validateResponse: false, strict parsing still applies', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(jsonResponseWithFloat)
+
+      const result = await xrpcSafe(fetchHandler, testQuery, {
+        params: { limit: 10 },
+        strictResponseProcessing: true,
+        validateResponse: false,
+      })
+
+      assert(!result.success)
+      expect(result).toBeInstanceOf(XrpcInvalidResponseError)
+      expect(result.message).toMatch('Unable to parse response payload')
+      assert(result.cause instanceof TypeError)
+      expect(result.cause.message).toBe('Invalid non-integer number: 1.5')
+    })
   })
 })