@cosmoops/connect-sdk 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -3,6 +3,142 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.37.0
+
+### The workspace switcher can stay visible at one workspace, and offer a second
+
+`ConnectWorkspaceSwitcher` has always hidden itself below two workspaces -
+right, since a switcher with one option teaches nothing. But a partner with no
+way to *create* a workspace from its own chrome had no way to help somebody
+discover that a second one is possible, either. `alwaysShow` is the opt-in:
+
+```tsx
+<AppShell workspaceSwitcher={{ alwaysShow: true }} /* ... */ />
+```
+
+Off by default, so every existing host keeps today's behaviour. On, the
+dropdown stays mounted below two workspaces and gains a "Create workspace"
+row that opens Connect - there is still no `workspaces.create()` on the SDK,
+deliberately: creating one is tied to KYC/KYB and a billing profile, which is
+Connect's job and not something an API key should be able to trigger.
+
+### A one-time plan no longer renews under the annual toggle
+
+`groupPlansByTier` filed a `billingInterval: "one-time"` plan as that tier's
+*annual* plan, because `PlanTier` only ever had two slots. For a tier that
+also sold a recurring plan under the same `planGroup`, that meant `annualSaving`
+compared a monthly charge against a one-time lump sum and produced a bogus
+"Save X%" badge, and switching `ConnectPlans`'s toggle to annual showed the
+one-time purchase as if it were this year's discounted rate on a plan that
+renews.
+
+`PlanTier.oneTime` is the fix - its own slot, which `annualSaving` and the
+annual/monthly toggle never read from. A tier that is *only* a one-time plan
+ignores the toggle entirely now, rather than happening to work by the other
+slot being empty.
+
+## 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.
+
+### A diary and a roster could not be joined
+
+One field, `ConnectWorkspaceMember.memberId`, without which no integration
+could say who an appointment belongs to.
+
+`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
@@ -92,6 +228,27 @@ 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/dist/cjs/client/components/app-shell.js

@@ -197,6 +197,6 @@ function AppShell({ name, icon, homeHref = "/", nav, secondaryNav, activePath, r
         onNavigate: closeMobile,
     }), [renderLink, activePath, closeMobile]);
     const accountRow = signedOut ? (showAuthButtons && ((0, jsx_runtime_1.jsxs)("div", { className: "flex flex-col gap-2", children: [(0, jsx_runtime_1.jsx)(auth_buttons_js_1.ConnectLoginButton, { size: "sm", fullWidth: true }), (0, jsx_runtime_1.jsx)(auth_buttons_js_1.ConnectRegisterButton, { size: "sm", fullWidth: true })] }))) : ((0, jsx_runtime_1.jsx)(user_menu_js_1.ConnectUserButton, { variant: "row", theme: theme, onThemeChange: onThemeChange }));
-    const railContent = ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(sidebar_js_1.ConnectSidebarHeader, { name: name, icon: icon, homeHref: homeHref }), workspaceSwitcher !== false && ((0, jsx_runtime_1.jsx)("div", { className: "shrink-0 px-3 pb-1", children: (0, jsx_runtime_1.jsx)(workspace_switcher_js_1.ConnectWorkspaceSwitcher, {}) })), (0, jsx_runtime_1.jsx)(sidebar_js_1.ConnectSidebarBody, { children: (0, jsx_runtime_1.jsx)(side_nav_js_1.ConnectSidebarNav, { nav: visibleNav }) }), (visibleSecondaryNav || sidebarFooter || showAppsGrid) && ((0, jsx_runtime_1.jsxs)(sidebar_js_1.ConnectSidebarFooter, { separated: false, children: [visibleSecondaryNav && (0, jsx_runtime_1.jsx)(side_nav_js_1.ConnectSidebarNav, { nav: visibleSecondaryNav }), sidebarFooter, showAppsGrid && (0, jsx_runtime_1.jsx)(apps_grid_js_1.ConnectAppsGrid, { variant: "row" })] })), accountRow && (0, jsx_runtime_1.jsx)(sidebar_js_1.ConnectSidebarFooter, { children: accountRow })] }));
+    const railContent = ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(sidebar_js_1.ConnectSidebarHeader, { name: name, icon: icon, homeHref: homeHref }), workspaceSwitcher !== false && ((0, jsx_runtime_1.jsx)("div", { className: "shrink-0 px-3 pb-1", children: (0, jsx_runtime_1.jsx)(workspace_switcher_js_1.ConnectWorkspaceSwitcher, { alwaysShow: workspaceSwitcher?.alwaysShow ?? false }) })), (0, jsx_runtime_1.jsx)(sidebar_js_1.ConnectSidebarBody, { children: (0, jsx_runtime_1.jsx)(side_nav_js_1.ConnectSidebarNav, { nav: visibleNav }) }), (visibleSecondaryNav || sidebarFooter || showAppsGrid) && ((0, jsx_runtime_1.jsxs)(sidebar_js_1.ConnectSidebarFooter, { separated: false, children: [visibleSecondaryNav && (0, jsx_runtime_1.jsx)(side_nav_js_1.ConnectSidebarNav, { nav: visibleSecondaryNav }), sidebarFooter, showAppsGrid && (0, jsx_runtime_1.jsx)(apps_grid_js_1.ConnectAppsGrid, { variant: "row" })] })), accountRow && (0, jsx_runtime_1.jsx)(sidebar_js_1.ConnectSidebarFooter, { children: accountRow })] }));
     return ((0, jsx_runtime_1.jsx)(motion_js_1.MotionProvider, { children: (0, jsx_runtime_1.jsxs)("div", { className: (0, cn_js_1.cn)("flex h-dvh bg-background", className), children: [(0, jsx_runtime_1.jsx)("a", { href: `#${CONTENT_ID}`, className: "sr-only focus:not-sr-only focus:absolute focus:start-3 focus:top-3 focus:z-50 focus:rounded-lg focus:bg-surface focus:px-3 focus:py-2 focus:text-sm focus:font-medium focus:text-foreground focus:shadow-lg focus:outline-2 focus:outline-offset-2 focus:outline-focus", children: "Skip to content" }), (0, jsx_runtime_1.jsx)(shell_context_js_1.ConnectShellProvider, { value: railShell, children: (0, jsx_runtime_1.jsx)(sidebar_js_1.ConnectSidebar, { children: railContent }) }), (0, jsx_runtime_1.jsx)(react_2.Drawer.Backdrop, { isOpen: mobileOpen, onOpenChange: setMobileOpen, children: (0, jsx_runtime_1.jsx)(react_2.Drawer.Content, { placement: "left", className: "w-[min(20rem,85vw)]", children: (0, jsx_runtime_1.jsxs)(react_2.Drawer.Dialog, { "aria-label": "Navigation menu", className: "p-0 pt-[env(safe-area-inset-top)] pb-[env(safe-area-inset-bottom)]", children: [(0, jsx_runtime_1.jsx)(react_2.Drawer.CloseTrigger, { className: "end-3 top-[calc(--spacing(3)+env(safe-area-inset-top))]" }), (0, jsx_runtime_1.jsx)(shell_context_js_1.ConnectShellProvider, { value: drawerShell, children: (0, jsx_runtime_1.jsx)("div", { className: "flex h-full flex-col [&>:first-child]:pe-10", children: railContent }) })] }) }) }), (0, jsx_runtime_1.jsxs)("div", { className: "flex min-w-0 flex-1 flex-col", children: [(0, jsx_runtime_1.jsxs)("header", { className: "flex h-14 shrink-0 items-center gap-2 border-b border-border bg-surface px-3 md:hidden", children: [(0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, variant: "tertiary", size: "sm", "aria-label": "Open navigation menu", onPress: () => setMobileOpen(true), children: (0, jsx_runtime_1.jsx)(lucide_react_1.Menu, { className: "size-5" }) }), (0, jsx_runtime_1.jsx)(logo_js_1.ConnectLogo, { name: name, icon: icon })] }), (0, jsx_runtime_1.jsx)("main", { id: CONTENT_ID, tabIndex: -1, className: "flex-1 overflow-y-auto outline-none", children: (0, jsx_runtime_1.jsxs)("div", { className: contentClassName ?? "w-full px-4 py-5 md:px-6 md:py-6", children: [gated ? (0, jsx_runtime_1.jsx)(access_gate_js_1.ConnectAccessGate, { children: children }) : children, footer] }) })] }), askAi && (0, jsx_runtime_1.jsx)(ask_ai_js_1.ConnectAskAi, { ...(askAi === true ? {} : askAi) })] }) }));
 }

