@prestyj/core 4.10.1

package/dist/index.d.ts

@@ -0,0 +1,359 @@
+export { ContextWindowOptions, DEFAULT_MAX_VIDEO_BYTES, MODELS, ModelInfo, getContextWindow, getDefaultModel, getMaxThinkingLevel, getModel, getModelsForProvider, getSummaryModel, getVideoByteLimit, usesOpenAICodexTransport } from './model-registry.js';
+import { Provider, ThinkingLevel } from '@prestyj/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;
+}
+
+/**
+ * Storage key for Kimi Code OAuth credentials. Kept distinct from the
+ * `moonshot` API-key entry so a user can configure BOTH and we always
+ * prefer OAuth for the logical `moonshot` provider.
+ */
+declare const MOONSHOT_OAUTH_KEY = "moonshot-oauth";
+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>;
+    /**
+     * True if the user has any usable auth for the logical provider. For
+     * `moonshot` this is satisfied by either the Kimi OAuth credential or the
+     * Moonshot API key.
+     */
+    hasProviderAuth(provider: string): Promise<boolean>;
+    /**
+     * True if the active credential for `provider` is a static API key with no
+     * refresh mechanism. For `moonshot` this is only true when the Kimi OAuth
+     * credential is absent (a present OAuth credential is refreshable).
+     */
+    isStaticApiKey(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>;
+
+/**
+ * Kimi Code OAuth — Device Authorization Grant (RFC 8628).
+ *
+ * Mirrors MoonshotAI/kimi-code's managed-auth flow. Three form-encoded
+ * POST endpoints against the OAuth host (default `https://auth.kimi.com`):
+ *
+ *  - `/api/oauth/device_authorization` (client_id)           → device + user code
+ *  - `/api/oauth/token` (grant_type=device_code)             → poll until authorized
+ *  - `/api/oauth/token` (grant_type=refresh_token)           → refresh access token
+ *
+ * Unlike Anthropic/OpenAI/Gemini (browser-redirect PKCE), this is a
+ * device-code/poll flow: we show the user a URL + code, they authorize in a
+ * browser on any device, and we poll for the token.
+ *
+ * After login the issued token is used against the managed coding API
+ * (`https://api.kimi.com/coding/v1`, distinct from the `api.moonshot.ai`
+ * API-key endpoint) via `Authorization: Bearer <access_token>`. We persist
+ * that base URL on the credential so the runtime routes there automatically.
+ */
+
+/** Managed coding API base URL the issued OAuth token is used against. */
+declare function kimiCodeBaseUrl(): string;
+/**
+ * Headers the Kimi For Coding API requires on every model request. The
+ * managed endpoint gates access to recognized coding agents: requests must
+ * carry a `kimi_code_cli` platform identity and matching `User-Agent`, or the
+ * server rejects with "only available for Coding Agents". Attach these to the
+ * inference client's default headers whenever the Kimi OAuth token is used.
+ */
+declare function kimiCodingHeaders(): Record<string, string>;
+/**
+ * True if `baseUrl` targets the Kimi For Coding managed endpoint (the URL
+ * persisted on Kimi OAuth credentials). Callers use this to decide whether to
+ * attach `kimiCodingHeaders()` — the Moonshot API-key path uses a different
+ * host and must NOT receive the coding-agent identity headers.
+ */
+declare function isKimiCodingEndpoint(baseUrl: string | undefined): boolean;
+/**
+ * Drive the Kimi device-code flow end-to-end. Shows the verification URL +
+ * user code via callbacks, opens the browser, and polls until the user
+ * authorizes (or a 15-minute local timeout elapses).
+ */
+declare function loginKimi(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
+/** Exchange a refresh token for a fresh Kimi access token. */
+declare function refreshKimiToken(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. "@prestyj/cli". */
+    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, MOONSHOT_OAUTH_KEY, 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, isKimiCodingEndpoint, isLoggerOpen, isModelLoaded, isThinkingLevelSupported, kimiCodeBaseUrl, kimiCodingHeaders, log, loginAnthropic, loginGemini, loginKimi, loginOpenAI, openLog, refreshAnthropicToken, refreshGeminiToken, refreshKimiToken, refreshOpenAIToken, registerLogCleanup, resample, setProgressCallback, transcribeVoice, withFileLock };