@cosmoops/connect-sdk 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -3,6 +3,117 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.34.0
+
+Getting a blocked customer unblocked, and getting them back afterwards - plus
+the field the deletion events were missing. No new resources: two of these are
+the places the subscription journey dead-ended, and the third is a number your
+webhook handler had no way to read.
+
+### `<ConnectAccessGate>` no longer strands people in a second tab
+
+The `subscription_missing` card's button used to `window.open(resolveUrl,
+"_blank")`. The customer subscribed over there, was left on Connect's billing
+page with nothing pointing home, and the tab they started in still showed
+"Choose a plan to continue" - unchanged, because nothing re-reads entitlements
+on its own. The usual ending was two open tabs and the belief that the payment
+had not gone through.
+
+Now it is a **same-tab navigation carrying `?next=`** back to the page they
+were standing on. Connect honours it after the subscribe when the origin
+matches one registered for your Connect client, so the customer lands back
+exactly where they were, subscribed.
+
+Register your app's origin in Console if you have not - an unregistered one
+costs the return trip, nothing more. They still reach Connect, still resolve
+the blocker, and:
+
+**A blocked gate now re-checks when the tab regains focus.** Covers everything
+the return trip cannot: a second tab, a colleague with the admin rights, a
+payment settled on a phone. Only while blocked - a `clear` gate does not put a
+request on the critical path of alt-tabbing back into a working app.
+
+`useConnectAccessGate()` gained a `refresh()` for the cases your app learns of
+a change some other way.
+
+### `buildCheckoutUrl({ next })`
+
+Where Connect sends the customer once the subscription is live:
+
+```ts
+buildCheckoutUrl({
+  appUrl,
+  applicationId,
+  planId,
+  next: window.location.href,   // back to your pricing page, subscribed
+});
+```
+
+Without it the default destination is the new subscription's own billing page
+- right for someone who started in Connect, wrong for someone who started on
+your pricing page. Connect validates the origin against your registered
+redirect URIs and ignores anything else, so an unrecognised value costs the
+return trip and can never redirect your customer somewhere you did not
+register.
+
+### `useConnectResource().refetch()` actually refetches
+
+It only re-ran the effect, on the assumption the caller had just evicted the
+cache entry itself through `mutateResource`. The provider's cache is a `Map`
+of resolved promises with no expiry, so a `refetch()` on its own re-read the
+same settled promise and reported the same stale answer forever. It now evicts
+first. Still safe after a `mutateResource` against the same path.
+
+### Note for applications that cannot be used without a plan
+
+If your application is unusable without a subscription, the better fix is on
+Connect's side and needs no SDK change: a platform admin turns on **"Require a
+subscription to sign in"** on your Connect client. Plan selection then happens
+*inside* the sign-in handshake - the customer picks a plan, free tier first,
+and is handed back to you automatically - instead of them arriving signed-in
+and hitting this gate at all. The gate stays as the backstop for a
+subscription that lapses mid-use, which is what the changes above are for.
+
+
+### The deletion events carry your retention policy
+
+`workspace.deletion_scheduled` and `workspace.deleted` now include `policy`:
+your application's own data policy, frozen as it stood when the customer
+confirmed the deletion.
+
+```ts
+"workspace.deleted": async ({ workspaceId, policy }) => {
+  for (const dataClass of policy?.dataClasses ?? []) {
+    if (dataClass.disposition === "retain") {
+      await archive(workspaceId, dataClass.key, dataClass.retainDays);
+    }
+  }
+}
+```
+
+Before this, the two events carried `purgeAfter` and `graceDays` — Connect's
+clock — and nothing about yours. The number a handler actually acts on is
+`retainDays` per data class (and `quarantineDays` per held identifier), and
+that was the one number never on the wire: every integration had to re-declare
+in code what it had already declared in Console, where the two drift the first
+time somebody edits the policy and nothing fails.
+
+`policy` is per recipient — a deletion fans out to every application the
+workspace subscribed to, and each receives only its own declaration. It is the
+*clamped*, *versioned* snapshot: `version` names the policy the customer was
+shown, and the numbers are the ones Connect promised them rather than whatever
+your stored policy says today. `null` only for a deletion confirmed before
+policies existed; an application that has declared nothing gets empty arrays,
+never a missing key.
+
+New types: `ConnectDeletionPolicyNotice`, `ConnectDataClassNotice`,
+`ConnectResourceReleaseNotice`, `ConnectDataDisposition`,
+`ConnectFiduciaryRole`.
+
+Also corrected: `requestedBy` on `workspace.deletion_scheduled` is
+`"owner" | "platform_admin"` — which path the request came in on. The payload
+example in Console had been showing a user id, which is not on the wire.
+
 ## 0.33.0
 
 Two additions: the public visitor assistant, and `connect.enrichment.presence()`.

package/README.md

@@ -2,7 +2,7 @@
 
 Official client for the **CosmoOps Connect application-partner API** (`/api/v1/application/*`).
 
-**Current version: `0.20.0`** · [Release notes](#release-notes) · [Full changelog](./CHANGELOG.md)
+**Current version: `0.33.0`** · [Release notes](#release-notes) · [Full changelog](./CHANGELOG.md)
 — follows semver with the 0.x convention that a **minor** version may carry a
 breaking change (a patch never does). Read the release notes for your target
 version before upgrading past a minor bump.
@@ -12,7 +12,7 @@ npm install @cosmoops/connect-sdk
 npm install streamdown   # optional — Ask AI's markdown renderer, see step 4
 ```
 
-Five entry points, and the split is a security boundary, not a preference:
+Six entry points, and the split is a security boundary, not a preference:
 
 | Import | Runs in | Holds the API key |
 | --- | --- | --- |
@@ -20,8 +20,12 @@ Five entry points, and the split is a security boundary, not a preference:
 | `@cosmoops/connect-sdk/client` | the browser | never |
 | `@cosmoops/connect-sdk/next` | your backend | **yes** (Next.js plug-and-play) |
 | `@cosmoops/connect-sdk/mcp` | your backend | **yes** (store, as MCP tools) |
+| `@cosmoops/connect-sdk/ui` | either | never (presentational, no `"use client"`) |
 | `@cosmoops/connect-sdk` | anywhere | types + `ConnectError` only |
 
+Plus `@cosmoops/connect-sdk/theme.css`, which is not code: the one shared
+HeroUI theme the components are drawn against.
+
 The browser half never sees a credential. It calls your own origin, and
 `createConnectHandler` — mounted in your backend — is what talks to Connect.
 
@@ -49,8 +53,14 @@ npm install @cosmoops/connect-sdk
 | --- | --- | --- |
 | `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 | a non-production Connect instance; unset means `https://connect.cosmoops.com` |
+| `CONNECT_SESSION_COOKIE` | no | session cookie name; unset means `connect_session` |
+
+Production is the absence of configuration — set `CONNECT_APP_URL` only when
+you mean somewhere else. Note that it is **server-side**: `ConnectProvider`
+defaults `appUrl` to the production origin on its own, so an app pointed at a
+local instance must pass `appUrl` too or its portal links and its sign-in
+redirect will go to production. See [Environments](https://connect.cosmoops.com/docs/environments).
 
 **3. Mount the bridge route.** One file, no arguments — this is your entire backend integration:
 
@@ -919,7 +929,9 @@ So the hand-off is a URL, and Connect renders it as a modal over the relevant pa
 
 ## Release notes
 
-Full history: [CHANGELOG.md](./CHANGELOG.md). Latest first:
+**[CHANGELOG.md](./CHANGELOG.md) is the current and complete history**, through
+`0.33.0`. What follows is an older excerpt, kept for the migration notes in it, and
+it stops at `0.20.0` — read the changelog for anything newer.
 
 ### 0.20.0
 

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

@@ -40,7 +40,19 @@ function formatDate(iso) {
  */
 function useConnectAccessGate() {
     const { session, isLoading: sessionLoading } = (0, provider_js_1.useConnect)();
-    const { data, isLoading: entitlementsLoading } = (0, provider_js_1.useConnectEntitlements)();
+    const { data, isLoading: entitlementsLoading, refetch } = (0, provider_js_1.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 };
     }
@@ -151,6 +163,49 @@ function useConnectAccessGate() {
  */
 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.
+     */
+    (0, react_1.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.
@@ -219,9 +274,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 ((0, jsx_runtime_1.jsx)(motion_js_1.MotionProvider, { children: (0, jsx_runtime_1.jsx)(motion_js_1.m.div, { initial: { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, transition: motion_js_1.ENTER, children: (0, jsx_runtime_1.jsxs)(react_2.Card, { className: className, children: [(0, jsx_runtime_1.jsxs)(react_2.Card.Header, { children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-2", children: [(0, jsx_runtime_1.jsx)(Icon, { className: `size-5 shrink-0 ${iconClassName}`, "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)(react_2.Card.Title, { children: title })] }), (0, jsx_runtime_1.jsx)(react_2.Card.Description, { children: message })] }), resolveUrl && ((0, jsx_runtime_1.jsx)(react_2.Card.Footer, { children: (0, jsx_runtime_1.jsxs)(react_2.Button, { variant: "primary", onPress: () => window.open(resolveUrl, "_blank", "noopener,noreferrer"), children: [actionLabel ?? "Resolve on Connect", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5" })] }) }))] }) }) }));
+    return ((0, jsx_runtime_1.jsx)(motion_js_1.MotionProvider, { children: (0, jsx_runtime_1.jsx)(motion_js_1.m.div, { initial: { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, transition: motion_js_1.ENTER, children: (0, jsx_runtime_1.jsxs)(react_2.Card, { className: className, children: [(0, jsx_runtime_1.jsxs)(react_2.Card.Header, { children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-2", children: [(0, jsx_runtime_1.jsx)(Icon, { className: `size-5 shrink-0 ${iconClassName}`, "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)(react_2.Card.Title, { children: title })] }), (0, jsx_runtime_1.jsx)(react_2.Card.Description, { children: message })] }), resolveUrl && ((0, jsx_runtime_1.jsx)(react_2.Card.Footer, { children: (0, jsx_runtime_1.jsxs)(react_2.Button, { variant: "primary", onPress: () => window.location.assign(withReturnTo(resolveUrl)), children: [actionLabel ?? "Resolve on Connect", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5" })] }) }))] }) }) }));
 }
 /**
  * The skippable payment-due warning. Dismissal is scoped to this specific
@@ -240,3 +313,26 @@ function PaymentRetryBanner({ blocker, className, }) {
                                     window.localStorage.setItem(dismissKey, "1");
                             }, children: (0, jsx_runtime_1.jsx)(lucide_react_1.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/cjs/client/provider.js

@@ -503,7 +503,7 @@ function useConnectSessions() {
  */
 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.
@@ -543,6 +543,9 @@ 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/cjs/client/use-checkout.js

@@ -166,12 +166,14 @@ 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.
  */
-function buildCheckoutUrl({ appUrl, applicationId, planId, subscriptionId, coupon, }) {
+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/cjs/helpers.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_PLAN_LIMIT = void 0;
 exports.blockingBlockers = blockingBlockers;
 exports.normalizePlanFeatures = normalizePlanFeatures;
+exports.planLimitFor = planLimitFor;
+exports.planLimitAllows = planLimitAllows;
 /**
  * The blockers that actually deny access, in the order to show them.
  *
@@ -28,3 +31,46 @@ function blockingBlockers(readiness) {
 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.
+ */
+exports.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.
+ */
+function planLimitFor(limits, key) {
+    return limits?.[key] ?? exports.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.");
+ * }
+ * ```
+ */
+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/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.storeIndexCovers = exports.describeQueryRejection = exports.unchangedSince = exports.storeIndexSignature = exports.storeIndexFor = exports.serverTimestamp = exports.increment = exports.documentExists = exports.deleteField = exports.arrayUnion = exports.arrayRemove = exports.normalizePlanFeatures = exports.blockingBlockers = exports.isConnectError = exports.ConnectError = void 0;
+exports.storeIndexCovers = exports.describeQueryRejection = exports.unchangedSince = exports.storeIndexSignature = exports.storeIndexFor = exports.serverTimestamp = exports.increment = exports.documentExists = exports.deleteField = exports.arrayUnion = exports.arrayRemove = exports.planLimitFor = exports.planLimitAllows = exports.NO_PLAN_LIMIT = exports.normalizePlanFeatures = exports.blockingBlockers = exports.isConnectError = exports.ConnectError = void 0;
 /**
  * `@cosmoops/connect-sdk` - the official client for the CosmoOps Connect
  * **application-partner API** (`/api/v1/application/*`).
@@ -22,6 +22,10 @@ Object.defineProperty(exports, "isConnectError", { enumerable: true, get: functi
 var helpers_js_1 = require("./helpers.js");
 Object.defineProperty(exports, "blockingBlockers", { enumerable: true, get: function () { return helpers_js_1.blockingBlockers; } });
 Object.defineProperty(exports, "normalizePlanFeatures", { enumerable: true, get: function () { return helpers_js_1.normalizePlanFeatures; } });
+var helpers_js_2 = require("./helpers.js");
+Object.defineProperty(exports, "NO_PLAN_LIMIT", { enumerable: true, get: function () { return helpers_js_2.NO_PLAN_LIMIT; } });
+Object.defineProperty(exports, "planLimitAllows", { enumerable: true, get: function () { return helpers_js_2.planLimitAllows; } });
+Object.defineProperty(exports, "planLimitFor", { enumerable: true, get: function () { return helpers_js_2.planLimitFor; } });
 var store_js_1 = require("./store.js");
 Object.defineProperty(exports, "arrayRemove", { enumerable: true, get: function () { return store_js_1.arrayRemove; } });
 Object.defineProperty(exports, "arrayUnion", { enumerable: true, get: function () { return store_js_1.arrayUnion; } });

package/dist/cjs/next/index.js

@@ -79,11 +79,18 @@ const errors_js_1 = require("../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/cjs/server/client.js

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

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

@@ -17,6 +17,10 @@ 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 (0, http_js_1.request)(this.transport, { method: "GET", path: "/plans" });
@@ -24,6 +28,7 @@ class BillingResource {
             plans: (response.plans ?? []).map((plan) => ({
                 ...plan,
                 features: (0, helpers_js_1.normalizePlanFeatures)(plan.features),
+                limits: plan.limits ?? [],
             })),
         };
     }

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EntitlementsResource = void 0;
 const http_js_1 = require("../http.js");
+const helpers_js_1 = require("../../helpers.js");
 /**
  * The two checks worth making on every request: may this workspace be here at
  * all, and what is it paying for.
@@ -45,6 +46,52 @@ 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 helpers_js_1.NO_PLAN_LIMIT;
+        return (0, helpers_js_1.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 (0, helpers_js_1.planLimitAllows)(await this.getLimit(workspaceId, key), currentCount, additional);
+    }
     /**
      * One page of the workspaces subscribed to your application, newest first.
      *