@omega.js/backend 0.1.0

package/dist/manager/routes/payments/intent/post.js

@@ -0,0 +1,341 @@
+const path = require('path');
+const loadProvider = require('../../../libraries/load-provider.js');
+const powertools = require('node-powertools');
+const OrderId = require('../../../libraries/payment/order-id.js');
+const recaptcha = require('../../../libraries/recaptcha.js');
+const discountCodes = require('../../../libraries/payment/discount-codes.js');
+const { hasAuthUser } = require('../../../libraries/auth-user.js');
+const { COLLECTION: CART_COLLECTION } = require('../../../libraries/abandoned-cart-config.js');
+
+/**
+ * POST /payments/intent
+ * Creates a payment intent (e.g., Stripe Checkout Session) for subscription or one-time purchase
+ * Requires authentication
+ */
+module.exports = async ({ ctx, Manager, user, settings, libraries }) => {
+  const { admin } = libraries;
+
+  // Require authentication
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  // A purchaser has to BE a user of this project: an auth user AND the user doc a
+  // signup creates behind it. The pair only ever comes apart for a uid that lives
+  // in ANOTHER project (a local QA checkout run against the emulator) or an
+  // account deleted mid-session — and a checkout begun without it ends as a
+  // webhook with nowhere to write, which the pipeline then refuses on its own
+  // ([#399](https://github.com/Omega-JS-Stack/omega/issues/399)). Refusing HERE
+  // means no provider session, no intent doc, and no half-written account.
+  //
+  // The DOC half is defense in depth on the token lane — authenticate() only calls
+  // a JWT caller authenticated once it has read their user doc — and the live gate
+  // on the omega-admin-key lane, which authenticates carrying no user at all.
+  const missing = await findMissingPurchaser(admin, user.auth.uid);
+
+  if (missing) {
+    ctx.warn(`Checkout refused: uid=${user.auth.uid} has ${missing} in this project — a purchase requires both an auth user and a user doc`);
+    return ctx.respond('Your account could not be verified. Please sign out, sign back in, and try again.', { code: 403 });
+  }
+
+  // Verify reCAPTCHA (skip during automated tests). verify() owns the whole
+  // decision: no RECAPTCHA_SECRET_KEY configured → pass (unkeyed brands are a
+  // sanctioned population; cp257: keys are optional and per-brand); secret +
+  // missing/bad token → fail. No pre-check here: an empty-token 403 before
+  // verify() would permanently reject every checkout from a brand that never
+  // configured reCAPTCHA. Same shape as routes/marketing/contact/post.js.
+  if (!ctx.isTesting()) {
+    const recaptchaToken = settings.verification?.['g-recaptcha-response'];
+    const recaptchaValid = await recaptcha.verify(recaptchaToken);
+    if (!recaptchaValid) {
+      return ctx.respond('Request could not be verified', { code: 403 });
+    }
+  }
+
+  const uid = user.auth.uid;
+  const provider = settings.provider;
+  const productId = settings.productId;
+  const attribution = settings.attribution;
+  const trackingConsent = settings.trackingConsent;
+  const discount = settings.discount;
+  const supplemental = settings.supplemental;
+  const simulate = settings.simulate;
+  let trial = settings.trial;
+  let frequency = settings.frequency;
+
+  ctx.log(`Intent request: uid=${uid}, provider=${provider}, product=${productId}, frequency=${frequency}, trial=${trial}, simulate=${simulate || 'none'}`);
+
+  // Validate product exists in config
+  const product = (Manager.config.payment?.products || []).find(p => p.id === productId);
+  if (!product) {
+    ctx.log(`Product "${productId}" not found (available: ${(Manager.config.payment?.products || []).map(p => p.id).join(', ')})`);
+    return ctx.respond(`Product '${productId}' not found`, { code: 400 });
+  }
+
+  const productType = product.type || 'subscription';
+
+  ctx.log(`Product resolved: id=${product.id}, name=${product.name}, type=${productType}, trialDays=${product.trial?.days || 'none'}`);
+
+  // Subscription-specific guards
+  if (productType === 'subscription') {
+    // Require frequency for subscriptions
+    if (!frequency) {
+      return ctx.respond('Frequency is required for subscription products', { code: 400 });
+    }
+
+    // Block checkout unless user has no subscription or is fully cancelled
+    const subProductId = user.subscription?.product?.id || 'basic';
+    const subStatus = user.subscription?.status;
+    if (subProductId !== 'basic' && subStatus !== 'cancelled') {
+      ctx.log(`User ${uid} has existing subscription: product=${subProductId}, status=${subStatus}, resourceId=${user.subscription.payment?.resourceId}`);
+      return ctx.respond('You already have a subscription. Please cancel your existing subscription before purchasing a new one.', { code: 400 });
+    }
+
+    // Resolve trial eligibility: if requested but user has subscription history, silently downgrade
+    if (trial) {
+      const historySnapshot = await admin.firestore()
+        .collection('payments-orders')
+        .where('owner', '==', uid)
+        .where('type', '==', 'subscription')
+        .limit(1)
+        .get();
+
+      if (!historySnapshot.empty) {
+        ctx.log(`User ${uid} not eligible for trial (has subscription history), continuing without trial`);
+        trial = false;
+      }
+    }
+  } else {
+    // One-time purchases don't use trial or frequency. `once` is what a
+    // one-time buy bills on, and it is written here rather than taken from the
+    // caller: a checkout that asked for `annually` on a one-time product put
+    // that word on the intent doc, the provider call and the confirmation URL
+    // alike ([#668](https://github.com/Omega-JS-Stack/omega/issues/668)).
+    trial = false;
+    frequency = 'once';
+  }
+
+  // Validate discount code (if provided)
+  let resolvedDiscount = null;
+  if (discount) {
+    const discountResult = discountCodes.validate(discount, user);
+    if (!discountResult.valid) {
+      return ctx.respond(`Invalid discount code: ${discount}`, { code: 400 });
+    }
+    resolvedDiscount = discountResult;
+    ctx.log(`Discount validated: code=${resolvedDiscount.code}, percent=${resolvedDiscount.percent}, amount=${resolvedDiscount.amount}, duration=${resolvedDiscount.duration}`);
+  }
+
+  // Mint the order id against the intents that already exist. The id keys the
+  // intent doc written below, so an unchecked repeat overwrote another
+  // customer's checkout ([#664](https://github.com/Omega-JS-Stack/omega/issues/664)).
+  const orderId = await OrderId.mint({ admin, ctx });
+
+  ctx.log(`Generated orderId=${orderId}`);
+
+  // Build redirect URLs
+  const confirmationUrl = buildConfirmationUrl(Manager.project.websiteUrl, { product, productId, productType, frequency, provider, trial, orderId, discount: resolvedDiscount });
+  const cancelUrl = buildCancelUrl(Manager.project.websiteUrl, { productId, frequency });
+
+  // Load the provider module
+  let providerModule;
+  try {
+    providerModule = loadProvider(path.join(__dirname, 'providers'), provider);
+  } catch (e) {
+    return ctx.respond(`Unknown provider: ${provider}`, { code: 400 });
+  }
+
+  // Create the intent via the provider
+  let result;
+  try {
+    result = await providerModule.createIntent({
+      uid,
+      orderId,
+      product,
+      productId,
+      frequency,
+      trial,
+      discount: resolvedDiscount,
+      simulate,
+      confirmationUrl,
+      cancelUrl,
+      ctx,
+    });
+  } catch (e) {
+    // A REFUSAL the framework itself wrote is the one thing said out loud: a
+    // discount code that covers the whole price leaves nothing for PayPal or
+    // Coinbase to charge, and that is the buyer's own code and price to hear
+    // rather than a fault to hide (`chargeableAmount()` in
+    // libraries/payment/discount-codes.js codes it 400,
+    // [#786](https://github.com/Omega-JS-Stack/omega/issues/786)).
+    if (e.code === 400) {
+      return ctx.respond(e.message, { code: 400 });
+    }
+
+    // The provider's own words stay in the logs — a client gets one neutral
+    // sentence, never an SDK message naming our internals ([#212]).
+    ctx.error(`Failed to create ${provider} intent: uid=${uid}, product=${productId}, error=${e.message}`);
+    return ctx.respond('We could not start your checkout right now. Please try again shortly.', { code: 500 });
+  }
+
+  ctx.log(`${provider} intent created: id=${result.id}, url=${result.url}`);
+
+  // Build timestamps
+  const now = powertools.timestamp(new Date(), { output: 'string' });
+  const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+  // Save to payments-intents collection (keyed by orderId for consistent lookup with payments-orders)
+  await admin.firestore().doc(`payments-intents/${orderId}`).set({
+    id: orderId,
+    intentId: result.id,
+    provider: provider,
+    owner: uid,
+    status: 'pending',
+    productId: productId,
+    type: productType,
+    frequency: frequency,
+    trial: trial,
+    attribution: attribution,
+    trackingConsent: trackingConsent,
+    // The CUSTOMER's request context, captured here because this is the only
+    // moment the backend hears from their browser: the webhook that completes
+    // the order arrives from the provider's servers. Meta and TikTok match a
+    // server conversion to the browsing session on exactly this pair
+    // ([#385](https://github.com/Omega-JS-Stack/omega/issues/385)), and the
+    // order fold copies it off the intent.
+    request: {
+      ip: ctx.request.geolocation?.ip || null,
+      userAgent: ctx.request.client?.userAgent || null,
+    },
+    discount: resolvedDiscount,
+    supplemental: supplemental,
+    raw: result.raw,
+    metadata: {
+      created: {
+        timestamp: now,
+        timestampUNIX: nowUNIX,
+      },
+    },
+  });
+
+  ctx.log(`Saved payments-intents/${orderId}: uid=${uid}, product=${productId}, type=${productType}, frequency=${frequency}, trial=${trial}`);
+
+  // Tell the abandoned-cart sweep this shopper is mid-checkout. Asking for a
+  // provider session is the loudest "buying it right now" the backend ever
+  // hears, and the cart's reminder clock was otherwise set once, when the page
+  // opened, and never moved — so a shopper still working through the checkout
+  // was mailed about the cart they were paying for
+  // ([#655](https://github.com/Omega-JS-Stack/omega/issues/655)).
+  //
+  // Fire-and-forget, and an `update` on purpose: a checkout reached without the
+  // page's cart tracker (an unauthenticated page load, a direct link) has no
+  // cart, and this must never CREATE one the sweep would then chase.
+  admin.firestore().doc(`${CART_COLLECTION}/${uid}`).update({ lastActivityAt: nowUNIX })
+    .then(() => ctx.log(`Updated ${CART_COLLECTION}/${uid}: lastActivityAt=${nowUNIX}`))
+    .catch((e) => {
+      // Not-found is the ordinary case above, not a fault
+      if (e.code !== 5) {
+        ctx.error(`Failed to stamp checkout activity on ${CART_COLLECTION}/${uid}: ${e.message}`);
+      }
+    });
+
+  return ctx.respond({
+    id: result.id,
+    orderId: orderId,
+    url: result.url,
+    // What the server actually RECEIVED to match this conversion with — key
+    // NAMES only, never a value ([#577](https://github.com/Omega-JS-Stack/omega/issues/577)).
+    // The dev palette reads the browser's side of the same question off the
+    // document; this is the only way to see which of those cookies survived the
+    // trip, which is exactly where a blocked pixel shows up.
+    attribution: {
+      cookies: Object.keys(attribution?.cookies || {}),
+    },
+  });
+};
+
+/**
+ * Which half of the purchaser is missing, if either
+ *
+ * @param {object} admin - The firebase-admin app
+ * @param {string} uid - The authenticated caller's uid
+ * @returns {Promise<string|null>} What is missing, phrased for the log line, or null when both exist
+ */
+async function findMissingPurchaser(admin, uid) {
+  // The omega-admin-key lane authenticates with no user token, so there may be no
+  // uid to look up at all — getUser('') throws, which would answer a 500 where the
+  // whole point is a loud 403
+  if (!uid) {
+    return 'no auth user';
+  }
+
+  if (!await hasAuthUser(admin, uid)) {
+    return 'no auth user';
+  }
+
+  const userDoc = await admin.firestore().doc(`users/${uid}`).get();
+
+  return userDoc.exists ? null : 'no user doc';
+}
+
+/**
+ * Build the confirmation/success redirect URL
+ *
+ * `amount` is what the customer is charged TODAY, not the list price: the
+ * confirmation page hands that param straight to the client's analytics modules,
+ * so quoting the list price on a discounted checkout over-reports revenue to
+ * GA4/pixels. The discount comes off HERE rather than in a provider, because a
+ * real provider applies the coupon on its own hosted page and never revisits
+ * this URL — quoting it provider-side would have left every Stripe checkout
+ * reporting the full price ([#239](https://github.com/Omega-JS-Stack/omega/issues/239)).
+ */
+function buildConfirmationUrl(baseUrl, { product, productId, productType, frequency, provider, trial, orderId, discount }) {
+  const listPrice = productType === 'subscription'
+    ? (product.prices?.[frequency] || 0)
+    : (product.prices?.once || 0);
+
+  // A trial charges nothing today; otherwise a validated coupon comes off the
+  // first charge (every code is duration: 'once' — the renewal stays full price)
+  const amount = trial && product.trial?.days
+    ? 0
+    : discountCodes.applyToAmount(listPrice, discount);
+
+  const url = new URL('/payment/confirmation', baseUrl);
+  url.searchParams.set('productId', productId);
+  url.searchParams.set('productName', product.name || productId);
+  url.searchParams.set('amount', String(amount));
+  url.searchParams.set('currency', 'USD');
+  // What was BOUGHT, said outright rather than inferred from the cadence beside
+  // it: the confirmation page holds nothing else about the product, and a
+  // checkout that sent the wrong frequency left it polling the account for a
+  // plan a one-time purchase never writes
+  // ([#668](https://github.com/Omega-JS-Stack/omega/issues/668)).
+  url.searchParams.set('type', productType);
+  url.searchParams.set('frequency', frequency || 'once');
+  url.searchParams.set('paymentMethod', provider);
+  url.searchParams.set('trial', String(!!trial && !!product.trial?.days));
+  url.searchParams.set('orderId', orderId);
+  url.searchParams.set('track', 'true');
+
+  return url.toString();
+}
+
+/**
+ * Build the cancel/back redirect URL
+ */
+function buildCancelUrl(baseUrl, { productId, frequency }) {
+  const url = new URL('/payment/checkout', baseUrl);
+  url.searchParams.set('product', productId);
+
+  if (frequency) {
+    url.searchParams.set('frequency', frequency);
+  }
+
+  url.searchParams.set('payment', 'cancelled');
+
+  return url.toString();
+}
+
+// Exported for testing — the discounted `amount` is a provider-independent
+// promise of this route, not of whichever provider happens to run
+module.exports.buildConfirmationUrl = buildConfirmationUrl;

