hci-atrium 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anders Petruschke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+# hci-atrium
+
+The TypeScript client for Atrium. Its flagship module is **"Sign in with
+Atrium"** — OAuth 2.0 Authorization Code + PKCE against your Atrium instance — plus an
+authenticated `fetch` that every future SDK module builds on. React bindings ship in the same
+package under the `hci-atrium/react` subpath.
+
+- **Zero runtime dependencies** (PKCE uses the platform's WebCrypto).
+- **ESM + TypeScript strict.** Plain `tsc` build, no bundler required.
+- **SSR/import-safe** — importing the package on a server never throws; browser APIs are touched
+  only at call time.
+
+## Install
+
+```sh
+pnpm add hci-atrium
+```
+
+Or `npm install hci-atrium`.
+
+## Register an app
+
+An app is registered on an Atrium **project**, next to its API keys (Capabilities → Apps). You
+give it a display name and the redirect URIs it will use (your app's https origins, plus loopback
+for local dev) and get back a public **`client_id`**. There is **no client secret** — these are
+public clients and PKCE is the proof. Only **project members** can sign in, checked live on every
+request, so removing a member ends their app sessions immediately.
+
+## Quickstart (React)
+
+```tsx
+import { Atrium } from "hci-atrium"
+import { AtriumProvider, RequireSignIn, useUser } from "hci-atrium/react"
+
+const atrium = new Atrium({
+  baseUrl: "https://atrium.example.edu",
+  clientId: "your-registered-client-id",
+})
+
+function App() {
+  return (
+    <AtriumProvider atrium={atrium}>
+      <RequireSignIn>
+        <Dashboard />
+      </RequireSignIn>
+    </AtriumProvider>
+  )
+}
+
+function Dashboard() {
+  const user = useUser() // undefined while loading, null when signed out, else the user
+  return <p>Signed in as {user?.email}</p>
+}
+```
+
+`<RequireSignIn>` renders its children once the user is signed in and a minimal "Sign in with
+Atrium" button otherwise (pass `fallback` for your own landing page). The callback that Atrium
+redirects back to is handled automatically — no route or effect to wire up.
+
+## Core API (no framework)
+
+```ts
+const atrium = new Atrium({ baseUrl, clientId })
+```
+
+| Member | Description |
+| --- | --- |
+| `new Atrium({ baseUrl, clientId })` | Args take precedence over the `ATRIUM_BASE_URL` / `ATRIUM_CLIENT_ID` env vars. `baseUrl` is required. |
+| `atrium.auth.signIn(opts?)` | Full-page redirect PKCE sign-in. `opts.redirectUri` overrides the default (current origin + path); `opts.scope` sets the OAuth scope. Called while signed in, it re-authenticates. |
+| `atrium.auth.user` | The signed-in user (`{ id, email, … }`) or `null`. |
+| `atrium.auth.signOut()` | Revokes the refresh token, clears storage, and emits a change. |
+| `atrium.auth.onChange(cb)` | Subscribe to user changes; returns an unsubscribe function. |
+| `atrium.auth.onError(cb)` | Subscribe to auth errors (state mismatch, token exchange, refresh). |
+| `atrium.auth.ready()` | Resolves once initial callback handling / session resume settles. |
+| `atrium.fetch(path, init?)` | `fetch` against the instance with the bearer token attached, silent refresh, and a one-shot 401 retry. Relative paths resolve against `baseUrl`. |
+
+### How it behaves
+
+- **Callback handled automatically.** On construction (browser only) the SDK detects `?code&state`
+  on the current URL, validates `state`, exchanges the code + PKCE verifier at the token endpoint,
+  stores the tokens, strips the params via `history.replaceState`, loads `/v1/users/me`, and emits a
+  change. Failures (state mismatch, exchange error, or `?error=` from a denied sign-in) surface via
+  `onError`, never silently.
+- **Endpoints are discovered** from `{baseUrl}/.well-known/oauth-authorization-server` (RFC 8414),
+  falling back to the conventional `/oauth/*` paths, and cached.
+- **Tokens live in `localStorage`**, namespaced by `baseUrl` + `clientId`, so multiple `Atrium`
+  instances never collide. The PKCE verifier + state live in `sessionStorage` across the redirect.
+- **Refresh is silent and single-flight**: proactive when the access token nears expiry, reactive
+  (retry once) on a 401, and concurrent callers share one refresh. If refresh fails, the SDK drops
+  to a signed-out state and emits a change.
+
+## Phase-1 surface
+
+Beyond auth, the client exposes the library / assets / sources / sessions / rooms namespaces plus
+`chat` and `embed`. Every method takes an **options object** with `filters` kept nested
+(`search("rain", { modality, filters: { … } })`); names are **camelCase**, translated to the wire's
+snake_case in one place (the shaping layer). Authenticate with an OAuth `clientId` **or** an
+`apiKey` — the latter works in the browser too (a one-time console note points at PKCE for hosted
+apps).
+
+| Member | Description |
+| --- | --- |
+| `library.search(query?, opts?)` | Semantic search — text, `like` (an asset/hit/id), `image`/`audio`/`video`, or `vector`. `matchBy` (weighted map), tag facets, and the long tail ride `filters`. |
+| `library.searchByExamples(positives, opts?)` | Mood-board search over a set of example assets (`method` defaults to `"cav"`). Seeds are `Asset` or `by.asset(id)`. |
+| `library.compare(a, b, opts?)` | Similarity of two operands (`Asset` / text / `by.*`), raw + calibrated. `opts.space` forces the embedding space. |
+| `library.enrich(query, opts)` | Pull external candidates into the library; `opts.preview` is a dry-run. Returns the raw payload. |
+| `assets.list(opts?)` / `assets.get(id, opts?)` / `assets.upload(file, opts?)` | Browse, fetch, and upload assets. `file` is a `Blob`/`File` or a URL string. |
+| `sources.list()` / `sources.search(query, opts?)` / `sources.import(opts)` | External-provider gateway — read-only fan-out search, then import a `Candidate`. |
+| `sessions.start(opts?)` / `sessions.resume(id)` / `sessions.event(id, type, opts?)` | Durable, append-only session logs. |
+| `rooms.open(opts?)` / `rooms.get(id)` / `rooms.list()` / `rooms.join(code)` | Live [`Room`](#live-rooms) handles — `open`/`get`/`list` are authenticated, `join(code)` is a loginless participant. |
+| `chat(messages, opts?)` | Chat completion. Pass `responseFormat` a **Zod** schema for validated structured output (Zod is an optional peer dep). |
+| `embed(opts)` | Embed exactly one of `text` / `image` / `audio` / `video` into a vector; `model` is required. |
+| `transcribe(audio, opts?)` | Speech-to-text over a multipart audio upload; `opts.verbose` fills `.language` / `.duration` / `.segments`. |
+| `by.*` | Operand grammar for `searchByExamples` / `compare`: `by.asset` / `by.text` / `by.file` / `by.concept`, and `by.vector([…])` — the only way to pass a raw vector. |
+| `Decider({ margin, dwell })` | N-way hysteresis winner-selection over a live score stream — `update(scores)` returns a new winner only on a real switch. |
+| `close()` / `await using` | Aborts in-flight requests; `AbortSignal` is accepted per call via `opts.signal`. |
+
+### Live rooms
+
+A `Room` is pure live transport over one WebSocket — text signals *and* the ephemeral binary
+audio-analysis stream. `room.on(type, handler)` registers a handler (its return value auto-replies to
+a matching `room.request(...)`); `room.send(type, payload, { to })` fans out; player controls
+(`play` / `configureLayers` / `clearLayer` / `clearAll` / `setLayerEffects` / `queryLayers` /
+`watchLayers` / `playerUrl`) drive the hosted Player; `room.audioSignals(cb)` decodes the
+loudness/spectrum/beat stream. `connect()` opens the socket (every wire method calls it for you);
+`close()` / `await using` / a passed `AbortSignal` tears it down.
+
+Not yet ported (environment- or broker-bound, tracked as parity exceptions): `record(into=session)`
+host bridging, and `audioVectors` / `audioScores` (the embed/chat-broker protocol). Audio-signal
+*consumption* is complete. In Node <22 pass a `WebSocketCtor` (e.g. from `ws`); browsers and Node ≥22
+use the global.
+
+Errors derive from `AtriumError`: HTTP failures are `APIError` (401/403 → `AuthError`, 429/5xx →
+`TransientAuthError`), and caller mistakes (mutually-exclusive inputs, unsupported filters) are
+`InvalidArgumentError`.
+
+## Quickstart (search + play)
+
+```ts
+import { Atrium } from "hci-atrium"
+
+const atrium = new Atrium({ baseUrl: "https://atrium.example.edu", apiKey: "atr_…" })
+const [hit] = await atrium.library.search("distant thunder", { modality: "audio" })
+if (hit) new Audio(hit.asset.contentUrl).play() // public, no-auth, cache-friendly URL
+```
+
+## Quickstart (join a room, react to a signal)
+
+```ts
+import { joinRoom, Decider } from "hci-atrium"
+
+// Loginless: a participant joins by connect code (no account, no client).
+await using room = await joinRoom("ABC12345", { baseUrl: "https://atrium.example.edu" })
+
+// React to what peers broadcast; a returned value auto-replies to a request().
+room.on("scene.change", (e) => console.log("scene →", e.payload.name))
+
+// Consume the live audio-analysis stream and switch mood beds with hysteresis.
+const mood = new Decider({ margin: 0.15, dwell: 2 })
+room.audioSignals((sig) => {
+  if (sig.kind !== "frame") return
+  const winner = mood.update({ calm: 1 - sig.frame.level, intense: sig.frame.level })
+  if (winner) room.send("mood", { winner })
+})
+```
+
+## Honest caveat: the guard is UX, not secrecy
+
+For a static single-page app the client-side guard is **user experience, not a security boundary**
+— the bundle is public and anyone can read it. What's actually protected is **every Atrium call**:
+the token carries the app's project-scoped access, membership is verified live on the server, and no
+app token can reach a project's management surface. Put secrets in an Atrium session or a
+server-side API key, never in the app bundle.
+
+## Development
+
+```sh
+pnpm install
+pnpm build   # tsc → dist/ (.js + .d.ts)
+pnpm test    # vitest (mocked fetch, no live server)
+pnpm lint    # biome check
+```