@meprotocol/agent-me-sdk

v1.0.0

Published

a month ago

AI Chatbot SDK - Embeddable chatbot widget for any website

0High
0Medium
0Low

agentpoles

chatbot sdk ai widget

MeAgent SDK

AI-powered chatbot widget that can be embedded on any website. Built with TypeScript, works with vanilla HTML, React, Vue, Angular, and any other web framework.

🚀 Try the Live Demo | 📖 View Documentation

Features

🚀 Easy Integration: Single script tag integration - no dependencies required
💬 AI-Powered Chat: Real-time streaming responses with offer recommendations
🎨 Modern UI: Beautiful, customizable interface with smooth animations
📱 Fully Responsive: Works perfectly on desktop and mobile
🔧 Configurable: Customize position, environment, network and more
🔐 Magic Link Authentication: Built-in wallet authentication for blockchain redemption
⚡ Standalone Bundle: All dependencies included (~1.7MB minified, includes ethers, web3, runtime-sdk, protocol-core)
🛍️ Smart Redemption: Same-brand and cross-brand reward token swapping
🎯 Product Discovery: AI-powered offer search, category browsing, and brand exploration

Installation

CDN Usage (Recommended)

The SDK is a standalone bundle with all blockchain dependencies included. Just load one script:

<!-- Load SDK from npm CDN -->
<script src="https://cdn.jsdelivr.net/npm/me-agent-sdk/dist/me-agent-sdk.min.js"></script>

<!-- Initialize -->
<script>
  window.addEventListener("DOMContentLoaded", async () => {
    await MeAgent.init({
      emailAddress: "[email protected]", // optional (required for redemption)
      brandId: "your-brand-id", // optional
      userId: "user-123", // optional
      position: "bottom-right", // optional: 'bottom-right' or 'bottom-left'
      environment: MeAgent.Environment.DEV, // optional: DEV, STAGING, or PROD
      network: MeAgent.Network.SEPOLIA, // optional: SEPOLIA, HEDERA, BASE, or POLYGON
    });
  });
</script>

Global Variable: The SDK exposes window.MeAgent for browser usage.

CDN Options:

jsDelivr (Recommended):

Latest version: https://cdn.jsdelivr.net/npm/me-agent-sdk/dist/me-agent-sdk.min.js
Specific version: https://cdn.jsdelivr.net/npm/[email protected]/dist/me-agent-sdk.min.js
Unminified (dev): https://cdn.jsdelivr.net/npm/me-agent-sdk/dist/me-agent-sdk.js

unpkg:

Latest version: https://unpkg.com/me-agent-sdk/dist/me-agent-sdk.min.js
Specific version: https://unpkg.com/[email protected]/dist/me-agent-sdk.min.js

Global Variable: The SDK exposes window.MeAgent for browser usage. All methods and constants are available on this global object.

Via npm

npm install me-agent-sdk

Usage:

import MeAgent, { Environment, SupportedNetwork } from "me-agent-sdk";

MeAgent.init({
  emailAddress: "[email protected]",
  brandId: "your-brand-id",
  userId: "user-123",
  position: "bottom-right",
  environment: Environment.DEV,
  network: SupportedNetwork.SEPOLIA,
});

Note: The npm package is built with Webpack and includes all blockchain dependencies bundled together:

ethers.js v5.7.2
web3 v1.10.0
@developeruche/runtime-sdk v0.11.8
@developeruche/protocol-core v0.10.55
@gelatonetwork/relay-sdk

No additional packages needed - everything works out of the box!

Configuration Options

| Option | Type | Required | Default | Description | | ------------------ | ---------------- | -------- | -------------- | ----------------------------------------------------------------- | | emailAddress | string | No | - | User's email address for authentication | | brandId | string | No | - | Your brand identifier | | userId | string | Yes | - | Unique user identifier (required) | | position | string | No | 'bottom-right' | Widget position: 'bottom-right' or 'bottom-left' | | environment | Environment | No | DEV | Environment: DEV, STAGING, or PROD | | network | SupportedNetwork | No | SEPOLIA | Blockchain network: SEPOLIA, HEDERA, BASE, or POLYGON | | onAddToCart | function | No | - | Callback when user adds an offer to cart | | onRemoveFromCart | function | No | - | Callback when user removes an offer from cart | | onShare | function | No | - | Callback when user clicks share button on offer details | | onLikeUnlike | function | No | - | Callback when user clicks like/unlike button on offer details | | likedOffers | object | No | {} | Initial liked state for offers (map of offer IDs to booleans) | | cartItems | CartItem[] | No | [] | Array of items currently in cart (for showing "Remove from Cart") |

Callback Functions & Cart Management

The SDK supports optional callbacks for e-commerce actions on the offer details page:

// Example cart state
let myCart = [];

