@tribe-nest/forge 3.9.0 → 3.11.0

package/src/utils/membershipAccess.ts

@@ -0,0 +1,182 @@
+/**
+ * The ONE answer to "does this membership grant access right now", and the
+ * separate answer to "what should we tell the member".
+ *
+ * ## Why this file exists
+ *
+ * The backend has always kept a member's benefits alive through `past_due` and
+ * the grace window — that is a locked product decision (retention beats a few
+ * days of free access; an abrupt cut-off during a bank hiccup is the top
+ * cancellation trigger). Three fan-facing components disagreed with it, each
+ * with its own `status === "active"` string compare:
+ *
+ *   - Forge `MembershipGate`      → locked past_due members out of paid content
+ *   - Forge `AccountDashboard`    → badge read "Cancelled"
+ *   - client `MembershipTab`      → badge read "Cancelled", cancel button hidden
+ *
+ * So a member whose card bounced lost access instantly AND was told they had
+ * cancelled. Both wrong, from the same overloaded boolean.
+ *
+ * ## How it stays fixed
+ *
+ * The server is the source of truth. `describeMembershipAccess` (backend,
+ * `services/_core/membershipAccess.ts`) runs the SAME `grantsAccess` predicate
+ * the membership guard, community tier resolution and the notification workers
+ * use, and ships the result as `membership.access` on every membership a fan
+ * surface receives. `getMembershipAccess` below prefers that block. It never
+ * re-decides; a UI gate and a server gate cannot disagree.
+ *
+ * The status fallback exists only for a client running against a server that
+ * predates the `access` block. Keep it in lockstep with
+ * `ACCESS_GRANTING_STATUSES` on the backend — and prefer adding to the server.
+ */
+
+export const MEMBERSHIP_BILLING_STATE = {
+  active: "active",
+  ending: "ending",
+  pastDue: "past_due",
+  grace: "grace",
+  pending: "pending",
+  ended: "ended",
+} as const;
+
+export type MembershipBillingState = (typeof MEMBERSHIP_BILLING_STATE)[keyof typeof MEMBERSHIP_BILLING_STATE];
+
+/** Mirror of the backend's `ACCESS_GRANTING_STATUSES` — fallback only. */
+const ACCESS_GRANTING_STATUSES = ["active", "past_due", "grace"];
+const RECOVERABLE_STATUSES = ["past_due", "grace"];
+
+export type MembershipAccessSummary = {
+  /** May this member use their benefits right now. */
+  hasAccess: boolean;
+  billingState: MembershipBillingState;
+  /** A charge failed and recovery is still possible — show the fix-my-card path. */
+  paymentFailed: boolean;
+  /** ISO date access is cut if the card is not fixed. */
+  graceUntil: string | null;
+  pastDueAt: string | null;
+  cancelAtPeriodEnd: boolean;
+};
+
+export type MembershipAccessInput =
+  | {
+      status?: string | null;
+      cancelAtPeriodEnd?: boolean | null;
+      graceUntil?: string | null;
+      pastDueAt?: string | null;
+      access?: Partial<MembershipAccessSummary> | null;
+    }
+  | null
+  | undefined;
+
+const NO_MEMBERSHIP: MembershipAccessSummary = {
+  hasAccess: false,
+  billingState: MEMBERSHIP_BILLING_STATE.ended,
+  paymentFailed: false,
+  graceUntil: null,
+  pastDueAt: null,
+  cancelAtPeriodEnd: false,
+};
+
+const billingStateFromStatus = (status: string | null | undefined, cancelAtPeriodEnd: boolean) => {
+  switch (status) {
+    case "active":
+      return cancelAtPeriodEnd ? MEMBERSHIP_BILLING_STATE.ending : MEMBERSHIP_BILLING_STATE.active;
+    case "past_due":
+      return MEMBERSHIP_BILLING_STATE.pastDue;
+    case "grace":
+      return MEMBERSHIP_BILLING_STATE.grace;
+    case "pending":
+      return MEMBERSHIP_BILLING_STATE.pending;
+    default:
+      return MEMBERSHIP_BILLING_STATE.ended;
+  }
+};
+
+export function getMembershipAccess(membership: MembershipAccessInput): MembershipAccessSummary {
+  if (!membership) return NO_MEMBERSHIP;
+
+  const server = membership.access;
+  if (server && typeof server.hasAccess === "boolean" && server.billingState) {
+    return {
+      hasAccess: server.hasAccess,
+      billingState: server.billingState,
+      paymentFailed: !!server.paymentFailed,
+      graceUntil: server.graceUntil ?? null,
+      pastDueAt: server.pastDueAt ?? null,
+      cancelAtPeriodEnd: !!server.cancelAtPeriodEnd,
+    };
+  }
+
+  const status = membership.status ?? null;
+  const cancelAtPeriodEnd = !!membership.cancelAtPeriodEnd;
+  return {
+    hasAccess: !!status && ACCESS_GRANTING_STATUSES.includes(status),
+    billingState: billingStateFromStatus(status, cancelAtPeriodEnd),
+    paymentFailed: !!status && RECOVERABLE_STATUSES.includes(status),
+    graceUntil: membership.graceUntil ?? null,
+    pastDueAt: membership.pastDueAt ?? null,
+    cancelAtPeriodEnd,
+  };
+}
+
+/**
+ * The label + explanation a member should see. Deliberately separate from
+ * access: a `past_due` member keeps their benefits AND must be told their
+ * payment failed. Showing "Active" to someone whose card bounced is its own
+ * failure — it is why they never fix it.
+ */
+export type MembershipStatusMessage = {
+  label: string;
+  /** Longer explanation, or null when there is nothing to explain. */
+  detail: string | null;
+  /** Show the "update payment method" affordance. */
+  showUpdatePayment: boolean;
+  /** Severity for styling — the caller maps this onto its own theme colors. */
+  tone: "positive" | "warning" | "neutral";
+};
+
+const formatDay = (iso: string | null): string | null => {
+  if (!iso) return null;
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? null : date.toLocaleDateString();
+};
+
+export function getMembershipStatusMessage(access: MembershipAccessSummary): MembershipStatusMessage {
+  switch (access.billingState) {
+    case MEMBERSHIP_BILLING_STATE.active:
+      return { label: "Active", detail: null, showUpdatePayment: false, tone: "positive" };
+
+    case MEMBERSHIP_BILLING_STATE.ending:
+      return {
+        label: "Ending",
+        detail: "Your membership is cancelled and will not renew. You keep access until the end of this period.",
+        showUpdatePayment: false,
+        tone: "neutral",
+      };
+
+    case MEMBERSHIP_BILLING_STATE.pastDue:
+    case MEMBERSHIP_BILLING_STATE.grace: {
+      const until = formatDay(access.graceUntil);
+      return {
+        label: "Payment failed",
+        detail: until
+          ? `We couldn't charge your payment method. You still have full access until ${until} — update your card to keep it.`
+          : "We couldn't charge your payment method. You still have full access — update your card to keep it.",
+        showUpdatePayment: true,
+        tone: "warning",
+      };
+    }
+
+    case MEMBERSHIP_BILLING_STATE.pending:
+      return {
+        label: "Pending",
+        detail: "Your membership isn't active yet — finish checkout to unlock it.",
+        showUpdatePayment: false,
+        tone: "neutral",
+      };
+
+    default:
+      return { label: "Ended", detail: null, showUpdatePayment: false, tone: "neutral" };
+  }
+}