@mmailaender/convex-creem 0.1.0

package/src/core/catalog.test.ts

@@ -0,0 +1,212 @@
+import { describe, expect, it } from "vitest";
+import {
+  isSupportedRecurringCycle,
+  normalizeRecurringCycle,
+  normalizePlanCategory,
+  normalizeBillingType,
+  normalizePlanCatalog,
+  findPlanById,
+  findPlanByProductId,
+} from "./catalog.js";
+
+describe("isSupportedRecurringCycle", () => {
+  it("returns true for every-month", () => {
+    expect(isSupportedRecurringCycle("every-month")).toBe(true);
+  });
+
+  it("returns true for every-year", () => {
+    expect(isSupportedRecurringCycle("every-year")).toBe(true);
+  });
+
+  it("returns false for unknown cycle", () => {
+    expect(isSupportedRecurringCycle("weekly")).toBe(false);
+  });
+});
+
+describe("normalizeRecurringCycle", () => {
+  it("returns undefined for null", () => {
+    expect(normalizeRecurringCycle(null)).toBeUndefined();
+  });
+
+  it("returns undefined for undefined", () => {
+    expect(normalizeRecurringCycle(undefined)).toBeUndefined();
+  });
+
+  it("returns the value for supported cycles", () => {
+    expect(normalizeRecurringCycle("every-month")).toBe("every-month");
+    expect(normalizeRecurringCycle("every-three-months")).toBe(
+      "every-three-months",
+    );
+    expect(normalizeRecurringCycle("every-six-months")).toBe(
+      "every-six-months",
+    );
+    expect(normalizeRecurringCycle("every-year")).toBe("every-year");
+  });
+
+  it("returns custom for unsupported cycles", () => {
+    expect(normalizeRecurringCycle("weekly")).toBe("custom");
+    expect(normalizeRecurringCycle("biweekly")).toBe("custom");
+  });
+});
+
+describe("normalizePlanCategory", () => {
+  it("returns custom for null", () => {
+    expect(normalizePlanCategory(null)).toBe("custom");
+  });
+
+  it("returns custom for undefined", () => {
+    expect(normalizePlanCategory(undefined)).toBe("custom");
+  });
+
+  it("returns the value for known categories", () => {
+    expect(normalizePlanCategory("free")).toBe("free");
+    expect(normalizePlanCategory("trial")).toBe("trial");
+    expect(normalizePlanCategory("paid")).toBe("paid");
+    expect(normalizePlanCategory("enterprise")).toBe("enterprise");
+    expect(normalizePlanCategory("custom")).toBe("custom");
+  });
+
+  it("returns custom for unknown values", () => {
+    expect(normalizePlanCategory("premium")).toBe("custom");
+    expect(normalizePlanCategory("vip")).toBe("custom");
+  });
+});
+
+describe("normalizeBillingType", () => {
+  it("returns custom for null", () => {
+    expect(normalizeBillingType(null)).toBe("custom");
+  });
+
+  it("returns custom for undefined", () => {
+    expect(normalizeBillingType(undefined)).toBe("custom");
+  });
+
+  it("returns the value for known types", () => {
+    expect(normalizeBillingType("recurring")).toBe("recurring");
+    expect(normalizeBillingType("onetime")).toBe("onetime");
+    expect(normalizeBillingType("custom")).toBe("custom");
+  });
+
+  it("returns custom for unknown values", () => {
+    expect(normalizeBillingType("metered")).toBe("custom");
+  });
+});
+
+describe("normalizePlanCatalog", () => {
+  it("returns undefined for null", () => {
+    expect(normalizePlanCatalog(null)).toBeUndefined();
+  });
+
+  it("returns undefined for undefined", () => {
+    expect(normalizePlanCatalog(undefined)).toBeUndefined();
+  });
+
+  it("normalizes plan entries", () => {
+    const catalog = normalizePlanCatalog({
+      version: "1",
+      plans: [
+        {
+          planId: "pro",
+          category: "paid",
+          billingType: "recurring",
+          billingCycles: ["every-month", "every-year"],
+        },
+        {
+          planId: "custom",
+          category: "unknown_category" as any,
+          billingType: "unknown_type" as any,
+          billingCycles: ["every-month", "biweekly" as any],
+        },
+      ],
+    });
+    expect(catalog).toBeDefined();
+    expect(catalog!.plans[0].category).toBe("paid");
+    expect(catalog!.plans[0].billingType).toBe("recurring");
+    expect(catalog!.plans[0].billingCycles).toEqual([
+      "every-month",
+      "every-year",
+    ]);
+    // Unknown values normalize to "custom"
+    expect(catalog!.plans[1].category).toBe("custom");
+    expect(catalog!.plans[1].billingType).toBe("custom");
+    expect(catalog!.plans[1].billingCycles).toEqual(["every-month", "custom"]);
+  });
+
+  it("filters out null cycles from normalization", () => {
+    const catalog = normalizePlanCatalog({
+      version: "1",
+      plans: [
+        {
+          planId: "test",
+          category: "paid",
+          billingCycles: [null as any, "every-month"],
+        },
+      ],
+    });
+    // null normalizes to undefined which gets filtered out
+    expect(catalog!.plans[0].billingCycles).toEqual(["every-month"]);
+  });
+});
+
+describe("findPlanById", () => {
+  const catalog = {
+    version: "1",
+    plans: [
+      { planId: "free", category: "free" as const },
+      { planId: "pro", category: "paid" as const },
+    ],
+  };
+
+  it("finds a plan by id", () => {
+    expect(findPlanById(catalog, "pro")).toEqual({
+      planId: "pro",
+      category: "paid",
+    });
+  });
+
+  it("returns undefined for unknown id", () => {
+    expect(findPlanById(catalog, "enterprise")).toBeUndefined();
+  });
+
+  it("returns undefined for undefined catalog", () => {
+    expect(findPlanById(undefined, "pro")).toBeUndefined();
+  });
+});
+
+describe("findPlanByProductId", () => {
+  const catalog = {
+    version: "1",
+    plans: [
+      {
+        planId: "pro",
+        category: "paid" as const,
+        creemProductIds: {
+          "every-month": "prod_1",
+          "every-year": "prod_2",
+        } as Record<string, string>,
+      },
+      {
+        planId: "basic",
+        category: "paid" as const,
+        creemProductIds: { "every-month": "prod_3" } as Record<string, string>,
+      },
+    ],
+  };
+
+  it("finds plan by product id", () => {
+    expect(findPlanByProductId(catalog, "prod_2")?.planId).toBe("pro");
+    expect(findPlanByProductId(catalog, "prod_3")?.planId).toBe("basic");
+  });
+
+  it("returns undefined for unknown product id", () => {
+    expect(findPlanByProductId(catalog, "prod_unknown")).toBeUndefined();
+  });
+
+  it("returns undefined for undefined catalog", () => {
+    expect(findPlanByProductId(undefined, "prod_1")).toBeUndefined();
+  });
+
+  it("returns undefined for undefined productId", () => {
+    expect(findPlanByProductId(catalog, undefined)).toBeUndefined();
+  });
+});

