@frontmcp/utils 0.12.1 → 1.0.0-beta.1

package/llm/index.d.ts

@@ -0,0 +1,2 @@
+export { processPlatformToolCalls } from './llm-tool-handlers';
+export type { CallToolFn, OpenAIToolCallItem, OpenAIToolResponse, ClaudeToolUseBlock, ClaudeToolResultBlock, VercelToolCallInfo, PlatformToolCallsInput, PlatformToolCallsOutput, SupportedPlatform, } from './llm-tool-handler.types';

package/llm/llm-tool-handler.types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * LLM platform tool call types.
+ *
+ * Defines the input/output shapes for processing tool calls across
+ * different AI SDK platforms (OpenAI, Claude, Vercel AI).
+ */
+/** Generic function signature for executing an MCP tool. */
+export type CallToolFn = (name: string, args?: Record<string, unknown>) => Promise<unknown>;
+export interface OpenAIToolCallItem {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ClaudeToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface VercelToolCallInfo {
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+}
+export interface OpenAIToolResponse {
+    role: 'tool';
+    tool_call_id: string;
+    content: string;
+}
+export interface ClaudeToolResultBlock {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+}
+export type PlatformToolCallsInput = {
+    openai: OpenAIToolCallItem[];
+    claude: ClaudeToolUseBlock[];
+    'vercel-ai': VercelToolCallInfo;
+};
+export type PlatformToolCallsOutput = {
+    openai: OpenAIToolResponse[];
+    claude: ClaudeToolResultBlock[];
+    'vercel-ai': unknown;
+};
+export type SupportedPlatform = keyof PlatformToolCallsInput;

package/llm/llm-tool-handlers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * processPlatformToolCalls — generic handler that processes LLM tool calls
+ * for any supported platform and returns platform-appropriate responses.
+ *
+ * Usable from both React hooks and Node.js backends.
+ */
+import type { CallToolFn, OpenAIToolCallItem, OpenAIToolResponse, ClaudeToolUseBlock, ClaudeToolResultBlock, VercelToolCallInfo } from './llm-tool-handler.types';
+export declare function processPlatformToolCalls(platform: 'openai', calls: OpenAIToolCallItem[], callTool: CallToolFn): Promise<OpenAIToolResponse[]>;
+export declare function processPlatformToolCalls(platform: 'claude', calls: ClaudeToolUseBlock[], callTool: CallToolFn): Promise<ClaudeToolResultBlock[]>;
+export declare function processPlatformToolCalls(platform: 'vercel-ai', calls: VercelToolCallInfo, callTool: CallToolFn): Promise<unknown>;

package/naming/index.d.ts

@@ -1 +1,2 @@
-export { NameCase, splitWords, toCase, sepFor, shortHash, ensureMaxLen, idFromString } from './naming';
+export { splitWords, toCase, sepFor, shortHash, ensureMaxLen, idFromString } from './naming';
+export type { NameCase } from './naming';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/utils",
-  "version": "0.12.1",
+  "version": "1.0.0-beta.1",
   "description": "Shared utility functions for FrontMCP - string manipulation, URI handling, path utilities, and more",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -44,6 +44,28 @@
       "optional": true
     }
   },
+  "imports": {
+    "#crypto-provider": {
+      "browser": "./crypto/browser.js",
+      "default": "./crypto/node.js"
+    },
+    "#async-context": {
+      "browser": "./async-context/browser-async-context.js",
+      "default": "./async-context/node-async-context.js"
+    },
+    "#event-emitter": {
+      "browser": "./event-emitter/browser-event-emitter.js",
+      "default": "./event-emitter/node-event-emitter.js"
+    },
+    "#env": {
+      "browser": "./env/browser-env.js",
+      "default": "./env/node-env.js"
+    },
+    "#path": {
+      "browser": "./path/browser-path.js",
+      "default": "./path/node-path.js"
+    }
+  },
   "type": "commonjs",
   "main": "./index.js",
   "module": "./esm/index.mjs",

package/path/browser-path.d.ts

@@ -0,0 +1,5 @@
+export declare function resolve(..._segments: string[]): string;
+export declare function join(..._segments: string[]): string;
+export declare function basename(p: string, ext?: string): string;
+export declare function dirname(_p: string): string;
+export declare function extname(p: string): string;

package/path/index.d.ts

@@ -1 +1,2 @@
 export { trimSlashes, joinPath } from './path';
+export { resolve as pathResolve, join as pathJoin, basename, dirname, extname } from '#path';

package/path/node-path.d.ts

@@ -0,0 +1 @@
+export { resolve, join, basename, dirname, extname } from 'path';

package/storage/adapters/index.d.ts

@@ -10,3 +10,7 @@ export { VercelKvStorageAdapter } from './vercel-kv';
 export { UpstashStorageAdapter } from './upstash';
 export { FileSystemStorageAdapter } from './filesystem';
 export type { FileSystemAdapterOptions } from './filesystem';
