[Swift] Make protocol agnostic to usage by markmur · Pull Request #307 · Shopify/checkout-kit

markmur · 2026-06-19T11:16:54Z

The protocol/ package previously baked in opinions about which checkout events matter and how their payloads should be shaped, so every platform inherited the same curation and any tweak rippled through the shared layer. This splits the concerns: protocol/ becomes purely agnostic — transport (EmbeddedCheckoutProtocol, renamed from CheckoutProtocol), the full generated payload types, and a generated catalog of events, describing every OpenRPC method with no view on which surface — while each platform's CheckoutKit now owns curation and consumer-facing transformation. Swift's kit reclaims the CheckoutProtocol name as its curated namespace, exposing the six ec.* events plus window.open and rejecting everything else with a JSON-RPC method-not-found response.

Look at platforms/swift/Sources/ShopifyCheckoutKit/CheckoutProtocol.swift for the curation surface and run the Swift suite — CheckoutProtocolTests covers supported/unsupported method handling and window.open delegation.

Before — `protocol/` owns the curation

// protocol/.../ShopifyCheckoutProtocol/CheckoutProtocol.swift
public enum CheckoutProtocol {
    public static let specVersion = "2026-04-08"
    public static let complete = NotificationDescriptor<Checkout>(method: "ec.complete")
    public static let start = NotificationDescriptor<Checkout>(method: "ec.start")
    // ...the rest of the curated events...

    package static let supportedProtocolMethods: Set<String> = [
        readyMethod, start.method, complete.method, error.method,
        lineItemsChange.method, messagesChange.method, totalsChange.method,
        windowOpen.method
    ]
    package static func methodNotFoundResponse(forUnsupportedProtocolRequest:) -> String? { ... }
}

After — `protocol/` is agnostic, the kit curates

// protocol/ now only exposes transport + generated types:
//   EmbeddedCheckoutProtocol (transport), GeneratedProtocolCatalog (every method, uncurated)

// platforms/swift/.../ShopifyCheckoutKit/CheckoutProtocol.swift
public enum CheckoutProtocol {
    public typealias Client = EmbeddedCheckoutProtocol.Client

    public static let complete = EmbeddedCheckoutProtocol.Event.complete
    public static let start = EmbeddedCheckoutProtocol.Event.start
    // ...the six curated ec.* events...

    static let supportedProtocolMethods: Set<String> = [
        EmbeddedCheckoutProtocol.readyMethod,
        start.method, complete.method, error.method,
        lineItemsChange.method, messagesChange.method, totalsChange.method,
        windowOpen.method
    ]
    static func methodNotFoundResponse(forUnsupportedProtocolRequest:) -> String? { ... }
}

Call sites move from baked-in defaults to explicit curation

// Before
CheckoutProtocol.url(for: url)

// After — the kit passes its own curated delegations into the agnostic transport
EmbeddedCheckoutProtocol.url(for: url, delegations: CheckoutProtocol.defaultDelegations)

markmur · 2026-06-19T11:20:12Z

+        epCartReady.method,
+        epCartAuth.method,
+        epCartError.method,
+        epCartStart.method,
+        epCartComplete.method,
+        epCartLineItemsChange.method,
+        epCartBuyerChange.method,
+        epCartMessagesChange.method,


TBD on whether these events should be part of the generated API surface. They're part of the spec so arguably they should.

I've dropped them. The EmbeddedCheckoutProtocol should only be concerned with ec events. We might consider adding an EmbeddedCartProtocol submodule later for ep events if needed

markmur · 2026-06-19T11:20:51Z

