@getspot/spot-widget-vue2 1.4.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @getspot/spot-widget-vue2
 
+## 2.0.0
+
+### Major Changes
+
+- 4c59d56: Typescript support
+
+### Patch Changes
+
+- Updated dependencies [4c59d56]
+  - @getspot/spot-widget@2.0.0
+
 ## 1.4.0
 
 ### Minor Changes

package/README.md

@@ -1,12 +1,444 @@
-# Spot Vue2 Widget
+# @getspot/spot-widget-vue2
 
-## Description
-This is a UI component for displaying a quote offer to users in a checkout flow
+Vue 2 component wrapper for the Spot refund guarantee widget.
+
+> **Note:** This Vue 2 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-vue2
+npm install @getspot/spot-widget-vue2
+```
+
+## Quick Start
+
+```vue
+<template>
+  <Vue2SpotWidget
+    :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>
+import Vue2SpotWidget from '@getspot/spot-widget-vue2';
+
+export default {
+  components: {
+    Vue2SpotWidget
+  },
+  
+  data() {
+    return {
+      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'
+      }
+    };
+  },
+
+  methods: {
+    onQuoteRetrieved(quote) {
+      console.log('Quote retrieved:', quote);
+    },
+
+    onOptIn(data) {
+      console.log('User opted in:', data);
+      // Handle opt-in logic
+    },
+
+    onOptOut(data) {
+      console.log('User opted out:', data);
+      // Handle opt-out logic
+    },
+
+    onError(error) {
+      console.error('Widget error:', error);
+      // Handle errors
+    }
+  }
+};
+</script>
+```
+
+## TypeScript Support
+
+This package includes TypeScript definitions for Vue 2. To use with TypeScript:
+
+```vue
+<template>
+  <Vue2SpotWidget
+    :api-config="apiConfig"
+    :quote-request-data="quoteData"
+    @opt-in="onOptIn"
+    @opt-out="onOptOut"
+    @error="onError"
+  />
+</template>
+
+<script lang="ts">
+import Vue from 'vue';
+import Vue2SpotWidget from '@getspot/spot-widget-vue2';
+import type { Quote, SelectionData, ApiConfig, QuoteRequestData } from '@getspot/spot-widget';
+
+interface Data {
+  apiConfig: ApiConfig;
+  quoteData: QuoteRequestData;
+}
+
+export default Vue.extend({
+  components: {
+    Vue2SpotWidget
+  },
+  
+  data(): Data {
+    return {
+      apiConfig: {
+        environment: 'production',
+        partnerId: 'your-partner-id'
+      },
+      quoteData: {
+        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: {
+    onOptIn(data: SelectionData) {
+      console.log('User opted in:', data);
+    },
+
+    onOptOut(data: SelectionData) {
+      console.log('User opted out:', data);
+    },
+
+    onError(error: Error) {
+      console.error('Widget error:', error);
+    }
+  }
+});
+</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
+<Vue2SpotWidget @quote-retrieved="onQuoteRetrieved" />
+```
+
+**Payload:** `Quote` object
+
+### @opt-in
+
+Emitted when user opts in to the refund guarantee.
+
+```vue
+<Vue2SpotWidget @opt-in="onOptIn" />
+```
+
+**Payload:** `SelectionData` object with `status: 'QUOTE_ACCEPTED'`
+
+### @opt-out
+
+Emitted when user opts out of the refund guarantee.
+
+```vue
+<Vue2SpotWidget @opt-out="onOptOut" />
+```
+
+**Payload:** `SelectionData` object with `status: 'QUOTE_DECLINED'`
+
+### @error
+
+Emitted when an error occurs during quote retrieval.
+
+```vue
+<Vue2SpotWidget @error="onError" />
+```
+
+**Payload:** Error object with `message`, `status`, and `responseBody`
+
+### @no-matching-quote
+
+Emitted when no matching quote is found.
+
+```vue
+<Vue2SpotWidget @no-matching-quote="onNoMatchingQuote" />
 ```
 
-## Usage
+**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
+<Vue2SpotWidget @selection-change="onSelectionChange" />
+```
+
+**Payload:** `SelectionData` object
+
+## Exposed Methods
+
+You can access widget methods using template refs:
+
+```vue
+<template>
+  <div>
+    <Vue2SpotWidget
+      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>
+import Vue2SpotWidget from '@getspot/spot-widget-vue2';
+
+export default {
+  components: {
+    Vue2SpotWidget
+  },
+
+  methods: {
+    async updateQuote() {
+      const success = await this.$refs.spotWidget.updateQuote({
+        // new quote data
+      });
+      console.log('Quote updated:', success);
+    },
+
+    getSelection() {
+      const selection = this.$refs.spotWidget.getSelection();
+      console.log('Current selection:', selection);
+    },
+
+    validateSelection() {
+      const isValid = this.$refs.spotWidget.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>
+  <Vue2SpotWidget
+    :theme="{
+      primaryColor: '#007bff',
+      borderRadius: '8px',
+      fontFamily: 'Arial, sans-serif'
+    }"
+    v-bind="otherProps"
+  />
+</template>
+```
+
+## Error Handling
+
+Always implement error handling for production use:
+
+```vue
+<template>
+  <div>
+    <Vue2SpotWidget
+      v-bind="widgetProps"
+      @error="handleError"
+      @no-matching-quote="handleNoQuote"
+    />
+    <div v-if="errorMessage" class="error-message">
+      {{ errorMessage }}
+    </div>
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      errorMessage: ''
+    };
+  },
+
+  methods: {
+    handleError(error) {
+      console.error('Spot Widget Error:', error);
+      
+      // Show user-friendly message
+      this.errorMessage = '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
+        });
+      }
+    },
+
+    handleNoQuote() {
+      this.errorMessage = 'No refund guarantee available for this product.';
+    }
+  }
+};
+</script>
+```
+
+## Vue 2 Specific Notes
+
+This package is specifically designed for Vue 2.x applications. Key differences from the Vue 3 version:
+
+- Uses Vue 2 Options API syntax
+- Compatible with Vue 2.6+ (requires Vue 2.7+ for full TypeScript support)
+- Uses `beforeDestroy` lifecycle hook instead of `beforeUnmount`
+- Function-based watchers instead of arrow functions for Vue 2 compatibility
+
+## Compatibility
+
+- **Vue**: 2.6+
+- **TypeScript**: 4.x - 5.x (requires Vue 2.7+ for full TS support)
+- **Node.js**: 16+
+
+## Migration from Vue 2 to Vue 3
+
+If you're migrating from Vue 2 to Vue 3, consider switching to `@getspot/spot-widget-vue` which is designed for Vue 3 and includes:
+
+- Composition API support
+- Better TypeScript integration
+- Modern Vue 3 lifecycle hooks
+- Enhanced performance
+
+## 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 Vue from 'vue';
+import type { SpotWidgetOptions, SelectionData, Quote } from '@getspot/spot-widget';
+
+export interface Vue2SpotWidgetProps 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 Vue2SpotWidgetMethods {
+  updateQuote: (newQuoteRequestData: SpotWidgetOptions['quoteRequestData']) => Promise<boolean>;
+  getSelection: () => SelectionData | null;
+  validateSelection: () => boolean;
+  destroy: () => void;
+}
+
+declare const Vue2SpotWidget: Vue.Component<Vue2SpotWidgetProps, Vue2SpotWidgetMethods>;
+
+export default Vue2SpotWidget;

package/package.json

@@ -1,22 +1,39 @@
 {
   "name": "@getspot/spot-widget-vue2",
-  "version": "1.4.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.4.0"
+    "@getspot/spot-widget": "2.0.0"
   },
   "peerDependencies": {
     "vue": "^2.6.0"
   },
   "devDependencies": {
     "vite": "^4.0.0",
-    "@vitejs/plugin-vue2": "^2.0.0"
+    "@vitejs/plugin-vue2": "^2.0.0",
+    "vitest": "^0.34.0",
+    "@vitest/coverage-v8": "^0.34.0",
+    "jsdom": "^22.0.0",
+    "@vue/test-utils": "^1.3.6",
+    "vue": "^2.7.14",
+    "vue-template-compiler": "^2.7.14"
   },
   "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,13 +0,0 @@
-
-> @getspot/spot-widget-vue2@1.4.0 build /builds/getspot/spot-widget/packages/vue2
-> vite build
-
-vite v4.5.13 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  4.41 kB │ gzip: 1.47 kB
-dist/index.es.js  5.98 kB │ gzip: 1.66 kB
-✓ built in 396ms

package/src/Vue2SpotWidget.vue

@@ -1,230 +0,0 @@
-<template>
-  <div ref="container" />
-</template>
-
-<script>
-import SpotWidget from "@getspot/spot-widget";
-
-export default {
-  name: "Vue2SpotWidget",
-  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) => {
-            if (this.onOptIn) this.onOptIn(data);
-            if (this.onSelectionChange) this.onSelectionChange(data);
-          }
-        }),
-        ...(this.onOptOut && { 
-          onOptOut: (data) => {
-            if (this.onOptOut) this.onOptOut(data);
-            if (this.onSelectionChange) 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: function(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: function() {
-        this.reinitializeWidget();
-      },
-      deep: true,
-    },
-    showTable: function(newVal, oldVal) {
-      if (newVal !== oldVal) {
-        this.reinitializeWidget();
-      }
-    },
-    optInSelected: function(newVal, oldVal) {
-      if (newVal !== oldVal) {
-        this.reinitializeWidget();
-      }
-    },
-    theme: {
-      handler: function(newTheme, oldTheme) {
-        if (this.widget && JSON.stringify(newTheme) !== JSON.stringify(oldTheme)) {
-          this.updateTheme(newTheme);
-        }
-      },
-      deep: true,
-    },
-    mergedCallbacks: {
-      handler: function(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);
-          if (this.onError) this.onError(err);
-        }
-      });
-    },
-    reinitializeWidget() {
-      if (this.widget) {
-        this.widget.destroy();
-        this.widget = null;
-      }
-      this.initializeWidget();
-    },
-    async updateQuote(newQuoteRequestData) {
-      return this.widget && this.widget.updateQuote ? this.widget.updateQuote(newQuoteRequestData) : undefined;
-    },
-    getSelection() {
-      return this.widget && this.widget.getSelection ? this.widget.getSelection() : undefined;
-    },
-    validateSelection() {
-      return this.widget && this.widget.validateSelection ? this.widget.validateSelection() : undefined;
-    },
-    updateTheme: function(newTheme) {
-      if (!this.widget || !this.widget.container) return;
-      
-      var entries = Object.keys(newTheme || {});
-      for (var i = 0; i < entries.length; i++) {
-        var key = entries[i];
-        var value = newTheme[key];
-        var cssVariable = "--" + key;
-        this.widget.container.style.setProperty(cssVariable, value);
-      }
-    },
-    updateCallbacks: function(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;
-      }
-    },
-  },
-  beforeDestroy() {
-    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-vue2";
-import path from "path";
-
-export default defineConfig({
-  plugins: [vue()],
-  build: {
-    outDir: "dist",
-    lib: {
-      entry: path.resolve(__dirname, "src/Vue2SpotWidget.vue"),
-      name: "Vue2SpotWidget",
-      fileName: (format) => `index.${format}.js`,
-      formats: ["umd", "es"],
-    },
-    rollupOptions: {
-      external: ["vue", "@getspot/spot-widget"],
-      output: {
-        globals: {
-          vue: "Vue",
-        },
-      },
-    },
-  },
-});