core-services-sdk 1.3.81 → 1.3.83

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.81",
+  "version": "1.3.83",
   "main": "src/index.js",
   "type": "module",
   "types": "types/index.d.ts",

package/src/http/http.js

@@ -24,6 +24,7 @@
  * @property {string} url - The URL to send the request to.
  * @property {any} body - The request body to send.
  * @property {Record<string, string>} [headers] - Optional HTTP headers.
+ * @property {RequestInit} [extraParams] - Additional fetch options.
  * @property {ResponseTypeValue} [expectedType] - Expected response type.
  */
 
@@ -32,6 +33,7 @@
  * @property {string} url - The URL to send the request to.
  * @property {any} body - The request body to send.
  * @property {Record<string, string>} [headers] - Optional HTTP headers.
+ * @property {RequestInit} [extraParams] - Additional fetch options.
  * @property {ResponseTypeValue} [expectedType] - Expected response type.
  */
 
@@ -40,6 +42,7 @@
  * @property {string} url - The URL to send the request to.
  * @property {any} body - The request body to send.
  * @property {Record<string, string>} [headers] - Optional HTTP headers.
+ * @property {RequestInit} [extraParams] - Additional fetch options.
  * @property {ResponseTypeValue} [expectedType] - Expected response type.
  */
 
@@ -48,6 +51,7 @@
  * @property {string} url - The URL to send the request to.
  * @property {any} [body] - Optional request body to send.
  * @property {Record<string, string>} [headers] - Optional HTTP headers.
+ * @property {RequestInit} [extraParams] - Additional fetch options.
  * @property {ResponseTypeValue} [expectedType] - Expected response type.
  */
 
