@shopify/ui-extensions 2025.10.0-rc.4 → 2025.10.0-rc.41

package/src/surfaces/point-of-sale/api/device-api/device-api.ts

@@ -0,0 +1,21 @@
+export interface DeviceApiContent {
+  /**
+   * The name of the device
+   */
+  name: string;
+  /**
+   * The string ID of the device
+   */
+  getDeviceId(): Promise<string>;
+  /**
+   * Whether the device is a tablet
+   */
+  isTablet(): Promise<boolean>;
+}
+
+/**
+ * Access information about the device, like name and ID
+ */
+export interface DeviceApi {
+  device: DeviceApiContent;
+}

package/src/surfaces/point-of-sale/api/draft-order-api/draft-order-api.ts

@@ -0,0 +1,20 @@
+export interface DraftOrderApi {
+  draftOrder: DraftOrderApiContent;
+}
+
+export interface DraftOrderApiContent {
+  /**
+   * The unique identifier for the draft order
+   */
+  id: number;
+
+  /**
+   * The name of the draft order
+   */
+  name: string;
+
+  /**
+   * The unique identifier of the customer associated with the draft order
+   */
+  customerId?: number;
+}

package/src/surfaces/point-of-sale/api/locale-api/locale-api.ts

@@ -0,0 +1,16 @@
+import type {ReadonlySignalLike} from '../../../../shared';
+
+export interface LocaleApiContent {
+  /**
+   * Provides read-only access to the current IETF-formatted locale and allows subscribing to locale changes.
+   * The `value` property provides the current locale, and `subscribe` allows listening to changes.
+   */
+  current: ReadonlySignalLike<string>;
+}
+
+/**
+ * Access the merchant’s current locale (in [IETF format](https://en.wikipedia.org/wiki/IETF_language_tag)) to internationalize your extension content.
+ */
+export interface LocaleApi {
+  locale: LocaleApiContent;
+}

package/src/surfaces/point-of-sale/api/navigation-api/navigation-api.ts

@@ -0,0 +1,63 @@
+export interface NavigationNavigateOptions {
+  /**
+   * Developer-defined information to be stored in the associated NavigationHistoryEntry once the navigation is complete, retrievable via getState().
+   */
+  state?: unknown;
+}
+
+/**
+ * The NavigationHistoryEntry interface of the Navigation API represents a single navigation history entry.
+ */
+export interface NavigationHistoryEntry {
+  /** Returns the key of the history entry. This is a unique, UA-generated value that represents the history entry's slot in the entries list rather than the entry itself. */
+  key: string;
+  /**
+   * Returns the URL of this history entry.
+   */
+  url: string | null;
+  /**
+   * Returns a clone of the available state associated with this history entry.
+   */
+  getState(): unknown;
+}
+
+/**
+ * The NavigationCurrentEntryChangeEvent interface of the Navigation API is the event object for the currententrychange event, which fires when the Navigation.currentEntry has changed.
+ */
+export interface NavigationCurrentEntryChangeEvent {
+  /**
+   * Returns the NavigationHistoryEntry that was navigated from.
+   */
+  from: NavigationHistoryEntry;
+}
+
+export interface Navigation {
+  /**
+   * The navigate() method navigates to a specific URL, updating any provided state in the history entries list.
+   */
+  navigate: NavigateFunction;
+  /**
+   * The currentEntry read-only property of the Navigation interface returns a NavigationHistoryEntry object representing the location the user is currently navigated to right now.
+   */
+  currentEntry: NavigationHistoryEntry;
+  /**
+   * The back() method of the Navigation interface navigates to the previous entry in the history list.
+   */
+  back(): void;
+  addEventListener(
+    type: 'currententrychange',
+    cb: (event: NavigationCurrentEntryChangeEvent) => void,
+  ): void;
+  removeEventListener(
+    type: 'currententrychange',
+    cb: (event: NavigationCurrentEntryChangeEvent) => void,
+  ): void;
+}
+
+export interface NavigateFunction {
+  /**
+   * Navigates to a specific URL, updating any provided state in the history entries list.
+   * @param url The destination URL to navigate to.
+   */
+  (url: string, options?: NavigationNavigateOptions): void;
+}

