@ikatec/digisac-api-sdk 3.0.0 → 4.0.0

package/src/core/BaseCrudApi.test-d.ts

@@ -0,0 +1,48 @@
+import { expectError, expectType } from 'tsd'
+import type { ApiClient } from './ApiClient'
+import { BaseCrudApi } from './BaseCrudApi'
+import type { Paginated } from './types'
+
+// ── Test model ──────────────────────────────────────────────────────
+
+type Item = { id: string; name: string; tags?: { id: string; label: string }[] }
+type CreateItem = { name: string }
+type UpdateItem = { name?: string }
+
+declare const client: ApiClient
+const api = new BaseCrudApi<Item, CreateItem, UpdateItem>(client, '/items')
+
+// ── getMany overloads ───────────────────────────────────────────────
+
+expectType<Promise<Paginated<Item>>>(api.getMany())
+expectType<Promise<Paginated<Item>>>(api.getMany({ page: 1 }))
+expectType<Promise<Paginated<Item>>>(api.getMany({ paginate: true }))
+expectType<Promise<Item[]>>(api.getMany({ paginate: false }))
+expectType<Promise<Item[]>>(api.getMany({ where: { name: 'x' }, paginate: false }))
+
+// ── getOne / getById ────────────────────────────────────────────────
+
+expectType<Promise<Item | null>>(api.getOne())
+expectType<Promise<Item | null>>(api.getOne({ where: { name: 'x' } }))
+expectType<Promise<Item>>(api.getById('1'))
+expectType<Promise<Item>>(api.getById('1', { include: ['tags'], attributes: ['id'] }))
+
+// getById only accepts include/attributes
+expectError(api.getById('1', { where: { name: 'x' } }))
+expectError(api.getById('1', { attributes: ['missing'] }))
+
+// ── create / updateById / deleteById ────────────────────────────────
+
+expectType<Promise<Item>>(api.create({ name: 'x' }))
+expectType<Promise<Item>>(api.updateById('1', {}))
+expectType<Promise<Item>>(api.deleteById('1'))
+
+expectError(api.create({}))
+expectError(api.create({ name: 1 }))
+expectError(api.updateById('1', { name: 1 }))
+
+// ── Query typing ────────────────────────────────────────────────────
+
+expectError(api.getMany({ where: { missing: 'x' } }))
+expectError(api.getMany({ order: [['missing', 'ASC']] }))
+expectError(api.getMany({ include: ['name'] }))

package/src/core/BaseCrudApi.test.ts

@@ -8,6 +8,10 @@ import type { Paginated } from './types'
 type Item = { id: string; name: string }
 type CreateItem = { name: string }
 type UpdateItem = { name?: string }
+type ItemWithTags = Item & {
+  owner?: { id: string; name: string }
+  tags?: { id: string; label: string }[]
+}
 
 // ── Mock client factory ──────────────────────────────────────────────
 
@@ -23,6 +27,11 @@ function createMockClient(): ApiClient {
   }
 }
 
+/** The URL passed to the nth `client.get` call, with the query string percent-decoded. */
+function calledUrl(client: ApiClient, call = 0): string {
+  return decodeURIComponent(vi.mocked(client.get).mock.calls.at(call)?.at(0) as string)
+}
+
 // ── Tests ────────────────────────────────────────────────────────────
 
 describe('BaseCrudApi', () => {
@@ -73,6 +82,30 @@ describe('BaseCrudApi', () => {
     })
   })
 
