@lunora/react 1.0.0-alpha.9 → 1.0.0-alpha.91

package/LICENSE.md

@@ -103,3 +103,9 @@ 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.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -94,24 +94,31 @@ function MessageList({ room }: { room: string }) {
 
 ## Hooks
 
-| Hook                                                 | Returns                                                         | Notes                                                                          |
-| ---------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| `useQuery(fn, args, options?)`                       | `T \| undefined`                                                | Live query; shares one WS subscription across consumers of the same key.       |
-| `useMutation(fn)`                                    | `{ mutate, pending, data, error, reset, withOptimisticUpdate }` | Per-call `optimistic` / `optimisticUpdate` options pass through to the client. |
-| `useSubscription(fn, args, options?)`                | `{ data, error }`                                               | No initial fetch — only server-pushed values.                                  |
-| `usePaginatedQuery(fn, args, { initialNumItems })`   | `{ results, status, isLoading, loadMore }`                      | Cursor-paginated feed that stays consistent under live edits.                  |
-| `useInfiniteQuery(fn, args, { initialNumItems })`    | `{ pages, status, hasNextPage, fetchNextPage, … }`              | Page-array variant of the same paginator.                                      |
-| `usePreloadedQuery(preloaded)`                       | `T`                                                             | Reads a server `Preloaded` token, then goes live.                              |
-| `usePresence({ heartbeat, listPresent, roomId, … })` | present members                                                 | Drives the `definePresence` heartbeat + list functions.                        |
-| `useFlag(key, default, context?)`                    | flag value (live)                                               | Live OpenFeature flag over the WS; reads `default` until the server answers.   |
-| `useFlags(defaults, context?)`                       | `{ [key]: value }`                                              | Batch variant — one live value per key in the `defaults` map.                  |
-| `useStream(fn, args, options?)`                      | `{ chunks, status, error, cancel }`                             | Consumes a streamed action response chunk by chunk.                            |
-| `useRateLimit(config, options?)`                     | `{ ok, disabled, retryAfter, check, consume, reset }`           | Client-side mirror of a `@lunora/ratelimit` budget for instant UX.             |
-| `useConnectionStatus()`                              | `ConnectionStatus`                                              | `idle` / `connecting` / `connected` / `offline`.                               |
-| `useAuth()`                                          | `{ user, token, setToken }`                                     | Call `setToken(jwt)` after sign-in; RPC then carries the token.                |
-| `useAuthState()`                                     | `{ isAuthenticated, isLoading }`                                | Hydration-safe three-state gate.                                               |
-
-`Authenticated`, `Unauthenticated`, and `AuthLoading` are gate components built on `useAuthState`. `CheckoutButton`, `CustomerPortalButton`, and `useCheckout` wrap `@lunora/payment` flows.
+| Hook                                                                       | Returns                                                                                                                          | Notes                                                                                                                                  |
+| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `useQuery(fn, args, options?)`                                             | `T \| undefined`                                                                                                                 | Live query; shares one WS subscription across consumers of the same key.                                                               |
+| `useMutation(fn)`                                                          | `{ mutate, pending, data, error, reset, withOptimisticUpdate }`                                                                  | Per-call `optimistic` / `optimisticUpdate` options pass through to the client.                                                         |
+| `useSubscription(fn, args, options?)`                                      | `{ data, error }`                                                                                                                | No initial fetch — only server-pushed values.                                                                                          |
+| `usePaginatedQuery(fn, args, { initialNumItems, onError? })`               | `{ results, status, isLoading, loadMore, error }`                                                                                | Cursor-paginated feed that stays consistent under live edits. A failed tail page is dropped so `loadMore` can retry it.                |
+| `useInfiniteQuery(fn, args, { initialNumItems, onError? })`                | `{ pages, status, hasNextPage, fetchNextPage, error, … }`                                                                        | Page-array variant of the same paginator.                                                                                              |
+| `usePreloadedQuery(preloaded, options?)`                                   | `T`                                                                                                                              | Reads a server `Preloaded` token, then goes live. Pass `onError` to see a session expiry instead of rendering the stale SSR snapshot.  |
+| `usePresence(roomId, { heartbeat, listPresent, … })`                       | `{ present, sessionId, setData, error }`                                                                                         | Drives the `definePresence` heartbeat + list functions. `roomId` is a positional first argument, not an option.                        |
+| `useFlag(key, default)`                                                    | flag value (live)                                                                                                                | Live OpenFeature flag over the WS; reads `default` until the server answers. Evaluated under the socket's server-verified identity.    |
+| `useFlags(defaults)`                                                       | `{ [key]: value }`                                                                                                               | Batch variant — one live value per key in the `defaults` map.                                                                          |
+| `useStream(fn, args, options?)`                                            | `{ chunks, status, error, cancel }`                                                                                              | Consumes a streamed action response chunk by chunk.                                                                                    |
+| `useRateLimit(config, options?)`                                           | `{ ok, disabled, retryAfter, check, consume, reset }`                                                                            | Client-side mirror of a `@lunora/ratelimit` budget for instant UX.                                                                     |
+| `useConnectionStatus()`                                                    | `ConnectionStatus`                                                                                                               | `idle` / `connecting` / `connected` / `offline`.                                                                                       |
+| `useAuth()`                                                                | `{ user, token, setToken }`                                                                                                      | Call `setToken(jwt)` after sign-in; RPC then carries the token.                                                                        |
+| `useAuthState()`                                                           | `{ isAuthenticated, isLoading }`                                                                                                 | Hydration-safe three-state gate.                                                                                                       |
+| `useAgentToolEvents({ api, threadKey, … })`                                | `{ events }`                                                                                                                     | One agent thread's tool lifecycle: call / result / awaiting-approval / progress.                                                       |
+| `useVoiceAgent({ voice, threadKey, … })`                                   | `{ status, transcript, startCall, endCall, … }`                                                                                  | Full-duplex voice call: mic capture, playback, live transcripts, barge-in.                                                             |
+| `useAuthUsers` / `useAuthSessions` / `useOrganizations` / `useImpersonate` | `{ data, error, loading, hasMore, total, loadMore, refetch }` (`useImpersonate`: `{ data, error, pending, impersonate, reset }`) | Admin-plane auth reads for a console UI; each needs an admin-capable token. HTTP-only, so `refetch()` rather than a live subscription. |
+
+`Authenticated`, `Unauthenticated`, and `AuthLoading` are gate components built on `useAuthState`.
+
+The payment kit — `CheckoutButton`, `CustomerPortalButton`, and `useCheckout`, which wrap `@lunora/payment` flows — ships from the `@lunora/react/payment` subpath, not the package root: it renders a DOM `<button>` and navigates via `globalThis.location`, so it is the one part of this package that is browser-only (the root barrel stays renderer-agnostic, which is what lets `@lunora/react-native` re-export it wholesale).
+
+`useVoiceAgent` opens nothing until you call `startCall()` — that is what requests the microphone, so it has to run from a user gesture; `endCall()` releases the socket, the mic tracks and the Web Audio graph, and also runs on unmount. See the [voice-agent docs](https://lunora.sh/docs/packages/react#voice-agents--usevoiceagentoptions) for the silence/barge-in thresholds.
 
 ## Server Components