@omega.js/web 0.1.0

package/core/js/pages/payment/checkout/modules/tracking.js

@@ -0,0 +1,54 @@
+// Analytics tracking for the checkout page — one canonical fire per step; the
+// catalog decides which provider hears it, under which name, in which dialect
+// (#328), and the transport under it is guarded per provider (#306)
+import { event } from '__main_assets__/js/libs/analytics.js';
+import { calculatePrices } from './pricing.js';
+
+// What the funnel reports this checkout is worth: the LIST price of what is
+// being bought, before any code comes off it.
+//
+// calculatePrices() is the one place that knows every price shape a catalog can
+// carry — the cadence keys, the one-time `once` key, and the legacy
+// `amount`/`monthly` fallbacks — and its `subtotal` IS that list price. The
+// hand-rolled read this replaced never looked at `once`, so a product priced
+// `{ once: 49.99 }` sent `begin_checkout` and `add_payment_info` a value of 0
+// while `purchase` reported $49.99
+// ([#668](https://github.com/Omega-JS-Stack/omega/issues/668)).
+function getBasePrice(state) {
+  return calculatePrices(state).subtotal;
+}
+
+// Build common item array for tracking
+function buildItems(state, price) {
+  return [{
+    item_id: state.product.id,
+    item_name: state.product.name,
+    item_category: state.product.type === 'subscription' ? 'subscription' : 'one-time',
+    item_variant: state.frequency,
+    price: price,
+    quantity: 1,
+  }];
+}
+
+export function trackBeginCheckout(state) {
+  const price = getBasePrice(state);
+  const items = buildItems(state, price);
+
+  event('begin_checkout', {
+    currency: 'USD',
+    value: price,
+    items: items,
+  });
+}
+
+export function trackAddPaymentInfo(state, paymentMethod) {
+  const price = getBasePrice(state);
+  const items = buildItems(state, price);
+
+  event('add_payment_info', {
+    currency: 'USD',
+    value: price,
+    payment_type: paymentMethod,
+    items: items,
+  });
+}

package/core/js/pages/payment/confirmation/index.js

@@ -0,0 +1,91 @@
+// Payment Confirmation Page
+import { state, buildBindingsState } from './modules/state.js';
+import { trackPurchaseIfNeeded } from './modules/tracking.js';
+import { triggerCelebration } from './modules/celebration.js';
+import { verifyPurchase, initialStatus } from './modules/verify.js';
+import omega from '@omega.js/client';
+import { createLogger } from '__main_assets__/js/libs/logger.js';
+
+const logger = createLogger('confirmation');
+
+/* Test URL
+  https://localhost:3000/payment/confirmation?orderId=ORD-TRIAL-123&productId=pro&productName=Pro%20Plan&amount=0&currency=USD&frequency=annually&paymentMethod=stripe&trial=true&track=true
+*/
+
+// Module export
+export default () => {
+  return new Promise(async function (resolve) {
+    await omega.dom().ready();
+    await initializeConfirmation();
+    return resolve();
+  });
+};
+
+// Update UI via bindings (single source of truth)
+function updateUI() {
+  omega.bindings().update(buildBindingsState());
+}
+
+// Initialize confirmation page
+async function initializeConfirmation() {
+  // Parse URL params into state
+  parseUrlParams();
+
+  // Update UI with loaded data
+  updateUI();
+
+  // The browser half of the purchase (if the track=true param is present) —
+  // Meta's and TikTok's retargeting signal, deduped against the webhook's own
+  // fire (#386). The revenue TRUTH is the webhook's, always.
+  trackPurchaseIfNeeded(state);
+
+  // Subscribe to push notifications on CTA click (requires user gesture).
+  // Wired before the verification wait so the CTAs are live immediately.
+  document.querySelectorAll('.btn').forEach(($btn) => {
+    $btn.addEventListener('click', () => {
+      omega.notifications().subscribe().catch((e) => {
+        logger.warn('Notification subscribe failed:', e.message);
+      });
+    }, { once: true });
+  });
+
+  // The redirect is the provider's CLAIM; entitlement is granted by the
+  // webhook, which lands after the browser does — or never (#232). Hold the
+  // page in `processing` until the account itself carries the purchase. A
+  // purchase that opened already answered has no poll to wait on and nothing to
+  // wait for auth for — it rendered its receipt in the update above.
+  if (state.status === 'processing') {
+    await new Promise((resolve) => omega.auth().listen({ once: true }, resolve));
+
+    // ONE reveal: the update that answers the page is the update that brings
+    // the order details with it, and the celebration rides that same flip —
+    // numbers arriving seconds before the confetti read as broken (Ian's QA).
+    state.status = await verifyPurchase(state);
+    updateUI();
+
+    if (state.status !== 'confirmed') {
+      logger.warn(`Purchase not confirmed against the account state: orderId=${state.orderId}, product=${state.productId}`);
+      return;
+    }
+  }
+
+  // Trigger celebration animation — only for a purchase that really landed
+  await triggerCelebration();
+}
+
+// Parse URL parameters into minimal state
+function parseUrlParams() {
+  const urlParams = new URLSearchParams(window.location.search);
+
+  state.orderId = urlParams.get('orderId') || '';
+  state.productId = urlParams.get('productId') || '';
+  state.productName = urlParams.get('productName') || '';
+  state.amount = parseFloat(urlParams.get('amount') || 0);
+  state.currency = urlParams.get('currency') || 'USD';
+  state.type = urlParams.get('type') || '';
+  state.frequency = urlParams.get('frequency') || '';
+  state.paymentMethod = urlParams.get('paymentMethod') || '';
+  state.hasFreeTrial = urlParams.get('trial') === 'true';
+  state.status = initialStatus(state);
+  state.loaded = true;
+}

