@gymmymac/bob-widget 3.0.4 → 3.1.0

package/README.md

@@ -2,238 +2,50 @@
 
 AI-powered automotive parts assistant widget for integration into partner websites.
 
-**v3.0.0** - Major release with multi-tenant support, RAF animations, swipeable Bob, and enhanced mobile experience.
+**Current Version:** 3.1.0
 
-## What's New in v3.0.0
-
-- 🎭 **SwipeableBob**: Gesture-based interactions - swipe Bob away or back into view
-- 🏢 **Multi-Tenant Support**: Configurable looks and animations per tenant
-- 🎬 **RAF Animations**: Smooth 60fps animations using requestAnimationFrame
-- ⚡ **MatrixProductLoader**: Cyberpunk-style loading with phased states
-- 🔥 **SparkDealBanner**: Animated promotional banners
-- 👋 **Returning User Detection**: Personalized greetings for repeat visitors
-- 🎨 **Theme Settings**: Dynamic theme configuration from database
-
-## Installation
-
-```bash
-npm install @gymmymac/bob-widget
-```
-
-## Quick Start (Recommended)
-
-The easiest way to integrate Bob - just use the `BobWidget` component:
-
-```tsx
-import { BobWidget } from '@gymmymac/bob-widget';
-
-function App() {
-  return (
-    <BobWidget
-      bobConfig={{
-        supabaseUrl: 'https://gjoguxzstsihhxvdgpto.supabase.co',
-        supabaseKey: 'eyJhbGciOiJI...', // Bob's public anon key
-      }}
-      hostApiConfig={{
-        baseUrl: 'https://api.yoursite.com',
-        apiKey: process.env.API_KEY!,
-        partnerCode: 'YOUR_PARTNER_CODE',
-      }}
-      hostContext={{
-        user: { id: user?.id, email: user?.email },
-        vehicle: { selectedVehicle: currentVehicle },
-      }}
-      callbacks={{
-        onVehicleIdentified: (vehicle) => saveVehicle(vehicle),
-        onAddToCart: (item) => addToCart(item),
-      }}
-      variant="mobile"
-    />
-  );
-}
-```
-
-**That's it!** No `QueryClientProvider` wrapping needed - Bob handles everything internally.
-
-## Alternative: BobProvider + Bob
-
-If you need access to Bob's context in other components:
+## Quick Start
 
 ```tsx
-import { BobProvider, Bob, useHostContext } from '@gymmymac/bob-widget';
-
-function App() {
-  return (
-    <BobProvider
-      bobConfig={{
-        supabaseUrl: 'https://gjoguxzstsihhxvdgpto.supabase.co',
-        supabaseKey: 'eyJhbGciOiJI...',
-      }}
-      hostApiConfig={{
-        baseUrl: 'https://api.yoursite.com',
-        apiKey: process.env.API_KEY!,
-        partnerCode: 'YOUR_PARTNER_CODE',
-      }}
-      hostContext={{
-        user: { id: user?.id, email: user?.email },
-      }}
-      callbacks={{
-        onAddToCart: (item) => addToCart(item),
-      }}
-    >
-      <YourApp />
-      <Bob variant="mobile" />
-    </BobProvider>
-  );
-}
-```
-
-## Checking Bob's Version
-
-Ask Bob directly: "What version are you running?"
+import { BobStandalone } from '@gymmymac/bob-widget';
 
-Or programmatically:
-```tsx
-import { BOB_VERSION, getBobVersion } from '@gymmymac/bob-widget';
-
-console.log(`Bob Widget Version: ${getBobVersion()}`); // "3.0.0"
-```
-
-Check the console for startup logs:
-```
-[BobWidget] Package loaded - v3.0.0
-[BobWidget] v3.0.0 initialized
-[BobWidget] QueryClient: internal
+<BobStandalone
+  partner="CARFIX"
+  sessionToken={sessionToken}
+  onAddToCart={(item) => addToCart(item)}
+  onNavigate={(url) => router.push(url)}
+/>
 ```
 
-## Configuration
+**That's it!** Bob auto-configures from the database.
 
-### BobWidget / BobProvider Props
+## Documentation
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `bobConfig` | `BobConfig` | Bob's Supabase credentials (for animations, TTS) |
-| `hostApiConfig` | `HostApiConfig` | Your API credentials for product/vehicle lookups |
-| `hostContext` | `HostContext` | Current user, vehicle, cart, and purchase history |
-| `callbacks` | `BobCallbacks` | Event handlers for Bob actions |
-| `queryClient` | `QueryClient` | Optional: share your app's QueryClient |
+📖 **[Full Documentation](./BOB-DOCUMENTATION.md)** - Complete integration guide, props reference, behaviour guidelines, and troubleshooting.
 
