@basictech/react 0.11.0 → 0.12.0-beta.1

package/README.md

@@ -18,22 +18,24 @@ its package metadata.
 
 ## Install
 
-Install the React SDK and declare the schema package you import directly:
+This README describes the `0.12.0-beta.1` release candidate. After publication, install
+matching versions of the React SDK and the schema package you import directly:
 
 ```bash
-npm install @basictech/react @basictech/schema
+npm install @basictech/react@0.12.0-beta.1 @basictech/schema@0.12.0-beta.1
 ```
 
 React is a peer dependency and must already be installed by your application.
 
 ## Auth update guide
 
-Upgrade the packages you use together from npm's default `latest` channel:
+Upgrade the packages you use together. npm's `latest` channel remains on `0.11.0` and
+does not contain all of the API changes described here:
 
 ```bash
-npm install @basictech/react@latest @basictech/schema@latest
+npm install @basictech/react@0.12.0-beta.1 @basictech/schema@0.12.0-beta.1
 # If you import core directly, update that dependency too:
-npm install @basictech/core@latest
+npm install @basictech/core@0.12.0-beta.1
 ```
 
 Keep the public packages on matching versions. No browser storage reset or persisted-profile
@@ -42,9 +44,8 @@ that an older installed beta contains the update.
 
 ### Update auth checks and editing controls
 
-- Replace `useAuth().status === 'reauth_required'` with `status === 'expired'`.
-  Core client snapshots likewise use `authStatus: 'expired'`; only low-level `AuthSession`
-  retains the legacy compatibility state.
+- Replace `useAuth().status === 'reauth_required'` with `status === 'expired'`. The
+  `reauth_required` state no longer exists anywhere, including low-level `AuthSession`.
 - Use `auth.canWrite` to disable mutation controls and `auth.readOnlyReason` for explanation.
   It is account eligibility, not a guarantee of connectivity or permission to a particular source.
   Catch imperative mutation errors too: auth can expire after the UI renders. Newly attempted
