@beeuni/sdk 0.1.0 → 0.3.0

package/README.md

@@ -1,12 +1,9 @@
 # @beeuni/sdk
 
-The **single, opinionated data layer** for the Beeuni API. One typed
-client wraps both the **Beeuni REST API** and the **agent runtime** so a
-host app — web, mobile, reference — imports **only `@beeuni/sdk`**. The SDK
-owns its types: the transcript is Beeuni's own format (`beeuni.transcript.v1`),
-and the package depends on no harness SDK. (The no-raw-`backendApi`/`authenticatedFetch` rule
-below is the target state, not yet fully true of apps/web — see Rules of the
-road.)
+Connect your product to Beeuni Computer as an agent backend. One typed client
+manages projects, sessions, tools, files, and live agent responses from web,
+mobile, or server applications. The SDK includes typed transcripts
+(`beeuni.transcript.v1`) and optional React hooks.
 
 > Philosophy: **one Beeuni token, one client, every action a method.** Keys never
 > leave the server; mutations own their side-effects there; the host states intent.
@@ -84,7 +81,7 @@ One connector as a handle: `run` returns the output itself and throws
 `upstreamStatus`, `retryAfterSeconds`) or `ConnectorApprovalPendingError`;
 `paginate` follows a cursor and throws `ConnectorPageLimitError` (with
 `nextArgs`) past `maxPages`; `useConnectorQuery` (`@beeuni/sdk/react`) caches a
