@witqq/agent-sdk 0.6.0 → 0.7.0

package/dist/auth/index.d.ts

@@ -1,140 +1,6 @@
-/**
- * Base auth token returned by all auth providers.
- *
- * @example
- * ```ts
- * import type { AuthToken } from "@witqq/agent-sdk/auth";
- *
- * const token: AuthToken = {
- *   accessToken: "gho_abc123...",
- *   tokenType: "bearer",
- *   obtainedAt: Date.now(),
- * };
- * ```
- */
-interface AuthToken {
-    /** The access token string */
-    accessToken: string;
-    /** Token type (e.g. "bearer") */
-    tokenType: string;
-    /** Seconds until token expires (undefined = long-lived) */
-    expiresIn?: number;
-    /** Timestamp when the token was obtained */
-    obtainedAt: number;
-}
-/**
- * Copilot-specific token (GitHub OAuth, long-lived).
- *
- * @example
- * ```ts
- * import type { CopilotAuthToken } from "@witqq/agent-sdk/auth";
- *
- * const token: CopilotAuthToken = {
- *   accessToken: "gho_abc123...",
- *   tokenType: "bearer",
- *   obtainedAt: Date.now(),
- *   login: "octocat",
- * };
- * ```
- */
-interface CopilotAuthToken extends AuthToken {
-    /** GitHub user login associated with the token */
-    login?: string;
-}
-/**
- * Claude-specific token (OAuth+PKCE, expires in 8h).
- *
- * @example
- * ```ts
- * import type { ClaudeAuthToken } from "@witqq/agent-sdk/auth";
- *
- * const token: ClaudeAuthToken = {
- *   accessToken: "sk-ant-oat01-...",
- *   tokenType: "bearer",
- *   expiresIn: 28800,
- *   obtainedAt: Date.now(),
- *   refreshToken: "sk-ant-rt01-...",
- *   scopes: ["user:inference", "user:profile"],
- * };
- * ```
- */
-interface ClaudeAuthToken extends AuthToken {
-    /** Refresh token for obtaining new access tokens */
-    refreshToken: string;
-    /** OAuth scopes granted */
-    scopes: string[];
-}
-/**
- * Result of initiating a GitHub Device Flow.
- *
- * @example
- * ```ts
- * import { CopilotAuth } from "@witqq/agent-sdk/auth";
- *
- * const auth = new CopilotAuth();
- * const { userCode, verificationUrl, waitForToken } = await auth.startDeviceFlow();
- * console.log(`Open ${verificationUrl} and enter code: ${userCode}`);
- * const token = await waitForToken();
- * ```
- */
-interface DeviceFlowResult {
-    /** The code the user must enter at the verification URL */
-    userCode: string;
-    /** URL where the user enters the code */
-    verificationUrl: string;
-    /** Polls GitHub until user authorizes; resolves with token */
-    waitForToken: (signal?: AbortSignal) => Promise<CopilotAuthToken>;
-}
-/** Options for starting a Claude OAuth flow */
-interface OAuthFlowOptions {
-    /** The redirect URI registered with the OAuth app */
-    redirectUri?: string;
-    /** OAuth scopes to request (defaults to user:profile user:inference) */
-    scopes?: string;
-}
-/**
- * Result of initiating a Claude OAuth flow.
- *
- * @example
- * ```ts
- * import type { OAuthFlowResult } from "@witqq/agent-sdk/auth";
- *
- * const result: OAuthFlowResult = {
- *   authorizeUrl: "https://claude.ai/oauth/authorize?...",
- *   completeAuth: async (code) => ({ ... }),
- * };
- * // Open result.authorizeUrl in browser, get code from redirect
- * const token = await result.completeAuth(code);
- * ```
- */
-interface OAuthFlowResult {
-    /** URL to open in browser for user authorization */
-    authorizeUrl: string;
-    /** Exchange the authorization code (or full redirect URL) for tokens */
-    completeAuth: (codeOrUrl: string) => Promise<ClaudeAuthToken>;
-}
-/** Base error for auth operations.
- * @param message - Error description
- * @param options - Standard ErrorOptions (e.g. cause)
- */
-declare class AuthError extends Error {
-    constructor(message: string, options?: ErrorOptions);
-}
-/** Device code expired before user authorized */
-declare class DeviceCodeExpiredError extends AuthError {
-    constructor();
-}
-/** User denied access during OAuth flow */
-declare class AccessDeniedError extends AuthError {
-    constructor();
-}
-/** Token exchange or refresh failed.
- * @param message - Error description
- * @param options - Standard ErrorOptions (e.g. cause)
- */
-declare class TokenExchangeError extends AuthError {
-    constructor(message: string, options?: ErrorOptions);
-}
+import { D as DeviceFlowResult, O as OAuthFlowOptions, a as OAuthFlowResult, C as ClaudeAuthToken, A as AuthToken } from '../types-Bh5AhqD-.js';
+export { b as AccessDeniedError, c as AuthError, d as CopilotAuthToken, e as DeviceCodeExpiredError, T as TokenExchangeError } from '../types-Bh5AhqD-.js';
+import '../errors-BDLbNu9w.js';
 
 /** Fetch function type for dependency injection in tests */
 type FetchFn$1 = typeof globalThis.fetch;
@@ -268,4 +134,154 @@ declare class ClaudeAuth {
     private mapTokenResponse;
 }
 
-export { AccessDeniedError, AuthError, type AuthToken, ClaudeAuth, type ClaudeAuthToken, CopilotAuth, type CopilotAuthToken, DeviceCodeExpiredError, type DeviceFlowResult, type OAuthFlowOptions, type OAuthFlowResult, TokenExchangeError };
+/**
+ * Automatic background token refresh manager.
+ *
+ * Schedules token refresh at a configurable threshold before expiry
+ * (default 80% of token lifetime). Emits events on refresh, failure,
+ * and token expiry. Handles retry on failure and clean disposal.
+ *
+ * When all retries are exhausted but the token hasn't expired yet,
+ * the manager waits until the token's expiry time and then starts
+ * a fresh retry cycle. This continues until refresh succeeds or
+ * the token expires.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { TokenRefreshManager } from "@witqq/agent-sdk/auth";
+ *
+ * const manager = new TokenRefreshManager({
+ *   token: claudeToken,
+ *   refresh: (rt) => claudeAuth.refreshToken(rt),
+ * });
+ * manager.on("refreshed", (newToken) => { tokenStore.save("claude", newToken); });
+ * manager.on("error", (err) => { console.error("Refresh failed:", err); });
+ * manager.start();
+ * // ...later
+ * manager.dispose();
+ * ```
+ *
+ * @example Integration with createAuthHandler
+ * ```ts
+ * import { TokenRefreshManager } from "@witqq/agent-sdk/auth";
+ * import { createAuthHandler } from "@witqq/agent-sdk/chat/server";
+ * import type { ClaudeAuthToken } from "@witqq/agent-sdk/auth";
+ *
+ * let refreshManager: TokenRefreshManager | undefined;
+ *
+ * const authHandler = createAuthHandler({
+ *   tokenStore,
+ *   onAuth: (provider, token) => {
+ *     // Clean up previous manager
+ *     refreshManager?.dispose();
+ *     refreshManager = undefined;
+ *
+ *     if (provider === "claude" && token.expiresIn) {
+ *       refreshManager = new TokenRefreshManager({
+ *         token,
+ *         refresh: (t) =>
+ *           claudeAuth.refreshToken((t as ClaudeAuthToken).refreshToken),
+ *       });
+ *       refreshManager.on("refreshed", (newToken) => {
+ *         tokenStore.save("claude", newToken);
+ *       });
+ *       refreshManager.on("expired", () => {
+ *         console.warn("Claude token expired — re-authentication required");
+ *       });
+ *       refreshManager.start();
+ *     }
+ *   },
+ * });
+ * ```
+ */
+
+/** Events emitted by TokenRefreshManager */
+interface TokenRefreshEvents {
+    /** Emitted when token was successfully refreshed */
+    refreshed: (token: AuthToken) => void;
+    /** Emitted when refresh attempt failed (may retry) */
+    error: (error: Error, attempt: number) => void;
+    /** Emitted when token expired and could not be refreshed */
+    expired: () => void;
+    /** Emitted when manager is disposed */
+    disposed: () => void;
+}
+/** Configuration for TokenRefreshManager */
+interface TokenRefreshOptions {
+    /** Current token with expiresIn and obtainedAt */
+    token: AuthToken;
+    /**
+     * Function that performs the actual token refresh.
+     * Receives the current token and returns a new one.
+     */
+    refresh: (token: AuthToken) => Promise<AuthToken>;
+    /**
+     * Fraction of token lifetime at which to trigger refresh (0-1).
+     * Default: 0.8 (refresh at 80% of lifetime, i.e. with 20% remaining)
+     */
+    refreshThreshold?: number;
+    /**
+     * Maximum retry attempts on refresh failure. Default: 3
+     */
+    maxRetries?: number;
+    /**
+     * Base delay between retries in ms. Exponential backoff applied. Default: 1000
+     */
+    retryDelayMs?: number;
+    /**
+     * Minimum schedule delay in ms (prevents scheduling in the past). Default: 1000
+     */
+    minDelayMs?: number;
+}
+type EventName = keyof TokenRefreshEvents;
+/**
+ * Background token refresh manager with event emission and retry logic.
+ *
+ * Lifecycle: `new` → `start()` → (auto-refreshes) → `stop()` or `dispose()`
+ */
+declare class TokenRefreshManager {
+    private currentToken;
+    private readonly refreshFn;
+    private readonly threshold;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    private readonly minDelayMs;
+    private timerId;
+    private running;
+    private disposed;
+    private readonly listeners;
+    constructor(options: TokenRefreshOptions);
+    /** Register an event listener */
+    on<K extends EventName>(event: K, listener: TokenRefreshEvents[K]): this;
+    /** Remove an event listener */
+    off<K extends EventName>(event: K, listener: TokenRefreshEvents[K]): this;
+    /** Current token managed by this instance */
+    get token(): AuthToken;
+    /** Whether the manager is currently running */
+    get isRunning(): boolean;
+    /** Whether the manager has been disposed */
+    get isDisposed(): boolean;
+    /**
+     * Start automatic refresh scheduling.
+     * If the token is already expired, emits "expired" immediately.
+     * If the token has no expiresIn, does nothing (long-lived token).
+     */
+    start(): void;
+    /** Stop automatic refresh (can be restarted with start()) */
+    stop(): void;
+    /**
+     * Update the managed token (e.g. after manual refresh).
+     * Reschedules automatic refresh if running.
+     */
+    updateToken(token: AuthToken): void;
+    /** Stop and clean up all resources */
+    dispose(): void;
+    private schedule;
+    private performRefresh;
+    private computeRefreshDelay;
+    private isTokenExpired;
+    private clearTimer;
+    private emit;
+}
+
+export { AuthToken, ClaudeAuth, ClaudeAuthToken, CopilotAuth, DeviceFlowResult, OAuthFlowOptions, OAuthFlowResult, type TokenRefreshEvents, TokenRefreshManager, type TokenRefreshOptions };

