lightspeed-retail-sdk 3.3.5 → 3.4.1

package/README.md

@@ -2,9 +2,18 @@
 
 A modern JavaScript SDK for interacting with the Lightspeed Retail API. This SDK provides a convenient, secure, and flexible way to access Lightspeed Retail's features—including customer, item, and order management.
 
-**Current Version: 3.3.5** — improve error checking on token refresh to prevent false email warnings.
+**Current Version: 3.4.1** — Auto-discovery system for seamless cron job and production deployment.
 
-## **🆕 Recent Updates (v3.3.5)**
+## **🆕 Recent Updates (v3.4.0)**
+
+- **🤖 Auto-Discovery System**: SDK automatically discovers storage configuration after CLI setup - perfect for cron jobs and automated scripts
+- **🔧 Enhanced Token Injection**: Interactive `inject-tokens` command with prompts for access/refresh tokens, expiry settings, and storage backend selection  
+- **🏭 Production Environment Support**: Login command supports headless environments with `--no-browser` option
+- **📁 Storage Configuration Management**: Automatic saving and updating of storage configurations during CLI operations
+- **🔄 Migration Transparency**: Storage migrations automatically update all scripts to use new storage
+- **💡 Improved CLI UX**: Better error messages, token validation, and clear instructions for manual OAuth flows
+
+## **Previous Updates (v3.3.5)**
 
 - **Add centralized query param builder for API requests**: Add centralized query param builder for API requests. Supports input as object, string, or array, and manages relations/load_relations. Ensures no double-encoding of parameters and handles special cases for 'or' and 'timeStamp'.
 - **🎯 Enhanced Parameter Support**: All main getter methods now support both legacy and new object-based parameters with full backward compatibility
@@ -20,12 +29,14 @@ A modern JavaScript SDK for interacting with the Lightspeed Retail API. This SDK
 
 ## 🚀 Key Features
 
-- **Modern API**: Object-based parameters with full backward compatibility
-- **Timestamp Filtering**: Get only records updated since a specific time
-- **Robust Error Handling**: Clean, silent error handling with consistent return types
-- **Enhanced CLI**: Browser selection, default scopes, and improved authentication
-- **Multiple Storage Options**: File, encrypted, database, and in-memory token storage
-- **Comprehensive Coverage**: 20+ API methods with consistent interfaces
+- **🤖 Auto-Discovery**: Zero-configuration after CLI setup - perfect for cron jobs and production
+- **🔄 Modern API**: Object-based parameters with full backward compatibility
+- **🕒 Timestamp Filtering**: Get only records updated since a specific time
+- **🛡️ Robust Error Handling**: Clean, silent error handling with consistent return types
+- **🎯 Enhanced CLI**: Interactive setup with storage selection and headless support
+- **🔒 Multiple Storage Options**: File, encrypted, database, and in-memory token storage
+- **📊 Comprehensive Coverage**: 20+ API methods with consistent interfaces
+- **⚡ Seamless Token Management**: Automatic token refresh with failure notifications
 
 ## 🔄 Migrating from 3.1.x
 
