@cosmoops/connect-sdk 0.33.0 → 0.34.0

package/dist/esm/client/components/access-gate.js

@@ -1,6 +1,6 @@
 "use client";
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { Ban, AlertTriangle, Building2, Clock, CreditCard, ExternalLink, User, X } from "lucide-react";
 import { Button, Card } from "@heroui/react";
 import { blockingBlockers } from "../../helpers.js";
@@ -36,7 +36,19 @@ function formatDate(iso) {
  */
 export function useConnectAccessGate() {
     const { session, isLoading: sessionLoading } = useConnect();
-    const { data, isLoading: entitlementsLoading } = useConnectEntitlements();
+    const { data, isLoading: entitlementsLoading, refetch } = useConnectEntitlements();
+    return { ...decideAccess(session, sessionLoading, data, entitlementsLoading), refresh: refetch };
+}
+/**
+ * The priority ordering, with the reads lifted out.
+ *
+ * Split from the hook so the twelve verdicts stay one `return` each and none
+ * of them has to carry `refresh` - a field that is the same function in every
+ * branch and says nothing about which branch it is. Pure, like
+ * `rbac/policy.ts` and `evaluateSignInRisk`, and for the same reason: a
+ * decision spread across its inputs cannot be tested.
+ */
+function decideAccess(session, sessionLoading, data, entitlementsLoading) {
     if (sessionLoading) {
         return { state: "loading", blocker: null, paymentRetry: null };
     }
@@ -147,6 +159,49 @@ export function useConnectAccessGate() {
  */
 export function ConnectAccessGate({ children, fallback, loading, className }) {
     const gate = useConnectAccessGate();
+    const isBlocked = gate.state !== "loading" &&
+        gate.state !== "signed_out" &&
+        gate.state !== "clear" &&
+        gate.state !== "payment_retry";
+    /**
+     * A blocked gate re-checks when the tab comes back.
+     *
+     * Every blocker this component draws is resolved **somewhere else** - on
+     * Connect, in another tab, by an admin, on a phone - and none of that
+     * reaches this tab. The resolve button used to open Connect in a new tab,
+     * so the overwhelmingly common path was: subscribe over there, switch back,
+     * and find the same "Choose a plan to continue" card, with a reload the
+     * only way out. It read as the purchase not having worked.
+     *
+     * The button is a same-tab navigation now (see `GateCard`), which handles
+     * the common case on its own. This covers the rest: a second tab, a
+     * colleague with the admin rights, a payment settled on a phone.
+     *
+     * Only while blocked, deliberately. A `clear` gate re-reading entitlements
+     * on every tab focus would put a request on the critical path of
+     * alt-tabbing back into an application that is working fine, for every
+     * workspace, all day. Nothing is gained by it: the gate has nothing to
+     * show, and losing access mid-session is what the server-side check before
+     * each action is for.
+     */
+    useEffect(() => {
+        if (!isBlocked || typeof document === "undefined")
+            return;
+        const recheck = () => {
+            if (document.visibilityState === "visible")
+                gate.refresh();
+        };
+        document.addEventListener("visibilitychange", recheck);
+        window.addEventListener("focus", recheck);
+        return () => {
+            document.removeEventListener("visibilitychange", recheck);
+            window.removeEventListener("focus", recheck);
+        };
+        // `gate.refresh` is stable per render of the provider and re-subscribing
+        // on it would churn the listeners; `isBlocked` is the only thing that
+        // should add or remove them.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [isBlocked]);
     // `children`, unless the host explicitly asked for a placeholder. See the
     // doc comment - this is the branch that decides whether a partner's page
     // can stream.
@@ -215,9 +270,27 @@ function AccessGateFallback({ state, blocker, className, }) {
  * so "see plans" landing back on the same blocked screen never gets anyone
  * to a choice they can act on. Sending them to Connect's own subscribe page
  * always resolves.
+ *
+ * ### Same tab, and it carries the way back
+ *
+ * It used to `window.open(resolveUrl, "_blank")`. A new tab is the wrong
+ * shape for a step you have to finish before you can continue: the customer
+ * subscribes over there, is left on Connect's billing page with nothing
+ * pointing home, and the tab they started in is still showing this card. The
+ * most common ending was two open tabs and the belief that the payment had
+ * not worked.
+ *
+ * So: a same-tab navigation carrying `?next=` back to the page they are
+ * standing on, which Connect honours after a subscribe once the origin
+ * matches one registered for this application's client
+ * (`resolveApplicationReturnUrl`). An unregistered origin costs the return
+ * trip and nothing else - they still reach Connect, still resolve the
+ * blocker, and `ConnectAccessGate`'s focus re-check catches them on the way
+ * back. Partners should register their app's origin; the fallback is a
+ * degraded path, not a broken one.
  */
 function GateCard({ icon: Icon, iconClassName, title, message, actionLabel, resolveUrl, className, }) {
-    return (_jsx(MotionProvider, { children: _jsx(m.div, { initial: { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, transition: ENTER, children: _jsxs(Card, { className: className, children: [_jsxs(Card.Header, { children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Icon, { className: `size-5 shrink-0 ${iconClassName}`, "aria-hidden": "true" }), _jsx(Card.Title, { children: title })] }), _jsx(Card.Description, { children: message })] }), resolveUrl && (_jsx(Card.Footer, { children: _jsxs(Button, { variant: "primary", onPress: () => window.open(resolveUrl, "_blank", "noopener,noreferrer"), children: [actionLabel ?? "Resolve on Connect", _jsx(ExternalLink, { className: "size-3.5" })] }) }))] }) }) }));
+    return (_jsx(MotionProvider, { children: _jsx(m.div, { initial: { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, transition: ENTER, children: _jsxs(Card, { className: className, children: [_jsxs(Card.Header, { children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Icon, { className: `size-5 shrink-0 ${iconClassName}`, "aria-hidden": "true" }), _jsx(Card.Title, { children: title })] }), _jsx(Card.Description, { children: message })] }), resolveUrl && (_jsx(Card.Footer, { children: _jsxs(Button, { variant: "primary", onPress: () => window.location.assign(withReturnTo(resolveUrl)), children: [actionLabel ?? "Resolve on Connect", _jsx(ExternalLink, { className: "size-3.5" })] }) }))] }) }) }));
 }
 /**
  * The skippable payment-due warning. Dismissal is scoped to this specific
@@ -236,3 +309,26 @@ function PaymentRetryBanner({ blocker, className, }) {
                                     window.localStorage.setItem(dismissKey, "1");
                             }, children: _jsx(X, { className: "size-4" }) })] })] }) }));
 }
+/**
+ * `resolveUrl` with `?next=` pointing at the page the customer is standing
+ * on, so Connect can hand them back once the blocker is gone.
+ *
+ * Returns the URL untouched if anything is off - no `window`, an unparseable
+ * `resolveUrl`, a `next` already set by the server. Getting back is a
+ * courtesy on top of resolving the blocker, and it must never be the reason
+ * somebody cannot reach the screen that resolves it.
+ */
+function withReturnTo(resolveUrl) {
+    if (typeof window === "undefined")
+        return resolveUrl;
+    try {
+        const url = new URL(resolveUrl);
+        if (url.searchParams.has("next"))
+            return resolveUrl;
+        url.searchParams.set("next", window.location.href);
+        return url.toString();
+    }
+    catch {
+        return resolveUrl;
+    }
+}

