@getspot/spot-widget 1.4.0 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @getspot/spot-widget
 
+## 2.0.1
+
+### Patch Changes
+
+- ccc78eb: Fix npm docs generation for interfaces and types
+
+## 2.0.0
+
+### Major Changes
+
+- 4c59d56: Typescript support
+
 ## 1.4.0
 
 ### Minor Changes

package/README.md

@@ -1,12 +1,569 @@
-# Spot Widget
+# @getspot/spot-widget
 
-## Description
-This is a UI component for displaying a quote offer to users in a checkout flow
+Core JavaScript/TypeScript library for integrating Spot's refund guarantee widget into your applications.
 
 ## Installation
 
 ```bash
-npm install --save @getspot/spot-widget
+npm install @getspot/spot-widget
 ```
 
-## Usage
+## Quick Start
+
+```javascript
+import SpotWidget from '@getspot/spot-widget';
+
+// Create widget instance
+const widget = new SpotWidget({
+  location: '#spot-widget-container', // CSS selector or DOM element
+  apiConfig: {
+    environment: 'production', // 'sandbox' for testing
+    partnerId: 'your-partner-id'
+  },
+  quoteRequestData: {
+    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'
+  },
+  callbacks: {
+    onOptIn: (data) => {
+      console.log('User opted in:', data);
+      // Handle opt-in logic
+    },
+    onOptOut: (data) => {
+      console.log('User opted out:', data);
+      // Handle opt-out logic
+    },
+    onQuoteRetrieved: (quote) => {
+      console.log('Quote retrieved:', quote);
+    },
+    onError: (error) => {
+      console.error('Widget error:', error);
+    }
+  }
+});
+```
+
+## TypeScript Support
+
+This package is written in TypeScript and includes full type definitions.
+
+```typescript
+import SpotWidget, { SpotWidgetOptions, SelectionData, Quote } from '@getspot/spot-widget';
+
+const options: SpotWidgetOptions = {
+  // ... your configuration
+};
+
+const widget = new SpotWidget(options);
+```
+
+## Configuration
+
+### SpotWidgetOptions
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `location` | `string \| HTMLElement` | No | `"body"` | Target element for the widget |
+| `apiConfig` | `ApiConfig` | Yes | - | API configuration |
+| `quoteRequestData` | `QuoteRequestData` | Yes | - | Quote request information |
+| `showTable` | `boolean` | No | `true` | Whether to show payout table |
+| `optInSelected` | `boolean` | No | `false` | Pre-select opt-in option |
+| `theme` | `Theme` | No | - | Custom styling |
+| `callbacks` | `Callbacks` | No | `{}` | Event callbacks |
+
+### ApiConfig
+
+```typescript
+{
+  environment: 'production' | 'sandbox' | 'local';
+  partnerId: string;
+  customEndpoint?: string; // Optional custom API endpoint
+}
+```
+
+### QuoteRequestData
+
+#### Single Product Quote
+
+```typescript
+{
+  startDate: string;        // ISO 8601 date
+  endDate: string;          // ISO 8601 date
+  currencyCode: 'USD' | 'CAD' | 'AUD';
+  eventType: string;        // Event description
+  productType: 'Pass' | 'Trip' | 'Registration';
+  productDuration: 'Daily' | 'Seasonal' | 'Trip' | 'Event';
+  productPrice: number;     // Price in specified currency
+  productId: string;        // Unique product identifier
+  cartId: string;           // Shopping cart identifier
+  productName: string;      // Human-readable product name
+  participantDescription?: string; // Optional participant info
+}
+```
+
+#### Batch Quote (Multiple Products)
+
+```typescript
+{
+  cartInfo: {
+    cartId: string;
+    cartName: string;
+    currencyCode: 'USD' | 'CAD' | 'AUD';
+  };
+  items: Array<{
+    // All single product fields except cartId and currencyCode
+    cartItemId?: string; // Optional item identifier
+  }>;
+}
+```
+
+## Widget Methods
+
+### updateQuote(newQuoteRequestData)
+
+Update the widget with new quote data.
+
+```javascript
+const success = await widget.updateQuote({
+  // new quote request data
+});
+console.log('Update successful:', success);
+```
+
+**Returns:** `Promise<boolean>`
+
+### getSelection()
+
+Get the current user selection.
+
+```javascript
+const selection = widget.getSelection();
+console.log('User selection:', selection);
+```
+
+**Returns:** `SelectionData | null`
+
+### validateSelection()
+
+Check if the user has made a selection.
+
+```javascript
+const isValid = widget.validateSelection();
+if (!isValid) {
+  console.log('Please make a selection');
+}
+```
+
+**Returns:** `boolean`
+
+### destroy()
+
+Clean up the widget instance.
+
+```javascript
+widget.destroy();
+```
+
+## Callbacks
+
+### onOptIn(data: SelectionData)
+
+Called when user opts into the refund guarantee.
+
+```javascript
+{
+  onOptIn: (data) => {
+    console.log('Opt-in data:', data);
+    // data.status === 'QUOTE_ACCEPTED'
+    // data.quoteId - unique quote identifier
+    // data.spotPrice - refund guarantee price
+  }
+}
+```
+
+### onOptOut(data: SelectionData)
+
+Called when user opts out of the refund guarantee.
+
+```javascript
+{
+  onOptOut: (data) => {
+    console.log('Opt-out data:', data);
+    // data.status === 'QUOTE_DECLINED'
+    // data.quoteId - unique quote identifier
+  }
+}
+```
+
+### onQuoteRetrieved(quote: Quote)
+
+Called when a quote is successfully retrieved.
+
+```javascript
+{
+  onQuoteRetrieved: (quote) => {
+    console.log('Quote:', quote);
+    // quote.id - quote identifier
+    // quote.spotPrice - refund guarantee price
+    // quote.communication - display text and labels
+  }
+}
+```
+
+### onError(error: ErrorData)
+
+Called when an error occurs.
+
+```javascript
+{
+  onError: (error) => {
+    console.error('Error:', error);
+    // error.message - error description
+    // error.status - HTTP status code (if applicable)
+    // error.responseBody - API response (if applicable)
+  }
+}
+```
+
+### noMatchingQuote(data)
+
+Called when no quote is available for the request.
+
+```javascript
+{
+  noMatchingQuote: (data) => {
+    console.log('No quote available:', data);
+    // Handle case where product isn't eligible
+  }
+}
+```
+
+## Styling
+
+Customize the widget appearance using the `theme` option:
+
+```javascript
+const widget = new SpotWidget({
+  // ... other options
+  theme: {
+    primaryColor: '#007bff',
+    secondaryColor: '#6c757d',
+    borderRadius: '8px',
+    fontFamily: 'Arial, sans-serif',
+    fontSize: '14px'
+    // Any CSS custom properties (without -- prefix)
+  }
+});
+```
+
+## Error Handling
+
+Always implement comprehensive error handling:
+
+```javascript
+const widget = new SpotWidget({
+  // ... configuration
+  callbacks: {
+    onError: (error) => {
+      // Log for debugging
+      console.error('Spot Widget Error:', error);
+      
+      // Handle different error types
+      if (error.status === 404) {
+        console.log('Product not eligible for refund guarantee');
+      } else if (error.status >= 500) {
+        console.log('Service temporarily unavailable');
+      }
+      
+      // Track in analytics
+      if (window.analytics) {
+        window.analytics.track('spot_widget_error', {
+          message: error.message,
+          status: error.status
+        });
+      }
+    },
+    noMatchingQuote: (data) => {
+      console.log('No refund guarantee available');
+      // Hide widget or show alternative messaging
+    }
+  }
+});
+```
+
+## Environments
+
+### Sandbox (Development)
+
+Use the sandbox environment for testing:
+
+```javascript
+{
+  apiConfig: {
+    environment: 'sandbox',
+    partnerId: 'your-sandbox-partner-id'
+  }
+}
+```
+
+### Production
+
+Use the production environment for live applications:
+
+```javascript
+{
+  apiConfig: {
+    environment: 'production',
+    partnerId: 'your-production-partner-id'
+  }
+}
+```
+
+
+
+## API Reference
+
+This package exports the following types and interfaces:
+
+### Interfaces
+
+#### ApiConfig
+
+```typescript
+export interface ApiConfig {
+  environment: 'sandbox' | 'production' | 'local';
+  partnerId: string;
+  customEndpoint?: string;
+}
+```
+
+#### QuoteMetadata
+
+```typescript
+export interface QuoteMetadata {
+  segment?: string;
+  operator?: string;
+  channel?: string;
+  consumerId?: string;
+}
+```
+
+#### CartInfo
+
+```typescript
+export interface CartInfo {
+  cartId: string;
+  cartName: string;
+  currencyCode: 'USD' | 'CAD' | 'AUD';
+  metadata?: QuoteMetadata;
+  isPartialPayment?: boolean;
+}
+```
+
+#### QuoteItem
+
+```typescript
+export interface QuoteItem {
+  productPrice: number;
+  productType: 'Pass' | 'Trip' | 'Registration';
+  productDuration: 'Daily' | 'Seasonal' | 'Trip' | 'Event';
+  productId: string;
+  cartId: string;
+  cartName: string;
+  productName: string;
+  participantDescription?: string;
+  eventType: string;
+  currencyCode: 'USD' | 'CAD' | 'AUD';
+  startDate: string;
+  endDate: string;
+  partnerRiskEnd?: Date;
+  metadata?: QuoteMetadata;
+  isPartialPayment?: boolean;
+  hostCountry?: string;
+  hostCountryState?: string;
+  destinations?: string[];
+  dob?: string;
+}
+```
+
+#### BatchQuoteRequest
+
+```typescript
+export interface BatchQuoteRequest {
+  cartInfo: CartInfo;
+  items: BatchQuoteItem[];
+}
+```
+
+#### QualifyingReason
+
+```typescript
+export interface QualifyingReason {
+  rank: number;
+  name?: string;
+  benefitType?: {
+    name: string;
+  };
+}
+```
+
+#### PayoutScheduleItem
+
+```typescript
+export interface PayoutScheduleItem {
+  text: string;
+  percent: string | number;
+  amount: number;
+}
+```
+
+#### Communication
+
+```typescript
+export interface Communication {
+  name: string;
+  description: string;
+  bulletPoints: string[];
+  yesOptionText: string;
+  noOptionText: string;
+  legalDisclaimer: string;
+  termsAndConditionsUrl: string;
+  paymentTerms?: string;
+}
+```
+
+#### Quote
+
+```typescript
+export interface Quote {
+  id: string;
+  cartItemId?: string;
+  spotPrice: number;
+  currencyCode: string;
+  communication: Communication;
+  payoutSchedule: PayoutScheduleItem[];
+  qualifyingReasons?: QualifyingReason[];
+  coveredItems?: string[];
+  originalQuotes?: Quote[];
+}
+```
+
+#### ApiResponse
+
+```typescript
+export interface ApiResponse {
+  status: 'QUOTE_AVAILABLE' | 'QUOTES_AVAILABLE' | 'NO_MATCHING_QUOTE';
+  data?: Quote;
+  quotes?: Quote[];
+  totalSpotPrice?: number;
+  spotPrice?: number;
+  currencyCode?: string;
+  communication?: Communication;
+  payoutSchedule?: PayoutScheduleItem[];
+  coveredItems?: string[];
+}
+```
+
+#### SelectionData
+
+```typescript
+export interface SelectionData {
+  status: 'QUOTE_ACCEPTED' | 'QUOTE_DECLINED';
+  spotPrice?: number;
+  quoteId?: string;
+  selection?: string;
+  batchQuoteDetails?: Array<{
+    quoteId: string;
+    productPrice: number;
+    cartItemId: string;
+  }>;
+}
+```
+
+#### Callbacks
+
+```typescript
+export interface Callbacks {
+  onOptIn?: (data: SelectionData) => void;
+  onOptOut?: (data: SelectionData) => void;
+  onQuoteRetrieved?: (quote: Quote) => void;
+  onError?: (error: { message: string; status?: number; responseBody?: any }) => void;
+  noMatchingQuote?: (data: { status: string; data: QuoteRequestData }) => void;
+}
+```
+
+#### Theme
+
+```typescript
+export interface Theme {
+  [key: string]: string;
+}
+```
+
+#### SpotWidgetOptions
+
+```typescript
+export interface SpotWidgetOptions {
+  location?: string | HTMLElement;
+  showTable?: boolean;
+  optInSelected?: boolean;
+  apiConfig: ApiConfig;
+  quoteRequestData: QuoteRequestData;
+  callbacks?: Callbacks;
+  theme?: Theme;
+  isPartialPayment?: boolean;
+}
+```
+
+#### ElementOptions
+
+```typescript
+export interface ElementOptions {
+  text?: string;
+  className?: string;
+  parent?: HTMLElement;
+  innerHTML?: string;
+  href?: string;
+  target?: string;
+}
+```
+
+### Type Aliases
+
+#### QuoteRequestData
+
+```typescript
+export type QuoteRequestData = QuoteItem | BatchQuoteRequest;
+```
+
+## Framework Integration
+
+This is the core library. For framework-specific wrappers:
+
+- **React**: [@getspot/spot-widget-react](../react)
+- **Vue 3**: [@getspot/spot-widget-vue](../vue)  
+- **Vue 2**: [@getspot/spot-widget-vue2](../vue2)
+
+## Browser Support
+
+- Modern browsers (ES2020+)
+- Chrome 80+
+- Firefox 74+
+- Safari 13+
+- Edge 80+
+
+## License
+
+See the main package for license information.
+
+## Support
+
+For support, please contact [support@getspot.com](mailto:support@getspot.com).