package/src/surfaces/point-of-sale/api/order-api/order-api.ts

@@ -0,0 +1,26 @@
+/**
+ * Interface to access the order
+ */
+export interface OrderApi {
+  order: OrderApiContent;
+}
+
+/**
+ * Interface for Order details
+ */
+export interface OrderApiContent {
+  /**
+   * The unique identifier for the order
+   */
+  id: number;
+
+  /**
+   * The name of the order
+   */
+  name: string;
+
+  /**
+   * The unique identifier of the customer associated with the order
+   */
+  customerId?: number;
+}

package/src/surfaces/point-of-sale/api/pin-pad-api.ts

@@ -0,0 +1,23 @@
+import {PinPadOptions, PinValidationResult} from '../types/pin-pad';
+
+export interface PinPadApiContent {
+  /** Shows a pin pad to the user in a modal dialog.
+   *
+   * @param onSubmit the function to be called when the PIN is submitted.
+   * The callback should be used to validate the PIN and return `accept` or `reject`.
+   * @param options the options for the pin pad
+   */
+  showPinPad(
+    onSubmit: (
+      pin: number[],
+    ) => Promise<PinValidationResult> | PinValidationResult,
+    options?: PinPadOptions,
+  ): void;
+}
+
+/**
+ * Access the Pin Pad API for pin pad functionality in a modal.
+ */
+export interface PinPadApi {
+  pinPad: PinPadApiContent;
+}

package/src/surfaces/point-of-sale/api/print-api/print-api.ts

@@ -0,0 +1,29 @@
+/**
+ * Access the print API for printing functionality
+ */
+export interface PrintApiContent {
+  /**
+   * Trigger a print dialog.
+   *
+   * The src must be either:
+   * - A relative path that will be appended to your app's [application_url](/docs/apps/build/cli-for-apps/app-configuration#application_url)
+   * - A full URL to your app's backend that will be used to return the document to print
+   *
+   * Supported document types:
+   * - HTML documents (recommended for best printing experience)
+   * - Text files
+   * - Image files (PNG, JPEG, etc.)
+   * - PDF files (Note: On Android devices, PDFs will be downloaded and must be printed using an external application)
+   *
+   * @param src the source URL of the content to print.
+   * @returns Promise<void> that resolves when content is ready and native print dialog appears.
+   */
+  print(src: string): Promise<void>;
+}
+
+/**
+ * Interface for printing
+ */
+export interface PrintApi {
+  print: PrintApiContent;
+}

package/src/surfaces/point-of-sale/api/product-api/product-api.ts

@@ -0,0 +1,14 @@
+export interface ProductApi {
+  product: ProductApiContent;
+}
+
+export interface ProductApiContent {
+  /**
+   * The unique identifier for the product.
+   */
+  id: number;
+  /**
+   * The unique identifier for the product variant.
+   */
+  variantId: number;
+}

package/src/surfaces/point-of-sale/api/product-search-api/product-search-api.ts