package/dist/esm/client/provider.js

@@ -483,7 +483,7 @@ export function useConnectSessions() {
  */
 export function useConnectResource(path, options) {
     const requiresSession = options?.requiresSession ?? true;
-    const { fetchResource, session, isLoading: sessionLoading } = useConnect();
+    const { fetchResource, invalidateResource, session, isLoading: sessionLoading } = useConnect();
     // Stamped with the `path` it belongs to, so switching paths reports loading
     // without a synchronous `setIsLoading(true)` - and, more usefully, so a
     // resolved response for a previous path can never be read as this one's.
@@ -523,6 +523,9 @@ export function useConnectResource(path, options) {
         // should render its signed-out state, not skeletons forever.
         isLoading: !signedOut && !loaded,
         error: loaded?.error ?? null,
-        refetch: () => setVersion((v) => v + 1),
+        refetch: () => {
+            invalidateResource(path);
+            setVersion((v) => v + 1);
+        },
     };
 }

package/dist/esm/client/use-checkout.js

@@ -161,12 +161,14 @@ export function buildCancelUrl({ appUrl, subscriptionId }) {
  * prefix that has never served this page. Building the other one is what
  * sent every first-time subscriber from a partner's pricing page to a 404.
  */
-export function buildCheckoutUrl({ appUrl, applicationId, planId, subscriptionId, coupon, }) {
+export function buildCheckoutUrl({ appUrl, applicationId, planId, subscriptionId, coupon, next, }) {
     const path = subscriptionId
         ? `/billing/subscriptions/${encodeURIComponent(subscriptionId)}/change-plan/${encodeURIComponent(planId)}`
         : `/apps/${encodeURIComponent(applicationId)}/subscribe/${encodeURIComponent(planId)}`;
     const url = new URL(path, appUrl);
     if (coupon?.trim())
         url.searchParams.set("coupon", coupon.trim());
+    if (next?.trim())
+        url.searchParams.set("next", next.trim());
     return url.toString();
 }

package/dist/esm/helpers.js

@@ -24,3 +24,46 @@ export function blockingBlockers(readiness) {
 export function normalizePlanFeatures(features) {
     return (features ?? []).map((feature) => typeof feature === "string" ? { key: feature, name: feature, description: "" } : feature);
 }
+/**
+ * What a key the plan carries no answer for reads as - see
+ * `SubscribedPlan.limits`, which is sparse.
+ *
+ * `"none"` rather than `"unlimited"`: a plan that was never asked about a
+ * limit has not sold it, and defaulting the other way would hand an unbounded
+ * allowance to every tier that predates the question.
+ */
+export const NO_PLAN_LIMIT = { model: "none", value: null };
+/**
+ * One plan's answer for one limit key, with the sparse-map default applied.
+ *
+ * Indexing `plan.limits` directly is what makes a missing key `undefined`,
+ * which then reads as unlimited through the first `?.` somebody writes. This
+ * returns a `PlanLimit` either way.
+ */
+export function planLimitFor(limits, key) {
+    return limits?.[key] ?? NO_PLAN_LIMIT;
+}
+/**
+ * Whether `additional` more of the resource fit under this limit, given how
+ * many the subscriber already has. The comparison, written once.
+ *
+ * Every way of writing it at a call site is wrong in a different direction:
+ * `count < limit.value` is off by one as soon as you add more than one row,
+ * `if (!limit.value)` refuses the unlimited tier, and
+ * `limit.value ?? Infinity` grants unlimited to a plan that allows none. This
+ * is the same implementation Connect's own server uses to validate a plan.
+ *
+ * ```ts
+ * const limit = await connect.entitlements.getLimit(workspaceId, "sites");
+ * if (!planLimitAllows(limit, await countSites(workspaceId))) {
+ *   throw new Error("Your plan's site limit is reached.");
+ * }
+ * ```
+ */
+export function planLimitAllows(limit, currentCount, additional = 1) {
+    if (limit.model === "unlimited")
+        return true;
+    if (limit.model === "none")
+        return false;
+    return currentCount + additional <= (limit.value ?? 0);
+}

package/dist/esm/index.js

@@ -15,5 +15,6 @@
  */
 export { ConnectError, isConnectError } from "./errors.js";
 export { blockingBlockers, normalizePlanFeatures } from "./helpers.js";
+export { NO_PLAN_LIMIT, planLimitAllows, planLimitFor } from "./helpers.js";
 export { arrayRemove, arrayUnion, deleteField, documentExists, increment, serverTimestamp, storeIndexFor, storeIndexSignature, unchangedSince, } from "./store.js";
 export { describeQueryRejection, storeIndexCovers } from "./store-schema.js";

package/dist/esm/next/index.js

@@ -35,11 +35,18 @@ import { ConnectError } from "../errors.js";
  * | --- | --- | --- |
  * | `CONNECT_API_KEY` | yes | server-side credential |
  * | `CONNECT_CLIENT_ID` | yes | OAuth client id |
- * | `CONNECT_APP_URL` | no | non-production Connect instance |
- * | `CONNECT_SESSION_COOKIE` | no | session cookie name |
+ * | `CONNECT_APP_URL` | no | non-production Connect instance; unset means production |
+ * | `CONNECT_SESSION_COOKIE` | no | session cookie name; unset means `connect_session` |
+ *
+ * `CONNECT_APP_URL` is server-side only and does not reach the browser:
+ * `ConnectProvider` defaults `appUrl` to the production origin independently,
+ * so an app pointed at another instance must pass that prop as well or its
+ * portal links and its browser-built authorize URL still go to production.
  *
  * Register `{your origin}/api/connect/callback` as a redirect URI in the
- * application's Connect client section. That is the only step this cannot do for you.
+ * application's Connect client section. That is the only step this cannot do
+ * for you, and Connect matches it exactly - every origin you run from needs
+ * its own entry, localhost included.
  *
  * No `next.config.ts` changes needed either, including `transpilePackages`:
  * `dist/` is already ES2022 with `"use client"` hoisted to the top of every

package/dist/esm/server/client.js

@@ -175,4 +175,4 @@ export class ConnectClient {
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.32.0";
+export const SDK_VERSION = "0.34.0";

package/dist/esm/server/resources/billing.js

@@ -14,6 +14,10 @@ export class BillingResource {
      * independently of the instance it talks to. Without the coercion a partner
      * pointed at a Connect that has not upgraded yet renders a feature list of
      * blanks - which is exactly what happened. See `normalizePlanFeatures`.
+     *
+     * `limits` is defaulted for the same reason, one version later: an instance
+     * that predates limits sends no such field, and a pricing grid mapping over
+     * `plan.limits` would throw rather than simply show no limit rows.
      */
     async listPlans() {
         const response = await request(this.transport, { method: "GET", path: "/plans" });
@@ -21,6 +25,7 @@ export class BillingResource {
             plans: (response.plans ?? []).map((plan) => ({
                 ...plan,
                 features: normalizePlanFeatures(plan.features),
+                limits: plan.limits ?? [],
             })),
         };
     }

package/dist/esm/server/resources/entitlements.js

@@ -1,4 +1,5 @@
 import { pathSegment, request } from "../http.js";
+import { NO_PLAN_LIMIT, planLimitAllows, planLimitFor } from "../../helpers.js";
 /**
  * The two checks worth making on every request: may this workspace be here at
  * all, and what is it paying for.
@@ -42,6 +43,52 @@ export class EntitlementsResource {
         const result = await this.getSubscription(workspaceId);
         return result.hasActiveSubscription && (result.plan?.features.includes(feature) ?? false);
     }
+    /**
+     * How much of a metered resource this workspace may have - the numeric
+     * counterpart of `hasFeature`, for the resources your application counts
+     * itself (sites, projects, pipelines).
+     *
+     * **This is the effective ceiling, not the plan's own number.** Connect has
+     * already folded in whatever the add-ons on the subscription raise it by, so
+     * "Starter includes 1 site, they bought two 5-site packs" arrives here as
+     * `{ model: "limited", value: 11 }`. You never join the plan against the
+     * add-on list yourself, and a customer who buys another pack needs no change
+     * on your side.
+     *
+     * Returns `{ model: "none" }` rather than throwing when there is no active
+     * subscription, when the plan carries no answer for this key, and when the
+     * Connect instance predates limits entirely - the same reasoning
+     * `hasFeature` gives for answering `false`: "not entitled" is the same answer
+     * either way, and a limit check should not need a try/catch around it.
+     *
+     * Connect does not enforce this. It cannot see what you are counting, so it
+     * hands you the number and your code refuses the next row - `canAdd` is that
+     * comparison if you already have the count.
+     */
+    async getLimit(workspaceId, key) {
+        const result = await this.getSubscription(workspaceId);
+        if (!result.hasActiveSubscription)
+            return NO_PLAN_LIMIT;
+        return planLimitFor(result.plan?.limits, key);
+    }
+    /**
+     * Whether this workspace may add `additional` more of a limited resource,
+     * given how many it already has.
+     *
+     * You supply the count, because only your application can produce it. This
+     * is `getLimit` plus `planLimitAllows`, which exists so the comparison is
+     * not rewritten per call site - see that helper for the three ways of
+     * getting it wrong.
+     *
+     * ```ts
+     * if (!(await connect.entitlements.canAdd(workspaceId, "sites", sites.length))) {
+     *   return refuse("Your plan's site limit is reached.");
+     * }
+     * ```
+     */
+    async canAdd(workspaceId, key, currentCount, additional = 1) {
+        return planLimitAllows(await this.getLimit(workspaceId, key), currentCount, additional);
+    }
     /**
      * One page of the workspaces subscribed to your application, newest first.
      *

package/dist/types/client/components/access-gate.d.ts

@@ -23,6 +23,15 @@ export type ConnectAccessGateState = "loading"
  | "clear";
 export interface ConnectAccessGateResult {
     state: ConnectAccessGateState;
+    /**
+     * Re-reads entitlements, evicting the cached answer first.
+     *
+     * Exposed because a blocker is almost always resolved **somewhere this tab
+     * cannot see** - on Connect, in another tab or on a phone - and nothing
+     * about that reaches this one. The gate wires it to the tab regaining
+     * focus; call it yourself if your app learns of a change some other way.
+     */
+    refresh(): void;
     /** The blocker driving a hard-block state (`suspended`/`no_subscription`/`onboarding_pending`/`blocked`). `null` otherwise. */
     blocker: ReadinessBlocker | null;
     /** The `payment_retry_pending` blocker, only when `state === "payment_retry"`. Carries `graceEndsAt`. */

package/dist/types/client/provider.d.ts

@@ -196,7 +196,21 @@ export interface ConnectProviderProps {
      * not a Connect URL - it is your backend that exchanges the code.
      */
     redirectUri?: string;
-    /** Override for non-production Connect instances. */
+    /**
+     * Override for non-production Connect instances. Defaults to
+     * `https://connect.cosmoops.com`.
+     *
+     * The twin of `CONNECT_APP_URL`, and *not* derived from it - that variable
+     * is read on your server and never reaches the browser. This value is where
+     * the user menu's Profile, Billing and Invoices destinations open, where
+     * `ConnectAppsGrid` sends an unsubscribed application, where checkout
+     * opens, and - if you pass `redirectUri` and so build the authorize URL
+     * here rather than in your own `/signin` route - where sign-in goes. Point
+     * the server somewhere else and leave this alone and the two halves
+     * disagree, so pass both or neither. Your root layout is a Server
+     * Component, so `appUrl={process.env.CONNECT_APP_URL}` is enough and needs
+     * no browser-visible variable.
+     */
     appUrl?: string;
     /**
      * Replace the `fetch` used to reach your bridge. The browser-side twin of
@@ -327,11 +341,20 @@ export declare function useConnectEntitlements(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -347,11 +370,20 @@ export declare function useConnectAddonUsage(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -361,11 +393,20 @@ export declare function useConnectPlans(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -384,11 +425,20 @@ export declare function useConnectCompanyProfile(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -400,11 +450,20 @@ export declare function useConnectApps(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -423,11 +482,20 @@ export declare function useConnectWorkspaces(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -442,11 +510,20 @@ export declare function useConnectWorkspaceMembers(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -456,11 +533,20 @@ export declare function useConnectIntegrations(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -476,11 +562,20 @@ export declare function useConnectSessions(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -512,11 +607,20 @@ export declare function useConnectResource<T>(path: string, options?: Readonly<U
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };