@mmailaender/convex-creem 0.1.0

package/src/svelte/widgets/index.ts

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

package/src/svelte/widgets/productGroupContext.ts

@@ -0,0 +1,7 @@
+import type { ProductItemRegistration } from "./types.js";
+
+export type ProductGroupContextValue = {
+  registerItem: (item: ProductItemRegistration) => () => void;
+};
+
+export const PRODUCT_GROUP_CONTEXT_KEY = Symbol("creem.product.group.context");

package/src/svelte/widgets/subscriptionContext.ts

@@ -0,0 +1,7 @@
+import type { SubscriptionPlanRegistration } from "./types.js";
+
+export type SubscriptionContextValue = {
+  registerPlan: (plan: SubscriptionPlanRegistration) => () => void;
+};
+
+export const SUBSCRIPTION_CONTEXT_KEY = Symbol("creem.subscription.context");

package/src/svelte/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/tailwind.css

@@ -0,0 +1,6 @@
+/* IntelliSense-only entrypoint.
+   NOT used in any build — exists solely so the Tailwind CSS IDE plugin
+   can discover @utility classes from the design-system when editing
+   files inside src/svelte/.  */
+@import "tailwindcss";
+@import "./library.css";

package/src/test.ts

@@ -0,0 +1,18 @@
+/// <reference types="vite/client" />
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register the component with the test convex instance.
+ * @param t - The test convex instance, e.g. from calling `convexTest`.
+ * @param name - The name of the component, as registered in convex.config.ts.
+ */
+export function register(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "creem",
+) {
+  t.registerComponent(name, schema, modules);
+}
+export default { register, schema, modules };