# AI Product Recommender - Integration Guide

> AI Product Recommender is an intelligent vector search and AI reasoning service designed for Shopify stores. It powers natural language semantic recommendations, clarifying followup questions, dynamic form/quiz preselection, and real-time WebSocket event streams.

## Core Documentation & Endpoints

- [Full Integration Guide](https://ai-product-recommender.terry-naturally.sneakpeek.cc/llms-full.txt): Comprehensive Markdown documentation covering the Storefront JavaScript SDK, Shopify App Proxy HMAC authentication, and Asynchronous WebSocket pipelines.
- [Interactive Web Docs](https://ai-product-recommender.terry-naturally.sneakpeek.cc/docs): Responsive developer documentation with copy-paste code snippets and parameter tables.

## Quick API Overview

- `POST /api/v1/async/recommendations`: Asynchronous queued recommendations returning HTTP 202 ticket with dynamic `ws_url`.
- `POST /api/v1/async/followup-questions`: Asynchronous queued followup questions returning HTTP 202 ticket with dynamic `ws_url`.
- `POST /api/v1/async/preselect-options`: Asynchronous queued option preselection returning HTTP 202 ticket with dynamic `ws_url`.
- `GET /api/v1/async/jobs/{jobId}`: Polling status endpoint for asynchronous jobs.

## Storefront JavaScript SDK

- Global Object: `window.LoopAiProductRecommender`
- Readiness Hook: `window.LoopAiProductRecommender.ready().then(recommender => ...)`
- App Proxy Route: `/apps/loop-ai-recommender/*` -> `/api/v1/*`

## Real-Time WebSockets

- Channels: Dedicated job channels (e.g. `recommendations.{jobId}`, `followup-questions.{jobId}`, `preselect-options.{jobId}`)
- Dynamic URL: `ticket.ws_url` returned directly in 202 Accepted response
- Events: `ProductRecommendationCompleted`, `FollowupQuestionCompleted`, `PreselectFormOptionsCompleted`

## Safety & Prompt Guard Policy Enforcement

- Policy Refusals: Requests violating merchant safety or compliance instructions return a domain error payload `{ "errors": [ { "type": "PromptGuard", "message": "..." } ] }`.
- Domain Refusal Contract: Safety guard blocks resolve with status `completed` (HTTP 200 via SDK/proxy) containing domain errors rather than transport/system failures.