@omega.js/backend 0.1.0

package/dist/manager/routes/marketing/webhook/providers/beehiiv.js

@@ -0,0 +1,197 @@
+/**
+ * Beehiiv webhook provider
+ *
+ * Beehiiv sends one event per POST (unlike SendGrid's batched array).
+ * Each event includes a `publication_id` so the provider can decide whether
+ * the event belongs to THIS brand or a sibling brand sharing the same parent.
+ *
+ * Supported event types (anything else is silently ignored):
+ *   - 'subscription.unsubscribed' — user clicked unsubscribe in a Beehiiv email
+ *   - 'subscription.deleted'      — admin or API removed the subscriber
+ *   - 'subscription.paused'       — user paused delivery (treat as revoke; we
+ *                                    can't differentiate "pause" semantics)
+ *
+ * Publication routing:
+ *   - If the event's publication_id doesn't match this brand's configured
+ *     publication, silent skip. This is how the shared-devbeans publication
+ *     case works: the parent fans the event to every child, and only the
+ *     brand(s) sharing that publication actually process it.
+ *   - getPublicationId() reads from config.marketing.newsletter.providers.beehiiv.publicationId
+ *     or fuzzy-matches by brand name against the Beehiiv API.
+ *
+ * No idempotency ledger — the revoke + cross-provider remove are idempotent, so a
+ * provider retry re-runs safely with the same end state.
+ */
+
+const REVOKE_EVENT_TYPES = new Set([
+  'subscription.unsubscribed',
+  'subscription.deleted',
+  'subscription.paused',
+]);
+
+/**
+ * Parse the raw webhook request into a normalized array (single-element).
+ * Beehiiv sends one event per POST. Some HTTP clients serialize objects with
+ * extra keys merged in (e.g. our test client merges query params into the body) —
+ * we tolerate that by pulling fields explicitly.
+ */
+function parseWebhook(req) {
+  const body = req.body;
+
+  if (!body || typeof body !== 'object') {
+    throw new Error('Empty or non-object webhook body');
+  }
+
+  // Beehiiv's event ID lives at `data.id` (per their docs) but their actual
+  // delivery shape can vary across endpoints. Try common locations.
+  const eventId = body.id
+    || body.event_id
+    || body.data?.id
+    || null;
+
+  const eventType = body.event || body.type || null;
+
+  // Email may be at top-level or nested under `data`
+  const rawEmail = body.email || body.data?.email || null;
+  const email = typeof rawEmail === 'string' ? rawEmail.trim().toLowerCase() : null;
+
+  // Publication ID — required to decide whether THIS brand should handle it
+  const publicationId = body.publication_id || body.data?.publication_id || null;
+
+  // Timestamp — Beehiiv uses ISO 8601. Fall back to data.created_at variants.
+  const timestampISO = body.created_at
+    || body.timestamp
+    || body.data?.created_at
+    || null;
+
+  const timestampUNIX = timestampISO
+    ? Math.floor(new Date(timestampISO).getTime() / 1000) || null
+    : null;
+
+  return [{
+    eventId,
+    eventType,
+    email,
+    timestamp: timestampUNIX,
+    publicationId,
+    raw: body,
+  }];
+}
+
+/**
+ * Returns true if this event type represents a revocation we should act on.
+ */
+function isSupported(parsed) {
+  return REVOKE_EVENT_TYPES.has(parsed.eventType);
+}
+
+/**
+ * Process a single parsed event. Called by the dispatcher for each supported event.
+ * Returns a result object summarizing what happened.
+ */
+async function handleEvent({ Manager, ctx, parsed }) {
+  const { admin } = Manager.libraries;
+  const { eventId, eventType, email, timestamp, publicationId } = parsed;
+
+  if (!email) {
+    ctx.log(`beehiiv webhook: event ${eventId} (${eventType}) missing email, skipping`);
+    return { handled: false, reason: 'missing-email' };
+  }
+
+  // Publication filter — silent skip if the event isn't for our publication.
+  // This is THE mechanism that routes shared-publication events (e.g. devbeans
+  // across 6 brands) to only the brands that share that publication.
+  // beehiivProvider.getPublicationId() reads Manager.config.marketing.newsletter.providers.beehiiv.publicationId
+  // first, then falls back to fuzzy-match against the Beehiiv API by brand name.
+  if (publicationId) {
+    let ourPublicationId = null;
+    try {
+      const beehiivProvider = require('../../../../libraries/email/providers/beehiiv.js');
+      if (typeof beehiivProvider.getPublicationId === 'function') {
+        ourPublicationId = await beehiivProvider.getPublicationId();
+      }
+    } catch (e) {
+      ctx.error('beehiiv webhook: failed to resolve our publication ID:', e);
+      return { handled: false, reason: 'publication-resolve-failed' };
+    }
+
+    if (!ourPublicationId) {
+      ctx.log(`beehiiv webhook: no publication configured for this brand, skipping event ${eventId}`);
+      return { handled: false, reason: 'no-local-publication' };
+    }
+
+    if (ourPublicationId !== publicationId) {
+      ctx.log(`beehiiv webhook: publication mismatch (event=${publicationId}, ours=${ourPublicationId}), skipping`);
+      return { handled: false, reason: 'publication-mismatch' };
+    }
+  }
+
+  // Build the canonical revokedAt timestamp from the event (or server time if missing)
+  const startTime = ctx.meta.startTime;
+  const eventUNIX = typeof timestamp === 'number' ? timestamp : startTime.timestampUNIX;
+  const eventISO = new Date(eventUNIX * 1000).toISOString();
+
+  // Look up the user by email
+  const snapshot = await admin.firestore().collection('users')
+    .where('auth.email', '==', email)
+    .limit(1)
+    .get()
+    .catch((e) => {
+      ctx.error(`beehiiv webhook: user lookup failed for ${email}:`, e);
+      return null;
+    });
+
+  if (!snapshot || snapshot.empty) {
+    // Silent skip — this email may not map to a customer of THIS brand even if
+    // the publication matched (legitimate for shared-devbeans where 6 brands
+    // process every event but only one has the user).
+    ctx.log(`beehiiv webhook: no user found for ${email}, skipping doc update`);
+    return { handled: false, reason: 'user-not-found', email };
+  }
+
+  const userDoc = snapshot.docs[0];
+  const uid = userDoc.id;
+
+  // Write consent.marketing.status = 'revoked' (preserve grantedAt — informational audit trail)
+  await admin.firestore().doc(`users/${uid}`).set({
+    consent: {
+      marketing: {
+        status: 'revoked',
+        revokedAt: {
+          timestamp: eventISO,
+          timestampUNIX: eventUNIX,
+          source: 'beehiiv',
+          ip: null,
+          text: null,
+        },
+      },
+    },
+    metadata: Manager.Metadata().set({ tag: 'marketing/webhook:beehiiv' }),
+  }, { merge: true });
+
+  ctx.log(`beehiiv webhook: revoked consent.marketing for ${uid} (${email}) — eventType=${eventType}`);
+
+  // Cross-provider sync: also remove from SendGrid (best-effort, idempotent on 404)
+  const shouldCallExternalAPIs = !ctx.isTesting() || process.env.TEST_EXTENDED_MODE;
+
+  if (shouldCallExternalAPIs) {
+    try {
+      const mailer = Manager.Email(ctx);
+      await mailer.remove(email);
+      ctx.log(`beehiiv webhook: cross-provider sync complete for ${email}`);
+    } catch (e) {
+      // Best-effort — user doc is already updated. Log + continue.
+      ctx.error(`beehiiv webhook: cross-provider sync failed for ${email}:`, e);
+    }
+  } else {
+    ctx.log('beehiiv webhook: skipping cross-provider sync (OMEGA_TEST_MODE=true)');
+  }
+
+  return { handled: true, uid, email, eventType };
+}
+
+module.exports = {
+  parseWebhook,
+  isSupported,
+  handleEvent,
+};

