@mmailaender/convex-creem 0.1.0

package/src/core/resolver.test.ts

@@ -0,0 +1,283 @@
+import { describe, expect, it } from "vitest";
+import { resolveBillingSnapshot } from "./resolver.js";
+
+describe("resolveBillingSnapshot", () => {
+  it("maps recurring subscription intervals and seat actions", () => {
+    const snapshot = resolveBillingSnapshot({
+      catalog: {
+        version: "1",
+        plans: [
+          {
+            planId: "pro",
+            category: "paid",
+            billingType: "recurring",
+            billingCycles: ["every-month", "every-year"],
+            pricingModel: "seat",
+            creemProductIds: {
+              monthly: "prod_monthly",
+              yearly: "prod_yearly",
+            },
+          },
+        ],
+      },
+      currentSubscription: {
+        productId: "prod_monthly",
+        status: "active",
+        recurringInterval: "every-month",
+        seats: 5,
+      },
+    });
+
+    expect(snapshot.activePlanId).toBe("pro");
+    expect(snapshot.recurringCycle).toBe("every-month");
+    expect(snapshot.availableActions).toContain("switch_interval");
+    expect(snapshot.availableActions).toContain("update_seats");
+  });
+
+  it("supports one-time payments", () => {
+    const snapshot = resolveBillingSnapshot({
+      catalog: {
+        version: "1",
+        plans: [
+          {
+            planId: "credits",
+            category: "paid",
+            billingType: "onetime",
+            creemProductIds: { default: "prod_credits" },
+          },
+        ],
+      },
+      payment: {
+        status: "pending",
+        productId: "prod_credits",
+      },
+    });
+
+    expect(snapshot.billingType).toBe("onetime");
+    expect(snapshot.payment?.status).toBe("pending");
+    expect(snapshot.availableActions).toEqual(["checkout"]);
+  });
+
+  it("maps trialing subscription to trial category with trialEnd in metadata", () => {
+    const snapshot = resolveBillingSnapshot({
+      catalog: {
+        version: "1",
+        plans: [
+          {
+            planId: "basic",
+            category: "paid",
+            billingType: "recurring",
+            creemProductIds: { "every-month": "prod_basic" },
+          },
+        ],
+      },
+      currentSubscription: {
+        productId: "prod_basic",
+        status: "trialing",
+        recurringInterval: "every-month",
+        trialEnd: "2026-03-04T08:23:39.000Z",
+      },
+    });
+
+    expect(snapshot.activeCategory).toBe("trial");
+    expect(snapshot.subscriptionState).toBe("trialing");
+    expect(snapshot.metadata?.trialEnd).toBe("2026-03-04T08:23:39.000Z");
+    expect(snapshot.availableActions).toContain("cancel");
+  });
+
+  it("falls back to custom category when no catalog mapping exists", () => {
+    const snapshot = resolveBillingSnapshot({
+      currentSubscription: {
+        status: "unpaid",
+      },
+    });
+
+    expect(snapshot.activeCategory).toBe("custom");
+    expect(snapshot.availableActions).toEqual(["portal"]);
+  });
+
+  it("maps scheduled_cancel to paid with cancel + reactivate actions", () => {
+    const snapshot = resolveBillingSnapshot({
+      catalog: {
+        version: "1",
+        plans: [
+          {
+            planId: "pro",
+            category: "paid",
+            billingType: "recurring",
+            creemProductIds: { "every-month": "prod_1" },
+          },
+        ],
+      },
+      currentSubscription: {
+        productId: "prod_1",
+        status: "scheduled_cancel",
+        recurringInterval: "every-month",
+        cancelAtPeriodEnd: true,
+        currentPeriodEnd: "2026-03-01T00:00:00.000Z",
+      },
+    });
+
+    expect(snapshot.activeCategory).toBe("paid");
+    expect(snapshot.subscriptionState).toBe("scheduled_cancel");
+    expect(snapshot.availableActions).toContain("cancel");
+    expect(snapshot.availableActions).toContain("reactivate");
+    expect(snapshot.availableActions).toContain("portal");
+    expect(snapshot.metadata?.cancelAtPeriodEnd).toBe(true);
+  });
+
+  it("maps past_due subscription to paid category", () => {
+    const snapshot = resolveBillingSnapshot({
+      catalog: {
+        version: "1",
+        plans: [
+          {
+            planId: "basic",
+            category: "paid",
+            billingType: "recurring",
+            creemProductIds: { "every-month": "prod_basic" },
+          },
+        ],
+      },
+      currentSubscription: {
+        productId: "prod_basic",
+        status: "past_due",
+        recurringInterval: "every-month",
+      },
+    });
+
+    expect(snapshot.activeCategory).toBe("paid");
+    expect(snapshot.subscriptionState).toBe("past_due");
+    expect(snapshot.availableActions).toContain("portal");
+  });
+
+  it("maps enterprise plan to contact_sales action only", () => {
+    const snapshot = resolveBillingSnapshot({
+      catalog: {
+        version: "1",
+        plans: [
+          {
+            planId: "enterprise",
+            category: "enterprise",
+            billingType: "custom",
+            creemProductIds: { default: "prod_ent" },
+          },
+        ],
+      },
+      currentSubscription: {
+        productId: "prod_ent",
+        status: "active",
+        recurringInterval: "every-month",
+      },
+    });
+
+    expect(snapshot.activeCategory).toBe("enterprise");
+    expect(snapshot.availableActions).toEqual(["contact_sales"]);
+  });
+
+  it("returns checkout action when no subscription exists", () => {
+    const snapshot = resolveBillingSnapshot({
+      catalog: {
+        version: "1",
+        plans: [
+          {
+            planId: "pro",
+            category: "paid",
+            billingType: "recurring",
+            creemProductIds: { "every-month": "prod_1" },
+          },
+        ],
+      },
+    });
+
+    expect(snapshot.availableActions).toEqual(["checkout"]);
+    expect(snapshot.activePlanId).toBeNull();
+  });
+
+  it("maps canceled subscription to paid with reactivate action", () => {
+    const snapshot = resolveBillingSnapshot({
+      catalog: {
+        version: "1",
+        plans: [
+          {
+            planId: "pro",
+            category: "paid",
+            billingType: "recurring",
+            creemProductIds: { "every-month": "prod_1" },
+          },
+        ],
+      },
+      currentSubscription: {
+        productId: "prod_1",
+        status: "canceled",
+        recurringInterval: "every-month",
+      },
+    });
+
+    expect(snapshot.activeCategory).toBe("paid");
+    expect(snapshot.availableActions).toContain("reactivate");
+    expect(snapshot.availableActions).toContain("portal");
+  });
+
+  it("uses defaultPlanId as fallback when no subscription product matches", () => {
+    const snapshot = resolveBillingSnapshot({
+      catalog: {
+        version: "1",
+        defaultPlanId: "free",
+        plans: [
+          {
+            planId: "free",
+            category: "free",
+            billingType: "custom",
+          },
+          {
+            planId: "pro",
+            category: "paid",
+            billingType: "recurring",
+            creemProductIds: { "every-month": "prod_1" },
+          },
+        ],
+      },
+    });
+
+    expect(snapshot.activePlanId).toBe("free");
+    expect(snapshot.activeCategory).toBe("free");
+  });
+
+  it("infers onetime billing type from payment when no plan exists", () => {
+    const snapshot = resolveBillingSnapshot({
+      payment: {
+        status: "pending",
+        productId: "prod_unknown",
+      },
+    });
+
+    expect(snapshot.billingType).toBe("onetime");
+    expect(snapshot.activePlanId).toBeNull();
+    expect(snapshot.availableActions).toEqual(["checkout"]);
+  });
+
+  it("infers recurring billing type from subscription when no plan exists", () => {
+    const snapshot = resolveBillingSnapshot({
+      currentSubscription: {
+        status: "active",
+        recurringInterval: "every-year",
+      },
+    });
+
+    expect(snapshot.billingType).toBe("recurring");
+    expect(snapshot.recurringCycle).toBe("every-year");
+    expect(snapshot.availableBillingCycles).toEqual(["every-year"]);
+  });
+
+  it("normalizes unknown recurring interval to custom", () => {
+    const snapshot = resolveBillingSnapshot({
+      currentSubscription: {
+        status: "active",
+        recurringInterval: "every-two-weeks",
+      },
+    });
+
+    expect(snapshot.recurringCycle).toBe("custom");
+  });
+});

