@stigmer/react 3.39.1-dev.20260928194002 → 3.40.1

package/billing/plan-features.js

@@ -0,0 +1,128 @@
+// What a plan offers, as the console shows it: which plans are offered and
+// in what order, what each includes, and the formatting of its terms and
+// periods.
+//
+// A plan's features render from its entitlements through the shared
+// vocabulary (../internal/features.ts), never from the plan's stored
+// description: a plan row is immutable once seeded, and the description is
+// free text that can promise a feature before it is built. The console
+// shows only what an organization can use today.
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { PlanInstrument } from "@stigmer/protos/ai/stigmer/billing/plan/v1/spec_pb";
+import { PlanLifecycle } from "@stigmer/protos/ai/stigmer/billing/plan/v1/status_pb";
+import { Feature } from "@stigmer/protos/ai/stigmer/platform/v1/entitlement_pb";
+import { FEATURE_COPY, isNamedFeature } from "../internal/features.js";
+import { formatCreditBalance } from "./format.js";
+// BigInt(0), not a literal: the docs site compiles this source for a
+// target below ES2020, which has no BigInt literal syntax.
+const ZERO = BigInt(0);
+/**
+ * Features a plan may list ahead of the gate that serves them, which
+ * Stigmer Cloud does not offer yet. The console leaves them out of every
+ * comparison. Bring-your-own provider keys leaves this set when the proxy
+ * uses an organization's own key.
+ */
+export const NOT_YET_OFFERED = new Set([Feature.byo_provider_keys]);
+/** The features `entitlements` grant that Cloud offers today, in contract order. */
+export function offeredFeatures(entitlements) {
+    const listed = entitlements?.features ?? [];
+    return [...new Set(listed)]
+        .filter((feature) => isNamedFeature(feature) && !NOT_YET_OFFERED.has(feature))
+        .sort((a, b) => a - b)
+        .map((feature) => ({ feature, ...FEATURE_COPY[feature] }));
+}
+/**
+ * The plans an organization can subscribe to, cheapest monthly minimum
+ * first, so a comparison reads upward from Free; equal minimums keep the
+ * catalog's order. Retired rows and prepaid instruments are left out.
+ */
+export function buyablePlans(plans) {
+    return plans
+        .filter((plan) => plan.spec?.instrument === PlanInstrument.subscription && plan.status?.lifecycle === PlanLifecycle.active)
+        .map((plan, index) => ({ plan, index }))
+        .sort((a, b) => compareMinimums(a.plan, b.plan) || a.index - b.index)
+        .map(({ plan }) => plan);
+}
+/** The cheapest plan that can be bought and includes `feature`, if any. */
+export function lowestPlanWith(plans, feature) {
+    return buyablePlans(plans).find((plan) => offeredFeatures(plan.spec?.entitlements).some((offered) => offered.feature === feature));
+}
+/** What `from` offers that `to` does not: what a switch stops the organization creating. */
+export function featuresLost(from, to) {
+    const kept = new Set(offeredFeatures(to.spec?.entitlements).map((offered) => offered.feature));
+    return offeredFeatures(from?.spec?.entitlements).filter((offered) => !kept.has(offered.feature));
+}
+function compareMinimums(a, b) {
+    const left = a.spec?.terms?.monthlyMinimumMicros ?? ZERO;
+    const right = b.spec?.terms?.monthlyMinimumMicros ?? ZERO;
+    return left === right ? 0 : left < right ? -1 : 1;
+}
+/** A plan's monthly minimum, e.g. "$99.00/month". */
+export function formatMonthlyMinimum(terms) {
+    return `${formatCreditBalance(terms?.monthlyMinimumMicros ?? ZERO)}/month`;
+}
+/**
+ * A plan's usage share as its terms state it, for operators who read terms,
+ * e.g. "or 10% of provider cost, whichever is greater; the commission
+ * already paid on tokens counts toward it". Empty when the plan has no
+ * usage share.
+ */
+export function formatUsageShare(terms) {
+    const percent = sharePercent(terms);
+    return percent === ""
+        ? ""
+        : `or ${percent} of provider cost, whichever is greater; the commission already paid on tokens counts toward it`;
+}
+/**
+ * The same share as a customer reads it: usage stays paid from credits,
+ * and the commission on it counts toward the minimum up to the spend at
+ * which the plan costs nothing extra, e.g. "Usage is still paid from
+ * credits. The 10% commission on it counts toward the minimum, so from
+ * $990.00 a month in provider costs the plan costs nothing extra." Empty
+ * when the plan has no usage share.
+ */
+export function explainUsageShare(terms) {
+    const percent = sharePercent(terms);
+    if (percent === "") {
+        return "";
+    }
+    const basisPoints = BigInt(terms?.usageShareBasisPoints ?? 0);
+    // The provider cost whose share equals the minimum: past it, the share is the plan's cost and the commission pays it.
+    const breakEven = ((terms?.monthlyMinimumMicros ?? ZERO) * BigInt(10_000)) / basisPoints;
+    return (`Usage is still paid from credits. The ${percent} commission on it counts toward the minimum, ` +
+        `so from ${formatCreditBalance(breakEven)} a month in provider costs the plan costs nothing extra.`);
+}
+/** The usage share as a percentage, e.g. "10%" or "12.50%"; empty when there is none. */
+export function sharePercent(terms) {
+    const basisPoints = terms?.usageShareBasisPoints ?? 0;
+    if (basisPoints === 0) {
+        return "";
+    }
+    return `${basisPoints % 100 === 0 ? `${basisPoints / 100}` : (basisPoints / 100).toFixed(2)}%`;
+}
+/** The managed organizations a plan includes and what each beyond costs, or empty. */
+export function formatManagedOrganizations(entitlements, terms) {
+    if (!(entitlements?.features ?? []).includes(Feature.managed_organizations)) {
+        return "";
+    }
+    const included = entitlements?.limits?.includedManagedOrganizations;
+    const fee = terms?.perExtraOrganizationMicros ?? ZERO;
+    if (included === undefined) {
+        return "Unlimited managed organizations";
+    }
+    const beyond = fee > ZERO ? `, then ${formatCreditBalance(fee)}/month each` : "";
+    return `${included} managed organization${included === 1 ? "" : "s"} included${beyond}`;
+}
+const DAY = new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", year: "numeric", timeZone: "UTC" });
+/**
+ * A period boundary as a UTC calendar day, e.g. "Feb 28, 2027". Periods
+ * run anniversary to anniversary in UTC, the rule the invoice follows.
+ */
+export function formatPeriodDay(timestamp) {
+    return timestamp === undefined ? "" : formatDay(timestampDate(timestamp));
+}
+/** An instant as its UTC calendar day, the way {@link formatPeriodDay} shows a period boundary. */
+export function formatDay(date) {
+    return DAY.format(date);
+}
+//# sourceMappingURL=plan-features.js.map

package/billing/plan-features.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-features.js","sourceRoot":"","sources":["../src/billing/plan-features.ts"],"names":[],"mappings":"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"}

package/billing/plan-state.d.ts

@@ -0,0 +1,43 @@
+import type { Plan } from "@stigmer/protos/ai/stigmer/billing/plan/v1/api_pb";
+import type { Subscription } from "@stigmer/protos/ai/stigmer/billing/subscription/v1/api_pb";
+/** An organization's standing on its plan. */
+export type PlanStanding = {
+    readonly kind: "free";
+} | {
+    readonly kind: "active";
+    readonly planId: string;
+} | {
+    readonly kind: "past-due";
+    readonly planId: string;
+} | {
+    readonly kind: "ending";
+    readonly planId: string;
+    readonly endsAt: Date;
+};
+/** What choosing a plan (or Free) would do. */
+export type PlanMove = {
+    readonly kind: "subscribe";
+    readonly to: Plan;
+} | {
+    readonly kind: "switch";
+    readonly fromPlanId: string;
+    readonly to: Plan;
+} | {
+    readonly kind: "resume";
+    readonly to: Plan;
+} | {
+    readonly kind: "cancel";
+    readonly fromPlanId: string;
+    readonly endsAt: Date;
+};
+/**
+ * The standing a stored subscription gives at `now`: the engine's live
+ * rule (active, past due, or canceled but not yet at its period's end),
+ * else Free. `null` (never subscribed) is Free.
+ */
+export declare function planStanding(subscription: Subscription | null, now: Date): PlanStanding;
+/** The move choosing `target` (a plan, or `"free"`) makes from `standing`, or `null` for none. */
+export declare function planMove(standing: PlanStanding, target: Plan | "free", periodEnd: Date | undefined): PlanMove | null;
+/** The plan id in force for `standing`, or empty on Free. */
+export declare function standingPlanId(standing: PlanStanding): string;
+//# sourceMappingURL=plan-state.d.ts.map