package/dist/manager/routes/marketing/webhook/providers/sendgrid.js

@@ -0,0 +1,194 @@
+/**
+ * SendGrid webhook provider
+ *
+ * SendGrid sends an array of events per POST. This module parses the array,
+ * decides which events represent an unsubscribe (revocation of marketing consent),
+ * and exposes a per-event handler that:
+ *   1. Looks up the user by email in this brand's Firestore (silent skip if not found)
+ *   2. Writes consent.marketing.status = 'revoked' to the user doc, source: 'sendgrid'
+ *   3. Calls Beehiiv to remove the contact too (cross-provider sync — idempotent on 404)
+ *
+ * Supported event types (anything else is silently ignored):
+ *   - 'unsubscribe'         — user clicked the unified unsubscribe link
+ *   - 'group_unsubscribe'   — user unsubscribed from a specific ASM group
+ *   - 'spamreport'          — user marked email as spam
+ *   - 'bounce'              — ONLY when bounce_classification is 'Invalid Address' (hard bounce).
+ *                              Technical bounces (DMARC, TLS, DNS) are sender-side issues and
+ *                              should NOT revoke the recipient's consent.
+ *   - 'dropped'             — ONLY when bounce_classification is 'Invalid Address'.
+ *
+ * Note: 'group_unsubscribe' is the most common one (matches our ASM-link flow), and since
+ * an unsubscribe group is account-global across every brand sharing the SendGrid account,
+ * an unsub from the marketing group legitimately removes the user from marketing across
+ * the entire account.
+ *
+ * No idempotency ledger — the revoke + cross-provider remove are idempotent, so a
+ * provider retry re-runs safely with the same end state.
+ */
+
+const REVOKE_EVENT_TYPES = new Set([
+  'unsubscribe',
+  'group_unsubscribe',
+  'spamreport',
+]);
+
+// Bounce events only revoke consent when the bounce_classification indicates
+// the mailbox genuinely doesn't exist. Technical bounces (DMARC, TLS, DNS),
+// reputation bounces, content blocks, and temporary failures are the SENDER's
+// problem — the recipient's email is still valid.
+const HARD_BOUNCE_CLASSIFICATIONS = new Set([
+  'Invalid Address',
+]);
+
+/**
+ * Parse the raw webhook request into a normalized array of events.
+ * SendGrid sends an array of events as the body. Some HTTP clients (including
+ * @omega.js/backend's own test client) JSON-encode arrays as objects with numeric keys —
+ * we tolerate both shapes plus the rare single-event object form.
+ */
+function parseWebhook(req) {
+  const body = req.body;
+
+  if (!body) {
+    throw new Error('Empty webhook body');
+  }
+
+  let events;
+  if (Array.isArray(body)) {
+    // Real SendGrid: array body
+    events = body;
+  } else if (body && typeof body === 'object' && typeof body['0'] === 'object' && body['0'] !== null) {
+    // Array serialized as object-with-numeric-keys (test clients, some proxies)
+    events = [];
+    let i = 0;
+    while (body[String(i)]) {
+      events.push(body[String(i)]);
+      i += 1;
+    }
+  } else {
+    // Single event sent as a bare object
+    events = [body];
+  }
+
+  return events.map((event) => {
+    // sg_event_id is SendGrid's per-event unique ID, retained for log context.
+    // smtp-id is another stable identifier we fall back to.
+    const eventId = event.sg_event_id || event['smtp-id'] || event.smtpId || null;
+    const eventType = event.event;
+    const email = typeof event.email === 'string' ? event.email.trim().toLowerCase() : null;
+    const timestamp = typeof event.timestamp === 'number' ? event.timestamp : null;
+    const asmGroupId = event.asm_group_id || null;
+    const bounceClassification = event.bounce_classification || null;
+
+    return {
+      eventId,
+      eventType,
+      email,
+      timestamp,
+      asmGroupId,
+      bounceClassification,
+      raw: event,
+    };
+  });
+}
+
+/**
+ * Returns true if this parsed event represents a revocation we should act on.
+ * For bounce/dropped events, only hard bounces (Invalid Address) qualify.
+ */
+function isSupported(parsed) {
+  const { eventType, bounceClassification } = parsed;
+
+  if (REVOKE_EVENT_TYPES.has(eventType)) {
+    return true;
+  }
+
+  if (eventType === 'bounce' || eventType === 'dropped') {
+    return HARD_BOUNCE_CLASSIFICATIONS.has(bounceClassification);
+  }
+
+  return false;
+}
+
+/**
+ * Process a single parsed event. Called by the dispatcher for each supported event.
+ *
+ * Returns a result object summarizing what happened (for logging/response).
+ */
+async function handleEvent({ Manager, ctx, parsed }) {
+  const { admin } = Manager.libraries;
+  const { eventId, eventType, email, timestamp } = parsed;
+
+  if (!email) {
+    ctx.log(`sendgrid webhook: event ${eventId} (${eventType}) missing email, skipping`);
+    return { handled: false, reason: 'missing-email' };
+  }
+
+  // Convert SendGrid's UNIX timestamp to our canonical { timestamp, timestampUNIX } shape.
+  // Fall back to server time if missing.
+  const startTime = ctx.meta.startTime;
+  const eventUNIX = typeof timestamp === 'number' ? timestamp : startTime.timestampUNIX;
+  const eventISO = new Date(eventUNIX * 1000).toISOString();
+
+  // Look up the user by email
+  const snapshot = await admin.firestore().collection('users')
+    .where('auth.email', '==', email)
+    .limit(1)
+    .get()
+    .catch((e) => {
+      ctx.error(`sendgrid webhook: user lookup failed for ${email}:`, e);
+      return null;
+    });
+
+  if (!snapshot || snapshot.empty) {
+    // Silent skip — this email may not map to a customer of THIS brand (shared SendGrid account).
+    ctx.log(`sendgrid webhook: no user found for ${email}, skipping doc update`);
+    return { handled: false, reason: 'user-not-found', email };
+  }
+
+  const userDoc = snapshot.docs[0];
+  const uid = userDoc.id;
+
+  // Write consent.marketing.status = 'revoked' (preserve grantedAt — informational audit trail)
+  await admin.firestore().doc(`users/${uid}`).set({
+    consent: {
+      marketing: {
+        status: 'revoked',
+        revokedAt: {
+          timestamp: eventISO,
+          timestampUNIX: eventUNIX,
+          source: 'sendgrid',
+          ip: null,
+          text: null,
+        },
+      },
+    },
+    metadata: Manager.Metadata().set({ tag: 'marketing/webhook:sendgrid' }),
+  }, { merge: true });
+
+  ctx.log(`sendgrid webhook: revoked consent.marketing for ${uid} (${email}) — eventType=${eventType}`);
+
+  // Cross-provider sync: also remove from Beehiiv (best-effort, idempotent on 404)
+  const shouldCallExternalAPIs = !ctx.isTesting() || process.env.TEST_EXTENDED_MODE;
+
+  if (shouldCallExternalAPIs) {
+    try {
+      const mailer = Manager.Email(ctx);
+      await mailer.remove(email);
+      ctx.log(`sendgrid webhook: cross-provider sync complete for ${email}`);
+    } catch (e) {
+      // Best-effort — user doc is already updated. Log + continue.
+      ctx.error(`sendgrid webhook: cross-provider sync failed for ${email}:`, e);
+    }
+  } else {
+    ctx.log('sendgrid webhook: skipping cross-provider sync (OMEGA_TEST_MODE=true)');
+  }
+
+  return { handled: true, uid, email, eventType };
+}
+
+module.exports = {
+  parseWebhook,
+  isSupported,
+  handleEvent,
+};

