Skip to content

Me-Protocol/me-agent-sdk

BranchesTags

Repository files navigation

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.

Live Demo GitHub

🚀 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: "user@example.com", // 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/me-agent-sdk@1.0.0/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/me-agent-sdk@1.0.0/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: "user@example.com",
  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: "user@example.com",
        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:

  1. SDK is properly loaded:

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

  2. Email address is provided:

    MeAgent.init({
  emailAddress: "user@example.com", // Required for redemption
  // ... other config
});

  3. Using supported browser - See Browser Support section below

  4. 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:

  1. Build the SDK: npm run build
  2. Run npm run serve to start a local server
  3. Open http://localhost:5500 in your browser
  4. 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: "user@example.com",
          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/me-agent-sdk@1.7.2/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

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

22 tags

Packages

 
 
 

Contributors

Languages