@salespark/toolkit 2.1.16 → 2.1.18

package/README.md

@@ -32,7 +32,7 @@ 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
 - **Environment detection**: `isBrowser`, `isNode` runtime checks
 
 ---
@@ -544,6 +544,22 @@ isNilOrEmpty(undefined);
 // Result: true
 ```
 
+**`isNilEmptyOrEmptyObject(value: unknown): boolean`** — Checks if value is nil, empty string, or an empty plain object (no own keys).
+
+```javascript
+isNilEmptyOrEmptyObject(null);
+// Result: true
+
+isNilEmptyOrEmptyObject("");
+// Result: true
+
+isNilEmptyOrEmptyObject({});
+// Result: true
+
+isNilEmptyOrEmptyObject({ a: 1 });
+// Result: false
+```
+
 **`hasNilOrEmpty(array: unknown): boolean`** — Checks if any element in array is nil or empty.
 
 ```javascript
@@ -836,17 +852,17 @@ assessSecurityRisks([]);
 // Result: { score: 0, level: "safe", recommendations: ["Content appears safe to use"] }
 ```
 
-**`scrambleString(value: string, secret: string): SalesParkContract<object>`** — Scrambles a string using a repeating secret (XOR) and Base64. Reversible obfuscation only (not crypto).
+**`encodeString(input: string, secret: string): SalesParkContract<any>`** — Base64-encodes a string and scrambles it with the provided secret (obfuscation only).
 
 ```javascript
-const scrambled = scrambleString("Hello", "secret");
+const encoded = encodeString("Hello", "secret");
 // Result: { status: true, data: "..." }
 
-const original = descrambleString(scrambled.data, "secret");
+const decoded = decodeString(encoded.data, "secret");
 // Result: { status: true, data: "Hello" }
 ```
 
-**`descrambleString(value: string, secret: string): SalesParkContract<object>`** — Reverses `scrambleString` using the same secret.
+**`decodeString(encoded: string, secret: string): SalesParkContract<any>`** — Reverses `encodeString` using the same secret.
 
 **`encodeObject(input: object, secret: string): SalesParkContract<object>`** — JSON-stringifies an object, Base64-encodes it, and scrambles the result (obfuscation only).
 
@@ -860,6 +876,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.
@@ -993,5 +1053,5 @@ MIT © [SalesPark](https://salespark.io)
 
 ---
 
-_Document version: 13_  
-_Last update: 09-01-2026_
+_Document version: 15_  
+_Last update: 16-02-2026_

package/dist/index.cjs

@@ -506,6 +506,17 @@ var isNilOrEmpty = (value) => {
     return true;
   }
 };
+var isNilEmptyOrEmptyObject = (value) => {
+  try {
+    if (isNilOrEmpty(value)) return true;
+    if (typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length === 0) {
+      return true;
+    }
+    return false;
+  } catch {
+    return true;
+  }
+};
 var hasNilOrEmpty = (array) => {
   try {
     if (!Array.isArray(array)) return true;
@@ -1881,6 +1892,24 @@ var encodeObject = (input, secret) => {
     return { status: false, data: error };
   }
 };
+var encodeString = (input, secret) => {
+  try {
+    if (typeof input !== "string") {
+      return { status: false, data: "Input must be a string" };
+    }
+    if (!secret || typeof secret !== "string") {
+      return { status: false, data: "Secret must be a non-empty string" };
+    }
+    const base64 = toBase64(input);
+    const scrambledResponse = scrambleString(base64, secret);
+    if (!scrambledResponse.status) {
+      return { status: false, data: "Scrambling failed" };
+    }
+    return { status: true, data: scrambledResponse.data };
+  } catch (error) {
+    return { status: false, data: error };
+  }
+};
 var decodeObject = (encoded, secret) => {
   try {
     if (typeof encoded !== "string") {
@@ -1899,6 +1928,24 @@ var decodeObject = (encoded, secret) => {
     return { status: false, data: error };
   }
 };
+var decodeString = (encoded, secret) => {
+  try {
+    if (typeof encoded !== "string") {
+      return { status: false, data: "Encoded value must be a string" };
+    }
+    if (!secret || typeof secret !== "string") {
+      return { status: false, data: "Secret must be a non-empty string" };
+    }
+    const descrambledResponse = descrambleString(encoded, secret);
+    if (!descrambledResponse.status) {
+      return { status: false, data: "Descrambling failed" };
+    }
+    const value = fromBase64(descrambledResponse.data);
+    return { status: true, data: value };
+  } catch (error) {
+    return { status: false, data: error };
+  }
+};
 
 // src/utils/defer.ts
 var swallow = (p) => p.catch(() => {
@@ -1984,6 +2031,195 @@ 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;
@@ -2004,15 +2240,18 @@ exports.compact = compact;
 exports.currencyToSymbol = currencyToSymbol;
 exports.debounce = debounce;
 exports.deburr = deburr;
+exports.decodeBase36Code = decodeBase36Code;
 exports.decodeObject = decodeObject;
+exports.decodeString = decodeString;
 exports.deferAfterResponse = deferAfterResponse;
 exports.deferAfterResponseNonCritical = deferAfterResponseNonCritical;
 exports.deferNonCritical = deferNonCritical;
 exports.deferPostReturn = deferPostReturn;
 exports.delay = delay;
-exports.descrambleString = descrambleString;
 exports.difference = difference;
+exports.encodeBase36Code = encodeBase36Code;
 exports.encodeObject = encodeObject;
+exports.encodeString = encodeString;
 exports.fill = fill;
 exports.flatten = flatten;
 exports.flattenDepth = flattenDepth;
@@ -2030,6 +2269,7 @@ exports.intersection = intersection;
 exports.isBrowser = isBrowser;
 exports.isFlattenable = isFlattenable;
 exports.isNil = isNil;
+exports.isNilEmptyOrEmptyObject = isNilEmptyOrEmptyObject;
 exports.isNilEmptyOrZeroLen = isNilEmptyOrZeroLen;
 exports.isNilEmptyOrZeroLength = isNilEmptyOrZeroLength;
 exports.isNilOrEmpty = isNilOrEmpty;
@@ -2072,7 +2312,6 @@ exports.safeParseInt = safeParseInt;
 exports.safeSubtract = safeSubtract;
 exports.sanitize = sanitize;
 exports.sanitizeMarkdown = sanitizeMarkdown;
-exports.scrambleString = scrambleString;
 exports.sentenceCase = sentenceCase;
 exports.shuffle = shuffle;
 exports.slugify = slugify;