core-services-sdk 1.3.62 → 1.3.64

package/.claude/settings.local.json

@@ -0,0 +1,22 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test:*)",
+      "Bash(docker rm:*)",
+      "Bash(docker run:*)",
+      "Bash(mongosh:*)",
+      "Bash(for:*)",
+      "Bash(do if mongosh --port 27099 --eval \"db.runCommand({ ping: 1 })\")",
+      "Bash(then echo \"Connected after $i attempts\")",
+      "Bash(break)",
+      "Bash(fi)",
+      "Bash(echo:*)",
+      "Bash(done)",
+      "Bash(docker logs:*)",
+      "Bash(docker system:*)",
+      "Bash(docker volume prune:*)",
+      "Bash(docker image prune:*)",
+      "Bash(docker builder prune:*)"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.62",
+  "version": "1.3.64",
   "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/apply-filter.js

@@ -1,11 +1,24 @@
+/**
+ * @fileoverview Provides utilities for applying MongoDB-style filter operators to Knex query builders.
+ *
+ * This module contains functions to convert filter objects with various operators (equality,
+ * comparison, pattern matching, null checks, etc.) into SQL WHERE clauses using Knex.
+ * Supports automatic camelCase to snake_case conversion for database column names.
+ *
+ * @module postgresql/apply-filter
+ */
+
 import { toSnakeCase } from '../core/case-mapper.js'
 
 /**
- * @typedef {Object} OperatorFunction
- * @property {import('knex').Knex.QueryBuilder} query - Knex query builder instance
- * @property {string} key - Column name (qualified with table name)
- * @property {*} value - Value to compare against
- * @returns {import('knex').Knex.QueryBuilder} Modified query builder
+ * Type definition for filter operator functions.
+ * Each operator function applies a WHERE condition to a Knex query builder.
+ *
+ * @typedef {Function} OperatorFunction
+ * @param {import('knex').Knex.QueryBuilder} q - Knex query builder instance
+ * @param {string} key - Column name (qualified with table name, e.g., "table.column")
+ * @param {*} value - Value to compare against (type depends on operator)
+ * @returns {import('knex').Knex.QueryBuilder} Modified query builder with WHERE clause applied
  */
 
 /**
@@ -165,9 +178,10 @@ const applyFilterObject = (q, qualifiedKey, value) => {
  * Builds a Knex query with MongoDB-style filter operators.
  * Pure utility function that can be used across repositories.
  *
- * This function converts camelCase filter keys to snake_case and applies
- * various filter operators to build SQL WHERE clauses. All column names
- * are automatically qualified with the provided table name.
+ * This function applies various filter operators to build SQL WHERE clauses. All column names
+ * are automatically qualified with the provided table name. Filter keys are used as-is without
+ * any case conversion. If you need automatic camelCase to snake_case conversion, use
+ * {@link applyFilterSnakeCase} instead.
  *
  * **Supported Operators:**
  * - `eq` - Equality (default for simple values)
@@ -184,15 +198,19 @@ const applyFilterObject = (q, qualifiedKey, value) => {
  * - `isNotNull` - Check if field is NOT NULL
  *
  * **Key Features:**
- * - Automatic camelCase to snake_case conversion for filter keys
+ * - Filter keys are used as-is (no automatic case conversion)
  * - Qualified column names (table.column format)
  * - Multiple operators can be applied to the same field
  * - Unknown operators are silently ignored
  * - Arrays are automatically converted to IN clauses
  *
+ * **Note:** This function does NOT convert filter keys. If your database uses snake_case columns
+ * but your filter keys are in camelCase, use {@link applyFilterSnakeCase} instead, or ensure
+ * your filter keys already match your database column names.
+ *
  * @param {Object} params - Function parameters
  * @param {import('knex').Knex.QueryBuilder} params.query - Knex query builder instance to apply filters to
- * @param {Object<string, *>} params.filter - Filter object with camelCase keys (will be converted to snake_case)
+ * @param {Object<string, *>} params.filter - Filter object with keys matching database column names (used as-is)
  *   Filter values can be:
  *   - Simple values (string, number, boolean) → treated as equality
  *   - Arrays → treated as IN operator
@@ -252,14 +270,13 @@ const applyFilterObject = (q, qualifiedKey, value) => {
  * })
  *
  * @example
- * // camelCase conversion - deletedAt converts to deleted_at
- * applyFilter({ query, filter: { deletedAt: { isNull: true } }, tableName: 'assets' })
+ * // Filter keys are used as-is - ensure they match your database column names
+ * applyFilter({ query, filter: { deleted_at: { isNull: true } }, tableName: 'assets' })
  * // SQL: WHERE assets.deleted_at IS NULL
+ * // Note: If you need camelCase conversion, use applyFilterSnakeCase instead
  */
 export function applyFilter({ query, filter, tableName }) {
-  const convertedFilter = toSnakeCase(filter)
-
-  return Object.entries(convertedFilter).reduce((q, [key, value]) => {
+  return Object.entries(filter).reduce((q, [key, value]) => {
     const qualifiedKey = `${tableName}.${key}`
 
     if (value && typeof value === 'object' && !Array.isArray(value)) {
@@ -273,3 +290,112 @@ export function applyFilter({ query, filter, tableName }) {
     return OPERATORS.eq(q, qualifiedKey, value)
   }, query)
 }
+
+/**
+ * Applies MongoDB-style filter operators to a Knex query with automatic camelCase to snake_case conversion.
+ *
+ * This function is a convenience wrapper around {@link applyFilter} that automatically converts
+ * all filter keys from camelCase to snake_case before applying the filters. This is useful when
+ * your application code uses camelCase naming conventions but your database columns use snake_case.
+ *
+ * The function first converts all filter object keys using `toSnakeCase`, then applies the filters
+ * using the standard `applyFilter` function. This ensures that filter keys like `userId` are
+ * converted to `user_id` before being used in SQL queries.
+ *
+ * **Key Features:**
+ * - Automatic camelCase to snake_case key conversion
+ * - Same operator support as `applyFilter`
+ * - Qualified column names (table.column format)
+ * - Multiple operators can be applied to the same field
+ * - Arrays are automatically converted to IN clauses
+ *
+ * **Supported Operators:**
+ * Same as {@link applyFilter}:
+ * - `eq` - Equality (default for simple values)
+ * - `ne` / `neq` - Not equal
+ * - `in` - Array membership (or pass array directly)
+ * - `nin` - Not in array
+ * - `gt` - Greater than
+ * - `gte` - Greater than or equal
+ * - `lt` - Less than
+ * - `lte` - Less than or equal
+ * - `like` - Case-sensitive pattern matching (SQL LIKE)
+ * - `ilike` - Case-insensitive pattern matching (PostgreSQL ILIKE)
+ * - `isNull` - Check if field is NULL
+ * - `isNotNull` - Check if field is NOT NULL
+ *
+ * @param {Object} params - Function parameters
+ * @param {import('knex').Knex.QueryBuilder} params.query - Knex query builder instance to apply filters to
+ * @param {Object<string, *>} params.filter - Filter object with camelCase keys (will be converted to snake_case)
+ *   Filter values can be:
+ *   - Simple values (string, number, boolean) → treated as equality
+ *   - Arrays → treated as IN operator
+ *   - Objects with operator keys → apply specific operators
+ * @param {string} params.tableName - Table name used to qualify column names (e.g., "assets" → "assets.column_name")
+ * @returns {import('knex').Knex.QueryBuilder} Modified query builder with applied WHERE clauses (using snake_case column names)
+ *
+ * @throws {TypeError} If query is not a valid Knex QueryBuilder instance
+ *
+ * @example
+ * // Simple equality with camelCase key - converts to WHERE assets.user_id = 1
+ * const query = db('assets').select('*')
+ * applyFilterSnakeCase({ query, filter: { userId: 1 }, tableName: 'assets' })
+ * // SQL: WHERE assets.user_id = 1
+ *
+ * @example
+ * // Not equal with camelCase key - converts to WHERE assets.status != 'deleted'
+ * applyFilterSnakeCase({
+ *   query,
+ *   filter: { status: { ne: 'deleted' } },
+ *   tableName: 'assets'
+ * })
+ * // SQL: WHERE assets.status != 'deleted'
+ *
+ * @example
+ * // Array/IN operator with camelCase key - converts to WHERE assets.status IN ('active', 'pending')
+ * applyFilterSnakeCase({
+ *   query,
+ *   filter: { status: ['active', 'pending'] },
+ *   tableName: 'assets'
+ * })
+ * // SQL: WHERE assets.status IN ('active', 'pending')
+ *
+ * @example
+ * // Range operators with camelCase keys - converts to WHERE assets.price >= 100 AND assets.price <= 200
+ * applyFilterSnakeCase({
+ *   query,
+ *   filter: { price: { gte: 100, lte: 200 } },
+ *   tableName: 'assets'
+ * })
+ * // SQL: WHERE assets.price >= 100 AND assets.price <= 200
+ *
+ * @example
+ * // Null checks with camelCase key - converts to WHERE assets.deleted_at IS NULL
+ * applyFilterSnakeCase({
+ *   query,
+ *   filter: { deletedAt: { isNull: true } },
+ *   tableName: 'assets'
+ * })
+ * // SQL: WHERE assets.deleted_at IS NULL
+ *
+ * @example
+ * // Multiple filters with camelCase keys
+ * applyFilterSnakeCase({
+ *   query,
+ *   filter: {
+ *     userId: 123,              // Converts to user_id
+ *     createdAt: { gte: '2024-01-01' },  // Converts to created_at
+ *     status: 'active'
+ *   },
+ *   tableName: 'assets'
+ * })
+ * // SQL: WHERE assets.user_id = 123 AND assets.created_at >= '2024-01-01' AND assets.status = 'active'
+ *
+ * @see {@link applyFilter} For the base function without key conversion
+ * @see {@link toSnakeCase} For details on the key conversion process
+ */
+export function applyFilterSnakeCase({ query, filter, tableName }) {
+  const convertedFilter = toSnakeCase(filter)
+
+  return applyFilter({ query, filter: convertedFilter, tableName })
+}

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('+972523443413', {
+          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,