lightspeed-retail-sdk 3.3.5 → 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.5** — 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.5)**
+## **🆕 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
@@ -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/package.json

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