package/src/core/catalog.ts

@@ -0,0 +1,119 @@
+import type {
+  BillingType,
+  PlanCatalog,
+  PlanCatalogEntry,
+  PlanCategory,
+  RecurringCycle,
+  SupportedRecurringCycle,
+} from "./types.js";
+
+/** All billing cycles supported by the Creem API, in display order. */
+export const SUPPORTED_RECURRING_CYCLES: SupportedRecurringCycle[] = [
+  "every-month",
+  "every-three-months",
+  "every-six-months",
+  "every-year",
+];
+
+const PLAN_CATEGORIES: PlanCategory[] = [
+  "free",
+  "trial",
+  "paid",
+  "enterprise",
+  "custom",
+];
+
+const BILLING_TYPES: BillingType[] = ["recurring", "onetime", "custom"];
+
+const PLAN_CATEGORY_SET = new Set(PLAN_CATEGORIES);
+const BILLING_TYPE_SET = new Set(BILLING_TYPES);
+const RECURRING_CYCLE_SET = new Set(SUPPORTED_RECURRING_CYCLES);
+
+/** Type guard: check if a string is a supported Creem billing cycle. */
+export const isSupportedRecurringCycle = (
+  value: string,
+): value is SupportedRecurringCycle =>
+  RECURRING_CYCLE_SET.has(value as SupportedRecurringCycle);
+
+/** Normalize a billing cycle string to a `RecurringCycle`. Returns `"custom"` for unrecognized values, `undefined` for nullish. */
+export const normalizeRecurringCycle = (
+  value: string | null | undefined,
+): RecurringCycle | undefined => {
+  if (!value) {
+    return undefined;
+  }
+  if (isSupportedRecurringCycle(value)) {
+    return value;
+  }
+  return "custom";
+};
+
+/** Normalize a plan category string. Returns `"custom"` for unrecognized or nullish values. */
+export const normalizePlanCategory = (
+  value: string | null | undefined,
+): PlanCategory => {
+  if (!value) {
+    return "custom";
+  }
+  if (PLAN_CATEGORY_SET.has(value as PlanCategory)) {
+    return value as PlanCategory;
+  }
+  return "custom";
+};
+
+/** Normalize a billing type string. Returns `"custom"` for unrecognized or nullish values. */
+export const normalizeBillingType = (
+  value: string | null | undefined,
+): BillingType => {
+  if (!value) {
+    return "custom";
+  }
+  if (BILLING_TYPE_SET.has(value as BillingType)) {
+    return value as BillingType;
+  }
+  return "custom";
+};
+
+/** Normalize all entries in a plan catalog (categories, billing types, cycles). Returns `undefined` for nullish input. */
+export const normalizePlanCatalog = (
+  catalog: PlanCatalog | null | undefined,
+): PlanCatalog | undefined => {
+  if (!catalog) {
+    return undefined;
+  }
+  return {
+    ...catalog,
+    plans: catalog.plans.map((plan) => ({
+      ...plan,
+      category: normalizePlanCategory(plan.category),
+      billingType: normalizeBillingType(plan.billingType),
+      billingCycles: (plan.billingCycles ?? [])
+        .map((cycle) => normalizeRecurringCycle(cycle))
+        .flatMap((cycle) => (cycle ? [cycle] : [])),
+    })),
+  };
+};
+
+/** Find a plan in the catalog by its `planId`. */
+export const findPlanById = (
+  catalog: PlanCatalog | undefined,
+  planId: string,
+): PlanCatalogEntry | undefined => {
+  if (!catalog) {
+    return undefined;
+  }
+  return catalog.plans.find((plan) => plan.planId === planId);
+};
+
+/** Find a plan in the catalog that contains the given Creem product ID in its `creemProductIds`. */
+export const findPlanByProductId = (
+  catalog: PlanCatalog | undefined,
+  productId: string | undefined,
+): PlanCatalogEntry | undefined => {
+  if (!catalog || !productId) {
+    return undefined;
+  }
+  return catalog.plans.find((plan) =>
+    Object.values(plan.creemProductIds ?? {}).includes(productId),
+  );
+};

