> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useadmesh.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js

> Install and configure admesh-weave-node for backend recommendation fetching

## 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:

```bash theme={null}
npm install @admesh/weave-node@latest
```

Initialize the client:

```typescript theme={null}
import { AdMeshClient } from '@admesh/weave-node';

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

Fetch recommendations:

```typescript theme={null}
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):

```bash theme={null}
npm install @admesh/weave-node@latest
```

Yarn:

```bash theme={null}
yarn add @admesh/weave-node@latest
```

pnpm:

```bash theme={null}
pnpm add @admesh/weave-node@latest
```

***

## Core Concepts

### AdMeshClient

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

```typescript theme={null}
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

```typescript theme={null}
// 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.

```typescript theme={null}
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:**

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:**

```bash theme={null}
# .env
ADMESH_API_KEY=your-api-key-here
```

### TypeScript errors

**Solution:**

* Ensure TypeScript 4.0 or higher
* Import types explicitly: import type { Recommendation } 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.