@omega.js/backend 0.1.0

package/dist/manager/routes/payments/cancel/providers/stripe.js

@@ -0,0 +1,33 @@
+const isTrialing = require('../_is-trialing.js');
+
+/**
+ * Stripe cancel provider
+ * Cancels a subscription — immediately if trialing, at period end otherwise.
+ */
+module.exports = {
+  /**
+   * Cancel a Stripe subscription
+   *
+   * If the subscription is currently trialing, cancel immediately to avoid
+   * giving free premium access for the remainder of the trial.
+   * Otherwise, cancel at the end of the current billing period.
+   *
+   * @param {object} options
+   * @param {string} options.resourceId - Stripe subscription ID (e.g., 'sub_xxx')
+   * @param {string} options.uid - User's UID (for logging)
+   * @param {object} options.subscription - User's current subscription object
+   * @param {object} options.ctx - Assistant instance for logging
+   */
+  async cancelAtPeriodEnd({ resourceId, uid, subscription, ctx }) {
+    const StripeLib = require('../../../../libraries/payment/providers/stripe.js');
+    const stripe = StripeLib.init();
+
+    if (isTrialing(subscription)) {
+      await stripe.subscriptions.cancel(resourceId);
+      ctx.log(`Stripe cancel immediate (trialing): sub=${resourceId}, uid=${uid}`);
+    } else {
+      await stripe.subscriptions.update(resourceId, { cancel_at_period_end: true });
+      ctx.log(`Stripe cancel at period end: sub=${resourceId}, uid=${uid}`);
+    }
+  },
+};

package/dist/manager/routes/payments/cancel/providers/test.js

@@ -0,0 +1,118 @@
+const powertools = require('node-powertools');
+const isTrialing = require('../_is-trialing.js');
+
+/**
+ * Test cancel provider
+ * Simulates the Stripe webhook that results from cancellation
+ * by writing directly to payments-webhooks/{eventId} with status=pending.
+ * The on-write trigger picks it up and runs the full pipeline.
+ *
+ * If the user is trialing, simulates immediate cancellation (customer.subscription.deleted).
+ * Otherwise, simulates cancel at period end (customer.subscription.updated with cancel_at_period_end=true).
+ *
+ * Only available in non-production environments.
+ */
+module.exports = {
+  async cancelAtPeriodEnd({ resourceId, uid, subscription, ctx }) {
+    if (ctx.isProduction()) {
+      throw new Error('Test provider is not available in production');
+    }
+
+    const admin = ctx.Manager.libraries.admin;
+
+    const timestamp = Date.now();
+    const now = Math.floor(timestamp / 1000);
+    const periodEnd = now + (30 * 86400);
+
+    // Look up the Stripe product ID for the plan so resolveProduct() can match.
+    // The order doc is the first source; when there is no order (a seeded paid persona, or
+    // any state where the order is missing) the subscription's own product is the fallback —
+    // without it the plan carries product=null and the pipeline downgrades the user to Basic
+    // mid-cancel instead of scheduling the cancellation.
+    const orderId = subscription?.payment?.orderId;
+    let productId = null;
+
+    if (orderId) {
+      const orderDoc = await admin.firestore().doc(`payments-orders/${orderId}`).get();
+      if (orderDoc.exists) {
+        productId = orderDoc.data().unified?.product?.id || null;
+      }
+    }
+
+    productId = productId || subscription?.product?.id || null;
+
+    // Falls back to the "_test_<id>" sentinel when no real Stripe product is configured.
+    const products = ctx.Manager.config.payment?.products || [];
+    const product = products.find(p => p.id === productId);
+    const stripeProductId = product
+      ? (product.stripe?.productId || `_test_${product.id}`)
+      : null;
+
+    // Detect if user is on a trial
+    const trialing = isTrialing(subscription);
+
+    // Trialing: immediate cancel (customer.subscription.deleted)
+    // Non-trialing: cancel at period end (customer.subscription.updated)
+    const eventType = trialing
+      ? 'customer.subscription.deleted'
+      : 'customer.subscription.updated';
+    const eventId = `_test-evt-cancel-${timestamp}`;
+
+    const subscriptionObj = {
+      id: resourceId,
+      object: 'subscription',
+      status: trialing ? 'canceled' : 'active',
+      // A seeded persona may have no order; Firestore rejects undefined outright.
+      metadata: { uid, orderId: orderId || null },
+      cancel_at_period_end: !trialing,
+      cancel_at: trialing ? now : periodEnd,
+      canceled_at: trialing ? now : null,
+      current_period_end: trialing ? now : periodEnd,
+      current_period_start: now - (30 * 86400),
+      start_date: now - (30 * 86400),
+      trial_start: trialing ? (now - 86400) : null,
+      trial_end: trialing ? now : null,
+      plan: { product: stripeProductId, interval: 'month' },
+    };
+
+    const nowTs = powertools.timestamp(new Date(), { output: 'string' });
+    const nowUNIX = powertools.timestamp(nowTs, { output: 'unix' });
+
+    // Write directly to payments-webhooks — on-write trigger handles the rest
+    await admin.firestore().doc(`payments-webhooks/${eventId}`).set({
+      id: eventId,
+      provider: 'test',
+      status: 'pending',
+      owner: uid,
+      raw: {
+        id: eventId,
+        type: eventType,
+        data: { object: subscriptionObj },
+      },
+      event: {
+        type: eventType,
+        category: 'subscription',
+        resourceType: 'subscription',
+        resourceId: resourceId,
+      },
+      error: null,
+      // The SAME keys the webhook route writes ([../../webhook/post.js]) — the
+      // pipeline's staleness clock reads `metadata.created.timestampUNIX`, so a
+      // synthetic doc spelling it `received` handed the clock nothing and rode a
+      // now-fallback that made every test-processor event look freshly arrived
+      // ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+      metadata: {
+        created: {
+          timestamp: nowTs,
+          timestampUNIX: nowUNIX,
+        },
+        completed: {
+          timestamp: null,
+          timestampUNIX: null,
+        },
+      },
+    });
+
+    ctx.log(`Test cancel provider: wrote payments-webhooks/${eventId} (${eventType}) for sub=${resourceId}, uid=${uid}, trialing=${trialing}`);
+  },
+};

