sanity-plugin-stripe 0.1.1 → 0.2.0

package/dist/server.d.ts

@@ -1,11 +1,11 @@
 /**
- * `sanity-plugin-stripe/server`: the site's checkout route and Stripe webhook. Web `Request` and
- * `Response` only, so the handlers fit Next.js, Remix, Astro, SvelteKit or Hono. It imports
- * neither Sanity nor React.
+ * `sanity-plugin-stripe/server`: the site's checkout route, Stripe webhook and customer portal
+ * route. Web `Request` and `Response` only, so the handlers fit Next.js, Remix, Astro, SvelteKit
+ * or Hono. It imports neither Sanity nor React.
  */
-import { a as CartVariant, f as readCartProducts, n as CartLine, o as CheckoutProblem, r as CartProduct, t as Availability } from "./cart-D2KxuwQz.js";
-import { a as regionOptions, i as readShopSettings, n as ShippingRegion, o as formatMoney, r as ShopSettings, s as formatPrice, t as RegionOption } from "./regions-DbCIM0I1.js";
+import { C as readSubscription, S as readCartProducts, a as SubscriptionDelivery, b as describeInterval, c as shippingQuote, d as CartProduct, h as Interval, i as ShopSettings, l as Availability, m as CheckoutProblem, n as ShippingQuote, o as readShopSettings, p as CartVariant, r as ShippingRegion, s as regionOptions, t as RegionOption, u as CartLine } from "./regions-Bfhg4QDs.js";
 import { t as EU_COUNTRIES } from "./countries-BSdN9FCR.js";
