hexagon-ai

Hexagon AI SDK

Make your website discoverable by ChatGPT, Perplexity, Claude, and other AI platforms.

🚀 Quick Start

Express / Node.js (Recommended)

npm install hexagon-ai

const express = require('express');
const Hexagon = require('hexagon-ai');

const app = express();

// Initialize Hexagon
const hexagon = new Hexagon({
  merchantId: 'your-merchant-id',  // Get from dashboard.joinhexagon.com
  apiKey: 'your-api-key'
});

// Add blog routes to your website
app.use('/hexagon-ai', hexagon.blogRoutes());

// Generate sitemap for AI crawlers
app.use('/sitemap.xml', hexagon.sitemapRoutes());

app.listen(3000);

That's it! Your AI-generated blogs are now live on your website.

Next.js Setup

Next.js requires additional files for routing. See NEXTJS_SETUP.md for complete setup guide.

You'll need to create:

1. middleware.ts - Analytics tracking
2. app/api/hexagon-blog/[slug]/route.ts - API route to fetch blogs
3. app/hexagon-ai/[slug]/page.tsx - Page component to display blogs

Time to setup: 5 minutes (copy/paste files from guide)

🎯 How It Works

1. We Generate Blogs for Your Products

• Hexagon automatically creates SEO-optimized blog articles about your products
• Blogs are stored in our database (not yours)
• New blogs are generated daily based on your product catalog

2. Blogs Are Accessible on YOUR Website

When you install the SDK, blog URLs automatically work on your domain:

https://yourwebsite.com/hexagon-ai/best-running-shoes-2024
https://yourwebsite.com/hexagon-ai/wireless-headphones-buying-guide
https://yourwebsite.com/hexagon-ai/yoga-mat-comparison
... (thousands more)

3. AI Crawlers Discover Your Content

Sitemap Discovery:

<!-- https://yourwebsite.com/sitemap.xml -->
<urlset>
  <url><loc>https://yourwebsite.com/hexagon-ai/best-running-shoes-2024</loc></url>
  <url><loc>https://yourwebsite.com/hexagon-ai/wireless-headphones-buying-guide</loc></url>
  <!-- ... all your blogs -->
</urlset>

What Happens:

1. 🤖 ChatGPT/Perplexity crawler visits yourwebsite.com/sitemap.xml
2. 🗺️ Crawler discovers 1,000+ blog URLs
3. 📄 Crawler visits yourwebsite.com/hexagon-ai/best-running-shoes-2024
4. ⚡ SDK fetches blog from Hexagon database (100ms)
5. 💾 SDK caches result for 24 hours
6. 📝 Crawler sees clean markdown content
7. 🎉 Your products appear in AI search results!

4. Visitors See Rich HTML Content

When a human visitor accesses the same URL:

• ✅ Beautiful HTML formatting
• ✅ Product images and links
• ✅ SEO metadata
• ✅ Fast response (served from cache)

When an AI crawler accesses the URL:

• ✅ Clean markdown format
• ✅ Structured data (Schema.org)
• ✅ Easy to parse and cite
• ✅ Optimized for AI understanding

📖 Complete Setup Guide

Step 1: Install SDK

npm install hexagon-ai

Step 2: Get Your Credentials

1. Sign up at dashboard.joinhexagon.com
2. Upload your product catalog
3. Copy your Merchant ID and API Key

Step 3: Add to Your Server

const express = require('express');
const Hexagon = require('hexagon-ai');

const app = express();

const hexagon = new Hexagon({
  merchantId: process.env.HEXAGON_MERCHANT_ID,
  apiKey: process.env.HEXAGON_API_KEY
});

// Mount blog routes
app.use('/hexagon-ai', hexagon.blogRoutes());

// Mount sitemap
app.use('/sitemap.xml', hexagon.sitemapRoutes());

app.listen(3000);

Step 4: Verify It Works

# Test a blog URL
curl https://yourwebsite.com/hexagon-ai/best-running-shoes-2024

# Check sitemap
curl https://yourwebsite.com/sitemap.xml

# Test markdown format (what AI crawlers see)
curl https://yourwebsite.com/hexagon-ai/best-running-shoes-2024.md

🎨 Customization Options

Custom Blog Route

// Use a different path (default is /blog)
const hexagon = new Hexagon({
  merchantId: 'your-id',
  apiKey: 'your-key',
  customRoutes: {
    blogs: '/articles'  // Now accessible at /articles/:slug
  }
});

