@mmailaender/convex-creem 0.1.0

package/dist/client/index.d.ts

@@ -0,0 +1,1041 @@
+import "./polyfill.js";
+import { Creem as CreemSDK } from "creem";
+import { type CreemWebhookEvent } from "./parsers.js";
+import { type FunctionReference, type HttpRouter } from "convex/server";
+import { type Infer } from "convex/values";
+import { type RunMutationCtx, type RunSchedulerMutationCtx, type RunQueryCtx, type RunActionCtx } from "../component/util.js";
+import type { ComponentApi } from "../component/_generated/component.js";
+import type { BillingSnapshot, PaymentSnapshot } from "../core/types.js";
+export * from "../core/index.js";
+export type { RunSchedulerMutationCtx } from "../component/util.js";
+export { getEntityId, lowerCaseHeaders, toHex, constantTimeEqual, normalizeSignature, } from "./helpers.js";
+export { type CreemWebhookEvent, getEventType, getEventData, getCustomerId, getConvexEntityId, parseSubscription, parseCheckout, parseProduct, manualParseSubscription, } from "./parsers.js";
+/** Convex validator for the `subscriptions` table. Use with `v.object(subscriptionValidator.fields)` in custom functions. */
+export declare const subscriptionValidator: import("convex/values").VObject<{
+    mode?: string | undefined;
+    collectionMethod?: string | undefined;
+    priceId?: string | undefined;
+    discountId?: string | null | undefined;
+    canceledAt?: string | null | undefined;
+    endsAt?: string | null | undefined;
+    trialStart?: string | null | undefined;
+    trialEnd?: string | null | undefined;
+    seats?: number | null | undefined;
+    lastTransactionId?: string | null | undefined;
+    nextTransactionDate?: string | null | undefined;
+    id: string;
+    createdAt: string;
+    status: string;
+    metadata: Record<string, any>;
+    currency: string | null;
+    modifiedAt: string | null;
+    recurringInterval: string | null;
+    customerId: string;
+    productId: string;
+    amount: number | null;
+    currentPeriodStart: string;
+    currentPeriodEnd: string | null;
+    cancelAtPeriodEnd: boolean;
+    startedAt: string | null;
+    endedAt: string | null;
+    checkoutId: string | null;
+}, {
+    id: import("convex/values").VString<string, "required">;
+    customerId: import("convex/values").VString<string, "required">;
+    productId: import("convex/values").VString<string, "required">;
+    status: import("convex/values").VString<string, "required">;
+    amount: import("convex/values").VUnion<number | null, [import("convex/values").VFloat64<number, "required">, import("convex/values").VNull<null, "required">], "required", never>;
+    currency: import("convex/values").VUnion<string | null, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "required", never>;
+    recurringInterval: import("convex/values").VUnion<string | null, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "required", never>;
+    currentPeriodStart: import("convex/values").VString<string, "required">;
+    currentPeriodEnd: import("convex/values").VUnion<string | null, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "required", never>;
+    cancelAtPeriodEnd: import("convex/values").VBoolean<boolean, "required">;
+    startedAt: import("convex/values").VUnion<string | null, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "required", never>;
+    endedAt: import("convex/values").VUnion<string | null, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "required", never>;
+    priceId: import("convex/values").VString<string | undefined, "optional">;
+    checkoutId: import("convex/values").VUnion<string | null, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "required", never>;
+    metadata: import("convex/values").VRecord<Record<string, any>, import("convex/values").VString<string, "required">, import("convex/values").VAny<any, "required", string>, "required", string>;
+    collectionMethod: import("convex/values").VString<string | undefined, "optional">;
+    discountId: import("convex/values").VUnion<string | null | undefined, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "optional", never>;
+    canceledAt: import("convex/values").VUnion<string | null | undefined, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "optional", never>;
+    endsAt: import("convex/values").VUnion<string | null | undefined, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "optional", never>;
+    trialStart: import("convex/values").VUnion<string | null | undefined, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "optional", never>;
+    trialEnd: import("convex/values").VUnion<string | null | undefined, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "optional", never>;
+    seats: import("convex/values").VUnion<number | null | undefined, [import("convex/values").VFloat64<number, "required">, import("convex/values").VNull<null, "required">], "optional", never>;
+    lastTransactionId: import("convex/values").VUnion<string | null | undefined, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "optional", never>;
+    nextTransactionDate: import("convex/values").VUnion<string | null | undefined, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "optional", never>;
+    mode: import("convex/values").VString<string | undefined, "optional">;
+    createdAt: import("convex/values").VString<string, "required">;
+    modifiedAt: import("convex/values").VUnion<string | null, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "required", never>;
+}, "required", "id" | "mode" | "createdAt" | "collectionMethod" | "status" | "metadata" | `metadata.${string}` | "currency" | "modifiedAt" | "recurringInterval" | "customerId" | "productId" | "amount" | "currentPeriodStart" | "currentPeriodEnd" | "cancelAtPeriodEnd" | "startedAt" | "endedAt" | "priceId" | "checkoutId" | "discountId" | "canceledAt" | "endsAt" | "trialStart" | "trialEnd" | "seats" | "lastTransactionId" | "nextTransactionDate">;
+/** TypeScript type for a subscription document (inferred from the Convex schema). */
+export type Subscription = Infer<typeof subscriptionValidator>;
+/**
+ * Convex arg validator for checkout creation.
+ * Matches the args sent by `<Subscription.Root>` and `<Product.Root>` widgets.
+ * Use in your own `action()` definitions for custom RBAC wrappers.
+ */
+export declare const checkoutCreateArgs: {
+    productId: import("convex/values").VString<string, "required">;
+    successUrl: import("convex/values").VString<string | undefined, "optional">;
+    fallbackSuccessUrl: import("convex/values").VString<string | undefined, "optional">;
+    units: import("convex/values").VFloat64<number | undefined, "optional">;
+    metadata: import("convex/values").VRecord<Record<string, string> | undefined, import("convex/values").VString<string, "required">, import("convex/values").VString<string, "required">, "optional", string>;
+    discountCode: import("convex/values").VString<string | undefined, "optional">;
+    theme: import("convex/values").VUnion<"light" | "dark" | undefined, [import("convex/values").VLiteral<"light", "required">, import("convex/values").VLiteral<"dark", "required">], "optional", never>;
+};
+/**
+ * Convex arg validator for subscription updates (plan switch or seat change).
+ * Matches the args sent by `<Subscription.Root>` widgets.
+ */
+export declare const subscriptionUpdateArgs: {
+    subscriptionId: import("convex/values").VString<string | undefined, "optional">;
+    productId: import("convex/values").VString<string | undefined, "optional">;
+    units: import("convex/values").VFloat64<number | undefined, "optional">;
+    updateBehavior: import("convex/values").VUnion<"proration-charge-immediately" | "proration-charge" | "proration-none" | undefined, [import("convex/values").VLiteral<"proration-charge-immediately", "required">, import("convex/values").VLiteral<"proration-charge", "required">, import("convex/values").VLiteral<"proration-none", "required">], "optional", never>;
+};
+/**
+ * Convex arg validator for subscription cancellation.
+ * Matches the args sent by `<Subscription.Root>` cancel button.
+ */
+export declare const subscriptionCancelArgs: {
+    subscriptionId: import("convex/values").VString<string | undefined, "optional">;
+    revokeImmediately: import("convex/values").VBoolean<boolean | undefined, "optional">;
+};
+/**
+ * Convex arg validator for subscription resume.
+ * Matches the args sent by `<Subscription.Root>` resume button.
+ */
+export declare const subscriptionResumeArgs: {
+    subscriptionId: import("convex/values").VString<string | undefined, "optional">;
+};
+/**
+ * Convex arg validator for subscription pause.
+ * Matches the args sent by `<Subscription.Root>` pause button.
+ */
+export declare const subscriptionPauseArgs: {
+    subscriptionId: import("convex/values").VString<string | undefined, "optional">;
+};
+/** Function reference type for internal mutations that receive a subscription document. */
+export type SubscriptionHandler = FunctionReference<"mutation", "internal", {
+    subscription: Subscription;
+}>;
+/**
+ * Map of webhook event type → handler function.
+ * Handlers run **after** the component's built-in processing (customer/subscription/order upserts).
+ * The `ctx` is a Convex mutation context — you can read/write to your own tables.
+ *
+ * @example
+ * ```ts
+ * creem.registerRoutes(http, {
+ *   events: {
+ *     "checkout.completed": async (ctx, event) => {
+ *       // Grant entitlements, send emails, log analytics
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export type WebhookEventHandlers = Record<string, (ctx: RunMutationCtx, event: CreemWebhookEvent) => Promise<void> | void>;
+/**
+ * Callback that resolves the authenticated user for `creem.api({ resolve })`.
+ * Called on every generated Convex function to determine the billing entity.
+ *
+ * - `userId` — your app's user ID (stored in checkout metadata as `convexUserId`)
+ * - `email` — user's email (passed to Creem for customer creation)
+ * - `entityId` — billing entity ID. For personal billing, same as `userId`.
+ *   For org billing, return the org ID so all billing scopes to the organization.
+ *
+ * @example
+ * ```ts
+ * const resolve: ApiResolver = async (ctx) => {
+ *   const user = await ctx.runQuery(api.users.currentUser);
+ *   return { userId: user._id, email: user.email, entityId: user._id };
+ * };
+ * ```
+ */
+export type ApiResolver = (ctx: RunQueryCtx) => Promise<{
+    userId: string;
+    email: string;
+    entityId: string;
+}>;
+/**
+ * Configuration for the Creem Convex component.
+ * All fields are optional — environment variables are used as fallbacks.
+ */
+type CreemConfig = {
+    /**
+     * Default cancel mode for subscriptions.
+     * - `"immediate"` — cancel and revoke access now
+     * - `"scheduled"` — cancel at end of current billing period
+     * - Omit to use Creem's store-level default.
+     */
+    cancelMode?: "immediate" | "scheduled";
+    /** Creem API key. Falls back to `CREEM_API_KEY` env var. */
+    apiKey?: string;
+    /** Creem webhook signing secret. Falls back to `CREEM_WEBHOOK_SECRET` env var. */
+    webhookSecret?: string;
+    /** Creem SDK server index (for non-default endpoints). Falls back to `CREEM_SERVER_IDX` env var. */
+    serverIdx?: number;
+    /** Creem SDK server URL override (for test/staging). Falls back to `CREEM_SERVER_URL` env var. */
+    serverURL?: string;
+};
+/**
+ * Main entry point for the Creem–Convex integration.
+ *
+ * Instantiate once in your `convex/billing.ts` and use its methods
+ * to manage subscriptions, checkouts, products, customers, and orders.
+ *
+ * **Two usage patterns:**
+ * 1. **Quick start** — call `creem.api({ resolve })` to generate ready-to-export Convex functions
+ * 2. **Full control** — use namespace getters (`creem.subscriptions.*`, `creem.checkouts.*`, etc.)
+ *    directly in your own Convex functions for custom auth/RBAC
+ *
+ * @example
+ * ```ts
+ * import { Creem } from "@mmailaender/convex-creem";
+ * import { components } from "./_generated/api";
+ *
+ * export const creem = new Creem(components.creem);
+ * ```
+ */
+export declare class Creem {
+    component: ComponentApi;
+    private config;
+    /** Direct access to the Creem SDK client, pre-configured with your API key. Use for resources without webhook sync (licenses, discounts, transactions). */
+    sdk: CreemSDK;
+    private apiKey;
+    private webhookSecret;
+    private serverIdx?;
+    private serverURL?;
+    constructor(component: ComponentApi, config?: CreemConfig);
+    private getCustomerByEntityId;
+    /** Pull all products from the Creem API into the Convex database. Typically called once via `internalAction` or the CLI. */
+    syncProducts(ctx: RunActionCtx): Promise<void>;
+    private createCheckoutSession;
+    private createCustomerPortalSession;
+    private listProducts;
+    private getCurrentSubscription;
+    /** Return active subscriptions for an entity, excluding ended and expired trials. */
+    private listUserSubscriptions;
+    /** Return paid one-time orders for an entity. */
+    private listUserOrders;
+    /** Return all subscriptions for an entity, including ended and expired trials. */
+    private listAllUserSubscriptions;
+    private getProduct;
+    private toSubscriptionSnapshot;
+    /**
+     * Resolve the current billing state for a billing entity.
+     * Returns plan, status, available actions, subscription metadata, etc.
+     * Used internally by `getBillingModel` and exposed for custom billing UIs.
+     */
+    getBillingSnapshot(ctx: RunQueryCtx, { entityId, payment, }: {
+        entityId: string;
+        payment?: PaymentSnapshot | null;
+    }): Promise<BillingSnapshot>;
+    private verifyWebhook;
+    /** Upsert a customer record if we have both entityId and customerId. */
+    private upsertCustomerFromWebhook;
+    /**
+     * Subscription management namespace.
+     *
+     * All methods take explicit `entityId` — use them directly in your own
+     * Convex functions, or let `creem.api({ resolve })` handle auth for you.
+     *
+     * - `.getCurrent()` — current active subscription with product join (Convex DB)
+     * - `.list()` — active subscriptions, excludes ended + expired trials (Convex DB)
+     * - `.listAll()` — all subscriptions including ended (Convex DB)
+     * - `.update()` — plan switch (`productId`) or seat change (`units`) (Creem API, optimistic)
+     * - `.cancel()` — cancel subscription (Creem API, optimistic)
+     * - `.pause()` — pause an active subscription (Creem API, optimistic)
+     * - `.resume()` — resume a paused or scheduled-cancel subscription (Creem API, optimistic)
+     */
+    get subscriptions(): {
+        getCurrent: (ctx: RunQueryCtx, { entityId }: {
+            entityId: string;
+        }) => Promise<{
+            product: {
+                billingPeriod?: string;
+                billingType: string;
+                createdAt: string;
+                currency: string;
+                defaultSuccessUrl?: string | null;
+                description: string | null;
+                features?: Array<{
+                    description: string;
+                    id: string;
+                }>;
+                id: string;
+                imageUrl?: string;
+                metadata?: Record<string, any>;
+                mode?: string;
+                modifiedAt: string | null;
+                name: string;
+                price: number;
+                productUrl?: string;
+                status: string;
+                taxCategory?: string;
+                taxMode?: string;
+            };
+            amount: number | null;
+            cancelAtPeriodEnd: boolean;
+            canceledAt?: string | null;
+            checkoutId: string | null;
+            collectionMethod?: string;
+            createdAt: string;
+            currency: string | null;
+            currentPeriodEnd: string | null;
+            currentPeriodStart: string;
+            customerId: string;
+            discountId?: string | null;
+            endedAt: string | null;
+            endsAt?: string | null;
+            id: string;
+            lastTransactionId?: string | null;
+            metadata: Record<string, any>;
+            mode?: string;
+            modifiedAt: string | null;
+            nextTransactionDate?: string | null;
+            priceId?: string;
+            productId: string;
+            recurringInterval: string | null;
+            seats?: number | null;
+            startedAt: string | null;
+            status: string;
+            trialEnd?: string | null;
+            trialStart?: string | null;
+        } | null>;
+        list: (ctx: RunQueryCtx, { entityId }: {
+            entityId: string;
+        }) => Promise<{
+            amount: number | null;
+            cancelAtPeriodEnd: boolean;
+            canceledAt?: string | null;
+            checkoutId: string | null;
+            collectionMethod?: string;
+            createdAt: string;
+            currency: string | null;
+            currentPeriodEnd: string | null;
+            currentPeriodStart: string;
+            customerId: string;
+            discountId?: string | null;
+            endedAt: string | null;
+            endsAt?: string | null;
+            id: string;
+            lastTransactionId?: string | null;
+            metadata: Record<string, any>;
+            mode?: string;
+            modifiedAt: string | null;
+            nextTransactionDate?: string | null;
+            priceId?: string;
+            product: {
+                billingPeriod?: string;
+                billingType: string;
+                createdAt: string;
+                currency: string;
+                defaultSuccessUrl?: string | null;
+                description: string | null;
+                features?: Array<{
+                    description: string;
+                    id: string;
+                }>;
+                id: string;
+                imageUrl?: string;
+                metadata?: Record<string, any>;
+                mode?: string;
+                modifiedAt: string | null;
+                name: string;
+                price: number;
+                productUrl?: string;
+                status: string;
+                taxCategory?: string;
+                taxMode?: string;
+            } | null;
+            productId: string;
+            recurringInterval: string | null;
+            seats?: number | null;
+            startedAt: string | null;
+            status: string;
+            trialEnd?: string | null;
+            trialStart?: string | null;
+        }[]>;
+        listAll: (ctx: RunQueryCtx, { entityId }: {
+            entityId: string;
+        }) => Promise<{
+            amount: number | null;
+            cancelAtPeriodEnd: boolean;
+            canceledAt?: string | null;
+            checkoutId: string | null;
+            collectionMethod?: string;
+            createdAt: string;
+            currency: string | null;
+            currentPeriodEnd: string | null;
+            currentPeriodStart: string;
+            customerId: string;
+            discountId?: string | null;
+            endedAt: string | null;
+            endsAt?: string | null;
+            id: string;
+            lastTransactionId?: string | null;
+            metadata: Record<string, any>;
+            mode?: string;
+            modifiedAt: string | null;
+            nextTransactionDate?: string | null;
+            priceId?: string;
+            product: {
+                billingPeriod?: string;
+                billingType: string;
+                createdAt: string;
+                currency: string;
+                defaultSuccessUrl?: string | null;
+                description: string | null;
+                features?: Array<{
+                    description: string;
+                    id: string;
+                }>;
+                id: string;
+                imageUrl?: string;
+                metadata?: Record<string, any>;
+                mode?: string;
+                modifiedAt: string | null;
+                name: string;
+                price: number;
+                productUrl?: string;
+                status: string;
+                taxCategory?: string;
+                taxMode?: string;
+            } | null;
+            productId: string;
+            recurringInterval: string | null;
+            seats?: number | null;
+            startedAt: string | null;
+            status: string;
+            trialEnd?: string | null;
+            trialStart?: string | null;
+        }[]>;
+        update: (ctx: RunSchedulerMutationCtx, args: {
+            entityId: string;
+            subscriptionId?: string;
+            productId?: string;
+            units?: number;
+            updateBehavior?: "proration-charge-immediately" | "proration-charge" | "proration-none";
+        }) => Promise<void>;
+        cancel: (ctx: RunSchedulerMutationCtx, args: {
+            entityId: string;
+            subscriptionId?: string;
+            revokeImmediately?: boolean;
+        }) => Promise<void>;
+        pause: (ctx: RunSchedulerMutationCtx, args: {
+            entityId: string;
+            subscriptionId?: string;
+        }) => Promise<void>;
+        resume: (ctx: RunSchedulerMutationCtx, args: {
+            entityId: string;
+            subscriptionId?: string;
+        }) => Promise<void>;
+    };
+    /**
+     * Checkout namespace.
+     *
+     * - `.create()` — create a checkout URL with 3-tier `successUrl` resolution and optional `theme` (Creem API)
+     */
+    get checkouts(): {
+        create: (ctx: RunActionCtx, args: {
+            entityId: string;
+            userId: string;
+            email: string;
+            productId: string;
+            successUrl?: string;
+            fallbackSuccessUrl?: string;
+            units?: number;
+            metadata?: Record<string, string>;
+            discountCode?: string;
+            theme?: "light" | "dark";
+        }) => Promise<{
+            url: string;
+        }>;
+    };
+    /**
+     * Product namespace. All reads come from the local Convex DB (synced via webhooks).
+     *
+     * - `.list()` — all synced products (public, no `entityId` needed)
+     * - `.get()` — single product by Creem product ID
+     */
+    get products(): {
+        list: (ctx: RunQueryCtx, options?: {
+            includeArchived?: boolean;
+        }) => Promise<{
+            billingPeriod?: string;
+            billingType: string;
+            createdAt: string;
+            currency: string;
+            defaultSuccessUrl?: string | null;
+            description: string | null;
+            features?: Array<{
+                description: string;
+                id: string;
+            }>;
+            id: string;
+            imageUrl?: string;
+            metadata?: Record<string, any>;
+            mode?: string;
+            modifiedAt: string | null;
+            name: string;
+            price: number;
+            productUrl?: string;
+            status: string;
+            taxCategory?: string;
+            taxMode?: string;
+        }[]>;
+        get: (ctx: RunQueryCtx, { productId }: {
+            productId: string;
+        }) => Promise<{
+            billingPeriod?: string;
+            billingType: string;
+            createdAt: string;
+            currency: string;
+            defaultSuccessUrl?: string | null;
+            description: string | null;
+            features?: Array<{
+                description: string;
+                id: string;
+            }>;
+            id: string;
+            imageUrl?: string;
+            metadata?: Record<string, any>;
+            mode?: string;
+            modifiedAt: string | null;
+            name: string;
+            price: number;
+            productUrl?: string;
+            status: string;
+            taxCategory?: string;
+            taxMode?: string;
+        } | null>;
+    };
+    /**
+     * Customer namespace.
+     *
+     * - `.retrieve()` — customer record by billing entity (Convex DB)
+     * - `.portalUrl()` — generate a Creem customer billing portal URL (Creem API)
+     */
+    get customers(): {
+        retrieve: (ctx: RunQueryCtx, { entityId }: {
+            entityId: string;
+        }) => Promise<{
+            country?: string;
+            createdAt?: string;
+            email?: string;
+            entityId: string;
+            id: string;
+            metadata?: Record<string, any>;
+            mode?: string;
+            name?: string | null;
+            updatedAt?: string;
+        } | null>;
+        portalUrl: (ctx: RunActionCtx, { entityId }: {
+            entityId: string;
+        }) => Promise<{
+            url: string;
+        }>;
+    };
+    /**
+     * Order namespace.
+     *
+     * - `.list()` — paid one-time orders for a billing entity (Convex DB)
+     */
+    get orders(): {
+        list: (ctx: RunQueryCtx, { entityId }: {
+            entityId: string;
+        }) => Promise<{
+            affiliate?: string | null;
+            amount: number;
+            amountDue?: number;
+            amountPaid?: number;
+            checkoutId?: string | null;
+            createdAt: string;
+            currency: string;
+            customerId: string;
+            discountAmount?: number;
+            discountId?: string | null;
+            id: string;
+            metadata?: Record<string, any>;
+            mode?: string;
+            productId: string;
+            status: string;
+            subTotal?: number;
+            taxAmount?: number;
+            transactionId?: string | null;
+            type: string;
+            updatedAt: string;
+        }[]>;
+    };
+    /**
+     * Composite billing model for connected widgets.
+     *
+     * Aggregates snapshot + products + subscriptions + orders into a single
+     * object that `<Subscription.Root>` and `<Product.Root>` widgets consume.
+     *
+     * Graceful when `entityId` is `null` — returns public product catalog only
+     * (useful for unauthenticated pricing pages).
+     *
+     * @param ctx - Convex query context
+     * @param options.entityId - Billing entity ID, or `null` for public-only data
+     * @param options.user - User info for the UI (widgets display email, etc.)
+     */
+    getBillingModel(ctx: RunQueryCtx, { entityId, user, }: {
+        entityId: string | null;
+        user?: {
+            _id: string;
+            email: string;
+        } | null;
+    }): Promise<{
+        user: {
+            _id: string;
+            email: string;
+        } | null;
+        billingSnapshot: BillingSnapshot | null;
+        allProducts: {
+            billingPeriod?: string;
+            billingType: string;
+            createdAt: string;
+            currency: string;
+            defaultSuccessUrl?: string | null;
+            description: string | null;
+            features?: Array<{
+                description: string;
+                id: string;
+            }>;
+            id: string;
+            imageUrl?: string;
+            metadata?: Record<string, any>;
+            mode?: string;
+            modifiedAt: string | null;
+            name: string;
+            price: number;
+            productUrl?: string;
+            status: string;
+            taxCategory?: string;
+            taxMode?: string;
+        }[];
+        ownedProductIds: string[];
+        subscriptionProductId: string | null;
+        activeSubscriptions: Array<{
+            id: string;
+            productId: string;
+            status: string;
+            cancelAtPeriodEnd: boolean;
+            currentPeriodEnd: string | null;
+            currentPeriodStart: string;
+            seats: number | null;
+            recurringInterval: string | null;
+            trialEnd: string | null;
+        }>;
+        hasCreemCustomer: boolean;
+    } | {
+        user: {
+            _id: string;
+            email: string;
+        } | null;
+        billingSnapshot: BillingSnapshot;
+        allProducts: {
+            billingPeriod?: string;
+            billingType: string;
+            createdAt: string;
+            currency: string;
+            defaultSuccessUrl?: string | null;
+            description: string | null;
+            features?: Array<{
+                description: string;
+                id: string;
+            }>;
+            id: string;
+            imageUrl?: string;
+            metadata?: Record<string, any>;
+            mode?: string;
+            modifiedAt: string | null;
+            name: string;
+            price: number;
+            productUrl?: string;
+            status: string;
+            taxCategory?: string;
+            taxMode?: string;
+        }[];
+        ownedProductIds: string[];
+        subscriptionProductId: string | null;
+        activeSubscriptions: {
+            id: string;
+            productId: string;
+            status: string;
+            cancelAtPeriodEnd: boolean;
+            currentPeriodEnd: string | null;
+            currentPeriodStart: string;
+            seats: number | null | undefined;
+            recurringInterval: string | null;
+            trialEnd: string | null;
+        }[];
+        hasCreemCustomer: boolean;
+    }>;
+    /**
+     * Generate ready-to-export Convex function definitions.
+     *
+     * Each function calls your `resolve` callback to authenticate the user
+     * and determine the billing entity, then delegates to the corresponding
+     * namespace method. Destructure and re-export in your `convex/billing.ts`.
+     *
+     * For full control, use the namespace getters directly instead
+     * (e.g. `creem.subscriptions.cancel(ctx, { entityId })`).
+     *
+     * @param options.resolve - Auth callback that returns `{ userId, email, entityId }`
+     * @returns Object with `uiModel`, `snapshot`, `checkouts`, `subscriptions`, `products`, `customers`, `orders`
+     *
+     * @example
+     * ```ts
+     * const { uiModel, checkouts, subscriptions } = creem.api({ resolve });
+     * export { uiModel };
+     * export const checkoutsCreate = checkouts.create;
+     * ```
+     */
+    api({ resolve }: {
+        resolve: ApiResolver;
+    }): {
+        uiModel: import("convex/server").RegisteredQuery<"public", {}, Promise<{
+            user: {
+                _id: string;
+                email: string;
+            } | null;
+            billingSnapshot: BillingSnapshot | null;
+            allProducts: {
+                billingPeriod?: string;
+                billingType: string;
+                createdAt: string;
+                currency: string;
+                defaultSuccessUrl?: string | null;
+                description: string | null;
+                features?: Array<{
+                    description: string;
+                    id: string;
+                }>;
+                id: string;
+                imageUrl?: string;
+                metadata?: Record<string, any>;
+                mode?: string;
+                modifiedAt: string | null;
+                name: string;
+                price: number;
+                productUrl?: string;
+                status: string;
+                taxCategory?: string;
+                taxMode?: string;
+            }[];
+            ownedProductIds: string[];
+            subscriptionProductId: string | null;
+            activeSubscriptions: Array<{
+                id: string;
+                productId: string;
+                status: string;
+                cancelAtPeriodEnd: boolean;
+                currentPeriodEnd: string | null;
+                currentPeriodStart: string;
+                seats: number | null;
+                recurringInterval: string | null;
+                trialEnd: string | null;
+            }>;
+            hasCreemCustomer: boolean;
+        } | {
+            user: {
+                _id: string;
+                email: string;
+            } | null;
+            billingSnapshot: BillingSnapshot;
+            allProducts: {
+                billingPeriod?: string;
+                billingType: string;
+                createdAt: string;
+                currency: string;
+                defaultSuccessUrl?: string | null;
+                description: string | null;
+                features?: Array<{
+                    description: string;
+                    id: string;
+                }>;
+                id: string;
+                imageUrl?: string;
+                metadata?: Record<string, any>;
+                mode?: string;
+                modifiedAt: string | null;
+                name: string;
+                price: number;
+                productUrl?: string;
+                status: string;
+                taxCategory?: string;
+                taxMode?: string;
+            }[];
+            ownedProductIds: string[];
+            subscriptionProductId: string | null;
+            activeSubscriptions: {
+                id: string;
+                productId: string;
+                status: string;
+                cancelAtPeriodEnd: boolean;
+                currentPeriodEnd: string | null;
+                currentPeriodStart: string;
+                seats: number | null | undefined;
+                recurringInterval: string | null;
+                trialEnd: string | null;
+            }[];
+            hasCreemCustomer: boolean;
+        }>>;
+        snapshot: import("convex/server").RegisteredQuery<"public", {}, Promise<BillingSnapshot | null>>;
+        checkouts: {
+            create: import("convex/server").RegisteredAction<"public", {
+                units?: number | undefined;
+                metadata?: Record<string, string> | undefined;
+                successUrl?: string | undefined;
+                fallbackSuccessUrl?: string | undefined;
+                discountCode?: string | undefined;
+                theme?: "light" | "dark" | undefined;
+                productId: string;
+            }, Promise<{
+                url: string;
+            }>>;
+        };
+        subscriptions: {
+            update: import("convex/server").RegisteredMutation<"public", {
+                units?: number | undefined;
+                productId?: string | undefined;
+                subscriptionId?: string | undefined;
+                updateBehavior?: "proration-charge-immediately" | "proration-charge" | "proration-none" | undefined;
+            }, Promise<void>>;
+            cancel: import("convex/server").RegisteredMutation<"public", {
+                subscriptionId?: string | undefined;
+                revokeImmediately?: boolean | undefined;
+            }, Promise<void>>;
+            resume: import("convex/server").RegisteredMutation<"public", {
+                subscriptionId?: string | undefined;
+            }, Promise<void>>;
+            pause: import("convex/server").RegisteredMutation<"public", {
+                subscriptionId?: string | undefined;
+            }, Promise<void>>;
+            list: import("convex/server").RegisteredQuery<"public", {}, Promise<{
+                amount: number | null;
+                cancelAtPeriodEnd: boolean;
+                canceledAt?: string | null;
+                checkoutId: string | null;
+                collectionMethod?: string;
+                createdAt: string;
+                currency: string | null;
+                currentPeriodEnd: string | null;
+                currentPeriodStart: string;
+                customerId: string;
+                discountId?: string | null;
+                endedAt: string | null;
+                endsAt?: string | null;
+                id: string;
+                lastTransactionId?: string | null;
+                metadata: Record<string, any>;
+                mode?: string;
+                modifiedAt: string | null;
+                nextTransactionDate?: string | null;
+                priceId?: string;
+                product: {
+                    billingPeriod?: string;
+                    billingType: string;
+                    createdAt: string;
+                    currency: string;
+                    defaultSuccessUrl?: string | null;
+                    description: string | null;
+                    features?: Array<{
+                        description: string;
+                        id: string;
+                    }>;
+                    id: string;
+                    imageUrl?: string;
+                    metadata?: Record<string, any>;
+                    mode?: string;
+                    modifiedAt: string | null;
+                    name: string;
+                    price: number;
+                    productUrl?: string;
+                    status: string;
+                    taxCategory?: string;
+                    taxMode?: string;
+                } | null;
+                productId: string;
+                recurringInterval: string | null;
+                seats?: number | null;
+                startedAt: string | null;
+                status: string;
+                trialEnd?: string | null;
+                trialStart?: string | null;
+            }[]>>;
+            listAll: import("convex/server").RegisteredQuery<"public", {}, Promise<{
+                amount: number | null;
+                cancelAtPeriodEnd: boolean;
+                canceledAt?: string | null;
+                checkoutId: string | null;
+                collectionMethod?: string;
+                createdAt: string;
+                currency: string | null;
+                currentPeriodEnd: string | null;
+                currentPeriodStart: string;
+                customerId: string;
+                discountId?: string | null;
+                endedAt: string | null;
+                endsAt?: string | null;
+                id: string;
+                lastTransactionId?: string | null;
+                metadata: Record<string, any>;
+                mode?: string;
+                modifiedAt: string | null;
+                nextTransactionDate?: string | null;
+                priceId?: string;
+                product: {
+                    billingPeriod?: string;
+                    billingType: string;
+                    createdAt: string;
+                    currency: string;
+                    defaultSuccessUrl?: string | null;
+                    description: string | null;
+                    features?: Array<{
+                        description: string;
+                        id: string;
+                    }>;
+                    id: string;
+                    imageUrl?: string;
+                    metadata?: Record<string, any>;
+                    mode?: string;
+                    modifiedAt: string | null;
+                    name: string;
+                    price: number;
+                    productUrl?: string;
+                    status: string;
+                    taxCategory?: string;
+                    taxMode?: string;
+                } | null;
+                productId: string;
+                recurringInterval: string | null;
+                seats?: number | null;
+                startedAt: string | null;
+                status: string;
+                trialEnd?: string | null;
+                trialStart?: string | null;
+            }[]>>;
+        };
+        products: {
+            list: import("convex/server").RegisteredQuery<"public", {}, Promise<{
+                billingPeriod?: string;
+                billingType: string;
+                createdAt: string;
+                currency: string;
+                defaultSuccessUrl?: string | null;
+                description: string | null;
+                features?: Array<{
+                    description: string;
+                    id: string;
+                }>;
+                id: string;
+                imageUrl?: string;
+                metadata?: Record<string, any>;
+                mode?: string;
+                modifiedAt: string | null;
+                name: string;
+                price: number;
+                productUrl?: string;
+                status: string;
+                taxCategory?: string;
+                taxMode?: string;
+            }[]>>;
+            get: import("convex/server").RegisteredQuery<"public", {
+                productId: string;
+            }, Promise<{
+                billingPeriod?: string;
+                billingType: string;
+                createdAt: string;
+                currency: string;
+                defaultSuccessUrl?: string | null;
+                description: string | null;
+                features?: Array<{
+                    description: string;
+                    id: string;
+                }>;
+                id: string;
+                imageUrl?: string;
+                metadata?: Record<string, any>;
+                mode?: string;
+                modifiedAt: string | null;
+                name: string;
+                price: number;
+                productUrl?: string;
+                status: string;
+                taxCategory?: string;
+                taxMode?: string;
+            } | null>>;
+        };
+        customers: {
+            retrieve: import("convex/server").RegisteredQuery<"public", {}, Promise<{
+                country?: string;
+                createdAt?: string;
+                email?: string;
+                entityId: string;
+                id: string;
+                metadata?: Record<string, any>;
+                mode?: string;
+                name?: string | null;
+                updatedAt?: string;
+            } | null>>;
+            portalUrl: import("convex/server").RegisteredAction<"public", {}, Promise<{
+                url: string;
+            }>>;
+        };
+        orders: {
+            list: import("convex/server").RegisteredQuery<"public", {}, Promise<{
+                affiliate?: string | null;
+                amount: number;
+                amountDue?: number;
+                amountPaid?: number;
+                checkoutId?: string | null;
+                createdAt: string;
+                currency: string;
+                customerId: string;
+                discountAmount?: number;
+                discountId?: string | null;
+                id: string;
+                metadata?: Record<string, any>;
+                mode?: string;
+                productId: string;
+                status: string;
+                subTotal?: number;
+                taxAmount?: number;
+                transactionId?: string | null;
+                type: string;
+                updatedAt: string;
+            }[]>>;
+        };
+    };
+    /**
+     * Register the Creem webhook HTTP route on your Convex `httpRouter`.
+     *
+     * Automatically handles `checkout.completed`, `subscription.*`, and `product.*`
+     * events — upserts customers, subscriptions, orders, and products in the Convex DB.
+     *
+     * @param http - Your Convex HTTP router (from `httpRouter()`)
+     * @param options.path - Webhook endpoint path (default: `"/creem/events"`)
+     * @param options.events - Optional custom handlers that run **after** built-in processing
+     *
+     * @example
+     * ```ts
+     * const http = httpRouter();
+     * creem.registerRoutes(http, {
+     *   events: {
+     *     "checkout.completed": async (ctx, event) => { ... },
+     *   },
+     * });
+     * ```
+     */
+    registerRoutes(http: HttpRouter, { path, events, }?: {
+        path?: string;
+        events?: WebhookEventHandlers;
+    }): void;
+}
+//# sourceMappingURL=index.d.ts.map