@vicaniddouglas/js_aide 1.19.2 → 1.20.1

package/README.md

@@ -44,6 +44,23 @@ Specialized formatting for financial data. Includes native support for **UGX** (
 
 A smart loader for external libraries (like SheetJS or jsPDF). Manages CDN fallbacks, retry logic, and ensures libraries are only loaded when needed.
 
+### `Response (ok / error)`
+
+A standardized response helper mirroring the Python `py_aide.response.Response` pattern. Every operation returns `{ status, data, log }`.
+
+- `ok(data)` — creates a success response (truthy via `valueOf()`)
+- `error(message)` — creates an error response (falsy via `valueOf()`)
+- The `Response` class has a **guarded constructor** — only `ok()` and `error()` can instantiate it; direct `new Response(...)` throws.
+
+### `FieldTokenizer`
+
+A cryptographic token engine compatible with the Python `FieldTokenizer`. Produces v3 tokens (URL-safe base64) that are byte-for-byte interchangeable between JS and Python.
+
+- **Non-deterministic** — same value produces a different token each time (random XOR seed)
+- **Integrity** — HMAC-SHA256 verification detects tampering
+- **TTL support** — tokens can expire; expiry is checked on `detokenize()`
+- **Isolated secrets** — different keys produce incompatible tokens
+
 ### `WebSocket Client`
 
 A professional-grade WebSocket implementation with automatic reconnection, heartbeat monitoring, and a registry to prevent duplicate connections.

package/declarations.d.ts

@@ -1614,4 +1614,89 @@ declare module "@vicaniddouglas/js_aide" {
    * @returns Object with element, callback, and pool counts
    */
   export function getWatcherStats(): WatcherStats;
+
+  // =========================================================
+  // Response (from response.js)
+  // =========================================================
+  /**
+   * Standardized response object with { status, data, log } shape.
+   * Cannot be instantiated directly — use ok() or error() instead.
+   */
+  export class Response {
+    /** true on success, false on error */
+    status: boolean;
+    /** Error message on failure, "" on success */
+    log: string;
+    /** The payload on success, null on error */
+    data: any;
+
+    /** @throws Error — use ok() / error() instead */
+    private constructor();
+
+    /** Truthy on success, falsy on error */
+    valueOf(): boolean;
+  }
+
+  /**
+   * Create a success Response.
+   * @param data Optional payload (defaults to undefined)
+   */
+  export function ok(data?: any): Response;
+
+  /**
+   * Create an error Response.
+   * @param message Error description
+   */
+  export function error(message: string): Response;
+
+  // =========================================================
+  // Tokenizer (from tokens/tokenizer.js)
+  // =========================================================
+  interface TokenizeOptions {
+    /** Time-to-live in seconds */
+    ttl?: number;
+    /** Explicit timestamp (Unix seconds) for testing */
+    timestamp?: number;
+  }
+
+  interface DetokenizeOptions {
+    /** Skip TTL expiry check (default: true) */
+    verify_ttl?: boolean;
+  }
+
+  /**
+   * Cryptographic token engine compatible with Python FieldTokenizer.
+   * Produces v3 tokens with HMAC-SHA256 integrity and optional TTL.
+   */
+  export class FieldTokenizer {
+    /**
+     * @param secret HMAC key — required, no default.
+     */
+    constructor(secret: string);
+
+    /**
+     * Transform a value into a non-deterministic, integrity-checked v3 token.
+     * @returns Response with .data = base64url token string on success
+     */
+    tokenize(value: any, options?: TokenizeOptions): Response;
+
+    /**
+     * Recover the original value from a token, verifying integrity.
+     * Handles v1, v2, and v3 tokens transparently.
+     * @returns Response with .data = original value on success
+     */
+    detokenize(token: string, options?: DetokenizeOptions): Response;
+  }
+
+  /**
+   * Quick token creation — one call, cached secret.
+   * Pass opts.secret on first call to set the secret.
+   */
+  export function tokenize(value: any, options?: TokenizeOptions & { secret?: string }): Response;
+
+  /**
+   * Quick token verification — one call, cached secret.
+   * Pass opts.secret on first call to set the secret.
+   */
+  export function detokenize(token: string, options?: DetokenizeOptions & { secret?: string }): Response;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vicaniddouglas/js_aide",
-  "version": "1.19.2",
+  "version": "1.20.1",
   "description": "A versatile collection of modular JavaScript utility helpers designed to streamline single-page application (SPA) development and general web programming tasks.",
   "main": "dist/js_aide.cjs.js",
   "module": "dist/js_aide.esm.js",