@base44/app-plugin-commerce 0.1.0

package/base44/shared/commerce/payments.ts

@@ -0,0 +1,495 @@
+// Deploy marker: 1
+// Bump after connecting a payment provider: env vars are injected at deploy time,
+// and editing this file redeploys every commerce/* function.
+// See skills/commerce/references/online-payments.md §2.
+/**
+ * Online payments — the provider-neutral utility every caller uses.
+ *
+ * Nothing outside this file (and the adapter it points at) knows which payment
+ * provider the store uses. Checkout, the payment-link/verify function, the
+ * webhook and refunds all call the operations below; the admin UI talks about
+ * "an online payment provider", not a brand.
+ *
+ * **The wiring** is one line — `ACTIVE_PROVIDER`. It is bound to the Stripe
+ * adapter (`stripe.ts`), which is fully implemented: hosted payment page,
+ * payment links, return-verification, webhook signature checking and refunds.
+ *
+ * **To use a different provider** (PayPal, Adyen, a local PSP): write an adapter
+ * that satisfies `PaymentAdapter` and point `ACTIVE_PROVIDER` at it. That is the
+ * whole change on the backend — no caller, no UI and no entity needs touching.
+ * See skills/commerce/references/online-payments.md.
+ *
+ * Credentials always come from the host — an injected secret (Base44 puts the
+ * Stripe keys in `STRIPE_SECRET_KEY` / `STRIPE_PUBLISHABLE_KEY` once Stripe is
+ * set up for the app) or a connector — never from the `commerce.PaymentGateway`
+ * entity and never from the client.
+ */
+import { HttpError } from "./auth.ts";
+import { round2 } from "./money.ts";
+import { transitionOrder } from "./orders.ts";
+import * as stripe from "./stripe.ts";
+
+/** A hosted-payment session: the page a customer pays on. */
+export interface PaymentSession {
+  id: string;
+  url: string;
+  /** "paid" once the provider has the money. */
+  paid: boolean;
+  /** Provider's payment/charge id, stored on the order for refunds. */
+  payment_reference: string;
+  expires_at?: number;
+  /** The order this session was opened for, as the provider recorded it. */
+  order_id: string;
+  order_key: string;
+}
+
+export interface PaymentConnection {
+  connected: boolean;
+  error?: string;
+}
+
+/** What a provider implementation has to offer. Keep these signatures. */
+export interface PaymentAdapter {
+  /** Machine id (e.g. "stripe"); also the connector name on hosts that use one. */
+  id: string;
+  /** Human label — the only place a provider brand belongs in the backend. */
+  label: string;
+  /** The `commerce.PaymentGateway` slug this provider backs. */
+  gatewaySlug: string;
+  connection(sr: any): Promise<PaymentConnection>;
+  createSession(sr: any, order: any, opts: {
+    successUrl: string;
+    cancelUrl: string;
+    customerEmail?: string;
+  }): Promise<PaymentSession>;
+  retrieveSession(sr: any, sessionId: string): Promise<PaymentSession>;
+  /**
+   * Invalidate a previously issued payment page, if the provider supports it, so
+   * an old link can't be paid after the order changed. Best-effort.
+   */
+  expireSession?(sr: any, sessionId: string): Promise<boolean>;
+  refund(sr: any, opts: {
+    paymentReference: string;
+    amount: number;
+    currency: string;
+    reason?: string;
+    idempotencyKey?: string;
+  }): Promise<{ id: string; status: string; amount: number }>;
+  /** True when the raw webhook body really came from the provider. */
+  verifyWebhook(opts: { payload: string; header: string; secret: string }): Promise<boolean>;
+  /** Pull the fields the order lifecycle needs out of a webhook body. */
+  parseWebhookEvent(body: any): {
+    type: string;
+    paid: boolean;
+    order_id: string;
+    order_key: string;
+    session_id: string;
+    payment_reference: string;
+  };
+}
+
+// ── the Stripe adapter ───────────────────────────────────────────────────────
+
+function toPaymentSession(session: stripe.CheckoutSession): PaymentSession {
+  return {
+    id: session.id,
+    url: session.url,
+    paid: session.payment_status === "paid",
+    payment_reference: session.payment_intent,
+    expires_at: session.expires_at,
+    order_id: session.order_id,
+    order_key: session.order_key,
+  };
+}
+
+const stripeAdapter: PaymentAdapter = {
+  id: "stripe",
+  label: "Stripe",
+  gatewaySlug: "stripe",
+
+  async connection(sr) {
+    // Verified, not just present: a disconnected or rotated key must stop
+    // reading as connected, or the store advertises card payment it can't take.
+    const check = await stripe.verifyStripeCredential(sr);
+    return { connected: check.ok, error: check.error };
+  },
+
+  async createSession(sr, order, opts) {
+    return toPaymentSession(await stripe.createCheckoutSession(sr, order, opts));
+  },
+
+  async retrieveSession(sr, sessionId) {
+    return toPaymentSession(await stripe.retrieveCheckoutSession(sr, sessionId));
+  },
+
+  expireSession(sr, sessionId) {
+    return stripe.expireCheckoutSession(sr, sessionId);
+  },
+
+  refund(sr, opts) {
+    return stripe.createStripeRefund(sr, {
+      paymentIntentId: opts.paymentReference,
+      amount: opts.amount,
+      currency: opts.currency,
+      reason: opts.reason,
+      idempotencyKey: opts.idempotencyKey,
+    });
+  },
+
+  verifyWebhook(opts) {
+    return stripe.verifyWebhookSignature(opts);
+  },
+
+  parseWebhookEvent(body) {
+    const type = String(body?.type ?? "");
+    const object = body?.data?.object ?? {};
+    const metadata = object.metadata ?? {};
+    const paid = type === "checkout.session.completed"
+      ? object.payment_status === "paid"
+      : type === "payment_intent.succeeded";
+    return {
+      type,
+      paid,
+      order_id: String(metadata.order_id ?? ""),
+      order_key: String(metadata.order_key ?? ""),
+      session_id: type.startsWith("checkout.session") ? String(object.id ?? "") : "",
+      payment_reference: type.startsWith("checkout.session")
+        ? String(typeof object.payment_intent === "string" ? object.payment_intent : object.payment_intent?.id ?? "")
+        : String(object.id ?? ""),
+    };
+  },
+};
+
+/** ← The one line to change when moving to another provider. */
+export const ACTIVE_PROVIDER: PaymentAdapter = stripeAdapter;
+
+// ── order bookkeeping (provider-neutral meta keys) ───────────────────────────
+
+export const SESSION_META_KEY = "_payment_session_id";
+export const REFERENCE_META_KEY = "_payment_reference";
+
+export function orderMeta(order: any, key: string): string {
+  return String((order?.meta_data ?? []).find((m: any) => m?.key === key)?.value ?? "");
+}
+
+/** meta_data with these keys replaced (empty values remove the key). */
+export function withOrderMeta(order: any, entries: Record<string, string>): any[] {
+  const meta = (order?.meta_data ?? []).filter((m: any) => !Object.hasOwn(entries, m?.key));
+  for (const [key, value] of Object.entries(entries)) {
+    if (value) meta.push({ key, value });
+  }
+  return meta;
+}
+
+// ── return URLs ──────────────────────────────────────────────────────────────
+
+/** An absolute http(s) URL — what every provider requires for its return URLs. */
+export function isAbsoluteUrl(value: unknown): boolean {
+  try {
+    const url = new URL(String(value));
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * First candidate that is a usable absolute origin, without a trailing slash.
+ *
+ * Providers reject relative paths ("Not a valid URL"), so the return URLs have
+ * to be built from a real origin. Callers pass their candidates in order of
+ * authority — an explicit `return_url`, the store's configured URL, then the
+ * origin the request came from (the admin or storefront calling this lives on the
+ * app's own host, which is exactly where the customer should land back).
+ */
+export function resolveReturnBase(candidates: Array<unknown>): string {
+  for (const candidate of candidates) {
+    const value = String(candidate ?? "").trim();
+    if (value && isAbsoluteUrl(value)) return value.replace(/\/+$/, "");
+  }
+  return "";
+}
+
+/** The origin of the caller, from the request headers ("" when absent). */
+export function requestOrigin(req: Request): string {
+  const origin = req.headers.get("origin");
+  if (origin && isAbsoluteUrl(origin)) return origin;
+  const referer = req.headers.get("referer");
+  if (referer && isAbsoluteUrl(referer)) {
+    try { return new URL(referer).origin; } catch { /* ignore */ }
+  }
+  return "";
+}
+
+/** Default path of the return page, when the store hasn't said otherwise. */
+export const DEFAULT_RETURN_PATH = "/order-received";
+
+/**
+ * Add the ids the return page needs to verify the payment, keeping existing
+ * query params. Applied to caller-supplied URLs too: without these they can't
+ * confirm anything.
+ */
+export function withReturnParams(url: string, order: any, outcome: "success" | "cancel"): string {
+  const parsed = new URL(url);
+  parsed.searchParams.set("order_id", String(order.id));
+  parsed.searchParams.set("order_key", String(order.order_key ?? ""));
+  parsed.searchParams.set("payment", outcome);
+  return parsed.toString();
+}
+
+/**
+ * Where the customer lands after paying: an origin plus the store's return path
+ * (`settings.general.order_received_path`), which is configuration — a hardcoded
+ * guess sends payers to a 404.
+ */
+export function orderReturnUrl(base: string, order: any, outcome: "success" | "cancel", path?: unknown): string {
+  const origin = String(base).replace(/\/+$/, "");
+  const rawPath = String(path ?? "").trim() || DEFAULT_RETURN_PATH;
+  const withSlash = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
+  return withReturnParams(`${origin}${withSlash}`, order, outcome);
+}
+
+/**
+ * The pair of absolute return URLs for a payment session, or a 400 that says how
+ * to fix it — better than letting the provider answer "Not a valid URL".
+ *
+ * Precedence: `successUrl`/`cancelUrl` per outcome → `returnUrl` (the return
+ * page, both outcomes) → `storeUrl`/request origin + `returnPath`. Every result
+ * carries `order_id`, `order_key` and `payment`.
+ */
+export function resolveReturnUrls(opts: {
+  order: any;
+  req?: Request;
+  successUrl?: unknown;
+  cancelUrl?: unknown;
+  returnUrl?: unknown;
+  storeUrl?: unknown;
+  returnPath?: unknown;
+}): { successUrl: string; cancelUrl: string } {
+  const base = resolveReturnBase([opts.storeUrl, opts.req ? requestOrigin(opts.req) : ""]);
+
+  // A `returnUrl` naming a page is used as-is; a bare origin has no page in it,
+  // so it is treated as a base and gets the store's return path appended.
+  const returnUrlIsPage = isAbsoluteUrl(opts.returnUrl) &&
+    new URL(String(opts.returnUrl)).pathname.replace(/\/+$/, "") !== "";
+  const returnUrlAsBase = isAbsoluteUrl(opts.returnUrl) && !returnUrlIsPage
+    ? String(opts.returnUrl).replace(/\/+$/, "")
+    : "";
+
+  const pick = (specific: unknown, outcome: "success" | "cancel") => {
+    if (isAbsoluteUrl(specific)) return withReturnParams(String(specific), opts.order, outcome);
+    if (returnUrlIsPage) return withReturnParams(String(opts.returnUrl), opts.order, outcome);
+    const origin = returnUrlAsBase || base;
+    return origin ? orderReturnUrl(origin, opts.order, outcome, opts.returnPath) : "";
+  };
+
+  const success = pick(opts.successUrl, "success");
+  const cancel = pick(opts.cancelUrl, "cancel");
+
+  if (!success || !cancel) {
+    throw new HttpError(
+      400,
+      "Can't build the return URLs for the payment page: pass an absolute success_url/cancel_url (or return_url pointing at your return page), or set the store URL in the store's general settings.",
+      "return_url_required",
+      { needs: ["success_url", "cancel_url"], hint: "settings.general.store_url + order_received_path" },
+    );
+  }
+  return { successUrl: success, cancelUrl: cancel };
+}
+
+/**
+ * What a payment-return page should show, decided **server-side** from the
+ * confirmed payment state plus the outcome the provider claims in the URL.
+ *
+ * The URL is only ever a hint (`?payment=success` is editable by anyone), so
+ * `paid` — the answer from the provider — always wins over it.
+ */
+export function paymentReturnState(input: { paid: boolean; outcome?: string }):
+  "paid" | "cancelled" | "unpaid" {
+  if (input.paid) return "paid";
+  return input.outcome === "cancel" ? "cancelled" : "unpaid";
+}
+
+// ── provider-neutral operations ──────────────────────────────────────────────
+
+/** Does this gateway slug mean "pay online with the configured provider"? */
+export function isOnlineGateway(slug: string): boolean {
+  return String(slug || "") === ACTIVE_PROVIDER.gatewaySlug;
+}
+
+/**
+ * Whether the store can actually take an online payment right now.
+ *
+ * A *live fact about the host's payment setup*, never a constant: surface it from
+ * here so a "no payment provider connected" state disappears by itself once the
+ * provider is set up.
+ */
+export async function onlinePaymentStatus(sr: any): Promise<{
+  provider: string;
+  provider_label: string;
+  gateway_slug: string;
+  connected: boolean;
+  error?: string;
+}> {
+  const conn = await ACTIVE_PROVIDER.connection(sr);
+  return {
+    provider: ACTIVE_PROVIDER.id,
+    provider_label: ACTIVE_PROVIDER.label,
+    gateway_slug: ACTIVE_PROVIDER.gatewaySlug,
+    connected: conn.connected,
+    ...(conn.error ? { error: conn.error } : {}),
+  };
+}
+
+/**
+ * Start (or resume) payment for an order: returns the hosted page to send the
+ * customer to. Used by checkout right after the order is created **and** by the
+ * admin to produce a payment link for an unpaid order — same session either way,
+ * so both routes behave identically.
+ *
+ * The session id and payment reference are stored on the order so the return
+ * handler and the webhook can confirm without trusting anything in the URL.
+ */
+export async function startOnlinePayment(sr: any, order: any, opts: {
+  successUrl: string;
+  cancelUrl: string;
+  customerEmail?: string;
+}): Promise<{ provider: string; session_id: string; url: string; expires_at?: number }> {
+  if (isOrderPaid(order)) {
+    throw new HttpError(409, "This order is already paid.", "already_paid");
+  }
+
+  // Retire the previous payment page before minting a new one: after an order is
+  // edited, an older link would otherwise still be payable at the old total.
+  const previousSession = orderMeta(order, SESSION_META_KEY);
+  if (previousSession && ACTIVE_PROVIDER.expireSession) {
+    try {
+      await ACTIVE_PROVIDER.expireSession(sr, previousSession);
+    } catch {
+      // already completed or expired — nothing to do
+    }
+  }
+
+  const session = await ACTIVE_PROVIDER.createSession(sr, order, opts);
+  if (!session.url) {
+    throw new HttpError(502, "The payment provider did not return a payment page.", "payment_session_failed");
+  }
+  await sr.entities["commerce.Order"].update(order.id, {
+    meta_data: withOrderMeta(order, {
+      [SESSION_META_KEY]: session.id,
+      [REFERENCE_META_KEY]: session.payment_reference,
+    }),
+  });
+  return {
+    provider: ACTIVE_PROVIDER.id,
+    session_id: session.id,
+    url: session.url,
+    expires_at: session.expires_at,
+  };
+}
+
+/** Paid enough to stop asking for money? */
+export function isOrderPaid(order: any): boolean {
+  return Boolean(order?.date_paid) || ["processing", "completed", "refunded"].includes(order?.status);
+}
+
+/**
+ * Session ids reach us from places the customer controls (a return URL, a webhook
+ * body), so without this anyone could pay a cheap order of their own and replay
+ * that session against an expensive one — or someone else's.
+ */
+function assertSessionBelongsToOrder(session: PaymentSession, order: any): void {
+  const sameOrder = session.order_id && session.order_id === String(order.id);
+  const sameKey = !session.order_key || session.order_key === String(order.order_key ?? "");
+  if (!sameOrder || !sameKey) {
+    throw new HttpError(
+      409,
+      "That payment belongs to a different order.",
+      "session_order_mismatch",
+    );
+  }
+}
+
+/**
+ * Confirm a payment and move the order on — **idempotent**, so the webhook and
+ * the customer's return can both run in any order and only the first one has an
+ * effect (no double stock reduction, coupon counting or emails).
+ *
+ * Whether money arrived is always asked of the provider; `trustedPaid` (a
+ * signature-verified event) only stands in when there is no session to fetch.
+ *
+ * With no `sessionId`, the session stored on the order is used, which is what a
+ * "check payment status" button in the admin wants.
+ */
+export async function confirmOnlinePayment(sr: any, order: any, opts: {
+  sessionId?: string;
+  paymentReference?: string;
+  settings?: Record<string, any>;
+  actor?: string;
+  trustedPaid?: boolean;
+} = {}): Promise<{ paid: boolean; already_confirmed: boolean; order: any }> {
+  if (isOrderPaid(order)) return { paid: true, already_confirmed: true, order };
+
+  let paid = false;
+  let reference = opts.paymentReference ?? "";
+
+  const storedSessionId = orderMeta(order, SESSION_META_KEY);
+  const sessionId = opts.sessionId || storedSessionId;
+  if (sessionId) {
+    const session = await ACTIVE_PROVIDER.retrieveSession(sr, sessionId);
+    // The order's own session was minted for it; one from the request must prove it.
+    if (sessionId !== storedSessionId) assertSessionBelongsToOrder(session, order);
+    // A payment intent can succeed a moment before its session reads paid.
+    paid = session.paid || !!opts.trustedPaid;
+    reference = reference || session.payment_reference;
+  } else {
+    paid = !!opts.trustedPaid;
+  }
+  if (!paid) return { paid: false, already_confirmed: false, order };
+
+  if (reference) {
+    await sr.entities["commerce.Order"].update(order.id, {
+      transaction_id: reference,
+      meta_data: withOrderMeta(order, { [REFERENCE_META_KEY]: reference }),
+    });
+    order.transaction_id = reference;
+  }
+  await transitionOrder(sr, order, "processing", {
+    settings: opts.settings,
+    actor: opts.actor ?? "payment-provider",
+    note: `Payment received via ${ACTIVE_PROVIDER.label}${reference ? ` (${reference})` : ""}.`,
+  });
+  return { paid: true, already_confirmed: false, order };
+}
+
+/**
+ * Refund money at the provider. Called *before* the local refund record is
+ * written, so a failed provider refund never leaves a phantom refund behind.
+ * Returns null when the order has no online payment to refund.
+ */
+export async function refundOnlinePayment(sr: any, order: any, opts: {
+  amount: number;
+  reason?: string;
+  idempotencyKey?: string;
+}): Promise<{ provider: string; id: string; status: string; amount: number } | null> {
+  const reference = order?.transaction_id || orderMeta(order, REFERENCE_META_KEY);
+  if (!isOnlineGateway(order?.payment_method) || !reference) return null;
+
+  const refund = await ACTIVE_PROVIDER.refund(sr, {
+    paymentReference: reference,
+    amount: round2(opts.amount),
+    currency: String(order.currency || "USD"),
+    reason: opts.reason,
+    idempotencyKey: opts.idempotencyKey,
+  });
+  return { provider: ACTIVE_PROVIDER.id, ...refund };
+}
+
+/** Webhook plumbing, provider-neutral. */
+export function verifyPaymentWebhook(opts: { payload: string; header: string; secret: string }): Promise<boolean> {
+  return ACTIVE_PROVIDER.verifyWebhook(opts);
+}
+
+export function parsePaymentWebhook(body: any) {
+  return ACTIVE_PROVIDER.parseWebhookEvent(body);
+}

package/base44/shared/commerce/reviews.ts

@@ -0,0 +1,36 @@
+/**
+ * Review aggregates: keep Product.average_rating / rating_count in sync with
+ * approved reviews. Called by commerce/admin-reviews on any moderation change and by
+ * commerce/storefront-catalog when auto-approve is enabled.
+ */
+import { round2 } from "./money.ts";
+
+/** Recompute a product's rating aggregates from its APPROVED reviews. */
+export async function recalcProductRating(sr: any, productId: string): Promise<{ average: number; count: number }> {
+  const approved: any[] = [];
+  let skip = 0;
+  // paginate defensively; a product rarely has >500 reviews but be correct
+  while (true) {
+    const page = (await sr.entities["commerce.ProductReview"].filter(
+      { product_id: productId, status: "approved" },
+      "-created_date",
+      500,
+      skip,
+    )) ?? [];
+    approved.push(...page);
+    if (page.length < 500) break;
+    skip += 500;
+  }
+
+  const rated = approved.filter((r) => typeof r.rating === "number" && r.rating > 0);
+  const count = approved.length;
+  const average = rated.length
+    ? round2(rated.reduce((a, r) => a + r.rating, 0) / rated.length)
+    : 0;
+
+  await sr.entities["commerce.Product"].update(productId, {
+    average_rating: average,
+    rating_count: count,
+  });
+  return { average, count };
+}

package/base44/shared/commerce/scan.ts

@@ -0,0 +1,57 @@
+/**
+ * Full-collection scan helper. Base44's filter() is exact-match with a 5k page
+ * cap and no total count, so server-side search/aggregation loops pages of 500.
+ * Keep `cap` sane — reports over very large stores should move to a
+ * materialized stats entity (see skills/commerce/references/limits-and-performance.md).
+ */
+
+export interface ScanOpts {
+  /** Hard cap on records scanned (default 10_000). */
+  cap?: number;
+  /** Page size per request (default 500). */
+  pageSize?: number;
+  /** Optional field projection passed through to filter(). */
+  fields?: string[];
+}
+
+/**
+ * Scan every record matching `query` (null/{} = all records via list()).
+ * `entityApi` is e.g. `sr.entities["commerce.Order"]`.
+ *
+ * The 4th arg accepts either a plain number (treated as `cap`) or a full
+ * `ScanOpts` object, so both `scanAll(e, {}, "order", 500)` and
+ * `scanAll(e, {}, "order", { cap: 500 })` call styles are valid.
+ */
+export async function scanAll(
+  entityApi: any,
+  query: Record<string, any> | null = null,
+  sort = "-created_date",
+  optsOrCap: ScanOpts | number = {},
+): Promise<any[]> {
+  const opts: ScanOpts = typeof optsOrCap === "number" ? { cap: optsOrCap } : optsOrCap;
+  const cap = opts.cap ?? 10_000;
+  const pageSize = opts.pageSize ?? 500;
+  const out: any[] = [];
+  let skip = 0;
+  while (out.length < cap) {
+    const page = query && Object.keys(query).length
+      ? (await entityApi.filter(query, sort, pageSize, skip, opts.fields)) ?? []
+      : (await entityApi.list(sort, pageSize, skip)) ?? [];
+    out.push(...page);
+    if (page.length < pageSize) break;
+    skip += pageSize;
+  }
+  return out.slice(0, cap);
+}
+
+/** Case-insensitive "haystack contains needle" for server-side search actions. */
+export function textMatch(haystack: unknown, needle: string): boolean {
+  if (!needle) return true;
+  return String(haystack ?? "").toLowerCase().includes(needle.toLowerCase());
+}
+
+/** Slice a filtered array into a page + has_next probe (limit+1 convention). */
+export function pageSlice<T>(rows: T[], limit = 20, skip = 0): { rows: T[]; has_next: boolean } {
+  const page = rows.slice(skip, skip + limit + 1);
+  return { rows: page.slice(0, limit), has_next: page.length > limit };
+}

package/base44/shared/commerce/sequence.ts

@@ -0,0 +1,35 @@
+/**
+ * Order-number sequencing and opaque key/id generation.
+ *
+ * NOTE ON CONCURRENCY: Base44 has no transactions, so nextOrderNumber() is a
+ * read-max-then-increment and two simultaneous checkouts could race. The window
+ * is tiny and order ids (not numbers) are the primary key; see
+ * skills/commerce/references/limits-and-performance.md for mitigations.
+ */
+
+const ORDER_NUMBER_START = 1001;
+
+/** Next human-facing sequential order number (max existing + 1, starts at 1001). */
+export async function nextOrderNumber(sr: any): Promise<number> {
+  const latest = (await sr.entities["commerce.Order"].list("-order_number", 1)) ?? [];
+  const max = Number(latest[0]?.order_number ?? 0);
+  return Math.max(max + 1, ORDER_NUMBER_START);
+}
+
+/**
+ * Random order key used as a bearer credential for guest order tracking
+ * (an unguessable per-order key). Treat like a secret; only ever share with the
+ * order's owner.
+ */
+export function generateOrderKey(): string {
+  const bytes = new Uint8Array(18);
+  crypto.getRandomValues(bytes);
+  let key = "";
+  for (const b of bytes) key += (b % 36).toString(36);
+  return `order_${key.slice(0, 24)}`;
+}
+
+/** Stable uuid for embedded line ids, cart tokens, item keys. */
+export function uuid(): string {
+  return crypto.randomUUID();
+}

package/base44/shared/commerce/settings.ts

@@ -0,0 +1,57 @@
+/**
+ * StoreSettings access. Settings are stored one record per group:
+ * { group_id: "general" | "products" | "inventory" | "tax"
+ *           | "shipping" | "emails", values: {...} }
+ */
+
+/**
+ * Fetch settings groups in one list() call.
+ * Returns { [group_id]: values }. Pass no groupIds to get every group.
+ * Callers should fetch once per invocation and pass the object around.
+ */
+export async function getSettings(sr: any, ...groupIds: string[]): Promise<Record<string, any>> {
+  const records = (await sr.entities["commerce.StoreSettings"].list(undefined, 100)) ?? [];
+  const out: Record<string, any> = {};
+  for (const rec of records) {
+    if (!rec?.group_id) continue;
+    if (groupIds.length && !groupIds.includes(rec.group_id)) continue;
+    out[rec.group_id] = rec.values ?? {};
+  }
+  return out;
+}
+
+/** Read one key from a fetched groups object with a fallback. */
+export function getSetting(groups: Record<string, any>, group: string, key: string, fallback?: any): any {
+  const v = groups?.[group]?.[key];
+  return v === undefined || v === null ? fallback : v;
+}
+
+/**
+ * Project only the settings that are safe to expose to anonymous storefront
+ * callers (used by commerce/storefront-catalog `get-store-info`). Never expose the
+ * emails group, notification recipients, or internal thresholds.
+ */
+export function storefrontSafeSettings(groups: Record<string, any>): Record<string, any> {
+  const general = groups.general ?? {};
+  const products = groups.products ?? {};
+  const tax = groups.tax ?? {};
+  const inventory = groups.inventory ?? {};
+  return {
+    store_name: general.store_name ?? "",
+    currency: general.currency ?? "USD",
+    currency_position: general.currency_position ?? "left",
+    thousand_sep: general.thousand_sep ?? ",",
+    decimal_sep: general.decimal_sep ?? ".",
+    num_decimals: general.num_decimals ?? 2,
+    enable_taxes: general.enable_taxes ?? true,
+    enable_coupons: general.enable_coupons ?? true,
+    weight_unit: products.weight_unit ?? "kg",
+    dimension_unit: products.dimension_unit ?? "cm",
+    enable_reviews: products.enable_reviews ?? true,
+    review_rating_required: products.review_rating_required ?? true,
+    prices_include_tax: tax.prices_include_tax ?? false,
+    display_prices_shop: tax.display_prices_shop ?? "excl",
+    display_prices_cart: tax.display_prices_cart ?? "excl",
+    hide_out_of_stock: inventory.hide_out_of_stock ?? false,
+  };
+}