@ikatec/digisac-api-sdk 3.1.0 → 4.1.0

package/src/core/errors.ts

@@ -0,0 +1,284 @@
+/**
+ * A field-level error from the backend `validate` middleware — one entry per failed rule.
+ */
+export interface FieldError {
+  /** Where the field was read from: `body`, `params`, `query`, `headers` or `cookies`. */
+  location: string
+  /** The field name, e.g. `name`. */
+  field: string
+  /** `<location>.<field>`, e.g. `body.name`. */
+  path: string
+  message: string
+  /** The failed rule, e.g. `required` or `hasLengthLesserThanOrEqual`. */
+  code: string
+}
+
+/**
+ * The backend error name sent as `error` in the body (`ApiError.errorClass`). Known names are listed
+ * for autocomplete; any other string is still accepted. `HttpError` is the generic one: most 400s
+ * and every unexpected 500.
+ */
+export type ErrorClassName =
+  | 'HttpError'
+  | 'ValidationError'
+  | 'BadRequestHttpError'
+  | 'UnauthorizedHttpError'
+  | 'PaymentRequired'
+  | 'ForbiddenHttpError'
+  | 'NotFoundHttpError'
+  | 'TooManyRequestsHttpError'
+  | (string & {})
+
+export interface ApiErrorOptions {
+  /** Response headers. */
+  headers?: Headers
+  /** The parsed JSON error body, or the raw text when it is not JSON. */
+  body?: unknown
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+/**
+ * Flattens the backend `errors` object — `{ <location>: { <field>: { messages: string[], types: string[] } } }`
+ * — into one {@link FieldError} per message. Returns `null` when there are no field errors.
+ */
+export function parseFieldErrors(errors: unknown): FieldError[] | null {
+  if (!isRecord(errors)) {
+    return null
+  }
+
+  const parsed: FieldError[] = []
+  for (const [location, fields] of Object.entries(errors)) {
+    if (!isRecord(fields)) {
+      continue
+    }
+    for (const [field, detail] of Object.entries(fields)) {
+      if (!isRecord(detail)) {
+        continue
+      }
+      const messages = Array.isArray(detail.messages) ? detail.messages.map(String) : []
+      const types = Array.isArray(detail.types) ? detail.types.map(String) : []
+      messages.forEach((message, index) => {
+        parsed.push({
+          location,
+          field,
+          path: `${location}.${field}`,
+          message,
+          code: types[index] ?? types[0] ?? '',
+        })
+      })
+    }
+  }
+
+  return parsed.length ? parsed : null
+}
+
+/** Base class of every error thrown by the SDK. */
+export class DigisacError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'DigisacError'
+  }
+}
+
+/** The request never got an HTTP response (network failure, DNS, connection refused, ...). */
+export class ApiConnectionError extends DigisacError {
+  constructor(message = 'Connection error.', options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'ApiConnectionError'
+  }
+}
+
+/**
+ * The API answered with a non-2xx status. Thrown as the subclass matching the status
+ * (`NotFoundError`, `BadRequestError`, ...) — or `ValidationError` for a 400 field validation
+ * failure — so callers can narrow with `instanceof`.
+ */
+export class ApiError extends DigisacError {
+  /** The backend error name (`error` in the body), e.g. `ValidationError` or `PaymentRequired`. */
+  public readonly errorClass?: ErrorClassName | undefined
+  public readonly status?: number | undefined
+  /** Field errors of a 400 `ValidationError`; `null` when the response carries none. */
+  public readonly validationErrors: FieldError[] | null
+  public readonly headers?: Headers | undefined
+  /** The parsed JSON error body (`{ error, message, status, errors?, extra? }`), or the raw text. */
+  public readonly body?: unknown
+
+  constructor(
+    message: string,
+    errorClass?: ErrorClassName,
+    status?: number,
+    validationErrors: FieldError[] | null = null,
+    options: ApiErrorOptions = {},
+  ) {
+    super(message)
+    this.name = 'ApiError'
+    this.errorClass = errorClass
+    this.status = status
+    this.validationErrors = validationErrors
+    this.headers = options.headers
+    this.body = options.body
+  }
+
+  /**
+   * Builds the `ApiError` subclass for a response and its (already read) body: `ValidationError`
+   * for a 400 `ValidationError`, else the class of the status.
+   */
+  static fromResponse(
+    status: number,
+    statusText: string,
+    headers: Headers,
+    body: unknown,
+  ): ApiError {
+    let message = `HTTP Error ${status}: ${statusText}`
+    let errorClass: string | undefined
+    let validationErrors: FieldError[] | null = null
+
+    if (isRecord(body)) {
+      const apiMessage = typeof body.message === 'string' ? body.message : undefined
+      errorClass = typeof body.error === 'string' ? body.error : undefined
+      message = apiMessage || errorClass || message
+      validationErrors = parseFieldErrors(body.errors)
+    }
+
+    const ErrorClass = errorClassFor(status, errorClass)
+    return new ErrorClass(message, errorClass, status, validationErrors, { headers, body })
+  }
+}
+
+/** 400 (see {@link ValidationError} for field validation failures). */
+export class BadRequestError extends ApiError {
+  override name = 'BadRequestError'
+}
+
+/**
+ * 400 `ValidationError` — the request failed field validation. `validationErrors` is always an
+ * array here (empty when the backend sent no field details).
+ */
+export class ValidationError extends BadRequestError {
+  override name = 'ValidationError'
+  declare public readonly validationErrors: FieldError[]
+
+  constructor(
+    message: string,
+    errorClass?: ErrorClassName,
+    status?: number,
+    validationErrors: FieldError[] | null = null,
+    options: ApiErrorOptions = {},
+  ) {
+    super(message, errorClass, status, validationErrors ?? [], options)
+  }
+}
+
+/** 401 — missing or invalid access token. */
+export class AuthenticationError extends ApiError {
+  override name = 'AuthenticationError'
+}
+
+/** 402 — the account is out of credits or over a plan limit. */
+export class PaymentRequiredError extends ApiError {
+  override name = 'PaymentRequiredError'
+}
+
+/** 403 — the user lacks the permission for this action. */
+export class PermissionDeniedError extends ApiError {
+  override name = 'PermissionDeniedError'
+}
+
+/** 404 */
+export class NotFoundError extends ApiError {
+  override name = 'NotFoundError'
+}
+
+/** 409 */
+export class ConflictError extends ApiError {
+  override name = 'ConflictError'
+}
+
+/** 422 */
+export class UnprocessableEntityError extends ApiError {
+  override name = 'UnprocessableEntityError'
+}
+
+/** 429 */
+export class RateLimitError extends ApiError {
+  override name = 'RateLimitError'
+
+  /**
+   * Seconds to wait before retrying, or `null` when the response does not say.
+   *
+   * Reads the standard `Retry-After` header (delay seconds or HTTP date) first, then the
+   * `X-RateLimit-Reset` header the Digisac backend sends (Unix time in seconds).
+   */
+  get retryAfter(): number | null {
+    return (
+      parseRetryAfter(this.headers?.get('Retry-After')) ??
+      parseRateLimitReset(this.headers?.get('X-RateLimit-Reset'))
+    )
+  }
+}
+
+const secondsUntil = (epochMs: number): number =>
+  Math.max(0, Math.ceil((epochMs - Date.now()) / 1000))
+
+/** `Retry-After`: delay seconds or an HTTP date. */
+function parseRetryAfter(value: string | null | undefined): number | null {
+  if (!value?.trim()) {
+    return null
+  }
+  const seconds = Number(value)
+  if (Number.isFinite(seconds)) {
+    return Math.max(0, seconds)
+  }
+  const date = Date.parse(value)
+  return Number.isNaN(date) ? null : secondsUntil(date)
+}
+
+/**
+ * `X-RateLimit-Reset`: Unix time in seconds (what the Digisac backend sends). Small values are
+ * read as delay seconds instead, the other convention in use for this header.
+ */
+function parseRateLimitReset(value: string | null | undefined): number | null {
+  if (!value?.trim()) {
+    return null
+  }
+  const reset = Number(value)
+  if (!Number.isFinite(reset)) {
+    return null
+  }
+  // Anything before 2001-09-09 (1e9 s) can't be a reset time, so it is a delay.
+  return reset < 1e9 ? Math.max(0, reset) : secondsUntil(reset * 1000)
+}
+
+/** 5xx */
+export class InternalServerError extends ApiError {
+  override name = 'InternalServerError'
+}
+
+function errorClassFor(status: number, errorClass: string | undefined): typeof ApiError {
+  if (status === 400 && errorClass === 'ValidationError') {
+    return ValidationError
+  }
+
+  switch (status) {
+    case 400:
+      return BadRequestError
+    case 401:
+      return AuthenticationError
+    case 402:
+      return PaymentRequiredError
+    case 403:
+      return PermissionDeniedError
+    case 404:
+      return NotFoundError
+    case 409:
+      return ConflictError
+    case 422:
+      return UnprocessableEntityError
+    case 429:
+      return RateLimitError
+    default:
+      return status >= 500 ? InternalServerError : ApiError
+  }
+}

