@base44/app-plugin-commerce 0.1.0

package/base44/shared/commerce/stripe.ts

@@ -0,0 +1,463 @@
+/**
+ * Stripe payments — the ONE module that talks to Stripe.
+ *
+ * Everything provider-specific lives here: credential lookup, Checkout Session
+ * creation (used both for the storefront redirect and for the admin's payment
+ * link), session retrieval, refunds, and webhook signature verification. Nothing
+ * calls this module directly — everything goes through the provider-neutral
+ * utility in `payments.ts`, which is where the adapter is bound.
+ *
+ * **Swapping in another provider** (PayPal, Adyen, a local PSP): write an adapter
+ * in `payments.ts` against that API — see
+ * skills/commerce/references/online-payments.md.
+ *
+ * Credentials come from the host, never from the `commerce.PaymentGateway`
+ * entity and never from the client: on Base44, setting up Stripe for the app
+ * injects `STRIPE_SECRET_KEY` into backend functions (see `stripeConnection`).
+ */
+import { HttpError } from "./auth.ts";
+import { round2 } from "./money.ts";
+
+const STRIPE_API = "https://api.stripe.com/v1";
+
+/** Currencies Stripe expects in whole units (no cents). */
+const ZERO_DECIMAL = new Set([
+  "BIF", "CLP", "DJF", "GNF", "JPY", "KMF", "KRW", "MGA", "PYG",
+  "RWF", "UGX", "VND", "VUV", "XAF", "XOF", "XPF",
+]);
+
+/** Amount → Stripe's smallest currency unit. 12.34 USD → 1234; 1200 JPY → 1200. */
+export function toMinorUnits(amount: number, currency: string): number {
+  const value = Number(amount) || 0;
+  if (ZERO_DECIMAL.has(String(currency || "").toUpperCase())) return Math.round(value);
+  return Math.round(round2(value) * 100);
+}
+
+/** Stripe's smallest unit → a display amount, for reading values back. */
+export function fromMinorUnits(minor: number, currency: string): number {
+  const value = Number(minor) || 0;
+  if (ZERO_DECIMAL.has(String(currency || "").toUpperCase())) return value;
+  return round2(value / 100);
+}
+
+export interface StripeConnection {
+  connected: boolean;
+  accessToken?: string;
+  /** Where the credential came from — useful when diagnosing setup. */
+  source?: "env" | "connector";
+  error?: string;
+}
+
+/** `STRIPE_SECRET_KEY`, injected by the host's Stripe integration. */
+function secretKeyFromEnv(): string {
+  try {
+    return String(Deno.env.get("STRIPE_SECRET_KEY") ?? "");
+  } catch {
+    return ""; // no env access in this runtime
+  }
+}
+
+/**
+ * Can we call Stripe, and with what credential? Never throws — "not set up yet"
+ * is a normal state (the store just can't take cards), so callers branch on
+ * `connected` instead of catching.
+ *
+ * Two credential sources, in order:
+ *
+ * 1. **`STRIPE_SECRET_KEY` in the environment** — this is how Base44 works.
+ *    Stripe is a *platform integration* there (app dashboard → Integrations →
+ *    Stripe), not an OAuth connector: the platform holds the keys and injects
+ *    `STRIPE_SECRET_KEY` / `STRIPE_PUBLISHABLE_KEY` into backend functions.
+ *    Verified on a hosted app — a function's whole environment is
+ *    `BASE44_APP_ID`, `STRIPE_PUBLISHABLE_KEY`, `STRIPE_SECRET_KEY`.
+ * 2. **A `stripe` OAuth connector**, for hosts that expose Stripe that way.
+ *    There is no such connector in Base44's catalog, so this is a portability
+ *    fallback rather than the Base44 path.
+ */
+export async function stripeConnection(sr: any): Promise<StripeConnection> {
+  const envKey = secretKeyFromEnv();
+  if (envKey) return { connected: true, accessToken: envKey, source: "env" };
+
+  try {
+    const conn = await sr?.connectors?.getConnection?.("stripe");
+    const accessToken = conn?.accessToken ?? conn?.access_token ?? "";
+    if (accessToken) return { connected: true, accessToken, source: "connector" };
+  } catch {
+    // fall through — an absent connector is not an error worth surfacing
+  }
+  return {
+    connected: false,
+    error: "No Stripe credentials: set up Stripe for this app (its keys arrive as STRIPE_SECRET_KEY).",
+  };
+}
+
+export interface CredentialCheck {
+  /** The credential exists *and* the provider accepts it. */
+  ok: boolean;
+  /** The provider actively rejected it (revoked, rotated, wrong mode). */
+  rejected: boolean;
+  error?: string;
+}
+
+/** Short-lived per-isolate cache, keyed by token so a key change busts it. */
+let credentialCache: { token: string; at: number; result: CredentialCheck } | null = null;
+const CREDENTIAL_TTL_MS = 60_000;
+
+/**
+ * Is the credential **usable**, not merely present?
+ *
+ * Presence alone is a poor proxy: a key that has been disconnected, rotated or
+ * revoked still sits in the environment until the function is redeployed, so the
+ * store would advertise card payment and only discover the truth when a customer
+ * tries to pay. This asks Stripe (`GET /balance`, the cheapest authenticated
+ * call) and caches the answer for a minute so hot paths don't pay for it.
+ *
+ * A **rejected** credential means not connected. A *network* failure is not
+ * allowed to flip a working store to "no payments" on a blip: the last good
+ * answer stands until the cache expires.
+ */
+export async function verifyStripeCredential(sr: any): Promise<CredentialCheck> {
+  const conn = await stripeConnection(sr);
+  if (!conn.connected) return { ok: false, rejected: true, error: conn.error };
+  const token = conn.accessToken!;
+
+  const cached = credentialCache;
+  if (cached && cached.token === token && Date.now() - cached.at < CREDENTIAL_TTL_MS) {
+    return cached.result;
+  }
+
+  let result: CredentialCheck;
+  try {
+    const res = await fetch(`${STRIPE_API}/balance`, { headers: { Authorization: `Bearer ${token}` } });
+    if (res.ok) {
+      result = { ok: true, rejected: false };
+    } else {
+      const body = await res.json().catch(() => ({}));
+      const rejected = res.status === 401 || res.status === 403;
+      result = {
+        ok: false,
+        rejected,
+        error: body?.error?.message ?? `The payment provider rejected the credential (${res.status}).`,
+      };
+    }
+  } catch (e) {
+    if (cached?.token === token && cached.result.ok) return cached.result; // transient
+    result = { ok: false, rejected: false, error: (e as Error)?.message ?? "Could not reach the payment provider." };
+  }
+
+  credentialCache = { token, at: Date.now(), result };
+  return result;
+}
+
+/** The token, or a 503 that says what the operator has to do. */
+async function requireToken(sr: any): Promise<string> {
+  const conn = await stripeConnection(sr);
+  if (!conn.connected) {
+    throw new HttpError(
+      503,
+      "Card payments are unavailable: no payment provider is set up for this app.",
+      "payment_provider_unavailable",
+      { provider: "stripe", reason: conn.error },
+    );
+  }
+  return conn.accessToken!;
+}
+
+/**
+ * One Stripe REST call. `form` is flattened into `application/x-www-form-urlencoded`
+ * (Stripe's wire format), supporting the nested `a[b][0][c]` shape it expects.
+ * Stripe errors surface as HttpError with Stripe's own message.
+ */
+export async function stripeRequest(
+  sr: any,
+  method: "GET" | "POST",
+  path: string,
+  form?: Record<string, unknown>,
+  opts: { idempotencyKey?: string } = {},
+): Promise<any> {
+  const token = await requireToken(sr);
+  const body = form ? encodeForm(form) : undefined;
+
+  const send = (idempotencyKey?: string) => fetch(`${STRIPE_API}${path}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      ...(body ? { "Content-Type": "application/x-www-form-urlencoded" } : {}),
+      ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
+    },
+    body,
+  });
+
+  let res = await send(opts.idempotencyKey);
+  let payload = await res.json().catch(() => ({}));
+
+  // An idempotency key that Stripe has seen with *different* parameters is a
+  // hard error ("Keys for idempotent requests can only be used with the same
+  // parameters…") and it sticks for 24h. Idempotency is an optimisation here —
+  // it stops a double-click creating two payment pages — so a clash must not
+  // cost the operator a working payment link: retry once without the key.
+  if (!res.ok && opts.idempotencyKey && payload?.error?.type === "idempotency_error") {
+    console.warn(`stripe: idempotency clash on ${path} (${opts.idempotencyKey}) — retrying without a key`);
+    res = await send(undefined);
+    payload = await res.json().catch(() => ({}));
+  }
+
+  if (!res.ok) {
+    const message = payload?.error?.message ?? `Stripe request failed (${res.status}).`;
+    throw new HttpError(502, message, payload?.error?.code ?? "stripe_error", {
+      provider: "stripe",
+      stripe_type: payload?.error?.type,
+    });
+  }
+  return payload;
+}
+
+/** Stripe's bracket form encoding: { a: { b: [1] } } → a[b][0]=1 */
+export function encodeForm(form: Record<string, unknown>): string {
+  const params = new URLSearchParams();
+  const walk = (prefix: string, value: unknown) => {
+    if (value === undefined || value === null || value === "") return;
+    if (Array.isArray(value)) {
+      value.forEach((v, i) => walk(`${prefix}[${i}]`, v));
+    } else if (typeof value === "object") {
+      for (const [k, v] of Object.entries(value as Record<string, unknown>)) walk(`${prefix}[${k}]`, v);
+    } else {
+      params.append(prefix, String(value));
+    }
+  };
+  for (const [key, value] of Object.entries(form)) walk(key, value);
+  return params.toString();
+}
+
+/**
+ * Short stable fingerprint of a request body, for idempotency keys.
+ *
+ * An idempotency key must map 1:1 to a set of parameters — Stripe rejects reusing
+ * one with *different* parameters ("Keys for idempotent requests can only be used
+ * with the same parameters…"). Keying on the order id plus its total was wrong:
+ * editing an order without moving the total (swapped items, a corrected email)
+ * kept the key while changing the request. Hashing the request itself makes the
+ * key change exactly when the request does — so a retry or double-click still
+ * dedupes, and an edited order gets a fresh session.
+ */
+export async function requestFingerprint(form: Record<string, unknown>): Promise<string> {
+  const encoded = new TextEncoder().encode(encodeForm(form));
+  const digest = await crypto.subtle.digest("SHA-256", encoded);
+  return [...new Uint8Array(digest)].slice(0, 8).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// ── Checkout Session ─────────────────────────────────────────────────────────
+
+/**
+ * Line items for the Checkout Session. One Stripe line per order line keeps the
+ * hosted page recognisable, and a single "Shipping, tax & fees" line carries
+ * everything else so the Stripe total always equals `order.total` exactly —
+ * which is what the order, the emails and the refund maths all use.
+ */
+export function sessionLineItems(order: any): Array<Record<string, unknown>> {
+  const currency = String(order.currency || "USD").toLowerCase();
+  const lines: Array<Record<string, unknown>> = [];
+  let accountedFor = 0;
+
+  for (const line of order.line_items ?? []) {
+    const qty = Math.max(1, Number(line.quantity) || 1);
+    // Stripe multiplies unit_amount by quantity, so send the discounted unit price.
+    const unit = round2((Number(line.total) || 0) / qty);
+    if (unit <= 0) continue;
+    accountedFor = round2(accountedFor + unit * qty);
+    lines.push({
+      quantity: qty,
+      price_data: {
+        currency,
+        unit_amount: toMinorUnits(unit, currency),
+        product_data: {
+          name: String(line.name || "Item").slice(0, 250),
+          ...(line.sku ? { description: `SKU ${line.sku}` } : {}),
+        },
+      },
+    });
+  }
+
+  const remainder = round2((Number(order.total) || 0) - accountedFor);
+  if (remainder > 0) {
+    lines.push({
+      quantity: 1,
+      price_data: {
+        currency,
+        unit_amount: toMinorUnits(remainder, currency),
+        product_data: { name: "Shipping, tax & fees" },
+      },
+    });
+  }
+
+  // Rounding drift (or an order that is entirely discounts) — fall back to one
+  // line for the whole total rather than sending Stripe a different number.
+  if (!lines.length || remainder < 0) {
+    return [{
+      quantity: 1,
+      price_data: {
+        currency,
+        unit_amount: toMinorUnits(order.total ?? 0, currency),
+        product_data: { name: `Order #${order.order_number ?? order.id}` },
+      },
+    }];
+  }
+  return lines;
+}
+
+export interface CheckoutSession {
+  id: string;
+  url: string;
+  status: string;
+  payment_status: string;
+  payment_intent: string;
+  expires_at?: number;
+  /** Read back from the session's own metadata — Stripe's record, not a caller's claim. */
+  order_id: string;
+  order_key: string;
+}
+
+function toCheckoutSession(session: any): CheckoutSession {
+  const metadata = session.metadata ?? {};
+  return {
+    id: String(session.id),
+    url: String(session.url ?? ""),
+    status: String(session.status ?? ""),
+    payment_status: String(session.payment_status ?? ""),
+    payment_intent: typeof session.payment_intent === "string"
+      ? session.payment_intent
+      : String(session.payment_intent?.id ?? ""),
+    expires_at: session.expires_at,
+    order_id: String(metadata.order_id ?? ""),
+    order_key: String(metadata.order_key ?? ""),
+  };
+}
+
+/**
+ * Create a Stripe Checkout Session for an order — the hosted payment page. The
+ * same call powers the storefront redirect and the admin's "payment link", so
+ * there is one payment flow to reason about, and no card data ever touches this
+ * app.
+ *
+ * `order_id` + `order_key` travel in the session metadata so the webhook and the
+ * return handler can find (and authorize) the order without trusting the URL.
+ */
+export async function createCheckoutSession(sr: any, order: any, opts: {
+  successUrl: string;
+  cancelUrl: string;
+  customerEmail?: string;
+  locale?: string;
+}): Promise<CheckoutSession> {
+  const form: Record<string, unknown> = {
+    mode: "payment",
+    line_items: sessionLineItems(order),
+    success_url: opts.successUrl,
+    cancel_url: opts.cancelUrl,
+    client_reference_id: String(order.id),
+    ...(opts.customerEmail ? { customer_email: opts.customerEmail } : {}),
+    metadata: {
+      order_id: String(order.id),
+      order_key: String(order.order_key ?? ""),
+      order_number: String(order.order_number ?? ""),
+    },
+    payment_intent_data: {
+      metadata: { order_id: String(order.id), order_key: String(order.order_key ?? "") },
+    },
+  };
+  const session = await stripeRequest(sr, "POST", "/checkout/sessions", form, {
+    idempotencyKey: `order-${order.id}-${await requestFingerprint(form)}`,
+  });
+
+  return toCheckoutSession(session);
+}
+
+/**
+ * Expire a Checkout Session so its link stops working. Used when a new session is
+ * minted for an order — otherwise an older link would still be payable, at the
+ * total the order had when that link was made.
+ *
+ * Best-effort by design: a session that is already completed or expired answers
+ * an error, which is not a problem worth surfacing.
+ */
+export async function expireCheckoutSession(sr: any, sessionId: string): Promise<boolean> {
+  if (!sessionId) return false;
+  try {
+    await stripeRequest(sr, "POST", `/checkout/sessions/${encodeURIComponent(sessionId)}/expire`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function retrieveCheckoutSession(sr: any, sessionId: string): Promise<CheckoutSession> {
+  const session = await stripeRequest(sr, "GET", `/checkout/sessions/${encodeURIComponent(sessionId)}`);
+  return toCheckoutSession(session);
+}
+
+/** Refund a captured payment (full or partial). `amount` is in display units. */
+export async function createStripeRefund(sr: any, opts: {
+  paymentIntentId: string;
+  amount: number;
+  currency: string;
+  reason?: string;
+  idempotencyKey?: string;
+}): Promise<{ id: string; status: string; amount: number }> {
+  const refund = await stripeRequest(sr, "POST", "/refunds", {
+    payment_intent: opts.paymentIntentId,
+    amount: toMinorUnits(opts.amount, opts.currency),
+    ...(opts.reason ? { metadata: { reason: String(opts.reason).slice(0, 500) } } : {}),
+  }, { idempotencyKey: opts.idempotencyKey });
+  return {
+    id: String(refund.id),
+    status: String(refund.status ?? ""),
+    amount: fromMinorUnits(refund.amount ?? 0, opts.currency),
+  };
+}
+
+// ── webhook signature ────────────────────────────────────────────────────────
+
+/**
+ * Verify a Stripe webhook signature (`Stripe-Signature: t=…,v1=…`) against the
+ * raw request body. Constant-time comparison, and a timestamp tolerance so a
+ * captured request can't be replayed indefinitely.
+ *
+ * Returns false — never throws — so the caller answers 400 without leaking why.
+ */
+export async function verifyWebhookSignature(opts: {
+  payload: string;
+  header: string;
+  secret: string;
+  toleranceSeconds?: number;
+  nowSeconds?: number;
+}): Promise<boolean> {
+  const { payload, header, secret } = opts;
+  if (!payload || !header || !secret) return false;
+
+  const parts = header.split(",").map((p) => p.trim().split("="));
+  const timestamp = parts.find((p) => p[0] === "t")?.[1] ?? "";
+  const signatures = parts.filter((p) => p[0] === "v1").map((p) => p[1]);
+  if (!timestamp || !signatures.length) return false;
+
+  const tolerance = opts.toleranceSeconds ?? 300;
+  const now = opts.nowSeconds ?? Math.floor(Date.now() / 1000);
+  const age = now - Number(timestamp);
+  if (!Number.isFinite(age) || Math.abs(age) > tolerance) return false;
+
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${timestamp}.${payload}`));
+  const expected = [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("");
+  return signatures.some((sig) => timingSafeEqual(sig, expected));
+}
+
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i += 1) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}

package/base44/shared/commerce/tax.ts

@@ -0,0 +1,136 @@
+/**
+ * Tax-rate matching and application, following standard commerce tax semantics:
+ * - rates match by tax class + location (empty field = wildcard)
+ * - rates sort by priority asc; ONE rate applies per priority level
+ * - non-compound rates apply on the base amount; compound rates apply on
+ *   (base + all previously accumulated tax), in priority order
+ */
+import { round2 } from "./money.ts";
+
+export interface TaxAddress {
+  country?: string;
+  state?: string;
+  postcode?: string;
+  city?: string;
+}
+
+/** Does `postcode` match `pattern`? Supports exact, `90*` wildcard, `1000...2000` numeric range. */
+export function postcodeMatchesPattern(pattern: string, postcode: string): boolean {
+  const p = (pattern || "").trim().toUpperCase();
+  const pc = (postcode || "").trim().toUpperCase();
+  if (!p) return true; // empty pattern = wildcard
+  if (!pc) return false;
+  if (p.includes("...")) {
+    const [lo, hi] = p.split("...").map((s) => parseInt(s.trim(), 10));
+    const n = parseInt(pc, 10);
+    return !Number.isNaN(lo) && !Number.isNaN(hi) && !Number.isNaN(n) && n >= lo && n <= hi;
+  }
+  if (p.includes("*")) {
+    const re = new RegExp("^" + p.split("*").map(escapeRegex).join(".*") + "$");
+    return re.test(pc);
+  }
+  return p === pc;
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function rateMatchesLocation(rate: any, addr: TaxAddress): boolean {
+  const country = (addr.country || "").toUpperCase();
+  const state = (addr.state || "").toUpperCase();
+  const city = (addr.city || "").toLowerCase();
+  if (rate.country && rate.country.toUpperCase() !== country) return false;
+  if (rate.state && rate.state.toUpperCase() !== state) return false;
+  const postcodes: string[] = rate.postcodes || [];
+  if (postcodes.length && !postcodes.some((p: string) => postcodeMatchesPattern(p, addr.postcode || ""))) return false;
+  const cities: string[] = rate.cities || [];
+  if (cities.length && !cities.some((c: string) => (c || "").toLowerCase() === city)) return false;
+  return true;
+}
+
+/**
+ * Find the applicable rates for a tax class at an address.
+ * Sorted by priority asc (menu_order breaks ties); one rate per priority.
+ */
+export function matchTaxRates(allRates: any[], addr: TaxAddress, taxClass: string): any[] {
+  const cls = taxClass || "standard";
+  const candidates = (allRates || [])
+    .filter((r) => (r.tax_class || "standard") === cls && rateMatchesLocation(r, addr))
+    .sort((a, b) => (a.priority ?? 1) - (b.priority ?? 1) || (a.menu_order ?? 0) - (b.menu_order ?? 0));
+  // only the first matching rate per priority level applies
+  const byPriority = new Map<number, any>();
+  for (const r of candidates) {
+    const p = r.priority ?? 1;
+    if (!byPriority.has(p)) byPriority.set(p, r);
+  }
+  return [...byPriority.values()];
+}
+
+export interface AppliedRate {
+  rate: any;
+  amount: number;
+}
+
+/**
+ * Apply matched rates (already priority-deduped, priority-ordered) to an
+ * ex-tax amount. Non-compound rates each apply on the base; compound rates
+ * apply on base + accumulated tax so far.
+ */
+export function applyRates(amount: number, rates: any[]): AppliedRate[] {
+  const base = Number(amount) || 0;
+  const out: AppliedRate[] = [];
+  let accumulated = 0;
+  for (const rate of rates || []) {
+    const pct = (Number(rate.rate) || 0) / 100;
+    const taxable = rate.compound ? base + accumulated : base;
+    const tax = round2(taxable * pct);
+    accumulated += tax;
+    out.push({ rate, amount: tax });
+  }
+  return out;
+}
+
+export interface InclusiveTaxResult {
+  net: number;
+  taxes: AppliedRate[];
+  totalTax: number;
+}
+
+/**
+ * Extract tax from a tax-INCLUSIVE gross amount (prices_include_tax mode),
+ * mirroring standard inclusive-tax extraction: compound rates are unwound from the
+ * outside in (last priority first), then the remaining amount is split across
+ * the non-compound rates which all share the same net base.
+ */
+export function extractInclusiveTax(gross: number, rates: any[]): InclusiveTaxResult {
+  let remaining = Number(gross) || 0;
+  const taxesByRate = new Map<any, number>();
+
+  // 1) unwind compound rates, highest priority (applied last) first
+  const compound = (rates || []).filter((r) => r.compound).reverse();
+  for (const rate of compound) {
+    const pct = (Number(rate.rate) || 0) / 100;
+    const tax = round2(remaining - remaining / (1 + pct));
+    taxesByRate.set(rate, tax);
+    remaining -= tax;
+  }
+
+  // 2) the non-compound rates all apply on the same net base
+  const regular = (rates || []).filter((r) => !r.compound);
+  const regularSum = regular.reduce((a, r) => a + (Number(r.rate) || 0) / 100, 0);
+  const net = regularSum > 0 ? remaining / (1 + regularSum) : remaining;
+  for (const rate of regular) {
+    const pct = (Number(rate.rate) || 0) / 100;
+    taxesByRate.set(rate, round2(net * pct));
+  }
+
+  const taxes: AppliedRate[] = (rates || []).map((rate) => ({ rate, amount: taxesByRate.get(rate) ?? 0 }));
+  const totalTax = round2(taxes.reduce((a, t) => a + t.amount, 0));
+  return { net: round2((Number(gross) || 0) - totalTax), taxes, totalTax };
+}
+
+/** Sum of applied-rate amounts, rounded. */
+export function sumTax(applied: AppliedRate[]): number {
+  return round2((applied || []).reduce((a, t) => a + t.amount, 0));
+}