@alexkroman1/aai-cli 5.3.0 → 5.5.0

package/dist/templates/retail/tools/cancel_pending_order.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { creditRefund, REFUND_DELAY_NOTE, REFUND_IMMEDIATE_NOTE } from "../refund.ts";
+import { resolveOrder } from "../resolve.ts";
+import { authenticatedUser, getState, isError, retailTool, setFocus } from "../store.ts";
+
+/** tau2 accepts exactly these two. Anything else is refused. */
+const CANCEL_REASONS = ["no longer needed", "ordered by mistake"] as const;
+
+export const cancelPendingOrder = retailTool({
+  name: "cancel_pending_order",
+  description:
+    "Cancel a pending order. Only an order whose status is exactly 'pending' can be cancelled — " +
+    "check the status first. The reason must be either 'no longer needed' or 'ordered by mistake'. " +
+    "State the order, its total and the refund destination to the caller and get an explicit yes " +
+    "before calling this.",
+  inputSchema: z.object({
+    order_id: z
+      .string()
+      .max(120)
+      .describe("Order id such as '#W0000000', or a spoken reference to one of their orders"),
+    reason: z
+      .enum(CANCEL_REASONS)
+      .describe("Either 'no longer needed' or 'ordered by mistake' — no other reason is accepted"),
+  }),
+  // `execute` before `summary`: TS infers the wrapper's generic `R` from
+  // `execute`'s return type, and processes object literal properties in
+  // source order — with `summary` first, `result` in its signature can't be
+  // inferred and silently falls back to `unknown`.
+  execute: (args, ctx) => {
+    const state = getState(ctx);
+    const user = authenticatedUser(state);
+    if (isError(user)) return user;
+
+    const order = resolveOrder(state, args.order_id);
+    if (isError(order)) return order;
+    setFocus(state, { orderId: order.order_id });
+
+    if (order.status !== "pending") {
+      return {
+        error: `Order ${order.order_id} is ${order.status}, and only a pending order can be cancelled.`,
+      };
+    }
+    // The enum makes this unreachable from a well-formed call; it stays because
+    // the reason is the one field a caller supplies in free speech.
+    if (!CANCEL_REASONS.includes(args.reason)) {
+      return {
+        error: `'${args.reason}' is not an accepted cancellation reason. It must be 'no longer needed' or 'ordered by mistake'.`,
+      };
+    }
+
+    let immediate = false;
+    const refunds = order.payment_history
+      .filter((payment) => payment.transaction_type === "payment")
+      .map((payment) => {
+        const credited = creditRefund(user, payment.payment_method_id, payment.amount);
+        immediate = immediate || credited.immediate;
+        return {
+          transaction_type: "refund" as const,
+          amount: payment.amount,
+          payment_method_id: payment.payment_method_id,
+        };
+      });
+
+    order.status = "cancelled";
+    order.cancel_reason = args.reason;
+    order.payment_history.push(...refunds);
+
+    const total = refunds.reduce((sum, refund) => sum + refund.amount, 0);
+    return {
+      order_id: order.order_id,
+      status: order.status,
+      cancel_reason: order.cancel_reason,
+      refunded: total,
+      refund_immediate: immediate,
+      message: `Order ${order.order_id} is cancelled and $${total.toFixed(2)} is being refunded. ${
+        immediate ? REFUND_IMMEDIATE_NOTE : REFUND_DELAY_NOTE
+      }`,
+    };
+  },
+  summary: (_args, result) =>
+    "error" in result ? "cancel failed" : `cancelled ${result.order_id}`,
+});

