@shopify/ui-extensions 2025.10.0-rc.3 → 2025.10.0-rc.30

package/src/surfaces/point-of-sale/event/data/BaseApi.ts

@@ -0,0 +1,3 @@
+import {StorageApi} from '../../api/storage-api/storage-api';
+
+export type BaseApi = StorageApi;

package/src/surfaces/point-of-sale/event/data/BaseData.ts

@@ -0,0 +1,8 @@
+import type {ConnectivityState, Device, Session} from '../../../point-of-sale';
+
+export interface BaseData {
+  connectivity: ConnectivityState;
+  device: Device;
+  locale: string;
+  session: Session;
+}

package/src/surfaces/point-of-sale/event/data/CartUpdateEventData.ts

@@ -0,0 +1,7 @@
+import {BaseData} from './BaseData';
+import {Cart} from '../../api';
+import {BaseApi} from './BaseApi';
+
+export interface CartUpdateEventData extends BaseData, BaseApi {
+  cart: Cart;
+}

package/src/surfaces/point-of-sale/event/data/CashTrackingSessionData.ts

@@ -0,0 +1,17 @@
+import {BaseData} from './BaseData';
+import {BaseApi} from './BaseApi';
+
+export interface CashTrackingSessionStartData extends BaseData, BaseApi {
+  cashTrackingSessionStart: {
+    id: number;
+    openingTime: string;
+  };
+}
+
+export interface CashTrackingSessionCompleteData extends BaseData, BaseApi {
+  cashTrackingSessionComplete: {
+    id: number;
+    openingTime: string;
+    closingTime: string;
+  };
+}

package/src/surfaces/point-of-sale/event/data/ExchangeTransactionData.ts

@@ -0,0 +1,10 @@
+import {BaseTransactionComplete} from '../../types/base-transaction-complete';
+import {LineItem} from '../../types/cart';
+
+export interface ExchangeTransactionData extends BaseTransactionComplete {
+  transactionType: 'Exchange';
+  returnId?: number;
+  exchangeId?: number;
+  lineItemsAdded: LineItem[];
+  lineItemsRemoved: LineItem[];
+}

package/src/surfaces/point-of-sale/event/data/ReprintReceiptData.ts

@@ -0,0 +1,7 @@
+import {BaseTransactionComplete} from '../../types/base-transaction-complete';
+import {OrderLineItem} from '../../types/order';
+
+export interface ReprintReceiptData extends BaseTransactionComplete {
+  transactionType: 'Reprint';
+  lineItems: OrderLineItem[];
+}

package/src/surfaces/point-of-sale/event/data/ReturnTransactionData.ts

@@ -0,0 +1,10 @@
+import {BaseTransactionComplete} from '../../types/base-transaction-complete';
+import {LineItem} from '../../types/cart';
+
+export interface ReturnTransactionData extends BaseTransactionComplete {
+  transactionType: 'Return';
+  refundId?: number;
+  returnId?: number;
+  exchangeId?: number;
+  lineItems: LineItem[];
+}

package/src/surfaces/point-of-sale/event/data/SaleTransactionData.ts

@@ -0,0 +1,8 @@
+import {BaseTransactionComplete} from '../../types/base-transaction-complete';
+import {LineItem} from '../../types/cart';
+
+export interface SaleTransactionData extends BaseTransactionComplete {
+  transactionType: 'Sale';
+  draftCheckoutUuid?: string;
+  lineItems: LineItem[];
+}

package/src/surfaces/point-of-sale/event/data/TransactionCompleteData.ts

@@ -0,0 +1,21 @@
+import {BaseData} from './BaseData';
+import type {SaleTransactionData} from './SaleTransactionData';
+import type {ExchangeTransactionData} from './ExchangeTransactionData';
+import type {ReturnTransactionData} from './ReturnTransactionData';
+import type {ReprintReceiptData} from './ReprintReceiptData';
+import {BaseApi} from './BaseApi';
+
+export interface TransactionCompleteData extends BaseData, BaseApi {
+  transaction:
+    | SaleTransactionData
+    | ReturnTransactionData
+    | ExchangeTransactionData;
+}
+
+export interface TransactionCompleteWithReprintData extends BaseData, BaseApi {
+  transaction:
+    | SaleTransactionData
+    | ReturnTransactionData
+    | ExchangeTransactionData
+    | ReprintReceiptData;
+}

package/src/surfaces/point-of-sale/event/data.ts

@@ -0,0 +1,16 @@
+export type {BaseData} from './data/BaseData';
+export type {BaseApi} from './data/BaseApi';
+export type {ReprintReceiptData} from './data/ReprintReceiptData';
+export type {
+  TransactionCompleteData,
+  TransactionCompleteWithReprintData,
+} from './data/TransactionCompleteData';
+export type {
+  CashTrackingSessionCompleteData,
+  CashTrackingSessionStartData,
+} from './data/CashTrackingSessionData';
+
+export type {CartUpdateEventData} from './data/CartUpdateEventData';
+
+export type {Device} from '../types/device';
+export type {Money} from '../types/money';

package/src/surfaces/point-of-sale/event/output/BaseOutput.ts

@@ -0,0 +1,8 @@
+interface ExtensionError extends Error {
+  level: 'error' | 'warning';
+  message: string;
+}
+
+export interface BaseOutput {
+  errors?: ExtensionError[];
+}

package/src/surfaces/point-of-sale/event/output.ts

@@ -0,0 +1 @@
+export type {BaseOutput} from './output/BaseOutput';

package/src/surfaces/point-of-sale/extension-targets.ts

@@ -0,0 +1,202 @@
+import {BaseOutput} from './event/output';
+import {
+  CashTrackingSessionStartData,
+  CashTrackingSessionCompleteData,
+} from './event/data/CashTrackingSessionData';
+import {TransactionCompleteData} from './event/data/TransactionCompleteData';
+import {CartUpdateEventData} from './event/data/CartUpdateEventData';
+
+import type {RenderExtension} from '../../extension';
+
+import type {
+  StandardApi,
+  ActionApi,
+  ActionTargetApi,
+  CartApi,
+  CartLineItemApi,
+  CustomerApi,
+  DraftOrderApi,
+  ProductApi,
+  OrderApi,
+  StorageApi,
+} from './api';
+import type {ActionExtensionComponents} from './components/targets/ActionExtensionComponents';
+import type {BlockExtensionComponents} from './components/targets/BlockExtensionComponents';
+import type {SmartGridComponents} from './components/targets/SmartGridComponents';
+import type {ReceiptComponents} from './components/targets/ReceiptComponents';
+import type {BasicComponents} from './components/targets/BasicComponents';
+import type {TransactionCompleteWithReprintData} from './event/data';
+
+export interface EventExtensionTargets {
+  'pos.transaction-complete.event.observe': (
+    data: TransactionCompleteData,
+  ) => Promise<BaseOutput>;
+  'pos.cash-tracking-session-start.event.observe': (
+    data: CashTrackingSessionStartData,
+  ) => Promise<BaseOutput>;
+  'pos.cash-tracking-session-complete.event.observe': (
+    data: CashTrackingSessionCompleteData,
+  ) => Promise<BaseOutput>;
+  'pos.cart-update.event.observe': (
+    data: CartUpdateEventData,
+  ) => Promise<BaseOutput>;
+}
+
+export interface RenderExtensionTargets {
+  'pos.home.tile.render': RenderExtension<
+    StandardApi<'pos.home.tile.render'> & ActionApi & CartApi,
+    SmartGridComponents
+  >;
+  'pos.home.modal.render': RenderExtension<
+    ActionTargetApi<'pos.home.modal.render'> & CartApi,
+    BasicComponents
+  >;
+  'pos.return.post.action.menu-item.render': RenderExtension<
+    StandardApi<'pos.return.post.action.menu-item.render'> &
+      ActionApi &
+      OrderApi,
+    ActionExtensionComponents
+  >;
+  'pos.return.post.action.render': RenderExtension<
+    ActionTargetApi<'pos.return.post.action.render'> & OrderApi,
+    BasicComponents
+  >;
+  'pos.return.post.block.render': RenderExtension<
+    StandardApi<'pos.return.post.block.render'> & OrderApi & ActionApi,
+    BlockExtensionComponents
+  >;
+  'pos.exchange.post.action.menu-item.render': RenderExtension<
+    StandardApi<'pos.exchange.post.action.menu-item.render'> &
+      ActionApi &
+      OrderApi,
+    ActionExtensionComponents
+  >;
+  'pos.exchange.post.action.render': RenderExtension<
+    ActionTargetApi<'pos.exchange.post.action.render'> & OrderApi,
+    BasicComponents
+  >;
+  'pos.exchange.post.block.render': RenderExtension<
+    StandardApi<'pos.exchange.post.block.render'> & OrderApi & ActionApi,
+    BlockExtensionComponents
+  >;
+  'pos.purchase.post.action.menu-item.render': RenderExtension<
+    StandardApi<'pos.purchase.post.action.menu-item.render'> &
+      ActionApi &
+      OrderApi,
+    ActionExtensionComponents
+  >;
+  'pos.purchase.post.action.render': RenderExtension<
+    ActionTargetApi<'pos.purchase.post.action.render'> & OrderApi,
+    BasicComponents
+  >;
+  'pos.purchase.post.block.render': RenderExtension<
+    StandardApi<'pos.purchase.post.block.render'> & OrderApi & ActionApi,
+    BlockExtensionComponents
+  >;
+  'pos.product-details.action.menu-item.render': RenderExtension<
+    StandardApi<'pos.product-details.action.menu-item.render'> &
+      ActionApi &
+      CartApi &
+      ProductApi,
+    ActionExtensionComponents
+  >;
+  'pos.product-details.action.render': RenderExtension<
+    ActionTargetApi<'pos.product-details.action.render'> & CartApi & ProductApi,
+    BasicComponents
+  >;
+  'pos.product-details.block.render': RenderExtension<
+    StandardApi<'pos.product-details.block.render'> &
+      CartApi &
+      ProductApi &
+      ActionApi,
+    BlockExtensionComponents
+  >;
+  'pos.order-details.action.menu-item.render': RenderExtension<
+    StandardApi<'pos.order-details.action.menu-item.render'> &
+      ActionApi &
+      CartApi &
+      OrderApi,
+    ActionExtensionComponents
+  >;
+  'pos.order-details.action.render': RenderExtension<
+    ActionTargetApi<'pos.order-details.action.render'> & CartApi & OrderApi,
+    BasicComponents
+  >;
+  'pos.order-details.block.render': RenderExtension<
+    StandardApi<'pos.order-details.block.render'> &
+      CartApi &
+      OrderApi &
+      ActionApi,
+    BlockExtensionComponents
+  >;
+  'pos.draft-order-details.action.menu-item.render': RenderExtension<
+    StandardApi<'pos.draft-order-details.action.menu-item.render'> &
+      ActionApi &
+      CartApi &
+      DraftOrderApi,
+    ActionExtensionComponents
+  >;
+  'pos.draft-order-details.action.render': RenderExtension<
+    ActionTargetApi<'pos.draft-order-details.action.render'> &
+      DraftOrderApi &
+      CartApi,
+    BasicComponents
+  >;
+  'pos.draft-order-details.block.render': RenderExtension<
+    StandardApi<'pos.draft-order-details.block.render'> &
+      ActionApi &
+      CartApi &
+      DraftOrderApi,
+    BlockExtensionComponents
+  >;
+  'pos.customer-details.action.menu-item.render': RenderExtension<
+    StandardApi<'pos.customer-details.action.menu-item.render'> &
+      ActionApi &
+      CartApi &
+      CustomerApi,
+    ActionExtensionComponents
+  >;
+  'pos.customer-details.action.render': RenderExtension<
+    ActionTargetApi<'pos.customer-details.action.render'> &
+      CartApi &
+      CustomerApi,
+    BasicComponents
+  >;
+  'pos.customer-details.block.render': RenderExtension<
+    StandardApi<'pos.customer-details.block.render'> &
+      CartApi &
+      CustomerApi &
+      ActionApi,
+    BlockExtensionComponents
+  >;
+  'pos.cart.line-item-details.action.menu-item.render': RenderExtension<
+    StandardApi<'pos.cart.line-item-details.action.menu-item.render'> &
+      ActionApi &
+      CartApi &
+      CartLineItemApi,
+    ActionExtensionComponents
+  >;
+  'pos.cart.line-item-details.action.render': RenderExtension<
+    ActionTargetApi<'pos.cart.line-item-details.action.render'> &
+      ActionApi &
+      CartApi &
+      CartLineItemApi,
+    BasicComponents
+  >;
+  'pos.receipt-footer.block.render': RenderExtension<
+    {[key: string]: any} & StorageApi & TransactionCompleteWithReprintData,
+    ReceiptComponents
+  >;
+  'pos.receipt-header.block.render': RenderExtension<
+    {[key: string]: any} & StorageApi & TransactionCompleteWithReprintData,
+    ReceiptComponents
+  >;
+}
+
+export interface ExtensionTargets
+  extends RenderExtensionTargets,
+    EventExtensionTargets {}
+
+export type RenderExtensionTarget = keyof RenderExtensionTargets;
+export type EventExtensionTarget = keyof EventExtensionTargets;
+export type ExtensionTarget = keyof ExtensionTargets;

