@kenkaiiii/gg-core 4.4.0

package/dist/index.d.ts

@@ -0,0 +1,295 @@
+export { ContextWindowOptions, MODELS, ModelInfo, getContextWindow, getDefaultModel, getMaxThinkingLevel, getModel, getModelsForProvider, getSummaryModel, usesOpenAICodexTransport } from './model-registry.js';
+import { Provider, ThinkingLevel } from '@kenkaiiii/gg-ai';
+export { AppPaths, getAppPaths } from './paths.js';
+
+declare function getSupportedThinkingLevels(provider: Provider, model: string): readonly ThinkingLevel[];
+declare function isThinkingLevelSupported(provider: Provider, model: string, level: ThinkingLevel): boolean;
+declare function getNextThinkingLevel(provider: Provider, model: string, current: ThinkingLevel | undefined): ThinkingLevel | undefined;
+
+type LogLevel = "INFO" | "ERROR" | "WARN" | "DEBUG";
+/**
+ * Open the debug log in append mode, tagging this process with a session id and
+ * remembering `name` for the shutdown line. Idempotent — re-calling while open
+ * is a no-op. Returns true only when it *newly* opened the file (so callers can
+ * write a one-time startup line); returns false if already open or if the file
+ * could not be opened.
+ */
+declare function openLog(filePath: string, name: string): boolean;
+/** Session identifier included on every log line as `sid=<id>`. */
+declare function getSessionId(): string;
+/** True if the logger has an open file descriptor. */
+declare function isLoggerOpen(): boolean;
+/** Write a timestamped log line. No-op if the logger is not open. */
+declare function log(level: LogLevel, category: string, message: string, data?: Record<string, unknown>): void;
+/**
+ * Register a cleanup callback (e.g. an EventBus unsubscriber) to run when the
+ * logger closes. Lets app-side bridges hook into the shared lifecycle without
+ * the core needing to know about app types.
+ */
+declare function registerLogCleanup(fn: () => void): void;
+/**
+ * Write a shutdown line (unless suppressed), close the file descriptor, and run
+ * any registered cleanups.
+ */
+declare function closeLogger(opts?: {
+    shutdownLine?: boolean;
+}): void;
+
+/**
+ * Simple file-based lock with PID tracking and stale detection.
+ * Uses atomic file creation (wx flag) to prevent races.
+ */
+declare function withFileLock<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
+
+/**
+ * Resolve the current Claude Code release version for spoofing the claude-cli
+ * User-Agent on OAuth and inference requests. Cached in-memory for the process
+ * lifetime and on disk for 24h. Falls back to a hardcoded constant if the npm
+ * registry is unreachable and no cache exists.
+ */
+declare function getClaudeCodeVersion(): Promise<string>;
+/** Build the User-Agent string Anthropic's OAuth + inference edges expect. */
+declare function getClaudeCliUserAgent(): Promise<string>;
+
+interface OAuthCredentials {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    accountId?: string;
+    projectId?: string;
+    baseUrl?: string;
+}
+interface OAuthLoginCallbacks {
+    onOpenUrl: (url: string) => void;
+    onPromptCode: (message: string) => Promise<string>;
+    onStatus: (message: string) => void;
+}
+
+declare class AuthStorage {
+    private data;
+    private filePath;
+    private loaded;
+    /** Per-provider lock to serialize concurrent refresh calls. */
+    private refreshLocks;
+    constructor(filePath?: string);
+    /** Path to the on-disk auth file. Useful for status output. */
+    get path(): string;
+    /** List provider keys with stored credentials. */
+    listProviders(): Promise<string[]>;
+    /** True if credentials exist for `provider`. */
+    hasCredentials(provider: string): Promise<boolean>;
+    load(): Promise<void>;
+    private ensureLoaded;
+    getCredentials(provider: string): Promise<OAuthCredentials | undefined>;
+    setCredentials(provider: string, creds: OAuthCredentials): Promise<void>;
+    clearCredentials(provider: string): Promise<void>;
+    clearAll(): Promise<void>;
+    /**
+     * Returns valid credentials, auto-refreshing if expired.
+     * If `forceRefresh` is true, refreshes even if the token hasn't expired
+     * (useful when the provider rejects a token with 401 before its stored expiry).
+     * Throws if not logged in.
+     */
+    resolveCredentials(provider: string, opts?: {
+        forceRefresh?: boolean;
+    }): Promise<OAuthCredentials>;
+    /**
+     * Returns a valid access token, auto-refreshing if expired.
+     * Throws if not logged in.
+     */
+    resolveToken(provider: string): Promise<string>;
+    private save;
+}
+declare class NotLoggedInError extends Error {
+    provider: string;
+    constructor(provider: string);
+}
+
+declare function generatePKCE(): Promise<{
+    verifier: string;
+    challenge: string;
+}>;
+
+declare function loginAnthropic(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
+declare function refreshAnthropicToken(refreshToken: string): Promise<OAuthCredentials>;
+
+declare function loginOpenAI(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
+declare function refreshOpenAIToken(refreshToken: string): Promise<OAuthCredentials>;
+
+declare function loginGemini(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
+declare function refreshGeminiToken(refreshToken: string): Promise<OAuthCredentials>;
+
+/**
+ * Minimal Telegram Bot API client using raw fetch().
+ * Supports long polling, markdown messages, inline keyboards, and message splitting.
+ */
+interface TelegramConfig {
+    botToken: string;
+    /** Only accept messages from this Telegram user ID. */
+    allowedUserId: number;
+}
+interface TelegramUpdate {
+    update_id: number;
+    message?: {
+        message_id: number;
+        from: {
+            id: number;
+            first_name: string;
+        };
+        chat: {
+            id: number;
+            type: string;
+            title?: string;
+        };
+        text?: string;
+        voice?: {
+            file_id: string;
+            duration: number;
+            mime_type?: string;
+            file_size?: number;
+        };
+    };
+    callback_query?: {
+        id: string;
+        from: {
+            id: number;
+        };
+        message: {
+            chat: {
+                id: number;
+            };
+        };
+        data: string;
+    };
+    my_chat_member?: {
+        chat: {
+            id: number;
+            type: string;
+            title?: string;
+        };
+        from: {
+            id: number;
+        };
+        new_chat_member: {
+            status: string;
+        };
+    };
+}
+interface InlineButton {
+    text: string;
+    callback_data: string;
+}
+/** Incoming message with chat context. */
+interface TelegramMessage {
+    text: string;
+    chatId: number;
+    chatType: "private" | "group" | "supergroup" | "channel";
+    chatTitle?: string;
+}
+/** Incoming voice note with chat context. */
+interface TelegramVoiceMessage {
+    fileId: string;
+    duration: number;
+    chatId: number;
+    chatType: "private" | "group" | "supergroup" | "channel";
+    chatTitle?: string;
+}
+declare class TelegramBot {
+    private token;
+    private allowedUserId;
+    private offset;
+    private running;
+    private onMessage;
+    private onVoiceMessage;
+    private onCallback;
+    private onBotAdded;
+    private onBotRemoved;
+    constructor(config: TelegramConfig);
+    /** Register handler for incoming text messages. */
+    onText(handler: (msg: TelegramMessage) => void): void;
+    /** Register handler for incoming voice notes. */
+    onVoice(handler: (msg: TelegramVoiceMessage) => void): void;
+    /** Register handler for inline keyboard button presses. */
+    onCallbackQuery(handler: (data: string, chatId: number) => void): void;
+    /** Register handler for when the bot is added to a group. */
+    onAddedToGroup(handler: (chatId: number, chatTitle?: string) => void): void;
+    /** Register handler for when the bot is removed from a group. */
+    onRemovedFromGroup(handler: (chatId: number) => void): void;
+    /** Start long polling. Blocks until stop() is called. */
+    start(): Promise<void>;
+    /** Stop long polling. */
+    stop(): void;
+    /** Send a text message to a specific chat. Converts markdown and splits long messages. */
+    send(chatId: number, text: string, buttons?: InlineButton[][]): Promise<void>;
+    /** Send a plain text message (no markdown parsing) to a specific chat. */
+    sendPlain(chatId: number, text: string): Promise<void>;
+    /** Send a typing indicator to a specific chat. */
+    sendTyping(chatId: number): Promise<void>;
+    /** Get a direct download URL for a Telegram file. */
+    getFileUrl(fileId: string): Promise<string>;
+    private getUpdates;
+    private handleUpdate;
+    private apiCall;
+}
+
+/**
+ * Voice note transcription using local Whisper model.
+ * Uses @huggingface/transformers (pure JS/WASM) — no native deps, no API keys.
+ * Model (~75MB) is downloaded on first use and cached locally.
+ */
+/** Optional callback for model download progress. */
+type ProgressCallback = (info: {
+    status: string;
+    progress?: number;
+    file?: string;
+}) => void;
+/** Set a callback to receive model download progress updates. */
+declare function setProgressCallback(cb: ProgressCallback | null): void;
+/**
+ * Resample audio from one sample rate to another using linear interpolation.
+ */
+declare function resample(audio: Float32Array, fromRate: number, toRate: number): Float32Array;
+/**
+ * Downmix multi-channel audio to mono by averaging all channels.
+ */
+declare function downmixToMono(channelData: Float32Array[]): Float32Array;
+/**
+ * Decode OGG Opus audio buffer to 16kHz mono PCM Float32Array.
+ */
+declare function decodeOggOpus(buffer: Uint8Array): Promise<Float32Array>;
+/** Whether the model has been loaded already. */
+declare function isModelLoaded(): boolean;
+/**
+ * Transcribe a voice message from its Telegram file URL.
+ * Downloads the OGG Opus file, decodes to PCM, and runs Whisper locally.
+ */
+declare function transcribeVoice(fileUrl: string): Promise<string>;
+
+interface AutoUpdateConfig {
+    /** npm package to self-update, e.g. "@kenkaiiii/ggcoder". */
+    packageName: string;
+    /**
+     * Absolute path to this app's update-state.json, or a thunk resolving it.
+     * A thunk keeps path resolution lazy so callers can derive it from
+     * `os.homedir()` without freezing the value at module-load time (which
+     * breaks tests that mock the home directory after import).
+     */
+    stateFilePath: string | (() => string);
+    /** Builds the in-session "update available" notification. */
+    periodicMessage?: (args: {
+        currentVersion: string;
+        latestVersion: string;
+        updateCommand: string;
+    }) => string;
+}
+interface AutoUpdater {
+    checkAndAutoUpdate(currentVersion: string): string | null;
+    getPendingUpdate(currentVersion: string): {
+        latestVersion: string;
+    } | null;
+    startPeriodicUpdateCheck(currentVersion: string, onUpdate: (message: string) => void): void;
+    stopPeriodicUpdateCheck(): void;
+}
+declare function createAutoUpdater(config: AutoUpdateConfig): AutoUpdater;
+
+export { AuthStorage, type AutoUpdateConfig, type AutoUpdater, type InlineButton, type LogLevel, NotLoggedInError, type OAuthCredentials, type OAuthLoginCallbacks, type ProgressCallback, TelegramBot, type TelegramConfig, type TelegramMessage, type TelegramUpdate, type TelegramVoiceMessage, closeLogger, createAutoUpdater, decodeOggOpus, downmixToMono, generatePKCE, getClaudeCliUserAgent, getClaudeCodeVersion, getNextThinkingLevel, getSessionId, getSupportedThinkingLevels, isLoggerOpen, isModelLoaded, isThinkingLevelSupported, log, loginAnthropic, loginGemini, loginOpenAI, openLog, refreshAnthropicToken, refreshGeminiToken, refreshOpenAIToken, registerLogCleanup, resample, setProgressCallback, transcribeVoice, withFileLock };