@@ -72,8 +73,10 @@ function AuthNotice() {
 
 ### Render per-account status
 
-`useAccounts().accounts` now returns `BasicAccount[]`, including anonymous and expired accounts.
-Each account adds `auth: { status, reason, checkedAt }` to the existing profile fields:
+`useAccounts().accounts` returns `BasicAccount[]`, including anonymous and expired accounts, and
+`useAccounts().activeAccount` is this tab's selection. The former `profiles`/`users`/`activeUser`
+snapshot aliases and the `active` hook field are gone. Each account adds
+`auth: { status, reason, checkedAt }` to the existing profile fields:
 
 | Account status | Meaning |
 | --- | --- |
@@ -90,6 +93,11 @@ is expired; otherwise an unverified remembered account is checking. The active a
 has `auth.status: 'anon'`, while top-level `useAuth()` reports `status: 'signed_out'` and
 `isAnonymous: true`. REST exposes one remembered account, not a multi-account registry.
 
+`account.auth.reason` is exactly `'AUTH_EXPIRED' | null`. Raw active-account diagnostics such as
+`invalid_grant` remain available as `useAuth().error`. Sign-in prerequisite errors returned by
+server-backed hooks are stable within each hook but intentionally distinct objects from that raw
+diagnostic; an expired hook can report `AUTH_EXPIRED` while the auth diagnostic is `invalid_grant`.
+
 Ordinary network loss is not expiry, and anonymous editing still works. `goOnline()` cannot
 bypass expired read-only enforcement. Reauthorization resumes retained queued work; already
 accepted server requests cannot be undone by client cancellation. REST has no offline cache.
@@ -278,7 +286,7 @@ The package also exports the adapters for explicit composition: `BrowserKeyValue
 `browserStorage`, `BrowserTokenStore`, `PersistenceStore`, `browserUploadTransport`,
 `createBrowserMessageChannel`, `createBrowserAuthChannelFactory`, `browserNavigate`,
 `browserCurrentUrl`, and `browserReplaceUrl`. Most applications only need `createBasic`, which
-installs them.
+installs them. `supportsAccessTokenAdoption` is internal and is not a public React export.
 
 ### Token storage
 
@@ -352,8 +360,8 @@ unknown table names and infer fields in reads, writes, and queries.
 | `isAnonymous` | `boolean` | The active sync profile is anonymous and not signed in |
 | `status` | `'bootstrapping' \| 'signed_out' \| 'authenticated' \| 'recovering' \| 'expired'` | Current public auth lifecycle |
 | `canWrite` | `boolean` | Active-account write eligibility; source permissions still apply |
-| `readOnlyReason` | `string \| null` | For example `AUTH_EXPIRED` when reauthorization is needed |
-| `error` | `BasicError \| null` | Stable auth bootstrap/refresh error code when available |
+| `readOnlyReason` | `ReadOnlyReason \| null` | `'AUTH_EXPIRED' \| 'AUTH_CHECKING' \| 'AUTHORIZATION_REQUIRED' \| 'CLIENT_NOT_STARTED'`; switch exhaustively for banners |
+| `error` | `BasicError \| null` | Raw active auth diagnostic; same object while its code and expired state are unchanged |
 | `user` | `AuthUser \| null` | OIDC user info (`sub`, `pds_url`, and optional `email`, `name`, `picture`, `handle`) |
 | `did` | `string \| null` | Signed-in account DID |
 | `handle` | `string \| null` | Resolved account handle |
@@ -399,10 +407,10 @@ replicas and returns to another local profile or a fresh anonymous one when enab
 
 ### `basic.useAccounts()`
 
-`useAccounts()` returns `{ accounts, active, switchAccount, addAccount, removeAccount }`:
+`useAccounts()` returns `{ accounts, activeAccount, switchAccount, addAccount, removeAccount }`:
 
 - `accounts: BasicAccount[]` lists local profiles with per-account auth summaries.
-- `active: BasicAccount | null` is this tab's selected profile and auth summary.
+- `activeAccount: BasicAccount | null` is this tab's selected profile and auth summary.
 - `switchAccount(id): Promise<void>` changes the active profile in this tab.
 - `addAccount(): Promise<BasicProfile>` creates and activates a new anonymous profile from which to
   start another sign-in.
@@ -418,12 +426,12 @@ replicas and returns to another local profile or a fresh anonymous one when enab
 import { basic } from './basic'
 
 export function AccountSwitcher() {
-  const { accounts, active, switchAccount, addAccount, removeAccount } = basic.useAccounts()
+  const { accounts, activeAccount, switchAccount, addAccount, removeAccount } = basic.useAccounts()
 
   return (
     <section>
       <select
-        value={active?.id ?? ''}
+        value={activeAccount?.id ?? ''}
         onChange={(event) => void switchAccount(event.currentTarget.value)}
       >
         {accounts.map((account) => (
@@ -433,7 +441,7 @@ export function AccountSwitcher() {
         ))}
       </select>
       <button onClick={() => void addAccount()}>Add account</button>
-      {active && <button onClick={() => void removeAccount(active.id)}>Remove local profile</button>}
+      {activeAccount && <button onClick={() => void removeAccount(activeAccount.id)}>Remove local profile</button>}
     </section>
   )
 }
@@ -821,9 +829,8 @@ Shares v2 is capability-gated and requires sign-in. `useOutgoingShares()` return
 ```text
 {
   data: OutgoingShareInfo[]
-  outgoingShares: OutgoingShareInfo[] // alias of data
   isLoading: boolean
-  error: BasicError | null
+  error: BasicError | null // load failure, or AUTHORIZATION_REQUIRED / AUTH_EXPIRED while not signed in
   refresh(): void
   create(input: CreateOutgoingShareInput): Promise<OutgoingShareInfo>
   get(id: string): Promise<OutgoingShareInfo>
@@ -869,7 +876,7 @@ export function OutgoingShares() {
       <button onClick={() => location.assign(shares.manageUrl())}>Manage in Basic ID</button>
       {shares.error && <p>{shares.error.code}</p>}
       <ul>
-        {shares.outgoingShares.map((share) => (
+        {shares.data.map((share) => (
           <li key={share.id}>
             {share.recipientDid}: {share.effectiveState}
             {share.state === 'pending' && (
@@ -907,9 +914,8 @@ management belong there. `client.shares.leave()` is intentionally owner-only and
 ```text
 {
   data: MountInfo[]
-  mounts: MountInfo[] // alias of data
   isLoading: boolean
-  error: BasicError | null
+  error: BasicError | null // load failure, or AUTHORIZATION_REQUIRED / AUTH_EXPIRED while not signed in
   refresh(): void
   open(mountId: string): Promise<MountHandle<S>>
   manageUrl(): string
@@ -955,7 +961,7 @@ export function IncomingMounts() {
     <section>
       <button onClick={() => location.assign(mounts.manageUrl())}>Manage mounts</button>
       <ul>
-        {mounts.mounts.map((mount) => (
+        {mounts.data.map((mount) => (
           <li key={mount.id}>
             {mount.role} from {mount.originOwnerDid}
             <button onClick={() => void open(mount.id)}>Open</button>
@@ -1090,7 +1096,8 @@ The unbound exports mirror the bound hooks:
 | `useMounts()`, `useOutgoingShares()` | Same share results |
 
 Every unbound hook must run below `BasicProvider`; otherwise it throws `Basic hooks must be used
-within a <BasicProvider>`.
+within a <BasicProvider>`. Bound hooks likewise throw outside their own `basic.Provider`, because
+the Provider is what starts and stops the client.
 
 ## Error handling
 

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode, ReactElement } from 'react';
-import { BasicSchema, BasicConfig, BasicClient, BasicAccount, BasicProfile, AuthStatus, BasicError, AuthUser, BasicSyncStatus, BasicRejection, BasicConflict, SourceRef, SchemaStatus, BasicDb, Repo, FileRecord, MountFileInfo, StorageInfo, FileListQuery, MountInfo, MountHandle, OutgoingShareInfo, CreateOutgoingShareInput, MountsQuery, JsonObject, BasicRecord, Query, MountViewerFiles, OwnerFiles, TableNames, Collection, InferValue, KeyValueStorage, TokenStore, AuthMessageChannel, ReplicaStoreFactory, StoragePartition, ReplicaStore, UploadTransportAdapter } from '@basictech/core';
+import { BasicSchema, BasicConfig, BasicClient, BasicAccount, BasicProfile, ReadOnlyReason, AuthStatus, BasicError, AuthUser, BasicSyncStatus, BasicRejection, BasicConflict, SourceRef, SchemaStatus, BasicDb, Repo, FileRecord, MountFileInfo, StorageInfo, FileListQuery, MountInfo, MountHandle, OutgoingShareInfo, CreateOutgoingShareInput, MountsQuery, JsonObject, BasicRecord, Query, MountViewerFiles, OwnerFiles, TableNames, Collection, InferValue, KeyValueStorage, TokenStore, AuthChannelContext, AuthMessageChannel, ReplicaStoreFactory, StoragePartition, ReplicaStore, UploadTransportAdapter } from '@basictech/core';
 
 type BrowserBasicConfig<S extends BasicSchema = BasicSchema> = BasicConfig<S>;
 /** Create a core client with the complete browser adapter set installed. */
@@ -8,7 +8,7 @@ declare function createBasicClient<S extends BasicSchema>(config: BrowserBasicCo
 
 interface UseAccountsResult {
     accounts: BasicAccount[];
-    active: BasicAccount | null;
+    activeAccount: BasicAccount | null;
     switchAccount(id: string): Promise<void>;
     addAccount(): Promise<BasicProfile>;
     removeAccount(id: string): Promise<void>;
@@ -20,8 +20,9 @@ interface UseAuthResult {
     isSignedIn: boolean;
     isAnonymous: boolean;
     canWrite: boolean;
-    readOnlyReason: string | null;
+    readOnlyReason: ReadOnlyReason | null;
     status: AuthStatus;
+    /** Raw auth diagnostic; stable identity while its code and expired state are unchanged. */
     error: BasicError | null;
     user: AuthUser | null;
     did: string | null;
@@ -64,6 +65,7 @@ declare function useFiles(query?: FileListQuery, options?: {
 interface UseStorageInfoResult {
     data: StorageInfo | null;
     isLoading: boolean;
+    /** Load failure, or the sign-in requirement while no account is signed in. */
     error: BasicError | null;
     refresh(): void;
 }
@@ -71,8 +73,8 @@ declare function useStorageInfo(): UseStorageInfoResult;
 
 interface UseMountsResult<S extends BasicSchema = BasicSchema> {
     data: MountInfo[];
-    mounts: MountInfo[];
     isLoading: boolean;
+    /** Load failure, or the sign-in requirement while no account is signed in. */
     error: BasicError | null;
     refresh(): void;
     open(mountId: string): Promise<MountHandle<S>>;
@@ -81,8 +83,8 @@ interface UseMountsResult<S extends BasicSchema = BasicSchema> {
 declare function useMounts(query?: MountsQuery): UseMountsResult;
 interface UseOutgoingSharesResult {
     data: OutgoingShareInfo[];
-    outgoingShares: OutgoingShareInfo[];
     isLoading: boolean;
+    /** Load failure, or the sign-in requirement while no account is signed in. */
     error: BasicError | null;
     refresh(): void;
     create(input: CreateOutgoingShareInput): Promise<OutgoingShareInfo>;
@@ -211,6 +213,8 @@ declare class BrowserTokenStore implements TokenStore {
     private waitForAccessToken;
 }
 
+/** The subset of BrowserTokenStore the auth channel needs; any token store providing it works. */
+type AccessTokenAdopter = Pick<BrowserTokenStore, 'accessToken' | 'adoptAccessToken'>;
 interface BrowserMessageChannel {
     postMessage(message: unknown): void;
     close(): void;
@@ -223,9 +227,11 @@ declare function createBrowserMessageChannel(name: string): BrowserMessageChanne
 /**
  * Access tokens may cross tabs transiently but are never written to browser
  * storage. The receiving adapter adopts the token before core handles the
- * ordinary token-rotation notification.
+ * ordinary token-rotation notification. Core supplies the token key for the
+ * profile's auth channel; channels without a context (the accounts channel)
+ * are plain BroadcastChannels.
  */
-declare function createBrowserAuthChannelFactory(clientId: string, tokenStore: BrowserTokenStore): (name: string) => AuthMessageChannel;
+declare function createBrowserAuthChannelFactory(tokenStore: AccessTokenAdopter): (name: string, context?: AuthChannelContext) => AuthMessageChannel;
 
 declare function browserNavigate(url: string): void;
 declare function browserCurrentUrl(): string;
@@ -269,4 +275,4 @@ declare class PersistenceStore implements ReplicaStoreFactory {
 /** Browser multipart transport with upload progress, adapted from the Drive UI. */
 declare const browserUploadTransport: UploadTransportAdapter;
 
-export { BasicProvider, type BasicProviderProps, type BoundBasicProviderProps, type BrowserBasicConfig, BrowserKeyValueStorage, type BrowserLockManager, type BrowserMessageChannel, BrowserTokenStore, type CreateBasicConfig, type CreatedBasic, PersistenceStore, type PersistenceStoreOptions, type UseAccountsResult, type UseAuthResult, type UseBasicResult, type UseFilesResult, type UseMountsResult, type UseOutgoingSharesResult, type UseQueryResult, type UseReposResult, type UseStorageInfoResult, type UseSyncStatusResult, browserCurrentUrl, browserNavigate, browserReplaceUrl, browserStorage, browserUploadTransport, createBasic, createBasicClient, createBrowserAuthChannelFactory, createBrowserMessageChannel, useAccounts, useAuth, useBasic, useCollection, useDb, useFiles, useMounts, useOutgoingShares, useQuery, useRepos, useSchemaStatus, useStorageInfo, useSyncStatus };
+export { type AccessTokenAdopter, BasicProvider, type BasicProviderProps, type BoundBasicProviderProps, type BrowserBasicConfig, BrowserKeyValueStorage, type BrowserLockManager, type BrowserMessageChannel, BrowserTokenStore, type CreateBasicConfig, type CreatedBasic, PersistenceStore, type PersistenceStoreOptions, type UseAccountsResult, type UseAuthResult, type UseBasicResult, type UseFilesResult, type UseMountsResult, type UseOutgoingSharesResult, type UseQueryResult, type UseReposResult, type UseStorageInfoResult, type UseSyncStatusResult, browserCurrentUrl, browserNavigate, browserReplaceUrl, browserStorage, browserUploadTransport, createBasic, createBasicClient, createBrowserAuthChannelFactory, createBrowserMessageChannel, useAccounts, useAuth, useBasic, useCollection, useDb, useFiles, useMounts, useOutgoingShares, useQuery, useRepos, useSchemaStatus, useStorageInfo, useSyncStatus };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode, ReactElement } from 'react';
-import { BasicSchema, BasicConfig, BasicClient, BasicAccount, BasicProfile, AuthStatus, BasicError, AuthUser, BasicSyncStatus, BasicRejection, BasicConflict, SourceRef, SchemaStatus, BasicDb, Repo, FileRecord, MountFileInfo, StorageInfo, FileListQuery, MountInfo, MountHandle, OutgoingShareInfo, CreateOutgoingShareInput, MountsQuery, JsonObject, BasicRecord, Query, MountViewerFiles, OwnerFiles, TableNames, Collection, InferValue, KeyValueStorage, TokenStore, AuthMessageChannel, ReplicaStoreFactory, StoragePartition, ReplicaStore, UploadTransportAdapter } from '@basictech/core';
+import { BasicSchema, BasicConfig, BasicClient, BasicAccount, BasicProfile, ReadOnlyReason, AuthStatus, BasicError, AuthUser, BasicSyncStatus, BasicRejection, BasicConflict, SourceRef, SchemaStatus, BasicDb, Repo, FileRecord, MountFileInfo, StorageInfo, FileListQuery, MountInfo, MountHandle, OutgoingShareInfo, CreateOutgoingShareInput, MountsQuery, JsonObject, BasicRecord, Query, MountViewerFiles, OwnerFiles, TableNames, Collection, InferValue, KeyValueStorage, TokenStore, AuthChannelContext, AuthMessageChannel, ReplicaStoreFactory, StoragePartition, ReplicaStore, UploadTransportAdapter } from '@basictech/core';
 
 type BrowserBasicConfig<S extends BasicSchema = BasicSchema> = BasicConfig<S>;
 /** Create a core client with the complete browser adapter set installed. */
@@ -8,7 +8,7 @@ declare function createBasicClient<S extends BasicSchema>(config: BrowserBasicCo
 
 interface UseAccountsResult {
     accounts: BasicAccount[];
-    active: BasicAccount | null;
+    activeAccount: BasicAccount | null;
     switchAccount(id: string): Promise<void>;
     addAccount(): Promise<BasicProfile>;
     removeAccount(id: string): Promise<void>;
@@ -20,8 +20,9 @@ interface UseAuthResult {
     isSignedIn: boolean;
     isAnonymous: boolean;
     canWrite: boolean;
-    readOnlyReason: string | null;
+    readOnlyReason: ReadOnlyReason | null;
     status: AuthStatus;
+    /** Raw auth diagnostic; stable identity while its code and expired state are unchanged. */
     error: BasicError | null;
     user: AuthUser | null;
     did: string | null;
@@ -64,6 +65,7 @@ declare function useFiles(query?: FileListQuery, options?: {
 interface UseStorageInfoResult {
     data: StorageInfo | null;
     isLoading: boolean;
+    /** Load failure, or the sign-in requirement while no account is signed in. */
     error: BasicError | null;
     refresh(): void;
 }
@@ -71,8 +73,8 @@ declare function useStorageInfo(): UseStorageInfoResult;
 
 interface UseMountsResult<S extends BasicSchema = BasicSchema> {
     data: MountInfo[];
-    mounts: MountInfo[];
     isLoading: boolean;
+    /** Load failure, or the sign-in requirement while no account is signed in. */
     error: BasicError | null;
     refresh(): void;
     open(mountId: string): Promise<MountHandle<S>>;
@@ -81,8 +83,8 @@ interface UseMountsResult<S extends BasicSchema = BasicSchema> {
 declare function useMounts(query?: MountsQuery): UseMountsResult;
 interface UseOutgoingSharesResult {
     data: OutgoingShareInfo[];
-    outgoingShares: OutgoingShareInfo[];
     isLoading: boolean;
+    /** Load failure, or the sign-in requirement while no account is signed in. */
     error: BasicError | null;
     refresh(): void;
     create(input: CreateOutgoingShareInput): Promise<OutgoingShareInfo>;
@@ -211,6 +213,8 @@ declare class BrowserTokenStore implements TokenStore {
     private waitForAccessToken;
 }
 
+/** The subset of BrowserTokenStore the auth channel needs; any token store providing it works. */
+type AccessTokenAdopter = Pick<BrowserTokenStore, 'accessToken' | 'adoptAccessToken'>;
 interface BrowserMessageChannel {
     postMessage(message: unknown): void;
     close(): void;
@@ -223,9 +227,11 @@ declare function createBrowserMessageChannel(name: string): BrowserMessageChanne
 /**
  * Access tokens may cross tabs transiently but are never written to browser
  * storage. The receiving adapter adopts the token before core handles the
- * ordinary token-rotation notification.
+ * ordinary token-rotation notification. Core supplies the token key for the
+ * profile's auth channel; channels without a context (the accounts channel)
+ * are plain BroadcastChannels.
  */
-declare function createBrowserAuthChannelFactory(clientId: string, tokenStore: BrowserTokenStore): (name: string) => AuthMessageChannel;
+declare function createBrowserAuthChannelFactory(tokenStore: AccessTokenAdopter): (name: string, context?: AuthChannelContext) => AuthMessageChannel;
 
 declare function browserNavigate(url: string): void;
 declare function browserCurrentUrl(): string;
@@ -269,4 +275,4 @@ declare class PersistenceStore implements ReplicaStoreFactory {
 /** Browser multipart transport with upload progress, adapted from the Drive UI. */
 declare const browserUploadTransport: UploadTransportAdapter;
 
-export { BasicProvider, type BasicProviderProps, type BoundBasicProviderProps, type BrowserBasicConfig, BrowserKeyValueStorage, type BrowserLockManager, type BrowserMessageChannel, BrowserTokenStore, type CreateBasicConfig, type CreatedBasic, PersistenceStore, type PersistenceStoreOptions, type UseAccountsResult, type UseAuthResult, type UseBasicResult, type UseFilesResult, type UseMountsResult, type UseOutgoingSharesResult, type UseQueryResult, type UseReposResult, type UseStorageInfoResult, type UseSyncStatusResult, browserCurrentUrl, browserNavigate, browserReplaceUrl, browserStorage, browserUploadTransport, createBasic, createBasicClient, createBrowserAuthChannelFactory, createBrowserMessageChannel, useAccounts, useAuth, useBasic, useCollection, useDb, useFiles, useMounts, useOutgoingShares, useQuery, useRepos, useSchemaStatus, useStorageInfo, useSyncStatus };
+export { type AccessTokenAdopter, BasicProvider, type BasicProviderProps, type BoundBasicProviderProps, type BrowserBasicConfig, BrowserKeyValueStorage, type BrowserLockManager, type BrowserMessageChannel, BrowserTokenStore, type CreateBasicConfig, type CreatedBasic, PersistenceStore, type PersistenceStoreOptions, type UseAccountsResult, type UseAuthResult, type UseBasicResult, type UseFilesResult, type UseMountsResult, type UseOutgoingSharesResult, type UseQueryResult, type UseReposResult, type UseStorageInfoResult, type UseSyncStatusResult, browserCurrentUrl, browserNavigate, browserReplaceUrl, browserStorage, browserUploadTransport, createBasic, createBasicClient, createBrowserAuthChannelFactory, createBrowserMessageChannel, useAccounts, useAuth, useBasic, useCollection, useDb, useFiles, useMounts, useOutgoingShares, useQuery, useRepos, useSchemaStatus, useStorageInfo, useSyncStatus };