@shopify/ui-extensions 2023.7.3 → 2023.10.1

package/src/surfaces/checkout/api/standard/standard.ts

@@ -15,10 +15,10 @@ import type {ExtensionTarget} from '../../targets';
 import {ApiVersion} from '../../../../shared';
 
 /**
- * A key-value storage object for extension targets.
+ * A key-value storage object for the extension.
  *
- * Stored data is only available to this specific app
- * at this specific extension target.
+ * Stored data is only available to this specific extension
+ * and any of its instances.
  *
  * The storage backend is implemented with `localStorage` and
  * should persist across the buyer's checkout session.
@@ -56,8 +56,15 @@ export interface Storage {
  * * [`network_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#network-access): the extension can make external network calls.
  *
  * * [`block_progress`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#block-progress): the extension can block a buyer's progress and the merchant has allowed this blocking behavior.
+ *
+ * * [`collect_buyer_consent.sms_marketing`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can collect buyer consent for SMS marketing.
  */
-export type Capability = 'api_access' | 'network_access' | 'block_progress';
+
+export type Capability =
+  | 'api_access'
+  | 'network_access'
+  | 'block_progress'
+  | 'collect_buyer_consent.sms_marketing';
 
 /**
  * Meta information about an extension target.
@@ -79,6 +86,8 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
    * * [`network_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#network-access): the extension can make external network calls.
    *
    * * [`block_progress`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#block-progress): the extension can block a buyer's progress and the merchant has allowed this blocking behavior.
+   *
+   * * [`collect_buyer_consent.sms_marketing`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can collect buyer consent for SMS marketing.
    */
   capabilities: StatefulRemoteSubscribable<Capability[]>;
 