package/src/surfaces/point-of-sale/types/base-transaction-complete.ts

@@ -0,0 +1,21 @@
+import type {Customer, Discount} from './cart';
+import type {Money} from './money';
+import type {Payment} from './payment';
+import type {ShippingLine} from './shipping-line';
+import type {TaxLine} from './tax-line';
+import type {TransactionType} from './transaction-type';
+
+export interface BaseTransactionComplete {
+  transactionType: TransactionType;
+  orderId?: number;
+  customer?: Customer;
+  discounts?: Discount[];
+  taxTotal: Money;
+  subtotal: Money;
+  grandTotal: Money;
+  paymentMethods: Payment[];
+  balanceDue: Money;
+  shippingLines?: ShippingLine[];
+  taxLines?: TaxLine[];
+  executedAt: string;
+}

package/src/surfaces/point-of-sale/types/cart.ts

@@ -0,0 +1,188 @@
+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;
+  note?: string;
+  cartDiscount?: Discount;
+  cartDiscounts: Discount[];
+  customer?: Customer;
+  lineItems: LineItem[];
+  properties: Record<string, string>;
+}
+
+export interface CartUpdateInput {
+  note?: string;
+  cartDiscount?: Discount;
+  cartDiscounts: Discount[];
+  customer?: Customer;
+  lineItems: LineItem[];
+  properties: Record<string, string>;
+}
+
+export interface Customer {
+  id: number;
+}
+
+export interface LineItem {
+  uuid: string;
+  price?: number;
+  quantity: number;
+  title?: string;
+  variantId?: number;
+  productId?: number;
+  discounts: Discount[];
+  taxable: boolean;
+  taxLines: TaxLine[];
+  sku?: string;
+  vendor?: string;
+  properties: {[key: string]: string};
+  isGiftCard: boolean;
+  attributedUserId?: number;
+  requiresSellingPlan?: boolean;
+  hasSellingPlanGroups?: boolean;
+  /**
+   * The currently selected selling plan for this line item.
+   */
+  sellingPlan?: SellingPlan;
+}
+
+/**
+ * Represents a selling plan associated with a line item.
+ */
+export interface SellingPlan {
+  /**
+   * The unique identifier of the selling plan.
+   */
+  id: number;
+  /**
+   * The name of the selling plan.
+   */
+  name: string;
+  /**
+   * The fingerprint of the applied selling plan within this cart session.
+   * Provided by POS. Not available during refund / exchanges.
+   */
+  digest?: string;
+  /**
+   * The interval of the selling plan. (DAY, WEEK, MONTH, YEAR).
+   */
+  deliveryInterval?: SellingPlanDeliveryInterval;
+  /**
+   * The number of intervals between deliveries.
+   */
+  deliveryIntervalCount?: number;
+}
+
+export enum SellingPlanDeliveryInterval {
+  Day = 'DAY',
+  Week = 'WEEK',
+  Month = 'MONTH',
+  Year = 'YEAR',
+}
+
+export interface Discount {
+  amount: number;
+  currency?: string;
+  discountDescription?: string;
+  type?: string;
+}
+
+/**
+ * Parameters for adding custom properties to a line item.
+ */
+export interface SetLineItemPropertiesInput {
+  /**
+   * The uuid belonging to the line item which should receive the custom properties.
+   */
+  lineItemUuid: string;
+  /**
+   * The custom properties to apply to the line item.
+   */
+  properties: Record<string, string>;
+}
+
+/**
+ * Parameters for adding a line item discount.
+ */
+export interface SetLineItemDiscountInput {
+  /**
+   * The uuid belonging to the line item which should receive the discount.
+   */
+  lineItemUuid: string;
+  /**
+   * The discount to be applied to the line item.
+   */
+  lineItemDiscount: LineItemDiscount;
+}
+
+export interface LineItemDiscount {
+  /**
+   * The title of the line item discount.
+   */
+  title: string;
+  /**
+   * The discount type.
+   */
+  type: 'Percentage' | 'FixedAmount';
+  /**
+   * The percentage or fixed amount for the discount.
+   */
+  amount: string;
+}
+
+export interface CustomSale {
+  quantity: number;
+  title: string;
+  price: string;
+  taxable: boolean;
+}
+
+export interface Address {
+  address1?: string;
+  address2?: string;
+  city?: string;
+  company?: string;
+  firstName?: string;
+  lastName?: string;
+  phone?: string;
+  province?: string;
+  country?: string;
+  zip?: string;
+  name?: string;
+  provinceCode?: string;
+  countryCode?: CountryCode;
+}
+
+export interface SetLineItemSellingPlanInput {
+  /**
+   * The uuid of the line item to which the selling plan should be applied.
+   */
+  lineItemUuid: string;
+  /**
+   * The ID of the selling plan to apply to the line item.
+   */
+  sellingPlanId: number;
+  /**
+   * The name of the selling plan to apply to the line item.
+   */
+  sellingPlanName: string;
+  /**
+   * The interval of the selling plan. (DAY, WEEK, MONTH, YEAR).
+   * If not provided, POS will try to fetch it from the server after syncing the cart.
+   */
+  sellingPlanDeliveryInterval?: SellingPlanDeliveryInterval;
+  /**
+   * The number of intervals between deliveries.
+   * If not provided, POS will try to fetch it from the server after syncing the cart.
+   */
+  sellingPlanDeliveryIntervalCount?: number;
+}