[Woo POS][Historical Orders] Order Details: Email Receipt action (Wireframe UI) (1/1) #16110

staskus · 2025-09-09T16:00:28Z

Description

Add Email Receipt action to completed orders:

Update PointOfSaleOrderDetailsView with a section that has a button "Email receipt" when order status is .completed.
Present existing POSSendReceiptView when button is tapped.
Make POSSendReceiptView more reusable by injecting receipt sending action.
Added POSPageHeaderView ViewModifier to modify back button from outside.
Make POS receipt-sending reusable by extract it from OrderController into POSReceiptController which allows to pass any order ID.
Optimize existing order receipt services by only requiring Order ID and email address, not the whole Order object.
Optimize receipt-sending when using send-email API endpoint to utilize force_email_update parameter and not require updating order separately.

There are enough refactoring in this PR, I'm leaving Order List and Order Details update after the email is sent to another PR:

[Woo POS][Historical Orders] Order Details: Email Receipt action - Update Order List and Order Details (2/2) #16113

Steps to reproduce

Open POS
Menu -> Orders
Click through orders
Confirm Completed orders have Email receipt button
Tap on a button
Confirm Email receipt view is opened
Confirm x closes the view
Try inputting incorrect emails
Confirm validation continues to work
Enter and send email
Confirm the email is received
PTR order list and select order again, confirm order shows a new email address (automatic updating will be done in another PR)

Testing information

Tested on iPad 26.0 simulator
Tested with 9.6 and 10.0 WooCommerce sites, to verify both send_email and send_order_details endpoints

Screenshots

Simulator.Screen.Recording.-.iPad.Air.13-inch.M3.-.2025-09-09.at.18.53.30.mov

I have considered if this change warrants user-facing release notes and have added them to RELEASE-NOTES.txt if necessary.

…etails

PointOfSaleOrderController only works with current order that is currently being build. However, we want to reuse receipt functionality for historical orders as well. Extracting POSReceiptController to a separate entity allows to reuse it.

…on Order

…gacy API endpoint - send_email from 9.8 allows to pass email and force_email_update parameters - send_order_details requires to update order before sending the receipt

dangermattic · 2025-09-09T16:01:24Z

	1 Warning
⚠️	This PR is larger than 300 lines of changes. Please consider splitting it into smaller PRs for easier and faster reviews.

Generated by 🚫 Danger

wpmobilebot · 2025-09-09T16:10:05Z

📲 You can test the changes from this Pull Request in WooCommerce iOS Prototype by scanning the QR code below to install the corresponding build.

	App Name	WooCommerce iOS Prototype
	Build Number	`pr16110-4ae1b3c`
	Version	`23.2`
	Bundle ID	`com.automattic.alpha.woocommerce`
	Commit	`4ae1b3c`
	Installation URL	3sasocqcpl7v0

Automatticians: You can use our internal self-serve MC tool to give yourself access to those builds if needed.

jaclync

Works as expected 🚀 left some non-blocking comments on the code.

Some observations from testing:

(minor) In both light and dark modes, the selected order row background color could have a bit more contrast from the unselected rows.

dark	light

My test store's time zone is 20 hours behind my device time zone. The date in the POS order UI was first shown in the device time zone, which is different from what's shown in the email, and in the order details UI in the app. Interestingly, after checking the orders tab in the app, the order date became displayed in the store time zone. Another minor consideration is to show the "payment date" instead of the order creation date.

Note the order date in the screenshots.

