@fgv/ts-extras 5.0.2 → 5.1.0-0

package/lib/packlets/ai-assist/registry.js

@@ -0,0 +1,150 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allProviderIds = void 0;
+exports.getProviderDescriptors = getProviderDescriptors;
+exports.getProviderDescriptor = getProviderDescriptor;
+/**
+ * Centralized provider registry — single source of truth for all AI provider metadata.
+ * @packageDocumentation
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+// ============================================================================
+// Built-in providers
+// ============================================================================
+/**
+ * All known AI provider descriptors. Copy-paste first, then alphabetical.
+ * @internal
+ */
+const BUILTIN_PROVIDERS = [
+    {
+        id: 'copy-paste',
+        label: 'Copy / Paste',
+        buttonLabel: 'AI Assist | Copy',
+        needsSecret: false,
+        apiFormat: 'openai',
+        baseUrl: '',
+        defaultModel: '',
+        supportedTools: [],
+        corsRestricted: false
+    },
+    {
+        id: 'anthropic',
+        label: 'Anthropic Claude',
+        buttonLabel: 'AI Assist | Claude',
+        needsSecret: true,
+        apiFormat: 'anthropic',
+        baseUrl: 'https://api.anthropic.com/v1',
+        defaultModel: 'claude-sonnet-4-5-20250929',
+        supportedTools: ['web_search'],
+        corsRestricted: false
+    },
+    {
+        id: 'google-gemini',
+        label: 'Google Gemini',
+        buttonLabel: 'AI Assist | Gemini',
+        needsSecret: true,
+        apiFormat: 'gemini',
+        baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+        defaultModel: 'gemini-2.5-flash',
+        supportedTools: ['web_search'],
+        corsRestricted: false
+    },
+    {
+        id: 'groq',
+        label: 'Groq',
+        buttonLabel: 'AI Assist | Groq',
+        needsSecret: true,
+        apiFormat: 'openai',
+        baseUrl: 'https://api.groq.com/openai/v1',
+        defaultModel: 'llama-3.3-70b-versatile',
+        supportedTools: [],
+        corsRestricted: false
+    },
+    {
+        id: 'mistral',
+        label: 'Mistral',
+        buttonLabel: 'AI Assist | Mistral',
+        needsSecret: true,
+        apiFormat: 'openai',
+        baseUrl: 'https://api.mistral.ai/v1',
+        defaultModel: 'mistral-large-latest',
+        supportedTools: [],
+        corsRestricted: false
+    },
+    {
+        id: 'openai',
+        label: 'OpenAI',
+        buttonLabel: 'AI Assist | OpenAI',
+        needsSecret: true,
+        apiFormat: 'openai',
+        baseUrl: 'https://api.openai.com/v1',
+        defaultModel: 'gpt-4o',
+        supportedTools: ['web_search'],
+        corsRestricted: false
+    },
+    {
+        id: 'xai-grok',
+        label: 'xAI Grok',
+        buttonLabel: 'AI Assist | Grok',
+        needsSecret: true,
+        apiFormat: 'openai',
+        baseUrl: 'https://api.x.ai/v1',
+        defaultModel: { base: 'grok-4-1-fast', tools: 'grok-4-1-fast-reasoning' },
+        supportedTools: ['web_search'],
+        corsRestricted: true
+    }
+];
+/**
+ * Index for O(1) lookup by id.
+ * @internal
+ */
+const PROVIDER_BY_ID = new Map(BUILTIN_PROVIDERS.map((d) => [d.id, d]));
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * All valid provider ID values, in the same order as the registry.
+ * @public
+ */
+exports.allProviderIds = BUILTIN_PROVIDERS.map((d) => d.id);
+/**
+ * Get all known provider descriptors. Copy-paste first, then alphabetical.
+ * @returns All built-in provider descriptors
+ * @public
+ */
+function getProviderDescriptors() {
+    return BUILTIN_PROVIDERS;
+}
+/**
+ * Get a provider descriptor by id.
+ * @param id - The provider identifier
+ * @returns The descriptor, or a failure if the provider is unknown
+ * @public
+ */
+function getProviderDescriptor(id) {
+    const descriptor = PROVIDER_BY_ID.get(id);
+    if (!descriptor) {
+        return (0, ts_utils_1.fail)(`unknown AI provider: ${id}`);
+    }
+    return (0, ts_utils_1.succeed)(descriptor);
+}
+//# sourceMappingURL=registry.js.map

