payment apps: add support for supported buyer contexts #3875

punkstar · 2024-05-09T10:54:48Z

WHY are these changes introduced?

To provide configuration to support future payment app extension features.

WHAT is this pull request doing?

Introduces new configuration for payment app extensions called supported_buyer_contexts. These are small objects with a currency member and an optional countries array.

How to test your changes?

Create a payment app extension: pnpm shopify app generate extension
Modify the configuration to add some supported buyer context configuration:

[[extensions.supported_buyer_contexts]]
currency = "USD"

[[extensions.supported_buyer_contexts]]
currency = "CAD"
countries = ["CA"]

[[extensions.supported_buyer_contexts]]
currency = "EUR"
countries = ["FR", "DE", "XX"]

Deploy new app version: pnpm shopify app deploy

Test Cases

✅ Backwards Compatibility

Do not include any supported_buyer_contexts configuration in the app extension configuration.
Assert that the version is deployed successfully.

AppDeploy payload contains no supported_buyer_contexts:

{
  ...
  "appModules": [
    {
      "config": "{\"api_version\":\"2021-07\",\"start_payment_session_url\":\"https://api.paymentprovider.com/endpoint\",\"merchant_label\":\"Offsite Payments App Extension\",\"supported_countries\":[\"US\"],\"supported_payment_methods\":[\"visa\"],\"test_mode_available\":true,\"supports_oversell_protection\":false,\"supports_3ds\":false,\"supports_deferred_payments\":false,\"supports_installments\":false}",
      "context": "payments.offsite.render",
      "handle": "offsite",
      "uuid": "dc0e3cc2-55e9-4b22-b323-7d70a05f0169"
    },
    ...
  ]
}

✅ Valid Configuration

Include the following configuration.
Assert that the version is deployed successfully.

Configuration:

[[extensions.supported_buyer_contexts]]
currency = "USD"

[[extensions.supported_buyer_contexts]]
currency = "CAD"
countries = ["CA"]

[[extensions.supported_buyer_contexts]]
currency = "EUR"
countries = ["FR", "DE", "LT"]

AppDeploy payload contains expected supported_buyer_contexts value:

{
  ...
  "appModules": [
 {
      "config": "{\"api_version\":\"2021-07\",\"start_payment_session_url\":\"https://api.paymentprovider.com/endpoint\",\"merchant_label\":\"Offsite Payments App Extension\",\"supported_countries\":[\"US\"],\"supported_payment_methods\":[\"visa\"],\"supported_buyer_contexts\":[{\"currency\":\"USD\"},{\"currency\":\"CAD\",\"countries\":[\"CA\"]},{\"currency\":\"EUR\",\"countries\":[\"FR\",\"DE\",\"LT\"]}],\"test_mode_available\":true,\"supports_oversell_protection\":false,\"supports_3ds\":false,\"supports_deferred_payments\":false,\"supports_installments\":false}",
      ...
    },
    ...
  ]
}

✅ Invalid Configuration

Include the following configuration.
Assert that the version is stopped from deploying.

Configuration:

[[extensions.supported_buyer_contexts]]
currency = "USD"
countries = [] # Empty countries array is ambiguous and not allowed.

[[extensions.supported_buyer_contexts]]
countries = ["CA"] # Currency is required

✅ Extension Import (where supported buyer contexts exist)

Publish a version that has a supported buyer context.
Delete the extension directory.
Run shopify app import-extensions to import the extension.
Observe that the correct TOML is generated.

Command runs successfully:

Configuration is correctly generated:

✅ Extension Import (where supported buyer contexts does not exist)

Publish a version that has no supported buyer context.
Delete the extension directory.
Run shopify app import-extensions to import the extension.
Observe that the correct TOML is generated and there is no extensions.supported_buyer_context entries.

Command runs successfully:

Configuration is correctly generated:

Post-release steps

No post-release action required. Documentation changes will be introduced in the future.

Measuring impact

How do we know this change was effective? Please choose one:

n/a - this doesn't need measurement, e.g. a linting rule or a bug-fix
Existing analytics will cater for this addition
PR includes analytics changes to measure impact

Checklist

I've considered possible cross-platform impacts (Mac, Linux, Windows)
I've considered possible documentation changes
I've made sure that any changes to dev or deploy have been reflected in the internal flowchart.

github-actions · 2024-05-09T11:00:19Z

Coverage report

St.^❔	Category	Percentage	Covered / Total
🟡	Statements	71.96% (+0.13% 🔼)	7034/9775
🟡	Branches	68.79% (-0.33% 🔻)	3483/5063
🟡	Functions	71.44% (-0.03% 🔻)	1881/2633
🟡	Lines	73.27% (+0.18% 🔼)	6632/9051

Show new covered files 🐣

St.^❔	File	Statements	Branches	Functions	Lines
🔴	`...` / shopify-developers-client.ts	1.65%	0%	0%	1.74%
🟢	`...` / active-app-release.ts	100%	100%	100%	100%
🟢	`...` / apps.ts	100%	100%	100%	100%
🟢	`...` / create-app-version.ts	100%	100%	100%	100%
🟢	`...` / create-app.ts	100%	100%	100%	100%
🟢	`...` / organization.ts	100%	100%	100%	100%
🟢	`...` / organizations.ts	100%	100%	100%	100%
🟢	`...` / release-version.ts	100%	100%	100%	100%
🟢	`...` / user-info.ts	100%	100%	100%	100%
🟢	`...` / shopify-developers.ts	100%	75%	100%	100%

Show files with reduced coverage 🔻

St.^❔	File	Statements	Branches	Functions	Lines
🟢	`...` / app.test-data.ts	93.06% (-0.04% 🔻)	92.94% (-0.47% 🔻)	83.56%	92.55% (-0.05% 🔻)
🟢	`...` / app.ts	86.21% (-0.94% 🔻)	74.12% (+1.39% 🔼)	89.36% (-1.75% 🔻)	87.5% (-1.21% 🔻)
🟢	`...` / identifiers.ts	100% (+4.08% 🔼)	88.24% (-0.34% 🔻)	100%	100%
🟢	`...` / loader.ts	93.04% (-0.52% 🔻)	86.78% (-0.72% 🔻)	95% (-0.41% 🔻)	94.03% (-0.43% 🔻)
🟢	`...` / extension-instance.ts	85.71% (-0.21% 🔻)	77.55% (-0.88% 🔻)	91.11%	87.1% (-0.2% 🔻)
🟢	`...` / config.ts	91.18% (-1.68% 🔻)	75% (-10.71% 🔻)	90% (+1.11% 🔼)	96.43% (+0.78% 🔼)
🟢	`...` / generate.ts	100%	78.13% (-1.88% 🔻)	100%	100%
🟢	`...` / write-app-configuration-file.ts	95% (-0.12% 🔻)	89.29% (-3.31% 🔻)	100%	97.3% (-0.07% 🔻)
🟢	`...` / link.ts	96.1% (-0.41% 🔻)	72.73% (-19.21% 🔻)	100%	95.89% (-0.5% 🔻)
🟢	`...` / breakdown-extensions.ts	96.43% (-0.12% 🔻)	82.69% (-0.64% 🔻)	100%	100%
🟢	`...` / id-matching.ts	98.77% (-0.18% 🔻)	75% (-9.62% 🔻)	100%	100%
🟢	`...` / select-app.ts	92.86% (-0.48% 🔻)	75%	100%	100%
🟢	`...` / extension.ts	91.21% (-0.1% 🔻)	74.51% (+0.92% 🔼)	91.67%	90.91% (-0.1% 🔻)
🟢	`...` / fetch-extension-specifications.ts	95.65% (-1.01% 🔻)	87.5% (+7.5% 🔼)	100%	100%
🔴	`...` / developer-platform-client.ts	40% (+3.64% 🔼)	28.57% (-2.68% 🔻)	50% (-10% 🔻)	41.67% (+4.82% 🔼)

Test suite run success

1655 tests passing in 767 suites.

Report generated by 🧪jest coverage report action from 894b551

github-actions · 2024-05-21T09:33:01Z