app.use('/articles', hexagon.blogRoutes());

Custom Cache Duration

const hexagon = new Hexagon({
  merchantId: 'your-id',
  apiKey: 'your-key',
  cacheTTL: 3600000  // 1 hour (default is 24 hours)
});

Add Your Own Styling

app.get('/blog/:slug', async (req, res) => {
  const { slug } = req.params;
  
  // Fetch blog from Hexagon
  const blog = await hexagon.getBlog(slug);
  
  // Wrap in your custom template
  res.send(`
    <!DOCTYPE html>
    <html>
    <head>
      <title>${blog.title}</title>
      <link rel="stylesheet" href="/styles.css">
    </head>
    <body>
      <header>Your Header</header>
      <main>
        ${blog.content}
      </main>
      <footer>Your Footer</footer>
    </body>
    </html>
  `);
});

🔧 Advanced Usage

Blog List Page

Create a blog index showing all your articles:

app.get('/blog', async (req, res) => {
  const page = parseInt(req.query.page) || 1;
  
  // Get paginated blog list
  const blogs = await hexagon.listBlogs({ page, limit: 20 });
  
  res.send(`
    <h1>Our Blog</h1>
    <ul>
      ${blogs.map(blog => `
        <li>
          <a href="https://github.com/hexagon-labs/server-sdk/blob/HEAD/blog/${blog.slug}">${blog.title}</a>
          <p>${blog.excerpt}</p>
        </li>
      `).join('')}
    </ul>
    <a href="https://github.com/hexagon-labs/server-sdk/blob/HEAD/blog?page=${page + 1}">Next Page</a>
  `);
});

Manual API Access

const hexagon = new Hexagon({ merchantId: 'id', apiKey: 'key' });

// Get single blog
const blog = await hexagon.getBlog('best-running-shoes-2024');

// List all blog slugs (lightweight)
const slugs = await hexagon.listBlogSlugs();

// Get blog metadata
const metadata = await hexagon.getBlogMetadata('some-slug');

📊 Understanding Blog Storage

Where Are Blogs Stored?

In Hexagon's Database (not your server):

• ✅ No storage needed on your end
• ✅ Automatic backups
• ✅ Always up-to-date
• ✅ Scales to millions of blogs

How Are Blogs Served?

Customer visits: yourwebsite.com/blog/article-1
         ↓
    SDK checks cache
         ↓
   Cache miss? Fetch from Hexagon API (100ms)
         ↓
    Cache for 24 hours
         ↓
   Serve to visitor (5ms next time)

Performance:

• First visit: 100ms (fetches from Hexagon)
• Cached visits: 5ms (served from memory)
• Cache duration: 24 hours (configurable)

🤖 AI Crawler Optimization

What AI Crawlers See

When ChatGPT, Perplexity, or Claude visit your blog:

1. Markdown Format (.md extension)

# Best Running Shoes 2024

When choosing running shoes, consider these factors:

1. **Cushioning** - Protects joints during impact
2. **Fit** - Prevents blisters and injuries
3. **Durability** - Quality materials last longer

## Top Picks

### Premium Running Shoes
Our premium shoes feature advanced cushioning...

2. Structured Data (Schema.org)

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Best Running Shoes 2024",
  "author": { "@type": "Organization", "name": "Your Company" },
  "datePublished": "2024-11-10",
  "keywords": ["running shoes", "marathon", "fitness"]
}

3. Clean HTML (for regular crawlers)

<article>
  <h1>Best Running Shoes 2024</h1>
  <p>When choosing running shoes...</p>
</article>

📈 Scaling to 10,000+ Blogs

Question: What if I have 10,000 blogs?

Answer: No problem! The SDK is designed for scale.

How It Handles Large Catalogs:

1. Sitemap Lists URLs (not full content)

   • 10,000 URLs = ~500KB
   • Fast to generate and parse

2. Blogs Fetched On-Demand

   • Only fetches blogs that are actually visited
   • Not all 10,000 blogs are loaded at once

3. Smart Caching

   • Popular blogs stay in cache
   • Reduces API calls by 99%

4. Pagination Support

   • Blog list pages load 20 at a time
   • No performance issues

Example Traffic Pattern:

10,000 blogs in catalog
  ↓
100 popular blogs = 90% of traffic
  ↓
Cached after first visit
  ↓
Result: ~10 API calls/day (rest served from cache)

🛠️ Troubleshooting

Blogs Not Showing Up?

1. Check your credentials:

