lightspeed-retail-sdk 2.0.13 → 3.0.0

package/README.md

@@ -2,18 +2,65 @@
 
 A JavaScript SDK for interacting with the Lightspeed Retail API. This SDK provides a convenient way to access Lightspeed Retail's functionalities, including customer, item, order management, and more.
 
-## Update
+**Current Version: 3.0.0** - Updated with new OAuth system support and enhanced token management.
 
-- This package has been enhanced to support both CommonJS and module usage. I have also added methods for fetching both a gift card, and all gift cards.
-- I've added PUT and POST methods to many of the domains now.
+## 🚨 Important Update - New OAuth System
+
+**Lightspeed has implemented a new OAuth authorization server.** This SDK has been updated to support the new endpoints and token rotation system.
+
+### Key Changes
+
+- **New OAuth endpoints** - Updated to use `https://cloud.lightspeedapp.com/auth/oauth/token`
+- **Token rotation** - Both access and refresh tokens now change with each refresh
+- **Token persistence** - Tokens must be stored between application restarts
+- **Longer token values** - Ensure your storage can handle the new token lengths
 
 ## Features
 
 - Easy-to-use methods for interacting with various Lightspeed Retail endpoints.
 - Built-in handling of API rate limits.
 - Automatic token management for authentication.
+- **NEW: Auto-retry on authentication errors** - Automatically refreshes tokens and retries failed requests.
 - Support for paginated responses from the Lightspeed API.
 - Retry logic for handling transient network issues.
+- **NEW: Flexible token storage** - File-based, database, or custom storage options.
+- **NEW: Advanced search capabilities** - Search items and customers with flexible queries.
+- **NEW: Bulk operations** - Update multiple items efficiently.
+- **NEW: Inventory management** - Low stock alerts and category-based queries.
+- Support for both CommonJS and ES modules.
+
+## Smart Token Management
+
+The SDK intelligently manages tokens with these features:
+
+- **Automatic refresh** - Tokens are refreshed before they expire (1-minute buffer)
+- **Auto-retry on 401 errors** - If a token is invalid, the SDK automatically refreshes and retries the request
+- **Persistent storage priority** - Always checks stored tokens first, falls back to environment variables
+- **Token rotation support** - Handles Lightspeed's new token rotation system seamlessly
+
+### Token Priority Order
+
+1. **Stored tokens** (from your chosen storage method)
+2. **Environment variables** (fallback)
+3. **Automatic refresh** (when expired)
+
+## Environment Variables
+
+For development and testing, you can use environment variables:
+
+```bash
+# Required
+LIGHTSPEED_ACCOUNT_ID=your_account_id
+LIGHTSPEED_CLIENT_ID=your_client_id
+LIGHTSPEED_CLIENT_SECRET=your_client_secret
+
+# Optional (for initial setup)
+LIGHTSPEED_ACCESS_TOKEN=your_access_token
+LIGHTSPEED_REFRESH_TOKEN=your_refresh_token
+LIGHTSPEED_TOKEN_EXPIRES_AT=2025-01-01T00:00:00.000Z
+```
+
+⚠️ **Note**: Environment variables are used as fallback when no stored tokens are found. Once tokens are stored via your chosen storage method, those take priority.
 
 ## Installation
 
@@ -21,61 +68,292 @@ A JavaScript SDK for interacting with the Lightspeed Retail API. This SDK provid
 npm install lightspeed-retail-sdk
 ```
 
-## Get started:
+## Quick Start
 
-```
+### Basic Usage (In-Memory Storage)
+
+```javascript
 import LightspeedRetailSDK from "lightspeed-retail-sdk";
 
 const api = new LightspeedRetailSDK({
   accountID: "Your Account No.",
   clientID: "Your client ID.",
   clientSecret: "Your client secret.",
-  refreshToken: "Your refresh token.",
+  refreshToken: "Your initial refresh token.",
+  // No tokenStorage = uses InMemoryTokenStorage by default
+});
+```
+
+⚠️ **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.
+
+### Recommended Usage (Persistent Storage)
+
+#### File-Based Storage
+
+```javascript
+import LightspeedRetailSDK, { FileTokenStorage } from "lightspeed-retail-sdk";
+
+const api = new LightspeedRetailSDK({
+  accountID: "Your Account No.",
+  clientID: "Your client ID.",
+  clientSecret: "Your client secret.",
+  refreshToken: "Your initial refresh token.",
+  tokenStorage: new FileTokenStorage("./lightspeed-tokens.json"),
 });
 
-export default api
+export default api;
 ```
 
