@kichan/extension-client NPM

KICHAN Client Library (`@kichan/extension-client`)

This is a lightweight JavaScript library (@kichan/extension-client) that websites include to interact with the KICHAN browser extension. It provides simple functions like kichan.request() for websites to request LLM operations using the user's keys managed by the extension.

This lightweight JavaScript library allows websites to interact with the KICHAN browser extension, enabling them to request LLM operations using the user's keys.

Important: This library must be included by the website itself. The KICHAN extension does not automatically inject it.

Installation

You can install the library using npm:

npm install @kichan/extension-client

Or include it directly from a CDN (link TBD when published):

Usage

Once the library is included in your page (either via a bundler/import or a <script> tag), it exposes a window.kichan object.

// Example using ES Modules (if installed via npm)
// import { KichanRequestData } from '@kichan/extension-interface'; // For TypeScript projects

async function askKichan() {
  // Check if the KICHAN extension is installed and active
  // The isInstalled() method checks if the extension's content script
  // has successfully run on the page.
  // Recommended: Also import types for better developer experience
  // import { KichanRequestData, KichanResponseData, KichanErrorData, KichanErrorCode, isKichanError } from '@kichan/extension-client';

  if (window.kichan && window.kichan.isInstalled()) {
    // Prepare the request data (follows OpenAI Chat Completions structure)
    // Type KichanRequestData can be imported from @kichan/extension-interface
    const requestData /*: KichanRequestData*/ = {
      messages: [
        { role: 'system', content: 'You are a helpful assistant.' },
        { role: 'user', content: 'Translate "hello world" to French.' }
      ],
      model_hint: 'gpt-4o-mini', // Optional: Suggest a model
      temperature: 0.7,         // Optional: Other OpenAI-compatible parameters
    };

    console.log("Sending request to KICHAN:", requestData);

    try {
      // Await the promise. It resolves ONLY on success.
      const response = await window.kichan.request(requestData);

      // If the promise resolved, it's a successful response (KichanResponseData)
      console.log("Received success response from KICHAN:", response);
      if (response.choices && response.choices.length > 0) {
          const messageContent = response.choices[0].message.content;
          console.log("Assistant's reply:", messageContent);
          // Use the successful response
      } else {
          console.warn("Received response, but no choices found?", response);
      }

    } catch (error) {
        // If the promise rejected, it contains the error details (KichanErrorData)
        console.error("KICHAN request failed:", error);

        // Type guard recommended for robust handling (import isKichanError)
        // if (isKichanError(error)) { ... }
        if (error && typeof error === 'object' && 'kichan_error' in error) {
            const kichanError = (error as any).kichan_error; // Cast for simplicity here
            console.error(`KICHAN Error (${kichanError.source}): ${kichanError.code} - ${kichanError.message}`);
            // You can use kichanError.code (which is KichanErrorCode) in a switch:
            // switch (kichanError.code) {
            //    case 'USER_DENIED': /* handle denial */ break;
            //    case 'TIMEOUT': /* handle timeout */ break;
            //    // ... etc ...
            // }
        } else {
            // Handle unexpected error format
            console.error("An unexpected error occurred:", error);
        }
    }
  } else {
    console.log("KICHAN extension not detected. Please install KICHAN.");
    // Optionally guide the user to install the extension
  }
}

// Call the function when needed, e.g., on a button click
// askKichan();

See the @kichan/extension-interface package for detailed type definitions of the request and response objects. The error codes (KichanErrorCode) are also defined there and re-exported by @kichan/extension-client.