Merge pull request #2986 from Shopify/06-16-add_editable_cart_property

Add `editable` cart property

Author: MrGVSV

packages/ui-extensions-react/src/surfaces/point-of-sale/hooks/cart-api.ts

@@ -1,10 +1,8 @@
 import type {Cart} from '@shopify/ui-extensions/point-of-sale';
 import {useApi} from './api';
 import {useEffect, useRef, useState} from 'react';
-import {
-  StatefulRemoteSubscribable,
-  makeStatefulSubscribable,
-} from '@remote-ui/async-subscription';
+import type {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
+import {makeStatefulSubscribable} from '@remote-ui/async-subscription';
 
 /**
  * Global instance of the subscribable that is created on the first `useStatefulSubscribableCart` call.
@@ -19,6 +17,34 @@ const isCartApi = (api: any): boolean => {
   return 'cart' in api;
 };
 
+/**
+ * A hook for checking if the cart has been determined to be editable.
+ *
+ * This hook is stateful and can be used to trigger a re-render when the value of this editable state changes.
+ *
+ * If the cart's `editable` property is not set, defaults to `true`.
+ *
+ * @returns true if the cart is editable, false otherwise.
+ */
+export const useCartEditable = (): boolean => {
+  const statefulSubscribableCart = useStatefulSubscribableCart();
+  const [editable, setEditable] = useState<boolean>(
+    statefulSubscribableCart.current.editable ?? true,
+  );
+
+  const unsubscribeRef = useRef<() => void>();
+
+  useEffect(() => {
+    if (!unsubscribeRef.current) {
+      statefulSubscribableCart.subscribe((cart: Cart) => {
+        setEditable(cart.editable ?? true);
+      });
+    }
+  }, [statefulSubscribableCart]);
+
+  return editable;
+};
+
 /**
  * A hook utilizing `useState` and the `useStatefulSubscribableCart` function to create a component state.
  * @returns this hook returns the latest Cart state which re-renders on change.
@@ -57,6 +83,7 @@ export function useStatefulSubscribableCart(): StatefulRemoteSubscribable<Cart>
 
   return statefulSubscribable;
 }
+
 /**
  * A function destroying the subscriptions `useStatefulSubscribableCart` has.
  */

packages/ui-extensions-react/src/surfaces/point-of-sale/hooks/index.ts

@@ -1,6 +1,7 @@
 export {useApi, useExtensionApi} from './api';
 export {
   useCartSubscription,
+  useCartEditable,
   useStatefulSubscribableCart,
   destroyStatefulSubscribableCart,
 } from './cart-api';

packages/ui-extensions/src/surfaces/point-of-sale/render/api/cart-api/cart-api.ts

@@ -21,7 +21,8 @@ export type CartDiscountType = 'Percentage' | 'FixedAmount' | 'Code';
 export type LineItemDiscountType = 'Percentage' | 'FixedAmount';
 
 export interface CartApiContent {
-  /** Provides a subscription to POS cart changes.
+  /**
+   * Provides a subscription to POS cart changes.
    * Provides an initial value and a callback to subscribe to value changes. Currently supports only one subscription.
    * You can utilize `makeStatefulSubscribable` on a `RemoteSubscribable` to implement multiple subscriptions.
    * Using `makeStatefulSubscribable` or the corresponding hooks counts as a subscription.
@@ -31,99 +32,151 @@ export interface CartApiContent {
   /** Bulk update the cart
    * @param cartState the cart state to set
    * @returns the updated cart
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   bulkCartUpdate(cartState: CartUpdateInput): Promise<Cart>;
 
   /** Apply a cart level discount
    * @param type the type of discount applied (example: 'Percentage')
    * @param title the title attributed with the discount
    * @param amount the percentage or fixed monetary amount deducted with the discount. Pass in `undefined` if using discount codes.
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   applyCartDiscount(
     type: CartDiscountType,
     title: string,
     amount?: string,
   ): Promise<void>;
 
-  /** Add a code discount to the cart
+  /**
+   * Add a code discount to the cart
    * @param code the code for the discount to add to the cart
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   addCartCodeDiscount(code: string): Promise<void>;
 
-  /** Remove the cart discount */
+  /**
+   * Remove the cart discount
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
+   */
   removeCartDiscount(): Promise<void>;
 
-  /** Remove all cart and line item discounts
+  /**
+   * Remove all cart and line item discounts
    * @param disableAutomaticDiscounts Whether or not automatic discounts should be enabled after removing the discounts.
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   removeAllDiscounts(disableAutomaticDiscounts: boolean): Promise<void>;
 
-  /** Clear the cart */
+  /**
+   * Clear the cart
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
+   */
   clearCart(): Promise<void>;
 
-  /** Set the customer in the cart
+  /**
+   * Set the customer in the cart
    * @param customer the customer object to add to the cart
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   setCustomer(customer: Customer): Promise<void>;
 
-  /** Remove the current customer from the cart */
+  /**
+   * Remove the current customer from the cart
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
+   */
   removeCustomer(): Promise<void>;
 
-  /** Add a custom sale to the cart
+  /**
+   * Add a custom sale to the cart
    * @param customSale the custom sale object to add to the cart
    * @returns {string} the uuid of the line item added
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   addCustomSale(customSale: CustomSale): Promise<string>;
 
-  /** Add a line item by variant ID to the cart
+  /**
+   * Add a line item by variant ID to the cart
    * @param variantId the product variant's numeric ID to add to the cart
    * @param quantity the number of this variant to add to the cart
    * @returns {string} the uuid of the line item added
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   addLineItem(variantId: number, quantity: number): Promise<string>;
 
-  /** Remove the line item at this uuid from the cart
+  /**
+   * Remove the line item at this uuid from the cart
    * @param uuid the uuid of the line item that should be removed
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   removeLineItem(uuid: string): Promise<void>;
 
-  /** Adds custom properties to the cart
+  /**
+   * Adds custom properties to the cart
    * @param properties the custom key to value object to attribute to the cart
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   addCartProperties(properties: Record<string, string>): Promise<void>;
 
-  /** Removes the specified cart properties
+  /**
+   * Removes the specified cart properties
    * @param keys the collection of keys to be removed from the cart properties
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   removeCartProperties(keys: string[]): Promise<void>;
 
-  /** Adds custom properties to the specified line item
+  /**
+   * Adds custom properties to the specified line item
    * @param uuid the uuid of the line item to which the properties should be stringd
    * @param properties the custom key to value object to attribute to the line item
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   addLineItemProperties(
     uuid: string,
     properties: Record<string, string>,
   ): Promise<void>;
 
-  /** Adds custom properties to multiple line items at the same time.
+  /**
+   * Adds custom properties to multiple line items at the same time.
    * @param lineItemProperties the collection of custom line item properties to apply to their respective line items.
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   bulkAddLineItemProperties(
     lineItemProperties: SetLineItemPropertiesInput[],
   ): Promise<void>;
 
-  /** Removes the specified line item properties
+  /**
+   * Removes the specified line item properties
    * @param uuid the uuid of the line item to which the properties should be removed
    * @param keys the collection of keys to be removed from the line item properties
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   removeLineItemProperties(uuid: string, keys: string[]): Promise<void>;
 
-  /** Add a discount on a line item to the cart
+  /**
+   * Add a discount on a line item to the cart
    * @param uuid the uuid of the line item that should receive a discount
    * @param type the type of discount applied (example: 'Percentage')
    * @param title the title attributed with the discount
    * @param amount the percentage or fixed monetary amount deducted with the discout
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   setLineItemDiscount(
     uuid: string,
@@ -132,45 +185,65 @@ export interface CartApiContent {
     amount: string,
   ): Promise<void>;
 
-  /** Set line item discounts to multiple line items at the same time.
+  /**
+   * Set line item discounts to multiple line items at the same time.
    * @param lineItemDiscounts a map of discounts to add. They key is the uuid of the line item you want to add the discount to. The value is the discount input.
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   bulkSetLineItemDiscounts(
     lineItemDiscounts: SetLineItemDiscountInput[],
   ): Promise<void>;
 
-  /** Sets an attributed staff to all line items in the cart.
+  /**
+   * Sets an attributed staff to all line items in the cart.
    * @param staffId the ID of the staff. Providing undefined will clear the attributed staff from all line items.
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   setAttributedStaff(staffId: number | undefined): Promise<void>;
 
-  /** Sets an attributed staff to a specific line items in the cart.
+  /**
+   * Sets an attributed staff to a specific line items in the cart.
    * @param staffId the ID of the staff. Providing undefined will clear the attributed staff on the line item.
    * @param lineItemUuid the UUID of the line item.
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   setAttributedStaffToLineItem(
     staffId: number | undefined,
     lineItemUuid: string,
   ): Promise<void>;
 
-  /** Remove all discounts from a line item
+  /**
+   * Remove all discounts from a line item
    * @param uuid the uuid of the line item whose discounts should be removed
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   removeLineItemDiscount(uuid: string): Promise<void>;
 
-  /** Add an address to the customer (Customer must be present)
+  /**
+   * Add an address to the customer (Customer must be present)
    * @param address the address object to add to the customer in cart
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   addAddress(address: Address): Promise<void>;
 
   /**
    * Delete an address from the customer (Customer must be present)
    * @param addressId the address ID to delete
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   deleteAddress(addressId: number): Promise<void>;
 
-  /** Update the default address for the customer (Customer must be present)
+  /**
+   * Update the default address for the customer (Customer must be present)
    * @param addressId the address ID to set as the default address
+   *
+   * @throws CartNotEditableError if the cart is not currently editable.
    */
   updateDefaultAddress(addressId: number): Promise<void>;
 }

packages/ui-extensions/src/surfaces/point-of-sale/render/api/cart-api/errors.ts

@@ -0,0 +1,17 @@
+import {CartApiContent} from './cart-api';
+
+type CartApiMethods = Omit<CartApiContent, 'subscribable'>;
+
+/**
+ * An error thrown when an attempt to edit the cart is made while it is not editable.
+ */
+export class CartNotEditableError extends Error {
+  constructor(
+    /** The name of the method that attempted to modify the cart */
+    public methodName: keyof CartApiMethods,
+  ) {
+    super(
+      `attempted to modify cart when not editable (calling "${methodName}")`,
+    );
+  }
+}

packages/ui-extensions/src/surfaces/point-of-sale/types/cart.ts

@@ -2,6 +2,12 @@ import {CountryCode} from './country-code';
 import {TaxLine} from './tax-line';
 
 export interface Cart {
+  /**
+   * Indicates whether the cart is currently editable.
+   *
+   * An undefined value should be treated as `true` for backward compatibility.
+   */
+  editable?: boolean;
   subtotal: string;
   taxTotal: string;
   grandTotal: string;