package/dist/cjs/client/components/plan-pricing.js

@@ -140,20 +140,25 @@ function groupPlansByTier(plans) {
             description: plan.description,
             monthly: null,
             annual: null,
+            oneTime: null,
             annualSavingPercent: null,
         };
         if (plan.billingInterval === "monthly") {
             if (!tier.monthly || plan.price < tier.monthly.price)
                 tier.monthly = plan;
         }
-        else if (!tier.annual || plan.price < tier.annual.price) {
-            tier.annual = plan;
+        else if (plan.billingInterval === "annual") {
+            if (!tier.annual || plan.price < tier.annual.price)
+                tier.annual = plan;
+        }
+        else if (!tier.oneTime || plan.price < tier.oneTime.price) {
+            tier.oneTime = plan;
         }
         tiers.set(planGroup, tier);
     }
     return [...tiers.values()]
         .map((tier) => {
-        const identity = tier.monthly ?? tier.annual;
+        const identity = tier.monthly ?? tier.annual ?? tier.oneTime;
         return {
             ...tier,
             name: identity?.name ?? tier.name,
@@ -164,7 +169,7 @@ function groupPlansByTier(plans) {
         .sort((a, b) => tierFloorPrice(a) - tierFloorPrice(b));
 }
 function tierFloorPrice(tier) {
-    const prices = [tier.monthly, tier.annual]
+    const prices = [tier.monthly, tier.annual, tier.oneTime]
         .filter((plan) => plan !== null)
         .map((plan) => monthlyOf(plan.price, plan.billingInterval));
     return prices.length > 0 ? Math.min(...prices) : Number.MAX_SAFE_INTEGER;

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

@@ -129,7 +129,9 @@ function ConnectPlans({ planIds, hideCoupon = false, className }) {
                         // Growth tier, and marking only the row it literally subscribes to
                         // would leave its own card unmarked half the time.
                         const isCurrentTier = subscription?.plan != null &&
-                            (tier.monthly?.id === subscription.plan.id || tier.annual?.id === subscription.plan.id);
+                            (tier.monthly?.id === subscription.plan.id ||
+                                tier.annual?.id === subscription.plan.id ||
+                                tier.oneTime?.id === subscription.plan.id);
                         const isCurrent = action === "current";
                         const cadenceUnavailable = showAnnual ? tier.annual === null : tier.monthly === null;
                         return ((0, jsx_runtime_1.jsx)(motion_js_1.m.div, { variants: { hidden: { opacity: 0, y: 12 }, show: { opacity: 1, y: 0, transition: motion_js_1.ENTER } }, children: (0, jsx_runtime_1.jsxs)(react_1.Card, { className: isCurrentTier ? "h-full border-accent" : "h-full", children: [(0, jsx_runtime_1.jsxs)(react_1.Card.Header, { children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex items-start justify-between gap-2", children: [(0, jsx_runtime_1.jsx)(react_1.Card.Title, { children: tier.name }), (0, jsx_runtime_1.jsxs)("div", { className: "flex shrink-0 items-center gap-1.5", children: [tier.annualSavingPercent !== null && showAnnual && ((0, jsx_runtime_1.jsxs)(react_1.Chip, { className: "bg-accent-soft text-accent", children: ["Save ", tier.annualSavingPercent, "%"] })), isCurrentTier && (0, jsx_runtime_1.jsx)(react_1.Chip, { className: "bg-accent-soft text-accent", children: "Current" })] })] }), tier.description && (0, jsx_runtime_1.jsx)(react_1.Card.Description, { children: tier.description })] }), (0, jsx_runtime_1.jsxs)(react_1.Card.Content, { className: "flex flex-col gap-4", children: [(0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)(motion_js_1.AnimatePresence, { mode: "popLayout", initial: false, children: (0, jsx_runtime_1.jsx)(motion_js_1.m.div, { initial: { opacity: 0, y: 6 }, animate: { opacity: 1, y: 0 }, exit: { opacity: 0, y: -6 }, transition: { duration: 0.15 }, children: (0, plan_pricing_js_1.isFreePlan)(plan.price) ? ((0, jsx_runtime_1.jsx)("span", { className: "text-2xl font-semibold text-foreground", children: "Free" })) : ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("span", { className: "text-2xl font-semibold text-foreground", children: (0, plan_pricing_js_1.formatPrice)(plan.price) }), (0, jsx_runtime_1.jsx)("span", { className: "text-sm text-muted", children: (0, plan_pricing_js_1.pricePerLabel)(plan.billingInterval) })] })) }, plan.billingInterval) }), !(0, plan_pricing_js_1.isFreePlan)(plan.price) && ((0, jsx_runtime_1.jsxs)("p", { className: "mt-1 text-xs text-muted", children: ["+", plan.gstRate, "% GST"] })), cadenceUnavailable && ((0, jsx_runtime_1.jsxs)("p", { className: "mt-1 text-xs text-muted", children: ["Only sold ", (0, plan_pricing_js_1.intervalLabel)(plan.billingInterval).adverb, "."] }))] }), plan.trialDays && !(0, plan_pricing_js_1.isFreePlan)(plan.price) ? ((0, jsx_runtime_1.jsxs)("p", { className: "text-xs font-medium text-accent", children: [plan.trialDays, "-day free trial"] })) : null, plan.features.length > 0 && ((0, jsx_runtime_1.jsx)("ul", { className: "flex flex-col gap-1.5", children: plan.features.map((feature) => (
@@ -214,7 +216,13 @@ function ConnectUnsubscribeRow({ subscription, appUrl, checkout, }) {
  * monthly-only is a real thing (a free or entry plan usually is), and hiding
  * it while a customer looks at annual pricing loses them an option that is
  * still available to buy.
+ *
+ * A tier that is *only* a one-time plan ignores the toggle entirely - there
+ * is no cadence to switch between, so the price it shows must not depend on
+ * `showAnnual`.
  */
 function pickTierPlan(tier, showAnnual) {
+    if (tier.oneTime && !tier.monthly && !tier.annual)
+        return tier.oneTime;
     return showAnnual ? (tier.annual ?? tier.monthly) : (tier.monthly ?? tier.annual);
 }

package/dist/cjs/client/components/workspace-switcher.js

@@ -14,6 +14,9 @@ function workspaceInitials(name) {
     const parts = name.trim().split(/\s+/).filter(Boolean);
     return (parts.slice(0, 2).map((part) => part[0]).join("") || "?").toUpperCase();
 }
+function openExternal(url) {
+    window.open(url, "_blank", "noopener,noreferrer");
+}
 /**
  * Switches which workspace this application is looking at.
  *
@@ -22,11 +25,15 @@ function workspaceInitials(name) {
  * it reads as a heading for the nav rather than as one more destination.
  *
  * It decides for itself whether to appear: an account with one workspace is
- * shown nothing, because a switcher offering one option teaches the user
- * nothing and costs a row of chrome on every screen. That is the opposite of
- * Connect's own switcher, which always renders - Connect is where a workspace
- * is *created*, so hiding it at one workspace would guarantee nobody ever
- * reached two. A partner application creates nothing, so it has no such duty.
+ * shown nothing by default, because a switcher offering one option teaches
+ * the user nothing and costs a row of chrome on every screen. That is the
+ * opposite of Connect's own switcher, which always renders - Connect is where
+ * a workspace is *created*, so hiding it at one workspace would guarantee
+ * nobody ever reached two. `alwaysShow` is the escape hatch for a partner
+ * application that wants that same discoverability without becoming Connect:
+ * it keeps the dropdown open below two workspaces and adds a row that sends
+ * the member to Connect to actually create one, since there is nothing here
+ * that can.
  *
  * **Authorization is the data, not a prop.** The list comes from the caller's
  * own session (`GET /workspaces` takes no user id), so a workspace the user
@@ -45,19 +52,22 @@ function workspaceInitials(name) {
  * component - so the only thing to do afterwards is reload, which is what
  * `onSwitched` defaults to.
  */
-function ConnectWorkspaceSwitcher({ onSwitched, row = true, className, }) {
-    const { mutateResource } = (0, provider_js_1.useConnect)();
+function ConnectWorkspaceSwitcher({ onSwitched, row = true, className, alwaysShow = false, }) {
+    const { mutateResource, appUrl } = (0, provider_js_1.useConnect)();
     const { collapsed } = (0, shell_context_js_1.useConnectShell)();
     const user = (0, provider_js_1.useConnectUser)();
     const { data, isLoading } = (0, provider_js_1.useConnectWorkspaces)();
     const [switching, setSwitching] = (0, react_1.useState)(null);
     const [error, setError] = (0, react_1.useState)(null);
     const workspaces = data?.workspaces ?? [];
-    // Nothing to switch between, or nothing loaded yet. Deliberately renders
-    // `null` rather than a skeleton: this sits in persistent chrome, and a
-    // placeholder that resolves to nothing for most accounts is worse than
-    // appearing a moment late for the few who have two.
-    if (isLoading || workspaces.length < 2)
+    // Nothing loaded yet. Deliberately renders `null` rather than a skeleton:
+    // this sits in persistent chrome, and a placeholder that resolves to
+    // nothing for most accounts is worse than appearing a moment late.
+    //
+    // Below one workspace, `alwaysShow` is the only thing that keeps this
+    // rendering - the default stays "nothing to switch between" for every
+    // host that hasn't opted in.
+    if (isLoading || (!alwaysShow && workspaces.length < 2))
         return null;
     const active = workspaces.find((workspace) => workspace.isActive);
     const label = active?.name ?? user?.workspaceName ?? "Workspace";
@@ -87,7 +97,7 @@ function ConnectWorkspaceSwitcher({ onSwitched, row = true, className, }) {
                     // A 32px tile rather than a 20px glyph, so the initials land on the
                     // same optical centre the avatar below them uses - see
                     // `SIDEBAR_ROW_TILE`. Collapsed, this tile *is* the switcher.
-                    (0, jsx_runtime_1.jsxs)(react_2.Button, { variant: "tertiary", "aria-label": `Workspace: ${label}. Switch workspace`, className: (0, shell_context_js_1.sidebarRowClass)({ tile: true, className }), children: [(0, jsx_runtime_1.jsx)("span", { className: "flex size-8 shrink-0 items-center justify-center rounded-lg bg-accent-soft text-xs font-semibold text-accent", children: workspaceInitials(label) }), (0, jsx_runtime_1.jsx)(shell_context_js_1.SidebarLabel, { className: "text-sm font-medium text-foreground", children: label }), (0, jsx_runtime_1.jsx)(motion_js_1.m.span, { className: "shrink-0 text-muted", animate: { opacity: collapsed ? 0 : 1 }, transition: collapsed ? { duration: 0.1 } : { duration: 0.18, delay: 0.1 }, "aria-hidden": true, children: (0, jsx_runtime_1.jsx)(lucide_react_1.ChevronsUpDown, { className: "size-4" }) })] })) : ((0, jsx_runtime_1.jsxs)(react_2.Button, { variant: "secondary", size: "sm", className: "w-full justify-between", children: [(0, jsx_runtime_1.jsx)("span", { className: "truncate", children: label }), (0, jsx_runtime_1.jsx)(lucide_react_1.ChevronsUpDown, { className: "size-4 shrink-0 text-muted", "aria-hidden": "true" })] })), (0, jsx_runtime_1.jsx)(react_2.Dropdown.Popover, { children: (0, jsx_runtime_1.jsx)(react_2.ListBox, { children: workspaces.map((workspace) => ((0, jsx_runtime_1.jsxs)(react_2.ListBox.Item, { id: workspace.workspaceId, textValue: workspace.name, isDisabled: !selectable(workspace) || switching !== null, onAction: () => void handleSwitch(workspace), children: [(0, jsx_runtime_1.jsxs)("div", { className: "min-w-0", children: [(0, jsx_runtime_1.jsx)("p", { className: "truncate text-sm", children: workspace.name }), selectable(workspace) ? null : ((0, jsx_runtime_1.jsx)("p", { className: "truncate text-xs text-muted", children: reasonUnavailable(workspace) }))] }), (0, jsx_runtime_1.jsx)(react_2.ListBox.ItemIndicator, {})] }, workspace.workspaceId))) }) })] }), error && !collapsed ? (0, jsx_runtime_1.jsx)("p", { className: "mt-1 px-2 text-xs text-danger", children: error }) : null] }));
+                    (0, jsx_runtime_1.jsxs)(react_2.Button, { variant: "tertiary", "aria-label": `Workspace: ${label}. Switch workspace`, className: (0, shell_context_js_1.sidebarRowClass)({ tile: true, className }), children: [(0, jsx_runtime_1.jsx)("span", { className: "flex size-8 shrink-0 items-center justify-center rounded-lg bg-accent-soft text-xs font-semibold text-accent", children: workspaceInitials(label) }), (0, jsx_runtime_1.jsx)(shell_context_js_1.SidebarLabel, { className: "text-sm font-medium text-foreground", children: label }), (0, jsx_runtime_1.jsx)(motion_js_1.m.span, { className: "shrink-0 text-muted", animate: { opacity: collapsed ? 0 : 1 }, transition: collapsed ? { duration: 0.1 } : { duration: 0.18, delay: 0.1 }, "aria-hidden": true, children: (0, jsx_runtime_1.jsx)(lucide_react_1.ChevronsUpDown, { className: "size-4" }) })] })) : ((0, jsx_runtime_1.jsxs)(react_2.Button, { variant: "secondary", size: "sm", className: "w-full justify-between", children: [(0, jsx_runtime_1.jsx)("span", { className: "truncate", children: label }), (0, jsx_runtime_1.jsx)(lucide_react_1.ChevronsUpDown, { className: "size-4 shrink-0 text-muted", "aria-hidden": "true" })] })), (0, jsx_runtime_1.jsx)(react_2.Dropdown.Popover, { children: (0, jsx_runtime_1.jsxs)(react_2.ListBox, { children: [workspaces.map((workspace) => ((0, jsx_runtime_1.jsxs)(react_2.ListBox.Item, { id: workspace.workspaceId, textValue: workspace.name, isDisabled: !selectable(workspace) || switching !== null, onAction: () => void handleSwitch(workspace), children: [(0, jsx_runtime_1.jsxs)("div", { className: "min-w-0", children: [(0, jsx_runtime_1.jsx)("p", { className: "truncate text-sm", children: workspace.name }), selectable(workspace) ? null : ((0, jsx_runtime_1.jsx)("p", { className: "truncate text-xs text-muted", children: reasonUnavailable(workspace) }))] }), (0, jsx_runtime_1.jsx)(react_2.ListBox.ItemIndicator, {})] }, workspace.workspaceId))), alwaysShow ? ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [workspaces.length > 0 && (0, jsx_runtime_1.jsx)(react_2.Separator, {}), (0, jsx_runtime_1.jsxs)(react_2.ListBox.Item, { id: "__create_workspace", textValue: "Create workspace", onAction: () => openExternal(appUrl), children: [(0, jsx_runtime_1.jsx)(lucide_react_1.Plus, { className: "size-4 shrink-0 text-muted", "aria-hidden": true }), (0, jsx_runtime_1.jsx)("p", { className: "truncate text-sm", children: "Create workspace" })] })] })) : null] }) })] }), error && !collapsed ? (0, jsx_runtime_1.jsx)("p", { className: "mt-1 px-2 text-xs text-danger", children: error }) : null] }));
 }
 /** Belongs to the user, and usable here. The same two facts `switch` enforces. */
 function selectable(workspace) {

package/dist/cjs/next/index.js

@@ -41,6 +41,7 @@ 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");
@@ -352,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.35.0";
+exports.SDK_VERSION = "0.37.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/client/components/app-shell.js

@@ -194,6 +194,6 @@ export function AppShell({ name, icon, homeHref = "/", nav, secondaryNav, active
         onNavigate: closeMobile,
     }), [renderLink, activePath, closeMobile]);
     const accountRow = signedOut ? (showAuthButtons && (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(ConnectLoginButton, { size: "sm", fullWidth: true }), _jsx(ConnectRegisterButton, { size: "sm", fullWidth: true })] }))) : (_jsx(ConnectUserButton, { variant: "row", theme: theme, onThemeChange: onThemeChange }));