+export { LocalStorageAdapter } from './localstorage';
+export type { LocalStorageAdapterOptions } from './localstorage';
+export { IndexedDBStorageAdapter } from './indexeddb';
+export type { IndexedDBAdapterOptions } from './indexeddb';

package/storage/adapters/indexeddb.d.ts

@@ -0,0 +1,77 @@
+/**
+ * IndexedDB Storage Adapter
+ *
+ * Browser-compatible storage using the IndexedDB API.
+ * Persistent, supports larger data than localStorage (~50MB+ per origin).
+ *
+ * Suitable for key persistence in browser environments where
+ * larger storage capacity is needed.
+ */
+import { BaseStorageAdapter } from './base';
+import type { SetOptions } from '../types';
+/**
+ * Options for the IndexedDB adapter.
+ */
+export interface IndexedDBAdapterOptions {
+    /**
+     * Database name.
+     * @default 'frontmcp'
+     */
+    dbName?: string;
+    /**
+     * Object store name.
+     * @default 'kv'
+     */
+    storeName?: string;
+    /**
+     * Key prefix for namespacing.
+     * @default 'frontmcp:'
+     */
+    prefix?: string;
+}
+/**
+ * Browser IndexedDB-based storage adapter.
+ *
+ * Features:
+ * - Persistent across page reloads and browser restarts
+ * - Asynchronous API matching StorageAdapter contract
+ * - TTL support via stored expiration timestamps
+ * - Larger storage limit than localStorage (~50MB+)
+ *
+ * Limitations:
+ * - No pub/sub support
+ * - Browser-only (requires globalThis.indexedDB)
+ * - Pattern matching uses simple iteration over all keys
+ */
+export declare class IndexedDBStorageAdapter extends BaseStorageAdapter {
+    protected readonly backendName = "indexeddb";
+    private readonly dbName;
+    private readonly storeName;
+    private readonly prefix;
+    private db;
+    constructor(options?: IndexedDBAdapterOptions);
+    private assertAvailable;
+    private key;
+    private stripPrefix;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ping(): Promise<boolean>;
+    private getStore;
+    private idbRequest;
+    private idbTransaction;
+    get(key: string): Promise<string | null>;
+    protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    expire(key: string, ttlSeconds: number): Promise<boolean>;
+    ttl(key: string): Promise<number | null>;
+    keys(pattern?: string): Promise<string[]>;
+    incr(key: string): Promise<number>;
+    decr(key: string): Promise<number>;
+    /**
+     * Increment by amount. NOT atomic — uses read-then-write which can race
+     * under concurrent access (e.g., multiple browser tabs).
+     */
+    incrBy(key: string, amount: number): Promise<number>;
+    private matchPattern;
+}

package/storage/adapters/localstorage.d.ts

@@ -0,0 +1,84 @@
+/**
+ * LocalStorage Storage Adapter
+ *
+ * Browser-compatible storage using the Web Storage API (localStorage).
+ * Persistent across page reloads but limited to ~5MB per origin.
+ *
+ * Supports optional AES-256-GCM at-rest encryption when an encryption key
+ * is provided, preventing clear-text storage of sensitive values.
+ */
+import { BaseStorageAdapter } from './base';
+import type { SetOptions, MessageHandler, Unsubscribe } from '../types';
+/**
+ * Options for the LocalStorage adapter.
+ */
+export interface LocalStorageAdapterOptions {
+    /**
+     * Key prefix for namespacing.
+     * @default 'frontmcp:'
+     */
+    prefix?: string;
+    /**
+     * Optional 32-byte AES-256-GCM encryption key.
+     * When provided, all values are encrypted at rest in localStorage.
+     */
+    encryptionKey?: Uint8Array;
+    /**
+     * Whether to allow plaintext storage when no encryption key is provided.
+     * @default true
+     */
+    allowPlaintext?: boolean;
+}
+/**
+ * Browser localStorage-based storage adapter.
+ *
+ * Features:
+ * - Persistent across page reloads
+ * - Synchronous underlying API (async interface for consistency)
+ * - TTL support via stored expiration timestamps
+ * - Size-limited (~5MB per origin)
+ *
+ * Limitations:
+ * - No pub/sub support
+ * - incr/decr/incrBy are non-atomic (read-then-write); do not assume atomicity under concurrent access
+ * - String-only values (matches StorageAdapter contract)
+ * - Pattern matching uses simple iteration
+ */
+export declare class LocalStorageAdapter extends BaseStorageAdapter {
+    protected readonly backendName = "localstorage";
+    private readonly prefix;
+    private readonly encryptionKey;
+    private readonly allowPlaintext;
+    private readonly encoder;
+    private readonly decoder;
+    constructor(options?: LocalStorageAdapterOptions);
+    private assertAvailable;
+    private key;
+    private stripPrefix;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ping(): Promise<boolean>;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: SetOptions): Promise<void>;
+    protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    mget(keys: string[]): Promise<(string | null)[]>;
+    mset(entries: {
+        key: string;
+        value: string;
+        options?: SetOptions;
+    }[]): Promise<void>;
+    mdelete(keys: string[]): Promise<number>;
+    expire(key: string, ttlSeconds: number): Promise<boolean>;
+    ttl(key: string): Promise<number | null>;
+    keys(pattern?: string): Promise<string[]>;
+    count(pattern?: string): Promise<number>;
+    incr(key: string): Promise<number>;
+    decr(key: string): Promise<number>;
+    incrBy(key: string, amount: number): Promise<number>;
+    publish(): Promise<number>;
+    subscribe(_channel: string, _handler: MessageHandler): Promise<Unsubscribe>;
+    supportsPubSub(): boolean;
+    private matchPattern;
+}

