@atproto/lex-client 0.0.15 → 0.0.17

package/src/xrpc.test.ts

@@ -0,0 +1,1453 @@
+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 {
+  XrpcAuthenticationError,
+  XrpcFetchError,
+  XrpcInternalError,
+  XrpcInvalidResponseError,
+  XrpcResponseError,
+  XrpcUpstreamError,
+} 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()) }),
+  l.jsonPayload({ value: l.string() }),
+  ['TestError'],
+)
+
+const testProcedure = l.procedure(
+  'io.example.testProcedure',
+  l.params(),
+  l.jsonPayload({ text: l.string() }),
+  l.jsonPayload({ id: l.string() }),
+  ['ProcedureError'],
+)
+
+const testBinaryQuery = l.query(
+  'io.example.testBinaryQuery',
+  l.params(),
+  l.payload('application/octet-stream', undefined),
+)
+
+const testBinaryProcedure = l.procedure(
+  'io.example.testBinaryProcedure',
+  l.params(),
+  l.payload('image/*', undefined),
+  l.payload('application/octet-stream', undefined),
+)
+
+const testNoOutputQuery = l.query(
+  'io.example.testNoOutputQuery',
+  l.params(),
+  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 = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'hello' })
+      })
+
+      const response = await xrpc(fetchHandler, testQuery, {
+        params: { limit: 10 },
+      })
+
+      expect(response).toBeInstanceOf(XrpcResponse)
+      expect(response.success).toBe(true)
+      expect(response.status).toBe(200)
+      expect(response.body).toEqual({ value: 'hello' })
+      expect(response.encoding).toBe('application/json')
+      expect(response.isParsed).toBe(true)
+      expect(response.value).toBe(response)
+    })
+
+    it('returns parsed JSON body for a procedure', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ id: 'abc123' })
+      })
+
+      const response = await xrpc(fetchHandler, testProcedure, {
+        body: { text: 'hello world' },
+      })
+
+      expect(response.success).toBe(true)
+      expect(response.status).toBe(200)
+      expect(response.body).toEqual({ id: 'abc123' })
+      expect(response.encoding).toBe('application/json')
+    })
+
+    it('returns binary body for a binary query', async () => {
+      const bytes = new Uint8Array([1, 2, 3, 4])
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return new Response(bytes, {
+          headers: { 'content-type': 'application/octet-stream' },
+        })
+      })
+
+      const response = await xrpc(fetchHandler, testBinaryQuery)
+
+      expect(response.success).toBe(true)
+      expect(response.body).toBeInstanceOf(Uint8Array)
+      expect(response.body).toEqual(bytes)
+      expect(response.encoding).toBe('application/octet-stream')
+      expect(response.isParsed).toBe(false)
+    })
+
+    it('returns binary body for a binary procedure', async () => {
+      const bytes = new Uint8Array([10, 20, 30])
+      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]),
+        encoding: 'image/png',
+      })
+
+      expect(response.success).toBe(true)
+      expect(response.body).toBeInstanceOf(Uint8Array)
+      expect(response.body).toEqual(bytes)
+    })
+
+    it('returns no body for a no-output query', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return new Response(null, { status: 200 })
+      })
+
+      const response = await xrpc(fetchHandler, testNoOutputQuery)
+
+      expect(response.success).toBe(true)
+      expect(response.status).toBe(200)
+      expect(response.body).toBeUndefined()
+      expect(response.encoding).toBeUndefined()
+    })
+
+    it('passes query params as URL search params', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'ok' })
+      })
+
+      await xrpc(fetchHandler, testQuery, { params: { limit: 25 } })
+
+      expect(fetchHandler).toHaveBeenCalledOnce()
+      const [path] = fetchHandler.mock.calls[0]
+      expect(path).toContain('/xrpc/io.example.testQuery')
+      expect(path).toContain('limit=25')
+    })
+
+    it('sends POST with JSON body for procedures', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ id: 'new-id' })
+      })
+
+      await xrpc(fetchHandler, testProcedure, {
+        body: { text: 'test content' },
+      })
+
+      expect(fetchHandler).toHaveBeenCalledOnce()
+      const [, init] = fetchHandler.mock.calls[0]
+      expect(init.method).toBe('POST')
+      expect(new Headers(init.headers).get('content-type')).toBe(
+        'application/json',
+      )
+    })
+
+    it('forwards custom headers', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'ok' })
+      })
+
+      await xrpc(fetchHandler, testQuery, {
+        params: { limit: 1 },
+        headers: { authorization: 'Bearer token123' },
+      })
+
+      expect(fetchHandler).toHaveBeenCalledOnce()
+      const [, init] = fetchHandler.mock.calls[0]
+      expect(new Headers(init.headers).get('authorization')).toBe(
+        'Bearer token123',
+      )
+    })
+
+    it('accepts optional params as omitted', async () => {
+      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' })
+    })
+  })
+
+  describe('error handling', () => {
+    describe('fetch errors', () => {
+      it('throws XrpcFetchError when fetchHandler throws', async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          throw new TypeError('fetch failed')
+        })
+
+        await expect(
+          xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
+        ).rejects.toSatisfy((err) => {
+          assert(err instanceof XrpcFetchError)
+          expect(err).toBeInstanceOf(XrpcInternalError)
+          expect(err.cause).toBeInstanceOf(TypeError)
+          expect(err.message).toContain('fetch failed')
+          return true
+        })
+      })
+
+      it('throws XrpcFetchError when fetchHandler rejects', async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          throw new Error('network timeout')
+        })
+
+        await expect(
+          xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
+        ).rejects.toSatisfy((err) => {
+          assert(err instanceof XrpcFetchError)
+          expect(err.message).toContain('network timeout')
+          expect(err.shouldRetry()).toBe(true)
+          return true
+        })
+      })
+    })
+
+    describe('response errors', () => {
+      it('throws XrpcResponseError for 400 with valid error payload', async () => {
+        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({
+            error: 'TestError',
+            message: 'bad request',
+          })
+          return true
+        })
+      })
+
+      it('throws XrpcAuthenticationError for 401', async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          return Response.json(
+            { error: 'AuthenticationRequired', message: 'Token expired' },
+            { status: 401 },
+          )
+        })
+
+        await expect(
+          xrpc(fetchHandler, testQuery, { params: { limit: 10 } }),
+        ).rejects.toSatisfy((err) => {
+          assert(err instanceof XrpcAuthenticationError)
+          expect(err.status).toBe(401)
+          expect(err.message).toBe('Token expired')
+          return true
+        })
+      })
+
+      it('throws XrpcUpstreamError 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')
+          return true
+        })
+      })
+
+      it('throws XrpcUpstreamError 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')
+          return true
+        })
+      })
+
+      it('Reflects upstream 5xx errors with valid XRPC payload', async () => {
+        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({
+            error: 'ServerError',
+            message: 'Something went wrong',
+          })
+          return true
+        })
+      })
+    })
+
+    describe('invalid response errors', () => {
+      it('throws XrpcInvalidResponseError when response body fails validation', async () => {
+        // Schema expects { value: string } but we return { 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)
+          expect(err.cause).toBeInstanceOf(Error)
+          return true
+        })
+      })
+
+      it('throws XrpcUpstreamError 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)
+          expect(err.message).toContain('application/json')
+          return true
+        })
+      })
+    })
+
+    describe('content-type header errors', () => {
+      it('throws XrpcInternalError when content-type header is set', async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          return Response.json({ value: 'ok' })
+        })
+
+        await expect(
+          xrpc(fetchHandler, testQuery, {
+            params: { limit: 10 },
+            headers: { 'content-type': 'application/json' },
+          }),
+        ).rejects.toSatisfy((err) => {
+          assert(err instanceof XrpcInternalError)
+          expect(err.cause).toBeInstanceOf(TypeError)
+          return true
+        })
+      })
+    })
+
+    describe('response payload parsing', () => {
+      it('throws XrpcUpstreamError 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).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 = 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).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 = vi.fn<FetchHandler>(async () => {
+          return 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 = 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')
+          return true
+        })
+      })
+    })
+
+    describe('content-type handling', () => {
+      it('parses content-type with charset parameter', async () => {
+        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 },
+        })
+
+        expect(response.success).toBe(true)
+        expect(response.body).toEqual({ value: 'hello' })
+      })
+
+      it('handles response with no content-type and empty body as no payload', async () => {
+        const fetchHandler: FetchHandler = async () =>
+          new Response(new ArrayBuffer(0), { status: 200 })
+
+        const response = await xrpc(fetchHandler, testNoOutputQuery)
+
+        expect(response.success).toBe(true)
+        expect(response.body).toBeUndefined()
+      })
+
+      it('treats response with no content-type but non-empty body as binary', async () => {
+        const bytes = new Uint8Array([1, 2, 3])
+        const fetchHandler: FetchHandler = async () =>
+          new Response(bytes, { status: 200 })
+
+        const response = await xrpc(fetchHandler, testBinaryQuery)
+
+        expect(response.success).toBe(true)
+        expect(response.body).toBeInstanceOf(Uint8Array)
+        expect(response.body).toEqual(bytes)
+      })
+    })
+
+    describe('non-2xx non-4xx/5xx responses', () => {
+      it('throws XrpcUpstreamError 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')
+          return true
+        })
+      })
+    })
+  })
+
+  describe('validateRequest', () => {
+    it('rejects invalid query params when enabled', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'ok' })
+      })
+
+      await expect(
+        xrpc(fetchHandler, testQuery, {
+          // @ts-expect-error intentionally passing invalid params
+          params: { limit: 'not-a-number' },
+          validateRequest: true,
+        }),
+      ).rejects.toSatisfy((err) => {
+        assert(err instanceof XrpcInternalError)
+        expect(err).not.toBeInstanceOf(XrpcFetchError)
+        return true
+      })
+    })
+
+    it('rejects invalid procedure body when enabled', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ id: 'abc' })
+      })
+
+      await expect(
+        xrpc(fetchHandler, testProcedure, {
+          // @ts-expect-error intentionally passing invalid body
+          body: { text: 123 },
+          validateRequest: true,
+        }),
+      ).rejects.toSatisfy((err) => {
+        assert(err instanceof XrpcInternalError)
+        expect(err).not.toBeInstanceOf(XrpcFetchError)
+        return true
+      })
+    })
+
+    it('skips body validation by default (invalid body sent as-is)', async () => {
+      const fetchHandler: FetchHandler = async () => Response.json({ id: 'ok' })
+
+      // Invalid body ({ text: 123 }) is not validated client-side
+      const response = await xrpc(fetchHandler, testProcedure, {
+        // @ts-expect-error intentionally passing invalid body
+        body: { text: 123 },
+      })
+
+      expect(response.success).toBe(true)
+      expect(response.body).toEqual({ id: 'ok' })
+    })
+
+    it('succeeds with valid body when enabled', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ id: 'valid' })
+      })
+
+      const response = await xrpc(fetchHandler, testProcedure, {
+        body: { text: 'hello' },
+        validateRequest: true,
+      })
+
+      expect(response.success).toBe(true)
+      expect(response.body).toEqual({ id: 'valid' })
+    })
+  })
+
+  describe('validateResponse', () => {
+    it('rejects invalid response body by default', async () => {
+      // Schema expects { value: string } but server returns { 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)
+        return true
+      })
+    })
+
+    it('accepts invalid response body when disabled', async () => {
+      // Schema expects { value: string } but server returns { value: 123 }
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 123 })
+      })
+
+      const response = await xrpc(fetchHandler, testQuery, {
+        params: { limit: 10 },
+        validateResponse: false,
+      })
+
+      expect(response.success).toBe(true)
+      expect(response.body).toEqual({ value: 123 })
+    })
+
+    it('succeeds with valid response body when enabled', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'hello' })
+      })
+
+      const response = await xrpc(fetchHandler, testQuery, {
+        params: { limit: 10 },
+        validateResponse: true,
+      })
+
+      expect(response.success).toBe(true)
+      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 XrpcUpstreamError)
+        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 XrpcUpstreamError)
+        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 XrpcUpstreamError)
+          expect(err.message).toMatch('Unable to parse response payload')
+          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 XrpcInvalidResponseError)
+        expect(err).toBeInstanceOf(XrpcUpstreamError)
+        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 XrpcUpstreamError)
+        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 = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'hello' })
+      })
+
+      const result = await xrpcSafe(fetchHandler, testQuery, {
+        params: { limit: 5 },
+      })
+
+      assert(result.success)
+      expect(result).toBeInstanceOf(XrpcResponse)
+      expect(result.body).toEqual({ value: 'hello' })
+      expect(result.encoding).toBe('application/json')
+      expect(result.value).toBe(result)
+    })
+
+    it('returns successful result for a JSON procedure', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ id: 'new-id' })
+      })
+
+      const result = await xrpcSafe(fetchHandler, testProcedure, {
+        body: { text: 'hello' },
+      })
+
+      assert(result.success)
+      expect(result.body).toEqual({ id: 'new-id' })
+    })
+
+    it('returns successful result for a binary query', async () => {
+      const bytes = new Uint8Array([5, 6, 7])
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return new Response(bytes, {
+          headers: { 'content-type': 'application/octet-stream' },
+        })
+      })
+
+      const result = await xrpcSafe(fetchHandler, testBinaryQuery)
+
+      assert(result.success)
+      expect(result.body).toBeInstanceOf(Uint8Array)
+      expect(result.body).toEqual(bytes)
+      expect(result.isParsed).toBe(false)
+    })
+
+    it('returns successful result for a binary procedure', async () => {
+      const bytes = new Uint8Array([42])
+      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]),
+        encoding: 'image/jpeg',
+      })
+
+      assert(result.success)
+      expect(result.body).toEqual(bytes)
+    })
+
+    it('returns successful result for a no-output query', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return new Response(null, { status: 200 })
+      })
+
+      const result = await xrpcSafe(fetchHandler, testNoOutputQuery)
+
+      assert(result.success)
+      expect(result.body).toBeUndefined()
+      expect(result.encoding).toBeUndefined()
+    })
+  })
+
+  describe('error handling', () => {
+    describe('fetch errors', () => {
+      it('returns XrpcFetchError when fetchHandler throws', async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          throw new TypeError('fetch failed')
+        })
+
+        const result = await xrpcSafe(fetchHandler, testQuery, {
+          params: { limit: 10 },
+        })
+
+        assert(!result.success)
+        expect(result).toBeInstanceOf(XrpcFetchError)
+        expect(result).toBeInstanceOf(XrpcInternalError)
+      })
+
+      it('returns XrpcFetchError when fetchHandler rejects', async () => {
+        const fetchHandler = vi.fn<FetchHandler>(async () => {
+          throw new Error('network timeout')
+        })
+
+        const result = await xrpcSafe(fetchHandler, testQuery, {
+          params: { limit: 10 },
+        })
+
+        assert(!result.success)
+        expect(result).toBeInstanceOf(XrpcFetchError)
+        expect(result.message).toContain('network timeout')
+      })
+    })
+
+    describe('response errors', () => {
+      it('returns XrpcResponseError for 400 with valid error payload', async () => {
+        const fetchHandler: FetchHandler = async () =>
+          Response.json(
+            { error: 'TestError', message: 'bad request' },
+            { status: 400 },
+          )
+
+        const result = await xrpcSafe(fetchHandler, testQuery, {
+          params: { limit: 10 },
+        })
+
+        assert(!result.success)
+        assert(result instanceof XrpcResponseError)
+        expect(result.status).toBe(400)
+        expect(result.body).toEqual({
+          error: 'TestError',
+          message: 'bad request',
+        })
+      })
+
+      it('returns XrpcAuthenticationError for 401', async () => {
+        const fetchHandler: FetchHandler = async () =>
+          Response.json(
+            { error: 'AuthenticationRequired', message: 'Token expired' },
+            { status: 401 },
+          )
+
+        const result = await xrpcSafe(fetchHandler, testQuery, {
+          params: { limit: 10 },
+        })
+
+        assert(!result.success)
+        assert(result instanceof XrpcResponseError)
+        expect(result).toBeInstanceOf(XrpcAuthenticationError)
+        expect(result.status).toBe(401)
+      })
+
+      it('returns XrpcUpstreamError for non-XRPC error response', async () => {
+        const fetchHandler: FetchHandler = async () =>
+          new Response('Not Found', {
+            status: 404,
+            headers: { 'content-type': 'text/plain' },
+          })
+
+        const result = await xrpcSafe(fetchHandler, testQuery, {
+          params: { limit: 10 },
+        })
+
+        assert(!result.success)
+        expect(result).toBeInstanceOf(XrpcUpstreamError)
+      })
+
+      it('returns XrpcUpstreamError for 500 without valid error payload', async () => {
+        const fetchHandler: FetchHandler = async () =>
+          new Response('Internal Server Error', {
+            status: 500,
+            headers: { 'content-type': 'text/html' },
+          })
+
+        const result = await xrpcSafe(fetchHandler, testQuery, {
+          params: { limit: 10 },
+        })
+
+        assert(!result.success)
+        expect(result).toBeInstanceOf(XrpcUpstreamError)
+      })
+    })
+
+    describe('invalid response errors', () => {
+      it('returns XrpcInvalidResponseError when response body fails validation', async () => {
+        const fetchHandler: FetchHandler = async () =>
+          Response.json({ value: 123 })
+
+        const result = await xrpcSafe(fetchHandler, testQuery, {
+          params: { limit: 10 },
+        })
+
+        assert(!result.success)
+        expect(result).toBeInstanceOf(XrpcInvalidResponseError)
+        expect(result).toBeInstanceOf(XrpcUpstreamError)
+      })
+
+      it('returns XrpcUpstreamError when response has wrong content-type', async () => {
+        const fetchHandler: FetchHandler = async () =>
+          new Response('binary data', {
+            status: 200,
+            headers: { 'content-type': 'text/plain' },
+          })
+
+        const result = await xrpcSafe(fetchHandler, testQuery, {
+          params: { limit: 10 },
+        })
+
+        assert(!result.success)
+        expect(result).toBeInstanceOf(XrpcUpstreamError)
+      })
+    })
+
+    describe('content-type header errors', () => {
+      it('returns XrpcInternalError when content-type header is set', async () => {
+        const fetchHandler: FetchHandler = async () =>
+          Response.json({ value: 'ok' })
+
+        const result = await xrpcSafe(fetchHandler, testQuery, {
+          params: { limit: 10 },
+          headers: { 'content-type': 'application/json' },
+        })
+
+        assert(!result.success)
+        expect(result).toBeInstanceOf(XrpcInternalError)
+        expect(result.cause).toBeInstanceOf(TypeError)
+      })
+    })
+  })
+
+  describe('validateRequest', () => {
+    it('returns XrpcInternalError for invalid query params when enabled', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'ok' })
+      })
+
+      const result = await xrpcSafe(fetchHandler, testQuery, {
+        // @ts-expect-error intentionally passing invalid params
+        params: { limit: 'not-a-number' },
+        validateRequest: true,
+      })
+
+      assert(!result.success)
+      expect(result).toBeInstanceOf(XrpcInternalError)
+      expect(result).not.toBeInstanceOf(XrpcFetchError)
+    })
+
+    it('returns XrpcInternalError for invalid body when enabled', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ id: 'abc' })
+      })
+
+      const result = await xrpcSafe(fetchHandler, testProcedure, {
+        // @ts-expect-error intentionally passing invalid body
+        body: { text: 123 },
+        validateRequest: true,
+      })
+
+      assert(!result.success)
+      expect(result).toBeInstanceOf(XrpcInternalError)
+      expect(result).not.toBeInstanceOf(XrpcFetchError)
+    })
+
+    it('skips body validation by default (invalid body sent as-is)', async () => {
+      const fetchHandler: FetchHandler = async () => Response.json({ id: 'ok' })
+
+      const result = await xrpcSafe(fetchHandler, testProcedure, {
+        // @ts-expect-error intentionally passing invalid body
+        body: { text: 123 },
+      })
+
+      assert(result.success)
+      expect(result.body).toEqual({ id: 'ok' })
+    })
+
+    it('succeeds with valid body when enabled', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ id: 'valid' })
+      })
+
+      const result = await xrpcSafe(fetchHandler, testProcedure, {
+        body: { text: 'hello' },
+        validateRequest: true,
+      })
+
+      assert(result.success)
+      expect(result.body).toEqual({ id: 'valid' })
+    })
+  })
+
+  describe('validateResponse', () => {
+    it('returns XrpcInvalidResponseError 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(XrpcInvalidResponseError)
+      expect(result).toBeInstanceOf(XrpcUpstreamError)
+    })
+
+    it('accepts invalid response body when disabled', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 123 })
+      })
+
+      const result = await xrpcSafe(fetchHandler, testQuery, {
+        params: { limit: 10 },
+        validateResponse: false,
+      })
+
+      assert(result.success)
+      expect(result.body).toEqual({ value: 123 })
+    })
+
+    it('succeeds with valid response body when enabled', async () => {
+      const fetchHandler = vi.fn<FetchHandler>(async () => {
+        return Response.json({ value: 'hello' })
+      })
+
+      const result = await xrpcSafe(fetchHandler, testQuery, {
+        params: { limit: 10 },
+        validateResponse: true,
+      })
+
+      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(XrpcUpstreamError)
+      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(XrpcUpstreamError)
+      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(XrpcUpstreamError)
+      expect(result.message).toBe(
+        'Invalid response: 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(XrpcUpstreamError)
+      expect(result.message).toBe(
+        'Invalid response: 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(XrpcUpstreamError)
+      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(XrpcUpstreamError)
+      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(XrpcUpstreamError)
+      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('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.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(XrpcInvalidResponseError)
+      expect(result).toBeInstanceOf(XrpcUpstreamError)
+    })
+
+    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(XrpcUpstreamError)
+      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')
+    })
+  })
+})