@base44/app-plugin-commerce 0.1.5 → 0.1.7

package/base44/functions/commerce/storefront-cart/entry.ts

@@ -8,6 +8,10 @@
  *          apply-coupon | remove-coupon | set-shipping-address |
  *          choose-shipping-method | totals
  * Every mutating action returns the fresh priced cart view.
+ *
+ * `add-item` is self-healing: a missing/unknown/expired cart_token starts a
+ * fresh cart instead of failing, so storefronts must persist the cart_token
+ * from every response rather than assuming the one they sent survived.
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
 import { HttpError, getCallerUser } from "../../../shared/commerce/auth.ts";
@@ -141,7 +145,26 @@ Deno.serve(async (req: Request) => {
       }
 
       case "add-item": {
-        const cart = await loadCart(sr, payload.cart_token);
+        // A missing, stale or expired token must not strand the shopper: start a
+        // fresh cart and add the item to it. The response carries the new
+        // cart_token — storefronts must always persist the token from the
+        // response, not assume the one they sent survived.
+        let cart: any;
+        try {
+          cart = await loadCart(sr, payload.cart_token);
+        } catch (e) {
+          const code = (e as any)?.code;
+          if (!["cart_token_required", "cart_not_found", "cart_expired"].includes(code)) throw e;
+          cart = await sr.entities["commerce.Cart"].create({
+            cart_token: uuid(),
+            customer_email: user?.email ?? "",
+            items: [],
+            coupon_codes: [],
+            status: "active",
+            expires_at: cartExpiry(),
+          });
+          if (user) await mergeUserCarts(sr, cart, user);
+        }
         await addItem(sr, cart, payload);
         return ok((await priceCart(sr, cart, { customerEmail: user?.email })).view);
       }
@@ -214,7 +237,18 @@ Deno.serve(async (req: Request) => {
         };
         if (!address.country) throw new HttpError(400, "address.country is required.", "country_required");
         await touch(sr, cart, { shipping_address: address });
-        return ok((await priceCart(sr, cart, { customerEmail: user?.email })).view);
+        const priced = await priceCart(sr, cart, { customerEmail: user?.email });
+        // Fail loudly the moment an unsupported address is validated — a quiet
+        // `none_available` view is how a checkout dead-ends later at place-order.
+        if (priced.view.shipping_status === "none_available") {
+          throw new HttpError(
+            400,
+            "This store does not ship to this address.",
+            "shipping_not_available",
+            { shipping_address: address, cart: priced.view },
+          );
+        }
+        return ok(priced.view);
       }
 
       case "choose-shipping-method": {

package/base44/functions/commerce/storefront-catalog/entry.ts

@@ -1,17 +1,16 @@
 /**
  * commerce/storefront-catalog — public catalog browsing API.
  *
- * Actions: list-products | get-product | list-categories | list-tags |
+ * Actions: list-products | get-product | list-categories | list-ribbons |
  *          list-attributes | get-store-info | submit-review
  *
- * Visibility rules: only status=publish products; browse context hides
- * catalog_visibility hidden/search; search context hides hidden/catalog;
- * inventory.hide_out_of_stock removes out-of-stock products entirely.
+ * Visibility rules: only status=publish products (the admin's single Visible
+ * toggle); inventory.hide_out_of_stock removes out-of-stock products entirely.
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
-import { getCallerUser, HttpError, requireUser } from "../../../shared/commerce/auth.ts";
+import { getCallerUser, HttpError } from "../../../shared/commerce/auth.ts";
 import { getSettings, getSetting, storefrontSafeSettings } from "../../../shared/commerce/settings.ts";
-import { isOnlineGateway, onlinePaymentStatus } from "../../../shared/commerce/payments.ts";
+import { isCardGateway } from "../../../shared/commerce/payments.ts";
 import { isVariable } from "../../../shared/commerce/products.ts";
 import { recalcProductRating } from "../../../shared/commerce/reviews.ts";
 import { scanAll } from "../../../shared/commerce/scan.ts";
@@ -47,8 +46,8 @@ Deno.serve(async (req: Request) => {
         return ok(await getProduct(sr, payload));
       case "list-categories":
         return ok(await listCategories(sr));
-      case "list-tags":
-        return ok(await listTags(sr, payload));
+      case "list-ribbons":
+        return ok(await listRibbons(sr, payload));
       case "list-attributes":
         return ok(await listAttributes(sr));
       case "get-store-info":
@@ -105,15 +104,6 @@ async function listProducts(sr: any, p: any): Promise<any> {
 
   let products = await scanAll(sr.entities["commerce.Product"], { status: "publish" }, "-created_date", 5000);
 
-  // visibility per context
-  products = products.filter((prod: any) => {
-    const vis = prod.catalog_visibility ?? "visible";
-    if (vis === "hidden") return false;
-    if (isSearchContext && vis === "catalog") return false;
-    if (!isSearchContext && vis === "search") return false;
-    return true;
-  });
-
   if (hideOutOfStock || p.in_stock_only) {
     products = products.filter((prod: any) => prod.stock_status !== "outofstock");
   }
@@ -127,8 +117,8 @@ async function listProducts(sr: any, p: any): Promise<any> {
     const catIds = await categoryWithDescendants(sr, String(p.category_id));
     products = products.filter((prod: any) => (prod.category_ids || []).some((c: string) => catIds.has(c)));
   }
-  if (p.tag_id) {
-    products = products.filter((prod: any) => (prod.tag_ids || []).includes(String(p.tag_id)));
+  if (p.ribbon_id) {
+    products = products.filter((prod: any) => (prod.ribbon_ids || []).includes(String(p.ribbon_id)));
   }
   if (p.attribute_id && p.attribute_term) {
     products = products.filter((prod: any) =>
@@ -147,7 +137,7 @@ async function listProducts(sr: any, p: any): Promise<any> {
   products.sort(SORTS[sortKey] ?? SORTS["-created_date"]);
 
   const start = (page - 1) * perPage;
-  const pageItems = await withTags(sr, products.slice(start, start + perPage).map(publicProduct));
+  const pageItems = await withRibbons(sr, products.slice(start, start + perPage).map(publicProduct));
   return {
     products: pageItems,
     page,
@@ -157,18 +147,19 @@ async function listProducts(sr: any, p: any): Promise<any> {
 }
 
 /**
- * Attach resolved `tags` to listing rows. A row otherwise carries only tag_ids,
- * which is why cards end up with no tags at all — the shape a card needs has to
- * be in the row it renders. One tag read per request, not per row; kept to
- * {id, name} so a listing payload stays small (use list-tags for counts).
+ * Attach resolved `ribbons` to listing rows. A row otherwise carries only
+ * ribbon_ids, which is why cards end up with no ribbons at all — the shape a
+ * card needs has to be in the row it renders. One ribbon read per request, not
+ * per row; kept to {id, name} so a listing payload stays small (use
+ * list-ribbons for counts).
  */
-async function withTags(sr: any, rows: any[]): Promise<any[]> {
-  if (!rows.some((r) => (r.tag_ids ?? []).length)) return rows;
-  const all = await scanAll(sr.entities["commerce.ProductTag"], {}, "name", 2000);
+async function withRibbons(sr: any, rows: any[]): Promise<any[]> {
+  if (!rows.some((r) => (r.ribbon_ids ?? []).length)) return rows;
+  const all = await scanAll(sr.entities["commerce.ProductRibbon"], {}, "name", 2000);
   const byId = new Map(all.map((t: any) => [t.id, { id: t.id, name: t.name }]));
   return rows.map((r) => ({
     ...r,
-    tags: (r.tag_ids ?? []).map((id: string) => byId.get(id)).filter(Boolean),
+    ribbons: (r.ribbon_ids ?? []).map((id: string) => byId.get(id)).filter(Boolean),
   }));
 }
 
@@ -199,16 +190,16 @@ async function getProduct(sr: any, p: any): Promise<any> {
   } else if (p.slug) {
     product = (await sr.entities["commerce.Product"].filter({ slug: String(p.slug) }, undefined, 1))?.[0] ?? null;
   }
-  if (!product || product.status !== "publish" || product.catalog_visibility === "hidden") {
+  if (!product || product.status !== "publish") {
     throw new HttpError(404, "Product not found.", "not_found");
   }
 
-  const [variations, categories, tags] = await Promise.all([
+  const [variations, categories, ribbons] = await Promise.all([
     isVariable(product)
       ? sr.entities["commerce.ProductVariation"].filter({ product_id: product.id }, "menu_order", 500)
       : Promise.resolve([]),
     resolveMany(sr.entities["commerce.ProductCategory"], product.category_ids),
-    resolveMany(sr.entities["commerce.ProductTag"], product.tag_ids),
+    resolveMany(sr.entities["commerce.ProductRibbon"], product.ribbon_ids),
   ]);
 
   const purchasableVariations = (variations ?? []).filter(
@@ -233,7 +224,7 @@ async function getProduct(sr: any, p: any): Promise<any> {
     product: publicProduct(product),
     variations: purchasableVariations.map(publicProduct),
     categories,
-    tags,
+    ribbons,
     reviews: {
       items: reviews.slice(0, reviewsPerPage).map(publicReview),
       page: reviewsPage,
@@ -313,41 +304,37 @@ async function listCategories(sr: any): Promise<any> {
 }
 
 /**
- * Tags for a tag cloud / "shop by tag" nav. Entities are admin-only, so a
- * storefront has no other way to enumerate them — and list-products `tag_id` is
- * useless without the ids.
+ * Ribbons for cards / a "shop by ribbon" nav. Entities are admin-only, so a
+ * storefront has no other way to enumerate them — and list-products `ribbon_id`
+ * is useless without the ids.
  *
  * `count` is tallied from the products this API would actually list, NOT from
- * ProductTag.count: that field counts drafts and hidden products too, and drifts
- * until admin-tools recount-terms runs — either way a nav built on it can show
- * "Gift (7)" that lists nothing, or hide a tag that has stock.
+ * ProductRibbon.count: that field counts drafts too, and drifts until
+ * admin-tools recount-terms runs — either way a nav built on it can show
+ * "Gift (7)" that lists nothing, or hide a ribbon that has stock.
  * `with_products_only` (default true) then drops the empty ones.
  */
-async function listTags(sr: any, p: any): Promise<any> {
+async function listRibbons(sr: any, p: any): Promise<any> {
   const settings = await getSettings(sr, "inventory");
   const hideOutOfStock = !!getSetting(settings, "inventory", "hide_out_of_stock", false);
 
   const products = (await scanAll(sr.entities["commerce.Product"], { status: "publish" }, undefined, 5000))
-    .filter((prod: any) => {
-      const vis = prod.catalog_visibility ?? "visible";
-      if (vis === "hidden" || vis === "search") return false;   // browse context
-      return !(hideOutOfStock && prod.stock_status === "outofstock");
-    });
+    .filter((prod: any) => !(hideOutOfStock && prod.stock_status === "outofstock"));
 
   const counts = new Map<string, number>();
   for (const prod of products) {
-    for (const id of prod.tag_ids ?? []) counts.set(id, (counts.get(id) ?? 0) + 1);
+    for (const id of prod.ribbon_ids ?? []) counts.set(id, (counts.get(id) ?? 0) + 1);
   }
 
-  const all = await scanAll(sr.entities["commerce.ProductTag"], {}, "name", 2000);
-  const tags = all
+  const all = await scanAll(sr.entities["commerce.ProductRibbon"], {}, "name", 2000);
+  const ribbons = all
     .map((t: any) => ({
       id: t.id,
       name: t.name,
       count: counts.get(t.id) ?? 0,
     }))
     .filter((t: any) => p?.with_products_only === false || t.count > 0);
-  return { tags };
+  return { ribbons };
 }
 
 async function listAttributes(sr: any): Promise<any> {
@@ -365,18 +352,16 @@ async function listAttributes(sr: any): Promise<any> {
 async function getStoreInfo(sr: any): Promise<any> {
   const settings = await getSettings(sr);
   const gateways = (await sr.entities["commerce.PaymentGateway"].filter({ enabled: true }, "order", 50)) ?? [];
-  // An online gateway is only offerable while its provider is actually
-  // connected — otherwise the customer would pick "Card" and pay nothing. This
-  // is a live check, never a stored flag.
-  const online = await onlinePaymentStatus(sr);
-  const offerable = gateways.filter((g: any) => !isOnlineGateway(g.slug) || online.connected);
+  // Every enabled gateway is returned — the admin's Payments settings are the
+  // single switch. `online: true` marks the card option (place-order answers
+  // with a payment page to redirect to); everything else settles manually.
   return {
     settings: storefrontSafeSettings(settings),
-    payment_gateways: offerable.map((g: any) => ({
+    payment_gateways: gateways.map((g: any) => ({
       slug: g.slug,
       title: g.title ?? g.slug,
       description: g.description ?? "",
-      online: isOnlineGateway(g.slug),
+      online: isCardGateway(g.slug),
     })),
     countries: COUNTRIES,
     currencies: CURRENCIES,
@@ -385,13 +370,16 @@ async function getStoreInfo(sr: any): Promise<any> {
 
 // ── reviews ──────────────────────────────────────────────────────────────────
 
-/** Signed-in only: the reviewer's email is the session's, never the payload's. */
+/**
+ * Public by design: anyone can review with an email address — no login. A
+ * signed-in session supplies the email (and can't spoof another); a guest
+ * passes `email` in the payload. Stricter policies (login-gated forms,
+ * verified-buyers-only, required ratings) are the storefront's to enforce in
+ * its UI — see .agents/skills/commerce/references/reviews.md. The one server switch is
+ * auto-approval; everything else submits as `hold` for moderation.
+ */
 async function submitReview(sr: any, p: any, user: any): Promise<any> {
-  requireUser(user);
   const settings = await getSettings(sr, "products");
-  if (!getSetting(settings, "products", "enable_reviews", true)) {
-    throw new HttpError(403, "Reviews are disabled for this store.", "reviews_disabled");
-  }
 
   const productId = String(p.product_id || "");
   let product: any = null;
@@ -399,28 +387,23 @@ async function submitReview(sr: any, p: any, user: any): Promise<any> {
   if (!product || product.status !== "publish") {
     throw new HttpError(404, "Product not found.", "not_found");
   }
-  const reviewerEmail = String(user.email ?? "").trim().toLowerCase();
-  if (!reviewerEmail) {
-    throw new HttpError(403, "Your account has no email address to review under.", "forbidden");
+  // Session email wins — a signed-in caller can never review as someone else.
+  const reviewerEmail = String(user?.email ?? p.email ?? "").trim().toLowerCase();
+  if (!reviewerEmail || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(reviewerEmail)) {
+    throw new HttpError(400, "A valid email address is required to review.", "email_required");
   }
-  const reviewer = String(p.reviewer ?? user.full_name ?? "").trim();
+  const reviewer = String(p.reviewer ?? user?.full_name ?? "").trim() || reviewerEmail.split("@")[0];
   const review = String(p.review ?? "").trim();
   const rating = p.rating == null ? null : Math.floor(Number(p.rating));
 
-  if (!reviewer || !review) {
-    throw new HttpError(400, "reviewer and review are required.", "review_incomplete");
-  }
-  if (getSetting(settings, "products", "review_rating_required", true) && (rating == null || rating < 1)) {
-    throw new HttpError(400, "A star rating is required.", "rating_required");
+  if (!review) {
+    throw new HttpError(400, "review is required.", "review_incomplete");
   }
   if (rating != null && (rating < 0 || rating > 5)) {
     throw new HttpError(400, "Rating must be between 0 and 5.", "invalid_rating");
   }
 
   const verified = await hasPurchased(sr, reviewerEmail, product.id);
-  if (getSetting(settings, "products", "only_verified_reviews", false) && !verified) {
-    throw new HttpError(403, "Only customers who purchased this product can review it.", "verified_only");
-  }
 
   const autoApprove = !!getSetting(settings, "products", "auto_approve_reviews", false);
   const created = await sr.entities["commerce.ProductReview"].create({

package/base44/functions/commerce/storefront-checkout/cart-pricing.ts

@@ -36,20 +36,16 @@ export async function loadCart(sr: any, cartToken: string | undefined): Promise<
 
 export interface PricingData {
   settings: Record<string, any>;
-  taxRates: any[];
-  zones: any[];
-  zoneMethods: any[];
+  locations: any[];
 }
 
 /** One round of catalog-config reads shared by every priced response. */
 export async function loadPricingData(sr: any): Promise<PricingData> {
-  const [settings, taxRates, zones, zoneMethods] = await Promise.all([
+  const [settings, locations] = await Promise.all([
     getSettings(sr),
-    scanAll(sr.entities["commerce.TaxRate"], {}, "menu_order", 2000),
-    scanAll(sr.entities["commerce.ShippingZone"], {}, "order", 500),
-    scanAll(sr.entities["commerce.ShippingZoneMethod"], {}, "order", 1000),
+    scanAll(sr.entities["commerce.ShippingTaxLocation"], {}, "order", 500),
   ]);
-  return { settings, taxRates, zones, zoneMethods };
+  return { settings, locations };
 }
 
 export interface ResolvedItem {
@@ -179,9 +175,7 @@ export async function priceCart(sr: any, cart: any, opts: { pricingData?: Pricin
     shipping_address: cart.shipping_address,
     chosenShippingMethodId: chosenShippingMethodId || undefined,
     settings,
-    taxRates: pricingData.taxRates,
-    zones: pricingData.zones,
-    zoneMethods: pricingData.zoneMethods,
+    locations: pricingData.locations,
   });
 
   let totals = priceWith(cart.chosen_shipping_method);
@@ -196,6 +190,7 @@ export async function priceCart(sr: any, cart: any, opts: { pricingData?: Pricin
     shippingEnabled: getSetting(settings, "shipping", "enable_shipping", true) !== false,
     chosenMethodId: cart.chosen_shipping_method,
     available: totals.available_shipping_methods,
+    hasAddress: !!cart.shipping_address?.country,
   });
   if (shippingSelection.method_id !== (cart.chosen_shipping_method || "")) {
     cart.chosen_shipping_method = shippingSelection.method_id;

package/base44/functions/commerce/storefront-checkout/entry.ts

@@ -20,13 +20,11 @@ import { checkPurchasable, releaseExpiredHolds } from "../../../shared/commerce/
 import { transitionOrder, serializeOrderForCustomer } from "../../../shared/commerce/orders.ts";
 import { resolveShippingSelection } from "../../../shared/commerce/shipping.ts";
 import {
-  confirmOnlinePayment,
-  isOnlineGateway,
+  confirmCardPayment,
+  isCardGateway,
   isOrderPaid,
-  orderMeta,
   resolveReturnUrls,
-  SESSION_META_KEY,
-  startOnlinePayment,
+  startCardPayment,
 } from "../../../shared/commerce/payments.ts";
 import { generateOrderKey, nextOrderNumber } from "../../../shared/commerce/sequence.ts";
 import { round2 } from "../../../shared/commerce/money.ts";
@@ -154,9 +152,7 @@ async function placeOrder(sr: any, req: Request, user: any, payload: any): Promi
     shipping_address: shippingAddress,
     chosenShippingMethodId: chosenShippingMethodId || undefined,
     settings,
-    taxRates: pricingData.taxRates,
-    zones: pricingData.zones,
-    zoneMethods: pricingData.zoneMethods,
+    locations: pricingData.locations,
   });
 
   // The method may be named on this call (`chosen_shipping_method`) or carried on
@@ -224,7 +220,7 @@ async function placeOrder(sr: any, req: Request, user: any, payload: any): Promi
   // (4) customer upsert by billing email
   const notices: string[] = [];
   if (payload.create_account && !user) {
-    notices.push("account_creation_requires_login"); // see skills/commerce/references/guest-access-security.md
+    notices.push("account_creation_requires_login"); // see .agents/skills/commerce/references/guest-access-security.md
   }
   const customer = await upsertCustomer(sr, billing, shippingAddress, user);
 
@@ -275,50 +271,42 @@ async function placeOrder(sr: any, req: Request, user: any, payload: any): Promi
   // (7) cart consumed
   try { await sr.entities["commerce.Cart"].update(cart.id, { status: "converted" }); } catch { /* best-effort */ }
 
-  // (9) gateway routing
+  // (9) gateway routing: the card gateway sends the customer to the provider's
+  // payment page; every other gateway is manual — the money settles outside the
+  // store, so the order goes on-hold with the gateway's instructions and the
+  // merchant moves it on once paid.
   let paymentInstructions: any = null;
   let payment: any = null;
-  switch (gateway.slug) {
-    // Settled outside the store, so no money has arrived yet: on-hold, and the
-    // merchant moves it on once it has.
-    case "offline":
-      await transitionOrder(sr, order, "on-hold", { settings });
-      paymentInstructions = {
-        type: "offline",
-        description: gateway.description ?? "Pay outside the store. Your order is confirmed once we receive payment.",
-        account_details: gateway.settings?.account_details ?? [],
-      };
-      break;
-    default:
-      if (isOnlineGateway(gateway.slug)) {
-        // Online payment: the order stays `pending` and the customer is sent to
-        // the provider's hosted page. Confirmation comes back through
-        // commerce/payments `verify` (return) and commerce/payment-webhook.
-        const { successUrl, cancelUrl } = resolveReturnUrls({
-          order,
-          req,
-          successUrl: payload.success_url,
-          cancelUrl: payload.cancel_url,
-          returnUrl: payload.return_url,
-          returnPath: settings.general?.order_received_path,
-        });
-        const link = await startOnlinePayment(sr, order, {
-          successUrl,
-          cancelUrl,
-          customerEmail: billing.email,
-        });
-        payment = {
-          status: "requires_payment",
-          provider: link.provider,
-          checkout_url: link.url,
-          session_id: link.session_id,
-          note: "Send the customer to checkout_url; the order stays pending until the payment is confirmed.",
-        };
-      } else {
-        // custom gateway added by the store: leave pending for external wiring
-        payment = { status: "pending_external", note: `Gateway "${gateway.slug}" requires custom wiring.` };
-      }
-      break;
+  if (isCardGateway(gateway.slug)) {
+    // The order stays `pending` while the customer pays. Confirmation comes
+    // back through commerce/payments `complete-return`/`verify` (customer
+    // return) and commerce/payment-webhook.
+    const { successUrl, cancelUrl } = resolveReturnUrls({
+      order,
+      req,
+      successUrl: payload.success_url,
+      cancelUrl: payload.cancel_url,
+      returnUrl: payload.return_url,
+      returnPath: settings.general?.order_received_path,
+    });
+    const link = await startCardPayment(sr, order, {
+      successUrl,
+      cancelUrl,
+      customerEmail: billing.email,
+    });
+    payment = {
+      status: "requires_payment",
+      checkout_url: link.url,
+      reference: link.reference,
+      note: "Send the customer to checkout_url; the order stays pending until the payment is confirmed.",
+    };
+  } else {
+    await transitionOrder(sr, order, "on-hold", { settings });
+    paymentInstructions = {
+      type: gateway.slug === "offline" ? "offline" : "manual",
+      description: gateway.description ?? "Pay outside the store. Your order is confirmed once we receive payment.",
+      account_details: gateway.settings?.account_details ?? [],
+    };
   }
 
   // update customer aggregates for paid statuses
@@ -359,17 +347,16 @@ async function confirmPayment(sr: any, payload: any): Promise<any> {
   if (!["pending", "on-hold"].includes(order.status)) {
     throw new HttpError(409, `Order is ${order.status} and cannot be confirmed.`, "invalid_status");
   }
-  if (!isOnlineGateway(order.payment_method)) {
+  if (!isCardGateway(order.payment_method)) {
     throw new HttpError(
       400,
-      "This order is not paid through the online payment provider, so its payment cannot be confirmed here. Settle it from the admin.",
-      "not_an_online_payment",
+      "This order is not paid by card, so its payment cannot be confirmed here. Settle it from the admin.",
+      "not_a_card_payment",
     );
   }
 
   const settings = await getSettings(sr);
-  const result = await confirmOnlinePayment(sr, order, {
-    sessionId: payload.session_id || orderMeta(order, SESSION_META_KEY),
+  const result = await confirmCardPayment(sr, order, {
     settings,
     actor: "customer-return",
   });

package/base44/shared/commerce/card-payment.ts

@@ -0,0 +1,80 @@
+/**
+ * Card payments — file 1 of 2 to implement when wiring a payment provider
+ * (Stripe, PayPal, Adyen, a local PSP…). File 2 is the webhook:
+ * `base44/functions/commerce/payment-webhook/entry.ts`.
+ *
+ * Everything around these three functions is already built: checkout creates
+ * the order, prices it, holds stock and routes the customer to the URL you
+ * return; the webhook and the return page confirm payment idempotently and
+ * move the order to processing (stock, emails, download permissions, webhooks
+ * all fire from there); admin refunds write the refund record and restock.
+ * Implement ONLY the provider calls below — no other file needs to change.
+ *
+ * Until implemented, the Credit Card checkout option answers
+ * 503 `no_card_payment_provider`.
+ *
+ * Credentials belong in backend secrets/env (e.g. Deno.env.get("...")) —
+ * never in an entity and never from the client.
+ */
+import { HttpError } from "./auth.ts";
+
+/** A hosted payment page for one order. */
+export interface CardPaymentPage {
+  /** Where the customer goes to pay. */
+  url: string;
+  /**
+   * The provider's id for this payment (session / intent / transaction id).
+   * Stored on the order; handed back to `checkCardPaymentPaid` and
+   * `refundCardPayment`.
+   */
+  reference: string;
+}
+
+/**
+ * Create a payment page for `order.total` in `order.currency`.
+ *
+ * Send the customer back to `successUrl` / `cancelUrl` after they pay or give
+ * up (both already carry order_id/order_key for the return page). If your
+ * provider supports metadata, attach `order.id` and `order.order_key` so the
+ * webhook can name the order.
+ */
+export async function createCardPayment(
+  _sr: any,
+  _order: any,
+  _opts: { successUrl: string; cancelUrl: string; customerEmail?: string },
+): Promise<CardPaymentPage> {
+  throw new HttpError(
+    503,
+    "Card payments are not available yet — no card payment provider is set up for this store.",
+    "no_card_payment_provider",
+  );
+}
+
+/**
+ * Has the provider actually received the money for this payment? Ask the
+ * provider (`reference` is what `createCardPayment` returned) — never trust
+ * a claim from the client. Called by the customer-return page, the webhook's
+ * unsigned path, and the admin's "Check payment" button.
+ */
+export async function checkCardPaymentPaid(_sr: any, _order: any, _reference: string): Promise<boolean> {
+  return false;
+}
+
+/**
+ * Refund `amount` (display units, e.g. 12.34) of a payment at the provider.
+ * Return the provider's refund id, or throw an HttpError if the provider
+ * refuses. Leave unimplemented to keep refunds manual: the admin then records
+ * refunds locally and returns the money from the provider's own dashboard.
+ */
+export async function refundCardPayment(_sr: any, _order: any, _opts: {
+  reference: string;
+  amount: number;
+  currency: string;
+  reason?: string;
+}): Promise<{ refund_id: string }> {
+  throw new HttpError(
+    501,
+    "Refunding through the payment provider is not implemented — record the refund without `refund_payment` and return the money from the provider's dashboard.",
+    "card_refund_not_implemented",
+  );
+}