package/dist/manager/routes/payments/cancel/_is-trialing.js

@@ -0,0 +1,40 @@
+/**
+ * Is this subscription still INSIDE its free trial?
+ *
+ * The cancel flow asks this in two places and both have to agree, so it is one
+ * function rather than a copy per caller ([#267](https://github.com/Omega-JS-Stack/omega/issues/267)):
+ *
+ * - the route waives the 24-hour young-subscription guard for a trial (that
+ *   guard exists for settlement games on a PAID subscription; a trial has no
+ *   payment to settle, and a same-day trial cancel is the most common trial
+ *   behavior there is), and
+ * - every provider cancels a trial NOW instead of at period end — Ian's ruling
+ *   (2026-08-15): we do not keep serving a trial we know will not convert.
+ *
+ * The test: the trial is claimed, the subscription is live, and the subscription
+ * still expires exactly when the TRIAL does. That last clause is what makes a
+ * CONVERTED trial read false — conversion moves `expires` out to the end of the
+ * first paid period while `trial.expires` stays where it was, so the two stop
+ * matching the moment real money is involved.
+ *
+ * A trial that has run out but has not been swept yet still reads true, which is
+ * the answer this flow wants: nothing was ever paid, so there is nothing to let
+ * ride to a period end.
+ *
+ * The expiry has to EXIST to match. The three providers this was folded out of
+ * compared the two timestamps directly, so a subscription carrying neither one
+ * matched itself on `undefined` and read as trialing — harmless while the answer
+ * only chose a cancel mode, but this now also waives a guard, and a guard must
+ * never be waived by missing data.
+ *
+ * @param {object} [subscription] - The user's subscription object
+ * @returns {boolean}
+ */
+module.exports = function isTrialing(subscription) {
+  const trialExpires = subscription?.trial?.expires?.timestampUNIX;
+
+  return !!(subscription?.trial?.claimed
+    && subscription?.status === 'active'
+    && trialExpires
+    && trialExpires === subscription?.expires?.timestampUNIX);
+};

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