package/lib/packlets/ai-assist/toolFormats.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Provider-specific tool format translation and tool resolution logic.
+ * @packageDocumentation
+ */
+import { type JsonObject } from '@fgv/ts-json-base';
+import { type AiServerToolConfig, type IAiProviderDescriptor, type IAiToolEnablement } from './model';
+/**
+ * Resolves the effective tools for a completion call.
+ *
+ * - If per-call tools are provided, they override settings-level tools entirely.
+ * - Otherwise, settings-level enabled tools are used.
+ * - Only tools supported by the provider are included.
+ * - Returns an empty array if no tools are enabled (= no tools sent).
+ *
+ * @param descriptor - The provider descriptor (used to filter by supported tools)
+ * @param settingsTools - Tool enablement from provider settings (optional)
+ * @param perCallTools - Per-call tool override (optional)
+ * @returns The resolved list of tool configs to include in the request
+ * @public
+ */
+export declare function resolveEffectiveTools(descriptor: IAiProviderDescriptor, settingsTools?: ReadonlyArray<IAiToolEnablement>, perCallTools?: ReadonlyArray<AiServerToolConfig>): ReadonlyArray<AiServerToolConfig>;
+/**
+ * Formats tool configs for the xAI/OpenAI Responses API.
+ * @param tools - The resolved tool configs
+ * @returns Provider-native tool objects for the `tools` request field
+ * @public
+ */
+export declare function toResponsesApiTools(tools: ReadonlyArray<AiServerToolConfig>): ReadonlyArray<JsonObject>;
+/**
+ * Formats tool configs for the Anthropic Messages API.
+ * @param tools - The resolved tool configs
+ * @returns Provider-native tool objects for the `tools` request field
+ * @public
+ */
+export declare function toAnthropicTools(tools: ReadonlyArray<AiServerToolConfig>): ReadonlyArray<JsonObject>;
+/**
+ * Formats tool configs for the Gemini generateContent API.
+ * Gemini uses `google_search` for search grounding — no per-tool config options.
+ * @param tools - The resolved tool configs
+ * @returns Provider-native tool objects for the `tools` request field
+ * @public
+ */
+export declare function toGeminiTools(tools: ReadonlyArray<AiServerToolConfig>): ReadonlyArray<JsonObject>;
+//# sourceMappingURL=toolFormats.d.ts.map

package/lib/packlets/ai-assist/toolFormats.js

@@ -0,0 +1,166 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveEffectiveTools = resolveEffectiveTools;
+exports.toResponsesApiTools = toResponsesApiTools;
+exports.toAnthropicTools = toAnthropicTools;
+exports.toGeminiTools = toGeminiTools;
+// ============================================================================
+// Tool resolution
+// ============================================================================
+/**
+ * Resolves the effective tools for a completion call.
+ *
+ * - If per-call tools are provided, they override settings-level tools entirely.
+ * - Otherwise, settings-level enabled tools are used.
+ * - Only tools supported by the provider are included.
+ * - Returns an empty array if no tools are enabled (= no tools sent).
+ *
+ * @param descriptor - The provider descriptor (used to filter by supported tools)
+ * @param settingsTools - Tool enablement from provider settings (optional)
+ * @param perCallTools - Per-call tool override (optional)
+ * @returns The resolved list of tool configs to include in the request
+ * @public
+ */
+function resolveEffectiveTools(descriptor, settingsTools, perCallTools) {
+    const supported = new Set(descriptor.supportedTools);
+    if (perCallTools !== undefined) {
+        return perCallTools.filter((t) => supported.has(t.type));
+    }
+    if (settingsTools === undefined) {
+        return [];
+    }
+    return settingsTools
+        .filter((e) => e.enabled && supported.has(e.type))
+        .map((e) => { var _a; return (_a = e.config) !== null && _a !== void 0 ? _a : { type: e.type }; });
+}
+// ============================================================================
+// OpenAI / xAI Responses API format
+// ============================================================================
+/**
+ * Formats a web search tool config for the xAI/OpenAI Responses API.
+ * @internal
+ */
+function webSearchToResponsesApi(config) {
+    const tool = { type: 'web_search' };
+    if (config.allowedDomains || config.blockedDomains) {
+        const filters = {};
+        if (config.allowedDomains) {
+            filters.allowed_domains = [...config.allowedDomains];
+        }
+        if (config.blockedDomains) {
+            filters.excluded_domains = [...config.blockedDomains];
+        }
+        tool.filters = filters;
+    }
+    if (config.enableImageUnderstanding) {
+        tool.enable_image_understanding = true;
+    }
+    return tool;
+}
+/**
+ * Formats tool configs for the xAI/OpenAI Responses API.
+ * @param tools - The resolved tool configs
+ * @returns Provider-native tool objects for the `tools` request field
+ * @public
+ */
+function toResponsesApiTools(tools) {
+    return tools.map((t) => {
+        switch (t.type) {
+            case 'web_search':
+                return webSearchToResponsesApi(t);
+            /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
+            default: {
+                const _exhaustive = t.type;
+                return { type: String(_exhaustive) };
+            }
+        }
+    });
+}
+// ============================================================================
+// Anthropic Messages API format
+// ============================================================================
+/**
+ * Formats a web search tool config for the Anthropic Messages API.
+ * @internal
+ */
+function webSearchToAnthropic(config) {
+    const tool = {
+        type: 'web_search_20250305',
+        name: 'web_search'
+    };
+    if (config.maxUses !== undefined) {
+        tool.max_uses = config.maxUses;
+    }
+    if (config.allowedDomains) {
+        tool.allowed_domains = [...config.allowedDomains];
+    }
+    if (config.blockedDomains) {
+        tool.blocked_domains = [...config.blockedDomains];
+    }
+    return tool;
+}
+/**
+ * Formats tool configs for the Anthropic Messages API.
+ * @param tools - The resolved tool configs
+ * @returns Provider-native tool objects for the `tools` request field
+ * @public
+ */
+function toAnthropicTools(tools) {
+    return tools.map((t) => {
+        switch (t.type) {
+            case 'web_search':
+                return webSearchToAnthropic(t);
+            /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
+            default: {
+                const _exhaustive = t.type;
+                return { type: String(_exhaustive) };
+            }
+        }
+    });
+}
+// ============================================================================
+// Gemini generateContent API format
+// ============================================================================
+/**
+ * Formats tool configs for the Gemini generateContent API.
+ * Gemini uses `google_search` for search grounding — no per-tool config options.
+ * @param tools - The resolved tool configs
+ * @returns Provider-native tool objects for the `tools` request field
+ * @public
+ */
+function toGeminiTools(tools) {
+    const result = [];
+    for (const t of tools) {
+        switch (t.type) {
+            case 'web_search':
+                result.push({ google_search: {} });
+                break;
+            /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
+            default: {
+                const _exhaustive = t.type;
+                result.push({ type: String(_exhaustive) });
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=toolFormats.js.map

package/lib/packlets/crypto-utils/constants.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Current format version for encrypted files.
+ * @public
+ */
+export declare const ENCRYPTED_FILE_FORMAT: "encrypted-collection-v1";
+/**
+ * Default encryption algorithm.
+ * @public
+ */
+export declare const DEFAULT_ALGORITHM: "AES-256-GCM";
+/**
+ * Key size in bytes for AES-256.
+ * @public
+ */
+export declare const AES_256_KEY_SIZE: number;
+/**
+ * IV size in bytes for GCM mode.
+ * @public
+ */
+export declare const GCM_IV_SIZE: number;
+/**
+ * Auth tag size in bytes for GCM mode.
+ * @public
+ */
+export declare const GCM_AUTH_TAG_SIZE: number;
+//# sourceMappingURL=constants.d.ts.map

package/lib/packlets/crypto-utils/constants.js

@@ -0,0 +1,51 @@
+"use strict";
+// Copyright (c) 2024 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GCM_AUTH_TAG_SIZE = exports.GCM_IV_SIZE = exports.AES_256_KEY_SIZE = exports.DEFAULT_ALGORITHM = exports.ENCRYPTED_FILE_FORMAT = void 0;
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Current format version for encrypted files.
+ * @public
+ */
+exports.ENCRYPTED_FILE_FORMAT = 'encrypted-collection-v1';
+/**
+ * Default encryption algorithm.
+ * @public
+ */
+exports.DEFAULT_ALGORITHM = 'AES-256-GCM';
+/**
+ * Key size in bytes for AES-256.
+ * @public
+ */
+exports.AES_256_KEY_SIZE = 32;
+/**
+ * IV size in bytes for GCM mode.
+ * @public
+ */
+exports.GCM_IV_SIZE = 12;
+/**
+ * Auth tag size in bytes for GCM mode.
+ * @public
+ */
+exports.GCM_AUTH_TAG_SIZE = 16;
+//# sourceMappingURL=constants.js.map

package/lib/packlets/crypto-utils/converters.d.ts

@@ -0,0 +1,58 @@
+import { JsonValue } from '@fgv/ts-json-base';
+import { Converter } from '@fgv/ts-utils';
+import { EncryptedFileErrorMode, EncryptedFileFormat, EncryptionAlgorithm, IEncryptedFile, IKeyDerivationParams, INamedSecret, KeyDerivationFunction } from './model';
+/**
+ * Converter for {@link CryptoUtils.EncryptionAlgorithm | encryption algorithm} values.
+ * @public
+ */
+export declare const encryptionAlgorithm: Converter<EncryptionAlgorithm>;
+/**
+ * Converter for {@link CryptoUtils.EncryptedFileFormat | encrypted file format} version.
+ * @public
+ */
+export declare const encryptedFileFormat: Converter<EncryptedFileFormat>;
+/**
+ * Converter for {@link CryptoUtils.EncryptedFileErrorMode | encrypted file error mode}.
+ * @public
+ */
+export declare const encryptedFileErrorMode: Converter<EncryptedFileErrorMode>;
+/**
+ * Converter for {@link CryptoUtils.KeyDerivationFunction | key derivation function} type.
+ * @public
+ */
+export declare const keyDerivationFunction: Converter<KeyDerivationFunction>;
+/**
+ * Converter for {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.
+ * @public
+ */
+export declare const keyDerivationParams: Converter<IKeyDerivationParams>;
+/**
+ * Converter for base64 strings (validates format).
+ * @public
+ */
+export declare const base64String: Converter<string>;
+/**
+ * Converter which converts a base64 string to a Uint8Array.
+ * @public
+ */
+export declare const uint8ArrayFromBase64: Converter<Uint8Array>;
+/**
+ * Converter for {@link CryptoUtils.INamedSecret | named secret} from JSON representation.
+ * Expects key as base64 string in JSON, converts to Uint8Array.
+ * @public
+ */
+export declare const namedSecret: Converter<INamedSecret>;
+/**
+ * Creates a converter for {@link CryptoUtils.IEncryptedFile | encrypted files} with optional typed metadata.
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @param metadataConverter - Optional converter for validating metadata field
+ * @returns A converter that validates and converts encrypted file structures
+ * @public
+ */
+export declare function createEncryptedFileConverter<TMetadata = JsonValue>(metadataConverter?: Converter<TMetadata>): Converter<IEncryptedFile<TMetadata>>;
+/**
+ * Default converter for encrypted files without typed metadata.
+ * @public
+ */
+export declare const encryptedFile: Converter<IEncryptedFile>;
+//# sourceMappingURL=converters.d.ts.map