opencode-qwen-cli-auth 2.2.9 → 2.3.0

package/dist/lib/constants.js

@@ -1,12 +1,24 @@
 /**
- * Constants for Qwen OAuth Plugin
+ * @fileoverview Constants for Qwen OAuth Plugin
+ * Centralized configuration for OAuth endpoints, headers, error codes, and other constants
+ * @license MIT
  */
-/** Plugin identifier */
+
+/** Plugin identifier for logging and debugging */
 export const PLUGIN_NAME = "qwen-oauth-plugin";
-/** Provider ID for opencode configuration (used in model references like qwen-code/coder-model) */
+
+/**
+ * Provider ID for opencode configuration
+ * Used in model references like qwen-code/coder-model
+ */
 export const PROVIDER_ID = "qwen-code";
-/** Dummy API key (actual auth via OAuth) */
+
+/**
+ * Dummy API key placeholder
+ * Actual authentication is handled via OAuth flow, not API key
+ */
 export const DUMMY_API_KEY = "qwen-oauth";
+
 /**
  * Default Qwen DashScope base URL (fallback if resource_url is missing)
  * Note: This plugin is for OAuth authentication only. For API key authentication,
@@ -15,27 +27,43 @@ export const DUMMY_API_KEY = "qwen-oauth";
  * IMPORTANT: OAuth endpoints use /api/v1, DashScope OpenAI-compatible uses /compatible-mode/v1
  * - OAuth endpoints: /api/v1/oauth2/ (for authentication)
  * - Chat API: /v1/ (for completions)
+ *
+ * @constant {string}
  */
 // NOTE:
 // qwen-code (official CLI) defaults to DashScope OpenAI-compatible endpoint when
 // `resource_url` is missing. This is required for the free OAuth flow to behave
 // the same as the CLI.
 export const DEFAULT_QWEN_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
-/** Qwen OAuth endpoints and configuration */
+
+/**
+ * Qwen OAuth endpoints and configuration
+ * Source: Qwen Code CLI (https://github.com/QwenLM/qwen-code)
+ * @namespace
+ */
 export const QWEN_OAUTH = {
+    /** OAuth 2.0 Device Code endpoint */
     DEVICE_CODE_URL: "https://chat.qwen.ai/api/v1/oauth2/device/code",
+    /** OAuth 2.0 Token endpoint */
     TOKEN_URL: "https://chat.qwen.ai/api/v1/oauth2/token",
     /**
      * Qwen OAuth Client ID
-     * Source: Qwen Code CLI (https://github.com/QwenLM/qwen-code)
      * This is a public client ID used for OAuth Device Authorization Grant flow (RFC 8628)
+     * @constant {string}
      */
     CLIENT_ID: "f0304373b74a44d2b584a3fb70ca9e56",
+    /** OAuth scopes requested: openid, profile, email, and model completion access */
     SCOPE: "openid profile email model.completion",
+    /** OAuth 2.0 Device Code grant type (RFC 8628) */
     GRANT_TYPE_DEVICE: "urn:ietf:params:oauth:grant-type:device_code",
+    /** OAuth 2.0 Refresh Token grant type */
     GRANT_TYPE_REFRESH: "refresh_token",
 };