package/storage/index.d.ts

@@ -12,7 +12,7 @@ export { TypedStorage } from './typed-storage';
 export type { TypedStorageOptions, TypedSetOptions, TypedSetEntry } from './typed-storage.types';
 export { EncryptedTypedStorage } from './encrypted-typed-storage';
 export type { EncryptedTypedStorageOptions, EncryptedSetOptions, EncryptedSetEntry, EncryptionKey, StoredEncryptedBlob, ClientKeyBinding, } from './encrypted-typed-storage.types';
-export { BaseStorageAdapter, MemoryStorageAdapter, RedisStorageAdapter, VercelKvStorageAdapter, UpstashStorageAdapter, FileSystemStorageAdapter, } from './adapters';
-export type { FileSystemAdapterOptions } from './adapters';
+export { BaseStorageAdapter, MemoryStorageAdapter, RedisStorageAdapter, VercelKvStorageAdapter, UpstashStorageAdapter, FileSystemStorageAdapter, LocalStorageAdapter, IndexedDBStorageAdapter, } from './adapters';
+export type { FileSystemAdapterOptions, LocalStorageAdapterOptions, IndexedDBAdapterOptions } from './adapters';
 export { globToRegex, matchesPattern, validatePattern, escapeGlob } from './utils/pattern';
 export { MAX_TTL_SECONDS, validateTTL, validateOptionalTTL, ttlToExpiresAt, expiresAtToTTL, isExpired, normalizeTTL, } from './utils/ttl';

package/uri/index.d.ts

@@ -1,2 +1,3 @@
 export { isValidMcpUri, extractUriScheme, isValidMcpUriTemplate } from './uri-validation';
-export { ParsedUriTemplate, parseUriTemplate, matchUriTemplate, expandUriTemplate, extractTemplateParams, isUriTemplate, } from './uri-template';
+export { parseUriTemplate, matchUriTemplate, expandUriTemplate, extractTemplateParams, isUriTemplate, } from './uri-template';
+export type { ParsedUriTemplate } from './uri-template';

package/esm/package.json

@@ -1,69 +0,0 @@
-{
-  "name": "@frontmcp/utils",
-  "version": "0.12.1",
-  "description": "Shared utility functions for FrontMCP - string manipulation, URI handling, path utilities, and more",
-  "author": "AgentFront <info@agentfront.dev>",
-  "license": "Apache-2.0",
-  "keywords": [
-    "utils",
-    "utilities",
-    "uri",
-    "url",
-    "string",
-    "path",
-    "typescript",
-    "mcp"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/agentfront/frontmcp.git",
-    "directory": "libs/utils"
-  },
-  "bugs": {
-    "url": "https://github.com/agentfront/frontmcp/issues"
-  },
-  "homepage": "https://github.com/agentfront/frontmcp/blob/main/libs/utils/README.md",
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "dependencies": {
-    "@noble/hashes": "^2.0.1",
-    "@noble/ciphers": "^2.1.1",
-    "@enclave-vm/ast": "^2.11.1",
-    "zod": "^4.0.0"
-  },
-  "peerDependencies": {
-    "@vercel/kv": "^2.0.0 || ^3.0.0",
-    "ioredis": "^5.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@vercel/kv": {
-      "optional": true
-    },
-    "ioredis": {
-      "optional": true
-    }
-  },
-  "type": "module",
-  "main": "../index.js",
-  "module": "./index.mjs",
-  "types": "../index.d.ts",
-  "sideEffects": false,
-  "exports": {
-    "./package.json": "../package.json",
-    ".": {
-      "require": {
-        "types": "../index.d.ts",
-        "default": "../index.js"
-      },
-      "import": {
-        "types": "../index.d.ts",
-        "default": "./index.mjs"
-      }
-    }
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "typescript": "^5.0.0"
-  }
-}