@openhoo/hoopilot 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -1,3 +1,44 @@
+/** 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;
+    /** 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;
+    /** 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): Response;
+
 type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 interface Logger {
     info(message: string): void;
@@ -35,6 +76,7 @@ interface CopilotAuthOptions {
     copilotApiBaseUrl?: string;
     env?: NodeJS.ProcessEnv;
     fetch?: FetchLike;
+    githubApiBaseUrl?: string;
 }
 interface CopilotAccess {
     apiBaseUrl: string;
@@ -49,6 +91,7 @@ interface HoopilotServerOptions extends CopilotAuthOptions {
     logger?: HoopilotLogger;
     logFormat?: LogFormat | string;
     logLevel?: LogLevel | string;
+    metrics?: MetricsRegistry;
     port?: number;
 }
 interface StartedHoopilotServer {
@@ -56,6 +99,71 @@ interface StartedHoopilotServer {
     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;
+    overageCount?: number;
+    overagePermitted?: boolean;
+    percentRemaining?: number;
+    remaining?: number;
+    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>;
+}
+/** A point-in-time JSON view of the in-process metrics. */
+interface MetricsSnapshot {
+    inFlight: number;
+    requests: {
+        byRoute: Record<string, number>;
+        byStatus: Record<string, number>;
+        total: number;
+    };
+    startedAt: string;
+    tokens: {
+        byModel: Record<string, ModelTokenTotals>;
+        cached: number;
+        completion: number;
+        prompt: number;
+        reasoning: number;
+        total: number;
+    };
+    upstream: {
+        errors: number;
+        total: number;
+    };
+    uptimeSeconds: number;
+}
 
 declare class CopilotAuthError extends Error {
     constructor(message: string);
@@ -77,14 +185,50 @@ 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;
 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;
@@ -122,8 +266,16 @@ declare function chatCompletionToCompletion(completion: JsonObject): JsonObject;
 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 { type CopilotAccess, CopilotAuth, CopilotAuthError, type CopilotAuthOptions, CopilotClient, DEFAULT_LOG_FORMAT, DEFAULT_LOG_LEVEL, DEFAULT_MODEL, type FetchLike, type HoopilotLogger, type HoopilotLoggerOptions, type HoopilotServerOptions, type JsonObject, type LogFields, type LogFormat, type LogLevel, type LogMethod, type Logger, type StartedHoopilotServer, authStorePath, chatCompletionToCompletion, chatCompletionToResponse, completionsRequestToChatCompletion, createHoopilotHandler, createHoopilotLogger, fallbackModels, githubCopilotDeviceLogin, noopLogger, normalizeChatCompletionRequest, normalizeModelsResponse, normalizeRequestedModel, parseLogFormat, parseLogLevel, readStoredCopilotAuth, responsesRequestToChatCompletion, responsesStreamFromChatStream, startHoopilotServer, writeStoredCopilotAuth };
+export { 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 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, applyCopilotHeaders, applyGithubApiHeaders, authStorePath, chatCompletionToCompletion, chatCompletionToResponse, completionsRequestToChatCompletion, createHoopilotHandler, createHoopilotLogger, extractTokenUsage, fallbackModels, githubCopilotDeviceLogin, noopLogger, normalizeChatCompletionRequest, normalizeCopilotUsage, normalizeModelsResponse, normalizeRequestedModel, observeResponseUsage, parseLogFormat, parseLogLevel, readStoredCopilotAuth, responsesRequestToChatCompletion, responsesStreamFromChatStream, startHoopilotServer, writeStoredCopilotAuth };

package/dist/index.d.ts

@@ -1,3 +1,44 @@
+/** 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;
+    /** 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;
+    /** 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): Response;
+
 type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 interface Logger {
     info(message: string): void;
@@ -35,6 +76,7 @@ interface CopilotAuthOptions {
     copilotApiBaseUrl?: string;
     env?: NodeJS.ProcessEnv;
     fetch?: FetchLike;
+    githubApiBaseUrl?: string;
 }
 interface CopilotAccess {
     apiBaseUrl: string;
@@ -49,6 +91,7 @@ interface HoopilotServerOptions extends CopilotAuthOptions {
     logger?: HoopilotLogger;
     logFormat?: LogFormat | string;
     logLevel?: LogLevel | string;
+    metrics?: MetricsRegistry;
     port?: number;
 }
 interface StartedHoopilotServer {
@@ -56,6 +99,71 @@ interface StartedHoopilotServer {
     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;
+    overageCount?: number;
+    overagePermitted?: boolean;
+    percentRemaining?: number;
+    remaining?: number;
+    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>;
+}
+/** A point-in-time JSON view of the in-process metrics. */
+interface MetricsSnapshot {
+    inFlight: number;
+    requests: {
+        byRoute: Record<string, number>;
+        byStatus: Record<string, number>;
+        total: number;
+    };
+    startedAt: string;
+    tokens: {
+        byModel: Record<string, ModelTokenTotals>;
+        cached: number;
+        completion: number;
+        prompt: number;
+        reasoning: number;
+        total: number;
+    };
+    upstream: {
+        errors: number;
+        total: number;
+    };
+    uptimeSeconds: number;
+}
 
 declare class CopilotAuthError extends Error {
     constructor(message: string);
@@ -77,14 +185,50 @@ 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;
 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;
@@ -122,8 +266,16 @@ declare function chatCompletionToCompletion(completion: JsonObject): JsonObject;
 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 { type CopilotAccess, CopilotAuth, CopilotAuthError, type CopilotAuthOptions, CopilotClient, DEFAULT_LOG_FORMAT, DEFAULT_LOG_LEVEL, DEFAULT_MODEL, type FetchLike, type HoopilotLogger, type HoopilotLoggerOptions, type HoopilotServerOptions, type JsonObject, type LogFields, type LogFormat, type LogLevel, type LogMethod, type Logger, type StartedHoopilotServer, authStorePath, chatCompletionToCompletion, chatCompletionToResponse, completionsRequestToChatCompletion, createHoopilotHandler, createHoopilotLogger, fallbackModels, githubCopilotDeviceLogin, noopLogger, normalizeChatCompletionRequest, normalizeModelsResponse, normalizeRequestedModel, parseLogFormat, parseLogLevel, readStoredCopilotAuth, responsesRequestToChatCompletion, responsesStreamFromChatStream, startHoopilotServer, writeStoredCopilotAuth };
+export { 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 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, applyCopilotHeaders, applyGithubApiHeaders, authStorePath, chatCompletionToCompletion, chatCompletionToResponse, completionsRequestToChatCompletion, createHoopilotHandler, createHoopilotLogger, extractTokenUsage, fallbackModels, githubCopilotDeviceLogin, noopLogger, normalizeChatCompletionRequest, normalizeCopilotUsage, normalizeModelsResponse, normalizeRequestedModel, observeResponseUsage, parseLogFormat, parseLogLevel, readStoredCopilotAuth, responsesRequestToChatCompletion, responsesStreamFromChatStream, startHoopilotServer, writeStoredCopilotAuth };