@@ -0,0 +1,94 @@
+import type {MultipleResourceResult} from '../../types/multiple-resource-result';
+import type {PaginatedResult} from '../../types/paginated-result';
+import type {Product, ProductVariant} from '../../types/product';
+
+export type ProductSortType =
+  | 'RECENTLY_ADDED'
+  | 'RECENTLY_ADDED_ASCENDING'
+  | 'ALPHABETICAL_A_TO_Z'
+  | 'ALPHABETICAL_Z_TO_A';
+
+/**
+ * Base interface for pagination.
+ */
+export interface PaginationParams {
+  /**
+   * Specifies the number of results to be returned in this page. The maximum number of items that will be returned is 50.
+   */
+  first?: number;
+  /**
+   * Specifies the page cursor. Items after this cursor will be returned.
+   */
+  afterCursor?: string;
+}
+
+/**
+ * Interface for product search
+ */
+export interface ProductSearchParams extends PaginationParams {
+  /**
+   * The search term to be used to search for POS products.
+   */
+  queryString?: string;
+  /**
+   * Specifies the order in which products should be sorted. When a `queryString` is provided, sortType will not have any effect, as the results will be returned in order by relevance to the `queryString`.
+   */
+  sortType?: ProductSortType;
+}
+
+export interface ProductSearchApiContent {
+  /** Search for products on the POS device.
+   * @param searchParams The parameters for the product search.
+   */
+  searchProducts(
+    searchParams: ProductSearchParams,
+  ): Promise<PaginatedResult<Product>>;
+
+  /** Fetches a single product's details.
+   * @param productId The ID of the product to lookup.
+   */
+  fetchProductWithId(productId: number): Promise<Product | undefined>;
+
+  /** Fetches multiple products' details.
+   * @param productIds Specifies the array of product IDs to lookup. This is limited to 50 products. All excess requested IDs will be removed from the array.
+   */
+  fetchProductsWithIds(
+    productIds: number[],
+  ): Promise<MultipleResourceResult<Product>>;
+
+  /** Fetches a single product variant's details.
+   * @param productVariantId The ID of the product variant to lookup.
+   */
+  fetchProductVariantWithId(
+    productVariantId: number,
+  ): Promise<ProductVariant | undefined>;
+
+  /** Fetches multiple product variants' details.
+   * @param productVariantIds Specifies the array of product variant IDs to lookup. This is limited to 50 product variants. All excess requested IDs will be removed from the array.
+   */
+  fetchProductVariantsWithIds(
+    productVariantIds: number[],
+  ): Promise<MultipleResourceResult<ProductVariant>>;
+
+  /** Fetches all product variants associated with a product.
+   * @param productId The product ID. All variants' details associated with this product ID are returned.
+   */
+  fetchProductVariantsWithProductId(
+    productId: number,
+  ): Promise<ProductVariant[]>;
+
+  /** Fetches a page of product variants associated with a product.
+   * @param paginationParams The parameters for pagination.
+   */
+  fetchPaginatedProductVariantsWithProductId(
+    productId: number,
+    paginationParams: PaginationParams,
+  ): Promise<PaginatedResult<ProductVariant>>;
+}
+
+/**
+ * Access Point of Sale's native product search functionality.
+ */
+export interface ProductSearchApi {
+  productSearch: ProductSearchApiContent;
+}

package/src/surfaces/point-of-sale/api/scanner-api/scanner-api.ts

@@ -0,0 +1,42 @@
+import type {ReadonlySignalLike} from '../../../../shared';
+
+/** The scanner source the POS device supports. */
+export type ScannerSource = 'camera' | 'external' | 'embedded';
+
+export interface ScannerSubscriptionResult {
+  /** The string data from the last scanner event received. */
+  data?: string;
+  /** The scanning source from which the scan event came. */
+  source?: ScannerSource;
+}
+
+export interface ScannerSources {
+  /**
+   * The current available scanner sources.
+   * The `value` property provides the current sources, and `subscribe` allows listening to changes.
+   */
+  current: ReadonlySignalLike<ScannerSource[]>;
+}
+
+export interface ScannerData {
+  /**
+   * The current scan data.
+   * The `value` property provides the current scan result, and `subscribe` allows listening to new scans.
+   */
+  current: ReadonlySignalLike<ScannerSubscriptionResult>;
+}
+
+export interface ScannerApiContent {
+  /**
+   * Provides read-only access to scanner data and allows subscribing to new scan events.
+   */
+  scannerData: ScannerData;
+  /**
+   * Provides read-only access to the available scanner sources on the POS device.
+   */
+  sources: ScannerSources;
+}
+
+export interface ScannerApi {
+  scanner: ScannerApiContent;
+}

package/src/surfaces/point-of-sale/api/session-api/session-api.ts

@@ -0,0 +1,22 @@
+import type {Session} from '../../types/session';
+
+export interface SessionApiContent {
+  /**
+   * Access information on the current POS session.
+   */
+  currentSession: Session;
+  /**
+   * Get a fresh session token for communication with your app's backend service.
+   * When the authenticated user (the user that logged into Shopify POS with their email address) doesn't have the correct app permissions enabled for your app, null will be returned. This is irrelevant of which POS Staff member is pinned in, as those are not authenticated users.
+   * For more information, see our [app permissions documentation](https://help.shopify.com/en/manual/your-account/users/roles/permissions/store-permissions#apps-and-channels-permissions).
+   * Calls to Shopify APIs must be made by your app’s backend service.
+   */
+  getSessionToken: () => Promise<string | undefined>;
+}
+
+/**
+ * Access information on the current Session, including data on the current shop, user, staff and location.
+ */
+export interface SessionApi {
+  session: SessionApiContent;
+}

