@salespark/toolkit 2.1.17 → 2.1.18

package/dist/index.d.cts

@@ -981,8 +981,52 @@ declare const deferAfterResponse: (res: HttpResponseLike, fn: DeferFn) => void;
  ******************************************************************/
 declare const deferAfterResponseNonCritical: (res: HttpResponseLike, fn: DeferFn) => void;
 
+/******************************************************
+ * ##: Reversible Base36 Code Encoder/Decoder (No Deps)
+ * Encodes a base36 identifier into a lower-case base36 code using a secret key.
+ * Decodes back with the same secret and configuration.
+ * History:
+ * 16-02-2026: Created
+ ****************************************************/
+type EncodeDecodeConfig = {
+    secret: string;
+    bitSize?: number;
+    rotateBits?: number;
+    addConstant?: string;
+};
+/******************************************************************
+ * ##: Encode Base36 Identifier
+ * Obfuscates a base36 identifier into a reversible lowercase base36 code using XOR mixing, constant addition, and rotation.
+ *
+ * TL;DR: Encodes a base36 identifier into a reversible base36 code.
+ * Uses a secret-derived key and fixed-width math to keep outputs bounded and reversible.
+ * @param {string} identifier - Source identifier in base36 format
+ * @param {EncodeDecodeConfig} config - Encoding configuration including secret and optional parameters
+ * @returns {SalesParkContract<{ code: string }>} - Return a SalesPark Contract object.
+ * History:
+ * 16-02-2026: Created
+ ******************************************************************/
+declare const encodeBase36Code: (identifier: string, config: EncodeDecodeConfig) => SalesParkContract<{
+    code: string;
+}>;
+/******************************************************************
+ * ##: Decode Base36 Code
+ * Reverses the obfuscation steps to restore the original identifier using the same secret and configuration parameters.
+ *
+ * TL;DR: Decodes a base36 code back into the original identifier.
+ * Requires the same secret and config to reliably reverse XOR, add, and rotation.
+ * @param {string} code - Encoded base36 code to decode
+ * @param {EncodeDecodeConfig} config - Decoding configuration including secret and optional parameters
+ * @returns {SalesParkContract<{ identifier: string }>} - Return a SalesPark Contract object.
+ * History:
+ * 16-02-2026: Created
+ ******************************************************************/
+declare const decodeBase36Code: (code: string, config: EncodeDecodeConfig) => SalesParkContract<{
+    identifier: string;
+}>;
+
 /** Environment helpers (runtime-agnostic checks) */
 declare const isBrowser: boolean;
 declare const isNode: boolean;
 
-export { type CapitalizeFirstOptions, type CapitalizeWordsOptions, type DeferFn, type FormatCurrencyProOptions, type HttpResponseLike, type SecurityCheckResult, type SecurityRisk, type SentenceCaseOptions, addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, capitalizeFirst, capitalizeWords, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, decodeObject, decodeString, deferAfterResponse, deferAfterResponseNonCritical, deferNonCritical, deferPostReturn, delay, difference, encodeObject, encodeString, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, formatCurrencyPro, formatDecimalNumber, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrEmptyObject, isNilEmptyOrZeroLen, isNilEmptyOrZeroLength, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilOrZeroLength, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, numbersEqual, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeAdd, safeDivide, safeJSONParse, safeMultiply, safeParseFloat, safeParseInt, safeSubtract, sanitize, sanitizeMarkdown, sentenceCase, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };
+export { type CapitalizeFirstOptions, type CapitalizeWordsOptions, type DeferFn, type EncodeDecodeConfig, type FormatCurrencyProOptions, type HttpResponseLike, type SecurityCheckResult, type SecurityRisk, type SentenceCaseOptions, addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, capitalizeFirst, capitalizeWords, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, decodeBase36Code, decodeObject, decodeString, deferAfterResponse, deferAfterResponseNonCritical, deferNonCritical, deferPostReturn, delay, difference, encodeBase36Code, encodeObject, encodeString, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, formatCurrencyPro, formatDecimalNumber, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrEmptyObject, isNilEmptyOrZeroLen, isNilEmptyOrZeroLength, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilOrZeroLength, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, numbersEqual, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeAdd, safeDivide, safeJSONParse, safeMultiply, safeParseFloat, safeParseInt, safeSubtract, sanitize, sanitizeMarkdown, sentenceCase, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };

package/dist/index.d.ts

@@ -981,8 +981,52 @@ declare const deferAfterResponse: (res: HttpResponseLike, fn: DeferFn) => void;
  ******************************************************************/
 declare const deferAfterResponseNonCritical: (res: HttpResponseLike, fn: DeferFn) => void;
 
+/******************************************************
+ * ##: Reversible Base36 Code Encoder/Decoder (No Deps)
+ * Encodes a base36 identifier into a lower-case base36 code using a secret key.
+ * Decodes back with the same secret and configuration.
+ * History:
+ * 16-02-2026: Created
+ ****************************************************/
+type EncodeDecodeConfig = {
+    secret: string;
+    bitSize?: number;
+    rotateBits?: number;
+    addConstant?: string;
+};
+/******************************************************************
+ * ##: Encode Base36 Identifier
+ * Obfuscates a base36 identifier into a reversible lowercase base36 code using XOR mixing, constant addition, and rotation.
+ *
+ * TL;DR: Encodes a base36 identifier into a reversible base36 code.
+ * Uses a secret-derived key and fixed-width math to keep outputs bounded and reversible.
+ * @param {string} identifier - Source identifier in base36 format
+ * @param {EncodeDecodeConfig} config - Encoding configuration including secret and optional parameters
+ * @returns {SalesParkContract<{ code: string }>} - Return a SalesPark Contract object.
+ * History:
+ * 16-02-2026: Created
+ ******************************************************************/
+declare const encodeBase36Code: (identifier: string, config: EncodeDecodeConfig) => SalesParkContract<{
+    code: string;
+}>;
+/******************************************************************
+ * ##: Decode Base36 Code
+ * Reverses the obfuscation steps to restore the original identifier using the same secret and configuration parameters.
+ *
+ * TL;DR: Decodes a base36 code back into the original identifier.
+ * Requires the same secret and config to reliably reverse XOR, add, and rotation.
+ * @param {string} code - Encoded base36 code to decode
+ * @param {EncodeDecodeConfig} config - Decoding configuration including secret and optional parameters
+ * @returns {SalesParkContract<{ identifier: string }>} - Return a SalesPark Contract object.
+ * History:
+ * 16-02-2026: Created
+ ******************************************************************/
+declare const decodeBase36Code: (code: string, config: EncodeDecodeConfig) => SalesParkContract<{
+    identifier: string;
+}>;
+
 /** Environment helpers (runtime-agnostic checks) */
 declare const isBrowser: boolean;
 declare const isNode: boolean;
 
-export { type CapitalizeFirstOptions, type CapitalizeWordsOptions, type DeferFn, type FormatCurrencyProOptions, type HttpResponseLike, type SecurityCheckResult, type SecurityRisk, type SentenceCaseOptions, addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, capitalizeFirst, capitalizeWords, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, decodeObject, decodeString, deferAfterResponse, deferAfterResponseNonCritical, deferNonCritical, deferPostReturn, delay, difference, encodeObject, encodeString, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, formatCurrencyPro, formatDecimalNumber, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrEmptyObject, isNilEmptyOrZeroLen, isNilEmptyOrZeroLength, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilOrZeroLength, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, numbersEqual, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeAdd, safeDivide, safeJSONParse, safeMultiply, safeParseFloat, safeParseInt, safeSubtract, sanitize, sanitizeMarkdown, sentenceCase, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };
+export { type CapitalizeFirstOptions, type CapitalizeWordsOptions, type DeferFn, type EncodeDecodeConfig, type FormatCurrencyProOptions, type HttpResponseLike, type SecurityCheckResult, type SecurityRisk, type SentenceCaseOptions, addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, capitalizeFirst, capitalizeWords, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, decodeBase36Code, decodeObject, decodeString, deferAfterResponse, deferAfterResponseNonCritical, deferNonCritical, deferPostReturn, delay, difference, encodeBase36Code, encodeObject, encodeString, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, formatCurrencyPro, formatDecimalNumber, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrEmptyObject, isNilEmptyOrZeroLen, isNilEmptyOrZeroLength, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilOrZeroLength, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, numbersEqual, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeAdd, safeDivide, safeJSONParse, safeMultiply, safeParseFloat, safeParseInt, safeSubtract, sanitize, sanitizeMarkdown, sentenceCase, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };

package/dist/index.js

@@ -2029,10 +2029,199 @@ var deferAfterResponseNonCritical = (res, fn) => {
   }
 };
 
+// src/utils/base36.ts
+var DEFAULTS = {
+  bitSize: 80,
+  rotateBits: 17,
+  addConstant: "0x1fd0a5b7c3"
+};
+var isValidBase36 = (value) => /^[a-z0-9]+$/i.test(value);
+var normalizeInput = (value) => (value || "").trim();
+var assertSecret = (secret) => {
+  if (typeof secret !== "string" || secret.trim().length < 12) {
+    return { status: false, data: { message: "Missing or weak secret" } };
+  }
+  return { status: true, data: true };
+};
+var parseBase36BigInt = (value) => {
+  try {
+    const normalizedValue = normalizeInput(value);
+    if (!normalizedValue) {
+      return { status: false, data: { message: "Empty input" } };
+    }
+    if (!isValidBase36(normalizedValue)) {
+      return { status: false, data: { message: "Invalid base36 input" } };
+    }
+    const safeValue = normalizedValue.toLowerCase();
+    let output = 0n;
+    for (let i = 0; i < safeValue.length; i++) {
+      const char = safeValue[i];
+      const digit = char >= "0" && char <= "9" ? BigInt(char.charCodeAt(0) - 48) : BigInt(char.charCodeAt(0) - 87);
+      output = output * 36n + digit;
+    }
+    return { status: true, data: output };
+  } catch (error) {
+    return {
+      status: false,
+      data: { message: "Failed to parse base36 input", error }
+    };
+  }
+};
+var toBase36Lower = (value) => {
+  try {
+    if (value < 0n) {
+      return {
+        status: false,
+        data: { message: "Negative values are not supported" }
+      };
+    }
+    return { status: true, data: value.toString(36) };
+  } catch (error) {
+    return {
+      status: false,
+      data: { message: "Failed to convert to base36", error }
+    };
+  }
+};
+var getParams = (config) => {
+  try {
+    const bitSizeRaw = BigInt(config.bitSize ?? DEFAULTS.bitSize);
+    if (bitSizeRaw <= 0n) {
+      return {
+        status: false,
+        data: { message: "bitSize must be greater than 0" }
+      };
+    }
+    const rotateRaw = BigInt(config.rotateBits ?? DEFAULTS.rotateBits);
+    const rotateBits = (rotateRaw % bitSizeRaw + bitSizeRaw) % bitSizeRaw;
+    const addConstant = BigInt(config.addConstant ?? DEFAULTS.addConstant);
+    const mask = (1n << bitSizeRaw) - 1n;
+    return {
+      status: true,
+      data: { bitSize: bitSizeRaw, rotateBits, addConstant, mask }
+    };
+  } catch (error) {
+    return { status: false, data: { message: "Invalid configuration", error } };
+  }
+};
+var secretToKey = (secret, mask) => {
+  let key = 0n;
+  const safeSecret = secret.trim();
+  for (let i = 0; i < safeSecret.length; i++) {
+    key = key * 131n + BigInt(safeSecret.charCodeAt(i)) & mask;
+  }
+  return key;
+};
+var rotl = (x, r, bitSize, mask) => {
+  if (r === 0n) return x & mask;
+  return (x << r | x >> bitSize - r) & mask;
+};
+var rotr = (x, r, bitSize, mask) => {
+  if (r === 0n) return x & mask;
+  return (x >> r | x << bitSize - r) & mask;
+};
+var encodeBase36Code = (identifier, config) => {
+  try {
+    const secretCheck = assertSecret(config?.secret);
+    if (!secretCheck.status) {
+      return { status: false, data: secretCheck.data };
+    }
+    const input = normalizeInput(identifier);
+    if (!input) {
+      return { status: false, data: { message: "Identifier is required" } };
+    }
+    if (!isValidBase36(input)) {
+      return {
+        status: false,
+        data: { message: "Identifier must be base36 (0-9, A-Z)" }
+      };
+    }
+    const parsed = parseBase36BigInt(input);
+    if (!parsed.status) {
+      return { status: false, data: parsed.data };
+    }
+    const params = getParams(config);
+    if (!params.status) {
+      return { status: false, data: params.data };
+    }
+    const {
+      bitSize,
+      rotateBits,
+      addConstant,
+      mask
+    } = params.data;
+    const key = secretToKey(config.secret, mask);
+    let value = parsed.data & mask;
+    value = value ^ key;
+    value = value + addConstant & mask;
+    value = rotl(value, rotateBits, bitSize, mask);
+    const codeResult = toBase36Lower(value);
+    if (!codeResult.status) {
+      return { status: false, data: codeResult.data };
+    }
+    return { status: true, data: { code: codeResult.data } };
+  } catch (error) {
+    return {
+      status: false,
+      data: { message: "Failed to encode code", error }
+    };
+  }
+};
+var decodeBase36Code = (code, config) => {
+  try {
+    const secretCheck = assertSecret(config?.secret);
+    if (!secretCheck.status) {
+      return { status: false, data: secretCheck.data };
+    }
+    const input = normalizeInput(code);
+    if (!input) {
+      return { status: false, data: { message: "Code is required" } };
+    }
+    if (!isValidBase36(input)) {
+      return {
+        status: false,
+        data: { message: "Code must be base36 (0-9, a-z)" }
+      };
+    }
+    const parsed = parseBase36BigInt(input);
+    if (!parsed.status) {
+      return { status: false, data: parsed.data };
+    }
+    const params = getParams(config);
+    if (!params.status) {
+      return { status: false, data: params.data };
+    }
+    const {
+      bitSize,
+      rotateBits,
+      addConstant,
+      mask
+    } = params.data;
+    const key = secretToKey(config.secret, mask);
+    let value = parsed.data & mask;
+    value = rotr(value, rotateBits, bitSize, mask);
+    value = value - addConstant & mask;
+    value = value ^ key;
+    const identifierResult = toBase36Lower(value);
+    if (!identifierResult.status) {
+      return { status: false, data: identifierResult.data };
+    }
+    return {
+      status: true,
+      data: { identifier: identifierResult.data.toUpperCase() }
+    };
+  } catch (error) {
+    return {
+      status: false,
+      data: { message: "Failed to decode code", error }
+    };
+  }
+};
+
 // src/index.ts
 var isBrowser = typeof globalThis !== "undefined" && typeof globalThis.document !== "undefined";
 var isNode = typeof process !== "undefined" && !!process.versions?.node;
 