package/src/core/resolver.ts

@@ -0,0 +1,160 @@
+import {
+  findPlanById,
+  findPlanByProductId,
+  normalizePlanCatalog,
+  normalizeRecurringCycle,
+} from "./catalog.js";
+import type {
+  AvailableAction,
+  BillingResolverInput,
+  BillingSnapshot,
+  BillingType,
+  PlanCategory,
+  PlanCatalogEntry,
+  SubscriptionSnapshot,
+} from "./types.js";
+
+const toCategoryFromSubscription = (
+  subscription: SubscriptionSnapshot | null | undefined,
+): PlanCategory => {
+  const status = subscription?.status;
+  if (status === "trialing") {
+    return "trial";
+  }
+  if (
+    status === "active" ||
+    status === "scheduled_cancel" ||
+    status === "past_due" ||
+    status === "canceled"
+  ) {
+    return "paid";
+  }
+  return "custom";
+};
+
+const toBillingType = (
+  plan: PlanCatalogEntry | undefined,
+  input: BillingResolverInput,
+): BillingType => {
+  if (plan?.billingType) {
+    return plan.billingType;
+  }
+  if (input.payment) {
+    return "onetime";
+  }
+  if (input.currentSubscription) {
+    return "recurring";
+  }
+  return "custom";
+};
+
+const buildActions = (
+  input: BillingResolverInput,
+  plan: PlanCatalogEntry | undefined,
+  billingType: BillingType,
+): AvailableAction[] => {
+  const actions = new Set<AvailableAction>();
+  const subscription = input.currentSubscription;
+
+  if (plan?.category === "enterprise") {
+    actions.add("contact_sales");
+    return Array.from(actions);
+  }
+
+  if (billingType === "onetime") {
+    actions.add("checkout");
+    return Array.from(actions);
+  }
+
+  if (!subscription) {
+    actions.add("checkout");
+    return Array.from(actions);
+  }
+
+  actions.add("portal");
+
+  if (
+    subscription.status === "active" ||
+    subscription.status === "trialing" ||
+    subscription.status === "scheduled_cancel"
+  ) {
+    actions.add("cancel");
+  }
+
+  if (
+    subscription.status === "canceled" ||
+    subscription.status === "scheduled_cancel"
+  ) {
+    actions.add("reactivate");
+  }
+
+  if ((plan?.billingCycles?.length ?? 0) > 1) {
+    actions.add("switch_interval");
+  }
+
+  if (
+    (plan?.pricingModel === "seat" || subscription.seats != null) &&
+    billingType === "recurring"
+  ) {
+    actions.add("update_seats");
+  }
+
+  return Array.from(actions);
+};
+
+/**
+ * Resolve a `BillingSnapshot` from subscription, catalog, and payment data.
+ * This is the core billing state resolver — determines the active plan, category,
+ * available actions, and metadata based on the current subscription state.
+ *
+ * Used internally by `creem.getBillingSnapshot()`. Can also be called directly
+ * for custom billing UIs that don't use the Creem class.
+ */
+export const resolveBillingSnapshot = (
+  input: BillingResolverInput,
+): BillingSnapshot => {
+  const catalog = normalizePlanCatalog(input.catalog);
+  const subscription = input.currentSubscription ?? null;
+  const planFromSubscription = findPlanByProductId(
+    catalog,
+    subscription?.productId,
+  );
+  const fallbackPlan = catalog?.defaultPlanId
+    ? findPlanById(catalog, catalog.defaultPlanId)
+    : undefined;
+  const activePlan = planFromSubscription ?? fallbackPlan;
+
+  const billingType = toBillingType(activePlan, input);
+  const recurringCycle = normalizeRecurringCycle(
+    subscription?.recurringInterval,
+  );
+  const availableBillingCycles =
+    activePlan?.billingCycles && activePlan.billingCycles.length > 0
+      ? activePlan.billingCycles
+      : recurringCycle
+        ? [recurringCycle]
+        : [];
+
+  return {
+    resolvedAt: input.now ?? new Date().toISOString(),
+    catalogVersion: catalog?.version,
+    activePlanId: activePlan?.planId ?? null,
+    activeCategory:
+      subscription?.status === "trialing"
+        ? "trial"
+        : (activePlan?.category ?? toCategoryFromSubscription(subscription)),
+    billingType,
+    recurringCycle,
+    availableBillingCycles,
+    subscriptionState: subscription?.status,
+    seats: subscription?.seats ?? undefined,
+    payment: input.payment ?? null,
+    availableActions: buildActions(input, activePlan, billingType),
+    metadata: {
+      cancelAtPeriodEnd: subscription?.cancelAtPeriodEnd ?? false,
+      currentPeriodEnd: subscription?.currentPeriodEnd ?? null,
+      trialEnd: subscription?.trialEnd ?? null,
+      userContext: input.userContext ?? {},
+    },
+  };
+};