package/core/js/pages/payment/confirmation/modules/celebration.js

@@ -0,0 +1,45 @@
+// Celebration animation for confirmation page
+import omega from '@omega.js/client';
+
+// Trigger confetti celebration
+export async function triggerCelebration() {
+  try {
+    await omega.dom().loadScript({
+      src: 'https://cdn.jsdelivr.net/npm/canvas-confetti@1.9.2/dist/confetti.browser.min.js'
+    });
+
+    // Center burst
+    window.confetti({
+      particleCount: 100,
+      spread: 70,
+      origin: { y: 0.6 },
+      // Brand confetti: ocean accent + a festive hand-mixed set (legacy
+      // purple-era palette retired, Ian 2026-07-16)
+      colors: ['#2563eb', '#18b7cf', '#21c07c', '#efa312', '#e4572e'],
+    });
+
+    // Left side burst
+    setTimeout(() => {
+      window.confetti({
+        particleCount: 50,
+        angle: 60,
+        spread: 55,
+        origin: { x: 0 },
+        colors: ['#2563eb', '#18b7cf', '#21c07c'],
+      });
+    }, 250);
+
+    // Right side burst
+    setTimeout(() => {
+      window.confetti({
+        particleCount: 50,
+        angle: 120,
+        spread: 55,
+        origin: { x: 1 },
+        colors: ['#21c07c', '#efa312', '#e4572e'],
+      });
+    }, 400);
+  } catch (error) {
+    console.log('Confetti library failed to load:', error);
+  }
+}

package/core/js/pages/payment/confirmation/modules/state.js