-## Example Request
+#### Custom Storage (Database Example)
+
+```javascript
+import LightspeedRetailSDK from "lightspeed-retail-sdk";
+
+class DatabaseTokenStorage {
+  constructor(userId) {
+    this.userId = userId;
+  }
+
+  async getTokens() {
+    const user = await db.users.findById(this.userId);
+    return {
+      access_token: user.lightspeed_access_token,
+      refresh_token: user.lightspeed_refresh_token,
+      expires_at: user.lightspeed_token_expires_at,
+    };
+  }
 
+  async setTokens(tokens) {
+    await db.users.update(this.userId, {
+      lightspeed_access_token: tokens.access_token,
+      lightspeed_refresh_token: tokens.refresh_token,
+      lightspeed_token_expires_at: tokens.expires_at,
+    });
+  }
+}
+
+const api = new LightspeedRetailSDK({
+  accountID: "Your Account No.",
+  clientID: "Your client ID.",
+  clientSecret: "Your client secret.",
+  refreshToken: "Your initial refresh token.",
+  tokenStorage: new DatabaseTokenStorage(userId),
+});
 ```
+
+## Example Requests
+
+```javascript
+// Basic item request
 const item = await api.getItem(7947, '["Category", "Images"]');
 console.log(item);
 
-7497 being the itemID. You can pass required relations as above.
+// Get all items
+const allItems = await api.getItems();
+
+// Get limited number of items
+const firstTenItems = await api.getItems(null, 10);
+
+// Search for items
+const searchResults = await api.searchItems("iPhone", '["Category"]');
+
+// Get low stock items
+const lowStockItems = await api.getItemsWithLowStock(10, '["Category"]');
+
+// Bulk update items
+const updates = [
+  { itemID: 123, data: { description: "Updated description" } },
+  { itemID: 456, data: { qoh: 50 } },
+];
+const results = await api.updateMultipleItems(updates);
+
+// Check API connection
+const status = await api.ping();
+console.log(status);
+
+// Check API connection
+const status = await api.ping();
+console.log(status);
+```
+
+## Token Storage Options
+
+### Built-in Storage Classes
+
+1. **InMemoryTokenStorage** (default) - Stores tokens in memory only
+2. **FileTokenStorage** - Stores tokens in a JSON file
+
+### Custom Storage Interface
+
+Implement your own storage by creating a class with these methods:
+
+```javascript
+class CustomTokenStorage {
+  async getTokens() {
+    // Return an object with: { access_token, refresh_token, expires_at }
+  }
+
+  async setTokens(tokens) {
+    // Store the tokens object: { access_token, refresh_token, expires_at, expires_in }
+  }
+}
+```
+
+## Migration from Previous Versions
+
+If you're upgrading from a previous version:
+
+1. **Update your refresh token** by making one call to the new OAuth endpoint
+2. **Implement token storage** to persist the rotating tokens
+3. **Update token URLs** (handled automatically by the SDK)
+4. **Ensure storage can handle longer tokens** (new tokens are significantly longer)
+
+## API Methods
+
+### Core Resources
+
+#### Customers
+
+- `getCustomer(id, relations)` - Fetch a specific customer by ID
+- `getCustomers(relations)` - Retrieve all customers
+- `putCustomer(id, data)` - Update a customer
+- `postCustomer(data)` - Create a new customer
+- `searchCustomers(searchTerm, relations)` - Search customers by name or email
+
+#### Items
+
+- `getItem(id, relations)` - Fetch a specific item by ID
+- `getItems(relations, limit)` - Retrieve all items (or limited number if limit specified)
+- `getMultipleItems(items, relations)` - Get multiple items by IDs
+- `putItem(id, data)` - Update an item
+- `postItem(data)` - Create a new item
+- `getVendorItems(vendorID, relations)` - Get items by vendor
+- `searchItems(searchTerm, relations)` - Search items by description
+- `getItemsByCategory(categoryId, relations)` - Get items in a category
+- `getItemsWithLowStock(threshold, relations)` - Get items below stock threshold
+- `updateMultipleItems(updates)` - Bulk update multiple items
+
+#### Matrix Items
+
+- `getMatrixItem(id, relations)` - Fetch a specific matrix item by ID
+- `getMatrixItems(relations)` - Retrieve all matrix items
+- `putMatrixItem(id, data)` - Update a matrix item
+- `postMatrixItem(data)` - Create a new matrix item
+
+#### Categories
+
+- `getCategory(id, relations)` - Fetch a specific category by ID
+- `getCategories(relations)` - Retrieve all categories
+- `putCategory(id, data)` - Update a category
+- `postCategory(data)` - Create a new category
+
+#### Manufacturers
+
+- `getManufacturer(id, relations)` - Fetch a specific manufacturer by ID
+- `getManufacturers(relations)` - Retrieve all manufacturers
+- `putManufacturer(id, data)` - Update a manufacturer
+- `postManufacturer(data)` - Create a new manufacturer
+
+#### Vendors
+
+- `getVendor(id, relations)` - Fetch a specific vendor by ID
+- `getVendors(relations)` - Retrieve all vendors
+- `putVendor(id, data)` - Update a vendor
+- `postVendor(data)` - Create a new vendor
+
+#### Orders
+
+- `getOrder(id, relations)` - Fetch a specific order by ID
+- `getOrders(relations)` - Retrieve all orders
+- `getOrdersByVendorID(id, relations)` - Get orders by vendor
+- `getOpenOrdersByVendorID(id, relations)` - Get open orders by vendor
+
+#### Sales
+
+- `getSale(id, relations)` - Fetch a specific sale by ID
+- `getSales(relations)` - Retrieve all sales
+- `getMultipleSales(saleIDs, relations)` - Get multiple sales by IDs
+- `getSalesByDateRange(startDate, endDate, relations)` - Get sales in date range
+- `putSale(id, data)` - Update a sale
+- `postSale(data)` - Create a new sale
+
+#### Sale Lines
+
+- `getSaleLinesByItem(itemID, relations)` - Get sale lines for an item
+- `getSaleLinesByItems(ids, startDate, endDate, relations)` - Get sale lines for multiple items with date filter
+- `getSaleLinesByVendorID(id, startDate, endDate, relations)` - Get sale lines by vendor with date filter
+
+### Account & Configuration
+
+#### Account Information
+
+- `getAccount(relations)` - Get account/shop information
+
+#### Employees
+
+- `getEmployees(relations)` - Get all employees
+- `getEmployee(id, relations)` - Get a specific employee
+
+#### System Configuration
+
+- `getCustomerTypes(relations)` - Get customer types
+- `getRegisters(relations)` - Get registers/shops
+- `getPaymentTypes(relations)` - Get payment types
+- `getTaxClasses(relations)` - Get tax classes
+- `getItemAttributes(relations)` - Get item attributes
+
+### Gift Cards & Special Orders
+
+- `getGiftCards(relations)` - Get all gift cards
+- `getGiftCard(id, relations)` - Get a specific gift card by code
+- `getSpecialOrders(relations)` - Get special orders
+
+### Images
+
+- `getImages(relations)` - Get all images
+- `postImage(imageFilePath, metadata)` - Upload an image
+
+### Utility Methods
+
+- `ping()` - Test API connection and authentication
+- `refreshTokens()` - Force refresh of access tokens
+- `getTokenInfo()` - Get current token status information
+
+## Error Handling
+
+The SDK includes comprehensive error handling with automatic retries for transient failures:
+
+```javascript
+try {
+  const item = await api.getItem(123);
+  console.log(item);
+} catch (error) {
+  console.error("API Error:", error.message);
+  // Error details are automatically logged by the SDK
+}
 ```
 
