cartmate
v1.0.1
Published
Framework-agnostic conversational shopping assistant
Downloads
11
Maintainers
don_uniquenessReadme
🛒 CartMate - Conversational Shopping Assistant
CartMate is a framework-agnostic, AI-powered shopping assistant widget that can be dropped into any e-commerce website (WordPress, Shopify, React, Vue, HTML). It helps users find products, get recommendations, and manage their cart through a natural chat interface.
🚀 Features at a Glance
- Conversational Search: Users type "red sneakers under $50" -> CartMate filters and shows results.
- Smart Recommendations: "What goes with this?" suggests related items based on cart contents.
- Universal Compatibility: Built as a standard Web Component (
<cart-mate>). Works everywhere. - Zero-Dependency: No React, Vue, or jQuery required on the host site.
- Themable: customized via CSS variables to match your brand.
📦 Installation
Option 1: CDN (Easiest)
Add this to your HTML <body> or footer:
<!-- 1. Load the Widget -->
<script src="https://unpkg.com/@cartmate/widget@latest/dist/cartmate.umd.cjs"></script>
<!-- 2. Configure & Place -->
<script>
window.__CARTMATE_CONFIG__ = {
apiKey: "YOUR_API_KEY",
greeting: "Hi! I'm your store assistant. 🛍️",
endpoints: {
search: "https://your-store.com/api/search",
addToCart: "https://your-store.com/api/cart",
recommendations: "https://your-store.com/api/recommendations",
},
theme: {
primaryColor: "#6200ea",
},
};
</script>
<cart-mate></cart-mate>Option 2: NPM (For Bundlers)
npm install @cartmate/widgetIn your app entry point (e.g., main.js or App.jsx):
import "@cartmate/widget/dist/cartmate.js";
// The <cart-mate> element is now registered and ready to use!⚙️ Configuration
The window.__CARTMATE_CONFIG__ object controls everything.
| Option | Type | Description |
| :-------------------------- | :------- | :------------------------------------------------- |
| endpoints | Object | Required. Links to your backend APIs. |
| endpoints.search | String | URL for product search (POST request). |
| endpoints.addToCart | String | URL to add items to cart (POST). |
| endpoints.recommendations | String | URL for AI recommendations (POST). |
| theme | Object | Custom colors and positioning. |
| theme.primaryColor | String | Main brand color (hex code). |
| theme.position | String | "bottom-right" (default) or "bottom-left". |
| greeting | String | Initial message shown to users. |
| quickActions | Array | Quick suggestion buttons (e.g., "On Sale", "New"). |
Backend API Requirements
Your endpoints should accept JSON and return results in a standard format. See Integration Guide for full API specs.
🛠️ Development & Simulation
Want to modify the widget source code?
Clone & Install:
git clone https://github.com/your-repo/cartmate.git cd cartmate npm installRun Dev Server:
npm run devOpens a demo page at
http://localhost:5173.Build for Production:
npm run buildCreates optimized files in
dist/.Simulate Production: A convenient simulation page exists to test the built widget against the local API:
- Open
simulation/index.htmlin your browser. - Ensure
npm run devis running (to serve the API).
- Open
📚 Documentation Links
- Deployment Guide: How to publish to NPM or host on Netlify.
- Integration Guide: Deep dive into API schemas and framework-specific setups (React, Vue, WordPress).
- Walkthrough: Project architecture and feature overview.