berget 1.1.0 → 1.3.0

package/src/types/api.d.ts

@@ -14,6 +14,20 @@ export interface paths {
     /**
      * List all API keys
      * @description Lists all API keys for the authenticated user's organization.
+     *
+     * ## Using the CLI
+     *
+     * You can also manage API keys using our CLI tool:
+     * ```
+     * # Login first (if you haven't already)
+     * npx berget auth login
+     *
+     * # List all API keys
+     * npx berget api-keys list
+     *
+     * # Create a new API key
+     * npx berget api-keys create --name my-api-key
+     * ```
      */
     get: {
       responses: {
@@ -36,6 +50,17 @@ export interface paths {
     /**
      * Create a new API key
      * @description Creates a new API key for the authenticated user's organization. The full API key is only returned once at creation time.
+     *
+     * ## Using the CLI
+     *
+     * Creating an API key is easier with our CLI tool:
+     * ```
+     * # Login first (if you haven't already)
+     * npx berget auth login
+     *
+     * # Create a new API key
+     * npx berget api-keys create --name my-api-key
+     * ```
      */
     post: {
       requestBody: {
@@ -97,6 +122,21 @@ export interface paths {
     /**
      * Rotate an API key
      * @description Rotates an API key by invalidating the old key and generating a new one. The new key is returned in the response and is only shown once.
+     *
+     * ## Using the CLI
+     *
+     * You can also rotate API keys using our CLI tool:
+     * ```
+     * # Login first (if you haven't already)
+     * npx berget auth login
+     *
+     * # Rotate an API key
+     * npx berget api-keys rotate --id <key-id>
+     * ```
+     *
+     * ## Security Note
+     *
+     * When you rotate an API key, the old key becomes invalid immediately. Make sure to update any applications using the key.
      */
     put: {
       parameters: {
@@ -131,6 +171,20 @@ export interface paths {
     /**
      * Get API key usage statistics
      * @description Returns usage statistics for a specific API key including request count, daily breakdown, model-specific usage, and token consumption.
+     *
+     * ## Using the CLI
+     *
+     * You can also view API key usage using our CLI tool:
+     * ```
+     * # Login first (if you haven't already)
+     * npx berget auth login
+     *
+     * # View usage for a specific API key
+     * npx berget api-keys usage --id <key-id>
+     *
+     * # View usage for all API keys
+     * npx berget usage
+     * ```
      */
     get: {
       parameters: {
@@ -351,13 +405,27 @@ export interface paths {
   "/v1/auth/login": {
     /**
      * OAuth login
-     * @description Initiates OAuth login flow via Keycloak
+     * @description Initiates OAuth login flow via Keycloak.
+     *
+     * ## CLI Authentication
+     *
+     * For a simpler experience, you can use our CLI tool to authenticate:
+     * ```
+     * npx berget auth login
+     * ```
+     *
+     * After logging in, you can create an API key with:
+     * ```
+     * npx berget api-keys create --name my-api-key
+     * ```
      */
     get: {
       parameters: {
         query?: {
           /** @description URL to redirect to after successful login */
           redirect_uri?: string;
+          /** @description How to return the token after successful login (default is redirect) */
+          response_type?: "redirect" | "json";
         };
       };
       responses: {
@@ -389,29 +457,108 @@ export interface paths {
     };
   };
   "/v1/auth/device": {
-    /** Initiate device authorization flow */
+    /**
+     * Initiate device authorization flow
+     * @description Initiates the device authorization flow, returning a device code and user verification URL.
+     *
+     * ## Using the CLI
+     *
+     * The recommended way to authenticate is through our CLI tool:
+     * ```
+     * npx berget auth login
+     * ```
+     *
+     * This handles the device flow automatically and provides a better user experience.
+     */
     post: {
       responses: {
         /** @description Device authorization initiated */
         200: {
-          content: never;
+          content: {
+            "application/json": components["schemas"]["DeviceAuthInitResponse"];
+          };
         };
       };
     };
   };
   "/v1/auth/device/token": {
-    /** Poll for device token */
+    /**
+     * Poll for device token
+     * @description Polls for the status of a device authorization flow. The client should poll this endpoint
+     * until it receives a token or an error.
+     *
+     * ## Using the CLI
+     *
+     * The recommended way to authenticate is through our CLI tool:
+     * ```
+     * npx berget auth login
+     * ```
+     *
+     * This handles the polling automatically and provides a better user experience.
+     *
+     * ## Troubleshooting
+     *
+     * - If you receive a 400 error, the device code may be invalid or expired
+     * - If you receive a 429 error, you're polling too frequently
+     * - If you receive a 500 error, there may be an issue with the authentication service
+     */
     post: {
       requestBody: {
         content: {
-          "application/json": {
-            device_code?: string;
-          };
+          "application/json": components["schemas"]["DeviceAuthRequest"];
         };
       };
       responses: {
         /** @description Token returned or pending status */
         200: {
+          content: {
+            "application/json": components["schemas"]["DeviceAuthPendingResponse"] | components["schemas"]["DeviceAuthTokenResponse"];
+          };
+        };
+        /** @description Invalid device code or expired token */
+        400: {
+          content: never;
+        };
+        /** @description Polling too frequently */
+        429: {
+          content: never;
+        };
+        /** @description Server error during authentication */
+        500: {
+          content: never;
+        };
+      };
+    };
+  };
+  "/v1/auth/refresh": {
+    /**
+     * Refresh access token
+     * @description Refreshes an access token using a refresh token. This endpoint can be used to obtain a new
+     * access token when the current one expires.
+     *
+     * ## Using the CLI
+     *
+     * The CLI tool handles token refresh automatically:
+     * ```
+     * # The CLI will refresh tokens as needed
+     * npx berget api-keys list
+     * ```
+     */
+    post: {
+      requestBody: {
+        content: {
+          "application/json": components["schemas"]["RefreshTokenRequest"];
+        };
+      };
+      responses: {
+        /** @description New access and refresh tokens */
+        200: {
+          content: {
+            "application/json": components["schemas"]["RefreshTokenResponse"];
+          };
+        };
+        /** @description Invalid or expired refresh token */
+        401: {
           content: never;
         };
       };
@@ -1418,8 +1565,6 @@ export interface components {
     };
     AuthToken: {
       accessToken: string;
-      /** @enum {string} */
-      tokenType: "Bearer";
       expiresIn: number;
       user?: {
         id: string;
@@ -1437,6 +1582,55 @@ export interface components {
       /** Format: uri */
       avatarUrl: string;
     };
+    RefreshTokenRequest: {
+      /** @description The refresh token to use */
+      refresh_token: string;
+      /** @description Whether this is a device token */
+      is_device_token?: boolean;
+    };
+    RefreshTokenResponse: {
+      /** @description The new access token */
+      token: string;
+      /** @description The new refresh token */
+      refresh_token: string;
+      /** @description Seconds until the access token expires */
+      expires_in: number;
+      /** @description Seconds until the refresh token expires */
+      refresh_expires_in: number;
+    };
+    DeviceAuthRequest: {
+      /** @description The device code obtained from the device authorization request */
+      device_code: string;
+    };
+    DeviceAuthInitResponse: {
+      /** @description Code used by the device to poll for authentication status */
+      device_code: string;
+      /** @description Code displayed to the user for authentication */
+      user_code: string;
+      /** @description URL where the user should enter the user_code */
+      verification_url: string;
+      /** @description Expiration time in seconds */
+      expires_in: number;
+      /** @description Polling interval in seconds */
+      interval: number;
+    };
+    DeviceAuthPendingResponse: {
+      /**
+       * @description Authentication is still pending
+       * @enum {string}
+       */
+      status: "pending";
+    };
+    DeviceAuthTokenResponse: {
+      /** @description Access token */
+      token: string;
+      /** @description Refresh token */
+      refresh_token: string;
+      /** @description Access token expiration time in seconds */
+      expires_in: number;
+      /** @description Refresh token expiration time in seconds */
+      refresh_expires_in: number;
+    };
     Usage: {
       current_period: {
         /** Format: date-time */

package/src/types/json.d.ts

@@ -0,0 +1,4 @@
+declare module "*.json" {
+  const value: any;
+  export = value;
+}

package/src/utils/default-api-key.ts

@@ -2,11 +2,15 @@ import * as fs from 'fs'
 import * as path from 'path'
 import * as os from 'os'
 import chalk from 'chalk'
+import { ApiKeyService } from '../services/api-key-service'
+import readline from 'readline'
+import { logger } from './logger'
 
 interface DefaultApiKeyData {
   id: string
   name: string
   prefix: string
+  key: string
 }
 
 /**
@@ -44,7 +48,7 @@ export class DefaultApiKeyManager {
         this.defaultApiKey = JSON.parse(data)
       }
     } catch (error) {
-      console.error(chalk.dim('Failed to load default API key configuration'))
+      logger.debug('Failed to load default API key configuration')
       this.defaultApiKey = null
     }
   }
@@ -65,22 +69,29 @@ export class DefaultApiKeyManager {
         }
       }
     } catch (error) {
-      console.error(chalk.dim('Failed to save default API key configuration'))
+      logger.debug('Failed to save default API key configuration')
     }
   }
   
   /**
    * Set the default API key
    */
-  public setDefaultApiKey(id: string, name: string, prefix: string): void {
-    this.defaultApiKey = { id, name, prefix }
+  public setDefaultApiKey(id: string, name: string, prefix: string, key: string): void {
+    this.defaultApiKey = { id, name, prefix, key }
     this.saveConfig()
   }
   
   /**
-   * Get the default API key
+   * Get the default API key string
    */
-  public getDefaultApiKey(): DefaultApiKeyData | null {
+  public getDefaultApiKey(): string | null {
+    return this.defaultApiKey?.key || null
+  }
+  
+  /**
+   * Get the default API key data object
+   */
+  public getDefaultApiKeyData(): DefaultApiKeyData | null {
     return this.defaultApiKey
   }
   
@@ -91,4 +102,111 @@ export class DefaultApiKeyManager {
     this.defaultApiKey = null
     this.saveConfig()
   }
+
+  /**
+   * Prompts the user to select a default API key if none is set
+   * @returns The selected API key or null if none was selected
+   */
+  public async promptForDefaultApiKey(): Promise<string | null> {
+    try {
+      logger.debug('promptForDefaultApiKey called')
+      
+      // If we already have a default API key, return it
+      if (this.defaultApiKey) {
+        logger.debug('Using existing default API key')
+        return this.defaultApiKey.key
+      }
+
+      logger.debug('No default API key found, getting ApiKeyService')
+      
+      const apiKeyService = ApiKeyService.getInstance()
+      
+      // Get all API keys
+      let apiKeys;
+      try {
+        logger.debug('Calling apiKeyService.list()')
+        
+        apiKeys = await apiKeyService.list()
+        
+        logger.debug(`Got ${apiKeys ? apiKeys.length : 0} API keys`)
+        
+        if (!apiKeys || apiKeys.length === 0) {
+          logger.warn('No API keys found. Create one with:')
+          logger.info('  berget api-keys create --name "My Key"')
+          return null
+        }
+      } catch (error) {
+        // Check if this is an authentication error
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const isAuthError = errorMessage.includes('Unauthorized') || 
+                           errorMessage.includes('Authentication failed') ||
+                           errorMessage.includes('AUTH_FAILED');
+        
+        if (isAuthError) {
+          logger.warn('Authentication required. Please run `berget auth login` first.');
+        } else {
+          logger.error('Error fetching API keys:');
+          if (error instanceof Error) {
+            logger.error(error.message);
+            logger.debug(`API key list error: ${error.message}`);
+            logger.debug(`Stack: ${error.stack}`);
+          }
+        }
+        return null;
+      }
+      
+      logger.info('Select an API key to use as default:')
+      
+      // Display available API keys
+      apiKeys.forEach((key, index) => {
+        logger.log(`  ${index + 1}. ${key.name} (${key.prefix}...)`)
+      })
+      
+      // Create readline interface for user input
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+      })
+      
+      // Prompt for selection
+      const selection = await new Promise<number>((resolve) => {
+        rl.question('Enter number (or press Enter to cancel): ', (answer) => {
+          rl.close()
+          const num = parseInt(answer.trim(), 10)
+          if (isNaN(num) || num < 1 || num > apiKeys.length) {
+            resolve(-1) // Invalid selection
+          } else {
+            resolve(num - 1) // Convert to zero-based index
+          }
+        })
+      })
+      
+      if (selection === -1) {
+        logger.warn('No API key selected')
+        return null
+      }
+      
+      const selectedKey = apiKeys[selection]
+      
+      // Create a new API key with the selected name
+      const newKey = await apiKeyService.create({
+        name: `CLI Default (copy of ${selectedKey.name})`,
+        description: 'Created automatically by the Berget CLI for default use'
+      })
+      
+      // Save the new key as default
+      this.setDefaultApiKey(
+        newKey.id.toString(), 
+        newKey.name, 
+        newKey.key.substring(0, 8), // Use first 8 chars as prefix
+        newKey.key
+      )
+      
+      logger.success(`✓ Default API key set to: ${newKey.name}`)
+      return newKey.key
+    } catch (error) {
+      logger.error('Failed to set default API key:', error)
+      return null
+    }
+  }
 }

package/src/utils/error-handler.ts

@@ -30,11 +30,11 @@ export function handleError(message: string, error: any): void {
   
   // Check for authentication errors
   if (
-    (typeof error === 'string' && error.includes('Unauthorized')) ||
-    (error && error.message && error.message.includes('Unauthorized')) ||
-    (error && error.code && error.code === 401)
+    (typeof error === 'string' && (error.includes('Unauthorized') || error.includes('Authentication failed'))) ||
+    (error && error.message && (error.message.includes('Unauthorized') || error.message.includes('Authentication failed'))) ||
+    (error && error.code && (error.code === 401 || error.code === 'AUTH_FAILED'))
   ) {
     console.error(chalk.yellow('\nYou need to be logged in to use this command.'));
-    console.error(chalk.yellow('Run `berget login` to authenticate.'));
+    console.error(chalk.yellow('Run `berget auth login` to authenticate.'));
   }
 }

package/src/utils/logger.ts

@@ -0,0 +1,159 @@
+import chalk from 'chalk'
+
+/**
+ * Log levels in order of increasing verbosity
+ */
+export enum LogLevel {
+  NONE = 0,
+  ERROR = 1,
+  WARN = 2,
+  INFO = 3,
+  DEBUG = 4
+}
+
+/**
+ * Logger class for centralized logging with configurable log levels
+ */
+export class Logger {
+  private static instance: Logger
+  private logLevel: LogLevel = LogLevel.INFO // Default log level
+  
+  private constructor() {
+    // Set log level from environment variable or command line argument
+    if (process.env.LOG_LEVEL) {
+      this.setLogLevelFromString(process.env.LOG_LEVEL)
+    } else if (process.argv.includes('--debug')) {
+      this.logLevel = LogLevel.DEBUG
+    } else if (process.argv.includes('--quiet')) {
+      this.logLevel = LogLevel.ERROR
+    }
+  }
+  
+  public static getInstance(): Logger {
+    if (!Logger.instance) {
+      Logger.instance = new Logger()
+    }
+    return Logger.instance
+  }
+  
+  /**
+   * Set the log level from a string
+   */
+  private setLogLevelFromString(level: string): void {
+    switch (level.toLowerCase()) {
+      case 'none':
+        this.logLevel = LogLevel.NONE
+        break
+      case 'error':
+        this.logLevel = LogLevel.ERROR
+        break
+      case 'warn':
+        this.logLevel = LogLevel.WARN
+        break
+      case 'info':
+        this.logLevel = LogLevel.INFO
+        break
+      case 'debug':
+        this.logLevel = LogLevel.DEBUG
+        break
+      default:
+        // Invalid log level, keep default
+        console.warn(`Invalid log level: ${level}. Using default (INFO).`)
+    }
+  }
+  
+  /**
+   * Set the log level
+   */
+  public setLogLevel(level: LogLevel): void {
+    this.logLevel = level
+  }
+  
+  /**
+   * Get the current log level
+   */
+  public getLogLevel(): LogLevel {
+    return this.logLevel
+  }
+  
+  /**
+   * Log a debug message (only shown at DEBUG level)
+   */
+  public debug(message: string, ...args: any[]): void {
+    if (this.logLevel >= LogLevel.DEBUG) {
+      if (args.length > 0) {
+        console.log(chalk.yellow(`DEBUG: ${message}`), ...args)
+      } else {
+        console.log(chalk.yellow(`DEBUG: ${message}`))
+      }
+    }
+  }
+  
+  /**
+   * Log an info message (shown at INFO level and above)
+   */
+  public info(message: string, ...args: any[]): void {
+    if (this.logLevel >= LogLevel.INFO) {
+      if (args.length > 0) {
+        console.log(chalk.blue(message), ...args)
+      } else {
+        console.log(chalk.blue(message))
+      }
+    }
+  }
+  
+  /**
+   * Log a warning message (shown at WARN level and above)
+   */
+  public warn(message: string, ...args: any[]): void {
+    if (this.logLevel >= LogLevel.WARN) {
+      if (args.length > 0) {
+        console.log(chalk.yellow(message), ...args)
+      } else {
+        console.log(chalk.yellow(message))
+      }
+    }
+  }
+  
+  /**
+   * Log an error message (shown at ERROR level and above)
+   */
+  public error(message: string, ...args: any[]): void {
+    if (this.logLevel >= LogLevel.ERROR) {
+      if (args.length > 0) {
+        console.error(chalk.red(message), ...args)
+      } else {
+        console.error(chalk.red(message))
+      }
+    }
+  }
+  
+  /**
+   * Log a success message (shown at INFO level and above)
+   */
+  public success(message: string, ...args: any[]): void {
+    if (this.logLevel >= LogLevel.INFO) {
+      if (args.length > 0) {
+        console.log(chalk.green(message), ...args)
+      } else {
+        console.log(chalk.green(message))
+      }
+    }
+  }
+  
+  /**
+   * Log a plain message without color (shown at INFO level and above)
+   */
+  public log(message: string, ...args: any[]): void {
+    if (this.logLevel >= LogLevel.INFO) {
+      if (args.length > 0) {
+        console.log(message, ...args)
+      } else {
+        console.log(message)
+      }
+    }
+  }
+}
+
+// Export a singleton instance for easy import
+export const logger = Logger.getInstance()

package/src/utils/token-manager.ts

@@ -2,6 +2,7 @@ import * as fs from 'fs'
 import * as path from 'path'
 import * as os from 'os'
 import chalk from 'chalk'
+import { logger } from './logger'
 
 interface TokenData {
   access_token: string
@@ -44,7 +45,7 @@ export class TokenManager {
         this.tokenData = JSON.parse(data)
       }
     } catch (error) {
-      console.error(chalk.dim('Failed to load authentication token'))
+      logger.error('Failed to load authentication token')
       this.tokenData = null
     }
   }
@@ -65,7 +66,7 @@ export class TokenManager {
         }
       }
     } catch (error) {
-      console.error(chalk.dim('Failed to save authentication token'))
+      logger.error('Failed to save authentication token')
     }
   }
   
@@ -100,14 +101,14 @@ export class TokenManager {
       const expirationBuffer = 10 * 60 * 1000 // 10 minutes in milliseconds
       const isExpired = Date.now() + expirationBuffer >= this.tokenData.expires_at;
       
-      if (isExpired && process.argv.includes('--debug')) {
-        console.log(chalk.yellow(`DEBUG: Token expired or expiring soon. Current time: ${new Date().toISOString()}, Expiry: ${new Date(this.tokenData.expires_at).toISOString()}`));
+      if (isExpired) {
+        logger.debug(`Token expired or expiring soon. Current time: ${new Date().toISOString()}, Expiry: ${new Date(this.tokenData.expires_at).toISOString()}`);
       }
       
       return isExpired;
     } catch (error) {
       // If there's any error checking expiration, assume token is expired
-      console.error(chalk.dim(`Error checking token expiration: ${error instanceof Error ? error.message : String(error)}`));
+      logger.error(`Error checking token expiration: ${error instanceof Error ? error.message : String(error)}`);
       return true;
     }
   }

package/tsconfig.json

@@ -39,7 +39,7 @@
     // "resolvePackageJsonExports": true,                /* Use the package.json 'exports' field when resolving package imports. */
     // "resolvePackageJsonImports": true,                /* Use the package.json 'imports' field when resolving imports. */
     // "customConditions": [],                           /* Conditions to set in addition to the resolver-specific defaults when resolving imports. */
-    // "resolveJsonModule": true,                        /* Enable importing .json files. */
+    "resolveJsonModule": true,                        /* Enable importing .json files. */
     // "allowArbitraryExtensions": true,                 /* Enable importing files with any extension, provided a declaration file is present. */
     // "noResolve": true,                                /* Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project. */