@@ -205,9 +209,11 @@ export const post = async ({
   url,
   body,
   headers = {},
+  extraParams = {},
   expectedType = ResponseType.json,
 }) => {
   const response = await fetch(url, {
+    ...extraParams,
     method: HTTP_METHODS.POST,
     headers: { ...JSON_HEADER, ...headers },
     body: JSON.stringify(body),
@@ -227,9 +233,11 @@ export const put = async ({
   url,
   body,
   headers = {},
+  extraParams = {},
   expectedType = ResponseType.json,
 }) => {
   const response = await fetch(url, {
+    ...extraParams,
     method: HTTP_METHODS.PUT,
     headers: { ...JSON_HEADER, ...headers },
     body: expectedType === ResponseType.json ? JSON.stringify(body) : body,
@@ -249,9 +257,11 @@ export const patch = async ({
   url,
   body,
   headers = {},
+  extraParams = {},
   expectedType = ResponseType.json,
 }) => {
   const response = await fetch(url, {
+    ...extraParams,
     method: HTTP_METHODS.PATCH,
     headers: { ...JSON_HEADER, ...headers },
     body: JSON.stringify(body),
@@ -271,9 +281,11 @@ export const deleteApi = async ({
   url,
   body,
   headers = {},
+  extraParams = {},
   expectedType = ResponseType.json,
 }) => {
   const response = await fetch(url, {
+    ...extraParams,
     method: HTTP_METHODS.DELETE,
     headers: { ...JSON_HEADER, ...headers },
     ...(body ? { body: JSON.stringify(body) } : {}),

package/src/postgresql/index.js

@@ -5,4 +5,6 @@ export * from './filters/apply-filter.js'
 export * from './modifiers/apply-order-by.js'
 export * from './start-stop-postgres-docker.js'
 export * from './modifiers/apply-pagination.js'
+export * from './repositories/BaseRepository.js'
 export * from './filters/apply-filter-snake-case.js'
+export * from './repositories/TenantScopedRepository.js'

package/src/postgresql/pagination/paginate.js

@@ -75,6 +75,7 @@ export async function sqlPaginate({
   limit = 10,
   filter = {},
   snakeCase = true,
+  distinctOn,
 }) {
   const listQuery = baseQuery.clone()
   const countQuery = baseQuery.clone()
@@ -89,7 +90,9 @@ export async function sqlPaginate({
 
   const [rows, countResult] = await Promise.all([
     listQuery.select('*'),
-    countQuery.count('* as count').first(),
+    distinctOn
+      ? countQuery.countDistinct(`${distinctOn} as count`).first()
+      : countQuery.count('* as count').first(),
   ])
 
   const totalCount = normalizeNumberOrDefault(countResult?.count || 0)

package/src/postgresql/repositories/BaseRepository.js

@@ -0,0 +1,95 @@
+import { sqlPaginate } from '../pagination/paginate.js'
+import { toSnakeCase } from '../../core/case-mapper.js'
+
+/**
+ * BaseRepository
+ *
+ * Provides:
+ * - tableName getter (static + instance support)
+ * - baseQuery(options)
+ * - constructor-level query shaping (optional)
+ * - generic find() with pagination
+ *
+ * Does NOT enforce tenant isolation.
+ */
+
+export class BaseRepository {
+  constructor({ db, log, baseQueryBuilder } = {}) {
+    if (!db) {
+      throw new Error('BaseRepository requires db instance')
+    }
+
+    this.db = db
+    this.log = log
+    this._baseQueryBuilder = baseQueryBuilder
+  }
+
+  /**
+   * Each concrete repository must define:
+   * static tableName = 'table_name'
+   */
+  get tableName() {
+    if (!this.constructor.tableName) {
+      throw new Error(`tableName not defined for ${this.constructor.name}`)
+    }
+
+    return this.constructor.tableName
+  }
+
+  /**
+   * Builds the base knex query.
+   * Applies constructor-level baseQueryBuilder if provided.
+   */
+  baseQuery(options = {}, params) {
+    const { trx } = options
+    const connection = trx || this.db
+
+    const qb = connection(this.tableName)
+
+    if (this._baseQueryBuilder) {
+      // Pass full params for optional dynamic shaping
+      return this._baseQueryBuilder(qb, params)
+    }
+
+    return qb
+  }
+
+  /**
+   * Generic paginated find
+   */
+  async find({
+    page = 1,
+    limit = 10,
+    filter = {},
+    orderBy = { column: 'created_at', direction: 'desc' },
+    options = {},
+    mapRow = (row) => row,
+    ...restParams
+  }) {
+    try {
+      const qb = this.baseQuery(options, {
+        page,
+        limit,
+        filter,
+        orderBy,
+        options,
+        ...restParams,
+      })
+
+      return await sqlPaginate({
+        page,
+        limit,
+        orderBy,
+        baseQuery: qb,
+        mapRow,
+        filter: toSnakeCase(filter),
+      })
+    } catch (error) {
+      if (this.log) {
+        this.log.error({ error }, `Error finding from ${this.tableName}`)
+      }
+
+      throw error
+    }
+  }
+}

package/src/postgresql/repositories/TenantScopedRepository.js

@@ -0,0 +1,40 @@
+/**
+ * TenantScopedRepository
+ *
+ * Extends BaseRepository
+ * Enforces tenantId presence inside filter.
+ *
+ * Does NOT modify filter.
+ * Does NOT rebuild filter.
+ * Only validates existence.
+ */
+
+import { BaseRepository } from './BaseRepository.js'
+
+export class TenantScopedRepository extends BaseRepository {
+  /**
+   * Extracts and validates tenantId from filter
+   */
+  getRequiredTenantId(filter = {}) {
+    const { tenantId } = filter
+
+    if (!tenantId) {
+      throw new Error(
+        `Scoped repository (${this.tableName}), tenantId is required`,
+      )
+    }
+
+    return tenantId
+  }
+
+  /**
+   * Overrides find to enforce tenant presence
+   */
+  async find(params = {}) {
+    const { filter = {} } = params
+
+    this.getRequiredTenantId(filter)
+
+    return super.find(params)
+  }
+}

package/tests/http/http.unit.test.js

@@ -185,3 +185,73 @@ describe('http client (native fetch)', () => {
     })
   })
 })
+
+describe('extraParams support', () => {
+  it('should pass extraParams to fetch in GET', async () => {
+    mockFetch.mockResolvedValueOnce(
+      createMockResponse({ body: JSON.stringify({ ok: true }) }),
+    )
+
+    const controller = new AbortController()
+
+    await http.get({
+      url: 'http://test.com',
+      extraParams: {
+        signal: controller.signal,
+        redirect: 'follow',
+      },
+    })
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'http://test.com',
+      expect.objectContaining({
+        method: HTTP_METHODS.GET,
+        signal: controller.signal,
+        redirect: 'follow',
+      }),
+    )
+  })
+
+  it('should pass extraParams to fetch in POST', async () => {
+    mockFetch.mockResolvedValueOnce(
+      createMockResponse({ body: JSON.stringify({ ok: true }) }),
+    )
+
+    await http.post({
+      url: 'http://test.com',
+      body: { a: 1 },
+      extraParams: {
+        credentials: 'include',
+      },
+    })
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'http://test.com',
+      expect.objectContaining({
+        method: HTTP_METHODS.POST,
+        credentials: 'include',
+      }),
+    )
+  })
+
+  it('should pass extraParams to fetch in DELETE', async () => {
+    mockFetch.mockResolvedValueOnce(
+      createMockResponse({ body: JSON.stringify({ ok: true }) }),
+    )
+
+    await http.deleteApi({
+      url: 'http://test.com',
+      extraParams: {
+        keepalive: true,
+      },
+    })
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'http://test.com',
+      expect.objectContaining({
+        method: HTTP_METHODS.DELETE,
+        keepalive: true,
+      }),
+    )
+  })
+})

package/tests/repositories/BaseRepository.test.js

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { BaseRepository } from '../../src/postgresql/repositories/BaseRepository.js'
+
+// 🔥 mock dependencies
+vi.mock('../../src/postgresql/pagination/paginate.js', () => ({
+  sqlPaginate: vi.fn().mockResolvedValue({ page: 1 }),
+}))
+
+vi.mock('../../filters/apply-filter-snake-case.js', () => ({
+  applyFilterSnakeCase: vi.fn(),
+}))
+
+vi.mock('../../filters/apply-filter.js', () => ({
+  applyFilter: vi.fn(),
+}))
+
+vi.mock('../../core/normalize-premitives-types-or-default.js', () => ({
+  normalizeNumberOrDefault: vi.fn((v) => Number(v)),
+}))
+
+// import AFTER mocks
+import { sqlPaginate } from '../../src/postgresql/pagination/paginate.js'
+import { toSnakeCase } from '../../src/core/case-mapper.js'
+
+describe('BaseRepository', () => {
+  let dbMock
+  let logMock
+
+  class TestRepo extends BaseRepository {
+    static tableName = 'test_table'
+  }
+
+  beforeEach(() => {
+    dbMock = vi.fn(() => ({
+      clone: vi.fn(),
+    }))
+
+    logMock = {
+      error: vi.fn(),
+    }
+  })
+
+  it('throws if db not provided', () => {
+    expect(() => new BaseRepository()).toThrow()
+  })
+
+  it('returns correct tableName', () => {
+    const repo = new TestRepo({ db: dbMock })
+    expect(repo.tableName).toBe('test_table')
+  })
+
+  it('baseQuery uses db when no trx', () => {
+    const repo = new TestRepo({ db: dbMock })
+
+    repo.baseQuery()
+
+    expect(dbMock).toHaveBeenCalledWith('test_table')
+  })
+
+  it('baseQuery uses trx when provided', () => {
+    const trxMock = vi.fn()
+    const repo = new TestRepo({ db: dbMock })
+
+    repo.baseQuery({ trx: trxMock })
+
+    expect(trxMock).toHaveBeenCalledWith('test_table')
+    expect(dbMock).not.toHaveBeenCalled()
+  })
+
+  it('baseQuery applies baseQueryBuilder', () => {
+    const builderMock = vi.fn((qb) => qb)
+    const repo = new TestRepo({
+      db: dbMock,
+      baseQueryBuilder: builderMock,
+    })
+
+    repo.baseQuery({}, { some: 'param' })
+
+    expect(builderMock).toHaveBeenCalled()
+  })
+
+  it('find calls sqlPaginate with correct params', async () => {
+    const repo = new TestRepo({ db: dbMock })
+
+    await repo.find({
+      page: 2,
+      limit: 5,
+      filter: { a: 1 },
+    })
+
+    expect(sqlPaginate).toHaveBeenCalled()
+  })
+
+  it('logs error if sqlPaginate throws', async () => {
+    // @ts-ignore
+    sqlPaginate.mockRejectedValueOnce(new Error('fail'))
+
+    const repo = new TestRepo({ db: dbMock, log: logMock })
+
+    await expect(repo.find({ filter: {} })).rejects.toThrow()
+
+    expect(logMock.error).toHaveBeenCalled()
+  })
+})

package/tests/repositories/TenantScopedRepository.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect, vi } from 'vitest'
+import { TenantScopedRepository } from '../../src/postgresql/repositories/TenantScopedRepository.js'
+
+class TestTenantRepo extends TenantScopedRepository {
+  static tableName = 'tenant_table'
+}
+
+describe('TenantScopedRepository', () => {
+  const dbMock = vi.fn(() => ({}))
+
+  it('throws if tenantId missing', async () => {
+    const repo = new TestTenantRepo({ db: dbMock })
+
+    await expect(repo.find({ filter: {} })).rejects.toThrow()
+  })
+
+  it('does not throw if tenantId exists', async () => {
+    const repo = new TestTenantRepo({ db: dbMock })
+
+    // Spy on BaseRepository.find instead of overriding repo.find
+    const superSpy = vi
+      .spyOn(Object.getPrototypeOf(TenantScopedRepository.prototype), 'find')
+      .mockResolvedValue(true)
+
+    const result = await repo.find({
+      filter: { tenantId: 'abc' },
+    })
+
+    expect(result).toBe(true)
+    expect(superSpy).toHaveBeenCalled()
+
+    superSpy.mockRestore()
+  })
+
+  it('getRequiredTenantId returns tenantId', () => {
+    const repo = new TestTenantRepo({ db: dbMock })
+
+    const id = repo.getRequiredTenantId({
+      tenantId: 'tenant-1',
+    })
+
+    expect(id).toBe('tenant-1')
+  })
+})

package/types/http/http.d.ts

@@ -3,60 +3,157 @@ export function get({
   headers,
   extraParams,
   expectedType,
-}: {
-  url: any
-  headers?: {}
-  extraParams?: {}
-  expectedType?: 'json'
-}): Promise<any>
+}: HttpGetOptions): Promise<any>
 export function post({
   url,
   body,
   headers,
+  extraParams,
   expectedType,
-}: {
-  url: any
-  body: any
-  headers?: {}
-  expectedType?: 'json'
-}): Promise<any>
+}: HttpPostOptions): Promise<any>
 export function put({
   url,
   body,
   headers,
+  extraParams,
   expectedType,
-}: {
-  url: any
-  body: any
-  headers?: {}
-  expectedType?: 'json'
-}): Promise<any>
+}: HttpPutOptions): Promise<any>
 export function patch({
   url,
   body,
   headers,
+  extraParams,
   expectedType,
-}: {
-  url: any
-  body: any
-  headers?: {}
-  expectedType?: 'json'
-}): Promise<any>
+}: HttpPatchOptions): Promise<any>
 export function deleteApi({
   url,
   body,
   headers,
+  extraParams,
   expectedType,
-}: {
-  url: any
+}: HttpDeleteOptions): Promise<any>
+/**
+ * Consolidated HTTP client with methods for common HTTP operations.
+ *
+ * @type {{
+ *   get: (options: HttpGetOptions) => Promise<any>,
+ *   put: (options: HttpPutOptions) => Promise<any>,
+ *   post: (options: HttpPostOptions) => Promise<any>,
+ *   patch: (options: HttpPatchOptions) => Promise<any>,
+ *   deleteApi: (options: HttpDeleteOptions) => Promise<any>
+ * }}
+ */
+export const http: {
+  get: (options: HttpGetOptions) => Promise<any>
+  put: (options: HttpPutOptions) => Promise<any>
+  post: (options: HttpPostOptions) => Promise<any>
+  patch: (options: HttpPatchOptions) => Promise<any>
+  deleteApi: (options: HttpDeleteOptions) => Promise<any>
+}
+export type ResponseTypeValue = 'json' | 'xml' | 'text' | 'raw' | 'file'
+export type HttpGetOptions = {
+  /**
+   * - The URL to send the request to.
+   */
+  url: string
+  /**
+   * - Optional HTTP headers.
+   */
+  headers?: Record<string, string>
+  /**
+   * - Additional fetch options.
+   */
+  extraParams?: RequestInit
+  /**
+   * - Expected response type.
+   */
+  expectedType?: ResponseTypeValue
+}
+export type HttpPostOptions = {
+  /**
+   * - The URL to send the request to.
+   */
+  url: string
+  /**
+   * - The request body to send.
+   */
+  body: any
+  /**
+   * - Optional HTTP headers.
+   */
+  headers?: Record<string, string>
+  /**
+   * - Additional fetch options.
+   */
+  extraParams?: RequestInit
+  /**
+   * - Expected response type.
+   */
+  expectedType?: ResponseTypeValue
+}
+export type HttpPutOptions = {
+  /**
+   * - The URL to send the request to.
+   */
+  url: string
+  /**
+   * - The request body to send.
+   */
   body: any
-  headers?: {}
-  expectedType?: 'json'
-}): Promise<any>
-export namespace http {
-  export { get }
-  export { put }
-  export { post }
-  export { patch }
-  export { deleteApi }
+  /**
+   * - Optional HTTP headers.
+   */
+  headers?: Record<string, string>
+  /**
+   * - Additional fetch options.
+   */
+  extraParams?: RequestInit
+  /**
+   * - Expected response type.
+   */
+  expectedType?: ResponseTypeValue
+}
+export type HttpPatchOptions = {
+  /**
+   * - The URL to send the request to.
+   */
+  url: string
+  /**
+   * - The request body to send.
+   */
+  body: any
+  /**
+   * - Optional HTTP headers.
+   */
+  headers?: Record<string, string>
+  /**
+   * - Additional fetch options.
+   */
+  extraParams?: RequestInit
+  /**
+   * - Expected response type.
+   */
+  expectedType?: ResponseTypeValue
+}
+export type HttpDeleteOptions = {
+  /**
+   * - The URL to send the request to.
+   */
+  url: string
+  /**
+   * - Optional request body to send.
+   */
+  body?: any
+  /**
+   * - Optional HTTP headers.
+   */
+  headers?: Record<string, string>
+  /**
+   * - Additional fetch options.
+   */
+  extraParams?: RequestInit
+  /**
+   * - Expected response type.
+   */
+  expectedType?: ResponseTypeValue
 }