-### BobWidget Additional Props
+📋 **[Changelog](./CHANGELOG.md)** - Version history and release notes.
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `variant` | `'mobile' \| 'inline' \| 'floating' \| 'fullscreen'` | `'mobile'` | Display variant |
-| `showChat` | `boolean` | `true` | Show chat interface |
-| `className` | `string` | `''` | Additional CSS classes |
-
-### Host Context
-
-Pass your app's state to Bob for personalized interactions:
-
-```tsx
-const hostContext = useMemo(() => ({
-  user: {
-    id: user?.id,
-    email: user?.email,
-    name: user?.name,
-    isAuthenticated: !!user,
-  },
-  vehicle: {
-    selectedVehicle: currentVehicle,
-    garageVehicles: userVehicles,
-  },
-  cart: {
-    items: cartItems,
-    totalValue: cartTotal,
-  },
-  history: {
-    purchases: orderHistory,
-    lastOrderDate: lastOrder?.date,
-  },
-  currentPage: location.pathname,
-}), [user, currentVehicle, userVehicles, cartItems, cartTotal, orderHistory]);
-```
-
-### Callbacks
-
-Handle Bob's actions in your app:
-
-```tsx
-const callbacks = {
-  onVehicleIdentified: (vehicle) => {
-    dispatch(setCurrentVehicle(vehicle));
-  },
-  onPartsFound: (parts) => {
-    dispatch(setParts(parts));
-  },
-  onAddToCart: (item) => {
-    dispatch(addToCart(item));
-  },
-  onCheckoutRequested: (url) => {
-    window.location.href = url;
-  },
-};
-```
-
-## Hooks
-
-Access Bob's context from anywhere in your app (when using BobProvider):
+## Installation
 