@@ -0,0 +1,149 @@
+const path = require('path');
+const loadProvider = require('../../../libraries/load-provider.js');
+const powertools = require('node-powertools');
+const isAlreadyGone = require('../../../libraries/payment/provider-errors.js');
+const isTrialing = require('./_is-trialing.js');
+
+/**
+ * POST /payments/cancel
+ * Cancels the authenticated user's subscription at the end of the current billing period.
+ * Delegates to the provider (e.g., Stripe) to set cancel_at_period_end=true.
+ * The resulting webhook triggers the Firestore pipeline which updates subscription state
+ * and fires the cancellation-requested transition handler.
+ * Stores the cancellation reason/feedback on payments-orders/{orderId}.requests.cancellation.
+ * Requires authentication.
+ */
+module.exports = async ({ ctx, user, settings }) => {
+  // Require authentication
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  const uid = user.auth.uid;
+  const confirmed = settings.confirmed;
+
+  // Require explicit confirmation
+  if (!confirmed) {
+    return ctx.respond('Cancellation must be confirmed', { code: 400 });
+  }
+
+  const subscription = user.subscription;
+
+  // Require an active or suspended paid subscription
+  if (!subscription || (subscription.status !== 'active' && subscription.status !== 'suspended') || subscription.product?.id === 'basic') {
+    ctx.log(`Cancel rejected: uid=${uid}, status=${subscription?.status}, product=${subscription?.product?.id}`);
+    return ctx.respond('No active paid subscription found', { code: 400 });
+  }
+
+  // `skipGuards` arrives in the request body, so it is a REQUEST, not a decision:
+  // it is honored for an admin, or anywhere outside a real deployment (the test
+  // suites and the dev palette cancel seeded subscriptions minutes old). Every
+  // other caller is ignored — loudly — and the guards below run as normal.
+  const mayBypassGuards = user.roles?.admin === true || ctx.isDevelopment() || ctx.isTesting();
+  const skipGuards = settings.skipGuards === true && mayBypassGuards;
+
+  if (settings.skipGuards === true && !mayBypassGuards) {
+    ctx.warn(`Ignoring skipGuards on cancel: uid=${uid} is not permitted to bypass the cancellation guards`);
+  }
+
+  // Guard: subscription younger than 24 hours (privileged callers may bypass via skipGuards).
+  //
+  // A TRIAL is exempt ([#267](https://github.com/Omega-JS-Stack/omega/issues/267)):
+  // the guard exists to stop a cancellation racing a PAID checkout that is still
+  // settling, and a trial has no payment to settle. Blocking it told the most
+  // common trial behavior there is — cancelling the same day you started — that
+  // the subscription "is still being set up".
+  const trialing = isTrialing(subscription);
+  const startDateUNIX = subscription.payment?.startDate?.timestampUNIX;
+  if (!skipGuards && !trialing && startDateUNIX) {
+    const ageMs = Date.now() - (startDateUNIX * 1000);
+    const twentyFourHoursMs = 24 * 60 * 60 * 1000;
+    if (ageMs < twentyFourHoursMs) {
+      ctx.log(`Cancel rejected: uid=${uid}, subscription is only ${Math.round(ageMs / 1000 / 60)} minutes old`);
+      return ctx.respond('Your subscription is still being set up. Please try again after 24-48 hours.', { code: 400 });
+    }
+  }
+
+  // Guard: already pending cancellation
+  if (subscription.cancellation?.pending === true) {
+    ctx.log(`Cancel rejected: uid=${uid}, cancellation already pending`);
+    return ctx.respond('Subscription is already pending cancellation', { code: 400 });
+  }
+
+  const provider = subscription.payment?.provider;
+  const resourceId = subscription.payment?.resourceId;
+
+  if (!provider || !resourceId) {
+    ctx.log(`Cancel rejected: uid=${uid}, missing provider=${provider} or resourceId=${resourceId}`);
+    return ctx.respond('Subscription payment details not found', { code: 400 });
+  }
+
+  // Load the provider module
+  let providerModule;
+  try {
+    providerModule = loadProvider(path.join(__dirname, 'providers'), provider);
+  } catch (e) {
+    return ctx.respond(`Unknown provider: ${provider}`, { code: 400 });
+  }
+
+  // Cancel at period end via the provider
+  try {
+    await providerModule.cancelAtPeriodEnd({ resourceId, uid, subscription, ctx });
+  } catch (e) {
+    // A suspended subscription the provider says NO LONGER EXISTS is a dead
+    // record on our side alone: reset it directly so the user can re-subscribe.
+    // The classification is the whole guard — every transient or unrecognized
+    // failure falls through to the caller with NOTHING written, so a network
+    // blip can never fabricate a cancellation ([#212]).
+    if (subscription.status === 'suspended' && isAlreadyGone(e)) {
+      ctx.log(`Provider reports the suspended subscription is already gone (${e.message}), resetting directly`);
+      const admin = ctx.Manager.libraries.admin;
+      const now = powertools.timestamp(new Date(), { output: 'string' });
+      const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+      await admin.firestore().doc(`users/${uid}`).set({
+        subscription: {
+          status: 'cancelled',
+          product: { id: 'basic', name: 'Basic' },
+          cancellation: { pending: false, date: { timestamp: now, timestampUNIX: nowUNIX } },
+        },
+      }, { merge: true });
+
+      ctx.log(`Directly cancelled suspended subscription for uid=${uid}`);
+      return ctx.respond({ success: true });
+    }
+
+    // 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 cancel subscription via ${provider}: uid=${uid}, sub=${resourceId}, error=${e.message}`);
+    return ctx.respond('We could not cancel your subscription right now. Please try again shortly.', { code: 500 });
+  }
+
+  // Store cancellation reason/feedback on the order doc
+  const orderId = subscription.payment?.orderId;
+
+  if (orderId) {
+    const admin = ctx.Manager.libraries.admin;
+    const now = powertools.timestamp(new Date(), { output: 'string' });
+    const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+    await admin.firestore().doc(`payments-orders/${orderId}`).set({
+      requests: {
+        cancellation: {
+          reason: settings.reason || null,
+          feedback: settings.feedback || null,
+          date: {
+            timestamp: now,
+            timestampUNIX: nowUNIX,
+          },
+        },
+      },
+    }, { merge: true });
+
+    ctx.log(`Stored cancellation request on payments-orders/${orderId}: reason=${settings.reason}`);
+  }
+
+  ctx.log(`Cancel ${trialing ? 'immediate (trialing)' : 'scheduled'}: uid=${uid}, provider=${provider}, sub=${resourceId}, reason=${settings.reason}`);
+
+  return ctx.respond({ success: true });
+};

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

