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
150 lines • 5.82 kB
TypeScript
/**
* WeaveResponseProcessor
*
* Automatically detects and enhances AdMesh recommendation links in organic LLM responses.
* Handles:
* - Automatic link detection (AdMesh tracking URLs)
* - Label enhancement (<sub>[Ad]</sub> subscript labels)
* - Exposure pixel triggering
* - Streaming response support (MutationObserver)
*/
export interface DetectedLink {
element: HTMLAnchorElement;
href: string;
text: string;
hasAdLabel: boolean;
matchedRecommendation?: {
ad_id: string;
click_url: string;
exposure_url?: string;
};
}
export interface ProcessorConfig {
autoAddLabels?: boolean;
fireExposurePixels?: boolean;
labelStyle?: {
fontSize?: string;
fontWeight?: string;
color?: string;
marginLeft?: string;
};
}
export interface ExposurePixelTarget {
exposureUrl?: string;
adId?: string;
linkElement: HTMLAnchorElement;
}
export declare class WeaveResponseProcessor {
private autoAddLabels;
private fireExposurePixels;
private labelStyle;
private processedLinks;
private mutationObserver;
constructor(config?: ProcessorConfig);
/**
* Get links to process with CSS selector optimization
*
* Optimized approach:
* 1. Use CSS selector to find AdMesh links (97% faster)
* - Matches: api.useadmesh.com/click/*, *.useadmesh.com/click/*
* 2. Fallback to scanning all links if selector finds nothing
* 3. Recommendation validation ensures accuracy
*/
private getLinksToProcess;
/**
* Scan container for ALL links and process only AdMesh recommendation links
*
* This method:
* 1. Scans container for all <a> tags (or uses optimized selector)
* 2. If recommendations provided: Filters to only process links matching recommendation click_url values
* 3. If NO recommendations: Detects links by URL pattern (api.useadmesh.com/click/*)
* 4. Ignores non-AdMesh links (external links, documentation, etc.)
* 5. Adds [Ad] labels to matching links
* 6. Fires exposure pixels for each match
*
* NOTE: When recommendations array is empty, this method detects AdMesh links by URL pattern.
* This is important for Weave Ad Format where the backend embeds links in the LLM response
* and the frontend hook doesn't have access to the recommendations data.
*/
scanAndProcessLinks(container: HTMLElement, recommendations: any[], onExposurePixel?: (target: ExposurePixelTarget) => void): DetectedLink[];
/**
* Check if link already has [Ad] label
*
* This method checks for [Ad] labels on BOTH sides of the link:
* - Previous sibling (left side): [Ad] link text
* - Next sibling (right side): link text [Ad]
*
* This prevents duplicate label rendering when the LLM response
* already contains [Ad] labels in either position.
*/
private hasAdLabel;
/**
* Add [Ad] label as subscript after link with "Why this ad?" tooltip
*
* This method:
* 1. Removes any [Ad] label on the LEFT side (previous sibling)
* 2. Creates a <sub> element with [Ad] text
* 3. Positions it immediately after the link (to the RIGHT)
* 4. Adds tooltip styling with default cursor (not help cursor)
* 5. Adds click handler for tooltip interaction
* 6. Ensures only ONE label per link, always on the RIGHT side
*/
private addAdLabel;
/**
* Remove [Ad] label from the LEFT side (previous sibling) of a link
*
* This ensures that only ONE [Ad] label appears on the RIGHT side,
* removing any duplicate labels that might be on the left.
*/
private removeLeftAdLabel;
/**
* Check if a URL is an AdMesh link
*
* Detects AdMesh links by checking if the URL contains /click/ and matches AdMesh patterns:
* - https://api.useadmesh.com/click/...
* - https://api.admesh.com/click/...
* - http://localhost:8000/click/... (local development)
* - Any URL with /click/ that looks like an AdMesh tracking URL
*/
private isAdMeshLink;
/**
* Extract ad ID from AdMesh click URL
*
* URL format: https://api.useadmesh.com/click/{ad_id}?...
* Returns the ad_id portion or the full URL if extraction fails
*/
private extractAdIdFromUrl;
/**
* Convert AdMesh click URL to exposure URL (Weave Ad Format only)
*
* This is ONLY used for Weave Ad Format where the LLM embeds click URLs in the response text
* and we need to derive the exposure URL for tracking.
*
* Click URL format: https://api.useadmesh.com/click/r/{aid}?aid={aid}&rid={rid}&nonce={nonce}&exp={exp}&sig={sig}
* Exposure URL format: https://api.useadmesh.com/exposure?aid={aid}&rid={rid}&nonce={nonce}&exp={exp}&sig={sig}&cpx={cpx}
*
* This method:
* 1. Parses the click URL to extract the base domain and query parameters
* 2. Replaces the /click/r/{aid} path with /exposure
* 3. Preserves all tracking parameters (aid, rid, nonce, exp, sig)
* 4. Adds cpx=0 as default (actual CPX value is set server-side)
*
* @param clickUrl - The AdMesh click tracking URL
* @returns The corresponding exposure tracking URL, or the original URL if conversion fails
*/
private convertClickUrlToExposureUrl;
/**
* Watch container for new links (streaming support)
*/
watchForNewLinks(container: HTMLElement, recommendations: any[], onExposurePixel?: (target: ExposurePixelTarget) => void): void;
/**
* Stop watching for new links
*/
stopWatching(): void;
/**
* Clear processed links cache
*/
clearCache(): void;
}
export default WeaveResponseProcessor;
//# sourceMappingURL=WeaveResponseProcessor.d.ts.map