core-services-sdk 1.3.82 → 1.3.84

package/package.json

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

package/src/http/http-method.js

@@ -1,7 +1,8 @@
 export const HTTP_METHODS = Object.freeze({
   GET: 'GET',
-  POST: 'POST',
   PUT: 'PUT',
+  HEAD: 'HEAD',
+  POST: 'POST',
   PATCH: 'PATCH',
   DELETE: 'DELETE',
 })

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,9 +51,17 @@
  * @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.
  */
 
+/**
+ * @typedef {Object} HttpHeadOptions
+ * @property {string} url - The URL to send the request to.
+ * @property {Record<string, string>} [headers] - Optional HTTP headers.
+ * @property {RequestInit} [extraParams] - Additional fetch options.
+ */
+
 import httpStatus from 'http-status'
 import { parseStringPromise } from 'xml2js'
 
@@ -205,9 +216,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 +240,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 +264,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 +288,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) } : {}),
@@ -282,6 +301,25 @@ export const deleteApi = async ({
   return getResponsePayload(response, expectedType)
 }
 
+/**
+ * Sends an HTTP HEAD request.
+ *
+ * @param {HttpHeadOptions} options - The request options.
+ * @returns {Promise<Response>} The raw fetch response (headers only).
+ * @throws {HttpError} If the response status is not successful.
+ */
+export const head = async ({ url, headers = {}, extraParams = {} }) => {
+  const response = await fetch(url, {
+    ...extraParams,
+    method: HTTP_METHODS.HEAD,
+    headers: { ...JSON_HEADER, ...headers },
+  })
+
+  await checkStatus(response)
+
+  return response
+}
+
 /**
  * Consolidated HTTP client with methods for common HTTP operations.
  *
@@ -290,13 +328,16 @@ export const deleteApi = async ({
  *   put: (options: HttpPutOptions) => Promise<any>,
  *   post: (options: HttpPostOptions) => Promise<any>,
  *   patch: (options: HttpPatchOptions) => Promise<any>,
- *   deleteApi: (options: HttpDeleteOptions) => Promise<any>
+ *   deleteApi: (options: HttpDeleteOptions) => Promise<any>,
+ *   head: (options: HttpHeadOptions) => Promise<Response>
  * }}
  */
+
 export const http = {
   get,
   put,
   post,
   patch,
   deleteApi,
+  head,
 }

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

@@ -6,9 +6,10 @@ import { HTTP_METHODS } from '../../src/http/http-method.js'
 describe('HTTP_METHODS constant', () => {
   it('should include all standard HTTP methods', () => {
     expect(HTTP_METHODS).toEqual({
+      PUT: 'PUT',
       GET: 'GET',
+      HEAD: 'HEAD',
       POST: 'POST',
-      PUT: 'PUT',
       PATCH: 'PATCH',
       DELETE: 'DELETE',
     })

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

@@ -20,6 +20,7 @@ const createMockResponse = ({
     statusText,
     text: vi.fn().mockResolvedValue(body),
     headers: {
+      // @ts-ignore
       get: vi.fn().mockImplementation((k) => headers[k]),
     },
   }
@@ -185,3 +186,213 @@ 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,
+      }),
+    )
+  })
+})
+
+describe('HEAD', () => {
+  it('should send a HEAD request and return response object', async () => {
+    const mockResponse = createMockResponse({
+      status: 200,
+      headers: { 'content-length': '1234' },
+    })
+
+    mockFetch.mockResolvedValueOnce(mockResponse)
+
+    const result = await http.head({
+      url: 'http://test.com',
+    })
+
+    expect(result).toBe(mockResponse)
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'http://test.com',
+      expect.objectContaining({
+        method: HTTP_METHODS.HEAD,
+      }),
+    )
+  })
+
+  it('should expose response headers', async () => {
+    const mockResponse = createMockResponse({
+      headers: { etag: 'abc123' },
+    })
+
+    mockFetch.mockResolvedValueOnce(mockResponse)
+
+    const result = await http.head({
+      url: 'http://test.com',
+    })
+
+    expect(result.headers.get('etag')).toBe('abc123')
+  })
+
+  it('should throw HttpError on non-2xx status', async () => {
+    mockFetch.mockResolvedValueOnce(
+      createMockResponse({
+        status: 500,
+        body: 'server error',
+      }),
+    )
+
+    await expect(
+      http.head({
+        url: 'http://test.com',
+      }),
+    ).rejects.toThrow(HttpError)
+  })
+})
+
+describe('edge cases', () => {
+  it('should fallback to text when JSON parsing fails', async () => {
+    const invalidJson = '{invalid json'
+
+    mockFetch.mockResolvedValueOnce(createMockResponse({ body: invalidJson }))
+
+    const result = await http.get({
+      url: 'http://test.com',
+      expectedType: ResponseType.json,
+    })
+
+    expect(result).toBe(invalidJson)
+  })
+
+  it('should fallback to text when XML parsing fails', async () => {
+    const invalidXml = '<note><invalid></note>'
+
+    mockFetch.mockResolvedValueOnce(createMockResponse({ body: invalidXml }))
+
+    const result = await http.get({
+      url: 'http://test.com',
+      expectedType: ResponseType.xml,
+    })
+
+    expect(result).toBe(invalidXml)
+  })
+
+  it('should allow overriding headers', async () => {
+    mockFetch.mockResolvedValueOnce(
+      createMockResponse({ body: JSON.stringify({ ok: true }) }),
+    )
+
+    await http.get({
+      url: 'http://test.com',
+      headers: {
+        Authorization: 'Bearer token123',
+      },
+    })
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'http://test.com',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer token123',
+        }),
+      }),
+    )
+  })
+
+  it('should send DELETE request without body', async () => {
+    mockFetch.mockResolvedValueOnce(
+      createMockResponse({ body: JSON.stringify({ ok: true }) }),
+    )
+
+    await http.deleteApi({
+      url: 'http://test.com',
+    })
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'http://test.com',
+      expect.objectContaining({
+        method: HTTP_METHODS.DELETE,
+      }),
+    )
+  })
+
+  it('should include default JSON content-type header', async () => {
+    mockFetch.mockResolvedValueOnce(
+      createMockResponse({ body: JSON.stringify({ ok: true }) }),
+    )
+
+    await http.post({
+      url: 'http://test.com',
+      body: { a: 1 },
+    })
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'http://test.com',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          'Content-Type': 'application/json',
+        }),
+      }),
+    )
+  })
+})

package/types/http/http-method.d.ts

@@ -1,7 +1,8 @@
 export const HTTP_METHODS: Readonly<{
   GET: 'GET'
-  POST: 'POST'
   PUT: 'PUT'
+  HEAD: 'HEAD'
+  POST: 'POST'
   PATCH: 'PATCH'
   DELETE: 'DELETE'
 }>

package/types/http/http.d.ts

@@ -3,60 +3,178 @@ 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>
+export function head({
+  url,
+  headers,
+  extraParams,
+}: HttpHeadOptions): Promise<Response>
+/**
+ * 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>,
+ *   head: (options: HttpHeadOptions) => Promise<Response>
+ * }}
+ */
+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>
+  head: (options: HttpHeadOptions) => Promise<Response>
+}
+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
+}
+export type HttpHeadOptions = {
+  /**
+   * - The URL to send the request to.
+   */
+  url: string
+  /**
+   * - Optional HTTP headers.
+   */
+  headers?: Record<string, string>
+  /**
+   * - Additional fetch options.
+   */
+  extraParams?: RequestInit
 }

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'