package/dist/templates/retail/tools/exchange_delivered_order_items.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { resolveOrder } from "../resolve.ts";
+import { authenticatedUser, getState, isError, retailTool, setFocus } from "../store.ts";
+import { assertCanCoverDiff, planItemSwap } from "../swap.ts";
+
+export const exchangeDeliveredOrderItems = retailTool({
+  name: "exchange_delivered_order_items",
+  description:
+    "Request an exchange of items in a delivered order for different options of the SAME products. " +
+    "Only a 'delivered' order can be exchanged, and only once. Remind the caller to name EVERY " +
+    "item they want exchanged before you call this, read the whole list and the price difference " +
+    "back, and get an explicit yes. No new order is needed — the customer gets an email explaining " +
+    "how to send the originals back.",
+  inputSchema: z.object({
+    order_id: z
+      .string()
+      .max(120)
+      .describe("Order id such as '#W0000000', or a spoken reference to one of their orders"),
+    item_ids: z
+      .array(z.string().max(60))
+      .max(20)
+      .describe("Item ids to exchange. May repeat if the order holds duplicates"),
+    new_item_ids: z
+      .array(z.string().max(60))
+      .max(20)
+      .describe("Replacement item ids, each matching the item in the same position"),
+    payment_method_id: z
+      .string()
+      .max(80)
+      .describe("Method to charge or refund the price difference"),
+  }),
+  // `execute` before `summary`: TS infers the wrapper's generic `R` from
+  // `execute`'s return type, and processes object literal properties in
+  // source order — with `summary` first, `result` in its signature can't be
+  // inferred and silently falls back to `unknown`.
+  execute: (args, ctx) => {
+    const state = getState(ctx);
+    const user = authenticatedUser(state);
+    if (isError(user)) return user;
+
+    const order = resolveOrder(state, args.order_id);
+    if (isError(order)) return order;
+    setFocus(state, { orderId: order.order_id });
+
+    if (order.status !== "delivered") {
+      return {
+        error: `Order ${order.order_id} is ${order.status}. Only a delivered order can be exchanged, and only once.`,
+      };
+    }
+
+    // requireDifferent is false: tau2 permits a same-item entry here, and a
+    // zero-difference exchange is harmless on a delivered order.
+    const plan = planItemSwap(state, order, args.item_ids, args.new_item_ids, {
+      requireDifferent: false,
+    });
+    if (isError(plan)) return plan;
+
+    const blocked = assertCanCoverDiff(user, args.payment_method_id, plan.diff);
+    if (blocked) return blocked;
+
+    // No balance moves and no items change: this records a REQUEST. The money
+    // and the item swap settle when the originals come back.
+    order.status = "exchange requested";
+    order.exchange_items = [...args.item_ids].sort();
+    order.exchange_new_items = [...args.new_item_ids].sort();
+    order.exchange_payment_method_id = args.payment_method_id;
+    order.exchange_price_difference = plan.diff;
+
+    return {
+      order_id: order.order_id,
+      status: order.status,
+      price_difference: plan.diff,
+      exchange_items: order.exchange_items,
+      exchange_new_items: order.exchange_new_items,
+      message:
+        plan.diff > 0
+          ? `Exchange requested on ${order.order_id}. $${plan.diff.toFixed(2)} will be charged to ${args.payment_method_id}. An email with return instructions is on its way.`
+          : `Exchange requested on ${order.order_id}. $${Math.abs(plan.diff).toFixed(2)} will be refunded to ${args.payment_method_id}. An email with return instructions is on its way.`,
+    };
+  },
+  summary: (_args, result) =>
+    "error" in result ? "exchange failed" : `exchange requested on ${result.order_id}`,
+});

package/dist/templates/retail/tools/find_user_id_by_email.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { authenticateAs } from "../authenticate.ts";
+import { getState, retailTool } from "../store.ts";
+
+export const findUserIdByEmail = retailTool({
+  name: "find_user_id_by_email",
+  description:
+    "Find a customer's user id by their email address. This is how you authenticate the caller — " +
+    "do it before anything else, even if they volunteer their user id. Prefer this over " +
+    "find_user_id_by_name_zip unless they cannot remember the email.",
+  inputSchema: z.object({
+    email: z.string().max(200).describe("The customer's email, e.g. 'something@example.com'"),
+  }),
+  requiresAuth: false,
+  // `execute` must come before `summary` in this object literal: TS infers the
+  // wrapper's generic `R` from `execute`'s return type, and processes object
+  // literal properties in source order — with `summary` first, `result` in its
+  // signature can't be inferred and silently falls back to `unknown`.
+  execute: (args, ctx) => {
+    const state = getState(ctx);
+    const target = args.email.trim().toLowerCase();
+    const match = Object.values(state.store.users).find(
+      (user) => user.email.toLowerCase() === target,
+    );
+    if (!match) {
+      return { error: `No customer found with email ${args.email}.` };
+    }
+    return authenticateAs(state, match);
+  },
+  summary: (_args, result) =>
+    "error" in result ? "lookup failed" : `identified ${result.user_id}`,
+});

