@witqq/agent-sdk 0.3.1 → 0.5.0

package/dist/auth/index.d.cts

@@ -0,0 +1,271 @@
+/**
+ * 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);
+}
+
+/** Fetch function type for dependency injection in tests */
+type FetchFn$1 = typeof globalThis.fetch;
+/**
+ * Programmatic GitHub Device Flow authentication for Copilot SDK.
+ *
+ * @example
+ * ```ts
+ * const auth = new CopilotAuth();
+ * const flow = await auth.startDeviceFlow();
+ * console.log(`Open ${flow.verificationUrl} and enter ${flow.userCode}`);
+ * const token = await flow.waitForToken();
+ * // Use token.accessToken with CopilotBackendOptions.githubToken
+ * ```
+ */
+declare class CopilotAuth {
+    private readonly fetchFn;
+    /** @param options - Optional configuration with custom fetch for testing */
+    constructor(options?: {
+        fetch?: FetchFn$1;
+    });
+    /**
+     * Start the GitHub Device Flow.
+     * Returns a device code result with user code, verification URL,
+     * and a `waitForToken()` function that polls until the user authorizes.
+     *
+     * @param options - Optional scopes and abort signal
+     * @returns Device flow result with user code, verification URL, and waitForToken poller
+     * @throws {AuthError} If the device code request fails
+     * @throws {DeviceCodeExpiredError} If the device code expires before user authorizes
+     * @throws {AccessDeniedError} If the user denies access
+     *
+     * @example
+     * ```ts
+     * const auth = new CopilotAuth();
+     * const { userCode, verificationUrl, waitForToken } = await auth.startDeviceFlow();
+     * console.log(`Open ${verificationUrl} and enter code: ${userCode}`);
+     * const token = await waitForToken();
+     * ```
+     */
+    startDeviceFlow(options?: {
+        scopes?: string;
+        signal?: AbortSignal;
+    }): Promise<DeviceFlowResult>;
+    private pollForToken;
+    private fetchUserLogin;
+    private delay;
+}
+
+/** Fetch function type for dependency injection in tests */
+type FetchFn = typeof globalThis.fetch;
+/** Random bytes generator for dependency injection in tests */
+type RandomBytesFn = (size: number) => Uint8Array;
+/**
+ * Programmatic OAuth+PKCE authentication for Claude SDK.
+ *
+ * @example
+ * ```ts
+ * const auth = new ClaudeAuth();
+ * const { authorizeUrl, completeAuth } = auth.startOAuthFlow({
+ *   redirectUri: "https://platform.claude.com/oauth/code/callback",
+ * });
+ * // Open authorizeUrl in browser, get code from redirect
+ * const token = await completeAuth(code);
+ * // Use token with ClaudeBackendOptions: env.CLAUDE_CODE_OAUTH_TOKEN
+ * ```
+ */
+declare class ClaudeAuth {
+    private readonly fetchFn;
+    private readonly randomBytes;
+    /**
+     * @param options - Optional configuration with custom fetch and random bytes for testing
+     */
+    constructor(options?: {
+        fetch?: FetchFn;
+        randomBytes?: RandomBytesFn;
+    });
+    /**
+     * Start the Claude OAuth+PKCE flow.
+     * Generates PKCE code verifier/challenge and returns an authorize URL
+     * plus a `completeAuth(code)` function for token exchange.
+     *
+     * @param options - Redirect URI and optional scopes
+     * @returns OAuth flow result with authorize URL and completeAuth function
+     * @throws {AuthError} If PKCE generation fails
+     *
+     * @example
+     * ```ts
+     * const auth = new ClaudeAuth();
+     * const { authorizeUrl, completeAuth } = auth.startOAuthFlow({
+     *   redirectUri: "https://platform.claude.com/oauth/code/callback",
+     * });
+     * console.log(`Open: ${authorizeUrl}`);
+     * const token = await completeAuth(authorizationCode);
+     * ```
+     */
+    startOAuthFlow(options?: OAuthFlowOptions): OAuthFlowResult;
+    /**
+     * Extract an authorization code from user input.
+     * Accepts a raw code string or a full redirect URL containing a `code` query parameter.
+     *
+     * @param input - Raw authorization code or redirect URL
+     * @returns The extracted authorization code
+     *
+     * @example
+     * ```ts
+     * ClaudeAuth.extractCode("abc123"); // "abc123"
+     * ClaudeAuth.extractCode("https://platform.claude.com/oauth/code/callback?code=abc123&state=xyz"); // "abc123"
+     * ```
+     */
+    static extractCode(input: string): string;
+    /**
+     * Refresh an expired Claude token.
+     *
+     * @param refreshToken - The refresh token from a previous authentication
+     * @returns New auth token with refreshed access token
+     * @throws {TokenExchangeError} If the refresh request fails
+     *
+     * @example
+     * ```ts
+     * const auth = new ClaudeAuth();
+     * const newToken = await auth.refreshToken(oldToken.refreshToken);
+     * ```
+     */
+    refreshToken(refreshToken: string): Promise<ClaudeAuthToken>;
+    private generateCodeVerifier;
+    private generateState;
+    private buildAuthorizeUrl;
+    private generateCodeChallengeSync;
+    private exchangeCode;
+    private mapTokenResponse;
+}
+
+export { AccessDeniedError, AuthError, type AuthToken, ClaudeAuth, type ClaudeAuthToken, CopilotAuth, type CopilotAuthToken, DeviceCodeExpiredError, type DeviceFlowResult, type OAuthFlowOptions, type OAuthFlowResult, TokenExchangeError };

