@omega.js/backend 0.1.0

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

@@ -0,0 +1,147 @@
+/**
+ * Chargebee refund provider
+ * Issues a refund for the latest invoice and cancels the subscription immediately.
+ *
+ * Refund amount:
+ * - Full refund if the last payment was ≤7 days ago
+ * - Prorated refund (based on days remaining in billing period) if >7 days ago
+ *
+ * Chargebee refunds are issued on invoices via POST /invoices/{id}/refund.
+ * After refunding, the subscription is cancelled immediately.
+ *
+ * A one-time purchase is its own non-recurring invoice, refunded in full.
+ */
+const { FULL_REFUND_DAYS } = require('../../../../libraries/payment/refund-policy.js');
+
+module.exports = {
+  /**
+   * Process a refund for a Chargebee subscription
+   *
+   * @param {object} options
+   * @param {string} options.resourceId - Chargebee subscription ID
+   * @param {string} options.uid - User's UID (for logging)
+   * @param {object} options.subscription - User's subscription object from Firestore
+   * @param {object} options.ctx - Assistant instance for logging
+   * @returns {{ amount: number, currency: string, full: boolean }}
+   */
+  async processRefund({ resourceId, uid, ctx }) {
+    const ChargebeeLib = require('../../../../libraries/payment/providers/chargebee.js');
+    ChargebeeLib.init();
+
+    // 1. Retrieve subscription
+    const subResult = await ChargebeeLib.request(`/subscriptions/${resourceId}`);
+    const sub = subResult.subscription;
+
+    // 2. Find the latest paid invoice for this subscription
+    const invoiceResult = await ChargebeeLib.request(
+      `/invoices?subscription_id[is]=${encodeURIComponent(resourceId)}&status[is]=paid&sort_by[desc]=date&limit=1`,
+    );
+
+    const invoices = invoiceResult.list || [];
+
+    if (invoices.length === 0) {
+      throw new Error('No paid invoice found for this subscription');
+    }
+
+    const invoice = invoices[0].invoice;
+    const invoiceAmountCents = invoice.amount_paid || invoice.total || 0;
+
+    if (invoiceAmountCents <= 0) {
+      throw new Error('No refundable amount on the latest invoice');
+    }
+
+    // 3. Calculate refund amount
+    const invoicePaidAt = invoice.paid_at || invoice.date;
+    const daysSincePayment = (Date.now() / 1000 - invoicePaidAt) / 86400;
+
+    let refundAmountCents;
+    let isFullRefund;
+
+    if (daysSincePayment <= FULL_REFUND_DAYS) {
+      refundAmountCents = invoiceAmountCents;
+      isFullRefund = true;
+    } else {
+      // Prorated: remaining days / total days * amount
+      const periodStart = sub.current_term_start || invoice.date;
+      const periodEnd = sub.current_term_end || (invoice.date + 86400 * 30);
+      const totalDays = (periodEnd - periodStart) / 86400;
+      const daysRemaining = Math.max(0, (periodEnd - Date.now() / 1000) / 86400);
+
+      refundAmountCents = Math.round((daysRemaining / totalDays) * invoiceAmountCents);
+      isFullRefund = false;
+    }
+
+    if (refundAmountCents <= 0) {
+      throw new Error('No refundable amount remaining');
+    }
+
+    // 4. Issue refund on the invoice
+    await ChargebeeLib.request(`/invoices/${invoice.id}/refund`, {
+      method: 'POST',
+      body: { refund_amount: refundAmountCents },
+    });
+
+    const currency = invoice.currency_code || 'USD';
+
+    ctx.log(`Chargebee refund issued: invoiceId=${invoice.id}, amount=${refundAmountCents}, full=${isFullRefund}, uid=${uid}`);
+
+    // 5. Cancel subscription immediately (if not already cancelled)
+    if (sub.status !== 'cancelled') {
+      await ChargebeeLib.request(`/subscriptions/${resourceId}/cancel_for_items`, {
+        method: 'POST',
+        body: { cancel_option: 'immediately' },
+      });
+      ctx.log(`Chargebee subscription cancelled immediately: sub=${resourceId}, uid=${uid}`);
+    }
+
+    return {
+      amount: refundAmountCents / 100,
+      currency: currency.toLowerCase(),
+      full: isFullRefund,
+    };
+  },
+
+  /**
+   * Process a refund for a Chargebee ONE-TIME purchase
+   *
+   * A one-time purchase is a non-recurring INVOICE, and Chargebee issues refunds
+   * on invoices — the same call the subscription path makes, against the order's
+   * own invoice. Always FULL: a one-time purchase buys no billing period, so
+   * there is nothing to prorate over
+   * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+   *
+   * @param {object} options
+   * @param {string} options.resourceId - Chargebee invoice ID
+   * @param {string} options.uid - User's UID (for logging)
+   * @param {object} options.order - The payments-orders doc being refunded
+   * @param {object} options.ctx - Assistant instance for logging
+   * @returns {{ amount: number, currency: string, full: boolean }}
+   */
+  async processOneTimeRefund({ resourceId, uid, order, ctx }) {
+    const ChargebeeLib = require('../../../../libraries/payment/providers/chargebee.js');
+    ChargebeeLib.init();
+
+    const invoiceResult = await ChargebeeLib.request(`/invoices/${resourceId}`);
+    const invoice = invoiceResult.invoice;
+    const amountCents = invoice?.amount_paid || 0;
+
+    if (amountCents <= 0) {
+      throw new Error('No refundable amount on this purchase');
+    }
+
+    await ChargebeeLib.request(`/invoices/${resourceId}/refund`, {
+      method: 'POST',
+      body: { refund_amount: amountCents },
+    });
+
+    const currency = invoice.currency_code || 'USD';
+
+    ctx.log(`Chargebee one-time refund issued: invoiceId=${resourceId}, amount=${amountCents}, orderId=${order?.id}, uid=${uid}`);
+
+    return {
+      amount: amountCents / 100,
+      currency: currency.toLowerCase(),
+      full: true,
+    };
+  },
+};

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

