@cosmoops/connect-sdk 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -3,6 +3,257 @@
 `@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()`.
+
+### The visitor assistant
+
+A chat bubble for **your customers' own websites**, answered by Connect, for
+people who have no account anywhere. A visitor asks about that business, or
+books a call with them; your application holds no model credential and runs no
+AI infrastructure.
+
+Three calls drive a conversation and five manage what it is allowed to say:
+
+```ts
+const session = await connect.visitor.startSession({
+  workspaceId,          // which of your customers' sites this is
+  page: "/pricing",
+});
+
+const stream = await connect.visitor.chat({
+  sessionId: session.sessionId,
+  workspaceId,
+  message: "do you take walk-ins?",
+});
+```
+
+Needs an API key scoped to **`visitor:chat`**, and **`visitor:knowledge`** to
+manage the knowledge base. Both are workspace-scoped, so they carry the second
+check every workspace-wide scope carries: a live subscription to the workspace
+you name.
+
+**The assistant answers from a knowledge base you publish, and from nothing
+else.** `connect.visitor.knowledge.*` writes to a store that exists only for
+this purpose:
+
+```ts
+const item = await connect.visitor.knowledge.save({
+  workspaceId,
+  title: "Opening hours",
+  body: "Mon-Fri, 9 to 6. Closed on public holidays.",
+  source: "authored",
+});
+await connect.visitor.knowledge.publish({ workspaceId, itemId: item.id });
+```
+
+Five things to know before wiring it in, in the order they will bite you:
+
+**It is not the workspace's Context Index, and must never become it.** The
+corpus behind `ai.chat` is fed by every Drive upload a workspace makes —
+contracts, payroll, customer lists. Pointing a public widget at that would let
+a stranger extract an internal document, helpfully summarised. Nothing reaches
+the visitor store except through an explicit `publish`, and the assistant's
+read path has no route to the other corpus at all. Do not try to fill it by
+uploading to Drive; that is the invariant, not an inconvenience.
+
+**Publishing is its own call, and unpublishing can fail.** `save` always writes
+a draft, so no edit can make text public by accident. `unpublish` removes the
+retrievable copy *before* it flips the record, which means a failure leaves the
+item **still live** — surface the error and let them retry rather than greying
+the row out optimistically. For a retracted price, an item that looks withdrawn
+and is not is the most expensive bug this feature has.
+
+**Record `grounded: false` from the `done` event.** It means nothing published
+covered the question, so the assistant said so and offered a call instead of
+inventing an answer. A run of them is a knowledge base with a gap in it, which
+is the most useful signal this endpoint produces.
+
+**`mode` tells you how the knowledge reaches the model**, and `inline` is the
+good state. Below a size threshold the whole published set is carried in the
+prompt — the model sees every item rather than a top-k slice, with no chunk
+boundaries and no retrieval round trip. `retrieval` only begins once a
+knowledge base has outgrown that, and only then does `indexState` on each item
+matter.
+
+**The workspace is yours to resolve, not the browser's.** Connect checks the
+`workspaceId` you send against your own subscriptions, so the worst case is
+bounded to your own customers rather than the platform's. That is still one
+customer's budget spent from another's page, so if you serve several customers,
+resolve the workspace from your own widget record — the token in the embed
+snippet, say — rather than trusting a field a page supplied.
+
+`<ConnectVisitorChat>` in `./client` is the widget itself: a bubble that
+becomes a full-height sheet on a phone and an anchored panel above `sm`, with
+the composer's input type decided by the server rather than guessed from the
+reply — so an email field brings up a keyboard with an `@` on it and a
+verification code can be offered straight from the notification. It renders on
+a page with **no `ConnectProvider`**, which most marketing pages are, and it
+mints nothing until somebody opens it.
+
+Times offered for a call are drawn from the turn's tool result, never from the
+assistant's sentence, and the appointment is placed by a typed action rather
+than by the model — so it cannot book a time nobody offered, and a phone number
+never arrives parsed out of prose.
+
+### `connect.enrichment.presence()`
+
+`connect.enrichment.presence()` — how visible a business is online, scored out
+of 100.
+
+The third sibling of `company()` and `brand()`: that one answers what a
+business does, the other what it looks like, and this answers how findable it
+is — by a search engine, by a customer, and by the assistants that
+increasingly answer questions about a business before anybody visits its site.
+
+Returns the score, a breakdown across five categories, every check with the
+evidence behind it, every social profile linked from the site, and a
+prioritised list of what to fix.
+
+```ts
+const result = await connect.enrichment.presence({ domain: "acme.com" });
+if (result.status === "scanned") {
+  for (const next of result.scan.recommendations) {
+    console.log(`${next.priority}. ${next.title} — ${next.fix}`);
+  }
+}
+```
+
+Needs an API key scoped to **`enrichment:presence`**.
+
+Three things to know before wiring it in:
+
+**The score is computed, not generated.** Every point comes from a check run
+against something a fetcher actually observed, and every check ships with its
+weight, what was seen and the URL that settles it — so the total is
+reconstructable. A model only orders the recommendations and writes the prose;
+it cannot move the number. That is the whole reason this is worth showing a
+customer: ask a model how good a company's web presence is and it answers 72
+with total confidence for a site it never read.
+
+**`social` is claimed, never verified.** Those are URLs the site itself
+printed. Nothing proves the account belongs to that business — render it as
+"linked from their site". Check `machineReadable` too: `false` means a real
+profile that search engines have to infer from a footer link, which is a
+specific, common and easily fixed finding.
+
+**A low score is a success, not a skip.** Every check failing is the most
+useful report this produces. Only `unreachable` means the site did not answer —
+and `provider_unavailable` means *Connect* did not, which is never something
+to tell your user about their own site.
+
 ## 0.32.0
 
 Push notifications: `connect.push.send()` on the server, `useConnectPush()` in

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;
+    }
+}