@basictech/react 0.11.0-beta.1 → 0.11.0-beta.2

package/README.md

@@ -151,8 +151,8 @@ client.
 | --- | --- | --- | --- |
 | `clientId` | `string` | Required | The application's client DID. Its Basic app metadata must register the redirect URI. |
 | `schema` | `S extends BasicSchema` | Required by `createBasic` | Pass the `defineSchema()` result used by this application. It is optional only in the lower-level `createBasicClient`. |
-| `identityOrigin` | `string` | `'https://basic.id'` | Use another Identity v1 origin for handle resolution and the shares management URL. |
-| `defaultPds` | `string` | `'https://pds.basic.id'` | Change the PDS discovered by no-argument `signIn()`. `signIn(handleOrDid)` discovers that identity's PDS instead. |
+| `identityOrigin` | `string` | `'https://basic.id'` | Use another Basic ID web origin for the shares management URL. |
+| `defaultPds` | `string` | `'https://pds.basic.id'` | Change the PDS used for handle resolution and no-argument `signIn()`. `signIn(handleOrDid)` discovers that identity's PDS after resolving handles here. |
 | `redirectUri` | `string` | `location.origin + location.pathname` | Set an explicit OAuth callback route. Outside a browser location, it is required. The URI must appear in the client metadata for `clientId`. |
 | `mode` | `'sync' \| 'rest'` | `'sync'` | Choose direct REST when offline replicas, anonymous mode, multi-account state, and `watch()` are not needed. |
 | `anonymous` | `boolean` | `true` in sync mode | Set `false` to require sign-in. REST mode always disables anonymous workspaces. |
@@ -170,6 +170,7 @@ client.
 | `currentUrl` | `() => string` | `location.href`, or `''` without `location` | Tell auth bootstrap where to read OAuth `code` and `state`. |
 | `replaceUrl` | `(url: string) => void` | `history.replaceState({}, '', url)` | Integrate removal of consumed OAuth query parameters with custom navigation. |
 | `createMessageChannel` | `(name: string) => AuthMessageChannel` | `BroadcastChannel` when available | Replace or disable cross-context auth notifications. The default token adapter also transfers access tokens transiently between tabs. |
+| `reconcileTrigger` | `(listener: () => void) => () => void` | `focus`, `online`, and `visibilitychange` listeners | Subscribe the client to host lifecycle signals so a suspended or backgrounded application reconciles credentials with its owner and mounted Sync sessions on resume. Return a cleanup function; the client calls it on `stop()`. |
 | `ownerCredential` | `OwnerCredentialAdapter` | None | First-party Basic ID/dev tooling can inject owner credentials for `client.drive()`, account-wide `client.storageInfo()`, and `client.shares.leave()`. Normal app credentials should use existing repos and `shares.manageUrl()`. |
 | `uploadTransport` | `UploadTransportAdapter` | Browser XHR, then the core fetch fallback | Supply a multipart transport. XHR is used by default because fetch has no upload-progress events. |
 | `warn` | `(message: string) => void` | `console.warn` for schema checks | Route schema-drift warnings into application logging. |
@@ -192,6 +193,10 @@ The defaults are selected from browser capabilities at client creation:
 - **Auth coordination:** token rotation and sign-out notifications use `BroadcastChannel` when
   available. Access tokens can cross that channel transiently but are not written by the default
   token store.
+- **Lifecycle recovery:** when a tab regains focus, comes back online, or becomes visible again,
+  the client reconciles fresh credentials with the owner and mounted Sync sessions. A browser that
+  suspended the page recovers without a reload, and transient refresh failures retry rather than
+  signing the profile out. Override `reconcileTrigger` to supply that signal in another host.
 - **Uploads:** browser multipart uploads use XHR for real `onProgress(loaded, total)` events. The
   fetch fallback reports only start and completion.
 
@@ -745,6 +750,7 @@ Shares v2 is capability-gated and requires sign-in. `useOutgoingShares()` return
   get(id: string): Promise<OutgoingShareInfo>
   cancel(id: string): Promise<OutgoingShareInfo>
   revoke(id: string): Promise<OutgoingShareInfo>
