@eifi1/ui-kit 0.41.0 → 0.43.0

package/src/billing/billing-labels.ts

@@ -108,6 +108,13 @@ export interface BillingLabels {
   choosePlan: string;
   /** The payment-failed banner's action, to the provider's portal: "Update payment method". */
   updatePayment: string;
+  /**
+   * 0.42 (§16.7 A, §16.8): the payment-failed banner for an admin who isn't the buyer
+   * (`portal: "buyer_only"`), with no button — only the buyer can change the card.
+   * `buyer` is their display name, or `undefined` when they are gone ("the admin who
+   * bought the subscription").
+   */
+  paymentFailedAskBuyer: (buyer?: string) => string;
   /** The processing banner's action, when the app gives one: "Check again". */
   checkAgain: string;
 
@@ -153,6 +160,30 @@ export interface BillingLabels {
    */
   notAtProvider: string;
 
+  /* ── The portal for the buyer only, the in-app cancel (0.42, §16) ── */
+  /**
+   * In place of "Payment and invoices" for an admin who isn't the buyer (`portal:
+   * "buyer_only"`, §16.2 decision 3): the provider's portal opens only for the buyer.
+   * `buyer` is their display name — or `undefined` when they are gone or have left the
+   * company, and the words then say "the admin who bought the subscription".
+   */
+  buyerHolds: (buyer?: string) => string;
+  /** `CancelSubscriptionConfirm`'s title: "Cancel subscription". */
+  cancelConfirmTitle: string;
+  /** Its body; `date` is the period's end, formatted: "Your subscription ends on
+   *  9 Nov 2026. Until then everything works as before." */
+  cancelConfirmBody: (date: string) => string;
+  /** Its confirm button (§16.4): "Cancel subscription now". German: "Jetzt kündigen",
+   *  the confirmation button's words in §312k BGB. */
+  cancelConfirmAction: string;
+  /** In place of "Cancel subscription" while a cancel is scheduled (§16.7 C, `POST
+   *  /billing/resume`): "Keep subscription". */
+  keepSubscription: string;
+  /** 0.43 (§17.3): the muted note under the actions while the portal opens in a new tab —
+   *  `provider` the provider's name ("Paddle"), `app` the app's; without the app, "this
+   *  page". "Payment and invoices open at Paddle in a new tab; Kastlan stays open here." */
+  portalOpensNewTab: (provider: string, app?: string) => string;
+
   /* ── The pay page (§14.4) ── */
   /* Built into the static page `dist/pay/` at the kit's build: it has no React and no
      provider, so an app's override never reaches it. */
@@ -184,6 +215,15 @@ export interface BillingLabels {
   /** The confirm button: "Change plan". */
   switchConfirm: string;
 
+  /* ── The permanent-grant warning (0.42, §16.2 decision 5, §16.8 B) ── */
+  /** The warning's title, before a checkout (`PlanPicker`) or a switch
+   *  (`PlanSwitchConfirm`) under a grant without an end: "Your free access continues". */
+  grantWarningTitle: string;
+  /** What the purchase does under it: nothing to the plan while the grant runs. */
+  grantWarningBody: string;
+  /** `PlanPicker`'s button that goes on to the checkout: "Buy anyway". */
+  grantWarningAction: string;
+
   /* ── Offline (§12.5) ── */
   /** Changes refused as `billing_read_only` inside a sync reply, kept queued and sent
    *  after payment: "3 changes waiting for a plan". */
@@ -271,6 +311,10 @@ export const DEFAULT_BILLING_LABELS: BillingLabels = {
   processing: "Your payment is being processed. Your plan starts as soon as it’s confirmed; this page updates by itself.",
   choosePlan: "Choose a plan",
   updatePayment: "Update payment method",
+  paymentFailedAskBuyer: (buyer) =>
+    buyer
+      ? `The payment failed. ${buyer} can update the payment method.`
+      : "The payment failed. The admin who bought the subscription can update the payment method.",
   checkAgain: "Check again",
 
   lockReason: "Your plan has ended. Choose a plan to make changes again.",
@@ -286,6 +330,16 @@ export const DEFAULT_BILLING_LABELS: BillingLabels = {
   manage: "Payment and invoices",
   cancel: "Cancel subscription",
   notAtProvider: "Nothing to manage yet. Payments and invoices appear here once you have a paid plan.",
+  buyerHolds: (buyer) =>
+    buyer
+      ? `The payment method and the invoices are with ${buyer}, who bought the subscription.`
+      : "The payment method and the invoices are with the admin who bought the subscription.",
+  cancelConfirmTitle: "Cancel subscription",
+  cancelConfirmBody: (date) => `Your subscription ends on ${date}. Until then everything works as before.`,
+  cancelConfirmAction: "Cancel subscription now",
+  keepSubscription: "Keep subscription",
+  portalOpensNewTab: (provider, app) =>
+    `Payment and invoices open at ${provider} in a new tab; ${app ? `${app} stays open here` : "this page stays open"}.`,
 
   payOpening: "Opening the secure checkout…",
   payNothing: "There’s no payment to make here. To choose a plan, go back to the app.",
@@ -300,6 +354,11 @@ export const DEFAULT_BILLING_LABELS: BillingLabels = {
   switchNextCharge: (date) => `Next charge on ${date}`,
   switchConfirm: "Change plan",
 
+  grantWarningTitle: "Your free access continues",
+  grantWarningBody:
+    "You have free access with no end date. A purchase won’t change your plan while the free access runs: you would pay for a plan that doesn’t apply.",
+  grantWarningAction: "Buy anyway",
+
   waitingChanges: (count) =>
     count === 1 ? "1 change waiting for a plan" : `${count} changes waiting for a plan`,
   discardWaiting: "Discard waiting changes",

package/src/billing/billing-overview.ts

@@ -54,6 +54,43 @@ export interface BillingOverview {
    * server-kit before 0.13 still type-checks; absent, read it as false.
    */
   switching?: boolean;
+  /**
+   * 0.42 (server-kit 0.14, §16.3): who may open the provider's portal. `"buyer_only"`:
+   * the row has a buyer (`provider_payer_user_id`) and the viewer isn't them — every
+   * portal target would answer `403 billing_portal_buyer_only`, so "Payment and
+   * invoices" is a caption naming the buyer and "Cancel subscription" is the in-app
+   * cancel (`POST /billing/cancel`). `"open"`, or absent (server-kit before 0.14): as
+   * before. Pass it to `SubscriptionActions`' `portal`.
+   */
+  portal?: BillingPortalAccess;
+  /**
+   * 0.42 (§16.3, §16.7 G): the buyer's display name, for the caption under
+   * `"buyer_only"`; `null` when the buyer is gone or no longer a member of the company,
+   * and the words then say "the admin who bought the subscription".
+   */
+  buyer_name?: string | null;
+}
+
+/** 0.42 (§16.3): `BillingOverview.portal` and `BillingStanding.portal` — server-kit's
+ *  `Literal["open", "buyer_only"]`. */
+export type BillingPortalAccess = "open" | "buyer_only";
+
+/**
+ * 0.42 (§16.2 decision 5, §16.7 E): whether the payer's free grant runs WITHOUT AN END —
+ * an operator's grant (`source: "manual"`) with `comped_until` empty. A purchase under
+ * it leaves the row `comped` on the grant's plan (§12.11): only the paid price moves,
+ * so the payer would pay for a plan that never applies. Pass it to `PlanPicker`'s and
+ * `PlanSwitchConfirm`'s `permanentGrant`, which warn before the checkout or the switch.
+ *
+ * `source` is checked explicitly, not implied by the missing date: Kurvenschmiede's
+ * pre-launch beta rows are `comped` with `comped_until` null too (their launch-plus-12-
+ * months end isn't written yet, §3.2), and they are not permanent. A grant with an end
+ * gets no warning either: the bought plan applies from that end on.
+ */
+export function isPermanentGrant(
+  overview: Pick<BillingOverview, "status" | "source"> & { comped_until?: BillingOverview["comped_until"] },
+): boolean {
+  return overview.status === "comped" && overview.source === "manual" && overview.comped_until == null;
 }
 
 /** 0.39: what the payer pays at the provider (server-kit's `PaidPrice`, §15.2.10),

package/src/billing/billing-standing.ts

@@ -1,6 +1,7 @@
 import { toDate } from "../lib/format";
 import type { DateInput } from "../lib/format";
 import type { SubscriptionStatus } from "./billing-labels";
+import type { BillingPortalAccess } from "./billing-overview";
 
 /**
  * What a device knows of the payer's standing — the fields of `GET /billing/overview`
@@ -16,6 +17,13 @@ export interface BillingStanding {
   /** When a free grant ends: a beta user's 12 months, an operator's grant. Empty for a
    *  grant without an end (§12.8). */
   comped_until?: DateInput;
+  /** 0.42 (server-kit 0.14, §16.7 A): who may open the provider's portal, as the
+   *  overview's `portal` — `GET /billing/status` says it too, for the payment-failed
+   *  banner (`BillingBanner`'s `portal`). Absent: `"open"`. */
+  portal?: BillingPortalAccess;
+  /** 0.42 (§16.7 A): the buyer's display name, as the overview's `buyer_name`; `null`
+   *  when the buyer is gone or has left the company. */
+  buyer_name?: string | null;
 }
 
 /**

package/src/billing/cancel-request.ts

@@ -0,0 +1,75 @@
+import { useState } from "react";
+
+/**
+ * What the payer asked for in the app (0.43, kastlan `18bf4c0`): `"cancel"` after
+ * `POST /billing/cancel` answered 204, `"resume"` after `POST /billing/resume` — while the
+ * overview still shows the old `cancel_at_period_end`, until the provider's
+ * `subscription.updated` has landed (§16.3). `null`: nothing asked, or the row has moved.
+ */
+export type CancelRequested = "cancel" | "resume" | null;
+
+/** What the page shows for the row as read now — `CancelRequest.view(rowScheduled)`. */
+export interface CancelRequestView {
+  /** For `SubscriptionActions`' `cancelRequested`. */
+  requested: CancelRequested;
+  /** What the plan line says — the asked-for state until the row moves, then the row's:
+   *  "Cancels on …" at once after a cancel, "Renews on …" after "Keep subscription". */
+  cancelScheduled: boolean;
+  /** Call on the 204 of a cancel or of a resume. A cancel and its undo both asked before
+   *  the row moved cancel out. */
+  noteAsked: () => void;
+}
+
+export interface CancelRequest {
+  /** Read the overview again every few seconds while this is true — the overview query's
+   *  `waiting` (kastlan's `useBillingOverview({ waiting })`, a `refetchInterval` inside) —
+   *  so the page follows the provider. Needs no overview data: pass it to the query. */
+  waiting: boolean;
+  /**
+   * The row as read now (the overview's `cancel_at_period_end`; `undefined` while it
+   * loads) → what the page shows. Call it during render, after the query: when the row
+   * has moved past what was asked, it drops the request (React's "adjust state while
+   * rendering" pattern), so `waiting` turns false and the query stops polling.
+   */
+  view: (rowScheduled: boolean | null | undefined) => CancelRequestView;
+}
+
+/**
+ * The in-app cancel's follow-up (0.43, kastlan's derivation in `18bf4c0`): after "Cancel
+ * subscription now" or "Keep subscription" the server answers 204 at once, but the row's
+ * `cancel_at_period_end` only changes when the provider's webhook lands. Until then the
+ * page shows what was asked for, and a second press would ask the provider again.
+ *
+ * The state lives in the hook and needs no overview at construction, so it goes BEFORE
+ * the overview query, which reads `waiting`, and the view comes after it — the overview
+ * read once (build review 0.43, kastlan B2; kastlan `subscription-section.tsx:74-92`):
+ *
+ *     const request = useCancelRequest();
+ *     const { data } = useBillingOverview({ waiting: request.waiting });
+ *     const view = request.view(data?.cancel_at_period_end);
+ *     <p>{standingLine({ ...data, cancel_at_period_end: view.cancelScheduled })}</p>
+ *     <SubscriptionActions
+ *       cancelAtPeriodEnd={data.cancel_at_period_end}
+ *       cancelRequested={view.requested}
+ *       onResume={() => resume.mutate(undefined, { onSuccess: view.noteAsked })}
+ *       …
+ *     />
+ */
+export function useCancelRequest(): CancelRequest {
+  // What was asked, kept with the row's state it was asked against.
+  const [asked, setAsked] = useState<{ scheduled: boolean } | null>(null);
+  const view = (row: boolean | null | undefined): CancelRequestView => {
+    // Not read yet: nothing to show against, and nothing to drop.
+    if (row === undefined || row === null) return { requested: null, cancelScheduled: false, noteAsked: () => {} };
+    // The row has moved: it says the rest. Adjusted during render, React's pattern for
+    // state that follows a prop.
+    if (asked !== null && asked.scheduled !== row) setAsked(null);
+    const open = asked !== null && asked.scheduled === row;
+    return {
+      requested: open ? (row ? "resume" : "cancel") : null,
+      cancelScheduled: open ? !row : row,
+      noteAsked: () => setAsked((a) => (a !== null && a.scheduled === row ? null : { scheduled: row })),
+    };
+  };
+  return { waiting: asked !== null, view };
+}

package/src/billing/cancel-subscription.tsx

@@ -0,0 +1,102 @@
+import type { KeyboardEvent } from "react";
+
+import { useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import type { LabelOverride } from "../i18n/kit-labels";
+import { DEFAULT_COMMON_LABELS } from "../i18n/shared-labels";
+import { formatDate } from "../lib/format";
+import type { DateInput } from "../lib/format";
+import { Button } from "../components/button";
+import { DialogFrame } from "../components/dialog-frame";
+import { COMMIT_EXCEPT_BILLING } from "../components/write-lock";
+import { useBillingLabels } from "./billing-labels";
+import type { BillingLabels } from "./billing-labels";
+
+export interface CancelSubscriptionConfirmProps {
+  open: boolean;
+  /** `false` when the admin dismisses it — Back, Escape, the backdrop. Confirm leaves it
+   *  open: close it once `POST /billing/cancel` answers. */
+  onOpenChange: (open: boolean) => void;
+  /** The overview's `current_period_end`: the day the subscription ends. Formatted with
+   *  the kit's date formatter (`formatDate`, `"medium"`). */
+  periodEnd: DateInput;
+  /** Confirm: the app's `POST /billing/cancel` (server-kit 0.14, §16.3). */
+  onConfirm: () => void;
+  /** The cancel is under way: Confirm's spinner, no second press, and Escape and Back
+   *  don't close. */
+  pending?: boolean;
+  /** The date's locale. Default: the provider's. */
+  locale?: string;
+  /** Prop > `<UiKitProvider labels={{ billing }}>` > English. */
+  labels?: LabelOverride<BillingLabels>;
+}
+
+/**
+ * The in-app cancel's confirm (docs/billing-harmonization.md §16.2 decision 2, §16.4,
+ * ui-kit 0.42): "Cancel subscription" for an admin the provider's portal doesn't open for
+ * (`SubscriptionActions`' `portal="buyer_only"` → `onCancelInApp`). It names the day the
+ * subscription ends — "Your subscription ends on 9 Nov 2026. Until then everything works
+ * as before." — and its button reads "Cancel subscription now" (German "Jetzt kündigen",
+ * the confirmation button of §312k BGB).
+ *
+ *     <CancelSubscriptionConfirm
+ *       open={asking}
+ *       onOpenChange={setAsking}
+ *       periodEnd={overview.current_period_end}
+ *       pending={cancel.isPending}
+ *       onConfirm={() => cancel.mutate()}
+ *     />
+ *
+ * The cancel is at the period's end (Paddle's `cancel`, not immediately); the row follows
+ * by webhook (`cancel_at_period_end`), as after a cancel in the portal, and
+ * `SubscriptionActions` then offers "Keep subscription" (`onResume`).
+ *
+ * It takes no billing lock (`COMMIT_EXCEPT_BILLING` built in, §3.3): a read-only payer
+ * may always cancel. A demo lock still holds it, as the server's demo guard does. The kit
+ * sends no request.
+ */
+export function CancelSubscriptionConfirm({
+  open,
+  onOpenChange,
+  periodEnd,
+  onConfirm,
+  pending = false,
+  locale: localeProp,
+  labels: labelsProp,
+}: CancelSubscriptionConfirmProps) {
+  const labels = useBillingLabels(labelsProp);
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  const locale = useKitLocale(localeProp);
+
+  return (
+    <DialogFrame
+      open={open}
+      title={labels.cancelConfirmTitle}
+      description={labels.cancelConfirmBody(formatDate(periodEnd, "medium", { locale }))}
+      onClose={() => {
+        if (!pending) onOpenChange(false);
+      }}
+      onKeyDown={(e: KeyboardEvent<HTMLDivElement>) => {
+        if (pending && e.key === "Escape") e.preventDefault();
+      }}
+      aria-busy={pending || undefined}
+      data-cancel-subscription-confirm=""
+      actions={(close) => (
+        <>
+          <Button variant="secondary" onClick={close} disabled={pending}>
+            {common.back}
+          </Button>
+          <Button
+            variant="danger"
+            commit={COMMIT_EXCEPT_BILLING}
+            pending={pending}
+            onClick={() => {
+              if (!pending) onConfirm();
+            }}
+          >
+            {labels.cancelConfirmAction}
+          </Button>
+        </>
+      )}
+    />
+  );
+}

package/src/billing/plan-card.tsx

@@ -11,6 +11,7 @@ import type { ChoiceCardProps } from "../components/choice-card";
 import { Chip } from "../components/chip";
 import { ToggleGroup } from "../components/toggle-group";
 import { Button } from "../components/button";
+import { DialogFrame } from "../components/dialog-frame";
 import { useBillingLabels } from "./billing-labels";
 import type { BillingLabels } from "./billing-labels";
 import { BILLING_INTERVALS, billingCurrencyFor, formatPlanPrice, planPrice } from "./plan-price";
@@ -263,6 +264,24 @@ export interface PlanPickerProps extends Omit<PlanDisplayProps, "currency" | "in
   onChoose: (choice: PlanChoice) => void;
   /** The checkout is being opened: the button's spinner, no second press. */
   pending?: boolean;
+  /**
+   * 0.42 (§16.2 decision 5, §16.8 B): the payer's free grant runs without an end —
+   * `isPermanentGrant(overview)`. A purchase under it changes nothing the payer gets
+   * while the grant runs (§12.11), so the button first opens a confirm —
+   * `grantWarningTitle`, `grantWarningBody`, "Buy anyway" (`grantWarningAction`) and
+   * "Back" — and {@link onChoose} runs only on "Buy anyway". Warned, not refused.
+   *
+   * Not while {@link switching}: then the pick opens `PlanSwitchConfirm`, which takes
+   * the same `permanentGrant` and shows the warning above its figures — one warning,
+   * in the dialog where the payer agrees, rather than a confirm before a confirm.
+   */
+  permanentGrant?: boolean;
+  /**
+   * 0.42: the overview's `switching` — the app sends this pick to `PlanSwitchConfirm`
+   * (§15.2.10), not the checkout. Only decides where {@link permanentGrant}'s warning
+   * shows; the button and {@link onChoose} are the same either way.
+   */
+  switching?: boolean;
   /** The provider's localised price for a plan, or `undefined` for the catalogue's —
    *  see {@link PlanCardProps.pricePreview}. */
   pricePreview?: (plan: BillingPlan, choice: Omit<PlanChoice, "plan">) => ReactNode | undefined;
@@ -308,6 +327,11 @@ function pricedIntervals(plans: readonly BillingPlan[]): BillingInterval[] {
  * The button never takes the write lock: billing itself always works, a read-only payer
  * must be able to pay (§3.3). It is off, with the reason on hover and focus, while
  * nothing is picked or the current plan is.
+ *
+ * 0.42 (§16.8 B): under a grant without an end (`permanentGrant`) the payer is warned
+ * before paying for a plan that won't apply — here, in a confirm before `onChoose`, on
+ * the way to the checkout; on the way to a switch (`switching`) in `PlanSwitchConfirm`
+ * instead, so the warning shows once on either path.
  */
 export function PlanPicker({
   plans,
@@ -324,6 +348,8 @@ export function PlanPicker({
   currencies: currenciesProp,
   onChoose,
   pending,
+  permanentGrant = false,
+  switching = false,
   pricePreview,
   legend,
   name,
@@ -338,6 +364,8 @@ export function PlanPicker({
   const labels = useBillingLabels(labelsProp);
   const locale = useKitLocale(localeProp);
   const generated = useId();
+  /** The choice the grant warning holds back until "Buy anyway". */
+  const [warned, setWarned] = useState<PlanChoice | null>(null);
   const groupName = name ?? generated;
   const legendId = `${generated}-legend`;
 
@@ -447,11 +475,79 @@ export function PlanPicker({
           className="max-sm:w-full"
           disabledReason={blocked}
           pending={pending}
-          onClick={() => picked && onChoose({ plan: picked.code, interval, currency })}
+          onClick={() => {
+            if (!picked) return;
+            const choice = { plan: picked.code, interval, currency };
+            if (permanentGrant && !switching) setWarned(choice);
+            else onChoose(choice);
+          }}
         >
           {buttonText}
         </Button>
       </div>
+      {permanentGrant && !switching && (
+        <GrantWarningConfirm
+          open={warned !== null}
+          onOpenChange={(open) => {
+            if (!open) setWarned(null);
+          }}
+          onConfirm={() => {
+            if (warned) onChoose(warned);
+          }}
+          labels={labelsProp}
+        />
+      )}
     </div>
   );
 }
+
+export interface GrantWarningConfirmProps {
+  /** Shown, controlled. */
+  open: boolean;
+  /** `false` on "Back", Escape, the backdrop — and after "Buy anyway". */
+  onOpenChange: (open: boolean) => void;
+  /** "Buy anyway": the app opens its checkout. The dialog closes itself after it. */
+  onConfirm: () => void;
+  /** Prop > `<UiKitProvider labels={{ billing }}>` > English: `grantWarningTitle`,
+   *  `grantWarningBody`, `grantWarningAction`. "Back" is `common.back`. */
+  labels?: LabelOverride<BillingLabels>;
+}
+
+/**
+ * 0.42 (§16.8 B): the permanent-grant warning before a checkout — `grantWarningTitle`,
+ * `grantWarningBody`, "Back" and "Buy anyway" (`grantWarningAction`). {@link PlanPicker}
+ * shows it itself under `permanentGrant` when not `switching`. Exported for the path the
+ * picker cannot see: an app that meant to switch, learned there is no subscription to
+ * switch (keksdose: `/billing/plan/preview` → 409 `billing_not_subscribed`) and falls back
+ * to a checkout — show this before that checkout, so a permanent-grant holder is still
+ * warned. Carries `data-grant-warning`.
+ */
+export function GrantWarningConfirm({ open, onOpenChange, onConfirm, labels: labelsProp }: GrantWarningConfirmProps) {
+  const labels = useBillingLabels(labelsProp);
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  return (
+    <DialogFrame
+      open={open}
+      title={labels.grantWarningTitle}
+      description={labels.grantWarningBody}
+      onClose={() => onOpenChange(false)}
+      data-grant-warning=""
+      actions={(close) => (
+        <>
+          <Button variant="secondary" onClick={close}>
+            {common.back}
+          </Button>
+          <Button
+            variant="primary"
+            onClick={() => {
+              onConfirm();
+              onOpenChange(false);
+            }}
+          >
+            {labels.grantWarningAction}
+          </Button>
+        </>
+      )}
+    />
+  );
+}

package/src/billing/plan-switch.tsx

@@ -6,6 +6,7 @@ import { DEFAULT_COMMON_LABELS } from "../i18n/shared-labels";
 import { pluralForm } from "../i18n/plurals";
 import type { PluralForms } from "../i18n/plurals";
 import { formatDate, formatMoney, formatNumber } from "../lib/format";
+import { AlertBanner } from "../components/alert-banner";
 import { Button } from "../components/button";
 import { DialogFrame } from "../components/dialog-frame";
 import { Spinner } from "../components/spinner";
@@ -67,6 +68,15 @@ export interface PlanSwitchConfirmProps {
   onConfirm: () => void;
   /** The figures' and the date's locale. Default: the provider's. */
   locale?: string;
+  /**
+   * 0.42 (§16.2 decision 5, §16.8 B): the payer's free grant runs without an end —
+   * `isPermanentGrant(overview)`. The switch changes the PAID plan, not the applied one
+   * (§12.11), so the dialog says so above its figures (`grantWarningTitle`,
+   * `grantWarningBody`) before the payer agrees. Confirm stays Confirm: the warning is
+   * this dialog's own, and `PlanPicker` — told `switching` — shows none of its own on
+   * the way here, so the payer reads it once.
+   */
+  permanentGrant?: boolean;
   /** Prop > `<UiKitProvider labels={{ billing }}>` > English. */
   labels?: LabelOverride<BillingLabels>;
 }
@@ -105,6 +115,7 @@ export function PlanSwitchConfirm({
   formatLimit,
   onConfirm,
   locale: localeProp,
+  permanentGrant = false,
   labels: labelsProp,
 }: PlanSwitchConfirmProps) {
   const labels = useBillingLabels(labelsProp);
@@ -164,6 +175,11 @@ export function PlanSwitchConfirm({
         </>
       )}
     >
+      {permanentGrant && (
+        <AlertBanner tone="warning" size="sm" data-grant-warning="">
+          <strong className="block font-medium">{labels.grantWarningTitle}</strong> {labels.grantWarningBody}
+        </AlertBanner>
+      )}
       {preview === undefined ? (
         <div className="flex justify-center py-4">
           <Spinner showLabel />

package/src/billing/provider-page.ts

@@ -0,0 +1,75 @@
+/**
+ * The provider's hosted portal in a NEW TAB (0.43, docs/billing-harmonization.md §17):
+ * "Payment and invoices", the portal's "Cancel subscription" and the payment-failed
+ * banner's "Update payment method" open at the provider while the app stays open where
+ * it was. kastlan's `usePortal` (feat/kit-0.42, `72c3177`) is the reference.
+ *
+ * The checkout is NOT one of them (§17.4): it stays in the same tab, since the page waits
+ * for the payer's return (`useCheckoutProcessing`).
+ */
+
+/** How the page went: in a tab of its own, or — the browser refused one — in this one. */
+export type ProviderPageWay = "new-tab" | "same-tab";
+
+export interface OpenProviderPageOptions {
+  /** The window to open from and to fall back to. Default the global `window` (a test's
+   *  or an iframe's own). */
+  window?: Window;
+}
+
+/**
+ * Opens the provider's page in a new tab, from INSIDE the click: call it in the click
+ * handler itself, before any `await` — a `window.open` after one is blocked as a pop-up.
+ *
+ * 1. opens `about:blank` synchronously and sets its `opener` to `null`, so the provider's
+ *    page cannot reach back into the app;
+ * 2. awaits `fetchUrl` — the app's `POST /billing/portal` with its target, answering the
+ *    `url` (the kit sends no request);
+ * 3. points the tab at the URL;
+ * 4. on a refusal closes the tab again and rethrows, so the app shows its error;
+ * 5. where the browser refused the tab (a pop-up blocker), or it was closed while the
+ *    URL was on its way, the app's own page goes there instead.
+ *
+ *     <SubscriptionActions
+ *       onPortal={(target) => {
+ *         openProviderPage(() => api.billingPortal({ target }).then((r) => r.url)).catch(showError);
+ *       }}
+ *       providerName="Paddle"
+ *       appName="Kastlan"
+ *     />
+ *
+ * Resolves with the way it went.
+ */
+export async function openProviderPage(
+  fetchUrl: () => Promise<string>,
+  options: OpenProviderPageOptions = {},
+): Promise<ProviderPageWay> {
+  const win = options.window ?? window;
+  let tab: Window | null;
+  try {
+    tab = win.open("about:blank", "_blank");
+  } catch {
+    tab = null;
+  }
+  if (tab) {
+    try {
+      // The provider's page must not reach back into the app.
+      tab.opener = null;
+    } catch {
+      /* a browser that guards `opener`: the tab is still ours to point */
+    }
+  }
+  let url: string;
+  try {
+    url = await fetchUrl();
+  } catch (error) {
+    tab?.close();
+    throw error;
+  }
+  if (tab && !tab.closed) {
+    tab.location.href = url;
+    return "new-tab";
+  }
+  win.location.assign(url);
+  return "same-tab";
+}