@mmailaender/convex-creem 0.1.0

package/src/core/subscriptionUpdate.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildUpdateSummary,
+  type UpdateSummaryInput,
+} from "./subscriptionUpdate.js";
+
+const base: UpdateSummaryInput = {
+  kind: "plan-switch",
+  updateBehavior: "proration-charge-immediately",
+  currentLabel: "Basic",
+  newLabel: "Premium",
+};
+
+describe("buildUpdateSummary", () => {
+  describe("plan-switch", () => {
+    it("returns correct title for plan-switch", () => {
+      const result = buildUpdateSummary(base);
+      expect(result.title).toBe("Switch plan?");
+      expect(result.confirmLabel).toBe("Confirm switch");
+    });
+
+    it("describes proration-charge-immediately", () => {
+      const result = buildUpdateSummary(base);
+      expect(result.description).toContain("prorated and charged immediately");
+    });
+
+    it("describes proration-charge", () => {
+      const result = buildUpdateSummary({
+        ...base,
+        updateBehavior: "proration-charge",
+      });
+      expect(result.description).toContain(
+        "prorated and applied to your next invoice",
+      );
+    });
+
+    it("describes proration-none", () => {
+      const result = buildUpdateSummary({
+        ...base,
+        updateBehavior: "proration-none",
+      });
+      expect(result.description).toContain("next billing cycle");
+    });
+
+    it("preserves labels", () => {
+      const result = buildUpdateSummary(base);
+      expect(result.currentLabel).toBe("Basic");
+      expect(result.newLabel).toBe("Premium");
+    });
+  });
+
+  describe("seat-update", () => {
+    it("returns correct title for seat-update", () => {
+      const result = buildUpdateSummary({ ...base, kind: "seat-update" });
+      expect(result.title).toBe("Update seats?");
+      expect(result.confirmLabel).toBe("Confirm update");
+    });
+  });
+
+  describe("dateNote with currentPeriodEnd", () => {
+    it("includes date note for proration-charge", () => {
+      const result = buildUpdateSummary({
+        ...base,
+        updateBehavior: "proration-charge",
+        currentPeriodEnd: "2025-06-15T00:00:00Z",
+      });
+      expect(result.dateNote).toContain("next invoice");
+      expect(result.dateNote).toContain("2025");
+    });
+
+    it("includes date note for proration-none", () => {
+      const result = buildUpdateSummary({
+        ...base,
+        updateBehavior: "proration-none",
+        currentPeriodEnd: "2025-06-15T00:00:00Z",
+      });
+      expect(result.dateNote).toContain("next billing cycle");
+      expect(result.dateNote).toContain("2025");
+    });
+
+    it("returns null dateNote for proration-charge-immediately", () => {
+      const result = buildUpdateSummary({
+        ...base,
+        updateBehavior: "proration-charge-immediately",
+        currentPeriodEnd: "2025-06-15T00:00:00Z",
+      });
+      expect(result.dateNote).toBeNull();
+    });
+
+    it("returns null dateNote when no currentPeriodEnd", () => {
+      const result = buildUpdateSummary({
+        ...base,
+        updateBehavior: "proration-charge",
+      });
+      expect(result.dateNote).toBeNull();
+    });
+
+    it("returns null dateNote for invalid date", () => {
+      const result = buildUpdateSummary({
+        ...base,
+        updateBehavior: "proration-charge",
+        currentPeriodEnd: "not-a-date",
+      });
+      expect(result.dateNote).toBeNull();
+    });
+  });
+
+  describe("trial handling", () => {
+    it("returns trial description when isTrialing is true", () => {
+      const result = buildUpdateSummary({
+        ...base,
+        isTrialing: true,
+      });
+      expect(result.description).toContain("trial");
+      expect(result.dateNote).toBeNull();
+    });
+
+    it("includes trial end date when provided", () => {
+      const result = buildUpdateSummary({
+        ...base,
+        isTrialing: true,
+        trialEnd: "2025-07-01T00:00:00Z",
+      });
+      expect(result.description).toContain("trial");
+      expect(result.description).toContain("2025");
+    });
+
+    it("uses generic trial message when trialEnd is null", () => {
+      const result = buildUpdateSummary({
+        ...base,
+        isTrialing: true,
+        trialEnd: null,
+      });
+      expect(result.description).toContain("free trial will continue");
+    });
+
+    it("handles invalid trialEnd date gracefully", () => {
+      const result = buildUpdateSummary({
+        ...base,
+        isTrialing: true,
+        trialEnd: "invalid-date",
+      });
+      // Falls back to generic trial message
+      expect(result.description).toContain("free trial will continue");
+    });
+
+    it("returns correct confirm label for trial plan-switch", () => {
+      const result = buildUpdateSummary({
+        ...base,
+        isTrialing: true,
+      });
+      expect(result.confirmLabel).toBe("Confirm switch");
+    });
+
+    it("returns correct confirm label for trial seat-update", () => {
+      const result = buildUpdateSummary({
+        ...base,
+        kind: "seat-update",
+        isTrialing: true,
+      });
+      expect(result.confirmLabel).toBe("Confirm update");
+    });
+  });
+});

