@soba-so/react 0.0.1

package/LICENSE

@@ -0,0 +1,191 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work and such
+Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable (except as stated in this section) patent license to make, have
+made, use, offer to sell, sell, import, and otherwise transfer the Work, where
+such license applies only to those patent claims licensable by such Contributor
+that are necessarily infringed by their Contribution(s) alone or by combination
+of their Contribution(s) with the Work to which such Contribution(s) was
+submitted. If You institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work or a
+Contribution incorporated within the Work constitutes direct or contributory
+patent infringement, then any patent licenses granted to You under this License
+for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof
+in any medium, with or without modifications, and in Source or Object form,
+provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+You must cause any modified files to carry prominent notices stating that You
+changed the files; and
+You must retain, in the Source form of any Derivative Works that You distribute,
+all copyright, patent, trademark, and attribution notices from the Source form
+of the Work, excluding those notices that do not pertain to any part of the
+Derivative Works; and
+If the Work includes a "NOTICE" text file as part of its distribution, then any
+Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted
+for inclusion in the Work by You to the Licensor shall be under the terms and
+conditions of this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify the terms of
+any separate license agreement you may have executed with Licensor regarding
+such Contributions.
+
+6. Trademarks.
+
+This License does not grant permission to use the trade names, trademarks,
+service marks, or product names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor provides the
+Work (and each Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
+including, without limitation, any warranties or conditions of TITLE,
+NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
+solely responsible for determining the appropriateness of using or
+redistributing the Work and assume any risks associated with Your exercise of
+permissions under this License.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including negligence),
+contract, or otherwise, unless required by applicable law (such as deliberate
+and grossly negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special, incidental,
+or consequential damages of any character arising as a result of this License or
+out of the use or inability to use the Work (including but not limited to
+damages for loss of goodwill, work stoppage, computer failure or malfunction, or
+any and all other commercial damages or losses), even if such Contributor has
+been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may choose to
+offer, and charge a fee for, acceptance of support, warranty, indemnity, or
+other liability obligations and/or rights consistent with this License. However,
+in accepting such obligations, You may act only on Your own behalf and on Your
+sole responsibility, not on behalf of any other Contributor, and only if You
+agree to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification within
+third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,151 @@
+# @soba-so/react
+
+**Let your users bring the AI they already pay for, from your own React app.**
+
+```jsx
+import { SobaProvider, ConnectCompute, ComputeStatus } from "@soba-so/react"
+
+<SobaProvider sessionEndpoint="/api/soba/session" user={session.user.id}>
+  <ConnectCompute />
+  <ComputeStatus />
+</SobaProvider>
+```
+
+Drop that in your settings page. A person pairs their machine once, and their
+Claude Code, Codex or local model starts serving your runs, **with no change at
+your call site**.
+
+## The one thing your server has to do
+
+A browser cannot mint a Soba session: that takes your `sk_soba_` secret key, and
+that key can start runs and read every user's usage. So the provider asks a route
+of **yours** for a short-lived, single-user credential, the way Stripe's
+ephemeral keys work.
+
+```ts
+// app/api/soba/session/route.ts
+export async function POST() {
+  const session = await auth()                      // your auth, your rules
+  const res = await fetch("https://soba.so/v1/end_users/session", {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${process.env.SOBA_KEY}`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({ user: session.user.id }),
+  })
+  return Response.json(await res.json())
+}
+```
+
+That is the whole integration. `user` is the same id you pass on a run, which is
+what makes the person whose machine this is and the person a run is attributed to
+the same row.
+
+The session lives ten minutes. A settings page left open for an hour is the
+ordinary case, so the provider refreshes it before it expires **and** heals a
+request that meets a dead one: a 401 mints a new session and retries once, for
+every component in the tree.
+
+If you would rather mint it yourself, pass `session` instead. It cannot be
+refreshed, and the provider says so rather than failing quietly at minute eleven.
+
+## The components
+
+### `<ConnectCompute />`
+
+The connect step, and the component that carries the real friction. It asks which
+compute they have, shows the one command to run on the machine they want to use,
+takes the short code that command prints, and then **waits for the machine to
+actually appear**.
+
+That last part is the whole design. A pairing that never dials the gateway looks
+exactly like a successful one right up until the first run fails, so the panel
+does not stop at "approved". Detected, not asserted.
+
+Nothing is ever pasted back. The credential is written straight to that machine,
+at `~/.soba/worker.json`, and neither this component nor your app ever sees it.
+
+### `<ComputeStatus />`
+
+The component with no equivalent in an auth product. When the compute is
+someone's own laptop, the state of that laptop is user-facing: asleep, offline,
+signed out of its CLI, or serving a run right now are all things only the person
+in front of it can fix, so all of them are shown.
+
+`authenticated` stays **tri-state** all the way to the screen. `true` is signed
+in, `false` is a positive finding that it is signed out, and `null` means we could
+not tell. Rendering the third as the second tells someone their working setup is
+broken.
+
+Several of these on one page is still one request: they read the provider's
+polling rather than starting their own, and a hidden tab does not poll at all.
+
+## The hook
+
+```js
+const { compute, connect, run, client, session } = useSoba()
+```
+
+| | |
+|---|---|
+| `compute` | `machines`, `connected`, `online`, `loading`, `error`, `refresh()` |
+| `connect` | `app`, `command`, `publishableKey` |
+| `run` | Start a run through your own endpoint and read its events |
+| `client` | The framework-free API underneath, for anything the hook does not cover |
+
+`connected` means they have paired something. `online` means something of theirs
+could serve a run right now. They are different questions and a UI usually needs
+both.
+
+## Runs from the browser
+
+A run is started by **your** server, because starting one takes your secret key.
+Point the provider at a route that does it, and the hook will read the stream:
+
+```ts
+// app/api/soba/run/route.ts
+import { Soba } from "@soba-so/sdk"
+
+export async function POST(request: Request) {
+  const session = await auth()
+  const soba = new Soba({ apiKey: process.env.SOBA_KEY })
+  const run = await soba.run({ user: session.user.id, ...(await request.json()) })
+  return new Response(toSSE(run), { headers: { "content-type": "text/event-stream" } })
+}
+```
+
+```jsx
+const { run } = useSoba()
+const events = await run({ prompt: "Summarise everything I saved this week" })
+for await (const event of events) {
+  if (event.type === "delta") append(event.text)
+}
+```
+
+Only the five frozen event types reach the browser. A tool call never does: your
+server already executed it, against the data it already touches.
+
+## Styling
+
+The stylesheet injects itself once, so there is no import to get wrong in an RSC
+tree. Everything is scoped under `.soba-connect` with no element selectors and no
+assumed reset, and every colour is a custom property you can redefine:
+
+```css
+.soba-connect {
+  --sc-accent: #1a1a1c;
+  --sc-r: 6px;
+}
+```
+
+Pass `injectStyles={false}` to the provider and import `@soba-so/react/styles.css`
+yourself if you would rather own it.
+
+## Requirements
+
+React 18 or newer, as a peer dependency. No other runtime dependencies. The
+package is a client component: it carries its own `"use client"`, so it works in
+a Next app router tree without a wrapper.
+
+All rights reserved. Not published under an open-source licence.

package/dist/ComputeStatus.d.ts

@@ -0,0 +1,15 @@
+export interface ComputeStatusProps {
+    className?: string;
+}
+/**
+ * What this person has connected, and what it is doing right now.
+ *
+ * The component with no equivalent in an auth product. When the compute is
+ * someone's own laptop, the state of that laptop is user-facing: asleep,
+ * offline, signed out of its CLI or serving a run are all things only the
+ * person in front of it can do anything about, so all of them are shown.
+ *
+ * It reads the provider's polling rather than starting its own, so three of
+ * these on one page is still one request.
+ */
+export declare function ComputeStatus({ className }: ComputeStatusProps): import("react").JSX.Element;

package/dist/ConnectCompute.d.ts

@@ -0,0 +1,21 @@
+import type { Machine } from "./types.js";
+export interface ConnectComputeProps {
+    /** From `?code=` when they arrived from a terminal that already has one. */
+    initialCode?: string;
+    onConnected?: (machines: Machine[]) => void;
+    className?: string;
+    /** False when you place `<ComputeStatus />` yourself, so the machines are not
+     *  told twice. Left true the panel opens on what this person already has. */
+    showStatus?: boolean;
+}
+/**
+ * The connect step, and the component that carries the real friction.
+ *
+ * It does not stop at "approved": a pairing that never dials the gateway looks
+ * exactly like a successful one right up until the first run fails, so it waits
+ * for the machine to actually appear. Detected, not asserted.
+ *
+ * This is the same panel the hosted page uses. The only difference is where the
+ * session comes from, which is what <SobaProvider> is for.
+ */
+export declare function ConnectCompute({ initialCode, onConnected, className, showStatus, }: ConnectComputeProps): import("react").JSX.Element;

package/dist/SobaProvider.d.ts

@@ -0,0 +1,39 @@
+import { type ReactNode } from "react";
+export interface SobaProviderProps {
+    children: ReactNode;
+    /**
+     * An `est_` session you minted on your server. Cannot be refreshed, so prefer
+     * `sessionEndpoint` for anything a person leaves open.
+     */
+    session?: string;
+    /**
+     * Your own route. The provider POSTs `{ user }` to it with your cookies, and
+     * expects `{ session, expires_in }` back. Four lines on your server:
+     *
+     * ```ts
+     * const res = await fetch("https://soba.so/v1/end_users/session", {
+     *   method: "POST",
+     *   headers: { authorization: `Bearer ${process.env.SOBA_KEY}` },
+     *   body: JSON.stringify({ user: session.user.id }),
+     * })
+     * return Response.json(await res.json())
+     * ```
+     */
+    sessionEndpoint?: string;
+    /** The same id you pass as `user` on a run. It is what makes the person whose
+     *  machine this is and the person a run is attributed to the same row. */
+    user?: string;
+    /** Your route that starts a run with `@soba-so/sdk` and forwards the stream. */
+    runEndpoint?: string;
+    baseUrl?: string;
+    pollMs?: number;
+    /** The stylesheet injects itself once. Turn it off to ship your own. */
+    injectStyles?: boolean;
+    fetchImpl?: typeof fetch;
+    onError?: (error: Error) => void;
+}
+/**
+ * Holds the one thing everything else needs: a live session for one of your
+ * users. Everything below it, component or hook, reads from here.
+ */
+export declare function SobaProvider(props: SobaProviderProps): import("react").JSX.Element;

package/dist/context.d.ts

@@ -0,0 +1,47 @@
+import type { AgentEvent, ConnectApi, Machine, Message } from "./types.js";
+/** What your endpoint is asked for. Everything but `signal` is forwarded to it
+ *  verbatim, because the run's shape is `soba.run()`'s and yours to widen. */
+export interface RunRequest {
+    prompt?: string;
+    messages?: Message[];
+    model?: string;
+    system?: string;
+    signal?: AbortSignal;
+    [key: string]: unknown;
+}
+export interface ComputeState {
+    /** Every machine this person has paired, in whatever state it is in. */
+    machines: Machine[];
+    /** They have paired something. It may still be asleep. */
+    connected: boolean;
+    /** Something of theirs could serve a run right now. */
+    online: boolean;
+    loading: boolean;
+    error: Error | null;
+    refresh(): Promise<void>;
+}
+export interface ConnectState {
+    /** Your app's name, as the person connecting will see it. */
+    app: {
+        name: string;
+    } | null;
+    /** The exact command to run on the machine being paired. */
+    command: string | null;
+    publishableKey: string | null;
+    loading: boolean;
+    error: Error | null;
+}
+export interface SobaContextValue {
+    /** The `est_` session, once there is one. */
+    session: string | null;
+    /** The framework-free client, for anything the hook does not cover. */
+    client: ConnectApi | null;
+    error: Error | null;
+    compute: ComputeState;
+    connect: ConnectState;
+    /** Start a run through YOUR endpoint and read its events. Throws when the
+     *  provider was given no `runEndpoint`, since a browser cannot start one. */
+    run(request: RunRequest): Promise<AsyncIterable<AgentEvent>>;
+}
+export declare const SobaContext: import("react").Context<SobaContextValue | null>;
+export declare function useSoba(): SobaContextValue;

package/dist/events.d.ts

@@ -0,0 +1,7 @@
+import type { AgentEvent } from "./types.js";
+export declare function parseEvent(raw: string): AgentEvent | null;
+/** Server-sent events off a response body. Also reads newline-delimited JSON,
+ *  since a hand-written proxy route usually forwards lines rather than frames. */
+export declare function readEvents(response: Response): AsyncGenerator<AgentEvent>;
+/** Everything a run said, for a caller that only wants the answer. */
+export declare function collectText(events: AsyncIterable<AgentEvent>): Promise<string>;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { ComputeStatus, type ComputeStatusProps } from "./ComputeStatus.js";
+export { ConnectCompute, type ConnectComputeProps } from "./ConnectCompute.js";
+export { type ComputeState, type ConnectState, type RunRequest, type SobaContextValue, useSoba, } from "./context.js";
+export { collectText, parseEvent, readEvents } from "./events.js";
+export { SobaProvider, type SobaProviderProps } from "./SobaProvider.js";
+export { injectStyles } from "./styles.js";
+export type { AgentEvent, AgentEventType, ConnectApi, ConnectContext, CostClass, Machine, MachineState, Message, PendingCode, Runtime, RunUsage, } from "./types.js";