@cosmoops/connect-sdk 0.35.0 → 0.36.0

package/CHANGELOG.md

@@ -3,6 +3,109 @@
 `@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
@@ -92,6 +195,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/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.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/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.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/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.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.35.0",
+  "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",