package/billing/plan-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-state.d.ts","sourceRoot":"","sources":["../src/billing/plan-state.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mDAAmD,CAAC;AAC9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2DAA2D,CAAC;AAG9F,8CAA8C;AAC9C,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;CAAE,CAAC;AAEhF,+CAA+C;AAC/C,MAAM,MAAM,QAAQ,GAChB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;CAAE,CAAC;AAEpF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,YAAY,CAiBvF;AAED,kGAAkG;AAClG,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,IAAI,GAAG,MAAM,EACrB,SAAS,EAAE,IAAI,GAAG,SAAS,GAC1B,QAAQ,GAAG,IAAI,CAuBjB;AAED,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAE7D"}

package/billing/plan-state.js

@@ -0,0 +1,69 @@
+// Where an organization stands on its plan, and what choosing a plan
+// would do, decided the way the server decides it (the subscription
+// engine's moves), so the confirm step states the move the server makes.
+//
+//   subscribe  no live plan: a monthly period opens now on the plan
+//   switch     a live plan, another chosen: this period closes early,
+//              billed for the time it ran, and a new one opens now
+//   resume     the plan being canceled, chosen again: the cancel is
+//              withdrawn and the period runs on
+//   cancel     Free chosen on a live plan: the plan runs to its period's
+//              end, then the organization is on Free
+//
+// Choosing the plan already in force, or Free while on Free or already
+// canceling, is no move at all.
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { SubscriptionState } from "@stigmer/protos/ai/stigmer/billing/subscription/v1/status_pb";
+/**
+ * The standing a stored subscription gives at `now`: the engine's live
+ * rule (active, past due, or canceled but not yet at its period's end),
+ * else Free. `null` (never subscribed) is Free.
+ */
+export function planStanding(subscription, now) {
+    const status = subscription?.status;
+    const planId = subscription?.spec?.planId ?? "";
+    switch (status?.state) {
+        case SubscriptionState.active:
+            return { kind: "active", planId };
+        case SubscriptionState.past_due:
+            return { kind: "past-due", planId };
+        case SubscriptionState.canceled: {
+            const end = status.currentPeriodEnd === undefined ? undefined : timestampDate(status.currentPeriodEnd);
+            return end !== undefined && now.getTime() < end.getTime()
+                ? { kind: "ending", planId, endsAt: end }
+                : { kind: "free" };
+        }
+        default:
+            return { kind: "free" };
+    }
+}
+/** The move choosing `target` (a plan, or `"free"`) makes from `standing`, or `null` for none. */
+export function planMove(standing, target, periodEnd) {
+    if (target === "free") {
+        if (standing.kind === "active" || standing.kind === "past-due") {
+            return periodEnd === undefined ? null : { kind: "cancel", fromPlanId: standing.planId, endsAt: periodEnd };
+        }
+        return null;
+    }
+    const targetId = target.metadata?.id ?? "";
+    switch (standing.kind) {
+        case "free":
+            return { kind: "subscribe", to: target };
+        case "ending":
+            return targetId === standing.planId
+                ? { kind: "resume", to: target }
+                : { kind: "switch", fromPlanId: standing.planId, to: target };
+        case "active":
+        case "past-due":
+            return targetId === standing.planId ? null : { kind: "switch", fromPlanId: standing.planId, to: target };
+        default: {
+            const exhaustive = standing;
+            throw new Error(`unknown plan standing ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+/** The plan id in force for `standing`, or empty on Free. */
+export function standingPlanId(standing) {
+    return standing.kind === "free" ? "" : standing.planId;
+}
+//# sourceMappingURL=plan-state.js.map

package/billing/plan-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-state.js","sourceRoot":"","sources":["../src/billing/plan-state.ts"],"names":[],"mappings":"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"}

package/billing/redirect.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Where a billing flow leaves the app for a Stripe-hosted page, and where
+ * Stripe sends the person back.
+ *
+ * By default the console navigates its own window to Stripe and Stripe
+ * returns to the host's billing page on the same origin: right for a web
+ * console. A host whose window cannot host a third-party page, such as a
+ * desktop webview whose origin is not a web address Stripe can return to,
+ * passes a {@link BillingRedirect}: `openUrl` opens the page elsewhere
+ * (the system browser), and `returnUrl` names a real web page for Stripe
+ * to return to. The person finishes there; the host's reads refresh when
+ * its window regains focus, because the state lives on the server.
+ */
+/** The host's seam for leaving the app to a Stripe-hosted page. */
+export interface BillingRedirect {
+    /**
+     * Opens a Stripe-hosted page. Absent, the current window navigates to
+     * it. Desktop hosts open the system browser.
+     */
+    readonly openUrl?: (url: string) => void | Promise<void>;
+    /**
+     * The absolute URL of the billing page Stripe returns to, without a
+     * query. Absent, the current origin's `/settings/billing`.
+     */
+    readonly returnUrl?: string;
+}
+/** The billing page Stripe returns to, per the redirect or the current origin. */
+export declare function billingReturnUrl(redirect: BillingRedirect | undefined): string;
+/** Leaves for a Stripe-hosted page through the redirect, or by navigating this window. */
+export declare function leaveForStripe(url: string, redirect: BillingRedirect | undefined): Promise<void>;
+//# sourceMappingURL=redirect.d.ts.map

package/billing/redirect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirect.d.ts","sourceRoot":"","sources":["../src/billing/redirect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,CAM9E;AAED,0FAA0F;AAC1F,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAMtG"}

package/billing/redirect.js

@@ -0,0 +1,30 @@
+/**
+ * Where a billing flow leaves the app for a Stripe-hosted page, and where
+ * Stripe sends the person back.
+ *
+ * By default the console navigates its own window to Stripe and Stripe
+ * returns to the host's billing page on the same origin: right for a web
+ * console. A host whose window cannot host a third-party page, such as a
+ * desktop webview whose origin is not a web address Stripe can return to,
+ * passes a {@link BillingRedirect}: `openUrl` opens the page elsewhere
+ * (the system browser), and `returnUrl` names a real web page for Stripe
+ * to return to. The person finishes there; the host's reads refresh when
+ * its window regains focus, because the state lives on the server.
+ */
+/** The billing page Stripe returns to, per the redirect or the current origin. */
+export function billingReturnUrl(redirect) {
+    if (redirect?.returnUrl !== undefined) {
+        return redirect.returnUrl;
+    }
+    const origin = typeof window === "undefined" ? "" : window.location.origin;
+    return `${origin}/settings/billing`;
+}
+/** Leaves for a Stripe-hosted page through the redirect, or by navigating this window. */
+export async function leaveForStripe(url, redirect) {
+    if (redirect?.openUrl !== undefined) {
+        await redirect.openUrl(url);
+        return;
+    }
+    window.location.href = url;
+}
+//# sourceMappingURL=redirect.js.map

package/billing/redirect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirect.js","sourceRoot":"","sources":["../src/billing/redirect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAgBH,kFAAkF;AAClF,MAAM,UAAU,gBAAgB,CAAC,QAAqC;IACpE,IAAI,QAAQ,EAAE,SAAS,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,QAAQ,CAAC,SAAS,CAAC;IAC5B,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC3E,OAAO,GAAG,MAAM,mBAAmB,CAAC;AACtC,CAAC;AAED,0FAA0F;AAC1F,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAW,EAAE,QAAqC;IACrF,IAAI,QAAQ,EAAE,OAAO,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,OAAO;IACT,CAAC;IACD,MAAM,CAAC,QAAQ,CAAC,IAAI,GAAG,GAAG,CAAC;AAC7B,CAAC"}

package/billing/useBillingAccount.d.ts

@@ -1,4 +1,13 @@
 import type { BillingAccount } from "@stigmer/protos/ai/stigmer/billing/v1/billing_account_pb";
+/** Options for {@link useBillingAccount}. */
+export interface UseBillingAccountOptions {
+    /**
+     * Re-read the account when the window regains focus: for a host that
+     * sends Stripe's pages to another window (the system browser), so a card
+     * saved there shows on return. Default `false`.
+     */
+    readonly refetchOnWindowFocus?: boolean;
+}
 /** Return value of {@link useBillingAccount}. */
 export interface UseBillingAccountReturn {
     /** The billing account, or `null` before the first successful fetch. */
@@ -36,5 +45,5 @@ export interface UseBillingAccountReturn {
  * return <div>Balance: {formatCreditBalance(account.balance?.availableMicros)}</div>;
  * ```
  */
-export declare function useBillingAccount(orgId: string | null): UseBillingAccountReturn;
+export declare function useBillingAccount(orgId: string | null, options?: UseBillingAccountOptions): UseBillingAccountReturn;
 //# sourceMappingURL=useBillingAccount.d.ts.map

package/billing/useBillingAccount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useBillingAccount.d.ts","sourceRoot":"","sources":["../src/billing/useBillingAccount.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0DAA0D,CAAC;AAI/F,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IACxC,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,GAAG,IAAI,GACnB,uBAAuB,CAazB"}
+{"version":3,"file":"useBillingAccount.d.ts","sourceRoot":"","sources":["../src/billing/useBillingAccount.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0DAA0D,CAAC;AAI/F,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAED,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IACxC,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,OAAO,CAAC,EAAE,wBAAwB,GACjC,uBAAuB,CAczB"}

package/billing/useBillingAccount.js

@@ -25,11 +25,11 @@ import { useFetch } from "../internal/useFetch.js";
  * return <div>Balance: {formatCreditBalance(account.balance?.availableMicros)}</div>;
  * ```
  */
-export function useBillingAccount(orgId) {
+export function useBillingAccount(orgId, options) {
     const stigmer = useStigmer();
     const { data: account, isLoading, isRefetching, error, refetch } = useFetch(orgId
         ? () => stigmer.billing.getOrCreateBillingAccount(orgId)
-        : null, [orgId, stigmer], null);
+        : null, [orgId, stigmer], null, { refetchOnWindowFocus: options?.refetchOnWindowFocus ?? false });
     return { account, isLoading, isRefetching, error, refetch };
 }
 //# sourceMappingURL=useBillingAccount.js.map

package/billing/useBillingAccount.js.map

@@ -1 +1 @@
-{"version":3,"file":"useBillingAccount.js","sourceRoot":"","sources":["../src/billing/useBillingAccount.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAOb,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAgBnD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAoB;IAEpB,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAE7B,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,QAAQ,CACzE,KAAK;QACH,CAAC,CAAC,GAAG,EAAE,CACH,OAAO,CAAC,OAAO,CAAC,yBAAyB,CAAC,KAAK,CAAC;QACpD,CAAC,CAAC,IAAI,EACR,CAAC,KAAK,EAAE,OAAO,CAAC,EAChB,IAA6B,CAC9B,CAAC;IAEF,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"useBillingAccount.js","sourceRoot":"","sources":["../src/billing/useBillingAccount.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAOb,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AA0BnD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAoB,EACpB,OAAkC;IAElC,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAE7B,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,QAAQ,CACzE,KAAK;QACH,CAAC,CAAC,GAAG,EAAE,CACH,OAAO,CAAC,OAAO,CAAC,yBAAyB,CAAC,KAAK,CAAC;QACpD,CAAC,CAAC,IAAI,EACR,CAAC,KAAK,EAAE,OAAO,CAAC,EAChB,IAA6B,EAC7B,EAAE,oBAAoB,EAAE,OAAO,EAAE,oBAAoB,IAAI,KAAK,EAAE,CACjE,CAAC;IAEF,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC9D,CAAC"}

package/billing/useChangePlan.d.ts

@@ -0,0 +1,51 @@
+import type { Subscription } from "@stigmer/protos/ai/stigmer/billing/subscription/v1/api_pb";
+/** Return value of {@link useChangePlan}. */
+export interface UseChangePlanReturn {
+    /**
+     * Move the organization onto a plan: subscribe (from Free), switch, or
+     * resume a canceled plan by choosing it again. A switch takes effect
+     * now: the current period closes early, billed for the time it ran, and
+     * a new monthly period opens on the new plan. Nothing is charged at the
+     * moment of the change; every period is collected when it closes.
+     *
+     * Refused with the `PAYMENT_METHOD_REQUIRED` reason when the
+     * organization has no saved card (see
+     * {@link useCreatePaymentMethodSetupSession}). Resolves with the
+     * subscription as it stands after the change.
+     */
+    readonly changePlan: (orgId: string, planId: string) => Promise<Subscription>;
+    /** `true` while a change is in flight. */
+    readonly isSubmitting: boolean;
+    /** Error from the last failed attempt, or `null` when healthy. */
+    readonly error: Error | null;
+    /** Reset `error` to `null`. */
+    readonly clearError: () => void;
+}
+/**
+ * Behaviour hook that moves an organization onto a plan.
+ *
+ * The caller needs `can_manage_billing` on the organization (its admins).
+ * Refetch the subscription, entitlements and estimate after a change.
+ */
+export declare function useChangePlan(): UseChangePlanReturn;
+/** Return value of {@link useCancelSubscription}. */
+export interface UseCancelSubscriptionReturn {
+    /**
+     * Cancel the organization's subscription. It keeps its plan to the end
+     * of the current period and is on Free after it; nothing it built is
+     * deleted. Choosing the same plan again before then resumes it.
+     */
+    readonly cancel: (orgId: string) => Promise<Subscription>;
+    /** `true` while a cancel is in flight. */
+    readonly isSubmitting: boolean;
+    /** Error from the last failed attempt, or `null` when healthy. */
+    readonly error: Error | null;
+    /** Reset `error` to `null`. */
+    readonly clearError: () => void;
+}
+/**
+ * Behaviour hook that cancels an organization's subscription at the end
+ * of its period. The caller needs `can_manage_billing` on the organization.
+ */
+export declare function useCancelSubscription(): UseCancelSubscriptionReturn;
+//# sourceMappingURL=useChangePlan.d.ts.map

package/billing/useChangePlan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChangePlan.d.ts","sourceRoot":"","sources":["../src/billing/useChangePlan.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2DAA2D,CAAC;AAQ9F,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9E,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,mBAAmB,CA2BnD;AAED,qDAAqD;AACrD,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC1D,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,2BAA2B,CAwBnE"}

package/billing/useChangePlan.js

@@ -0,0 +1,61 @@
+"use client";
+import { useCallback, useMemo, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { CancelSubscriptionInputSchema, ChangePlanInputSchema, } from "@stigmer/protos/ai/stigmer/billing/subscription/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+/**
+ * Behaviour hook that moves an organization onto a plan.
+ *
+ * The caller needs `can_manage_billing` on the organization (its admins).
+ * Refetch the subscription, entitlements and estimate after a change.
+ */
+export function useChangePlan() {
+    const stigmer = useStigmer();
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [error, setError] = useState(null);
+    const changePlan = useCallback(async (orgId, planId) => {
+        setIsSubmitting(true);
+        setError(null);
+        try {
+            return await stigmer.subscription.changePlan(create(ChangePlanInputSchema, { orgId, planId }));
+        }
+        catch (e) {
+            const err = toError(e);
+            setError(err);
+            throw err;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [stigmer.subscription]);
+    const clearError = useCallback(() => setError(null), []);
+    return useMemo(() => ({ changePlan, isSubmitting, error, clearError }), [changePlan, isSubmitting, error, clearError]);
+}
+/**
+ * Behaviour hook that cancels an organization's subscription at the end
+ * of its period. The caller needs `can_manage_billing` on the organization.
+ */
+export function useCancelSubscription() {
+    const stigmer = useStigmer();
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [error, setError] = useState(null);
+    const cancel = useCallback(async (orgId) => {
+        setIsSubmitting(true);
+        setError(null);
+        try {
+            return await stigmer.subscription.cancel(create(CancelSubscriptionInputSchema, { orgId }));
+        }
+        catch (e) {
+            const err = toError(e);
+            setError(err);
+            throw err;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [stigmer.subscription]);
+    const clearError = useCallback(() => setError(null), []);
+    return useMemo(() => ({ cancel, isSubmitting, error, clearError }), [cancel, isSubmitting, error, clearError]);
+}
+//# sourceMappingURL=useChangePlan.js.map

package/billing/useChangePlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChangePlan.js","sourceRoot":"","sources":["../src/billing/useChangePlan.ts"],"names":[],"mappings":"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"}

package/billing/useCreateBillingPortalSession.d.ts

@@ -1,10 +1,13 @@
+import { type BillingRedirect } from "./redirect.js";
 /** Return value of {@link useCreateBillingPortalSession}. */
 export interface UseCreateBillingPortalSessionReturn {
     /**
      * Open the Stripe Customer Portal for payment method management.
      *
-     * On success, redirects the user to the Stripe-hosted portal page.
-     * The promise resolves before the redirect occurs.
+     * On success, leaves for the Stripe-hosted portal page: through
+     * `redirect.openUrl` when given, else by navigating this window. The
+     * portal returns to `redirect.returnUrl` when given, else to the page
+     * the person is on.
      */
     readonly openPortal: (orgId: string) => Promise<void>;
     /** `true` while the portal session is being created. */
@@ -31,5 +34,5 @@ export interface UseCreateBillingPortalSessionReturn {
  * </button>
  * ```
  */
-export declare function useCreateBillingPortalSession(): UseCreateBillingPortalSessionReturn;
+export declare function useCreateBillingPortalSession(redirect?: BillingRedirect): UseCreateBillingPortalSessionReturn;
 //# sourceMappingURL=useCreateBillingPortalSession.d.ts.map

package/billing/useCreateBillingPortalSession.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCreateBillingPortalSession.d.ts","sourceRoot":"","sources":["../src/billing/useCreateBillingPortalSession.ts"],"names":[],"mappings":"AAMA,6DAA6D;AAC7D,MAAM,WAAW,mCAAmC;IAClD;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,6BAA6B,IAAI,mCAAmC,CAmCnF"}
+{"version":3,"file":"useCreateBillingPortalSession.d.ts","sourceRoot":"","sources":["../src/billing/useCreateBillingPortalSession.ts"],"names":[],"mappings":"AAKA,OAAO,EAAoC,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAEvF,6DAA6D;AAC7D,MAAM,WAAW,mCAAmC;IAClD;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,CAAC,EAAE,eAAe,GACzB,mCAAmC,CAyCrC"}

package/billing/useCreateBillingPortalSession.js

@@ -2,6 +2,7 @@
 import { useCallback, useState } from "react";
 import { useStigmer } from "../hooks.js";
 import { toError } from "../internal/toError.js";
+import { billingReturnUrl, leaveForStripe } from "./redirect.js";
 /**
  * Behavior hook that opens the Stripe Customer Portal for payment
  * method management.
@@ -19,8 +20,10 @@ import { toError } from "../internal/toError.js";
  * </button>
  * ```
  */
-export function useCreateBillingPortalSession() {
+export function useCreateBillingPortalSession(redirect) {
     const stigmer = useStigmer();
+    const openUrl = redirect?.openUrl;
+    const pinnedReturnUrl = redirect?.returnUrl;
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
     const clearError = useCallback(() => setError(null), []);
@@ -28,13 +31,17 @@ export function useCreateBillingPortalSession() {
         setIsLoading(true);
         setError(null);
         try {
-            const returnUrl = typeof window !== "undefined" ? window.location.href : "";
+            const returnUrl = pinnedReturnUrl !== undefined
+                ? billingReturnUrl({ returnUrl: pinnedReturnUrl })
+                : typeof window !== "undefined"
+                    ? window.location.href
+                    : "";
             const response = await stigmer.billing.createBillingPortalSession({
                 orgId,
                 returnUrl,
             });
             if (response.portalUrl) {
-                window.location.href = response.portalUrl;
+                await leaveForStripe(response.portalUrl, { openUrl });
             }
         }
         catch (err) {
@@ -44,7 +51,7 @@ export function useCreateBillingPortalSession() {
         finally {
             setIsLoading(false);
         }
-    }, [stigmer]);
+    }, [stigmer, openUrl, pinnedReturnUrl]);
     return { openPortal, isLoading, error, clearError };
 }
 //# sourceMappingURL=useCreateBillingPortalSession.js.map

package/billing/useCreateBillingPortalSession.js.map

@@ -1 +1 @@
-{"version":3,"file":"useCreateBillingPortalSession.js","sourceRoot":"","sources":["../src/billing/useCreateBillingPortalSession.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAmBjD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,6BAA6B;IAC3C,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC,CAAC;IAEvD,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAEzD,MAAM,UAAU,GAAG,WAAW,CAC5B,KAAK,EAAE,KAAa,EAAiB,EAAE;QACrC,YAAY,CAAC,IAAI,CAAC,CAAC;QACnB,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEf,IAAI,CAAC;YACH,MAAM,SAAS,GACb,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAE5D,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,0BAA0B,CAAC;gBAChE,KAAK;gBACL,SAAS;aACV,CAAC,CAAC;YAEH,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;gBACvB,MAAM,CAAC,QAAQ,CAAC,IAAI,GAAG,QAAQ,CAAC,SAAS,CAAC;YAC5C,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;YACvB,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AACtD,CAAC"}
+{"version":3,"file":"useCreateBillingPortalSession.js","sourceRoot":"","sources":["../src/billing/useCreateBillingPortalSession.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAwB,MAAM,eAAe,CAAC;AAqBvF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,6BAA6B,CAC3C,QAA0B;IAE1B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,QAAQ,EAAE,OAAO,CAAC;IAClC,MAAM,eAAe,GAAG,QAAQ,EAAE,SAAS,CAAC;IAC5C,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC,CAAC;IAEvD,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAEzD,MAAM,UAAU,GAAG,WAAW,CAC5B,KAAK,EAAE,KAAa,EAAiB,EAAE;QACrC,YAAY,CAAC,IAAI,CAAC,CAAC;QACnB,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEf,IAAI,CAAC;YACH,MAAM,SAAS,GACb,eAAe,KAAK,SAAS;gBAC3B,CAAC,CAAC,gBAAgB,CAAC,EAAE,SAAS,EAAE,eAAe,EAAE,CAAC;gBAClD,CAAC,CAAC,OAAO,MAAM,KAAK,WAAW;oBAC7B,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI;oBACtB,CAAC,CAAC,EAAE,CAAC;YAEX,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,0BAA0B,CAAC;gBAChE,KAAK;gBACL,SAAS;aACV,CAAC,CAAC;YAEH,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;gBACvB,MAAM,cAAc,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;YACvB,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC,EACD,CAAC,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,CACpC,CAAC;IAEF,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AACtD,CAAC"}

package/billing/useCreateCheckoutSession.d.ts

@@ -1,9 +1,10 @@
 import type { CreateCreditCheckoutSessionResponse } from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
+import { type BillingRedirect } from "./redirect.js";
 /** Parameters for {@link useCreateCheckoutSession}'s `createSession` callback. */
 export interface CreateCheckoutSessionInput {
     /** Organization purchasing credits. */
     readonly orgId: string;
-    /** Credit pack to purchase (e.g., "starter", "growth", "team"). */
+    /** Credit pack to purchase: its id, e.g. "starter", "growth" or "team" (the pack named Scale). */
     readonly packId: string;
     /** URL to redirect to after successful payment. */
     readonly successUrl: string;
@@ -15,9 +16,10 @@ export interface UseCreateCheckoutSessionReturn {
     /**
      * Create a Stripe Checkout Session and redirect the user.
      *
-     * On success, sets `window.location.href` to the Stripe-hosted
-     * checkout page URL. The promise resolves with the response before
-     * the redirect occurs, allowing callers to perform cleanup if needed.
+     * On success, leaves for the Stripe-hosted checkout page: through the
+     * hook's `redirect.openUrl` when given, else by navigating this window.
+     * The promise resolves with the response before the redirect occurs,
+     * allowing callers to perform cleanup if needed.
      */
     readonly createSession: (input: CreateCheckoutSessionInput) => Promise<CreateCreditCheckoutSessionResponse>;
     /** `true` while the checkout session is being created. */
@@ -50,5 +52,5 @@ export interface UseCreateCheckoutSessionReturn {
  * };
  * ```
  */
-export declare function useCreateCheckoutSession(): UseCreateCheckoutSessionReturn;
+export declare function useCreateCheckoutSession(redirect?: BillingRedirect): UseCreateCheckoutSessionReturn;
 //# sourceMappingURL=useCreateCheckoutSession.d.ts.map