await MeAgent.init({
  // ... other config

  // Cart Management
  onAddToCart: async (offer, variantId) => {
    console.log("Adding to cart:", offer, "variant:", variantId);
    myCart.push({ offerCode: offer.offerCode, variantId });

    // Update SDK's cart state
    MeAgent.updateCartItems(myCart);

    // Your add to cart logic here (e.g., API call, state update)
  },

  onRemoveFromCart: async (offerCode, variantId) => {
    console.log("Removing from cart:", offerCode, "variant:", variantId);
    myCart = myCart.filter(
      (item) => !(item.offerCode === offerCode && item.variantId === variantId)
    );

    // Update SDK's cart state
    MeAgent.updateCartItems(myCart);

    // Your remove from cart logic here
  },

  // Pass initial cart items to show correct button state
  cartItems: myCart, // Array of { offerCode, variantId?, quantity? }

  // Social Actions
  onShare: (offer) => {
    console.log("Share clicked:", offer);
    // Your share logic here
  },

  onLikeUnlike: (offer, isLiked) => {
    console.log(`Offer ${isLiked ? "liked" : "unliked"}:`, offer);

    // Update your liked offers state
    const myLikedOffers = { ...likedOffers };
    myLikedOffers[offer.id] = isLiked;

    // Update SDK's liked state
    MeAgent.updateLikedOffers(myLikedOffers);

    // Your like/unlike logic here (e.g., API call)
  },

  likedOffers: {
    "offer-id-1": true,
    "offer-id-2": false,
  },
});

CartItem Interface

interface CartItem {
  offerCode: string; // Offer code/ID
  variantId?: string; // Product variant ID (if applicable)
  quantity?: number; // Quantity (optional)
}

How it works:

If an offer is in cartItems, the button shows "Remove from Cart"
If not in cart, the button shows "Add to Cart"
Clicking the button calls either onAddToCart or onRemoveFromCart
You manage your cart state, and the SDK reflects it in the UI

Important:

After adding or removing items from your cart, call MeAgent.updateCartItems(newCartArray) to update the SDK's cart state.
After liking or unliking offers, call MeAgent.updateLikedOffers(newLikedObject) to update the SDK's liked state.
These updates ensure the UI reflects changes immediately without requiring a page refresh.

Note: Action buttons (Add to Cart, Like, Share) will only appear on the offer details page if their respective callback functions are provided.

Programmatic Control

The SDK provides methods to programmatically control the chat widget:

Browser (CDN)

// After initialization
await MeAgent.init({ ... });

// Open the chat widget
MeAgent.open();

// Close the chat widget
MeAgent.close();

// Toggle the chat widget
MeAgent.toggle();

// Update cart items (after cart changes)
MeAgent.updateCartItems(newCartArray);

// Update liked offers (after like/unlike)
MeAgent.updateLikedOffers(newLikedObject);

// Destroy the SDK
MeAgent.destroy();

React / NPM

import { useState, useEffect } from "react";
import { MeAgentSDK } from "me-agent-sdk";

function App() {
  const [sdkInstance, setSdkInstance] = useState(null);

  useEffect(() => {
    const initSDK = async () => {
      const sdk = new MeAgentSDK({
        emailAddress: "[email protected]",
        brandId: "your-brand",
        userId: "user-123",
      });

      await sdk.init();
      setSdkInstance(sdk); // Store instance for control
    };

    initSDK();
  }, []);

  // Control methods
  const handleOpenChat = () => sdkInstance?.open();
  const handleCloseChat = () => sdkInstance?.close();
  const handleToggleChat = () => sdkInstance?.toggle();
  const handleUpdateCart = (newCart) => sdkInstance?.updateCartItems(newCart);
  const handleUpdateLiked = (newLiked) =>
    sdkInstance?.updateLikedOffers(newLiked);

  return (
    <div>
      <button onClick={handleOpenChat}>Open Chat</button>
      <button onClick={handleCloseChat}>Close Chat</button>
      <button onClick={handleToggleChat}>Toggle Chat</button>
    </div>
  );
}

Common Use Cases

Auto-open on page load:

await MeAgent.init({ ... });
MeAgent.open();

Open after user action:

form.addEventListener("submit", async (e) => {
  e.preventDefault();
  // Process form...
  MeAgent.open(); // Show chat for support
});

Open for first-time visitors:

const isFirstVisit = !localStorage.getItem("visited");
if (isFirstVisit) {
  MeAgent.open();
  localStorage.setItem("visited", "true");
}

Deep link integration:

const params = new URLSearchParams(window.location.search);
if (params.get("chat") === "open") {
  MeAgent.open();
}

Environments

MeAgent.Environment.DEV; // Development environment
MeAgent.Environment.STAGING; // Staging environment
MeAgent.Environment.PROD; // Production environment

Supported Networks

MeAgent.Network.SEPOLIA; // Ethereum Sepolia testnet
MeAgent.Network.HEDERA; // Hedera network
MeAgent.Network.BASE; // Base network
MeAgent.Network.POLYGON; // Polygon network

Features in Detail

💬 AI Chat

The widget provides an AI-powered chat interface that can:

Answer questions about products and services
Search for offers and deals in real-time
Provide personalized recommendations based on user queries
Display quick action buttons for common tasks
Stream responses for a natural conversation feel

🛍️ Offer Discovery

Users can explore offers through multiple channels:

AI Search: Ask the AI to find specific offers
Category Browsing: View offers organized by purchase categories
Brand Discovery: Explore brands that offer signup and purchase rewards
Card Lists: Horizontal scrollable lists with "View All" functionality
Detailed Views: Full product details with variants, reviews, and pricing

🎁 Offer Redemption

Complete blockchain-powered redemption flow:

Same-Brand Redemption: Use brand tokens to redeem offers from the same brand
Cross-Brand Redemption: Swap tokens from one brand to redeem offers from another
Magic Link Authentication: Secure wallet creation and management (no seed phrases!)
Multi-Reward Support: Automatically check balances across all reward tokens
Swap Calculations: Real-time token swap amount calculations
Step-by-Step UI: Clear Review → Processing → Complete flow
Coupon Generation: Automatic discount code generation and delivery
Checkout Integration: Direct links to brand checkout with applied coupons

💰 Reward Management

The SDK integrates with ME Protocol for:

Multi-reward balance checking
Cross-brand token swapping via protocol vaults
Automatic affordability checking before redemption
Gelato relay for gasless transactions
Transaction refunds on failed orders

Troubleshooting

Redemption Not Working

If redemption features aren't working, verify:

SDK is properly loaded:

<script src="https://cdn.jsdelivr.net/npm/me-agent-sdk/dist/me-agent-sdk.min.js"></script>

Email address is provided:

MeAgent.init({
  emailAddress: "[email protected]", // Required for redemption
  // ... other config
});

Using supported browser - See Browser Support section below
Check browser console for errors - Look for authentication or network errors

CDN Loading Issues

If the SDK fails to load from CDN:

Check your internet connection
Verify firewall/proxy settings aren't blocking cdn.jsdelivr.net
Try using unpkg as an alternative: https://unpkg.com/me-agent-sdk/dist/me-agent-sdk.min.js
Use a specific version instead of @latest

Browser Support

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)
Mobile browsers (iOS Safari, Chrome Mobile)

Development

Setup

# Clone the repository
git clone https://github.com/Me-Protocol/me-agent-sdk.git
cd me-agent-sdk

# Install dependencies
npm install

# Build the SDK
npm run build

Development Workflow

# Watch mode (rebuilds on changes)
npm run watch

# Run local server
npm run serve

# Development with live reload
npm run dev:full

Bundled Dependencies

The SDK is built with Webpack and includes these blockchain libraries:

ethers v5.7.2 - Blockchain interactions and wallet management
web3 v1.10.0 - Web3 provider for Magic wallet
@developeruche/runtime-sdk v0.11.8 - ME Protocol runtime for redemption logic
@developeruche/protocol-core v0.10.55 - ME Protocol core for token swaps and relay
@gelatonetwork/relay-sdk - Gelato relay for gasless transactions

Everything is bundled together - no external dependencies needed!

Project Structure

src/
├── types/           # TypeScript interfaces and types
├── core/            # Core utilities and constants
├── data/            # API clients and authentication
├── services/        # Business logic layer
├── controllers/     # UI orchestration layer
├── views/           # UI rendering (pure view functions)
└── index.ts         # Public API entry point

For detailed architecture information, see ARCHITECTURE_GUIDE.md.

Testing

Live Demo: Visit https://me-protocol.github.io/me-agent-sdk/ to see the SDK in action.

Local Testing:

Build the SDK: npm run build
Run npm run serve to start a local server
Open http://localhost:5500 in your browser
The example uses the local build from dist/me-agent-sdk.min.js

Note: The docs/index.html and example/index.html files load the SDK from the local dist/ folder for development. When deploying to production (GitHub Pages, CDN), update the script tag to use the CDN URL.

Quick Reference

Complete CDN Setup (Copy & Paste)

<!DOCTYPE html>
<html>
  <head>
    <title>My App with ME Agent SDK</title>
  </head>
  <body>
    <!-- Your website content -->

    <!-- Load ME Agent SDK (standalone - includes all dependencies) -->
    <script src="https://cdn.jsdelivr.net/npm/me-agent-sdk/dist/me-agent-sdk.min.js"></script>

    <!-- Initialize SDK -->
    <script>
      window.addEventListener("DOMContentLoaded", async () => {
        await MeAgent.init({
          emailAddress: "[email protected]",
          brandId: "your-brand-id",
          userId: "user-123",
          position: "bottom-right",
          environment: MeAgent.Environment.DEV,
          network: MeAgent.Network.SEPOLIA,
        });
      });
    </script>
  </body>
</html>

CDN URLs

| Package | Version | CDN URL | | ------------ | ------- | -------------------------------------------------------------------------- | | ME Agent SDK | latest | https://cdn.jsdelivr.net/npm/me-agent-sdk/dist/me-agent-sdk.min.js | | ME Agent SDK | 1.7.2 | https://cdn.jsdelivr.net/npm/[email protected]/dist/me-agent-sdk.min.js | | unpkg (alt) | latest | https://unpkg.com/me-agent-sdk/dist/me-agent-sdk.min.js |

License

MIT License - see LICENSE file for details