We detected some changes at either packages/*/src or packages/cli-kit/assets/cli-ruby/** and there are no updates in the .changeset.
If the changes are user-facing, run "pnpm changeset add" to track your changes and include them in the next release CHANGELOG.

marklevi

LGTM overall !
It would be great to also spin 🌀 test the pnpm shopify app import-extensions flow ensuring that we are also importing extensions appropriately.
You could also include some tests here: packages/app/src/cli/services/payments/extension-to-toml.test.ts

marklevi · 2024-05-21T13:22:08Z

@punkstar something to also keep in mind is that the minimum required CLI version for payments app extension support is v3.60. Your PR changes would only be applicable to future CLI version releases (soonest being May 27th)

lacoursieresimon

little context on CLI, but it does seem to make sense overall 👍

lacoursieresimon · 2024-05-21T14:22:57Z

...tensions/specifications/payments_app_extension_schemas/base_payments_app_extension_schema.ts

@@ -12,6 +12,7 @@ export interface BasePaymentsAppExtensionDeployConfigType {
  merchant_label: string
  supported_countries: string[]
  supported_payment_methods: string[]
+  supported_buyer_contexts?: {currency: string; countries?: [string, ...string[]]}[]


Am I understanding correctly that this type definition enforces the non-empty condition? (countries?: [string, ...string[]] versus a simpler string[])

If so, do we also need the nonempty() check at line 70? I guess it doesn't hurt either 🤷

If we want to make supported_buyer_contexts required at some point later, are we able to do so or is making it nullable today forcing lifetime support of a nullable value?

Am I understanding correctly that this type definition enforces the non-empty condition? (countries?: [string, ...string[]] versus a simpler string[])

Correct!

If so, do we also need the nonempty() check at line 70? I guess it doesn't hurt either 🤷

We need both. SupportedBuyerContextsSchema is the schema definition that will validate and parse input (by calling #parse on it). BasePaymentsAppExtensionDeployConfigType is just the type definition and the output of the schema. We can compute one from the type from the schema (type SchemaType = zod.infer<typeof Schema>) but there must be a reason we don't!

If we want to make supported_buyer_contexts required at some point later, are we able to do so or is making it nullable today forcing lifetime support of a nullable value?

I don't think we have the concept of config schema versions right now, so we'd likely have to introduce a new pattern to support this. It may already be used by other parts of the CLI but we're not making an irreversible decision.

lacoursieresimon · 2024-05-21T14:33:38Z

...ions/payments_app_extension_schemas/custom_credit_card_payments_app_extension_schema.test.ts

@@ -150,6 +155,7 @@ describe('customCreditCardPaymentsAppExtensionDeployConfig', () => {
      supports_3ds: config.supports_3ds,
      supported_countries: config.supported_countries,
      supported_payment_methods: config.supported_payment_methods,
+      supported_buyer_contexts: config.supported_buyer_contexts,


Should we also test the mapping for customCreditCardDeployConfigToCLIConfig ?

punkstar · 2024-05-24T16:26:10Z

Thanks for the feedback @marklevi! I've added some tests around the TOML generation to cover the new field and I've top hatted the import extension command. All looks fine!

marklevi

💪

punkstar force-pushed the punkstar/supported-buyer-contexts branch from 50a4dd7 to ffb0902 Compare May 9, 2024 10:56

punkstar force-pushed the punkstar/supported-buyer-contexts branch 2 times, most recently from c6404ab to 216f81a Compare May 16, 2024 16:02

punkstar self-assigned this May 21, 2024

payment apps: add support for supported buyer contexts

c597bc1

punkstar force-pushed the punkstar/supported-buyer-contexts branch from 216f81a to c597bc1 Compare May 21, 2024 09:31

punkstar marked this pull request as ready for review May 21, 2024 09:32

punkstar requested review from marklevi, romidane, lacoursieresimon and yigitozkavci May 21, 2024 09:33

punkstar added the #gsd:38440 label May 21, 2024

marklevi requested changes May 21, 2024

View reviewed changes

add test coverage to toml tests

894b551

lacoursieresimon approved these changes May 21, 2024

View reviewed changes

punkstar requested a review from marklevi May 24, 2024 16:26

marklevi approved these changes May 28, 2024

View reviewed changes

shauns approved these changes May 28, 2024

View reviewed changes

punkstar added this pull request to the merge queue May 29, 2024

Merged via the queue into main with commit 38ef1bf May 29, 2024
32 checks passed

punkstar deleted the punkstar/supported-buyer-contexts branch May 29, 2024 08:34

shopify-shipit bot temporarily deployed to nightly May 29, 2024 13:15 Inactive

shopify-shipit bot temporarily deployed to production May 31, 2024 12:35 Inactive

shopify-shipit bot temporarily deployed to experimental June 3, 2024 10:32 Inactive

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

payment apps: add support for supported buyer contexts #3875

payment apps: add support for supported buyer contexts #3875

punkstar commented May 9, 2024 •

edited

github-actions bot commented May 9, 2024 •

edited

github-actions bot commented May 21, 2024

marklevi left a comment •

edited

marklevi commented May 21, 2024 •

edited

lacoursieresimon left a comment

lacoursieresimon May 21, 2024

lacoursieresimon May 21, 2024

punkstar May 24, 2024

lacoursieresimon May 21, 2024

punkstar commented May 24, 2024

marklevi left a comment

payment apps: add support for supported buyer contexts #3875

payment apps: add support for supported buyer contexts #3875

Conversation

punkstar commented May 9, 2024 • edited

WHY are these changes introduced?

WHAT is this pull request doing?

How to test your changes?

Test Cases

Post-release steps

Measuring impact

Checklist

github-actions bot commented May 9, 2024 • edited

Coverage report

Test suite run success

github-actions bot commented May 21, 2024

marklevi left a comment • edited

Choose a reason for hiding this comment

marklevi commented May 21, 2024 • edited

lacoursieresimon left a comment

Choose a reason for hiding this comment

lacoursieresimon May 21, 2024

Choose a reason for hiding this comment

lacoursieresimon May 21, 2024

Choose a reason for hiding this comment

punkstar May 24, 2024

Choose a reason for hiding this comment

lacoursieresimon May 21, 2024

Choose a reason for hiding this comment

punkstar commented May 24, 2024

marklevi left a comment

Choose a reason for hiding this comment

punkstar commented May 9, 2024 •

edited

github-actions bot commented May 9, 2024 •

edited

marklevi left a comment •

edited

marklevi commented May 21, 2024 •

edited