-export { addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, capitalizeFirst, capitalizeWords, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, decodeObject, decodeString, deferAfterResponse, deferAfterResponseNonCritical, deferNonCritical, deferPostReturn, delay, difference, encodeObject, encodeString, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, formatCurrencyPro, formatDecimalNumber, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrEmptyObject, isNilEmptyOrZeroLen, isNilEmptyOrZeroLength, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilOrZeroLength, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, numbersEqual, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeAdd, safeDivide, safeJSONParse, safeMultiply, safeParseFloat, safeParseInt, safeSubtract, sanitize, sanitizeMarkdown, sentenceCase, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };
+export { addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, capitalizeFirst, capitalizeWords, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, decodeBase36Code, decodeObject, decodeString, deferAfterResponse, deferAfterResponseNonCritical, deferNonCritical, deferPostReturn, delay, difference, encodeBase36Code, encodeObject, encodeString, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, formatCurrencyPro, formatDecimalNumber, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrEmptyObject, isNilEmptyOrZeroLen, isNilEmptyOrZeroLength, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilOrZeroLength, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, numbersEqual, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeAdd, safeDivide, safeJSONParse, safeMultiply, safeParseFloat, safeParseInt, safeSubtract, sanitize, sanitizeMarkdown, sentenceCase, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map