lightspeed-retail-sdk 3.3.4 → 3.4.0

package/README.md

@@ -2,9 +2,16 @@
 
 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.4** — improve error checking on token refresh to prevent false email warnings.
+**Current Version: 3.4.0** — Enhanced CLI with interactive token injection and production environment support.
 
-## **🆕 Recent Updates (v3.3.4)**
+## **🆕 Recent Updates (v3.4.0)**
+
+- **🔧 Enhanced Token Injection**: Interactive `inject-tokens` command with prompts for access/refresh tokens, expiry settings, and storage backend selection
+- **🏭 Production Environment Support**: Login command now supports headless environments with `--no-browser` option and automatic detection
+- **💡 Improved CLI UX**: Better error messages, token validation, and clear instructions for manual OAuth flows
+- **📖 Enhanced Documentation**: Updated README and CLI help with production deployment guidance
+
+## **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
@@ -66,7 +73,7 @@ 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.4)**](#-recent-updates-v334)
+  - [**🆕 Recent Updates (v3.3.5)**](#-recent-updates-v335)
   - [🚀 Key Features](#-key-features)
   - [🔄 Migrating from 3.1.x](#-migrating-from-31x)
     - [Backward Compatibility](#backward-compatibility)
@@ -107,6 +114,8 @@ const items = await sdk.getItems({
       - [Alternative: Local Installation](#alternative-local-installation)
     - [Basic Usage (In-Memory Storage)](#basic-usage-in-memory-storage)
     - [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 +206,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 +217,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 +267,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 +289,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
@@ -655,7 +690,28 @@ const api = new LightspeedRetailSDK({
 
 ### 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

@@ -61,6 +61,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 +93,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
@@ -422,6 +439,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();
+
+      // 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(

package/dist/src/core/LightspeedSDK.cjs

@@ -291,6 +291,81 @@ class LightspeedSDKCore {
             this.refreshInProgress = false; // Release the lock
         }
     }
+    // Core API request handler
+    async executeApiRequest(options, retries = 0) {
+        await this.handleRateLimit(options);
+        const token = await this.getToken();
+        if (!token) throw new Error("Error Fetching Token");
+        options.headers = {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+            ...options.headers
+        };
+        // Centralized query param handling
+        if (options.params) {
+            const queryString = buildQueryParams(options.params);
+            if (queryString) {
+                // Remove any trailing ? or & from url
+                options.url = options.url.replace(/[?&]+$/, "");
+                options.url += (options.url.includes("?") ? "&" : "?") + queryString;
+            }
+            delete options.params; // Don't let axios try to re-encode
+        }
+        try {
+            const res = await (0, _axios.default)(options);
+            this.lastResponse = res;
+            if (options.method === "GET") {
+                var _res_data_attributes, _res_data_attributes1;
+                // Handle successful response with no data or empty data
+                if (!res.data || Object.keys(res.data).length === 0) {
+                    return {
+                        data: {},
+                        next: null,
+                        previous: null
+                    };
+                }
+                // Check if response has the expected structure but with empty arrays
+                const dataKeys = Object.keys(res.data).filter((key)=>key !== "@attributes");
+                if (dataKeys.length > 0) {
+                    const firstDataKey = dataKeys[0];
+                    const firstDataValue = res.data[firstDataKey];
+                // No need to log for empty arrays - this is normal
+                }
+                // Handle successful response with data
+                return {
+                    data: res.data,
+                    next: (_res_data_attributes = res.data["@attributes"]) === null || _res_data_attributes === void 0 ? void 0 : _res_data_attributes.next,
+                    previous: (_res_data_attributes1 = res.data["@attributes"]) === null || _res_data_attributes1 === void 0 ? void 0 : _res_data_attributes1.prev
+                };
+            } else {
+                return res.data;
+            }
+        } catch (err) {
+            var _err_response;
+            // Handle 401 auth errors with automatic retry
+            if (((_err_response = err.response) === null || _err_response === void 0 ? void 0 : _err_response.status) === 401 && !options._authRetryAttempted) {
+                console.log("🔄 401 error - forcing token refresh and retrying...");
+                options._authRetryAttempted = true;
+                this.token = null;
+                try {
+                    await this.refreshTokens();
+                    return this.executeApiRequest(options, retries);
+                } catch (refreshError) {
+                    console.error("Failed to refresh tokens:", refreshError.message);
+                    throw refreshError;
+                }
+            }
+            // Handle retryable errors
+            if (this.isRetryableError(err) && retries < this.maxRetries) {
+                this.handleError(`Network Error Retrying in 2 seconds...`, err.message, false);
+                await sleep(2000);
+                return this.executeApiRequest(options, retries + 1);
+            } else {
+                // Simple error handling - let the calling method decide how to handle it
+                throw err;
+            }
+        }
+    }
     // Paginated data fetching
     async getAllData(options) {
         var _options_params;

package/dist/src/core/LightspeedSDK.mjs

@@ -320,6 +320,97 @@ export class LightspeedSDKCore {
     }
   }
 
+  // Core API request handler
+  async executeApiRequest(options, retries = 0) {
+    await this.handleRateLimit(options);
+
+    const token = await this.getToken();
+    if (!token) throw new Error("Error Fetching Token");
+
+    options.headers = {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+      ...options.headers,
+    };
+
+    // Centralized query param handling
+    if (options.params) {
+      const queryString = buildQueryParams(options.params);
+      if (queryString) {
+        // Remove any trailing ? or & from url
+        options.url = options.url.replace(/[?&]+$/, "");
+        options.url += (options.url.includes("?") ? "&" : "?") + queryString;
+      }
+      delete options.params; // Don't let axios try to re-encode
+    }
+
+    try {
+      const res = await axios(options);
+      this.lastResponse = res;
+
+      if (options.method === "GET") {
+        // Handle successful response with no data or empty data
+        if (!res.data || Object.keys(res.data).length === 0) {
+          return {
+            data: {},
+            next: null,
+            previous: null,
+          };
+        }
+
+        // Check if response has the expected structure but with empty arrays
+        const dataKeys = Object.keys(res.data).filter(
+          (key) => key !== "@attributes"
+        );
+        if (dataKeys.length > 0) {
+          const firstDataKey = dataKeys[0];
+          const firstDataValue = res.data[firstDataKey];
+
+          // No need to log for empty arrays - this is normal
+        }
+
+        // Handle successful response with data
+        return {
+          data: res.data,
+          next: res.data["@attributes"]?.next,
+          previous: res.data["@attributes"]?.prev,
+        };
+      } else {
+        return res.data;
+      }
+    } catch (err) {
+      // Handle 401 auth errors with automatic retry
+      if (err.response?.status === 401 && !options._authRetryAttempted) {
+        console.log("🔄 401 error - forcing token refresh and retrying...");
+
+        options._authRetryAttempted = true;
+        this.token = null;
+
+        try {
+          await this.refreshTokens();
+          return this.executeApiRequest(options, retries);
+        } catch (refreshError) {
+          console.error("Failed to refresh tokens:", refreshError.message);
+          throw refreshError;
+        }
+      }
+
+      // Handle retryable errors
+      if (this.isRetryableError(err) && retries < this.maxRetries) {
+        this.handleError(
+          `Network Error Retrying in 2 seconds...`,
+          err.message,
+          false
+        );
+        await sleep(2000);
+        return this.executeApiRequest(options, retries + 1);
+      } else {
+        // Simple error handling - let the calling method decide how to handle it
+        throw err;
+      }
+    }
+  }
+
   // Paginated data fetching
   async getAllData(options) {
     let allData = [];

package/package.json

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