package/dist/__mocks__/ui.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="jest" />
+export declare const renderHeader: jest.Mock<any, any, any>;
+export declare const renderBenefits: jest.Mock<any, any, any>;
+export declare const renderQualifyingReasons: jest.Mock<any, any, any>;
+export declare const renderPayoutTable: jest.Mock<any, any, any>;
+export declare const renderConsentSection: jest.Mock<any, any, any>;
+export declare const renderError: jest.Mock<any, any, any>;
+export declare const renderNoMatchingQuote: jest.Mock<any, any, any>;
+export declare const addEventListeners: jest.Mock<any, any, any>;
+export declare const toggleOptIn: jest.Mock<any, any, any>;
+export declare const updateQualifyingReasonVisibility: jest.Mock<any, any, any>;
+//# sourceMappingURL=ui.d.ts.map

package/dist/__mocks__/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../src/__mocks__/ui.ts"],"names":[],"mappings":";AAEA,eAAO,MAAM,YAAY,0BAA2D,CAAC;AACrF,eAAO,MAAM,cAAc,0BAAY,CAAC;AACxC,eAAO,MAAM,uBAAuB,0BAAY,CAAC;AACjD,eAAO,MAAM,iBAAiB,0BAAY,CAAC;AAC3C,eAAO,MAAM,oBAAoB,0BAAY,CAAC;AAC9C,eAAO,MAAM,WAAW,0BAAY,CAAC;AACrC,eAAO,MAAM,qBAAqB,0BAAY,CAAC;AAC/C,eAAO,MAAM,iBAAiB,0BAAY,CAAC;AAC3C,eAAO,MAAM,WAAW,0BAAY,CAAC;AACrC,eAAO,MAAM,gCAAgC,0BAAY,CAAC"}