@@ -0,0 +1,41 @@
+const isTrialing = require('../_is-trialing.js');
+
+/**
+ * Chargebee cancel provider
+ * Cancels a subscription — immediately if trialing, at period end otherwise.
+ *
+ * Chargebee cancel_option:
+ * - 'end_of_term': Sets status to non_renewing (cancel at period end)
+ * - 'immediately': Cancels right away (status → cancelled)
+ */
+module.exports = {
+  /**
+   * Cancel 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 current subscription object
+   * @param {object} options.ctx - Assistant instance for logging
+   */
+  async cancelAtPeriodEnd({ resourceId, uid, subscription, ctx }) {
+    const ChargebeeLib = require('../../../../libraries/payment/providers/chargebee.js');
+    ChargebeeLib.init();
+
+    if (isTrialing(subscription)) {
+      // Immediate cancel for trials
+      await ChargebeeLib.request(`/subscriptions/${resourceId}/cancel_for_items`, {
+        method: 'POST',
+        body: { cancel_option: 'immediately' },
+      });
+      ctx.log(`Chargebee cancel immediate (trialing): sub=${resourceId}, uid=${uid}`);
+    } else {
+      // Cancel at end of billing period
+      await ChargebeeLib.request(`/subscriptions/${resourceId}/cancel_for_items`, {
+        method: 'POST',
+        body: { cancel_option: 'end_of_term' },
+      });
+      ctx.log(`Chargebee cancel at period end: sub=${resourceId}, uid=${uid}`);
+    }
+  },
+};

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