package/src/core/index.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./catalog.js";
+export * from "./resolver.js";
+export * from "./selectors.js";
+export * from "./payments.js";
+export * from "./markdown.js";
+export { pendingCheckout } from "./pendingCheckout.js";
+export * from "./subscriptionUpdate.js";

package/src/core/markdown.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { renderMarkdown, renderMarkdownInline } from "./markdown.js";
+
+describe("renderMarkdown", () => {
+  it("renders basic markdown to HTML", () => {
+    const result = renderMarkdown("**bold** text");
+    expect(result).toContain("<strong>bold</strong>");
+    expect(result).toContain("text");
+  });
+
+  it("returns empty string for null input", () => {
+    expect(renderMarkdown(null)).toBe("");
+  });
+
+  it("returns empty string for undefined input", () => {
+    expect(renderMarkdown(undefined)).toBe("");
+  });
+
+  it("returns empty string for empty string input", () => {
+    expect(renderMarkdown("")).toBe("");
+  });
+
+  it("renders GFM line breaks", () => {
+    const result = renderMarkdown("line1\nline2");
+    expect(result).toContain("<br");
+  });
+});
+
+describe("renderMarkdownInline", () => {
+  it("renders inline markdown without wrapping p tags", () => {
+    const result = renderMarkdownInline("**bold** text");
+    expect(result).toContain("<strong>bold</strong>");
+    expect(result).not.toContain("<p>");
+  });
+
+  it("returns empty string for null input", () => {
+    expect(renderMarkdownInline(null)).toBe("");
+  });
+
+  it("returns empty string for undefined input", () => {
+    expect(renderMarkdownInline(undefined)).toBe("");
+  });
+});