package/src/surfaces/point-of-sale/api/standard/standard-api.ts

@@ -0,0 +1,21 @@
+import {ConnectivityApi} from '../connectivity-api/connectivity-api';
+import {DeviceApi} from '../device-api/device-api';
+import {LocaleApi} from '../locale-api/locale-api';
+import {SessionApi} from '../session-api/session-api';
+import {ToastApi} from '../toast-api/toast-api';
+import {ProductSearchApi} from '../product-search-api/product-search-api';
+import {PrintApi} from '../print-api/print-api';
+import {StorageApi} from '../storage-api/storage-api';
+import {PinPadApi} from '../pin-pad-api';
+
+export type StandardApi<T> = {[key: string]: any} & {
+  extensionPoint: T;
+} & LocaleApi &
+  ToastApi &
+  SessionApi &
+  PrintApi &
+  ProductSearchApi &
+  DeviceApi &
+  ConnectivityApi &
+  StorageApi &
+  PinPadApi;

package/src/surfaces/point-of-sale/api/storage-api/storage-api.ts

@@ -0,0 +1,5 @@
+import {Storage} from '../../types/storage';
+
+export interface StorageApi {
+  storage: Storage;
+}

package/src/surfaces/point-of-sale/api/toast-api/toast-api.ts

@@ -0,0 +1,16 @@
+export interface ShowToastOptions {
+  duration?: number;
+}
+
+export interface ToastApiContent {
+  /**
+   * Show a toast.
+   * @param content The text content to display.
+   * @param options An object containing ShowToastOptions.
+   */
+  show: (content: string, options?: ShowToastOptions) => void;
+}
+
+export interface ToastApi {
+  toast: ToastApiContent;
+}

package/src/surfaces/point-of-sale/api.ts

@@ -0,0 +1,128 @@
+export type {
+  CartApi,
+  CartDiscountType,
+  CartApiContent,
+  LineItemDiscountType,
+} from './api/cart-api/cart-api';
+
+export type {CartLineItemApi} from './api/cart-line-item-api/cart-line-item-api';
+
+export type {ActionApi, ActionApiContent} from './api/action-api/action-api';
+
+export type {StandardApi} from './api/standard/standard-api';
+export type {ActionTargetApi} from './api/action-target-api/action-target-api';
+
+export type {
+  ConnectivityStateSeverity,
+  ConnectivityState,
+  ConnectivityApiContent,
+  ConnectivityApi,
+} from './api/connectivity-api/connectivity-api';
+
+export type {
+  CustomerApi,
+  CustomerApiContent,
+} from './api/customer-api/customer-api';
+
+export type {DeviceApi, DeviceApiContent} from './api/device-api/device-api';
+
+export type {LocaleApi, LocaleApiContent} from './api/locale-api/locale-api';
+
+export type {OrderApiContent, OrderApi} from './api/order-api/order-api';
+
+export type {
+  ProductApi,
+  ProductApiContent,
+} from './api/product-api/product-api';
+
+export type {
+  DraftOrderApi,
+  DraftOrderApiContent,
+} from './api/draft-order-api/draft-order-api';
+
+export type {PrintApi, PrintApiContent} from './api/print-api/print-api';
+
+export type {
+  PaginationParams,
+  ProductSortType,
+  ProductSearchParams,
+  ProductSearchApi,
+  ProductSearchApiContent,
+} from './api/product-search-api/product-search-api';
+
+export type {
+  ScannerSource,
+  ScannerSubscriptionResult,
+  ScannerApi,
+  ScannerApiContent,
+} from './api/scanner-api/scanner-api';
+
+export type {
+  SessionApiContent,
+  SessionApi,
+} from './api/session-api/session-api';
+
+export type {StorageApi} from './api/storage-api/storage-api';
+
+export type {
+  ShowToastOptions,
+  ToastApiContent,
+  ToastApi,
+} from './api/toast-api/toast-api';
+
+// Type exports
+export type {
+  Cart,
+  CartUpdateInput,
+  Customer,
+  LineItem,
+  Discount,
+  SetLineItemPropertiesInput,
+  SetLineItemDiscountInput,
+  LineItemDiscount,
+  CustomSale,
+  Address,
+  SellingPlan,
+  SetLineItemSellingPlanInput,
+} from './types/cart';
+
+export type {OrderLineItem, LineItemRefund} from './types/order';
+
+export type {DirectApiRequestBody} from './types/direct-api-request-body';
+
+export type {
+  ShippingLine,
+  CalculatedShippingLine,
+  CustomShippingLine,
+} from './types/shipping-line';
+
+export type {TaxLine} from './types/tax-line';
+
+export type {PaymentMethod, Payment} from './types/payment';
+
+export type {MultipleResourceResult} from './types/multiple-resource-result';
+
+export type {PaginatedResult} from './types/paginated-result';
+
+export type {
+  Product,
+  ProductVariant,
+  ProductVariantOption,
+  ProductVariantInventoryPolicy,
+  ProductOption,
+} from './types/product';
+
+export type {CountryCode} from './types/country-code';
+
+export type {Session} from './types/session';
+export type {Storage} from './types/storage';
+export {StorageError} from './types/storage';
+
+export type {PinPadApiContent, PinPadApi} from './api/pin-pad-api';
+export type {
+  PinPadOptions,
+  PinPadResult,
+  PinLength,
+  PinPadActionType,
+  PinValidationResult,
+} from './types/pin-pad';