@@ -0,0 +1,56 @@
+const isTrialing = require('../_is-trialing.js');
+
+/**
+ * PayPal cancel provider
+ * Cancels a subscription — immediately if trialing, at period end otherwise.
+ *
+ * Note: PayPal does not have "cancel at period end" like Stripe. Cancellation
+ * stops the billing agreement right away, and for a PAID subscription the
+ * subscriber keeps access until the end of the period they already paid for
+ * (PayPal's default behavior, and ours — the pipeline leaves the future
+ * `expires` in place).
+ *
+ * A TRIAL is where the two part company
+ * ([#267](https://github.com/Omega-JS-Stack/omega/issues/267)): access ends NOW,
+ * because there is no paid-for period to serve out. PayPal exposes no second
+ * cancel mode to ask for that, so the call itself is necessarily the same one —
+ * the immediacy is enforced on OUR side, in the unified transform: for a
+ * subscription still inside its trial window `calculatePeriodEnd()` returns null
+ * (libraries/payment/providers/paypal.js), so the cancellation webhook resolves
+ * the subscription to `cancelled` with nothing pending and no future expiry,
+ * instead of pricing a "remaining period" off a setup-fee payment. The
+ * `subscription-cancelled` transition only shapes the email that follows. The
+ * branch is here so the intent is stated at the call site and the logs say which
+ * cancel this was, exactly as the Stripe and Chargebee providers do.
+ */
+module.exports = {
+  /**
+   * Cancel 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.subscription - User's current subscription object
+   * @param {object} options.ctx - Assistant instance for logging
+   */
+  async cancelAtPeriodEnd({ resourceId, uid, subscription, ctx }) {
+    const PayPalLib = require('../../../../libraries/payment/providers/paypal.js');
+
+    const trialing = isTrialing(subscription);
+
+    await PayPalLib.request(`/v1/billing/subscriptions/${resourceId}/cancel`, {
+      method: 'POST',
+      body: JSON.stringify({
+        reason: trialing
+          ? 'Customer cancelled during free trial'
+          : 'Customer requested cancellation',
+      }),
+    });
+
+    if (trialing) {
+      ctx.log(`PayPal cancel immediate (trialing): sub=${resourceId}, uid=${uid}`);
+    } else {
+      ctx.log(`PayPal cancel at period end: sub=${resourceId}, uid=${uid}`);
+    }
+  },
+};