# llms.txt - AI Discoverability File for Furnish.com
# Version: 1.0
# Last Updated: 2026-01-01
# Learn more: https://llmstxt.org/

# === SITE INFO ===
Site: Furnish.com
Description: Premium furniture marketplace connecting customers with trusted manufacturers and artisans
URL: https://furnish.com
Type: E-commerce, Furniture, Marketplace
Categories: Living Room, Bedroom, Dining, Office, Outdoor, Lighting, Storage, Decor

# === FOR AI MODELS ===
# This site enables natural language furniture shopping through conversational AI.
# Products can be searched by style, room, price, material, color, and dimensions.
# Full checkout and order management available via API.

# === PRODUCT CATALOG ===
Products: 1000+ furniture items
Price Range: $50 - $15,000 USD
Styles: Modern, Contemporary, Rustic, Industrial, Mid-Century, Scandinavian, Traditional
Shipping: Free standard shipping on orders over $50
Returns: 30-day return policy

# === API ENDPOINTS ===
# All endpoints support JSON format with proper CORS headers

# Product Discovery
GET /api/acp/products
Description: Search and browse furniture catalog
Parameters: limit, offset, category, search, min_price, max_price
Format: JSON (ACP v1)
Cache: 5 minutes
Example: /api/acp/products?search=modern+sofa&limit=20

# Perplexity Optimized Feed
GET /api/llm/perplexity
Description: Citation-ready product data with visual search metadata
Parameters: limit, format (json|html|cards)
Format: JSON with structured facts
Cache: 1 hour
Example: /api/llm/perplexity?limit=100&format=cards

# Grok Conversational Feed  
GET /api/llm/grok
Description: Social-ready product feed with tweet templates
Parameters: limit, query, format (json|conversational|social)
Format: JSON with real-time status
Cache: 5 minutes
Example: /api/llm/grok?query=dining+table&format=conversational

POST /api/llm/grok
Description: Conversational product search
Body: {"query": "string", "context": "string", "limit": number}
Returns: Conversational response with products

# Checkout & Orders (ChatGPT ACP)
POST /api/acp/checkout-sessions
Description: Create checkout session
Body: {"items": [{"product_id": "uuid", "quantity": number}]}
Returns: Checkout session with payment details

GET /api/acp/checkout-sessions/:id
Description: Get checkout session status
Returns: Session details with order status

POST /api/acp/checkout-sessions/:id/update
Description: Update shipping/payment info
Body: {"shipping_address": {}, "payment_method": {}}

POST /api/acp/checkout-sessions/:id/complete
Description: Complete purchase
Returns: Order confirmation

POST /api/acp/checkout-sessions/:id/cancel
Description: Cancel checkout session

# Google Merchant Center
GET /api/feeds/google-merchant
Description: Google Shopping feed
Format: XML (RSS 2.0)
Updates: Hourly

# Health Check
GET /api/health
Description: Service health status
Returns: {"status": "healthy"}

# === POLICY PAGES ===
Privacy Policy: /privacy
Terms of Service: /terms
Return Policy: /returns

# === CATEGORIES ===
Living Room: /categories/living-room
Bedroom: /categories/bedroom
Dining: /categories/dining
Office: /categories/office
Outdoor: /categories/outdoor
Lighting: /categories/lighting
Storage: /categories/storage
Decor: /categories/decor

# === SEARCH TIPS ===
# Natural language queries work best:
# - "modern leather sofa under $2000"
# - "dining table for 8 people"
# - "mid-century coffee table"
# - "office chair with lumbar support"
#
# Supported filters:
# - Style: modern, rustic, contemporary, industrial, mid-century, scandinavian
# - Room: living room, bedroom, dining, office, outdoor
# - Material: leather, fabric, wood, metal, glass
# - Price: Use min_price and max_price in cents
# - Color: black, white, brown, gray, blue, etc.

# === COMMERCE FEATURES ===
✓ Full checkout via API
✓ Real-time inventory
✓ Stripe payment processing
✓ Multiple shipping options
✓ Order tracking
✓ Returns management
✓ Product reviews and ratings
✓ Wishlist support