package/src/surfaces/point-of-sale/components/Badge/examples/default.html

@@ -0,0 +1,5 @@
+<s-badge tone="neutral">Neutral</s-badge>
+<s-badge tone="success">Success</s-badge>
+<s-badge tone="info">Highlight</s-badge>
+<s-badge tone="warning">Warning</s-badge>
+<s-badge tone="critical">Critical</s-badge>

package/src/surfaces/point-of-sale/components/Badge.d.ts

@@ -0,0 +1,52 @@
+/** VERSION: undefined **/
+/* eslint-disable import-x/extensions */
+/* eslint-disable @typescript-eslint/no-namespace */
+/* eslint-disable @typescript-eslint/member-ordering */
+/* eslint-disable line-comment-position */
+/* eslint-disable @typescript-eslint/unified-signatures */
+/* eslint-disable no-var */
+/* eslint-disable import-x/namespace */
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
+/// <reference lib="DOM" />
+import type {BadgeProps, Key, Ref} from './components-shared.d.ts';
+
+export type ComponentChildren = any;
+/**
+ * Used when an element does not have children.
+ */
+export interface BaseElementProps<TClass = HTMLElement> {
+  key?: Key;
+  ref?: Ref<TClass>;
+  slot?: Lowercase<string>;
+}
+/**
+ * Used when an element has children.
+ */
+export interface BaseElementPropsWithChildren<TClass = HTMLElement>
+  extends BaseElementProps<TClass> {
+  children?: ComponentChildren;
+}
+
+declare const tagName = 's-badge';
+export interface BadgeJSXProps extends Pick<BadgeProps, 'id'> {
+  tone?: Extract<
+    BadgeProps['tone'],
+    'auto' | 'neutral' | 'info' | 'success' | 'warning' | 'critical' | 'caution'
+  >;
+  children?: ComponentChildren;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    [tagName]: BadgeJSXProps;
+  }
+}
+declare module 'preact' {
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      [tagName]: BadgeJSXProps & BaseElementPropsWithChildren<BadgeJSXProps>;
+    }
+  }
+}
+
+export {tagName};
+export type {BadgeJSXProps};

package/src/surfaces/point-of-sale/components/Banner/examples/default.html

@@ -0,0 +1,15 @@
+<s-banner heading="Label" tone="success">
+  <s-button slot="primary-action">Action</s-button>
+</s-banner>
+
+<s-banner heading="Label" tone="info">
+  <s-button slot="primary-action">Action</s-button>
+</s-banner>
+
+<s-banner heading="Label" tone="warning">
+  <s-button slot="primary-action">Action</s-button>
+</s-banner>
+
+<s-banner heading="Label" tone="critical">
+  <s-button slot="primary-action">Action</s-button>
+</s-banner>