@stigmer/react 3.39.1-dev.20260928194002 → 3.40.1

package/src/billing/useCreateCheckoutSession.ts

@@ -4,12 +4,13 @@ import { useCallback, useState } from "react";
 import type { CreateCreditCheckoutSessionResponse } from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
 import { useStigmer } from "../hooks.js";
 import { toError } from "../internal/toError.js";
+import { leaveForStripe, 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;
@@ -22,9 +23,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,
@@ -60,8 +62,11 @@ export interface UseCreateCheckoutSessionReturn {
  * };
  * ```
  */
-export function useCreateCheckoutSession(): UseCreateCheckoutSessionReturn {
+export function useCreateCheckoutSession(
+  redirect?: BillingRedirect,
+): UseCreateCheckoutSessionReturn {
   const stigmer = useStigmer();
+  const openUrl = redirect?.openUrl;
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
@@ -83,7 +88,7 @@ export function useCreateCheckoutSession(): UseCreateCheckoutSessionReturn {
         });
 
         if (response.checkoutUrl) {
-          window.location.href = response.checkoutUrl;
+          await leaveForStripe(response.checkoutUrl, { openUrl });
         }
 
         return response;
@@ -94,7 +99,7 @@ export function useCreateCheckoutSession(): UseCreateCheckoutSessionReturn {
         setIsSubmitting(false);
       }
     },
-    [stigmer],
+    [stigmer, openUrl],
   );
 
   return { createSession, isSubmitting, error, clearError };

package/src/billing/useCreatePaymentMethodSetupSession.ts

@@ -0,0 +1,77 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+import { billingReturnUrl, leaveForStripe, type BillingRedirect } from "./redirect.js";
+
+/** Return value of {@link useCreatePaymentMethodSetupSession}. */
+export interface UseCreatePaymentMethodSetupSessionReturn {
+  /**
+   * Leave for Stripe's hosted page to save a card, with no charge. Stripe
+   * returns to the billing page with `?setup=success` (and `&plan=<id>`
+   * when `planId` names the plan the person was subscribing to, so the
+   * page can reopen that choice), or without a query when they leave.
+   * The saved card becomes the organization's default for every invoice.
+   */
+  readonly addPaymentMethod: (orgId: string, planId?: string) => Promise<void>;
+  /** `true` while the setup session is being created. */
+  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 saves a payment method through a Stripe-hosted setup
+ * page: the card door every subscription needs before its first period.
+ *
+ * The caller needs `can_manage_billing` on the organization. Pass the
+ * host's {@link BillingRedirect} where the window cannot host Stripe's
+ * page itself.
+ */
+export function useCreatePaymentMethodSetupSession(
+  redirect?: BillingRedirect,
+): UseCreatePaymentMethodSetupSessionReturn {
+  const stigmer = useStigmer();
+  const openUrl = redirect?.openUrl;
+  const returnUrl = redirect?.returnUrl;
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const addPaymentMethod = useCallback(
+    async (orgId: string, planId?: string): Promise<void> => {
+      setIsSubmitting(true);
+      setError(null);
+      try {
+        const billingPage = billingReturnUrl({ returnUrl });
+        const success = new URLSearchParams({ setup: "success" });
+        if (planId !== undefined && planId !== "") {
+          success.set("plan", planId);
+        }
+        const response = await stigmer.billing.createPaymentMethodSetupSession({
+          orgId,
+          successUrl: `${billingPage}?${success.toString()}`,
+          cancelUrl: billingPage,
+        });
+        if (response.setupUrl) {
+          await leaveForStripe(response.setupUrl, { openUrl });
+        }
+      } catch (e) {
+        const err = toError(e);
+        setError(err);
+        throw err;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [stigmer.billing, openUrl, returnUrl],
+  );
+  const clearError = useCallback(() => setError(null), []);
+
+  return useMemo(
+    () => ({ addPaymentMethod, isSubmitting, error, clearError }),
+    [addPaymentMethod, isSubmitting, error, clearError],
+  );
+}

package/src/billing/useEntitlements.ts

@@ -0,0 +1,80 @@
+"use client";
+
+import { useMemo } from "react";
+import { create } from "@bufbuild/protobuf";
+import {
+  GetEntitlementsInputSchema,
+  type GetEntitlementsOutput,
+} from "@stigmer/protos/ai/stigmer/billing/subscription/v1/io_pb";
+import type { Feature } from "@stigmer/protos/ai/stigmer/platform/v1/entitlement_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Options for {@link useEntitlements}. */
+export interface UseEntitlementsOptions {
+  /** Skip fetching while `false` (stable no-op). Default `true`. */
+  readonly enabled?: boolean;
+}
+
+/** Return value of {@link useEntitlements}. */
+export interface UseEntitlementsReturn {
+  /**
+   * What the organization may do right now and the plan that permits it
+   * (`planId` empty on Free), or `null` before the first successful fetch.
+   */
+  readonly entitlements: GetEntitlementsOutput | null;
+  /**
+   * Whether the organization's plan includes `feature` right now; `null`
+   * until the entitlements have loaded, so a caller never refuses on a
+   * guess.
+   */
+  readonly allows: (feature: Feature) => boolean | null;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that resolves what an organization's plan permits right now.
+ *
+ * The answer is derived by the server on every read: the live
+ * subscription's plan, else Free's. A platform-managed organization
+ * resolves through its integrator's plan. Every member may read it
+ * (`can_view_billing` is granted to viewers).
+ *
+ * Cloud-only. Self-hosted editions answer from their license, not a plan,
+ * so callers gate on the edition before reading (see `UpgradeNotice`).
+ *
+ * @example
+ * ```tsx
+ * const { allows } = useEntitlements(orgId);
+ * if (allows(Feature.teams) === false) return <UpgradeNotice feature={Feature.teams} />;
+ * ```
+ */
+export function useEntitlements(
+  orgId: string | null,
+  options?: UseEntitlementsOptions,
+): UseEntitlementsReturn {
+  const stigmer = useStigmer();
+  const enabled = (options?.enabled ?? true) && orgId !== null && orgId !== "";
+  const { data: entitlements, isLoading, error, refetch } = useFetch(
+    enabled && orgId ? () => stigmer.subscription.getEntitlements(create(GetEntitlementsInputSchema, { orgId })) : null,
+    [enabled, orgId, stigmer],
+    null as GetEntitlementsOutput | null,
+    { refetchOnWindowFocus: true },
+  );
+  const features = entitlements?.entitlements?.features;
+  return useMemo(
+    () => ({
+      entitlements,
+      allows: (feature: Feature) => (features === undefined ? null : features.includes(feature)),
+      isLoading,
+      error,
+      refetch,
+    }),
+    [entitlements, features, isLoading, error, refetch],
+  );
+}

package/src/billing/usePeriodEstimate.ts

@@ -0,0 +1,59 @@
+"use client";
+
+import { useMemo } from "react";
+import { create } from "@bufbuild/protobuf";
+import {
+  GetPeriodEstimateInputSchema,
+  type PeriodEstimate,
+} from "@stigmer/protos/ai/stigmer/billing/subscription/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Options for {@link usePeriodEstimate}. */
+export interface UsePeriodEstimateOptions {
+  /** Skip fetching while `false`: read only while a subscription is live. Default `true`. */
+  readonly enabled?: boolean;
+}
+
+/** Return value of {@link usePeriodEstimate}. */
+export interface UsePeriodEstimateReturn {
+  /** The current period's estimated invoice, or `null` before the first successful fetch. */
+  readonly estimate: PeriodEstimate | null;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that estimates what an organization's current subscription
+ * period will be invoiced.
+ *
+ * The estimate is the invoice the period would close with if no further
+ * usage occurred: the plan's minimum for the whole period (or its share of
+ * the period's provider cost, whichever is greater), less the commission
+ * already collected on tokens, plus managed organizations beyond those
+ * included. The server rates it by the same rule the monthly close
+ * invoices by, so it agrees with the invoice to the cent.
+ *
+ * The server answers NOT_FOUND when nothing is live to invoice (Free, or a
+ * managed organization), so enable it only while a subscription is live.
+ *
+ * Cloud-only; the caller needs `can_view_billing` on the organization.
+ */
+export function usePeriodEstimate(
+  orgId: string | null,
+  options?: UsePeriodEstimateOptions,
+): UsePeriodEstimateReturn {
+  const stigmer = useStigmer();
+  const enabled = (options?.enabled ?? true) && orgId !== null && orgId !== "";
+  const { data: estimate, isLoading, error, refetch } = useFetch(
+    enabled && orgId ? () => stigmer.subscription.getPeriodEstimate(create(GetPeriodEstimateInputSchema, { orgId })) : null,
+    [enabled, orgId, stigmer],
+    null as PeriodEstimate | null,
+    { refetchOnWindowFocus: true },
+  );
+  return useMemo(() => ({ estimate, isLoading, error, refetch }), [estimate, isLoading, error, refetch]);
+}

package/src/billing/usePlans.ts

@@ -0,0 +1,65 @@
+"use client";
+
+import { useMemo } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { Plan } from "@stigmer/protos/ai/stigmer/billing/plan/v1/api_pb";
+import { ListPlansInputSchema } from "@stigmer/protos/ai/stigmer/billing/plan/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Options for {@link usePlans}. */
+export interface UsePlansOptions {
+  /** Include retired plans beside the ones that can still be bought. Default `false`. */
+  readonly includeRetired?: boolean;
+  /** Skip fetching while `false` (stable no-op). Default `true`. */
+  readonly enabled?: boolean;
+}
+
+/** Return value of {@link usePlans}. */
+export interface UsePlansReturn {
+  /** The catalog's plans, or `null` before the first successful fetch. */
+  readonly plans: readonly Plan[] | null;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that lists the Stigmer Cloud plan catalog.
+ *
+ * Every signed-in caller may read it. By default it lists only the plans
+ * that can still be bought; `includeRetired` adds the retired rows an
+ * operator audits. Free is not a row: an organization with no live
+ * subscription is on Free.
+ *
+ * Cloud-only: other editions serve no plans.
+ *
+ * @example
+ * ```tsx
+ * const { plans } = usePlans();
+ * ```
+ */
+export function usePlans(options?: UsePlansOptions): UsePlansReturn {
+  const stigmer = useStigmer();
+  const enabled = options?.enabled ?? true;
+  const includeRetired = options?.includeRetired ?? false;
+  const { data: plans, isLoading, isRefetching, error, refetch } = useFetch(
+    enabled
+      ? () =>
+          stigmer.plan
+            .list(create(ListPlansInputSchema, { includeRetired }))
+            .then((result): readonly Plan[] => result.entries)
+      : null,
+    [enabled, includeRetired, stigmer],
+    null as readonly Plan[] | null,
+  );
+  return useMemo(
+    () => ({ plans, isLoading, isRefetching, error, refetch }),
+    [plans, isLoading, isRefetching, error, refetch],
+  );
+}

package/src/billing/useSubscription.ts

@@ -0,0 +1,70 @@
+"use client";
+
+import { useMemo } from "react";
+import { create } from "@bufbuild/protobuf";
+import { isNotFound } from "@stigmer/sdk";
+import type { Subscription } from "@stigmer/protos/ai/stigmer/billing/subscription/v1/api_pb";
+import { GetSubscriptionForOrganizationInputSchema } from "@stigmer/protos/ai/stigmer/billing/subscription/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Return value of {@link useSubscription}. */
+export interface UseSubscriptionReturn {
+  /**
+   * The organization's subscription as stored; `null` when it never
+   * subscribed (it is on Free) or before the first successful fetch.
+   * A subscription that ended reads `canceled` with its period in the
+   * past; {@link useEntitlements} says what the organization may do now.
+   */
+  readonly subscription: Subscription | null;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. Never NOT_FOUND. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that reads an organization's subscription.
+ *
+ * The server answers NOT_FOUND for an organization that never subscribed;
+ * this hook reads that as `null`, because never subscribed is a state (the
+ * Free plan), not a failure.
+ *
+ * Pass `null` as `orgId` to skip fetching. Refetches when the window
+ * regains focus, so a plan changed in another window, or a card saved in
+ * the system browser, shows on return.
+ *
+ * Cloud-only; the caller needs `can_view_billing` on the organization.
+ *
+ * @example
+ * ```tsx
+ * const { subscription } = useSubscription(orgId);
+ * ```
+ */
+export function useSubscription(orgId: string | null): UseSubscriptionReturn {
+  const stigmer = useStigmer();
+  const { data: subscription, isLoading, isRefetching, error, refetch } = useFetch(
+    orgId
+      ? () =>
+          stigmer.subscription
+            .getForOrganization(create(GetSubscriptionForOrganizationInputSchema, { orgId }))
+            .catch((err: unknown) => {
+              if (isNotFound(err)) {
+                return null;
+              }
+              throw err;
+            })
+      : null,
+    [orgId, stigmer],
+    null as Subscription | null,
+    { refetchOnWindowFocus: true },
+  );
+  return useMemo(
+    () => ({ subscription, isLoading, isRefetching, error, refetch }),
+    [subscription, isLoading, isRefetching, error, refetch],
+  );
+}