package/src/core/markdown.ts

@@ -0,0 +1,26 @@
+import { Marked } from "marked";
+
+const marked = new Marked({
+  async: false,
+  gfm: true,
+  breaks: true,
+});
+
+/**
+ * Render a markdown string to HTML.
+ * Intended for short product/plan descriptions synced from Creem.
+ * Returns an empty string for nullish input.
+ */
+export function renderMarkdown(md: string | undefined | null): string {
+  if (!md) return "";
+  return marked.parse(md) as string;
+}
+
+/**
+ * Render a markdown string to inline HTML (no wrapping `<p>` tags).
+ * Useful for single-line titles or short labels.
+ */
+export function renderMarkdownInline(md: string | undefined | null): string {
+  if (!md) return "";
+  return marked.parseInline(md) as string;
+}

package/src/core/payments.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import {
+  parseCheckoutSuccessParams,
+  hasCheckoutSuccessParams,
+} from "./payments.js";
+
+describe("parseCheckoutSuccessParams", () => {
+  it("parses a full query string with leading ?", () => {
+    const result = parseCheckoutSuccessParams(
+      "?checkout_id=chk_1&order_id=ord_2&customer_id=cus_3&product_id=prod_4&request_id=req_5&signature=sig_6",
+    );
+    expect(result).toEqual({
+      checkoutId: "chk_1",
+      orderId: "ord_2",
+      customerId: "cus_3",
+      productId: "prod_4",
+      requestId: "req_5",
+      signature: "sig_6",
+    });
+  });
+
+  it("parses a query string without leading ?", () => {
+    const result = parseCheckoutSuccessParams(
+      "checkout_id=chk_1&order_id=ord_2",
+    );
+    expect(result.checkoutId).toBe("chk_1");
+    expect(result.orderId).toBe("ord_2");
+  });
+
+  it("returns undefined for missing params", () => {
+    const result = parseCheckoutSuccessParams("");
+    expect(result.checkoutId).toBeUndefined();
+    expect(result.orderId).toBeUndefined();
+    expect(result.customerId).toBeUndefined();
+    expect(result.productId).toBeUndefined();
+    expect(result.requestId).toBeUndefined();
+    expect(result.signature).toBeUndefined();
+  });
+
+  it("accepts a URLSearchParams instance", () => {
+    const params = new URLSearchParams({
+      checkout_id: "chk_url",
+      order_id: "ord_url",
+    });
+    const result = parseCheckoutSuccessParams(params);
+    expect(result.checkoutId).toBe("chk_url");
+    expect(result.orderId).toBe("ord_url");
+  });
+});
+
+describe("hasCheckoutSuccessParams", () => {
+  it("returns true when both checkoutId and orderId are present", () => {
+    expect(
+      hasCheckoutSuccessParams({ checkoutId: "chk_1", orderId: "ord_1" }),
+    ).toBe(true);
+  });
+
+  it("returns false when checkoutId is missing", () => {
+    expect(hasCheckoutSuccessParams({ orderId: "ord_1" })).toBe(false);
+  });
+
+  it("returns false when orderId is missing", () => {
+    expect(hasCheckoutSuccessParams({ checkoutId: "chk_1" })).toBe(false);
+  });
+
+  it("returns false when both are missing", () => {
+    expect(hasCheckoutSuccessParams({})).toBe(false);
+  });
+});

package/src/core/payments.ts