@@ -0,0 +1,40 @@
+/**
+ * Coinbase Commerce refund provider — the explicit UNSUPPORTED one.
+ *
+ * Coinbase Commerce has no refund API. Returning crypto is a transfer the
+ * merchant makes by hand from the dashboard, at whatever the coin is worth that
+ * day, and nothing about it is ever attached to the charge — so there is no call
+ * this file could make and no amount it could report
+ * ([#642](https://github.com/Omega-JS-Stack/omega/issues/642)).
+ *
+ * The file still EXISTS, because a missing one makes the route answer "Unknown
+ * provider" — a different and wrong statement about a provider this backend
+ * plainly knows ([Capability gating](../../../../../../docs/payment-system.md)).
+ *
+ * Nothing reaches these functions in practice: the refund route refuses a crypto
+ * order before it loads a provider, through the ONE predicate the account page's
+ * refund button reads too (`libraries/payment/refund-policy.js`), so a button the
+ * page offers is still a refund the route accepts. They throw rather than
+ * silently answering, so a caller that ever bypasses that refusal fails at the
+ * bypass instead of recording a refund that never happened.
+ */
+
+const UNSUPPORTED = 'Coinbase Commerce has no refund API — a crypto refund is a manual transfer from the Coinbase Commerce dashboard';
+
+module.exports = {
+  /**
+   * Refund a Coinbase subscription — there is no such thing to refund
+   * @throws {Error} always
+   */
+  async processRefund() {
+    throw new Error(`${UNSUPPORTED} (and Coinbase Commerce has no subscriptions at all)`);
+  },
+
+  /**
+   * Refund a Coinbase ONE-TIME purchase — unsupported, by the provider
+   * @throws {Error} always
+   */
+  async processOneTimeRefund() {
+    throw new Error(UNSUPPORTED);
+  },
+};

package/dist/manager/routes/payments/refund/providers/paypal.js

