@getspot/spot-widget 1.3.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @getspot/spot-widget
 
+## 2.0.0
+
+### Major Changes
+
+- 4c59d56: Typescript support
+
+## 1.4.0
+
+### Minor Changes
+
+- 5b3eaaf: add qualifying reasons for pass/trip offers
+
 ## 1.3.0
 
 ### Minor Changes

package/README.md

@@ -1,12 +1,382 @@
-# 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](docs/interfaces/ApiConfig.md)
+- [ApiError](docs/interfaces/ApiError.md)
+- [ApiResponse](docs/interfaces/ApiResponse.md)
+- [BatchQuoteItem](docs/interfaces/BatchQuoteItem.md)
+- [BatchQuoteRequest](docs/interfaces/BatchQuoteRequest.md)
+- [Callbacks](docs/interfaces/Callbacks.md)
+- [CartInfo](docs/interfaces/CartInfo.md)
+- [Communication](docs/interfaces/Communication.md)
+- [ElementOptions](docs/interfaces/ElementOptions.md)
+- [PayoutScheduleItem](docs/interfaces/PayoutScheduleItem.md)
+- [QualifyingReason](docs/interfaces/QualifyingReason.md)
+- [Quote](docs/interfaces/Quote.md)
+- [QuoteItem](docs/interfaces/QuoteItem.md)
+- [QuoteMetadata](docs/interfaces/QuoteMetadata.md)
+- [SelectionData](docs/interfaces/SelectionData.md)
+- [SpotWidgetOptions](docs/interfaces/SpotWidgetOptions.md)
+- [Theme](docs/interfaces/Theme.md)
+
+### Type Aliases
+
+- [QuoteRequestData](docs/type-aliases/QuoteRequestData.md)
+
+> **📚 Full API Documentation**: See [docs/](docs/) for detailed documentation of all types and interfaces.
+
+## 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/briefcase.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-briefcase-icon lucide-briefcase"><path d="M16 20V4a2 2 0 0 0-2-2h-4a2 2 0 0 0-2 2v16"/><rect width="20" height="14" x="2" y="6" rx="2"/></svg>

package/dist/building.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-building2-icon lucide-building-2"><path d="M6 22V4a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2v18Z"/><path d="M6 12H4a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2h2"/><path d="M18 9h2a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2h-2"/><path d="M10 6h4"/><path d="M10 10h4"/><path d="M10 14h4"/><path d="M10 18h4"/></svg>

package/dist/cross.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-cross-icon lucide-cross"><path d="M4 9a2 2 0 0 0-2 2v2a2 2 0 0 0 2 2h4a1 1 0 0 1 1 1v4a2 2 0 0 0 2 2h2a2 2 0 0 0 2-2v-4a1 1 0 0 1 1-1h4a2 2 0 0 0 2-2v-2a2 2 0 0 0-2-2h-4a1 1 0 0 1-1-1V4a2 2 0 0 0-2-2h-2a2 2 0 0 0-2 2v4a1 1 0 0 1-1 1z"/></svg>

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"}