@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/ecommerce/agentic-commerce-protocol.md

@@ -0,0 +1,203 @@
+# Agentic Commerce Protocol (ACP)
+
+> Open standard for AI agents to discover products, initiate checkouts, and complete purchases programmatically.
+
+**When to use:** Building any e-commerce system that should be accessible to AI shopping agents (ChatGPT, Perplexity Shopping, Claude), or integrating AI purchasing capabilities into your own agents.
+**Stack:** Any web framework + Stripe (ACP is Stripe-native)
+
+---
+
+## What Is ACP?
+
+Traditional e-commerce: **Human browses website → clicks "Buy" → enters payment**
+Agentic commerce: **AI agent discovers product via API → negotiates terms → completes purchase programmatically**
+
+ACP defines a standard protocol so:
+1. Merchants expose product catalogs in a machine-readable format
+2. AI agents can browse, compare, and purchase without scraping HTML
+3. Payment credentials are shared securely via SharedPaymentTokens (SPT)
+4. Merchants retain full control of branding, pricing, and fulfillment
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────┐     ┌─────────────────────────┐
+│     AI Shopping Agent    │     │      Merchant Server     │
+│ (ChatGPT, your agent)   │     │                          │
+│                          │     │ ┌──────────────────────┐ │
+│ 1. Discover products ────┼────▶│ │ ACP Product Catalog  │ │
+│                          │     │ │ /acp/products        │ │
+│ 2. Get pricing/terms ◀───┼─────│ │ /acp/pricing         │ │
+│                          │     │ └──────────────────────┘ │
+│ 3. Initiate checkout ────┼────▶│ ┌──────────────────────┐ │
+│    (with SPT)            │     │ │ ACP Checkout          │ │
+│                          │     │ │ /acp/checkout         │ │
+│ 4. Confirm order ◀───────┼─────│ │ → Stripe payment     │ │
+│                          │     │ └──────────────────────┘ │
+└─────────────────────────┘     └─────────────────────────┘
+```
+
+---
+
+## For Merchants: Making Your Store Agent-Accessible
+
+### Step 1: Product Catalog Endpoint
+
+Expose your products in a structured, machine-readable format:
+
+```javascript
+// GET /acp/products
+router.get('/acp/products', async (req, res) => {
+  const { category, query, limit = 20, offset = 0 } = req.query;
+
+  const products = await db.query(
+    `SELECT id, name, description, price, currency, images, category,
+            availability, variants, attributes
+     FROM products
+     WHERE is_active = true
+     ${category ? 'AND category = $1' : ''}
+     ORDER BY name
+     LIMIT $${category ? 2 : 1} OFFSET $${category ? 3 : 2}`,
+    category ? [category, parseInt(limit), parseInt(offset)]
+             : [parseInt(limit), parseInt(offset)]
+  );
+
+  res.json({
+    products: products.rows.map(p => ({
+      id: p.id,
+      name: p.name,
+      description: p.description,
+      price: { amount: p.price, currency: p.currency },
+      images: p.images,
+      category: p.category,
+      availability: p.availability,
+      variants: p.variants,
+      attributes: p.attributes,  // size, color, material, etc.
+    })),
+    pagination: { limit: parseInt(limit), offset: parseInt(offset), total: products.rowCount },
+  });
+});
+```
+
+### Step 2: Checkout Endpoint
+
+Allow agents to initiate purchases programmatically:
+
+```javascript
+// POST /acp/checkout
+router.post('/acp/checkout', async (req, res) => {
+  const { items, shipping_address, payment_token } = req.body;
+
+  // Validate items and get current prices
+  const validated = await validateAndPriceItems(items);
+  if (!validated.valid) {
+    return res.status(400).json({ error: validated.errors });
+  }
+
+  // Create Stripe Checkout Session
+  const session = await stripe.checkout.sessions.create({
+    line_items: validated.lineItems,
+    mode: 'payment',
+    shipping_address_collection: shipping_address ? undefined : { allowed_countries: ['US'] },
+    success_url: `${process.env.BASE_URL}/order/confirmed/{CHECKOUT_SESSION_ID}`,
+    cancel_url: `${process.env.BASE_URL}/order/cancelled`,
+    metadata: { source: 'acp', agent_id: req.headers['x-agent-id'] || 'unknown' },
+  });
+
+  res.json({
+    checkout_url: session.url,
+    session_id: session.id,
+    expires_at: new Date(session.expires_at * 1000).toISOString(),
+    total: validated.total,
+  });
+});
+```
+
+### Step 3: Agent-Readable Product Schema
+
+Use structured data (JSON-LD) to make products discoverable:
+
+```html
+<!-- Add to product pages for web-crawling agents -->
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "Product Name",
+  "description": "Product description",
+  "offers": {
+    "@type": "Offer",
+    "price": "29.99",
+    "priceCurrency": "USD",
+    "availability": "https://schema.org/InStock"
+  }
+}
+</script>
+```
+
+---
+
+## For AI Agent Developers: Consuming ACP
+
+```javascript
+// Example: AI agent purchasing from an ACP-enabled merchant
+async function purchaseProduct(merchantUrl, productId, quantity) {
+  // 1. Get product details
+  const product = await fetch(`${merchantUrl}/acp/products/${productId}`);
+  const productData = await product.json();
+
+  // 2. Initiate checkout
+  const checkout = await fetch(`${merchantUrl}/acp/checkout`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Agent-Id': 'your-agent-id',
+    },
+    body: JSON.stringify({
+      items: [{ product_id: productId, quantity }],
+    }),
+  });
+  const checkoutData = await checkout.json();
+
+  // 3. Return checkout URL for user to complete payment
+  return {
+    checkout_url: checkoutData.checkout_url,
+    total: checkoutData.total,
+    expires_at: checkoutData.expires_at,
+  };
+}
+```
+
+---
+
+## Design Principles
+
+1. **Merchants retain control** — pricing, branding, fulfillment stay with the merchant
+2. **Agents are intermediaries** — they help users find and purchase, not bypass the merchant
+3. **Structured over scraped** — API endpoints beat HTML parsing for reliability
+4. **Payment security** — use Stripe's tokenization, never handle raw card data
+5. **Agent identification** — track which AI agent initiated a purchase for analytics
+
+---
+
+## Integration with Stripe Agent Toolkit
+
+For existing Stripe merchants, ACP integration can be minimal:
+
+```bash
+npm install @stripe/agent-toolkit
+```
+
+The toolkit already provides tools for creating products, prices, payment links, and checkout sessions — all ACP needs is a structured catalog endpoint on top of this.
+
+---
+
+## Sources
+
+- Stripe/OpenAI: "Developing an open standard for agentic commerce" (October 2025)
+- GitHub: agentic-commerce-protocol/agentic-commerce-protocol (Apache 2.0)
+- Stripe: "Agentic Commerce Suite" blog post (2025)
+- commercetools: "7 AI Trends Shaping Agentic Commerce" (2025)
+- Envive AI: "46 E-Commerce AI Statistics" (2025)

package/skills-library/ecommerce/cart-abandonment-recovery.md

@@ -0,0 +1,236 @@
+# Cart Abandonment Recovery Patterns
+
+> Exit-intent detection, recovery emails, and session analytics to recover 15-25% of abandoned cart revenue.
+
+**When to use:** Any e-commerce system with a checkout flow. Global cart abandonment rate is 70.22% ($260B recoverable US revenue annually).
+**Stack:** Node.js/Express, React, email service (SendGrid/Resend), optional analytics
+
+---
+
+## Why Carts Are Abandoned
+
+| Reason | % of Abandonments | Fix |
+|--------|-------------------|-----|
+| Extra costs too high (shipping, tax) | 49% | Show total upfront |
+| Required account creation | 24% | Guest checkout |
+| Complex checkout process | 18% | Reduce steps |
+| Couldn't calculate total | 17% | Show running total |
+| Didn't trust site with card | 17% | Trust signals |
+| Delivery too slow | 16% | Show delivery date |
+| Website errors | 13% | Test checkout flow |
+
+---
+
+## Pattern 1: Recovery Email Sequence
+
+### Trigger: Cart inactive for X minutes
+
+```javascript
+// Check for abandoned carts (run every 15 minutes via cron)
+async function findAbandonedCarts() {
+  const abandoned = await db.query(
+    `SELECT c.*, u.email, u.first_name
+     FROM carts c
+     JOIN users u ON u.id = c.user_id
+     WHERE c.status = 'active'
+       AND c.updated_at < NOW() - INTERVAL '1 hour'
+       AND c.updated_at > NOW() - INTERVAL '7 days'
+       AND c.id NOT IN (SELECT cart_id FROM cart_recovery_emails WHERE sent_at > NOW() - INTERVAL '24 hours')
+       AND (SELECT COUNT(*) FROM cart_items WHERE cart_id = c.id) > 0`,
+  );
+  return abandoned.rows;
+}
+
+// Send recovery sequence
+async function sendRecoveryEmail(cart, emailNumber) {
+  const items = await getCartItems(cart.id);
+  const templates = {
+    1: { // 1 hour after abandonment
+      subject: `You left something behind`,
+      delay: '1 hour',
+      includeDiscount: false,
+    },
+    2: { // 24 hours
+      subject: `Still thinking about it?`,
+      delay: '24 hours',
+      includeDiscount: false,
+    },
+    3: { // 72 hours — include incentive
+      subject: `10% off your cart — just for you`,
+      delay: '72 hours',
+      includeDiscount: true,
+      discountPercent: 10,
+    },
+  };
+
+  const template = templates[emailNumber];
+
+  await sendEmail({
+    to: cart.email,
+    subject: template.subject,
+    template: 'cart-recovery',
+    data: {
+      firstName: cart.first_name,
+      items: items.map(i => ({
+        name: i.name,
+        image: i.image_url,
+        price: i.price,
+        quantity: i.quantity,
+      })),
+      cartUrl: `${process.env.BASE_URL}/cart?recover=${cart.id}`,
+      discount: template.includeDiscount ? {
+        code: await generateDiscountCode(cart.user_id, template.discountPercent),
+        percent: template.discountPercent,
+        expires: '48 hours',
+      } : null,
+      subtotal: items.reduce((sum, i) => sum + i.price * i.quantity, 0),
+    },
+  });
+
+  await db.query(
+    `INSERT INTO cart_recovery_emails (cart_id, email_number, sent_at) VALUES ($1, $2, NOW())`,
+    [cart.id, emailNumber]
+  );
+}
+```
+
+### Recovery Email Schema
+
+```sql
+CREATE TABLE cart_recovery_emails (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  cart_id UUID NOT NULL REFERENCES carts(id),
+  email_number INTEGER NOT NULL,  -- 1, 2, or 3
+  sent_at TIMESTAMP DEFAULT NOW(),
+  opened_at TIMESTAMP,
+  clicked_at TIMESTAMP,
+  converted BOOLEAN DEFAULT false
+);
+
+CREATE INDEX idx_recovery_cart ON cart_recovery_emails(cart_id);
+```
+
+---
+
+## Pattern 2: Exit-Intent Detection (Client-Side)
+
+```javascript
+// Detect when user is about to leave checkout
+function useExitIntent(onExitIntent) {
+  useEffect(() => {
+    const handleMouseLeave = (e) => {
+      // Mouse moves toward browser chrome (top of viewport)
+      if (e.clientY <= 0) {
+        onExitIntent();
+      }
+    };
+
+    // Desktop: mouse leaving viewport
+    document.addEventListener('mouseleave', handleMouseLeave);
+
+    // Mobile: detect back button or tab switch
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === 'hidden') {
+        onExitIntent();
+      }
+    };
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+
+    return () => {
+      document.removeEventListener('mouseleave', handleMouseLeave);
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
+    };
+  }, [onExitIntent]);
+}
+
+// Usage in checkout component
+function Checkout() {
+  const [showExitModal, setShowExitModal] = useState(false);
+
+  useExitIntent(() => {
+    if (!showExitModal) {
+      setShowExitModal(true);
+      // Track event
+      analytics.track('exit_intent_triggered', { page: 'checkout' });
+    }
+  });
+
+  return (
+    <>
+      <CheckoutForm />
+      {showExitModal && (
+        <Modal onClose={() => setShowExitModal(false)}>
+          <h2>Wait! Your cart is saved</h2>
+          <p>Complete your purchase now or we'll email you a reminder.</p>
+          <Button onClick={() => setShowExitModal(false)}>Continue Checkout</Button>
+          <Button variant="secondary" onClick={saveCartAndEmail}>
+            Email me my cart
+          </Button>
+        </Modal>
+      )}
+    </>
+  );
+}
+```
+
+---
+
+## Pattern 3: Cart Analytics
+
+Track the checkout funnel to find where users drop off:
+
+```javascript
+// Server-side event tracking
+async function trackCartEvent(userId, sessionId, event, metadata = {}) {
+  await db.query(
+    `INSERT INTO cart_events (user_id, session_id, event_type, metadata, created_at)
+     VALUES ($1, $2, $3, $4, NOW())`,
+    [userId, sessionId, event, JSON.stringify(metadata)]
+  );
+}
+
+// Events to track:
+// cart_viewed, item_added, item_removed, quantity_changed,
+// checkout_started, shipping_entered, payment_entered,
+// order_completed, exit_intent_triggered, recovery_email_opened,
+// recovery_email_clicked, recovery_converted
+```
+
+### Funnel Query
+
+```sql
+SELECT
+  event_type,
+  COUNT(DISTINCT session_id) as sessions,
+  ROUND(
+    COUNT(DISTINCT session_id)::numeric /
+    FIRST_VALUE(COUNT(DISTINCT session_id)) OVER (ORDER BY
+      CASE event_type
+        WHEN 'cart_viewed' THEN 1
+        WHEN 'checkout_started' THEN 2
+        WHEN 'payment_entered' THEN 3
+        WHEN 'order_completed' THEN 4
+      END
+    ) * 100, 1
+  ) as conversion_pct
+FROM cart_events
+WHERE created_at > NOW() - INTERVAL '30 days'
+  AND event_type IN ('cart_viewed', 'checkout_started', 'payment_entered', 'order_completed')
+GROUP BY event_type
+ORDER BY
+  CASE event_type
+    WHEN 'cart_viewed' THEN 1
+    WHEN 'checkout_started' THEN 2
+    WHEN 'payment_entered' THEN 3
+    WHEN 'order_completed' THEN 4
+  END;
+```
+
+---
+
+## Sources
+
+- MDPI: Consumer Purchase Behavior Analysis with XAI/SHAP (Feb 2025) — 89% F1 score
+- Quickchat AI: Cart abandonment strategy (2025) — 15-25% recovery
+- Bloomreach: AI cart abandonment prevention (2025)
+- Booking.com: AI chatbot case study — 20% conversion increase (2025)