@mmailaender/convex-creem 0.1.0

package/src/react/widgets/index.ts

@@ -0,0 +1,36 @@
+import { SubscriptionItem } from "./SubscriptionItem.js";
+import { SubscriptionRoot } from "./SubscriptionRoot.js";
+import { ProductItem } from "./ProductItem.js";
+import { ProductRoot } from "./ProductRoot.js";
+
+export { BillingPortal } from "./BillingPortal.js";
+
+export const Subscription: typeof SubscriptionItem & {
+  Root: typeof SubscriptionRoot;
+  Item: typeof SubscriptionItem;
+  /** @deprecated Use `Subscription.Root` instead. */
+  Group: typeof SubscriptionRoot;
+} = Object.assign(SubscriptionItem, {
+  Root: SubscriptionRoot,
+  Item: SubscriptionItem,
+  Group: SubscriptionRoot,
+});
+
+export const Product: typeof ProductItem & {
+  Root: typeof ProductRoot;
+  Item: typeof ProductItem;
+  /** @deprecated Use `Product.Root` instead. */
+  Group: typeof ProductRoot;
+} = Object.assign(ProductItem, {
+  Root: ProductRoot,
+  Item: ProductItem,
+  Group: ProductRoot,
+});
+
+export type {
+  ConnectedBillingApi,
+  ConnectedBillingModel,
+  ProductType,
+  SubscriptionPlanType,
+  Transition,
+} from "./types.js";

package/src/react/widgets/productGroupContext.ts

@@ -0,0 +1,10 @@
+import { createContext } from "react";
+import type { ProductItemRegistration } from "./types.js";
+
+export type ProductGroupContextValue = {
+  registerItem: (item: ProductItemRegistration) => () => void;
+};
+
+export const ProductGroupContext = createContext<
+  ProductGroupContextValue | undefined
+>(undefined);

package/src/react/widgets/subscriptionContext.ts

@@ -0,0 +1,10 @@
+import { createContext } from "react";
+import type { SubscriptionPlanRegistration } from "./types.js";
+
+export type SubscriptionContextValue = {
+  registerPlan: (plan: SubscriptionPlanRegistration) => () => void;
+};
+
+export const SubscriptionContext = createContext<
+  SubscriptionContextValue | undefined
+>(undefined);

package/src/react/widgets/types.ts

