Package Exports

admesh-ui-sdk

Readme

AdMesh UI SDK

A React + TypeScript component library for displaying AdMesh product recommendations with built-in tracking and theming support.

🚀 Features

Pre-built UI Components - Ready-to-use components for product recommendations
Built-in Tracking - Automatic click, view, and conversion tracking
Intelligent Layouts - Auto-selects optimal layout based on intent and data
Theme Support - Light/dark mode with custom accent colors
TypeScript First - Full type safety and IntelliSense support
Framework Agnostic - React core, but designed for easy embedding
Responsive Design - Mobile-first responsive components
Accessibility - WCAG 2.1 AA compliant

📦 Installation

npm install admesh-ui-sdk

🎯 Quick Start

import React from 'react';
import { AdMeshLayout } from 'admesh-ui-sdk';
// No CSS import needed! Styles are auto-injected ✨

const recommendations = [
  {
    title: "HubSpot CRM",
    reason: "Perfect for remote teams with excellent collaboration features",
    intent_match_score: 0.92,
    admesh_link: "https://useadmesh.com/track?ad_id=hubspot-123",
    ad_id: "hubspot-123",
    product_id: "hubspot-crm",
    has_free_tier: true,
    trial_days: 14,
    keywords: ["CRM", "Sales", "Marketing"]
  }
];

function App() {
  return (
    <AdMeshLayout
      recommendations={recommendations}
      autoLayout={true}
      showMatchScores={true}
      onProductClick={(adId, admeshLink) => {
        console.log('Product clicked:', { adId, admeshLink });
      }}
    />
  );
}

🧩 Components

Core Components

AdMeshLayout

The main layout component that automatically chooses the best display format.

AdMeshProductCard

Individual product recommendation card.

AdMeshCompareTable

Side-by-side product comparison table.

AdMeshBadge

Reusable badge component.

AdMeshLinkTracker

Wrapper for tracking any clickable element.

💬 Conversational Ad Units

AdMeshConversationalUnit

Smart conversational ad component that adapts to different chat contexts and display modes.

AdMeshConversationSummary

End-of-conversation summary with top recommendations and action buttons.

AdMeshInlineRecommendation

Compact inline recommendation component perfect for chat interfaces.

🎨 Theming

const theme = {
  mode: 'dark', // 'light' | 'dark'
  accentColor: '#8b5cf6', // Custom accent color
};

💬 Conversational Ad Units

Perfect for chat interfaces, AI assistants, and conversational experiences.

Quick Start - Conversational Units

import React from 'react';
import { AdMeshConversationalUnit } from 'admesh-ui-sdk';

const recommendations = [
  {
    title: "HubSpot CRM",
    reason: "Perfect for remote teams with excellent collaboration features",
    intent_match_score: 0.92,
    admesh_link: "https://useadmesh.com/track?ad_id=hubspot-123",
    ad_id: "hubspot-123",
    product_id: "hubspot-crm",
    has_free_tier: true,
    trial_days: 14,
    keywords: ["CRM", "Sales", "Marketing"]
  }
];

function ChatInterface() {
  return (
    <div className="chat-container">
      {/* Your chat messages */}
      <div className="message">I need a CRM for my team</div>

      {/* AdMesh conversational ad unit */}
      <AdMeshConversationalUnit
        recommendations={recommendations}
        config={{
          displayMode: 'inline', // 'inline' | 'minimal' | 'floating' | 'summary'
          context: 'chat',
          maxRecommendations: 3,
          showPoweredBy: true
        }}
        onRecommendationClick={(adId, admeshLink) => {
          window.open(admeshLink, '_blank');
        }}
      />
    </div>
  );
}

Display Modes

Inline Mode

Full recommendations displayed inline with the conversation:

<AdMeshConversationalUnit
  recommendations={recommendations}
  config={{ displayMode: 'inline', context: 'chat' }}
/>

Minimal Mode

Compact display showing match count and top recommendation:

<AdMeshConversationalUnit
  recommendations={recommendations}
  config={{ displayMode: 'minimal', context: 'assistant' }}
/>

Floating Mode

Floating overlay that doesn't interrupt the conversation flow:

<AdMeshConversationalUnit
  recommendations={recommendations}
  config={{ displayMode: 'floating', context: 'support' }}
/>

Summary Mode

End-of-conversation summary with top recommendations:

