@base44/app-plugin-commerce 0.1.0

package/base44/functions/commerce/payment-webhook/entry.ts

@@ -0,0 +1,135 @@
+/**
+ * commerce/payment-webhook — the payment provider's server-to-server callback.
+ *
+ * The second of the two confirmation paths (the first is the customer returning
+ * to the storefront, which calls `commerce/payments` `verify`). This one covers
+ * the buyer who pays and closes the tab. Both are idempotent, so whichever
+ * arrives second does nothing.
+ *
+ * Unlike every other function here this takes the provider's **raw body** rather
+ * than an `{action, ...}` envelope, because the signature is computed over those
+ * exact bytes.
+ *
+ * **Trust model — the payload is never believed on its own.** Two paths:
+ *
+ * 1. **A signing secret is configured** (`PAYMENT_WEBHOOK_SECRET`, or
+ *    `STRIPE_WEBHOOK_SECRET`): the signature is verified here and the event's
+ *    "paid" is then trusted directly — one fewer round trip.
+ * 2. **No secret available** — which is the case on Base44, where a function's
+ *    environment is fixed (`BASE44_APP_ID`, `STRIPE_PUBLISHABLE_KEY`,
+ *    `STRIPE_SECRET_KEY`) and apps cannot add their own: the body is treated as
+ *    nothing more than a *nudge naming an order*. Whether money arrived is then
+ *    asked of the provider directly, over our own authenticated API call.
+ *
+ * Either way the event must carry a matching `order_key`, and any session it
+ * names is checked to have been opened for that order — so a real payment for
+ * one order can't be pointed at another, and a forged webhook achieves nothing
+ * beyond making us re-check an order.
+ *
+ * So this endpoint is useful with or without a secret, and safe either way.
+ *
+ * Setup: register this function's URL with the provider (Stripe: events
+ * `checkout.session.completed`, `payment_intent.succeeded`). On the hosted Base44
+ * platform, also configure the app's Stripe webhook secret in the app settings —
+ * verified behavior: a request carrying a `stripe-signature` header is rejected
+ * by the platform *before* any function runs unless that is set.
+ *
+ * Provider specifics (signature scheme, event shapes) live in
+ * shared/commerce/payments.ts and its adapter — nothing here is Stripe-only.
+ */
+import { createClientFromRequest } from "npm:@base44/sdk";
+import { getSettings } from "../../../shared/commerce/settings.ts";
+import {
+  confirmOnlinePayment,
+  parsePaymentWebhook,
+  verifyPaymentWebhook,
+} from "../../../shared/commerce/payments.ts";
+
+/** Providers retry on non-2xx; answer 200 for anything we deliberately ignore. */
+const ok = (data: unknown, status = 200) => Response.json({ success: true, data }, { status });
+const fail = (status: number, error: string, code: string) =>
+  Response.json({ success: false, error, code }, { status });
+
+function webhookSecret(): string {
+  try {
+    return String(
+      Deno.env.get("PAYMENT_WEBHOOK_SECRET") ?? Deno.env.get("STRIPE_WEBHOOK_SECRET") ?? "",
+    );
+  } catch {
+    return ""; // no env access → unsigned path (the payload is not trusted)
+  }
+}
+
+Deno.serve(async (req: Request) => {
+  try {
+    const payload = await req.text();
+    const header = req.headers.get("stripe-signature") ?? req.headers.get("x-payment-signature") ?? "";
+    const secret = webhookSecret();
+
+    // With a secret we can prove the event came from the provider and take its
+    // word. Without one we accept the request but believe nothing in it — the
+    // payment is confirmed against the provider below.
+    let signatureVerified = false;
+    if (secret) {
+      signatureVerified = await verifyPaymentWebhook({ payload, header, secret });
+      if (!signatureVerified) return fail(400, "Invalid webhook signature.", "invalid_signature");
+    }
+
+    let body: any;
+    try {
+      body = JSON.parse(payload);
+    } catch {
+      return fail(400, "Malformed webhook body.", "invalid_body");
+    }
+    const event = parsePaymentWebhook(body);
+    if (!event.order_id) return ok({ ignored: true, type: event.type, reason: "no_order_reference" });
+    // An unsigned event claiming "paid" proves nothing, but it is still worth
+    // re-checking the order it names; a signed one that doesn't claim paid isn't.
+    if (signatureVerified && !event.paid) {
+      return ok({ ignored: true, type: event.type, reason: "not_a_payment_success" });
+    }
+
+    const base44 = createClientFromRequest(req);
+    const sr = base44.asServiceRole;
+
+    let order: any = null;
+    try { order = await sr.entities["commerce.Order"].get(event.order_id); } catch { order = null; }
+    // Required, not merely checked when offered: every session we open carries one.
+    if (!order || !event.order_key || order.order_key !== event.order_key) {
+      console.error(`commerce/payment-webhook: no matching order for ${event.order_id}`);
+      return ok({ ignored: true, reason: "order_not_found" });
+    }
+
+    const settings = await getSettings(sr);
+    let result;
+    try {
+      result = await confirmOnlinePayment(sr, order, {
+        sessionId: event.session_id,
+        paymentReference: event.payment_reference,
+        // Only a verified signature justifies skipping the provider round trip.
+        trustedPaid: signatureVerified,
+        settings,
+        actor: "payment-webhook",
+      });
+    } catch (e) {
+      // Forged or misrouted: answer 200 so the provider stops retrying.
+      if ((e as any)?.code === "session_order_mismatch") {
+        console.error(`commerce/payment-webhook: session ${event.session_id} is not for order ${order.id}`);
+        return ok({ ignored: true, reason: "session_order_mismatch" });
+      }
+      throw e;
+    }
+
+    return ok({
+      order_id: order.id,
+      paid: result.paid,
+      already_confirmed: result.already_confirmed,
+      status: result.order.status,
+      verified_signature: signatureVerified,
+    });
+  } catch (e) {
+    // 500 makes the provider retry, which is what we want for a transient failure.
+    console.error("commerce/payment-webhook error:", e);
+    return fail(500, (e as Error)?.message ?? "Internal error", "internal_error");
+  }
+});

