@shopify/ui-extensions 2022.10.5 → 2023.4.0

package/src/surfaces/checkout/api/order-status/order-status.ts

@@ -0,0 +1,28 @@
+import {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
+
+/**
+ * Information about an order that was placed.
+ */
+export interface Order {
+  /**
+   * A globally-unique identifier.
+   * @example 'gid://shopify/Order/1'
+   */
+  id: string;
+  /**
+   * Unique identifier for the order that appears on the order.
+   * @example '#1000'
+   */
+  name: string;
+  /**
+   * If cancelled, the time at which the order was cancelled.
+   */
+  cancelledAt?: string;
+}
+
+export interface OrderStatusApi {
+  /**
+   * Order information that's available post-checkout.
+   */
+  order: StatefulRemoteSubscribable<Order | undefined>;
+}

package/src/surfaces/checkout/api/payment-method/render.ts

@@ -0,0 +1,55 @@
+export type PaymentMethodAttributesResult =
+  | PaymentMethodAttributesResultSuccess
+  | PaymentMethodAttributesResultError;
+
+export interface PaymentMethodAttributesResultSuccess {
+  /**
+   * Indicates that the payment method attributes were set successfully.
+   */
+  type: 'success';
+}
+
+export interface PaymentMethodAttributesResultError {
+  /**
+   * Indicates that the payment method attributes were not set successfully.
+   */
+  type: 'error';
+
+  /**
+   * A message that explains the error. This message is useful for debugging.
+   * It is **not** localized, and therefore should not be presented directly
+   * to the buyer.
+   */
+  message: string;
+}
+
+/**
+ * A key-value pair that represents an attribute of a payment method.
+ */
+export interface PaymentMethodAttribute {
+  key: string;
+  value: string | number | boolean;
+}
+
+export type PaymentMethodAttributesChange = PaymentMethodAttributesUpdateChange;
+
+export interface PaymentMethodAttributesUpdateChange {
+  /**
+   * The type of the `PaymentMethodAttributesChange` API.
+   */
+  type: 'updatePaymentMethodAttributes';
+
+  /**
+   * The payment method attributes
+   */
+  attributes: PaymentMethodAttribute[];
+}
+
+export interface PaymentMethodRenderApi {
+  /**
+   * Sets the attributes of the related payment method.
+   */
+  applyPaymentMethodAttributesChange(
+    change: PaymentMethodAttributesChange,
+  ): Promise<PaymentMethodAttributesResult>;
+}

package/src/surfaces/checkout/api/pickup/pickup-locations.ts

@@ -0,0 +1,8 @@
+import type {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
+
+export interface PickupLocationsApi {
+  /**
+   * Whether the customer location input form is shown to the buyer.
+   */
+  locationFormVisible: StatefulRemoteSubscribable<boolean>;
+}

package/src/surfaces/checkout/api/pickup/pickup-points.ts

@@ -0,0 +1,8 @@
+import type {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
+
+export interface PickupPointsApi {
+  /**
+   * Whether the customer location input form is shown to the buyer.
+   */
+  locationFormVisible: StatefulRemoteSubscribable<boolean>;
+}

package/src/surfaces/checkout/api/redeemable/render.ts

@@ -0,0 +1,55 @@
+export type RedeemableChangeResult =
+  | RedeemableChangeResultSuccess
+  | RedeemableChangeResultError;
+
+export interface RedeemableChangeResultSuccess {
+  /**
+   * Indicates that the redeemable change was applied successfully.
+   */
+  type: 'success';
+}
+
+export interface RedeemableChangeResultError {
+  /**
+   * Indicates that the redeemable change was not applied successfully.
+   */
+  type: 'error';
+
+  /**
+   * A message that explains the error. This message is useful for debugging.
+   * It is **not** localized, and therefore should not be presented directly
+   * to the buyer.
+   */
+  message: string;
+}
+
+/**
+ * A key-value pair that represents an attribute of a redeemable payment method.
+ */
+export interface RedeemableAttribute {
+  key: string;
+  value: string;
+}
+
+export type RedeemableChange = RedeemableAddChange;
+
+export interface RedeemableAddChange {
+  /**
+   * The type of the `RedeemableChange` API.
+   */
+  type: 'redeemableAddChange';
+
+  /**
+   * The redeemable attributes
+   */
+  attributes: RedeemableAttribute[];
+}
+
+export interface RedeemableRenderApi {
+  /**
+   * Applies a redeemable change to add a redeemable payment method.
+   */
+  applyRedeemableChange(
+    change: RedeemableChange,
+  ): Promise<RedeemableChangeResult>;
+}

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

@@ -808,3 +808,60 @@ export type CountryCode =
   | 'ZM'
   | 'ZW'
   | 'ZZ';
+
+/**
+ * Union of supported storefront API versions
+ */
+export type StorefrontApiVersion =
+  | '2022-04'
+  | '2022-07'
+  | '2022-10'
+  | '2023-01'
+  | 'unstable';
+
+/**
+ * GraphQL error returned by the Shopify Storefront APIs.
+ */
+export interface GraphQLError {
+  message: string;
+  extensions: {
+    requestId: string;
+    code: string;
+  };
+}
+
+export interface ValidationError {
+  /**
+   * Error message to be displayed to the buyer.
+   */
+  message: string;
+  /**
+   * The checkout UI field that the error is associated with.
+   *
+   * Example: `$.cart.deliveryGroups[0].deliveryAddress.countryCode`
+   *
+   * See the [supported targets](https://shopify.dev/docs/api/functions/reference/cart-checkout-validation/graphql#supported-targets)
+   * for more information.
+   */
+  target?: string;
+}
+
+export interface SellingPlan {
+  /**
+   * A globally-unique identifier.
+   * @example 'gid://shopify/SellingPlan/1'
+   */
+  id: string;
+}
+
+export interface Attribute {
+  /**
+   * The key for the attribute.
+   */
+  key: string;
+
+  /**
+   * The value for the attribute.
+   */
+  value: string;
+}

package/src/surfaces/checkout/api/shipping/shipping-method-details.ts

@@ -0,0 +1,15 @@
+import type {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
+
+import {ShippingOption} from '../standard/standard';
+
+export interface ShippingMethodDetailsApi {
+  /**
+   * The shipping option the extension is attached to.
+   */
+  target: StatefulRemoteSubscribable<ShippingOption>;
+
+  /**
+   * Whether the shipping option the extension is attached to is currently selected in the UI.
+   */
+  targetSelected: StatefulRemoteSubscribable<boolean>;
+}

package/src/surfaces/checkout/api/standard/README.md

@@ -1 +1,100 @@
-# Standard checkout API
+# Standard extension point API
+
+This document outlines the API that is provided to every extension point. When the extension point renders UI (like `Checkout::PostPurchase::Render`), these properties are part of the second argument to an extension point. When the extension point does not render UI (like `Checkout::PostPurchase::ShouldRender`), these properties are part of the first argument.
+
+## `locale`
+
+The locale of the checkout in which the extension is running. This value is provided as a string in [IETF format](https://en.wikipedia.org/wiki/IETF_language_tag).
+
+## `version`
+
+The UI extension renderer version being used for the extension. Currently, there is only a single version, `'unstable'`.
+
+## `extensionPoint`
+
+The extension point that was run. This can be useful if you register a single function to handle more than one extension point:
+
+```ts
+import {extend} from '@shopify/checkout-ui-extensions';
+
+extend('FirstExtensionPoint', handleExtensionPoint);
+extend('SecondExtensionPoint', handleExtensionPoint);
+
+function handleExtensionPoint(input) {
+  switch (input.extensionPoint) {
+    case 'FirstExtensionPoint': {
+      // ...
+      break;
+    }
+    case 'SecondExtensionPoint': {
+      // ...
+      break;
+    }
+  }
+}
+```
+
+## `lineItems`
+
+The `lineItems` property gives you access to the merchandise the buyer is purchasing through checkout. Like other resources in checkout, this value is wrapped in a `StatefulRemoteSubscribable` in order to give your extension a way to subscribe to changes to the line items. These changes can happen when there are stock problems that require the buyer to change the contents of their cart, or when other extensions change the line items through the `applyLineItemChange()` APIs documented below.
+
+```ts
+import {extend} from '@shopify/checkout-ui-extensions';
+
+extend('ExtensionPoint', (root, {lineItems}) => {
+  const text = root.createText(
+    `Your line items are: ${JSON.stringify(lineItems.current)}`,
+  );
+  root.appendChild(text);
+
+  lineItems.subscribe((newLineItems) => {
+    text.updateText(`Your new line items are: ${JSON.stringify(newLineItems)}`);
+  });
+});
+```
+
+## `ui`
+
+The `ui` property offers a set of methods to interact with the extension's UI.
+
+```ts
+import {
+  extend,
+  Button,
+  Link,
+  Modal,
+  TextBlock,
+} from '@shopify/checkout-ui-extensions';
+
+extend('ExtensionPoint', (root, {ui}) => {
+  const modalFragment = root.createFragment();
+  const modal = root.createComponent(
+    Modal,
+    {id: 'my-modal', title: 'Return policy', padding: true},
+    [
+      root.createComponent(
+        TextBlock,
+        undefined,
+        'We have a 30-day return policy, which means you have 30 days after receiving your item to request a return.',
+      ),
+      root.createComponent(
+        Button,
+        {
+          onPress() {
+            ui.overlay.close('my-modal');
+          },
+        },
+        'Close',
+      ),
+    ],
+  );
+  modalFragment.appendChild(modal);
+  const link = root.createComponent(
+    Link,
+    {overlay: modalFragment},
+    'Return policy',
+  );
+
+  root.appendChild(link);
+});
+```