core-services-sdk 1.3.63 → 1.3.65

package/package.json

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

package/src/core/normalize-phone-number.js

@@ -3,7 +3,46 @@
 
 import * as raw from 'google-libphonenumber'
 
-/** Resolve libphonenumber regardless of interop shape */
+/**
+ * @typedef {Object} NormalizedPhone
+ * @property {string} e164
+ * @property {number} type
+ * @property {string} national
+ * @property {number} countryCode
+ * @property {string} nationalClean
+ * @property {string} international
+ * @property {string} countryCodeE164
+ * @property {string} internationalClean
+ * @property {string | undefined} regionCode
+ */
+
+/**
+ * normalize-phone-number.js
+ *
+ * Utilities for parsing, validating, and normalizing phone numbers
+ * using google-libphonenumber.
+ *
+ * Supports both ESM and CJS interop builds.
+ * All normalization outputs are canonical and safe for persistence,
+ * comparison, indexing, and login identifiers.
+ */
+
+/**
+ * Resolve google-libphonenumber exports regardless of ESM / CJS shape.
+ *
+ * Some builds expose:
+ *   - raw.PhoneNumberUtil
+ * Others expose:
+ *   - raw.default.PhoneNumberUtil
+ *
+ * This helper guarantees a consistent API.
+ *
+ * @returns {{
+ *   PhoneNumberUtil: any,
+ *   PhoneNumberFormat: any
+ * }}
+ * @throws {Error} If required exports are missing
+ */
 export function getLib() {
   // Prefer direct (CJS-style or ESM w/ named), else default
   // e.g. raw.PhoneNumberUtil OR raw.default.PhoneNumberUtil
@@ -19,6 +58,15 @@ export function getLib() {
 
 let _util // lazy singleton
 
+/**
+ * Lazy singleton accessor for PhoneNumberUtil.
+ *
+ * Ensures:
+ * - Single instance per process
+ * - No eager initialization cost
+ *
+ * @returns {any} PhoneNumberUtil instance
+ */
 export function phoneUtil() {
   if (!_util) {
     const { PhoneNumberUtil } = getLib()
@@ -27,15 +75,25 @@ export function phoneUtil() {
   return _util
 }
 
+/**
+ * Internal helper returning PhoneNumberFormat enum.
+ *
+ * @returns {any} PhoneNumberFormat enum
+ */
 function formats() {
   const { PhoneNumberFormat } = getLib()
   return PhoneNumberFormat
 }
 
 /**
- * Trim and remove invisible RTL markers.
- * @param {string} input
- * @returns {string}
+ * Cleans user input before parsing:
+ * - Trims whitespace
+ * - Removes invisible RTL/LTR markers
+ *
+ * Does NOT remove digits, plus sign, or formatting characters.
+ *
+ * @param {string} input Raw user input
+ * @returns {string} Cleaned input string
  */
 function clean(input) {
   return String(input)
@@ -44,27 +102,69 @@ function clean(input) {
 }
 
 /**
- * Convert a parsed libphonenumber object into a normalized result.
+ * Converts a parsed google-libphonenumber object into a normalized result.
+ *
+ * Returned formats:
+ * - e164: Canonical phone number in E.164 format.
+ *   Intended for storage, indexing, comparison, login identifiers, and OTP flows.
+ *
+ * - national: Local, human-readable phone number representation.
+ *   May include formatting characters such as dashes or spaces.
+ *
+ * - nationalClean: Local phone number containing digits only.
+ *
+ * - international: Human-readable international representation.
+ *
+ * - internationalClean: International phone number containing digits only,
+ *   without '+' or formatting characters.
+ *
+ * - regionCode: ISO 3166-1 alpha-2 region code (e.g. "IL").
+ *
+ * - countryCallingCode: Numeric international dialing code (e.g. 972).
+ *
+ * - countryCallingCodeE164: International dialing code with '+' prefix (e.g. "+972").
+ *
+ * Notes:
+ * - Only `e164` should be persisted or used for identity comparison.
+ * - All other formats are intended strictly for UI, display, copy, or integrations.
+ *
  * @param {any} parsed
- * @returns {{e164:string,national:string,international:string,regionCode:string|undefined,type:number}}
+ *   Parsed phone number object returned by google-libphonenumber.
+ *
+ * @returns {NormalizedPhone}
  */
+
 function toResult(parsed) {
   const PNF = formats()
   const util = phoneUtil()
-  return {
+
+  const results = {
+    type: util.getNumberType(parsed),
     e164: util.format(parsed, PNF.E164),
     national: util.format(parsed, PNF.NATIONAL),
-    international: util.format(parsed, PNF.INTERNATIONAL),
     regionCode: util.getRegionCodeForNumber(parsed),
-    type: util.getNumberType(parsed),
+    international: util.format(parsed, PNF.INTERNATIONAL),
+  }
+
+  const countryCode = `${parsed.getCountryCode()}`
+
+  return {
+    ...results,
+    countryCode,
+    countryCodeE164: `+${countryCode}`,
+    nationalClean: results.national.replace(/\D/g, ''),
+    internationalClean: results.e164.replace(/\D/g, ''),
   }
 }
 
 /**
- * Parse & validate an international number (must start with '+').
- * @param {string} input
- * @returns {{e164:string,national:string,international:string,regionCode:string|undefined,type:number}}
- * @throws {Error} If the number is invalid
+ * Normalize and validate an international phone number.
+ *
+ * Input MUST start with '+'.
+ *
+ * @param {string} input International phone number (E.164-like)
+ * @returns {NormalizedPhone}
+ * @throws {Error} If the phone number is invalid
  */
 export function normalizePhoneOrThrowIntl(input) {
   try {
@@ -82,11 +182,22 @@ export function normalizePhoneOrThrowIntl(input) {
 }
 
 /**
- * Parse & validate a national number using a region hint.
- * @param {string} input
- * @param {string} defaultRegion
- * @returns {{e164:string,national:string,international:string,regionCode:string|undefined,type:number}}
- * @throws {Error} If the number is invalid
+ * Normalize and validate a national phone number using a region hint.
+ *
+ * Example:
+ *   input: "0523444444"
+ *   defaultRegion: "IL"
+ *
+ * @param {string} input National phone number
+ * @param {string} defaultRegion ISO 3166-1 alpha-2 country code
+ * @returns {{
+ *   e164: string,
+ *   national: string,
+ *   international: string,
+ *   regionCode: string | undefined,
+ *   type: number
+ * }}
+ * @throws {Error} If the phone number is invalid
  */
 export function normalizePhoneOrThrowWithRegion(input, defaultRegion) {
   try {
@@ -104,13 +215,21 @@ export function normalizePhoneOrThrowWithRegion(input, defaultRegion) {
 }
 
 /**
- * Smart normalization:
- * - If input starts with '+', parse as international.
- * - Otherwise require a defaultRegion and parse as national.
- * @param {string} input
- * @param {{ defaultRegion?: string }} [opts]
- * @returns {{e164:string,national:string,international:string,regionCode:string|undefined,type:number}}
- * @throws {Error} If invalid or defaultRegion is missing for non-international input
+ * Smart normalization entry point.
+ *
+ * Behavior:
+ * - If input starts with '+', parses as international
+ * - Otherwise requires defaultRegion and parses as national
+ *
+ * This is the recommended function for login, signup, and verification flows.
+ *
+ * @param {string} input Phone number (international or national)
+ * @param {{
+ *   defaultRegion?: string
+ * }} [opts]
+ *
+ * @returns {NormalizedPhone}
+ * @throws {Error} If invalid or defaultRegion is missing
  */
 export function normalizePhoneOrThrow(input, opts = {}) {
   const cleaned = clean(input)

package/src/postgresql/core/get-table-name.js

@@ -0,0 +1,10 @@
+/**
+ * Extracts base table name from Knex QueryBuilder.
+ * Relies on Knex internal structure.
+ *
+ * @param {import('knex').Knex.QueryBuilder} query
+ * @returns {string|undefined}
+ */
+export function getTableNameFromQuery(query) {
+  return query?._single?.table
+}

package/src/postgresql/filters/apply-filter-object.js

@@ -0,0 +1,19 @@
+import { OPERATORS } from './operators.js'
+
+/**
+ * Applies multiple operators on the same column.
+ *
+ * @param {import('knex').Knex.QueryBuilder} query
+ * @param {string} qualifiedKey
+ * @param {Object<string, *>} value
+ * @returns {import('knex').Knex.QueryBuilder}
+ */
+export function applyFilterObject(query, qualifiedKey, value) {
+  return Object.entries(value).reduce((q, [operator, val]) => {
+    if (!OPERATORS[operator]) {
+      return q
+    }
+
+    return OPERATORS[operator](q, qualifiedKey, val)
+  }, query)
+}

package/src/postgresql/filters/apply-filter-snake-case.js

@@ -0,0 +1,16 @@
+import { toSnakeCase } from '../../core/case-mapper.js'
+import { applyFilter } from './apply-filter.js'
+
+/**
+ * Applies filters with automatic camelCase to snake_case conversion.
+ *
+ * @param {Object} params
+ * @param {import('knex').Knex.QueryBuilder} params.query
+ * @param {Object} params.filter
+ */
+export function applyFilterSnakeCase({ query, filter }) {
+  return applyFilter({
+    query,
+    filter: toSnakeCase(filter),
+  })
+}

package/src/postgresql/filters/apply-filter.js

@@ -0,0 +1,33 @@
+import { getTableNameFromQuery } from '../core/get-table-name.js'
+import { OPERATORS } from './operators.js'
+import { applyFilterObject } from './apply-filter-object.js'
+
+/**
+ * Applies MongoDB-style filters to a Knex QueryBuilder.
+ *
+ * @param {Object} params
+ * @param {import('knex').Knex.QueryBuilder} params.query
+ * @param {Object} [params.filter]
+ * @returns {import('knex').Knex.QueryBuilder}
+ */
+export function applyFilter({ query, filter = {} }) {
+  const tableName = getTableNameFromQuery(query)
+
+  if (!filter || Object.keys(filter).length === 0) {
+    return query
+  }
+
+  return Object.entries(filter).reduce((q, [key, value]) => {
+    const qualifiedKey = tableName ? `${tableName}.${key}` : key
+
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      return applyFilterObject(q, qualifiedKey, value)
+    }
+
+    if (Array.isArray(value)) {
+      return OPERATORS.in(q, qualifiedKey, value)
+    }
+
+    return OPERATORS.eq(q, qualifiedKey, value)
+  }, query)
+}

package/src/postgresql/filters/operators.js

@@ -0,0 +1,32 @@
+/**
+ * @typedef {Function} OperatorFunction
+ * @param {import('knex').Knex.QueryBuilder} q
+ * @param {string} key
+ * @param {*} value
+ * @returns {import('knex').Knex.QueryBuilder}
+ */
+
+/**
+ * @type {Object<string, OperatorFunction>}
+ */
+export const OPERATORS = {
+  in: (q, key, value) => q.whereIn(key, value),
+  nin: (q, key, value) => q.whereNotIn(key, value),
+
+  eq: (q, key, value) => q.where(key, '=', value),
+  ne: (q, key, value) => q.where(key, '!=', value),
+  neq: (q, key, value) => q.where(key, '!=', value),
+
+  gt: (q, key, value) => q.where(key, '>', value),
+  gte: (q, key, value) => q.where(key, '>=', value),
+  lt: (q, key, value) => q.where(key, '<', value),
+  lte: (q, key, value) => q.where(key, '<=', value),
+
+  like: (q, key, value) => q.where(key, 'like', value),
+  ilike: (q, key, value) => q.where(key, 'ilike', value),
+
+  isNull: (q, key, value) => (value ? q.whereNull(key) : q.whereNotNull(key)),
+
+  isNotNull: (q, key, value) =>
+    value ? q.whereNotNull(key) : q.whereNull(key),
+}

package/src/postgresql/index.js

@@ -1,5 +1,8 @@
-export * from './paginate.js'
-export * from './apply-filter.js'
 export * from './connect-to-pg.js'
 export * from './validate-schema.js'
+export * from './pagination/paginate.js'
+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 './filters/apply-filter-snake-case.js'

package/src/postgresql/modifiers/apply-order-by.js

@@ -0,0 +1,19 @@
+import { getTableNameFromQuery } from '../core/get-table-name.js'
+
+/**
+ * Applies ORDER BY clause.
+ *
+ * @param {Object} params
+ * @param {import('knex').Knex.QueryBuilder} params.query
+ * @param {{ column: string, direction?: 'asc'|'desc' }} params.orderBy
+ */
+export function applyOrderBy({ query, orderBy }) {
+  if (!orderBy?.column) {
+    return query
+  }
+
+  const tableName = getTableNameFromQuery(query)
+  const column = tableName ? `${tableName}.${orderBy.column}` : orderBy.column
+
+  return query.orderBy(column, orderBy.direction || 'asc')
+}

package/src/postgresql/modifiers/apply-pagination.js

@@ -0,0 +1,12 @@
+/**
+ * Applies LIMIT and OFFSET.
+ *
+ * @param {Object} params
+ * @param {import('knex').Knex.QueryBuilder} params.query
+ * @param {number} [params.page=1]
+ * @param {number} [params.limit=10]
+ */
+export function applyPagination({ query, page = 1, limit = 10 }) {
+  const offset = (page - 1) * limit
+  return query.limit(limit).offset(offset)
+}

package/src/postgresql/pagination/paginate.js

@@ -0,0 +1,48 @@
+import { applyFilter } from '../filters/apply-filter.js'
+import { applyFilterSnakeCase } from '../filters/apply-filter-snake-case.js'
+import { applyOrderBy } from '../modifiers/apply-order-by.js'
+import { applyPagination } from '../modifiers/apply-pagination.js'
+import { normalizeNumberOrDefault } from '../../core/normalize-premitives-types-or-default.js'
+
+/**
+ * Executes paginated query.
+ *
+ * @async
+ */
+export async function sqlPaginate({
+  mapRow,
+  orderBy,
+  page = 1,
+  baseQuery,
+  limit = 10,
+  filter = {},
+  snakeCase = true,
+}) {
+  const listQuery = baseQuery.clone()
+  const countQuery = baseQuery.clone()
+
+  const applyFilterFn = snakeCase ? applyFilterSnakeCase : applyFilter
+
+  applyFilterFn({ query: listQuery, filter })
+  applyFilterFn({ query: countQuery, filter })
+
+  applyOrderBy({ query: listQuery, orderBy })
+  applyPagination({ query: listQuery, page, limit })
+
+  const [rows, countResult] = await Promise.all([
+    listQuery.select('*'),
+    countQuery.count('* as count').first(),
+  ])
+
+  const totalCount = normalizeNumberOrDefault(countResult?.count || 0)
+  const totalPages = Math.ceil(totalCount / limit)
+
+  return {
+    totalCount,
+    totalPages,
+    currentPage: page,
+    hasPrevious: page > 1,
+    hasNext: page < totalPages,
+    list: mapRow ? rows.map(mapRow) : rows,
+  }
+}

package/tests/core/normalize-phone-number.unit.test.js

@@ -58,6 +58,51 @@ describe('phone normalization', () => {
       expect(out.regionCode).toBe('IL')
     })
 
+    describe('normalizePhoneOrThrow - international input', () => {
+      it('returns full normalized data for international input without defaultRegion', () => {
+        const out = normalizePhoneOrThrow('+972523443413')
+
+        // canonical
+        expect(out.e164).toBe('+972523443413')
+        // clean formats
+
+        expect(out.internationalClean).toBe('972523443413')
+        expect(out.nationalClean).toBe('0523443413')
+
+        // formatted (do not assert exact formatting)
+        expect(typeof out.national).toBe('string')
+        expect(typeof out.international).toBe('string')
+
+        // metadata
+        expect(out.regionCode).toBe('IL')
+        expect(out.countryCode).toBe('972')
+        expect(out.countryCodeE164).toBe('+972')
+        expect(typeof out.type).toBe('number')
+      })
+
+      it('returns identical normalized data when defaultRegion is provided', () => {
+        const out = normalizePhoneOrThrow('0523443413', {
+          defaultRegion: 'IL',
+        })
+
+        // canonical
+        expect(out.e164).toBe('+972523443413')
+
+        // clean formats
+        expect(out.internationalClean).toBe('972523443413')
+        expect(out.nationalClean).toBe('0523443413')
+
+        // formatted (do not assert exact formatting)
+        expect(typeof out.national).toBe('string')
+        expect(typeof out.international).toBe('string')
+
+        // metadata
+        expect(out.regionCode).toBe('IL')
+        expect(out.countryCode).toBe('972')
+        expect(out.countryCodeE164).toBe('+972')
+        expect(typeof out.type).toBe('number')
+      })
+    })
     it('normalizePhoneOrThrow (smart): throws if national with no defaultRegion', () => {
       expect(() => normalizePhoneOrThrow('054-123-4567')).toThrow(
         /defaultRegion is required/i,