Searchspring Integration Assistant

Instructions

Implementation Reference

• src/searchspring-client.ts:52-406 (handler)

  The primary handler function `getApiGuide` that executes the tool logic. It takes an API name and returns comprehensive formatted guidance including endpoints, parameters, code examples, best practices, and documentation links based on a predefined apiGuides object.
  async getApiGuide(params: ApiGuideParams) { const { api } = params; const siteId = this.getSiteIdOrExample(); const apiGuides = { search: { name: "Search API", description: "Full-text product search with filtering, sorting, and pagination", endpoint: `https://${siteId}.a.searchspring.io/api/search/search.json`, requiredParams: ["siteId", "resultsFormat", "userId", "sessionId", "pageLoadId", "domain"], optionalParams: ["q", "page", "resultsPerPage", "filter.*", "bgfilter.*", "sort.*", "redirectResponse", "landingPage", "tag", "includedFacets", "excludedFacets", "disableInlineBanners", "lastViewed", "cart", "shopper"], example: `fetch('https://${siteId}.a.searchspring.io/api/search/search.json?siteId=${siteId}&resultsFormat=json&q=shoes&userId=user123&sessionId=session456&pageLoadId=page789&domain=https://yoursite.com') .then(response => response.json()) .then(data => { console.log('Total results:', data.pagination.totalResults); data.results.forEach(product => { console.log(product.title, product.price); }); }) .catch(error => console.error('Search error:', error));`, useCases: [ "Product catalog search", "Category page filtering", "Search results page", "Faceted navigation" ], bestPractices: [ "Always include tracking parameters: userId (from ssUserId cookie), sessionId (from ssSessionIdNamespace cookie), pageLoadId (UUID v4), domain (window.location.href)", "Use background filters (bgfilter.*) for permanent filtering, not filter.*", "Implement proper error handling with .catch()", "Use debouncing for real-time search (minimum 50ms for autocomplete)", "Include pagination for large result sets", "Use query parameter (q) for all search requests" ] }, autocomplete: { name: "Autocomplete API", description: "Real-time product preview as user types - REQUIRED for autocomplete functionality (not Search API)", endpoint: `https://${siteId}.a.searchspring.io/api/search/autocomplete.json`, requiredParams: ["siteId", "resultsFormat", "userId", "sessionId", "pageLoadId", "domain"], optionalParams: ["q", "resultsPerPage", "page", "filter.*", "bgfilter.*", "sort.*", "redirectResponse", "lastViewed", "cart", "shopper"], example: `const searchInput = document.getElementById('search'); let debounceTimer; searchInput.addEventListener('input', function(e) { clearTimeout(debounceTimer); const query = e.target.value; if (query.length >= 2) { debounceTimer = setTimeout(() => { fetchAutocomplete(query); }, 50); // 50ms debounce as recommended by Searchspring docs } }); function fetchAutocomplete(query) { fetch('https://${siteId}.a.searchspring.io/api/search/autocomplete.json?siteId=${siteId}&resultsFormat=json&q=' + query + '&userId=user123&sessionId=session456&pageLoadId=page789&domain=https://yoursite.com') .then(response => response.json()) .then(data => displaySuggestions(data)) .catch(error => console.error('Autocomplete error:', error)); }`, useCases: [ "Search input suggestions", "Product finder autocomplete", "Category autocomplete", "Brand/attribute suggestions" ], bestPractices: [ "Use debouncing (300ms delay recommended)", "Start suggesting after 2+ characters", "Limit results to 8-10 suggestions", "Handle keyboard navigation (up/down arrows)", "Clear suggestions on blur or escape" ] }, suggest: { name: "Suggest API", description: "Spell correction and alternative search term suggestions", endpoint: `https://${siteId}.a.searchspring.io/api/suggest/query`, requiredParams: ["siteId"], optionalParams: ["q", "language", "suggestionCount", "productCount"], example: `function getSuggestions(query) { fetch('https://${siteId}.a.searchspring.io/api/suggest/query?siteId=${siteId}&q=' + query + '&language=en&suggestionCount=4') .then(response => response.json()) .then(data => { if (data.spellCorrection && data.spellCorrection.corrected) { showSpellCorrection(data.spellCorrection.corrected); } if (data.suggestions && data.suggestions.length > 0) { showAlternativeSuggestions(data.suggestions); } }) .catch(error => console.error('Suggest error:', error)); }`, useCases: [ "Spell correction for misspelled queries", "Alternative search suggestions", "No results page suggestions", "Query expansion" ], bestPractices: [ "Show spell corrections prominently", "Limit suggestions to 3-5 alternatives", "Use on no-results pages", "Consider user's language/locale" ] }, trending: { name: "Trending API", description: "Popular search terms and trending content", endpoint: `https://${siteId}.a.searchspring.io/api/suggest/trending`, requiredParams: ["siteId"], optionalParams: ["limit"], example: `function loadTrendingTerms() { fetch('https://${siteId}.a.searchspring.io/api/suggest/trending?siteId=${siteId}&limit=6') .then(response => response.json()) .then(data => { const container = document.getElementById('trending-terms'); data.terms.forEach(term => { const link = document.createElement('a'); link.href = '/search?q=' + encodeURIComponent(term.query); link.textContent = term.query; container.appendChild(link); }); }) .catch(error => console.error('Trending error:', error)); }`, useCases: [ "Homepage trending searches", "No results page alternatives", "Popular content widgets", "Search inspiration" ], bestPractices: [ "Update trending terms regularly", "Limit to 5-8 terms for better UX", "Use on homepage and no-results pages", "Make terms clickable for easy searching" ] }, recommendations: { name: "Recommendations API", description: "Personalized product recommendations", endpoint: `https://${siteId}.a.searchspring.io/boost/${siteId}/recommend`, requiredParams: ["tags"], optionalParams: ["products", "blockedItems", "categories", "brands", "shopper", "cart", "lastViewed", "limits", "filter.*"], example: `function getRecommendations() { const params = new URLSearchParams({ tags: 'similar-products,trending', products: 'PRODUCT-123', limits: '5,10', shopper: 'user123' }); fetch('https://${siteId}.a.searchspring.io/boost/${siteId}/recommend?' + params) .then(response => response.json()) .then(data => { data.profiles.forEach(profile => { console.log('Profile:', profile.tag); profile.results.forEach(product => { console.log(' -', product.title, product.price); }); }); }) .catch(error => console.error('Recommendations error:', error)); }`, useCases: [ "Product page cross-sells", "Homepage personalization", "Cart page upsells", "Related products" ], bestPractices: [ "Use multiple recommendation types (tags)", "Include personalization data (shopper, cart, lastViewed)", "Block out-of-stock or inappropriate items", "Set reasonable limits per profile" ] }, finder: { name: "Finder API", description: "Faceted search for building product finder interfaces - uses Search API with resultsPerPage=0", endpoint: `https://${siteId}.a.searchspring.io/api/search/search.json`, requiredParams: ["siteId", "resultsPerPage=0"], optionalParams: ["filter.*", "bgfilter.*", "includedFacets", "excludedFacets"], example: `function getFacets() { fetch('https://${siteId}.a.searchspring.io/api/search/search.json?siteId=${siteId}&resultsPerPage=0&filter.category=shoes') .then(response => response.json()) .then(data => { data.facets.forEach(facet => { console.log('Facet:', facet.label); facet.values.forEach(value => { console.log(' -', value.label, '(' + value.count + ')'); }); }); }) .catch(error => console.error('Finder error:', error)); }`, useCases: [ "Product finder widgets", "Advanced filtering interfaces", "Category navigation", "Faceted search" ], bestPractices: [ "Always set resultsPerPage=0 for facets-only", "Use includedFacets to limit returned facets", "Apply background filters for category pages", "Show facet counts for better UX" ] }, beacon: { name: "Beacon API", description: "Advanced event tracking for Personalized Recommendations - NOTE: For basic product tracking use IntelliSuggest ss.track.* methods", endpoint: `https://beacon.searchspring.io/api/event`, requiredParams: ["array of event objects with: category, context, event, id, type"], optionalParams: ["pid (for profile.product.* events)"], example: `function trackEvent(eventType, eventData) { const payload = { type: eventType, category: 'searchspring.recommendations.user-interactions', siteId: '${siteId}', id: 'event-' + Date.now(), userid: 'user123', sessionid: 'session456', data: eventData, context: { website: { trackingCode: '${siteId}' }, page: { url: window.location.href } } }; fetch('https://beacon.searchspring.io/api/event', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }) .then(response => response.json()) .then(data => console.log('Event tracked:', data)) .catch(error => console.error('Tracking error:', error)); }`, useCases: [ "Recommendation impression tracking", "Click-through analytics", "User behavior analytics", "Custom event tracking" ], bestPractices: [ "Use consistent event categories", "Include user and session identifiers", "Batch events when possible", "Handle tracking failures gracefully", "Include relevant context data" ] }, "bulk-index": { name: "Bulk Indexing API", description: "Bulk product data indexing and management", endpoint: `https://index-api.searchspring.net/api/index/feed`, requiredParams: ["feedId"], optionalParams: ["requestedBy"], example: `// Platform-specific bulk indexing implementation // For cart platforms (Shopify, BigCommerce) - use PUT method function triggerCartPlatformIndex(feedId, secretKey) { // Authentication via URL (siteId:secretKey@host) const url = 'https://${siteId}:' + secretKey + '@index-api.searchspring.net/api/index/feed?feedId=' + feedId; fetch(url, { method: 'PUT' // Downloads feed from cart platform }) .then(response => response.json()) .then(data => { if (data.success) { console.log('Bulk index triggered successfully'); } }) .catch(error => console.error('Bulk index error:', error)); } // For custom feeds - use POST with file upload function uploadCustomFeed(feedId, secretKey, feedFile) { const formData = new FormData(); formData.append('feedFile', feedFile); const url = 'https://${siteId}:' + secretKey + '@index-api.searchspring.net/api/index/feed?feedId=' + feedId; fetch(url, { method: 'POST', body: formData // multipart/form-data }) .then(response => response.json()) .then(data => console.log('Feed uploaded:', data)) .catch(error => console.error('Upload error:', error)); }`, useCases: [ "Product catalog updates", "Inventory synchronization", "Scheduled data imports", "Content management integration" ], bestPractices: [ "Use PUT method for cart platforms (Shopify, BigCommerce, etc.)", "Use POST method for custom feed uploads", "Authentication: siteId:secretKey@ in URL (not headers)", "Check status endpoint before triggering new index", "Only one index per hour allowed", "Use multipart/form-data for POST requests" ] } }; const guide = apiGuides[api]; if (!guide) { throw new Error(`Unknown API: ${api}`); } return { content: [ { type: "text", text: this.addSiteIdNote(`# ${guide.name} Implementation Guide ## Overview ${guide.description} **API Endpoint**: ${guide.endpoint} ## Required Parameters ${guide.requiredParams.map(param => `- \`${param}\``).join('\n')} ## Optional Parameters ${guide.optionalParams.map(param => `- \`${param}\``).join('\n')} ## Implementation Example \`\`\`javascript ${guide.example} \`\`\` ## Common Use Cases ${guide.useCases.map(useCase => `- ${useCase}`).join('\n')} ## Best Practices ${guide.bestPractices.map(practice => `- ${practice}`).join('\n')} ## Documentation 📖 **Full API Documentation**: https://docs.searchspring.com/api/${api}/ 🎯 **Help Center**: https://help.searchspring.net/ 🔧 **Implementation Guides**: https://help.searchspring.net/hc/en-us/sections/201185149`), }, ], }; }
• src/index.ts:36-50 (registration)

  Tool registration in the tools array passed to ListToolsRequestSchema handler, defining name, description, and input schema.
  { name: "searchspring_api_guide", description: "Get comprehensive implementation guidance for any Searchspring API", inputSchema: { type: "object", properties: { api: { type: "string", enum: ["search", "autocomplete", "suggest", "trending", "recommendations", "finder", "beacon", "bulk-index"], description: "The Searchspring API to get implementation guidance for", }, }, required: ["api"], }, },
• src/searchspring-client.ts:18-20 (schema)

  TypeScript interface defining the input parameters for the getApiGuide handler, matching the tool's inputSchema enum.
  export interface ApiGuideParams { api: "search" | "autocomplete" | "suggest" | "trending" | "recommendations" | "finder" | "beacon" | "bulk-index"; }
• src/index.ts:140-141 (handler)

  Dispatch handler in the CallToolRequestSchema switch statement that routes tool calls to the SearchspringClient.getApiGuide method.
  case "searchspring_api_guide": return await searchspringClient.getApiGuide(args as any);