@microsoft/rayfin-guide 1.34.0-alpha.1148 → 1.34.0-beta.0

package/assets/docs/auth/overview.md

@@ -12,7 +12,9 @@ This guide explains how to configure Rayfin authentication in your application.
 - **Token management** - Access tokens never exposed to application code.
 - **Session Management** - Automatic state tracking with localStorage, sessionStorage, or custom storage.
 - **Event System** - React-friendly session change notifications.
-- **Server-side Compatible** - Works in Node.js with custom storage.
+- **Isomorphic** - Works in Node.js, React Native, and Electron without crashing.
+  The constructor auto-detects the runtime and skips browser APIs when `window` is undefined.
+- **Async Storage** - Storage adapters can return promises for async backends (e.g., React Native AsyncStorage).
 
 ## Auth client API surface
 
@@ -23,7 +25,9 @@ The auth client exposes the following methods for sign-up, sign-in, session mana
 | `signUp({ email, password })` | Register a new user. |
 | `signIn({ email, password })` | Authenticate an existing user. |
 | `signOut()` | End the current session. |
-| `getSession()` | Return the current session (opaque; check `isAuthenticated` or `user`). |
+| `getSession()` | Return the current session (async; check `isAuthenticated` or `user`). |
+| `startAutoRefresh()` | Resume automatic token refresh (for React Native / manual control). |
+| `stopAutoRefresh()` | Pause automatic token refresh. |
 | `onSessionChange(callback)` | Subscribe to session state changes; returns an unsubscribe function. |
 
 > **Important**
@@ -114,11 +118,15 @@ That hook keeps React in sync with the Rayfin auth session.
 ```typescript
 import { useState, useEffect } from 'react';
 import { auth } from './lib/rayfin';
+import type { OpaqueSession } from '@microsoft/rayfin-auth';
 
 export function useAuth() {
-  const [session, setSession] = useState(auth.getSession());
+  const [session, setSession] = useState<OpaqueSession | null>(null);
 
-  useEffect(() => auth.onSessionChange(setSession), []);
+  useEffect(() => {
+    setSession(auth.getSession());
+    return auth.onSessionChange(setSession);
+  }, []);
 
   return {
     ...session,

package/assets/docs/data/graphql.md

@@ -34,6 +34,9 @@ Rayfin's fluent client produces DAB-compliant GraphQL and returns typed entities
 The GraphQL fluent client is available as `client.data.<Entity>`.
 Some older examples may show `client.data.gql.<Entity>`.
 
+Required `@text()` fields return an empty string when the stored value is empty.
+Optional `@text({ optional: true })` fields preserve `null` so apps can distinguish an intentionally missing value from empty text.
+
 ### Read multiple records
 
 Here is an example to read records and order by a column.
@@ -259,7 +262,7 @@ const env = loadEnv();
 const client = new RayfinClient<AppSchema>({
   baseUrl: env['VITE_RAYFIN_API_URL'],
   publishableKey: env['VITE_RAYFIN_PUBLISHABLE_KEY'],
-  authStorage: false, // Required — Node.js has no localStorage
+  authStorage: false, // Optional — Node.js has no localStorage but Auth auto-detects
 });
 
 async function seed() {
@@ -295,7 +298,8 @@ Run with `npx tsx scripts/seed.ts`, or add `"seed": "npx tsx scripts/seed.ts"` t
 
 Key rules:
 
-- Set `authStorage: false` — Node.js has no `localStorage` and the client will crash without it.
+- Set `authStorage: false` — disables session persistence in Node.js scripts.
+  This is optional since Auth now auto-detects Node.js and falls back to memory-only storage, but explicit `false` makes intent clear.
 - Read `baseUrl` and `publishableKey` from `.env`, not hardcoded values — the port and key vary per project.
 - Email/password auth works for **local development seeding only**.
   Deployed Fabric apps use Entra SSO exclusively.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-guide",
-  "version": "1.34.0-alpha.1148",
+  "version": "1.34.0-beta.0",
   "description": "Cross-cutting Builder guides for the Rayfin platform — discovered by `@microsoft/rayfin-docs` via the `rayfinDocs` package.json field convention.",
   "type": "module",
   "files": [