@cosmoops/connect-sdk 0.34.1 → 0.36.0

package/CHANGELOG.md

@@ -3,6 +3,228 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.36.0
+
+### A workspace's billing details can be read, so a tax id is typed once
+
+`workspaces.billingProfile({ asUser })` returns the legal name, GSTIN,
+registered address and entity form the customer gave CosmoOps so we can
+invoice them.
+
+It exists for one shape of problem: an application that prints documents - a
+CRM's quotation letterhead - needs the same three facts about the same legal
+entity, and the only way to get them was to ask the customer again. Two copies
+of a GSTIN diverge, and on an Indian quotation the first two characters of that
+GSTIN are what decide CGST+SGST versus IGST.
+
+```ts
+const token = await getConnectSessionToken();
+const billing = token ? await connect.workspaces.billingProfile({ asUser: token }) : null;
+// offer "Use my billing details" — then keep your own copy
+```
+
+**It is a prefill source, not a shared record.** This is the *Bill To* side -
+who we invoice - and your letterhead is the *Bill From* side. They are the same
+facts for most customers without being the same field: a group that bills us
+through a holding company while quoting under a trading subsidiary has to stay
+expressible. So copy it on first setup and keep your copy authoritative. There
+is deliberately **no write form** - an application must not edit the details
+its own invoices are raised against.
+
+**Nothing in it is verified.** It is self-declared in the customer's billing
+settings, not the KYB record; no PAN check stands behind it. A convenience,
+never evidence of identity.
+
+**It needs `billing:read` on the signed-in member**, on top of `workspaces:read`
+on your key. A tax identity belongs to whoever can already see it in Connect's
+billing screens - an owner, admin or manager - and it cannot be granted through
+a role on your application. So an ordinary member gets a `403` here where they
+get a roster from `members()`: **treat that as a normal branch**, offer the
+prefill to whoever can use it, and let everyone else type their own details.
+
+`razorpayCustomerId` is not returned. It is a payment-provider handle no
+partner has a use for.
+
+### `getConnectSessionToken()`, so `asUser` works from a Server Component
+
+Every `asUser` call needs the caller's opaque session token, and there was no
+way to obtain one inside a Server Component: `getConnectSession()` answers
+*who* the caller is and deliberately does not hand back the credential. A page
+that wanted its own workspace's roster had to reimplement the cookie read or
+route the call through the browser.
+
+```tsx
+const token = await getConnectSessionToken();
+const members = token ? await connect.workspaces.members({ asUser: token }) : [];
+```
+
+**It is the cookie, unverified** - no round trip, and no check that the session
+is still live. A non-null answer means a cookie was present, not that it works;
+Connect is what answers `401` for a revoked one. Use `getConnectSession()` for
+"is somebody here" and this for "hand Connect the credential they arrived
+with".
+
+### `SDK_VERSION` matched the published version again
+
+It still read `0.35.0` after the version bump, so every request from this
+release would have carried a `User-Agent` a version behind. `src/sdk.test.ts`
+is what caught it, and is the reason the constant is pinned to
+`package.json` rather than trusted.
+
+
+One field, `ConnectWorkspaceMember.memberId`, without which no integration
+could say who an appointment belongs to.
+
+### A diary and a roster could not be joined
+
+`Booking.hostMemberIds` holds `WorkspaceMember.id` values, and so does
+`listBookings`' `hostMemberId` filter. `workspaces.members()` returned
+`userId` and no member id at all - so the two sets of ids had nothing in
+common, and a partner could filter a diary by a value it had no way to read
+back.
+
+That made two obvious features unreachable rather than merely awkward: a host
+column on a calendar, and narrowing a shared calendar to one person. Both fail
+*quietly* if you reach for `userId` instead, because a filter nobody matches
+returns an empty window, which reads as a free afternoon rather than a bug.
+
+```ts
+const { members } = await connect.workspaces.members({ asUser });
+const byMemberId = new Map(members.map((m) => [m.memberId, m]));
+
+const { bookings } = await connect.scheduling.listBookings({ workspaceId, asUser });
+bookings.map((b) => b.hostMemberIds.map((id) => byMemberId.get(id)?.displayName));
+```
+
+The two ids are not interchangeable and neither is derived from the other:
+`userId` identifies the person everywhere else in this API, `memberId` is what
+the calendar speaks in. It is workspace-scoped and opaque - do not address a
+member by it anywhere else.
+
+Additive, so nothing breaks. `Booking.hostMemberIds`' own doc comment claimed
+these were already the ids `workspaces.listMembers` returns, which was wrong
+twice over - that method is `workspaces.members()`, and until now its rows
+carried no id these could be matched against.
+
+## 0.35.0
+
+One addition, `connectProviderProps()`, for a mistake both applications built
+on this SDK shipped before anyone noticed.
+
+### Your server and your browser can address different Connect instances
+
+`CONNECT_APP_URL` points the server at a non-production Connect. It is not
+`NEXT_PUBLIC_`, so it never reaches the browser, and `ConnectProvider` defaults
+`appUrl` to the public instance independently. Point one and not the other and
+nothing fails: your API reads go to staging while every destination the browser
+builds opens **production** - the user menu's Profile and Billing rows, the app
+launcher's link for an unsubscribed application, `ConnectAccessGate`'s subscribe
+target, and checkout.
+
+The docs said to pass both. That was a rule to remember rather than a shape to
+follow, and the sentence next to it - "the provider takes no props, which is the
+point" - was about `clientId` and read as being about all of them.
+
+```tsx title="app/layout.tsx"
+import { connectProviderProps } from "@cosmoops/connect-sdk/next";
+import { ConnectProvider } from "@cosmoops/connect-sdk/client";
+
+<ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>
+```
+
+It returns `{ appUrl }`, resolved from `CONNECT_APP_URL` and falling back to the
+production origin - so the line is correct in every environment and you write it
+once. Props you pass yourself still win, as long as the spread comes first.
+
+**Call it in the Server Component, not in your shell.** It reads a server-side
+variable, so it ships from `/next`, which a Client Component cannot import -
+attempting it fails the build naming `this-entry-is-server-only`. A shell that
+needs `usePathname()` takes the result as a prop; `{ appUrl }` is a plain
+serializable object, so that costs nothing.
+
+Already have a helper that owns this origin - because you also build your own
+links into Connect - keep using it. One function owning the read beats this one
+sitting beside it.
+
+Nothing changes if you were already passing `appUrl`, and nothing breaks if you
+were not: the default is unchanged.
+
+**This was never a security issue**, which is worth saying because it sounds
+like one. `appUrl` is a navigation target you set from your own environment: it
+carries no credential, no gate or permission check reads it, it is never
+reachable from a URL or a request body, and redirect URIs are still matched
+exactly server-side. The worst case is a real charge in the wrong instance, not
+a way in.
+
+### The sidebar's nav rows are 36px, so a ten-route rail stops scrolling
+
+`AppShell`'s rail is the only part of the shell that grows with *your* route
+count, and `ConnectSidebarBody` is the only part that scrolls - so a rail that
+overflows overflows there. Ten destinations at the old 40px came to 436px of
+nav against 273px of fixed chrome (header, workspace switcher, secondary-nav
+footer, account footer), which needs a 709px viewport to sit still; a 1366x768
+screen has about 678px of it. The nav scrolled under its own footer on the most
+common small laptop, which reads as a rail with destinations missing from it.
+
+Nav rows - and every 20px-glyph row, so the secondary nav and the app launcher
+too - are now **36px**, and the scrolling region's own vertical padding drops
+from 8px to 4px a side. That is 56px back on a twelve-row integration, enough
+that the same rail sits still. 36px is still past WCAG 2.5.8's 24px target
+minimum, with the row's full width as the hit area.
+
+**The two 32px-glyph rows stay at 40px** - the workspace switcher and the
+account row. There are exactly two of them, neither scales with your nav, and
+both need the height: a 32px avatar in a 36px row has 2px of air, and the
+account row's label is two lines.
+
+**Shrinking the icons would not have done it.** The glyph box is a flex
+centring container for an icon *you* supply at your own size, so a smaller box
+buys no vertical space and only pushes the icon off the 32px horizontal centre
+the collapsed rail is built on - `RAIL_GUTTER + inset + glyph/2 = RAIL_COLLAPSED / 2`
+is what lets the rail collapse without anything drifting sideways.
+
+Nothing in your code changes. If your nav is long enough to still overflow, the
+levers are the row count and `secondaryNav` - a rail is navigation, and past a
+dozen rows a scrolling one is a sitemap.
+
+### `doctor` now catches it
+
+`npx @cosmoops/connect-sdk doctor` reports a **note** when `CONNECT_APP_URL` is
+set and the layout holding `<ConnectProvider>` passes no `appUrl`, with the fix
+in the output. A note rather than a failure, so it cannot break a CI run: the
+prop may be threaded from the layout into a `"use client"` shell, which reading
+the layout cannot see.
+
+### The rail fits a ten-destination nav on a laptop
+
+`AppShell`'s nav rows, its launcher and its secondary-nav rows are **36px**
+rather than 40px, and the one region that scrolls (`ConnectSidebarBody`) carries
+`py-1` rather than `py-2`. The two rows with a 32px glyph - the account row and
+the workspace switcher - stay at 40px: there are exactly two of them, neither
+grows with your nav, and both need the height (a 32px tile in a 36px row has 2px
+of air, and the account row's name-over-email label measures ~32px on its own).
+
+Ten destinations at 40px came to 436px of nav against 273px of fixed chrome,
+which needs a 709px viewport to sit still - a 1366x768 screen has about 678px of
+it, so the nav scrolled on a perfectly ordinary laptop. Four pixels a row is 48px
+back across the twelve rows a real integration draws. 36px is still comfortably
+past WCAG 2.5.8's 24px target minimum, with the row's full width as the hit area.
+
+The glyph box is deliberately unchanged at 20px. It is a flex centring container
+for an icon **you** supply at your own size, so shrinking it buys no vertical
+space and only pushes the icon off the 32px centre the collapsed rail is built
+on. If you pass an icon larger than 20px it will now sit in a slightly tighter
+row; `size-5` remains the recommendation.
+
+### Fixed: the User-Agent reported the wrong version
+
+`SDK_VERSION` was left at `0.34.0` when 0.34.1 shipped, so every request this
+package made identified itself as the previous release. It is in step again, and
+the assertion that pins it to `package.json` is back to green - it had been
+failing since that release, unnoticed because the publish guard runs the build
+and the pack check rather than the test suite. Diagnostic only; nothing behaved
+differently.
+
 ## 0.34.1
 
 Two tabs, or one abandoned sign-in and one fresh one, could not both work -

package/dist/cjs/cli/doctor.js

@@ -1,3 +1,4 @@
+"use client";
 "use strict";
 /**
  * `npx @cosmoops/connect-sdk doctor` - checks a wired-up project for the
@@ -84,14 +85,14 @@ function checkBridge(appDir, root) {
     }
     return { status: "pass", title: `Bridge route handler (${(0, node_path_1.relative)(root, bridge)})` };
 }
-function checkProvider(appDir, root) {
+function checkProvider(appDir, root, env) {
     const layouts = walk(appDir, ["layout.tsx", "layout.jsx"]);
     const hosting = layouts.filter((path) => /<ConnectProvider/.test(read(path)));
     if (hosting.length === 0) {
         return {
             status: "fail",
             title: "ConnectProvider in a layout",
-            detail: 'Nothing renders <ConnectProvider>. Every client hook and component below it throws without one. In app/layout.tsx:\n       import { ConnectProvider } from "@cosmoops/connect-sdk/client";\n       <ConnectProvider>{children}</ConnectProvider>',
+            detail: 'Nothing renders <ConnectProvider>. Every client hook and component below it throws without one. In app/layout.tsx:\n       import { connectProviderProps } from "@cosmoops/connect-sdk/next";\n       import { ConnectProvider } from "@cosmoops/connect-sdk/client";\n       <ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>',
         };
     }
     // A nested provider re-fetches the session and keeps a second cache that the
@@ -104,8 +105,42 @@ function checkProvider(appDir, root) {
             detail: `Found in ${hosting.length} layouts (${hosting.map((path) => (0, node_path_1.relative)(root, path)).join(", ")}). Nested providers keep separate caches, so a mutation in one is invisible to the other. Keep the outermost one only.`,
         };
     }
+    /*
+     * The split integration, and the reason this check exists at all.
+     *
+     * `CONNECT_APP_URL` points the *server* at a non-production Connect. It is
+     * not `NEXT_PUBLIC_`, so `ConnectProvider` cannot read it and defaults
+     * `appUrl` to production independently - and nothing fails. The API reads go
+     * to the configured instance while every destination the browser builds
+     * opens production: the user menu's Profile and Billing rows, the launcher's
+     * link for an unsubscribed application, the access gate's subscribe target,
+     * and checkout. Both applications built on this SDK shipped exactly that.
+     *
+     * `warn` rather than `fail`: the prop may be threaded from a parent Server
+     * Component into a `"use client"` shell, which is the documented shape for a
+     * shell needing `usePathname()` - and that assignment is not visible in the
+     * layout this reads. So this cannot tell from the outside, which is what
+     * `warn` means here.
+     */
+    const pointedElsewhere = /^[ \t]*CONNECT_APP_URL[ \t]*=[ \t]*\S/m.test(env);
+    const carriesOrigin = /appUrl|connectProviderProps/.test(read(hosting[0]));
+    if (pointedElsewhere && !carriesOrigin) {
+        return {
+            status: "warn",
+            title: "ConnectProvider in a layout",
+            detail: `CONNECT_APP_URL is set, but ${(0, node_path_1.relative)(root, hosting[0])} passes no appUrl - so your server talks to that instance while every link the browser builds opens production Connect. Spread it in:\n       <ConnectProvider {...connectProviderProps()}>  // from "@cosmoops/connect-sdk/next"\n       Already threading it into a "use client" shell? Then this is fine and you can ignore it.`,
+        };
+    }
     return { status: "pass", title: `ConnectProvider in a layout (${(0, node_path_1.relative)(root, hosting[0])})` };
 }