order UI before sending email	order details	order UI after sending email / checking orders tab (not sure if it's relevant)

jaclync · 2025-09-11T06:12:42Z

WooCommerce/WooCommerceTests/POS/Mocks/MockPOSReceiptController.swift

+import struct Yosemite.Order
+
+final class MockPOSReceiptController: POSReceiptControllerProtocol {
+    var shouldThrowReceiptError: Bool = false


nit: maybe this variable could be more generic to allow any type of error instead of PointOfSaleOrderController.PointOfSaleOrderControllerError.noOrder; or indicating that this variable is for throwing this specific error

jaclync · 2025-09-11T06:27:10Z

WooCommerce/Classes/POS/Controllers/POSReceiptController.swift

@@ -0,0 +1,95 @@
+import Foundation
+import Observation


super nit: this import doesn't seem needed? It's interesting periphery doesn't detect unused imports.

jaclync · 2025-09-11T06:39:39Z

WooCommerce/Classes/POS/Controllers/POSReceiptController.swift

+    func sendReceipt(orderID: Int64, recipientEmail: String) async throws
+}
+
+final class POSReceiptController: POSReceiptControllerProtocol {


nit: how about some other name like POSReceiptSender/POSReceiptSendingService? As this class doesn't seem to hold any states for POS, a minor naming suggestion to avoid "controller" based on the POS documentation on controllers:

woocommerce-ios/WooCommerce/Classes/POS/README.md

Lines 48 to 52 in 3914fc5

#### Controllers

Each `Controller` handles a piece of global shared state, and provides the interface for interacting with it.

Often, the best way to do that is to expose a single enum covering all valid possibilities for that state, rather than exposing model objects. We've not achieved that in all the controllers yet, and some global state hasn't been encapsulated in a controller successfully yet, for example card payments.

Thanks for sharing. Yes, I think it's better to rename it to keep controller behavior consistent 👍

jaclync · 2025-09-11T06:52:36Z

WooCommerce/Classes/POS/Presentation/PointOfSaleEntryPointView.swift

@@ -85,7 +88,7 @@ struct PointOfSaleEntryPointView: View {
        .environmentObject(posModalManager)
        .environmentObject(posSheetManager)
        .environmentObject(posCoverManager)
-        .environment(PointOfSaleOrderListModel(ordersController: ordersController))
+        .environment(PointOfSaleOrderListModel(ordersController: ordersController, receiptController: receiptController))


nit: how about DI'ing PointOfSaleOrderListModel instead of POSReceiptControllerProtocol , so that PointOfSaleOrderListModel is explicitly owned?

I updated it to be the same way as with aggregateModel. Keeping it in the entryPointView as @State

jaclync · 2025-09-11T06:56:04Z

Modules/Sources/NetworkingCore/Remote/OrdersRemote.swift

+                                   method: .post,
+                                   siteID: siteID,
+                                   path: path,
+                                   parameters: parameters,
+                                   availableAsRESTRequest: true)


super nit: indentation

jaclync · 2025-09-11T06:57:45Z

Modules/Sources/NetworkingCore/Remote/OrdersRemote.swift

+            "billing": [
+                "email": emailAddress
+            ]


just wondering, does this affect other billing fields than the email field like the address? I'm guessing/hoping it doesn't. If it does, we might want to stay with the previous order remote update.

No, it doesn't affect other billing fields. I tested. It targets only the email address.

jaclync · 2025-09-11T07:04:03Z

Modules/Tests/YosemiteTests/Tools/POS/POSOrderServiceTests.swift

+    @Test
+    func updatePOSOrder_calls_remote_updatePOSOrderEmail_with_correct_parameters() async throws {


super nit: could be in the same line? Same for the other test case.

jaclync · 2025-09-11T07:16:57Z

WooCommerce/Classes/POS/Presentation/Reusable Views/POSPageHeaderView.swift

+
+extension View {
+    /// Sets the back button icon for all POSPageHeaderView instances in the view hierarchy.
+    /// - Parameter icon: The system name for the back button icon (e.g., "xmark")


nit: it looks like this icon only work for system symbols? Maybe can make it more obvious in the function signature.

Renamed to systemName: to follow the Image(..) initializer

jaclync · 2025-09-11T07:17:37Z

WooCommerce/WooCommerceTests/POS/Controllers/POSReceiptControllerTests.swift

+    let mockOrderService = MockPOSOrderService()
+    let mockReceiptService = MockReceiptService()
+    let mockAnalyticsProvider = MockAnalyticsProvider()
+    let mockFeatureFlagService = MockFeatureFlagService()
+    let mockPluginsService = MockPluginsService()
+    let sut: POSReceiptController


nit: could these be private?

jaclync · 2025-09-11T07:21:42Z

WooCommerce/WooCommerceTests/POS/Controllers/PointOfSaleOrderControllerTests.swift

-        @Test func sendReceipt_tracks_success_with_eligible_for_pos_receipt() async throws {
-            // Given
-            let mockPluginsService = MockPluginsService()
-            mockPluginsService.setMockPlugin(.wooCommerce,
-                                             systemPlugin: SystemPlugin.fake().copy(plugin: "woocommerce/woocommerce.php",
-                                                                                    version: "10.0.0-dev",
-                                                                                    active: true))
-
-            let mockFeatureFlagService = MockFeatureFlagService()
-            mockFeatureFlagService.isFeatureFlagEnabledReturnValue[.pointOfSaleReceipts] = true
-
-            let sut = PointOfSaleOrderController(orderService: orderService,
-                                                 receiptService: receiptService,
-                                                 analytics: analytics,
-                                                 featureFlagService: mockFeatureFlagService,
-                                                 pluginsService: mockPluginsService)
-            let order = Order.fake()
-            orderService.orderToReturn = order
-
-            // We need an existing order before we can send a receipt
-            await sut.syncOrder(for: .init(purchasableItems: [makeItem()]), retryHandler: { })
-            analyticsProvider.receivedEvents.removeAll()
-            analyticsProvider.receivedProperties.removeAll()
-
-            // When
-            try await sut.sendReceipt(recipientEmail: "[email protected]")
-
-            // Then
-            let indexOfEvent = try #require(analyticsProvider.receivedEvents.firstIndex(where: { $0 == "receipt_email_success" }))
-            #expect(analyticsProvider.receivedProperties[indexOfEvent]["eligible_for_pos_receipt"] as? Bool == true)
-        }

-        @Test func sendReceipt_without_order_tracks_failure_without_eligible_for_pos_receipt() async throws {
-            // Given
-            let mockFeatureFlagService = MockFeatureFlagService()
-            mockFeatureFlagService.isFeatureFlagEnabledReturnValue[.pointOfSaleReceipts] = true
-            let sut = PointOfSaleOrderController(orderService: orderService,
-                                                 receiptService: receiptService,
-                                                 analytics: analytics,
-                                                 featureFlagService: mockFeatureFlagService)
-
-            // When
-            do {
-                try await sut.sendReceipt(recipientEmail: "[email protected]")
-            } catch {
-                // Then
-                let indexOfEvent = try #require(analyticsProvider.receivedEvents.firstIndex(where: { $0 == "receipt_email_failed" }))
-                #expect(analyticsProvider.receivedProperties[indexOfEvent]["eligible_for_pos_receipt"] == nil)
-            }
-        }
-
-        @Test func sendReceipt_tracks_failure_with_eligible_for_pos_receipt() async throws {
-            // Given
-            let mockPluginsService = MockPluginsService()
-            mockPluginsService.setMockPlugin(.wooCommerce,
-                                             systemPlugin: SystemPlugin.fake().copy(plugin: "woocommerce/woocommerce.php",
-                                                                                    version: "10.0.0-dev",
-                                                                                    active: true))
-
-            let mockFeatureFlagService = MockFeatureFlagService()
-            mockFeatureFlagService.isFeatureFlagEnabledReturnValue[.pointOfSaleReceipts] = true
-            let sut = PointOfSaleOrderController(orderService: orderService,
-                                                 receiptService: receiptService,
-                                                 analytics: analytics,
-                                                 featureFlagService: mockFeatureFlagService,
-                                                 pluginsService: mockPluginsService)
-
-            receiptService.sendReceiptResult = .failure(DotcomError.unknown(code: "test_error", message: "Test error"))
-
-            let order = Order.fake()
-            orderService.orderToReturn = order
-
-            // We need an existing order before we can send a receipt
-            await sut.syncOrder(for: .init(purchasableItems: [makeItem()]), retryHandler: { })
-            analyticsProvider.receivedEvents.removeAll()
-            analyticsProvider.receivedProperties.removeAll()
-
-            // When
-            do {
-                try await sut.sendReceipt(recipientEmail: "[email protected]")
-            } catch {
-                // Then
-                let indexOfEvent = try #require(analyticsProvider.receivedEvents.firstIndex(where: { $0 == "receipt_email_failed" }))
-                #expect(analyticsProvider.receivedProperties[indexOfEvent]["eligible_for_pos_receipt"] as? Bool == true)
-                #expect(analyticsProvider.receivedProperties[indexOfEvent]["error_description"] as? String != nil)
-            }
-        }
-    }


nit: do you think we can keep the analytics tests, or maybe they are not necessary for some reasons?

I moved them to POSReceiptSenderTests, they still exist 👍

…details-email-receipt-action

staskus · 2025-09-11T18:57:39Z

Thank you for your thorough review, @jaclync! Great comments as always. I addressed everything except the selection color. I will leave these updates after the designer input 👍

staskus added 14 commits September 9, 2025 09:50

Add Email receipt action with action section to point of sale order d…

cc339f2

…etails

Conditional actions presentation

1bf4399

Move receipt-related tests to POSReceiptControllerTests

fcc4550

Update POSSendReceiptView to allow injecting receipt-sending logic

c2dfab9

Update POSTabCoordinator dependency injection

acb223b

Create updatePOSOrderEmail in OrdersRemote for targeted email update …

68b8aca

…on Order

Remove dependency of Order from POSOrderService updatePOSOrder email

c60ac56

Remove Order dependency from POSReceiptService sendReceipt method

3be0b8c

Update POSReceiptController to rely on orderID and not Order

348d86e

Send receipt from PointOfSaleOrderDetailsView

134e27b

Allow modifying posHeaderBackButton through a view modifier

c6c2999

Speed up POS Receipt Sending - only update order when sending with le…

5f87a42

…gacy API endpoint - send_email from 9.8 allows to pass email and force_email_update parameters - send_order_details requires to update order before sending the receipt

Remove unused code

76e692f

staskus added this to the 23.3 milestone Sep 9, 2025

staskus added type: task An internally driven task. feature: POS labels Sep 9, 2025

staskus requested review from toupper, jaclync and joshheald September 10, 2025 05:49

Only modify back button icon from POSPageHeaderView

9b2d86b

staskus changed the title ~~[Woo POS][Historical Orders] Order Details: Email Receipt action (Wireframe UI)~~ [Woo POS][Historical Orders] Order Details: Email Receipt action (Wireframe UI) (1/1) Sep 10, 2025

staskus mentioned this pull request Sep 10, 2025

[Woo POS][Historical Orders] Order Details: Email Receipt action - Update Order List and Order Details (2/2) #16113

Merged

1 task

jaclync self-assigned this Sep 11, 2025

jaclync approved these changes Sep 11, 2025

View reviewed changes

staskus added 3 commits September 11, 2025 20:29

Merge branch 'trunk' into woomob-1140-woo-poshistorical-orders-order-…

b39f801

…details-email-receipt-action

Make POSReceiptControllerTests properties private

f259d64

Fix OrdersRemote formatting

ac9435a

staskus added 7 commits September 11, 2025 20:40

Fix POSOrderServiceTests formatting

b16a96b

Remove import Observation from POSReceiptController

199d2f4

Name posHeaderBackButtonIcon with systemName

95f5b26

Make error throw from mocks more reusable

4a397e7

Rename POSReceiptController to POSReceiptSender

274c455

Use site timezone for order date formatting

9504721

Hold orderListModel in PointOfSaleEntryPointView as aggregateModel

9c6c91e

Update PointOfSaleEntryPointView.swift

4ae1b3c

staskus force-pushed the woomob-1140-woo-poshistorical-orders-order-details-email-receipt-action branch from 31d1f6b to 4ae1b3c Compare September 11, 2025 20:09

staskus merged commit 7b5f2dc into trunk Sep 12, 2025
14 checks passed

staskus deleted the woomob-1140-woo-poshistorical-orders-order-details-email-receipt-action branch September 12, 2025 05:55

	#### Controllers

	Each `Controller` handles a piece of global shared state, and provides the interface for interacting with it.

	Often, the best way to do that is to expose a single enum covering all valid possibilities for that state, rather than exposing model objects. We've not achieved that in all the controllers yet, and some global state hasn't been encapsulated in a controller successfully yet, for example card payments.

		@Test
		func updatePOSOrder_calls_remote_updatePOSOrderEmail_with_correct_parameters() async throws {

[Woo POS][Historical Orders] Order Details: Email Receipt action (Wireframe UI) (1/1) #16110

[Woo POS][Historical Orders] Order Details: Email Receipt action (Wireframe UI) (1/1) #16110

Uh oh!

Conversation

staskus commented Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Steps to reproduce

Testing information

Screenshots

Uh oh!

dangermattic commented Sep 9, 2025

Uh oh!

wpmobilebot commented Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jaclync left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

staskus commented Sep 11, 2025

Uh oh!

Uh oh!

Uh oh!

staskus commented Sep 9, 2025 •

edited

Loading

wpmobilebot commented Sep 9, 2025 •

edited

Loading

jaclync left a comment •

edited

Loading