@raideno/convex-stripe 0.2.3 → 0.2.4

package/dist/index.d.ts

@@ -151,25 +151,53 @@ declare const CreateCustomerImplementation: {
 
 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;
     };
     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;
         };
         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: {
@@ -178,13 +206,21 @@ export declare interface InputConfiguration {
                 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>;
     };
     callbacks?: {
+        /** Called after a row is inserted/upserted/deleted in your Stripe tables. */
         afterChange?: CallbackAfterChange;
     };
+    /**
+     * 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;
 }
 
@@ -192,8 +228,29 @@ 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;
@@ -206,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;
@@ -280,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;
@@ -312,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;
@@ -1444,6 +1571,11 @@ 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", {
     webhooks?: {
     account?: boolean | undefined;

package/dist/server.js

@@ -9696,10 +9696,31 @@ const internalConvexStripe = (configuration_, options_) => {
   );
   return {
     stripe: {
+      /** Raw HTTP handler descriptors. Prefer `addHttpRoutes` unless you need manual control. */
       http: http_,
+      /** A pre-configured Stripe SDK client using your `secret_key` and `version`. */
       client: new Stripe(ConvexStripeInternalConfiguration.stripe.secret_key, {
         apiVersion: ConvexStripeInternalConfiguration.stripe.version
       }),
+      /**
+       * 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, config) => {
         config = normalizeConfiguration(config || configuration_);
         http.route({
@@ -9717,6 +9738,14 @@ const internalConvexStripe = (configuration_, options_) => {
           })
         });
       },
+      /**
+       * 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, args, options = {}) => PortalImplementation.handler(
         context,
         args,
@@ -9724,6 +9753,14 @@ const internalConvexStripe = (configuration_, options_) => {
         ConvexStripeInternalConfiguration,
         ConvexStripeInternalOptions
       ),
+      /**
+       * 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, args, options = {}) => SubscribeImplementation.handler(
         context,
         args,
@@ -9731,6 +9768,13 @@ const internalConvexStripe = (configuration_, options_) => {
         ConvexStripeInternalConfiguration,
         ConvexStripeInternalOptions
       ),
+      /**
+       * 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, args, options = {}) => PayImplementation.handler(
         context,
         args,
@@ -9739,6 +9783,13 @@ const internalConvexStripe = (configuration_, options_) => {
         ConvexStripeInternalOptions
       ),
       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, args, options = {}) => CreateCustomerImplementation.handler(
           context,
           args,
@@ -9748,6 +9799,14 @@ const internalConvexStripe = (configuration_, options_) => {
         )
       },
       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, args, options = {}) => CreateAccountImplementation.handler(
           context,
           args,
@@ -9755,6 +9814,14 @@ const internalConvexStripe = (configuration_, options_) => {
           ConvexStripeInternalConfiguration,
           ConvexStripeInternalOptions
         ),
+        /**
+         * 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, args, options = {}) => {
           return CreateAccountLinkImplementation.handler(
             context,
@@ -9766,6 +9833,10 @@ const internalConvexStripe = (configuration_, options_) => {
         }
       }
     },
+    /**
+     * Internal Convex mutation that persists a Stripe object into your database.
+     * Typically called from within the webhook handler  not meant for direct use.
+     */
     store: internalMutationGeneric({
       args: StoreImplementation.args,
       handler: async (context, args) => StoreImplementation.handler(
@@ -9775,6 +9846,11 @@ const internalConvexStripe = (configuration_, options_) => {
         ConvexStripeInternalOptions
       )
     }),
+    /**
+     * 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: internalActionGeneric({
       args: SyncImplementation.args,
       handler: (context, args) => SyncImplementation.handler(

package/package.json

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