+import { n as formatPrice, t as formatMoney } from "./money-XMQaHsbV.js";
 import Stripe$1, { Stripe } from "stripe";
 interface OrderItem {
   /** Sanity document id of the product. */
@@ -15,11 +15,25 @@ interface OrderItem {
   quantity: number;
   /** For the whole line, in the currency's minor unit (cents). */
   amountTotal: number;
+  /** True on a line that is a subscription: it is delivered and charged again. */
+  subscription?: boolean;
 }
-/** A paid Checkout Session, read into what a shop needs to send it. It is never saved in Sanity. */
+/**
+ * A paid order, read into what a shop needs to send it: a paid Checkout Session, or a renewal of
+ * a subscription that one started. It is never saved in Sanity.
+ */
 interface Order {
+  /** The Checkout Session that took the order. For a renewal, the one that started the subscription. */
   sessionId: string;
   paymentIntentId: string | null;
+  /** Set on a renewal: the invoice Stripe charged for it. */
+  invoiceId?: string;
+  /** Set when the order started a subscription, and on each of its renewals. */
+  subscription?: {
+    id: string;
+    /** Null when Stripe holds an interval the plugin doesn't offer, such as days. */
+    interval: Interval | null;
+  };
   /** False for a payment made in a sandbox or in test mode. */
   livemode: boolean;
   currency: string;
@@ -63,8 +77,8 @@ interface ProductQueryOptions {
 export declare function cartProductProjection(options?: ProductQueryOptions): string;
 /** Every product that has the commerce field filled in, for the cart page. */
 export declare function cartProductsQuery(options?: ProductQueryOptions): string;
-/** The shop settings: shipping regions and whether stock sells out by itself. */
-export declare const SHOP_SETTINGS_QUERY = "*[_type == \"stripeShopSettings\" && _id == \"stripeShopSettings\"][0]{shippingRegions[]{_key, title, everywhereElse, countries, rate}, autoSoldOut}";
+/** The shop settings: shipping regions, selling out at 0, and delivery for subscriptions. */
+export declare const SHOP_SETTINGS_QUERY = "*[_type == \"stripeShopSettings\" && _id == \"stripeShopSettings\"][0]{shippingRegions[]{_key, title, everywhereElse, countries, rate, freeFrom}, autoSoldOut, subscriptionDelivery}";
 /** A product's stock, as its private stock document holds it. */
 interface ProductStock {
   /** For a product without variants. Null when it isn't counted. */
@@ -127,8 +141,8 @@ interface StockChange {
   /** Below 0 when more was sold than was in stock. */
   to: number;
 }
-/** Where the payment is in the Stripe Dashboard. */
-export declare function dashboardUrl(order: Pick<Order, 'livemode' | 'paymentIntentId' | 'sessionId'>): string;
+/** Where the payment is in the Stripe Dashboard: a renewal's invoice, a subscription, a payment. */
+export declare function dashboardUrl(order: Pick<Order, 'livemode' | 'paymentIntentId' | 'sessionId' | 'invoiceId' | 'subscription'>): string;
 interface OrderEmailOptions {
   /** Starts the subject line. */
   shopName: string;
@@ -144,10 +158,16 @@ interface OrderEmail {
   text: string;
   html: string;
 }
-/** A plain order email for the shop: what to pack, where to send it and who paid. */
+/**
+ * A plain order email for the shop: what to pack, where to send it and who paid. It serves a
+ * subscription's renewal too, from `onRenewal`.
+ */
 export declare function orderEmail(order: Order, options: OrderEmailOptions): OrderEmail;
-/** The events a webhook endpoint for the shop listens to. */
-export declare const WEBHOOK_EVENTS: readonly ["checkout.session.completed", "checkout.session.async_payment_succeeded", "checkout.session.async_payment_failed"];
+/**
+ * The events a webhook endpoint for the shop listens to. The last three are for subscriptions; a
+ * shop without any can leave them out.
+ */
+export declare const WEBHOOK_EVENTS: readonly ["checkout.session.completed", "checkout.session.async_payment_succeeded", "checkout.session.async_payment_failed", "invoice.paid", "invoice.payment_failed", "customer.subscription.deleted"];
 type Handler = (request: Request) => Promise<Response>;
 type Log = (level: 'info' | 'warn' | 'error', message: string) => void;
 interface CheckoutMessages {
@@ -199,7 +219,12 @@ interface CheckoutRouteOptions {
   hideRemaining?: boolean;
   /** Minutes until an unpaid session expires, about 30 at least. Stripe's default is 24 hours. */
   expiresInMinutes?: number;
-  /** Changes the session before it is created: promotion codes, phone numbers, consent. */
+  /**
+   * Shows a field for a promotion code on Stripe's page. Codes are made in the Stripe Dashboard,
+   * one per checkout. On a subscription, the code's coupon says whether renewals are discounted.
+   */
+  promotionCodes?: boolean;
+  /** Changes the session before it is created: phone numbers, consent, a customer. */
   extend?: (params: Stripe$1.Checkout.SessionCreateParams, context: {
     lines: CartLine[];
     region: ShippingRegion;
@@ -213,7 +238,9 @@ interface CheckoutRouteOptions {
 }
 /**
  * The site's checkout route. The browser posts the cart's product references and the chosen
- * shipping region; prices, stock and shipping are read fresh from Sanity here.
+ * shipping region; prices, stock and shipping are read fresh from Sanity here. A cart with a
+ * subscription in it becomes a subscription checkout; anything bought once in the same cart is
+ * charged with the first payment.
  *
  * ```ts
  * // app/api/checkout/route.ts
@@ -233,6 +260,16 @@ interface OrderContext {
    * Stripe is asked to deliver the event again, and only the stock is tried again.
    */
   stockError?: string;
+  /** The Checkout Session that took the order. */
+  session: Stripe$1.Checkout.Session;
+  stripe: Stripe$1;
+}
+interface RenewalContext extends OrderContext {
+  /** The paid invoice. `session` is the Checkout Session that started the subscription. */
+  invoice: Stripe$1.Invoice;
+}
+interface SubscriptionContext {
+  /** The Checkout Session that started the subscription. */
   session: Stripe$1.Checkout.Session;
   stripe: Stripe$1;
 }
@@ -259,13 +296,33 @@ interface WebhookRouteOptions {
   onOrder?: (order: Order, context: OrderContext) => void | Promise<void>;
   /** Called when a delayed payment (a bank transfer, for one) fails. Nothing was fulfilled. */
   onPaymentFailed?: (session: Stripe$1.Checkout.Session) => void | Promise<void>;
+  /**
+   * Called once for each paid renewal of a subscription, after stock is lowered: there is a
+   * parcel to send again. The order's address is the customer's as it is now. The first payment
+   * of a subscription is not a renewal: it reaches `onOrder`.
+   */
+  onRenewal?: (order: Order, context: RenewalContext) => void | Promise<void>;
+  /**
+   * Called when a renewal's payment fails. Stripe tries again and writes to the customer by
+   * itself, so there is nothing that has to be done here. It can be called more than once.
+   */
+  onRenewalFailed?: (invoice: Stripe$1.Invoice, context: SubscriptionContext) => void | Promise<void>;
+  /** Called when a subscription ends: cancelled, or given up on after failed payments. */
+  onSubscriptionEnded?: (subscription: Stripe$1.Subscription, context: SubscriptionContext) => void | Promise<void>;
+  /**
+   * Called for every other event the endpoint receives, once its signature is checked: a
+   * dispute, a refund. These are not sorted by shop: they are the Stripe account's.
+   */
+  onEvent?: (event: Stripe$1.Event, context: {
+    stripe: Stripe$1;
+  }) => void | Promise<void>;
   log?: Log;
 }
 /**
  * The site's Stripe webhook. A paid order of this shop lowers stock and calls `onOrder`, each
- * once per payment however often Stripe delivers the event. Payments made any other way on the
- * same Stripe account (a Payment Link, another site) are left alone. Nothing is fulfilled on the
- * thank-you page.
+ * once per payment however often Stripe delivers the event. A paid renewal of a subscription
+ * does the same and calls `onRenewal`. Payments made any other way on the same Stripe account (a
+ * Payment Link, another site) are left alone. Nothing is fulfilled on the thank-you page.
  *
  * ```ts
  * // app/api/stripe/webhook/route.ts
@@ -275,6 +332,27 @@ interface WebhookRouteOptions {
  * Point a Stripe webhook endpoint at it with the events in `WEBHOOK_EVENTS`.
  */
 export declare function webhookRoute(options: WebhookRouteOptions): Handler;
+interface PortalRouteOptions {
+  /** From `createStripe`. */
+  stripe: Stripe$1 | null | undefined;
+  /** What a visitor reads when the portal can't be opened. */
+  message?: string;
+  log?: Log;
+}
+/**
+ * Sends a visitor to Stripe's customer portal, where a subscriber changes their card or address,
+ * pauses or cancels, and finds their invoices. There are no accounts to build: the visitor types
+ * their email on Stripe's page and Stripe emails them a link in.
+ *
+ * ```ts
+ * // app/account/route.ts
+ * export const GET = portalRoute({stripe})
+ * ```
+ *
+ * Switch the portal's login link on once, in the Stripe Dashboard under Settings, Billing,
+ * Customer portal, and choose there what subscribers may change.
+ */
+export declare function portalRoute(options: PortalRouteOptions): () => Promise<Response>;
 /** The Stripe API version the plugin is written and tested against (stripe-node 23). */
 export declare const STRIPE_API_VERSION = "2026-10-28.endive";
 /**
@@ -289,4 +367,4 @@ export declare const STRIPE_API_VERSION = "2026-10-28.endive";
  * stripe-node's options, such as `maxNetworkRetries` or `httpClient`.
  */
 export declare function createStripe(secretKey: string, config?: Omit<Stripe.StripeConfig, 'apiVersion' | 'appInfo'>): Stripe;
-export { type Availability, type CartLine, type CartProduct, type CartVariant, type CheckoutMessages, type CheckoutProblem, type CheckoutRouteOptions, EU_COUNTRIES, type Order, type OrderContext, type OrderEmail, type OrderEmailOptions, type OrderItem, type ProductQueryOptions, type ProductStock, type RegionOption, type SanityReader, type SanityTransaction, type SanityWriter, type ShippingRegion, type ShopSettings, type StockChange, type WebhookRouteOptions, formatMoney, formatPrice, readCartProducts, readShopSettings, regionOptions };
+export { type Availability, type CartLine, type CartProduct, type CartVariant, type CheckoutMessages, type CheckoutProblem, type CheckoutRouteOptions, EU_COUNTRIES, type Interval, type Order, type OrderContext, type OrderEmail, type OrderEmailOptions, type OrderItem, type PortalRouteOptions, type ProductQueryOptions, type ProductStock, type RegionOption, type RenewalContext, type SanityReader, type SanityTransaction, type SanityWriter, type ShippingQuote, type ShippingRegion, type ShopSettings, type StockChange, type SubscriptionContext, type SubscriptionDelivery, type WebhookRouteOptions, describeInterval, formatMoney, formatPrice, readCartProducts, readShopSettings, readSubscription, regionOptions, shippingQuote };