@@ -0,0 +1,239 @@
+/**
+ * PayPal refund provider
+ * Refunds the most recent payment on a PayPal subscription and cancels it.
+ * A one-time purchase is refunded against its order's capture instead.
+ *
+ * PayPal refunds are issued against individual sale/capture transactions,
+ * not against the subscription itself. We find the most recent completed
+ * transaction and refund it.
+ *
+ * Proration is the same day-based compute Stripe and Chargebee run — PayPal
+ * just makes us assemble the period ourselves: it exposes no period_start /
+ * period_end on a transaction, so the period the refunded payment bought runs
+ * from that payment forward one billing interval. The interval comes from the
+ * subscription's own plan; when neither the plan nor `next_billing_time` can
+ * supply it the refund REFUSES rather than guessing at somebody's money
+ * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ */
+const { FULL_REFUND_DAYS } = require('../../../../libraries/payment/refund-policy.js');
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+module.exports = {
+  /**
+   * Process a refund for a PayPal subscription
+   *
+   * @param {object} options
+   * @param {string} options.resourceId - PayPal subscription ID (e.g., 'I-xxx')
+   * @param {string} options.uid - User's UID (for logging)
+   * @param {object} options.ctx - Assistant instance for logging
+   * @returns {{ amount: number, currency: string, full: boolean }}
+   */
+  async processRefund({ resourceId, uid, ctx }) {
+    const PayPalLib = require('../../../../libraries/payment/providers/paypal.js');
+
+    // 1. Get subscription transactions to find the latest payment
+    const now = new Date();
+    const oneYearAgo = new Date(now);
+    oneYearAgo.setFullYear(oneYearAgo.getFullYear() - 1);
+
+    const transactions = await PayPalLib.request(
+      `/v1/billing/subscriptions/${resourceId}/transactions?start_time=${oneYearAgo.toISOString()}&end_time=${now.toISOString()}`
+    );
+
+    const completedTransactions = (transactions.transactions || [])
+      .filter(t => t.status === 'COMPLETED')
+      .sort((a, b) => new Date(b.time) - new Date(a.time));
+
+    if (completedTransactions.length === 0) {
+      throw new Error('No completed transactions found for this subscription');
+    }
+
+    const latestTransaction = completedTransactions[0];
+    const saleId = latestTransaction.id;
+    const transactionAmount = parseFloat(latestTransaction.amount_with_breakdown?.gross_amount?.value || '0');
+    const currency = latestTransaction.amount_with_breakdown?.gross_amount?.currency_code || 'USD';
+
+    if (transactionAmount <= 0) {
+      throw new Error('No refundable amount on the latest transaction');
+    }
+
+    // 2. Calculate refund amount
+    const transactionDate = new Date(latestTransaction.time);
+    const daysSincePayment = (now - transactionDate) / (1000 * 60 * 60 * 24);
+
+    let refundAmount;
+    let isFullRefund;
+
+    if (daysSincePayment <= FULL_REFUND_DAYS) {
+      refundAmount = transactionAmount;
+      isFullRefund = true;
+    } else {
+      // Prorated: remaining days / total days * amount — the same compute the
+      // Stripe and Chargebee providers run, over a period PayPal makes us derive.
+      const sub = await PayPalLib.request(`/v1/billing/subscriptions/${resourceId}`);
+      const periodEnd = await this.resolvePeriodEnd({ sub, resourceId, periodStart: transactionDate, PayPalLib, ctx });
+
+      const totalDays = (periodEnd - transactionDate) / DAY_MS;
+
+      if (totalDays <= 0) {
+        throw new Error(`PayPal billing period for subscription ${resourceId} ends at or before the payment it covers — refusing to prorate`);
+      }
+
+      const daysRemaining = Math.max(0, (periodEnd - now) / DAY_MS);
+
+      refundAmount = Math.round((daysRemaining / totalDays) * transactionAmount * 100) / 100;
+      isFullRefund = false;
+    }
+
+    if (refundAmount <= 0) {
+      throw new Error('No refundable amount remaining');
+    }
+
+    // 3. Issue the refund against the sale/capture
+    await PayPalLib.request(`/v2/payments/captures/${saleId}/refund`, {
+      method: 'POST',
+      body: JSON.stringify({
+        amount: {
+          value: refundAmount.toFixed(2),
+          currency_code: currency,
+        },
+        note_to_payer: 'Subscription refund',
+      }),
+    });
+
+    ctx.log(`PayPal refund issued: saleId=${saleId}, amount=${refundAmount}, full=${isFullRefund}, uid=${uid}`);
+
+    // 4. Cancel the subscription
+    try {
+      await PayPalLib.request(`/v1/billing/subscriptions/${resourceId}/cancel`, {
+        method: 'POST',
+        body: JSON.stringify({ reason: 'Refund requested' }),
+      });
+      ctx.log(`PayPal subscription cancelled after refund: sub=${resourceId}, uid=${uid}`);
+    } catch (e) {
+      // Already cancelled — that's fine
+      ctx.log(`PayPal subscription cancel after refund failed (may already be cancelled): ${e.message}`);
+    }
+
+    return {
+      amount: refundAmount,
+      currency: currency.toLowerCase(),
+      full: isFullRefund,
+    };
+  },
+
+  /**
+   * Process a refund for a PayPal ONE-TIME purchase
+   *
+   * A one-time purchase is a PayPal ORDER (Orders API v2) and the money sits on
+   * its capture, so the refund is issued against that capture. Always FULL: a
+   * one-time purchase buys no billing period, so there is nothing to prorate over
+   * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+   *
+   * @param {object} options
+   * @param {string} options.resourceId - PayPal order ID
+   * @param {string} options.uid - User's UID (for logging)
+   * @param {object} options.order - The payments-orders doc being refunded
+   * @param {object} options.ctx - Assistant instance for logging
+   * @returns {{ amount: number, currency: string, full: boolean }}
+   */
+  async processOneTimeRefund({ resourceId, uid, order, ctx }) {
+    const PayPalLib = require('../../../../libraries/payment/providers/paypal.js');
+
+    const paypalOrder = await PayPalLib.request(`/v2/checkout/orders/${resourceId}`);
+    const captures = paypalOrder.purchase_units?.[0]?.payments?.captures || [];
+    const capture = captures.find(c => c.status === 'COMPLETED');
+
+    if (!capture) {
+      throw new Error(`No completed capture found for PayPal order ${resourceId}`);
+    }
+
+    const amount = parseFloat(capture.amount?.value || '0');
+    const currency = capture.amount?.currency_code || 'USD';
+
+    if (amount <= 0) {
+      throw new Error('No refundable amount on this purchase');
+    }
+
+    await PayPalLib.request(`/v2/payments/captures/${capture.id}/refund`, {
+      method: 'POST',
+      body: JSON.stringify({
+        amount: {
+          value: amount.toFixed(2),
+          currency_code: currency,
+        },
+        note_to_payer: 'Purchase refund',
+      }),
+    });
+
+    ctx.log(`PayPal one-time refund issued: captureId=${capture.id}, amount=${amount}, orderId=${order?.id}, uid=${uid}`);
+
+    return {
+      amount: amount,
+      currency: currency.toLowerCase(),
+      full: true,
+    };
+  },
+
+  /**
+   * Resolve the end of the billing period a PayPal payment bought.
+   *
+   * PayPal's own answer comes first: `billing_info.next_billing_time` IS the
+   * period end while a subscription is live. A cancelled or suspended
+   * subscription drops that field, so the period is rebuilt from the payment
+   * being refunded plus the plan's REGULAR billing interval — the same
+   * derivation the PayPal library's period-end resolution runs. When neither is
+   * available the refund refuses: an invented period is an invented amount of
+   * somebody's money.
+   *
+   * @param {object} options
+   * @param {object} options.sub - The PayPal subscription resource
+   * @param {string} options.resourceId - PayPal subscription ID (for messages)
+   * @param {Date} options.periodStart - Start of the period being refunded (the payment's own date)
+   * @param {object} options.PayPalLib - The PayPal library (plan lookup)
+   * @param {object} options.ctx - Assistant instance for logging
+   * @returns {Promise<Date>} The period end
+   * @throws {Error} When the billing period cannot be derived
+   */
+  async resolvePeriodEnd({ sub, resourceId, periodStart, PayPalLib, ctx }) {
+    const nextBilling = sub.billing_info?.next_billing_time;
+
+    if (nextBilling) {
+      return new Date(nextBilling);
+    }
+
+    if (!sub.plan_id) {
+      throw new Error(`PayPal subscription ${resourceId} has no next_billing_time and no plan_id — the billing period cannot be derived`);
+    }
+
+    const plan = await PayPalLib.request(`/v1/billing/plans/${sub.plan_id}`);
+    const cycle = (plan.billing_cycles || []).find(c => c.tenure_type === 'REGULAR');
+    const unit = cycle?.frequency?.interval_unit;
+    const count = cycle?.frequency?.interval_count || 1;
+
+    if (!unit) {
+      throw new Error(`PayPal plan ${sub.plan_id} exposes no REGULAR billing interval — the billing period cannot be derived`);
+    }
+
+    // UTC arithmetic on purpose: the local-time setters shift the period by an
+    // hour across a DST boundary, and a billing period is not a wall clock.
+    const periodEnd = new Date(periodStart);
+
+    if (unit === 'YEAR') {
+      periodEnd.setUTCFullYear(periodEnd.getUTCFullYear() + count);
+    } else if (unit === 'MONTH') {
+      periodEnd.setUTCMonth(periodEnd.getUTCMonth() + count);
+    } else if (unit === 'WEEK') {
+      periodEnd.setUTCDate(periodEnd.getUTCDate() + (count * 7));
+    } else if (unit === 'DAY') {
+      periodEnd.setUTCDate(periodEnd.getUTCDate() + count);
+    } else {
+      throw new Error(`PayPal plan ${sub.plan_id} uses an unknown billing interval "${unit}" — the billing period cannot be derived`);
+    }
+
+    ctx.log(`PayPal period end derived from plan ${sub.plan_id}: ${count} ${unit} after ${periodStart.toISOString()} → ${periodEnd.toISOString()}`);
+
+    return periodEnd;
+  },
+};

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