@@ -0,0 +1,179 @@
+import type { FunctionReference } from "convex/server";
+import type { BillingSnapshot, RecurringCycle } from "../../core/types.js";
+
+export type { CheckoutIntent } from "../../core/types.js";
+
+/**
+ * UI-side permission flags for billing widgets.
+ * Controls which buttons are enabled/visible. This is **cosmetic gating only** —
+ * enforce real permissions server-side in your Convex functions.
+ *
+ * When a permission is `false`, the corresponding button renders as disabled.
+ * When omitted or `undefined`, all actions default to enabled.
+ */
+export type BillingPermissions = {
+  /** Allow creating new checkouts (subscribe / buy buttons). */
+  canCheckout?: boolean;
+  /** Allow switching plans or billing intervals. */
+  canChangeSubscription?: boolean;
+  /** Allow cancelling the active subscription. */
+  canCancelSubscription?: boolean;
+  /** Allow resuming a paused or scheduled-cancel subscription. */
+  canResumeSubscription?: boolean;
+  /** Allow changing the seat count on seat-based plans. */
+  canUpdateSeats?: boolean;
+  /** Allow opening the Creem customer billing portal. */
+  canAccessPortal?: boolean;
+};
+
+/**
+ * Backend function references for connected billing widgets.
+ * Created once in your layout/page and passed to `<Subscription.Root>`, `<Product.Root>`, and `<BillingPortal>`.
+ *
+ * All references point to Convex functions generated by `creem.api({ resolve })`
+ * or your own custom wrappers.
+ *
+ * @example
+ * ```ts
+ * const billingApi: ConnectedBillingApi = {
+ *   uiModel: api.billing.uiModel,
+ *   checkouts: { create: api.billing.checkoutsCreate },
+ *   subscriptions: {
+ *     update: api.billing.subscriptionsUpdate,
+ *     cancel: api.billing.subscriptionsCancel,
+ *     resume: api.billing.subscriptionsResume,
+ *   },
+ *   customers: { portalUrl: api.billing.customersPortalUrl },
+ * };
+ * ```
+ */
+export type ConnectedBillingApi = {
+  /** Query that returns the `ConnectedBillingModel` — called by all widgets to load billing state. */
+  uiModel: FunctionReference<"query">;
+  /** Checkout actions. */
+  checkouts: {
+    /** Create a checkout session and return `{ url }`. */
+    create: FunctionReference<"action">;
+  };
+  /** Subscription mutation references. All optional — omit to hide the corresponding UI controls. */
+  subscriptions?: {
+    /** Plan switch or seat update mutation. */
+    update?: FunctionReference<"mutation">;
+    /** Cancel subscription mutation. */
+    cancel?: FunctionReference<"mutation">;
+    /** Resume paused/scheduled-cancel subscription mutation. */
+    resume?: FunctionReference<"mutation">;
+  };
+  /** Customer actions. */
+  customers?: {
+    /** Action that returns `{ url }` for the Creem billing portal. */
+    portalUrl?: FunctionReference<"action">;
+  };
+};
+
+/** Product data as returned by the billing model query. Mirrors the Convex DB product schema. */
+export type ConnectedProduct = {
+  id: string;
+  name?: string;
+  description?: string;
+  price?: number;
+  currency?: string;
+  billingType?: string;
+  billingPeriod?: string;
+  status?: string;
+  taxMode?: string;
+  taxCategory?: string;
+  imageUrl?: string;
+  features?: Array<{ id: string; description: string }>;
+};
+
+/**
+ * Complete billing state returned by the `uiModel` query.
+ * Consumed internally by all connected widgets — you typically don't need to access this directly.
+ */
+export type ConnectedBillingModel = {
+  /** Authenticated user info, or `null` when unauthenticated (public pricing page). */
+  user: {
+    _id: string;
+    email: string;
+    isFree?: boolean;
+    isTrialing?: boolean;
+    trialEnd?: string | null;
+  } | null;
+  /** Resolved billing state (plan, status, available actions). `null` when unauthenticated. */
+  billingSnapshot: BillingSnapshot | null;
+  /** All synced products from the Creem dashboard. */
+  allProducts: ConnectedProduct[];
+  /** Product IDs the entity has purchased (one-time orders). */
+  ownedProductIds: string[];
+  /** Product ID of the current subscription, or `null`. */
+  subscriptionProductId: string | null;
+  /** All active subscriptions with full details. */
+  activeSubscriptions?: Array<{
+    id: string;
+    productId: string;
+    status: string;
+    cancelAtPeriodEnd: boolean;
+    currentPeriodEnd: string | null;
+    currentPeriodStart: string;
+    seats: number | null;
+    recurringInterval: string | null;
+    trialEnd?: string | null;
+  }>;
+  /** Whether this entity has a Creem customer record (needed for billing portal). */
+  hasCreemCustomer?: boolean;
+  /** Reserved for future billing policy data. */
+  policy?: unknown;
+};
+
+/**
+ * Plan type for `<Subscription.Item>`.
+ * - `"free"` — free tier, no checkout
+ * - `"single"` — standard paid plan (flat pricing)
+ * - `"seat-based"` — per-seat pricing with optional seat picker
+ * - `"enterprise"` — "Contact sales" CTA, no checkout
+ */
+export type SubscriptionPlanType =
+  | "free"
+  | "single"
+  | "seat-based"
+  | "enterprise";
+
+export type SubscriptionPlanRegistration = {
+  planId: string;
+  type: SubscriptionPlanType;
+  title?: string;
+  description?: string;
+  contactUrl?: string;
+  recommended?: boolean;
+  productIds?: Partial<Record<RecurringCycle, string>>;
+};
+
+/**
+ * Product type for `<Product.Item>`.
+ * - `"one-time"` — purchased once, shows "Owned" badge after purchase
+ * - `"recurring"` — can be purchased multiple times (consumable), no "Owned" badge
+ */
+export type ProductType = "one-time" | "recurring";
+
+/**
+ * Upgrade path rule for `<Product.Root transition={[...]}>`.
+ * - `"direct"` — checkout uses the target product directly
+ * - `"via_product"` — checkout uses a dedicated upgrade product (delta pricing)
+ */
+export type Transition =
+  | { from: string; to: string; kind: "direct" }
+  | {
+      from: string;
+      to: string;
+      kind: "via_product";
+      /** Creem product ID for the upgrade (e.g. a delta-priced "Basic → Premium" product). */
+      viaProductId: string;
+    };
+
+export type ProductItemRegistration = {
+  productId: string;
+  type: ProductType;
+  title?: string;
+  description?: string;
+};

package/src/svelte/index.ts