package/src/core/selectors.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from "vitest";
+import {
+  hasBillingAction,
+  isOneTimeBilling,
+  isEnterpriseBilling,
+  shouldShowBillingCycleToggle,
+  isTerminalPaymentStatus,
+} from "./selectors.js";
+import type { BillingSnapshot } from "./types.js";
+
+const makeSnapshot = (
+  overrides: Partial<BillingSnapshot> = {},
+): BillingSnapshot => ({
+  resolvedAt: new Date().toISOString(),
+  activePlanId: null,
+  activeCategory: "paid",
+  billingType: "recurring",
+  availableBillingCycles: [],
+  payment: null,
+  availableActions: [],
+  ...overrides,
+});
+
+describe("hasBillingAction", () => {
+  it("returns true when action is present", () => {
+    const snapshot = makeSnapshot({ availableActions: ["checkout", "portal"] });
+    expect(hasBillingAction(snapshot, "checkout")).toBe(true);
+    expect(hasBillingAction(snapshot, "portal")).toBe(true);
+  });
+
+  it("returns false when action is absent", () => {
+    const snapshot = makeSnapshot({ availableActions: ["checkout"] });
+    expect(hasBillingAction(snapshot, "cancel")).toBe(false);
+  });
+});
+
+describe("isOneTimeBilling", () => {
+  it("returns true for onetime billing type", () => {
+    expect(isOneTimeBilling(makeSnapshot({ billingType: "onetime" }))).toBe(
+      true,
+    );
+  });
+
+  it("returns false for recurring billing type", () => {
+    expect(isOneTimeBilling(makeSnapshot({ billingType: "recurring" }))).toBe(
+      false,
+    );
+  });
+});
+
+describe("isEnterpriseBilling", () => {
+  it("returns true for enterprise category", () => {
+    expect(
+      isEnterpriseBilling(makeSnapshot({ activeCategory: "enterprise" })),
+    ).toBe(true);
+  });
+
+  it("returns false for paid category", () => {
+    expect(isEnterpriseBilling(makeSnapshot({ activeCategory: "paid" }))).toBe(
+      false,
+    );
+  });
+});
+
+describe("shouldShowBillingCycleToggle", () => {
+  it("returns true when recurring with multiple cycles and switch_interval action", () => {
+    const snapshot = makeSnapshot({
+      billingType: "recurring",
+      availableBillingCycles: ["every-month", "every-year"],
+      availableActions: ["switch_interval", "portal"],
+    });
+    expect(shouldShowBillingCycleToggle(snapshot)).toBe(true);
+  });
+
+  it("returns false when only one cycle available", () => {
+    const snapshot = makeSnapshot({
+      billingType: "recurring",
+      availableBillingCycles: ["every-month"],
+      availableActions: ["switch_interval"],
+    });
+    expect(shouldShowBillingCycleToggle(snapshot)).toBe(false);
+  });
+
+  it("returns false when onetime billing type", () => {
+    const snapshot = makeSnapshot({
+      billingType: "onetime",
+      availableBillingCycles: ["every-month", "every-year"],
+      availableActions: ["switch_interval"],
+    });
+    expect(shouldShowBillingCycleToggle(snapshot)).toBe(false);
+  });
+
+  it("returns false when switch_interval action is not available", () => {
+    const snapshot = makeSnapshot({
+      billingType: "recurring",
+      availableBillingCycles: ["every-month", "every-year"],
+      availableActions: ["portal"],
+    });
+    expect(shouldShowBillingCycleToggle(snapshot)).toBe(false);
+  });
+});
+
+describe("isTerminalPaymentStatus", () => {
+  it("returns true for paid", () => {
+    expect(isTerminalPaymentStatus("paid")).toBe(true);
+  });
+
+  it("returns true for refunded", () => {
+    expect(isTerminalPaymentStatus("refunded")).toBe(true);
+  });
+
+  it("returns true for partially_refunded", () => {
+    expect(isTerminalPaymentStatus("partially_refunded")).toBe(true);
+  });
+
+  it("returns false for pending", () => {
+    expect(isTerminalPaymentStatus("pending")).toBe(false);
+  });
+});