package/dist/manager/routes/payments/discount/get.js

@@ -0,0 +1,25 @@
+/**
+ * GET /payments/discount?code=FLASH20
+ * Validates a discount code and returns the discount details
+ */
+const discountCodes = require('../../../libraries/payment/discount-codes.js');
+
+module.exports = async ({ ctx, user, settings }) => {
+  const result = discountCodes.validate(settings.code, user.authenticated ? user : undefined);
+
+  ctx.log(`Discount validation: code=${result.code}, valid=${result.valid}`);
+
+  if (!result.valid) {
+    return ctx.respond({ valid: false }, { code: 200 });
+  }
+
+  // A code is percent-based or amount-based (Stripe's two coupon shapes) — the
+  // caller reads whichever field is present
+  return ctx.respond({
+    valid: true,
+    code: result.code,
+    percent: result.percent,
+    amount: result.amount,
+    duration: result.duration,
+  });
+};

package/dist/manager/routes/payments/dispute-alert/post.js

@@ -0,0 +1,117 @@
+const path = require('path');
+const loadProvider = require('../../../libraries/load-provider.js');
+const powertools = require('node-powertools');
+const safeCompare = require('../../../helpers/safe-compare.js');
+const env = require('../../../libraries/env.js');
+
+/**
+ * POST /payments/dispute-alert?provider=chargeblast&key=XXX
+ * Receives dispute alert webhooks (e.g., from Chargeblast), validates them,
+ * and saves to Firestore for async processing via onWrite trigger
+ *
+ * Query params:
+ *   - provider: alert provider name (default: 'chargeblast')
+ *   - key: must match OMEGA_WEBHOOK_KEY
+ *
+ * This handler is provider-agnostic. Each provider module defines:
+ *   - normalize(body) — extracts the standard dispute alert shape
+ */
+module.exports = async ({ ctx, Manager, libraries }) => {
+  const { admin } = libraries;
+  const body = ctx.request.body;
+  const query = ctx.request.query;
+
+  // Validate key
+  const key = query.key;
+  if (!safeCompare(key, env.get('OMEGA_WEBHOOK_KEY'))) {
+    return ctx.respond('Invalid key', { code: 401 });
+  }
+
+  // Determine alert provider (default: chargeblast)
+  const provider = query.provider || 'chargeblast';
+
+  // Load the provider module
+  let providerModule;
+  try {
+    providerModule = loadProvider(path.join(__dirname, 'providers'), provider);
+  } catch (e) {
+    return ctx.respond(`Unknown alert provider: ${provider}`, { code: 400 });
+  }
+
+  // Normalize the payload using the provider
+  let alert;
+  try {
+    alert = providerModule.normalize(body);
+  } catch (e) {
+    return ctx.respond(`Failed to normalize alert: ${e.message}`, { code: 400 });
+  }
+
+  const alertId = alert.id;
+
+  ctx.log(`Parsed dispute alert: id=${alertId}, alertProvider=${provider}, paymentProvider=${alert.provider}, amount=${alert.amount}, card=****${alert.card.last4}`);
+
+  // Build timestamps
+  const now = powertools.timestamp(new Date(), { output: 'string' });
+  const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+  // Claim the alert, then save — in ONE transaction, for the same reason the
+  // webhook route does: a read followed by a separate write leaves a window
+  // where two same-instant deliveries both see no doc and both write, and a
+  // dispute processed twice means two refunds ([#212]).
+  const docRef = admin.firestore().doc(`payments-disputes/${alertId}`);
+  const claimed = await admin.firestore().runTransaction(async (transaction) => {
+    const existingDoc = await transaction.get(docRef);
+
+    if (existingDoc.exists) {
+      const existingStatus = existingDoc.data()?.status;
+
+      // A failed alert is the one state that may be reclaimed — that IS the retry path
+      if (existingStatus !== 'failed') {
+        return { claimed: false, status: existingStatus };
+      }
+    }
+
+    // Save with status=pending (trigger handles the rest)
+    transaction.set(docRef, {
+      id: alertId,
+      provider: provider,
+      status: 'pending',
+      alert: alert,
+      match: null,
+      actions: {
+        refund: 'pending',
+        cancel: 'pending',
+        email: 'pending',
+      },
+      errors: [],
+      error: null,
+      metadata: {
+        created: {
+          timestamp: now,
+          timestampUNIX: nowUNIX,
+        },
+        completed: {
+          timestamp: null,
+          timestampUNIX: null,
+        },
+      },
+      raw: body,
+    });
+
+    return { claimed: true, retried: existingDoc.exists };
+  });
+
+  if (!claimed.claimed) {
+    ctx.log(`Duplicate dispute alert ${alertId}, existing status=${claimed.status}, skipping`);
+    return ctx.respond({ received: true, duplicate: true });
+  }
+
+  if (claimed.retried) {
+    ctx.log(`Retrying previously failed dispute alert ${alertId}`);
+  }
+
+  ctx.log(`Saved payments-disputes/${alertId}: alertProvider=${provider}, paymentProvider=${alert.provider}`);
+
+  // Return 200 immediately — async processing via Firestore trigger
+  return ctx.respond({ received: true });
+};

