ui.shipaid.com 0.2.4 → 0.2.5

package/README.md

@@ -1,80 +1,80 @@
-# ShipAid Shopify Widget
-
-This is the repository for the ShipAid Shopify (and possibly others in future) widget. It uses the [Lit](https://lit.dev/) web components library, so it is recommended to become familiar with it before contributing to this repository.
-
-Using Lit provides a framework that allows us to build a reactive UI, using JSX-like syntax - no need to use JQuery etc. And it can easily be installed in a page by using the custom web component name:
-```html
-<shipaid-widget>Fallback Content</shipaid-widget>
-```
-
-## Overview
-
-This widget provides an interface where a user can choose to add or remove ShipAid protection - this is actually a product in their store that can be added to cart. When the component is loaded, we immediately run a request to fetch the ShipAid protection product details from our API, as well as the customers current cart from the [Shopify AJAX API](https://shopify.dev/api/ajax/reference/cart).
-Once we have this data, we can check whether the customer currently has the ShipAid product in their cart, and show either the add or remove product buttons based on this.
-
-We also emit various [custom events](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events#adding_custom_data_%E2%80%93_customevent) when we add or remove the ShipAid product from the cart, so other developers can listen to these events, and update AJAX carts.
-
-### Events
-
-This is a list of the events emitted by the widget:
-
-| Event | Description | Payload |
-|-------|-------------|---------|
-| `shipaid-loaded` | Dispatched when the widget has finished fetching data from the API, and has successfully rendered. | Contains the data from the ShipAid API: [`ShipAidStore`](/types/shipaid.ts) |
-| `shipaid-protection-status` | Dispatched when a user either adds or removes the protection product from their cart. | `{ protection: boolean, cart: ShopifyCart, lineItem: ShopifyCartItem }` |
-
-### Methods
-
-This is a list of public methods that can be used to change protection settings:
-
-| Method | Description | Payload |
-|--------|-------------|---------|
-| `hasProtection` | Returns a boolean which indicates whether the protection item is currently in the cart. | |
-| `updateCart` | Updates the internal cart, and triggers any protection product updates - use this method with with ajax carts, to update protection state without needing to reload the page. | Optional - the cart object from the ajax API. |
-| `addProtection` | Adds the relevant protection item to cart. | |
-| `removeProtection` | Removes the protection item from the cart. | |
-
-## Contributing
-
-### Requirements
-
-- Node v16+
-- PNPM
-- Development Shopify store (with the ShipAid app installed)
-- ShipAid API development/staging instance
-
-### Development
-
-You will need to make sure your development store has the ShipAid app installed, so the store and its protection product is added to the DB. You will also need to ensure the Shopify app you are testing this with has an app proxy added, and pointed towards an API instance.
-
-```sh
-pnpm install
-pnpm run develop
-```
-
-Once the project is running, add the below to your development Shopify store `theme.liquid`:
-
-```html
-<!-- Dev -->
-<script src="http://localhost:3000/src/shipaid-widget.ts"type="module" ></script>
-<!-- Prod -->
-<script src="https://unpkg.com/ui.shipaid.com?module" type="module"></script>
-```
-And add the widget element in your cart (likely `/sections/main-cart-items.liquid`):
-
-```html
-<shipaid-widget>
-  <p>Loading ShipAid Protection</p>
-</shipaid-widget>
-```
-
-### Build
-
-Once the project has been built, you can publish the project to NPM, and users can add the script to their store using a package CDN (I.e. [Unpkg](https://unpkg.com/)).
-
-```sh
-pnpm install
-pnpm run lint
-pnpm run build
-pnpm publish
-```
+# ShipAid Shopify Widget
+
+This is the repository for the ShipAid Shopify (and possibly others in future) widget. It uses the [Lit](https://lit.dev/) web components library, so it is recommended to become familiar with it before contributing to this repository.
+
+Using Lit provides a framework that allows us to build a reactive UI, using JSX-like syntax - no need to use JQuery etc. And it can easily be installed in a page by using the custom web component name:
+```html
+<shipaid-widget>Fallback Content</shipaid-widget>
+```
+
+## Overview
+
+This widget provides an interface where a user can choose to add or remove ShipAid protection - this is actually a product in their store that can be added to cart. When the component is loaded, we immediately run a request to fetch the ShipAid protection product details from our API, as well as the customers current cart from the [Shopify AJAX API](https://shopify.dev/api/ajax/reference/cart).
+Once we have this data, we can check whether the customer currently has the ShipAid product in their cart, and show either the add or remove product buttons based on this.
+
+We also emit various [custom events](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events#adding_custom_data_%E2%80%93_customevent) when we add or remove the ShipAid product from the cart, so other developers can listen to these events, and update AJAX carts.
+
+### Events
+
+This is a list of the events emitted by the widget:
+
+| Event | Description | Payload |
+|-------|-------------|---------|
+| `shipaid-loaded` | Dispatched when the widget has finished fetching data from the API, and has successfully rendered. | Contains the data from the ShipAid API: [`ShipAidStore`](/types/shipaid.ts) |
+| `shipaid-protection-status` | Dispatched when a user either adds or removes the protection product from their cart. | `{ protection: boolean, cart: ShopifyCart, lineItem: ShopifyCartItem }` |
+
+### Methods
+
+This is a list of public methods that can be used to change protection settings:
+
+| Method | Description | Payload |
+|--------|-------------|---------|
+| `hasProtection` | Returns a boolean which indicates whether the protection item is currently in the cart. | |
+| `updateCart` | Updates the internal cart, and triggers any protection product updates - use this method with with ajax carts, to update protection state without needing to reload the page. | Optional - the cart object from the ajax API. |
+| `addProtection` | Adds the relevant protection item to cart. | |
+| `removeProtection` | Removes the protection item from the cart. | |
+
+## Contributing
+
+### Requirements
+
+- Node v16+
+- PNPM
+- Development Shopify store (with the ShipAid app installed)
+- ShipAid API development/staging instance
+
+### Development
+
+You will need to make sure your development store has the ShipAid app installed, so the store and its protection product is added to the DB. You will also need to ensure the Shopify app you are testing this with has an app proxy added, and pointed towards an API instance.
+
+```sh
+pnpm install
+pnpm run develop
+```
+
+Once the project is running, add the below to your development Shopify store `theme.liquid`:
+
+```html
+<!-- Dev -->
+<script src="http://localhost:3000/src/shipaid-widget.ts"type="module" ></script>
+<!-- Prod -->
+<script src="https://unpkg.com/ui.shipaid.com?module" type="module"></script>
+```
+And add the widget element in your cart (likely `/sections/main-cart-items.liquid`):
+
+```html
+<shipaid-widget>
+  <p>Loading ShipAid Protection</p>
+</shipaid-widget>
+```
+
+### Build
+
+Once the project has been built, you can publish the project to NPM, and users can add the script to their store using a package CDN (I.e. [Unpkg](https://unpkg.com/)).
+
+```sh
+pnpm install
+pnpm run lint
+pnpm run build
+pnpm publish
+```

package/dist-types/src/shipaid-widget.d.ts

@@ -0,0 +1,85 @@
+import { LitElement } from "lit";
+import type { ShopifyCart } from "../types/shopify";
+/**
+ * ShipAid Widget.
+ *
+ * @description When the <shipaid-widget> element is added to page, it will render this element,
+ * allowing a customer to add ShipAid protection to cart (and remove).
+ *
+ */
+export declare class ShipAidWidget extends LitElement {
+    static styles: import("lit").CSSResult;
+    disablePolling: boolean;
+    pollingInterval: number;
+    disableRefresh: boolean;
+    /** API Proxy pathname */
+    private _apiEndpoint;
+    /** The current store domain */
+    private _storeDomain;
+    /** The current store data object from the ShipAid API */
+    private _store;
+    /** The current cart data object from the Shopify API */
+    private _cart;
+    /** When the cart was last updated */
+    private _cartLastUpdated;
+    /** Whether we have finished the initial setup */
+    private _hasFinishedSetup;
+    /** Can be used to hide all widget content */
+    private _shouldShowWidget;
+    /** Whether the ShipAid protection product is currently added to the cart */
+    private _hasProtectionInCart;
+    /** The last action a user took */
+    private _lastAction;
+    /** The protection item from the Shopify cart */
+    private _protectionCartItem;
+    /** The protection variant that will be used */
+    private _protectionVariant;
+    /**
+     * Internal state
+     */
+    private _state;
+    /**
+     * Internal popup state
+     */
+    private _popup;
+    /** Getter to check if we should refresh the page or not */
+    get shouldRefreshOnUpdate(): boolean;
+    /** Getter to check whether to show the widget or not */
+    get planActive(): boolean;
+    private _currencyFormat;
+    /** Emit events */
+    private _dispatchEvent;
+    /** Handle cart or page refreshes */
+    private _handleRefresh;
+    /** Given the current order, it calculates the protection total according to the store protection settings. */
+    calculateProtectionTotal(cart?: ShopifyCart): Promise<number>;
+    /**
+     * Given the current order, it finds the relevant protection product variant, and adds it to cart.
+     * This should be run whenever the cart updates, or it is manually triggered.
+     */
+    private _findProtectionVariant;
+    /** Update State */
+    private _setState;
+    /** Updates the current protection status, calling the relevant add/remove function. */
+    private _updateProtection;
+    /** General fetch function, which handles error responses, and returns JSON responses. */
+    private _fetch;
+    /** Fetches store info from the ShipAid public API. */
+    private _fetchShipAidData;
+    /** Fetch current cart from the Shopify ajax API */
+    private _fetchCart;
+    /** Whether the cart currently contains Shipping protection from ShipAid. */
+    hasProtection(): boolean;
+    /** Update the internal cart, which will trigger any protection fee updates */
+    updateCart(cart?: ShopifyCart): Promise<void>;
+    /** Add ShipAid shipping protection. */
+    addProtection(): Promise<void>;
+    /** Remove ShipAid shipping protection. */
+    removeProtection(): Promise<void>;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "shipaid-widget": ShipAidWidget;
+    }
+}

package/dist-types/src/styles.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("lit").CSSResult;
+export default _default;

package/dist-types/types/shipaid.d.ts

@@ -0,0 +1,57 @@
+export interface ProtectionSettingsProductVariant {
+    id?: string;
+    sku?: string;
+    price?: string;
+    title?: string;
+    selectedOptions?: {
+        name?: string;
+        value?: string;
+    }[];
+}
+export interface ProtectionSettingsProduct {
+    id?: string;
+    title?: string;
+    options?: {
+        name: string;
+        value: string;
+    }[];
+    variants?: {
+        edges?: {
+            node?: ProtectionSettingsProductVariant;
+        }[];
+    };
+}
+export interface ProtectionSettings {
+    product?: ProtectionSettingsProduct;
+}
+export interface ProtectionSettingsPercentage extends ProtectionSettings {
+    protectionType: 'PERCENTAGE';
+    percentage: number;
+    minimumFee: number;
+}
+export interface ProtectionSettingsFixed extends ProtectionSettings {
+    protectionType: 'FIXED';
+    defaultFee?: number;
+    rules?: {
+        fee?: number;
+        rangeLower?: number;
+        rangeUpper?: number;
+    }[];
+}
+export interface ShipAidStore {
+    store: string;
+    currency: string;
+    widgetAutoOptIn?: boolean;
+    widgetShowCart?: boolean;
+    excludedProductSkus?: string[];
+    planActive: boolean;
+    protectionSettings: ProtectionSettingsFixed | ProtectionSettingsPercentage;
+}
+export interface ShipAidStoreQuery {
+    data: null | {
+        store: ShipAidStore;
+    };
+    errors?: {
+        message: string;
+    }[];
+}

package/dist-types/types/shopify.d.ts

@@ -0,0 +1,84 @@
+declare global {
+    interface Window {
+        Shopify?: {
+            shop?: string;
+            locale?: string;
+            designMode?: boolean;
+            currency?: {
+                active?: string;
+            };
+            Checkout?: Record<string, string>;
+        };
+    }
+}
+export interface ShopifyCart {
+    token: string;
+    note?: null;
+    original_total_price: number;
+    total_price: number;
+    total_discount: number;
+    total_weight: number;
+    item_count: number;
+    items?: ShopifyCartItem[];
+    requires_shipping: boolean;
+    currency: string;
+    items_subtotal_price: number;
+    cart_level_discount_applications?: (null)[] | null;
+    sections?: Record<string, string>;
+}
+export interface ShopifyCartItem {
+    id: number;
+    index: number;
+    position: number;
+    properties?: null;
+    quantity: number;
+    variant_id: number;
+    key: string;
+    title: string;
+    price: number;
+    original_price: number;
+    discounted_price: number;
+    line_price: number;
+    original_line_price: number;
+    total_discount: number;
+    discounts?: (null)[] | null;
+    sku: string;
+    grams: number;
+    vendor: string;
+    taxable: boolean;
+    product_id: number;
+    product_has_only_default_variant: boolean;
+    gift_card: boolean;
+    final_price: number;
+    final_line_price: number;
+    url: string;
+    featured_image: FeaturedImage;
+    image: string;
+    handle: string;
+    requires_shipping: boolean;
+    product_type: string;
+    product_title: string;
+    product_description: string;
+    variant_title?: null;
+    variant_options?: (string)[] | null;
+    options_with_values?: (OptionsWithValuesEntity)[] | null;
+    line_level_discount_allocations?: (null)[] | null;
+    line_level_total_discount: number;
+    sections?: Record<string, string>;
+}
+export interface FeaturedImage {
+    aspect_ratio: number;
+    alt: string;
+    height: number;
+    url: string;
+    width: number;
+}
+export interface OptionsWithValuesEntity {
+    name: string;
+    value: string;
+}
+export interface ShopifyCartAddPayload {
+    id: number | string;
+    quantity?: number;
+    sections?: string;
+}

package/dist-types/types/widget.d.ts

@@ -0,0 +1,13 @@
+export declare enum Events {
+    LOADED = "shipaid-loaded",
+    STATUS_UPDATE = "shipaid-protection-status"
+}
+export interface State {
+    loading: boolean;
+    success: boolean | null;
+    error: boolean | string | null;
+}
+export interface FetchHelper {
+    get: <Data>(url: string) => Promise<Data>;
+    post: <Data>(url: string, body: unknown) => Promise<Data>;
+}

package/package.json

@@ -1,41 +1,41 @@
-{
-  "name": "ui.shipaid.com",
-  "private": false,
-  "version": "0.2.4",
-  "main": "dist/ui.shipaid.com.umd.js",
-  "unpkg": "dist/ui.shipaid.com.iife.js",
-  "module": "dist/ui.shipaid.com.es.js",
-  "exports": {
-    ".": "./dist/ui.shipaid.com.es.js"
-  },
-  "types": "dist-types/src/shipaid-widget.d.ts",
-  "files": [
-    "dist",
-    "types"
-  ],
-  "scripts": {
-    "develop": "vite",
-    "build": "tsc && vite build",
-    "lint": "eslint . --ext=ts --fix"
-  },
-  "dependencies": {
-    "@lit-labs/task": "^1.1.2",
-    "lit": "^2.2.7",
-    "lit-element-effect": "^1.0.2"
-  },
-  "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "^5.30.0",
-    "@typescript-eslint/parser": "^5.30.0",
-    "eslint": "^7.32.0",
-    "eslint-config-standard": "^16.0.3",
-    "eslint-plugin-html": "^6.2.0",
-    "eslint-plugin-import": "^2.26.0",
-    "eslint-plugin-lit": "^1.6.1",
-    "eslint-plugin-lit-a11y": "^2.2.0",
-    "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-promise": "^5.2.0",
-    "typescript": "^4.7.4",
-    "vite": "^2.9.13",
-    "vite-plugin-full-reload": "^1.0.0"
-  }
-}
+{
+  "name": "ui.shipaid.com",
+  "private": false,
+  "version": "0.2.5",
+  "type": "module",
+  "main": "dist/ui.shipaid.com.umd.js",
+  "unpkg": "dist/ui.shipaid.com.iife.js",
+  "module": "dist/ui.shipaid.com.es.js",
+  "exports": {
+    ".": "./dist/ui.shipaid.com.es.js"
+  },
+  "types": "dist-types/src/shipaid-widget.d.ts",
+  "files": [
+    "dist-types",
+    "types"
+  ],
+  "scripts": {
+    "develop": "vite",
+    "build": "tsc && node build",
+    "lint": "eslint . --ext=ts --fix"
+  },
+  "dependencies": {
+    "@lit-labs/task": "^1.1.3",
+    "lit": "^2.3.1",
+    "lit-element-effect": "^1.0.2"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^5.35.1",
+    "@typescript-eslint/parser": "^5.35.1",
+    "eslint": "^7.32.0",
+    "eslint-config-standard": "^17.0.0",
+    "eslint-plugin-html": "^7.1.0",
+    "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-lit": "^1.6.1",
+    "eslint-plugin-lit-a11y": "^2.2.2",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-promise": "^5.2.0",
+    "typescript": "^4.8.2",
+    "vite": "^2.9.15"
+  }
+}

package/types/scss.d.ts

@@ -1,5 +1,5 @@
-declare module '*.scss' {
-  import { CSSResultGroup } from 'lit'
-  const styles: CSSResultGroup
-  export default styles
-}
+declare module '*.scss' {
+  import { CSSResultGroup } from 'lit'
+  const styles: CSSResultGroup
+  export default styles
+}

package/types/shipaid.ts

@@ -1,53 +1,54 @@
-export interface ProtectionSettingsProductVariant {
-  id?: string
-  sku?: string
-  price?: string
-  title?: string
-  selectedOptions?: { name?: string, value?: string }[]
-}
-
-export interface ProtectionSettingsProduct {
-  // Making these optional, as it is stored as a jsonb field, so we can't guarantee the format it returns.
-  id?: string
-  title?: string
-  options?: { name: string, value: string }[]
-  variants?: {
-    edges?: {
-      node?: ProtectionSettingsProductVariant
-    }[]
-  }
-}
-
-export interface ProtectionSettings {
-  product?: ProtectionSettingsProduct
-}
-
-export interface ProtectionSettingsPercentage extends ProtectionSettings {
-  protectionType: 'PERCENTAGE'
-  percentage: number
-  minimumFee: number
-}
-export interface ProtectionSettingsFixed extends ProtectionSettings {
-  protectionType: 'FIXED'
-  defaultFee?: number
-  // Making these optional, as it is stored as a jsonb field, so we can't guarantee the format it returns.
-  rules?: {
-    fee?: number
-    rangeLower?: number
-    rangeUpper?: number
-  }[]
-}
-
-export interface ShipAidStore {
-  store: string;
-  currency: string
-  widgetAutoOptIn?: boolean
-  widgetShowCart?: boolean
-  excludedProductSkus?: string[]
-  plan?: { active: boolean }
-  protectionSettings: ProtectionSettingsFixed | ProtectionSettingsPercentage
-}
-
-export interface ShipAidStoreQuery {
-  stores: ShipAidStore[]
-}
+export interface ProtectionSettingsProductVariant {
+  id?: string
+  sku?: string
+  price?: string
+  title?: string
+  selectedOptions?: { name?: string, value?: string }[]
+}
+
+export interface ProtectionSettingsProduct {
+  // Making these optional, as it is stored as a jsonb field, so we can't guarantee the format it returns.
+  id?: string
+  title?: string
+  options?: { name: string, value: string }[]
+  variants?: {
+    edges?: {
+      node?: ProtectionSettingsProductVariant
+    }[]
+  }
+}
+
+export interface ProtectionSettings {
+  product?: ProtectionSettingsProduct
+}
+
+export interface ProtectionSettingsPercentage extends ProtectionSettings {
+  protectionType: 'PERCENTAGE'
+  percentage: number
+  minimumFee: number
+}
+export interface ProtectionSettingsFixed extends ProtectionSettings {
+  protectionType: 'FIXED'
+  defaultFee?: number
+  // Making these optional, as it is stored as a jsonb field, so we can't guarantee the format it returns.
+  rules?: {
+    fee?: number
+    rangeLower?: number
+    rangeUpper?: number
+  }[]
+}
+
+export interface ShipAidStore {
+  store: string;
+  currency: string
+  widgetAutoOptIn?: boolean
+  widgetShowCart?: boolean
+  excludedProductSkus?: string[]
+  planActive: boolean
+  protectionSettings: ProtectionSettingsFixed | ProtectionSettingsPercentage
+}
+
+export interface ShipAidStoreQuery {
+  data: null | { store: ShipAidStore }
+  errors?: { message: string }[]
+}