package/base44/functions/commerce/payments/entry.ts

@@ -0,0 +1,238 @@
+/**
+ * commerce/payments — online payment for an order, provider-neutral.
+ *
+ * All provider specifics live in shared/commerce/payments.ts (currently wired to
+ * the Stripe adapter); this function is the API the storefront and the admin use.
+ *
+ * Actions:
+ *   status       — is an online payment provider connected? (admin)
+ *   create-link  — hosted payment page for an unpaid order: the storefront's
+ *                  redirect target and the admin's "payment link" (admin, or the
+ *                  customer holding the order_key). Works whatever the order's
+ *                  current payment method is — asking for a link is the decision
+ *                  to collect online, so the order is switched onto the online
+ *                  gateway (noted in the order log). Refused only when the store
+ *                  has online payment switched off.
+ *   complete-return — the `/order-received` flow in one call: confirm the payment,
+ *                  progress the order, and return the render-ready result plus a
+ *                  fresh payment link while unpaid. This is what the storefront's
+ *                  payment return page calls.
+ *   verify       — confirm payment after the customer returns from the provider,
+ *                  or re-check on demand (same access rules). Idempotent.
+ *
+ * Access: `order_id` + `order_key` authorizes the customer who owns the order
+ * (the same bearer rule as commerce/storefront-account); an admin may act on any
+ * order without a key. Entity access is service-role throughout.
+ * Authorization is not confirmation: a `session_id` passed to verify/
+ * complete-return must be one the provider opened for this order
+ * (409 `session_order_mismatch`).
+ */
+import { createClientFromRequest } from "npm:@base44/sdk";
+import { HttpError, getCallerUser, isAdmin } from "../../../shared/commerce/auth.ts";
+import { getSettings } from "../../../shared/commerce/settings.ts";
+import { serializeOrderForCustomer } from "../../../shared/commerce/orders.ts";
+import {
+  ACTIVE_PROVIDER,
+  confirmOnlinePayment,
+  isOnlineGateway,
+  isOrderPaid,
+  onlinePaymentStatus,
+  orderMeta,
+  paymentReturnState,
+  resolveReturnUrls,
+  SESSION_META_KEY,
+  startOnlinePayment,
+} from "../../../shared/commerce/payments.ts";
+
+function ok(data: unknown, status = 200): Response {
+  return Response.json({ success: true, data }, { status });
+}
+
+function fail(e: unknown): Response {
+  if (e instanceof HttpError) {
+    return Response.json(
+      { success: false, error: e.message, code: e.code ?? "error", ...(e.details ?? {}) },
+      { status: e.status },
+    );
+  }
+  console.error("commerce/payments error:", e);
+  return Response.json(
+    { success: false, error: (e as Error)?.message ?? "Internal error", code: "internal_error" },
+    { status: 500 },
+  );
+}
+
+Deno.serve(async (req: Request) => {
+  try {
+    const base44 = createClientFromRequest(req);
+    const sr = base44.asServiceRole;
+    const user = await getCallerUser(base44);
+    const admin = isAdmin(user);
+    const { action, ...payload } = await req.json();
+
+    switch (action) {
+      case "status": {
+        if (!admin) throw new HttpError(403, "Admin access required.", "forbidden");
+        return ok(await onlinePaymentStatus(sr));
+      }
+
+      case "create-link": {
+        const order = await authorizeOrder(sr, payload, admin);
+        if (isOrderPaid(order)) throw new HttpError(409, "This order is already paid.", "already_paid");
+
+        // Asking for a payment link *is* the decision to collect this order
+        // online, so it works whatever the order's current method is — an admin
+        // order starts with none at all, and switching from a manual method is a
+        // normal thing to want ("just send them a card link"). The one hard
+        // requirement is that the store offers online payment: an operator who
+        // turned the card gateway off has declined it, and this must respect that.
+        const gateway = await onlineGateway(sr);
+        if (!gateway || gateway.enabled === false) {
+          throw new HttpError(
+            400,
+            "Online payment is switched off for this store.",
+            "online_payments_disabled",
+            { gateway_slug: ACTIVE_PROVIDER.gatewaySlug },
+          );
+        }
+        // Record the switch, or the order would claim it's cash-on-delivery while
+        // the customer pays by card — and refunds key off `payment_method`.
+        if (!isOnlineGateway(order.payment_method)) {
+          const previous = order.payment_method_title || order.payment_method || "none";
+          await sr.entities["commerce.Order"].update(order.id, {
+            payment_method: gateway.slug,
+            payment_method_title: gateway.title ?? gateway.slug,
+          });
+          order.payment_method = gateway.slug;
+          order.payment_method_title = gateway.title ?? gateway.slug;
+          await sr.entities["commerce.OrderNote"].create({
+            order_id: order.id,
+            note: `Payment method set to ${order.payment_method_title} (was ${previous}) to send a payment link.`,
+            is_customer_note: false,
+            added_by: admin ? (user?.email ?? "admin") : "customer",
+          });
+        }
+
+        const settings = await getSettings(sr, "general");
+        const { successUrl, cancelUrl } = resolveReturnUrls({
+          order,
+          req,
+          successUrl: payload.success_url,
+          cancelUrl: payload.cancel_url,
+          returnUrl: payload.return_url,
+          storeUrl: settings.general?.store_url,
+          returnPath: settings.general?.order_received_path,
+        });
+        const link = await startOnlinePayment(sr, order, {
+          successUrl,
+          cancelUrl,
+          customerEmail: order.billing?.email || undefined,
+        });
+        return ok(link, 201);
+      }
+
+      /**
+       * The whole payment-return flow in one call, for the `/order-received`
+       * page a storefront has to implement: confirm with the provider, move the
+       * order on if the money landed, and hand back everything the page needs to
+       * render — including a fresh payment link when it is still unpaid, so
+       * "Pay now" needs no second round trip.
+       *
+       * Pass the query parameters the customer came back with. `payment` is only
+       * a hint: a confirmed payment always wins over it, so a hand-edited
+       * `?payment=success` cannot make this say paid.
+       */
+      case "complete-return": {
+        const order = await authorizeOrder(sr, payload, admin);
+        const settings = await getSettings(sr);
+        const result = await confirmOnlinePayment(sr, order, {
+          sessionId: payload.session_id || orderMeta(order, SESSION_META_KEY),
+          settings,
+          actor: admin ? (user?.email ?? "admin") : "customer-return",
+        });
+        const state = paymentReturnState({ paid: result.paid, outcome: payload.payment });
+
+        // Offer a way to pay again while unpaid — best-effort: an unavailable
+        // provider or a store that switched card payment off must not break the
+        // page, it just means no "Pay now" button.
+        let paymentLink: { url: string; session_id: string } | null = null;
+        if (state !== "paid" && payload.with_payment_link !== false && isOnlineGateway(result.order.payment_method)) {
+          try {
+            const { successUrl, cancelUrl } = resolveReturnUrls({
+              order: result.order,
+              req,
+              successUrl: payload.success_url,
+              cancelUrl: payload.cancel_url,
+              returnUrl: payload.return_url,
+              storeUrl: settings.general?.store_url,
+              returnPath: settings.general?.order_received_path,
+            });
+            const link = await startOnlinePayment(sr, result.order, {
+              successUrl,
+              cancelUrl,
+              customerEmail: result.order.billing?.email || undefined,
+            });
+            paymentLink = { url: link.url, session_id: link.session_id };
+          } catch (e) {
+            console.error("complete-return: could not mint a payment link:", e);
+          }
+        }
+
+        return ok({
+          state,                                   // paid | cancelled | unpaid
+          paid: result.paid,
+          already_confirmed: result.already_confirmed,
+          status: result.order.status,
+          order: admin ? result.order : serializeOrderForCustomer(result.order),
+          payment_link: paymentLink,
+        });
+      }
+
+      case "verify": {
+        const order = await authorizeOrder(sr, payload, admin);
+        const settings = await getSettings(sr);
+        const result = await confirmOnlinePayment(sr, order, {
+          sessionId: payload.session_id || orderMeta(order, SESSION_META_KEY),
+          settings,
+          actor: admin ? (user?.email ?? "admin") : "customer-return",
+        });
+        return ok({
+          paid: result.paid,
+          already_confirmed: result.already_confirmed,
+          status: result.order.status,
+          order: admin ? result.order : serializeOrderForCustomer(result.order),
+        });
+      }
+
+      default:
+        throw new HttpError(400, `Unknown action: ${action}`, "unknown_action");
+    }
+  } catch (e) {
+    return fail(e);
+  }
+});
+
+/** The `commerce.PaymentGateway` record backing online payment, if any. */
+async function onlineGateway(sr: any): Promise<any | null> {
+  const hits = (await sr.entities["commerce.PaymentGateway"].filter(
+    { slug: ACTIVE_PROVIDER.gatewaySlug },
+    undefined,
+    1,
+  )) ?? [];
+  return hits[0] ?? null;
+}
+
+/** order_key bearer, or an admin acting on any order. */
+async function authorizeOrder(sr: any, payload: any, admin: boolean): Promise<any> {
+  const orderId = String(payload?.order_id ?? "");
+  if (!orderId) throw new HttpError(400, "order_id is required.", "invalid_payload");
+  let order: any = null;
+  try { order = await sr.entities["commerce.Order"].get(orderId); } catch { order = null; }
+  if (!order) throw new HttpError(404, "Order not found.", "order_not_found");
+  if (admin) return order;
+
+  const key = String(payload?.order_key ?? "");
+  if (!key) throw new HttpError(400, "order_key is required.", "order_key_required");
+  if (order.order_key !== key) throw new HttpError(404, "Order not found.", "order_not_found");
+  return order;
+}

package/base44/functions/commerce/seed-store/defaults.ts

@@ -0,0 +1,162 @@
+/**
+ * commerce/seed-store default data: settings groups, payment gateways, tax classes and
+ * the fallback shipping zone. All idempotent — the seeder checks for existing
+ * records (by group_id / slug / name) before creating.
+ */
+
+/** Per-type email config keys. reset_password/new_account are handled by Base44 auth. */
+const EMAIL_TYPE_DEFAULTS: Record<string, any> = {
+  new_order: { enabled: true, subject: "", heading: "", recipient: "" },
+  cancelled_order: { enabled: true, subject: "", heading: "", recipient: "" },
+  failed_order: { enabled: true, subject: "", heading: "", recipient: "" },
+  on_hold_order: { enabled: true, subject: "", heading: "" },
+  processing_order: { enabled: true, subject: "", heading: "" },
+  completed_order: { enabled: true, subject: "", heading: "" },
+  refunded_order: { enabled: true, subject: "", heading: "" },
+  partial_refund: { enabled: true, subject: "", heading: "" },
+  customer_invoice: { enabled: true, subject: "", heading: "" },
+  customer_note: { enabled: true, subject: "", heading: "" },
+  reset_password: { enabled: true, managed_by: "base44_auth" },
+  new_account: { enabled: true, managed_by: "base44_auth" },
+};
+
+export const SETTINGS_DEFAULTS: Array<{ group_id: string; values: Record<string, any> }> = [
+  {
+    group_id: "general",
+    values: {
+      store_name: "",   // seed-store payload supplies it (the app/store name)
+      // Public URL of the shopfront (e.g. https://shop.example.com). Used to
+      // build the page a customer returns to after paying; when empty the
+      // origin of the calling app is used instead.
+      store_url: "",
+      // Storefront route customers return to after paying; a mismatch is a 404.
+      order_received_path: "/order-received",
+      address: { address_1: "", address_2: "", city: "", state: "", postcode: "", country: "US" },
+      enable_taxes: true,
+      enable_coupons: true,
+      calc_discounts_sequentially: false,
+      currency: "USD",
+      currency_position: "left",         // left | right | left_space | right_space
+      thousand_sep: ",",
+      decimal_sep: ".",
+      num_decimals: 2,
+    },
+  },
+  {
+    group_id: "products",
+    values: {
+      weight_unit: "kg",                 // kg | g | lbs | oz
+      dimension_unit: "cm",              // m | cm | mm | in | yd
+      enable_reviews: true,
+      only_verified_reviews: false,
+      review_rating_required: true,
+      auto_approve_reviews: false,
+    },
+  },
+  {
+    group_id: "inventory",
+    values: {
+      manage_stock: true,
+      hold_stock_minutes: 60,
+      notify_low_stock: true,
+      notify_out_of_stock: true,
+      notification_recipient: "",
+      low_stock_threshold: 2,
+      out_of_stock_threshold: 0,
+      hide_out_of_stock: false,
+    },
+  },
+  {
+    group_id: "tax",
+    values: {
+      prices_include_tax: false,
+      tax_based_on: "shipping",          // shipping | billing | base
+      shipping_tax_class: "inherit",     // inherit | standard | <class slug>
+      display_prices_shop: "excl",       // incl | excl
+      display_prices_cart: "excl",
+    },
+  },
+  {
+    group_id: "shipping",
+    values: {
+      enable_shipping: true,
+    },
+  },
+  {
+    group_id: "emails",
+    values: {
+      from_name: "",   // blank: emails.ts inherits general.store_name
+      admin_recipients: [],
+      ...EMAIL_TYPE_DEFAULTS,
+    },
+  },
+];
+
+export const GATEWAY_DEFAULTS = [
+  {
+    slug: "bacs",
+    title: "Direct bank transfer",
+    description: "Make your payment directly into our bank account. Please use your Order ID as the payment reference.",
+    enabled: true,
+    order: 0,
+    method_title: "Direct bank transfer",
+    method_description: "Take payments in person via BACS. Orders are set on-hold until payment clears.",
+    settings: { account_details: [] as any[] },
+  },
+  {
+    slug: "cheque",
+    title: "Check payments",
+    description: "Please send a check to our store address.",
+    enabled: false,
+    order: 1,
+    method_title: "Check payments",
+    method_description: "Take payments by check. Orders are set on-hold until payment clears.",
+    settings: {},
+  },
+  {
+    slug: "cod",
+    title: "Cash on delivery",
+    description: "Pay with cash upon delivery.",
+    enabled: true,
+    order: 2,
+    method_title: "Cash on delivery",
+    method_description: "Have your customers pay with cash (or by other means) upon delivery.",
+    settings: { enable_for_methods: [] as string[], enable_for_virtual: false },
+  },
+  {
+    slug: "stripe",
+    title: "Credit card",
+    description: "Pay securely by credit card.",
+    // Enabled by default: online payment is how a store should take money. It is
+    // only *offered* to customers while a payment provider is connected — the
+    // storefront gateway list and the admin both check that live — so enabling it
+    // here cannot strand a shopper on an unusable option.
+    enabled: true,
+    order: 3,
+    method_title: "Online card payments",
+    method_description:
+      "Card payments through the connected payment provider (Stripe out of the box). Connect the provider's connector to start taking payments; customers only see this option once it is connected.",
+    settings: { connector: "stripe" },
+  },
+];
+
+export const TAX_CLASS_DEFAULTS = [
+  { slug: "standard", name: "Standard" },
+  { slug: "reduced-rate", name: "Reduced rate" },
+  { slug: "zero-rate", name: "Zero rate" },
+];
+
+export const REST_OF_WORLD_ZONE = {
+  name: "Rest of the world",
+  order: 999,
+  locations: [] as any[],
+};
+
+/** Example method attached to the fallback zone so admins see the pattern. */
+export const REST_OF_WORLD_EXAMPLE_METHOD = {
+  method_id: "flat_rate",
+  title: "Flat rate",
+  enabled: true,
+  order: 0,
+  settings: { cost: 0, tax_status: "taxable", class_costs: [], no_class_cost: 0, calculation_type: "class" },
+};