package/dist/manager/routes/payments/dispute-alert/providers/chargeblast.js

@@ -0,0 +1,55 @@
+/**
+ * Chargeblast dispute alert provider
+ * Normalizes Chargeblast webhook payloads into a standard dispute alert shape
+ *
+ * Chargeblast sends two event types:
+ *   alert.created: id, card, cardBrand, amount, transactionDate, processor, etc.
+ *   alert.updated: same + externalOrder (charge ID), metadata (payment intent), customerEmail, etc.
+ */
+
+module.exports = {
+  /**
+   * Normalize a Chargeblast webhook payload
+   *
+   * @param {object} body - Raw request body from Chargeblast
+   * @returns {object} Normalized dispute alert
+   */
+  normalize(body) {
+    if (!body.id && !body.alertId) {
+      throw new Error('Missing required field: id');
+    }
+    if (!body.card) {
+      throw new Error('Missing required field: card');
+    }
+    if (!body.amount && body.amount !== 0) {
+      throw new Error('Missing required field: amount');
+    }
+    if (!body.transactionDate) {
+      throw new Error('Missing required field: transactionDate');
+    }
+
+    const cardStr = String(body.card);
+
+    return {
+      id: String(body.id || body.alertId),
+      card: {
+        last4: cardStr.slice(-4),
+        brand: body.cardBrand ? String(body.cardBrand).toLowerCase() : null,
+      },
+      amount: parseFloat(body.amount),
+      transactionDate: String(body.transactionDate).split(' ')[0], // date only, no time
+      // `processor` and `subprovider` are CHARGEBLAST's own payload field names —
+      // read verbatim, normalized onto our `provider` word on the way out (#428)
+      provider: body.processor ? String(body.processor).toLowerCase() : 'stripe',
+      alertType: body.alertType || null,
+      customerEmail: body.customerEmail || null,
+      // Stripe-specific IDs provided by Chargeblast on alert.updated events
+      chargeId: body.externalOrder || null,
+      paymentIntentId: body.metadata || null,
+      stripeUrl: body.externalUrl || null,
+      reasonCode: body.reasonCode || null,
+      subprovider: body.subprovider || null,
+      isRefunded: body.isRefunded || false,
+    };
+  },
+};