package/dist/templates/retail/tools/find_user_id_by_name_zip.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { authenticateAs } from "../authenticate.ts";
+import { getState, retailTool } from "../store.ts";
+
+export const findUserIdByNameZip = retailTool({
+  name: "find_user_id_by_name_zip",
+  description:
+    "Find a customer's user id by first name, last name and zip code. Use this only when the " +
+    "caller cannot remember the email address on the account.",
+  inputSchema: z.object({
+    first_name: z.string().max(100).describe("First name, e.g. 'John'"),
+    last_name: z.string().max(100).describe("Last name, e.g. 'Doe'"),
+    zip: z.string().max(20).describe("Zip code, e.g. '12345'"),
+  }),
+  requiresAuth: false,
+  // `execute` before `summary`: see find_user_id_by_email.ts for why the order
+  // is load-bearing for the generic `result` type in `summary`.
+  execute: (args, ctx) => {
+    const state = getState(ctx);
+    const first = args.first_name.trim().toLowerCase();
+    const last = args.last_name.trim().toLowerCase();
+    const zip = args.zip.replace(/\D/g, "");
+    const match = Object.values(state.store.users).find(
+      (user) =>
+        user.name.first_name.toLowerCase() === first &&
+        user.name.last_name.toLowerCase() === last &&
+        user.address.zip === zip,
+    );
+    if (!match) {
+      return {
+        error: `No customer found for ${args.first_name} ${args.last_name} at zip ${args.zip}.`,
+      };
+    }
+    return authenticateAs(state, match);
+  },
+  summary: (_args, result) =>
+    "error" in result ? "lookup failed" : `identified ${result.user_id}`,
+});

package/dist/templates/retail/tools/get_item_details.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { findItem, getState, isError, retailTool } from "../store.ts";
+
+export const getItemDetails = retailTool({
+  name: "get_item_details",
+  description:
+    "Get one specific item's options, price and availability. Takes an ITEM id, which is not the " +
+    "same as a product id.",
+  inputSchema: z.object({
+    item_id: z.string().max(60).describe("The item id, e.g. '1008292230'"),
+  }),
+  requiresAuth: false,
+  // `execute` before `summary`: see find_user_id_by_email.ts for why the order
+  // is load-bearing for the generic `result` type in `summary`.
+  execute: (args, ctx) => {
+    const found = findItem(getState(ctx), args.item_id);
+    if (isError(found)) return found;
+    return {
+      item_id: found.variant.item_id,
+      product_id: found.product.product_id,
+      product_name: found.product.name,
+      options: found.variant.options,
+      price: found.variant.price,
+      available: found.variant.available,
+    };
+  },
+  summary: (_args, result) =>
+    "error" in result ? "item read failed" : `read item ${result.item_id}`,
+});

package/dist/templates/retail/tools/get_order_details.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { resolveOrder } from "../resolve.ts";
+import { getState, isError, retailTool, setFocus } from "../store.ts";
+
+export const getOrderDetails = retailTool({
+  name: "get_order_details",
+  description:
+    "Get the status and full details of one of the authenticated customer's orders. Accepts the " +
+    "order id (e.g. '#W0000000' — note the leading '#'), or a spoken reference such as " +
+    "'my pending order', 'the delivered one', or 'the second pending order'.",
+  inputSchema: z.object({
+    order_id: z
+      .string()
+      .max(120)
+      .describe("Order id such as '#W0000000', or a spoken reference to one of their orders"),
+  }),
+  // `execute` before `summary`: see find_user_id_by_email.ts for why the order
+  // is load-bearing for the generic `result` type in `summary`.
+  execute: (args, ctx) => {
+    const state = getState(ctx);
+    const order = resolveOrder(state, args.order_id);
+    if (isError(order)) return order;
+    setFocus(state, { orderId: order.order_id });
+    return {
+      order_id: order.order_id,
+      status: order.status,
+      address: order.address,
+      items: order.items.map((item) => ({
+        name: item.name,
+        product_id: item.product_id,
+        item_id: item.item_id,
+        price: item.price,
+        options: item.options,
+      })),
+      payment_history: order.payment_history,
+      ...(order.fulfillments ? { fulfillments: order.fulfillments } : {}),
+      ...(order.cancel_reason ? { cancel_reason: order.cancel_reason } : {}),
+    };
+  },
+  summary: (_args, result) => ("error" in result ? "order read failed" : `read ${result.order_id}`),
+});

