admesh-ui-sdk 0.17.0 → 0.19.0

package/README.md

@@ -32,6 +32,153 @@ A comprehensive React + TypeScript component library for displaying AdMesh produ
 npm install admesh-ui-sdk
 ```
 
+## 🚀 Zero-Code Integration (Recommended for Platforms)
+
+The AdMesh SDK provides a **zero-code integration experience** that handles everything automatically. Perfect for platforms that want to add monetized recommendations without writing custom code.
+
+### 3-Step Integration
+
+**Step 1: Install the SDK**
+```bash
+npm install admesh-ui-sdk
+```
+
+**Step 2: Add a container element**
+```html
+<!-- Place this div where you want recommendations to appear -->
+<div id="admesh-recommendations"></div>
+```
+
+**Step 3: Initialize and fetch recommendations**
+```typescript
+import { AdMeshSDK } from 'admesh-ui-sdk';
+
+// Initialize once with your API key
+const admesh = new AdMeshSDK({
+  apiKey: 'your-api-key-here'
+});
+
+// Fetch and render recommendations automatically
+await admesh.showRecommendations({
+  query: userQuery,
+  containerId: 'admesh-recommendations',
+  format: 'auto' // optional: auto-detects best format
+});
+
+// Close session when conversation ends
+admesh.closeSession();
+```
+
+### Complete Example
+
+```typescript
+import { AdMeshSDK } from 'admesh-ui-sdk';
+
+const admesh = new AdMeshSDK({
+  apiKey: 'admesh_prod_your_key_here',
+  debug: true // optional: enable debug logging
+});
+
+// When user searches or asks a question
+async function handleUserQuery(query: string) {
+  try {
+    await admesh.showRecommendations({
+      query: query,
+      containerId: 'admesh-recommendations',
+      format: 'auto',
+      onRecommendationClick: (adId, admeshLink) => {
+        console.log('User clicked recommendation:', adId);
+        // Optional: custom handling before opening link
+      }
+    });
+  } catch (error) {
+    console.error('Failed to fetch recommendations:', error);
+  }
+}
+
+// When conversation ends
+function handleConversationEnd() {
+  admesh.closeSession();
+}
+```
+
+### Session Management
+
+The SDK automatically manages sessions for you:
+
+- **Automatic Session Creation**: A new session is created on first recommendation fetch
+- **Session Persistence**: Sessions are stored in localStorage and reused across page reloads
+- **Session Timeout**: Sessions expire after 30 minutes of inactivity
+- **Manual Control**: You can create new sessions or set custom session IDs
+
+```typescript
+// Create a new session (e.g., for a new conversation)
+const newSessionId = admesh.createNewSession();
+
+// Get current session ID
+const sessionId = admesh.getSessionId();
+
+// Set a custom session ID
+admesh.setSessionId('custom-session-id');
+
+// Close session when done
+admesh.closeSession();
+```
+
+### Configuration Options
+
+```typescript
+const admesh = new AdMeshSDK({
+  apiKey: 'your-api-key',                    // Required
+  apiBaseUrl: 'https://api.useadmesh.com',   // Optional: defaults to production
+  debug: false,                               // Optional: enable debug logging
+  theme: {                                    // Optional: customize appearance
+    mode: 'light',
+    primaryColor: '#3b82f6',
+    borderRadius: '8px'
+  }
+});
+```
+
+### What the SDK Handles Automatically
+
+- ✅ API authentication with your API key
+- ✅ Recommendation fetching from `/agent/recommend` endpoint
+- ✅ Session creation and management
+- ✅ Automatic rendering with appropriate UI components
+- ✅ Exposure tracking (when recommendations are shown)
+- ✅ Click tracking (when users click recommendations)
+- ✅ Conversion tracking (when users complete actions)
+- ✅ Error handling and logging
+- ✅ Responsive design and theming
+
+### Advanced: Custom Rendering
+
+If you need more control over rendering, you can use the individual components:
+
+```typescript
+import { AdMeshLayout } from 'admesh-ui-sdk';
+
+// Fetch recommendations manually
+const response = await admesh.fetcher.fetchRecommendations({
+  query: 'best CRM for small business',
+  session_id: admesh.getSessionId()
+});
+
+// Render with custom configuration
+<AdMeshLayout
+  response={{
+    layout_type: response.response?.layout_type,
+    recommendations: response.response?.recommendations || [],
+    citation_summary: response.response?.summary
+  }}
+  theme={{ mode: 'dark' }}
+  onRecommendationClick={(rec) => {
+    // Custom click handling
+  }}
+/>
+```
+
 ## ✨ Self-Contained Design
 
 **Zero configuration required!** The AdMesh UI SDK is completely self-contained and works like Google Ads or any professional SDK:

package/dist/components/AdMeshProductCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AdMeshProductCard.d.ts","sourceRoot":"","sources":["../../src/components/AdMeshProductCard.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4B,MAAM,OAAO,CAAC;AAEjD,OAAO,KAAK,EAAE,sBAAsB,EAAa,MAAM,gBAAgB,CAAC;AAUxE,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,sBAAsB,CAgW9D,CAAC"}
+{"version":3,"file":"AdMeshProductCard.d.ts","sourceRoot":"","sources":["../../src/components/AdMeshProductCard.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4B,MAAM,OAAO,CAAC;AAEjD,OAAO,KAAK,EAAE,sBAAsB,EAAa,MAAM,gBAAgB,CAAC;AASxE,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,sBAAsB,CAoV9D,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { AdMeshLayout, AdMeshProductCard, AdMeshInlineCard, AdMeshEcommerceCards, AdMeshSummaryUnit, AdMeshSummaryLayout, AdMeshLinkTracker, AdMeshBadge } from './components';
 export { AdMeshViewabilityTracker } from './components/AdMeshViewabilityTracker';
+export { AdMeshSDK, AdMeshSessionManager, AdMeshRecommendationFetcher, AdMeshTracker, AdMeshRenderer } from './sdk';
+export type { AdMeshSDKConfig, ShowRecommendationsOptions, FetchRecommendationsParams, FetcherConfig, TrackerConfig, RenderOptions } from './sdk';
 export { useAdMeshTracker, setAdMeshTrackerConfig, buildAdMeshLink, extractTrackingData } from './hooks/useAdMeshTracker';
 export { useAdMeshStyles } from './hooks/useAdMeshStyles';
 export { useViewabilityTracker, setViewabilityTrackerConfig } from './hooks/useViewabilityTracker';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,WAAW,EACZ,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AAGjF,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,mBAAmB,EACpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,eAAe,EAChB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC5B,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,sBAAsB,EACvB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EACV,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AAGjC,YAAY,EACV,oBAAoB,EACpB,WAAW,EACX,UAAU,EACV,SAAS,EACT,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,sBAAsB,EACtB,yBAAyB,EACzB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,2BAA2B,EAC3B,YAAY,EACb,MAAM,eAAe,CAAC;AAGvB,YAAY,EACV,uBAAuB,EACvB,oBAAoB,EACpB,UAAU,EACV,sBAAsB,EACtB,4BAA4B,EAC5B,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,uBAAuB,EACvB,4BAA4B,EAC5B,4BAA4B,EAC7B,MAAM,mBAAmB,CAAC;AAG3B,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,eAAO,MAAM,cAAc;;;;;;;CAO1B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,WAAW,EACZ,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AAGjF,OAAO,EACL,SAAS,EACT,oBAAoB,EACpB,2BAA2B,EAC3B,aAAa,EACb,cAAc,EACf,MAAM,OAAO,CAAC;AAEf,YAAY,EACV,eAAe,EACf,0BAA0B,EAC1B,0BAA0B,EAC1B,aAAa,EACb,aAAa,EACb,aAAa,EACd,MAAM,OAAO,CAAC;AAGf,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,mBAAmB,EACpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,eAAe,EAChB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC5B,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,sBAAsB,EACvB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EACV,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AAGjC,YAAY,EACV,oBAAoB,EACpB,WAAW,EACX,UAAU,EACV,SAAS,EACT,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,sBAAsB,EACtB,yBAAyB,EACzB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,2BAA2B,EAC3B,YAAY,EACb,MAAM,eAAe,CAAC;AAGvB,YAAY,EACV,uBAAuB,EACvB,oBAAoB,EACpB,UAAU,EACV,sBAAsB,EACtB,4BAA4B,EAC5B,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,uBAAuB,EACvB,4BAA4B,EAC5B,4BAA4B,EAC7B,MAAM,mBAAmB,CAAC;AAG3B,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,eAAO,MAAM,cAAc;;;;;;;CAO1B,CAAC"}