-## Methods
-
-- `getCustomer(id, relations)`: Fetches a specific customer by ID. Optionally, related data can be included.
-- `getCustomers(relations)`: Retrieves all customers. Optionally, related data can be included.
-- `getItem(id, relations)`: Fetches a specific item by ID. Optionally, related data can be included.
-- `getMultipleItems(items, relations)`: Retrieves multiple items by their IDs. Optionally, related data can be included.
-- `getItems(relations)`: Retrieves all items. Optionally, related data can be included.
-- `getvendorItems(vendorID, relations)`: Retrieves all items for a specific vendor. Optionally, related data can be included.
-- `getMatrixItems(relations)`: Fetches all matrix items. Optionally, related data can be included.
-- `getMatrixItem(id, relations)`: Fetches a specific matrix item by ID. Optionally, related data can be included.
-- `getCategory(id, relations)`: Retrieves a specific category by ID. Optionally, related data can be included.
-- `getCategories(relations)`: Retrieves all categories. Optionally, related data can be included.
-- `getManufacturer(id, relations)`: Fetches a specific manufacturer by ID. Optionally, related data can be included.
-- `getManufacturers(relations)`: Retrieves all manufacturers. Optionally, related data can be included.
-- `getOrder(id, relations)`: Fetches a specific order by ID. Optionally, related data can be included.
-- `getOrders(relations)`: Retrieves all orders. Optionally, related data can be included.
-- `getOrdersByVendorID(id, relations)`: Retrieves all orders for a specific vendor. Optionally, related data can be included.
-- `getOpenOrdersByVendorID(id, relations)`: Fetches all open orders for a specific vendor. Optionally, related data can be included.
-- `getVendor(id, relations)`: Fetches a specific vendor by ID. Optionally, related data can be included.
-- `getVendors(relations)`: Retrieves all vendors. Optionally, related data can be included.
-- `getSale(id, relations)`: Fetches a specific sale by ID. Optionally, related data can be included.
-- `getSales(relations)`: Retrieves all sales. Optionally, related data can be included.
-- `getMultipleSales(saleIDs, relations)`: Fetches multiple sales by their IDs. Optionally, related data can be included.
-- `getSaleLinesByItem(itemID, relations)`: Retrieves sale lines for a specific item. Optionally, related data can be included.
-- `getSaleLinesByItems(ids, startDate, endDate, relations)`: Retrieves sale lines for multiple items, filtered by date range. Optionally, related data can be included.
-- `getSaleLinesByVendorID(id, startDate, endDate, relations)`: Fetches sale lines for a specific vendor, filtered by date range. Optionally, related data can be included.
-- `getSpecialOrders(relations)`: Fetches special orders. Optionally, related data can be included.
+## Rate Limiting
+
+The SDK automatically handles Lightspeed's API rate limits by:
+
+- Monitoring rate limit headers
+- Calculating appropriate delays
+- Automatically waiting when limits are approached
+
+## Pagination
+
+For endpoints that return large datasets, the SDK automatically handles pagination:
+
+```javascript
+// This will automatically fetch all pages
+const allItems = await api.getItems();
+console.log(`Retrieved ${allItems.length} items`);
+```
 
 ## Contributing
 
-Contributions are welcome!
+Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## License
 
@@ -87,4 +365,5 @@ This SDK is not officially affiliated with Lightspeed HQ and is provided "as is"
 
 ## More Info
 
-The documentation for the Lightspeed Retail API can be found at https://developers.lightspeedhq.com/retail/introduction/introduction/
+- [Lightspeed Retail API Documentation](https://developers.lightspeedhq.com/retail/introduction/introduction/)
+- [New OAuth Documentation](https://developers.lightspeedhq.com/retail/authentication/oauth/)