@@ -0,0 +1,43 @@
+export {
+  parseCheckoutSuccessParams,
+  hasCheckoutSuccessParams,
+} from "../core/payments.js";
+export { pendingCheckout } from "../core/pendingCheckout.js";
+export { default as BillingToggle } from "./primitives/BillingToggle.svelte";
+export { default as SegmentGroup } from "./primitives/SegmentGroup.svelte";
+export { default as SegmentControl } from "./primitives/SegmentControl.svelte";
+export { default as NumberInput } from "./primitives/NumberInput.svelte";
+export { default as CheckoutButton } from "./primitives/CheckoutButton.svelte";
+export { default as CustomerPortalButton } from "./primitives/CustomerPortalButton.svelte";
+export { default as PricingCard } from "./primitives/PricingCard.svelte";
+export { default as PricingSection } from "./primitives/PricingSection.svelte";
+export { default as BillingGate } from "./primitives/BillingGate.svelte";
+export { default as ScheduledChangeBanner } from "./primitives/ScheduledChangeBanner.svelte";
+export { default as PaymentWarningBanner } from "./primitives/PaymentWarningBanner.svelte";
+export { default as TrialLimitBanner } from "./primitives/TrialLimitBanner.svelte";
+export { default as OneTimeCheckoutButton } from "./primitives/OneTimeCheckoutButton.svelte";
+export { default as OneTimePaymentStatusBadge } from "./primitives/OneTimePaymentStatusBadge.svelte";
+export { default as CheckoutSuccessSummary } from "./primitives/CheckoutSuccessSummary.svelte";
+export { Subscription, Product, BillingPortal } from "./widgets/index.js";
+export type {
+  BillingSnapshot,
+  CheckoutSuccessParams,
+  OneTimePaymentStatus,
+  RecurringCycle,
+} from "../core/types.js";
+export {
+  hasBillingAction,
+  isEnterpriseBilling,
+  isOneTimeBilling,
+  isTerminalPaymentStatus,
+  shouldShowBillingCycleToggle,
+} from "../core/selectors.js";
+export type {
+  BillingPermissions,
+  CheckoutIntent,
+  ConnectedBillingApi,
+  ConnectedBillingModel,
+  ProductType,
+  SubscriptionPlanType,
+  Transition,
+} from "./widgets/types.js";

package/src/svelte/primitives/BillingGate.svelte

