@ic-reactor/react 3.7.0 → 3.9.0

package/README.md

@@ -13,6 +13,28 @@ pnpm add @ic-reactor/react @icp-sdk/core @tanstack/react-query
 pnpm add @icp-sdk/auth
 ```
 
+`@icp-sdk/auth` is an optional peer. `AuthenticationManager` reaches it through a
+literal `import("@icp-sdk/auth/client")`, so Vite, Rollup and webpack code-split
+it into its own async chunk. That chunk is never fetched unless something
+touches authentication, and its bytes are dropped from the output entirely in
+apps that never reference the class.
+
+Bundlers still **resolve** that specifier while building the module graph, which
+happens before any tree-shaking — so a missing peer cannot simply be optimized
+away. The import therefore sits inside a `try` block, which webpack-family
+bundlers treat as declaring an optional dependency: with the peer absent the
+build succeeds and prints one warning,
+`Module not found: Can't resolve '@icp-sdk/auth/client'`. Only the login paths
+are affected, and they throw an actionable error if they are ever called.
+
+Install the peer to remove the warning, or silence it with
+[`ignoreWarnings`](https://webpack.js.org/configuration/other-options/#ignorewarnings):
+
+```js
+// webpack.config.js / next.config.js (webpack)
+ignoreWarnings: [{ module: /@ic-reactor\/react/, message: /@icp-sdk\/auth/ }]
+```
+
 ## Quick Start
 
 ```tsx
@@ -25,7 +47,6 @@ export const queryClient = new QueryClient()
 
 export const clientManager = new ClientManager({
   queryClient,
-  withCanisterEnv: true,
 })
 
 export const backend = new Reactor<_SERVICE>({
@@ -136,12 +157,41 @@ const mutation = updateProfile.useMutation({
 })
 ```
 
-## Identity Attributes / OpenID email and profile values
+## Internet Identity
 
-Identity attributes use a dedicated `IdentityAttributesManager`, with React
-bindings created by `createIdentityAttributeHooks`. The configured auth client
-must support the `@icp-sdk/auth` v7 constructor, sign-in, sign-out, and
-attribute-request APIs.
+`defineReactor` wires up Internet Identity for you — `useAuth`,
+`useUserPrincipal`, `useAgentState` and `useIdentityAttributes` come back
+alongside the actor hooks:
+
+```tsx
+// src/reactor.ts
+export const { useActorQuery, useAuth, useIdentityAttributes, authentication } =
+  defineReactor<_SERVICE>({
+    name: "backend",
+    idlFactory,
+    auth: {
+      // Required when the app is served from more than one origin, so every
+      // origin resolves to the same principal.
+      derivationOrigin: "https://app.example.com",
+      // The default signs the user out and reloads after 10 minutes idle.
+      idleOptions: { disableIdle: true },
+    },
+  })
+```
+
+Auth options are forwarded to the underlying `@icp-sdk/auth` client:
+`identityProvider`, `derivationOrigin`, `windowOpenerFeatures`,
+`openIdProvider`, `storage`, `keyType`, `idleOptions`, `identity`, and
+`transport`. Only the `"google" | "apple" | "microsoft"` aliases are accepted
+for `openIdProvider`; any other value is dropped, since raw issuer URLs are
+only meaningful on `requestOpenIdAttributes`, where they scope the keys.
+
+Pass `authentication` from one reactor into another to share a single session
+across canisters. That reactor adopts the manager's `ClientManager` so sign-in
+updates the agent it calls through, so pass either `authentication` or `auth` —
+not both.
+
+Set up manually when you need more control:
 
 ```tsx
 // src/auth.ts
@@ -162,6 +212,59 @@ export const { useIdentityAttributes } =
   createIdentityAttributeHooks(identityAttributes)
 ```
 
+`useAuth()` calls `authentication.prepareClient()` on mount. Outside React, do
+it yourself during startup — it preloads the auth module so `login()` can open
+the identity provider window synchronously inside a click handler, which is
+what browser popup blockers require:
+
+```ts
+// once, at startup — awaits the dynamic import and builds the AuthClient
+await authentication.prepareClient()
+
+// later, inside the click handler — no await before signIn(), so the popup
+// still counts as user-initiated
+button.onclick = () => authentication.login()
+```
+
+`authentication.getPreparedClient()` returns the already-built client
+synchronously, or `undefined` when the module has not loaded yet.
+
+If your bundler cannot resolve the optional peer at all, construct the client
+yourself and inject it — IC Reactor then never imports `@icp-sdk/auth`:
+
+```ts
+import { AuthClient } from "@icp-sdk/auth/client"
+
+const authentication = new AuthenticationManager({
+  clientManager,
+  authClient: new AuthClient(),
+})
+```
+
+## Identity Attributes / OpenID email and profile values
+
+Identity attributes use a dedicated `IdentityAttributesManager`, with React
+bindings created by `createIdentityAttributeHooks`. Works with `@icp-sdk/auth`
+v7 and v8; the two versions disagree on the nonce contract and IC Reactor
+normalizes whichever form you pass.
+
+**Pass the nonce as a callback.** Awaiting your backend before calling
+`requestOpenIdAttributes` ends the user gesture, and the browser then blocks
+the Internet Identity window:
+
+```tsx
+// ✅ window opens immediately, nonce resolves while the user is in II
+await requestOpenIdAttributes({
+  nonce: () => backend.registerBegin(),
+  openIdProvider: "google",
+  keys: ["email", "name"],
+})
+
+// ❌ gesture is gone by the time the window would open
+const nonce = await backend.registerBegin()
+await requestOpenIdAttributes({ nonce, openIdProvider: "google", keys })
+```
+
 ```tsx
 // src/RegisterWithOpenIdProvider.tsx
 import { useIdentityAttributes } from "./auth"
@@ -176,10 +279,8 @@ function RegisterWithOpenIdProvider() {
   } = useIdentityAttributes()
 
   async function handleProviderLogin() {
-    const nonce = await backend.registerBegin()
-
     const result = await requestOpenIdAttributes({
-      nonce,
+      nonce: () => backend.registerBegin(),
       openIdProvider: "microsoft",
       keys: ["email", "name"],
       windowOpenerFeatures: popupCenter(),
@@ -212,6 +313,54 @@ must send `signedAttributes.data` and `signedAttributes.signature` to the backen
 or canister and verify the signature, nonce, origin, timestamp, and requested keys
 before trusting or storing the attributes.
 
+## Server-Side Rendering
+
+**Build the reactor inside the request, not at module scope.**
+
+A reactor owns its `QueryClient`. On a server a module-scope reactor is created
+once per process and shared by every request, and query keys are
+`[canisterId, functionName, args]` — they do not include the caller. So a
+cached result for a caller-scoped method (`get_my_balance`, a deposit address,
+`my_profile`) is handed to whichever request asks next:
+
+```tsx
+// ❌ Shared by every request on the server
+export const app = defineReactor<_SERVICE>({
+  name: "backend",
+  idlFactory,
+  canisterId,
+})
+```
+
+```tsx
+// ✅ Per request: nothing is shared between users
+export default async function Page() {
+  const app = defineReactor<_SERVICE>({
+    name: "backend",
+    idlFactory,
+    canisterId,
+    queryClient: new QueryClient(),
+  })
+
+  const data = await app.reactor.fetchQuery({ functionName: "get_my_profile" })
+  return <Profile data={data} />
+}
+```
+
+Two further constraints on the App Router specifically:
+
+- Hooks are client-only, like every React hook — call them from a `"use client"`
+  module. A server component may import `Reactor` / `ClientManager` and make
+  imperative calls; that path works.
+- Hooks bind to their reactor's own `QueryClient` rather than to a
+  `QueryClientProvider`, so `HydrationBoundary` prefetch does not feed them
+  unless the provider's client _is_ that reactor's client. Next.js also
+  evaluates a shared module twice on the server (the RSC and SSR graphs), so a
+  module-scope reactor is two different instances there.
+
+If none of that applies — a client-only SPA — module-scope reactors are exactly
+right and none of this is a concern.
+
 ## Query Result Methods
 
 Every object returned by `createQuery`, `createSuspenseQuery`, and their

package/dist/auth/authentication-manager.d.ts

@@ -1,10 +1,14 @@
 import type { Identity } from "@icp-sdk/core/agent";
-import type { AuthClientLike, AuthClientSignInOptions, AuthState, AuthenticationClientOptions, AuthenticationSignInOptions } from "./types";
+import type { AuthClientLike, AuthClientSignInOptions, AuthState, AuthenticationClientOptions, AuthenticationSignInOptions } from "./types.js";
 import { ClientManager } from "@ic-reactor/core";
-export interface AuthenticationManagerParameters {
+export interface AuthenticationManagerParameters extends AuthenticationClientOptions {
     clientManager: ClientManager;
+    /**
+     * Bring your own client instance. When provided, IC Reactor never constructs
+     * one and never applies the options below to it.
+     */
     authClient?: AuthClientLike;
-    identityProvider?: string | URL;
+    /** Canister ID of a locally deployed Internet Identity. */
     internetIdentityId?: string;
 }
 /**
@@ -26,20 +30,36 @@ export declare class AuthenticationManager {
     private authClientConstructor?;
     private authClientConstructorPromise?;
     private authModuleMissing;
+    private authClientOptions?;
     private authStateValue;
     private readonly identityProvider?;
     private readonly internetIdentityId?;
+    private readonly defaultClientOptions;
     readonly clientManager: ClientManager;
     /** The current authentication state. */
     get authState(): AuthState;
-    constructor({ clientManager, authClient, identityProvider, internetIdentityId, }: AuthenticationManagerParameters);
+    constructor({ clientManager, authClient, identityProvider, internetIdentityId, ...clientOptions }: AuthenticationManagerParameters);
     /** @internal Used by IdentityAttributesManager. */
     get client(): AuthClientLike | undefined;
     subscribeAuthState(callback: (state: AuthState) => void): () => void;
     /**
-     * Preloads and creates an AuthClient before a user gesture is needed.
+     * Preloads the auth module and creates an AuthClient ahead of time.
+     *
+     * Call (and await) this before wiring up a login button: it makes
+     * {@link login} and {@link IdentityAttributesManager.request} able to open
+     * the identity provider synchronously inside the click handler, which is
+     * what browser popup blockers and the ICRC-29 transport require.
      */
     prepareClient(options?: AuthenticationClientOptions): Promise<AuthClientLike | undefined>;
+    /**
+     * Returns an AuthClient without awaiting, or `undefined` when the auth
+     * module has not been loaded yet.
+     *
+     * Callers that must stay inside a user gesture use this instead of
+     * {@link ensureClient}; awaiting anything before opening the identity
+     * provider window loses the gesture.
+     */
+    getPreparedClient(options?: AuthenticationClientOptions): AuthClientLike | undefined;
     authenticate: () => Promise<Identity | undefined>;
     login: (loginOptions?: AuthenticationSignInOptions) => Promise<void>;
     logout: (options?: {
@@ -49,7 +69,19 @@ export declare class AuthenticationManager {
     /** @internal Used by IdentityAttributesManager. */
     signInOrRecoverIdentity(options?: AuthClientSignInOptions): Promise<Identity>;
     private ensurePreparedClient;
+    /**
+     * Only rebuild the client when the effective options actually changed.
+     *
+     * Recreating on every call would discard the client warmed up by
+     * `prepareClient()` and register a duplicate sign-out callback on the
+     * shared IdleManager singleton each time.
+     */
     private shouldRecreateClient;
+    /**
+     * Merges constructor-level defaults with per-call overrides and fills in the
+     * network-appropriate identity provider.
+     */
+    private resolveClientOptions;
     private syncStateFromClient;
     /** @internal Used by IdentityAttributesManager. */
     ensureClient(options?: AuthenticationClientOptions): Promise<AuthClientLike | undefined>;

package/dist/auth/authentication-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authentication-manager.d.ts","sourceRoot":"","sources":["../../src/auth/authentication-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,KAAK,EACV,cAAc,EACd,uBAAuB,EACvB,SAAS,EACT,2BAA2B,EAC3B,2BAA2B,EAC5B,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,aAAa,EAAS,MAAM,kBAAkB,CAAA;AASvD,MAAM,WAAW,+BAA+B;IAC9C,aAAa,EAAE,aAAa,CAAA;IAC5B,UAAU,CAAC,EAAE,cAAc,CAAA;IAC3B,gBAAgB,CAAC,EAAE,MAAM,GAAG,GAAG,CAAA;IAC/B,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAQD;;;;;;;;;GASG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,UAAU,CAAC,CAAgB;IACnC,OAAO,CAAC,WAAW,CAAC,CAA+B;IACnD,OAAO,CAAC,qBAAqB,CAAQ;IACrC,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,oBAAoB,CAAwC;IACpE,OAAO,CAAC,qBAAqB,CAAC,CAAuB;IACrD,OAAO,CAAC,4BAA4B,CAAC,CAEpC;IACD,OAAO,CAAC,iBAAiB,CAAQ;IACjC,OAAO,CAAC,cAAc,CAKrB;IACD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAc;IAChD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAQ;IAC5C,SAAgB,aAAa,EAAE,aAAa,CAAA;IAE5C,wCAAwC;IACxC,IAAW,SAAS,IAAI,SAAS,CAEhC;gBAEW,EACV,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,kBAAkB,GACnB,EAAE,+BAA+B;IA2BlC,mDAAmD;IACnD,IAAW,MAAM,+BAEhB;IAEM,kBAAkB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI;IAS9D;;OAEG;IACU,aAAa,CAAC,OAAO,CAAC,EAAE,2BAA2B;IAiBzD,YAAY,QAAa,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAuD5D;IAEM,KAAK,GAAU,eAAe,2BAA2B,mBA2D/D;IAEM,MAAM,GAAU,UAAU;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,mBAerD;YAEa,gBAAgB;IAa9B,mDAAmD;IACtC,uBAAuB,CAClC,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,QAAQ,CAAC;IAyBpB,OAAO,CAAC,oBAAoB;IAmB5B,OAAO,CAAC,oBAAoB;YAId,mBAAmB;IAmBjC,mDAAmD;IACtC,YAAY,CAAC,OAAO,CAAC,EAAE,2BAA2B;IAY/D,mDAAmD;IACtC,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE,OAAO;IAQxE,mDAAmD;IAC5C,iBAAiB;IAIxB,mDAAmD;IAC5C,sBAAsB,CAAC,KAAK,EAAE,KAAK;IAI1C,OAAO,CAAC,0BAA0B;IAYlC,OAAO,CAAC,WAAW;YASL,yBAAyB;CAsCxC"}
+{"version":3,"file":"authentication-manager.d.ts","sourceRoot":"","sources":["../../src/auth/authentication-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,KAAK,EACV,cAAc,EACd,uBAAuB,EACvB,SAAS,EACT,2BAA2B,EAC3B,2BAA2B,EAC5B,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,aAAa,EAAwB,MAAM,kBAAkB,CAAA;AAUtE,MAAM,WAAW,+BAAgC,SAAQ,2BAA2B;IAClF,aAAa,EAAE,aAAa,CAAA;IAC5B;;;OAGG;IACH,UAAU,CAAC,EAAE,cAAc,CAAA;IAC3B,2DAA2D;IAC3D,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAMD;;;;;;;;;GASG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,UAAU,CAAC,CAAgB;IACnC,OAAO,CAAC,WAAW,CAAC,CAA+B;IACnD,OAAO,CAAC,qBAAqB,CAAQ;IACrC,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,oBAAoB,CAAwC;IACpE,OAAO,CAAC,qBAAqB,CAAC,CAAuB;IACrD,OAAO,CAAC,4BAA4B,CAAC,CAEpC;IACD,OAAO,CAAC,iBAAiB,CAAQ;IACjC,OAAO,CAAC,iBAAiB,CAAC,CAA6B;IACvD,OAAO,CAAC,cAAc,CAKrB;IACD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAc;IAChD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA6B;IAClE,SAAgB,aAAa,EAAE,aAAa,CAAA;IAE5C,wCAAwC;IACxC,IAAW,SAAS,IAAI,SAAS,CAEhC;gBAEW,EACV,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,GAAG,aAAa,EACjB,EAAE,+BAA+B;IAiClC,mDAAmD;IACnD,IAAW,MAAM,+BAEhB;IAEM,kBAAkB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI;IAS9D;;;;;;;OAOG;IACU,aAAa,CAAC,OAAO,CAAC,EAAE,2BAA2B;IAUhE;;;;;;;OAOG;IACI,iBAAiB,CACtB,OAAO,CAAC,EAAE,2BAA2B,GACpC,cAAc,GAAG,SAAS;IAItB,YAAY,QAAa,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CA2E5D;IAEM,KAAK,GAAU,eAAe,2BAA2B,mBAwD/D;IAEM,MAAM,GAAU,UAAU;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,mBAuBrD;YAEa,gBAAgB;IAc9B,mDAAmD;IACtC,uBAAuB,CAClC,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,QAAQ,CAAC;IAyBpB,OAAO,CAAC,oBAAoB;IAiB5B;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAO5B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;YAed,mBAAmB;IAmBjC,mDAAmD;IACtC,YAAY,CAAC,OAAO,CAAC,EAAE,2BAA2B;IAQ/D,mDAAmD;IACtC,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE,OAAO;IAQxE,mDAAmD;IAC5C,iBAAiB;IAIxB,mDAAmD;IAC5C,sBAAsB,CAAC,KAAK,EAAE,KAAK;IAI1C,OAAO,CAAC,0BAA0B;IAYlC,OAAO,CAAC,WAAW;YASL,yBAAyB;CAkCxC"}