@soba-so/react 0.0.14 → 0.0.16

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/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: {