package/types/postgresql/index.d.ts

@@ -5,4 +5,6 @@ export * from './filters/apply-filter.js'
 export * from './modifiers/apply-order-by.js'
 export * from './start-stop-postgres-docker.js'
 export * from './modifiers/apply-pagination.js'
+export * from './repositories/BaseRepository.js'
 export * from './filters/apply-filter-snake-case.js'
+export * from './repositories/TenantScopedRepository.js'

package/types/postgresql/pagination/paginate.d.ts

@@ -69,6 +69,7 @@ export function sqlPaginate({
   limit,
   filter,
   snakeCase,
+  distinctOn,
 }: {
   baseQuery: import('knex').Knex.QueryBuilder
   filter?: any

package/types/postgresql/repositories/BaseRepository.d.ts

@@ -0,0 +1,50 @@
+/**
+ * BaseRepository
+ *
+ * Provides:
+ * - tableName getter (static + instance support)
+ * - baseQuery(options)
+ * - constructor-level query shaping (optional)
+ * - generic find() with pagination
+ *
+ * Does NOT enforce tenant isolation.
+ */
+export class BaseRepository {
+  constructor({ db, log, baseQueryBuilder }?: {})
+  db: any
+  log: any
+  _baseQueryBuilder: any
+  /**
+   * Each concrete repository must define:
+   * static tableName = 'table_name'
+   */
+  get tableName(): any
+  /**
+   * Builds the base knex query.
+   * Applies constructor-level baseQueryBuilder if provided.
+   */
+  baseQuery(options: {}, params: any): any
+  /**
+   * Generic paginated find
+   */
+  find({
+    page,
+    limit,
+    filter,
+    orderBy,
+    options,
+    mapRow,
+    ...restParams
+  }: {
+    [x: string]: any
+    page?: number
+    limit?: number
+    filter?: {}
+    orderBy?: {
+      column: string
+      direction: string
+    }
+    options?: {}
+    mapRow?: (row: any) => any
+  }): Promise<any>
+}

package/types/postgresql/repositories/TenantScopedRepository.d.ts

@@ -0,0 +1,11 @@
+export class TenantScopedRepository extends BaseRepository {
+  /**
+   * Extracts and validates tenantId from filter
+   */
+  getRequiredTenantId(filter?: {}): any
+  /**
+   * Overrides find to enforce tenant presence
+   */
+  find(params?: {}): Promise<any>
+}
+import { BaseRepository } from './BaseRepository.js'