package/src/core/subscriptionUpdate.ts

@@ -0,0 +1,102 @@
+import type { UpdateBehavior } from "./types.js";
+
+export type UpdateSummaryInput = {
+  kind: "plan-switch" | "seat-update";
+  updateBehavior: UpdateBehavior;
+  currentLabel: string;
+  newLabel: string;
+  currentPeriodEnd?: string | null;
+  isTrialing?: boolean;
+  trialEnd?: string | null;
+};
+
+export type UpdateSummary = {
+  title: string;
+  description: string;
+  currentLabel: string;
+  newLabel: string;
+  dateNote: string | null;
+  confirmLabel: string;
+};
+
+const getBehaviorDescription = (updateBehavior: UpdateBehavior): string => {
+  switch (updateBehavior) {
+    case "proration-charge-immediately":
+      return "The price difference will be prorated and charged immediately.";
+    case "proration-charge":
+      return "The price difference will be prorated and applied to your next invoice.";
+    case "proration-none":
+      return "The new price will take effect at your next billing cycle.";
+  }
+};
+
+const formatPeriodEnd = (
+  iso: string,
+  updateBehavior: UpdateBehavior,
+): string | null => {
+  const date = new Date(iso);
+  if (isNaN(date.getTime())) return null;
+  const formatted = date.toLocaleDateString(undefined, {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+  });
+  if (updateBehavior === "proration-charge") {
+    return `Your next invoice is on ${formatted}.`;
+  }
+  if (updateBehavior === "proration-none") {
+    return `Your next billing cycle starts on ${formatted}.`;
+  }
+  return null;
+};
+
+const formatTrialEnd = (iso: string): string | null => {
+  const date = new Date(iso);
+  if (isNaN(date.getTime())) return null;
+  const formatted = date.toLocaleDateString(undefined, {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+  });
+  return `Your trial continues until ${formatted}. The new price will apply once the trial ends.`;
+};
+
+export const buildUpdateSummary = (
+  input: UpdateSummaryInput,
+): UpdateSummary => {
+  const {
+    kind,
+    updateBehavior,
+    currentLabel,
+    newLabel,
+    currentPeriodEnd,
+    isTrialing,
+    trialEnd,
+  } = input;
+
+  if (isTrialing) {
+    const trialNote = trialEnd ? formatTrialEnd(trialEnd) : null;
+    return {
+      title: kind === "plan-switch" ? "Switch plan?" : "Update seats?",
+      description:
+        trialNote ??
+        "Your free trial will continue. The new price will take effect once the trial ends.",
+      currentLabel,
+      newLabel,
+      dateNote: null,
+      confirmLabel:
+        kind === "plan-switch" ? "Confirm switch" : "Confirm update",
+    };
+  }
+
+  return {
+    title: kind === "plan-switch" ? "Switch plan?" : "Update seats?",
+    description: getBehaviorDescription(updateBehavior),
+    currentLabel,
+    newLabel,
+    dateNote: currentPeriodEnd
+      ? formatPeriodEnd(currentPeriodEnd, updateBehavior)
+      : null,
+    confirmLabel: kind === "plan-switch" ? "Confirm switch" : "Confirm update",
+  };
+};

