@supernal/interface-nextjs 1.0.26 → 1.0.28

package/dist/index.d.mts

@@ -1,8 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1 from 'react';
-import { NavigationGraph, NavigationPath, NavigationContext, ToolMetadata } from '@supernal/interface/browser';
-import { AIInterface } from '@supernal/interface';
-export { AICommand, AIResponse } from '@supernal/interface';
+import { NavigationGraph, NavigationPath, NavigationContext, ToolMetadata, AIInterface } from '@supernal/interface/browser';
+export { AICommand, AIResponse } from '@supernal/interface/browser';
 
 interface SupernalProviderProps {
     children: React$1.ReactNode;
@@ -134,15 +133,173 @@ interface ChatContextType {
     sendMessage: (text: string) => Promise<void>;
     clearMessages: () => void;
     isLoading: boolean;
+    /** Whether real AI mode is active (API key is valid) */
+    isAiMode: boolean;
 }
 declare function useChatContext(): ChatContextType;
-declare function ChatProvider({ children, mode, apiKey, onToolExecute, }: {
+declare function ChatProvider({ children, mode, apiKey: propApiKey, onToolExecute, }: {
     children: React$1.ReactNode;
     mode?: 'fuzzy' | 'ai';
     apiKey?: string;
     onToolExecute?: (tool: string, result: any) => void;
 }): react_jsx_runtime.JSX.Element;
 
+type ApiKeyStatus = 'none' | 'validating' | 'valid' | 'invalid' | 'locked';
+interface UseApiKeyStorageOptions {
+    /**
+     * Enable encrypted storage (requires passphrase)
+     * @default false
+     */
+    encrypted?: boolean;
+    /**
+     * Callback when passphrase is needed for encrypted storage
+     */
+    onPassphraseRequired?: () => Promise<string>;
+    /**
+     * Callback when passphrase is invalid
+     */
+    onPassphraseInvalid?: () => void;
+}
+/**
+ * Hook for managing API key storage with validation
+ *
+ * This is the simple single-site version using localStorage.
+ * Compatible with future VaultClient integration for cross-site support.
+ *
+ * Features:
+ * - localStorage persistence (single site)
+ * - Format validation (sk-ant-* prefix, minimum length)
+ * - Optional live validation with Anthropic API
+ * - Masked display for security
+ * - Optional encryption at rest (Phase 1 of vault system)
+ *
+ * @param options - Configuration options
+ */
+declare function useApiKeyStorage(options?: UseApiKeyStorageOptions): {
+    hasApiKey: boolean;
+    isLocked: boolean;
+    setApiKey: (key: string, validate?: boolean) => Promise<boolean>;
+    clearApiKey: () => void;
+    revalidate: () => Promise<boolean>;
+    unlock: (passphrase: string) => Promise<boolean>;
+    lock: () => void;
+    apiKey: string | null;
+    status: ApiKeyStatus;
+    error: string | null;
+    maskedKey: string | null;
+};
+type UseApiKeyStorageReturn = ReturnType<typeof useApiKeyStorage>;
+
+interface ApiKeyProviderProps {
+    children: React$1.ReactNode;
+    /**
+     * Optional initial API key (e.g., from environment variable for dev)
+     * If provided and no key is in storage, this will be used
+     */
+    initialApiKey?: string;
+}
+declare function ApiKeyProvider({ children, initialApiKey }: ApiKeyProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access API key state and methods
+ * Must be used within ApiKeyProvider
+ */
+declare function useApiKey(): UseApiKeyStorageReturn;
+/**
+ * Hook to optionally access API key state
+ * Returns null if not within ApiKeyProvider (no error thrown)
+ */
+declare function useApiKeyOptional(): UseApiKeyStorageReturn | null;
+
+/**
+ * ClaudeClient - Simple direct API client for BYOK mode
+ *
+ * This client makes direct calls to the Anthropic API using the user's API key.
+ * It's designed for the BYOK (Bring Your Own Key) flow where users provide
+ * their own Anthropic API key.
+ *
+ * Note: This requires the 'anthropic-dangerous-direct-browser-access' header
+ * which Anthropic provides for browser-based applications.
+ *
+ * For production cross-site key management, see:
+ * docs/research/cross-site-key-management-byok.md
+ */
+interface ClaudeMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+interface ClaudeResponse {
+    id: string;
+    type: 'message';
+    role: 'assistant';
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    model: string;
+    stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+}
+interface ClaudeClientConfig {
+    apiKey: string;
+    model?: string;
+    maxTokens?: number;
+    systemPrompt?: string;
+}
+interface SendMessageOptions {
+    /** Conversation history to include */
+    messages?: ClaudeMessage[];
+    /** Override system prompt for this request */
+    systemPrompt?: string;
+    /** Override max tokens for this request */
+    maxTokens?: number;
+    /** Temperature (0-1) for response randomness */
+    temperature?: number;
+}
+interface SendMessageResult {
+    success: boolean;
+    message: string;
+    response?: ClaudeResponse;
+    error?: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCost: number;
+    };
+}
+/**
+ * Simple Claude API client for BYOK mode
+ */
+declare class ClaudeClient {
+    private apiKey;
+    private model;
+    private maxTokens;
+    private systemPrompt;
+    constructor(config: ClaudeClientConfig);
+    /**
+     * Send a message to Claude and get a response
+     */
+    sendMessage(userMessage: string, options?: SendMessageOptions): Promise<SendMessageResult>;
+    /**
+     * Update the API key
+     */
+    setApiKey(apiKey: string): void;
+    /**
+     * Update the model
+     */
+    setModel(model: string): void;
+    /**
+     * Update the system prompt
+     */
+    setSystemPrompt(systemPrompt: string): void;
+}
+/**
+ * Create a Claude client instance
+ */
+declare function createClaudeClient(config: ClaudeClientConfig): ClaudeClient;
+
 /**
  * Type definitions for ChatBubble component
  */
@@ -341,6 +498,18 @@ declare const Components: {
     readonly ChatInput: "chat-message-input";
     readonly ChatSendButton: "chat-send-button";
     readonly ChatClearButton: "chat-clear-button";
+    readonly ChatMoreMenu: "chat-more-menu";
+    readonly ChatMoreMenuButton: "chat-more-menu-button";
+    readonly ApiKeySection: "api-key-section";
+    readonly ApiKeyInput: "api-key-input";
+    readonly ApiKeySubmitButton: "api-key-submit-button";
+    readonly ApiKeyClearButton: "api-key-clear-button";
+    readonly ApiKeyConfigureButton: "api-key-configure-button";
+    readonly ApiKeyStatus: "api-key-status";
+    readonly ApiKeyMasked: "api-key-masked";
+    readonly ApiKeyError: "api-key-error";
+    readonly ApiKeyShowToggle: "api-key-show-toggle";
+    readonly ApiKeyCancelButton: "api-key-cancel-button";
 };
 /**
  * ChatBubbleVariant - Display modes for the chat interface
@@ -507,4 +676,4 @@ declare function scoreToolMatch(query: string, tool: ToolMetadata): number;
  */
 declare function findBestMatch(query: string, tools: ToolMetadata[]): FuzzyMatchResult;
 
-export { AutoNavigationContext, ChatBubble, type ChatBubbleSettings, ChatBubbleSettingsModal, ChatBubbleVariant, type ChatBubbleVariantType, type ChatBubbleVariantValue, ChatInputProvider, ChatProvider, CodeBlock, type CommandResult, Components, DemoAIInterface, type FuzzyMatchResult, FuzzyMatcher, MermaidDiagram, MessageRenderer, NavigationContextProvider, PageLayout, type PageLayoutType, type PageLayoutValue, SubtitleOverlay, SupernalProvider, type SupernalProviderProps, type ToolExecutionResult, ToolManager, type ToolMenuCategory, ToolMenuPopup, ToolMenuPopupTrigger, type UseToolMenuReturn, findBestMatch, scoreToolMatch, useAllContexts, useChatContext, useChatInput, useCurrentContext, useNavigate, useNavigationGraph, useNavigationPath, useRegisterTool, useToolMenu };
+export { ApiKeyProvider, type ApiKeyStatus, AutoNavigationContext, ChatBubble, type ChatBubbleSettings, ChatBubbleSettingsModal, ChatBubbleVariant, type ChatBubbleVariantType, type ChatBubbleVariantValue, ChatInputProvider, ChatProvider, ClaudeClient, type ClaudeClientConfig, type ClaudeMessage, type ClaudeResponse, CodeBlock, type CommandResult, Components, DemoAIInterface, type FuzzyMatchResult, FuzzyMatcher, MermaidDiagram, MessageRenderer, NavigationContextProvider, PageLayout, type PageLayoutType, type PageLayoutValue, type SendMessageOptions, type SendMessageResult, SubtitleOverlay, SupernalProvider, type SupernalProviderProps, type ToolExecutionResult, ToolManager, type ToolMenuCategory, ToolMenuPopup, ToolMenuPopupTrigger, type UseApiKeyStorageReturn, type UseToolMenuReturn, createClaudeClient, findBestMatch, scoreToolMatch, useAllContexts, useApiKey, useApiKeyOptional, useApiKeyStorage, useChatContext, useChatInput, useCurrentContext, useNavigate, useNavigationGraph, useNavigationPath, useRegisterTool, useToolMenu };

package/dist/index.d.ts

@@ -1,8 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1 from 'react';
-import { NavigationGraph, NavigationPath, NavigationContext, ToolMetadata } from '@supernal/interface/browser';
-import { AIInterface } from '@supernal/interface';
-export { AICommand, AIResponse } from '@supernal/interface';
+import { NavigationGraph, NavigationPath, NavigationContext, ToolMetadata, AIInterface } from '@supernal/interface/browser';
+export { AICommand, AIResponse } from '@supernal/interface/browser';
 
 interface SupernalProviderProps {
     children: React$1.ReactNode;
@@ -134,15 +133,173 @@ interface ChatContextType {
     sendMessage: (text: string) => Promise<void>;
     clearMessages: () => void;
     isLoading: boolean;
+    /** Whether real AI mode is active (API key is valid) */
+    isAiMode: boolean;
 }
 declare function useChatContext(): ChatContextType;
-declare function ChatProvider({ children, mode, apiKey, onToolExecute, }: {
+declare function ChatProvider({ children, mode, apiKey: propApiKey, onToolExecute, }: {
     children: React$1.ReactNode;
     mode?: 'fuzzy' | 'ai';
     apiKey?: string;
     onToolExecute?: (tool: string, result: any) => void;
 }): react_jsx_runtime.JSX.Element;
 
+type ApiKeyStatus = 'none' | 'validating' | 'valid' | 'invalid' | 'locked';
+interface UseApiKeyStorageOptions {
+    /**
+     * Enable encrypted storage (requires passphrase)
+     * @default false
+     */
+    encrypted?: boolean;
+    /**
+     * Callback when passphrase is needed for encrypted storage
+     */
+    onPassphraseRequired?: () => Promise<string>;
+    /**
+     * Callback when passphrase is invalid
+     */
+    onPassphraseInvalid?: () => void;
+}
+/**
+ * Hook for managing API key storage with validation
+ *
+ * This is the simple single-site version using localStorage.
+ * Compatible with future VaultClient integration for cross-site support.
+ *
+ * Features:
+ * - localStorage persistence (single site)
+ * - Format validation (sk-ant-* prefix, minimum length)
+ * - Optional live validation with Anthropic API
+ * - Masked display for security
+ * - Optional encryption at rest (Phase 1 of vault system)
+ *
+ * @param options - Configuration options
+ */
+declare function useApiKeyStorage(options?: UseApiKeyStorageOptions): {
+    hasApiKey: boolean;
+    isLocked: boolean;
+    setApiKey: (key: string, validate?: boolean) => Promise<boolean>;
+    clearApiKey: () => void;
+    revalidate: () => Promise<boolean>;
+    unlock: (passphrase: string) => Promise<boolean>;
+    lock: () => void;
+    apiKey: string | null;
+    status: ApiKeyStatus;
+    error: string | null;
+    maskedKey: string | null;
+};
+type UseApiKeyStorageReturn = ReturnType<typeof useApiKeyStorage>;
+
+interface ApiKeyProviderProps {
+    children: React$1.ReactNode;
+    /**
+     * Optional initial API key (e.g., from environment variable for dev)
+     * If provided and no key is in storage, this will be used
+     */
+    initialApiKey?: string;
+}
+declare function ApiKeyProvider({ children, initialApiKey }: ApiKeyProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access API key state and methods
+ * Must be used within ApiKeyProvider
+ */
+declare function useApiKey(): UseApiKeyStorageReturn;
+/**
+ * Hook to optionally access API key state
+ * Returns null if not within ApiKeyProvider (no error thrown)
+ */
+declare function useApiKeyOptional(): UseApiKeyStorageReturn | null;
+
+/**
+ * ClaudeClient - Simple direct API client for BYOK mode
+ *
+ * This client makes direct calls to the Anthropic API using the user's API key.
+ * It's designed for the BYOK (Bring Your Own Key) flow where users provide
+ * their own Anthropic API key.
+ *
+ * Note: This requires the 'anthropic-dangerous-direct-browser-access' header
+ * which Anthropic provides for browser-based applications.
+ *
+ * For production cross-site key management, see:
+ * docs/research/cross-site-key-management-byok.md
+ */
+interface ClaudeMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+interface ClaudeResponse {
+    id: string;
+    type: 'message';
+    role: 'assistant';
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    model: string;
+    stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+}
+interface ClaudeClientConfig {
+    apiKey: string;
+    model?: string;
+    maxTokens?: number;
+    systemPrompt?: string;
+}
+interface SendMessageOptions {
+    /** Conversation history to include */
+    messages?: ClaudeMessage[];
+    /** Override system prompt for this request */
+    systemPrompt?: string;
+    /** Override max tokens for this request */
+    maxTokens?: number;
+    /** Temperature (0-1) for response randomness */
+    temperature?: number;
+}
+interface SendMessageResult {
+    success: boolean;
+    message: string;
+    response?: ClaudeResponse;
+    error?: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCost: number;
+    };
+}
+/**
+ * Simple Claude API client for BYOK mode
+ */
+declare class ClaudeClient {
+    private apiKey;
+    private model;
+    private maxTokens;
+    private systemPrompt;
+    constructor(config: ClaudeClientConfig);
+    /**
+     * Send a message to Claude and get a response
+     */
+    sendMessage(userMessage: string, options?: SendMessageOptions): Promise<SendMessageResult>;
+    /**
+     * Update the API key
+     */
+    setApiKey(apiKey: string): void;
+    /**
+     * Update the model
+     */
+    setModel(model: string): void;
+    /**
+     * Update the system prompt
+     */
+    setSystemPrompt(systemPrompt: string): void;
+}
+/**
+ * Create a Claude client instance
+ */
+declare function createClaudeClient(config: ClaudeClientConfig): ClaudeClient;
+
 /**
  * Type definitions for ChatBubble component
  */
@@ -341,6 +498,18 @@ declare const Components: {
     readonly ChatInput: "chat-message-input";
     readonly ChatSendButton: "chat-send-button";
     readonly ChatClearButton: "chat-clear-button";
+    readonly ChatMoreMenu: "chat-more-menu";
+    readonly ChatMoreMenuButton: "chat-more-menu-button";
+    readonly ApiKeySection: "api-key-section";
+    readonly ApiKeyInput: "api-key-input";
+    readonly ApiKeySubmitButton: "api-key-submit-button";
+    readonly ApiKeyClearButton: "api-key-clear-button";
+    readonly ApiKeyConfigureButton: "api-key-configure-button";
+    readonly ApiKeyStatus: "api-key-status";
+    readonly ApiKeyMasked: "api-key-masked";
+    readonly ApiKeyError: "api-key-error";
+    readonly ApiKeyShowToggle: "api-key-show-toggle";
+    readonly ApiKeyCancelButton: "api-key-cancel-button";
 };
 /**
  * ChatBubbleVariant - Display modes for the chat interface
@@ -507,4 +676,4 @@ declare function scoreToolMatch(query: string, tool: ToolMetadata): number;
  */
 declare function findBestMatch(query: string, tools: ToolMetadata[]): FuzzyMatchResult;
 
-export { AutoNavigationContext, ChatBubble, type ChatBubbleSettings, ChatBubbleSettingsModal, ChatBubbleVariant, type ChatBubbleVariantType, type ChatBubbleVariantValue, ChatInputProvider, ChatProvider, CodeBlock, type CommandResult, Components, DemoAIInterface, type FuzzyMatchResult, FuzzyMatcher, MermaidDiagram, MessageRenderer, NavigationContextProvider, PageLayout, type PageLayoutType, type PageLayoutValue, SubtitleOverlay, SupernalProvider, type SupernalProviderProps, type ToolExecutionResult, ToolManager, type ToolMenuCategory, ToolMenuPopup, ToolMenuPopupTrigger, type UseToolMenuReturn, findBestMatch, scoreToolMatch, useAllContexts, useChatContext, useChatInput, useCurrentContext, useNavigate, useNavigationGraph, useNavigationPath, useRegisterTool, useToolMenu };
+export { ApiKeyProvider, type ApiKeyStatus, AutoNavigationContext, ChatBubble, type ChatBubbleSettings, ChatBubbleSettingsModal, ChatBubbleVariant, type ChatBubbleVariantType, type ChatBubbleVariantValue, ChatInputProvider, ChatProvider, ClaudeClient, type ClaudeClientConfig, type ClaudeMessage, type ClaudeResponse, CodeBlock, type CommandResult, Components, DemoAIInterface, type FuzzyMatchResult, FuzzyMatcher, MermaidDiagram, MessageRenderer, NavigationContextProvider, PageLayout, type PageLayoutType, type PageLayoutValue, type SendMessageOptions, type SendMessageResult, SubtitleOverlay, SupernalProvider, type SupernalProviderProps, type ToolExecutionResult, ToolManager, type ToolMenuCategory, ToolMenuPopup, ToolMenuPopupTrigger, type UseApiKeyStorageReturn, type UseToolMenuReturn, createClaudeClient, findBestMatch, scoreToolMatch, useAllContexts, useApiKey, useApiKeyOptional, useApiKeyStorage, useChatContext, useChatInput, useCurrentContext, useNavigate, useNavigationGraph, useNavigationPath, useRegisterTool, useToolMenu };