@@ -0,0 +1,28 @@
+<script lang="ts">
+  /* global $props, $derived */
+  import type { Snippet } from "svelte";
+  import type { AvailableAction, BillingSnapshot } from "../../core/types.js";
+  import { hasBillingActionLocal } from "./shared.js";
+
+  interface Props {
+    snapshot?: BillingSnapshot | null;
+    requiredActions: AvailableAction | AvailableAction[];
+    children?: Snippet;
+    fallback?: Snippet;
+  }
+
+  let { snapshot, requiredActions, children, fallback }: Props = $props();
+
+  const actions = $derived(
+    Array.isArray(requiredActions) ? requiredActions : [requiredActions],
+  );
+  const canRender = $derived(
+    snapshot != null && actions.every((action) => hasBillingActionLocal(snapshot, action)),
+  );
+</script>
+
+{#if canRender}
+  {@render children?.()}
+{:else}
+  {@render fallback?.()}
+{/if}

package/src/svelte/primitives/BillingToggle.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+  /* global $props */
+  import type { RecurringCycle } from "../../core/types.js";
+  import { formatRecurringCycle } from "./shared.js";
+  import SegmentGroup from "./SegmentGroup.svelte";
+
+  interface Props {
+    cycles?: RecurringCycle[];
+    value?: RecurringCycle;
+    onValueChange?: (cycle: RecurringCycle) => void;
+    className?: string;
+  }
+
+  let { cycles = [], value, onValueChange, className = "" }: Props = $props();
+</script>
+
+{#if cycles.length > 1}
+  <SegmentGroup
+    items={cycles.map((cycle) => ({
+      value: cycle,
+      label: formatRecurringCycle(cycle),
+    }))}
+    value={value}
+    onValueChange={(segment) => onValueChange?.(segment as RecurringCycle)}
+    className={className}
+  />
+{/if}

package/src/svelte/primitives/CheckoutButton.svelte

@@ -0,0 +1,60 @@
+<script lang="ts">
+  /* global $props, $state */
+  import type { Snippet } from "svelte";
+
+  interface Props {
+    productId: string;
+    href?: string;
+    disabled?: boolean;
+    className?: string;
+    onCheckout?: (payload: { productId: string }) => Promise<void> | void;
+    children?: Snippet;
+  }
+
+  let {
+    productId,
+    href = undefined,
+    disabled = false,
+    className = "",
+    onCheckout,
+    children,
+  }: Props = $props();
+
+  let isLoading = $state(false);
+
+  const handleClick = async () => {
+    if (disabled || isLoading || !onCheckout) return;
+    isLoading = true;
+    try {
+      await onCheckout({ productId });
+    } finally {
+      isLoading = false;
+    }
+  };
+</script>
+
+{#if onCheckout}
+  <button
+    type="button"
+    class={`button-filled disabled:cursor-not-allowed disabled:opacity-60 ${className}`}
+    {disabled}
+    onclick={handleClick}
+  >
+    {#if children}
+      {@render children()}
+    {:else}
+      {isLoading ? "Loading..." : "Checkout"}
+    {/if}
+  </button>
+{:else}
+  <a
+    href={href}
+    class={`button-filled ${className}`}
+  >
+    {#if children}
+      {@render children()}
+    {:else}
+      Checkout
+    {/if}
+  </a>
+{/if}

package/src/svelte/primitives/CheckoutSuccessSummary.svelte

@@ -0,0 +1,34 @@
+<script lang="ts">
+  /* global $props, $derived */
+  import {
+    hasCheckoutSuccessParams,
+    parseCheckoutSuccessParams,
+  } from "../../core/payments.js";
+  import type { CheckoutSuccessParams } from "../../core/types.js";
+
+  interface Props {
+    params?: CheckoutSuccessParams;
+    search?: string;
+    class?: string;
+  }
+
+  let { params = undefined, search = "", class: className = "" }: Props = $props();
+
+  const parsed = $derived(params ?? parseCheckoutSuccessParams(search));
+  const show = $derived(hasCheckoutSuccessParams(parsed));
+</script>
+
+{#if show}
+  <div
+    class={`rounded-lg border border-emerald-300 bg-emerald-50 px-4 py-3 text-sm text-emerald-900 dark:border-emerald-800 dark:bg-emerald-950/40 dark:text-emerald-200 ${className}`}
+  >
+    <p class="font-medium">Checkout completed successfully.</p>
+    <ul class="mt-2 space-y-1">
+      {#if parsed.checkoutId}<li>Checkout: {parsed.checkoutId}</li>{/if}
+      {#if parsed.orderId}<li>Order: {parsed.orderId}</li>{/if}
+      {#if parsed.customerId}<li>Customer: {parsed.customerId}</li>{/if}
+      {#if parsed.productId}<li>Product: {parsed.productId}</li>{/if}
+      {#if parsed.requestId}<li>Request: {parsed.requestId}</li>{/if}
+    </ul>
+  </div>
+{/if}

package/src/svelte/primitives/CustomerPortalButton.svelte

@@ -0,0 +1,60 @@
+<script lang="ts">
+  /* global $props, $state */
+  import type { Snippet } from "svelte";
+
+  interface Props {
+    href?: string;
+    disabled?: boolean;
+    className?: string;
+    onOpenPortal?: () => Promise<void> | void;
+    children?: Snippet;
+  }
+
+  let {
+    href = undefined,
+    disabled = false,
+    className = "",
+    onOpenPortal,
+    children,
+  }: Props = $props();
+
+  let isLoading = $state(false);
+
+  const handleClick = async () => {
+    if (disabled || isLoading || !onOpenPortal) return;
+    isLoading = true;
+    try {
+      await onOpenPortal();
+    } finally {
+      isLoading = false;
+    }
+  };
+</script>
+
+{#if onOpenPortal}
+  <button
+    type="button"
+    class={`${className || "button-outline"} disabled:cursor-not-allowed disabled:opacity-60 cursor-pointer`}
+    {disabled}
+    onclick={handleClick}
+  >
+    {#if children}
+      {@render children()}
+    {:else}
+      {isLoading ? "Loading..." : "Manage billing"}
+    {/if}
+  </button>
+{:else}
+  <a
+    href={href}
+    target="_blank"
+    rel="noopener noreferrer"
+    class={`${className || "button-outline"}`}
+  >
+    {#if children}
+      {@render children()}
+    {:else}
+      Manage billing
+    {/if}
+  </a>
+{/if}

package/src/svelte/primitives/NumberInput.svelte

@@ -0,0 +1,71 @@
+<script lang="ts">
+  interface Props {
+    value?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    compact?: boolean;
+    disabled?: boolean;
+    className?: string;
+    onValueChange?: (value: number) => void | Promise<void>;
+  }
+
+  let {
+    value = 1,
+    min = Number.NEGATIVE_INFINITY,
+    max = Number.POSITIVE_INFINITY,
+    step = 1,
+    compact = false,
+    disabled = false,
+    className = "",
+    onValueChange,
+  }: Props = $props();
+
+  const clamp = (candidate: number) => Math.min(max, Math.max(min, candidate));
+
+  const setValue = (candidate: number) => {
+    const next = clamp(candidate);
+    onValueChange?.(next);
+  };
+
+  const decrement = () => setValue((value ?? 0) - step);
+  const increment = () => setValue((value ?? 0) + step);
+</script>
+
+<div class={`number-input ${className}`}>
+  <button
+    type="button"
+    aria-label="Decrease value"
+    {disabled}
+    class="icon-button-sm"
+    onclick={decrement}
+  >
+    <svg aria-hidden="true" viewBox="0 0 256 256" fill="currentColor" class="h-4 w-4 text-foreground-on-tonal">
+      <path d="M216,128a12,12,0,0,1-12,12H52a12,12,0,0,1,0-24H204A12,12,0,0,1,216,128Z" />
+    </svg>
+  </button>
+
+  <input
+    type="number"
+    class={`input-ghost ${compact ? "number-input-value-compact" : "number-input-value"} max-w-12 input-no-spinner`}
+    value={value}
+    {disabled}
+    oninput={(event) => {
+      const parsed = Number((event.currentTarget as HTMLInputElement).value);
+      if (!Number.isFinite(parsed)) return;
+      setValue(parsed);
+    }}
+  />
+
+  <button
+    type="button"
+    aria-label="Increase value"
+    {disabled}
+    class="icon-button-sm"
+    onclick={increment}
+  >
+    <svg aria-hidden="true" viewBox="0 0 256 256" fill="currentColor" class="h-4 w-4 text-foreground-on-tonal">
+      <path d="M216,128a12,12,0,0,1-12,12H140v64a12,12,0,0,1-24,0V140H52a12,12,0,0,1,0-24h64V52a12,12,0,0,1,24,0v64h64A12,12,0,0,1,216,128Z" />
+    </svg>
+  </button>
+</div>

package/src/svelte/primitives/OneTimeCheckoutButton.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+  /* global $props */
+  import type { Snippet } from "svelte";
+  import CheckoutButton from "./CheckoutButton.svelte";
+
+  interface Props {
+    productId: string;
+    href?: string;
+    disabled?: boolean;
+    className?: string;
+    onCheckout?: (payload: { productId: string }) => Promise<void> | void;
+    children?: Snippet;
+  }
+
+  let {
+    productId,
+    href = undefined,
+    disabled = false,
+    className = "",
+    onCheckout,
+    children,
+  }: Props = $props();
+</script>
+
+<CheckoutButton
+  {productId}
+  {href}
+  {disabled}
+  {className}
+  {onCheckout}
+>
+  {#if children}
+    {@render children()}
+  {:else}
+    Buy now
+  {/if}
+</CheckoutButton>

package/src/svelte/primitives/OneTimePaymentStatusBadge.svelte

@@ -0,0 +1,20 @@
+<script lang="ts">
+  /* global $props */
+  import type { OneTimePaymentStatus } from "../../core/types.js";
+
+  interface Props {
+    status: OneTimePaymentStatus;
+    className?: string;
+  }
+
+  let { status, className = "" }: Props = $props();
+
+  const labels: Record<OneTimePaymentStatus, string> = {
+    pending: "Pending",
+    paid: "Paid",
+    refunded: "Refunded",
+    partially_refunded: "Partially refunded",
+  };
+</script>
+
+<span class={className}>{labels[status]}</span>

package/src/svelte/primitives/PaymentWarningBanner.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+  /* global $props, $derived */
+  import type { BillingSnapshot, PaymentSnapshot } from "../../core/types.js";
+
+  interface Props {
+    snapshot?: BillingSnapshot | null;
+    payment?: PaymentSnapshot | null;
+    className?: string;
+  }
+
+  let { snapshot = null, payment = null, className = "" }: Props = $props();
+
+  const activePayment = $derived(payment ?? snapshot?.payment ?? null);
+  const show = $derived(activePayment != null && activePayment.status !== "paid");
+  const message = $derived(
+    activePayment?.status === "pending"
+      ? "Your payment is pending confirmation. Wait for webhook confirmation before granting permanent access."
+      : activePayment?.status === "partially_refunded"
+        ? "This payment was partially refunded. Review entitlements that depend on purchase amount."
+        : "This payment was refunded. Access should generally be revoked or downgraded.",
+  );
+</script>
+
+{#if show}
+  <div
+    class={`rounded-lg border border-rose-300 bg-rose-50 px-4 py-3 text-sm text-rose-900 dark:border-rose-800 dark:bg-rose-950/40 dark:text-rose-200 ${className}`}
+  >
+    {message}
+  </div>
+{/if}