package/dist/auth/index.js

@@ -1,7 +1,21 @@
 import { createHash, randomBytes } from 'crypto';
 
+// src/errors.ts
+var AgentSDKError = class extends Error {
+  /** @internal Marker for cross-bundle identity checks */
+  _agentSDKError = true;
+  constructor(message, options) {
+    super(message, options);
+    this.name = "AgentSDKError";
+  }
+  /** Check if an error is an AgentSDKError (works across bundled copies) */
+  static is(error) {
+    return error instanceof Error && "_agentSDKError" in error && error._agentSDKError === true;
+  }
+};
+
 // src/auth/types.ts
-var AuthError = class extends Error {
+var AuthError = class extends AgentSDKError {
   constructor(message, options) {
     super(message, options);
     this.name = "AuthError";
@@ -347,6 +361,178 @@ function hexEncode(bytes) {
   return Buffer.from(bytes).toString("hex");
 }
 
-export { AccessDeniedError, AuthError, ClaudeAuth, CopilotAuth, DeviceCodeExpiredError, TokenExchangeError };
+// src/auth/refresh-manager.ts
+var TokenRefreshManager = class {
+  currentToken;
+  refreshFn;
+  threshold;
+  maxRetries;
+  retryDelayMs;
+  minDelayMs;
+  timerId = null;
+  running = false;
+  disposed = false;
+  listeners = {
+    refreshed: /* @__PURE__ */ new Set(),
+    error: /* @__PURE__ */ new Set(),
+    expired: /* @__PURE__ */ new Set(),
+    disposed: /* @__PURE__ */ new Set()
+  };
+  constructor(options) {
+    this.currentToken = { ...options.token };
+    this.refreshFn = options.refresh;
+    this.threshold = options.refreshThreshold ?? 0.8;
+    this.maxRetries = options.maxRetries ?? 3;
+    this.retryDelayMs = options.retryDelayMs ?? 1e3;
+    this.minDelayMs = options.minDelayMs ?? 1e3;
+  }
+  /** Register an event listener */
+  on(event, listener) {
+    this.listeners[event].add(listener);
+    return this;
+  }
+  /** Remove an event listener */
+  off(event, listener) {
+    this.listeners[event].delete(listener);
+    return this;
+  }
+  /** Current token managed by this instance */
+  get token() {
+    return { ...this.currentToken };
+  }
+  /** Whether the manager is currently running */
+  get isRunning() {
+    return this.running;
+  }
+  /** Whether the manager has been disposed */
+  get isDisposed() {
+    return this.disposed;
+  }
+  /**
+   * Start automatic refresh scheduling.
+   * If the token is already expired, emits "expired" immediately.
+   * If the token has no expiresIn, does nothing (long-lived token).
+   */
+  start() {
+    if (this.disposed) return;
+    if (this.running) return;
+    this.running = true;
+    this.schedule();
+  }
+  /** Stop automatic refresh (can be restarted with start()) */
+  stop() {
+    this.running = false;
+    this.clearTimer();
+  }
+  /**
+   * Update the managed token (e.g. after manual refresh).
+   * Reschedules automatic refresh if running.
+   */
+  updateToken(token) {
+    if (this.disposed) return;
+    this.currentToken = { ...token };
+    if (this.running) {
+      this.clearTimer();
+      this.schedule();
+    }
+  }
+  /** Stop and clean up all resources */
+  dispose() {
+    if (this.disposed) return;
+    this.stop();
+    this.disposed = true;
+    this.emit("disposed");
+    for (const set of Object.values(this.listeners)) {
+      set.clear();
+    }
+  }
+  // ─── Private ──────────────────────────────────────────────────
+  schedule() {
+    if (!this.running || this.disposed) return;
+    const delayMs = this.computeRefreshDelay();
+    if (delayMs === null) {
+      return;
+    }
+    if (delayMs <= 0) {
+      this.timerId = setTimeout(() => {
+        this.timerId = null;
+        if (!this.running || this.disposed) return;
+        void this.performRefresh();
+      }, 0);
+      return;
+    }
+    this.timerId = setTimeout(() => {
+      this.timerId = null;
+      if (!this.running || this.disposed) return;
+      void this.performRefresh();
+    }, Math.max(delayMs, this.minDelayMs));
+  }
+  async performRefresh(attempt = 1) {
+    if (!this.running || this.disposed) return;
+    try {
+      const newToken = await this.refreshFn(this.currentToken);
+      if (!this.running || this.disposed) return;
+      this.currentToken = { ...newToken };
+      this.emit("refreshed", newToken);
+      this.schedule();
+    } catch (err) {
+      if (!this.running || this.disposed) return;
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.emit("error", error, attempt);
+      if (attempt < this.maxRetries) {
+        const delay = this.retryDelayMs * Math.pow(2, attempt - 1);
+        this.timerId = setTimeout(() => {
+          this.timerId = null;
+          if (!this.running || this.disposed) return;
+          void this.performRefresh(attempt + 1);
+        }, delay);
+      } else {
+        if (this.isTokenExpired()) {
+          this.running = false;
+          this.emit("expired");
+        } else {
+          const expiresIn = this.currentToken.expiresIn;
+          if (expiresIn == null) return;
+          const expiresAt = this.currentToken.obtainedAt + expiresIn * 1e3;
+          const waitMs = Math.max(expiresAt - Date.now(), this.minDelayMs);
+          this.timerId = setTimeout(() => {
+            this.timerId = null;
+            if (!this.running || this.disposed) return;
+            void this.performRefresh();
+          }, waitMs);
+        }
+      }
+    }
+  }
+  computeRefreshDelay() {
+    if (this.currentToken.expiresIn == null) return null;
+    const lifetimeMs = this.currentToken.expiresIn * 1e3;
+    const refreshAtMs = this.currentToken.obtainedAt + lifetimeMs * this.threshold;
+    const now = Date.now();
+    const delay = refreshAtMs - now;
+    return delay;
+  }
+  isTokenExpired() {
+    if (this.currentToken.expiresIn == null) return false;
+    const expiresAt = this.currentToken.obtainedAt + this.currentToken.expiresIn * 1e3;
+    return Date.now() >= expiresAt;
+  }
+  clearTimer() {
+    if (this.timerId !== null) {
+      clearTimeout(this.timerId);
+      this.timerId = null;
+    }
+  }
+  emit(event, ...args) {
+    for (const listener of this.listeners[event]) {
+      try {
+        listener(...args);
+      } catch {
+      }
+    }
+  }
+};
+
+export { AccessDeniedError, AuthError, ClaudeAuth, CopilotAuth, DeviceCodeExpiredError, TokenExchangeError, TokenRefreshManager };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map