@ikatec/digisac-api-sdk 1.2.0

package/src/core/BaseCrudApi.test.ts

@@ -0,0 +1,278 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { BaseCrudApi } from './BaseCrudApi'
+import type { ApiClient } from './ApiClient'
+import type { Paginated } from './types'
+
+// ── Test types ───────────────────────────────────────────────────────
+
+type Item = { id: string; name: string }
+type CreateItem = { name: string }
+type UpdateItem = { name?: string }
+
+// ── Mock client factory ──────────────────────────────────────────────
+
+function createMockClient(): ApiClient {
+  return {
+    setAccessToken: vi.fn().mockReturnThis(),
+    request: vi.fn(),
+    get: vi.fn(),
+    post: vi.fn(),
+    put: vi.fn(),
+    patch: vi.fn(),
+    delete: vi.fn(),
+  }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('BaseCrudApi', () => {
+  let client: ReturnType<typeof createMockClient>
+  let api: BaseCrudApi<Item, CreateItem, UpdateItem>
+
+  beforeEach(() => {
+    client = createMockClient()
+    api = new BaseCrudApi<Item, CreateItem, UpdateItem>(client, '/items')
+  })
+
+  // ── Constructor ──────────────────────────────────────────────────
+
+  describe('constructor', () => {
+    it('strips trailing slash from basePath', () => {
+      const api2 = new BaseCrudApi(client, '/items/')
+      const mockResponse: Paginated<Item> = {
+        data: [],
+        total: 0,
+        limit: 10,
+        skip: 0,
+        currentPage: 1,
+        lastPage: 1,
+        from: 0,
+        to: 0,
+      }
+      vi.mocked(client.get).mockResolvedValue(mockResponse)
+
+      api2.getMany()
+      expect(client.get).toHaveBeenCalledWith('/items', undefined)
+    })
+
+    it('works with basePath without trailing slash', () => {
+      const mockResponse: Paginated<Item> = {
+        data: [],
+        total: 0,
+        limit: 10,
+        skip: 0,
+        currentPage: 1,
+        lastPage: 1,
+        from: 0,
+        to: 0,
+      }
+      vi.mocked(client.get).mockResolvedValue(mockResponse)
+
+      api.getMany()
+      expect(client.get).toHaveBeenCalledWith('/items', undefined)
+    })
+  })
+
+  // ── getMany ──────────────────────────────────────────────────────
+
+  describe('getMany', () => {
+    it('calls client.get with basePath when no query is provided', async () => {
+      const mockResponse: Paginated<Item> = {
+        data: [{ id: '1', name: 'Test' }],
+        total: 1,
+        limit: 10,
+        skip: 0,
+        currentPage: 1,
+        lastPage: 1,
+        from: 1,
+        to: 1,
+      }
+      vi.mocked(client.get).mockResolvedValue(mockResponse)
+
+      const result = await api.getMany()
+      expect(client.get).toHaveBeenCalledWith('/items', undefined)
+      expect(result).toEqual(mockResponse)
+    })
+
+    it('serializes query parameters into query string', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({ page: 2, perPage: 25 })
+      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
+      expect(calledUrl).toContain('/items?')
+      expect(calledUrl).toContain('page=2')
+      expect(calledUrl).toContain('perPage=25')
+    })
+
+    it('serializes where clause into query string', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({ where: { name: 'test' } })
+      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
+      expect(calledUrl).toContain('where')
+      expect(calledUrl).toContain('name')
+      expect(calledUrl).toContain('test')
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+      const headers = { 'X-Custom': 'value' }
+
+      await api.getMany(undefined, headers)
+      expect(client.get).toHaveBeenCalledWith('/items', headers)
+    })
+
+    it('forwards headers with query', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+      const headers = { Authorization: 'Bearer token' }
+
+      await api.getMany({ page: 1 }, headers)
+      expect(vi.mocked(client.get).mock.calls.at(0)?.at(1)).toEqual(headers)
+    })
+  })
+
+  // ── getOne ───────────────────────────────────────────────────────
+
+  describe('getOne', () => {
+    it('calls client.get with basePath/id', async () => {
+      const item: Item = { id: 'abc', name: 'Test' }
+      vi.mocked(client.get).mockResolvedValue(item)
+
+      const result = await api.getOne('abc')
+      expect(client.get).toHaveBeenCalledWith('/items/abc', undefined)
+      expect(result).toEqual(item)
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.get).mockResolvedValue({ id: '1', name: 'x' })
+      const headers = { 'X-Tenant': '123' }
+
+      await api.getOne('1', headers)
+      expect(client.get).toHaveBeenCalledWith('/items/1', headers)
+    })
+  })
+
+  // ── create ───────────────────────────────────────────────────────
+
+  describe('create', () => {
+    it('calls client.post with basePath and body', async () => {
+      const created: Item = { id: 'new', name: 'New Item' }
+      vi.mocked(client.post).mockResolvedValue(created)
+
+      const result = await api.create({ name: 'New Item' })
+      expect(client.post).toHaveBeenCalledWith('/items', { name: 'New Item' }, undefined)
+      expect(result).toEqual(created)
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.post).mockResolvedValue({ id: '1', name: 'x' })
+      const headers = { 'X-Request-Id': 'req-1' }
+
+      await api.create({ name: 'x' }, headers)
+      expect(client.post).toHaveBeenCalledWith('/items', { name: 'x' }, headers)
+    })
+  })
+
+  // ── updateById ───────────────────────────────────────────────────
+
+  describe('updateById', () => {
+    it('calls client.patch with basePath/id and body', async () => {
+      const updated: Item = { id: 'abc', name: 'Updated' }
+      vi.mocked(client.patch).mockResolvedValue(updated)
+
+      const result = await api.updateById('abc', { name: 'Updated' })
+      expect(client.patch).toHaveBeenCalledWith('/items/abc', { name: 'Updated' }, undefined)
+      expect(result).toEqual(updated)
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.patch).mockResolvedValue({ id: '1', name: 'y' })
+      const headers = { 'If-Match': 'etag-1' }
+
+      await api.updateById('1', { name: 'y' }, headers)
+      expect(client.patch).toHaveBeenCalledWith('/items/1', { name: 'y' }, headers)
+    })
+  })
+
+  // ── deleteById ───────────────────────────────────────────────────
+
+  describe('deleteById', () => {
+    it('calls client.delete with basePath/id', async () => {
+      const deleted: Item = { id: 'abc', name: 'Deleted' }
+      vi.mocked(client.delete).mockResolvedValue(deleted)
+
+      const result = await api.deleteById('abc')
+      expect(client.delete).toHaveBeenCalledWith('/items/abc', undefined)
+      expect(result).toEqual(deleted)
+    })
+
+    it('forwards custom headers', async () => {
+      vi.mocked(client.delete).mockResolvedValue({ id: '1', name: 'z' })
+      const headers = { 'X-Reason': 'cleanup' }
+
+      await api.deleteById('1', headers)
+      expect(client.delete).toHaveBeenCalledWith('/items/1', headers)
+    })
+  })
+
+  // ── Error propagation ────────────────────────────────────────────
+
+  describe('error propagation', () => {
+    it('propagates errors from client.get in getMany', async () => {
+      vi.mocked(client.get).mockRejectedValue(new Error('Network error'))
+      await expect(api.getMany()).rejects.toThrow('Network error')
+    })
+
+    it('propagates errors from client.get in getOne', async () => {
+      vi.mocked(client.get).mockRejectedValue(new Error('Not found'))
+      await expect(api.getOne('missing')).rejects.toThrow('Not found')
+    })
+
+    it('propagates errors from client.post in create', async () => {
+      vi.mocked(client.post).mockRejectedValue(new Error('Validation failed'))
+      await expect(api.create({ name: 'bad' })).rejects.toThrow('Validation failed')
+    })
+
+    it('propagates errors from client.patch in updateById', async () => {
+      vi.mocked(client.patch).mockRejectedValue(new Error('Conflict'))
+      await expect(api.updateById('1', { name: 'x' })).rejects.toThrow('Conflict')
+    })
+
+    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')
+    })
+  })
+
+  // ── Query serialization edge cases ───────────────────────────────
+
+  describe('query serialization', () => {
+    it('handles complex where with operators', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({ where: { name: { $like: '%test%' } } })
+      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
+      expect(calledUrl).toMatch(/^\/items\?/)
+      expect(calledUrl).toContain('%25test%25')
+    })
+
+    it('handles order parameter', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({ order: [['name', 'ASC']] })
+      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
+      expect(calledUrl).toContain('order')
+      expect(calledUrl).toContain('name')
+      expect(calledUrl).toContain('ASC')
+    })
+
+    it('handles empty query object', async () => {
+      vi.mocked(client.get).mockResolvedValue({ data: [], total: 0 })
+
+      await api.getMany({})
+      const calledUrl = vi.mocked(client.get).mock.calls.at(0)?.at(0) as string
+      // qs.stringify({}) produces '', so we get '/items?'
+      expect(calledUrl).toBe('/items?')
+    })
+  })
+})

