@ikatec/digisac-api-sdk 3.1.0 → 4.1.0

package/src/core/bindMethods.ts

@@ -0,0 +1,26 @@
+/**
+ * Binds every method of `instance`'s class chain (up to `Object.prototype`) to `instance`, as own
+ * properties, so methods keep working when destructured (`const { getMany } = api`). The most
+ * derived implementation wins; getters, setters and `constructor` are skipped.
+ */
+export function bindMethods(instance: object): void {
+  const target = instance as Record<PropertyKey, unknown>
+  const bound = new Set<PropertyKey>()
+
+  for (
+    let prototype: object | null = Object.getPrototypeOf(instance);
+    prototype && prototype !== Object.prototype;
+    prototype = Object.getPrototypeOf(prototype)
+  ) {
+    for (const key of Reflect.ownKeys(prototype)) {
+      if (key === 'constructor' || bound.has(key)) {
+        continue
+      }
+      const { value } = Object.getOwnPropertyDescriptor(prototype, key) as PropertyDescriptor
+      if (typeof value === 'function') {
+        target[key] = value.bind(instance)
+        bound.add(key)
+      }
+    }
+  }
+}

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()
+    })
+  })
+})