-/** HTTP Status Codes */
+
+/**
+ * HTTP Status Codes for error handling
+ * @namespace
+ */
 export const HTTP_STATUS = {
     OK: 200,
     BAD_REQUEST: 400,
@@ -43,21 +71,37 @@ export const HTTP_STATUS = {
     FORBIDDEN: 403,
     TOO_MANY_REQUESTS: 429,
 };
+
 /**
- * DashScope headers
+ * DashScope headers for OAuth authentication
  * Note: OAuth requires X-DashScope-AuthType to indicate qwen-oauth authentication
+ * @namespace
  */
 export const PORTAL_HEADERS = {
+    /** Header name for auth type specification */
     AUTH_TYPE: "X-DashScope-AuthType",
+    /** Header value for qwen-oauth authentication */
     AUTH_TYPE_VALUE: "qwen-oauth",
 };
-/** Device flow polling configuration */
+
+/**
+ * Device flow polling configuration
+ * Controls backoff strategy for OAuth token polling
+ * @namespace
+ */
 export const DEVICE_FLOW = {
+    /** Initial polling interval in milliseconds */
     INITIAL_POLL_INTERVAL: 2000, // 2 seconds
+    /** Maximum polling interval in milliseconds */
     MAX_POLL_INTERVAL: 10000, // 10 seconds
+    /** Backoff multiplier for exponential backoff */
     BACKOFF_MULTIPLIER: 1.5,
 };
-/** Error messages */
+
+/**
+ * Error messages for user-facing errors
+ * @namespace
+ */
 export const ERROR_MESSAGES = {
     TOKEN_REFRESH_FAILED: "Failed to refresh token, authentication required",
     DEVICE_AUTH_TIMEOUT: "Device authorization timed out",
@@ -65,14 +109,27 @@ export const ERROR_MESSAGES = {
     REQUEST_PARSE_ERROR: "Error parsing request",
     NO_RESOURCE_URL: "No resource_url in token response, using default",
 };
-/** OAuth error codes */
+
+/**
+ * OAuth error codes from RFC 8628 Device Flow
+ * @namespace
+ */
 export const OAUTH_ERRORS = {
+    /** User has not yet authorized the device code */
     AUTHORIZATION_PENDING: "authorization_pending",
+    /** Server requests slower polling (slow_down error) */
     SLOW_DOWN: "slow_down",
+    /** User denied the authorization request */
     ACCESS_DENIED: "access_denied",
+    /** Device code has expired */
     EXPIRED_TOKEN: "expired_token",
 };
-/** Log stages for request logging */
+
+/**
+ * Log stages for request logging
+ * Used for debugging and tracing request lifecycle
+ * @namespace
+ */
 export const LOG_STAGES = {
     BEFORE_TRANSFORM: "before-transform",
     AFTER_TRANSFORM: "after-transform",
@@ -81,29 +138,53 @@ export const LOG_STAGES = {
     DEVICE_CODE_REQUEST: "device-code-request",
     TOKEN_POLL: "token-poll",
 };
-/** Platform-specific browser opener commands */
+
+/**
+ * Platform-specific browser opener commands
+ * Used for opening OAuth verification URL in default browser
+ * @namespace
+ */
 export const PLATFORM_OPENERS = {
     darwin: "open",
     win32: "start",
     linux: "xdg-open",
 };
-/** OAuth authorization labels */
+
+/**
+ * OAuth authorization labels for UI display
+ * @namespace
+ */
 export const AUTH_LABELS = {
+    /** Label shown in OpenCode auth provider selection */
     OAUTH: "Qwen Code (qwen.ai OAuth)",
+    /** Instructions shown to user during OAuth flow */
     INSTRUCTIONS: "Visit the URL shown in your browser to complete authentication.",
 };
-/** OAuth verification URI parameters */
+
+/**
+ * OAuth verification URI parameters
+ * Used to construct complete verification URL with client identification
+ * @namespace
+ */
 export const VERIFICATION_URI = {
     /** Query parameter key for client identification */
     CLIENT_PARAM_KEY: "client=",
     /** Full query parameter for Qwen Code client */
     CLIENT_PARAM_VALUE: "client=qwen-code",
 };
-/** Token refresh buffer (refresh 30 seconds before expiry) */
+
+/**
+ * Token refresh buffer in milliseconds
+ * Tokens are refreshed 30 seconds before expiry to avoid race conditions
+ * @constant {number}
+ */
 export const TOKEN_REFRESH_BUFFER_MS = 30 * 1000; // 30 seconds
-/** Stream processing configuration */
+
+/**
+ * Stream processing configuration
+ * @namespace
+ */
 export const STREAM_CONFIG = {
     /** Maximum buffer size for SSE pass-through mode (1MB) */
     MAX_BUFFER_SIZE: 1024 * 1024,
 };
-//# sourceMappingURL=constants.js.map

package/dist/lib/logger.js

@@ -1,10 +1,34 @@
+/**
+ * @fileoverview Logging utilities for Qwen OAuth Plugin
+ * Provides configurable logging for debugging and request tracing
+ * @license MIT
+ */
+
 import { writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-// Logging configuration
+
+/**
+ * Flag to enable request logging to file
+ * Controlled by ENABLE_PLUGIN_REQUEST_LOGGING environment variable
+ * @constant {boolean}
+ */
 export const LOGGING_ENABLED = process.env.ENABLE_PLUGIN_REQUEST_LOGGING === "1";
+
+/**
+ * Flag to enable debug logging to console
+ * Controlled by DEBUG_QWEN_PLUGIN or ENABLE_PLUGIN_REQUEST_LOGGING environment variables
+ * @constant {boolean}
+ */
 export const DEBUG_ENABLED = process.env.DEBUG_QWEN_PLUGIN === "1" || LOGGING_ENABLED;
+
+/**
+ * Directory path for log files
+ * Logs are stored in ~/.opencode/logs/qwen-plugin/
+ * @constant {string}
+ */
 const LOG_DIR = join(homedir(), ".opencode", "logs", "qwen-plugin");
+
 // Log startup message about logging state
 if (LOGGING_ENABLED) {
     console.log("[qwen-oauth-plugin] Request logging ENABLED - logs will be saved to:", LOG_DIR);
@@ -12,23 +36,34 @@ if (LOGGING_ENABLED) {
 if (DEBUG_ENABLED && !LOGGING_ENABLED) {
     console.log("[qwen-oauth-plugin] Debug logging ENABLED");
 }
+
+/**
+ * Request counter for generating unique request IDs in logs
+ * @type {number}
+ */
 let requestCounter = 0;
+
 /**
  * Log request data to file (only when LOGGING_ENABLED is true)
- * @param stage - The stage of the request (e.g., "before-transform", "after-transform")
- * @param data - The data to log
+ * Creates JSON files with request/response data for debugging
+ * @param {string} stage - The stage of the request (e.g., "before-transform", "after-transform", "response")
+ * @param {Object} data - The data to log (request/response objects, metadata, etc.)
+ * @returns {void}
  */
 export function logRequest(stage, data) {
     // Only log if explicitly enabled via environment variable
     if (!LOGGING_ENABLED)
         return;
+    
     // Ensure log directory exists on first log
     if (!existsSync(LOG_DIR)) {
         mkdirSync(LOG_DIR, { recursive: true });
     }
+    
     const timestamp = new Date().toISOString();
     const requestId = ++requestCounter;
     const filename = join(LOG_DIR, `request-${requestId}-${stage}.json`);
+    
     try {
         writeFileSync(filename, JSON.stringify({
             timestamp,
@@ -43,10 +78,13 @@ export function logRequest(stage, data) {
         console.error("[qwen-oauth-plugin] Failed to write log:", error.message);
     }
 }
+
 /**
  * Log debug information (only when DEBUG_ENABLED is true)
- * @param message - Debug message
- * @param data - Optional data to log
+ * Used for detailed debugging during development
+ * @param {string} message - Debug message describing the context
+ * @param {*} [data] - Optional data to log (objects, values, etc.)
+ * @returns {void}
  */
 export function logDebug(message, data) {
     if (!DEBUG_ENABLED)
@@ -58,10 +96,13 @@ export function logDebug(message, data) {
         console.log(`[qwen-oauth-plugin] ${message}`);
     }
 }
+
 /**
  * Log error (always enabled for important issues)
- * @param message - Error message
- * @param data - Optional data to log
+ * Used for critical errors that need attention
+ * @param {string} message - Error message describing what went wrong
+ * @param {*} [data] - Optional data to log (error objects, context, etc.)
+ * @returns {void}
  */
 export function logError(message, data) {
     if (data !== undefined) {
@@ -71,10 +112,13 @@ export function logError(message, data) {
         console.error(`[qwen-oauth-plugin] ${message}`);
     }
 }
+
 /**
  * Log warning (always enabled for important issues)
- * @param message - Warning message
- * @param data - Optional data to log
+ * Used for non-critical issues that may need attention
+ * @param {string} message - Warning message describing the issue
+ * @param {*} [data] - Optional data to log (context, values, etc.)
+ * @returns {void}
  */
 export function logWarn(message, data) {
     if (data !== undefined) {
@@ -84,10 +128,13 @@ export function logWarn(message, data) {
         console.warn(`[qwen-oauth-plugin] ${message}`);
     }
 }
+
 /**
  * Log info message (always enabled)
- * @param message - Info message
- * @param data - Optional data to log
+ * Used for general informational messages
+ * @param {string} message - Info message describing the event
+ * @param {*} [data] - Optional data to log (context, values, etc.)
+ * @returns {void}
  */
 export function logInfo(message, data) {
     if (data !== undefined) {
@@ -97,4 +144,3 @@ export function logInfo(message, data) {
         console.log(`[qwen-oauth-plugin] ${message}`);
     }
 }
-//# sourceMappingURL=logger.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-qwen-cli-auth",
-  "version": "2.2.9",
+  "version": "2.3.0",
   "description": "Qwen OAuth authentication plugin for opencode - use your Qwen account instead of API keys",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",