+  describe('method binding', () => {
+    it('keeps `this` when methods are destructured', async () => {
+      vi.mocked(client.get).mockResolvedValue([{ id: '1', name: 'x' }])
+      vi.mocked(client.post).mockResolvedValue({ id: '1', name: 'x' })
+      vi.mocked(client.put).mockResolvedValue({ id: '1', name: 'x' })
+      vi.mocked(client.delete).mockResolvedValue({ id: '1', name: 'x' })
+      const { getMany, getOne, getById, create, updateById, deleteById } = api
+
+      await getMany({ paginate: false })
+      await getOne()
+      await getById('1')
+      await create({ name: 'x' })
+      await updateById('1', { name: 'x' })
+      await deleteById('1')
+
+      expect(calledUrl(client, 0)).toBe('/items?paginate=false')
+      expect(calledUrl(client, 1)).toBe('/items?limit=1&paginate=false')
+      expect(calledUrl(client, 2)).toBe('/items/1')
+      expect(client.post).toHaveBeenCalledWith('/items', { name: 'x' }, undefined)
+      expect(client.put).toHaveBeenCalledWith('/items/1', { name: 'x' }, undefined)
+      expect(client.delete).toHaveBeenCalledWith('/items/1', undefined)
+    })
+  })
+
   // ── getMany ──────────────────────────────────────────────────────
 
   describe('getMany', () => {
@@ -122,6 +155,27 @@ describe('BaseCrudApi', () => {
       expect(client.get).toHaveBeenCalledWith('/items', headers)
     })
 
+    it('returns the plain array when paginate is false', async () => {
+      const items: Item[] = [{ id: '1', name: 'a' }]
+      vi.mocked(client.get).mockResolvedValue(items)
+
+      const result = await api.getMany({ paginate: false })
+      expect(calledUrl(client)).toBe('/items?paginate=false')
+      expect(result).toEqual(items)
+    })
+
+    it('omits undefined query values', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      // Explicit undefined is rejected by exactOptionalPropertyTypes but reaches the SDK from JS
+      // callers or from consumers compiled without that flag.
+      const query = { page: 2, perPage: undefined, where: { name: undefined } } as unknown as {
+        page: number
+      }
+      await api.getMany(query)
+      expect(calledUrl(client)).toBe('/items?page=2')
+    })
+
     it('forwards headers with query', async () => {
       vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
       const headers = { Authorization: 'Bearer token' }
@@ -146,6 +200,29 @@ describe('BaseCrudApi', () => {
       expect(result).toEqual(item)
     })
 
+    it('keeps the caller query and forces limit 1 and paginate false', async () => {
+      vi.mocked(client.get).mockResolvedValue([])
+
+      await api.getOne({
+        where: { name: 'x' },
+        order: [['name', 'DESC']],
+        limit: 50,
+        paginate: true,
+      })
+      expect(calledUrl(client)).toBe(
+        '/items?where[name]=x&order[0][0]=name&order[0][1]=DESC&limit=1&paginate=false',
+      )
+    })
+
+    it('returns only the first item when the API returns more than one', async () => {
+      vi.mocked(client.get).mockResolvedValue([
+        { id: '1', name: 'a' },
+        { id: '2', name: 'b' },
+      ])
+
+      expect(await api.getOne()).toEqual({ id: '1', name: 'a' })
+    })
+
     it('returns null when no records match', async () => {
       vi.mocked(client.get).mockResolvedValue([])
 
@@ -174,6 +251,21 @@ describe('BaseCrudApi', () => {
       expect(result).toEqual(item)
     })
 
+    it('serializes include and attributes into the query string', async () => {
+      vi.mocked(client.get).mockResolvedValue({ id: 'abc', name: 'Test' })
+
+      await api.getById('abc', { attributes: ['id', 'name'] })
+      expect(calledUrl(client)).toBe('/items/abc?attributes[0]=id&attributes[1]=name')
+    })
+
+    it('forwards query and headers together', async () => {
+      vi.mocked(client.get).mockResolvedValue({ id: '1', name: 'x' })
+      const headers = { 'X-Tenant': '123' }
+
+      await api.getById('1', { attributes: ['id'] }, headers)
+      expect(client.get).toHaveBeenCalledWith('/items/1?attributes%5B0%5D=id', headers)
+    })
+
     it('forwards custom headers', async () => {
       vi.mocked(client.get).mockResolvedValue({ id: '1', name: 'x' })
       const headers = { 'X-Tenant': '123' }
@@ -269,6 +361,17 @@ describe('BaseCrudApi', () => {
       await expect(api.updateById('1', { name: 'x' })).rejects.toThrow('Conflict')
     })
 
+    it('propagates errors from client.get in getOne', async () => {
+      vi.mocked(client.get).mockRejectedValue(new Error('Unauthorized'))
+      await expect(api.getOne()).rejects.toThrow('Unauthorized')
+    })
+
+    it('rethrows the client error instance unchanged', async () => {
+      const error = Object.assign(new Error('Bad request'), { status: 400 })
+      vi.mocked(client.post).mockRejectedValue(error)
+      await expect(api.create({ name: 'bad' })).rejects.toBe(error)
+    })
+
     it('propagates errors from client.delete in deleteById', async () => {
       vi.mocked(client.delete).mockRejectedValue(new Error('Forbidden'))
       await expect(api.deleteById('1')).rejects.toThrow('Forbidden')
@@ -297,6 +400,53 @@ describe('BaseCrudApi', () => {
       expect(calledUrl).toContain('ASC')
     })
 
+    it('serializes nested include with where and include', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+      const tagsApi = new BaseCrudApi<ItemWithTags, CreateItem>(client, '/items')
+
+      await tagsApi.getMany({
+        include: ['owner', { model: 'tags', where: { label: 'vip' }, required: true }],
+      })
+      expect(calledUrl(client)).toBe(
+        '/items?include[0]=owner&include[1][model]=tags&include[1][where][label]=vip&include[1][required]=true',
+      )
+    })
+
+    it('serializes $in arrays with indices', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({ where: { id: { $in: ['a', 'b'] } } })
+      expect(calledUrl(client)).toBe('/items?where[id][$in][0]=a&where[id][$in][1]=b')
+    })
+
+    it('serializes $or/$and combinators', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({ where: { $or: [{ name: 'a' }, { name: 'b' }] } })
+      expect(calledUrl(client)).toBe('/items?where[$or][0][name]=a&where[$or][1][name]=b')
+    })
+
+    it('serializes order exactly', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({
+        order: [
+          ['name', 'ASC'],
+          ['id', 'desc'],
+        ],
+      })
+      expect(calledUrl(client)).toBe(
+        '/items?order[0][0]=name&order[0][1]=ASC&order[1][0]=id&order[1][1]=desc',
+      )
+    })
+
+    it('serializes booleans and numbers as strings', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({ paranoid: false, distinct: true, limit: 10, offset: 20 })
+      expect(calledUrl(client)).toBe('/items?paranoid=false&distinct=true&limit=10&offset=20')
+    })
+
     it('handles empty query object', async () => {
       vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
 

package/src/core/errors.test-d.ts

@@ -0,0 +1,14 @@
+import { expectAssignable, expectType } from 'tsd'
+import type { ApiError, ErrorClassName, FieldError, ValidationError } from './errors'
+
+declare const apiError: ApiError
+declare const validationError: ValidationError
+
+// ValidationError always carries an array; ApiError may not
+expectType<FieldError[]>(validationError.validationErrors)
+expectType<FieldError[] | null>(apiError.validationErrors)
+
+// errorClass accepts the known backend names and any other string
+expectAssignable<ErrorClassName>('PaymentRequired')
+expectAssignable<ErrorClassName>('SomeFutureError')
+expectType<ErrorClassName | undefined>(apiError.errorClass)

package/src/core/errors.test.ts

@@ -0,0 +1,389 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import {
+  ApiConnectionError,
+  ApiError,
+  AuthenticationError,
+  BadRequestError,
+  ConflictError,
+  DigisacError,
+  InternalServerError,
+  NotFoundError,
+  PaymentRequiredError,
+  PermissionDeniedError,
+  RateLimitError,
+  UnprocessableEntityError,
+  ValidationError,
+  parseFieldErrors,
+} from './errors'
+
+const fromResponse = (status: number, body?: unknown, headers: Record<string, string> = {}) =>
+  ApiError.fromResponse(status, 'Status Text', new Headers(headers), body)
+
+describe('errors', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  // ── parseFieldErrors ─────────────────────────────────────────────
+
+  describe('parseFieldErrors', () => {
+    it('flattens one entry per message with location, field, path and code', () => {
+      expect(
+        parseFieldErrors({
+          body: {
+            title: {
+              messages: ['Required.', 'Too long.'],
+              types: ['required', 'hasLengthLesserThanOrEqual'],
+            },
+          },
+          query: { page: { messages: ['Should be a number.'], types: ['number'] } },
+        }),
+      ).toEqual([
+        {
+          location: 'body',
+          field: 'title',
+          path: 'body.title',
+          message: 'Required.',
+          code: 'required',
+        },
+        {
+          location: 'body',
+          field: 'title',
+          path: 'body.title',
+          message: 'Too long.',
+          code: 'hasLengthLesserThanOrEqual',
+        },
+        {
+          location: 'query',
+          field: 'page',
+          path: 'query.page',
+          message: 'Should be a number.',
+          code: 'number',
+        },
+      ])
+    })
+
+    it('falls back to the first type when there are fewer types than messages', () => {
+      expect(
+        parseFieldErrors({ body: { name: { messages: ['a', 'b'], types: ['required'] } } }),
+      ).toMatchObject([{ code: 'required' }, { code: 'required' }])
+    })
+
+    it('uses an empty code when there are no types', () => {
+      expect(parseFieldErrors({ body: { name: { messages: ['Required.'] } } })).toMatchObject([
+        { message: 'Required.', code: '' },
+      ])
+    })
+
+    it('stringifies non-string messages and types', () => {
+      expect(parseFieldErrors({ body: { n: { messages: [42], types: [true] } } })).toMatchObject([
+        { message: '42', code: 'true' },
+      ])
+    })
+
+    it('skips fields without a messages array', () => {
+      expect(
+        parseFieldErrors({
+          body: {
+            a: { messages: 'Required.' },
+            b: { types: ['required'] },
+            c: 'Required.',
+            d: null,
+            e: ['Required.'],
+            ok: { messages: ['Required.'], types: ['required'] },
+          },
+        }),
+      ).toEqual([
+        { location: 'body', field: 'ok', path: 'body.ok', message: 'Required.', code: 'required' },
+      ])
+    })
+
+    it('skips locations that are not objects', () => {
+      expect(parseFieldErrors({ body: 'invalid', params: [], query: null })).toBeNull()
+    })
+
+    it.each([
+      ['undefined', undefined],
+      ['null', null],
+      ['a string', 'invalid'],
+      ['an array', [{ path: 'name', message: 'required' }]],
+      ['an empty object', {}],
+      ['locations without fields', { body: {} }],
+    ])('returns null for %s', (_label, input) => {
+      expect(parseFieldErrors(input)).toBeNull()
+    })
+  })
+
+  // ── Class hierarchy ──────────────────────────────────────────────
+
+  describe('DigisacError', () => {
+    it('is an Error with name DigisacError', () => {
+      const error = new DigisacError('boom')
+      expect(error).toBeInstanceOf(Error)
+      expect(error).toMatchObject({ name: 'DigisacError', message: 'boom' })
+    })
+
+    it('keeps the cause', () => {
+      const cause = new Error('root')
+      expect(new DigisacError('boom', { cause }).cause).toBe(cause)
+    })
+  })
+
+  describe('ApiConnectionError', () => {
+    it('extends DigisacError but not ApiError', () => {
+      const error = new ApiConnectionError()
+      expect(error).toBeInstanceOf(DigisacError)
+      expect(error).not.toBeInstanceOf(ApiError)
+      expect(error).toMatchObject({ name: 'ApiConnectionError', message: 'Connection error.' })
+    })
+
+    it('keeps the message and cause', () => {
+      const cause = new TypeError('fetch failed')
+      const error = new ApiConnectionError('Request failed', { cause })
+      expect(error).toMatchObject({ message: 'Request failed', cause })
+    })
+  })
+
+  describe('ValidationError constructor', () => {
+    it('turns a null validationErrors into an empty array', () => {
+      const error = new ValidationError('Invalid', 'ValidationError', 400)
+      expect(error.validationErrors).toEqual([])
+      expect(error.name).toBe('ValidationError')
+    })
+  })
+
+  describe('ApiError constructor', () => {
+    it('keeps the positional arguments backward compatible', () => {
+      const error = new ApiError('Not found', 'NotFoundHttpError', 404)
+      expect(error).toBeInstanceOf(DigisacError)
+      expect(error).toMatchObject({
+        name: 'ApiError',
+        message: 'Not found',
+        errorClass: 'NotFoundHttpError',
+        status: 404,
+        validationErrors: null,
+        headers: undefined,
+        body: undefined,
+      })
+    })
+
+    it('accepts headers and body', () => {
+      const headers = new Headers({ 'X-Request-Id': 'req-1' })
+      const error = new ApiError('x', undefined, 500, null, { headers, body: 'raw' })
+      expect(error.headers).toBe(headers)
+      expect(error.body).toBe('raw')
+    })
+  })
+
+  // ── ApiError.fromResponse ────────────────────────────────────────
+
+  describe('ApiError.fromResponse', () => {
+    it.each([
+      [400, BadRequestError, 'BadRequestError'],
+      [401, AuthenticationError, 'AuthenticationError'],
+      [402, PaymentRequiredError, 'PaymentRequiredError'],
+      [403, PermissionDeniedError, 'PermissionDeniedError'],
+      [404, NotFoundError, 'NotFoundError'],
+      [409, ConflictError, 'ConflictError'],
+      [422, UnprocessableEntityError, 'UnprocessableEntityError'],
+      [429, RateLimitError, 'RateLimitError'],
+      [500, InternalServerError, 'InternalServerError'],
+      [502, InternalServerError, 'InternalServerError'],
+      [599, InternalServerError, 'InternalServerError'],
+    ])('maps %i to %o', (status, ErrorClass, name) => {
+      const error = fromResponse(status)
+      expect(error).toBeInstanceOf(ErrorClass)
+      expect(error).toBeInstanceOf(ApiError)
+      expect(error).toBeInstanceOf(DigisacError)
+      expect(error).toMatchObject({ name, status })
+    })
+
+    it.each([405, 408, 410, 418, 499])('maps unlisted status %i to a plain ApiError', (status) => {
+      const error = fromResponse(status)
+      expect(Object.getPrototypeOf(error)).toBe(ApiError.prototype)
+      expect(error.name).toBe('ApiError')
+    })
+
+    describe('ValidationError', () => {
+      it('throws ValidationError for a 400 ValidationError, with its field errors', () => {
+        const error = fromResponse(400, {
+          error: 'ValidationError',
+          errors: { body: { name: { messages: ['Required.'], types: ['required'] } } },
+        })
+        expect(error).toBeInstanceOf(ValidationError)
+        expect(error).toBeInstanceOf(BadRequestError)
+        expect(error).toBeInstanceOf(ApiError)
+        expect(error).toMatchObject({
+          name: 'ValidationError',
+          errorClass: 'ValidationError',
+          validationErrors: [{ path: 'body.name', code: 'required' }],
+        })
+      })
+
+      it('gives ValidationError an empty validationErrors when there are no field details', () => {
+        const error = fromResponse(400, { error: 'ValidationError', message: 'Invalid file size.' })
+        expect(error).toBeInstanceOf(ValidationError)
+        expect(error.validationErrors).toEqual([])
+      })
+
+      it('keeps the status class for other backend names', () => {
+        const error = fromResponse(402, { error: 'PaymentRequired' })
+        expect(Object.getPrototypeOf(error)).toBe(PaymentRequiredError.prototype)
+      })
+
+      it.each([
+        ['ValidationError', 422, UnprocessableEntityError],
+        ['ValidationError', 500, InternalServerError],
+      ])('uses the status class for %s with status %i', (errorClass, status, ErrorClass) => {
+        const error = fromResponse(status, { error: errorClass })
+        expect(Object.getPrototypeOf(error)).toBe(ErrorClass.prototype)
+        expect(error.errorClass).toBe(errorClass)
+      })
+
+      it.each(['NotFoundHttpError', 'HttpError', 'constructor', 'toString', '__proto__'])(
+        'uses the status class for %s',
+        (errorClass) => {
+          const error = fromResponse(404, { error: errorClass })
+          expect(Object.getPrototypeOf(error)).toBe(NotFoundError.prototype)
+        },
+      )
+    })
+
+    it('reads message, errorClass and field errors from the backend body', () => {
+      const body = {
+        error: 'ValidationError',
+        message: 'The given data was invalid.',
+        status: 400,
+        errors: { body: { name: { messages: ['Required.'], types: ['required'] } } },
+      }
+      const headers = { 'Content-Type': 'application/json' }
+      const error = fromResponse(400, body, headers)
+      expect(error).toMatchObject({
+        message: 'The given data was invalid.',
+        errorClass: 'ValidationError',
+        validationErrors: [{ path: 'body.name', code: 'required' }],
+        body,
+      })
+      expect(error.headers?.get('Content-Type')).toBe('application/json')
+    })
+
+    it('uses the error name as message when message is missing or empty', () => {
+      expect(fromResponse(403, { error: 'AccessDenied' }).message).toBe('AccessDenied')
+      expect(fromResponse(403, { error: 'AccessDenied', message: '' }).message).toBe('AccessDenied')
+    })
+
+    it('uses the default message when the body has neither message nor error', () => {
+      expect(fromResponse(500, {}).message).toBe('HTTP Error 500: Status Text')
+    })
+
+    it('ignores non-string message and error', () => {
+      const error = fromResponse(400, { error: 123, message: { text: 'x' } })
+      expect(error).toMatchObject({
+        message: 'HTTP Error 400: Status Text',
+        errorClass: undefined,
+      })
+    })
+
+    it.each([
+      ['undefined', undefined],
+      ['a string', '<html>bad gateway</html>'],
+      ['an array', ['error']],
+      ['null', null],
+    ])('uses the default message when the body is %s and keeps it as body', (_label, body) => {
+      const error = fromResponse(502, body)
+      expect(error).toMatchObject({
+        message: 'HTTP Error 502: Status Text',
+        errorClass: undefined,
+        validationErrors: null,
+        body,
+      })
+    })
+  })
+
+  // ── RateLimitError.retryAfter ────────────────────────────────────
+
+  describe('RateLimitError.retryAfter', () => {
+    const retryAfter = (value?: string) =>
+      (
+        fromResponse(
+          429,
+          undefined,
+          value === undefined ? {} : { 'Retry-After': value },
+        ) as RateLimitError
+      ).retryAfter
+
+    it('reads delay seconds', () => {
+      expect(retryAfter('120')).toBe(120)
+      expect(retryAfter('0')).toBe(0)
+      expect(retryAfter('1.5')).toBe(1.5)
+    })
+
+    it('clamps negative seconds to 0', () => {
+      expect(retryAfter('-5')).toBe(0)
+    })
+
+    it('reads an HTTP date as seconds from now, rounded up', () => {
+      vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00.500Z') })
+      expect(retryAfter('Thu, 01 Jan 2026 00:00:30 GMT')).toBe(30)
+    })
+
+    it('returns 0 for an HTTP date in the past', () => {
+      vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00Z') })
+      expect(retryAfter('Wed, 31 Dec 2025 23:59:00 GMT')).toBe(0)
+    })
+
+    it('returns null when the header is missing, empty or invalid', () => {
+      expect(retryAfter()).toBeNull()
+      expect(retryAfter('')).toBeNull()
+      expect(retryAfter('soon')).toBeNull()
+    })
+
+    it('returns null for a whitespace-only header', () => {
+      expect(retryAfter('  ')).toBeNull()
+    })
+
+    describe('X-RateLimit-Reset (Digisac backend)', () => {
+      const withHeaders = (headers: Record<string, string>) =>
+        (fromResponse(429, undefined, headers) as RateLimitError).retryAfter
+
+      it('reads a Unix time in seconds as seconds from now, rounded up', () => {
+        vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00.500Z') })
+        const resetsAt = Date.parse('2026-01-01T00:10:00Z') / 1000
+        expect(withHeaders({ 'X-RateLimit-Reset': String(resetsAt) })).toBe(600)
+      })
+
+      it('returns 0 for a reset time in the past', () => {
+        vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00Z') })
+        const resetsAt = Date.parse('2025-12-31T23:00:00Z') / 1000
+        expect(withHeaders({ 'X-RateLimit-Reset': String(resetsAt) })).toBe(0)
+      })
+
+      it('reads small values as delay seconds', () => {
+        expect(withHeaders({ 'X-RateLimit-Reset': '45' })).toBe(45)
+        expect(withHeaders({ 'X-RateLimit-Reset': '0' })).toBe(0)
+        expect(withHeaders({ 'X-RateLimit-Reset': '-3' })).toBe(0)
+      })
+
+      it('matches the header name case-insensitively', () => {
+        expect(withHeaders({ 'x-ratelimit-reset': '45' })).toBe(45)
+      })
+
+      it('prefers Retry-After when both headers are present', () => {
+        expect(withHeaders({ 'Retry-After': '10', 'X-RateLimit-Reset': '45' })).toBe(10)
+      })
+
+      it('falls back to X-RateLimit-Reset when Retry-After is invalid', () => {
+        expect(withHeaders({ 'Retry-After': 'soon', 'X-RateLimit-Reset': '45' })).toBe(45)
+      })
+
+      it('returns null when the header is empty or not a number', () => {
+        expect(withHeaders({ 'X-RateLimit-Reset': '' })).toBeNull()
+        expect(withHeaders({ 'X-RateLimit-Reset': 'tomorrow' })).toBeNull()
+      })
+    })
+
+    it('returns null when the error has no headers', () => {
+      expect(new RateLimitError('x', undefined, 429).retryAfter).toBeNull()
+    })
+  })
+})