package/dist/templates/retail/tools/get_product_details.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { findProduct, getState, isError, retailTool, setFocus } from "../store.ts";
+
+export const getProductDetails = retailTool({
+  name: "get_product_details",
+  description:
+    "Get a product's variants — each with its item id, options, price and availability. Takes a " +
+    "PRODUCT id, which is not the same as an item id. Use list_all_product_types to find one.",
+  inputSchema: z.object({
+    product_id: z.string().max(60).describe("The product id, e.g. '6086499569'"),
+  }),
+  requiresAuth: false,
+  // `execute` before `summary`: see find_user_id_by_email.ts for why the order
+  // is load-bearing for the generic `result` type in `summary`.
+  execute: (args, ctx) => {
+    const state = getState(ctx);
+    const product = findProduct(state, args.product_id);
+    if (isError(product)) return product;
+    setFocus(state, { productId: product.product_id });
+    return {
+      name: product.name,
+      product_id: product.product_id,
+      variants: Object.values(product.variants).map((variant) => ({
+        item_id: variant.item_id,
+        options: variant.options,
+        price: variant.price,
+        available: variant.available,
+      })),
+    };
+  },
+  summary: (_args, result) =>
+    "error" in result ? "product read failed" : `read product ${result.name}`,
+});

package/dist/templates/retail/tools/get_user_details.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { authenticatedUser, getState, isError, retailTool } from "../store.ts";
+
+export const getUserDetails = retailTool({
+  name: "get_user_details",
+  description:
+    "Get the authenticated customer's profile: name, email, default address, payment methods " +
+    "(with gift-card balances) and their order ids with each order's status.",
+  inputSchema: z.object({
+    user_id: z.string().max(100).describe("The user id, e.g. 'sara_doe_496'"),
+  }),
+  // `execute` before `summary`: see find_user_id_by_email.ts for why the order
+  // is load-bearing for the generic `result` type in `summary`.
+  execute: (args, ctx) => {
+    const state = getState(ctx);
+    const user = authenticatedUser(state);
+    if (isError(user)) return user;
+    if (user.user_id !== args.user_id) {
+      return {
+        error: `${args.user_id} is not the customer on this call. You can help only one customer per conversation.`,
+      };
+    }
+    return {
+      user_id: user.user_id,
+      name: `${user.name.first_name} ${user.name.last_name}`,
+      email: user.email,
+      address: user.address,
+      payment_methods: Object.values(user.payment_methods).map((method) => ({
+        payment_method_id: method.id,
+        source: method.source,
+        ...(method.source === "gift_card" ? { balance: method.balance } : {}),
+        ...(method.source === "credit_card"
+          ? { brand: method.brand, last_four: method.last_four }
+          : {}),
+      })),
+      orders: user.orders.map((id) => ({
+        order_id: id,
+        status: state.store.orders[id]?.status ?? "unknown",
+      })),
+    };
+  },
+  summary: (_args, result) =>
+    "error" in result ? "profile read failed" : `read profile ${result.user_id}`,
+});

package/dist/templates/retail/tools/list_all_product_types.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { getState, retailTool } from "../store.ts";
+
+export const listAllProductTypes = retailTool({
+  name: "list_all_product_types",
+  description:
+    "List every product type the store carries, as a name-to-product-id map. Each product type " +
+    "has variant items with their own item ids and options.",
+  // Empty schema rather than omitting it: the wrapper has one code path, and
+  // that is where the per-call UI-update invariant lives.
+  inputSchema: z.object({}),
+  requiresAuth: false,
+  // `execute` before `summary`: see find_user_id_by_email.ts for why the order
+  // is load-bearing for the generic `result` type in `summary`.
+  execute: (_args, ctx) => {
+    const state = getState(ctx);
+    const entries = Object.values(state.store.products)
+      .map((product) => [product.name, product.product_id] as const)
+      .sort(([a], [b]) => a.localeCompare(b));
+    return { count: entries.length, products: Object.fromEntries(entries) };
+  },
+  summary: (_args, result) =>
+    "error" in result ? "catalog read failed" : `listed ${result.count} product types`,
+});

