@lessly/sdk-app 93.0.0 → 94.1.0

package/docs/README.md

@@ -74,6 +74,7 @@ you need to touch it directly.
 | `recipes/sdk-usage.md` | You need to call the platform API: creating the SDK client, handling `LesslyApiError`, using the generated `*QueryOptions`/`*MutationOptions` factories. |
 | `recipes/federation.md` | You're touching the Module Federation setup: shared singletons, the dual-mode build, or the dual-mode CSS graph (the federation vs standalone stylesheets). |
 | `recipes/access.md` | You're gating UI on the caller's permissions: `app.access`, `useCan`, and rendering a 403 as an empty state rather than an error (APP-012). |
+| `recipes/entitlements.md` | A call can fail with a 402 `entitlement_exhausted` / `entitlement_unavailable` (the organization reached its plan): `isEntitlementError` inside the shell, `upgradeUrl` outside it. |
 | `recipes/local-dev.md` | You're running the app locally: the dev proxy, device-code login, `.env.local`, or composing your app under a local shell. |
 
 ## Keeping this guide current

package/docs/recipes/entitlements.md

@@ -0,0 +1,96 @@
+# Recipe: the billing refusal (HTTP 402 `entitlement_exhausted` / `entitlement_unavailable`)
+
+Some operations consume something the organization pays for — emails, storage,
+a managed database. Before such an operation the toolkit asks billing whether
+the organization's plan allows it. When it does not, the call fails with
+**HTTP 402** and this body:
+
+```json
+{
+  "error": "entitlement_exhausted",
+  "reason": "trial_cap_reached",
+  "meter": "…",
+  "pool": "…",
+  "limit": 3000,
+  "used": 3000,
+  "requested": 1,
+  "plan": "trial",
+  "upgrade_url": "<Workspace web origin>/organization/billing?upgrade=pro&org=<org_id>"
+}
+```
+
+| Field | Values |
+| --- | --- |
+| `error` | `entitlement_exhausted` (every reason except `trial_class_unavailable`), `entitlement_unavailable` |
+| `reason` | `trial_cap_reached`, `trial_class_unavailable`, `billing_paused`, `budget_paused` |
+| `plan` | `trial`, `pro`, `enterprise`, `none` |
+
+This is not your App's error and not the user's mistake: it is the organization
+reaching the edge of its plan. **The Workspace shell shows it** — one window,
+with the reason and a path to Pro — for every federated App and for its own
+calls. Your App renders nothing for it.
+
+---
+
+## 1. Inside the shell: recognise it, render nothing
+
+```tsx
+import { isAccessDenied, isEntitlementError } from '@lepsto/sdk-app';
+
+function RequestError({ error }: { error: unknown }) {
+  // The shell already opened its refusal window. A second error here is a duplicate.
+  if (isEntitlementError(error)) return null;
+  if (isAccessDenied(error)) return <EmptyState title="You don't have access to this" />;
+  return <ErrorState error={error} />;
+}
+```
+
+Put the branch in the one shared component that classifies errors (see
+`access.md` §3 — state keeps the error *object*, never its message).
+`isEntitlementError` is true for exactly the rule the shell uses: status `402`
+and a body `error` of `entitlement_exhausted` or `entitlement_unavailable`. Any other 402 — a toolkit's
+own payment failure — is false and stays yours to show.
+
+Like `isAccessDenied`, it reads `status` and `body` structurally, so an error
+thrown by another copy of this SDK on the page is recognised too.
+
+## 2. Outside the shell: link to the upgrade path
+
+A standalone App, or an App calling through its own `fetch`, is invisible to the
+shell. Show a short notice with the link from `upgradeUrl(err)`:
+
+```tsx
+import { upgradeUrl } from '@lepsto/sdk-app';
+
+const href = upgradeUrl(error);
+if (href) {
+  return (
+    <Notice>
+      Your organization has reached its plan limit. <a href={href}>Upgrade to Pro</a>
+    </Notice>
+  );
+}
+```
+
+With your own `fetch`, pass the status and the parsed body:
+
+```ts
+const res = await fetch(url, init);
+if (!res.ok) {
+  const err = { status: res.status, body: await res.json().catch(() => null) };
+  if (isEntitlementError(err)) showUpgradeNotice(upgradeUrl(err));
+}
+```
+
+`upgradeUrl` returns the URL billing sent, unchanged, and `null` when the error
+is not an entitlement refusal or the URL is not an absolute `http(s)` URL. Never
+build this URL yourself — it names the refused organization.
+
+## What not to do
+
+- **Do not retry** the refused call in a loop. Nothing changes until the
+  organization upgrades or the next period starts.
+- **Do not cache** the refusal. After an upgrade the next call succeeds.
+- **Do not render it red**, and inside the shell do not render it at all.
+- **Do not branch on `reason`** to decide *whether* to show something — that is
+  `isEntitlementError`. `reason`, `used` and `limit` are for wording only.

package/docs/recipes/sdk-usage.md

@@ -71,6 +71,11 @@ try {
 }
 ```
 
+A **402** whose body `error` is `entitlement_exhausted` or
+`entitlement_unavailable` is billing refusing the
+call over the organization's plan. The Workspace shell shows it; see
+`entitlements.md` for `isEntitlementError` and `upgradeUrl`.
+
 ### Missing CSRF cookie
 
 Mutating calls (`POST`, `PUT`, `PATCH`, `DELETE`) require the `lepsto_csrf`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lessly/sdk-app",
   "description": "The Lessly SDK for App is a TypeScript SDK that provides runtime bindings and type-safe generated code for interacting with Lessly Platform APIs and services. This package generates type definitions and client bindings from API catalogs, enabling developers to build applications that consume Lessly platform services with full type safety and autocompletion.",
-  "version": "93.0.0",
+  "version": "94.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lepsto/lepsto-sdk-app.git"