package/src/core/index.ts

@@ -1,6 +1,25 @@
 export type { ApiClient, HttpMethod } from './ApiClient'
-export { BaseApiClient, ApiError } from './BaseApiClient'
-export type { ValidationError } from './BaseApiClient'
+export { BaseApiClient } from './BaseApiClient'
+export type { BaseApiClientOptions } from './BaseApiClient'
+export type { QueryFormat } from './queryString'
+export {
+  DigisacError,
+  ApiConnectionError,
+  ApiError,
+  BadRequestError,
+  ValidationError,
+  AuthenticationError,
+  PaymentRequiredError,
+  PermissionDeniedError,
+  NotFoundError,
+  ConflictError,
+  UnprocessableEntityError,
+  RateLimitError,
+  InternalServerError,
+  parseFieldErrors,
+} from './errors'
+export type { FieldError, ErrorClassName, ApiErrorOptions } from './errors'
+export { BaseApi } from './BaseApi'
 export { BaseCrudApi } from './BaseCrudApi'
 export { ArchivableCrudApi } from './ArchivableCrudApi'
 export type { WhereClause, IncludeItem, ListQuery, GetByIdQuery, Paginated } from './types'

package/src/core/queryString.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest'
+import qs from 'qs'
+import { toQueryString } from './queryString'
+
+/** Decodes a `?query=<JSON>` string back into the query object. */
+const decodeJson = (queryString: string): unknown =>
+  JSON.parse(new URLSearchParams(queryString.slice(1)).get('query') as string)
+
+describe('toQueryString', () => {
+  it.each([
+    ['undefined', undefined],
+    ['null', null],
+    ['an empty object', {}],
+    ['only undefined values', { page: undefined, where: undefined }],
+  ])('returns an empty string for %s', (_label, query) => {
+    expect(toQueryString(query, 'json')).toBe('')
+    expect(toQueryString(query, 'qs')).toBe('')
+  })
+
+  it("defaults to 'json'", () => {
+    expect(toQueryString({ page: 1 })).toBe(toQueryString({ page: 1 }, 'json'))
+  })
+
+  describe("'json'", () => {
+    it('sends ?query=<JSON>', () => {
+      expect(toQueryString({ page: 2 }, 'json')).toBe(`?query=${encodeURIComponent('{"page":2}')}`)
+    })
+
+    it('round-trips null, booleans, numbers, dates and deep nesting', () => {
+      const query = {
+        where: { deletedAt: null, isArchived: false, createdAt: { $gte: new Date('2026-01-01Z') } },
+        include: [{ model: 'a', include: [{ model: 'b', where: { id: { $in: ['x', 'y'] } } }] }],
+        limit: 10,
+      }
+      expect(decodeJson(toQueryString(query, 'json'))).toEqual({
+        ...query,
+        where: { ...query.where, createdAt: { $gte: '2026-01-01T00:00:00.000Z' } },
+      })
+    })
+
+    it('drops undefined values', () => {
+      expect(decodeJson(toQueryString({ page: 1, where: { name: undefined } }, 'json'))).toEqual({
+        page: 1,
+        where: {},
+      })
+    })
+
+    it('encodes characters that are special in URLs', () => {
+      const queryString = toQueryString({ where: { name: 'a&b=c?#%+ ' } }, 'json')
+      expect(queryString.slice('?query='.length)).not.toMatch(/[&=?#+ ]/)
+      expect(decodeJson(queryString)).toEqual({ where: { name: 'a&b=c?#%+ ' } })
+    })
+  })
+
+  describe("'qs'", () => {
+    it('sends bracket notation', () => {
+      expect(decodeURIComponent(toQueryString({ where: { name: 'x' }, page: 2 }, 'qs'))).toBe(
+        '?where[name]=x&page=2',
+      )
+    })
+
+    it('matches qs.stringify', () => {
+      const query = { where: { id: { $in: ['a', 'b'] } }, order: [['name', 'ASC']] }
+      expect(toQueryString(query, 'qs')).toBe(`?${qs.stringify(query)}`)
+    })
+
+    it('drops undefined values', () => {
+      expect(toQueryString({ page: 1, perPage: undefined }, 'qs')).toBe('?page=1')
+    })
+  })
+})

package/src/core/queryString.ts

@@ -0,0 +1,30 @@
+import qs from 'qs'
+
+/**
+ * How list/get queries (`where`, `include`, `order`, ...) are put in the URL:
+ *
+ * - `'json'` — `?query=<JSON>`, merged into `req.query` by the backend `parseQuery` middleware.
+ *   Keeps `null`, booleans and numbers typed and has no nesting limit.
+ * - `'qs'` — bracket notation (`?where[name]=x&page=2`). Readable, but the backend parses it with
+ *   `qs` defaults: `null` arrives as `''`, booleans/numbers as strings, and objects nested deeper
+ *   than 5 levels (e.g. an `include` inside an `include` with a `where`) are mangled.
+ */
+export type QueryFormat = 'json' | 'qs'
+
+export const DEFAULT_QUERY_FORMAT: QueryFormat = 'json'
+
+/** Serializes a query in `format`, or returns `''` when there is nothing to send. */
+export function toQueryString(
+  query?: object | null,
+  format: QueryFormat = DEFAULT_QUERY_FORMAT,
+): string {
+  if (!query) {
+    return ''
+  }
+  if (format === 'qs') {
+    const queryString = qs.stringify(query)
+    return queryString ? `?${queryString}` : ''
+  }
+  const json = JSON.stringify(query)
+  return json === '{}' ? '' : `?query=${encodeURIComponent(json)}`
+}

package/src/core/types.ts

@@ -125,6 +125,11 @@ export interface HasGetMany<TResponse, TQuery extends ListQuery<TResponse> = Lis
     query?: TQuery & { paginate?: true },
     headers?: Record<string, string>,
   ): Promise<Paginated<TResponse>>
+  /** When `paginate` is only known at runtime (e.g. a `boolean` variable). */
+  getMany(
+    query?: TQuery,
+    headers?: Record<string, string>,
+  ): Promise<Paginated<TResponse> | TResponse[]>
 }
 
 export type GetByIdQuery<T = Record<string, unknown>> = Pick<ListQuery<T>, 'include' | 'attributes'>

