@soba-so/react 0.0.13 → 0.0.15

package/README.md

@@ -32,7 +32,7 @@ export async function POST() {
       authorization: `Bearer ${process.env.SOBA_KEY}`,
       "content-type": "application/json",
     },
-    body: JSON.stringify({ user: session.user.id }),
+    body: JSON.stringify({ user: sobaUserId(session.user.username) }),
   })
   return Response.json(await res.json())
 }
@@ -42,6 +42,12 @@ 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.
 
+It also has to outlive your database. `session.user.id` is usually a key minted
+at sign-up, so a reset or a move turns one person into two — holding the machine
+under the old id, on metered compute under the new one. `sobaUserId`, from the
+server-only subpath `@soba-so/sdk/identity`, derives a stable id from something
+that survives: see [Identifying users](https://soba.so/docs/identity).
+
 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
@@ -106,11 +112,12 @@ 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"
+import { sobaUserId } from "@soba-so/sdk/identity"
 
 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()) })
+  const run = await soba.run({ user: sobaUserId(session.user.username), ...(await request.json()) })
   return new Response(toSSE(run), { headers: { "content-type": "text/event-stream" } })
 }
 ```

package/dist/RunError.d.ts

@@ -0,0 +1,66 @@
+/**
+ * THE OTHER HALF OF A RUN THAT DID NOT WORK.
+ *
+ * `<RunLimit>` and `<ConnectNudge>` answer the two failures a person can do
+ * something about — `payment_required` and `no_compute` — both decided BEFORE a
+ * run starts, where "connect something" or "upgrade" is a real button. This
+ * answers everything else: a supplier that refused, a key with no credit left,
+ * a model that is gone, a machine that disconnected mid-answer.
+ *
+ * It exists because that half was shipped as homework. `useRunLimit` returns
+ * null for anything unanswerable, which is correct and is also an instruction
+ * to the app to go and render something itself — so every surface in this repo
+ * wrote its own, four times, each one slightly different, and the one with the
+ * most machinery dropped the message on the floor for a month without anybody
+ * noticing. A `<p className="error">` is not a hard component to write. It is a
+ * very easy one to forget, and forgetting it looks exactly like the product
+ * doing nothing at all.
+ *
+ * THE PAIR IS THE POINT. Drop both in and they never both speak:
+ *
+ *     <RunLimit error={failure} />
+ *     <RunError error={failure} />
+ *
+ * The first draws when the failure is answerable and the second when it is not,
+ * so between them every failed run says something. That is the whole
+ * integration, and neither one needs the app to classify anything.
+ */
+export interface RunErrorProps {
+    /**
+     * Whatever your catch block caught. `null` — the value every app holds before
+     * the first failure — renders nothing, as does any failure `<RunLimit>` is
+     * already answering.
+     *
+     * Required, unlike `RunLimit.error`, and deliberately: there is no state form
+     * of this. A limit can be foreseen from the plan before anybody presses
+     * anything; an error cannot be foreseen at all, and a component that drew one
+     * speculatively would be inventing a failure.
+     */
+    error: unknown;
+    /**
+     * Run it again. Omitted draws no button, which is right for a surface where
+     * retrying is not one press — a chat has its own regenerate and should not
+     * grow a second one.
+     */
+    onRetry?: () => void;
+    /** Dismissing. Without it the message stays until the next run replaces it. */
+    onDismiss?: () => void;
+    /**
+     * The line above the message. The default names no cause, because this
+     * component by definition does not know the cause — the one thing it is sure
+     * of is that the run did not finish.
+     */
+    title?: string;
+    className?: string;
+}
+/**
+ * WHAT TO SAY ABOUT A FAILURE, or null when it is not this component's to say.
+ *
+ * Exported for the same reason `useRunLimit` is: an app whose errors have their
+ * own shape should ask this and draw its own. Null means either nothing failed
+ * or `<RunLimit>` has it, and in both cases the right thing to render is
+ * nothing — so `{runErrorMessage(e) && <MyError …/>}` is a complete integration
+ * without the app ever naming a status code.
+ */
+export declare function runErrorMessage(error: unknown): string | null;
+export declare function RunError({ error, onRetry, onDismiss, title, className }: RunErrorProps): import("react").JSX.Element | null;

package/dist/SobaProvider.d.ts

@@ -15,14 +15,17 @@ export interface SobaProviderProps {
      * const res = await fetch("https://www.soba.so/v1/end_users/session", {
      *   method: "POST",
      *   headers: { authorization: `Bearer ${process.env.SOBA_KEY}` },
-     *   body: JSON.stringify({ user: session.user.id }),
+     *   body: JSON.stringify({ user: sobaUserId(session.user.username) }),
      * })
      * 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. */
+     *  machine this is and the person a run is attributed to the same row — and
+     *  it has to outlive your database, or a reset splits that person in two.
+     *  `sobaUserId` from `@soba-so/sdk/identity` derives one; the reasoning is at
+     *  https://soba.so/docs/identity. */
     user?: string;
     /** Your route that starts a run with `@soba-so/sdk` and forwards the stream. */
     runEndpoint?: string;

package/dist/context.d.ts

@@ -20,9 +20,16 @@ export interface ComputeState {
     error: Error | null;
     refresh(): Promise<void>;
 }
-/** Why the flow was opened, carried into the panel's opening words. A person
- *  whose laptop went to sleep should not be sold the idea from scratch. */
-export type ConnectReason = "payment_required" | "no_compute" | "manual";
+/**
+ * Why the flow was opened, carried into the panel's opening words. A person
+ * whose laptop went to sleep should not be sold the idea from scratch.
+ *
+ * `pair` is the one that is not about words: it says the caller is ALREADY
+ * showing the steady state — the panel under `<ConnectButton />` — so the
+ * sheet must open on the chooser rather than repeating it. The other three
+ * leave where it opens to the panel.
+ */
+export type ConnectReason = "payment_required" | "no_compute" | "manual" | "pair";
 export interface ConnectState {
     /** Your app's name, as the person connecting will see it. */
     app: {

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { ConnectModal, type ConnectModalProps } from "./ConnectModal.js";
 export { ConnectNudge, type ConnectNudgeProps } from "./ConnectNudge.js";
 export { type ComputeState, type ConnectReason, type ConnectState, type PlanState, type RunRequest, type SobaContextValue, useSoba, } from "./context.js";
 export { collectText, parseEvent, readEvents } from "./events.js";
+export { RunError, type RunErrorProps, runErrorMessage } from "./RunError.js";
 export { RunLimit, type RunLimitProps } from "./RunLimit.js";
 export { SobaBilling, type SobaBillingProps } from "./SobaBilling.js";
 export { SobaCheckout, type SobaCheckoutProps } from "./SobaCheckout.js";