admesh-ui-sdk
Version:
Beautiful, modern React components for displaying AI-powered product recommendations with citation-based conversation ads, auto-triggered widgets, floating chat, conversational interfaces, persistent sidebar, and built-in tracking. Includes zero-code SDK
506 lines • 15.1 kB
TypeScript
export interface EcommerceProduct {
recommendation_id: string;
product_id: string;
external_id: string;
title: string;
price: number;
pricing: string;
url: string;
redirect_url: string;
admesh_link: string;
source: string;
original_price?: number;
discount_percentage?: number;
image_url?: string;
brand?: string;
rating?: number;
review_count?: number;
availability?: string;
description?: string;
shipping_info?: {
free_shipping_over_35: boolean;
standard_rate: number;
two_day_rate: number;
ship_to_store: boolean;
free_ship_to_store: boolean;
};
brand_trust_score?: number;
offer_trust_score?: number;
intent_match_score?: number;
categories?: string[];
features?: string[];
keywords?: string[];
id?: string;
}
export interface Product {
product_id: string;
product_link?: string;
product_click_url?: string;
product_name: string;
product_description: string;
product_price: number | string;
product_discount?: number | string | null;
product_cta_label: string;
product_image_url?: string;
product_features?: string[];
}
export interface CreativeInput {
brand_name: string;
product_name: string;
product_id?: string;
short_description: string;
long_description: string;
context_snippet?: string;
offer_summary?: string;
value_props: string[];
cta_label?: string;
cta_url: string;
assets: {
logo_url?: string;
image_urls?: string[];
primary_image_url?: string;
};
keywords?: string[];
categories?: string[];
allowed_formats?: string[];
preferred_format?: string;
fallback_formats?: string[];
resolved_format?: string;
format_resolution?: {
resolved_format: string;
resolution_reason: string;
attempted_formats: string[];
platform_allowed_formats: string[];
brand_preferred_format?: string;
brand_fallback_formats?: string[];
platform_override?: string;
intersected_fallbacks?: string[];
};
/**
* Bridge headline - question or prompt headline (e.g., "Want to add payments?")
*/
bridge_headline?: string;
/**
* Bridge description - brand description (1 sentence, short) displayed in the UI
*/
bridge_description?: string;
/**
* Bridge prompt (preferred name) - setup prompt or configuration instructions
* for followup sponsored recommendations / bridge ads.
* This is pasted to the input field when CTA is clicked.
*
* NOTE: `bridge_content` is kept for backward compatibility and will be
* treated as the same value when present.
*/
bridge_prompt?: string;
/** @deprecated Use `bridge_prompt` instead. */
bridge_content?: string;
/**
* Followup query - sponsored query string to execute when user selects the follow-up.
* Used in headless follow-up ad format for AI platforms with existing follow-up suggestion UI.
*/
followup_query?: string;
}
export interface AdMeshRecommendation {
recommendation_id: string;
session_id: string;
agent_id: string;
product_id: string;
realtime_offer_id?: string;
brand_id: string;
title: string;
url: string;
admesh_link: string;
exposure_url: string;
click_url: string;
followup_query?: string;
followup_engagement_url?: string;
followup_exposure_url?: string;
contextual_relevance_score: number;
engagement_status: string;
payout_model: string;
payout_amount_usd: number;
cpx_value: number;
cpc_value: number;
cpa_value: number;
creative_input: CreativeInput;
format_resolution?: {
resolved_format: string;
resolution_reason: string;
attempted_formats: string[];
platform_allowed_formats: string[];
brand_preferred_format?: string;
brand_fallback_formats?: string[];
platform_override?: string;
intersected_fallbacks?: string[];
};
timestamps: {
generated_at: string;
exposed_at: string | null;
clicked_at: string | null;
converted_at: string | null;
finalized_at: string | null;
};
created_at: string;
products?: Product[];
product_title?: string;
tail_summary?: string;
product_summary?: string;
weave_summary?: string;
product_logo?: {
url: string;
};
categories?: string[];
trust_score?: number;
model_used?: string;
reason?: string;
image_url?: string;
intent_match_score?: number;
}
export interface AdMeshTheme {
mode: 'light' | 'dark';
accentColor?: string;
primaryColor?: string;
secondaryColor?: string;
backgroundColor?: string;
surfaceColor?: string;
borderColor?: string;
textColor?: string;
textSecondaryColor?: string;
fontFamily?: string;
fontSize?: {
small?: string;
base?: string;
large?: string;
title?: string;
};
borderRadius?: string;
spacing?: {
small?: string;
medium?: string;
large?: string;
};
shadows?: {
small?: string;
medium?: string;
large?: string;
};
icons?: {
expandIcon?: string | React.ReactNode;
collapseIcon?: string | React.ReactNode;
starIcon?: string | React.ReactNode;
checkIcon?: string | React.ReactNode;
arrowIcon?: string | React.ReactNode;
};
gradients?: {
primary?: string;
secondary?: string;
accent?: string;
};
components?: {
card?: React.CSSProperties;
button?: React.CSSProperties;
expandableUnit?: React.CSSProperties;
productCard?: React.CSSProperties;
compareTable?: React.CSSProperties;
citationUnit?: React.CSSProperties;
inlineRecommendation?: React.CSSProperties;
};
disableDefaultStyles?: boolean;
}
export type IntentType = 'compare_products' | 'best_for_use_case' | 'trial_demo' | 'budget_conscious';
export type BadgeType = 'Top Match' | 'Free Tier' | 'AI Powered' | 'Popular' | 'New' | 'Trial Available';
export type BadgeVariant = 'primary' | 'secondary' | 'success' | 'warning';
export type BadgeSize = 'sm' | 'md' | 'lg';
export interface TrackingData {
recommendationId: string;
admeshLink: string;
userId?: string;
sessionId?: string;
productId?: string;
revenue?: number;
conversionType?: string;
metadata?: Record<string, unknown>;
}
export type ConversationalDisplayMode = 'inline' | 'summary' | 'floating' | 'minimal' | 'tail';
export type ConversationContext = 'chat' | 'assistant' | 'agent' | 'support';
export interface ConversationalAdConfig {
displayMode: ConversationalDisplayMode;
context: ConversationContext;
maxRecommendations?: number;
showPoweredBy?: boolean;
autoShow?: boolean;
delayMs?: number;
position?: 'top' | 'bottom' | 'inline';
}
export interface AdMeshTailAdProps {
summaryText: string;
recommendations: AdMeshRecommendation[];
theme?: AdMeshTheme;
className?: string;
style?: React.CSSProperties;
onLinkClick?: (recommendation: AdMeshRecommendation) => void;
sessionId?: string;
}
export type ChatMessageRole = 'user' | 'assistant' | 'system';
export type ChatPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
export type ChatSize = 'sm' | 'md' | 'lg' | 'xl';
export type ChatDisplayMode = 'widget' | 'fullscreen' | 'embedded';
export interface ChatMessage {
id: string;
role: ChatMessageRole;
content: string;
timestamp: Date;
recommendations?: AdMeshRecommendation[];
isTyping?: boolean;
}
export interface AdMeshChatConfig {
position: ChatPosition;
size: ChatSize;
displayMode: ChatDisplayMode;
autoOpen?: boolean;
showWelcomeMessage?: boolean;
welcomeMessage?: string;
placeholder?: string;
maxMessages?: number;
enableTypingIndicator?: boolean;
enableSuggestions?: boolean;
suggestions?: string[];
showInputField?: boolean;
}
export interface AdMeshBadgeProps {
type: BadgeType;
variant?: BadgeVariant;
size?: BadgeSize;
className?: string;
style?: React.CSSProperties;
}
export type AdMeshLayoutType = 'product' | 'inline' | 'tail' | 'ecommerce';
export interface AdMeshLayoutProps {
recommendations: AdMeshRecommendation[];
summaryText?: string;
maxItems?: number;
columns?: 'auto' | number | string;
spacing?: 'sm' | 'md' | 'lg' | 'xl' | string;
showTitle?: boolean;
title?: string;
theme?: AdMeshTheme;
className?: string;
style?: React.CSSProperties;
onLinkClick?: (recommendation: AdMeshRecommendation) => void;
/** Callback to paste content to input field (for bridge format CTA) */
onPasteToInput?: (content: string) => void;
sessionId?: string;
response?: {
layout_type?: string;
tail_summary?: string;
recommendations?: AdMeshRecommendation[];
requires_summary?: boolean;
};
layoutConfig?: {
backgroundColor?: string;
textColor?: string;
primaryColor?: string;
secondaryColor?: string;
accentColor?: string;
borderColor?: string;
borderRadius?: string;
fontSize?: string;
fontFamily?: string;
fontWeight?: string;
lineHeight?: string;
padding?: string;
margin?: string;
shadow?: string;
hoverColor?: string;
linkColor?: string;
customCSS?: string;
darkMode?: boolean;
};
}
export interface AdMeshLinkTrackerProps {
recommendationId: string;
admeshLink: string;
productId?: string;
children: React.ReactNode;
trackingData?: Record<string, unknown>;
className?: string;
style?: React.CSSProperties;
}
export interface UseAdMeshTrackerReturn {
trackClick: (data: TrackingData) => Promise<void>;
trackConversion: (data: TrackingData) => Promise<void>;
trackView: (data: TrackingData) => Promise<void>;
isTracking: boolean;
error: string | null;
}
/**
* PlatformRequest (AIP v1 UCP structure)
*
* This is what SDKs send to the operator via /aip/context endpoint.
* The operator then converts this to ContextRequest (flat structure) before sending to brand agents.
*
* Key structure:
* - Uses extensions.aip for AIP-specific fields (session_id, query_text, messages, etc.)
* - Operator converts PlatformRequest → ContextRequest (removes extensions, moves fields to top-level or context)
* - See ContextRequest type below for the flat structure sent to brand agents
*/
export interface Producer {
agent_id: string;
agent_role: string;
software: string;
software_version: string;
}
export interface Placement {
ad_unit: string;
}
export interface Device {
platform: string;
form_factor: string;
ua_hash?: string;
}
export interface Geography {
country: string;
}
export interface Context {
language: string;
publisher: string;
placement: Placement;
device: Device;
geography: Geography;
}
export interface Identity {
namespace: string;
value_hash: string;
confidence: number;
}
export interface AIPExtensions {
session_id: string;
turn_index: number;
query_text: string;
messages?: Array<{
role: string;
content: string;
id?: string;
}>;
cpx_floor?: number;
}
export interface Extensions {
aip: AIPExtensions;
[key: string]: any;
}
/**
* PlatformRequest - Full UCP structure sent by SDKs to operator
*
* The operator receives this and converts it to ContextRequest:
* - PlatformRequest uses extensions.aip (with query_text, messages)
* - ContextRequest is flat (no extensions, intent.summary replaces query_text)
* - Brand agents receive decision context only (no raw queries, no identity fields)
*/
export interface PlatformRequest {
spec_version: string;
message_id: string;
timestamp: string;
producer: Producer;
context: Context;
identity: Identity;
extensions: Extensions;
}
/**
* ContextRequest (for reference only - SDKs don't use this directly)
*
* This is the flat UCP structure that the operator sends to brand agents.
* The operator converts PlatformRequest (with extensions.aip) to ContextRequest
* (flat structure with no extensions).
*
* Key differences from PlatformRequest:
* - No extensions object - AIP fields moved to top-level or context object
* - session_id, turn_index, latency_budget_ms, allowed_formats, usage_constraints are top-level
* - intent and verticals are in context object
* - No raw queries (query_text) or messages - brand agents receive intent.summary only
* - No identity fields (user_id, hashes) - privacy protection
*/
export interface ContextIntent {
type: 'informational' | 'commercial' | 'transactional';
decision_phase: 'awareness' | 'consideration' | 'compare' | 'decision';
confidence: number;
summary: string;
}
export interface ContextSemantic {
language: string;
geography: Geography;
device: Device;
publisher: string;
placement: Placement;
intent: ContextIntent;
verticals: string[];
}
export interface Consent {
purposes: string[];
permissible_uses: string[];
ttl_seconds: number;
legal_basis: string;
}
export interface UsageConstraints {
disallowed: string[];
}
export interface ContextRequest {
spec_version: string;
message_id: string;
timestamp: string;
producer: Producer;
session_id: string;
turn_index: number;
latency_budget_ms?: number;
allowed_formats: string[];
consent: Consent;
usage_constraints: UsageConstraints;
context: ContextSemantic;
embeddings?: Array<{
id: string;
type: string;
dimension: number;
origin: {
text_window?: string;
on_device?: boolean;
};
}>;
}
export interface AIPContextResponse extends AdMeshRecommendation {
}
export interface AgentRecommendationResponse {
session_id: string;
message_id: string;
recommendations: AdMeshRecommendation[];
}
export interface AdMeshConfig {
trackingEnabled?: boolean;
defaultTheme?: AdMeshTheme;
}
export interface AdMeshChatInputProps {
value: string;
onChange: (value: string) => void;
onSubmit: (message: string) => void;
placeholder?: string;
disabled?: boolean;
suggestions?: string[];
className?: string;
theme?: AdMeshTheme;
onSendMessage?: (message: string) => void;
}
export interface AdMeshChatMessageProps {
message: ChatMessage;
theme?: AdMeshTheme;
className?: string;
style?: React.CSSProperties;
}
export interface AdMeshChatInterfaceProps {
messages: ChatMessage[];
config: AdMeshChatConfig;
theme?: AdMeshTheme;
onSendMessage: (message: string) => void;
className?: string;
isLoading?: boolean;
style?: React.CSSProperties;
}
//# sourceMappingURL=index.d.ts.map