-    const railContent = (_jsxs(_Fragment, { children: [_jsx(ConnectSidebarHeader, { name: name, icon: icon, homeHref: homeHref }), workspaceSwitcher !== false && (_jsx("div", { className: "shrink-0 px-3 pb-1", children: _jsx(ConnectWorkspaceSwitcher, {}) })), _jsx(ConnectSidebarBody, { children: _jsx(ConnectSidebarNav, { nav: visibleNav }) }), (visibleSecondaryNav || sidebarFooter || showAppsGrid) && (_jsxs(ConnectSidebarFooter, { separated: false, children: [visibleSecondaryNav && _jsx(ConnectSidebarNav, { nav: visibleSecondaryNav }), sidebarFooter, showAppsGrid && _jsx(ConnectAppsGrid, { variant: "row" })] })), accountRow && _jsx(ConnectSidebarFooter, { children: accountRow })] }));
+    const railContent = (_jsxs(_Fragment, { children: [_jsx(ConnectSidebarHeader, { name: name, icon: icon, homeHref: homeHref }), workspaceSwitcher !== false && (_jsx("div", { className: "shrink-0 px-3 pb-1", children: _jsx(ConnectWorkspaceSwitcher, { alwaysShow: workspaceSwitcher?.alwaysShow ?? false }) })), _jsx(ConnectSidebarBody, { children: _jsx(ConnectSidebarNav, { nav: visibleNav }) }), (visibleSecondaryNav || sidebarFooter || showAppsGrid) && (_jsxs(ConnectSidebarFooter, { separated: false, children: [visibleSecondaryNav && _jsx(ConnectSidebarNav, { nav: visibleSecondaryNav }), sidebarFooter, showAppsGrid && _jsx(ConnectAppsGrid, { variant: "row" })] })), accountRow && _jsx(ConnectSidebarFooter, { children: accountRow })] }));
     return (_jsx(MotionProvider, { children: _jsxs("div", { className: cn("flex h-dvh bg-background", className), children: [_jsx("a", { href: `#${CONTENT_ID}`, className: "sr-only focus:not-sr-only focus:absolute focus:start-3 focus:top-3 focus:z-50 focus:rounded-lg focus:bg-surface focus:px-3 focus:py-2 focus:text-sm focus:font-medium focus:text-foreground focus:shadow-lg focus:outline-2 focus:outline-offset-2 focus:outline-focus", children: "Skip to content" }), _jsx(ConnectShellProvider, { value: railShell, children: _jsx(ConnectSidebar, { children: railContent }) }), _jsx(Drawer.Backdrop, { isOpen: mobileOpen, onOpenChange: setMobileOpen, children: _jsx(Drawer.Content, { placement: "left", className: "w-[min(20rem,85vw)]", children: _jsxs(Drawer.Dialog, { "aria-label": "Navigation menu", className: "p-0 pt-[env(safe-area-inset-top)] pb-[env(safe-area-inset-bottom)]", children: [_jsx(Drawer.CloseTrigger, { className: "end-3 top-[calc(--spacing(3)+env(safe-area-inset-top))]" }), _jsx(ConnectShellProvider, { value: drawerShell, children: _jsx("div", { className: "flex h-full flex-col [&>:first-child]:pe-10", children: railContent }) })] }) }) }), _jsxs("div", { className: "flex min-w-0 flex-1 flex-col", children: [_jsxs("header", { className: "flex h-14 shrink-0 items-center gap-2 border-b border-border bg-surface px-3 md:hidden", children: [_jsx(Button, { isIconOnly: true, variant: "tertiary", size: "sm", "aria-label": "Open navigation menu", onPress: () => setMobileOpen(true), children: _jsx(Menu, { className: "size-5" }) }), _jsx(ConnectLogo, { name: name, icon: icon })] }), _jsx("main", { id: CONTENT_ID, tabIndex: -1, className: "flex-1 overflow-y-auto outline-none", children: _jsxs("div", { className: contentClassName ?? "w-full px-4 py-5 md:px-6 md:py-6", children: [gated ? _jsx(ConnectAccessGate, { children: children }) : children, footer] }) })] }), askAi && _jsx(ConnectAskAi, { ...(askAi === true ? {} : askAi) })] }) }));
 }