package/dist/auth/index.d.ts

@@ -0,0 +1,271 @@
+/**
+ * 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);
+}
+
+/** Fetch function type for dependency injection in tests */
+type FetchFn$1 = typeof globalThis.fetch;
+/**
+ * Programmatic GitHub Device Flow authentication for Copilot SDK.
+ *
+ * @example
+ * ```ts
+ * const auth = new CopilotAuth();
+ * const flow = await auth.startDeviceFlow();
+ * console.log(`Open ${flow.verificationUrl} and enter ${flow.userCode}`);
+ * const token = await flow.waitForToken();
+ * // Use token.accessToken with CopilotBackendOptions.githubToken
+ * ```
+ */
+declare class CopilotAuth {
+    private readonly fetchFn;
+    /** @param options - Optional configuration with custom fetch for testing */
+    constructor(options?: {
+        fetch?: FetchFn$1;
+    });
+    /**
+     * Start the GitHub Device Flow.
+     * Returns a device code result with user code, verification URL,
+     * and a `waitForToken()` function that polls until the user authorizes.
+     *
+     * @param options - Optional scopes and abort signal
+     * @returns Device flow result with user code, verification URL, and waitForToken poller
+     * @throws {AuthError} If the device code request fails
+     * @throws {DeviceCodeExpiredError} If the device code expires before user authorizes
+     * @throws {AccessDeniedError} If the user denies access
+     *
+     * @example
+     * ```ts
+     * const auth = new CopilotAuth();
+     * const { userCode, verificationUrl, waitForToken } = await auth.startDeviceFlow();
+     * console.log(`Open ${verificationUrl} and enter code: ${userCode}`);
+     * const token = await waitForToken();
+     * ```
+     */
+    startDeviceFlow(options?: {
+        scopes?: string;
+        signal?: AbortSignal;
+    }): Promise<DeviceFlowResult>;
+    private pollForToken;
+    private fetchUserLogin;
+    private delay;
+}
+
+/** Fetch function type for dependency injection in tests */
+type FetchFn = typeof globalThis.fetch;
+/** Random bytes generator for dependency injection in tests */
+type RandomBytesFn = (size: number) => Uint8Array;
+/**
+ * Programmatic OAuth+PKCE authentication for Claude SDK.
+ *
+ * @example
+ * ```ts
+ * const auth = new ClaudeAuth();
+ * const { authorizeUrl, completeAuth } = auth.startOAuthFlow({
+ *   redirectUri: "https://platform.claude.com/oauth/code/callback",
+ * });
+ * // Open authorizeUrl in browser, get code from redirect
+ * const token = await completeAuth(code);
+ * // Use token with ClaudeBackendOptions: env.CLAUDE_CODE_OAUTH_TOKEN
+ * ```
+ */
+declare class ClaudeAuth {
+    private readonly fetchFn;
+    private readonly randomBytes;
+    /**
+     * @param options - Optional configuration with custom fetch and random bytes for testing
+     */
+    constructor(options?: {
+        fetch?: FetchFn;
+        randomBytes?: RandomBytesFn;
+    });
+    /**
+     * Start the Claude OAuth+PKCE flow.
+     * Generates PKCE code verifier/challenge and returns an authorize URL
+     * plus a `completeAuth(code)` function for token exchange.
+     *
+     * @param options - Redirect URI and optional scopes
+     * @returns OAuth flow result with authorize URL and completeAuth function
+     * @throws {AuthError} If PKCE generation fails
+     *
+     * @example
+     * ```ts
+     * const auth = new ClaudeAuth();
+     * const { authorizeUrl, completeAuth } = auth.startOAuthFlow({
+     *   redirectUri: "https://platform.claude.com/oauth/code/callback",
+     * });
+     * console.log(`Open: ${authorizeUrl}`);
+     * const token = await completeAuth(authorizationCode);
+     * ```
+     */
+    startOAuthFlow(options?: OAuthFlowOptions): OAuthFlowResult;
+    /**
+     * Extract an authorization code from user input.
+     * Accepts a raw code string or a full redirect URL containing a `code` query parameter.
+     *
+     * @param input - Raw authorization code or redirect URL
+     * @returns The extracted authorization code
+     *
+     * @example
+     * ```ts
+     * ClaudeAuth.extractCode("abc123"); // "abc123"
+     * ClaudeAuth.extractCode("https://platform.claude.com/oauth/code/callback?code=abc123&state=xyz"); // "abc123"
+     * ```
+     */
+    static extractCode(input: string): string;
+    /**
+     * Refresh an expired Claude token.
+     *
+     * @param refreshToken - The refresh token from a previous authentication
+     * @returns New auth token with refreshed access token
+     * @throws {TokenExchangeError} If the refresh request fails
+     *
+     * @example
+     * ```ts
+     * const auth = new ClaudeAuth();
+     * const newToken = await auth.refreshToken(oldToken.refreshToken);
+     * ```
+     */
+    refreshToken(refreshToken: string): Promise<ClaudeAuthToken>;
+    private generateCodeVerifier;
+    private generateState;
+    private buildAuthorizeUrl;
+    private generateCodeChallengeSync;
+    private exchangeCode;
+    private mapTokenResponse;
+}
+
+export { AccessDeniedError, AuthError, type AuthToken, ClaudeAuth, type ClaudeAuthToken, CopilotAuth, type CopilotAuthToken, DeviceCodeExpiredError, type DeviceFlowResult, type OAuthFlowOptions, type OAuthFlowResult, TokenExchangeError };