-```tsx
-import { 
-  useBobContext,
-  useHostContext,
-  useBobCallbacks,
-} from '@gymmymac/bob-widget';
-
-function MyComponent() {
-  const { hostContext, updateHostContext } = useBobContext();
-  
-  // Update context when your app state changes
-  useEffect(() => {
-    updateHostContext({ user: { email: newEmail } });
-  }, [newEmail]);
-}
+```bash
+npm install @gymmymac/bob-widget@^3.1.0
 ```
 
-## Advanced: Shared QueryClient
-
-If you want Bob to share your app's React Query cache:
+## What's New in v3.1.0
 
-```tsx
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { BobProvider, Bob } from '@gymmymac/bob-widget';
-
-const queryClient = new QueryClient();
-
-function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <BobProvider
-        bobConfig={...}
-        hostApiConfig={...}
-        queryClient={queryClient} // Share the cache
-      >
-        <Bob variant="mobile" />
-      </BobProvider>
-    </QueryClientProvider>
-  );
-}
-```
+- 🎯 **BobStandalone** - Auto-configures from database (4 lines to integrate)
+- 🗄️ **Partner Config System** - All settings in `bob_partners` table
+- 🎨 **CSS Variables** - Customizable blur, opacity, colors
+- 🔍 **Debug Overlay** - Visual diagnostic tool
+- 📦 **Simplified Callbacks** - Only 3 essential callbacks needed
 
 ## Dependencies
 
-Bob Widget v3.0.0+ bundles its own dependencies. You only need:
+Only requires:
 - `react` ^18.0.0
 - `react-dom` ^18.0.0
 
-## Changelog
-
-See [CHANGELOG.md](./CHANGELOG.md) for version history.
-
-## Integration Guide
-
-For detailed integration instructions, see [CARFIX-INTEGRATION.md](./CARFIX-INTEGRATION.md).
+All other dependencies are bundled.
 
 ## License
 

package/dist/components/Bob.d.ts

@@ -12,6 +12,8 @@ interface BobProps {
     defaultBobImage?: string;
     verticalOffset?: number;
     scale?: number;
+    /** Session token for pre-authenticated sessions (vehicle/user context) */
+    sessionToken?: string;
 }
 export declare const Bob: React.FC<BobProps>;
 export {};

package/dist/components/BobDebugOverlay.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { PartnerConfig } from '../types/partner';
+
+interface BobDebugOverlayProps {
+    partnerConfig: PartnerConfig | null;
+    sessionToken?: string;
+}
+export declare const BobDebugOverlay: React.FC<BobDebugOverlayProps>;
+export default BobDebugOverlay;

package/dist/components/BobStandalone.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+import { StandaloneWidgetProps } from '../types/partner';
+
+/**
+ * BobStandalone - Simplified partner integration component
+ *
+ * Reduces integration from 30+ lines to just 4 lines of code.
+ * All configuration is auto-loaded from the bob_partners database table.
+ */
+export declare const BobStandalone: React.FC<StandaloneWidgetProps>;
+export default BobStandalone;

package/dist/hooks/useBobHealthCheck.d.ts

@@ -0,0 +1,30 @@
+export interface BobHealthCheckResult {
+    healthy: boolean;
+    reason?: string;
+    activeLookId?: string;
+    activeLookName?: string;
+    stateCount: number;
+    states: string[];
+    missingCritical: string[];
+    frameCount: number;
+}
+/**
+ * Health check hook for verifying Bob's animation system connectivity.
+ * Use this to diagnose issues with animation state loading on external sites.
+ *
+ * @example
+ * ```tsx
+ * const { checkHealth } = useBobHealthCheck();
+ *
+ * useEffect(() => {
+ *   checkHealth().then(result => {
+ *     if (!result.healthy) {
+ *       console.error('Bob health check failed:', result.reason);
+ *     }
+ *   });
+ * }, []);
+ * ```
+ */
+export declare const useBobHealthCheck: () => {
+    checkHealth: () => Promise<BobHealthCheckResult>;
+};

package/dist/hooks/usePartnerConfig.d.ts

@@ -0,0 +1,40 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+import { PartnerConfig, PartnerFeatureFlags } from '../types/partner';
+
+export interface UsePartnerConfigResult {
+    /** Loaded partner configuration */
+    config: PartnerConfig | null;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error if config failed to load */
+    error: Error | null;
+    /** Whether the current origin is allowed for this partner */
+    isOriginAllowed: boolean;
+    /** Supabase client configured for this partner */
+    supabaseClient: SupabaseClient | null;
+    /** Reload configuration */
+    reload: () => Promise<void>;
+}
+/**
+ * Hook to auto-load partner configuration from database
+ *
+ * @param partnerCode - Partner identifier (e.g., "CARFIX")
+ * @returns Partner configuration, loading state, and utilities
+ *
+ * @example
+ * ```tsx
+ * const { config, isLoading, error, supabaseClient } = usePartnerConfig('CARFIX');
+ *
+ * if (isLoading) return <LoadingSpinner />;
+ * if (error) return <ErrorMessage error={error} />;
+ *
+ * // Use config for layout, features, etc.
+ * const bottomOffset = config.default_bottom_offset;
+ * ```
+ */
+export declare function usePartnerConfig(partnerCode: string | undefined): UsePartnerConfigResult;
+/**
+ * Get feature flag value with default fallback
+ */
+export declare function getFeatureFlag<K extends keyof PartnerFeatureFlags>(config: PartnerConfig | null, flag: K, defaultValue: PartnerFeatureFlags[K]): PartnerFeatureFlags[K];
+export default usePartnerConfig;

package/dist/index.d.ts

@@ -3,6 +3,7 @@
  *
  * AI-powered automotive parts assistant widget - Full immersive experience
  *
+ * v3.1.0 - Standalone partner integration: auto-config from database, simplified props
  * v3.0.0 - Major rebuild with multi-tenant support, RAF animations, swipeable Bob
  * v1.4.0 - Redesigned PTT button: 3x larger, green "TALK" text, floating cartoon style
  * v1.3.1 - Bottom offset support for host navigation bars
@@ -12,6 +13,11 @@ export { BOB_VERSION, getBobVersion } from './version';
 export { BobProvider, useBobContext, useBobSupabase, useBobSupabaseSafe, useHostContext, useHostApiConfig, useBobCallbacks, useBobAnalyticsConfig, useBobAnalytics, useBobLayoutConfig, } from './BobProvider';
 export { BobWidget } from './components/BobWidget';
 export type { BobWidgetProps } from './components/BobWidget';
+export { BobStandalone } from './components/BobStandalone';
+export type { StandaloneWidgetProps } from './types/partner';
+export { usePartnerConfig, getFeatureFlag } from './hooks/usePartnerConfig';
+export type { PartnerConfig, PartnerFeatureFlags, EssentialCallbacks } from './types/partner';
+export { BobDebugOverlay } from './components/BobDebugOverlay';
 export { Bob } from './components/Bob';
 export type { BobVariant } from './components/Bob';
 export { BobCharacter } from './components/BobCharacter';
@@ -35,6 +41,8 @@ export { useBobBackdrop } from './hooks/useBobBackdrop';
 export { useThemeSettings } from './hooks/useThemeSettings';
 export { useSparkDeals } from './hooks/useSparkDeals';
 export { useReturningUser } from './hooks/useReturningUser';
+export { useBobHealthCheck } from './hooks/useBobHealthCheck';
+export type { BobHealthCheckResult } from './hooks/useBobHealthCheck';
 export type { HostContext, HostUserContext, HostVehicleContext, HostCartContext, HostHistoryContext, BobConfig, HostApiConfig, BobCallbacks, BobProviderConfig, BobLayoutConfig, } from './types/context';
 export type { Vehicle } from './types/vehicle';
 export type { Product, APIPart, CartItem, ServicePackage, Partslot, QualityTiers, Part, } from './types/product';