<AdMeshConversationalUnit
  recommendations={recommendations}
  config={{ displayMode: 'summary', context: 'agent' }}
  conversationSummary="We discussed your CRM needs..."
/>

Individual Conversational Components

AdMeshConversationSummary

Perfect for end-of-conversation summaries:

import { AdMeshConversationSummary } from 'admesh-ui-sdk';

<AdMeshConversationSummary
  recommendations={recommendations}
  conversationSummary="Here's what we discussed and found for you..."
  showTopRecommendations={3}
  onRecommendationClick={(adId, link) => window.open(link)}
  onStartNewConversation={() => startNewChat()}
/>

AdMeshInlineRecommendation

Compact inline recommendations for chat bubbles:

import { AdMeshInlineRecommendation } from 'admesh-ui-sdk';

<AdMeshInlineRecommendation
  recommendation={recommendation}
  compact={true}
  showReason={true}
  onClick={(adId, link) => window.open(link)}
/>

Configuration Options

ConversationalAdConfig

interface ConversationalAdConfig {
  displayMode: 'inline' | 'summary' | 'floating' | 'minimal';
  context: 'chat' | 'assistant' | 'agent' | 'support';
  maxRecommendations?: number;     // Default: 3
  showPoweredBy?: boolean;         // Default: true
  autoShow?: boolean;              // Default: true
  delayMs?: number;                // Default: 0
  position?: 'top' | 'bottom' | 'inline'; // Default: 'inline'
}

Integration Examples

Chat Application

function ChatApp() {
  const [messages, setMessages] = useState([]);
  const [recommendations, setRecommendations] = useState([]);

  const handleUserMessage = async (message) => {
    // Add user message
    setMessages(prev => [...prev, { role: 'user', content: message }]);

    // Get AI response and recommendations
    const response = await getAIResponse(message);
    setMessages(prev => [...prev, { role: 'assistant', content: response.text }]);

    // Show recommendations if available
    if (response.recommendations) {
      setRecommendations(response.recommendations);
    }
  };

  return (
    <div className="chat-container">
      {messages.map((msg, i) => (
        <div key={i} className={`message ${msg.role}`}>
          {msg.content}

          {/* Show recommendations after assistant messages */}
          {msg.role === 'assistant' && recommendations.length > 0 && (
            <AdMeshConversationalUnit
              recommendations={recommendations}
              config={{
                displayMode: 'inline',
                context: 'chat',
                maxRecommendations: 2
              }}
            />
          )}
        </div>
      ))}
    </div>
  );
}

<AdMeshLayout theme={theme} recommendations={recommendations} />

📊 Tracking

All components include built-in view and click tracking:

import { setAdMeshTrackerConfig } from '@admesh/ui-sdk';

setAdMeshTrackerConfig({
  apiBaseUrl: 'https://api.useadmesh.com',
  enabled: true,
  debug: true
});

🔗 Integration with AdMesh SDKs

Works seamlessly with AdMesh backend SDKs:

import { AdMesh } from '@admesh/typescript-sdk';
import { AdMeshLayout } from '@admesh/ui-sdk';

const client = new AdMesh({ apiKey: 'your-api-key' });

async function getRecommendations(query: string) {
  const response = await client.recommend.getRecommendations({
    query,
    format: 'auto'
  });

  return (
    <AdMeshLayout
      recommendations={response.response?.recommendations || []}
      autoLayout={true}
    />
  );
}

📚 API Reference

Types

interface AdMeshRecommendation {
  title: string;
  reason: string;
  intent_match_score: number; // 0-1
  admesh_link: string;
  ad_id: string;
  product_id: string;
  features?: string[];
  has_free_tier?: boolean;
  trial_days?: number;
  pricing?: string;
  keywords?: string[];
}

type IntentType =
  | 'compare_products'
  | 'best_for_use_case'
  | 'trial_demo'
  | 'budget_conscious';

interface AdMeshTheme {
  mode: 'light' | 'dark';
  accentColor?: string;
}

🛠 Development

# Install dependencies
npm install

# Start Storybook
npm run storybook

# Build library
npm run build

# Run linting
npm run lint

📄 License

MIT License

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests and stories
Submit a pull request

📞 Support

Documentation: AdMesh Docs
GitHub Issues: Report a bug
Email: support@useadmesh.com