@salespark/toolkit 2.1.17 → 2.1.19

package/README.md

@@ -32,7 +32,8 @@ npm i @salespark/toolkit
 - **Defer utilities**: post-return microtask scheduling, non-critical timers, after-response hooks.
 - **Boolean utilities**: safe boolean conversion with common representations
 - **Validation utilities**: IBAN validator (ISO 13616), Portuguese tax ID validator
-- **Security utilities**: Markdown XSS protection, content sanitization, risk assessment, obfuscation helpers
+- **Security utilities**: Markdown XSS protection, content sanitization, risk assessment, obfuscation helpers, reversible base36 code encoding/decoding
+- **UUID utilities**: uuidv4 generator (RFC 4122)
 - **Environment detection**: `isBrowser`, `isNode` runtime checks
 
 ---
@@ -52,6 +53,7 @@ import {
   clamp,
   isBrowser,
   toBool,
+  uuidv4,
 } from "@salespark/toolkit";
 
 // Debounce a function
@@ -74,6 +76,9 @@ const safe = clamp(15, 0, 10); // 10
 // Convert to boolean
 const bool = toBool("yes"); // true
 
+// Generate UUID v4
+const id = uuidv4();
+
 // Check environment
 if (isBrowser) {
   /* browser-specific code */
@@ -102,6 +107,9 @@ const safe = _.clamp(15, 0, 10); // 10
 // Convert to boolean
 const bool = _.toBool("yes"); // true
 
+// Generate UUID v4
+const id = _.uuidv4();
+
 // Check environment
 if (_.isBrowser) {
   /* browser-specific code */
@@ -876,6 +884,50 @@ const decoded = decodeObject(encoded.data, "secret");
 
 **`decodeObject(encoded: string, secret: string): SalesParkContract<object>`** — Reverses `encodeObject` using the same secret.
 
+**`encodeBase36Code(identifier: string, config: EncodeDecodeConfig): SalesParkContract<{ code: string }>`** — Encodes a base36 identifier into a reversible lower-case base36 code using secret-based XOR + rotation.
+
+```typescript
+import { encodeBase36Code, decodeBase36Code } from "@salespark/toolkit";
+
+const config = {
+  secret: "my-super-secret-key",
+  bitSize: 80,
+  rotateBits: 17,
+  addConstant: "0x1fd0a5b7c3",
+};
+
+const encoded = encodeBase36Code("AB12CD34", config);
+// Result: { status: true, data: { code: "..." } }
+
+const decoded = decodeBase36Code(encoded.data.code, config);
+// Result: { status: true, data: { identifier: "AB12CD34" } }
+```
+
+**`decodeBase36Code(code: string, config: EncodeDecodeConfig): SalesParkContract<{ identifier: string }>`** — Decodes a previously encoded base36 code back to the original identifier (upper-case).
+
+```typescript
+const bad = encodeBase36Code("AB-12", {
+  secret: "my-super-secret-key",
+});
+// Result: { status: false, data: { message: "Identifier must be base36 (0-9, A-Z)" } }
+
+const weakSecret = decodeBase36Code("abc123", {
+  secret: "short",
+});
+// Result: { status: false, data: { message: "Missing or weak secret" } }
+```
+
+**`EncodeDecodeConfig`** — Configuration object used by `encodeBase36Code` and `decodeBase36Code`.
+
+```typescript
+type EncodeDecodeConfig = {
+  secret: string; // required, minimum 12 chars
+  bitSize?: number; // default: 80
+  rotateBits?: number; // default: 17
+  addConstant?: string; // default: "0x1fd0a5b7c3"
+};
+```
+
 ### ✅ Validation Utilities
 
 **`isPTTaxId(value: string | number): boolean`** — Validates Portuguese Tax ID (NIF) with MOD-11 algorithm and format checking.
@@ -1009,5 +1061,5 @@ MIT © [SalesPark](https://salespark.io)
 
 ---
 
-_Document version: 14_  
-_Last update: 06-02-2026_
+_Document version: 16_  
+_Last update: 14-03-2026_

package/dist/index.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var uuid = require('uuid');
+
 // src/utils/array.ts
 function uniqBy(arr, key) {
   const seen = /* @__PURE__ */ new Set();
@@ -2031,10 +2033,203 @@ 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;
 
+Object.defineProperty(exports, "uuidv4", {
+  enumerable: true,
+  get: function () { return uuid.v4; }
+});
 exports.addSpaceBetweenNumbers = addSpaceBetweenNumbers;
 exports.addThousandsSpace = addThousandsSpace;
 exports.areArraysDeepEqualUnordered = areArraysDeepEqualUnordered;
@@ -2051,6 +2246,7 @@ exports.compact = compact;
 exports.currencyToSymbol = currencyToSymbol;
 exports.debounce = debounce;
 exports.deburr = deburr;
+exports.decodeBase36Code = decodeBase36Code;
 exports.decodeObject = decodeObject;
 exports.decodeString = decodeString;
 exports.deferAfterResponse = deferAfterResponse;
@@ -2059,6 +2255,7 @@ exports.deferNonCritical = deferNonCritical;
 exports.deferPostReturn = deferPostReturn;
 exports.delay = delay;
 exports.difference = difference;
+exports.encodeBase36Code = encodeBase36Code;
 exports.encodeObject = encodeObject;
 exports.encodeString = encodeString;
 exports.fill = fill;