package/src/core/BaseCrudApi.ts

@@ -0,0 +1,81 @@
+import qs from 'qs'
+import type { ApiClient } from './ApiClient'
+import type { CrudApi, ListQuery, Paginated } from './types'
+export type {
+  WhereClause,
+  IncludeItem,
+  ListQuery,
+  Paginated,
+  HasGetMany,
+  HasGetOne,
+  HasCreate,
+  HasUpdateById,
+  HasDeleteById,
+  CrudApi,
+} from './types'
+
+export class BaseCrudApi<
+  TResponse,
+  TCreate,
+  TUpdate = TCreate,
+  TQuery extends ListQuery<TResponse> = ListQuery<TResponse>,
+> implements CrudApi<TResponse, TCreate, TUpdate, TQuery> {
+  protected readonly client: ApiClient
+  protected readonly basePath: string
+
+  constructor(client: ApiClient, basePath: string) {
+    this.client = client
+    this.basePath = basePath.replace(/\/$/, '')
+  }
+
+  getMany(
+    query: TQuery & { paginate: false },
+    headers?: Record<string, string>,
+  ): Promise<TResponse[]>
+  getMany(
+    query?: TQuery & { paginate?: true },
+    headers?: Record<string, string>,
+  ): Promise<Paginated<TResponse>>
+  getMany(
+    query?: TQuery,
+    headers?: Record<string, string>,
+  ): Promise<Paginated<TResponse> | TResponse[]> {
+    const queryString = query ? `?${qs.stringify(query)}` : ''
+    return this.client.get<Paginated<TResponse> | TResponse[]>(
+      `${this.basePath}${queryString}`,
+      headers,
+    )
+  }
+
+  /**
+   * Returns a single resource by ID.
+   * @permissions $resourceName.view
+   */
+  getOne(id: string, headers?: Record<string, string>): Promise<TResponse> {
+    return this.client.get<TResponse>(`${this.basePath}/${id}`, headers)
+  }
+
+  /**
+   * Creates a new resource.
+   * @permissions $resourceName.create
+   */
+  create(body: TCreate, headers?: Record<string, string>): Promise<TResponse> {
+    return this.client.post<TResponse, TCreate>(this.basePath, body, headers)
+  }
+
+  /**
+   * Updates an existing resource by ID.
+   * @permissions $resourceName.update
+   */
+  updateById(id: string, body: TUpdate, headers?: Record<string, string>): Promise<TResponse> {
+    return this.client.patch<TResponse, TUpdate>(`${this.basePath}/${id}`, body, headers)
+  }
+
+  /**
+   * Deletes a resource by ID.
+   * @permissions $resourceName.delete
+   */
+  deleteById(id: string, headers?: Record<string, string>): Promise<TResponse> {
+    return this.client.delete<TResponse>(`${this.basePath}/${id}`, headers)
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,5 @@
+export type { ApiClient, HttpMethod } from './ApiClient'
+export { BaseApiClient, ApiError } from './BaseApiClient'
+export type { ValidationError } from './BaseApiClient'
+export { BaseCrudApi } from './BaseCrudApi'
+export type { WhereClause, IncludeItem, ListQuery, Paginated } from './types'

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

@@ -0,0 +1,263 @@
+import { expectAssignable, expectNotAssignable } from 'tsd'
+import type { WhereClause, IncludeItem, ListQuery } from './types'
+
+// ── Test model ──────────────────────────────────────────────────────
+
+type Comment = {
+  id: number
+  body: string
+  createdAt: string
+}
+
+type User = {
+  id: number
+  name: string
+  email: string
+  isActive: boolean
+  score: number | null
+  comments: Comment[]
+}
+
+// ── WhereClause ─────────────────────────────────────────────────────
+
+// simple equality
+expectAssignable<WhereClause<User>>({ id: 1 })
+expectAssignable<WhereClause<User>>({ name: 'alice' })
+expectAssignable<WhereClause<User>>({ isActive: true })
+
+// comparison operators
+expectAssignable<WhereClause<User>>({ id: { $eq: 1 } })
+expectAssignable<WhereClause<User>>({ id: { $ne: 2 } })
+expectAssignable<WhereClause<User>>({ id: { $gt: 0, $lt: 100 } })
+expectAssignable<WhereClause<User>>({ id: { $gte: 1, $lte: 50 } })
+
+// null operators
+expectAssignable<WhereClause<User>>({ score: { $is: null } })
+expectAssignable<WhereClause<User>>({ score: { $not: 0 } })
+
+// string operators
+expectAssignable<WhereClause<User>>({ name: { $like: '%alice%' } })
+expectAssignable<WhereClause<User>>({ name: { $iLike: '%alice%' } })
+expectAssignable<WhereClause<User>>({ email: { $notLike: '%spam%' } })
+expectAssignable<WhereClause<User>>({ email: { $regexp: '^test' } })
+
+// array operators
+expectAssignable<WhereClause<User>>({ id: { $in: [1, 2, 3] } })
+expectAssignable<WhereClause<User>>({ id: { $notIn: [4, 5] } })
+expectAssignable<WhereClause<User>>({ id: { $between: [1, 10] } })
+expectAssignable<WhereClause<User>>({ id: { $notBetween: [100, 200] } })
+
+// logical operators
+expectAssignable<WhereClause<User>>({ $and: [{ id: 1 }, { name: 'alice' }] })
+expectAssignable<WhereClause<User>>({ $or: [{ id: 1 }, { id: 2 }] })
+expectAssignable<WhereClause<User>>({
+  $and: { id: 1 },
+  $or: [{ name: 'alice' }, { name: 'bob' }],
+})
+
+// wrong value type for field
+expectNotAssignable<WhereClause<User>>({ id: 'not-a-number' })
+expectNotAssignable<WhereClause<User>>({ isActive: 'yes' })
+expectNotAssignable<WhereClause<User>>({ name: 123 })
+
+// ── IncludeItem ─────────────────────────────────────────────────────
+
+// string shorthand (association key)
+expectAssignable<IncludeItem<User>>('comments')
+
+// typed include object
+expectAssignable<IncludeItem<User>>({ model: 'comments' })
+expectAssignable<IncludeItem<User>>({
+  model: 'comments',
+  required: true,
+  where: { id: { $gt: 0 } },
+})
+
+// non-existent associations are rejected
+expectNotAssignable<IncludeItem<User>>('someOtherRelation')
+expectNotAssignable<IncludeItem<User>>({ model: 'someOtherRelation' })
+
+// ── ListQuery ───────────────────────────────────────────────────────
+
+// minimal query
+expectAssignable<ListQuery<User>>({})
+
+// with where
+expectAssignable<ListQuery<User>>({ where: { isActive: true } })
+
+// with pagination
+expectAssignable<ListQuery<User>>({ page: 1, perPage: 25 })
+expectAssignable<ListQuery<User>>({ limit: 10, offset: 0 })
+
+// with ordering
+expectAssignable<ListQuery<User>>({ order: [['id', 'ASC']] })
+expectAssignable<ListQuery<User>>({ order: [['name', 'desc']] })
+
+// with attributes / fields
+expectAssignable<ListQuery<User>>({ attributes: ['id', 'name'] })
+expectAssignable<ListQuery<User>>({ fields: ['email'] })
+
+// invalid attribute key
+expectNotAssignable<ListQuery<User>>({ attributes: ['nonExistentField'] })
+
+// invalid order direction
+expectNotAssignable<ListQuery<User>>({ order: [['id', 'INVALID']] })
+
+// with include
+expectAssignable<ListQuery<User>>({
+  include: ['comments'],
+  where: { id: { $in: [1, 2] } },
+})
+
+// with misc options
+expectAssignable<ListQuery<User>>({
+  subQuery: false,
+  paranoid: false,
+  distinct: true,
+})
+
+// combined query
+expectAssignable<ListQuery<User>>({
+  where: { isActive: true, name: { $like: '%a%' } },
+  include: [{ model: 'comments', required: true, where: { body: { $ne: '' } } }],
+  order: [['id', 'DESC']],
+  page: 1,
+  perPage: 20,
+  attributes: ['id', 'name', 'email'],
+})
+
+// ── Additional WhereClause tests ────────────────────────────────────
+
+// multiple fields at once
+expectAssignable<WhereClause<User>>({ id: 1, name: 'alice', isActive: true })
+
+// remaining string operators
+expectAssignable<WhereClause<User>>({ name: { $notILike: '%bob%' } })
+expectAssignable<WhereClause<User>>({ name: { $notRegexp: '^x' } })
+expectAssignable<WhereClause<User>>({ name: { $iRegexp: '^alice' } })
+expectAssignable<WhereClause<User>>({ name: { $notIRegexp: '^bob' } })
+
+// remaining array operators
+expectAssignable<WhereClause<User>>({ id: { $contains: [1, 2] } })
+expectAssignable<WhereClause<User>>({ id: { $contained: [1, 2, 3] } })
+expectAssignable<WhereClause<User>>({ id: { $overlap: [1, 2] } })
+expectAssignable<WhereClause<User>>({ id: { $any: [1, 2] } })
+expectAssignable<WhereClause<User>>({ id: { $all: [1, 2, 3] } })
+
+// $is with boolean
+expectAssignable<WhereClause<User>>({ isActive: { $is: true } })
+expectAssignable<WhereClause<User>>({ isActive: { $is: false } })
+
+// combining multiple operators on one field
+expectAssignable<WhereClause<User>>({ id: { $gt: 0, $lt: 100, $ne: 50 } })
+expectAssignable<WhereClause<User>>({ name: { $like: '%a%', $notLike: '%z%' } })
+
+// nested logical operators
+expectAssignable<WhereClause<User>>({
+  $or: [{ $and: [{ id: { $gt: 0 } }, { isActive: true }] }, { name: { $like: '%admin%' } }],
+})
+
+// deeply nested $and / $or
+expectAssignable<WhereClause<User>>({
+  $and: [{ $or: [{ id: 1 }, { id: 2 }] }, { $or: [{ name: 'alice' }, { name: 'bob' }] }],
+})
+
+// nullable field with operators
+expectAssignable<WhereClause<User>>({ score: { $eq: 10 } })
+expectAssignable<WhereClause<User>>({ score: { $gt: 5, $lte: 100 } })
+expectAssignable<WhereClause<User>>({ score: { $in: [1, 2, 3] } })
+expectAssignable<WhereClause<User>>({ score: null })
+
+// empty where clause
+expectAssignable<WhereClause<User>>({})
+
+// wrong operator value types
+expectNotAssignable<WhereClause<User>>({ id: { $eq: 'wrong' } })
+expectNotAssignable<WhereClause<User>>({ id: { $in: ['a', 'b'] } })
+expectNotAssignable<WhereClause<User>>({ id: { $between: ['a', 'b'] } })
+expectNotAssignable<WhereClause<User>>({ name: { $eq: 123 } })
+expectNotAssignable<WhereClause<User>>({ isActive: { $eq: 'yes' } })
+
+// ── Additional IncludeItem tests ────────────────────────────────────
+
+// include with `as` alias
+expectAssignable<IncludeItem<User>>({ model: 'comments', as: 'userComments' })
+
+// include with nested include
+expectAssignable<IncludeItem<User>>({
+  model: 'comments',
+})
+
+// include with where on association fields
+expectAssignable<IncludeItem<User>>({
+  model: 'comments',
+  where: { body: { $like: '%hello%' } },
+  required: false,
+})
+
+// non-existent association object is rejected
+expectNotAssignable<IncludeItem<User>>({
+  model: 'otherRelation',
+  as: 'alias',
+  include: [{ model: 'deep' }],
+  required: true,
+  where: { someField: 'value' },
+})
+
+// ── Additional ListQuery tests ──────────────────────────────────────
+
+// invalid field in order
+expectNotAssignable<ListQuery<User>>({ order: [['nonExistent', 'ASC']] })
+
+// invalid field in fields
+expectNotAssignable<ListQuery<User>>({ fields: ['nonExistent'] })
+
+// multiple order clauses
+expectAssignable<ListQuery<User>>({
+  order: [
+    ['id', 'ASC'],
+    ['name', 'DESC'],
+  ],
+})
+
+// all four order directions
+expectAssignable<ListQuery<User>>({ order: [['id', 'ASC']] })
+expectAssignable<ListQuery<User>>({ order: [['id', 'DESC']] })
+expectAssignable<ListQuery<User>>({ order: [['id', 'asc']] })
+expectAssignable<ListQuery<User>>({ order: [['id', 'desc']] })
+
+// through option
+expectAssignable<ListQuery<User>>({ through: { where: { active: true } } })
+
+// all pagination combos
+expectAssignable<ListQuery<User>>({ page: 2, perPage: 50, limit: 10, offset: 5 })
+
+// where with logical operators inside ListQuery
+expectAssignable<ListQuery<User>>({
+  where: { $or: [{ id: 1 }, { id: 2 }] },
+})
+
+// include with typed objects inside ListQuery — only known associations accepted
+expectAssignable<ListQuery<User>>({
+  include: [{ model: 'comments', required: true, where: { id: { $gt: 0 } } }, 'comments'],
+})
+// unknown association in include array is rejected
+expectNotAssignable<ListQuery<User>>({
+  include: ['otherRelation'],
+})
+
+// ── Model with no associations ──────────────────────────────────────
+
+type SimpleModel = {
+  id: number
+  value: string
+}
+
+// where works on flat models
+expectAssignable<WhereClause<SimpleModel>>({ id: 1, value: 'test' })
+expectAssignable<ListQuery<SimpleModel>>({ where: { id: { $in: [1, 2] } } })
+expectAssignable<ListQuery<SimpleModel>>({ attributes: ['id', 'value'] })
+expectNotAssignable<ListQuery<SimpleModel>>({ attributes: ['missing'] })
+
+// include on flat models (no associations) rejects any string
+expectNotAssignable<ListQuery<SimpleModel>>({ include: ['anything'] })