const hexagon = new Hexagon({
  merchantId: 'correct-id',  // Check dashboard
  apiKey: 'correct-key'      // Check dashboard
});

2. Verify routes are mounted:

app.use('/hexagon-ai', hexagon.blogRoutes());  // ✅
// Not: app.get('/blog', ...)              // ❌

3. Test API connection:

const blogs = await hexagon.listBlogSlugs();
console.log(`Found ${blogs.length} blogs`);

Slow Response Times?

1. Check cache settings:

const hexagon = new Hexagon({
  merchantId: 'id',
  apiKey: 'key',
  cacheTTL: 86400000  // 24 hours (default)
});

2. Monitor cache hits:

hexagon.on('cache-hit', (slug) => {
  console.log(`Cache hit for ${slug}`);
});

hexagon.on('cache-miss', (slug) => {
  console.log(`Cache miss for ${slug} - fetching from API`);
});

Sitemap Not Generated?

// Make sure sitemap route is mounted
app.use('/sitemap.xml', hexagon.sitemapRoutes());

// Or use custom path
app.get('/ai-sitemap.xml', hexagon.sitemapRoutes());

🎯 Best Practices

1. Use Environment Variables

// .env file
HEXAGON_MERCHANT_ID=your-merchant-id
HEXAGON_API_KEY=your-api-key

// server.js
require('dotenv').config();

const hexagon = new Hexagon({
  merchantId: process.env.HEXAGON_MERCHANT_ID,
  apiKey: process.env.HEXAGON_API_KEY
});

2. Add Error Handling

app.get('/blog/:slug', async (req, res) => {
  try {
    const blog = await hexagon.getBlog(req.params.slug);
    res.send(blog.content);
  } catch (error) {
    if (error.status === 404) {
      res.status(404).send('Blog not found');
    } else {
      res.status(500).send('Server error');
    }
  }
});

3. Submit Sitemap to Search Engines

After setup, submit your sitemap:

• Google Search Console: https://search.google.com/search-console
• Bing Webmaster Tools: https://www.bing.com/webmasters

Your sitemap URL: https://yourwebsite.com/sitemap.xml

4. Monitor Performance

const hexagon = new Hexagon({
  merchantId: 'id',
  apiKey: 'key',
  debug: true  // Logs cache hits/misses and API calls
});

📚 API Reference

new Hexagon(config)

Initialize the SDK.

Parameters:

• config.merchantId (required): Your merchant ID from dashboard
• config.apiKey (required): Your API key from dashboard
• config.cacheTTL (optional): Cache duration in ms (default: 86400000 = 24h)
• config.debug (optional): Enable debug logging (default: false)
• config.customRoutes (optional): Custom route paths

hexagon.blogRoutes()

Returns Express router for blog serving.

Usage:

app.use('/hexagon-ai', hexagon.blogRoutes());

Routes Created:

• GET /:slug - Serve blog as HTML
• GET /:slug.md - Serve blog as Markdown (for AI crawlers)

hexagon.sitemapRoutes()

Returns Express router for sitemap generation.

Usage:

app.use('/sitemap.xml', hexagon.sitemapRoutes());

hexagon.getBlog(slug)

Fetch single blog.

Returns: Promise

Example:

const blog = await hexagon.getBlog('best-running-shoes-2024');
console.log(blog.title, blog.content);

hexagon.listBlogSlugs()

Get list of all blog slugs (lightweight).

Returns: Promise<Array<{slug: string, updated_at: string}>>

Example:

const slugs = await hexagon.listBlogSlugs();
console.log(`Total blogs: ${slugs.length}`);

hexagon.listBlogs(options)

Get paginated blog list.

Parameters:

• options.page (optional): Page number (default: 1)
• options.limit (optional): Items per page (default: 20)

Returns: Promise<Array

Example:

const blogs = await hexagon.listBlogs({ page: 1, limit: 20 });

🚀 Next Steps

1. ✅ Install SDK: npm install hexagon-ai
2. ✅ Get credentials from dashboard.joinhexagon.com
3. ✅ Add 3 lines of code to your server
4. ✅ Submit sitemap to Google/Bing
5. ✅ Watch your products appear in AI search results!

📞 Support

• Documentation: docs.joinhexagon.com
• Dashboard: dashboard.joinhexagon.com
• Email: support@joinhexagon.com
• Issues: github.com/hexagon-ai/sdk/issues

📄 License

MIT License - see LICENSE file for details

Made with ❤️ by Hexagon AI