package/src/core/types.ts

@@ -0,0 +1,220 @@
+/** Category of a billing plan. Determines default UI behavior and available actions. */
+export type PlanCategory = "free" | "trial" | "paid" | "enterprise" | "custom";
+
+/** Billing model type. `"recurring"` for subscriptions, `"onetime"` for single purchases. */
+export type BillingType = "recurring" | "onetime" | "custom";
+
+/** Billing cycles supported by the Creem API. */
+export type SupportedRecurringCycle =
+  | "every-month"
+  | "every-three-months"
+  | "every-six-months"
+  | "every-year";
+
+/** Billing cycle including a `"custom"` fallback for unrecognized intervals. */
+export type RecurringCycle = SupportedRecurringCycle | "custom";
+
+/** Status of a one-time payment order. */
+export type OneTimePaymentStatus =
+  | "pending"
+  | "paid"
+  | "refunded"
+  | "partially_refunded";
+
+/**
+ * Actions the current billing entity is allowed to perform.
+ * Resolved by `resolveBillingSnapshot` based on subscription state.
+ * Use with `<BillingGate requiredActions="...">` for conditional UI rendering.
+ */
+export type AvailableAction =
+  | "checkout"
+  | "portal"
+  | "cancel"
+  | "reactivate"
+  | "switch_interval"
+  | "update_seats"
+  | "contact_sales";
+
+/** A single plan definition in the billing catalog. */
+export type PlanCatalogEntry = {
+  /** Unique plan identifier (e.g. `"basic"`, `"premium"`). */
+  planId: string;
+  /** Plan category — drives default UI behavior and action resolution. */
+  category: PlanCategory;
+  /** Billing model. Defaults to `"recurring"` if omitted. */
+  billingType?: BillingType;
+  /** Supported billing cycles for this plan (e.g. `["every-month", "every-year"]`). */
+  billingCycles?: RecurringCycle[];
+  /** Pricing model — `"seat"` enables per-seat controls in widgets. */
+  pricingModel?: "flat" | "seat";
+  /** Map of billing cycle → Creem product ID (e.g. `{ "every-month": "prod_xxx" }`). */
+  creemProductIds?: Record<string, string>;
+  /** "Contact sales" URL for enterprise plans. */
+  contactUrl?: string;
+  /** Highlight this plan as recommended in the UI. */
+  recommended?: boolean;
+  /** Arbitrary metadata for custom logic. */
+  metadata?: Record<string, unknown>;
+};
+
+/** Plan catalog entry enriched with resolved UI display fields from Creem product data. */
+export type UIPlanEntry = PlanCatalogEntry & {
+  /** Display title (auto-resolved from Creem product name if omitted). */
+  title?: string;
+  /** Display description (auto-resolved from Creem product description, rendered as Markdown). */
+  description?: string;
+};
+
+/** Static plan catalog configuration. Defines available plans and their Creem product mappings. */
+export type PlanCatalog = {
+  /** Catalog version string (included in `BillingSnapshot.catalogVersion`). */
+  version: string;
+  /** Ordered list of plan definitions. */
+  plans: PlanCatalogEntry[];
+  /** Plan ID to use when no subscription is active (e.g. `"free"`). */
+  defaultPlanId?: string;
+};
+
+/** Lightweight subscription state used by the billing resolver. */
+export type SubscriptionSnapshot = {
+  /** Creem subscription ID. */
+  id?: string;
+  /** Creem product ID of the subscribed plan. */
+  productId?: string;
+  /** Subscription status (e.g. `"active"`, `"trialing"`, `"canceled"`, `"paused"`, `"scheduled_cancel"`). */
+  status?: string;
+  /** Billing interval (e.g. `"every-month"`, `"every-year"`). */
+  recurringInterval?: string | null;
+  /** Number of seats (for seat-based pricing). */
+  seats?: number | null;
+  /** Whether the subscription is set to cancel at the end of the current period. */
+  cancelAtPeriodEnd?: boolean;
+  /** ISO timestamp of the current period end. */
+  currentPeriodEnd?: string | null;
+  /** ISO timestamp when the trial expires. */
+  trialEnd?: string | null;
+};
+
+/** Snapshot of a one-time payment, parsed from checkout success query params. */
+export type PaymentSnapshot = {
+  /** Payment status. */
+  status: OneTimePaymentStatus;
+  /** Creem checkout ID. */
+  checkoutId?: string;
+  /** Creem order ID. */
+  orderId?: string;
+  /** Creem customer ID. */
+  customerId?: string;
+  /** Creem product ID. */
+  productId?: string;
+  /** Your custom request ID (passed via checkout metadata). */
+  requestId?: string;
+};
+
+/** Query parameters from a Creem checkout success redirect URL. Parsed by `parseCheckoutSuccessParams`. */
+export type CheckoutSuccessParams = {
+  /** Creem checkout session ID (`checkout_id` query param). */
+  checkoutId?: string;
+  /** Creem order ID (`order_id` query param). */
+  orderId?: string;
+  /** Creem customer ID (`customer_id` query param). */
+  customerId?: string;
+  /** Creem product ID (`product_id` query param). */
+  productId?: string;
+  /** Your custom request ID (`request_id` query param). */
+  requestId?: string;
+  /** Creem signature for verification (`signature` query param). */
+  signature?: string;
+};
+
+/**
+ * Resolved billing state for a billing entity.
+ * Central data structure consumed by widgets and `<BillingGate>`.
+ * Produced by `creem.getBillingSnapshot()` or `resolveBillingSnapshot()`.
+ */
+export type BillingSnapshot = {
+  /** ISO timestamp when this snapshot was resolved. */
+  resolvedAt: string;
+  /** Version of the plan catalog used for resolution (if a catalog was provided). */
+  catalogVersion?: string;
+  /** ID of the currently active plan (from the catalog), or `null` if none matched. */
+  activePlanId: string | null;
+  /** Category of the active plan (e.g. `"free"`, `"paid"`, `"trial"`, `"enterprise"`). */
+  activeCategory: PlanCategory;
+  /** Current billing model. */
+  billingType: BillingType;
+  /** Current billing interval (e.g. `"every-month"`). */
+  recurringCycle?: RecurringCycle;
+  /** All billing cycles available for the active plan. Used by `<BillingToggle>`. */
+  availableBillingCycles: RecurringCycle[];
+  /** Raw subscription status string (e.g. `"active"`, `"trialing"`, `"canceled"`). */
+  subscriptionState?: string;
+  /** Current seat count for seat-based subscriptions. */
+  seats?: number;
+  /** One-time payment state, or `null` if not applicable. */
+  payment: PaymentSnapshot | null;
+  /** Actions the billing entity is allowed to perform. */
+  availableActions: AvailableAction[];
+  /** Additional metadata (cancelAtPeriodEnd, currentPeriodEnd, trialEnd, userContext). */
+  metadata?: Record<string, unknown>;
+};
+
+/**
+ * Intent object passed to `onBeforeCheckout` and stored by `pendingCheckout`.
+ * Represents the product and optional seat count the user wants to purchase.
+ */
+export type CheckoutIntent = {
+  /** Creem product ID to purchase. */
+  productId: string;
+  /** Number of seats/units (for seat-based plans). */
+  units?: number;
+};
+
+/**
+ * How the Creem API handles plan switches and seat changes.
+ * - `"proration-charge-immediately"` — prorate and charge the difference now
+ * - `"proration-charge"` — prorate, charge on next invoice
+ * - `"proration-none"` — no proration, change takes effect on next billing cycle
+ */
+export type UpdateBehavior =
+  | "proration-charge-immediately"
+  | "proration-charge"
+  | "proration-none";
+
+/** Get a human-readable description for a plan switch based on the proration behavior. */
+export const getSwitchPlanDescription = (
+  updateBehavior: UpdateBehavior,
+  planTitle?: string,
+): string => {
+  const prefix = planTitle
+    ? `You are about to switch to the ${planTitle} plan.`
+    : "You are about to switch your plan.";
+
+  switch (updateBehavior) {
+    case "proration-charge-immediately":
+      return `${prefix} The price difference will be prorated and charged immediately.`;
+    case "proration-charge":
+      return `${prefix} The price difference will be prorated and applied to your next invoice.`;
+    case "proration-none":
+      return `${prefix} The new price will take effect at your next billing cycle.`;
+  }
+};
+
+/** Arbitrary user context passed through to the billing resolver. */
+export type BillingUserContext = Record<string, unknown>;
+
+/** Input for `resolveBillingSnapshot()`. Provide subscription + catalog data to resolve the billing state. */
+export type BillingResolverInput = {
+  /** Optional plan catalog for plan-aware resolution. */
+  catalog?: PlanCatalog;
+  /** The entity's current (primary) subscription, or `null` if none. */
+  currentSubscription?: SubscriptionSnapshot | null;
+  /** All subscriptions for the entity (including ended). */
+  allSubscriptions?: SubscriptionSnapshot[];
+  /** One-time payment state (from checkout success params). */
+  payment?: PaymentSnapshot | null;
+  /** Arbitrary user context passed through to `metadata.userContext`. */
+  userContext?: BillingUserContext;
+  /** Override for the current timestamp (ISO string). Defaults to `new Date().toISOString()`. */
+  now?: string;
+};