@@ -211,6 +220,7 @@ export interface AppMetafieldEntryTarget {
     | 'customer'
     | 'product'
     | 'shop'
+    | 'shopUser'
     | 'variant'
     | 'company'
     | 'companyLocation'
@@ -238,6 +248,7 @@ export interface AppMetafieldEntry {
 export type {ApiVersion} from '../../../../shared';
 
 export type Version = string;
+export type CheckoutToken = string;
 
 /**
  * This returns a translated string matching a key in a locale file.
@@ -462,7 +473,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
    * Provides details on the buyer's progression through the checkout.
    *
-   * See [buyer journey](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi#example-buyer-journey)
+   * See [buyer journey](https://shopify.dev/docs/api/checkout-ui-extensions/apis/buyer-journey#examples)
    * examples for more information.
    */
   buyerJourney: BuyerJourney;
@@ -472,6 +483,14 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    */
   checkoutSettings: StatefulRemoteSubscribable<CheckoutSettings>;
 
+  /**
+   * A stable id that represents the current checkout.
+   *
+   * Matches the `token` field in the [WebPixel checkout payload](https://shopify.dev/docs/api/pixels/customer-events#checkout)
+   * and the `checkout_token` field in the [Admin REST API Order resource](https://shopify.dev/docs/api/admin-rest/unstable/resources/order#resource-object).
+   */
+  checkoutToken: StatefulRemoteSubscribable<CheckoutToken | undefined>;
+
   /**
    * Details on the costs the buyer will pay for this checkout.
    */
@@ -512,10 +531,10 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
 
   /**
    * Utilities for translating content and formatting values according to the current
-   * [`localization`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi#properties-propertydetail-localization)
+   * [`localization`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization)
    * of the checkout.
    *
-   * See [localization examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi#example-localization)
+   * See [localization examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization#examples)
    * for more information.
    */
   i18n: I18n;
@@ -528,7 +547,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
    * Details about the location, language, and currency of the buyer. For utilities to easily
    * format and translate content based on these details, you can use the
-   * [`i18n`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi#properties-propertydetail-i18n)
+   * [`i18n`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization#standardapi-propertydetail-i18n)
    * object instead.
    */
   localization: Localization;
@@ -554,7 +573,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
    * Used to query the Storefront GraphQL API with a prefetched token.
    *
-   * See [storefront api access examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi#example-storefront-api-access) for more information.
+   * See [storefront api access examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/storefront-api) for more information.
    */
   query: <Data = unknown, Variables = {[key: string]: unknown}>(
     query: string,
@@ -569,7 +588,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
    * Provides access to session tokens, which can be used to verify token claims on your app's server.
    *
-   * See [session token examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi#example-session-token) for more information.
+   * See [session token examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/session-token) for more information.
    */
   sessionToken: SessionToken;
 
@@ -577,7 +596,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    * The settings matching the settings definition written in the
    * [`shopify.extension.toml`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) file.
    *
-   *  See [settings examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi#example-settings) for more information.
+   *  See [settings examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/settings) for more information.
    *
    * > Note: When an extension is being installed in the editor, the settings will be empty until
    * a merchant sets a value. In that case, this object will be updated in real time as a merchant fills in the settings.
@@ -594,11 +613,24 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    */
   shippingAddress?: StatefulRemoteSubscribable<MailingAddress | undefined>;
 
+  /**
+   * The proposed buyer billing address. The address updates when the field is
+   * committed (on change) rather than every keystroke.
+   *
+   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   */
+  billingAddress?: StatefulRemoteSubscribable<MailingAddress | undefined>;
+
   /** Shop where the checkout is taking place. */
   shop: Shop;
 
   /**
-   * Key-value storage for the extension target.
+   * Key-value storage for the extension.
+   * Uses `localStorage` and should persist across the buyer's current checkout session.
+   * However, data persistence isn't guaranteed and storage is reset when the buyer starts a new checkout.
+   *
+   * Data is shared across all activated extension targets of this extension. In versions `<=2023-07`,
+   * each activated extension target had its own storage.
    */
   storage: Storage;
 
@@ -764,6 +796,26 @@ export interface Shop {
 }
 
 export interface CartCost {
+  /**
+   * A `Money` value representing the subtotal value of the items in the cart at the current
+   * step of checkout.
+   */
+  subtotalAmount: StatefulRemoteSubscribable<Money>;
+
+  /**
+   * A `Money` value representing the total shipping a buyer can expect to pay at the current
+   * step of checkout. This value includes shipping discounts. Returns undefined if shipping
+   * has not been negotiated yet, such as on the information step.
+   */
+  totalShippingAmount: StatefulRemoteSubscribable<Money | undefined>;
+
+  /**
+   * A `Money` value representing the total tax a buyer can expect to pay at the current
+   * step of checkout or the total tax included in product and shipping prices. Returns
+   * undefined if taxes are unavailable.
+   */
+  totalTaxAmount: StatefulRemoteSubscribable<Money | undefined>;
+
   /**
    * A `Money` value representing the minimum a buyer can expect to pay at the current
    * step of checkout. This value excludes amounts yet to be negotiated. For example,
@@ -1015,7 +1067,7 @@ export interface SelectedPaymentOption {
   /**
    * The unique handle referencing `PaymentOption.handle`.
    *
-   * See [availablePaymentOptions](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi#properties-propertydetail-availablepaymentoptions).
+   * See [availablePaymentOptions](https://shopify.dev/docs/api/checkout-ui-extensions/apis/payment-options#standardapi-propertydetail-availablepaymentoptions).
    */
   handle: string;
 }
@@ -1210,9 +1262,27 @@ export interface Customer {
    */
   image: ImageDetails;
   /**
-   * Defines if the customer accepts marketing activities.
+   * Defines if the customer email accepts marketing activities.
+   *
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   *
+   * > Caution: This field is deprecated and will be removed in a future version. Use `acceptsEmailMarketing` or `acceptsSmsMarketing` instead.
+   *
+   * @deprecated Use `acceptsEmailMarketing` or `acceptsSmsMarketing` instead.
    */
   acceptsMarketing: boolean;
+  /**
+   * Defines if the customer accepts email marketing activities.
+   *
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   */
+  acceptsEmailMarketing: boolean;
+  /**
+   * Defines if the customer accepts SMS marketing activities.
+   *
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   */
+  acceptsSmsMarketing: boolean;
   /**
    * The Store Credit Accounts owned by the customer and usable during the checkout process.
    *
@@ -1261,7 +1331,7 @@ export interface PaymentTermsTemplate {
    */
   id: string;
   /**
-   * The name of the payment terms translated to the buyer's current language. See [localization.language](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi#properties-propertydetail-localization).
+   * The name of the payment terms translated to the buyer's current language. See [localization.language](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization#standardapi-propertydetail-localization).
    */
   name: string;
   /**
@@ -1301,6 +1371,43 @@ export interface Analytics {
    * Publish method to emit analytics events to [Web Pixels](https://shopify.dev/docs/apps/marketing).
    */
   publish(name: string, data: {[key: string]: unknown}): Promise<boolean>;
+
+  /**
+   * A method for capturing details about a visitor on the online store.
+   */
+  visitor(data: {email?: string; phone?: string}): Promise<VisitorResult>;
+}
+/**
+ * Represents a visitor result.
+ */
+export type VisitorResult = VisitorSuccess | VisitorError;
+
+/**
+ * Represents a successful visitor result.
+ */
+export interface VisitorSuccess {
+  /**
+   * Indicates that the visitor information was validated and submitted.
+   */
+  type: 'success';
+}
+
+/**
+ * Represents an unsuccessful visitor result.
+ */
+export interface VisitorError {
+  /**
+   * Indicates that the visitor information is invalid and wasn't submitted.
+   * Examples are using the wrong data type or missing a required property.
+   */
+  type: 'error';
+
+  /**
+   * A message that explains the error. This message is useful for debugging.
+   * It's **not** localized, and therefore should not be presented directly
+   * to the buyer.
+   */
+  message: string;
 }
 
 /**
@@ -1359,10 +1466,15 @@ export interface DeliveryOptionReference {
   handle: string;
 }
 
+export type DeliveryOption =
+  | ShippingOption
+  | PickupPointOption
+  | PickupLocationOption;
+
 /**
  * Represents a base interface for a single delivery option.
  */
-export interface DeliveryOption {
+export interface DeliveryOptionBase {
   /**
    * The unique identifier of the delivery option.
    */
@@ -1377,12 +1489,17 @@ export interface DeliveryOption {
    * The description of the delivery option.
    */
   description?: string;
+
+  /**
+   * The code of the delivery option.
+   */
+  code: string;
 }
 
 /**
  * Represents a delivery option that is a shipping option.
  */
-export interface ShippingOption extends DeliveryOption {
+export interface ShippingOption extends DeliveryOptionBase {
   /**
    * The type of this delivery option.
    */
@@ -1423,7 +1540,7 @@ export interface ShippingOptionCarrier {
   name?: string;
 }
 
-export interface PickupPointOption extends DeliveryOption {
+export interface PickupPointOption extends DeliveryOptionBase {
   /**
    * The type of this delivery option.
    */
@@ -1450,7 +1567,7 @@ export interface PickupPointOption extends DeliveryOption {
   location: PickupPointLocation;
 }
 
-export interface PickupLocationOption extends DeliveryOption {
+export interface PickupLocationOption extends DeliveryOptionBase {
   /**
    * The type of this delivery option.
    */

package/src/surfaces/checkout/api.ts

@@ -55,6 +55,7 @@ export type {
   PickupLocationOption,
   PickupPointOption,
   NumberRange,
+  CheckoutToken,
 } from './api/standard/standard';
 export type {
   Attribute,

package/src/surfaces/checkout/components/ChoiceList/ChoiceList.doc.ts

@@ -54,7 +54,7 @@ const data: ReferenceEntityTemplateSchema = {
     {
       name: 'Checkbox',
       subtitle: 'Component',
-      url: 'checkox',
+      url: 'checkbox',
       type: 'Component',
     },
   ],

package/src/surfaces/checkout/components/ConsentCheckbox/ConsentCheckbox.doc.ts

@@ -0,0 +1,48 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'ConsentCheckbox',
+  description:
+    "Use buyer consent checkboxes for collecting the buyer's approval for a given policy.",
+  thumbnail: 'consent-checkbox-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'ConsentCheckboxProps',
+      description: '',
+      type: 'ConsentCheckboxProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Forms',
+  defaultExample: {
+    image: 'consent-checkbox-default.png',
+    codeblock: {
+      title: 'Basic ConsentCheckbox',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/ConsentCheckbox/examples/basic-consent-checkbox.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-consent-checkbox.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [
+    {
+      name: 'ConsentCheckbox',
+      subtitle: 'Component',
+      url: 'consent-checkbox',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

package/src/surfaces/checkout/components/ConsentCheckbox/ConsentCheckbox.ts

@@ -0,0 +1,17 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import {CheckboxProps} from '../Checkbox/Checkbox';
+
+export interface ConsentCheckboxProps extends Omit<CheckboxProps, 'value'> {
+  /**
+   * The policy for which buyer consent is being collected for.
+   *
+   * `sms-marketing`: Represents the policy for SMS marketing consent.
+   */
+  policy: 'sms-marketing';
+}
+
+export const ConsentCheckbox = createRemoteComponent<
+  'ConsentCheckbox',
+  ConsentCheckboxProps
+>('ConsentCheckbox');

package/src/surfaces/checkout/components/ConsentCheckbox/examples/basic-consent-checkbox.example.ts

@@ -0,0 +1,11 @@
+import {extension, ConsentCheckbox} from '@shopify/ui-extensions/checkout';
+
+export default extension('purchase.checkout.block.render', (root) => {
+  const consentCheckbox = root.createComponent(
+    ConsentCheckbox,
+    {policy: 'sms-marketing'},
+    'Text me with news and promotions',
+  );
+
+  root.appendChild(consentCheckbox);
+});

package/src/surfaces/checkout/components/ConsentPhoneField/ConsentPhoneField.doc.ts

@@ -0,0 +1,48 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'ConsentPhoneField',
+  description:
+    'Display a phone field for customers to sign up for text message marketing, noting that the phone field value will be automatically saved during checkout.',
+  thumbnail: 'consent-phonefield-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'ConsentPhoneFieldProps',
+      description: '',
+      type: 'ConsentPhoneFieldProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Forms',
+  defaultExample: {
+    image: 'consent-phonefield-default.png',
+    codeblock: {
+      title: 'Basic ConsentPhoneField',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/ConsentPhoneField/examples/basic-consent-phone-field.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-consent-phone-field.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [
+    {
+      name: 'ConsentCheckbox',
+      subtitle: 'Component',
+      url: 'consent-checkbox',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

package/src/surfaces/checkout/components/ConsentPhoneField/ConsentPhoneField.ts

@@ -0,0 +1,19 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import {PhoneFieldProps} from '../PhoneField/PhoneField';
+
+export type ConsentPolicy = 'sms-marketing';
+
+export interface ConsentPhoneFieldProps extends Omit<PhoneFieldProps, 'value'> {
+  /**
+   * The policy for which buyer consent is being collected for.
+   *
+   * `sms-marketing`: Represents the policy for SMS marketing consent.
+   */
+  policy: ConsentPolicy;
+}
+
+export const ConsentPhoneField = createRemoteComponent<
+  'ConsentPhoneField',
+  ConsentPhoneFieldProps
+>('ConsentPhoneField');

package/src/surfaces/checkout/components/ConsentPhoneField/examples/basic-consent-phone-field.example.ts

@@ -0,0 +1,10 @@
+import {extension, ConsentPhoneField} from '@shopify/ui-extensions/checkout';
+
+export default extension('purchase.checkout.block.render', (root) => {
+  const consentPhoneField = root.createComponent(ConsentPhoneField, {
+    label: 'Phone',
+    policy: 'sms-marketing',
+  });
+
+  root.appendChild(consentPhoneField);
+});

package/src/surfaces/checkout/components/Icon/Icon.ts

@@ -39,6 +39,7 @@ export type IconSource =
   | 'hamburger'
   | 'hollowCircle'
   | 'horizontalDots'
+  | 'image'
   | 'info'
   | 'infoFill'
   | 'list'
@@ -75,9 +76,7 @@ export interface IconProps extends IdProps {
   /**
    * Sets the appearance (color) of the icon.
    *
-   * By default the icon will inherit the color of its parent.
-   *
-   * @defaultValue 'monochrome'
+   * @defaultValue 'base'
    */
   appearance?: Appearance;
 

package/src/surfaces/checkout/components/LoginWithShop/LoginWithShop.ts

@@ -0,0 +1,16 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface LoginWithShopProps {
+  checked: boolean;
+  modalTitle?: string;
+  modalDescription?: string;
+  modalLogoSrc?: string;
+  apiKey?: string;
+  onComplete?(): void | Promise<void>;
+  onClosed?(): void;
+}
+
+export const LoginWithShop = createRemoteComponent<
+  'LoginWithShop',
+  LoginWithShopProps
+>('LoginWithShop');

package/src/surfaces/checkout/components/PaymentIcon/PaymentIcon.doc.ts

@@ -0,0 +1,55 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'PaymentIcon',
+  description:
+    'Payment icons can be used for displaying payment-related information or features such as a user’s saved or available payment methods.',
+  thumbnail: 'paymenticon-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'PaymentIconProps',
+      description: '',
+      type: 'PaymentIconProps',
+    },
+    {
+      title: 'PaymentMethod',
+      description: '',
+      type: 'PaymentMethod',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Media',
+  defaultExample: {
+    image: 'paymenticon-default.png',
+    codeblock: {
+      title: 'Basic PaymentIcon',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/PaymentIcon/examples/basic-paymenticon.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-paymenticon.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent:
+        '- Maintain the interior appearance of the SVG. The branded portion of the payment icon as provided meets the brand guidelines of the payment provider.\n\n- Maintain the border property of the payment icon. It is designed to adapt to merchant branding in Checkout and ensures a consistent appearance across the customer experience.\n\n- The icon size is designed to be displayed consistently across checkout.',
+    },
+  ],
+  related: [],
+};
+
+export default data;