@@ -0,0 +1,112 @@
+// State management for confirmation page
+// Minimal mutable state -- everything else is derived by buildBindingsState()
+
+import { FREQUENCIES, ONE_TIME_FREQUENCY } from '../../checkout/modules/state.js';
+
+// Minimal mutable state
+export const state = {
+  // Raw values from URL params (never formatted)
+  orderId: '',
+  productId: '',
+  productName: '',
+  amount: 0,
+  currency: 'USD',
+  // What was bought, straight off the redirect the intent route builds
+  // ('subscription' | 'one-time'): the one thing here that does not have to be
+  // inferred from the cadence beside it (#668)
+  type: '',
+  frequency: '',
+  paymentMethod: '',
+  hasFreeTrial: false,
+
+  // Whether the purchase has actually landed in the account yet (#232). The
+  // page opens UNSURE — the redirect is the provider's claim, and the webhook
+  // that grants entitlement arrives after the browser does.
+  // 'processing' | 'confirmed' | 'timeout'
+  status: 'processing',
+
+  // UI state
+  loaded: false,
+};
+
+// Build the complete bindings state from minimal state
+// Returns a fresh object every time -- no mutation of shared references
+export function buildBindingsState() {
+  // Only the cadences checkout SELLS renew (#282). A one-time buy arrives as
+  // `frequency=once`, which reading `!!state.frequency` called a subscription:
+  // every one-time receipt got the subscription sentence with its cycle slots
+  // empty, because `once` is not a cadence and the map below has no row for it.
+  // The same list decides what verify.js can poll the account for (#232).
+  const isSubscription = FREQUENCIES.includes(state.frequency);
+  const isOneTime = state.frequency === ONE_TIME_FREQUENCY;
+
+  const FREQUENCY_MAP = {
+    // `cycle` is the adverb ("charged annually"); `adjective` is the noun
+    // modifier ("annual subscription") — "annually subscription" was the tell.
+    daily: { cycle: 'daily', adjective: 'daily', period: 'day' },
+    weekly: { cycle: 'weekly', adjective: 'weekly', period: 'week' },
+    monthly: { cycle: 'monthly', adjective: 'monthly', period: 'month' },
+    annually: { cycle: 'annually', adjective: 'annual', period: 'year' },
+  };
+  const freq = FREQUENCY_MAP[state.frequency] || { cycle: '', adjective: '', period: '' };
+  const billingCycleText = freq.cycle;
+  const billingAdjectiveText = freq.adjective;
+  const billingPeriodText = freq.period;
+
+  // Build subscription info text
+  let subscriptionInfoText = '';
+  if (isSubscription) {
+    if (state.hasFreeTrial) {
+      subscriptionInfoText = `Free Trial Active! Your trial period has begun. You'll be charged ${billingCycleText} after the trial ends.`;
+    } else {
+      subscriptionInfoText = `Your ${billingAdjectiveText} subscription is now active. You'll be charged automatically each ${billingPeriodText}.`;
+    }
+  }
+
+  // The one-time buy's own note: what it needs to hear is that nothing else is
+  // coming, which is the opposite of everything the subscription copy says.
+  const purchaseInfoText = isOneTime
+    ? 'This is a one-time purchase. There is nothing to renew and nothing to cancel.'
+    : '';
+
+  return {
+    confirmation: {
+      order: {
+        id: state.orderId || 'Loading...',
+        // "Plan" is subscription language on a one-time buy (#282)
+        itemLabel: isOneTime ? 'Item' : 'Plan',
+        productName: state.productName || state.productId || 'Product',
+        total: formatCurrency(state.amount),
+        currency: state.currency,
+      },
+      subscription: {
+        // "Your subscription is now active" is a claim about the account, so it
+        // waits for the account to say so (#232)
+        show: isSubscription && state.status === 'confirmed',
+        hasFreeTrial: state.hasFreeTrial,
+        billingCycle: billingCycleText,
+        infoText: subscriptionInfoText,
+      },
+      purchase: {
+        // The same gate the subscription note sits behind: a note about what
+        // was bought waits until the purchase is known to have landed (#232)
+        show: isOneTime && state.status === 'confirmed',
+        infoText: purchaseInfoText,
+      },
+      // Which of the three moments the page is rendering (#232). Only
+      // `confirmed` may say the words "payment received".
+      verification: {
+        processing: state.status === 'processing',
+        confirmed: state.status === 'confirmed',
+        timedOut: state.status === 'timeout',
+      },
+      loaded: state.loaded,
+    },
+  };
+}
+
+// Format a number as currency, or return placeholder
+function formatCurrency(amount) {
+  if (amount == null || isNaN(amount)) return '$--';
+  return `$${Number(amount).toFixed(2)}`;
+}

package/core/js/pages/payment/confirmation/modules/tracking.js

@@ -0,0 +1,133 @@
+// The confirmation page's conversion PIXEL — the browser half of the checkout
+// ([#386](https://github.com/Omega-JS-Stack/omega/issues/386)).
+//
+// The backend's payment webhook is the TRUTH: it sees what the provider actually
+// charged. What only a browser can give is the RETARGETING signal — Meta's and
+// TikTok's pixels tie the conversion to the ad click sitting in this page's
+// cookies — and, for GA4, the session, the campaign and the client id a webhook
+// has none of.
+//
+// TWO THINGS THIS HALF GETS RIGHT, both found on 2026-08-27:
+//
+//  1. A TRIAL CHECKOUT IS NOT A PURCHASE
+//     ([#654](https://github.com/Omega-JS-Stack/omega/issues/654)). The intent
+//     route sets `?track=true` for EVERY checkout, trials included, so a $0 trial
+//     used to fire a browser `purchase` while the webhook fired `trial_start`.
+//     The AMOUNT was never the defect — the intent route already puts `amount=0`
+//     on a trial confirmation URL (`routes/payments/intent/post.js`) — the NAME
+//     was: two different event names never deduplicate, so each platform counted
+//     the browser half as a second conversion beside the server's trial. A trial
+//     order fires `trial_start` with value 0; everything else fires `purchase`.
+//  2. GA4 BELONGS ON THE PURCHASE HALF
+//     ([#656](https://github.com/Omega-JS-Stack/omega/issues/656)). GA4
+//     deduplicates `purchase` on `transaction_id`
+//     (https://support.google.com/analytics/answer/12313109), and both halves
+//     send the ORDER id — so the browser adds its attribution and GA4 still
+//     counts one purchase. `trial_start` is a GA4 CUSTOM event with no such
+//     dedupe, so its browser half names the ad platforms only and the server
+//     keeps GA4 to itself.
+//
+// Both halves carry the SAME dedupe id, or each platform counts two conversions:
+//
+//   THE DEDUPE ID IS `<canonical>.<order id>`
+//
+// which is the ORDER-ID branch of the backend's own derivation
+// (`events/firestore/payments-webhooks/analytics.js` resolveEventId keys the two
+// browser-twinned events, `purchase` and `trial_start`, on the order — the only
+// id a browser can compute).
+import omega from '@omega.js/client';
+import { event } from '__main_assets__/js/libs/analytics.js';
+import { FREQUENCIES, ONE_TIME_FREQUENCY } from '../../checkout/modules/state.js';
+
+// Build the canonical items array for the purchase.
+//
+// The category comes from WHAT WAS BOUGHT, and the redirect the intent route
+// builds now says so outright — `type=subscription|one-time`, the one field here
+// that needs no inferring ([#668](https://github.com/Omega-JS-Stack/omega/issues/668)).
+// The cadence is the FALLBACK, for a confirmation URL minted before the type was
+// sent: reading the truthiness of the frequency string called every one-time buy a
+// subscription, because checkout sends `frequency=once` for one (#282 is the same
+// bug in the receipt copy), so the fallback reads FREQUENCIES — the cadences
+// checkout actually SELLS, the same list the bindings and the verification poll
+// read. A stale link that carries a cadence for a one-time product (the live buy
+// reached this file as `frequency=annually`) is classified by the type regardless.
+//
+// `price` is the conversion's own amount, passed in rather than read off the
+// state: the intent route already sends `amount=0` on a trial checkout, so this
+// default and the trial's explicit 0 agree today. DEFENSIVE — the conversion's
+// value has ONE source in this file, so a confirmation URL that ever carried the
+// plan's price on a trial could not put it on the item either ([#654]).
+export function buildItems(state, price = state.amount) {
+  const isSubscription = state.type
+    ? state.type === 'subscription'
+    : FREQUENCIES.includes(state.frequency);
+
+  return [{
+    item_id: state.productId,
+    item_name: state.productName || state.productId,
+    item_category: isSubscription ? 'subscription' : 'one-time',
+    item_variant: isSubscription ? state.frequency : ONE_TIME_FREQUENCY,
+    price: price,
+    quantity: 1,
+  }];
+}
+
+// Fire the canonical conversion for this order — see the header for which.
+function trackPurchase(state) {
+  const canonical = state.hasFreeTrial ? 'trial_start' : 'purchase';
+  // A trial charges nothing. The intent route already sends `amount=0` for one,
+  // so this is DEFENSIVE: the value a trial reports is 0 here whatever the
+  // confirmation URL says ([#654]).
+  const value = state.hasFreeTrial ? 0 : state.amount;
+
+  event(canonical, {
+    // The same id the webhook sends, and the key GA4 collapses the two halves on.
+    transaction_id: state.orderId,
+    value: value,
+    currency: state.currency,
+    items: buildItems(state, value),
+    payment_provider: state.paymentMethod,
+    payment_frequency: state.frequency,
+    is_trial: state.hasFreeTrial,
+  }, {
+    // GA4 rides the purchase half (it dedupes on transaction_id) but never the
+    // trial half, where its event is custom and the server owns it outright.
+    providers: state.hasFreeTrial ? ['meta', 'tiktok'] : ['ga4', 'meta', 'tiktok'],
+    eventId: `${canonical}.${state.orderId}`,
+  });
+}
+
+// Track purchase only if the track=true URL param is present
+// Removes the param after tracking to prevent duplicates on refresh
+// Also stores orderId in omega storage as a backup guard
+export function trackPurchaseIfNeeded(state) {
+  const urlParams = new URLSearchParams(window.location.search);
+  const shouldTrack = urlParams.get('track') === 'true';
+
+  if (!shouldTrack) {
+    return;
+  }
+
+  // Track the purchase
+  trackPurchase(state);
+
+  // Remove 'track' param from URL to prevent re-tracking on refresh
+  urlParams.delete('track');
+  const newUrl = urlParams.toString()
+    ? `${window.location.pathname}?${urlParams.toString()}`
+    : window.location.pathname;
+  window.history.replaceState({}, document.title, newUrl);
+
+  // Backup: store orderId in storage
+  const trackedOrders = omega.storage().get('trackedPurchases', []);
+  if (!trackedOrders.includes(state.orderId)) {
+    trackedOrders.push(state.orderId);
+
+    // Keep only last 50 orders
+    if (trackedOrders.length > 50) {
+      trackedOrders.shift();
+    }
+
+    omega.storage().set('trackedPurchases', trackedOrders);
+  }
+}