package/src/design-system/README.md

@@ -0,0 +1,40 @@
+# Design System
+
+Foundation-first design system structure.
+
+## Structure
+
+- `typography/config.ts` - base numbers, steps, typefaces, role definitions,
+  semantic alias map.
+- `typography/tokens.ts` - computed typography tokens (desktop/tablet/mobile)
+  and helpers for future export pipelines.
+- `typography/utilities.css` - Tailwind-friendly utility classes (`.display-l`,
+  `.body-m`, etc.) and CSS variables.
+- `colors/config.ts` - semantic palettes, semantic role defaults (light/dark),
+  and state layer defaults.
+- `colors/index.ts` - typed exports for color foundation configuration.
+- `colors/utilities.css` - semantic color variables plus utility classes for
+  base and palette-prefixed intent roles.
+- `base.css` - global defaults (`surface.base` page background +
+  `foreground.default` + Body L text styles).
+- `rounded/config.ts` - semantic border radius roles, component defaults, and
+  component naming helpers.
+- `rounded/utilities.css` - semantic radius utility classes (`radius-s`,
+  `radius-m`, etc.).
+- `index.css` - aggregate stylesheet entry for the design system.
+
+## Notes
+
+- Responsive recalculation is applied only to `Display` and `Heading` roles.
+- Other roles keep desktop values across breakpoints.
+- Typeface and default weight are tokenized per family:
+  `--et-typeface-brand/plain` and `--et-font-weight-brand/plain`.
+- Color utility convention:
+- Canonical: `bg-surface-base`, `text-foreground-default`,
+  `border-border-default`.
+- Intent canonical: `bg-primary-surface-base`,
+  `text-success-foreground-default`.
+- Shortcut utilities (property-inferred): `surface-base`, `foreground-default`,
+  `primary-surface-base`.
+- Values are temporary defaults and are expected to be replaced by Figma-sourced
+  values later.