+/** The env files `checkEnv` reads, as one string, shared with `checkProvider`. */
+function envText(root) {
+    return [".env.local", ".env.development.local", ".env"]
+        .map((name) => (0, node_path_1.join)(root, name))
+        .filter(node_fs_1.existsSync)
+        .map(read)
+        .join("\n");
+}
 /**
  * Order is the whole check.
  *
@@ -146,8 +181,7 @@ function checkTheme(root) {
  * loaded it - exactly the shell `next dev` will inherit.
  */
 function checkEnv(root) {
-    const files = [".env.local", ".env.development.local", ".env"].map((name) => (0, node_path_1.join)(root, name));
-    const combined = files.filter(node_fs_1.existsSync).map(read).join("\n");
+    const combined = envText(root);
     return ["CONNECT_API_KEY", "CONNECT_CLIENT_ID"].map((name) => {
         // Horizontal whitespace only. `\s*` also matches the newline, so a bare
         // `CONNECT_API_KEY=` was satisfied by the *next* line's value and an empty
@@ -191,7 +225,7 @@ function runDoctor(argv = []) {
     console.log(`[connect-sdk] Checking ${(0, node_path_1.relative)(process.cwd(), root) || root}\n`);
     const checks = [
         checkBridge(appDir, root),
-        checkProvider(appDir, root),
+        checkProvider(appDir, root, envText(root)),
         checkTheme(root),
         ...checkEnv(root),
         checkRedirectUri(),

package/dist/cjs/client/components/shell-context.js

@@ -36,22 +36,51 @@ exports.RAIL_GUTTER = 12;
  * The row shape every sidebar control shares - nav items, the workspace tile,
  * the launcher, the user button.
  *
+ * **The height is not here.** It rides on `SIDEBAR_ROW_ICON` /
+ * `SIDEBAR_ROW_TILE` instead, because the two glyph sizes want different
+ * heights and only one of them is in the region that overflows - see those
+ * two constants.
+ *
  * `overflow-hidden` + `whitespace-nowrap` is what makes the collapse smooth:
  * the label is *clipped* by the shrinking rail rather than re-wrapped or
  * re-measured, so a width animation costs no reflow. Fading the label with
  * `SidebarLabel` on top of that hides the clip itself.
  */
-exports.SIDEBAR_ROW = "group/row relative flex h-10 w-full shrink-0 items-center justify-start gap-3 overflow-hidden whitespace-nowrap rounded-lg pe-2 text-sm font-normal transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
+exports.SIDEBAR_ROW = "group/row relative flex w-full shrink-0 items-center justify-start gap-3 overflow-hidden whitespace-nowrap rounded-lg pe-2 text-sm font-normal transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
 /**
- * Leading inset for a row whose glyph is 20px wide (a nav icon, the launcher).
+ * Leading inset *and height* for a row whose glyph is 20px wide (a nav icon,
+ * the launcher, a secondary-nav row).
+ *
  * `10 + 10 = 20`, and `RAIL_GUTTER + 20 = 32`. See `RAIL_COLLAPSED`.
+ *
+ * **36px, not 40px, and the height belongs on this axis rather than on
+ * `SIDEBAR_ROW`.** The nav is the only region of the rail that grows with the
+ * host's route count, and `ConnectSidebarBody` is the only region that
+ * scrolls - so a rail that overflows overflows here. Ten destinations at 40px
+ * came to 436px of nav against 273px of fixed chrome (header, switcher, two
+ * footers), which needs a 709px viewport to sit still; a 1366x768 screen has
+ * about 678px of it. Four pixels a row is 48px back across the twelve rows a
+ * real integration draws, and 36px is still comfortably past the 24px
+ * WCAG 2.5.8 target minimum with the row's full width as the hit area.
+ *
+ * It is deliberately *not* a smaller glyph. The 20px box is a flex centring
+ * container for an icon the **host** supplies at its own size, so shrinking
+ * the box buys no vertical space and only pushes the icon off the 32px centre
+ * the collapsed rail is built on.
  */
-exports.SIDEBAR_ROW_ICON = "ps-[10px]";
+exports.SIDEBAR_ROW_ICON = "h-9 ps-[10px]";
 /**
- * Leading inset for a row whose glyph is 32px wide (the avatar, the workspace
- * tile). `4 + 16 = 20`, landing on the same 32px centre as `SIDEBAR_ROW_ICON`.
+ * Leading inset and height for a row whose glyph is 32px wide (the avatar, the
+ * workspace tile). `4 + 16 = 20`, landing on the same 32px centre as
+ * `SIDEBAR_ROW_ICON`.
+ *
+ * **These stay at 40px.** There are exactly two of them and neither scales
+ * with the host's nav, so they are not what overflows - and both need the
+ * height: a 32px tile in a 36px row has 2px of air, and the account row's
+ * label is two lines (name over email, `leading-tight`) which measures ~32px
+ * on its own.
  */
-exports.SIDEBAR_ROW_TILE = "ps-[4px]";
+exports.SIDEBAR_ROW_TILE = "h-10 ps-[4px]";
 /**
  * The class list for one sidebar row, in one place.
  *

package/dist/cjs/client/components/sidebar.js

@@ -116,7 +116,12 @@ function ConnectSidebarBody({ children }) {
     // zoom away over a region of text is a WCAG 1.4.4 failure, and nothing
     // here needs it suppressed. On the desktop rail, where no ancestor
     // restricts anything, the pair is equivalent to the default.
-    (0, jsx_runtime_1.jsx)("div", { className: "flex min-h-0 flex-1 touch-pan-y touch-pinch-zoom flex-col gap-1 overflow-y-auto overflow-x-hidden px-3 py-2", children: children }));
+    // `py-1` rather than the `py-2` every other region carries: this is the
+    // one region that scrolls, so it is the first place to give up air when
+    // the nav is a row or two from overflowing. The rows paint their own
+    // rounded background, so the hairline above the footer is still clear of
+    // them. See `SIDEBAR_ROW_ICON` for the arithmetic this is part of.
+    (0, jsx_runtime_1.jsx)("div", { className: "flex min-h-0 flex-1 touch-pan-y touch-pinch-zoom flex-col gap-1 overflow-y-auto overflow-x-hidden px-3 py-1", children: children }));
 }
 /**
  * A pinned region at the foot of the rail - the secondary nav, the launcher,

package/dist/cjs/next/index.js

@@ -36,10 +36,12 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConnectClient = exports.createConnectHandler = void 0;
 exports.connectClient = connectClient;
+exports.connectProviderProps = connectProviderProps;
 exports.cookieSessionStore = cookieSessionStore;
 exports.createConnectHandlers = createConnectHandlers;
 exports.GET = handle;
 exports.POST = handle;
+exports.getConnectSessionToken = getConnectSessionToken;
 exports.getConnectSession = getConnectSession;
 exports.requireConnectSession = requireConnectSession;
 const react_1 = require("react");
@@ -68,8 +70,9 @@ const errors_js_1 = require("../errors.js");
  *
  * ```tsx
  * // app/layout.tsx
+ * import { connectProviderProps } from "@cosmoops/connect-sdk/next";
  * import { ConnectProvider } from "@cosmoops/connect-sdk/client";
- * <ConnectProvider>{children}</ConnectProvider>
+ * <ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>
  * ```
  *
  * No `next.config.ts` changes needed - configuration comes from the
@@ -86,6 +89,10 @@ const errors_js_1 = require("../errors.js");
  * `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.
+ * That is what the `connectProviderProps()` spread above is for, and why the
+ * layout is two imports rather than one - leave it off and the server half and
+ * the browser half of the same integration address different instances, with
+ * nothing failing to say so. See that function's own docs.
  *
  * 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
@@ -126,6 +133,55 @@ function connectClient(overrides = {}) {
         cached = client;
     return client;
 }
+/**
+ * The `ConnectProvider` props that come from the environment.
+ *
+ * ```tsx
+ * // app/layout.tsx - a Server Component
+ * import { connectProviderProps } from "@cosmoops/connect-sdk/next";
+ * import { ConnectProvider } from "@cosmoops/connect-sdk/client";
+ *
+ * <ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>
+ * ```
+ *
+ * ## What it is for
+ *
+ * `CONNECT_APP_URL` points the *server* at a non-production Connect. It is not
+ * `NEXT_PUBLIC_`, so it never reaches the browser, and `ConnectProvider`
+ * defaults `appUrl` to the production origin independently - so pointing the
+ * server somewhere else and leaving the prop off splits the integration in
+ * half. The server talks to dev and every destination the browser builds opens
+ * production: the user menu's Profile and Billing rows, the app launcher's link
+ * for an unsubscribed application, `ConnectAccessGate`'s subscribe target, and
+ * checkout. Nothing errors. The customer is simply asked to buy a second
+ * subscription in an instance where they have none.
+ *
+ * Both apps built on this SDK shipped that bug before anyone noticed, from
+ * reading "the provider takes no props" as a rule rather than as a remark about
+ * `clientId`. A root layout is a Server Component, so one spread fixes it with
+ * no browser-visible copy of the variable.
+ *
+ * ## What it deliberately leaves out
+ *
+ * `clientId` and `basePath`. The first is only needed alongside an explicit
+ * `redirectUri`, when you build the authorize URL in the browser rather than
+ * letting `signIn()` bounce through your own `/signin` route - and handing the
+ * browser a value it does not need is surface for nothing. The second is where
+ * *you* mounted the handler, which the environment does not know. Pass either
+ * yourself; a prop you pass always wins over this spread, whichever order you
+ * write them in, as long as the spread comes first.
+ *
+ * ## If you already have an origin helper
+ *
+ * Use it instead. An app that builds its own links into Connect (a "Manage
+ * team" button, a pricing page's subscribe target) needs that origin on the
+ * server too, and one function owning the read is better than this helper
+ * beside it - two readers of one variable is the shape that caused this. This
+ * exists for the integration that has no such helper, which is most of them.
+ */
+function connectProviderProps() {
+    return { appUrl: (process.env.CONNECT_APP_URL ?? client_js_1.DEFAULT_BASE_URL).replace(/\/+$/, "") };
+}
 /**
  * An httpOnly cookie holding the opaque `sessionToken`.
  *
@@ -297,6 +353,45 @@ async function readSession(request, options) {
 const cachedAmbientSession = (0, react_1.cache)(async () => {
     return readSession(await requestFromHeaders(), {});
 });
+/**
+ * The caller's opaque Connect **session token**, or `null` when signed out.
+ *
+ * ## What it is for
+ *
+ * Every `asUser` call on the server client needs one - `workspaces.*`,
+ * `scheduling.*`, the `/data` store's per-user form - and until this existed
+ * there was no way to obtain it inside a Server Component. `getConnectSession`
+ * answers *who* the caller is and deliberately does not hand back the
+ * credential, so a page that wanted to read its own workspace's roster had to
+ * either reimplement the cookie read or route the call through the browser.
+ *
+ * ```tsx
+ * // app/settings/page.tsx
+ * const token = await getConnectSessionToken();
+ * const members = token ? await connect.workspaces.members({ asUser: token }) : [];
+ * ```
+ *
+ * ## It is the cookie, unverified
+ *
+ * This reads the session store and nothing else - **no round trip, and no
+ * check that the token is still live.** A token from a revoked or expired
+ * session is a string that looks exactly like a good one, and Connect is what
+ * answers `401` for it. So this is not a sign-in check: use
+ * `getConnectSession()` for "is somebody here", and this for "hand Connect the
+ * credential they arrived with". A non-null answer means a cookie was present,
+ * not that it works.
+ *
+ * Reads `cookies()` transitively, so under `cacheComponents` it belongs inside
+ * a `<Suspense>` boundary like any other request-scoped read.
+ *
+ * Pass a `Request` to use it where `next/headers` does not exist, and a
+ * `session` store if you did not use the default cookie - the same two escape
+ * hatches `getConnectSession` takes, for the same reasons.
+ */
+async function getConnectSessionToken(request, options = {}) {
+    const store = options.session ?? cookieSessionStore();
+    return (await store.read(request ?? (await requestFromHeaders()))) ?? null;
+}
 /**
  * The signed-in user for a Server Component, Route Handler or Server Action,
  * or `null`.

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.34.0";
+exports.SDK_VERSION = "0.36.0";

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

@@ -54,6 +54,39 @@ class WorkspacesResource {
             json: input,
         });
     }
+    /**
+     * The billing identity of the workspace this session is on - its legal
+     * name, GSTIN, registered address and entity form.
+     *
+     * **For prefilling your own settings, once.** See
+     * `WorkspaceBillingProfile`, which carries the whole argument: this is the
+     * *Bill To* side, yours is the *Bill From* side, and they are the same facts
+     * for most customers without being the same field. There is no write form.
+     *
+     * ```ts
+     * // app/settings/page.tsx - offer "Use my billing details"
+     * const token = await getConnectSessionToken();
+     * const billing = token ? await connect.workspaces.billingProfile({ asUser: token }) : null;
+     * ```
+     *
+     * **Needs two things, not one.** `workspaces:read` on your key, *and*
+     * `billing:read` on the signed-in member - a tax identity belongs to
+     * whoever can already see it in Connect's billing screens, so an ordinary
+     * member gets a 403 here where they get a roster from `members()`. That
+     * cannot be granted through a role on your application, deliberately.
+     *
+     * So **treat the 403 as a normal branch**, not an error: offer the prefill
+     * to whoever can use it and let everyone else type their own details. A
+     * workspace admin is the person who sets this up anyway.
+     */
+    async billingProfile(options) {
+        const result = await (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: "/workspaces/billing-profile",
+            headers: (0, acting_as_js_1.actingAs)(options.asUser),
+        });
+        return result.billingProfile;
+    }
     /**
      * The team of the workspace this session is on.
      *

package/dist/esm/cli/doctor.js

@@ -81,14 +81,14 @@ function checkBridge(appDir, root) {
     }
     return { status: "pass", title: `Bridge route handler (${relative(root, bridge)})` };
 }
-function checkProvider(appDir, root) {
+function checkProvider(appDir, root, env) {
     const layouts = walk(appDir, ["layout.tsx", "layout.jsx"]);
     const hosting = layouts.filter((path) => /<ConnectProvider/.test(read(path)));
     if (hosting.length === 0) {
         return {
             status: "fail",
             title: "ConnectProvider in a layout",
-            detail: 'Nothing renders <ConnectProvider>. Every client hook and component below it throws without one. In app/layout.tsx:\n       import { ConnectProvider } from "@cosmoops/connect-sdk/client";\n       <ConnectProvider>{children}</ConnectProvider>',
+            detail: 'Nothing renders <ConnectProvider>. Every client hook and component below it throws without one. In app/layout.tsx:\n       import { connectProviderProps } from "@cosmoops/connect-sdk/next";\n       import { ConnectProvider } from "@cosmoops/connect-sdk/client";\n       <ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>',
         };
     }
     // A nested provider re-fetches the session and keeps a second cache that the
@@ -101,8 +101,42 @@ function checkProvider(appDir, root) {
             detail: `Found in ${hosting.length} layouts (${hosting.map((path) => relative(root, path)).join(", ")}). Nested providers keep separate caches, so a mutation in one is invisible to the other. Keep the outermost one only.`,
         };
     }
+    /*
+     * The split integration, and the reason this check exists at all.
+     *
+     * `CONNECT_APP_URL` points the *server* at a non-production Connect. It is
+     * not `NEXT_PUBLIC_`, so `ConnectProvider` cannot read it and defaults
+     * `appUrl` to production independently - and nothing fails. The API reads go
+     * to the configured instance while every destination the browser builds
+     * opens production: the user menu's Profile and Billing rows, the launcher's
+     * link for an unsubscribed application, the access gate's subscribe target,
+     * and checkout. Both applications built on this SDK shipped exactly that.
+     *
+     * `warn` rather than `fail`: the prop may be threaded from a parent Server
+     * Component into a `"use client"` shell, which is the documented shape for a
+     * shell needing `usePathname()` - and that assignment is not visible in the
+     * layout this reads. So this cannot tell from the outside, which is what
+     * `warn` means here.
+     */
+    const pointedElsewhere = /^[ \t]*CONNECT_APP_URL[ \t]*=[ \t]*\S/m.test(env);
+    const carriesOrigin = /appUrl|connectProviderProps/.test(read(hosting[0]));
+    if (pointedElsewhere && !carriesOrigin) {
+        return {
+            status: "warn",
+            title: "ConnectProvider in a layout",
+            detail: `CONNECT_APP_URL is set, but ${relative(root, hosting[0])} passes no appUrl - so your server talks to that instance while every link the browser builds opens production Connect. Spread it in:\n       <ConnectProvider {...connectProviderProps()}>  // from "@cosmoops/connect-sdk/next"\n       Already threading it into a "use client" shell? Then this is fine and you can ignore it.`,
+        };
+    }
     return { status: "pass", title: `ConnectProvider in a layout (${relative(root, hosting[0])})` };
 }
+/** The env files `checkEnv` reads, as one string, shared with `checkProvider`. */
+function envText(root) {
+    return [".env.local", ".env.development.local", ".env"]
+        .map((name) => join(root, name))
+        .filter(existsSync)
+        .map(read)
+        .join("\n");
+}
 /**
  * Order is the whole check.
  *
@@ -143,8 +177,7 @@ function checkTheme(root) {
  * loaded it - exactly the shell `next dev` will inherit.
  */
 function checkEnv(root) {
-    const files = [".env.local", ".env.development.local", ".env"].map((name) => join(root, name));
-    const combined = files.filter(existsSync).map(read).join("\n");
+    const combined = envText(root);
     return ["CONNECT_API_KEY", "CONNECT_CLIENT_ID"].map((name) => {
         // Horizontal whitespace only. `\s*` also matches the newline, so a bare
         // `CONNECT_API_KEY=` was satisfied by the *next* line's value and an empty
@@ -188,7 +221,7 @@ export function runDoctor(argv = []) {
     console.log(`[connect-sdk] Checking ${relative(process.cwd(), root) || root}\n`);
     const checks = [
         checkBridge(appDir, root),
-        checkProvider(appDir, root),
+        checkProvider(appDir, root, envText(root)),
         checkTheme(root),
         ...checkEnv(root),
         checkRedirectUri(),

package/dist/esm/client/components/shell-context.js

@@ -28,22 +28,51 @@ export const RAIL_GUTTER = 12;
  * The row shape every sidebar control shares - nav items, the workspace tile,
  * the launcher, the user button.
  *
+ * **The height is not here.** It rides on `SIDEBAR_ROW_ICON` /
+ * `SIDEBAR_ROW_TILE` instead, because the two glyph sizes want different
+ * heights and only one of them is in the region that overflows - see those
+ * two constants.
+ *
  * `overflow-hidden` + `whitespace-nowrap` is what makes the collapse smooth:
  * the label is *clipped* by the shrinking rail rather than re-wrapped or
  * re-measured, so a width animation costs no reflow. Fading the label with
  * `SidebarLabel` on top of that hides the clip itself.
  */
-export const SIDEBAR_ROW = "group/row relative flex h-10 w-full shrink-0 items-center justify-start gap-3 overflow-hidden whitespace-nowrap rounded-lg pe-2 text-sm font-normal transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
+export const SIDEBAR_ROW = "group/row relative flex w-full shrink-0 items-center justify-start gap-3 overflow-hidden whitespace-nowrap rounded-lg pe-2 text-sm font-normal transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
 /**
- * Leading inset for a row whose glyph is 20px wide (a nav icon, the launcher).
+ * Leading inset *and height* for a row whose glyph is 20px wide (a nav icon,
+ * the launcher, a secondary-nav row).
+ *
  * `10 + 10 = 20`, and `RAIL_GUTTER + 20 = 32`. See `RAIL_COLLAPSED`.
+ *
+ * **36px, not 40px, and the height belongs on this axis rather than on
+ * `SIDEBAR_ROW`.** The nav is the only region of the rail that grows with the
+ * host's route count, and `ConnectSidebarBody` is the only region that
+ * scrolls - so a rail that overflows overflows here. Ten destinations at 40px
+ * came to 436px of nav against 273px of fixed chrome (header, switcher, two
+ * footers), which needs a 709px viewport to sit still; a 1366x768 screen has
+ * about 678px of it. Four pixels a row is 48px back across the twelve rows a
+ * real integration draws, and 36px is still comfortably past the 24px
+ * WCAG 2.5.8 target minimum with the row's full width as the hit area.
+ *
+ * It is deliberately *not* a smaller glyph. The 20px box is a flex centring
+ * container for an icon the **host** supplies at its own size, so shrinking
+ * the box buys no vertical space and only pushes the icon off the 32px centre
+ * the collapsed rail is built on.
  */
-export const SIDEBAR_ROW_ICON = "ps-[10px]";
+export const SIDEBAR_ROW_ICON = "h-9 ps-[10px]";
 /**
- * Leading inset for a row whose glyph is 32px wide (the avatar, the workspace
- * tile). `4 + 16 = 20`, landing on the same 32px centre as `SIDEBAR_ROW_ICON`.
+ * Leading inset and height for a row whose glyph is 32px wide (the avatar, the
+ * workspace tile). `4 + 16 = 20`, landing on the same 32px centre as
+ * `SIDEBAR_ROW_ICON`.
+ *
+ * **These stay at 40px.** There are exactly two of them and neither scales
+ * with the host's nav, so they are not what overflows - and both need the
+ * height: a 32px tile in a 36px row has 2px of air, and the account row's
+ * label is two lines (name over email, `leading-tight`) which measures ~32px
+ * on its own.
  */
-export const SIDEBAR_ROW_TILE = "ps-[4px]";
+export const SIDEBAR_ROW_TILE = "h-10 ps-[4px]";
 /**
  * The class list for one sidebar row, in one place.
  *

package/dist/esm/client/components/sidebar.js

@@ -109,7 +109,12 @@ export function ConnectSidebarBody({ children }) {
     // zoom away over a region of text is a WCAG 1.4.4 failure, and nothing
     // here needs it suppressed. On the desktop rail, where no ancestor
     // restricts anything, the pair is equivalent to the default.
-    _jsx("div", { className: "flex min-h-0 flex-1 touch-pan-y touch-pinch-zoom flex-col gap-1 overflow-y-auto overflow-x-hidden px-3 py-2", children: children }));
+    // `py-1` rather than the `py-2` every other region carries: this is the
+    // one region that scrolls, so it is the first place to give up air when
+    // the nav is a row or two from overflowing. The rows paint their own
+    // rounded background, so the hairline above the footer is still clear of
+    // them. See `SIDEBAR_ROW_ICON` for the arithmetic this is part of.
+    _jsx("div", { className: "flex min-h-0 flex-1 touch-pan-y touch-pinch-zoom flex-col gap-1 overflow-y-auto overflow-x-hidden px-3 py-1", children: children }));
 }
 /**
  * A pinned region at the foot of the rail - the secondary nav, the launcher,

package/dist/esm/next/index.js

@@ -1,5 +1,5 @@
 import { cache } from "react";
-import { ConnectClient } from "../server/client.js";
+import { ConnectClient, DEFAULT_BASE_URL } from "../server/client.js";
 import { createConnectHandler } from "../server/handler.js";
 import { ConnectError } from "../errors.js";
 /**
@@ -24,8 +24,9 @@ import { ConnectError } from "../errors.js";
  *
  * ```tsx
  * // app/layout.tsx
+ * import { connectProviderProps } from "@cosmoops/connect-sdk/next";
  * import { ConnectProvider } from "@cosmoops/connect-sdk/client";
- * <ConnectProvider>{children}</ConnectProvider>
+ * <ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>
  * ```
  *
  * No `next.config.ts` changes needed - configuration comes from the
@@ -42,6 +43,10 @@ import { ConnectError } from "../errors.js";
  * `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.
+ * That is what the `connectProviderProps()` spread above is for, and why the
+ * layout is two imports rather than one - leave it off and the server half and
+ * the browser half of the same integration address different instances, with
+ * nothing failing to say so. See that function's own docs.
  *
  * 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
@@ -82,6 +87,55 @@ export function connectClient(overrides = {}) {
         cached = client;
     return client;
 }
+/**
+ * The `ConnectProvider` props that come from the environment.
+ *
+ * ```tsx
+ * // app/layout.tsx - a Server Component
+ * import { connectProviderProps } from "@cosmoops/connect-sdk/next";
+ * import { ConnectProvider } from "@cosmoops/connect-sdk/client";
+ *
+ * <ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>
+ * ```
+ *
+ * ## What it is for
+ *
+ * `CONNECT_APP_URL` points the *server* at a non-production Connect. It is not
+ * `NEXT_PUBLIC_`, so it never reaches the browser, and `ConnectProvider`
+ * defaults `appUrl` to the production origin independently - so pointing the
+ * server somewhere else and leaving the prop off splits the integration in
+ * half. The server talks to dev and every destination the browser builds opens
+ * production: the user menu's Profile and Billing rows, the app launcher's link
+ * for an unsubscribed application, `ConnectAccessGate`'s subscribe target, and
+ * checkout. Nothing errors. The customer is simply asked to buy a second
+ * subscription in an instance where they have none.
+ *
+ * Both apps built on this SDK shipped that bug before anyone noticed, from
+ * reading "the provider takes no props" as a rule rather than as a remark about
+ * `clientId`. A root layout is a Server Component, so one spread fixes it with
+ * no browser-visible copy of the variable.
+ *
+ * ## What it deliberately leaves out
+ *
+ * `clientId` and `basePath`. The first is only needed alongside an explicit
+ * `redirectUri`, when you build the authorize URL in the browser rather than
+ * letting `signIn()` bounce through your own `/signin` route - and handing the
+ * browser a value it does not need is surface for nothing. The second is where
+ * *you* mounted the handler, which the environment does not know. Pass either
+ * yourself; a prop you pass always wins over this spread, whichever order you
+ * write them in, as long as the spread comes first.
+ *
+ * ## If you already have an origin helper
+ *
+ * Use it instead. An app that builds its own links into Connect (a "Manage
+ * team" button, a pricing page's subscribe target) needs that origin on the
+ * server too, and one function owning the read is better than this helper
+ * beside it - two readers of one variable is the shape that caused this. This
+ * exists for the integration that has no such helper, which is most of them.
+ */
+export function connectProviderProps() {
+    return { appUrl: (process.env.CONNECT_APP_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "") };
+}
 /**
  * An httpOnly cookie holding the opaque `sessionToken`.
  *
@@ -267,6 +321,45 @@ async function readSession(request, options) {
 const cachedAmbientSession = cache(async () => {
     return readSession(await requestFromHeaders(), {});
 });
+/**
+ * The caller's opaque Connect **session token**, or `null` when signed out.
+ *
+ * ## What it is for
+ *
+ * Every `asUser` call on the server client needs one - `workspaces.*`,
+ * `scheduling.*`, the `/data` store's per-user form - and until this existed
+ * there was no way to obtain it inside a Server Component. `getConnectSession`
+ * answers *who* the caller is and deliberately does not hand back the
+ * credential, so a page that wanted to read its own workspace's roster had to
+ * either reimplement the cookie read or route the call through the browser.
+ *
+ * ```tsx
+ * // app/settings/page.tsx
+ * const token = await getConnectSessionToken();
+ * const members = token ? await connect.workspaces.members({ asUser: token }) : [];
+ * ```
+ *
+ * ## It is the cookie, unverified
+ *
+ * This reads the session store and nothing else - **no round trip, and no
+ * check that the token is still live.** A token from a revoked or expired
+ * session is a string that looks exactly like a good one, and Connect is what
+ * answers `401` for it. So this is not a sign-in check: use
+ * `getConnectSession()` for "is somebody here", and this for "hand Connect the
+ * credential they arrived with". A non-null answer means a cookie was present,
+ * not that it works.
+ *
+ * Reads `cookies()` transitively, so under `cacheComponents` it belongs inside
+ * a `<Suspense>` boundary like any other request-scoped read.
+ *
+ * Pass a `Request` to use it where `next/headers` does not exist, and a
+ * `session` store if you did not use the default cookie - the same two escape
+ * hatches `getConnectSession` takes, for the same reasons.
+ */
+export async function getConnectSessionToken(request, options = {}) {
+    const store = options.session ?? cookieSessionStore();
+    return (await store.read(request ?? (await requestFromHeaders()))) ?? null;
+}
 /**
  * The signed-in user for a Server Component, Route Handler or Server Action,
  * or `null`.

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.34.0";
+export const SDK_VERSION = "0.36.0";

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

@@ -51,6 +51,39 @@ export class WorkspacesResource {
             json: input,
         });
     }
+    /**
+     * The billing identity of the workspace this session is on - its legal
+     * name, GSTIN, registered address and entity form.
+     *
+     * **For prefilling your own settings, once.** See
+     * `WorkspaceBillingProfile`, which carries the whole argument: this is the
+     * *Bill To* side, yours is the *Bill From* side, and they are the same facts
+     * for most customers without being the same field. There is no write form.
+     *
+     * ```ts
+     * // app/settings/page.tsx - offer "Use my billing details"
+     * const token = await getConnectSessionToken();
+     * const billing = token ? await connect.workspaces.billingProfile({ asUser: token }) : null;
+     * ```
+     *
+     * **Needs two things, not one.** `workspaces:read` on your key, *and*
+     * `billing:read` on the signed-in member - a tax identity belongs to
+     * whoever can already see it in Connect's billing screens, so an ordinary
+     * member gets a 403 here where they get a roster from `members()`. That
+     * cannot be granted through a role on your application, deliberately.
+     *
+     * So **treat the 403 as a normal branch**, not an error: offer the prefill
+     * to whoever can use it and let everyone else type their own details. A
+     * workspace admin is the person who sets this up anyway.
+     */
+    async billingProfile(options) {
+        const result = await request(this.transport, {
+            method: "GET",
+            path: "/workspaces/billing-profile",
+            headers: actingAs(options.asUser),
+        });
+        return result.billingProfile;
+    }
     /**
      * The team of the workspace this session is on.
      *

package/dist/types/client/components/shell-context.d.ts

@@ -25,22 +25,51 @@ export declare const RAIL_GUTTER = 12;
  * The row shape every sidebar control shares - nav items, the workspace tile,
  * the launcher, the user button.
  *
+ * **The height is not here.** It rides on `SIDEBAR_ROW_ICON` /
+ * `SIDEBAR_ROW_TILE` instead, because the two glyph sizes want different
+ * heights and only one of them is in the region that overflows - see those
+ * two constants.
+ *
  * `overflow-hidden` + `whitespace-nowrap` is what makes the collapse smooth:
  * the label is *clipped* by the shrinking rail rather than re-wrapped or
  * re-measured, so a width animation costs no reflow. Fading the label with
  * `SidebarLabel` on top of that hides the clip itself.
  */
-export declare const SIDEBAR_ROW = "group/row relative flex h-10 w-full shrink-0 items-center justify-start gap-3 overflow-hidden whitespace-nowrap rounded-lg pe-2 text-sm font-normal transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
+export declare const SIDEBAR_ROW = "group/row relative flex w-full shrink-0 items-center justify-start gap-3 overflow-hidden whitespace-nowrap rounded-lg pe-2 text-sm font-normal transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
 /**
- * Leading inset for a row whose glyph is 20px wide (a nav icon, the launcher).
+ * Leading inset *and height* for a row whose glyph is 20px wide (a nav icon,
+ * the launcher, a secondary-nav row).
+ *
  * `10 + 10 = 20`, and `RAIL_GUTTER + 20 = 32`. See `RAIL_COLLAPSED`.
+ *
+ * **36px, not 40px, and the height belongs on this axis rather than on
+ * `SIDEBAR_ROW`.** The nav is the only region of the rail that grows with the
+ * host's route count, and `ConnectSidebarBody` is the only region that
+ * scrolls - so a rail that overflows overflows here. Ten destinations at 40px
+ * came to 436px of nav against 273px of fixed chrome (header, switcher, two
+ * footers), which needs a 709px viewport to sit still; a 1366x768 screen has
+ * about 678px of it. Four pixels a row is 48px back across the twelve rows a
+ * real integration draws, and 36px is still comfortably past the 24px
+ * WCAG 2.5.8 target minimum with the row's full width as the hit area.
+ *
+ * It is deliberately *not* a smaller glyph. The 20px box is a flex centring
+ * container for an icon the **host** supplies at its own size, so shrinking
+ * the box buys no vertical space and only pushes the icon off the 32px centre
+ * the collapsed rail is built on.
  */
-export declare const SIDEBAR_ROW_ICON = "ps-[10px]";
+export declare const SIDEBAR_ROW_ICON = "h-9 ps-[10px]";
 /**
- * Leading inset for a row whose glyph is 32px wide (the avatar, the workspace
- * tile). `4 + 16 = 20`, landing on the same 32px centre as `SIDEBAR_ROW_ICON`.
+ * Leading inset and height for a row whose glyph is 32px wide (the avatar, the
+ * workspace tile). `4 + 16 = 20`, landing on the same 32px centre as
+ * `SIDEBAR_ROW_ICON`.
+ *
+ * **These stay at 40px.** There are exactly two of them and neither scales
+ * with the host's nav, so they are not what overflows - and both need the
+ * height: a 32px tile in a 36px row has 2px of air, and the account row's
+ * label is two lines (name over email, `leading-tight`) which measures ~32px
+ * on its own.
  */
-export declare const SIDEBAR_ROW_TILE = "ps-[4px]";
+export declare const SIDEBAR_ROW_TILE = "h-10 ps-[4px]";
 /**
  * The class list for one sidebar row, in one place.
  *
@@ -57,7 +86,10 @@ export declare const SIDEBAR_ROW_TILE = "ps-[4px]";
  * lets a `w-fit`, centred, `px-`-padded button take this shape at all.
  */
 export declare function sidebarRowClass(options?: Readonly<{
-    /** The glyph is 32px (an avatar, a workspace tile) rather than 20px. */
+    /**
+     * The glyph is 32px (an avatar, a workspace tile) rather than 20px - which
+     * also makes the row 40px rather than 36px. See `SIDEBAR_ROW_TILE`.
+     */
     tile?: boolean;
     /** Paint the active treatment. */
     active?: boolean;

package/dist/types/client/components/sidebar.d.ts

@@ -73,13 +73,13 @@ export declare function ConnectSidebarFooter({ children, separated, }: Readonly<
     separated?: boolean;
 }>): import("react").JSX.Element;
 export type ConnectSidebarRowProps = Readonly<{
-    /** The glyph. 20px by default; 32px when `tile`. */
+    /** The glyph. 20px in a 36px row by default; 32px in a 40px row when `tile`. */
     icon: ReactNode;
     /** The row's text, and - when it is a string - its accessible name. */
     label: ReactNode;
     /** Overrides the accessible name. Required when `label` is not a string. */
     "aria-label"?: string;
-    /** The glyph is 32px (an avatar, a workspace tile) rather than 20px. */
+    /** The glyph is 32px (an avatar, a workspace tile) rather than 20px, in a 40px row. */
     tile?: boolean;
     /** Trailing content, e.g. a chevron. Clipped with the label while collapsed. */
     trailing?: ReactNode;

package/dist/types/next/index.d.ts

@@ -9,6 +9,55 @@ import type { UserResponse } from "../types.js";
  * are frequently absent.
  */
 export declare function connectClient(overrides?: Partial<ConnectClientOptions>): ConnectClient;
+/**
+ * The `ConnectProvider` props that come from the environment.
+ *
+ * ```tsx
+ * // app/layout.tsx - a Server Component
+ * import { connectProviderProps } from "@cosmoops/connect-sdk/next";
+ * import { ConnectProvider } from "@cosmoops/connect-sdk/client";
+ *
+ * <ConnectProvider {...connectProviderProps()}>{children}</ConnectProvider>
+ * ```
+ *
+ * ## What it is for
+ *
+ * `CONNECT_APP_URL` points the *server* at a non-production Connect. It is not
+ * `NEXT_PUBLIC_`, so it never reaches the browser, and `ConnectProvider`
+ * defaults `appUrl` to the production origin independently - so pointing the
+ * server somewhere else and leaving the prop off splits the integration in
+ * half. The server talks to dev and every destination the browser builds opens
+ * production: the user menu's Profile and Billing rows, the app launcher's link
+ * for an unsubscribed application, `ConnectAccessGate`'s subscribe target, and
+ * checkout. Nothing errors. The customer is simply asked to buy a second
+ * subscription in an instance where they have none.
+ *
+ * Both apps built on this SDK shipped that bug before anyone noticed, from
+ * reading "the provider takes no props" as a rule rather than as a remark about
+ * `clientId`. A root layout is a Server Component, so one spread fixes it with
+ * no browser-visible copy of the variable.
+ *
+ * ## What it deliberately leaves out
+ *
+ * `clientId` and `basePath`. The first is only needed alongside an explicit
+ * `redirectUri`, when you build the authorize URL in the browser rather than
+ * letting `signIn()` bounce through your own `/signin` route - and handing the
+ * browser a value it does not need is surface for nothing. The second is where
+ * *you* mounted the handler, which the environment does not know. Pass either
+ * yourself; a prop you pass always wins over this spread, whichever order you
+ * write them in, as long as the spread comes first.
+ *
+ * ## If you already have an origin helper
+ *
+ * Use it instead. An app that builds its own links into Connect (a "Manage
+ * team" button, a pricing page's subscribe target) needs that origin on the
+ * server too, and one function owning the read is better than this helper
+ * beside it - two readers of one variable is the shape that caused this. This
+ * exists for the integration that has no such helper, which is most of them.
+ */
+export declare function connectProviderProps(): {
+    appUrl: string;
+};
 /**
  * An httpOnly cookie holding the opaque `sessionToken`.
  *
@@ -71,6 +120,44 @@ declare function handle(request: Request): Promise<Response>;
  * when you need to configure one of them.
  */
 export { handle as GET, handle as POST };
+/**
+ * The caller's opaque Connect **session token**, or `null` when signed out.
+ *
+ * ## What it is for
+ *
+ * Every `asUser` call on the server client needs one - `workspaces.*`,
+ * `scheduling.*`, the `/data` store's per-user form - and until this existed
+ * there was no way to obtain it inside a Server Component. `getConnectSession`
+ * answers *who* the caller is and deliberately does not hand back the
+ * credential, so a page that wanted to read its own workspace's roster had to
+ * either reimplement the cookie read or route the call through the browser.
+ *
+ * ```tsx
+ * // app/settings/page.tsx
+ * const token = await getConnectSessionToken();
+ * const members = token ? await connect.workspaces.members({ asUser: token }) : [];
+ * ```
+ *
+ * ## It is the cookie, unverified
+ *
+ * This reads the session store and nothing else - **no round trip, and no
+ * check that the token is still live.** A token from a revoked or expired
+ * session is a string that looks exactly like a good one, and Connect is what
+ * answers `401` for it. So this is not a sign-in check: use
+ * `getConnectSession()` for "is somebody here", and this for "hand Connect the
+ * credential they arrived with". A non-null answer means a cookie was present,
+ * not that it works.
+ *
+ * Reads `cookies()` transitively, so under `cacheComponents` it belongs inside
+ * a `<Suspense>` boundary like any other request-scoped read.
+ *
+ * Pass a `Request` to use it where `next/headers` does not exist, and a
+ * `session` store if you did not use the default cookie - the same two escape
+ * hatches `getConnectSession` takes, for the same reasons.
+ */
+export declare function getConnectSessionToken(request?: Request, options?: {
+    session?: ConnectSessionStore;
+}): Promise<string | null>;
 /**
  * The signed-in user for a Server Component, Route Handler or Server Action,
  * or `null`.

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

@@ -138,4 +138,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.34.0";
+export declare const SDK_VERSION = "0.36.0";

package/dist/types/server/resources/scheduling.d.ts

@@ -42,7 +42,12 @@ export interface RescheduleBookingInput extends ActingAsOption {
 export interface ListBookingsInput extends ActingAsOption {
     workspaceId: string;
     status?: BookingStatus;
-    /** A Connect workspace member id - only bookings that committed them. */
+    /**
+     * A `ConnectWorkspaceMember.memberId` - only bookings that committed them.
+     *
+     * **Not a `userId`.** Pass one and the filter matches nothing, which comes
+     * back as an empty diary rather than an error.
+     */
     hostMemberId?: string;
     from?: string | Date;
     to?: string | Date;

package/dist/types/server/resources/workspaces.d.ts

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { ConnectInvitation, ConnectMemberAccess, ConnectMemberAccessResult, ConnectWorkspaceMember, UserWorkspace, WorkspaceSwitchResult } from "../../types.js";
+import type { ConnectInvitation, ConnectMemberAccess, ConnectMemberAccessResult, ConnectWorkspaceMember, UserWorkspace, WorkspaceBillingProfile, WorkspaceSwitchResult } from "../../types.js";
 /**
  * Which workspaces the signed-in user belongs to, moving between them, who
  * else is on the team, and inviting or granting access to your application.
@@ -41,6 +41,34 @@ export declare class WorkspacesResource {
     }, options: {
         asUser: string;
     }): Promise<WorkspaceSwitchResult>;
+    /**
+     * The billing identity of the workspace this session is on - its legal
+     * name, GSTIN, registered address and entity form.
+     *
+     * **For prefilling your own settings, once.** See
+     * `WorkspaceBillingProfile`, which carries the whole argument: this is the
+     * *Bill To* side, yours is the *Bill From* side, and they are the same facts
+     * for most customers without being the same field. There is no write form.
+     *
+     * ```ts
+     * // app/settings/page.tsx - offer "Use my billing details"
+     * const token = await getConnectSessionToken();
+     * const billing = token ? await connect.workspaces.billingProfile({ asUser: token }) : null;
+     * ```
+     *
+     * **Needs two things, not one.** `workspaces:read` on your key, *and*
+     * `billing:read` on the signed-in member - a tax identity belongs to
+     * whoever can already see it in Connect's billing screens, so an ordinary
+     * member gets a 403 here where they get a roster from `members()`. That
+     * cannot be granted through a role on your application, deliberately.
+     *
+     * So **treat the 403 as a normal branch**, not an error: offer the prefill
+     * to whoever can use it and let everyone else type their own details. A
+     * workspace admin is the person who sets this up anyway.
+     */
+    billingProfile(options: {
+        asUser: string;
+    }): Promise<WorkspaceBillingProfile>;
     /**
      * The team of the workspace this session is on.
      *

package/dist/types/types.d.ts

@@ -1741,6 +1741,59 @@ export interface UserWorkspace {
     /** Whether it holds an entitling subscription to your application. */
     subscribed: boolean;
 }
+/**
+ * A workspace's registered address, as its billing profile reports it.
+ *
+ * `stateCode` is the Indian state code, and it is the field that matters most
+ * of the six: it decides CGST+SGST versus IGST on anything you raise against
+ * this entity.
+ */
+export interface WorkspaceBillingAddress {
+    line1: string | null;
+    line2: string | null;
+    city: string | null;
+    stateCode: string | null;
+    postalCode: string | null;
+    countryCode: string;
+}
+/**
+ * A workspace's **self-declared** billing identity - what the customer gave
+ * CosmoOps so we can invoice them.
+ *
+ * ## Read it to prefill, not to share
+ *
+ * This is the *Bill To* side: who we invoice for the subscription. Your own
+ * application's letterhead is the *Bill From* side. For a single-entity
+ * customer they are the same three facts, which is the whole reason this is
+ * readable - a GSTIN typed twice is a GSTIN that diverges, and the copy on a
+ * quotation is the one that decides how the tax splits.
+ *
+ * They are **not the same field**, though. A group that bills us through a
+ * holding company while quoting under a trading subsidiary has to stay
+ * expressible, so copy this into your own settings on first setup and keep
+ * your copy authoritative. There is deliberately no write form: an
+ * application must not be able to edit the details its own invoices are
+ * raised against.
+ *
+ * ## Nothing here is verified
+ *
+ * It is what the customer typed, not a KYB record - no PAN check stands
+ * behind it. A convenience, never evidence of identity.
+ *
+ * Every field is nullable, because every one is optional to a customer who has
+ * not needed an invoice yet. Fall back to the workspace name you already hold
+ * on the session rather than printing an empty letterhead.
+ */
+export interface WorkspaceBillingProfile {
+    /** The registered entity name, or `null` - most workspaces never set one. */
+    legalName: string | null;
+    /** GSTIN, 15 characters. `null` for an unregistered customer. */
+    taxId: string | null;
+    /** `null` as a whole when none was given - one check, not six. */
+    billingAddress: WorkspaceBillingAddress | null;
+    /** The legal entity form, self-declared. `null` for an individual workspace. */
+    businessType: string | null;
+}
 /**
  * The result of a workspace switch.
  *
@@ -1761,6 +1814,20 @@ export interface WorkspaceSwitchResult {
  * catalog, not the member's Connect roles.
  */
 export interface ConnectWorkspaceMember {
+    /**
+     * The id the **calendar** speaks in - `Booking.hostMemberIds` holds these,
+     * and so does `listBookings`' `hostMemberId` filter.
+     *
+     * Carried beside `userId` because the two are different identifiers and
+     * scheduling is the one surface that uses this one: joining a diary to a
+     * roster, filtering it to one host, or putting a name against an
+     * appointment all go through `memberId`. Everywhere else a member is a
+     * `userId`.
+     *
+     * Opaque and workspace-scoped. Do not derive it from `userId` or address a
+     * member by it elsewhere in this API.
+     */
+    memberId: string;
     userId: string;
     email: string;
     displayName: string | null;
@@ -1885,9 +1952,15 @@ export interface Booking {
     /**
      * The workspace members committed to this appointment.
      *
-     * These are `WorkspaceMember.id` values - the same ids `workspaces.listMembers`
-     * returns and `listBookings`' `hostMemberId` filter takes, so an owner column
-     * is a lookup against a roster you already have rather than another round trip.
+     * These are `ConnectWorkspaceMember.memberId` values - what
+     * `workspaces.members()` returns as `memberId` and what `listBookings`'
+     * `hostMemberId` filter takes, so a host column is a lookup against a roster
+     * you already have rather than another round trip.
+     *
+     * **Not `userId`.** An earlier version of this comment said these were the
+     * ids `workspaces.listMembers` returns, which was wrong twice over: that
+     * method is `workspaces.members()`, and until `memberId` was added to its
+     * rows it returned no id these could be matched against at all.
      *
      * Resolved when the slot was held and frozen there: a round-robin event type
      * picks one host, a collective one commits the whole group, and re-pointing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.34.1",
+  "version": "0.36.0",
   "description": "Official server-side SDK for the CosmoOps Connect platform API - Login with Connect, entitlements, billing and metering.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
@@ -79,7 +79,7 @@
     "clean": "rm -rf dist",
     "build": "bun run clean && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && tsc -p tsconfig.types.json && bun run scripts/finalize-dist.ts",
     "verify:pack": "bun run scripts/verify-pack.ts",
-    "prepublishOnly": "bun run build && bun run verify:pack",
+    "prepublishOnly": "bun run build && bun run verify:pack && bun test",
     "test": "bun test",
     "docs:md": "typedoc --options typedoc.markdown.json",
     "storybook": "storybook dev -p 6106",