@openhoo/hoopilot 1.3.0 → 2.1.0

package/dist/index.d.cts

@@ -1,388 +0,0 @@
-/** Content-Type for the Prometheus text exposition format (version 0.0.4). */
-declare const PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
-/**
- * In-process metrics for the running proxy. Counters are monotonic for the life
- * of the process and reset on restart, which Prometheus handles natively. The
- * registry is intentionally allocation-light and synchronous; the single-
- * threaded event loop makes its mutations atomic with respect to each request.
- */
-declare class MetricsRegistry {
-    #private;
-    constructor(options?: {
-        now?: () => number;
-    });
-    /** Mark a request as started; pair with exactly one {@link observe}. */
-    startRequest(): void;
-    /** Record a completed request and clear its in-flight slot. */
-    observe(observation: RequestObservation): void;
-    /**
-     * Record whether one upstream completion reported token usage. `missing`
-     * counts responses that carried no usage object — most often streamed Chat
-     * Completions sent without `stream_options: {"include_usage": true}` — so a
-     * rising miss rate flags clients whose token usage is going unaccounted.
-     */
-    recordTokenExtraction(extracted: boolean): void;
-    /** Accumulate token counts for a model from one upstream completion. */
-    recordTokens(model: string, usage: TokenUsage): void;
-    /** Record one upstream Copilot call and whether it succeeded. */
-    recordUpstream(path: string, ok: boolean): void;
-    /** Store the latest Copilot quota so /metrics can expose it as gauges. */
-    recordCopilotQuota(usage: CopilotUsage): void;
-    /**
-     * Store the latest GitHub REST rate-limit budget, keyed by its resource bucket.
-     * A no-op when `rateLimit` is undefined (the response carried no rate-limit
-     * headers) so callers can pass {@link parseRateLimitHeaders} output directly.
-     */
-    recordGithubRateLimit(rateLimit: GithubRateLimit | undefined): void;
-    /** A JSON-friendly view of the current counters. */
-    snapshot(now?: () => number): MetricsSnapshot;
-    /** Render the Prometheus text exposition format (version 0.0.4). */
-    renderPrometheus(now?: () => number): string;
-}
-/**
- * Tee `response`'s body so the client receives an unchanged copy while a
- * background reader extracts token usage. Returns a new Response carrying the
- * client-facing branch and the original status/headers. Usage extraction never
- * throws into the client stream: a parse failure or an aborted client simply
- * yields no usage. When the body is absent the response is returned untouched.
- *
- * Pass the request's `signal` so a client disconnect cancels the observer
- * branch; combined with the runtime cancelling the client branch, that releases
- * the shared upstream connection instead of draining it in the background.
- */
-declare function observeResponseUsage(response: Response, fallbackModel: string, onUsage: (model: string, usage: TokenUsage) => void, signal?: AbortSignal, onOutcome?: (extracted: boolean) => void): Response;
-
-type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
-interface Logger {
-    info(message: string): void;
-    warn(message: string): void;
-    error(message: string): void;
-}
-type LogFields = Record<string, unknown>;
-type LogFormat = "json" | "pretty";
-type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal" | "silent";
-type StreamingProxyMode = "auto" | "buffer" | "live";
-interface LogMethod {
-    (message: string): void;
-    (fields: LogFields, message: string): void;
-}
-interface HoopilotLogger {
-    child(bindings: LogFields): HoopilotLogger;
-    debug: LogMethod;
-    error: LogMethod;
-    fatal: LogMethod;
-    info: LogMethod;
-    trace: LogMethod;
-    warn: LogMethod;
-}
-interface HoopilotLoggerOptions {
-    base?: LogFields;
-    colorize?: boolean;
-    env?: NodeJS.ProcessEnv;
-    format?: LogFormat | string;
-    level?: LogLevel | string;
-    stream?: {
-        write(message: string): unknown;
-    };
-}
-interface CopilotAuthOptions {
-    authStorePath?: string;
-    copilotApiBaseUrl?: string;
-    env?: NodeJS.ProcessEnv;
-    fetch?: FetchLike;
-    githubApiBaseUrl?: string;
-}
-interface CopilotAccess {
-    apiBaseUrl: string;
-    expiresAtMs: number;
-    source: "github-copilot-oauth";
-    token: string;
-}
-interface HoopilotServerOptions extends CopilotAuthOptions {
-    allowUnauthenticated?: boolean;
-    apiKey?: string;
-    host?: string;
-    logger?: HoopilotLogger;
-    logFormat?: LogFormat | string;
-    logLevel?: LogLevel | string;
-    metrics?: MetricsRegistry;
-    port?: number;
-    streamingProxyMode?: StreamingProxyMode | string;
-}
-interface StartedHoopilotServer {
-    server: Bun.Server<undefined>;
-    url: string;
-}
-type JsonObject = Record<string, unknown>;
-/** Normalized token usage extracted from an upstream OpenAI/Copilot response. */
-interface TokenUsage {
-    cachedTokens?: number;
-    completionTokens: number;
-    promptTokens: number;
-    reasoningTokens?: number;
-    totalTokens: number;
-}
-/** Per-model token totals accumulated by the metrics registry. */
-interface ModelTokenTotals {
-    cached: number;
-    completion: number;
-    prompt: number;
-    reasoning: number;
-    requests: number;
-    total: number;
-}
-/** A single completed request's facts, recorded into the metrics registry. */
-interface RequestObservation {
-    durationMs: number;
-    method: string;
-    route: string;
-    status: number;
-}
-/** One quota category (chat, completions, or premium_interactions/credits). */
-interface CopilotQuota {
-    entitlement?: number;
-    hasQuota?: boolean;
-    overageCount?: number;
-    overageEntitlement?: number;
-    overagePermitted?: boolean;
-    percentRemaining?: number;
-    quotaId?: string;
-    quotaResetAt?: string;
-    remaining?: number;
-    timestampUtc?: string;
-    tokenBasedBilling?: boolean;
-    unlimited?: boolean;
-    used?: number;
-}
-/** A GitHub Copilot account's plan and quota snapshot. */
-interface CopilotUsage {
-    accessTypeSku?: string;
-    chatEnabled?: boolean;
-    plan?: string;
-    quotaResetDate?: string;
-    quotas: Record<string, CopilotQuota>;
-}
-/**
- * GitHub REST API rate-limit budget parsed from the `x-ratelimit-*` headers that
- * `api.github.com` returns on every response. Hoopilot reads these off the
- * `copilot_internal/user` quota call it already makes, so the proxy's GitHub API
- * usage is visible without spending an extra request.
- */
-interface GithubRateLimit {
-    /** `x-ratelimit-resource` — the bucket the request counted against (e.g. `core`). */
-    resource: string;
-    /** `x-ratelimit-limit` — maximum requests allowed in the current window. */
-    limit?: number;
-    /** `x-ratelimit-remaining` — requests left in the current window. */
-    remaining?: number;
-    /** `x-ratelimit-used` — requests already spent in the current window. */
-    used?: number;
-    /** `x-ratelimit-reset` — Unix epoch seconds when the window resets. */
-    resetEpochSeconds?: number;
-    /** `retry-after` — seconds to wait, present on 429 / secondary-limit responses. */
-    retryAfterSeconds?: number;
-    /** Wall-clock epoch ms when these values were observed. */
-    observedAtMs: number;
-}
-/** JSON view of one GitHub rate-limit resource, as rendered into a snapshot. */
-interface GithubRateLimitSnapshot {
-    limit?: number;
-    observedAt: string;
-    remaining?: number;
-    resetAt?: string;
-    retryAfterSeconds?: number;
-    used?: number;
-}
-/** Request-latency summary for one route, in milliseconds. */
-interface RouteLatency {
-    avgMs: number;
-    count: number;
-}
-/**
- * Aggregate request-latency summary derived from the duration histogram. `avgMs`
- * is exact; the percentiles are estimated from the histogram buckets (Prometheus-
- * style linear interpolation), so they are approximate.
- */
-interface LatencySnapshot {
-    avgMs: number;
-    byRoute: Record<string, RouteLatency>;
-    count: number;
-    p50Ms: number;
-    p95Ms: number;
-}
-/** A point-in-time JSON view of the in-process metrics. */
-interface MetricsSnapshot {
-    githubRateLimit: Record<string, GithubRateLimitSnapshot>;
-    inFlight: number;
-    latency: LatencySnapshot;
-    requests: {
-        byRoute: Record<string, number>;
-        byStatus: Record<string, number>;
-        total: number;
-    };
-    startedAt: string;
-    tokens: {
-        byModel: Record<string, ModelTokenTotals>;
-        cached: number;
-        completion: number;
-        extraction: {
-            extracted: number;
-            missing: number;
-        };
-        prompt: number;
-        reasoning: number;
-        total: number;
-    };
-    upstream: {
-        errors: number;
-        total: number;
-    };
-    uptimeSeconds: number;
-}
-
-interface AnthropicStreamOptions {
-    model: string;
-    messageId?: string;
-}
-declare class AnthropicCompatibilityError extends Error {
-    constructor(message: string);
-}
-declare function anthropicMessagesToResponsesRequest(request: JsonObject): JsonObject;
-declare function responsesResponseToAnthropicMessage(response: JsonObject, fallbackModel: string): JsonObject;
-declare function responsesStreamToAnthropicStream(stream: ReadableStream<Uint8Array>, options: AnthropicStreamOptions): ReadableStream<Uint8Array>;
-declare function estimateAnthropicMessageTokens(request: JsonObject): JsonObject;
-
-declare class CopilotAuthError extends Error {
-    constructor(message: string);
-}
-declare class CopilotAuth {
-    #private;
-    constructor(options?: CopilotAuthOptions);
-    getAccess(): Promise<CopilotAccess>;
-}
-
-interface StoredCopilotAuth {
-    apiBaseUrl?: string;
-    createdAt?: string;
-    githubDomain?: string;
-    source?: string;
-    token: string;
-}
-declare function authStorePath(env?: NodeJS.ProcessEnv): string;
-declare function readStoredCopilotAuth(path?: string): StoredCopilotAuth | undefined;
-declare function writeStoredCopilotAuth(auth: StoredCopilotAuth, path?: string): void;
-
-/** Default GitHub REST host that serves the `copilot_internal/user` quota route. */
-declare const DEFAULT_GITHUB_API_BASE_URL = "https://api.github.com";
-/**
- * API version sent to the GitHub `copilot_internal` endpoints. This is a
- * different surface from the Copilot completions API (`x-github-api-version`
- * `2026-06-01`), so it is pinned separately and bumped independently.
- */
-declare const COPILOT_USAGE_API_VERSION = "2025-04-01";
-/**
- * Set the GitHub Copilot API request headers on `headers`, leaving any
- * caller-provided `accept` intact. Single source of truth for the pinned
- * integration id, editor/plugin versions, and API version so the proxy client
- * and the login-time verification call cannot drift apart.
- */
-declare function applyCopilotHeaders(headers: Headers, token: string): Headers;
-/**
- * Set headers for the GitHub REST `copilot_internal/user` quota call. This host
- * is `api.github.com` (not the Copilot API host) and expects the `token` auth
- * scheme with the raw stored OAuth token — not the `Bearer` scheme used by the
- * Copilot completion endpoints.
- */
-declare function applyGithubApiHeaders(headers: Headers, token: string): Headers;
-/**
- * Parse the GitHub REST `x-ratelimit-*` headers (plus `retry-after`) off a
- * response into a {@link GithubRateLimit}. `api.github.com` returns these on
- * every reply, so the proxy reads its GitHub API budget from the quota call it
- * already makes — no extra request is spent. Returns undefined when the response
- * carries no rate-limit headers (for example the Copilot completion host, which
- * does not emit them today) so callers record nothing rather than a phantom row.
- */
-declare function parseRateLimitHeaders(headers: Headers, nowMs?: number): GithubRateLimit | undefined;
-declare class CopilotClient {
-    #private;
-    constructor(options?: CopilotAuthOptions);
-    /**
-     * Fetch the Copilot account's quota / premium-request usage from the GitHub
-     * REST `copilot_internal/user` endpoint. The stored device-flow OAuth token is
-     * accepted directly here — no Copilot token exchange is required to read quota.
-     */
-    usage(signal?: AbortSignal): Promise<Response>;
-    chatCompletions(body: JsonObject, signal?: AbortSignal): Promise<Response>;
-    responses(body: string, signal?: AbortSignal): Promise<Response>;
-    models(signal?: AbortSignal): Promise<Response>;
-    fetchCopilot(path: string, init: RequestInit): Promise<Response>;
-}
-/**
- * Normalize a `copilot_internal/user` response into {@link CopilotUsage}. Handles
- * both the paid-plan shape (`quota_snapshots.{chat,completions,premium_interactions}`)
- * and the free-plan shape (`limited_user_quotas` remaining + `monthly_quotas`
- * allowance). `remaining` may be fractional and negative under permitted overage,
- * so `used` is derived as `max(0, entitlement - remaining)`.
- */
-declare function normalizeCopilotUsage(body: unknown): CopilotUsage;
-
-interface GithubCopilotDeviceLoginOptions {
-    clientId?: string;
-    domain?: string;
-    env?: NodeJS.ProcessEnv;
-    fetch?: FetchLike;
-    logger?: Logger;
-    openBrowser?: (url: string) => void | Promise<void>;
-    sleep?: (ms: number) => Promise<void>;
-}
-interface GithubCopilotDeviceLoginResult {
-    domain: string;
-    token: string;
-}
-declare function githubCopilotDeviceLogin(options?: GithubCopilotDeviceLoginOptions): Promise<GithubCopilotDeviceLoginResult>;
-
-declare const DEFAULT_LOG_FORMAT: LogFormat;
-declare const DEFAULT_LOG_LEVEL: LogLevel;
-declare const noopLogger: HoopilotLogger;
-declare function createHoopilotLogger(options?: HoopilotLoggerOptions): HoopilotLogger;
-declare function parseLogFormat(value: string | undefined): LogFormat;
-declare function parseLogLevel(value: string | undefined): LogLevel;
-
-declare const DEFAULT_MODEL = "gpt-4.1";
-interface ResponseStreamOptions {
-    model: string;
-    responseId?: string;
-}
-declare function responsesRequestToChatCompletion(request: JsonObject): JsonObject;
-declare function normalizeChatCompletionRequest(request: JsonObject): JsonObject;
-declare function completionsRequestToChatCompletion(request: JsonObject): JsonObject;
-declare function normalizeRequestedModel(model: unknown): string;
-declare function chatCompletionToResponse(completion: JsonObject, responseId?: string): JsonObject;
-/**
- * Reduce a Copilot `/responses` result into the `{ output }` document Codex's
- * remote-compaction client (`POST /responses/compact`) deserializes. Codex keeps
- * only assistant/user message items from `output` and discards everything else,
- * so a Responses `output` array passes through verbatim; when the upstream only
- * exposes `output_text` (or, for a stream it did not honor `stream: false` on,
- * `output_text` deltas) a single assistant message is synthesized instead. The
- * input may be a unary JSON body or an SSE stream, so both framings are handled.
- */
-declare function responsesCompactionResult(upstreamText: string, isSse: boolean): JsonObject;
-declare function chatCompletionToCompletion(completion: JsonObject): JsonObject;
-declare function completionStreamFromChatStream(chatStream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array>;
-declare function normalizeModelsResponse(upstream: unknown): JsonObject;
-declare function fallbackModels(): Array<JsonObject>;
-declare function responsesStreamFromChatStream(chatStream: ReadableStream<Uint8Array>, options: ResponseStreamOptions): ReadableStream<Uint8Array>;
-/**
- * Normalize an upstream `usage` object into {@link TokenUsage}. Accepts both the
- * Chat Completions shape (`prompt_tokens`/`completion_tokens`) and the Responses
- * shape (`input_tokens`/`output_tokens`), and pulls nested reasoning/cached
- * details when present. Returns undefined when no token counts are available so
- * callers can distinguish "no usage reported" from "zero tokens".
- */
-declare function extractTokenUsage(usage: unknown): TokenUsage | undefined;
-
-declare function createHoopilotHandler(options?: HoopilotServerOptions): (request: Request) => Promise<Response>;
-declare function startHoopilotServer(options?: HoopilotServerOptions): StartedHoopilotServer;
-
-export { AnthropicCompatibilityError, COPILOT_USAGE_API_VERSION, type CopilotAccess, CopilotAuth, CopilotAuthError, type CopilotAuthOptions, CopilotClient, type CopilotQuota, type CopilotUsage, DEFAULT_GITHUB_API_BASE_URL, DEFAULT_LOG_FORMAT, DEFAULT_LOG_LEVEL, DEFAULT_MODEL, type FetchLike, type GithubRateLimit, type GithubRateLimitSnapshot, type HoopilotLogger, type HoopilotLoggerOptions, type HoopilotServerOptions, type JsonObject, type LogFields, type LogFormat, type LogLevel, type LogMethod, type Logger, MetricsRegistry, type MetricsSnapshot, type ModelTokenTotals, PROMETHEUS_CONTENT_TYPE, type RequestObservation, type StartedHoopilotServer, type TokenUsage, anthropicMessagesToResponsesRequest, applyCopilotHeaders, applyGithubApiHeaders, authStorePath, chatCompletionToCompletion, chatCompletionToResponse, completionStreamFromChatStream, completionsRequestToChatCompletion, createHoopilotHandler, createHoopilotLogger, estimateAnthropicMessageTokens, extractTokenUsage, fallbackModels, githubCopilotDeviceLogin, noopLogger, normalizeChatCompletionRequest, normalizeCopilotUsage, normalizeModelsResponse, normalizeRequestedModel, observeResponseUsage, parseLogFormat, parseLogLevel, parseRateLimitHeaders, readStoredCopilotAuth, responsesCompactionResult, responsesRequestToChatCompletion, responsesResponseToAnthropicMessage, responsesStreamFromChatStream, responsesStreamToAnthropicStream, startHoopilotServer, writeStoredCopilotAuth };