@raideno/convex-stripe 0.3.5 → 0.3.7

package/README.md

@@ -46,6 +46,11 @@ Stripe [syncing](./documentation/references/tables.md), subscriptions, [checkout
     - [`stripe.client`](#stripeclient)
     - [`sync` Action](#sync-action)
     - [`store` Mutation](#store-mutation)
+    - [`stripe.helpers`](#stripehelpers)
+    - [`helpers.createCustomer`](#helperscreatecustomer)
+    - [`helpers.products`](#helpersproducts)
+    - [`helpers.subscription`](#helperssubscription)
+    - [`helpers.customer`](#helperscustomer)
   - [Synced Tables](#synced-tables)
   - [Synced Events](#synced-events)
   - [Best Practices](#best-practices)
@@ -797,6 +802,151 @@ This action is typically called manually from the Convex dashboard, or set up to
 
 An internal mutation that persists Stripe objects into your Convex database. This is called automatically from within the webhook handler and is not meant for direct use. It must be exported from the same file as your `internalConvexStripe` call.
 
+### `stripe.helpers`
+
+Returns a set of pre-built, authorization-aware Convex functions that cover the most common Stripe operations. These are ready to export and call from your frontend directly — no boilerplate required.
+
+Each returned function invokes your `authenticateAndAuthorize` callback to resolve the caller's identity before delegating to the underlying Stripe implementation. When a caller omits `entityId`, it means they want to act on themselves — your callback is responsible for deriving their identity from the Convex `context`.
+
+stripe.helpers({
+  authenticateAndAuthorize: async ({ context, operation, entityId }) => {
+    // Return [isAuthorized, resolvedEntityId | null]
+  }
+})
+```
+
+**`authenticateAndAuthorize` parameters (passed as a single object):**
+
+| Parameter   | Type                                                                                                 | Description                                                                                                                                                                                                            |
+| :---------- | :--------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `context`   | `GenericActionCtx<any>` or `GenericQueryCtx<any>`                                                    | The Convex context, **narrowed by `operation`**: action ops (`createCustomer`, `subscribe`, `pay`, `portal`) receive `GenericActionCtx`; query ops (`products`, `subscription`, `customer`) receive `GenericQueryCtx`. |
+| `operation` | `"createCustomer" \| "subscribe" \| "pay" \| "products" \| "subscription" \| "customer" \| "portal"` | The operation being performed.                                                                                                                                                                                         |
+| `entityId`  | `string \| undefined`                                                                                | The entity ID passed by the caller, or `undefined` if acting on themselves.                                                                                                                                            |
+
+**Returns:** `Promise<[boolean, string | null]>` — `[isAuthorized, entityId]`.
+
+**Returned functions:**
+
+| Name             | Kind             | Description                                  |
+| :--------------- | :--------------- | :------------------------------------------- |
+| `createCustomer` | `internalAction` | Create a Stripe customer for a given entity. |
+| `products`       | `query`          | List all synced products with their prices.  |
+| `subscription`   | `query`          | Get the entity's active subscription.        |
+| `customer`       | `query`          | Get the entity's Stripe customer record.     |
+
+## Pre-built Helper Functions
+
+`stripe.helpers()` is the fastest way to add Stripe to your app. Instead of hand-writing each Convex function, call `stripe.helpers()` once and export the returned functions:
+
+```ts
+// convex/stripe.ts
+import { getAuthUserId } from "@convex-dev/auth/server";
+import { internalConvexStripe } from "@raideno/convex-stripe/server";
+import type { HelperAuthCallback } from "@raideno/convex-stripe/server";
+import schema from "./schema";
+
+export const { stripe, store, sync } = internalConvexStripe({
+  schema,
+  stripe: {
+    secret_key: process.env.STRIPE_SECRET_KEY!,
+    account_webhook_secret: process.env.STRIPE_ACCOUNT_WEBHOOK_SECRET!,
+  },
+});
+
+// A single callback that authenticates every helper function.
+// `context` is automatically typed as GenericActionCtx or GenericQueryCtx
+// depending on which `operation` is being executed.
+const authenticateAndAuthorize: HelperAuthCallback = async ({
+  context,   // GenericActionCtx<any> or GenericQueryCtx<any>
+  operation,
+  entityId,
+}) => {
+  // For product listings there is no specific entity — allow everyone.
+  if (operation === "products") return [true, null];
+
+  const userId = await getAuthUserId(context);
+  if (!userId) return [false, null];
+
+  // If the caller passed an explicit entityId, use it; otherwise they act on themselves.
+  return [true, entityId ?? userId];
+};
+
+export const {
+  createCustomer,
+  products,
+  subscription,
+  customer,
+} = stripe.helpers({
+  authenticateAndAuthorize
+});
+```
+
+Then register `createCustomer` with your auth callbacks (the same way as the manual approach), and call the rest from your frontend:
+
+```ts
+// frontend
+const items     = await convex.query(api.stripe.products, {});
+const sub       = await convex.query(api.stripe.subscription, {});
+const me        = await convex.query(api.stripe.customer, {});
+
+// Return URLs are handled by helper config, so frontend calls stay clean.
+const { url }   = await convex.action(api.stripe.subscribe, {
+  priceId: "price_xxx",
+});
+
+const { url }   = await convex.action(api.stripe.pay, {
+  referenceId: "order_123",
+  line_items: [{ price: "price_yyy", quantity: 1 }],
+});
+
+const { url }   = await convex.action(api.stripe.portal, {});
+```
+
+### `helpers.createCustomer`
+
+An **internal** Convex action that creates a Stripe customer for the given `entityId`. Designed to be called from auth lifecycle callbacks (e.g. `afterUserCreatedOrUpdated`), not from the frontend directly.
+
+**Arguments:**
+
+| Parameter  | Type     | Required | Description                                         |
+| :--------- | :------- | :------- | :-------------------------------------------------- |
+| `entityId` | `string` | Yes      | Your app's internal identifier for the entity.      |
+| `email`    | `string` | No       | Email address to set on the Stripe customer record. |
+
+**Returns:** The Stripe customer document from your Convex database.
+
+### `helpers.products`
+
+A **public** Convex query that returns all synced Stripe products with their associated prices nested inside.
+
+**Arguments:** none
+
+**Returns:** An array of product documents from `stripeProducts`, each with a `prices` field containing all related entries from `stripePrices`.
+
+### `helpers.subscription`
+
+A **public** Convex query that returns the active Stripe subscription for the authenticated entity, or `null` if they have no subscription.
+
+**Arguments:**
+
+| Parameter  | Type     | Required | Description                                   |
+| :--------- | :------- | :------- | :-------------------------------------------- |
+| `entityId` | `string` | No       | Override the entity (defaults to the caller). |
+
+**Returns:** The subscription document from `stripeSubscriptions`, or `null`.
+
+### `helpers.customer`
+
+A **public** Convex query that returns the Stripe customer record for the authenticated entity, or `null` if they have no customer yet.
+
+**Arguments:**
+
+| Parameter  | Type     | Required | Description                                   |
+| :--------- | :------- | :------- | :-------------------------------------------- |
+| `entityId` | `string` | No       | Override the entity (defaults to the caller). |
+
+**Returns:** The customer document from `stripeCustomers`, or `null`.
+
 ## Synced Tables
 
 The library automatically syncs the following 24 Stripe resource types into your Convex database:

package/dist/index.d.ts

@@ -4,11 +4,13 @@ import { GenericActionCtx } from 'convex/server';
 import { GenericDataModel } from 'convex/server';
 import { GenericId } from 'convex/values';
 import { GenericMutationCtx } from 'convex/server';
+import { GenericQueryCtx } from 'convex/server';
 import { GenericSchema } from 'convex/server';
 import { HttpRouter } from 'convex/server';
 import { Infer } from 'convex/values';
 import { RegisteredAction } from 'convex/server';
 import { RegisteredMutation } from 'convex/server';
+import { RegisteredQuery } from 'convex/server';
 import { RoutableMethod } from 'convex/server';
 import { SchemaDefinition } from 'convex/server';
 import { TableDefinition } from 'convex/server';
@@ -24,12 +26,34 @@ import { VRecord } from 'convex/values';
 import { VString } from 'convex/values';
 import { VUnion } from 'convex/values';
 
+/**
+ * The operations handled by action-type helpers (run in an action context).
+ */
+declare type ActionOperation = "createCustomer";
+
 declare type AllRedirectHandlers = (typeof REDIRECT_HANDLERS)[number];
 
 export declare const allStripeTablesExcept: (tables: Array<keyof typeof stripeTables>) => typeof stripeTables;
 
 declare type ArgSchema = Record<string, Validator<any, "optional" | "required", any>>;
 
+/**
+ * Arguments passed to the `authenticateAndAuthorize` callback.
+ *
+ * This is a discriminated union: when `operation` is an action-type operation,
+ * `context` is narrowed to `GenericActionCtx<any>`. For query-type operations,
+ * it is narrowed to `GenericQueryCtx<any>`.
+ */
+declare type AuthArgs = {
+    context: GenericActionCtx<any>;
+    operation: ActionOperation;
+    entityId?: string;
+} | {
+    context: GenericQueryCtx<any>;
+    operation: QueryOperation;
+    entityId?: string;
+};
+
 export declare function buildSignedReturnUrl<O extends ReturnOrigin>({ configuration, origin, failureUrl, targetUrl, data, }: {
     configuration: InternalConfiguration;
     origin: O;
@@ -170,6 +194,32 @@ export declare function defineRedirectHandler<const T extends readonly string[],
 
 export declare function defineWebhookHandler<const T extends default_2.Event.Type>(handler: WebhookHandler<T>): WebhookHandler<T>;
 
+/**
+ * The callback used by `stripe.helpers()` to authenticate and authorize
+ * the caller for a given operation.
+ *
+ * **Contract:**
+ * - Return `[true, entityId]` when the caller is authenticated and the
+ *   resolved `entityId` should be used for the Stripe operation.
+ * - Return `[false, null]` (or throw) to reject the request.
+ * - When no `entityId` is passed to the helper function, it means the
+ *   caller wants to act on themselves — the callback is responsible for
+ *   deriving their identity from `context` (e.g. via `getAuthUserId`).
+ *
+ * @example
+ * const authenticateAndAuthorize: HelperAuthCallback = async ({
+ *   context,
+ *   operation,
+ *   entityId,
+ * }) => {
+ *   if (operation === "products") return [true, null];
+ *   const userId = await getAuthUserId(context);
+ *   if (!userId) return [false, null];
+ *   return [true, entityId ?? userId];
+ * };
+ */
+export declare type HelperAuthCallback = (args: AuthArgs) => Promise<[boolean, string | null]>;
+
 declare type InferArgs<S extends ArgSchema> = {
     [K in keyof S as S[K] extends Validator<any, "required", any> ? K : never]: Infer<S[K]>;
 } & {
@@ -477,6 +527,283 @@ export declare const internalConvexStripe: (configuration_: InputConfiguration &
              */
             link: (context: GenericActionCtx<any>, args: Parameters<(typeof CreateAccountLinkImplementation)["handler"]>[1], options?: Parameters<(typeof CreateAccountLinkImplementation)["handler"]>[2]) => Promise<default_2.Response<default_2.AccountLink>>;
         };
+        /**
+         * Returns a set of pre-built, authorization-aware Convex functions
+         * (actions and queries) that cover the most common Stripe operations.
+         *
+         * Each returned function calls your `authenticateAndAuthorize` callback
+         * to resolve the caller's identity and enforce access control before
+         * delegating to the underlying Stripe implementation.
+         *
+         * When a caller omits `entityId`, it signals that they want to act on
+         * themselves — your callback is responsible for deriving their identity
+         * from `context` (e.g. via `getAuthUserId`).
+         *
+         * **Returned functions:**
+         * - `internalCreateCustomer` — internal action: create a Stripe customer for a given entity.
+         * - `subscribe`             — public action:   create a subscription checkout session.
+         * - `pay`                   — public action:   create a one-time payment checkout session.
+         * - `products`              — public query:    list all products with their prices.
+         * - `subscription`          — public query:    get the entity's active subscription.
+         * - `customer`              — public query:    get the entity's Stripe customer record.
+         * - `portal`                — public action:   open a Billing Portal session.
+         *
+         * @param config - Configuration for the helpers.
+         * @param config.authenticateAndAuthorize - Callback that authenticates the
+         *   caller and returns `[isAuthorized, entityId | null]`.
+         * @param config.urls - Centralized return URL configuration (required). URLs are grouped
+         *   by operation: `subscribe`, `pay`, and `portal`.
+         *
+         * @example
+         * // convex/stripe.ts
+         * import { getAuthUserId } from "@convex-dev/auth/server";
+         *
+         * export const { stripe, store, sync } = internalConvexStripe({ ... });
+         *
+         * export const { internalCreateCustomer, subscribe, pay, products, subscription, customer, portal } =
+         *   stripe.helpers({
+         *     authenticateAndAuthorize: async ({ context, operation, entityId }) => {
+         *       const userId = await getAuthUserId(context);
+         *       if (!userId) return [false, null];
+         *       // If caller passed an explicit entityId, use it; otherwise act on themselves.
+         *       return [true, entityId ?? userId];
+         *     },
+         *     urls: {
+         *       subscribe: {
+         *         success: "https://example.com/success",
+         *         cancel: "https://example.com/cancel",
+         *         failure: "https://example.com/error",
+         *       },
+         *       pay: {
+         *         success: "https://example.com/pay-success",
+         *         cancel: "https://example.com/pay-cancel",
+         *         failure: "https://example.com/pay-error",
+         *       },
+         *       portal: {
+         *         return: "https://example.com/account",
+         *         failure: "https://example.com/portal-error",
+         *       },
+         *     },
+         *   });
+         */
+        helpers: (config: StripeHelpersConfig) => {
+            createCustomer: RegisteredAction<"internal", {
+            email?: string | undefined;
+            entityId: string;
+            }, Promise<{
+            _id: GenericId<"stripeCustomers">;
+            _creationTime: number;
+            accountId?: string | undefined;
+            entityId?: string | undefined;
+            stripe: {
+            email?: string | null | undefined;
+            metadata?: Record<string, string | number | null> | null | undefined;
+            address?: {
+            country?: string | null | undefined;
+            city?: string | null | undefined;
+            line1?: string | null | undefined;
+            line2?: string | null | undefined;
+            postal_code?: string | null | undefined;
+            state?: string | null | undefined;
+            } | null | undefined;
+            name?: string | null | undefined;
+            phone?: string | null | undefined;
+            shipping?: {
+            address?: {
+            country?: string | null | undefined;
+            city?: string | null | undefined;
+            line1?: string | null | undefined;
+            line2?: string | null | undefined;
+            postal_code?: string | null | undefined;
+            state?: string | null | undefined;
+            } | undefined;
+            name?: string | undefined;
+            phone?: string | null | undefined;
+            carrier?: string | null | undefined;
+            tracking_number?: string | null | undefined;
+            } | null | undefined;
+            currency?: string | null | undefined;
+            description?: string | null | undefined;
+            discount?: any;
+            tax?: {
+            ip_address?: string | null | undefined;
+            automatic_tax: "failed" | "not_collecting" | "supported" | "unrecognized_location";
+            location: {
+            state?: string | null | undefined;
+            country: string;
+            source: string;
+            } | null;
+            } | undefined;
+            cash_balance?: any;
+            default_source?: string | null | undefined;
+            delinquent?: boolean | null | undefined;
+            invoice_credit_balance?: any;
+            invoice_prefix?: string | null | undefined;
+            invoice_settings?: any;
+            next_invoice_sequence?: number | null | undefined;
+            preferred_locales?: string[] | null | undefined;
+            sources?: any;
+            subscriptions?: any;
+            tax_exempt?: "none" | "reverse" | "exempt" | null | undefined;
+            tax_ids?: any;
+            test_clock?: string | null | undefined;
+            object: string;
+            id: string;
+            created: number;
+            livemode: boolean;
+            balance: number;
+            };
+            lastSyncedAt: number;
+            customerId: string;
+            }>>;
+            products: RegisteredQuery<"public", {}, Promise<{
+            prices: {
+            _id: GenericId<"stripePrices">;
+            _creationTime: number;
+            accountId?: string | undefined;
+            stripe: {
+            metadata?: Record<string, string | number | null> | null | undefined;
+            object: string;
+            type: "one_time" | "recurring";
+            id: string;
+            created: number;
+            active: boolean;
+            livemode: boolean;
+            currency: string;
+            nickname: string | null;
+            billing_scheme: "per_unit" | "tiered";
+            tiers_mode: "graduated" | "volume" | null;
+            recurring: {
+            interval: "day" | "week" | "month" | "year";
+            interval_count: number;
+            meter: string | null;
+            trial_period_days: number | null;
+            usage_type: "licensed" | "metered";
+            } | null;
+            productId: string;
+            unit_amount: number | null;
+            lookup_key: string | null;
+            transform_quantity: {
+            divide_by: number;
+            round: "up" | "down";
+            } | null;
+            unit_amount_decimal: string | null;
+            };
+            lastSyncedAt: number;
+            priceId: string;
+            }[];
+            _id: GenericId<"stripeProducts">;
+            _creationTime: number;
+            accountId?: string | undefined;
+            stripe: {
+            metadata?: Record<string, string | number | null> | null | undefined;
+            statement_descriptor?: string | null | undefined;
+            unit_label?: string | null | undefined;
+            object: string;
+            id: string;
+            created: number;
+            active: boolean;
+            name: string;
+            url: string | null;
+            livemode: boolean;
+            updated: number;
+            description: string | null;
+            images: string[];
+            package_dimensions: {
+            length: number;
+            height: number;
+            weight: number;
+            width: number;
+            } | null;
+            shippable: boolean | null;
+            marketing_features: {
+            name?: string | null | undefined;
+            }[];
+            default_price: string | null;
+            };
+            productId: string;
+            lastSyncedAt: number;
+            }[]>>;
+            subscription: RegisteredQuery<"public", {
+            entityId?: string | undefined;
+            }, Promise<{
+            _id: GenericId<"stripeSubscriptions">;
+            _creationTime: number;
+            accountId?: string | undefined;
+            stripe: any;
+            lastSyncedAt: number;
+            customerId: string;
+            subscriptionId: string | null;
+            } | null>>;
+            customer: RegisteredQuery<"public", {
+            entityId?: string | undefined;
+            }, Promise<{
+            _id: GenericId<"stripeCustomers">;
+            _creationTime: number;
+            accountId?: string | undefined;
+            entityId?: string | undefined;
+            stripe: {
+            email?: string | null | undefined;
+            metadata?: Record<string, string | number | null> | null | undefined;
+            address?: {
+            country?: string | null | undefined;
+            city?: string | null | undefined;
+            line1?: string | null | undefined;
+            line2?: string | null | undefined;
+            postal_code?: string | null | undefined;
+            state?: string | null | undefined;
+            } | null | undefined;
+            name?: string | null | undefined;
+            phone?: string | null | undefined;
+            shipping?: {
+            address?: {
+            country?: string | null | undefined;
+            city?: string | null | undefined;
+            line1?: string | null | undefined;
+            line2?: string | null | undefined;
+            postal_code?: string | null | undefined;
+            state?: string | null | undefined;
+            } | undefined;
+            name?: string | undefined;
+            phone?: string | null | undefined;
+            carrier?: string | null | undefined;
+            tracking_number?: string | null | undefined;
+            } | null | undefined;
+            currency?: string | null | undefined;
+            description?: string | null | undefined;
+            discount?: any;
+            tax?: {
+            ip_address?: string | null | undefined;
+            automatic_tax: "failed" | "not_collecting" | "supported" | "unrecognized_location";
+            location: {
+            state?: string | null | undefined;
+            country: string;
+            source: string;
+            } | null;
+            } | undefined;
+            cash_balance?: any;
+            default_source?: string | null | undefined;
+            delinquent?: boolean | null | undefined;
+            invoice_credit_balance?: any;
+            invoice_prefix?: string | null | undefined;
+            invoice_settings?: any;
+            next_invoice_sequence?: number | null | undefined;
+            preferred_locales?: string[] | null | undefined;
+            sources?: any;
+            subscriptions?: any;
+            tax_exempt?: "none" | "reverse" | "exempt" | null | undefined;
+            tax_ids?: any;
+            test_clock?: string | null | undefined;
+            object: string;
+            id: string;
+            created: number;
+            livemode: boolean;
+            balance: number;
+            };
+            lastSyncedAt: number;
+            customerId: string;
+            } | null>>;
+        };
     };
     /**
      * Internal Convex mutation that persists a Stripe object into your database.
@@ -1662,6 +1989,11 @@ declare const PortalImplementation: {
     } & Omit<default_2.BillingPortal.SessionCreateParams, "customer" | "return_url">, stripeOptions: default_2.RequestOptions, configuration: InternalConfiguration, options: InternalOptions) => Promise<default_2.Response<default_2.BillingPortal.Session>>;
 };
 
+/**
+ * The operations handled by query-type helpers (run in a query context).
+ */
+declare type QueryOperation = "products" | "subscription" | "customer";
+
 declare type RecursiveDeepRequired<T> = T extends (...args: any[]) => any ? T : T extends object ? {
     [K in keyof T]-?: RecursiveDeepRequired<T[K]>;
 } : T;
@@ -1697,6 +2029,16 @@ declare type ReturnOrigin = (typeof RETURN_ORIGINS)[number];
 
 declare type StripeDataModel = DataModelFromSchemaDefinition<typeof stripeSchema>;
 
+/**
+ * Configuration for the pre-built Stripe helpers.
+ */
+export declare interface StripeHelpersConfig {
+    /**
+     * Callback that authenticates the caller and returns [isAuthorized, resolvedEntityId].
+     */
+    authenticateAndAuthorize: HelperAuthCallback;
+}
+
 declare const stripeSchema: SchemaDefinition<    {
 stripeAccounts: TableDefinition<VObject<    {
 entityId?: string | undefined;

package/dist/server.js

@@ -2182,6 +2182,31 @@ const internalMutationGeneric = ((functionDefinition) => {
   func._handler = handler;
   return func;
 });
+async function invokeQuery(func, argsStr) {
+  const requestId = "";
+  const args = jsonToConvex(JSON.parse(argsStr));
+  const queryCtx = {
+    db: setupReader(),
+    auth: setupAuth(requestId),
+    storage: setupStorageReader(requestId),
+    runQuery: (reference, args2) => runUdf("query", reference, args2)
+  };
+  const result = await invokeFunction(func, queryCtx, args);
+  validateReturnValue(result);
+  return JSON.stringify(convexToJson(result === void 0 ? null : result));
+}
+const queryGeneric = ((functionDefinition) => {
+  const handler = typeof functionDefinition === "function" ? functionDefinition : functionDefinition.handler;
+  const func = dontCallDirectly("query", handler);
+  assertNotBrowser();
+  func.isQuery = true;
+  func.isPublic = true;
+  func.invokeQuery = (argsStr) => invokeQuery(handler, argsStr);
+  func.exportArgs = exportArgs(functionDefinition);
+  func.exportReturns = exportReturns(functionDefinition);
+  func._handler = handler;
+  return func;
+});
 async function invokeAction(func, requestId, argsStr) {
   const args = jsonToConvex(JSON.parse(argsStr));
   const calls = setupActionCalls(requestId);
@@ -5764,7 +5789,12 @@ const DEFAULT_OPTIONS = {
   base: "stripe"
 };
 const normalizeOptions = (options) => {
-  return deepmerge(DEFAULT_OPTIONS, options);
+  const { logger, ...rest } = options;
+  const merged = deepmerge(DEFAULT_OPTIONS, rest);
+  return {
+    ...merged,
+    logger: logger || DEFAULT_OPTIONS.logger
+  };
 };
 const defineActionCallableFunction = (spec) => spec;
 const defineActionImplementation = (spec) => spec;
@@ -6929,6 +6959,110 @@ const SubscribeImplementation = defineActionCallableFunction({
     return checkout;
   }
 });
+const buildCreateCustomer = (configuration, options, authenticateAndAuthorize) => internalActionGeneric({
+  args: {
+    entityId: v.string(),
+    email: v.optional(v.string())
+  },
+  handler: async (context_, args) => {
+    const context = context_;
+    const [authorized, resolvedEntityId] = await authenticateAndAuthorize({
+      context,
+      operation: "createCustomer",
+      entityId: args.entityId
+    });
+    if (!authorized || !resolvedEntityId) {
+      throw new Error("Unauthorized");
+    }
+    return CreateCustomerImplementation.handler(
+      context,
+      { entityId: resolvedEntityId, email: args.email },
+      {},
+      configuration,
+      options
+    );
+  }
+});
+const buildCustomer = (_configuration, _options, authenticateAndAuthorize) => queryGeneric({
+  args: {
+    entityId: v.optional(v.string())
+  },
+  handler: async (context_, args) => {
+    const context = context_;
+    const [authorized, resolvedEntityId] = await authenticateAndAuthorize({
+      context,
+      operation: "customer",
+      entityId: args.entityId
+    });
+    if (!authorized || !resolvedEntityId) {
+      throw new Error("Unauthorized");
+    }
+    const customer = await context.db.query("stripeCustomers").withIndex("byEntityId", (q) => q.eq("entityId", resolvedEntityId)).unique();
+    return customer ?? null;
+  }
+});
+const buildProducts = (_configuration, _options, authenticateAndAuthorize) => queryGeneric({
+  args: {},
+  handler: async (context_) => {
+    const context = context_;
+    const [authorized] = await authenticateAndAuthorize({
+      context,
+      operation: "products",
+      entityId: void 0
+    });
+    if (!authorized) {
+      throw new Error("Unauthorized");
+    }
+    const prices = await context.db.query("stripePrices").collect();
+    const products = await context.db.query("stripeProducts").collect();
+    return products.map(
+      (product) => ({
+        ...product,
+        prices: prices.filter((price) => price.stripe.productId === product.productId)
+      })
+    );
+  }
+});
+const buildSubscription = (_configuration, _options, authenticateAndAuthorize) => queryGeneric({
+  args: {
+    entityId: v.optional(v.string())
+  },
+  handler: async (context_, args) => {
+    const context = context_;
+    const [authorized, resolvedEntityId] = await authenticateAndAuthorize({
+      context,
+      operation: "subscription",
+      entityId: args.entityId
+    });
+    if (!authorized || !resolvedEntityId) {
+      throw new Error("Unauthorized");
+    }
+    const customer = await context.db.query("stripeCustomers").withIndex("byEntityId", (q) => q.eq("entityId", resolvedEntityId)).unique();
+    if (!customer) return null;
+    const subscription = await context.db.query("stripeSubscriptions").withIndex(
+      "byCustomerId",
+      (q) => q.eq("customerId", customer.customerId)
+    ).unique();
+    return subscription ?? null;
+  }
+});
+const buildHelpers = (configuration, options, config) => {
+  const { authenticateAndAuthorize } = config;
+  return {
+    createCustomer: buildCreateCustomer(
+      configuration,
+      options,
+      authenticateAndAuthorize
+    ),
+    products: buildProducts(configuration, options, authenticateAndAuthorize),
+    subscription: buildSubscription(
+      configuration,
+      options,
+      authenticateAndAuthorize
+    ),
+    customer: buildCustomer(configuration, options, authenticateAndAuthorize)
+  };
+};
 const pickProductUpdateParams = (product) => {
   const {
     active,
@@ -9627,7 +9761,71 @@ const internalConvexStripe = (configuration_, options_) => {
             ConvexStripeInternalOptions
           );
         }
-      }
+      },
+      /**
+       * Returns a set of pre-built, authorization-aware Convex functions
+       * (actions and queries) that cover the most common Stripe operations.
+       *
+       * Each returned function calls your `authenticateAndAuthorize` callback
+       * to resolve the caller's identity and enforce access control before
+       * delegating to the underlying Stripe implementation.
+       *
+       * When a caller omits `entityId`, it signals that they want to act on
+       * themselves — your callback is responsible for deriving their identity
+       * from `context` (e.g. via `getAuthUserId`).
+       *
+       * **Returned functions:**
+       * - `internalCreateCustomer` — internal action: create a Stripe customer for a given entity.
+       * - `subscribe`             — public action:   create a subscription checkout session.
+       * - `pay`                   — public action:   create a one-time payment checkout session.
+       * - `products`              — public query:    list all products with their prices.
+       * - `subscription`          — public query:    get the entity's active subscription.
+       * - `customer`              — public query:    get the entity's Stripe customer record.
+       * - `portal`                — public action:   open a Billing Portal session.
+       *
+       * @param config - Configuration for the helpers.
+       * @param config.authenticateAndAuthorize - Callback that authenticates the
+       *   caller and returns `[isAuthorized, entityId | null]`.
+       * @param config.urls - Centralized return URL configuration (required). URLs are grouped
+       *   by operation: `subscribe`, `pay`, and `portal`.
+       *
+       * @example
+       * // convex/stripe.ts
+       * import { getAuthUserId } from "@convex-dev/auth/server";
+       *
+       * export const { stripe, store, sync } = internalConvexStripe({ ... });
+       *
+       * export const { internalCreateCustomer, subscribe, pay, products, subscription, customer, portal } =
+       *   stripe.helpers({
+       *     authenticateAndAuthorize: async ({ context, operation, entityId }) => {
+       *       const userId = await getAuthUserId(context);
+       *       if (!userId) return [false, null];
+       *       // If caller passed an explicit entityId, use it; otherwise act on themselves.
+       *       return [true, entityId ?? userId];
+       *     },
+       *     urls: {
+       *       subscribe: {
+       *         success: "https://example.com/success",
+       *         cancel: "https://example.com/cancel",
+       *         failure: "https://example.com/error",
+       *       },
+       *       pay: {
+       *         success: "https://example.com/pay-success",
+       *         cancel: "https://example.com/pay-cancel",
+       *         failure: "https://example.com/pay-error",
+       *       },
+       *       portal: {
+       *         return: "https://example.com/account",
+       *         failure: "https://example.com/portal-error",
+       *       },
+       *     },
+       *   });
+       */
+      helpers: (config) => buildHelpers(
+        ConvexStripeInternalConfiguration,
+        ConvexStripeInternalOptions,
+        config
+      )
     },
     /**
      * Internal Convex mutation that persists a Stripe object into your database.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raideno/convex-stripe",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Easy stripe billing for convex apps.",
   "keywords": [
     "billing",