@@ -0,0 +1,33 @@
+import type { CheckoutSuccessParams } from "./types.js";
+
+const getSearchParams = (search: string | URLSearchParams): URLSearchParams => {
+  if (search instanceof URLSearchParams) {
+    return search;
+  }
+  const raw = search.startsWith("?") ? search.slice(1) : search;
+  return new URLSearchParams(raw);
+};
+
+/**
+ * Parse Creem checkout success query parameters from a URL search string.
+ * Call on your success page to extract checkout/order/customer/product IDs.
+ *
+ * @param search - URL search string (e.g. `window.location.search`) or `URLSearchParams` instance
+ */
+export const parseCheckoutSuccessParams = (
+  search: string | URLSearchParams,
+): CheckoutSuccessParams => {
+  const params = getSearchParams(search);
+  return {
+    checkoutId: params.get("checkout_id") ?? undefined,
+    orderId: params.get("order_id") ?? undefined,
+    customerId: params.get("customer_id") ?? undefined,
+    productId: params.get("product_id") ?? undefined,
+    requestId: params.get("request_id") ?? undefined,
+    signature: params.get("signature") ?? undefined,
+  };
+};
+
+/** Check if the parsed params contain the minimum required fields for a valid checkout success (checkoutId + orderId). */
+export const hasCheckoutSuccessParams = (params: CheckoutSuccessParams) =>
+  Boolean(params.checkoutId && params.orderId);

package/src/core/pendingCheckout.test.ts

@@ -0,0 +1,44 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach } from "vitest";
+import { pendingCheckout } from "./pendingCheckout.js";
+
+describe("pendingCheckout", () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+  });
+
+  it("save stores intent in sessionStorage", () => {
+    pendingCheckout.save({ productId: "prod_123" });
+    const raw = sessionStorage.getItem("creem:pending-checkout");
+    expect(raw).not.toBeNull();
+    expect(JSON.parse(raw!)).toEqual({ productId: "prod_123" });
+  });
+
+  it("save stores intent with units", () => {
+    pendingCheckout.save({ productId: "prod_abc", units: 5 });
+    const raw = sessionStorage.getItem("creem:pending-checkout");
+    expect(JSON.parse(raw!)).toEqual({ productId: "prod_abc", units: 5 });
+  });
+
+  it("load returns the saved intent and clears storage", () => {
+    pendingCheckout.save({ productId: "prod_xyz" });
+    const intent = pendingCheckout.load();
+    expect(intent).toEqual({ productId: "prod_xyz" });
+    // Should be cleared after load
+    expect(sessionStorage.getItem("creem:pending-checkout")).toBeNull();
+  });
+
+  it("load returns null when nothing is saved", () => {
+    expect(pendingCheckout.load()).toBeNull();
+  });
+
+  it("clear removes the saved intent", () => {
+    pendingCheckout.save({ productId: "prod_del" });
+    pendingCheckout.clear();
+    expect(sessionStorage.getItem("creem:pending-checkout")).toBeNull();
+  });
+
+  it("clear is safe when nothing is saved", () => {
+    expect(() => pendingCheckout.clear()).not.toThrow();
+  });
+});

package/src/core/pendingCheckout.ts

@@ -0,0 +1,40 @@
+import type { CheckoutIntent } from "./types.js";
+
+const STORAGE_KEY = "creem:pending-checkout";
+
+/**
+ * Tiny sessionStorage-based helper for the "save intent → sign in → resume" pattern.
+ *
+ * Usage:
+ * 1. In `onBeforeCheckout`, call `pendingCheckout.save(intent)` then open sign-in
+ * 2. After auth completes, call `pendingCheckout.load()` — returns the intent and auto-clears
+ * 3. Resume checkout with the loaded intent (e.g. call `checkouts.create` manually)
+ */
+export const pendingCheckout = {
+  save(intent: CheckoutIntent): void {
+    try {
+      sessionStorage.setItem(STORAGE_KEY, JSON.stringify(intent));
+    } catch {
+      // sessionStorage unavailable (SSR, private browsing quota) — silently ignore
+    }
+  },
+
+  load(): CheckoutIntent | null {
+    try {
+      const raw = sessionStorage.getItem(STORAGE_KEY);
+      if (!raw) return null;
+      sessionStorage.removeItem(STORAGE_KEY);
+      return JSON.parse(raw) as CheckoutIntent;
+    } catch {
+      return null;
+    }
+  },
+
+  clear(): void {
+    try {
+      sessionStorage.removeItem(STORAGE_KEY);
+    } catch {
+      // silently ignore
+    }
+  },
+};