package/dist/api.d.ts

@@ -0,0 +1,26 @@
+import type { ApiResponse, QuoteRequestData, BatchQuoteRequest } from './types.js';
+/**
+ * Retrieve quote from Spot API
+ * @param endpoint   – Spot API URL
+ * @param partnerId  – partner UUID
+ * @param payload    – quoteRequestData
+ * @returns Promise resolving to API response
+ */
+export declare function fetchQuote(endpoint: string, partnerId: string, payload: QuoteRequestData): Promise<ApiResponse>;
+/**
+ * Retrieve batch quote from Spot API
+ * @param endpoint   – Spot API URL
+ * @param partnerId  – partner UUID
+ * @param batchPayload – batch request data with items array
+ * @returns Promise resolving to API response
+ */
+export declare function fetchBatchQuote(endpoint: string, partnerId: string, batchPayload: any): Promise<ApiResponse>;
+/**
+ * Retrieve multiple quotes in parallel from Spot API
+ * @param endpoint   – Spot API URL
+ * @param partnerId  – partner UUID
+ * @param batchData  – batch quote data with cartInfo and items
+ * @returns Promise resolving to formatted API response
+ */
+export declare function fetchMultipleQuotes(endpoint: string, partnerId: string, batchData: BatchQuoteRequest): Promise<ApiResponse>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAY,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE7F;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,WAAW,CAAC,CAwBtB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,GAAG,GAChB,OAAO,CAAC,WAAW,CAAC,CAyBtB;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,iBAAiB,GAC3B,OAAO,CAAC,WAAW,CAAC,CA8EtB"}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import type { SpotWidgetOptions, SelectionData } from "./types.js";
+declare class SpotWidget {
+    private options;
+    private root;
+    private currentSelection;
+    private container?;
+    private paymentTermsEl?;
+    private errorEl?;
+    private quote?;
+    private _onResize;
+    constructor(options?: Partial<SpotWidgetOptions>);
+    private _init;
+    private _renderWidget;
+    private _updateLayout;
+    private _setupOptionListeners;
+    showSelectionError(): void;
+    hideSelectionError(): void;
+    validateSelection(): boolean;
+    updateQuote(newQuoteRequestData: SpotWidgetOptions['quoteRequestData']): Promise<boolean>;
+    getSelection(): SelectionData | null;
+    destroy(): void;
+}
+export default SpotWidget;
+export type { SpotWidgetOptions, SelectionData, Quote, ApiConfig, QuoteRequestData, QuoteItem, BatchQuoteItem, BatchQuoteRequest, CartInfo, QualifyingReason, PayoutScheduleItem, Communication, ApiResponse, ApiError, ElementOptions, QuoteMetadata, Callbacks, Theme } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,iBAAiB,EAAS,aAAa,EAAqB,MAAM,YAAY,CAAC;AAkB7F,cAAM,UAAU;IACd,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,gBAAgB,CAAgB;IACxC,OAAO,CAAC,SAAS,CAAC,CAAc;IAChC,OAAO,CAAC,cAAc,CAAC,CAAc;IACrC,OAAO,CAAC,OAAO,CAAC,CAAc;IAC9B,OAAO,CAAC,KAAK,CAAC,CAAQ;IACtB,OAAO,CAAC,SAAS,CAAa;gBAElB,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAM;YAqBtC,KAAK;IAgFnB,OAAO,CAAC,aAAa;IAiDrB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,qBAAqB;IA6F7B,kBAAkB,IAAI,IAAI;IAgB1B,kBAAkB,IAAI,IAAI;IAM1B,iBAAiB,IAAI,OAAO;IAgBtB,WAAW,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAqE/F,YAAY,IAAI,aAAa,GAAG,IAAI;IAiCpC,OAAO,IAAI,IAAI;CAMhB;AAED,eAAe,UAAU,CAAC;AAC1B,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,KAAK,EACL,SAAS,EACT,gBAAgB,EAChB,SAAS,EACT,cAAc,EACd,iBAAiB,EACjB,QAAQ,EACR,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,WAAW,EACX,QAAQ,EACR,cAAc,EACd,aAAa,EACb,SAAS,EACT,KAAK,EACN,MAAM,YAAY,CAAC"}