+  getContactHandle(did: string): Promise<string | null>
   manageUrl(): string
 }
 ```
@@ -754,7 +760,7 @@ Shares v2 is capability-gated and requires sign-in. `useOutgoingShares()` return
 | Field | Type | Meaning |
 | --- | --- | --- |
 | `repo` | `'default' \| { repoId: string }` | Origin repo |
-| recipient | Exactly one of `recipientHandle: string` or `recipientDid: string` | A handle is trimmed, lowercased, and resolved through `identityOrigin`; a canonical DID skips handle resolution. |
+| recipient | Exactly one of `recipientHandle: string` or `recipientDid: string` | A handle is trimmed, lowercased, and resolved through `defaultPds`; a canonical DID skips handle resolution. |
 | `role` | `'viewer' \| 'editor'` | Collaborator role |
 | `scope` | `Array<{ table: string } \| { table: string; recordIds: string[] }>` | Whole-table clauses or static record sets |
 | `acceptBy` | `string` | Optional acceptance deadline passed to Shares v2 |
@@ -807,6 +813,10 @@ export function OutgoingShares() {
 `deliveryState`, and created, accepted, and ended timestamps/reasons. Revocation prevents future
 access but cannot retract data a recipient already downloaded.
 
+After a handle-based share is created successfully, the SDK stores a profile-local contact entry
+containing `{ did, handle }` in browser local storage. Use `getContactHandle(recipientDid)` to show
+the remembered handle; it returns `null` for DIDs that were shared directly or are not cached.
+
 `manageUrl()` returns the Basic ID `/shares` handoff. Invite acceptance and ordinary mount
 management belong there. `client.shares.leave()` is intentionally owner-only and throws
 `OWNER_CREDENTIAL_REQUIRED` without an explicit owner adapter.
@@ -1093,8 +1103,8 @@ for the lower-level model.
   Client Components should import `@basictech/react` directly.
 - Migrating from 0.10 requires deliberate call-site changes; there is no compatibility layer. Read
   [Migrating to Basic SDK 0.11](https://github.com/basicdb/basic-server/blob/dev/docs/MIGRATING_TO_0.11.md).
-- `0.11.0-beta.0` is a beta API. Check the installed version rather than assuming the repository
-  workspace has already been published.
+- 0.11 is a beta API, published to npm under the `beta` dist-tag. Check the installed version
+  rather than assuming it matches the repository workspace.
 
 ## License
 

package/dist/index.d.mts

@@ -87,6 +87,7 @@ interface UseOutgoingSharesResult {
     get(id: string): Promise<OutgoingShareInfo>;
     cancel(id: string): Promise<OutgoingShareInfo>;
     revoke(id: string): Promise<OutgoingShareInfo>;
+    getContactHandle(did: string): Promise<string | null>;
     manageUrl(): string;
 }
 declare function useOutgoingShares(): UseOutgoingSharesResult;

package/dist/index.d.ts

@@ -87,6 +87,7 @@ interface UseOutgoingSharesResult {
     get(id: string): Promise<OutgoingShareInfo>;
     cancel(id: string): Promise<OutgoingShareInfo>;
     revoke(id: string): Promise<OutgoingShareInfo>;
+    getContactHandle(did: string): Promise<string | null>;
     manageUrl(): string;
 }
 declare function useOutgoingShares(): UseOutgoingSharesResult;

package/dist/index.js

@@ -60,7 +60,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/create-client.ts
-var import_core5 = require("@basictech/core");
+var import_core4 = require("@basictech/core");
 
 // src/adapters/broadcast-channel.ts
 function createBrowserMessageChannel(name) {
@@ -444,7 +444,6 @@ function browserStorage(name) {
 }
 
 // src/adapters/token-store.ts
-var import_core3 = require("@basictech/core");
 var ACCESS_TOKEN_ADOPTION_TIMEOUT_MS = 100;
 function parseTokens(value) {
   if (!value) return null;
@@ -521,7 +520,7 @@ var BrowserTokenStore = class {
     else this.accessWaiters.delete(key);
   }
   waitForAccessToken(key, refreshToken) {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve) => {
       let timer;
       const waiter = {
         refreshToken,
@@ -537,17 +536,14 @@ var BrowserTokenStore = class {
         const remaining = (this.accessWaiters.get(key) ?? []).filter((candidate) => candidate !== waiter);
         if (remaining.length) this.accessWaiters.set(key, remaining);
         else this.accessWaiters.delete(key);
-        reject(new import_core3.BasicError(
-          "ACCESS_TOKEN_ADOPTION_TIMEOUT",
-          "timed out waiting for the access token matching persisted refresh material"
-        ));
+        resolve(null);
       }, ACCESS_TOKEN_ADOPTION_TIMEOUT_MS);
     });
   }
 };
 
 // src/adapters/upload.ts
-var import_core4 = require("@basictech/core");
+var import_core3 = require("@basictech/core");
 function responseHeaders(xhr) {
   const headers = new Headers();
   for (const line of xhr.getAllResponseHeaders().trim().split(/[\r\n]+/)) {
@@ -560,7 +556,7 @@ function responseHeaders(xhr) {
 var browserUploadTransport = {
   upload(request) {
     if (typeof XMLHttpRequest === "undefined") {
-      return Promise.reject(new import_core4.BasicError("XHR_UNAVAILABLE"));
+      return Promise.reject(new import_core3.BasicError("XHR_UNAVAILABLE"));
     }
     return new Promise((resolve, reject) => {
       const xhr = new XMLHttpRequest();
@@ -592,9 +588,9 @@ var browserUploadTransport = {
         statusText: xhr.statusText,
         headers: responseHeaders(xhr)
       })));
-      xhr.onerror = () => finish(() => reject(new import_core4.BasicError("NETWORK_ERROR", "the upload could not reach the server")));
+      xhr.onerror = () => finish(() => reject(new import_core3.BasicError("NETWORK_ERROR", "the upload could not reach the server")));
       xhr.onabort = () => finish(() => reject(request.signal?.reason ?? new DOMException("Aborted", "AbortError")));
-      xhr.ontimeout = () => finish(() => reject(new import_core4.BasicError("NETWORK_ERROR", "the upload timed out")));
+      xhr.ontimeout = () => finish(() => reject(new import_core3.BasicError("NETWORK_ERROR", "the upload timed out")));
       const form = new FormData();
       form.append("path", request.path);
       if (request.name !== void 0) form.append("name", request.name);
@@ -606,21 +602,37 @@ var browserUploadTransport = {
 };
 
 // src/create-client.ts
+function browserReconcileTrigger(listener) {
+  if (typeof window === "undefined" || typeof document === "undefined") return () => {
+  };
+  const onVisible = () => {
+    if (document.visibilityState === "visible") listener();
+  };
+  window.addEventListener("focus", listener);
+  window.addEventListener("online", listener);
+  document.addEventListener("visibilitychange", onVisible);
+  return () => {
+    window.removeEventListener("focus", listener);
+    window.removeEventListener("online", listener);
+    document.removeEventListener("visibilitychange", onVisible);
+  };
+}
 function createBasicClient(config) {
-  const local = browserStorage("localStorage") ?? new import_core5.MemoryKeyValueStorage();
-  const session = browserStorage("sessionStorage") ?? new import_core5.MemoryKeyValueStorage();
+  const local = browserStorage("localStorage") ?? new import_core4.MemoryKeyValueStorage();
+  const session = browserStorage("sessionStorage") ?? new import_core4.MemoryKeyValueStorage();
   const defaultTokenStore = config.tokenStore ? null : new BrowserTokenStore(local);
   const canBroadcast = typeof BroadcastChannel !== "undefined";
   const canPersistReplica = typeof indexedDB !== "undefined";
-  return (0, import_core5.createBasicClient)({
+  return (0, import_core4.createBasicClient)({
     ...config,
     kv: config.kv ?? local,
     tokenStore: config.tokenStore ?? defaultTokenStore,
     sessionStorage: config.sessionStorage ?? session,
-    replicaStore: config.replicaStore ?? (canPersistReplica ? new PersistenceStore(config.clientId) : new import_core5.MemoryReplicaStoreFactory()),
+    replicaStore: config.replicaStore ?? (canPersistReplica ? new PersistenceStore(config.clientId) : new import_core4.MemoryReplicaStoreFactory()),
     navigate: config.navigate ?? browserNavigate,
     currentUrl: config.currentUrl ?? browserCurrentUrl,
     replaceUrl: config.replaceUrl ?? browserReplaceUrl,
+    reconcileTrigger: config.reconcileTrigger ?? browserReconcileTrigger,
     createMessageChannel: config.createMessageChannel ?? (canBroadcast && defaultTokenStore ? createBrowserAuthChannelFactory(config.clientId, defaultTokenStore) : void 0),
     uploadTransport: config.uploadTransport ?? (typeof XMLHttpRequest === "undefined" ? void 0 : browserUploadTransport)
   });
@@ -706,7 +718,7 @@ var import_react4 = require("react");
 
 // src/hooks/client.ts
 var import_react3 = require("react");
-var import_core6 = require("@basictech/core");
+var import_core5 = require("@basictech/core");
 function useRequiredClient() {
   const client = (0, import_react3.useContext)(BasicClientContext);
   if (!client) throw new Error("Basic hooks must be used within a <BasicProvider>");
@@ -716,8 +728,8 @@ function useClientSnapshot(client) {
   return (0, import_react3.useSyncExternalStore)(client.subscribe, client.getSnapshot, client.getSnapshot);
 }
 function toBasicError(error, fallback = "UNKNOWN_ERROR") {
-  if (error instanceof import_core6.BasicError) return error;
-  return new import_core6.BasicError(fallback, error instanceof Error ? error.message : String(error));
+  if (error instanceof import_core5.BasicError) return error;
+  return new import_core5.BasicError(fallback, error instanceof Error ? error.message : String(error));
 }
 function useAsyncResult(load, initialData, enabled, settled, dependencies) {
   const loadRef = (0, import_react3.useRef)(load);
@@ -779,7 +791,7 @@ function useAccounts() {
 
 // src/hooks/auth.ts
 var import_react5 = require("react");
-var import_core7 = require("@basictech/core");
+var import_core6 = require("@basictech/core");
 function useAuthFor(client) {
   const snapshot = useClientSnapshot(client);
   const signIn = (0, import_react5.useCallback)((input) => client.signIn(input), [client]);
@@ -790,7 +802,7 @@ function useAuthFor(client) {
     isSignedIn: snapshot.isSignedIn,
     isAnonymous: snapshot.isAnonymous,
     status: snapshot.authStatus,
-    error: snapshot.authErrorCode ? new import_core7.BasicError(snapshot.authErrorCode) : null,
+    error: snapshot.authErrorCode ? new import_core6.BasicError(snapshot.authErrorCode) : null,
     user: snapshot.user,
     did: snapshot.did,
     handle: snapshot.handle,
@@ -979,6 +991,7 @@ function useOutgoingSharesFor(client) {
   const get = (0, import_react9.useCallback)((id) => client.shares.getOutgoing(id), [client]);
   const cancel = (0, import_react9.useCallback)((id) => client.shares.cancel(id), [client]);
   const revoke = (0, import_react9.useCallback)((id) => client.shares.revoke(id), [client]);
+  const getContactHandle = (0, import_react9.useCallback)((did) => client.shares.getContactHandle(did), [client]);
   const manageUrl = (0, import_react9.useCallback)(() => client.shares.manageUrl(), [client]);
   const { data: outgoingShares, ...state } = result;
   return {
@@ -989,6 +1002,7 @@ function useOutgoingSharesFor(client) {
     get,
     cancel,
     revoke,
+    getContactHandle,
     manageUrl
   };
 }