package/dist/templates/retail/tools/modify_pending_order_address.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { AddressFields, formatAddress, toAddress } from "../address.ts";
+import { resolveOrder } from "../resolve.ts";
+import { getState, isError, retailTool, setFocus } from "../store.ts";
+
+export const modifyPendingOrderAddress = retailTool({
+  name: "modify_pending_order_address",
+  description:
+    "Change the shipping address of a pending order. Read the new address back to the caller and " +
+    "get an explicit yes before calling this. This does not change the customer's default address.",
+  inputSchema: z.object({
+    order_id: z
+      .string()
+      .max(120)
+      .describe("Order id such as '#W0000000', or a spoken reference to one of their orders"),
+    ...AddressFields,
+  }),
+  // `execute` before `summary`: TS infers the wrapper's generic `R` from
+  // `execute`'s return type, and processes object literal properties in
+  // source order — with `summary` first, `result` in its signature can't be
+  // inferred and silently falls back to `unknown`.
+  execute: (args, ctx) => {
+    const state = getState(ctx);
+    const order = resolveOrder(state, args.order_id);
+    if (isError(order)) return order;
+    setFocus(state, { orderId: order.order_id });
+
+    // Any pending variant is fine here — unlike cancel and modify-items, which
+    // require exactly 'pending'. Re-addressing a modified order is harmless.
+    if (!order.status.startsWith("pending")) {
+      return {
+        error: `Order ${order.order_id} is ${order.status}, and only a pending order's address can be changed.`,
+      };
+    }
+
+    order.address = toAddress(args);
+    return {
+      order_id: order.order_id,
+      status: order.status,
+      address: order.address,
+      message: `Order ${order.order_id} now ships to ${formatAddress(order.address)}.`,
+    };
+  },
+  summary: (_args, result) =>
+    "error" in result ? "address change failed" : `re-addressed ${result.order_id}`,
+});

package/dist/templates/retail/tools/modify_pending_order_items.ts

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { resolveOrder } from "../resolve.ts";
+import {
+  authenticatedUser,
+  getState,
+  isError,
+  isGiftCard,
+  money,
+  retailTool,
+  setFocus,
+} from "../store.ts";
+import { applySwap, assertCanCoverDiff, planItemSwap } from "../swap.ts";
+
+export const modifyPendingOrderItems = retailTool({
+  name: "modify_pending_order_items",
+  description:
+    "Change items in a pending order to different options of the SAME products. This can be done " +
+    "ONCE per order and is irreversible — afterwards the order can no longer be cancelled or " +
+    "modified at all. Collect EVERY item the caller wants changed into one call, read the whole " +
+    "list and the price difference back, and get an explicit yes first. The item and replacement " +
+    "lists are positional and must be the same length.",
+  inputSchema: z.object({
+    order_id: z
+      .string()
+      .max(120)
+      .describe("Order id such as '#W0000000', or a spoken reference to one of their orders"),
+    item_ids: z
+      .array(z.string().max(60))
+      .max(20)
+      .describe("Item ids to change. May repeat if the order holds duplicates"),
+    new_item_ids: z
+      .array(z.string().max(60))
+      .max(20)
+      .describe("Replacement item ids, each matching the item in the same position"),
+    payment_method_id: z
+      .string()
+      .max(80)
+      .describe("Method to charge or refund the price difference, e.g. 'gift_card_0000000'"),
+  }),
+  // `execute` before `summary`: TS infers the wrapper's generic `R` from
+  // `execute`'s return type, and processes object literal properties in
+  // source order — with `summary` first, `result` in its signature can't be
+  // inferred and silently falls back to `unknown`.
+  execute: (args, ctx) => {
+    const state = getState(ctx);
+    const user = authenticatedUser(state);
+    if (isError(user)) return user;
+
+    const order = resolveOrder(state, args.order_id);
+    if (isError(order)) return order;
+    setFocus(state, { orderId: order.order_id });
+
+    // Exactly 'pending'. A 'pending (item modified)' order has already used its
+    // one modification, which is what makes this action terminal.
+    if (order.status !== "pending") {
+      return {
+        error: `Order ${order.order_id} is ${order.status}. Items can only be changed while an order is exactly 'pending', and only once.`,
+      };
+    }
+
+    const plan = planItemSwap(state, order, args.item_ids, args.new_item_ids, {
+      requireDifferent: true,
+    });
+    if (isError(plan)) return plan;
+
+    const blocked = assertCanCoverDiff(user, args.payment_method_id, plan.diff);
+    if (blocked) return blocked;
+
+    const method = user.payment_methods[args.payment_method_id];
+    if (method && isGiftCard(method)) {
+      method.balance = money(method.balance - plan.diff);
+    }
+    order.payment_history.push({
+      transaction_type: plan.diff > 0 ? "payment" : "refund",
+      amount: money(Math.abs(plan.diff)),
+      payment_method_id: args.payment_method_id,
+    });
+
+    applySwap(order, plan);
+    order.status = "pending (item modified)";
+
+    return {
+      order_id: order.order_id,
+      status: order.status,
+      price_difference: plan.diff,
+      items: order.items.map((item) => ({
+        name: item.name,
+        item_id: item.item_id,
+        options: item.options,
+        price: item.price,
+      })),
+      message:
+        plan.diff > 0
+          ? `Done. $${plan.diff.toFixed(2)} was charged to ${args.payment_method_id}. This order can no longer be modified or cancelled.`
+          : `Done. $${Math.abs(plan.diff).toFixed(2)} is being refunded to ${args.payment_method_id}. This order can no longer be modified or cancelled.`,
+    };
+  },
+  summary: (_args, result) =>
+    "error" in result
+      ? "item change failed"
+      : `modified ${result.order_id} (${result.price_difference >= 0 ? "+" : ""}${result.price_difference})`,
+});