-read. Guide: `/docs/sdk/connectors`; runnable: `examples/13-connectors-as-code.ts`.
+read. Guide: [Connectors](https://beeuni.ai/docs/connect/connectors#typed-calls-from-code); runnable: `examples/13-connectors-as-code.ts`.
 
 ```ts
 const linear = beeuni.project(projectId).connector('linear');
@@ -94,8 +91,8 @@ await linear.accounts();
 ```
 
 An action outside the file accepts any object and returns `output: unknown`.
-Managed Composio and Pipedream connectors publish no output schema, so their
-`output` stays `unknown`. `ConnectorArgs<'linear', 'list_issues'>` and
+For connectors without a declared output schema, `output` stays `unknown`.
+`ConnectorArgs<'linear', 'list_issues'>` and
 `ConnectorResult<'linear', 'list_issues'>` name the same types.
 
 #### Choose which account a call runs as
@@ -127,10 +124,7 @@ Nothing connected yet? Start a hosted authorization and say who the new account
 belongs to:
 
 ```ts
-await project.connectors.pipedream.connect('gmail', { owner: 'me' });      // my own
-await project.connectors.pipedream.connect('gmail', { owner: 'project' }); // shared
-
-// Or hand a human a link instead of authorizing inline:
+await project.setupLinks.requestConnector({ slug: 'gmail', owner: 'me' }); // my own
 await project.setupLinks.requestConnector({ slug: 'gmail', owner: 'project' });
 ```
 
@@ -154,7 +148,7 @@ The browser path needs the App's viewer scope set to `api`
 `403 insufficient_scope`. A service account answers `403` until a person
 grants it a project role (`beeuni access grant --service-account <id> --role
 member --project <id>`). Never put a provider API key in an App or a Convex
-deployment when a connector exists. Guide: `/docs/sdk/connectors`.
+deployment when a connector exists. Guide: [Connectors](https://beeuni.ai/docs/connect/connectors).
 
 ### Upload prompt attachments before Send
 
@@ -216,12 +210,19 @@ cannot retry: `retry` throws, and the item error carries code
 resolves at once. It deletes unbound storage best-effort and never rejects; a
 failed or refused DELETE leaves the object to the 24-hour expiry.
 `abort(localId)` cancels unfinished work. `dispose()` aborts listed work and
-deletes its uploads best-effort: no send holds them, and drafts keep no handle.
-Call it on non-React cleanup; the hook handles unmount and project changes.
-Unused uploads expire after 24 hours.
-
-Selections live in memory only. Never persist a File, blob URL, signed URL, or
-upload handle in a draft.
+deletes its uploads best-effort: no send holds them. Call it on non-React
+cleanup; the hook handles unmount and project changes. Unused uploads expire
+after 24 hours.
+
+A draft may keep a finished upload, so a reload or another composer brings the
+file back. Store its metadata (`item.attachment`: `attachment_id`, `filename`,
+`mime`, `size`, `expires_at`) and call `forget(ids)` before `dispose()`, so the
+upload is not deleted. Later, `restore([{ attachment, file? }])` lists it again
+as `ready` with no request, and returns its new id (`undefined` for an expired or
+invalid one). Send uses it like any ready upload. The server binds an attachment
+only for its own account, project and person, so the id grants nothing to
+anyone else. Never persist a File, a blob URL, or a signed URL: an unfinished
+upload cannot be kept.
 
 For non-composer uploads, call `beeuni.project(projectId).attachments.upload(file,
 { signal, onProgress, onUpload, resume })`. The server selects the transport in the
@@ -312,10 +313,7 @@ import { createBeeuni } from "@beeuni/sdk";
 
 const beeuni = createBeeuni({
   backendUrl: "https://api.beeuni.ai/v1",
-  getToken: () =>
-    supabase.auth
-      .getSession()
-      .then((s) => s.data.session?.access_token ?? null),
+  getToken: async () => beeuniToken,
 });
 
 // Projects
@@ -373,7 +371,7 @@ const warm = await beeuni.project(pid).sessions.ensureWarm(); // ordinary sessio
 
 // Sessions (id-bound handle)
 const s = beeuni.session(pid, sid);
-const cost = await s.cost(); // reads finalized LLM + compute cost; no runtime start
+const cost = await s.cost(); // reads finalized charges without starting the session
 await s.send("Build me a widget"); // provisions/resumes if needed, then prompts
 await s.rewind(userMessageId); // stages a reversible rollback on this session
 await s.restoreRewind(); // restores the removed path before the next prompt
@@ -480,7 +478,7 @@ In React, `useSessionMessageAuthors(projectId, sessionId, messageCount)` reads t
 ### Which model answered a turn
 
 `beeuni.session(projectId, sessionId).modelUsage()` (or `getSessionModelUsage`) returns
-`{ latest, billed_cost, turns }` from the gateway's request record. `latest` is
+`{ latest, billed_cost, turns }` for the session. `latest` is
 `{ served_model, fallback_from, at }` for the newest answered request: `served_model` is the model
 that answered, and `fallback_from` is the routed model when a fallback model answered in its place.
 `turns` maps the runtime message id of each prompt to `{ served_models, fallback_from, billed_cost }`.
@@ -494,9 +492,7 @@ A transcript message carries only the model its turn asked for. In React,
 transcript and events from both. The hook owns messages, rewind and restore,
 cancellation, commands, permissions, and questions. Hosts do not construct
 runtime routes. A feature one harness lacks is a capability: gate its control
-with `runtimeSupports(health?.capabilities, 'session.rewind')`. pi lists
-`session.subagents` only, so rewind, compaction, slash commands, the todo list
-and the runtime config document stay hidden or empty on a pi session.
+with `runtimeSupports(health?.capabilities, 'session.rewind')`.
 
 Every session saves its transcript at the end of each turn. `useSession` reads saved
 messages from the platform database while `/start` continues. It uses the
@@ -567,19 +563,18 @@ exhaustive — see `API-MAP.md` for the full per-domain surface:
 | `beeuni.accounts` | list · get · create · members · invites · `secretResources.{list,create,rotate,delete,grant,revoke,setAccess}` · `tokens.{list,create,revoke}` (account-scoped CLI PATs, `beeuni_pat_…`) · `audit.{log,export,webhooks.*}` (filterable project/session reconstruction log) · `branding.{get,update,uploadAsset,removeAsset,reset}` (Enterprise organization branding: logo / icon / favicon, light + dark, product name) (+ more: `updateName`, `leave`, `invite`, `removeMember`, `updateMemberRole`) |
 | `beeuni.billing` | entitlement/usage reads: `accountState` · `accountStateMinimal` · `transactions` · `transactionsSummary` · `creditBreakdown` · `usageHistory` · `usageRollup` · `sessionCosts.{list,get}` · `tierConfigurations` — plus a curated mutation surface: `subscription.{createPortalSession,cancel,reactivate,cancelScheduledChange,prorationPreview}` · `credits.{purchase,autoTopupSettings,configureAutoTopup}`. `checkout.{createSession,confirmSession}` and `subscription.scheduleDowngrade` are deprecated: they reject with `ENDPOINT_RETIRED` |
 | `beeuni.marketplace` | public marketplace catalog browse + sources (not project-scoped): `items` · `item` · `itemFile` · `marketplaces` · `featured` · `sources.{list,add,remove}` — distinct from the install-scoped `project(id).marketplace` |
-| `beeuni.github` | account-scoped GitHub App installs and repo linking: `getInstallation` · `listInstallations` · `listLinkableInstallations` (each entry carries `linked_to_other_accounts`, a count and never a tenant name) · `listRepositories` · `listRepositoryBranches` · `linkInstallation` · `saveInstallation` · `deleteInstallation` · `linkRepository` (`source: 'managed'` imports a repository the instance backend holds — instance operator only, and mutually exclusive with `installation_id`) · `replaceProjectRepository` (changes an existing project's repository with an expected old URL; accepts a repository-scoped PAT or a temporary GitHub user proof for a repository-scoped App grant; can atomically copy selected shared runtime secrets from another project in the same account) |
-| `beeuni.gitBackend` | the instance git backend ("Beeuni managed", one per deployment, never an account connection): `get()` → `{configured, kind: 'app'|'pat'|null, owner}` (any authenticated user) · `repositories({search?, limit?})` (instance operator only; 403 otherwise) |
+| `beeuni.github` | account-scoped GitHub App installs and repository linking: `getInstallation` · `listInstallations` · `listLinkableInstallations` · `listRepositories` · `listRepositoryBranches` · `linkInstallation` · `saveInstallation` · `deleteInstallation` · `linkRepository` · `replaceProjectRepository` (changes an existing project's repository with an expected old URL and repository-scoped authorization) |
 | `beeuni.notifications` | the caller's notifications, across accounts: `list({ limit?, before? })` (inbox page + `unread_count`) · `markRead({ ids } \| { all: true } \| { sessionId })` · `preferences` · `updatePreferences({ kinds })` (push and email per kind) · `webPushPublicKey` · `registerWebPushSubscription` · `unregisterWebPushSubscription` · `registerDeviceToken` · `unregisterDeviceToken` (native Expo push). Muting one session is `session(pid, sid).setWatch(false)`. Hooks: `useNotificationInbox`, `useNotificationPreferences`, `useSessionWatch`. Inbox rows, Web Push, email, and session watch are served only for projects with the `notification_center` flag on, off by default; with it off, the session creator's phone still gets the push |
 | `beeuni.validateToken()` | pasted-API-key validation helper — `GET /accounts/me`, never throws, resolves `{valid, identity?, error?}` |
 | `beeuni.connectors` | Connector data plane for an agent-minted session token: `catalog` · `tools` · `search` · `describe` · `call` (`{ account }`) · `accounts` · `uploadAttachment` |
 | `beeuni.project(id)` | id-bound handle: `.apps` (stable App URLs, access, artifacts, deployments, logs, rollback, start/stop, machines (`machines.list/start/stop/restart/destroy`, `scale`, `exec`), volumes (`volumes.list/create/update/destroy/snapshots/snapshot/restore/fork`), and `token`) · `.secrets` · `.access` · `.connectors` (data plane + configuration + Connections) · `.policies` · `.triggers` (cron / webhook / monitor / event; `.eventTypes({ connector })` lists a connector's app events) · `.files` · `.git` · `.changeRequests` (incl. `requestChanges`) · `.sessions` · `.tokens` (project-scoped CLI PATs — the `BEEUNI_TOKEN` shape) · `.marketplace` / `.registry` (install/update/remove catalog items) · `.setupLinks.{requestSecret,requestConnector}` (agent-minted secret-entry / connector links) · `.validateManifest` · `.gitToken` · `.setDefaultAgent(name)` · `.session(sid)` (+ more namespaces: `.review`, `.approvals`, `.gateway` (incl. `.routing` and `.playground`), `.channels`, `.modelDefaults`, `.sandbox`) |
 | `beeuni.session(pid, sid)` | id-bound handle: lifecycle (`get`/`update`/`delete`/`start`/`restart`/`stop`/`reloadConfig`/`reloadConfigStream`/`setSharing`/`participants`/`watch`/`setWatch`/`presence`/`previews`/`commit`/`publicShares`/`ensureReady`) · `providerSecretPool.{list,get,set}` · finalized `cost()` · `send`/`abort`/`rewind`/`restoreRewind`/`setModel`/`setAgent` · `transcript()` · `.files` · runtime URL helpers (`health`/`previewUrl`/`proxyUrl`) · runtime REST escape hatches: `stream()` and the deprecated `.runtime` |
-| `beeuni.runtime()` | the runtime REST client for the active sandbox (the SDK's own `RuntimeClient`, frozen at the `@opencode-ai/sdk` 1.18.23 route shapes); use a session-scoped handle in multi-tenant code |
+| `beeuni.runtime()` | the runtime REST client for the active computer; use a session-scoped handle in multi-tenant code |
 
 Runnable, self-contained scripts for the highest-value flows live in
 [`examples/`](./examples): list projects with a PAT, send + stream, the
-multi-tenant server-wrapper pattern, headless transcript rendering, cost
-pass-through / re-billing, and session files + project secrets. Each file's
+multi-tenant server-wrapper pattern, headless transcript rendering, finalized
+session usage, and session files + project secrets. Each file's
 header comment states the env vars and the exact `bun run examples/….ts`
 invocation.
 
@@ -594,7 +589,7 @@ await beeuni.project(projectId).sessions.create({
 ```
 
 Do not put credentials in this map. For a white-label/backend wrapper, create an
-operator-managed connection, store its credential through the dedicated
+connection managed by your application, store its credential through the dedicated
 credential endpoint, and pass only the non-secret connection id at session create:
 
 ```ts
@@ -625,27 +620,17 @@ await project.sessions.create({
 });
 ```
 
-For bring-your-own authorization, each logged-in member creates their own
-connection without supplying an owner id; Beeuni derives ownership from the bearer
-token:
+Each logged-in member can request authorization for their own account.
+Beeuni derives ownership from the bearer token:
 
 ```ts
-const connection = await project.connectors.connections.reconcileMember({
-  connector_alias: "gmail",
-  label: "My Gmail",
-});
-await project.connectors.connections.pipedreamConnect(connection.connection_id);
-// Complete OAuth, then:
-await project.connectors.connections.pipedreamFinalize(connection.connection_id);
-await project.sessions.create({
-  connector_bindings: { gmail: { connection_id: connection.connection_id } },
-});
+await project.setupLinks.requestConnector({ slug: 'gmail', owner: 'me' });
 ```
 
 Member connections are owner-only even for project managers, and sessions using
 one must remain private. A service account — an agent or a trigger — never
 reaches a member connection, only the shared project one. Project defaults
-remain shared; external/agent/subject connections remain operator-managed. Every connection is project/connector scoped
+remain shared; your application manages external/agent/subject connections. Every connection is project/connector scoped
 and resolved on every Connector request, so revocation takes effect without a
 restart. Credentials are encrypted server-side and are never returned, placed
 in `BEEUNI_SESSION_CONTEXT`, or injected into the sandbox environment. Raw env
@@ -670,7 +655,7 @@ handle.close();
 
 `session.stream()` emits the runtime's events (`message.updated`,
 `message.part.updated`, `session.status`, `permission.*`, `question.*`, …),
-the same from OpenCode and pi. Use `useSession()` in React.
+Use `useSession()` in React.
 
 Events arrive in batches, 16 ms apart. Consecutive `message.part.delta` events
 for one part field in a batch arrive as one event: `properties.delta` is their
@@ -727,17 +712,14 @@ app.use(async (req, res, next) => {
 });
 ```
 
-A runnable version of the pattern is `examples/03-server-wrapper.ts`, and the
-full production-shaped reference (per-user project isolation, route policy,
-rate limiting, cost markup for re-billing) is `apps/whitelabel-demo` in wrapper
-mode — see its README.
+A runnable version of the pattern is `examples/03-server-wrapper.ts`.
 
 ## Rendering chat (the headless chat kit)
 
 Everything needed to render an agent transcript without adopting any Beeuni
 UI: `classifyPart`/`classifyTurn` (framework-free, from the root entry)
 normalize all twelve part types of the Beeuni transcript format
-(`beeuni.transcript.v1`; both harnesses emit it) (text, reasoning, tool, file,
+(`beeuni.transcript.v1`) (text, reasoning, tool, file,
 subtask, patch, snapshot, agent, retry, compaction, step, + a forward-compat
 `unknown`) into a typed `ClassifiedPart`, and normalize a failed assistant
 turn's `info.error` into a `{ name, message }` `TurnError` — so "assistant
@@ -807,6 +789,8 @@ the root import — offers the same agents and models and sends the same pick.
 | `modelInDefaultView(model, { search, isStoreVisible, selected })` | → whether the empty-search picker shows the model |
 | `resolveModelDefault(modelDefaults, agentName)` | `/model-defaults` → agent → project → account → platform default |
 | `resolveComposerModel({ models, picks, serverDefault, globalDefault, agentModel, configModel, recent, providers })` | → `{ model, explicit, fallback }` |
+| `sessionModelCandidates({ session, lastPromptModel, gatewayEnabled })` | session row + last prompt's model → the models the session already runs, most trusted first: a chosen pin (`explicit`, `repointed`), the last prompt's model, a default pin. Put them in `picks` after this composer's own pick for the session |
+| `latestPromptModel(messages)` | transcript → the model of the newest user message that records one |
 
 The root barrel reads catalog helpers from `@beeuni/llm-catalog/lite`, which
 never includes the ~7.6 MB models.dev snapshot, so a bundler that does not
@@ -833,8 +817,7 @@ the root barrel; `@beeuni/sdk/react` re-exports them too). They're real classes:
   member (`.runtime`, `.previewUrl()`, `.proxyUrl()`) was touched before
   `ensureReady()` resolved this session's own sandbox.
 
-The canonical server-side wrapper shape — catch a 402 and pass the payload
-through to your own client for re-billing, instead of leaking a Beeuni error:
+Catch a 402 and pass the usage payload to your own client:
 
 ```ts
 import { ApiError, HeadlessAuthError, BillingError } from "@beeuni/sdk";
@@ -875,25 +858,15 @@ provider, resolved model, HTTP status, code, and bounded message.
 
 ## Entry points
 
-**There are four, plus one internal.** Everything framework-free lives at the
-root. `react` and `server` exist because each carries a dependency the root
-cannot; `wire-message-id` exists so a server can load one module, not the barrel.
-That is the whole map — learn it once.
+Use the root entry point for the framework-free client. Choose the React
+or server entry point when your integration needs those adapters.
 
 | import | when you use it | why it is separate |
 | --- | --- | --- |
 | `@beeuni/sdk` | **almost always.** `createBeeuni`, `configureBeeuni`, the REST surface, `files`, session URLs + health (`runtimeSupports` reads a runtime's `capabilities`), `classifyPart`/`classifyTurn`/`toolViewModel`/`toToolView`/`toolKind`, `openEventStream`, `narrowChatEvent`, the message queue, the error classes, and every domain type | — |
 | `@beeuni/sdk/react` | hooks and providers: `useSession`, every `useRuntime*` (each pre-W4 `useOpenCode*` name is a deprecated alias), `useChatTurns`/`renderParts`, the domain hooks | `react` is an **optional peer dependency**. Putting these at the root would force React on a CLI, a worker, or a React Native host |
 | `@beeuni/sdk/server` | `runWithBeeuni`, `createScopedBeeuni`, `getScopedConfig` — per-request config isolation in a Node/Bun backend | imports `node:async_hooks`. Never let it into a browser bundle |
-| `@beeuni/sdk/wire-message-id` | `mintWireMessageId`, `mintWireMessageIdAbove`, `newestWireIdClock`, `wireIdClock`, `wireIdClockDelta`, `maxWireIdClock`, `isWireIdAheadOf` — the OpenCode wire message-id clock | not a dependency split: the root exports the same names. A server that mints ids loads this one import-free module instead of the whole barrel |
-| `@beeuni/sdk/internal/*` | nothing, in host code | apps/web's zustand stores. Browser-only, **outside semver**, and not on the `window.Beeuni` global. Implementation detail that is regrettably visible |
-
-The root really is canonical, and that is a test rather than a promise:
-`src/root-canonical.test.ts` asserts that every name exported by every other
-isomorphic subpath is also exported from `@beeuni/sdk`. The only names it
-permits to be missing are the browser-only stores above — `zustand` is a
-forbidden import in the root's `isomorphic-core` tier, so they cannot live
-there.
+| `@beeuni/sdk/wire-message-id` | `mintWireMessageId`, `mintWireMessageIdAbove`, `newestWireIdClock`, `wireIdClock`, `wireIdClockDelta`, `maxWireIdClock`, `isWireIdAheadOf` — the message-id clock | the root exports the same names. A server that mints ids loads this one import-free module instead of the whole barrel |
 
 ```ts
 import { createBeeuni, classifyTurn, listFiles, openEventStream } from '@beeuni/sdk';
@@ -902,16 +875,8 @@ import { useSession } from '@beeuni/sdk/react';
 
 ### Legacy aliases — do not use in new code
 
-`package.json` still declares about twenty more subpaths: `/turns`, `/files`,
-`/session`, `/session/url`, `/auth`, `/config`, `/api-client`,
-`/projects-client`, `/platform-client`, `/opencode-client`, `/opencode-errors`,
-`/event-stream`, `/feature-flags`, `/fresh-sessions`, `/instance-routes`,
-`/message-queue`, and the un-prefixed store aliases.
-
-Every one of them is a one-line `export *` re-export under `src/deprecated/`,
-kept alive only so an existing `npm install` does not break. **They add nothing
-the root does not already export.** They are removed at the next major; new
-code imports the root.
+Legacy subpath aliases remain available for existing integrations.
+Use the root entry point in new code.
 
 ## Configuration
 
@@ -960,20 +925,16 @@ Its only platform code for the session runtime is the event transport
 
 ## Rules of the road
 
-- **No harness SDK in host code.** Import transcript and runtime types from
+- Import transcript and runtime types from
   `@beeuni/sdk`, and reach the runtime through the session verbs. `session.runtime`
   (the raw REST compatibility client) is deprecated.
-  (Holds today — no host imports `@opencode-ai/sdk`, and neither does the SDK.)
-- **No raw `backendApi` / `authenticatedFetch` in host code.** Use the facade or a
-  subpath module. (Aspirational: apps/web still calls `backendApi` via its
-  `@/lib/api-client` re-export in ~30 files and keeps a parallel
-  `authenticatedFetch` in `apps/web/src/lib/auth-token.ts` — migration pending.)
+- Use the facade or a subpath module for API calls.
 - **React data** comes from `@beeuni/sdk/react` hooks; **imperative actions** from
   the `createBeeuni` facade.
 
 ## Auth
 
-`Authorization: Bearer <token>` — a Supabase JWT (user sessions), a Beeuni PAT
+`Authorization: Bearer <token>` — a user session token, a Beeuni PAT
 (`beeuni_pat_…`) for server-side / automation use, or an OAuth access token
 (`beeuni_oat_…`) minted by "Sign in with Beeuni" — supplied via `getToken`.
 
@@ -1065,7 +1026,7 @@ const asUser = createBeeuni({ backendUrl, getToken: session.getToken });
 
 Also `signUp`, `sendMagicLink` + `verifyOtp`, `signInWithProvider` +
 `exchangeCode` (PKCE), `resetPassword`, `updatePassword`, `user`, `signOut` —
-all `/v1/auth/*`, no Supabase in the client. Guide: `/docs/sdk/auth`.
+all `/v1/auth/*`. Guide: `/docs/sdk/auth`.
 
 ## Tests
 
@@ -1129,9 +1090,9 @@ caller has no personal resource.
 
 ### ChatGPT subscription usage
 
-`getSessionCost` and `getTurnCost` report zero LLM cost for ChatGPT/Codex
-subscription messages. This also corrects historical runtime costs. Token
-counts remain available. Mixed sessions retain paid API costs; OpenAI API
+`session.modelUsage()` reports the LLM credits billed to your Beeuni account.
+Use `getTurnTokens` to read transcript token counts independently of billing.
+Mixed sessions retain paid API costs; OpenAI API
 models remain billable. Subscription coverage does not include sandbox compute.
 
 ### Durable prompt placement