@@ -66,7 +77,8 @@ const items = await sdk.getItems({
 ## Table of Contents
 
 - [Another Unofficial Lightspeed Retail V3 API SDK](#another-unofficial-lightspeed-retail-v3-api-sdk)
-  - [**🆕 Recent Updates (v3.3.5)**](#-recent-updates-v335)
+  - [**🆕 Recent Updates (v3.4.0)**](#-recent-updates-v340)
+  - [**Previous Updates (v3.3.5)**](#previous-updates-v335)
   - [🚀 Key Features](#-key-features)
   - [🔄 Migrating from 3.1.x](#-migrating-from-31x)
     - [Backward Compatibility](#backward-compatibility)
@@ -105,8 +117,12 @@ const items = await sdk.getItems({
   - [Quick Start](#quick-start)
     - [Modern CLI-First Approach (Recommended)](#modern-cli-first-approach-recommended)
       - [Alternative: Local Installation](#alternative-local-installation)
-    - [Basic Usage (In-Memory Storage)](#basic-usage-in-memory-storage)
+    - [Recommended Usage (Auto-Discovery)](#recommended-usage-auto-discovery)
+    - [Explicit Storage (Advanced)](#explicit-storage-advanced)
+    - [Production \& Cron Job Setup](#production--cron-job-setup)
     - [Manual Token Management (Advanced)](#manual-token-management-advanced)
+      - [Option 1: Interactive Token Injection (Easiest)](#option-1-interactive-token-injection-easiest)
+      - [Option 2: Programmatic Token Storage](#option-2-programmatic-token-storage)
       - [File-Based Storage](#file-based-storage)
       - [Encrypted Storage (Recommended)](#encrypted-storage-recommended)
   - [Database Storage (PostgreSQL, SQLite, and MongoDB)](#database-storage-postgresql-sqlite-and-mongodb)
@@ -197,6 +213,9 @@ lightspeed-retail-sdk login --browser firefox
 lightspeed-retail-sdk login --browser "google chrome"
 lightspeed-retail-sdk login --browser safari
 
+# Production/headless environment - display URL without opening browser
+lightspeed-retail-sdk login --no-browser
+
 # Check current token status
 lightspeed-retail-sdk token-status
 
@@ -205,6 +224,12 @@ lightspeed-retail-sdk refresh-token
 
 # View your account information
 lightspeed-retail-sdk whoami
+
+# Manually inject access and refresh tokens (interactive)
+lightspeed-retail-sdk inject-tokens
+
+# Manually inject tokens with command-line options
+lightspeed-retail-sdk inject-tokens --access "your_access_token" --refresh "your_refresh_token"
 ```
 
 #### Storage Management
@@ -249,10 +274,11 @@ lightspeed-retail-sdk login
 The login process:
 
 1. Prompts for your Lightspeed credentials (if not in environment)
-2. Optionally lets you choose a specific browser
-3. Opens browser for OAuth authorization
-4. Automatically exchanges code for tokens
-5. Stores tokens in your chosen backend
+2. Optionally lets you choose a specific browser (or skips browser opening in production)
+3. Opens browser for OAuth authorization (or displays URL for manual access)
+4. Waits for you to paste the authorization code from the redirect URL
+5. Automatically exchanges code for tokens
+6. Stores tokens in your chosen backend
 
 **Note**: If no scopes are specified via environment variables or user input, the default scope `employee:all` will be used.
 
@@ -270,6 +296,22 @@ lightspeed-retail-sdk login --browser "google chrome"
 # The CLI will ask if you want to choose a specific browser
 ```
 
+**Production/Headless Environments:**
+
+```bash
+# Skip browser opening and display URL for manual access
+lightspeed-retail-sdk login --no-browser
+```
+
+This is useful when:
+
+- Running in Docker containers or cloud environments without GUI
+- SSH sessions without X11 forwarding
+- Automated deployment scripts
+- CI/CD pipelines
+
+The CLI will automatically detect headless environments and display the OAuth URL instead of trying to open a browser.
+
 #### Token Management
 
 ##### Manual Token Refresh
@@ -608,54 +650,119 @@ npx lightspeed-retail-sdk login
 Then in your code:
 
 ```javascript
-import LightspeedRetailSDK, {
-  FileTokenStorage,
-  EncryptedTokenStorage,
-} from "lightspeed-retail-sdk";
-import dotenv from "dotenv";
-dotenv.config();
-
-// Use the same storage configuration as your CLI
-const fileStorage = new FileTokenStorage(
-  process.env.LIGHTSPEED_TOKEN_FILE || "./tokens/encrypted-tokens.json"
-);
-const tokenStorage = process.env.LIGHTSPEED_ENCRYPTION_KEY
-  ? new EncryptedTokenStorage(
-      fileStorage,
-      process.env.LIGHTSPEED_ENCRYPTION_KEY
-    )
-  : fileStorage;
+import LightspeedRetailSDK from "lightspeed-retail-sdk";
 
+// After CLI setup, your code is this simple:
 const api = new LightspeedRetailSDK({
-  accountID: process.env.LIGHTSPEED_ACCOUNT_ID,
   clientID: process.env.LIGHTSPEED_CLIENT_ID,
   clientSecret: process.env.LIGHTSPEED_CLIENT_SECRET,
-  tokenStorage,
+  accountID: process.env.LIGHTSPEED_ACCOUNT_ID,
+  // Storage automatically discovered from CLI setup!
 });
 
-// The SDK will automatically use stored tokens and refresh as needed
+// The SDK automatically finds your tokens and refreshes them as needed
+const items = await api.getItems();
 export default api;
 ```
 
-### Basic Usage (In-Memory Storage)
+### Recommended Usage (Auto-Discovery)
+
+**Best for most users**: After one-time CLI setup, no configuration needed:
 
 ```javascript
 import LightspeedRetailSDK from "lightspeed-retail-sdk";
 
+// After running: npm run cli login (one time setup)
 const api = new LightspeedRetailSDK({
-  accountID: "Your Account No.",
-  clientID: "Your client ID.",
-  clientSecret: "Your client secret.",
-  refreshToken: "Your initial refresh token.",
-  // No tokenStorage = uses InMemoryTokenStorage by default
+  clientID: process.env.LIGHTSPEED_CLIENT_ID,
+  clientSecret: process.env.LIGHTSPEED_CLIENT_SECRET,
+  accountID: process.env.LIGHTSPEED_ACCOUNT_ID,
+  // No tokenStorage needed - automatically discovered!
 });
+
+// Works immediately, handles token refresh automatically
+const items = await api.getItems();
 ```
 
-⚠️ **Warning**: Basic usage stores tokens in memory only. Tokens will be lost on application restart, which may cause issues with Lightspeed's new token rotation system.
+### Explicit Storage (Advanced)
+
+For advanced use cases where you want to specify storage manually:
+
+```javascript
+import LightspeedRetailSDK, { 
+  FileTokenStorage, 
+  EncryptedTokenStorage 
+} from "lightspeed-retail-sdk";
+
+const fileStorage = new FileTokenStorage('./lightspeed-tokens.json');
+const tokenStorage = process.env.LIGHTSPEED_ENCRYPTION_KEY
+  ? new EncryptedTokenStorage(fileStorage, process.env.LIGHTSPEED_ENCRYPTION_KEY)
+  : fileStorage;
+
+const api = new LightspeedRetailSDK({
+  clientID: process.env.LIGHTSPEED_CLIENT_ID,
+  clientSecret: process.env.LIGHTSPEED_CLIENT_SECRET,
+  accountID: process.env.LIGHTSPEED_ACCOUNT_ID,
+  tokenStorage: tokenStorage, // Explicit storage choice
+});
+```
+
+✅ **Auto-Discovery**: The SDK automatically discovers your storage configuration after initial CLI setup. Perfect for cron jobs and automated scripts.
+
+✅ **Explicit Storage**: You can still explicitly provide tokenStorage for advanced use cases. Choose from FileTokenStorage, EncryptedTokenStorage (recommended), DatabaseTokenStorage, or InMemoryTokenStorage (not recommended).
+
+### Production & Cron Job Setup
+
+The auto-discovery system is perfect for production environments and automated scripts:
+
+1. **Initial Setup** (run once):
+
+   ```bash
+   # Interactive setup with storage selection
+   npm run cli login
+   
+   # Or for headless environments:
+   npm run cli login --no-browser
+   ```
+
+2. **Your Scripts Work Automatically**:
+   - Cron jobs find storage configuration automatically
+   - Token refresh happens seamlessly in background
+   - Storage migrations update all scripts automatically
+   - No configuration management needed
+
+3. **Environment Variables** (recommended):
+
+   ```bash
+   export LIGHTSPEED_CLIENT_ID="your-client-id"
+   export LIGHTSPEED_CLIENT_SECRET="your-client-secret"  
+   export LIGHTSPEED_ACCOUNT_ID="your-account-id"
+   ```
 
 ### Manual Token Management (Advanced)
 
-If you prefer to handle authentication manually without the CLI:
+If you prefer to handle authentication manually without the CLI, you have several options:
+
+#### Option 1: Interactive Token Injection (Easiest)
+
+Use the CLI to manually input tokens you've obtained from elsewhere:
+
+```bash
+# Interactive prompts for tokens and storage configuration
+lightspeed-retail-sdk inject-tokens
+
+# Or specify tokens via command line and use interactive prompts for storage
+lightspeed-retail-sdk inject-tokens --access "your_access_token" --refresh "your_refresh_token"
+```
+
+This method will:
+
+- Prompt you to enter access and refresh tokens
+- Let you choose expiry settings (default 1 hour, custom date, or seconds)
+- Allow you to select your storage backend (file, encrypted file, or database)
+- Store the tokens securely in your chosen backend
+
+#### Option 2: Programmatic Token Storage
 
 #### File-Based Storage
 

package/dist/src/bin/cli.js

@@ -5,7 +5,9 @@ import dotenv from "dotenv";
 import {
   FileTokenStorage,
   EncryptedTokenStorage,
+  DatabaseTokenStorage,
 } from "../storage/TokenStorage.mjs";
+import { StorageConfig } from "../storage/StorageConfig.mjs";
 import LightspeedRetailSDK from "../../index.mjs";
 import inquirer from "inquirer";
 import { createInterface } from "readline";
@@ -61,6 +63,10 @@ program
     "-b, --browser <browser>",
     "Specify browser to use (chrome, firefox, safari, edge, etc.)"
   )
+  .option(
+    "--no-browser",
+    "Skip browser opening and display URL for manual access (useful in production/headless environments)"
+  )
   .action(async (options) => {
     let storageBackend = null;
     try {
@@ -89,70 +95,83 @@ program
         clientID
       )}&scope=${encodeURIComponent(scopes)}`;
 
-      console.log("\nOpening browser for authentication...");
+      // Detect if we're in a headless/production environment
+      const isHeadless = !process.env.DISPLAY && !process.env.SSH_CLIENT && process.platform !== 'darwin' && process.platform !== 'win32';
+      const skipBrowser = options.noBrowser || isHeadless;
 
-      // Open browser with optional browser specification
-      const openOptions = {};
-      if (options.browser) {
-        openOptions.app = { name: options.browser };
-        console.log(`Using browser: ${options.browser}`);
+      if (skipBrowser) {
+        console.log("\n🔗 OAuth Authentication Required");
+        console.log("\nPlease open the following URL in your browser to authorize the application:");
+        console.log(`\n${authUrl}\n`);
+        console.log("After authorizing, you will be redirected to your configured redirect URI");
+        console.log("with an authorization code in the URL (e.g., ?code=abc123...)");
       } else {
-        // Ask user if they want to choose a specific browser
-        const { chooseBrowser } = await inquirer.prompt([
-          {
-            type: "confirm",
-            name: "chooseBrowser",
-            message: "Do you want to choose a specific browser?",
-            default: false,
-          },
-        ]);
+        console.log("\nOpening browser for authentication...");
 
-        if (chooseBrowser) {
-          const { browserChoice } = await inquirer.prompt([
+        // Open browser with optional browser specification
+        const openOptions = {};
+        if (options.browser) {
+          openOptions.app = { name: options.browser };
+          console.log(`Using browser: ${options.browser}`);
+        } else {
+          // Ask user if they want to choose a specific browser
+          const { chooseBrowser } = await inquirer.prompt([
             {
-              type: "list",
-              name: "browserChoice",
-              message: "Select browser:",
-              choices: [
-                { name: "Default browser", value: null },
-                { name: "Google Chrome", value: "google chrome" },
-                { name: "Firefox", value: "firefox" },
-                { name: "Safari", value: "safari" },
-                { name: "Microsoft Edge", value: "microsoft edge" },
-                { name: "Brave", value: "brave" },
-                { name: "Opera", value: "opera" },
-                { name: "Custom browser name", value: "custom" },
-              ],
+              type: "confirm",
+              name: "chooseBrowser",
+              message: "Do you want to choose a specific browser?",
+              default: false,
             },
           ]);
 
-          if (browserChoice === "custom") {
-            const { customBrowser } = await inquirer.prompt([
+          if (chooseBrowser) {
+            const { browserChoice } = await inquirer.prompt([
               {
-                type: "input",
-                name: "customBrowser",
-                message: "Enter browser name:",
-                validate: (input) =>
-                  input.trim() !== "" || "Browser name cannot be empty",
+                type: "list",
+                name: "browserChoice",
+                message: "Select browser:",
+                choices: [
+                  { name: "Default browser", value: null },
+                  { name: "Google Chrome", value: "google chrome" },
+                  { name: "Firefox", value: "firefox" },
+                  { name: "Safari", value: "safari" },
+                  { name: "Microsoft Edge", value: "microsoft edge" },
+                  { name: "Brave", value: "brave" },
+                  { name: "Opera", value: "opera" },
+                  { name: "Custom browser name", value: "custom" },
+                ],
               },
             ]);
-            openOptions.app = { name: customBrowser };
-            console.log(`Using browser: ${customBrowser}`);
-          } else if (browserChoice) {
-            openOptions.app = { name: browserChoice };
-            console.log(`Using browser: ${browserChoice}`);
+
+            if (browserChoice === "custom") {
+              const { customBrowser } = await inquirer.prompt([
+                {
+                  type: "input",
+                  name: "customBrowser",
+                  message: "Enter browser name:",
+                  validate: (input) =>
+                    input.trim() !== "" || "Browser name cannot be empty",
+                },
+              ]);
+              openOptions.app = { name: customBrowser };
+              console.log(`Using browser: ${customBrowser}`);
+            } else if (browserChoice) {
+              openOptions.app = { name: browserChoice };
+              console.log(`Using browser: ${browserChoice}`);
+            }
           }
         }
-      }
 
-      try {
-        await open(authUrl, openOptions);
-      } catch (err) {
-        console.log(
-          `\n⚠️  Could not open browser automatically: ${err.message}`
-        );
-        console.log(`\nPlease manually open this URL in your browser:`);
-        console.log(authUrl);
+        try {
+          await open(authUrl, openOptions);
+          console.log(`\nIf the browser didn't open, manually visit: ${authUrl}`);
+        } catch (err) {
+          console.log(
+            `\n⚠️  Could not open browser automatically: ${err.message}`
+          );
+          console.log(`\nPlease manually open this URL in your browser:`);
+          console.log(`\n${authUrl}\n`);
+        }
       }
 
       // 3. Prompt for code
@@ -180,7 +199,7 @@ program
         ).toISOString();
 
         // 5. Store tokens using storage backend
-        storageBackend = await selectStorageBackend();
+        storageBackend = await selectStorageBackend(); // Save config for initial setup
         await storageBackend.setTokens({
           access_token: tokenData.access_token,
           refresh_token: tokenData.refresh_token,
@@ -211,7 +230,7 @@ program
   .action(async () => {
     let storageBackend = null;
     try {
-      storageBackend = await selectStorageBackend();
+      storageBackend = await selectStorageBackend(false); // Read-only, don't save config
       const tokens = await storageBackend.getTokens();
       if (!tokens || !tokens.access_token) {
         console.log("\n⚠️  No tokens found in storage.");
@@ -422,6 +441,153 @@ program
     }
   });
 
+program
+  .command("inject-tokens")
+  .description("Manually store an access & refresh token in chosen backend")
+  .option("--access <accessToken>", "Access token (skip interactive prompt)")
+  .option("--refresh <refreshToken>", "Refresh token (skip interactive prompt)")
+  .option(
+    "--expires-at <isoDatetime>",
+    "ISO8601 expiry (e.g. 2025-01-01T12:34:56.000Z). Overrides --expires-in."
+  )
+  .option(
+    "--expires-in <seconds>",
+    "Seconds until expiry (default 3600 if neither --expires-at nor --expires-in provided)"
+  )
+  .action(async (opts) => {
+    let storageBackend = null;
+    try {
+      console.log("\n🔑 Manual Token Injection\n");
+      console.log("This command allows you to manually store access and refresh tokens");
+      console.log("that you've obtained through other means (e.g., Lightspeed dashboard).\n");
+
+      // Get tokens either from command line options or interactive prompts
+      let accessToken = opts.access;
+      let refreshToken = opts.refresh;
+
+      if (!accessToken) {
+        accessToken = await prompt("Enter your access token: ");
+        if (!accessToken || accessToken.trim() === "") {
+          console.error("❌ Access token is required");
+          process.exit(1);
+        }
+        accessToken = accessToken.trim();
+      }
+
+      if (!refreshToken) {
+        refreshToken = await prompt("Enter your refresh token: ");
+        if (!refreshToken || refreshToken.trim() === "") {
+          console.error("❌ Refresh token is required");
+          process.exit(1);
+        }
+        refreshToken = refreshToken.trim();
+      }
+
+      // Get expiry information
+      let expiresAt;
+      if (opts.expiresAt) {
+        const d = new Date(opts.expiresAt);
+        if (isNaN(d.getTime())) {
+          console.error("❌ Invalid --expires-at value");
+          process.exit(1);
+        }
+        expiresAt = d.toISOString();
+      } else if (opts.expiresIn) {
+        const seconds = parseInt(opts.expiresIn, 10);
+        if (isNaN(seconds) || seconds <= 0) {
+          console.error("❌ Invalid --expires-in value");
+          process.exit(1);
+        }
+        expiresAt = new Date(Date.now() + seconds * 1000).toISOString();
+      } else {
+        // Interactive prompt for expiry
+        const expiryChoice = await inquirer.prompt([
+          {
+            type: "list",
+            name: "expiryMethod",
+            message: "How would you like to set the token expiry?",
+            choices: [
+              { name: "Default (1 hour from now)", value: "default" },
+              { name: "Specific date/time (ISO format)", value: "datetime" },
+              { name: "Seconds from now", value: "seconds" },
+            ],
+            default: "default",
+          },
+        ]);
+
+        switch (expiryChoice.expiryMethod) {
+          case "default":
+            expiresAt = new Date(Date.now() + 3600 * 1000).toISOString();
+            break;
+          case "datetime":
+            const { customDateTime } = await inquirer.prompt([
+              {
+                type: "input",
+                name: "customDateTime",
+                message: "Enter expiry date/time (ISO format, e.g., 2025-01-01T12:34:56.000Z):",
+                validate: (input) => {
+                  const d = new Date(input);
+                  return !isNaN(d.getTime()) || "Please enter a valid ISO datetime";
+                },
+              },
+            ]);
+            expiresAt = new Date(customDateTime).toISOString();
+            break;
+          case "seconds":
+            const { customSeconds } = await inquirer.prompt([
+              {
+                type: "input",
+                name: "customSeconds",
+                message: "Enter seconds until expiry:",
+                default: "3600",
+                validate: (input) => {
+                  const num = parseInt(input, 10);
+                  return (!isNaN(num) && num > 0) || "Please enter a positive number";
+                },
+              },
+            ]);
+            expiresAt = new Date(Date.now() + parseInt(customSeconds, 10) * 1000).toISOString();
+            break;
+        }
+      }
+
+      console.log("\n📁 Token Storage Configuration");
+      storageBackend = await selectStorageBackend(); // Save config for inject-tokens setup
+
+      // Validate tokens format (basic check)
+      if (accessToken.length < 10) {
+        console.warn("⚠️  Warning: Access token seems unusually short");
+      }
+      if (refreshToken.length < 10) {
+        console.warn("⚠️  Warning: Refresh token seems unusually short");
+      }
+
+      await storageBackend.setTokens({
+        access_token: accessToken,
+        refresh_token: refreshToken,
+        expires_at: expiresAt,
+        expires_in: Math.floor((new Date(expiresAt) - new Date()) / 1000),
+      });
+
+      console.log("\n✅ Tokens injected successfully!");
+      console.log("📋 Token Details:");
+      console.log(`   Access Token: ${accessToken.substring(0, 20)}...`);
+      console.log(`   Refresh Token: ${refreshToken.substring(0, 20)}...`);
+      console.log(`   Expires At: ${expiresAt}`);
+      
+      const minutesUntilExpiry = Math.floor((new Date(expiresAt) - new Date()) / 60000);
+      console.log(`   Time Until Expiry: ${minutesUntilExpiry} minutes`);
+
+      console.log("\n💡 You can now use the SDK with these tokens.");
+      console.log("   Test with: npm run cli whoami");
+    } catch (err) {
+      console.error("❌ Failed to inject tokens:", err.message);
+      process.exit(1);
+    } finally {
+      await cleanupStorageBackend(storageBackend);
+    }
+  });
+
 program
   .command("migrate-tokens")
   .description(
@@ -435,7 +601,7 @@ program
       console.log("\n🔄 Token Storage Migration Wizard\n");
       // Prompt for source backend
       console.log("Select SOURCE storage backend:");
-      sourceBackend = await selectStorageBackend();
+      sourceBackend = await selectStorageBackend(false); // Don't save config for source
       const sourceTokens = await sourceBackend.getTokens();
       if (!sourceTokens || !sourceTokens.access_token) {
         console.error("\n❌ No tokens found in source storage. Aborting.");
@@ -446,7 +612,7 @@ program
 
       // Prompt for destination backend
       console.log("\nSelect DESTINATION storage backend:");
-      destBackend = await selectStorageBackend();
+      destBackend = await selectStorageBackend(false); // Don't save config yet - will save after successful migration
 
       // Attempt to create table/collection/file if it doesn't exist (best effort)
       switch (destBackend.constructor.name) {
@@ -562,6 +728,16 @@ program
       }
       await destBackend.setTokens(sourceTokens);
       console.log("\n🎉 Tokens migrated successfully!");
+      
+      // Update storage configuration to point to the new destination
+      try {
+        const storageConfig = new StorageConfig();
+        const config = await getStorageConfig(destBackend);
+        await storageConfig.saveConfig(config);
+        console.log("✅ Storage configuration updated for auto-discovery");
+      } catch (configError) {
+        console.warn(`Warning: Could not update storage config: ${configError.message}`);
+      }
     } catch (error) {
       console.error("\n❌ Migration failed:", error.message);
     } finally {
@@ -577,7 +753,7 @@ program
   .action(async () => {
     let storageBackend = null;
     try {
-      storageBackend = await selectStorageBackend();
+      storageBackend = await selectStorageBackend(false); // Read-only, don't save config
       const tokens = await storageBackend.getTokens();
       if (!tokens || !tokens.access_token) {
         console.log("\n⚠️  No tokens found in storage. Please login first.");
@@ -881,7 +1057,70 @@ async function sendTestTokenRefreshFailureEmail(error, accountID) {
   }
 }
 
-async function selectStorageBackend() {
+/**
+ * Extract configuration from a storage instance for saving
+ * @param {TokenStorage} storage - Storage instance
+ * @returns {Object} Configuration object
+ */
+async function getStorageConfig(storage) {
+  // Handle EncryptedTokenStorage wrapper
+  if (storage.adapter) {
+    const innerConfig = await getStorageConfig(storage.adapter);
+    return {
+      type: innerConfig.type === "file" ? "encrypted-file" : "database",
+      settings: {
+        ...innerConfig.settings,
+        encrypted: true,
+        encryptionKey: process.env.LIGHTSPEED_ENCRYPTION_KEY || "[provided]"
+      }
+    };
+  }
+  
+  // Handle FileTokenStorage
+  if (storage.filePath) {
+    return {
+      type: "file",
+      settings: {
+        filePath: storage.filePath
+      }
+    };
+  }
+  
+  // Handle DatabaseTokenStorage
+  if (storage.dbConnectionString) {
+    return {
+      type: "database",
+      settings: {
+        connectionString: storage.dbConnectionString,
+        dbType: storage.dbType,
+        tableName: storage.tableName,
+        appId: storage.appId
+      }
+    };
+  }
+  
+  throw new Error("Unknown storage type for configuration");
+}
+
+async function selectStorageBackend(saveConfig = true) {
+  const storageConfig = new StorageConfig();
+  const storage = await selectStorageBackendInternal();
+  
+  // Save configuration for auto-discovery if requested
+  if (saveConfig) {
+    try {
+      const config = await getStorageConfig(storage);
+      await storageConfig.saveConfig(config);
+      console.log("✅ Storage configuration saved for auto-discovery");
+    } catch (error) {
+      console.warn(`Warning: Could not save storage config: ${error.message}`);
+    }
+  }
+  
+  return storage;
+}
+
+async function selectStorageBackendInternal() {
   const { storageType } = await inquirer.prompt([
     {
       type: "list",
@@ -984,10 +1223,6 @@ async function selectStorageBackend() {
       default:
         throw new Error("Unsupported database type");
     }
-    // Dynamically import DatabaseTokenStorage
-    const { DatabaseTokenStorage } = await import(
-      "../storage/TokenStorage.mjs"
-    );
     const dbStorage = new DatabaseTokenStorage(dbConnectionString, {
       dbType,
       tableName,
@@ -1075,7 +1310,7 @@ program
       console.log("🔄 Refreshing stored access token...\n");
 
       // Get storage backend
-      storageBackend = await selectStorageBackend();
+      storageBackend = await selectStorageBackend(false); // Read-only, don't save config
 
       // Get existing tokens
       const tokens = await storageBackend.getTokens();

package/dist/src/core/LightspeedSDK.cjs

@@ -187,6 +187,27 @@ async function sendTokenRefreshFailureEmail(error, accountID) {
     }
 }
 class LightspeedSDKCore {
+    /**
+   * Initialize token storage through auto-discovery if not explicitly provided
+   * @private
+   */ async _initializeStorage() {
+        if (this._storageInitialized) {
+            return;
+        }
+        if (!this.tokenStorage) {
+            try {
+                const { autoDiscoverStorage } = await Promise.resolve().then(()=>/*#__PURE__*/ _interop_require_wildcard(require("../storage/StorageConfig.cjs")));
+                this.tokenStorage = await autoDiscoverStorage();
+                if (!this.tokenStorage) {
+                    throw new Error("No token storage found. Please either:\n" + "• Run the CLI to set up storage: npm run cli login\n" + "• Or explicitly provide tokenStorage:\n" + "  - FileTokenStorage('./tokens.json')\n" + "  - EncryptedTokenStorage(fileStorage, key) [recommended]\n" + "  - DatabaseTokenStorage(connection, options)\n" + "  - InMemoryTokenStorage() [NOT RECOMMENDED]\n\n" + "See documentation: https://github.com/darrylmorley/lightspeed-retail-sdk#token-storage");
+                }
+            } catch (error) {
+                // If auto-discovery fails, throw helpful error
+                throw new Error("Failed to auto-discover token storage. " + error.message);
+            }
+        }
+        this._storageInitialized = true;
+    }
     // Core error handling
     handleError(context, err, shouldThrow = true) {
         const errorMessage = (err === null || err === void 0 ? void 0 : err.message) || "Unknown error occurred";
@@ -206,6 +227,8 @@ class LightspeedSDKCore {
     }
     // Token management
     async getToken() {
+        // Ensure storage is initialized
+        await this._initializeStorage();
         const now = new Date();
         const bufferTime = 5 * 60 * 1000; // 5-minute buffer
         const storedTokens = await this.tokenStorage.getTokens();
@@ -479,6 +502,8 @@ class LightspeedSDKCore {
         }
     }
     async getTokenInfo() {
+        // Ensure storage is initialized
+        await this._initializeStorage();
         const storedTokens = await this.tokenStorage.getTokens();
         return {
             hasAccessToken: !!storedTokens.access_token,
@@ -526,8 +551,14 @@ class LightspeedSDKCore {
         this.token = null;
         this.tokenExpiry = null;
         this.refreshInProgress = false;
-        // Token storage interface - defaults to in-memory if not provided
-        this.tokenStorage = tokenStorage || new InMemoryTokenStorage();
+        // Token storage interface - can be explicitly provided or auto-discovered
+        if (tokenStorage) {
+            this.tokenStorage = tokenStorage;
+        } else {
+            // Auto-discovery will be handled by async initialization
+            this.tokenStorage = null;
+            this._storageInitialized = false;
+        }
     }
 }
 _define_property(LightspeedSDKCore, "BASE_URL", "https://api.lightspeedapp.com/API/V3/Account");

package/dist/src/core/LightspeedSDK.mjs

@@ -146,8 +146,51 @@ export class LightspeedSDKCore {
     this.tokenExpiry = null;
     this.refreshInProgress = false;
 
-    // Token storage interface - defaults to in-memory if not provided
-    this.tokenStorage = tokenStorage || new InMemoryTokenStorage();
+    // Token storage interface - can be explicitly provided or auto-discovered
+    if (tokenStorage) {
+      this.tokenStorage = tokenStorage;
+    } else {
+      // Auto-discovery will be handled by async initialization
+      this.tokenStorage = null;
+      this._storageInitialized = false;
+    }
+  }
+
+  /**
+   * Initialize token storage through auto-discovery if not explicitly provided
+   * @private
+   */
+  async _initializeStorage() {
+    if (this._storageInitialized) {
+      return;
+    }
+
+    if (!this.tokenStorage) {
+      try {
+        const { autoDiscoverStorage } = await import("../storage/StorageConfig.mjs");
+        this.tokenStorage = await autoDiscoverStorage();
+        
+        if (!this.tokenStorage) {
+          throw new Error(
+            "No token storage found. Please either:\n" +
+            "• Run the CLI to set up storage: npm run cli login\n" +
+            "• Or explicitly provide tokenStorage:\n" +
+            "  - FileTokenStorage('./tokens.json')\n" + 
+            "  - EncryptedTokenStorage(fileStorage, key) [recommended]\n" +
+            "  - DatabaseTokenStorage(connection, options)\n" +
+            "  - InMemoryTokenStorage() [NOT RECOMMENDED]\n\n" +
+            "See documentation: https://github.com/darrylmorley/lightspeed-retail-sdk#token-storage"
+          );
+        }
+      } catch (error) {
+        // If auto-discovery fails, throw helpful error
+        throw new Error(
+          "Failed to auto-discover token storage. " + error.message
+        );
+      }
+    }
+
+    this._storageInitialized = true;
   }
 
   // Core error handling
@@ -216,6 +259,9 @@ export class LightspeedSDKCore {
 
   // Token management
   async getToken() {
+    // Ensure storage is initialized
+    await this._initializeStorage();
+    
     const now = new Date();
     const bufferTime = 5 * 60 * 1000; // 5-minute buffer
 
@@ -536,6 +582,9 @@ export class LightspeedSDKCore {
   }
 
   async getTokenInfo() {
+    // Ensure storage is initialized
+    await this._initializeStorage();
+    
     const storedTokens = await this.tokenStorage.getTokens();
     return {
       hasAccessToken: !!storedTokens.access_token,

package/dist/src/storage/StorageConfig.mjs

@@ -0,0 +1,175 @@
+import { promises as fs } from "fs";
+import path from "path";
+
+/**
+ * Storage configuration manager that tracks which storage type and settings
+ * are being used, enabling automatic storage discovery.
+ */
+export class StorageConfig {
+  constructor(configPath = ".lightspeed-storage-config.json") {
+    this.configPath = path.resolve(configPath);
+  }
+
+  /**
+   * Save storage configuration for future auto-discovery
+   * @param {Object} config - Storage configuration
+   * @param {string} config.type - Storage type: 'file', 'encrypted-file', 'database'
+   * @param {Object} config.settings - Storage-specific settings
+   */
+  async saveConfig(config) {
+    try {
+      const configData = {
+        type: config.type,
+        settings: config.settings,
+        lastUpdated: new Date().toISOString(),
+        version: "1.0"
+      };
+
+      await fs.writeFile(
+        this.configPath,
+        JSON.stringify(configData, null, 2),
+        "utf8"
+      );
+    } catch (error) {
+      console.warn(`Warning: Could not save storage config: ${error.message}`);
+    }
+  }
+
+  /**
+   * Load existing storage configuration
+   * @returns {Object|null} Configuration object or null if not found
+   */
+  async loadConfig() {
+    try {
+      const data = await fs.readFile(this.configPath, "utf8");
+      return JSON.parse(data);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return null; // Config file doesn't exist
+      }
+      console.warn(`Warning: Could not load storage config: ${error.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Check if storage configuration exists
+   * @returns {boolean}
+   */
+  async hasConfig() {
+    try {
+      await fs.access(this.configPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Remove storage configuration
+   */
+  async removeConfig() {
+    try {
+      await fs.unlink(this.configPath);
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        console.warn(`Warning: Could not remove storage config: ${error.message}`);
+      }
+    }
+  }
+}
+
+/**
+ * Create a token storage instance based on saved configuration
+ * @param {Object} config - Storage configuration from StorageConfig
+ * @returns {TokenStorage} Configured storage instance
+ */
+export async function createStorageFromConfig(config) {
+  const { 
+    FileTokenStorage, 
+    EncryptedTokenStorage, 
+    DatabaseTokenStorage 
+  } = await import("./TokenStorage.mjs");
+
+  switch (config.type) {
+    case "file": {
+      return new FileTokenStorage(config.settings.filePath);
+    }
+
+    case "encrypted-file": {
+      const fileStorage = new FileTokenStorage(config.settings.filePath);
+      return new EncryptedTokenStorage(fileStorage, config.settings.encryptionKey);
+    }
+
+    case "database": {
+      const dbStorage = new DatabaseTokenStorage(
+        config.settings.connectionString,
+        {
+          dbType: config.settings.dbType,
+          tableName: config.settings.tableName,
+          appId: config.settings.appId
+        }
+      );
+      
+      if (config.settings.encrypted) {
+        return new EncryptedTokenStorage(dbStorage, config.settings.encryptionKey);
+      }
+      
+      return dbStorage;
+    }
+
+    default:
+      throw new Error(`Unknown storage type: ${config.type}`);
+  }
+}
+
+/**
+ * Auto-discover and create the appropriate token storage based on
+ * previously saved configuration, environment variables, or defaults.
+ * @param {string} configPath - Optional path to config file
+ * @returns {TokenStorage|null} Storage instance or null if none found
+ */
+export async function autoDiscoverStorage(configPath) {
+  const storageConfig = new StorageConfig(configPath);
+  
+  // Try to load saved configuration first
+  const config = await storageConfig.loadConfig();
+  if (config) {
+    try {
+      return await createStorageFromConfig(config);
+    } catch (error) {
+      console.warn(`Warning: Could not create storage from saved config: ${error.message}`);
+    }
+  }
+
+  // Fallback: Check for environment variables for common setups
+  if (process.env.LIGHTSPEED_TOKEN_FILE) {
+    const { FileTokenStorage, EncryptedTokenStorage } = await import("./TokenStorage.mjs");
+    const fileStorage = new FileTokenStorage(process.env.LIGHTSPEED_TOKEN_FILE);
+    
+    if (process.env.LIGHTSPEED_ENCRYPTION_KEY) {
+      return new EncryptedTokenStorage(fileStorage, process.env.LIGHTSPEED_ENCRYPTION_KEY);
+    }
+    
+    return fileStorage;
+  }
+
+  // Check for default token file locations
+  const defaultPaths = [
+    ".lightspeed-tokens.json",
+    "./tokens/encrypted-tokens.json",
+    "./lightspeed-tokens.json"
+  ];
+
+  for (const defaultPath of defaultPaths) {
+    try {
+      await fs.access(defaultPath);
+      const { FileTokenStorage } = await import("./TokenStorage.mjs");
+      return new FileTokenStorage(defaultPath);
+    } catch {
+      // File doesn't exist, continue to next
+    }
+  }
+
+  return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightspeed-retail-sdk",
-  "version": "3.3.5",
+  "version": "3.4.1",
   "description": "Another unofficial Lightspeed Retail API SDK for Node.js",
   "type": "module",
   "main": "dist/index.cjs",