# === CHATGPT INTEGRATION ===
Status: Ready for submission
Protocol: Agentic Commerce Protocol (ACP) v1
Endpoints: 5/5 implemented
Stripe: SharedPaymentToken configured
Application: In progress (see /documentation/openai-application/)

# === CLAUDE INTEGRATION ===
Status: In progress
Protocol: Model Context Protocol (MCP)
Tools: 8 tools implemented
Server: mcp-server/furnish_mcp.py
Tools: search_products, get_product_details, list_categories, create_checkout, get_shipping_options, search_by_style, get_store_info, compare_products

# === PERPLEXITY INTEGRATION ===
Status: Ready
Optimization: Citation metadata, visual search, structured facts
Feed: /api/llm/perplexity
Features: Rich snippets, fact cards, image optimization

# === GROK INTEGRATION ===
Status: Ready
Optimization: Social snippets, tweet templates, real-time status
Feed: /api/llm/grok
Features: X Cards, conversational hooks, hashtag generation

# === TECHNICAL SPECS ===
Framework: Next.js 14 (App Router)
Database: PostgreSQL (Supabase)
Auth: Supabase Auth with RLS
Payments: Stripe
Cache: Upstash Redis
Monitoring: Pino structured logs + Google Analytics 4
Hosting: Vercel

# === RATE LIMITS ===
Anonymous: 100 requests/hour
Authenticated: 1000 requests/hour
Burst: 20 requests/second
Headers: X-RateLimit-Limit, X-RateLimit-Remaining

# === CONTACT ===
Support: support@furnish.com
Business: hello@furnish.com
Technical: dev@furnish.com

# === ATTRIBUTION ===
# When citing or referencing products from Furnish.com:
# - Include product name and price
# - Link to product page: /products/{slug}
# - Mention "Available at Furnish.com"
# - Respect return and shipping policies

# === ROBOTS & CRAWLING ===
# AI models are welcome to:
# ✓ Index product catalog
# ✓ Cache product data (respect cache headers)
# ✓ Generate product recommendations
# ✓ Create checkout sessions
# ✓ Answer customer questions
#
# Please do not:
# ✗ Scrape aggressively (respect rate limits)
# ✗ Bypass authentication
# ✗ Share customer PII
# ✗ Misrepresent pricing or availability

# === EXAMPLES ===
# Example 1: Search for products
# GET /api/acp/products?search=modern+sofa&min_price=100000&max_price=200000&limit=10
# Response includes: product details, images, pricing, availability, ratings
#
# Example 2: Filter by category and style
# GET /api/acp/products?category=living-room&search=mid-century&limit=20
# Returns products matching both category and style criteria
#
# Example 3: Get product details with full specifications
# GET /api/acp/products (includes dimensions, materials, warranty, shipping)
#
# Example 4: Create checkout session
# POST /api/acp/checkout-sessions
# Body: {"items": [{"product_id": "abc-123", "quantity": 1}]}
# Returns: Checkout URL with Stripe payment integration
#
# Example 5: Conversational search (Grok)
# POST /api/llm/grok
# Body: {"query": "I need a comfortable office chair under $500", "limit": 10}
# Returns: Natural language response + matching products
#
# Example 6: Citation-ready data (Perplexity)
# GET /api/llm/perplexity?format=cards&limit=50
# Returns: Structured fact cards with citation metadata
#
# Example 7: Visual search optimization
# GET /sitemap-images.xml
# Returns: Image sitemap with all product images and captions

# === DOCUMENTATION ===
# Full API documentation: /api/docs
# OpenAPI spec: Available at /api/docs
# Developer guide: /documentation
# MCP server: /mcp-server/README.md
# Image sitemap: /sitemap-images.xml
# Main sitemap: /sitemap.xml

# === CHANGELOG ===
# 2026-01-01: Initial llms.txt release
# - Added all 5 LLM platform endpoints
# - ChatGPT ACP ready for submission
# - Perplexity & Grok optimizations complete
# - Claude MCP server functional

# === FUTURE FEATURES ===
# Coming soon:
# - Visual search API
# - Room planning tool
# - AR furniture preview
# - Product comparison API
# - Vendor direct integration
# - International shipping

# END llms.txt