@raideno/convex-stripe 0.2.2 → 0.2.4

package/README.md

@@ -45,13 +45,16 @@ export default defineSchema({
 ```ts
 // convex/stripe.ts
 
-import { internalConvexStripe } from "@raideno/convex-stripe/server";
+import { internalConvexStripe, syncAllTables } from "@raideno/convex-stripe/server";
 
 export const { stripe, store, sync } = internalConvexStripe({
   stripe: {
     secret_key: process.env.STRIPE_SECRET_KEY!,
     account_webhook_secret: process.env.STRIPE_ACCOUNT_WEBHOOK_SECRET!,
   },
+  sync: {
+    tables: syncAllTables(),
+  },
 });
 
 export const createCustomer = internalAction({
@@ -165,6 +168,9 @@ Now you can use the provided functions to:
 
 If you wish to also add stripe connect, below is a guide on how to do it. You can find a full example in [`examples/marketplaces/README.md`](examples/marketplace/README.md).
 
+### 0. Enable connect on your stripe dashboard.
+...
+
 ### 1. Create a connect webhook using `sync` method.
 ...
 
@@ -243,8 +249,8 @@ This action is typically manually called or setup to be automatically called in
 }
 ```
 
-- `data` (optional, default: `true`): Syncs all existing Stripe resources to Convex tables.
-- `data.withConnect` (option, default: `false`): Syncs all existing Stripe resources from linked accounts to Convex tables.
+- `tables` (optional, default: `true`): Syncs all existing Stripe resources to Convex tables.
+- `tables.withConnect` (option, default: `false`): Syncs all existing Stripe resources from linked accounts to Convex tables.
 - `webhook.account` (optional, default: `false`): Creates/updates the account webhook endpoint. Returns the webhook secret if a new endpoint is created. You must set it in your convex environment variables as `STRIPE_ACCOUNT_WEBHOOK_SECRET`.
 - `webhook.connect` (optional, default: `false`): Creates/updates the connect webhook endpoint. Returns the webhook secret if a new endpoint is created. You must set it in your convex environment variables as `STRIPE_CONNECT_WEBHOOK_SECRET`.
 - `portal` (optional, default: `false`): Creates the default billing portal configuration if it doesn't exist.

package/dist/index.d.ts

@@ -149,41 +149,108 @@ declare const CreateCustomerImplementation: {
     }>;
 };
 
-export declare type InputConfiguration = WithOptional<InternalConfiguration, "portal" | "sync" | "redirectTtlMs" | "webhook" | "detached" | "catalog">;
-
-export declare type InputOptions = WithOptional<InternalOptions, "store" | "debug" | "logger" | "base">;
-
-export declare interface InternalConfiguration {
+export declare interface InputConfiguration {
     stripe: {
+        /** Stripe API version to pin against (recommended for stability). */
+        version?: default_2.StripeConfig["apiVersion"];
+        /** Secret key for your Stripe account (starts with `sk_`). */
         secret_key: string;
+        /** Webhook signing secret for account-level webhooks (starts with `whsec_`). */
         account_webhook_secret: string;
+        /**
+         * Webhook signing secret for Stripe Connect webhooks (if you use Connect).
+         * If omitted, Connect webhooks are treated as disabled/unverified.
+         */
         connect_webhook_secret?: string;
     };
-    catalog: {
-        products: default_2.ProductCreateParams[];
-        prices: default_2.PriceCreateParams[];
-        behavior: {
-            onExisting: "update" | "archive_and_recreate" | "skip" | "error";
-            onMissingKey: "create" | "error";
+    sync: {
+        catalog?: {
+            /** Products to ensure exist in Stripe (optional bootstrap). */
+            products?: default_2.ProductCreateParams[];
+            /** Prices to ensure exist in Stripe (optional bootstrap). */
+            prices?: default_2.PriceCreateParams[];
+            behavior?: {
+                /**
+                 * What to do if a product/price already exists in Stripe.
+                 * - update: update fields
+                 * - archive_and_recreate: archive and create a new object
+                 * - skip: leave as-is
+                 * - error: throw
+                 */
+                onExisting?: "update" | "archive_and_recreate" | "skip" | "error";
+                /**
+                 * What to do if the "metadata key" is missing on an object.
+                 * - create: create it
+                 * - error: throw
+                 */
+                onMissingKey?: "create" | "error";
+            };
+            /**
+             * Metadata field used to match local definitions to Stripe objects.
+             * Example: "app_internal_key"
+             */
+            metadataKey?: string;
         };
-        metadataKey: string;
-    };
-    webhook: {
-        metadata: Record<string, string>;
-        description: string;
-        path: string;
+        webhooks?: {
+            account: {
+                /** Metadata applied when creating/updating the Stripe webhook endpoint. */
+                metadata?: Record<string, string>;
+                /** Description used for the Stripe webhook endpoint. */
+                description?: string;
+                /** Override the default path (otherwise your code uses `/stripe/webhook`). */
+                path?: string;
+            };
+            connect: {
+                metadata?: Record<string, string>;
+                description?: string;
+                path?: string;
+            };
+        };
+        /** 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>;
     };
-    portal: default_2.BillingPortal.ConfigurationCreateParams;
-    callback?: {
-        unstable__afterChange?: CallbackAfterChange;
+    callbacks?: {
+        /** Called after a row is inserted/upserted/deleted in your Stripe tables. */
+        afterChange?: CallbackAfterChange;
     };
-    detached: boolean;
-    sync: Partial<Record<keyof typeof stripeTables, boolean>>;
-    redirectTtlMs: number;
+    /**
+     * If true, avoids attaching routes/state globally (depends on your library meaning).
+     * Document your intended behavior here.
+     */
+    detached?: boolean;
+    /** TTL for redirect state (ms). */
+    redirectTtlMs?: number;
 }
 
+export declare type InputOptions = Partial<InternalOptions>;
+
+export declare type InternalConfiguration = RecursiveDeepRequired<InputConfiguration>;
+
+/**
+ * Initializes the Convex Stripe integration.
+ *
+ * Returns a set of utilities to wire up HTTP routes, trigger Stripe actions,
+ * and keep your Convex database in sync with Stripe events.
+ *
+ * @param configuration_ - Your Stripe and sync configuration.
+ * @param options_ - Optional internal options (logger, debug mode, etc.).
+ *
+ * @example
+ * export const { stripe, store, sync } = internalConvexStripe({
+ *   stripe: {
+ *     secret_key: process.env.STRIPE_SECRET_KEY!,
+ *     account_webhook_secret: process.env.STRIPE_WHSEC!,
+ *   },
+ *   sync: {
+ *     tables: { customers: true, subscriptions: true },
+ *   },
+ * });
+ */
 export declare const internalConvexStripe: (configuration_: InputConfiguration, options_?: InputOptions) => {
     stripe: {
+        /** Raw HTTP handler descriptors. Prefer `addHttpRoutes` unless you need manual control. */
         http: {
             webhook: {
                 path: string;
@@ -196,12 +263,62 @@ export declare const internalConvexStripe: (configuration_: InputConfiguration,
                 readonly handler: (context: GenericActionCtx<GenericDataModel>, request: Request) => Promise<Response>;
             };
         };
+        /** A pre-configured Stripe SDK client using your `secret_key` and `version`. */
         client: default_2;
+        /**
+         * Registers the Stripe webhook and redirect routes on your Convex `HttpRouter`.
+         * Call this inside your `convex/http.ts` file.
+         *
+         * - `POST /stripe/webhook`  receives and verifies Stripe webhook events.
+         * - `GET  /stripe/return/*`  handles post-payment/portal redirect flows.
+         *
+         * @param http - Your Convex `HttpRouter` instance.
+         * @param config - Optional config override (defaults to the root configuration).
+         *
+         * @example
+         * // convex/http.ts
+         * import { httpRouter } from "convex/server";
+         * import { stripe } from "./stripe";
+         *
+         * const http = httpRouter();
+         * stripe.addHttpRoutes(http);
+         * export default http;
+         */
         addHttpRoutes: (http: HttpRouter, config?: InputConfiguration) => void;
+        /**
+         * Opens a Stripe Billing Portal session for an existing customer.
+         * Use this to let users manage their subscription, invoices, and payment methods.
+         *
+         * @param context - The Convex action context.
+         * @param args - Customer identifier and return URL.
+         * @param options - Optional overrides (e.g. portal configuration ID).
+         */
         portal: (context: GenericActionCtx<any>, args: Parameters<(typeof PortalImplementation)["handler"]>[1], options?: Parameters<(typeof PortalImplementation)["handler"]>[2]) => Promise<default_2.Response<default_2.BillingPortal.Session>>;
+        /**
+         * Creates a Stripe Checkout session in `subscription` mode.
+         * Redirects the user to Stripe Checkout to set up a recurring subscription.
+         *
+         * @param context - The Convex action context.
+         * @param args - Price ID, customer info, and success/cancel URLs.
+         * @param options - Optional overrides for the Checkout session.
+         */
         subscribe: (context: GenericActionCtx<any>, args: Parameters<(typeof SubscribeImplementation)["handler"]>[1], options?: Parameters<(typeof SubscribeImplementation)["handler"]>[2]) => Promise<default_2.Response<default_2.Checkout.Session>>;
+        /**
+         * Creates a Stripe Checkout session in `payment` mode (one-time payment).
+         *
+         * @param context - The Convex action context.
+         * @param args - Price ID, quantity, and success/cancel URLs.
+         * @param options - Optional overrides for the Checkout session.
+         */
         pay: (context: GenericActionCtx<any>, args: Parameters<(typeof PayImplementation)["handler"]>[1], options?: Parameters<(typeof PayImplementation)["handler"]>[2]) => Promise<default_2.Response<default_2.Checkout.Session>>;
         customers: {
+            /**
+             * Creates a new Stripe Customer and stores it in your Convex database.
+             *
+             * @param context - The Convex action context.
+             * @param args - Customer details (email, name, metadata, etc.).
+             * @param options - Optional overrides for the customer creation.
+             */
             create: (context: GenericActionCtx<any>, args: Parameters<(typeof CreateCustomerImplementation)["handler"]>[1], options?: Parameters<(typeof CreateCustomerImplementation)["handler"]>[2]) => Promise<{
                 _id: GenericId<"stripeCustomers">;
                 _creationTime: number;
@@ -270,6 +387,14 @@ export declare const internalConvexStripe: (configuration_: InputConfiguration,
             }>;
         };
         accounts: {
+            /**
+             * Creates a new Stripe Connect account (Express or Custom).
+             * Use this to onboard sellers, platforms, or service providers.
+             *
+             * @param context - The Convex action context.
+             * @param args - Account type, email, and capabilities.
+             * @param options - Optional overrides for the account creation.
+             */
             create: (context: GenericActionCtx<any>, args: Parameters<(typeof CreateAccountImplementation)["handler"]>[1], options?: Parameters<(typeof CreateAccountImplementation)["handler"]>[2]) => Promise<{
                 _id: GenericId<"stripeAccounts">;
                 _creationTime: number;
@@ -302,9 +427,21 @@ export declare const internalConvexStripe: (configuration_: InputConfiguration,
                 accountId: string;
                 lastSyncedAt: number;
             }>;
+            /**
+             * Creates a Stripe Connect Account Link for onboarding.
+             * Redirects the connected account holder to Stripe's hosted onboarding flow.
+             *
+             * @param context - The Convex action context.
+             * @param args - Account ID, refresh URL, and return URL.
+             * @param options - Optional overrides for the account link.
+             */
             link: (context: GenericActionCtx<any>, args: Parameters<(typeof CreateAccountLinkImplementation)["handler"]>[1], options?: Parameters<(typeof CreateAccountLinkImplementation)["handler"]>[2]) => Promise<default_2.Response<default_2.AccountLink>>;
         };
     };
+    /**
+     * Internal Convex mutation that persists a Stripe object into your database.
+     * Typically called from within the webhook handler  not meant for direct use.
+     */
     store: RegisteredMutation<"internal", {
     id?: any;
     value?: any;
@@ -1434,14 +1571,19 @@ export declare const internalConvexStripe: (configuration_: InputConfiguration,
     deleted?: undefined;
     doc?: undefined;
     } | undefined>>;
+    /**
+     * Internal Convex action that syncs Stripe catalog data (products, prices,
+     * webhooks, portal config) into Stripe based on your `sync` configuration.
+     * Run this manually or on deploy to keep Stripe in sync with your config.
+     */
     sync: RegisteredAction<"internal", {
-    portal?: boolean | undefined;
     webhooks?: {
     account?: boolean | undefined;
     connect?: boolean | undefined;
     } | undefined;
+    portal?: boolean | undefined;
     unstable_catalog?: boolean | undefined;
-    data: boolean | {
+    tables: boolean | {
     withConnect?: boolean | undefined;
     };
     }, Promise<void>>;
@@ -1486,6 +1628,10 @@ 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>>;
 };
 
+declare type RecursiveDeepRequired<T> = T extends (...args: any[]) => any ? T : T extends object ? {
+    [K in keyof T]-?: RecursiveDeepRequired<T[K]>;
+} : T;
+
 declare type StripeDataModel = DataModelFromSchemaDefinition<typeof stripeSchema>;
 
 declare const stripeSchema: SchemaDefinition<    {
@@ -8857,6 +9003,10 @@ declare const SubscribeImplementation: {
     } & Omit<default_2.Checkout.SessionCreateParams, "mode" | "customer" | "client_reference_id" | "line_items" | "success_url" | "ui_mode" | "cancel_url">, stripeOptions: default_2.RequestOptions, configuration: InternalConfiguration, options: InternalOptions) => Promise<default_2.Response<default_2.Checkout.Session>>;
 };
 
-declare type WithOptional<T, K extends keyof T = never> = Omit<T, K> & Partial<Pick<T, K>>;
+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 { }