@getspot/spot-widget-vue 1.3.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @getspot/spot-widget-vue
 
+## 2.0.0
+
+### Major Changes
+
+- 4c59d56: Typescript support
+
+### Patch Changes
+
+- Updated dependencies [4c59d56]
+  - @getspot/spot-widget@2.0.0
+
+## 1.4.0
+
+### Minor Changes
+
+- 5b3eaaf: add qualifying reasons for pass/trip offers
+
+### Patch Changes
+
+- Updated dependencies [5b3eaaf]
+  - @getspot/spot-widget@1.4.0
+
 ## 1.3.0
 
 ### Minor Changes

package/README.md

@@ -1,12 +1,439 @@
-# Spot Vue Widget
+# @getspot/spot-widget-vue
 
-## Description
-This is a UI component for displaying a quote offer to users in a checkout flow
+Vue 3 component wrapper for the Spot refund guarantee widget.
+
+> **Note:** This Vue wrapper uses types from [@getspot/spot-widget](https://www.npmjs.com/package/@getspot/spot-widget).
+
+### Key Types
+- `ApiConfig` - API configuration (environment, partnerId, customEndpoint)
+- `QuoteRequestData` - Quote request data for single items or batch requests
+- `SelectionData` - User selection data returned in callbacks
+- `Quote` - Quote response data with pricing and terms
+- `Theme` - Styling customization options
+
+For complete type definitions, see the [@getspot/spot-widget documentation](https://www.npmjs.com/package/@getspot/spot-widget).
 
 ## Installation
 
 ```bash
-npm install --save @getspot/spot-widget-vue
+npm install @getspot/spot-widget-vue
+```
+
+## Quick Start
+
+```vue
+<template>
+  <VueSpotWidget
+    :api-config="{
+      environment: 'production',
+      partnerId: 'your-partner-id'
+    }"
+    :quote-request-data="quoteData"
+    :show-table="true"
+    :opt-in-selected="false"
+    @quote-retrieved="onQuoteRetrieved"
+    @opt-in="onOptIn"
+    @opt-out="onOptOut"
+    @error="onError"
+  />
+</template>
+
+<script setup>
+import VueSpotWidget from '@getspot/spot-widget-vue';
+
+const quoteData = {
+  startDate: '2024-01-01T00:00:00Z',
+  endDate: '2024-01-07T23:59:59Z',
+  currencyCode: 'USD',
+  eventType: 'Ski Trip',
+  productType: 'Trip',
+  productDuration: 'Trip',
+  productPrice: 500,
+  productId: 'ski-trip-2024',
+  cartId: 'cart-123',
+  productName: 'Aspen Ski Trip 2024'
+};
+
+const onQuoteRetrieved = (quote) => {
+  console.log('Quote retrieved:', quote);
+};
+
+const onOptIn = (data) => {
+  console.log('User opted in:', data);
+  // Handle opt-in logic
+};
+
+const onOptOut = (data) => {
+  console.log('User opted out:', data);
+  // Handle opt-out logic
+};
+
+const onError = (error) => {
+  console.error('Widget error:', error);
+  // Handle errors
+};
+</script>
 ```
 
-## Usage
+## TypeScript Support
+
+This package includes full TypeScript definitions for Vue 3.
+
+```vue
+<script setup lang="ts">
+import VueSpotWidget from '@getspot/spot-widget-vue';
+import type { Quote, SelectionData } from '@getspot/spot-widget';
+
+interface QuoteData {
+  startDate: string;
+  endDate: string;
+  currencyCode: 'USD' | 'CAD' | 'AUD';
+  eventType: string;
+  productType: 'Pass' | 'Trip' | 'Registration';
+  productDuration: 'Daily' | 'Seasonal' | 'Trip' | 'Event';
+  productPrice: number;
+  productId: string;
+  cartId: string;
+  productName: string;
+}
+
+const quoteData: QuoteData = {
+  // ... your quote data
+};
+
+const onQuoteRetrieved = (quote: Quote) => {
+  console.log('Quote retrieved:', quote);
+};
+
+const onOptIn = (data: SelectionData) => {
+  console.log('User opted in:', data);
+};
+
+const onOptOut = (data: SelectionData) => {
+  console.log('User opted out:', data);
+};
+</script>
+```
+
+## Props
+
+### Required Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `apiConfig` | `ApiConfig` | Configuration for the Spot API including environment and partner ID |
+| `quoteRequestData` | `QuoteRequestData` | Quote request data containing product and cart information |
+
+### Optional Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showTable` | `boolean` | `true` | Whether to show the payout table |
+| `optInSelected` | `boolean` | `false` | Whether the widget should be pre-selected for opt-in |
+| `theme` | `Theme` | `undefined` | Theme customization options for styling the widget |
+
+## Events
+
+The component emits the following events:
+
+### @quote-retrieved
+
+Emitted when a quote is successfully retrieved.
+
+```vue
+<VueSpotWidget @quote-retrieved="onQuoteRetrieved" />
+```
+
+**Payload:** `Quote` object
+
+### @opt-in
+
+Emitted when user opts in to the refund guarantee.
+
+```vue
+<VueSpotWidget @opt-in="onOptIn" />
+```
+
+**Payload:** `SelectionData` object with `status: 'QUOTE_ACCEPTED'`
+
+### @opt-out
+
+Emitted when user opts out of the refund guarantee.
+
+```vue
+<VueSpotWidget @opt-out="onOptOut" />
+```
+
+**Payload:** `SelectionData` object with `status: 'QUOTE_DECLINED'`
+
+### @error
+
+Emitted when an error occurs during quote retrieval.
+
+```vue
+<VueSpotWidget @error="onError" />
+```
+
+**Payload:** Error object with `message`, `status`, and `responseBody`
+
+### @no-matching-quote
+
+Emitted when no matching quote is found.
+
+```vue
+<VueSpotWidget @no-matching-quote="onNoMatchingQuote" />
+```
+
+**Payload:** Object with `status: 'NO_MATCHING_QUOTE'` and original request data
+
+### @selection-change
+
+Emitted when user changes their selection (opt-in or opt-out).
+
+```vue
+<VueSpotWidget @selection-change="onSelectionChange" />
+```
+
+**Payload:** `SelectionData` object
+
+## Exposed Methods
+
+You can access widget methods using template refs:
+
+```vue
+<template>
+  <div>
+    <VueSpotWidget
+      ref="spotWidget"
+      v-bind="widgetProps"
+    />
+    <button @click="updateQuote">Update Quote</button>
+    <button @click="getSelection">Get Selection</button>
+    <button @click="validateSelection">Validate Selection</button>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import VueSpotWidget from '@getspot/spot-widget-vue';
+
+const spotWidget = ref();
+
+const updateQuote = async () => {
+  const success = await spotWidget.value?.updateQuote({
+    // new quote data
+  });
+  console.log('Quote updated:', success);
+};
+
+const getSelection = () => {
+  const selection = spotWidget.value?.getSelection();
+  console.log('Current selection:', selection);
+};
+
+const validateSelection = () => {
+  const isValid = spotWidget.value?.validateSelection();
+  console.log('Selection is valid:', isValid);
+};
+</script>
+```
+
+### Available Methods
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `updateQuote(data)` | `Promise<boolean>` | Update the quote with new request data |
+| `getSelection()` | `SelectionData \| null` | Get the current user selection |
+| `validateSelection()` | `boolean` | Validate that the user has made a selection |
+| `destroy()` | `void` | Destroy the widget instance and clean up resources |
+
+## Configuration
+
+### API Configuration
+
+The `apiConfig` prop accepts the following options:
+
+```typescript
+{
+  environment: 'production' | 'sandbox' | 'local',
+  partnerId: string,
+  customEndpoint?: string // Optional custom API endpoint
+}
+```
+
+### Quote Request Data
+
+#### Single Quote Format
+
+```typescript
+{
+  startDate: string,        // ISO 8601 date string
+  endDate: string,          // ISO 8601 date string  
+  currencyCode: 'USD' | 'CAD' | 'AUD',
+  eventType: string,        // e.g., "Ski Trip", "Concert"
+  productType: 'Pass' | 'Trip' | 'Registration',
+  productDuration: 'Daily' | 'Seasonal' | 'Trip' | 'Event',
+  productPrice: number,     // Price in specified currency
+  productId: string,        // Unique product identifier
+  cartId: string,           // Cart identifier
+  productName: string,      // Human-readable product name
+  participantDescription?: string // Optional participant details
+}
+```
+
+#### Batch Quote Format
+
+For multiple items in a cart:
+
+```typescript
+{
+  cartInfo: {
+    cartId: string,
+    cartName: string,
+    currencyCode: 'USD' | 'CAD' | 'AUD'
+  },
+  items: Array<{
+    // Same fields as single quote, minus cartId and currencyCode
+    cartItemId?: string // Optional unique identifier for cart item
+  }>
+}
+```
+
+## Styling
+
+Customize the widget appearance using the `theme` prop:
+
+```vue
+<template>
+  <VueSpotWidget
+    :theme="{
+      primaryColor: '#007bff',
+      borderRadius: '8px',
+      fontFamily: 'Arial, sans-serif'
+    }"
+    v-bind="otherProps"
+  />
+</template>
+```
+
+## Options API Usage
+
+If you prefer the Options API:
+
+```vue
+<template>
+  <VueSpotWidget
+    :api-config="apiConfig"
+    :quote-request-data="quoteRequestData"
+    @opt-in="handleOptIn"
+    @opt-out="handleOptOut"
+    @error="handleError"
+  />
+</template>
+
+<script>
+import VueSpotWidget from '@getspot/spot-widget-vue';
+
+export default {
+  components: {
+    VueSpotWidget
+  },
+  
+  data() {
+    return {
+      apiConfig: {
+        environment: 'production',
+        partnerId: 'your-partner-id'
+      },
+      quoteRequestData: {
+        startDate: '2024-01-01T00:00:00Z',
+        endDate: '2024-01-07T23:59:59Z',
+        currencyCode: 'USD',
+        eventType: 'Test Event',
+        productType: 'Trip',
+        productDuration: 'Trip',
+        productPrice: 100,
+        productId: 'test-product',
+        cartId: 'test-cart',
+        productName: 'Test Product'
+      }
+    };
+  },
+  
+  methods: {
+    handleOptIn(data) {
+      console.log('User opted in:', data);
+      // Handle opt-in logic
+    },
+    
+    handleOptOut(data) {
+      console.log('User opted out:', data);
+      // Handle opt-out logic
+    },
+    
+    handleError(error) {
+      console.error('Widget error:', error);
+      // Handle error
+    }
+  }
+};
+</script>
+```
+
+## Error Handling
+
+Always implement error handling for production use:
+
+```vue
+<template>
+  <div>
+    <VueSpotWidget
+      v-bind="widgetProps"
+      @error="handleError"
+      @no-matching-quote="handleNoQuote"
+    />
+    <div v-if="errorMessage" class="error-message">
+      {{ errorMessage }}
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const errorMessage = ref('');
+
+const handleError = (error) => {
+  console.error('Spot Widget Error:', error);
+  
+  // Show user-friendly message
+  errorMessage.value = 'Unable to load refund options. Please try again.';
+  
+  // Track error in analytics
+  if (window.analytics) {
+    window.analytics.track('spot_widget_error', {
+      message: error.message,
+      status: error.status
+    });
+  }
+};
+
+const handleNoQuote = () => {
+  errorMessage.value = 'No refund guarantee available for this product.';
+};
+</script>
+```
+
+## Compatibility
+
+- **Vue**: 3.x
+- **TypeScript**: 5.x  
+- **Node.js**: 16+
+
+## License
+
+See the main package for license information.
+
+## Support
+
+For support, please contact [support@getspot.com](mailto:support@getspot.com).

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { DefineComponent } from 'vue';
+import type { SpotWidgetOptions, SelectionData, Quote } from '@getspot/spot-widget';
+
+export interface VueSpotWidgetProps extends Omit<SpotWidgetOptions, 'location' | 'callbacks'> {
+  onQuoteRetrieved?: (quote: Quote) => void;
+  onOptIn?: (data: SelectionData) => void;
+  onOptOut?: (data: SelectionData) => void;
+  onError?: (error: { message: string; status?: number; responseBody?: any }) => void;
+  onNoMatchingQuote?: (data: { status: string; data: any }) => void;
+  onSelectionChange?: (data: SelectionData) => void;
+  callbacks?: SpotWidgetOptions['callbacks'];
+}
+
+export interface VueSpotWidgetMethods {
+  updateQuote: (newQuoteRequestData: SpotWidgetOptions['quoteRequestData']) => Promise<boolean>;
+  getSelection: () => SelectionData | null;
+  validateSelection: () => boolean;
+  destroy: () => void;
+}
+
+declare const VueSpotWidget: DefineComponent<VueSpotWidgetProps, {}, {}, {}, VueSpotWidgetMethods>;
+
+export default VueSpotWidget;

package/package.json

@@ -1,22 +1,39 @@
 {
   "name": "@getspot/spot-widget-vue",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "publishConfig": {
     "access": "public"
   },
   "main": "dist/index.umd.js",
   "module": "dist/index.es.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "dependencies": {
-    "@getspot/spot-widget": "1.3.0"
+    "@getspot/spot-widget": "2.0.0"
   },
   "peerDependencies": {
     "vue": "^3.0.0"
   },
   "devDependencies": {
     "vite": "^5.0.0",
-    "@vitejs/plugin-vue": "^5.0.0"
+    "@vitejs/plugin-vue": "^5.0.0",
+    "vitest": "^1.0.0",
+    "@vue/test-utils": "^2.4.0",
+    "jsdom": "^23.0.0",
+    "@vitest/coverage-v8": "^1.0.0",
+    "typescript": "^5.0.0",
+    "vue-tsc": "^1.8.0"
   },
   "scripts": {
-    "build": "vite build"
+    "build": "vite build && cp src/index.d.ts dist/index.d.ts",
+    "docs:readme": "node scripts/generate-readme.js",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest --coverage",
+    "test:ci": "vitest run --coverage"
   }
 }

package/.turbo/turbo-build.log

@@ -1,14 +0,0 @@
-
-> @getspot/spot-widget-vue@1.3.0 build /builds/getspot/spot-widget/packages/vue
-> vite build
-
-The CJS build of Vite's Node API is deprecated. See https://vite.dev/guide/troubleshooting.html#vite-cjs-node-api-deprecated for more details.
-vite v5.4.18 building for production...
-transforming...
-✓ 2 modules transformed.
-No name was provided for external module "@getspot/spot-widget" in "output.globals" – guessing "SpotWidget".
-rendering chunks...
-computing gzip size...
-dist/index.umd.js  3.65 kB │ gzip: 1.19 kB
-dist/index.es.js  4.99 kB │ gzip: 1.30 kB
-✓ built in 537ms

package/src/VueSpotWidget.vue

@@ -1,227 +0,0 @@
-<template>
-  <div ref="container" />
-</template>
-
-<script>
-import SpotWidget from "@getspot/spot-widget";
-
-export default {
-  name: "VueSpotWidget",
-  props: {
-    apiConfig: {
-      type: Object,
-      default: undefined,
-    },
-    quoteRequestData: {
-      type: [Object, Array],
-      default: undefined,
-    },
-    showTable: {
-      type: Boolean,
-      default: true,
-    },
-    optInSelected: {
-      type: Boolean,
-      default: false,
-    },
-    theme: {
-      type: Object,
-      default: undefined,
-    },
-    callbacks: {
-      type: Object,
-      default: () => ({}),
-    },
-    onQuoteRetrieved: {
-      type: Function,
-      default: undefined,
-    },
-    onOptIn: {
-      type: Function,
-      default: undefined,
-    },
-    onOptOut: {
-      type: Function,
-      default: undefined,
-    },
-    onError: {
-      type: Function,
-      default: undefined,
-    },
-    onNoMatchingQuote: {
-      type: Function,
-      default: undefined,
-    },
-    onSelectionChange: {
-      type: Function,
-      default: undefined,
-    },
-    options: {
-      type: Object,
-      default: () => ({}),
-    },
-  },
-  data() {
-    return {
-      widget: null,
-      reinitTimeout: null,
-    };
-  },
-  computed: {
-    mergedCallbacks() {
-      return {
-        ...this.callbacks,
-        ...(this.onQuoteRetrieved && { onQuoteRetrieved: this.onQuoteRetrieved }),
-        ...(this.onOptIn && { 
-          onOptIn: (data) => {
-            this.onOptIn?.(data);
-            this.onSelectionChange?.(data);
-          }
-        }),
-        ...(this.onOptOut && { 
-          onOptOut: (data) => {
-            this.onOptOut?.(data);
-            this.onSelectionChange?.(data);
-          }
-        }),
-        ...(this.onError && { onError: this.onError }),
-        ...(this.onNoMatchingQuote && { onNoMatchingQuote: this.onNoMatchingQuote }),
-      };
-    },
-    widgetOptions() {
-      return {
-        apiConfig: this.apiConfig,
-        quoteRequestData: this.quoteRequestData,
-        showTable: this.showTable,
-        optInSelected: this.optInSelected,
-        theme: this.theme,
-        callbacks: this.mergedCallbacks,
-        ...this.options,
-      };
-    },
-  },
-  mounted() {
-    this.initializeWidget();
-  },
-  watch: {
-    quoteRequestData: {
-      handler(newQuoteRequestData, oldQuoteRequestData) {
-        if (this.widget && newQuoteRequestData && JSON.stringify(newQuoteRequestData) !== JSON.stringify(oldQuoteRequestData)) {
-          // Debounce reinitialize to prevent multiple rapid updates
-          if (this.reinitTimeout) {
-            clearTimeout(this.reinitTimeout);
-          }
-          
-          this.reinitTimeout = setTimeout(() => {
-            this.reinitializeWidget();
-            this.reinitTimeout = null;
-          }, 100);
-        }
-      },
-      deep: true,
-    },
-    apiConfig: {
-      handler() {
-        this.reinitializeWidget();
-      },
-      deep: true,
-    },
-    showTable(newVal, oldVal) {
-      if (newVal !== oldVal) {
-        this.reinitializeWidget();
-      }
-    },
-    optInSelected(newVal, oldVal) {
-      if (newVal !== oldVal) {
-        this.reinitializeWidget();
-      }
-    },
-    theme: {
-      handler(newTheme, oldTheme) {
-        if (this.widget && JSON.stringify(newTheme) !== JSON.stringify(oldTheme)) {
-          this.updateTheme(newTheme);
-        }
-      },
-      deep: true,
-    },
-    mergedCallbacks: {
-      handler(newCallbacks, oldCallbacks) {
-        if (this.widget && JSON.stringify(newCallbacks) !== JSON.stringify(oldCallbacks)) {
-          this.updateCallbacks(newCallbacks);
-        }
-      },
-      deep: true,
-    },
-  },
-  methods: {
-    initializeWidget() {
-      // Destroy any existing widget first
-      if (this.widget) {
-        this.widget.destroy();
-        this.widget = null;
-      }
-      
-      // Clear the container completely
-      if (this.$refs.container) {
-        this.$refs.container.innerHTML = '';
-      }
-      
-      // Add a small delay to ensure DOM is ready
-      this.$nextTick(() => {
-        try {
-          this.widget = new SpotWidget({
-            ...this.widgetOptions,
-            location: this.$refs.container,
-          });
-        } catch (err) {
-          this.$emit("error", err);
-          this.onError?.(err);
-        }
-      });
-    },
-    reinitializeWidget() {
-      if (this.widget) {
-        this.widget.destroy();
-        this.widget = null;
-      }
-      this.initializeWidget();
-    },
-    async updateQuote(newQuoteRequestData) {
-      return this.widget?.updateQuote(newQuoteRequestData);
-    },
-    getSelection() {
-      return this.widget?.getSelection();
-    },
-    validateSelection() {
-      return this.widget?.validateSelection();
-    },
-    updateTheme(newTheme) {
-      if (!this.widget || !this.widget.container) return;
-      
-      Object.entries(newTheme || {}).forEach(([k, v]) => {
-        const cssVariable = `--${k}`;
-        this.widget.container.style.setProperty(cssVariable, v);
-      });
-    },
-    updateCallbacks(newCallbacks) {
-      if (!this.widget) return;
-      
-      this.widget.options.callbacks = newCallbacks;
-    },
-    destroy() {
-      if (this.widget && typeof this.widget.destroy === "function") {
-        this.widget.destroy();
-        this.widget = null;
-      }
-    },
-  },
-  beforeUnmount() {
-    if (this.reinitTimeout) {
-      clearTimeout(this.reinitTimeout);
-    }
-    if (this.widget && typeof this.widget.destroy === "function") {
-      this.widget.destroy();
-    }
-  },
-};
-</script>

package/vite.config.js

@@ -1,24 +0,0 @@
-import { defineConfig } from "vite";
-import vue from "@vitejs/plugin-vue";
-import path from "path";
-
-export default defineConfig({
-  plugins: [vue()],
-  build: {
-    outDir: "dist",
-    lib: {
-      entry: path.resolve(__dirname, "src/VueSpotWidget.vue"),
-      name: "VueSpotWidget",
-      fileName: (format) => `index.${format}.js`,
-      formats: ["umd", "es"],
-    },
-    rollupOptions: {
-      external: ["vue", "@getspot/spot-widget"],
-      output: {
-        globals: {
-          vue: "Vue",
-        },
-      },
-    },
-  },
-});