@ic-reactor/react 3.6.0 → 3.8.0

package/src/createSuspenseQuery.ts

@@ -34,28 +34,28 @@ import type {
   SuspenseQueryResult,
   SuspenseQueryFactoryConfig,
   NoInfer,
-} from "./types"
-import { buildChainedSelect } from "./utils"
+} from "./types.js"
+import { buildChainedSelect } from "./utils.js"
 
 // ============================================================================
 // Internal Implementation
 // ============================================================================
 
 const createSuspenseQueryImpl = <
-  A,
-  M extends FunctionName<A> = FunctionName<A>,
-  T extends TransformKey = "candid",
-  TSelected = QueryFnData<A, M, T>,
+  Service,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Transform extends TransformKey = "candid",
+  Selected = QueryFnData<Service, Method, Transform>,
 >(
-  reactor: Reactor<A, T>,
-  config: SuspenseQueryConfig<A, M, T, TSelected>
+  reactor: Reactor<Service, Transform>,
+  config: SuspenseQueryConfig<Service, Method, Transform, Selected>
 ): SuspenseQueryResult<
-  QueryFnData<A, M, T>,
-  TSelected,
-  QueryError<A, M, T>
+  QueryFnData<Service, Method, Transform>,
+  Selected,
+  QueryError<Service, Method, Transform>
 > => {
-  type TData = QueryFnData<A, M, T>
-  type TError = QueryError<A, M, T>
+  type TData = QueryFnData<Service, Method, Transform>
+  type TError = QueryError<Service, Method, Transform>
 
   const {
     functionName,
@@ -70,11 +70,11 @@ const createSuspenseQueryImpl = <
 
   const getQueryKey = () => reactor.generateQueryKey(params)
 
-  const applySelect = (raw: TData): TSelected =>
-    select ? select(raw) : (raw as unknown as TSelected)
+  const applySelect = (raw: TData): Selected =>
+    select ? select(raw) : (raw as unknown as Selected)
 
   /** Cache-first fetch for use in loaders / route preloading. */
-  const fetch = async (): Promise<TSelected> => {
+  const fetch = async (): Promise<Selected> => {
     const result = await reactor.fetchQuery(params)
     return applySelect(result)
   }
@@ -91,7 +91,7 @@ const createSuspenseQueryImpl = <
 
   const useSuspenseQueryHook: UseSuspenseQueryWithSelect<
     TData,
-    TSelected,
+    Selected,
     TError
   > = (options: any): any => {
     const baseOptions = reactor.getQueryOptions(params)
@@ -114,21 +114,20 @@ const createSuspenseQueryImpl = <
 
   const getCacheData: SuspenseQueryResult<
     TData,
-    TSelected,
+    Selected,
     TError
-  >["getCacheData"] = (selectFn?: (data: TSelected) => unknown): any => {
+  >["getCacheData"] = (selectFn?: (data: Selected) => unknown): any => {
     const raw = reactor.getQueryData(params)
     if (raw === undefined) return undefined
     const selected = applySelect(raw)
     return selectFn ? selectFn(selected) : selected
   }
 
-  const setData: SuspenseQueryResult<TData, TSelected, TError>["setData"] = (
+  const setData: SuspenseQueryResult<TData, Selected, TError>["setData"] = (
     updater
   ) => {
     return reactor.queryClient.setQueryData(getQueryKey(), updater as any) as
-      | TData
-      | undefined
+      TData | undefined
   }
 
   return {
@@ -147,17 +146,21 @@ const createSuspenseQueryImpl = <
 // ============================================================================
 
 export function createSuspenseQuery<
-  A,
-  T extends TransformKey,
-  M extends FunctionName<A> = FunctionName<A>,
-  TSelected = QueryFnData<A, M, T>,
+  Service,
+  Transform extends TransformKey,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Selected = QueryFnData<Service, Method, Transform>,
 >(
-  reactor: Reactor<A, T>,
-  config: SuspenseQueryConfig<NoInfer<A>, M, T, TSelected>
-): SuspenseQueryResult<QueryFnData<A, M, T>, TSelected, QueryError<A, M, T>> {
+  reactor: Reactor<Service, Transform>,
+  config: SuspenseQueryConfig<NoInfer<Service>, Method, Transform, Selected>
+): SuspenseQueryResult<
+  QueryFnData<Service, Method, Transform>,
+  Selected,
+  QueryError<Service, Method, Transform>
+> {
   return createSuspenseQueryImpl(
     reactor,
-    config as SuspenseQueryConfig<A, M, T, TSelected>
+    config as SuspenseQueryConfig<Service, Method, Transform, Selected>
   )
 }
 
@@ -166,24 +169,37 @@ export function createSuspenseQuery<
 // ============================================================================
 
 export function createSuspenseQueryFactory<
-  A,
-  T extends TransformKey,
-  M extends FunctionName<A> = FunctionName<A>,
-  TSelected = QueryFnData<A, M, T>,
+  Service,
+  Transform extends TransformKey,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Selected = QueryFnData<Service, Method, Transform>,
 >(
-  reactor: Reactor<A, T>,
-  config: SuspenseQueryFactoryConfig<NoInfer<A>, M, T, TSelected>
+  reactor: Reactor<Service, Transform>,
+  config: SuspenseQueryFactoryConfig<
+    NoInfer<Service>,
+    Method,
+    Transform,
+    Selected
+  >
 ): (
-  args: ReactorArgs<A, M, T>
-) => SuspenseQueryResult<QueryFnData<A, M, T>, TSelected, QueryError<A, M, T>> {
+  args: ReactorArgs<Service, Method, Transform>
+) => SuspenseQueryResult<
+  QueryFnData<Service, Method, Transform>,
+  Selected,
+  QueryError<Service, Method, Transform>
+> {
   const cache = new Map<
     string,
-    SuspenseQueryResult<QueryFnData<A, M, T>, TSelected, QueryError<A, M, T>>
+    SuspenseQueryResult<
+      QueryFnData<Service, Method, Transform>,
+      Selected,
+      QueryError<Service, Method, Transform>
+    >
   >()
 
-  return (args: ReactorArgs<A, M, T>) => {
+  return (args: ReactorArgs<Service, Method, Transform>) => {
     const key = reactor.generateQueryKey({
-      functionName: config.functionName as M,
+      functionName: config.functionName as Method,
       args,
     })
     const cacheKey = JSON.stringify(key)
@@ -191,8 +207,18 @@ export function createSuspenseQueryFactory<
     const existing = cache.get(cacheKey)
     if (existing) return existing
 
-    const result = createSuspenseQueryImpl<A, M, T, TSelected>(reactor, {
-      ...(config as SuspenseQueryFactoryConfig<A, M, T, TSelected>),
+    const result = createSuspenseQueryImpl<
+      Service,
+      Method,
+      Transform,
+      Selected
+    >(reactor, {
+      ...(config as SuspenseQueryFactoryConfig<
+        Service,
+        Method,
+        Transform,
+        Selected
+      >),
       args,
     })
     cache.set(cacheKey, result)

package/src/defineReactor.ts

@@ -0,0 +1,272 @@
+/**
+ * defineReactor - One-call bootstrap for a canister reactor + its React hooks.
+ *
+ * Collapses the four manual steps (QueryClient → ClientManager → Reactor →
+ * createActorHooks) into a single call, and turns the Reactor / DisplayReactor
+ * choice into a `display` flag.
+ * Use this when one-call bootstrap is enough. If you need reusable
+ * method-specific operations outside React, compose with query/mutation
+ * factories after setup.
+ *
+ * @example
+ * ```typescript
+ * import { defineReactor } from "@ic-reactor/react"
+ * import { idlFactory, type _SERVICE } from "./declarations/backend"
+ *
+ * const { reactor, useActorQuery, useActorMutation } = defineReactor<_SERVICE>({
+ *   name: "backend",
+ *   idlFactory,
+ *   canisterId: "rrkah-fqaaa-aaaaa-aaaaq-cai",
+ *   display: true, // ⇒ DisplayReactor (string principals/bigints)
+ * })
+ *
+ * function Profile() {
+ *   const { data } = useActorQuery({ functionName: "get_profile" })
+ *   return <div>{data?.name}</div>
+ * }
+ * ```
+ *
+ * @example Reuse an existing ClientManager (multiple canisters share one agent)
+ * ```typescript
+ * const ledger = defineReactor<_LEDGER>({ name: "ledger", idlFactory: ledgerIdl })
+ * const index = defineReactor<_INDEX>({
+ *   name: "index",
+ *   idlFactory: indexIdl,
+ *   clientManager: ledger.clientManager,
+ *   authentication: ledger.authentication, // one Internet Identity session
+ * })
+ * ```
+ *
+ * @example Internet Identity is wired up out of the box
+ * ```typescript
+ * const { useAuth, useIdentityAttributes } = defineReactor<_SERVICE>({
+ *   name: "backend",
+ *   idlFactory,
+ *   // Needed when the app is served from more than one origin.
+ *   auth: { derivationOrigin: "https://app.example.com" },
+ * })
+ *
+ * function LoginButton() {
+ *   const { login, logout, isAuthenticated, principal } = useAuth()
+ *   return isAuthenticated
+ *     ? <button onClick={() => logout()}>{principal?.toText()}</button>
+ *     : <button onClick={() => login()}>Sign in</button>
+ * }
+ * ```
+ */
+import { ClientManager, Reactor, DisplayReactor } from "@ic-reactor/core"
+import type {
+  BaseActor,
+  TransformKey,
+  ReactorParameters,
+  ClientManagerParameters,
+  DisplayReactorParameters,
+} from "@ic-reactor/core"
+import { QueryClient } from "@tanstack/react-query"
+import { createActorHooks, ActorHooks } from "./createActorHooks.js"
+import { AuthenticationManager } from "./auth/authentication-manager.js"
+import { IdentityAttributesManager } from "./auth/identity-attributes-manager.js"
+import { createIdentityAttributeHooks } from "./auth/createIdentityAttributeHooks.js"
+import type { UseIdentityAttributesReturn } from "./auth/createIdentityAttributeHooks.js"
+import { createAuthHooks } from "./hooks/createAuthHooks.js"
+import type { CreateAuthHooksReturn } from "./hooks/createAuthHooks.js"
+import type { AuthenticationManagerParameters } from "./auth/authentication-manager.js"
+
+/** Options shared by both the standard and display variants of defineReactor. */
+export interface DefineReactorSharedParameters
+  extends
+    Omit<ReactorParameters, "clientManager">,
+    Omit<ClientManagerParameters, "queryClient"> {
+  /**
+   * Reuse an existing ClientManager (e.g. to share one agent across canisters).
+   * When omitted, a ClientManager is created from the agent options below.
+   *
+   * A supplied or adopted manager brings its own agent and QueryClient, so
+   * `agentOptions` and `queryClient` apply only when this call creates one.
+   */
+  clientManager?: ClientManager
+  /**
+   * QueryClient for a ClientManager created by this call.
+   *
+   * Ignored when `clientManager` or `authentication` is supplied — queries run
+   * against that manager's own QueryClient, which is what is returned.
+   */
+  queryClient?: QueryClient
+  /**
+   * Reuse an existing AuthenticationManager, so several reactors share one
+   * Internet Identity session. When omitted, one is created for this reactor.
+   *
+   * Its `clientManager` is adopted for this reactor, so sign-in updates the
+   * same agent the reactor calls through. Supplying a different `clientManager`
+   * alongside it is rejected.
+   */
+  authentication?: AuthenticationManager
+  /**
+   * Internet Identity options forwarded to the AuthenticationManager
+   * (`identityProvider`, `derivationOrigin`, `idleOptions`, `storage`, …).
+   *
+   * Mutually exclusive with `authentication`: a manager built elsewhere is
+   * already configured, so these could not be applied to it.
+   */
+  auth?: Omit<AuthenticationManagerParameters, "clientManager">
+}
+
+/** Parameters for a standard (raw Candid types) reactor. */
+export interface DefineReactorParameters extends DefineReactorSharedParameters {
+  display?: false
+}
+
+/** Parameters for a DisplayReactor (UI-friendly string principals/bigints). */
+export interface DefineDisplayReactorParameters<
+  Service,
+> extends DefineReactorSharedParameters {
+  display: true
+  /** Optional initial argument validators (receive display types). */
+  validators?: DisplayReactorParameters<Service>["validators"]
+}
+
+/** The reactor instance plus its bound hooks and shared infrastructure. */
+export type DefineReactorResult<
+  Service,
+  Transform extends TransformKey,
+  R extends Reactor<Service, Transform>,
+> = ActorHooks<Service, Transform> &
+  CreateAuthHooksReturn & {
+    reactor: R
+    clientManager: ClientManager
+    queryClient: QueryClient
+    /** Internet Identity session manager backing `useAuth`. */
+    authentication: AuthenticationManager
+    /** Signed identity attribute requests backing `useIdentityAttributes`. */
+    identityAttributes: IdentityAttributesManager
+    useIdentityAttributes: () => UseIdentityAttributesReturn
+  }
+
+export function defineReactor<Service = BaseActor>(
+  params: DefineDisplayReactorParameters<Service>
+): DefineReactorResult<Service, "display", DisplayReactor<Service>>
+
+export function defineReactor<Service = BaseActor>(
+  params: DefineReactorParameters
+): DefineReactorResult<Service, "candid", Reactor<Service, "candid">>
+
+export function defineReactor<Service = BaseActor>(
+  params: DefineReactorParameters | DefineDisplayReactorParameters<Service>
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): DefineReactorResult<Service, any, any> {
+  const {
+    clientManager: providedClientManager,
+    queryClient: providedQueryClient,
+    authentication: providedAuthentication,
+    auth,
+    display,
+    agentOptions,
+    name,
+    idlFactory,
+    canisterId,
+    pollingOptions,
+  } = params as DefineDisplayReactorParameters<Service>
+
+  // A shared AuthenticationManager updates the identity on its own
+  // ClientManager. Giving this reactor a different one would leave its calls
+  // anonymous after sign-in, so adopt the manager's rather than building a new
+  // one, and refuse an explicit mismatch instead of splitting them silently.
+  if (
+    providedClientManager &&
+    providedAuthentication &&
+    providedAuthentication.clientManager !== providedClientManager
+  ) {
+    throw new Error(
+      `[ic-reactor] defineReactor("${name}") received an \`authentication\` manager bound to a different \`clientManager\`. ` +
+        `Sign-in would update the authentication manager's agent while this reactor calls through another one, ` +
+        `leaving its calls anonymous. Pass \`clientManager: authentication.clientManager\`, or omit \`clientManager\` to adopt it.`
+    )
+  }
+
+  // `auth` configures a manager this call would build; an existing one is
+  // already constructed, so these options could only be dropped on the floor.
+  if (providedAuthentication && auth) {
+    throw new Error(
+      `[ic-reactor] defineReactor("${name}") received both \`authentication\` and \`auth\`. ` +
+        `The supplied manager is already configured, so \`auth\` (${Object.keys(auth).join(", ")}) would be ignored. ` +
+        `Pass those options where that AuthenticationManager is created, or drop \`authentication\` to build one here.`
+    )
+  }
+
+  const clientManager =
+    providedClientManager ??
+    providedAuthentication?.clientManager ??
+    new ClientManager({
+      queryClient: providedQueryClient ?? new QueryClient(),
+      agentOptions,
+    })
+
+  // Always report the QueryClient actually in use: when a ClientManager is
+  // supplied or adopted, its own QueryClient is the one queries run against.
+  const queryClient = clientManager.queryClient
+
+  const reactorConfig = {
+    clientManager,
+    name,
+    idlFactory,
+    canisterId,
+    pollingOptions,
+  }
+
+  // The Reactor / DisplayReactor union cannot be expressed through the shared
+  // implementation signature, so the body is intentionally untyped here; the
+  // public overloads above carry the precise types for callers.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const reactor: any = display
+    ? new DisplayReactor<Service>({
+        ...reactorConfig,
+        validators: (params as DefineDisplayReactorParameters<Service>)
+          .validators,
+      })
+    : new Reactor<Service>(reactorConfig)
+
+  const hooks = createActorHooks(reactor)
+
+  // Auth is built on first use. `AuthenticationManager` dynamically imports the
+  // optional `@icp-sdk/auth` peer as soon as it is constructed, and reactors
+  // that never touch authentication should not pay for that.
+  let authenticationInstance: AuthenticationManager | undefined
+  const getAuthentication = () =>
+    (authenticationInstance ??=
+      providedAuthentication ??
+      new AuthenticationManager({ ...auth, clientManager }))
+
+  let identityAttributesInstance: IdentityAttributesManager | undefined
+  const getIdentityAttributes = () =>
+    (identityAttributesInstance ??= new IdentityAttributesManager(
+      getAuthentication()
+    ))
+
+  let authHooks: CreateAuthHooksReturn | undefined
+  const getAuthHooks = () =>
+    (authHooks ??= createAuthHooks(getAuthentication()))
+
+  let attributeHooks:
+    ReturnType<typeof createIdentityAttributeHooks> | undefined
+  const getAttributeHooks = () =>
+    (attributeHooks ??= createIdentityAttributeHooks(getIdentityAttributes()))
+
+  return {
+    ...hooks,
+    reactor,
+    clientManager,
+    queryClient,
+    // Stable wrappers: the hook call order inside them never changes, so the
+    // rules of hooks still hold.
+    useAuth: () => getAuthHooks().useAuth(),
+    useAgentState: () => getAuthHooks().useAgentState(),
+    useUserPrincipal: () => getAuthHooks().useUserPrincipal(),
+    useIdentityAttributes: () => getAttributeHooks().useIdentityAttributes(),
+    get authentication() {
+      return getAuthentication()
+    },
+    get identityAttributes() {
+      return getIdentityAttributes()
+    },
+  }
+}

package/src/{createAuthHooks.ts → hooks/createAuthHooks.ts}

@@ -1,26 +1,13 @@
-import {
-  useSyncExternalStore,
-  useEffect,
-  useRef,
-  useMemo,
-  useState,
-  useCallback,
-} from "react"
-import {
-  ClientManager,
-  AgentState,
-  AuthState,
-  ClientManagerSignInOptions,
-  IdentityAttributeResult,
-  RequestIdentityAttributesParameters,
-  RequestOpenIdIdentityAttributesParameters,
-} from "@ic-reactor/core"
+import { useSyncExternalStore, useEffect, useRef, useMemo } from "react"
+import type { AuthenticationManager } from "../auth/authentication-manager.js"
+import type { AuthState, AuthenticationSignInOptions } from "../auth/types.js"
+import type { AgentState } from "@ic-reactor/core"
 import type { Principal } from "@icp-sdk/core/principal"
 import type { Identity } from "@icp-sdk/core/agent"
 
 export interface UseAuthReturn {
   authenticate: () => Promise<Identity | undefined>
-  login: (options?: ClientManagerSignInOptions) => Promise<void>
+  login: (options?: AuthenticationSignInOptions) => Promise<void>
   logout: (options?: { returnTo?: string }) => Promise<void>
   isAuthenticated: boolean
   isAuthenticating: boolean
@@ -33,27 +20,13 @@ export interface CreateAuthHooksReturn {
   useAgentState: () => AgentState
   useUserPrincipal: () => Principal | null
   useAuth: () => UseAuthReturn
-  useIdentityAttributes: () => UseIdentityAttributesReturn
-}
-
-export interface UseIdentityAttributesReturn {
-  requestAttributes: (
-    params: RequestIdentityAttributesParameters
-  ) => Promise<IdentityAttributeResult>
-  requestOpenIdAttributes: (
-    params: RequestOpenIdIdentityAttributesParameters
-  ) => Promise<IdentityAttributeResult>
-  attributes: IdentityAttributeResult | null
-  isRequestingAttributes: boolean
-  attributeError: Error | null
-  clearAttributes: () => void
 }
 
 /**
  * Create authentication hooks for managing user sessions with Internet Identity.
  *
  * @example
- * const { useAuth, useUserPrincipal, useAgentState } = createAuthHooks(clientManager)
+ * const { useAuth, useUserPrincipal, useAgentState } = createAuthHooks(authentication)
  *
  * function App() {
  *   const { login, logout, principal, isAuthenticated } = useAuth()
@@ -64,8 +37,9 @@ export interface UseIdentityAttributesReturn {
  * }
  */
 export const createAuthHooks = (
-  clientManager: ClientManager
+  authentication: AuthenticationManager
 ): CreateAuthHooksReturn => {
+  const { clientManager } = authentication
   /**
    * Subscribe to agent state changes.
    * Returns the current agent state (agent, isInitialized, etc.)
@@ -84,10 +58,10 @@ export const createAuthHooks = (
    */
   const useAuthState = (): AuthState =>
     useSyncExternalStore(
-      (callback) => clientManager.subscribeAuthState(callback),
-      () => clientManager.authState,
+      (callback) => authentication.subscribeAuthState(callback),
+      () => authentication.authState,
       // Server snapshot - provide initial state for SSR
-      () => clientManager.authState
+      () => authentication.authState
     )
 
   /**
@@ -109,18 +83,27 @@ export const createAuthHooks = (
    * }
    */
   const useAuth = (): UseAuthReturn => {
-    const { login, logout, authenticate } = clientManager
+    const { login, logout, authenticate } = authentication
     const { isAuthenticated, isAuthenticating, identity, error } =
       useAuthState()
 
     // Track if we've already initialized to avoid duplicate calls
     const initializedRef = useRef(false)
 
-    // Auto-initialize on first mount to restore previous session
+    // Auto-initialize on first mount to restore previous session.
+    // `prepareClient` also warms up the AuthClient so a later `login()` can
+    // open the identity provider window inside the click handler.
     useEffect(() => {
       if (!initializedRef.current) {
         initializedRef.current = true
-        clientManager.initialize()
+        authentication
+          .prepareClient()
+          .catch(() => undefined)
+          .then(() => clientManager.initialize())
+          .then(() => authentication.authenticate())
+          // Failures are already reflected in authState/agentState; without
+          // this the rejection escapes as an unhandled promise rejection.
+          .catch(() => undefined)
       }
     }, [])
 
@@ -157,68 +140,9 @@ export const createAuthHooks = (
     return identity ? identity.getPrincipal() : null
   }
 
-  const useIdentityAttributes = (): UseIdentityAttributesReturn => {
-    const [attributes, setAttributes] =
-      useState<IdentityAttributeResult | null>(null)
-    const [isRequestingAttributes, setIsRequestingAttributes] = useState(false)
-    const [attributeError, setAttributeError] = useState<Error | null>(null)
-
-    const requestAttributes = useCallback(
-      async (params: RequestIdentityAttributesParameters) => {
-        setIsRequestingAttributes(true)
-        setAttributeError(null)
-        try {
-          const result = await clientManager.requestIdentityAttributes(params)
-          setAttributes(result)
-          return result
-        } catch (error) {
-          setAttributeError(error as Error)
-          throw error
-        } finally {
-          setIsRequestingAttributes(false)
-        }
-      },
-      []
-    )
-
-    const requestOpenIdAttributes = useCallback(
-      async (params: RequestOpenIdIdentityAttributesParameters) => {
-        setIsRequestingAttributes(true)
-        setAttributeError(null)
-        try {
-          const result =
-            await clientManager.requestOpenIdIdentityAttributes(params)
-          setAttributes(result)
-          return result
-        } catch (error) {
-          setAttributeError(error as Error)
-          throw error
-        } finally {
-          setIsRequestingAttributes(false)
-        }
-      },
-      []
-    )
-
-    const clearAttributes = useCallback(() => {
-      setAttributes(null)
-      setAttributeError(null)
-    }, [])
-
-    return {
-      requestAttributes,
-      requestOpenIdAttributes,
-      attributes,
-      isRequestingAttributes,
-      attributeError,
-      clearAttributes,
-    }
-  }
-
   return {
     useAuth,
     useAgentState,
     useUserPrincipal,
-    useIdentityAttributes,
   }
 }

package/src/hooks/index.ts

@@ -24,6 +24,10 @@ export {
   createActorMethodHooks,
 } from "./useActorMethod.js"
 
+// createAuthHooks
+export { createAuthHooks } from "./createAuthHooks.js"
+export type { CreateAuthHooksReturn, UseAuthReturn } from "./createAuthHooks.js"
+
 // ============================================================================
 // Types - UseReactor* (with reactor parameter)
 // ============================================================================