Rename and reorder payment methods at checkout

api_version = "2026-10"

[[extensions]]
name = "Rename and reorder payment methods"
handle = "rename-reorder-payment-methods"
type = "function"

  [[extensions.targeting]]
  target = "cart.payment-methods.transform.run"
  input_query = "src/cart_payment_methods_transform_run.graphql"
  export = "cart-payment-methods-transform-run"

  [extensions.build]
  command = ""
  path = "dist/function.wasm"

query CartPaymentMethodsTransformRunInput {
  paymentMethods {
    id
    name
  }
  paymentCustomization {
    metafield(namespace: "$app", key: "function-configuration") {
      jsonValue
    }
  }
}

// @ts-check

/**
 * @typedef {import("../generated/api").CartPaymentMethodsTransformRunInput} CartPaymentMethodsTransformRunInput
 * @typedef {import("../generated/api").CartPaymentMethodsTransformRunResult} CartPaymentMethodsTransformRunResult
 */

/**
 * Settings stored as JSON in the customization's metafield. Both are empty by
 * default, so checkout stays unchanged until the merchant configures them.
 */
const DEFAULT_CONFIG = {
  // Current name → name shown at checkout, matched case-insensitively.
  renames: /** @type {Record<string, string>} */ ({}),
  // Names in the order they should appear; unlisted methods keep their place after them.
  order: /** @type {string[]} */ ([]),
};

/**
 * @param {CartPaymentMethodsTransformRunInput} input
 * @returns {CartPaymentMethodsTransformRunResult}
 */
export function cartPaymentMethodsTransformRun(input) {
  const config = { ...DEFAULT_CONFIG, ...input.paymentCustomization?.metafield?.jsonValue };
  const renames = new Map(Object.entries(config.renames).map(([from, to]) => [from.toLowerCase(), to]));
  /** @param {string} name */
  const findMethod = (name) =>
    input.paymentMethods.find((method) => method.name.toLowerCase() === name.toLowerCase());

  // Rename operations refer to the method's ID, so they're independent of the order below.
  const renameOperations = input.paymentMethods
    .filter((method) => renames.has(method.name.toLowerCase()))
    .map((method) => ({
      paymentMethodRename: { paymentMethodId: method.id, name: renames.get(method.name.toLowerCase()) ?? method.name },
    }));

  // Index counts only methods present in this checkout, so a configured method
  // that isn't offered (another market, an inactive gateway) leaves no gap.
  const moveOperations = config.order
    .map(findMethod)
    .filter((method) => method != null)
    .map((method, index) => ({ paymentMethodMove: { paymentMethodId: method.id, index } }));

  return { operations: [...renameOperations, ...moveOperations] };
}