diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/camera-api/camera-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/camera-api/camera-api.ts index 59a6581791..b35c06b377 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/camera-api/camera-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/camera-api/camera-api.ts @@ -11,18 +11,18 @@ export interface CameraMediaOptions { */ facingMode?: 'user' | 'environment'; /** - * The maximum width (1 to 1920) of the image in pixels. Resizes the image to this width if it is larger. + * The requested maximum width of the captured image in pixels. Resizes the image to this width if it's larger. Values below 1 are clamped to 1, and values above 1920 are clamped to 1920 before capture. The `width` on the returned `CameraMediaResponse` is the actual captured image width. * @defaultValue 1080 */ maxWidth?: number; /** - * The maximum height (1 to 1920) of the image in pixels. Resizes the image to this height if it is larger. + * The requested maximum height of the captured image in pixels. Resizes the image to this height if it's larger. Values below 1 are clamped to 1, and values above 1920 are clamped to 1920 before capture. The `height` on the returned `CameraMediaResponse` is the actual captured image height. * @defaultValue 1080 */ maxHeight?: number; /** * The quality of the image returned. - * Percentile value between 0 (lowest quality/highest compression) and 1 (highest quality/lowest compression). + * A value between 0 (lowest quality, highest compression) and 1 (highest quality, lowest compression). Values outside this range throw an error. * @defaultValue 0.9 */ quality?: number; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/cash-drawer-api/cash-drawer-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/cash-drawer-api/cash-drawer-api.ts index 4e2841ca70..e83150dd97 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/cash-drawer-api/cash-drawer-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/cash-drawer-api/cash-drawer-api.ts @@ -6,6 +6,8 @@ export interface CashDrawerApiContent { /** * Opens the connected cash drawer device. The drawer will automatically open if a compatible cash drawer is connected to the POS device. Use for manual cash drawer operations, implementing custom payment workflows, or providing explicit cash drawer access in register management interfaces. * + * The returned promise doesn't confirm that the drawer physically opened. + * * @returns Void */ open(): Promise; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/device-api/device-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/device-api/device-api.ts index 7219339e3a..a117ce7649 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/device-api/device-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/device-api/device-api.ts @@ -4,7 +4,7 @@ */ export interface DeviceApiContent { /** - * The name of the device as configured by the merchant or system. Use for displaying device information in interfaces, logging, or support contexts where device identification is helpful. + * The operating system device name (for example, the iPad name set in system settings), or the device model name when no name was set. For the merchant-assigned register name configured in POS settings, use `registerName`. */ name: string; /** @@ -13,6 +13,9 @@ export interface DeviceApiContent { registerName: string; /** * Retrieves the unique string identifier for the device. Returns a promise that resolves to the device ID. Use for device-specific data storage, analytics tracking, or implementing device-based permissions and configurations. + * + * This identifier differs from the numeric device ID available as `shopify.session.deviceId` and as `device.deviceId` on event data. + * * Note: While Shopify POS attempts to maintain a stable identifier, it is not guaranteed to be permanent and may change. */ getDeviceId(): Promise; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/pin-pad-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/pin-pad-api.ts index dadb3ec743..aae9f7f39e 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/pin-pad-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/pin-pad-api.ts @@ -12,6 +12,8 @@ export interface PinPadApiContent { * * • **When rejected**: Displays the optional `errorMessage` and keeps the modal open. * + * Catch errors inside `onSubmit` and return `{result: 'reject', errorMessage}` with a message that's safe to display to the merchant. + * * Use for implementing secure authentication workflows, access control, or PIN-based verification systems. */ showPinPad( diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/device.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/device.ts index ca51199514..3e81c1ed40 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/device.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/device.ts @@ -8,7 +8,7 @@ export interface Device { */ name: string; /** - * The unique identifier for the POS device. + * The numeric Shopify POS device ID (the same value as `shopify.session.deviceId`). This differs from the string returned by `shopify.device.getDeviceId()`. */ deviceId: number; /** diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/pin-pad.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/pin-pad.ts index 0bf183880e..d16967e644 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/pin-pad.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/pin-pad.ts @@ -35,7 +35,7 @@ export type PinLength = 4 | 5 | 6 | 7 | 8 | 9 | 10; */ export interface PinPadActionType { /** - * The content for the prompt on the pin pad. Use to provide clear instructions or context about what the PIN is being used for. + * The label of the custom action button shown between the entry view and the keypad. */ label: string; /**