-import Foundation
-
-public enum CheckoutProtocol {
-    public static let specVersion = "2026-04-08"
-
-    public static let defaultDelegations: [String] = ["window.open"]
-
-    package static let readyMethod = "ec.ready"
-    package static let parseErrorCode = -32700
-    package static let parseErrorMessage = "Parse error"
-    package static let methodNotFoundCode = -32601
-    package static let methodNotFoundMessage = "Method not found"
-
-    public static let complete = NotificationDescriptor<Checkout>(method: "ec.complete")
-    public static let error = NotificationDescriptor<ErrorResponse>(method: "ec.error")
-    public static let lineItemsChange = NotificationDescriptor<Checkout>(
-        method: "ec.line_items.change"
-    )
-    public static let messagesChange = NotificationDescriptor<Checkout>(
-        method: "ec.messages.change"
-    )
-    public static let start = NotificationDescriptor<Checkout>(method: "ec.start")
-    public static let totalsChange = NotificationDescriptor<Checkout>(method: "ec.totals.change")
-
-    package static let supportedProtocolMethods: Set<String> = [
-        readyMethod,
-        start.method,
-        complete.method,
-        error.method,
-        lineItemsChange.method,
-        messagesChange.method,
-        totalsChange.method,
-        windowOpen.method
-    ]


This change lifts the curation out of the protocol into the kit - since that's where the abstraction should live

github-actions · 2026-06-22T08:25:23Z

React Native — Coverage Report

Lines	Statements	Branches	Functions
	91.66% (319/348)	87.86% (181/206)	100% (82/82)

markmur · 2026-06-22T09:37:41Z

Marking as ready for review to run CI

markmur · 2026-06-22T11:20:19Z

+public enum CheckoutProtocol {
+    public typealias Client = CheckoutTransport.Client
+
+    public static func url(for url: URL) -> URL {
+        CheckoutTransport.url(for: url, delegations: defaultDelegations)
+    }
+
+    static let defaultDelegations: [String] = ["window.open"]
+
+    static let methodNotFoundCode = -32601
+    static let methodNotFoundMessage = "Method not found"
+
+    public static let complete = GeneratedProtocolCatalog.ecComplete
+    public static let error = GeneratedProtocolCatalog.ecError
+    public static let lineItemsChange = GeneratedProtocolCatalog.ecLineItemsChange
+    public static let messagesChange = GeneratedProtocolCatalog.ecMessagesChange
+    public static let start = GeneratedProtocolCatalog.ecStart
+    public static let totalsChange = GeneratedProtocolCatalog.ecTotalsChange
+
+    static let supportedProtocolMethods: Set<String> = [
+        CheckoutTransport.readyMethod,
+        start.method,
+        complete.method,
+        error.method,
+        lineItemsChange.method,
+        messagesChange.method,
+        totalsChange.method,
+        windowOpen.method
+    ]


This is essentially a facade which curates the set of supported events and lives in the kit itself

github-actions · 2026-06-22T11:20:54Z

Package Size

Platform	Artifact	Base	Head	Delta
Android	release AAR	613.4 KiB	613.4 KiB	0 B

Measured from the PR base SHA and PR head SHA. This comment reports package artifact sizes only; it is not a final app binary-size report.

markmur · 2026-06-22T11:22:03Z

    /// Returns the given checkout URL with the query parameters required to
    /// initiate the Embedded Checkout Protocol handshake (`ec_version`,
    /// `ec_delegate`).
    public static func url(
        for url: URL,
-        delegations: [String] = defaultDelegations
+        delegations: [String] = []


CheckoutProtocol now uses this under the hood and supplies the defaults in the kit. This function is constrained to the package

markmur · 2026-06-22T15:27:14Z

+public enum EmbeddedCheckoutProtocol {
+    public static let specVersion = "2026-04-08"
+
+    package static let readyMethod = "ec.ready"
+    package static let parseErrorCode = -32700
+    package static let parseErrorMessage = "Parse error"
+
    /// Returns the given checkout URL with the query parameters required to
    /// initiate the Embedded Checkout Protocol handshake (`ec_version`,
    /// `ec_delegate`).
    public static func url(
        for url: URL,
-        delegations: [String] = defaultDelegations
+        delegations: [String] = []
    ) -> URL {
        guard var components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
            return url
        }
        var queryItems = components.queryItems ?? []
        queryItems.removeAll { $0.name == "ec_version" || $0.name == "ec_delegate" }

        queryItems.append(URLQueryItem(name: "ec_version", value: specVersion))
        if !delegations.isEmpty {
            queryItems.append(URLQueryItem(name: "ec_delegate", value: delegations.joined(separator: ",")))
        }



Heads up that I'm going to add support for ec_auth and ec_color_scheme here in a follow-up so that non-kit consumers can use the fully compliant protocol

markmur commented Jun 19, 2026

View reviewed changes

markmur force-pushed the agnostic-protocol-refactor branch from 9b8bfaf to a5da2b9 Compare June 19, 2026 11:22

markmur commented Jun 19, 2026

View reviewed changes

Comment thread platforms/react-native/modules/@shopify/checkout-kit-react-native/ios/ProtocolRelay.swift

markmur marked this pull request as ready for review June 22, 2026 08:24

markmur requested a review from a team as a code owner June 22, 2026 08:24

markmur marked this pull request as draft June 22, 2026 09:02

markmur changed the title ~~Make protocol agnostic to usage~~ [Draft] Make protocol agnostic to usage Jun 22, 2026

markmur self-assigned this Jun 22, 2026

markmur marked this pull request as ready for review June 22, 2026 09:37

markmur force-pushed the agnostic-protocol-refactor branch from e27325e to 4aa6560 Compare June 22, 2026 09:51

markmur commented Jun 22, 2026

View reviewed changes

markmur force-pushed the agnostic-protocol-refactor branch 2 times, most recently from 2403a3c to 979df1e Compare June 22, 2026 13:13

markmur added 4 commits June 22, 2026 14:13

Make protocol agnostic to usage

8930f2f

Fix formatting + discrepancies for CI

17c4f77

Make defaultDelegations internal, abstract delegations from url method

4c14955

Swift: dump API

c8cf90e

markmur force-pushed the agnostic-protocol-refactor branch from 979df1e to c8cf90e Compare June 22, 2026 13:14

Drop TS changes

ff95bae

markmur force-pushed the agnostic-protocol-refactor branch from 214a61f to ff95bae Compare June 22, 2026 13:27

markmur changed the title ~~[Draft] Make protocol agnostic to usage~~ [Swift] Make protocol agnostic to usage Jun 22, 2026

markmur added 2 commits June 22, 2026 15:50

CheckoutTransport -> EmbeddedCheckoutProtocol

33c14d2

Merge url method, use extension name formatting for client and codex

541cb4a

markmur requested review from kiftio and westeezy June 22, 2026 15:25

markmur requested a review from kieran-osgood-shopify June 22, 2026 15:25

markmur commented Jun 22, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Swift] Make protocol agnostic to usage#307

[Swift] Make protocol agnostic to usage#307
markmur wants to merge 7 commits into
mainfrom
agnostic-protocol-refactor

markmur commented Jun 19, 2026 •

edited

Loading

Uh oh!

markmur Jun 19, 2026

Uh oh!

markmur Jun 22, 2026

Uh oh!

markmur Jun 19, 2026

Uh oh!

Uh oh!

github-actions Bot commented Jun 22, 2026 •

edited

Loading

Uh oh!

markmur commented Jun 22, 2026

Uh oh!

markmur Jun 22, 2026

Uh oh!

github-actions Bot commented Jun 22, 2026 •

edited

Loading

Uh oh!

markmur Jun 22, 2026

Uh oh!

markmur Jun 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

markmur commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Before — protocol/ owns the curation

After — protocol/ is agnostic, the kit curates

Call sites move from baked-in defaults to explicit curation

Uh oh!

markmur Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

markmur Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

markmur Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

React Native — Coverage Report

Uh oh!

markmur commented Jun 22, 2026

Uh oh!

markmur Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Package Size

Uh oh!

markmur Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

markmur Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

markmur commented Jun 19, 2026 •

edited

Loading

Before — `protocol/` owns the curation

After — `protocol/` is agnostic, the kit curates

github-actions Bot commented Jun 22, 2026 •

edited

Loading

github-actions Bot commented Jun 22, 2026 •

edited

Loading