@@ -0,0 +1,160 @@
+/**
+ * Stripe refund provider
+ *
+ * Subscriptions: issues a refund for the latest invoice and cancels the
+ * subscription immediately. One-time purchases: refunds the payment behind the
+ * order's checkout session, in full.
+ *
+ * Refund amount:
+ * - Full refund if the last payment was ≤7 days ago
+ * - Prorated refund (based on days remaining in billing period) if >7 days ago
+ *
+ * After refunding, if the subscription is still active, it is cancelled immediately.
+ * Stripe then sends a customer.subscription.deleted webhook which the existing
+ * pipeline processes to update Firestore.
+ */
+const { FULL_REFUND_DAYS } = require('../../../../libraries/payment/refund-policy.js');
+
+module.exports = {
+  /**
+   * Process a refund for a Stripe subscription
+   *
+   * @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 subscription object from Firestore
+   * @param {object} options.ctx - Assistant instance for logging
+   * @returns {{ amount: number, currency: string, full: boolean }}
+   */
+  async processRefund({ resourceId, uid, ctx }) {
+    const StripeLib = require('../../../../libraries/payment/providers/stripe.js');
+    const stripe = StripeLib.init();
+
+    // 1. Retrieve subscription to get latest_invoice
+    const sub = await stripe.subscriptions.retrieve(resourceId);
+
+    if (!sub.latest_invoice) {
+      throw new Error('No invoice found for this subscription');
+    }
+
+    // 2. Retrieve the latest invoice to get payment_intent + timing
+    const invoiceId = typeof sub.latest_invoice === 'string'
+      ? sub.latest_invoice
+      : sub.latest_invoice.id;
+    const invoice = await stripe.invoices.retrieve(invoiceId);
+
+    if (!invoice.payment_intent) {
+      throw new Error('No payment found for the latest invoice');
+    }
+
+    // 3. Calculate refund amount
+    const invoicePaidAt = invoice.status_transitions?.paid_at || invoice.created;
+    const daysSincePayment = (Date.now() / 1000 - invoicePaidAt) / 86400;
+    const invoiceAmount = invoice.amount_paid; // in cents
+
+    if (invoiceAmount <= 0) {
+      throw new Error('No refundable amount on the latest invoice');
+    }
+
+    let refundAmount;
+    let isFullRefund;
+
+    if (daysSincePayment <= FULL_REFUND_DAYS) {
+      refundAmount = invoiceAmount;
+      isFullRefund = true;
+    } else {
+      // Prorated: remaining days / total days * amount
+      const periodStart = sub.current_period_start || invoice.period_start;
+      const periodEnd = sub.current_period_end || invoice.period_end;
+      const totalDays = (periodEnd - periodStart) / 86400;
+      const daysRemaining = Math.max(0, (periodEnd - Date.now() / 1000) / 86400);
+
+      refundAmount = Math.round((daysRemaining / totalDays) * invoiceAmount);
+      isFullRefund = false;
+    }
+
+    if (refundAmount <= 0) {
+      throw new Error('No refundable amount remaining');
+    }
+
+    // 4. Issue the refund
+    const paymentIntentId = typeof invoice.payment_intent === 'string'
+      ? invoice.payment_intent
+      : invoice.payment_intent.id;
+
+    // Idempotency key scoped to the subscription prevents double-refund from
+    // a user double-clicking the refund button. Stripe caches the response for
+    // 24 hours — any concurrent or repeated refund request for the same sub
+    // within that window returns the original refund instead of issuing a new one.
+    const refund = await stripe.refunds.create({
+      payment_intent: paymentIntentId,
+      amount: refundAmount,
+      reason: 'requested_by_customer',
+    }, {
+      idempotencyKey: `omega-refund-${resourceId}`,
+    });
+
+    ctx.log(`Stripe refund created: refundId=${refund.id}, amount=${refundAmount}, full=${isFullRefund}, uid=${uid}`);
+
+    // 5. Cancel subscription immediately (if not already canceled)
+    //    This triggers customer.subscription.deleted webhook → existing pipeline
+    if (sub.status !== 'canceled') {
+      await stripe.subscriptions.cancel(resourceId);
+      ctx.log(`Stripe subscription cancelled immediately: sub=${resourceId}, uid=${uid}`);
+    }
+
+    return {
+      amount: refundAmount / 100, // convert cents to dollars for response
+      currency: refund.currency,
+      full: isFullRefund,
+    };
+  },
+
+  /**
+   * Process a refund for a Stripe ONE-TIME purchase
+   *
+   * The order's resource is the checkout session the purchase completed with, and
+   * the payment behind it is what gets refunded. Always FULL: a one-time purchase
+   * buys no billing period, so there is nothing to prorate over
+   * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+   *
+   * @param {object} options
+   * @param {string} options.resourceId - Stripe checkout session ID (e.g., 'cs_xxx')
+   * @param {string} options.uid - User's UID (for logging)
+   * @param {object} options.order - The payments-orders doc being refunded
+   * @param {object} options.ctx - Assistant instance for logging
+   * @returns {{ amount: number, currency: string, full: boolean }}
+   */
+  async processOneTimeRefund({ resourceId, uid, order, ctx }) {
+    const StripeLib = require('../../../../libraries/payment/providers/stripe.js');
+    const stripe = StripeLib.init();
+
+    const session = await stripe.checkout.sessions.retrieve(resourceId);
+
+    const paymentIntentId = typeof session.payment_intent === 'string'
+      ? session.payment_intent
+      : session.payment_intent?.id;
+
+    if (!paymentIntentId) {
+      throw new Error(`No payment found for checkout session ${resourceId}`);
+    }
+
+    // No `amount` — the whole charge comes back. The idempotency key scoped to the
+    // session prevents a double-refund from a double-clicked button: Stripe caches
+    // the response for 24 hours and returns the original refund.
+    const refund = await stripe.refunds.create({
+      payment_intent: paymentIntentId,
+      reason: 'requested_by_customer',
+    }, {
+      idempotencyKey: `omega-refund-one-time-${resourceId}`,
+    });
+
+    ctx.log(`Stripe one-time refund created: refundId=${refund.id}, amount=${refund.amount}, orderId=${order?.id}, uid=${uid}`);
+
+    return {
+      amount: refund.amount / 100, // convert cents to dollars for response
+      currency: refund.currency,
+      full: true,
+    };
+  },
+};