package/src/design-system/base.css

@@ -0,0 +1,27 @@
+@layer base {
+  html {
+    scroll-behavior: smooth;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    html {
+      scroll-behavior: auto;
+    }
+  }
+
+  body {
+    background-color: var(--et-color-surface-subtle);
+    color: var(--et-color-foreground-default);
+    font-family: var(--et-typeface-plain);
+    font-weight: var(--et-font-weight-plain);
+    font-synthesis: none;
+    font-size: var(--et-type-body-l-size-desktop);
+    line-height: var(--et-type-body-l-line-height-desktop);
+    letter-spacing: var(--et-type-body-l-tracking-desktop);
+
+    @variant dark {
+      background-color: var(--et-color-surface-subtle-dark);
+      color: var(--et-color-foreground-default-dark);
+    }
+  }
+}

package/src/design-system/colors/color-utils.ts

@@ -0,0 +1,110 @@
+export function normalizeHex(input: string): string {
+  const raw = input.trim().replace(/^#/, "").toUpperCase();
+  if (/^[0-9A-F]{6}$/.test(raw)) return `#${raw}`;
+  if (/^[0-9A-F]{3}$/.test(raw))
+    return `#${raw
+      .split("")
+      .map((c) => c + c)
+      .join("")}`;
+  return "#000000";
+}
+
+function srgbToLinear(c: number): number {
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+function linearToSrgb(c: number): number {
+  return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+}
+
+function clamp01(n: number): number {
+  return Math.min(1, Math.max(0, n));
+}
+
+function clampChannel(n: number): number {
+  return Math.round(clamp01(n) * 255);
+}
+
+function toHex(n: number): string {
+  return n.toString(16).padStart(2, "0").toUpperCase();
+}
+
+export function hexToOklch(hexInput: string): string {
+  const hex = normalizeHex(hexInput);
+  const r = parseInt(hex.slice(1, 3), 16) / 255;
+  const g = parseInt(hex.slice(3, 5), 16) / 255;
+  const b = parseInt(hex.slice(5, 7), 16) / 255;
+
+  const lr = srgbToLinear(r);
+  const lg = srgbToLinear(g);
+  const lb = srgbToLinear(b);
+
+  const l = 0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb;
+  const m = 0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb;
+  const s = 0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb;
+
+  const l_ = Math.cbrt(l);
+  const m_ = Math.cbrt(m);
+  const s_ = Math.cbrt(s);
+
+  const L = 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_;
+  const a = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
+  const b2 = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
+
+  const C = Math.sqrt(a * a + b2 * b2);
+  let h = (Math.atan2(b2, a) * 180) / Math.PI;
+  if (h < 0) h += 360;
+
+  return `oklch(${L.toFixed(4)} ${C.toFixed(4)} ${h.toFixed(2)})`;
+}
+
+export function parseOklch(
+  input: string,
+): { l: number; c: number; h: number } | null {
+  const m = input
+    .trim()
+    .match(
+      /^oklch\(\s*([0-9]*\.?[0-9]+)\s+([0-9]*\.?[0-9]+)\s+([0-9]*\.?[0-9]+)(?:deg)?\s*\)$/i,
+    );
+  if (!m) return null;
+  const l = Number(m[1]);
+  const c = Number(m[2]);
+  const h = Number(m[3]);
+  if (!Number.isFinite(l) || !Number.isFinite(c) || !Number.isFinite(h))
+    return null;
+  return { l, c, h };
+}
+
+export function normalizeOklch(input: string): string {
+  const parsed = parseOklch(input);
+  if (!parsed) return input;
+  const h = ((parsed.h % 360) + 360) % 360;
+  return `oklch(${parsed.l.toFixed(4)} ${parsed.c.toFixed(4)} ${h.toFixed(2)})`;
+}
+
+export function oklchToHex(input: string): string {
+  const parsed = parseOklch(input);
+  if (!parsed) return "#000000";
+
+  const hRad = (parsed.h * Math.PI) / 180;
+  const a = parsed.c * Math.cos(hRad);
+  const b = parsed.c * Math.sin(hRad);
+
+  const l_ = parsed.l + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = parsed.l - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = parsed.l - 0.0894841775 * a - 1.291485548 * b;
+
+  const l = l_ * l_ * l_;
+  const m = m_ * m_ * m_;
+  const s = s_ * s_ * s_;
+
+  const lr = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+  const lg = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+  const lb = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
+
+  const r = clampChannel(linearToSrgb(lr));
+  const g = clampChannel(linearToSrgb(lg));
+  const bHex = clampChannel(linearToSrgb(lb));
+
+  return `#${toHex(r)}${toHex(g)}${toHex(bHex)}`;
+}