@gymmymac/bob-widget 3.2.3 → 3.2.5

package/dist/types/context.d.ts

@@ -153,6 +153,11 @@ export interface BobCallbacks {
     onError?: (error: Error) => void;
     /** Called for every trackable event - for server-side analytics */
     onAnalyticsEvent?: (event: BobAnalyticsEvent) => void;
+    /**
+     * Called once when the internal stopSpeech function is ready.
+     * Capture it to expose imperative speech control to the host (e.g. via BobStandaloneHandle).
+     */
+    onStopSpeechReady?: (fn: () => void) => void;
 }
 /**
  * Complete configuration for BobProvider

package/dist/types/message.d.ts

@@ -1,5 +1,11 @@
 import { Product } from './product';
 
+export interface QuickReply {
+    /** Button label, e.g. "View Brake Pads" */
+    label: string;
+    /** Navigation URL, e.g. "/products/brake-pads" */
+    url: string;
+}
 export interface Message {
     role: "user" | "assistant";
     content: string;
@@ -7,6 +13,8 @@ export interface Message {
     suggestedProducts?: Product[];
     /** Custom header for suggestions (e.g., "Wipers for your 2018 Toyota Rav 4") */
     suggestionsTitle?: string;
+    /** Navigation CTA buttons — tap fires onNavigate(url), no chat message sent */
+    quickReplies?: QuickReply[];
 }
 export interface HighlightedProduct {
     brand: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gymmymac/bob-widget",
-  "version": "3.2.3",
+  "version": "3.2.5",
   "description": "Bob - AI-powered automotive parts assistant widget with multi-tenant support, RAF animations, swipeable interactions, and GA4 analytics",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/install/carfix/00-README-PREINSTALL.md

@@ -1,111 +0,0 @@
-# Bob Widget v3.1.11 - CARFIX Installation Guide
-
-> 🚨 **STOP - READ THIS FIRST**
->
-> Bob v3.1.11 requires a **strict 3-stage installation process**. Skipping stages WILL cause visual issues (blur, wrong scale, wrong position).
-
-## Overview
-
-The 3-stage process ensures:
-1. **Stage A**: No old code remains (forensic removal)
-2. **Stage B**: Container is correctly configured (page preparation)
-3. **Stage C**: Only the new version is installed and verified
-
-## Quick Start (CLI)
-
-```bash
-# Stage A: Forensic Scan & Purge
-npx @gymmymac/bob-widget carfix stage-a
-
-# Stage B: Generate Page Template (if you have existing Header/BottomNav)
-npx @gymmymac/bob-widget carfix stage-b --target next-pages --output pages/ask-bob.tsx
-
-# Stage B: Generate Page Template WITH Layout Components (if you need Header/BottomNav)
-npx @gymmymac/bob-widget carfix stage-b --target next-pages --with-layout
-
-# Stage C: Install & Verify
-npx @gymmymac/bob-widget carfix stage-c --partner CARFIX
-```
-
-## What Each Stage Does
-
-### Stage A: Forensic Removal
-
-**Time: 2-5 minutes**
-
-Scans for and removes:
-- Bob component files (`Bob*.tsx`, `AskBob*.tsx`)
-- Bob hook files (`useBob*.ts`)
-- Bob type definitions (`*bob*.d.ts`)
-- Bob imports in any file
-- `BOB_` environment variables
-- Cached packages
-
-If issues are found, the script **exits with an error** and lists what to delete manually.
-
-### Stage B: Page Preparation
-
-**Time: 1 minute**
-
-Generates a container page template for your framework:
-- `next-pages` - Next.js Pages Router
-- `next-app` - Next.js App Router
-- `react-router` - React Router (Vite)
-
-**⚠️ IMPORTANT: Layout Components Required**
-
-The container height formula assumes you have:
-- **CARFIX Header**: 72px fixed at top
-- **CARFIX Bottom Navigation**: 72px fixed at bottom
-
-If these components **don't exist**, use the `--with-layout` flag:
-
-```bash
-npx @gymmymac/bob-widget carfix stage-b --target next-pages --with-layout
-```
-
-This generates:
-- `components/CarfixHeader.tsx` (72px header)
-- `components/CarfixBottomNav.tsx` (72px bottom nav)
-- Complete page template with layout wired up
-
-The template includes the correct container height calculation:
-```css
-height: calc(100dvh - 144px - env(safe-area-inset-bottom, 0px))
-```
-
-### Stage C: Install & Verify
-
-**Time: 1-2 minutes**
-
-- Installs `@gymmymac/bob-widget@3.1.11`
-- Verifies the installed version
-- Tests backend connectivity
-- Provides final code integration example
-
-## Manual Scripts
-
-If you prefer to run the stages manually, see:
-- `01-stage-a-forensic-scan.sh` / `.ps1`
-- `02-stage-a-cache-purge.sh` / `.ps1`
-- `03-stage-b-generate-container-template.mjs`
-- `04-stage-c-install-and-verify.mjs`
-
-## Verification Checklist
-
-After completing all stages, verify in browser:
-
-| Test | Expected Result |
-|------|-----------------|
-| Console version | `[BobWidget] Package loaded - v3.1.11` |
-| Bob visibility | Fully visible, not cropped |
-| No blur | Background is NOT blurred |
-| Correct scale | Bob is prominently sized |
-| Chat works | Messages send and Bob responds |
-| PTT (HTTPS) | Speech recognition activates |
-| Header visible | 72px CARFIX header at top |
-| Bottom nav visible | 72px navigation at bottom |
-
-## Support
-
-For issues, check the troubleshooting section in `BOB-DOCUMENTATION.md`.

package/install/carfix/05-runtime-verification-checklist.md

@@ -1,54 +0,0 @@
-# Bob Widget v3.1.19 - Runtime Verification Checklist
-
-> Complete this checklist after Stage C to confirm Bob is working correctly.
-
-## Browser Console Checks
-
-Open DevTools (F12) → Console tab:
-
-- [ ] `[BobWidget] Package loaded - v3.1.19`
-- [ ] `[BobStandalone] Initialized { version: "3.1.19", partner: "CARFIX", ... }`
-- [ ] `[BobWidget] Partner config loaded: { partner: "CARFIX", ... }`
-- [ ] No red error messages
-
-## Network Tab Checks
-
-Filter by `gjoguxzstsihhxvdgpto`:
-
-- [ ] `bob_partners` query returns 200
-- [ ] `bob_looks` query returns 200
-- [ ] `animation_states` query returns 200
-- [ ] `bob_animations` query returns 200
-- [ ] `bob_backdrops` query returns 200
-
-## Visual Checks
-
-- [ ] **Bob Visibility**: Character is fully visible, not cropped at top or bottom
-- [ ] **No Blur**: Background backdrop is NOT blurred (should be crisp)
-- [ ] **Correct Scale**: Bob is prominently sized (~140% mobile scale)
-- [ ] **Position**: Bob stands ON the counter overlay, not below it
-- [ ] **Container**: Bob fills space between CARFIX header and bottom nav
-
-## Functional Checks
-
-- [ ] **Chat Input**: Type a message → Bob responds
-- [ ] **PTT** (HTTPS only): Click microphone → speech recognition activates
-- [ ] **Vehicle Lookup**: Enter REGO (e.g., "HZP550") → Vehicle info returned
-- [ ] **Products**: Ask for parts → Products appear on shelf
-- [ ] **Add to Cart**: Say "add to cart" → `onAddToCart` callback fires
-
-## Common Issues
-
-| Issue | Solution |
-|-------|----------|
-| Wrong version in console | Clear `.vite` cache, restart dev server |
-| Background is blurred | Check CSS `--bob-blur-intensity` is 0 |
-| Bob is tiny | Check `scale` value in `bob_animations` table |
-| Bob is cropped | Container height not using 144px offset formula |
-| No products loading | Check `vehicle_id` is numeric in session token |
-
-## Pass/Fail
-
-If all checks pass: ✅ **Bob is correctly installed**
-
-If any check fails: See troubleshooting in `BOB-DOCUMENTATION.md` Section 9.

package/install/carfix/CARFIX-INSTALLATION-BRIEF.md

@@ -1,367 +0,0 @@
-# Bob Widget — CARFIX Installation Brief
-
-**Package:** `@gymmymac/bob-widget@3.1.19`  
-**Date:** 2026-02-13  
-**Status:** Production-ready, 36 unit tests passing, E2E baseline locked
-
----
-
-## 1. Peer Dependencies (Critical for Build)
-
-```json
-{
-  "peerDependencies": {
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
-  },
-  "dependencies (bundled — no action needed)": {
-    "@supabase/supabase-js": "^2.84.0",
-    "@tanstack/react-query": "^5.0.0"
-  }
-}
-```
-
-> If CARFIX already uses `@tanstack/react-query`, ensure versions are compatible (v5+).
-
----
-
-## 2. Installation
-
-```bash
-npm install @gymmymac/bob-widget@latest
-```
-
----
-
-## 3. Minimal Integration (4 lines)
-
-```tsx
-import { BobStandalone } from '@gymmymac/bob-widget';
-
-function AskBobPage() {
-  const router = useRouter();
-  const sessionToken = router.query.session as string;
-
-  return (
-    <div style={{
-      height: 'calc(100dvh - 144px - env(safe-area-inset-bottom, 0px))',
-      position: 'relative',
-      /* DO NOT use overflow: hidden — clips PTT button and chat drawer */
-    }}>
-      <BobStandalone
-        partner="CARFIX"
-        sessionToken={sessionToken}
-        bottomOffset={0}       /* Container already handles spacing */
-        zIndexBase={100}       /* Above header z-40 and nav z-30 */
-        onAddToCart={async (item) => {
-          // See Section 6 for full item shape including bundle metadata
-          await carfixCart.add(item);
-        }}
-        onNavigate={(url) => router.push(url)}
-        onCheckout={(checkoutUrl) => window.location.href = checkoutUrl}
-        onError={(error) => console.error('[Bob Error]', error)}
-      />
-    </div>
-  );
-}
-```
-
-> **Auto-configuration:** The `partner="CARFIX"` prop loads all API URLs, credentials, layout defaults, and feature flags from the `bob_partners` database table. No manual config needed.
-
----
-
-## 4. CARFIX API Configuration (Already in Database)
-
-```json
-{
-  "baseUrl": "https://flpzjbasdsfwoeruyxgp.supabase.co/functions/v1",
-  "apiKey": "eyJhbGciOiJIUzI1NiIs...wKoJ51_VPro_BrJz-A-NRpSmUW0XBP-7TJJcrhvYwxE",
-  "partnerCode": "CARFIX"
-}
-```
-
-### Available Endpoints
-
-| Endpoint | Purpose |
-|---|---|
-| `partner-api` | Session creation, cart, user context, orders |
-| `calculate-service-bundles` | Service packs with `preparedTiers[]` (incl. bundle discounts) |
-| `retrieve-vehicle-info` | NZ rego lookup |
-| `retrieve-parts` | Vehicle parts by category |
-
----
-
-## 5. Layout Constraints
-
-```
-┌──────────────────────────────┐
-│  CARFIX Header (72px, z-40)  │
-├──────────────────────────────┤
-│                              │
-│  Bob Container               │
-│  height: calc(100dvh - 144px │
-│          - safe-area-inset)  │
-│  position: relative          │
-│  NO overflow: hidden!        │
-│                              │
-├──────────────────────────────┤
-│  Bottom Nav (72px, z-30)     │
-└──────────────────────────────┘
-```
-
-**Bob's internal z-index stack (relative to `zIndexBase={100}`):**
-
-| Layer | z-index |
-|---|---|
-| Chat PTT Button | 145 |
-| Chat Drawer | 130 |
-| Counter Overlay | 70 |
-| Bob Character | 60 |
-| Product Shelf | 55 |
-| Backdrop | 10 |
-
----
-
-## 6. Callback Signatures
-
-### onAddToCart
-
-```typescript
-onAddToCart: (item: {
-  product_id: string;
-  product_name: string;
-  quantity: number;
-  unit_price: number;       // Final price (discount already applied for bundle items)
-  sku?: string;
-  brand?: string;
-  image_url?: string;
-  vehicle_id?: string;
-  // Bundle metadata (present when item is part of a service package)
-  is_bundle_item?: boolean;
-  bundle_discount_percentage?: number;
-  service_package_name?: string;
-  service_package_id?: string;
-  quality_tier?: string;    // "Economy" | "Standard" | "Premium" | "Performance"
-}) => Promise<void> | void;
-```
-
-### onNavigate
-
-```typescript
-onNavigate: (url: string) => void;
-// Example urls: "/product/SKU123", "/checkout"
-```
-
-### onCheckout
-
-```typescript
-onCheckout: (checkoutUrl: string) => void;
-// checkoutUrl is a full Stripe payment URL
-```
-
-### onError
-
-```typescript
-onError: (error: Error) => void;
-// Bob shows toast by default — this is for host-side logging
-```
-
----
-
-## 7. Bundle Discount Fields (NEW)
-
-The `calculate-service-bundles` API returns these fields per `PreparedTier`:
-
-```typescript
-interface PreparedTier {
-  tierName: string;              // "Economy" | "Standard" | "Premium" | "Performance"
-  displayName: string;
-  description: string;
-  isRecommended: boolean;        // true = CARFIX Value tier
-  isHidden: boolean;             // true = filter out (duplicate price)
-  
-  // Pricing (pre-calculated by API — never recompute)
-  totalPrice: number;            // Discounted bundle price
-  originalTotalPrice?: number;   // Full price before discount
-  savingsAmount?: number;        // Dollar savings (originalTotalPrice - totalPrice)
-  bundleDiscountPercentage?: number; // Discount % applied (0-50)
-  
-  productCount: number;
-  dominantBrand: string | null;
-  brands: PreparedTierBrand[];
-  products: PreparedTierProduct[];
-}
-
-interface PreparedTierProduct {
-  partslotId: number;
-  partslotName: string;          // "BRAKE PADS FRONT"
-  sku: string;
-  name: string;
-  brand: string;
-  brandFullName: string;
-  brandImageUrl: string;         // Full URL — use directly in <img>
-  productImageUrl: string;       // Full URL — use directly in <img>
-  price: number;                 // Legacy unit price
-  unitPrice: number;             // Per-unit price
-  displayPrice: number;          // Total (unitPrice × perCarQty) — USE THIS
-  isRotor: boolean;              // Show "[Pair]" badge
-  isMultiQty: boolean;           // Show quantity breakdown (e.g. spark plugs)
-  perCarQty: number;             // Quantity needed
-  partNumber: string | null;
-  webDescription: string | null;
-  viscosity: string | null;
-  volume: number | null;
-}
-
-interface PreparedTierBrand {
-  name: string;
-  fullName: string;
-  imageUrl: string;              // Full URL
-}
-```
-
-### Rendering Rules
-
-1. **Filter hidden tiers:** `preparedTiers.filter(t => !t.isHidden)`
-2. **When `savingsAmount > 0`:** Show ~~$originalTotalPrice~~ → **$totalPrice** + "SAVE $XX — X% Bundle Deal"
-3. **When `savingsAmount === 0`:** Show `totalPrice` normally, no discount UI
-4. **Use `displayPrice`** for individual products (already includes quantity)
-5. **Never calculate prices client-side** — all values arrive pre-calculated
-
----
-
-## 8. Session Handoff (Pre-authenticated Users)
-
-To pass vehicle/customer context from CARFIX to Bob:
-
-```
-1. CARFIX calls partner-api with action: "create_session"
-   → Body: { vehicle_id: 42899 }   ← MUST be a NUMBER
-   → Returns: { session_token: "abc123..." }
-
-2. Redirect to Bob page: /ask-bob?session=abc123...
-
-3. BobStandalone reads sessionToken from URL
-   → Calls session-handoff edge function
-   → Injects vehicle + customer context into chat
-```
-
-> **Critical:** `vehicle_id` must be numeric throughout the pipeline. String values cause silent API failures.
-
----
-
-## 9. Design Tokens
-
-The full design token file is exported from the package:
-
-```typescript
-import {
-  CARFIX_COLORS,
-  QUALITY_TIER_CONFIG,
-  IMAGE_URLS,
-  BADGE_CONFIG,
-  TYPOGRAPHY,
-  isRotorProduct,
-  getDisplayPrice,
-  formatNZD,
-} from '@gymmymac/bob-widget';
-```
-
-### Key Colors
-
-| Token | Value | Usage |
-|---|---|---|
-| `primary` | `#0052CC` | Standard tier, CTAs, CARFIX Value |
-| `secondary` | `#38BDF8` | Accents, links |
-| `accent` | `#FF8C00` | Premium tier |
-| `success` | `#22C55E` | "Fits Vehicle" badges, Add to Cart |
-| `destructive` | `#EF4444` | Performance tier |
-| `foreground` | `#0F172A` | Headers, primary text |
-| `mutedForeground` | `#64748B` | Descriptions |
-
-### Tier Visual Config
-
-| Tier | Color | Badge |
-|---|---|---|
-| Economy | `#475569` on `#F1F5F9` | 💰 |
-| Standard | `#0052CC` on `rgba(0,82,204,0.1)` | ⭐ CARFIX Value |
-| Premium | `#D97706` on `#FEF3C7` | 🏆 |
-| Performance | `#DC2626` on `#FEE2E2` | ⚡ |
-
----
-
-## 10. Exported Types (Full List)
-
-```typescript
-// Core widget components
-export { BobStandalone } from '@gymmymac/bob-widget';
-export type { StandaloneWidgetProps } from '@gymmymac/bob-widget';
-
-// Types available for CARFIX integration
-export type {
-  // Context & Config
-  HostContext, HostUserContext, HostVehicleContext, HostCartContext,
-  BobConfig, HostApiConfig, BobCallbacks, BobProviderConfig, BobLayoutConfig,
-  
-  // Products & Packages
-  Product, CartItem, ServicePackage, PreparedTier, PreparedTierProduct, PreparedTierBrand,
-  Partslot, QualityTiers, Part,
-  
-  // Partner
-  PartnerConfig, PartnerFeatureFlags, EssentialCallbacks,
-  
-  // Vehicle
-  Vehicle,
-  
-  // Messages
-  Message, HighlightedProduct,
-  
-  // Analytics
-  BobAnalyticsEvent, BobGA4Config,
-} from '@gymmymac/bob-widget';
-```
-
----
-
-## 11. Verification Checklist (Post-Install)
-
-```
-□ npm install completes without peer dependency warnings
-□ BobStandalone renders loading spinner, then Bob appears
-□ Bob character sits between header and bottom nav
-□ Chat drawer opens above bottom navigation (z-index check)
-□ PTT button is visible and not clipped
-□ Vehicle lookup works (try rego: HZP550)
-□ Service packages appear with tier cards
-□ Bundle discount shows Was/Now pricing where applicable
-□ "Add to Cart" callback fires with correct item shape
-□ Session handoff works (pass ?session=TOKEN)
-□ No console errors related to Bob
-□ Mobile: safe-area-inset respected on notched devices
-```
-
----
-
-## 12. Test Baseline
-
-Bob ships with **36 unit tests** and **8+ E2E scenarios** covering:
-
-- Callback mapping and stability
-- Tier validation and empty states
-- Rear Brake Disc/Drum filter logic
-- Bundle discount display and cart pricing
-- Vehicle lookup flow
-- Service package rendering
-- Chat drawer positioning
-
-Run locally: `cd packages/bob-widget && npx vitest run`
-
----
-
-## Support
-
-For integration issues, the Bob team needs:
-1. Browser console output (filter for `[Bob`)
-2. Network tab showing failed API calls
-3. Screenshot of layout issue
-4. Device/browser/viewport info