Node.js - AdMesh Documentation

Overview

The admesh-weave-node SDK is a backend Node.js package that fetches personalized recommendations from AdMesh. Use it to retrieve recommendations that your LLM can naturally weave into responses. When to use this SDK:

You want to embed recommendations directly in LLM responses (Weave Ad Format)
You need backend control over recommendation fetching
You’re building a custom LLM integration

When NOT to use this SDK:

You only need frontend recommendations (use admesh-ui-sdk instead)
You want a separate recommendations panel (use Tail/Product Format with admesh-ui-sdk)

Quick Start

Install the package:

npm install @admesh/weave-node@latest

Initialize the client:

import { AdMeshClient } from '@admesh/weave-node';

const client = new AdMeshClient({
  apiKey: process.env.ADMESH_API_KEY
});

Fetch recommendations:

const result = await client.getRecommendationsForWeave({
  sessionId: sessionId,
  messageId: messageId,
  query: userQuery
});

if (result.found) {
  const context = result.recommendations
    .map(r => \`- \${r.product_title}: \${r.click_url}\`)
    .join('\\n');
}

Requirements

Node.js 16.x or higher (LTS recommended)
API key from AdMesh dashboard
TypeScript support included
Works with Express, Fastify, Next.js API routes, etc.

Installation Methods

npm (recommended):

npm install @admesh/weave-node@latest

Yarn:

yarn add @admesh/weave-node@latest

pnpm:

pnpm add @admesh/weave-node@latest

Core Concepts

AdMeshClient

The main client for fetching recommendations. Initialize once and reuse across your application.

import { AdMeshClient } from '@admesh/weave-node';

const client = new AdMeshClient({
  apiKey: process.env.ADMESH_API_KEY,  // Required
  apiBaseUrl: process.env.ADMESH_API_BASE_URL  // Optional: defaults to https://api.useadmesh.com
});

Security: Never hardcode your API key. Always use environment variables or a secrets manager.

Session and Message IDs

AdMesh uses IDs to track user interactions:

Session ID: Unique identifier for a user’s conversation session
Message ID: Unique identifier for each individual message/query

// Your application generates these IDs
const sessionId = crypto.randomBytes(16).toString('hex');
const messageId = crypto.randomBytes(7).toString('hex');

Your backend is responsible for generating and managing session and message IDs. The SDK accepts these IDs but does not generate them.

API Methods

getRecommendationsForWeave()

Fetches recommendations for a given query that can be woven into LLM responses.

interface AdMeshSubscriptionOptions {
  sessionId: string;        // Required: Must be provided by frontend
  messageId: string;        // Required: Must be provided by frontend
  query: string;            // Required: User query for contextual recommendations
  latencyBudgetMs?: number; // Optional: Latency budget for auction processing (milliseconds)
  messages?: Array<{ role: string; content: string; id?: string }>;  // Optional: Conversation history
  locale?: string;          // Optional: User language in BCP 47 format (e.g., "en-US")
  geo?: string;             // Optional: User country code in ISO 3166-1 alpha-2 format (e.g., "US")
  userId?: string;          // Optional: Anonymous hashed user ID
  model?: string;           // Optional: AI model identifier (e.g., "gpt-4o")
  platformId?: string;      // Optional: Platform identifier
  platformSurface?: string; // Optional: Platform surface (e.g., "web")
}

interface AdMeshWaitResult {
  found: boolean;                         // Whether recommendations were found
  recommendations?: AdMeshRecommendation[]; // Array of recommendations
  query?: string;                         // Original query
  requestId?: string;                     // Request ID
  error?: string;                         // Error message if not found
}

interface AdMeshRecommendation {
  recommendation_id: string;              // Recommendation identifier
  ad_id: string;                          // Unique ad identifier
  product_id: string;                     // Product ID
  product_title: string;                  // Product/service title
  click_url: string;                      // Tracking URL for clicks
  exposure_url: string;                   // Tracking URL for exposures
  weave_summary?: string;                 // Weave format summary
  tail_summary?: string;                  // Tail format summary
  creative_input: CreativeInput;          // Creative content with product details
  contextual_relevance_score: number;     // Contextual relevance score (0-100)
  // ... and other fields
}

Example:

const result = await client.getRecommendationsForWeave({
  sessionId: 'session-abc123',  // Required: Must be provided by frontend
  messageId: 'msg-xyz789',      // Required: Must be provided by frontend
  query: 'best project management tools',  // Required
  latencyBudgetMs: 10000  // Optional: 10 second latency budget for auction processing
});

if (result.found) {
  console.log(\`Found \${result.recommendations.length} recommendations\`);
  result.recommendations?.forEach(rec => {
    console.log(\`- \${rec.product_title}: \${rec.click_url}\`);
    console.log(\`  Summary: \${rec.weave_summary || rec.creative_input?.short_description}\`);
  });
} else {
  console.log('No recommendations found:', result.error);
}

Integration Example

Here’s a complete example showing how to fetch recommendations and pass them to your LLM:

import express from 'express';
import { AdMeshClient } from '@admesh/weave-node';

const app = express();
app.use(express.json());

const client = new AdMeshClient({
  apiKey: process.env.ADMESH_API_KEY
});

app.post('/api/chat', async (req, res) => {
  const { sessionId, messageId, query } = req.body;

  try {
    // Step 1: Fetch AdMesh recommendations
    const result = await client.getRecommendationsForWeave({
      sessionId: sessionId,  // Required: Must be provided by frontend
      messageId: messageId,  // Required: Must be provided by frontend
      query: query,          // Required
      latencyBudgetMs: 10000  // Optional: 10 second latency budget for auction processing
    });

    // Step 2: Format recommendations for your LLM
    let recommendationsContext = '';
    if (result.found) {
      recommendationsContext = result.recommendations
        .map(r => \`- \${r.product_title}: \${r.click_url}\`)
        .join('\\n');
    }

    // Step 3: Pass to your LLM with recommendations
    const llmPrompt = \`\${query}\\n\\nRecommendations:\\n\${recommendationsContext}\`;
    const llmResponse = await callYourLLM(llmPrompt);

    // Step 4: Return response (LLM has woven AdMesh links into the text)
    res.json({ response: llmResponse });
  } catch (error) {
    console.error('Error:', error);
    res.status(500).json({ error: 'Failed to process request' });
  }
});

app.listen(3000);

Complete Integration: This example shows backend integration only. For frontend integration to detect and track the embedded links, see the Weave Ad Format guide.

Error Handling

Always wrap API calls in try-catch blocks:

try {
  const result = await client.getRecommendationsForWeave({
    sessionId,
    messageId,
    query
  });
  
  if (result.found) {
    // Process recommendations
  } else {
    // No recommendations found for this query
    console.log('No recommendations available');
  }
} catch (error) {
  console.error('Error fetching recommendations:', error.message);
  // Handle error appropriately
}

Common scenarios:

result.found === false: No recommendations available for the query (not an error)
Network errors: Retry with exponential backoff
Invalid API key: Check environment variables

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import type {
  AdMeshClient,
  AdMeshSubscriptionOptions,
  AdMeshWaitResult,
  AdMeshRecommendation
} from '@admesh/weave-node';

All methods and interfaces are fully typed for the best developer experience.

Troubleshooting

No recommendations returned

Possible causes:

Query is too generic (try more specific queries)
No active campaigns match the query
API key is invalid

Solution:

Use more specific queries (e.g., “best CRM for startups” instead of “software”)
Check that your AdMesh account has active campaigns
Verify API key in environment variables

API key errors

Check:

ADMESH_API_KEY is set in environment variables
API key is valid (check dashboard)
No extra whitespace in the key value

Example:

# .env
ADMESH_API_KEY=your-api-key-here

TypeScript errors

Solution:

Ensure TypeScript 4.0 or higher
Import types explicitly: import type from ‘@admesh/weave-node’
Check tsconfig.json includes “moduleResolution”: “node”

Network/timeout errors

Check:

Server has internet access
No firewall blocking outbound requests
Network is stable

Solution:

Implement retry logic with exponential backoff
Check server network configuration

Next Steps

Weave Ad Format Guide: Complete integration guide for embedding recommendations in LLM responses - /platforms/weave-ad-format Frontend SDK: Install admesh-ui-sdk to detect and track embedded links on the frontend - /ui-sdk/installation

You’re ready to start integrating.
Install @admesh/weave-node, fetch recommendations, and pass them to your LLM for natural weaving into responses.

Documentation Index

​Overview

​Quick Start

​Requirements

​Installation Methods

​Core Concepts

​AdMeshClient

​Session and Message IDs

​API Methods

​getRecommendationsForWeave()

​Integration Example

​Error Handling

​TypeScript Support

​Troubleshooting

​No recommendations returned

​API key errors

​TypeScript errors

​Network/timeout errors

​Next Steps

Overview

Quick Start

Requirements

Installation Methods

Core Concepts

AdMeshClient

Session and Message IDs

API Methods

getRecommendationsForWeave()

Integration Example

Error Handling

TypeScript Support

Troubleshooting

No recommendations returned

API key errors

TypeScript errors

Network/timeout errors

Next Steps