package/dist/manager/routes/payments/intent/providers/chargebee.js

@@ -0,0 +1,197 @@
+/**
+ * Chargebee intent provider
+ * Creates Chargebee Hosted Page sessions for subscription and one-time purchases
+ */
+module.exports = {
+  /**
+   * Create a Chargebee Hosted Page checkout session
+   *
+   * @param {object} options
+   * @param {string} options.uid - User's UID
+   * @param {string} options.orderId - @omega.js/backend order ID (XXXX-XXXX-XXXX)
+   * @param {object} options.product - Full product object from config
+   * @param {string} options.productId - Product ID from config (e.g., 'premium')
+   * @param {string} options.frequency - 'monthly' or 'annually' (subscriptions only)
+   * @param {boolean} options.trial - Whether to include a trial period
+   * @param {string} options.confirmationUrl - Success redirect URL
+   * @param {string} options.cancelUrl - Cancel redirect URL
+   * @param {object} options.ctx - Assistant instance for logging
+   * @returns {object} { id, url, raw }
+   */
+  async createIntent({ uid, orderId, product, productId, frequency, trial, discount, confirmationUrl, cancelUrl, ctx }) {
+    const ChargebeeLib = require('../../../../libraries/payment/providers/chargebee.js');
+    ChargebeeLib.init();
+
+    const productType = product.type || 'subscription';
+    const metaData = ChargebeeLib.buildMetaData(uid, orderId, productType === 'one-time' ? productId : undefined);
+
+    // Resolve Chargebee coupon if discount is present
+    let chargebeeCouponId = null;
+    if (discount) {
+      chargebeeCouponId = await resolveChargebeeCoupon(ChargebeeLib, discount, ctx);
+    }
+
+    let hostedPage;
+
+    if (productType === 'subscription') {
+      hostedPage = await createSubscriptionCheckout({ ChargebeeLib, uid, orderId, product, productId, frequency, trial, metaData, chargebeeCouponId, confirmationUrl, cancelUrl, ctx });
+    } else {
+      hostedPage = await createOneTimeCheckout({ ChargebeeLib, uid, orderId, product, productId, metaData, chargebeeCouponId, confirmationUrl, cancelUrl, ctx });
+    }
+
+    ctx.log(`Chargebee hosted page created: id=${hostedPage.id}, type=${productType}, url=${hostedPage.url}`);
+
+    return {
+      id: hostedPage.id,
+      url: hostedPage.url,
+      raw: hostedPage,
+    };
+  },
+};
+
+/**
+ * Create a Chargebee Hosted Page for a new subscription
+ */
+async function createSubscriptionCheckout({ ChargebeeLib, uid, orderId, product, productId, frequency, trial, metaData, chargebeeCouponId, confirmationUrl, cancelUrl, ctx }) {
+  const chargebeeItemId = product.chargebee?.itemId;
+
+  if (!chargebeeItemId) {
+    throw new Error(`No Chargebee item ID configured for product ${productId}`);
+  }
+
+  // Deterministic item price ID: {itemId}-{frequency}
+  const itemPriceId = `${chargebeeItemId}-${frequency}`;
+
+  // NOTE: subscription[meta_data] is NOT supported by Chargebee's hosted page checkout.
+  // We use pass_thru_content to carry our UID/orderId through the checkout flow,
+  // then backfill meta_data on the subscription after the webhook resolves the UID.
+  const params = {
+    subscription_items: {
+      item_price_id: [itemPriceId],
+      quantity: [1],
+    },
+    redirect_url: confirmationUrl,
+    cancel_url: cancelUrl,
+    pass_thru_content: metaData,
+  };
+
+  // Handle trial: if trial requested but product has no trial config in Chargebee,
+  // set trial_end explicitly. Otherwise let the item price's trial config handle it.
+  if (trial === false && product.trial?.days) {
+    // Explicitly skip trial by setting trial_end to 0
+    params.subscription = { trial_end: 0 };
+  }
+
+  // Apply discount coupon (first payment only)
+  if (chargebeeCouponId) {
+    params.coupon_ids = [chargebeeCouponId];
+  }
+
+  ctx.log(`Chargebee subscription checkout: itemPriceId=${itemPriceId}, uid=${uid}, trial=${trial}, coupon=${chargebeeCouponId || 'none'}`);
+
+  const result = await ChargebeeLib.request('/hosted_pages/checkout_new_for_items', {
+    method: 'POST',
+    body: params,
+  });
+
+  return result.hosted_page;
+}
+
+/**
+ * Create a Chargebee Hosted Page for a one-time charge
+ */
+async function createOneTimeCheckout({ ChargebeeLib, uid, orderId, product, productId, metaData, chargebeeCouponId, confirmationUrl, cancelUrl, ctx }) {
+  const price = product.prices?.once;
+
+  if (!price) {
+    throw new Error(`No one-time price configured for product ${productId}`);
+  }
+
+  // Amount in cents
+  const amountCents = Math.round(price * 100);
+
+  const params = {
+    charges: {
+      amount: [amountCents],
+      description: [product.name || productId],
+    },
+    redirect_url: confirmationUrl,
+    cancel_url: cancelUrl,
+    pass_thru_content: metaData,
+  };
+
+  // Apply discount coupon
+  if (chargebeeCouponId) {
+    params.coupon_ids = [chargebeeCouponId];
+  }
+
+  ctx.log(`Chargebee one-time checkout: amount=${amountCents}, productId=${productId}, uid=${uid}, coupon=${chargebeeCouponId || 'none'}`);
+
+  const result = await ChargebeeLib.request('/hosted_pages/checkout_one_time_for_items', {
+    method: 'POST',
+    body: params,
+  });
+
+  return result.hosted_page;
+}
+
+/**
+ * Resolve or create a Chargebee coupon for a discount code
+ * Uses a deterministic ID so the same code always maps to the same coupon
+ *
+ * A code is percent-based or amount-based, and Chargebee spells the second one
+ * `discount_type: 'fixed_amount'` with `discount_amount` in the currency's MINOR
+ * unit (cents — the same unit this file's one-time `charges.amount` uses) plus the
+ * `currency_code` it applies in. The two shapes carry different ids so a code can
+ * never collide with the other form, and the percent id is byte-identical to what
+ * it has always been, so coupons already live in a brand's site keep resolving
+ * ([#239](https://github.com/Omega-JS-Stack/omega/issues/239)).
+ *
+ * Verified against the params the API is asked to create, not against Chargebee:
+ * live-provider verification is a Stage 3 item, the same trust level as the rest
+ * of this provider ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ */
+async function resolveChargebeeCoupon(ChargebeeLib, discount, ctx) {
+  const isAmount = discount.amount > 0;
+  const currency = (ctx.Manager?.config?.payment?.currency || 'USD').toUpperCase();
+  const couponId = isAmount
+    ? `BEM_${discount.code}_${discount.amount}AMTOFF_ONCE`
+    : `BEM_${discount.code}_${discount.percent}OFF_ONCE`;
+
+  try {
+    // Check if coupon already exists
+    await ChargebeeLib.request(`/coupons/${couponId}`, { method: 'GET' });
+    ctx.log(`Chargebee coupon exists: ${couponId}`);
+    return couponId;
+  } catch (e) {
+    // Chargebee returns 404 for missing resources
+    if (e.status !== 404 && e.statusCode !== 404) {
+      throw e;
+    }
+  }
+
+  // Create the coupon
+  await ChargebeeLib.request('/coupons', {
+    method: 'POST',
+    body: {
+      id: couponId,
+      duration_type: 'one_time',
+      apply_on: 'invoice_amount',
+      ...(isAmount
+        ? {
+          name: `${discount.code} (${discount.amount.toFixed(2)} ${currency} off first payment)`,
+          discount_type: 'fixed_amount',
+          discount_amount: Math.round(discount.amount * 100),
+          currency_code: currency,
+        }
+        : {
+          name: `${discount.code} (${discount.percent}% off first payment)`,
+          discount_type: 'percentage',
+          discount_percentage: discount.percent,
+        }),
+    },
+  });
+
+  ctx.log(`Chargebee coupon created: ${couponId}`);
+  return couponId;
+}