package/src/core/withQueryFormat.test.ts

@@ -0,0 +1,136 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { ApiClient } from './ApiClient'
+import { BaseApiClient } from './BaseApiClient'
+import { BaseCrudApi } from './BaseCrudApi'
+import { StickerUsersApi } from '../apis/stickerUsers/StickerUsersApi'
+import { TermsApi } from '../apis/terms/TermsApi'
+
+type Item = { id: string; name: string }
+
+class ItemsApi extends BaseCrudApi<Item, { name: string }> {
+  constructor(client: ApiClient) {
+    super(client, '/items')
+    this.searchByName = this.searchByName.bind(this)
+  }
+
+  searchByName(name: string) {
+    return this.getMany({ where: { name }, paginate: false })
+  }
+}
+
+function createMockClient(): ApiClient {
+  return {
+    setAccessToken: vi.fn().mockReturnThis(),
+    request: vi.fn(),
+    get: vi.fn().mockResolvedValue([]),
+    post: vi.fn(),
+    put: vi.fn(),
+    patch: vi.fn(),
+    delete: vi.fn(),
+  }
+}
+
+const calledUrl = (client: ApiClient, call = 0) =>
+  decodeURIComponent(vi.mocked(client.get).mock.calls.at(call)?.at(0) as string)
+
+const JSON_QUERY = '/items?query={"where":{"name":"x"},"paginate":false}'
+const QS_QUERY = '/items?where[name]=x&paginate=false'
+
+describe('withQueryFormat', () => {
+  let client: ApiClient
+  let api: ItemsApi
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new ItemsApi(client)
+  })
+
+  it('returns a copy that uses the given format', async () => {
+    await api.withQueryFormat('qs').getMany({ where: { name: 'x' }, paginate: false })
+    expect(calledUrl(client)).toBe(QS_QUERY)
+  })
+
+  it('leaves the original API unchanged', async () => {
+    api.withQueryFormat('qs')
+    await api.getMany({ where: { name: 'x' }, paginate: false })
+    expect(calledUrl(client)).toBe(JSON_QUERY)
+    expect(api.client).toBe(client)
+  })
+
+  it('keeps the class, basePath and fields', () => {
+    const copy = api.withQueryFormat('qs')
+    expect(copy).toBeInstanceOf(ItemsApi)
+    expect(copy).toBeInstanceOf(BaseCrudApi)
+    expect(copy.basePath).toBe('/items')
+    expect(copy).not.toBe(api)
+  })
+
+  it('binds destructured methods to the copy', async () => {
+    const { getMany, getOne, getById } = api.withQueryFormat('qs')
+    await getMany({ where: { name: 'x' }, paginate: false })
+    await getOne({ where: { name: 'x' } })
+    await getById('1', { attributes: ['id'] })
+    expect(calledUrl(client, 0)).toBe(QS_QUERY)
+    expect(calledUrl(client, 1)).toBe('/items?where[name]=x&limit=1&paginate=false')
+    expect(calledUrl(client, 2)).toBe('/items/1?attributes[0]=id')
+  })
+
+  it('rebinds methods bound by subclass constructors', async () => {
+    const { searchByName } = api.withQueryFormat('qs')
+    await searchByName('x')
+    expect(calledUrl(client)).toBe(QS_QUERY)
+  })
+
+  it('can be chained again', async () => {
+    await api.withQueryFormat('qs').withQueryFormat('json').searchByName('x')
+    expect(calledUrl(client)).toBe(JSON_QUERY)
+  })
+
+  it('overrides a qs client back to json', async () => {
+    const qsApi = new ItemsApi(Object.assign(createMockClient(), { queryFormat: 'qs' as const }))
+    await qsApi.withQueryFormat('json').searchByName('x')
+    expect(calledUrl(qsApi.client)).toBe(JSON_QUERY)
+  })
+
+  it('still sends requests through the original client', async () => {
+    const copy = api.withQueryFormat('qs')
+    await copy.create({ name: 'x' })
+    expect(client.post).toHaveBeenCalledWith('/items', { name: 'x' }, undefined)
+    expect(copy.client.queryFormat).toBe('qs')
+    expect(client.queryFormat).toBeUndefined()
+  })
+
+  it('works on APIs that do not extend BaseCrudApi', async () => {
+    await new StickerUsersApi(client).withQueryFormat('qs').getMany({ page: 2 })
+    await new TermsApi(client).withQueryFormat('qs').getById('t1', { attributes: ['id'] })
+    expect(calledUrl(client, 0)).toBe('/sticker-users?page=2')
+    expect(calledUrl(client, 1)).toBe('/terms/t1?attributes[0]=id')
+  })
+
+  describe('with BaseApiClient', () => {
+    afterEach(() => {
+      vi.restoreAllMocks()
+    })
+
+    const mockFetch = () =>
+      vi
+        .spyOn(globalThis, 'fetch')
+        .mockResolvedValue(
+          new Response('[]', { status: 200, headers: { 'Content-Type': 'application/json' } }),
+        )
+
+    it('uses the base URL and a token set on the original client after copying', async () => {
+      const fetchSpy = mockFetch()
+      const baseClient = new BaseApiClient('https://api.example.com', 'old-token')
+      const copy = new ItemsApi(baseClient).withQueryFormat('qs')
+      baseClient.setAccessToken('new-token')
+
+      await copy.searchByName('x')
+
+      const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit]
+      expect(decodeURIComponent(url)).toBe(`https://api.example.com${QS_QUERY}`)
+      expect((init.headers as Record<string, string>).Authorization).toBe('Bearer new-token')
+      expect(baseClient.queryFormat).toBe('json')
+    })
+  })
+})