package/core/js/pages/payment/confirmation/modules/verify.js

@@ -0,0 +1,142 @@
+// Has the purchase the redirect claims actually LANDED? (#232)
+//
+// Entitlement is granted by the payment webhook, which arrives AFTER the
+// provider has redirected the browser here — usually a second or two later,
+// sometimes never (a declined charge, an undelivered webhook in local dev). The
+// redirect's URL params are the provider's claim, not proof, so the page asks
+// the account itself before it congratulates anyone.
+import omega from '@omega.js/client';
+import { createLogger } from '__main_assets__/js/libs/logger.js';
+import { FREQUENCIES } from '../../checkout/modules/state.js';
+
+const logger = createLogger('confirmation');
+
+// How often to ask, and how long before pointing the customer at support.
+export const POLL_INTERVAL_MS = 2000;
+export const POLL_TIMEOUT_MS = 30000;
+
+/**
+ * Is this a purchase whose landing the account doc can actually prove?
+ *
+ * Only the billing cadences checkout sells (`FREQUENCIES`) write account
+ * state to wait for. A one-time purchase arrives as `frequency=once` and
+ * writes nothing to the account doc — the receipt is the whole answer there.
+ *
+ * The product TYPE the redirect carries is the second guard, and it outranks
+ * the cadence: a checkout that sent the wrong frequency (`type=one-time,
+ * frequency=annually`, [#668](https://github.com/Omega-JS-Stack/omega/issues/668))
+ * had this page polling for a plan the purchase never writes, all the way to
+ * the timeout, on a payment that had completed cleanly. A redirect old enough
+ * to carry no type at all still answers on the cadence alone.
+ */
+export function isVerifiable(state) {
+  if (state?.type && state.type !== 'subscription') {
+    return false;
+  }
+
+  return FREQUENCIES.includes(state?.frequency);
+}
+
+/**
+ * The moment the page OPENS in.
+ *
+ * A purchase with a poll behind it opens UNSURE — nothing about the order may
+ * render until the account answers, or the receipt sits on screen beside a
+ * spinner and reads as broken (Ian's QA). One with no poll — a one-time buy the
+ * account doc never records — is already answered, so it renders at once.
+ *
+ * @param {object} state - the confirmation page state (frequency)
+ * @returns {'processing'|'confirmed'}
+ */
+export function initialStatus(state) {
+  return isVerifiable(state) ? 'processing' : 'confirmed';
+}
+
+/**
+ * Does this account carry the purchase that was just made?
+ *
+ * The account doc is the only purchase state a browser may read — `payments-orders`
+ * is admin-only by security rule — and it is exactly what the subscription
+ * webhook writes. The plan has to MATCH: a user who already held one plan while
+ * buying another must not be confirmed by the plan they walked in with.
+ *
+ * @param {object|null} account - the user doc, or null when there is none
+ * @param {string} productId - the plan the redirect says was bought
+ */
+export function purchaseLanded(account, productId) {
+  // No account doc is no ANSWER, never a yes — and it must not be asked about
+  // either: the client's `resolveSubscription(account)` falls back to the STORED
+  // auth state when it is handed nothing, so a null read would be answered out
+  // of localStorage with the plan the shopper walked in with.
+  if (!account) {
+    return false;
+  }
+
+  const resolved = omega.auth().resolveSubscription(account);
+
+  if (!resolved.active) {
+    return false;
+  }
+
+  return !productId || resolved.plan === productId;
+}
+
+// Read the buyer's own account doc.
+async function readAccount() {
+  const user = omega.auth().getUser();
+
+  if (!user) {
+    return null;
+  }
+
+  const snapshot = await omega.firestore().doc(`users/${user.uid}`).get();
+
+  return snapshot.exists() ? snapshot.data() : null;
+}
+
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Ask until the purchase is real, or the budget runs out.
+ *
+ * Every I/O seam is injected so the loop itself is unit-testable at full speed.
+ *
+ * @param {object} state - the confirmation page state (productId, frequency)
+ * @param {object} [seams] - read/sleep/now/interval/timeout overrides
+ * @returns {Promise<'confirmed'|'timeout'>}
+ */
+export async function verifyPurchase(state, {
+  read = readAccount,
+  sleep = wait,
+  now = () => Date.now(),
+  intervalMs = POLL_INTERVAL_MS,
+  timeoutMs = POLL_TIMEOUT_MS,
+} = {}) {
+  if (!isVerifiable(state)) {
+    return 'confirmed';
+  }
+
+  const deadline = now() + timeoutMs;
+
+  while (true) {
+    let account = null;
+
+    try {
+      account = await read();
+    } catch (e) {
+      // A read that FAILED is no answer, not a NO — the webhook may still be in
+      // flight behind a network blip. Keep asking; the budget decides.
+      logger.warn(`Could not read the account while confirming the purchase: ${e.message}`);
+    }
+
+    if (purchaseLanded(account, state.productId)) {
+      return 'confirmed';
+    }
+
+    if (now() >= deadline) {
+      return 'timeout';
+    }
+
+    await sleep(intervalMs);
+  }
+}