package/dist/templates/retail/tools/modify_pending_order_payment.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { resolveOrder } from "../resolve.ts";
+import {
+  authenticatedUser,
+  findPaymentMethod,
+  getState,
+  isError,
+  isGiftCard,
+  money,
+  retailTool,
+  setFocus,
+} from "../store.ts";
+
+export const modifyPendingOrderPayment = retailTool({
+  name: "modify_pending_order_payment",
+  description:
+    "Change which payment method a pending order is charged to. The new method must be different " +
+    "from the current one, and a gift card must hold enough to cover the whole order. The original " +
+    "method is refunded. Read the change back and get an explicit yes before calling this.",
+  inputSchema: z.object({
+    order_id: z
+      .string()
+      .max(120)
+      .describe("Order id such as '#W0000000', or a spoken reference to one of their orders"),
+    payment_method_id: z
+      .string()
+      .max(80)
+      .describe("The new payment method id, e.g. 'gift_card_0000000'"),
+  }),
+  // `execute` before `summary`: TS infers the wrapper's generic `R` from
+  // `execute`'s return type, and processes object literal properties in
+  // source order — with `summary` first, `result` in its signature can't be
+  // inferred and silently falls back to `unknown`.
+  execute: (args, ctx) => {
+    const state = getState(ctx);
+    const user = authenticatedUser(state);
+    if (isError(user)) return user;
+
+    const order = resolveOrder(state, args.order_id);
+    if (isError(order)) return order;
+    setFocus(state, { orderId: order.order_id });
+
+    if (!order.status.startsWith("pending")) {
+      return {
+        error: `Order ${order.order_id} is ${order.status}, and only a pending order's payment method can be changed.`,
+      };
+    }
+
+    const newMethod = findPaymentMethod(user, args.payment_method_id);
+    if (isError(newMethod)) return newMethod;
+
+    const original = order.payment_history[0];
+    if (order.payment_history.length !== 1 || original?.transaction_type !== "payment") {
+      return {
+        error: `Order ${order.order_id} does not have exactly one payment on record, so its payment method cannot be changed.`,
+      };
+    }
+    if (original.payment_method_id === args.payment_method_id) {
+      return {
+        error: `Order ${order.order_id} is already paid with ${args.payment_method_id}. The new method must be different.`,
+      };
+    }
+
+    const amount = original.amount;
+    if (isGiftCard(newMethod) && newMethod.balance < amount) {
+      return {
+        error: `Gift card ${args.payment_method_id}'s balance ($${newMethod.balance.toFixed(2)}) does not cover the $${amount.toFixed(2)} order total.`,
+      };
+    }
+
+    order.payment_history.push(
+      {
+        transaction_type: "payment",
+        amount,
+        payment_method_id: args.payment_method_id,
+      },
+      {
+        transaction_type: "refund",
+        amount,
+        payment_method_id: original.payment_method_id,
+      },
+    );
+
+    if (isGiftCard(newMethod)) {
+      newMethod.balance = money(newMethod.balance - amount);
+    }
+    const oldMethod = user.payment_methods[original.payment_method_id];
+    if (oldMethod && isGiftCard(oldMethod)) {
+      oldMethod.balance = money(oldMethod.balance + amount);
+    }
+
+    return {
+      order_id: order.order_id,
+      status: order.status,
+      amount,
+      paid_with: args.payment_method_id,
+      refunded_to: original.payment_method_id,
+      message: `Order ${order.order_id} is now charged to ${args.payment_method_id}, and $${amount.toFixed(2)} is going back to ${original.payment_method_id}.`,
+    };
+  },
+  summary: (_args, result) =>
+    "error" in result ? "payment change failed" : `re-paid ${result.order_id}`,
+});