package/src/core/withQueryFormat.ts

@@ -0,0 +1,47 @@
+import type { ApiClient } from './ApiClient'
+import type { QueryFormat } from './queryString'
+
+/**
+ * A view of `client` that serializes queries in `format`. Everything else — methods, base URL and
+ * the access token — is read from `client`, so `client.setAccessToken()` still applies to it.
+ */
+function overrideQueryFormat<T extends ApiClient>(client: T, format: QueryFormat): T {
+  return Object.create(client, {
+    queryFormat: { value: format, enumerable: true, configurable: true },
+  })
+}
+
+/**
+ * Copy of `api` whose client serializes queries in `format`; `api` itself is untouched.
+ *
+ * The copy has the same prototype and fields as `api`, with `client` replaced. Methods the
+ * constructor bound to `api` (`this.getMany = this.getMany.bind(this)`) are bound again to the
+ * copy, so they use its client.
+ */
+export function cloneWithQueryFormat<T extends object>(api: T, format: QueryFormat): T {
+  const source = api as T & { client: ApiClient }
+  const prototype = Object.getPrototypeOf(api) as Record<PropertyKey, unknown>
+  const copy = Object.create(prototype) as Record<PropertyKey, unknown>
+
+  for (const key of Reflect.ownKeys(api)) {
+    Object.defineProperty(
+      copy,
+      key,
+      Object.getOwnPropertyDescriptor(api, key) as PropertyDescriptor,
+    )
+  }
+  Object.defineProperty(copy, 'client', {
+    value: overrideQueryFormat(source.client, format),
+    enumerable: true,
+    configurable: true,
+    writable: false,
+  })
+  for (const key of Reflect.ownKeys(api)) {
+    const method = prototype[key]
+    if (typeof copy[key] === 'function' && typeof method === 'function') {
+      copy[key] = method.bind(copy)
+    }
+  }
+
+  return copy as T
+}