@powerhousedao/reactor-browser 6.2.2-dev.12 → 6.2.2-dev.13

package/README.md

@@ -9,6 +9,7 @@ This document contains all documentation comments for the hooks exported from `p
 - [Config: Editor](#config-editor)
 - [Config: Set Config by Object](#config-set-config-by-object)
 - [Config: Use Value by Key](#config-use-value-by-key)
+- [Renown in-page sign-in](#renown-in-page-sign-in)
 - [Document by ID](#document-by-id)
 - [Document Cache](#document-cache)
 - [Document of Type](#document-of-type)
@@ -507,3 +508,180 @@ Strongly typed, inferred from type definition for the key.
 Gets the value of an item in the global document config for a given key.
 
 Strongly typed, inferred from type definition for the key.
+
+---
+
+## Renown in-page sign-in
+
+Let users authenticate with Renown **inside your app** — no redirect to the
+Renown portal — using pluggable wallet adapters (RainbowKit for external
+wallets, Privy for social/email). This is the same integration Connect and the
+`test-fusion` app use. Import from `@powerhousedao/reactor-browser/renown` (or
+the package root).
+
+### Quick start — `RenownProvider`
+
+Mount one provider high in your tree. It initializes the SDK, seeds the first
+render (from a server session cookie for SSR, or `localStorage` for client-only
+apps), mounts the wallet adapters (lazy-loaded on the first login click), keeps a
+server-readable session cookie in sync when running under SSR, and revalidates
+the stored credential against the switchboard.
+
+```tsx
+import { RenownProvider } from "@powerhousedao/reactor-browser/renown";
+
+<RenownProvider
+  appName="my-app"
+  namespace="my-app"
+  switchboardUrl="https://switchboard.example/graphql"
+  adapters={{
+    rainbow: { walletConnectProjectId: "..." },
+    privy: { appId: "...", methods: ["google", "email"] },
+  }}
+  theme="light" // "light" | "dark" | { mode, accentColor?, accentColorForeground? }
+>
+  <App />
+</RenownProvider>;
+```
+
+The provider is **SSR-safe** — it renders on the server without `ssr: false`;
+the wallet libraries only load client-side on the first login click.
+
+Then build the login UI with `useRenownLoginMethods` (derives the button list
+from the config) and `useRenownAuth` (login + user state):
+
+```tsx
+import {
+  useRenownAuth,
+  useRenownLoginMethods,
+} from "@powerhousedao/reactor-browser/renown";
+
+function Login({ adapters }) {
+  const { user, login, pending, error, logout } = useRenownAuth();
+  const methods = useRenownLoginMethods(adapters);
+  if (user) return <button onClick={() => void logout()}>Log out</button>;
+  return (
+    <>
+      {methods.map((m) => (
+        <button key={m.id} disabled={pending} onClick={() => login(undefined, m.id)}>
+          {m.label}
+        </button>
+      ))}
+      {error ? <p>{error.message}</p> : null}
+    </>
+  );
+}
+```
+
+`login(session?, method?)` activates the adapters on click, routes `method` to
+the adapter that supports it, produces a `WalletSession`, and completes the
+Renown credential sign-in via the switchboard — falling back to the redirect
+flow when no switchboard/adapter is available.
+
+### À la carte
+
+`RenownProvider` composes pieces you can also mount yourself — use them directly
+only when you need a custom tree:
+
+- `<Renown appName namespace switchboardUrl revalidate? />` — SDK init (renders
+  `null`; place high in the tree).
+- `RenownWalletProvider` — wallet adapters (below).
+- `RenownInitialUserProvider` — seeds the first render with a `User` (see
+  [Server-side rendering](#server-side-rendering-ssr)).
+
+### Auth state — `useRenownAuth` / `useRenownAuthAsync`
+
+`useRenownAuth()` returns the live auth: `{ user, status, pending, error, login,
+logout, displayName, displayAddress, ... }`. Gate on it with a plain `if` — no
+wrapper component is needed:
+
+```tsx
+function EditButton() {
+  const { user } = useRenownAuth();
+  if (!user) return null;
+  return <button>Edit</button>;
+}
+```
+
+`useRenownAuthAsync()` adds a collapsed `state: "authenticated" | "resolving" |
+"unauthenticated"` (and `isResolving`) so you can show a skeleton during the
+resolving window **without a Suspense boundary** — handy for client-only apps:
+
+```tsx
+function EditButton() {
+  const { state } = useRenownAuthAsync();
+  if (state === "resolving") return <EditSkeleton />;
+  if (state === "unauthenticated") return null;
+  return <button>Edit</button>;
+}
+```
+
+### Server-side rendering (SSR)
+
+The provider tree is SSR-safe, so the logged-out shell renders on the server with
+no `ssr: false`. To render **authenticated** content on the server (no flash),
+give `RenownProvider` a server-resolved `session`:
+
+```tsx
+// app/layout.tsx (server component)
+import { verifySession } from "@/lib/dal";
+
+const session = await verifySession(); // reads + verifies the session cookie
+<RenownProvider appName="my-app" session={session}>
+  {children}
+</RenownProvider>;
+```
+
+Passing `session` also enables the **session-cookie sync**: after each login the
+client mints a bearer token and POSTs it to `sessionEndpoint` (default
+`/api/renown/session`), and clears it on logout. Your app provides the route
+handler that sets an HttpOnly cookie, and a Data Access Layer that verifies it
+with `verifyRenownSession` from `@renown/sdk/node` (see that package's README).
+
+### Client-only apps
+
+Omit `session` and the provider seeds the first render synchronously from
+`localStorage` (`readPersistedUser`), so a returning user renders authenticated
+on the first paint — no server, no flash. The stored credential is revalidated in
+the background (see below); `useRenownAuthAsync` exposes `resolving` for the cold
+start with no stored session.
+
+### Revalidation
+
+On mount the provider revalidates the restored credential against the switchboard
+and logs the user out if it was revoked or expired (`revalidate` prop, default
+`"always"`; set `"never"` to skip). In the browser this runs **non-blocking** in
+the background (fail-open — a transient outage keeps the session); Node scripts
+block on it (see `@renown/sdk`). This does not replace server-side checks: the
+switchboard enforces the credential on every real operation.
+
+### `RenownWalletProvider`
+
+Registers the login activator, lazy-mounts the configured adapters, and merges
+them into one controller for `useRenownAuth`. The wallet Provider tree wraps
+only the adapter bridges (each library's modal portals to `<body>`), never your
+`children`, so activating login never remounts your app. Props: `adapters`
+(config), `theme?`, `children`.
+
+### `useRenownLoginMethods(adapters, labels?)`
+
+Returns `{ id, label }[]` — one per configured login method (wallet + Privy
+methods, deduped) — reading config only (no wallet libraries load). Override
+labels via the second argument. Wire each to `login(undefined, id)`.
+
+### Testing (mock adapter)
+
+For e2e/dev, enable the **mock adapter** (`@renown/sdk/wallet/mock`) via the
+`mock` key. It's a headless signer backed by a viem local account — real EIP-712
+signatures, **no wallet extension or OAuth** — so sign-in runs deterministically
+in CI. **TEST/DEV ONLY; never enable in production** (it signs with a known key).
+
+```tsx
+<RenownWalletProvider adapters={{ mock: { methods: ["wallet", "google", "email"] } }}>
+  <App />
+</RenownWalletProvider>
+```
+
+See `test/test-fusion/e2e` (Playwright + mock adapter) and `test/vetra-e2e`
+(Connect login surface) for runnable examples, and the Powerhouse Academy
+"Renown authentication flow" guide for the full walkthrough.

package/dist/client-DAJGpNZH.d.ts

@@ -0,0 +1,14 @@
+import { T as SdkFunctionWrapper, c as ReactorGraphQLClient } from "./types-CVZRGBXo.js";
+import { GraphQLClient } from "graphql-request";
+
+//#region src/graphql/client.d.ts
+/**
+ * Creates a GraphQL client for the Reactor Subgraph API.
+ * @param urlOrGQLClient The URL of the GraphQL API or a GraphQL client instance.
+ * @param middleware An optional middleware function to wrap the GraphQL client calls.
+ * @returns A GraphQL client for the Reactor Subgraph API.
+ */
+declare function createClient(urlOrGQLClient: string | GraphQLClient, middleware?: SdkFunctionWrapper): ReactorGraphQLClient;
+//#endregion
+export { createClient as t };
+//# sourceMappingURL=client-DAJGpNZH.d.ts.map

package/dist/client-DAJGpNZH.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-DAJGpNZH.d.ts","names":[],"sources":["../src/graphql/client.ts"],"mappings":";;;;AA4BA;;;;;;AAAA,iBAAgB,YAAA,CACd,cAAA,WAAyB,aAAA,EACzB,UAAA,GAAa,kBAAA,GACZ,oBAAA"}

package/dist/index-B3keszpu.d.ts

@@ -0,0 +1,144 @@
+import { n as PGliteInterface, r as Results } from "./pglite-CntadC_p-BgIvrYtV.js";
+
+//#region ../../node_modules/.pnpm/@electric-sql+pglite@0.3.15/node_modules/@electric-sql/pglite/dist/live/index.d.ts
+interface LiveQueryOptions<T = {
+  [key: string]: any;
+}> {
+  query: string;
+  params?: any[] | null;
+  offset?: number;
+  limit?: number;
+  callback?: (results: Results<T>) => void;
+  signal?: AbortSignal;
+}
+interface LiveChangesOptions<T = {
+  [key: string]: any;
+}> {
+  query: string;
+  params?: any[] | null;
+  key: string;
+  callback?: (changes: Array<Change<T>>) => void;
+  signal?: AbortSignal;
+}
+interface LiveIncrementalQueryOptions<T = {
+  [key: string]: any;
+}> {
+  query: string;
+  params?: any[] | null;
+  key: string;
+  callback?: (results: Results<T>) => void;
+  signal?: AbortSignal;
+}
+interface LiveNamespace {
+  /**
+   * Create a live query
+   * @param query - The query to run
+   * @param params - The parameters to pass to the query
+   * @param callback - A callback to run when the query is updated
+   * @returns A promise that resolves to an object with the initial results,
+   * an unsubscribe function, and a refresh function
+   */
+  query<T = {
+    [key: string]: any;
+  }>(query: string, params?: any[] | null, callback?: (results: Results<T>) => void): Promise<LiveQuery<T>>;
+  /**
+   * Create a live query
+   * @param options - The options to pass to the query
+   * @returns A promise that resolves to an object with the initial results,
+   * an unsubscribe function, and a refresh function
+   */
+  query<T = {
+    [key: string]: any;
+  }>(options: LiveQueryOptions<T>): Promise<LiveQuery<T>>;
+  /**
+   * Create a live query that returns the changes to the query results
+   * @param query - The query to run
+   * @param params - The parameters to pass to the query
+   * @param callback - A callback to run when the query is updated
+   * @returns A promise that resolves to an object with the initial changes,
+   * an unsubscribe function, and a refresh function
+   */
+  changes<T = {
+    [key: string]: any;
+  }>(query: string, params: any[] | undefined | null, key: string, callback?: (changes: Array<Change<T>>) => void): Promise<LiveChanges<T>>;
+  /**
+   * Create a live query that returns the changes to the query results
+   * @param options - The options to pass to the query
+   * @returns A promise that resolves to an object with the initial changes,
+   * an unsubscribe function, and a refresh function
+   */
+  changes<T = {
+    [key: string]: any;
+  }>(options: LiveChangesOptions<T>): Promise<LiveChanges<T>>;
+  /**
+   * Create a live query with incremental updates
+   * @param query - The query to run
+   * @param params - The parameters to pass to the query
+   * @param callback - A callback to run when the query is updated
+   * @returns A promise that resolves to an object with the initial results,
+   * an unsubscribe function, and a refresh function
+   */
+  incrementalQuery<T = {
+    [key: string]: any;
+  }>(query: string, params: any[] | undefined | null, key: string, callback?: (results: Results<T>) => void): Promise<LiveQuery<T>>;
+  /**
+   * Create a live query with incremental updates
+   * @param options - The options to pass to the query
+   * @returns A promise that resolves to an object with the initial results,
+   * an unsubscribe function, and a refresh function
+   */
+  incrementalQuery<T = {
+    [key: string]: any;
+  }>(options: LiveIncrementalQueryOptions<T>): Promise<LiveQuery<T>>;
+}
+interface LiveQueryResults<T> extends Results<T> {
+  totalCount?: number;
+  offset?: number;
+  limit?: number;
+}
+interface LiveQuery<T> {
+  initialResults: LiveQueryResults<T>;
+  subscribe: (callback: (results: LiveQueryResults<T>) => void) => void;
+  unsubscribe: (callback?: (results: LiveQueryResults<T>) => void) => Promise<void>;
+  refresh: (options?: {
+    offset?: number;
+    limit?: number;
+  }) => Promise<void>;
+}
+interface LiveChanges<T = {
+  [key: string]: any;
+}> {
+  fields: {
+    name: string;
+    dataTypeID: number;
+  }[];
+  initialChanges: Array<Change<T>>;
+  subscribe: (callback: (changes: Array<Change<T>>) => void) => void;
+  unsubscribe: (callback?: (changes: Array<Change<T>>) => void) => Promise<void>;
+  refresh: () => Promise<void>;
+}
+type ChangeInsert<T> = {
+  __changed_columns__: string[];
+  __op__: 'INSERT';
+  __after__: number;
+} & T;
+type ChangeDelete<T> = {
+  __changed_columns__: string[];
+  __op__: 'DELETE';
+  __after__: undefined;
+} & T;
+type ChangeUpdate<T> = {
+  __changed_columns__: string[];
+  __op__: 'UPDATE';
+  __after__: number;
+} & T;
+type ChangeReset<T> = {
+  __op__: 'RESET';
+} & T;
+type Change<T> = ChangeInsert<T> | ChangeDelete<T> | ChangeUpdate<T> | ChangeReset<T>;
+type PGliteWithLive = PGliteInterface & {
+  live: LiveNamespace;
+};
+//#endregion
+export { LiveQueryResults as n, PGliteWithLive as r, LiveNamespace as t };
+//# sourceMappingURL=index-B3keszpu.d.ts.map

package/dist/index-B3keszpu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-B3keszpu.d.ts","names":["R","Results","d","PGliteInterface","LiveQueryOptions","T","AbortSignal","key","query","params","offset","limit","callback","results","signal","LiveChangesOptions","Change","Array","changes","LiveIncrementalQueryOptions","LiveNamespace","LiveQuery","Promise","LiveChanges","options","incrementalQuery","LiveQueryResults","totalCount","initialResults","subscribe","unsubscribe","refresh","fields","name","dataTypeID","initialChanges","ChangeInsert","__changed_columns__","__op__","__after__","ChangeDelete","ChangeUpdate","ChangeReset","live","setup","pg","_emscriptenOpts","namespaceObj","PGliteWithLive"],"sources":["../../../node_modules/.pnpm/@electric-sql+pglite@0.3.15/node_modules/@electric-sql/pglite/dist/live/index.d.ts"],"x_google_ignoreList":[0],"mappings":"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"}