package/dist/esm/client/components/plan-pricing.js

@@ -126,20 +126,25 @@ export function groupPlansByTier(plans) {
             description: plan.description,
             monthly: null,
             annual: null,
+            oneTime: null,
             annualSavingPercent: null,
         };
         if (plan.billingInterval === "monthly") {
             if (!tier.monthly || plan.price < tier.monthly.price)
                 tier.monthly = plan;
         }
-        else if (!tier.annual || plan.price < tier.annual.price) {
-            tier.annual = plan;
+        else if (plan.billingInterval === "annual") {
+            if (!tier.annual || plan.price < tier.annual.price)
+                tier.annual = plan;
+        }
+        else if (!tier.oneTime || plan.price < tier.oneTime.price) {
+            tier.oneTime = plan;
         }
         tiers.set(planGroup, tier);
     }
     return [...tiers.values()]
         .map((tier) => {
-        const identity = tier.monthly ?? tier.annual;
+        const identity = tier.monthly ?? tier.annual ?? tier.oneTime;
         return {
             ...tier,
             name: identity?.name ?? tier.name,
@@ -150,7 +155,7 @@ export function groupPlansByTier(plans) {
         .sort((a, b) => tierFloorPrice(a) - tierFloorPrice(b));
 }
 function tierFloorPrice(tier) {
-    const prices = [tier.monthly, tier.annual]
+    const prices = [tier.monthly, tier.annual, tier.oneTime]
         .filter((plan) => plan !== null)
         .map((plan) => monthlyOf(plan.price, plan.billingInterval));
     return prices.length > 0 ? Math.min(...prices) : Number.MAX_SAFE_INTEGER;

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

@@ -126,7 +126,9 @@ export function ConnectPlans({ planIds, hideCoupon = false, className }) {
                         // Growth tier, and marking only the row it literally subscribes to
                         // would leave its own card unmarked half the time.
                         const isCurrentTier = subscription?.plan != null &&
-                            (tier.monthly?.id === subscription.plan.id || tier.annual?.id === subscription.plan.id);
+                            (tier.monthly?.id === subscription.plan.id ||
+                                tier.annual?.id === subscription.plan.id ||
+                                tier.oneTime?.id === subscription.plan.id);
                         const isCurrent = action === "current";
                         const cadenceUnavailable = showAnnual ? tier.annual === null : tier.monthly === null;
                         return (_jsx(m.div, { variants: { hidden: { opacity: 0, y: 12 }, show: { opacity: 1, y: 0, transition: ENTER } }, children: _jsxs(Card, { className: isCurrentTier ? "h-full border-accent" : "h-full", children: [_jsxs(Card.Header, { children: [_jsxs("div", { className: "flex items-start justify-between gap-2", children: [_jsx(Card.Title, { children: tier.name }), _jsxs("div", { className: "flex shrink-0 items-center gap-1.5", children: [tier.annualSavingPercent !== null && showAnnual && (_jsxs(Chip, { className: "bg-accent-soft text-accent", children: ["Save ", tier.annualSavingPercent, "%"] })), isCurrentTier && _jsx(Chip, { className: "bg-accent-soft text-accent", children: "Current" })] })] }), tier.description && _jsx(Card.Description, { children: tier.description })] }), _jsxs(Card.Content, { className: "flex flex-col gap-4", children: [_jsxs("div", { children: [_jsx(AnimatePresence, { mode: "popLayout", initial: false, children: _jsx(m.div, { initial: { opacity: 0, y: 6 }, animate: { opacity: 1, y: 0 }, exit: { opacity: 0, y: -6 }, transition: { duration: 0.15 }, children: isFreePlan(plan.price) ? (_jsx("span", { className: "text-2xl font-semibold text-foreground", children: "Free" })) : (_jsxs(_Fragment, { children: [_jsx("span", { className: "text-2xl font-semibold text-foreground", children: formatPrice(plan.price) }), _jsx("span", { className: "text-sm text-muted", children: pricePerLabel(plan.billingInterval) })] })) }, plan.billingInterval) }), !isFreePlan(plan.price) && (_jsxs("p", { className: "mt-1 text-xs text-muted", children: ["+", plan.gstRate, "% GST"] })), cadenceUnavailable && (_jsxs("p", { className: "mt-1 text-xs text-muted", children: ["Only sold ", intervalLabel(plan.billingInterval).adverb, "."] }))] }), plan.trialDays && !isFreePlan(plan.price) ? (_jsxs("p", { className: "text-xs font-medium text-accent", children: [plan.trialDays, "-day free trial"] })) : null, plan.features.length > 0 && (_jsx("ul", { className: "flex flex-col gap-1.5", children: plan.features.map((feature) => (
@@ -211,7 +213,13 @@ function ConnectUnsubscribeRow({ subscription, appUrl, checkout, }) {
  * monthly-only is a real thing (a free or entry plan usually is), and hiding
  * it while a customer looks at annual pricing loses them an option that is
  * still available to buy.
+ *
+ * A tier that is *only* a one-time plan ignores the toggle entirely - there
+ * is no cadence to switch between, so the price it shows must not depend on
+ * `showAnnual`.
  */
 function pickTierPlan(tier, showAnnual) {
+    if (tier.oneTime && !tier.monthly && !tier.annual)
+        return tier.oneTime;
     return showAnnual ? (tier.annual ?? tier.monthly) : (tier.monthly ?? tier.annual);
 }

package/dist/esm/client/components/workspace-switcher.js

@@ -1,8 +1,8 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useState } from "react";
-import { Button, Dropdown, ListBox } from "@heroui/react";
-import { ChevronsUpDown } from "lucide-react";
+import { Button, Dropdown, ListBox, Separator } from "@heroui/react";
+import { ChevronsUpDown, Plus } from "lucide-react";
 import { useConnect, useConnectUser, useConnectWorkspaces } from "../provider.js";
 import { m } from "./motion.js";
 import { SidebarLabel, sidebarRowClass, useConnectShell } from "./shell-context.js";
@@ -11,6 +11,9 @@ function workspaceInitials(name) {
     const parts = name.trim().split(/\s+/).filter(Boolean);
     return (parts.slice(0, 2).map((part) => part[0]).join("") || "?").toUpperCase();
 }
+function openExternal(url) {
+    window.open(url, "_blank", "noopener,noreferrer");
+}
 /**
  * Switches which workspace this application is looking at.
  *
@@ -19,11 +22,15 @@ function workspaceInitials(name) {
  * it reads as a heading for the nav rather than as one more destination.
  *
  * It decides for itself whether to appear: an account with one workspace is
- * shown nothing, because a switcher offering one option teaches the user
- * nothing and costs a row of chrome on every screen. That is the opposite of
- * Connect's own switcher, which always renders - Connect is where a workspace
- * is *created*, so hiding it at one workspace would guarantee nobody ever
- * reached two. A partner application creates nothing, so it has no such duty.
+ * shown nothing by default, because a switcher offering one option teaches
+ * the user nothing and costs a row of chrome on every screen. That is the
+ * opposite of Connect's own switcher, which always renders - Connect is where
+ * a workspace is *created*, so hiding it at one workspace would guarantee
+ * nobody ever reached two. `alwaysShow` is the escape hatch for a partner
+ * application that wants that same discoverability without becoming Connect:
+ * it keeps the dropdown open below two workspaces and adds a row that sends
+ * the member to Connect to actually create one, since there is nothing here
+ * that can.
  *
  * **Authorization is the data, not a prop.** The list comes from the caller's
  * own session (`GET /workspaces` takes no user id), so a workspace the user
@@ -42,19 +49,22 @@ function workspaceInitials(name) {
  * component - so the only thing to do afterwards is reload, which is what
  * `onSwitched` defaults to.
  */
-export function ConnectWorkspaceSwitcher({ onSwitched, row = true, className, }) {
-    const { mutateResource } = useConnect();
+export function ConnectWorkspaceSwitcher({ onSwitched, row = true, className, alwaysShow = false, }) {
+    const { mutateResource, appUrl } = useConnect();
     const { collapsed } = useConnectShell();
     const user = useConnectUser();
     const { data, isLoading } = useConnectWorkspaces();
     const [switching, setSwitching] = useState(null);
     const [error, setError] = useState(null);
     const workspaces = data?.workspaces ?? [];
-    // Nothing to switch between, or nothing loaded yet. Deliberately renders
-    // `null` rather than a skeleton: this sits in persistent chrome, and a
-    // placeholder that resolves to nothing for most accounts is worse than
-    // appearing a moment late for the few who have two.
-    if (isLoading || workspaces.length < 2)
+    // Nothing loaded yet. Deliberately renders `null` rather than a skeleton:
+    // this sits in persistent chrome, and a placeholder that resolves to
+    // nothing for most accounts is worse than appearing a moment late.
+    //
+    // Below one workspace, `alwaysShow` is the only thing that keeps this
+    // rendering - the default stays "nothing to switch between" for every
+    // host that hasn't opted in.
+    if (isLoading || (!alwaysShow && workspaces.length < 2))
         return null;
     const active = workspaces.find((workspace) => workspace.isActive);
     const label = active?.name ?? user?.workspaceName ?? "Workspace";
@@ -84,7 +94,7 @@ export function ConnectWorkspaceSwitcher({ onSwitched, row = true, className, })
                     // A 32px tile rather than a 20px glyph, so the initials land on the
                     // same optical centre the avatar below them uses - see
                     // `SIDEBAR_ROW_TILE`. Collapsed, this tile *is* the switcher.
-                    _jsxs(Button, { variant: "tertiary", "aria-label": `Workspace: ${label}. Switch workspace`, className: sidebarRowClass({ tile: true, className }), children: [_jsx("span", { className: "flex size-8 shrink-0 items-center justify-center rounded-lg bg-accent-soft text-xs font-semibold text-accent", children: workspaceInitials(label) }), _jsx(SidebarLabel, { className: "text-sm font-medium text-foreground", children: label }), _jsx(m.span, { className: "shrink-0 text-muted", animate: { opacity: collapsed ? 0 : 1 }, transition: collapsed ? { duration: 0.1 } : { duration: 0.18, delay: 0.1 }, "aria-hidden": true, children: _jsx(ChevronsUpDown, { className: "size-4" }) })] })) : (_jsxs(Button, { variant: "secondary", size: "sm", className: "w-full justify-between", children: [_jsx("span", { className: "truncate", children: label }), _jsx(ChevronsUpDown, { className: "size-4 shrink-0 text-muted", "aria-hidden": "true" })] })), _jsx(Dropdown.Popover, { children: _jsx(ListBox, { children: workspaces.map((workspace) => (_jsxs(ListBox.Item, { id: workspace.workspaceId, textValue: workspace.name, isDisabled: !selectable(workspace) || switching !== null, onAction: () => void handleSwitch(workspace), children: [_jsxs("div", { className: "min-w-0", children: [_jsx("p", { className: "truncate text-sm", children: workspace.name }), selectable(workspace) ? null : (_jsx("p", { className: "truncate text-xs text-muted", children: reasonUnavailable(workspace) }))] }), _jsx(ListBox.ItemIndicator, {})] }, workspace.workspaceId))) }) })] }), error && !collapsed ? _jsx("p", { className: "mt-1 px-2 text-xs text-danger", children: error }) : null] }));
+                    _jsxs(Button, { variant: "tertiary", "aria-label": `Workspace: ${label}. Switch workspace`, className: sidebarRowClass({ tile: true, className }), children: [_jsx("span", { className: "flex size-8 shrink-0 items-center justify-center rounded-lg bg-accent-soft text-xs font-semibold text-accent", children: workspaceInitials(label) }), _jsx(SidebarLabel, { className: "text-sm font-medium text-foreground", children: label }), _jsx(m.span, { className: "shrink-0 text-muted", animate: { opacity: collapsed ? 0 : 1 }, transition: collapsed ? { duration: 0.1 } : { duration: 0.18, delay: 0.1 }, "aria-hidden": true, children: _jsx(ChevronsUpDown, { className: "size-4" }) })] })) : (_jsxs(Button, { variant: "secondary", size: "sm", className: "w-full justify-between", children: [_jsx("span", { className: "truncate", children: label }), _jsx(ChevronsUpDown, { className: "size-4 shrink-0 text-muted", "aria-hidden": "true" })] })), _jsx(Dropdown.Popover, { children: _jsxs(ListBox, { children: [workspaces.map((workspace) => (_jsxs(ListBox.Item, { id: workspace.workspaceId, textValue: workspace.name, isDisabled: !selectable(workspace) || switching !== null, onAction: () => void handleSwitch(workspace), children: [_jsxs("div", { className: "min-w-0", children: [_jsx("p", { className: "truncate text-sm", children: workspace.name }), selectable(workspace) ? null : (_jsx("p", { className: "truncate text-xs text-muted", children: reasonUnavailable(workspace) }))] }), _jsx(ListBox.ItemIndicator, {})] }, workspace.workspaceId))), alwaysShow ? (_jsxs(_Fragment, { children: [workspaces.length > 0 && _jsx(Separator, {}), _jsxs(ListBox.Item, { id: "__create_workspace", textValue: "Create workspace", onAction: () => openExternal(appUrl), children: [_jsx(Plus, { className: "size-4 shrink-0 text-muted", "aria-hidden": true }), _jsx("p", { className: "truncate text-sm", children: "Create workspace" })] })] })) : null] }) })] }), error && !collapsed ? _jsx("p", { className: "mt-1 px-2 text-xs text-danger", children: error }) : null] }));
 }
 /** Belongs to the user, and usable here. The same two facts `switch` enforces. */
 function selectable(workspace) {

package/dist/esm/next/index.js

@@ -321,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.35.0";
+export const SDK_VERSION = "0.37.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/app-shell.d.ts

@@ -36,8 +36,14 @@ export interface AppShellProps {
      * for an account with only one workspace - so the reason to pass `false` is
      * not "most users have one" (already handled) but "this application renders
      * its own".
+     *
+     * Pass `{ alwaysShow: true }` instead of `true` to keep it mounted below
+     * two workspaces too - see `ConnectWorkspaceSwitcherProps.alwaysShow` for
+     * what that changes about the dropdown.
      */
-    workspaceSwitcher?: false;
+    workspaceSwitcher?: false | {
+        alwaysShow?: boolean;
+    };
     /** Rendered below `children`, inside the scrolling content pane. */
     footer?: ReactNode;
     /**

package/dist/types/client/components/plan-pricing.d.ts

@@ -74,6 +74,16 @@ export interface PlanTier {
     description: string;
     monthly: Plan | null;
     annual: Plan | null;
+    /**
+     * A plan paid once, never on a cadence - its own slot rather than falling
+     * into `annual`. A one-time plan has no renewal to discount against, so
+     * filing it as "annual" used to let a tier mixing a recurring plan with a
+     * one-time one compute a `annualSavingPercent` between a monthly charge and
+     * a lump sum, and offered the one-time purchase under the annual toggle as
+     * though it renewed. `pickTierPlan` in `plans.tsx` is the only reader that
+     * needs to know this slot exists.
+     */
+    oneTime: Plan | null;
     /** Whole-percent saving from paying annually, or `null` when this tier has no pair to compare. */
     annualSavingPercent: number | null;
 }

package/dist/types/client/components/workspace-switcher.d.ts

@@ -14,6 +14,21 @@ export interface ConnectWorkspaceSwitcherProps {
      */
     row?: boolean;
     className?: string;
+    /**
+     * Render even when the signed-in account has fewer than two workspaces.
+     *
+     * Off by default, which keeps this component's documented posture for
+     * every other host: an account with one workspace sees nothing, because a
+     * switcher offering one option teaches it nothing. Pass `true` on an
+     * application that wants a single-workspace account to be able to
+     * discover - and start - creating a second one without leaving its own
+     * chrome. There is deliberately no `workspaces.create()` on the SDK:
+     * creating a workspace is Connect's job, tied to KYC/KYB and a billing
+     * profile, not something an API key should be able to trigger - so turning
+     * this on also adds a "Create workspace" row that opens Connect, rather
+     * than pretending the switcher can do it itself.
+     */
+    alwaysShow?: boolean;
 }
 /**
  * Switches which workspace this application is looking at.
@@ -23,11 +38,15 @@ export interface ConnectWorkspaceSwitcherProps {
  * it reads as a heading for the nav rather than as one more destination.
  *
  * It decides for itself whether to appear: an account with one workspace is
- * shown nothing, because a switcher offering one option teaches the user
- * nothing and costs a row of chrome on every screen. That is the opposite of
- * Connect's own switcher, which always renders - Connect is where a workspace
- * is *created*, so hiding it at one workspace would guarantee nobody ever
- * reached two. A partner application creates nothing, so it has no such duty.
+ * shown nothing by default, because a switcher offering one option teaches
+ * the user nothing and costs a row of chrome on every screen. That is the
+ * opposite of Connect's own switcher, which always renders - Connect is where
+ * a workspace is *created*, so hiding it at one workspace would guarantee
+ * nobody ever reached two. `alwaysShow` is the escape hatch for a partner
+ * application that wants that same discoverability without becoming Connect:
+ * it keeps the dropdown open below two workspaces and adds a row that sends
+ * the member to Connect to actually create one, since there is nothing here
+ * that can.
  *
  * **Authorization is the data, not a prop.** The list comes from the caller's
  * own session (`GET /workspaces` takes no user id), so a workspace the user
@@ -46,4 +65,4 @@ export interface ConnectWorkspaceSwitcherProps {
  * component - so the only thing to do afterwards is reload, which is what
  * `onSwitched` defaults to.
  */
-export declare function ConnectWorkspaceSwitcher({ onSwitched, row, className, }: Readonly<ConnectWorkspaceSwitcherProps>): import("react").JSX.Element | null;
+export declare function ConnectWorkspaceSwitcher({ onSwitched, row, className, alwaysShow, }: Readonly<ConnectWorkspaceSwitcherProps>): import("react").JSX.Element | null;

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

@@ -120,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.35.0";
+export declare const SDK_VERSION = "0.37.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.35.0",
+  "version": "0.37.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",