package/dist/manager/routes/payments/intent/providers/coinbase.js

@@ -0,0 +1,94 @@
+/**
+ * Coinbase Commerce intent provider
+ * Creates a hosted CHARGE and hands back the page the buyer pays it on
+ *
+ * ONE-TIME ONLY ([#642](https://github.com/Omega-JS-Stack/omega/issues/642)):
+ * a Coinbase Commerce charge is a single payment at a single price. There is no
+ * subscription, plan or billing agreement in this API, so a subscription product
+ * is refused here rather than half-sold — the checkout hides the crypto button
+ * on a plan for the same reason.
+ */
+const { chargeableAmount } = require('../../../../libraries/payment/discount-codes.js');
+
+module.exports = {
+  /**
+   * Create a Coinbase Commerce payment intent (a hosted charge)
+   *
+   * @param {object} options
+   * @param {string} options.uid - User's UID
+   * @param {string} options.orderId - Internal order ID
+   * @param {object} options.product - Full product object from config
+   * @param {string} options.productId - Product ID from config (e.g., 'launch-kit')
+   * @param {object} options.discount - Validated discount result, or null
+   * @param {string} options.confirmationUrl - Success redirect URL
+   * @param {string} options.cancelUrl - Cancel redirect URL
+   * @param {object} options.ctx - Assistant instance for logging
+   * @returns {object} { id, url, raw }
+   */
+  async createIntent({ uid, orderId, product, productId, discount, confirmationUrl, cancelUrl, ctx }) {
+    const CoinbaseLib = require('../../../../libraries/payment/providers/coinbase.js');
+
+    const productType = product.type || 'subscription';
+
+    if (productType !== 'one-time') {
+      throw new Error(`Coinbase Commerce cannot sell ${product.id}: a crypto charge is a one-time payment and this product is a ${productType}`);
+    }
+
+    if (product.archived) {
+      throw new Error(`Product ${product.id} is archived`);
+    }
+
+    const listPrice = product.prices?.once;
+
+    if (!listPrice) {
+      throw new Error(`No one-time price configured for ${product.id}`);
+    }
+
+    // The charge is a FIXED price we compute, so a validated coupon has to come
+    // off here: a real provider applies it on its own hosted page, and Coinbase
+    // has no coupon object at all. Leaving it out would charge the full amount
+    // in crypto while the confirmation page — which discounts the same way, in
+    // routes/payments/intent/post.js — reported the discounted one. A code that
+    // covers the whole price is refused by that same helper before this charge
+    // is ever created: Coinbase Commerce does not take a $0.00 one
+    // ([#786](https://github.com/Omega-JS-Stack/omega/issues/786)).
+    const amount = chargeableAmount(listPrice, discount, { provider: 'Coinbase Commerce' });
+
+    const brandName = ctx.Manager?.config?.brand?.name || product.name || productId;
+
+    const chargeParams = {
+      name: product.name || productId,
+      description: product.description || brandName,
+      pricing_type: 'fixed_price',
+      local_price: {
+        amount: amount.toFixed(2),
+        currency: 'USD',
+      },
+      // Coinbase Commerce metadata is a flat string map, and it is the ONLY place
+      // this purchase's identifiers live — the webhook pipeline reads uid and
+      // orderId back off the charge it looks up
+      metadata: CoinbaseLib.buildMetadata(uid, orderId, productId),
+      redirect_url: confirmationUrl,
+      cancel_url: cancelUrl,
+    };
+
+    const result = await CoinbaseLib.request('/charges', {
+      method: 'POST',
+      body: chargeParams,
+    });
+
+    const charge = result.data || result;
+
+    if (!charge.hosted_url) {
+      throw new Error('Coinbase Commerce charge created but no hosted_url returned');
+    }
+
+    ctx.log(`Coinbase charge created: id=${charge.id}, code=${charge.code}, amount=${chargeParams.local_price.amount}, url=${charge.hosted_url}`);
+
+    return {
+      id: charge.id,
+      url: charge.hosted_url,
+      raw: charge,
+    };
+  },
+};