@liquidcommercedev/rmn-sdk 1.5.0-beta.34 → 1.5.0-beta.36

package/README.md

@@ -1,89 +1,233 @@
-![](https://storage.googleapis.com/liquid-platform/repo_lc_dark.webp)
+# Liquid Commerce Retail Media Network (RMN) SDK
 
-# LiquidCommerce RMN SDK
-
-The Liquid Commerce RMN SDK provides an easier way to interact with our Retail Media Network APIs through a server-side SDK for Node.js and Web JS script (more libraries will soon follow).
+The Liquid Commerce RMN SDK enables retailers to transform their digital properties into powerful advertising platforms. It provides a comprehensive solution for implementing retail media advertising, supporting standard IAB ad formats and custom spot types.
 
 ## Overview
 
-The RMN SDK is bundled for use with both import/require , if you need the client side use the script below, compiled down to ES2015.
+The RMN SDK facilitates the integration of retail media advertising within e-commerce platforms, offering:
+
+- Multiple spot type support including IAB Standard formats
+- Dynamic spot selection and placement
+- Comprehensive event tracking and analytics
+- Carousel displays for multiple advertisements
+- Proximity-based loading for optimal performance
+- Flexible deployment across server-side and client-side environments
 
->`<script src="https://js.liquidcommerce.co/sdk/v1"></script>`
+## Installation
 
-| Method                  | Description                                                                                                                                 |
-|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
-| `spotSelection({})`     | A sample authenticated interaction with our Decision API that receives custom personalized ADs using machine learning and event based data. |
-| `createSpotElement({})` | A simple method that makes your life easier by creating the spot element ready for injection anywhere in your site.                         |
+```bash
+npm install @liquidcommercedev/rmn-sdk
+```
 
-# METHODS
+## Core Concepts
+
+### Spot Types
+
+The SDK supports IAB Standard Formats including:
+- Billboard
+- Rectangle variants (Large, Medium, Small)
+- Leaderboard variants
+- Skyscraper formats
+- Mobile-specific formats
+- Interstitials
+- ...and more to come
+
+### Event System
+
+The SDK implements a comprehensive event tracking system:
+
+```typescript
+enum RMN_EVENT {
+  LIFECYCLE_STATE = 'LIFECYCLE_STATE',
+  SPOT_EVENT = 'SPOT_EVENT'
+}
+
+enum RMN_SPOT_EVENT {
+  IMPRESSION = 'IMPRESSION',
+  CLICK = 'CLICK',
+  PURCHASE = 'PURCHASE',
+  ADD_TO_CART = 'ADD_TO_CART',
+  REMOVE_FROM_CART = 'REMOVE_FROM_CART',
+  ADD_TO_CART_FROM_DETAILS = 'ADD_TO_CART_FROM_DETAILS',
+  ADD_TO_WISHLIST = 'ADD_TO_WISHLIST',
+  EXPAND_PRODUCT = 'EXPAND_PRODUCT',
+  BUY_NOW = 'BUY_NOW'
+}
+```
 
-## Authentication
+## Usage
 
-The Liquid Commerce library provides convenient, secure, and encrypted access to our Liquid Commerce methods through API Key authentication.
+### Basic Implementation
 
-### Installation
+```typescript
+import { RmnClient } from '@liquidcommercedev/rmn-sdk';
 
-Install the package with:
+// Initialize the client
+const client = await RmnClient('your-api-key', {
+  env: 'production'
+});
 
-```sh
-npm install @liquidcommercedev/rmn-sdk
-# or
-yarn add @liquidcommercedev/rmn-sdk
+// Request spots
+const spots = await client.spotSelection({
+  spots: [{
+    placementId: 'sidebar-ad',
+    spot: RMN_SPOT_TYPE.MEDIUM_RECTANGLE,
+    count: 1
+  }],
+  filter: {
+    section: 'category-page',
+    category: 'electronics'
+  }
+});
 ```
 
-The Liquid Commerce methods use API keys to authenticate requests. You can request your keys from your Partnerships liaison.
+### Spot Injection
+
+```typescript
+await client.injectSpotElement({
+  inject: [{
+    placementId: 'sidebar-ad',
+    spotType: RMN_SPOT_TYPE.MEDIUM_RECTANGLE,
+    config: {
+      fluid: true,
+      colors: {
+        textColor: '#333333',
+        backgroundColor: '#FFFFFF',
+        ctaTextColor: '#FFFFFF',
+        ctaBorderColor: '#000000'
+      }
+    }
+  }]
+});
+```
 
-Development mode secret keys have the prefix dev_ and Production ready secret keys have the prefix prod_.
+### Event Handling
 
-Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
+```typescript
+const eventManager = RmnEventManager();
 
-Once you create a new instance of the LiquidCommerce() library it will generate an access token that then automatically attaches to each request, the access token has a 1hour expiry that continues to refresh on each call. If an hour has passed without using the token, you must authenticate again to fetch a fresh access token.
+// Track spot visibility
+eventManager.subscribe(RMN_EVENT.SPOT_EVENT, (data) => {
+  if (data.eventType === RMN_SPOT_EVENT.IMPRESSION) {
+    console.log('Spot impression:', data.spotId);
+  }
+});
 
-All API requests in production must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. API requests without authentication will also fail.
+// Track user interactions
+eventManager.subscribe(RMN_EVENT.SPOT_EVENT, (data) => {
+  if (data.eventType === RMN_SPOT_EVENT.CLICK) {
+    console.log('Spot clicked:', data.spotId);
+  }
+});
+```
 
-> **ALL LIVE/PRODUCTION API REQUESTS AND RESPONSES ARE ENCRYPTED IN TRANSMISSION.**
- 
+## Advanced Features
+
+### Spot Manager Service
+
+The SpotManager handles the lifecycle and state management of spots:
+
+```typescript
+interface ILifecycleState {
+  identifier: {
+    placementId: string;
+    spotId: string;
+    spotType: string;
+  };
+  dom: {
+    visibleOnViewport: boolean;
+    spotElement?: HTMLElement;
+  };
+  state: {
+    mounted: boolean;
+    unmounted: boolean;
+    loading: boolean;
+    error?: string;
+  };
+  displayConfig: {
+    isCarousel: boolean;
+    isCarouselItem: boolean;
+    isSingleItem: boolean;
+  };
+}
+```
 
-<!-- prettier-ignore -->
-```js
-const RmnClient = require('@liquidcommercedev/rmn-sdk');
+### Filtering Options
+
+The SDK supports comprehensive filtering capabilities:
+
+```typescript
+enum RMN_FILTER_PROPERTIES {
+  KEYWORDS = 'keywords',
+  PAGE_LOCATION = 'pageLocation',
+  PARENTCO = 'parentCo',
+  BRAND = 'brand',
+  CATEGORY = 'category',
+  TYPE = 'type',
+  CLASSIFICATION = 'classification',
+  HOLIDAY = 'holiday',
+  PUBLISHERS = 'publishers',
+  SECTION = 'section'
+}
 ```
 
-For ES modules and async/await:
+## Best Practices
 
-```js
-import { RmnClient } from '@liquidcommercedev/rmn-sdk';
-```
+### Performance Optimization
 
-### Usage
+1. **Proximity Loading**
+  - Utilize the built-in proximity observer
+  - Configure appropriate thresholds for your use case
+  - Implement proper cleanup
 
-```js
-import { RmnClient } from '@liquidcommercedev/rmn-sdk';
-// Your Account token provided to you through your account representative
-const client = await RmnClient('YOUR_API_KEY', {
-  env: 'staging'
-});
-```
+2. **State Management**
+  - Track spot lifecycle states
+  - Handle unmounting properly
+  - Clear resources when spots are destroyed
 
-## Selection
+3. **Error Handling**
+  - Implement proper error boundaries
+  - Provide fallback content
+  - Monitor spot lifecycle states
 
-A sample authenticated interaction with our Decision API that receives custom personalized ADs using machine learning and event based data.
+### Event Tracking
 
-### Sample Spot Selection 
+1. **Impression Tracking**
+  - Ensure proper viewport tracking
+  - Handle carousel impressions appropriately
+  - Monitor viewability metrics
 
-An example use case for LiquidCommerce's `spotSelection({})` method.
+2. **Interaction Tracking**
+  - Track all user interactions
+  - Implement proper event debugging
+  - Monitor conversion events
 
-<!-- prettier-ignore -->
-```js
-import RmnClient from '@liquidcommercedev/rmn-sdk';
-// Your Account token provided to you through your account representative
-const client = await RmnClient('YOUR_API_KEY', {
-  env: 'staging'
-});
+## TypeScript Support
 
-const spots = await client.spotSelection({
-  "spots": ['billboard', 'leaderboard']
-});
+The SDK is written in TypeScript and provides comprehensive type definitions for all features:
+
+- Spot Types and Configurations
+- Event Systems and Handlers
+- Service Interfaces
+- State Management Types
+
+## Environment Support
+
+### Browser Environment
+- Full DOM manipulation support
+- Lifecycle management
+- Event tracking
+- Proximity loading
+
+### Server Environment
+- Spot selection support
+- SSR compatibility
+- Reduced feature set
+
+## Contributing
+
+Please refer to our contribution guidelines for information on how to participate in the development of this SDK.
+
+## License
 
-console.log({ spots });
-```
+[License information here]