@raideno/convex-stripe 0.2.3 → 0.2.5

package/dist/index.d.ts

@@ -5,11 +5,13 @@ import { GenericDataModel } from 'convex/server';
 import { GenericId } from 'convex/values';
 import { GenericMutationCtx } from 'convex/server';
 import { HttpRouter } from 'convex/server';
+import { Infer } from 'convex/values';
 import { RegisteredAction } from 'convex/server';
 import { RegisteredMutation } from 'convex/server';
 import { RoutableMethod } from 'convex/server';
 import { SchemaDefinition } from 'convex/server';
 import { TableDefinition } from 'convex/server';
+import { Validator } from 'convex/values';
 import { VAny } from 'convex/values';
 import { VArray } from 'convex/values';
 import { VBoolean } from 'convex/values';
@@ -21,6 +23,18 @@ import { VRecord } from 'convex/values';
 import { VString } from 'convex/values';
 import { VUnion } from 'convex/values';
 
+declare type AllRedirectHandlers = (typeof REDIRECT_HANDLERS)[number];
+
+declare type ArgSchema = Record<string, Validator<any, "optional" | "required", any>>;
+
+export declare function buildSignedReturnUrl<O extends ReturnOrigin>({ configuration, origin, failureUrl, targetUrl, data, }: {
+    configuration: InternalConfiguration;
+    origin: O;
+    failureUrl?: string;
+    targetUrl: string;
+    data: ReturnDataMap[O];
+}): Promise<string>;
+
 export declare type CallbackAfterChange = (context: GenericMutationCtx<any>, operation: "upsert" | "delete" | "insert", event: CallbackEvent) => Promise<void>;
 
 export declare type CallbackEvent = {
@@ -149,27 +163,63 @@ declare const CreateCustomerImplementation: {
     }>;
 };
 
+export declare function defineRedirectHandler<const T extends readonly string[], S extends ArgSchema = {}>(handler: RedirectHandler<T, S>): RedirectHandler<T, S>;
+
+declare type InferArgs<S extends ArgSchema> = {
+    [K in keyof S as S[K] extends Validator<any, "required", any> ? K : never]: Infer<S[K]>;
+} & {
+    [K in keyof S as S[K] extends Validator<any, "optional", any> ? K : never]?: Infer<S[K]>;
+};
+
 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,22 +228,55 @@ 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;
-    redirectTtlMs?: number;
+    redirect?: {
+        /** TTL for redirect state (ms). */
+        ttlMs?: number;
+        /** Additional handlers for redirect-based flows (e.g. Checkout, OAuth). */
+        handlers?: Array<ReturnType<typeof defineRedirectHandler>>;
+    };
 }
 
 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 +289,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 +413,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,15 +453,27 @@ 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;
+    data?: any;
     indexName?: string | undefined;
     idField?: string | undefined;
-    data?: any;
     idValue?: any;
     field?: string | undefined;
     operation: string;
@@ -1444,6 +1597,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;
@@ -1500,6 +1658,22 @@ declare type RecursiveDeepRequired<T> = T extends (...args: any[]) => any ? T :
     [K in keyof T]-?: RecursiveDeepRequired<T[K]>;
 } : T;
 
+declare const REDIRECT_HANDLERS: RedirectHandler<readonly string[], ArgSchema>[];
+
+export declare type RedirectHandler<TOrigins extends readonly string[], S extends ArgSchema = {}> = {
+    origins: TOrigins;
+    data?: S;
+    handle: (origin: TOrigins[number], context: GenericActionCtx<StripeDataModel>, data: InferArgs<S>, configuration: InternalConfiguration, options: InternalOptions) => Promise<void>;
+};
+
+declare const RETURN_ORIGINS: string[];
+
+declare type ReturnDataMap = {
+    [H in AllRedirectHandlers as H["origins"][number]]: H extends RedirectHandler<any, infer S> ? InferArgs<S> : never;
+};
+
+declare type ReturnOrigin = (typeof RETURN_ORIGINS)[number];
+
 declare type StripeDataModel = DataModelFromSchemaDefinition<typeof stripeSchema>;
 
 declare const stripeSchema: SchemaDefinition<    {

package/dist/server.js

@@ -5628,7 +5628,10 @@ const DEFAULT_CONFIGURATION = {
     account_webhook_secret: "",
     connect_webhook_secret: ""
   },
-  redirectTtlMs: 15 * 60 * 1e3,
+  redirect: {
+    ttlMs: 15 * 60 * 1e3,
+    handlers: []
+  },
   detached: false,
   callbacks: {
     afterChange: async () => {
@@ -6322,7 +6325,7 @@ async function buildSignedReturnUrl({
     data,
     targetUrl,
     failureUrl,
-    exp: Date.now() + configuration.redirectTtlMs
+    exp: Date.now() + configuration.redirect.ttlMs
   };
   const data_ = toBase64Url(JSON.stringify(payload));
   const expected = await signData(
@@ -6365,10 +6368,11 @@ REDIRECT_HANDLERS.map(
   (handler) => handler.origins
 ).flat();
 const redirectImplementation = async (configuration, options, context, request) => {
+  const handlers = [...REDIRECT_HANDLERS, ...configuration.redirect.handlers];
   const url = new URL(request.url);
   const segments = url.pathname.split("/").filter(Boolean);
   const origin_ = segments[segments.length - 1];
-  if (!origin_ || !REDIRECT_HANDLERS.map((handler) => handler.origins).flat().includes(origin_)) {
+  if (!origin_ || !handlers.map((handler) => handler.origins).flat().includes(origin_)) {
     return new Response("Invalid return origin", { status: 400 });
   }
   const origin = origin_;
@@ -6419,7 +6423,7 @@ const redirectImplementation = async (configuration, options, context, request)
     }
     return new Response("Invalid target", { status: 400 });
   }
-  for (const handler of REDIRECT_HANDLERS) {
+  for (const handler of handlers) {
     if (handler.origins.includes(origin)) {
       try {
         await handler.handle(
@@ -9696,10 +9700,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 +9742,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 +9757,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 +9772,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 +9787,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 +9803,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 +9818,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 +9837,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 +9850,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(
@@ -9788,6 +9868,8 @@ const internalConvexStripe = (configuration_, options_) => {
 };
 export {
   Logger,
+  buildSignedReturnUrl,
+  defineRedirectHandler,
   internalConvexStripe,
   stripeTables,
   syncAllTables,

package/package.json

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