@raideno/convex-stripe 0.3.4 → 0.3.6

package/README.md

@@ -17,9 +17,9 @@ Stripe [syncing](./documentation/references/tables.md), subscriptions, [checkout
     - [7. Run the `sync` Action](#7-run-the-sync-action)
     - [8. Start Building](#8-start-building)
   - [Configuration](#configuration)
+    - [Schema Configuration](#schema-configuration)
     - [Stripe Configuration](#stripe-configuration)
     - [Sync Configuration](#sync-configuration)
-      - [Table Selection](#table-selection)
       - [Catalog (Unstable)](#catalog-unstable)
       - [Webhook Configuration](#webhook-configuration)
       - [Portal Configuration](#portal-configuration)
@@ -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)
@@ -113,8 +118,7 @@ export default defineSchema({
 });
 ```
 
-> [!WARNING]
-> Ensure that your table configuration in `convex/schema.ts` matches your `sync.tables` configuration in `convex/stripe.ts` exactly! If your `sync.tables` tries to sync a table that is excluded from your schema, Convex Stripe will throw a runtime error when processing webhooks.
+The package will only sync the tables you defined.
 
 See [Tables Reference](./documentation/references/tables.md) for the full list of tables and their schemas.
 
@@ -125,16 +129,16 @@ Call `internalConvexStripe` with your Stripe credentials and sync configuration.
 ```ts
 // convex/stripe.ts
 
-import { internalConvexStripe, syncAllTables } from "@raideno/convex-stripe/server";
+import { internalConvexStripe } from "@raideno/convex-stripe/server";
+
+import schema from "./schema";
 
 export const { stripe, store, sync } = internalConvexStripe({
+  schema: schema,
   stripe: {
     secret_key: process.env.STRIPE_SECRET_KEY!,
     account_webhook_secret: process.env.STRIPE_ACCOUNT_WEBHOOK_SECRET!,
   },
-  sync: {
-    tables: syncAllTables(),
-  },
 });
 ```
 
@@ -260,6 +264,9 @@ The `internalConvexStripe` function accepts a configuration object and an option
 ```ts
 const { stripe, store, sync } = internalConvexStripe(configuration, options);
 ```
+### Schema Configuration
+
+The `schema` key holds your convex app schema, from it the package will infer which stripe tables should be synced or not depending on what stripeTables where defined.
 
 ### Stripe Configuration
 
@@ -276,29 +283,6 @@ The `stripe` key in the configuration object holds your Stripe credentials and A
 
 The `sync` key controls which tables are synced and allows you to define catalog items, webhook endpoints, and billing portal configuration.
 
-#### Table Selection
-
-Three helper functions are provided to control which Stripe tables are synced into Convex:
-
-```ts
-import {
-  syncAllTables,
-  syncAllTablesExcept,
-  syncOnlyTables,
-} from "@raideno/convex-stripe/server";
-
-// Sync all 24 tables (default)
-{ tables: syncAllTables() }
-
-// Sync all tables except specific ones
-{ tables: syncAllTablesExcept(["stripeReviews", "stripePlans"]) }
-
-// Sync only specific tables
-{ tables: syncOnlyTables(["stripeCustomers", "stripeSubscriptions", "stripeProducts", "stripePrices"]) }
-```
-
-All 24 available tables are listed in the [Synced Tables](#synced-tables) section.
-
 #### Catalog (Unstable)
 
 The `sync.catalog` key lets you pre-define products and prices that should exist in Stripe. When the `sync` action is called with `{ catalog: true }`, the library ensures these objects exist in your Stripe account.
@@ -307,7 +291,6 @@ The `sync.catalog` key lets you pre-define products and prices that should exist
 internalConvexStripe({
   // ...
   sync: {
-    tables: syncAllTables(),
     catalog: {
       products: [
         { name: "Pro Plan", metadata: { convex_stripe_key: "pro" } },
@@ -502,15 +485,17 @@ Then update your configuration to include it:
 ```ts
 // convex/stripe.ts
 
+import { internalConvexStripe } from "@raideno/convex-stripe/server";
+
+import schema from "./schema";
+
 export const { stripe, store, sync } = internalConvexStripe({
+  schema: schema,
   stripe: {
     secret_key: process.env.STRIPE_SECRET_KEY!,
     account_webhook_secret: process.env.STRIPE_ACCOUNT_WEBHOOK_SECRET!,
     connect_webhook_secret: process.env.STRIPE_CONNECT_WEBHOOK_SECRET!,
-  },
-  sync: {
-    tables: syncAllTables(),
-  },
+  }
 });
 ```
 
@@ -817,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,10 +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';
@@ -23,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;
@@ -169,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]>;
 } & {
@@ -176,6 +227,7 @@ declare type InferArgs<S extends ArgSchema> = {
 };
 
 export declare interface InputConfiguration {
+    schema: SchemaDefinition<GenericSchema, true>;
     stripe: {
         /** Stripe API version to pin against (recommended for stability). */
         version?: default_2.StripeConfig["apiVersion"];
@@ -189,7 +241,7 @@ export declare interface InputConfiguration {
          */
         connect_webhook_secret?: string;
     };
-    sync: {
+    sync?: {
         catalog?: {
             /** Products to ensure exist in Stripe (optional bootstrap). */
             products?: default_2.ProductCreateParams[];
@@ -235,7 +287,7 @@ export declare interface InputConfiguration {
         /** Optional Billing Portal configuration to create/sync. */
         portal?: default_2.BillingPortal.ConfigurationCreateParams;
         /** Which Stripe tables you want to sync into Convex. */
-        tables: Record<keyof typeof stripeTables, boolean>;
+        tables?: Record<keyof typeof stripeTables, boolean>;
     };
     callbacks?: {
         /** Called after a row is inserted/upserted/deleted in your Stripe tables. */
@@ -282,7 +334,11 @@ export declare type InternalConfiguration = RecursiveDeepRequired<InputConfigura
  *   },
  * });
  */
-export declare const internalConvexStripe: (configuration_: InputConfiguration, options_?: InputOptions) => {
+export declare const internalConvexStripe: (configuration_: InputConfiguration & {
+    sync?: {
+        tables?: never;
+    };
+}, options_?: InputOptions) => {
     stripe: {
         /** Raw HTTP handler descriptors. Prefer `addHttpRoutes` unless you need manual control. */
         http: {
@@ -318,7 +374,7 @@ export declare const internalConvexStripe: (configuration_: InputConfiguration,
          * stripe.addHttpRoutes(http);
          * export default http;
          */
-        addHttpRoutes: (http: HttpRouter, config?: InputConfiguration) => void;
+        addHttpRoutes: (http: HttpRouter) => void;
         /**
          * Opens a Stripe Billing Portal session for an existing customer.
          * Use this to let users manage their subscription, invoices, and payment methods.
@@ -471,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.
@@ -1656,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;
@@ -1691,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;
@@ -9312,12 +9660,6 @@ export declare const SYNC_HANDLERS: readonly [{
     }, configuration: InternalConfiguration, options: InternalOptions) => Promise<void>;
 }];
 
-export declare const syncAllTables: () => Record<keyof typeof stripeTables, boolean>;
-
-export declare const syncAllTablesExcept: (tables: Array<keyof typeof stripeTables>) => Record<keyof typeof stripeTables, boolean>;
-
-export declare const syncOnlyTables: (tables: Array<keyof typeof stripeTables>) => Record<keyof typeof stripeTables, boolean>;
-
 export declare const WEBHOOK_HANDLERS: readonly [WebhookHandler<"account.updated">, WebhookHandler<"billing_portal.configuration.created" | "billing_portal.configuration.updated">, WebhookHandler<"capability.updated">, WebhookHandler<"charge.captured" | "charge.expired" | "charge.failed" | "charge.pending" | "charge.refunded" | "charge.succeeded" | "charge.updated">, WebhookHandler<"checkout.session.async_payment_failed" | "checkout.session.async_payment_succeeded" | "checkout.session.completed" | "checkout.session.expired">, WebhookHandler<"coupon.created" | "coupon.deleted" | "coupon.updated">, WebhookHandler<"credit_note.created" | "credit_note.updated" | "credit_note.voided">, WebhookHandler<"customer.created" | "customer.deleted" | "customer.updated">, WebhookHandler<"charge.dispute.closed" | "charge.dispute.created" | "charge.dispute.funds_reinstated" | "charge.dispute.funds_withdrawn" | "charge.dispute.updated">, WebhookHandler<"radar.early_fraud_warning.created" | "radar.early_fraud_warning.updated">, WebhookHandler<"invoice.created" | "invoice.deleted" | "invoice.finalization_failed" | "invoice.finalized" | "invoice.marked_uncollectible" | "invoice.overdue" | "invoice.overpaid" | "invoice.paid" | "invoice.payment_action_required" | "invoice.payment_failed" | "invoice.payment_succeeded" | "invoice.sent" | "invoice.upcoming" | "invoice.updated" | "invoice.voided" | "invoice.will_be_due">, WebhookHandler<"mandate.updated">, WebhookHandler<"payment_intent.amount_capturable_updated" | "payment_intent.canceled" | "payment_intent.created" | "payment_intent.partially_funded" | "payment_intent.payment_failed" | "payment_intent.processing" | "payment_intent.requires_action" | "payment_intent.succeeded">, WebhookHandler<"payment_method.attached" | "payment_method.automatically_updated" | "payment_method.detached" | "payment_method.updated">, WebhookHandler<"payout.canceled" | "payout.created" | "payout.failed" | "payout.paid" | "payout.reconciliation_completed" | "payout.updated">, WebhookHandler<"plan.created" | "plan.deleted" | "plan.updated">, WebhookHandler<"price.created" | "price.deleted" | "price.updated">, WebhookHandler<"product.created" | "product.deleted" | "product.updated">, WebhookHandler<"promotion_code.created" | "promotion_code.updated">, WebhookHandler<"charge.refund.updated" | "refund.created" | "refund.failed" | "refund.updated">, WebhookHandler<"review.closed" | "review.opened">, WebhookHandler<"setup_intent.canceled" | "setup_intent.created" | "setup_intent.requires_action" | "setup_intent.setup_failed" | "setup_intent.succeeded">, WebhookHandler<"subscription_schedule.aborted" | "subscription_schedule.canceled" | "subscription_schedule.completed" | "subscription_schedule.created" | "subscription_schedule.expiring" | "subscription_schedule.released" | "subscription_schedule.updated">, WebhookHandler<"customer.subscription.created" | "customer.subscription.deleted" | "customer.subscription.paused" | "customer.subscription.pending_update_applied" | "customer.subscription.pending_update_expired" | "customer.subscription.resumed" | "customer.subscription.trial_will_end" | "customer.subscription.updated">, WebhookHandler<"customer.tax_id.created" | "customer.tax_id.deleted" | "customer.tax_id.updated">, WebhookHandler<"transfer.created" | "transfer.reversed" | "transfer.updated">];
 
 declare type WebhookHandler<TEvents extends default_2.Event.Type> = {

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);
@@ -5612,21 +5637,6 @@ const stripeTables = {
   }).index("byAccountId", ["accountId"]).index(BY_STRIPE_ID_INDEX_NAME, ["capabilityId"])
 };
 defineSchema(stripeTables);
-const syncAllTables = () => Object.fromEntries(
-  Object.keys(stripeTables).map((table) => [table, true])
-);
-const syncAllTablesExcept = (tables) => Object.fromEntries(
-  Object.keys(stripeTables).map((table) => [
-    table,
-    !tables.includes(table)
-  ])
-);
-const syncOnlyTables = (tables) => Object.fromEntries(
-  Object.keys(stripeTables).map((table) => [
-    table,
-    tables.includes(table)
-  ])
-);
 const allStripeTablesExcept = (tables) => Object.fromEntries(
   Object.entries(stripeTables).map(([table, definition]) => [
     table,
@@ -5640,6 +5650,7 @@ const onlyStripeTables = (tables) => Object.fromEntries(
   ])
 );
 const DEFAULT_CONFIGURATION = {
+  schema: void 0,
   stripe: {
     version: "2025-08-27.basil",
     secret_key: "",
@@ -5659,42 +5670,42 @@ const DEFAULT_CONFIGURATION = {
     }
   },
   sync: {
-    catalog: {
-      products: [],
-      prices: [],
-      metadataKey: "convex_stripe_key",
-      behavior: {
-        onExisting: "update",
-        onMissingKey: "create"
-      }
-    },
     tables: {
       stripeAccounts: true,
+      stripeBillingPortalConfigurations: true,
       stripeCapabilities: true,
-      stripeTransfers: true,
+      stripeCharges: true,
+      stripeCheckoutSessions: true,
       stripeCoupons: true,
+      stripeCreditNotes: true,
       stripeCustomers: true,
+      stripeDisputes: true,
+      stripeEarlyFraudWarnings: true,
+      stripeInvoices: true,
+      stripeMandates: true,
+      stripePaymentIntents: true,
+      stripePaymentMethods: true,
+      stripePayouts: true,
+      stripePlans: true,
       stripePrices: true,
       stripeProducts: true,
       stripePromotionCodes: true,
-      stripeSubscriptions: true,
-      stripePayouts: true,
-      stripeCheckoutSessions: true,
-      stripePaymentIntents: true,
       stripeRefunds: true,
-      stripeInvoices: true,
       stripeReviews: true,
-      stripeCharges: true,
-      stripeCreditNotes: true,
-      stripeDisputes: true,
-      stripeEarlyFraudWarnings: true,
-      stripePaymentMethods: true,
-      stripePlans: true,
       stripeSetupIntents: true,
+      stripeSubscriptions: true,
       stripeSubscriptionSchedules: true,
       stripeTaxIds: true,
-      stripeMandates: true,
-      stripeBillingPortalConfigurations: true
+      stripeTransfers: true
+    },
+    catalog: {
+      products: [],
+      prices: [],
+      metadataKey: "convex_stripe_key",
+      behavior: {
+        onExisting: "update",
+        onMissingKey: "create"
+      }
     },
     webhooks: {
       account: {
@@ -5763,8 +5774,13 @@ const DEFAULT_CONFIGURATION = {
     }
   }
 };
-const normalizeConfiguration = (config) => {
-  return deepmerge(DEFAULT_CONFIGURATION, config);
+const normalizeConfiguration = (configuration) => {
+  const output = deepmerge(DEFAULT_CONFIGURATION, configuration);
+  const stripeTableNames = Object.keys(stripeTables);
+  output.sync.tables = Object.fromEntries(
+    Object.keys(configuration.schema.tables).filter((table) => stripeTableNames.includes(table)).map((table) => [table, true])
+  );
+  return output;
 };
 const DEFAULT_OPTIONS = {
   store: "store",
@@ -6938,6 +6954,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,
@@ -9527,8 +9647,7 @@ const internalConvexStripe = (configuration_, options_) => {
        * stripe.addHttpRoutes(http);
        * export default http;
        */
-      addHttpRoutes: (http, config) => {
-        config = normalizeConfiguration(config || configuration_);
+      addHttpRoutes: (http) => {
         http.route({
           path: http_.webhook.path,
           method: http_.webhook.method,
@@ -9637,7 +9756,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.
@@ -9679,8 +9862,5 @@ export {
   defineWebhookHandler,
   internalConvexStripe,
   onlyStripeTables,
-  stripeTables,
-  syncAllTables,
-  syncAllTablesExcept,
-  syncOnlyTables
+  stripeTables
 };

package/package.json

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