@cosmoops/connect-sdk 0.9.0 → 0.15.0

package/CHANGELOG.md

@@ -3,6 +3,503 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.15.0
+
+Your application's own database stops being a toy. Real queries, real
+aggregations, and real atomicity - without ever handing you a Firebase
+credential.
+
+Everything here is `data.*`. The rest of the SDK is unchanged.
+
+### Added
+
+- **`data.aggregate()` - count, sum and average in the database.**
+
+  ```ts
+  const { values } = await connect.data.aggregate({
+    workspaceId,
+    collection: "deals",
+    filters: [{ field: "outcome", op: "==", value: "won" }],
+    aggregations: [
+      { op: "count", alias: "count" },
+      { op: "sum", field: "value", alias: "total" },
+    ],
+  });
+  ```
+
+  Firestore bills an aggregation by the index entries it scans rather than by
+  the documents it would have returned, so a dashboard tile over ten thousand
+  rows costs a handful of reads and stays flat as the collection grows. Every
+  integration that had no aggregate call to reach for was paging the rows into
+  its own process and adding them up, which is an unbounded read wearing a
+  different name.
+
+  A `sum` or `avg` over nothing answers `null`, not `0` - "nothing matched"
+  and "the total is zero" are different facts.
+
+- **`data.commit()` - a set of writes that all land or none do**, across as
+  many of your collections as they name.
+
+  You never hold a transaction: a handle passed across an HTTP boundary is a
+  server-side lock whose duration your network controls. Instead you read,
+  decide, and commit conditional on nothing having moved. Connect runs the
+  whole set as one short transaction on its side.
+
+  ```ts
+  import { increment, unchangedSince } from "@cosmoops/connect-sdk";
+
+  await connect.data.commit({
+    workspaceId,
+    operations: [
+      { op: "create", collection: "ledger", id, data: entry },
+      {
+        op: "merge",
+        collection: "funds",
+        id: entry.fundId,
+        data: { balancePaise: increment(entry.amountPaise) },
+      },
+    ],
+  });
+  ```
+
+  A stale precondition throws `ConnectError` with status 409 and writes
+  nothing.
+
+- **`data.transaction(build)`** - the read/decide/commit loop with the retry
+  written once. `build` re-runs against fresh reads when a precondition went
+  stale, and only a 409 is retried: a 403 means the operation was wrong rather
+  than late.
+
+- **Field transforms**: `increment`, `serverTimestamp`, `arrayUnion`,
+  `arrayRemove`, `deleteField`, plus the `unchangedSince(document)` and
+  `documentExists()` precondition builders. All exported from the root entry,
+  so a Server Component and a client component build the same write the same
+  way.
+
+  `increment` is the one that genuinely cannot be done any other way: it is
+  commutative, so two concurrent increments both land - where read-add-write
+  from your own process loses one of them however carefully it retries.
+
+- **Composite indexes.** Declare them per collection on your application's
+  **Store** tab and Connect builds them in your database, reconciling on every
+  save - including removing ones you no longer declare, which would otherwise
+  be paid for on every document write forever.
+
+  This is what lifts the old one-filter ceiling. A query with no matching
+  index is still refused, but the refusal now names the index to declare
+  rather than telling you the shape is impossible.
+
+- **`_updateTime`** on every document that came from a read - Firestore's own
+  write timestamp, and the value a `{ updateTime }` precondition is compared
+  against. Not `_updatedAt`: a transform in the same commit can move that
+  field, and cannot touch the write timestamp.
+
+### Changed - breaking
+
+- **`data.query({ filter })` is now `data.query({ filters })`**, a list, ANDed.
+  `data.scan` takes the same. One filter becomes a one-element array:
+
+  ```ts
+  // Before
+  await connect.data.query({ workspaceId, collection: "tickets", filter: f });
+  // After
+  await connect.data.query({ workspaceId, collection: "tickets", filters: [f] });
+  ```
+
+  The server still accepts the singular `filter` query parameter, so an
+  integration on 0.14 or earlier keeps working against an upgraded Connect -
+  but the SDK method has moved and this one is a code change.
+
+- **`Plan.billingInterval` and `SubscribedPlan.billingInterval` are now
+  `BillingInterval`**, which adds `"one-time"`. Connect has been able to
+  return it; the SDK type could not represent it, so a one-time plan was typed
+  as monthly and rendered "per month" - a false price rather than a cosmetic
+  slip. `ConnectPlans`, `ConnectSubscription` and the subscribe dialog now
+  label it "once".
+
+  Exhaustive `switch`es on a billing interval will need a third arm.
+
+### Added - operators
+
+- `not-in` joins the query operators.
+
+## 0.14.0
+
+One session answers "who is this?" once, and the subscribe button goes where
+it says it does.
+
+### Changed - breaking
+
+- **`applicationRole` and `platformAccess` are now `role`, `permissions` and
+  `staff`**, three flat fields on `exchangeCode()` and `getUser()` (and on the
+  `/session` bridge read).
+
+  The two blocks they replace were mutually exclusive by construction. A
+  Connect platform account belongs to no workspace - Connect enforces it - so
+  a member session always carried `platformAccess: null` and a staff session
+  always carried `applicationRole: { role: null, granted: [] }`. Two shapes
+  for one question meant every integration wrote the same null-check twice,
+  and the block that did not apply still had to be built and sent.
+
+  ```ts
+  // Before
+  const { applicationRole, platformAccess } = await connect.identity.getUser(t);
+  if (platformAccess) {
+    if (!platformAccess.roles.includes("platform_admin")) return forbidden();
+    return renderOperatorConsole();
+  }
+  if (!applicationRole.granted.includes("invoice:write")) return forbidden();
+
+  // After
+  const { role, permissions, staff } = await connect.identity.getUser(t);
+  if (staff) {
+    if (role !== "platform_admin") return forbidden();
+    return renderOperatorConsole();
+  }
+  if (!permissions.includes("invoice:write")) return forbidden();
+  ```
+
+  Read `staff` first: it decides which vocabulary the other two speak - your
+  own Permission Catalog's ids for a member, Connect's `platform:*` ids for an
+  operator. A staff session reports one `role` rather than a list, and it is
+  the highest-authority role your application accepts; the platform roles nest
+  (`developer` ⊆ `platform_manager` ⊆ `platform_admin`), so nothing is lost,
+  and `permissions` is still the union over every accepted role.
+
+  `ApplicationRole` and `PlatformAccess` are gone as exported types, replaced
+  by `SessionAccess`. `useConnectPlatformAccess()` keeps its shape -
+  `roles` is now a one-element array on a staff session, `[]` otherwise - so
+  `<ConnectPlatformGate accept={[...]}>` is unchanged.
+
+  The signed-out `/session` response carries the same three fields
+  (`role: null, permissions: [], staff: false`) rather than a bare
+  `applicationRole: null`, so a client never tells "signed out" apart from
+  "signed in with no role" by which keys happen to be present.
+
+- **Workspace role ids lost their `org_` prefix** - `org_admin` is `admin`,
+  and the same for `finance`, `manager` and `member`. This is visible to you
+  only through `access.getUserRoles()` and `access.listRoles()`, which report
+  a *member's* resolved role on your application rather than these; if you
+  hardcoded a Connect workspace role id anywhere, it needs updating. Grants
+  stored under the old ids keep resolving.
+
+### Fixed
+
+- **Subscribing no longer lands on a 404.** `buildCheckoutUrl` - and so
+  `<ConnectPlans>`'s subscribe button - built
+  `/applications/{id}/subscribe/{planId}`. The portal route customers can
+  actually open is `/apps/...`; `/applications` is a Console-only prefix. Every
+  first-time subscriber sent from a partner's own pricing page hit a 404. The
+  matching `resolveUrl` on the `subscription_missing` readiness blocker was
+  wrong the same way and is fixed with it.
+
+- **`staff` actually reaches you.** Both `/sso/token` and `/sso/user` resolved
+  the staff block, typed it and documented it, then dropped it while building
+  the JSON response - the handlers are hand-built rather than schema-parsed,
+  so a forgotten field was silent. Staff access has been invisible to every
+  partner since it shipped in 0.11.0. If you turned it on and concluded it did
+  not work, it did not.
+
+- `SDK_VERSION`, sent in the `User-Agent`, said `0.12.0` on a 0.13.0 package.
+
+## 0.13.0
+
+The platform's grievance channel is now something you read rather than
+something you copy.
+
+### Added
+
+- **`connect.platform.getCompanyProfile()`** - the registered entity operating
+  Connect, and the grievance officer s.13 of India's DPDP Act 2023 requires a
+  Data Fiduciary to publish. Backed by the new
+  `GET /api/v1/application/company-profile`, which needs the new
+  **`company:read`** scope on your API key.
+
+  Your application is a Data Processor on that notice, not a second Data
+  Fiduciary, so the channel your privacy page names is this one. The shape it
+  replaces is four lines in an `.env`:
+
+  ```bash
+  # Before - a statutory contact that can go stale without anyone finding out.
+  APP_DATA_FIDUCIARY_NAME="..."
+  APP_GRIEVANCE_OFFICER_EMAIL="..."
+  ```
+
+  An officer resigns, and every application holding a copy is now publishing a
+  redressal channel that reaches nobody. Reading it removes that failure mode
+  outright, which is the entire reason it is an endpoint.
+
+  Every field is resolved server-side against the platform's published
+  defaults, so only `website` and `gstNumber` are nullable - there is nothing
+  here for you to write a fallback for.
+
+- **`useConnectCompanyProfile()`** - the same read through the browser bridge.
+  The one hook here that does not depend on a session, so it resolves for a
+  signed-out visitor too: the moment a grievance channel most needs to be
+  readable is on a public privacy page.
+
+- **`<ConnectGrievanceNotice />`** - the notice, rendered. The wording lives in
+  the SDK rather than being retyped per application, so a user comparing two
+  applications' privacy pages does not find two different accounts of who
+  their Data Fiduciary is.
+
+  ```tsx
+  import { ConnectGrievanceNotice } from "@cosmoops/connect-sdk/client";
+
+  <ConnectGrievanceNotice applicationName="CosmoOps CRM" />
+  ```
+
+  It renders `null` while loading and `null` on failure rather than a skeleton
+  or an error box - a red error in the middle of a legal notice reads as the
+  notice itself being broken. Call the hook directly if you want those states.
+
+### Upgrading
+
+Existing API keys do not carry `company:read`. Tick it on the key's scopes in
+the Console's Integration tab, or re-run the seed script for that application,
+which widens scopes in place.
+
+## 0.12.0
+
+The application shell is one column now. The top bar is gone, the rail holds
+everything it used to, and the rail starts collapsed.
+
+### Changed - breaking
+
+- **Two renames, both with deprecated aliases kept**, so nothing breaks on
+  upgrade:
+
+  | Was | Now | Why |
+  |---|---|---|
+  | `ConnectSideNav` | `ConnectSidebarNav` | The rail is a `ConnectSidebar` now; its parts are named after it |
+  | `ConnectUserMenu` | `ConnectUserButton` | It is a button that opens a modal. "Menu" had people looking for a dropdown that never existed |
+
+  **`AppShell` keeps its name.** It stays the one export in `/client` without
+  the `Connect` prefix, exactly as 0.8.0 decided. A host whose own layout
+  component is also called `AppShell` aliases it on import - `import {
+  AppShell as ConnectAppShell }` - which is the documented answer to that
+  clash and what both reference integrations do.
+
+- **The top bar is removed.** With it go two props:
+
+  - **`title`** - a page's heading belongs to the page. Move it to
+    `ConnectPageShell`, from `@cosmoops/connect-sdk/ui`, which renders it next
+    to that page's own breadcrumbs and actions:
+
+    ```tsx
+    // before                     // after
+    <AppShell title="Billing">    <AppShell>
+      <BillingPage />               <ConnectPageShell title="Billing">…</ConnectPageShell>
+    </AppShell>                   </AppShell>
+    ```
+
+  - **`headerActions`** - there is no header to put them in. A control that
+    belongs to a page goes in that page's `ConnectPageShell`; a control that
+    belongs to the *application* goes in `sidebarFooter`, which now accepts
+    sidebar rows (see `ConnectSidebarRow`).
+
+  Below `md` a slim bar remains, carrying the drawer trigger and the lockup and
+  nothing else. A phone has no rail to hold that trigger.
+
+- **`defaultCollapsed` now defaults to `true`.** The icon rail is the resting
+  state and expanding is the deliberate act - the rail's job is to be *there*,
+  not to be read. A stored preference from the user's last visit still wins.
+  Pass `defaultCollapsed={false}` to keep 0.11's behaviour.
+
+- **`ConnectUserMenu`'s `compact` prop** is superseded by
+  `ConnectUserButton`'s `variant`. The alias maps `compact` to
+  `variant="compact"` and the old default to `variant="inline"`, so existing
+  call sites are unchanged.
+
+- **`ConnectAppsGrid` now renders as a sidebar row by default**
+  (`variant="row"`). Pass `variant="icon"` for the square accent button it used
+  to be.
+
+### Added
+
+- **`secondaryNav`** on `AppShell` - a second `ConnectNav`, pinned to
+  the foot of the rail above the account row. For the routes a product has but
+  does not want competing with its own: settings, help, plans, status. Same
+  shape, same active resolution, same audience filtering, same `gateExempt`
+  handling as `nav`.
+
+- **The workspace switcher moved into the rail's header**, directly under the
+  brand, and is now collapse-aware: a 32px initials tile when the rail is
+  narrow, tile plus name plus chevron when it is open. It still hides itself
+  for an account with one workspace.
+
+- **The account row is the last thing in the rail.** Circular avatar, name over
+  email, opening the same account modal as before. It collapses to the avatar
+  alone, which is still a complete account control.
+
+- **`ConnectProfileModal`** - the account modal with no trigger of its own,
+  controlled by `isOpen`/`onOpenChange`. For an application that wants to keep
+  its own account control and put Connect's modal behind it.
+
+- **The rail's pieces are exported**: `ConnectSidebar`, `ConnectSidebarHeader`,
+  `ConnectSidebarBody`, `ConnectSidebarFooter`, `ConnectSidebarRow`, plus
+  `ConnectShellProvider` / `useConnectShell` / `sidebarRowClass` and the
+  `RAIL_COLLAPSED` / `RAIL_EXPANDED` constants. `AppShell` composes
+  exactly these, so an application whose chrome the prop API cannot express
+  rebuilds the same rail from the same parts rather than forking it.
+
+- **`ConnectLogo` takes `variant`** - `"full"` | `"mark"` | `"wordmark"`.
+  `collapsed` is deprecated in favour of `variant="mark"`.
+
+### Fixed
+
+- **The collapsed Ask AI panel occupied 400px at `lg` and up.** Its shell
+  carried `lg:w-[400px]` and `lg:w-0` at once; Tailwind emits arbitrary values
+  after scale values, so the override never applied and the closed panel sat
+  permanently in the layout, eating that much of the content pane on every page
+  with `askAi` on. Only the `translate-x` hid it below `lg`, which is why it
+  looked right on a phone and wrong on a laptop.
+
+- **Sidebar contrast, in both directions.** Resting nav rows were
+  `--foreground` - 17.6:1 against the rail in light, 15.8:1 in dark - so eight
+  destinations shouted as loudly as body copy and the selected row had to win
+  on background alone. They are `--muted` now (4.8:1 / 6.2:1, past AA), with
+  `--foreground` on hover. The *active* row was `text-accent` on
+  `bg-accent-soft`, which measures **2.8:1 in light and 4.0:1 in dark - both
+  below AA**, on the one row a user most needs to read; it now uses HeroUI's
+  derived `--accent-soft-foreground` (4.8:1 / 5.6:1), so a host that re-themes
+  `--accent` keeps the contrast.
+
+- **The account row and the app launcher looked permanently selected.** Both
+  are HeroUI `<Button variant="tertiary">` because they trigger overlays, and
+  `.button--tertiary` sets a real `--button-bg`. Next to the plain anchors the
+  nav renders, three rows in the rail appeared highlighted at once.
+
+- **The account avatar is a circle.** HeroUI's `.avatar` is `rounded-2xl`/
+  `rounded-3xl` - right for the media component, wrong for a person, and it
+  read as a rendering fault beside circular status dots.
+
+### Motion
+
+The rail animates its **width and nothing else**, via `motion`. Every row is
+laid out so its glyph sits on the same 32px horizontal centre in both states,
+and every label is clipped by the shrinking rail rather than re-measured - so
+collapsing costs no reflow on any row, and no child moves sideways. Section
+headings hold their box and cross-fade a rule in place of their text, so
+nothing jumps vertically either. A tween rather than a spring: an overshooting
+*width* drags every clip edge past its resting place and back, which reads as
+the labels wobbling.
+
+## 0.11.0
+
+### Changed - breaking
+
+- **`ConnectUser.workspaceId`, `workspaceName` and `workspaceType` are now
+  nullable.** They are `null` for exactly one thing: a **Connect platform
+  staff** session, described below. Every member session carries them as
+  before.
+
+  If you never turn staff access on for your application - it is off by
+  default, and only a Connect platform admin can turn it on - this is a type
+  narrow and nothing else. Reading `user.workspaceId` where a `string` is
+  wanted becomes a compile error, and `?? ""` is the wrong fix: decide what
+  your tenanting does with a session that has no tenant before you enable the
+  feature.
+
+  The honest alternative was a synthesized placeholder workspace, which would
+  have kept the types quiet while flowing a fabricated tenant id into the ID
+  token's `org_id` claim and into whatever you key your own rows on. A
+  compile error is cheaper than that.
+
+### Added
+
+- **Connect platform staff sign-in.** Connect's own operators
+  (`platform_admin`, `platform_manager`, `developer`) can now sign into your
+  application, so an operator console can live inside your product and be
+  authenticated by Connect rather than by a second login you maintain.
+
+  These accounts belong to no workspace - Connect enforces that, they cannot
+  own or join one - which is why the session is shaped differently: no
+  `workspaceId`, `subscription: null`, and `applicationRole.granted: []`.
+  Platform authority is deliberately *not* reported through the member-role
+  field. What staff hold is the new block:
+
+  ```ts
+  const { platformAccess } = await client.identity.getUser(sessionToken);
+  if (!platformAccess) return forbidden();
+  if (!platformAccess.roles.includes("platform_admin")) return forbidden();
+  ```
+
+  `roles` is the intersection of what the account holds and what your
+  application accepts - never Connect's full role list for that person.
+
+  Off by default and per-application. Ask a Connect platform admin to enable it
+  on your catalogue entry, naming the roles you accept; until then
+  `platformAccess` is always `null` and nothing below does anything.
+
+- **`platformAccess` on `exchangeCode()` and `getUser()`** - `PlatformAccess |
+  null`. Live on `getUser()`, like `subscription` and `applicationRole`: a
+  platform role revoked, or staff access turned off for your application,
+  comes back `null` there and Connect has already revoked the session.
+
+- **`<ConnectPlatformGate>`** and **`useConnectPlatformAccess()`** in
+  `/client`. The gate renders its children only for a staff session, and takes
+  an optional `roles` allowlist when your console has tiers of its own.
+
+  Like every gate in this package it is a **UX gate, not a security
+  boundary** - and that matters more here than anywhere else, because what
+  sits behind it is usually an operator console. Re-check `platformAccess`
+  server-side on every route it reveals.
+
+- **`ConnectNavItem.audience`** - `"staff"` or `"member"`. `AppShell` filters
+  the rail by it off the live session, so your operator routes appear only for
+  staff and your billing/team/usage routes disappear for them. A parent whose
+  children all disappear is dropped with them. `filterNavForAudience` is
+  exported for a rail you render yourself.
+
+- `ConnectAccessGate` passes a staff session straight through. Every state it
+  reports is a fact about a workspace, and `subscription_missing` would
+  otherwise send an operator to your plan picker to buy a plan for a workspace
+  that does not exist.
+
+### Note
+
+Workspace-scoped bridge routes (`/entitlements`, `/addons`, `/integrations`,
+`/ai/chat`, `/data/*`, `/kv/*`) answer `403 no_workspace` for a staff session.
+There is no tenant to read, and the only other option would be letting the
+request name one - which is precisely what `createConnectHandler` exists to
+prevent. An operator console reads `platformAccess` and talks to your own
+backend for anything tenant-shaped.
+
+## 0.10.0
+
+### Added
+
+- **`@cosmoops/connect-sdk/ui`** - the page-composition layer, and a new entry
+  point. `ConnectPageShell` (with `.Header` and `.Async`), `ConnectPageHeader`,
+  `ConnectSection`, `ConnectEmptyState`, `ConnectSettingRow`,
+  `ConnectStatusChip`.
+
+  The SDK already shipped the *application* chrome - the shell, the launcher,
+  the account menu, the plan grid - and nothing between that and raw HeroUI. So
+  every integration re-derived the same six primitives, and they drifted the
+  same way each time: the page action ending up below the description instead
+  of beside the title, section headings rendered as `h2` so every block became
+  a sibling of its own page, and one empty state doing duty for both "you have
+  none" and "none match this filter". Those are the three bugs these components
+  are shaped to make unrepresentable, not merely to style consistently.
+
+  **A separate entry from `/client`, deliberately.** That module's barrel
+  carries a `"use client"` directive, so re-exporting a presentational `<Card>`
+  wrapper through it would turn every page shell into a client boundary. Nothing
+  in `/ui` has a hook or state, so it renders in a Server Component and stays
+  out of the browser bundle.
+
+  ```tsx
+  import { ConnectPageShell, ConnectSection } from "@cosmoops/connect-sdk/ui";
+  ```
+
+- **`ConnectConfirmDialog`, `ConnectCursorPagination`, `ConnectFilterTabs`** in
+  `@cosmoops/connect-sdk/client` - the interactive counterparts, which hold
+  state and so belong on the browser side. `ConnectCursorPagination` has no page
+  numbers on purpose: a keyset-paginated list cannot know its page count without
+  a second billed index scan over the same filter, for a number nobody acts on.
+
 ## 0.9.0
 
 ### Added