package/src/core/selectors.ts

@@ -0,0 +1,35 @@
+import type {
+  AvailableAction,
+  BillingSnapshot,
+  OneTimePaymentStatus,
+} from "./types.js";
+
+const TERMINAL_PAYMENT_STATUSES = new Set<OneTimePaymentStatus>([
+  "paid",
+  "refunded",
+  "partially_refunded",
+]);
+
+/** Check whether a specific action is available in the given billing snapshot. */
+export const hasBillingAction = (
+  snapshot: BillingSnapshot,
+  action: AvailableAction,
+) => snapshot.availableActions.includes(action);
+
+/** Check whether the billing snapshot represents a one-time purchase (not a subscription). */
+export const isOneTimeBilling = (snapshot: BillingSnapshot) =>
+  snapshot.billingType === "onetime";
+
+/** Check whether the billing snapshot represents an enterprise plan. */
+export const isEnterpriseBilling = (snapshot: BillingSnapshot) =>
+  snapshot.activeCategory === "enterprise";
+
+/** Whether the billing cycle toggle (e.g. Monthly/Yearly) should be shown in the UI. */
+export const shouldShowBillingCycleToggle = (snapshot: BillingSnapshot) =>
+  snapshot.billingType === "recurring" &&
+  snapshot.availableBillingCycles.length > 1 &&
+  hasBillingAction(snapshot, "switch_interval");
+
+/** Whether the payment status is terminal (paid, refunded, or partially refunded). */
+export const isTerminalPaymentStatus = (status: OneTimePaymentStatus) =>
+  TERMINAL_PAYMENT_STATUSES.has(status);