@ic-reactor/react 3.7.0 → 3.9.0

package/src/auth/index.ts

@@ -1,7 +1,7 @@
-export * from "./authentication-manager"
-export * from "./identity-attributes-manager"
-export * from "./identity-attributes"
-export * from "./constants"
-export * from "./types"
-export * from "../hooks/createAuthHooks"
-export * from "./createIdentityAttributeHooks"
+export * from "./authentication-manager.js"
+export * from "./identity-attributes-manager.js"
+export * from "./identity-attributes.js"
+export * from "./constants.js"
+export * from "./types.js"
+export * from "../hooks/createAuthHooks.js"
+export * from "./createIdentityAttributeHooks.js"

package/src/auth/types.ts

@@ -1,4 +1,5 @@
-import type { Identity } from "@icp-sdk/core/agent"
+import type { Identity, SignIdentity } from "@icp-sdk/core/agent"
+import type { PartialIdentity } from "@icp-sdk/core/identity"
 import type { Principal } from "@icp-sdk/core/principal"
 
 export interface SignedIdentityAttributes {
@@ -6,9 +7,21 @@ export interface SignedIdentityAttributes {
   signature: Uint8Array
 }
 
+/**
+ * The 32-byte nonce issued by the relying-party canister.
+ *
+ * A function (or promise) lets the Internet Identity window open while the
+ * nonce is still being fetched, so the popup is opened inside the user gesture
+ * instead of after it. `@icp-sdk/auth` v8 requires the function form; v7
+ * accepts the promise form. IC Reactor normalizes whichever you pass to the
+ * shape the installed client expects.
+ */
+export type IdentityAttributeNonce =
+  Uint8Array | Promise<Uint8Array> | (() => Uint8Array | Promise<Uint8Array>)
+
 export interface IdentityAttributeRequest {
   keys: string[]
-  nonce: Uint8Array
+  nonce: IdentityAttributeNonce
 }
 
 export interface IdentityAttributeValues {
@@ -26,15 +39,102 @@ export interface IdentityAttributeResult {
   completedAt: string
 }
 
+/**
+ * The providers that Internet Identity supports for one-click sign-in. Only
+ * these three reach the underlying auth client.
+ */
 type IdentityAttributeOpenIdProviderAlias = "google" | "apple" | "microsoft"
 
+/**
+ * An OpenID provider, either as a well-known alias or as a raw issuer URL.
+ *
+ * The two forms are **not** interchangeable, and what each one does depends on
+ * where it is passed:
+ *
+ * - An alias (`"google" | "apple" | "microsoft"`) is forwarded to the auth
+ *   client, which adds an `openid` search param to the identity provider URL so
+ *   the user signs in through that provider directly.
+ * - Any other string is treated as a raw issuer URL and is **never** forwarded
+ *   to the auth client, so it never affects how the user signs in. It is only
+ *   meaningful when passed to {@link IdentityAttributesManager.requestOpenId}
+ *   (or `identityAttributeKeys`), which scopes the requested keys to
+ *   `openid:<issuer>:<key>`. Passed anywhere else it has no effect at all.
+ */
 export type IdentityAttributeOpenIdProvider =
   IdentityAttributeOpenIdProviderAlias | (string & {})
 
+/** Session key algorithm used for each sign-in. */
+export type AuthClientKeyType = "ECDSA" | "Ed25519"
+
+/** Structural shape of an `@icp-sdk/auth` `AuthClientStorage`. */
+export interface AuthClientStorageLike {
+  get(key: string): Promise<string | CryptoKeyPair | null>
+  set(key: string, value: string | CryptoKeyPair): Promise<void>
+  remove(key: string): Promise<void>
+}
+
+/** Idle-session configuration forwarded to the underlying AuthClient. */
+export interface AuthClientIdleOptions {
+  /** Called once the user has been idle for `idleTimeout` ms. */
+  onIdle?: () => unknown
+  /** Idle timeout in ms. @default 600_000 (10 minutes) */
+  idleTimeout?: number
+  /** Treat scroll events as activity. @default false */
+  captureScroll?: boolean
+  /** Scroll debounce in ms. @default 100 */
+  scrollDebounce?: number
+  /** Disable idle detection entirely. @default false */
+  disableIdle?: boolean
+  /**
+   * Disable the built-in idle callback, which signs the user out and reloads
+   * the page. @default false
+   */
+  disableDefaultIdleCallback?: boolean
+}
+
 export interface AuthenticationClientOptions {
+  /** Identity provider URL. @default "https://id.ai/authorize" */
   identityProvider?: string | URL
+  /** `window.open` features string for the identity provider popup. */
   windowOpenerFeatures?: string
+  /**
+   * Provider for one-click sign-in.
+   *
+   * Only the `"google" | "apple" | "microsoft"` aliases reach the auth client.
+   * Any other value is dropped here and has **no effect** — raw issuer URLs are
+   * only meaningful on `requestOpenId`, where they scope the requested keys.
+   * @see {@link IdentityAttributeOpenIdProvider}
+   */
   openIdProvider?: IdentityAttributeOpenIdProvider
+  /**
+   * Derivation origin for the identity provider.
+   *
+   * Required when the app is served from more than one origin (e.g. a custom
+   * domain plus `<canisterId>.icp0.io`) and every origin must resolve to the
+   * same principal.
+   * @see https://github.com/dfinity/internet-identity/blob/main/docs/internet-identity-spec.adoc
+   */
+  derivationOrigin?: string | URL
+  /** Persistent storage backend. @default IndexedDB */
+  storage?: AuthClientStorageLike
+  /**
+   * Session key algorithm. Use `"Ed25519"` when the storage backend cannot
+   * hold a `CryptoKey`. @default "ECDSA"
+   */
+  keyType?: AuthClientKeyType
+  /**
+   * Idle timeout configuration. Pass `{ disableIdle: true }` to opt out of the
+   * default behaviour, which signs the user out and reloads after 10 minutes.
+   */
+  idleOptions?: AuthClientIdleOptions
+  /** An existing identity to authenticate via delegation. */
+  identity?: SignIdentity | PartialIdentity
+  /**
+   * How the client talks to the identity provider. `"redirect"` requires
+   * `@icp-sdk/auth` v8 or later and is ignored by older versions.
+   * @default "window"
+   */
+  transport?: "window" | "redirect"
 }
 
 export interface AuthClientSignInOptions {
@@ -48,36 +148,52 @@ export interface AuthenticationSignInOptions
   onError?: (error?: string) => void | Promise<void>
 }
 
-export interface RequestIdentityAttributesParameters {
+export interface RequestIdentityAttributesParameters extends AuthenticationClientOptions {
   keys: string[]
-  nonce: Uint8Array
-  identityProvider?: string | URL
-  openIdProvider?: IdentityAttributeOpenIdProvider
-  windowOpenerFeatures?: string
+  nonce: IdentityAttributeNonce
+  /**
+   * Sign in as part of the same identity-provider interaction.
+   * @default true
+   */
   signIn?: boolean
   maxTimeToLive?: bigint
   targets?: Principal[]
 }
 
-export interface RequestOpenIdIdentityAttributesParameters {
-  nonce: Uint8Array
+export interface RequestOpenIdIdentityAttributesParameters extends Omit<
+  RequestIdentityAttributesParameters,
+  "openIdProvider"
+> {
+  /**
+   * Provider the requested `keys` are scoped to, producing
+   * `openid:<issuer>:<key>`.
+   *
+   * Passing one of the `"google" | "apple" | "microsoft"` aliases additionally
+   * routes sign-in through that provider, so the user grants attribute access
+   * in the same step. A raw issuer URL only scopes the keys.
+   * @see {@link IdentityAttributeOpenIdProvider}
+   */
   openIdProvider: IdentityAttributeOpenIdProvider
-  keys: string[]
-  identityProvider?: string | URL
-  windowOpenerFeatures?: string
-  signIn?: boolean
-  maxTimeToLive?: bigint
-  targets?: Principal[]
 }
 
+/**
+ * Structural subset of `@icp-sdk/auth`'s `AuthClient` that IC Reactor relies
+ * on. Declared locally so `@icp-sdk/auth` stays an optional peer dependency.
+ */
 export interface AuthClientLike {
   getIdentity(): Promise<Identity> | Identity
   isAuthenticated(): Promise<boolean> | boolean
   signIn(options?: AuthClientSignInOptions): Promise<Identity>
   signOut(options?: { returnTo?: string }): Promise<void>
-  requestAttributes(
-    params: IdentityAttributeRequest
-  ): Promise<SignedIdentityAttributes>
+  requestAttributes(params: {
+    keys: string[]
+    // Widened across `@icp-sdk/auth` v7 (value or promise) and v8 (thunk).
+    // Method-shorthand parameters are bivariant, so both real signatures are
+    // assignable to this one.
+    nonce: Uint8Array | Promise<Uint8Array> | (() => Promise<Uint8Array>)
+  }): Promise<SignedIdentityAttributes>
+  /** Present from `@icp-sdk/auth` v8; used to detect the nonce contract. */
+  memoize?<T>(produce: () => T | Promise<T>): Promise<T>
 }
 
 export interface AuthState {

package/src/createActorHooks.ts

@@ -34,18 +34,18 @@ import {
   UseMutationResult,
   InfiniteData,
 } from "@tanstack/react-query"
-import { useActorQuery } from "./hooks/useActorQuery"
-import { useActorSuspenseQuery } from "./hooks/useActorSuspenseQuery"
-import { useActorInfiniteQuery } from "./hooks/useActorInfiniteQuery"
-import { useActorSuspenseInfiniteQuery } from "./hooks/useActorSuspenseInfiniteQuery"
-import { useActorMutation } from "./hooks/useActorMutation"
+import { useActorQuery } from "./hooks/useActorQuery.js"
+import { useActorSuspenseQuery } from "./hooks/useActorSuspenseQuery.js"
+import { useActorInfiniteQuery } from "./hooks/useActorInfiniteQuery.js"
+import { useActorSuspenseInfiniteQuery } from "./hooks/useActorSuspenseInfiniteQuery.js"
+import { useActorMutation } from "./hooks/useActorMutation.js"
 import {
   useActorMethod,
   UseActorMethodParameters,
-} from "./hooks/useActorMethod"
-import { InfiniteQueryConfig } from "./createInfiniteQuery"
-import { SuspenseInfiniteQueryConfig } from "./createSuspenseInfiniteQuery"
-import { QueryConfig, SuspenseQueryConfig, MutationConfig } from "./types"
+} from "./hooks/useActorMethod.js"
+import { InfiniteQueryConfig } from "./createInfiniteQuery.js"
+import { SuspenseInfiniteQueryConfig } from "./createSuspenseInfiniteQuery.js"
+import { QueryConfig, SuspenseQueryConfig, MutationConfig } from "./types.js"
 
 export type ActorHooks<Service, Transform extends TransformKey> = {
   useActorQuery: {

package/src/createInfiniteQuery.ts

@@ -22,6 +22,7 @@
  * postsQuery.invalidate()
  */
 
+import { useMemo } from "react"
 import type {
   Reactor,
   FunctionName,
@@ -43,8 +44,12 @@ import {
   InfiniteQueryObserverOptions,
 } from "@tanstack/react-query"
 import { CallConfig } from "@icp-sdk/core/agent"
-import { NoInfer } from "./types"
-import { mergeFactoryQueryKey, normalizeQueryData } from "./utils"
+import { NoInfer } from "./types.js"
+import {
+  buildChainedSelect,
+  mergeFactoryQueryKey,
+  normalizeQueryData,
+} from "./utils.js"
 
 type InfiniteQueryFactoryFn<
   Service,
@@ -126,6 +131,16 @@ export interface InfiniteQueryConfig<
   initialPageParam: TPageParam
   /** Function to get args from page parameter */
   getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>
+  /**
+   * Narrows what the cache key derives from the call arguments.
+   *
+   * By default the key is scoped by `getArgs(initialPageParam)`, so two
+   * infinite queries on the same method with different arguments stay in
+   * separate cache entries. Supply this when those args embed the cursor and
+   * only part of them identifies the query — return the stable, serializable
+   * portion (typically everything except the pagination field).
+   */
+  getKeyArgs?: (args: ReactorArgs<Service, Method, Transform>) => unknown
   /** Function to determine next page parameter */
   getNextPageParam: (
     lastPage: InfiniteQueryPageData<Service, Method, Transform>,
@@ -155,17 +170,12 @@ export type InfiniteQueryFactoryConfig<
     TPageParam
   >,
 > = Omit<
+  // `getArgs` is supplied per factory call. `getKeyArgs` is inherited from
+  // InfiniteQueryConfig, which now applies it for every infinite query rather
+  // than only for factory-created ones.
   InfiniteQueryConfig<Service, Method, Transform, TPageParam, Selected>,
   "getArgs"
-> & {
-  /**
-   * Optional key-args derivation for factory calls.
-   * Receives the resolved args from `getArgs(initialPageParam)` and should return
-   * a stable serializable representation of the logical query identity
-   * (typically excluding pagination/cursor fields).
-   */
-  getKeyArgs?: (args: ReactorArgs<Service, Method, Transform>) => unknown
-}
+>
 
 // ============================================================================
 // Hook Interface
@@ -292,6 +302,7 @@ const createInfiniteQueryImpl = <
     queryKey: customQueryKey,
     initialPageParam,
     getArgs,
+    getKeyArgs,
     getNextPageParam,
     getPreviousPageParam,
     maxPages,
@@ -300,12 +311,22 @@ const createInfiniteQueryImpl = <
     ...rest
   } = config
 
-  // Get query key from actor manager
+  // Fold the call arguments into the key. Without them every infinite query on
+  // a method shares one cache entry, so two lists with different `getArgs` (a
+  // different page size, a different filter) serve each other's pages — the
+  // arguments live in a closure, not in the config, so nothing else
+  // distinguishes them.
+  //
+  // The first page's args stand for the query's identity; `getKeyArgs` lets a
+  // caller drop the cursor field when it is part of those args.
   const getQueryKey = (): QueryKey => {
+    const initialArgs = getArgs(initialPageParam)
+    const keyArgs = getKeyArgs?.(initialArgs) ?? initialArgs
+
     return reactor.generateQueryKey(
       {
         functionName,
-        queryKey: customQueryKey,
+        queryKey: mergeFactoryQueryKey(customQueryKey, undefined, keyArgs),
       },
       callConfig
     )
@@ -368,14 +389,12 @@ const createInfiniteQueryImpl = <
     Selected,
     TError
   > = (options: any): any => {
-    // Chain the selects: raw -> config.select -> options.select
-    const chainedSelect = (rawData: TInfiniteData) => {
-      const firstPass = select ? select(rawData) : rawData
-      if (options?.select) {
-        return options.select(firstPass)
-      }
-      return firstPass
-    }
+    // Memoized and identity-preserving; see buildChainedSelect for why the
+    // function identity matters to the observer's select-result cache.
+    const chainedSelect = useMemo(
+      () => buildChainedSelect(select as never, options?.select),
+      [options?.select]
+    )
 
     return useInfiniteQuery(
       {
@@ -535,10 +554,8 @@ export function createInfiniteQueryFactory<
   > = (
     getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>
   ) => {
-    const initialArgs = getArgs(config.initialPageParam)
-    const keyArgs = config.getKeyArgs?.(initialArgs) ?? initialArgs
-    const queryKey = mergeFactoryQueryKey(config.queryKey, undefined, keyArgs)
-
+    // `getKeyArgs` and the args-derived key segment are applied by the impl,
+    // which now does it for every infinite query rather than only for factories.
     return createInfiniteQueryImpl<
       Service,
       Method,
@@ -546,16 +563,13 @@ export function createInfiniteQueryFactory<
       TPageParam,
       Selected
     >(reactor, {
-      ...(({ getKeyArgs: _getKeyArgs, ...rest }) => rest)(
-        config as InfiniteQueryFactoryConfig<
-          Service,
-          Method,
-          Transform,
-          TPageParam,
-          Selected
-        >
-      ),
-      queryKey,
+      ...(config as InfiniteQueryFactoryConfig<
+        Service,
+        Method,
+        Transform,
+        TPageParam,
+        Selected
+      >),
       getArgs,
     })
   }

package/src/createMutation.ts

@@ -39,7 +39,7 @@ import type {
   MutationResult,
   MutationHookOptions,
   NoInfer,
-} from "./types"
+} from "./types.js"
 
 // ============================================================================
 // Internal helpers
@@ -91,16 +91,46 @@ const createMutationImpl = <
 
   /**
    * Imperative execution for non-React usage.
-   * Calls the canister method and invalidates factory-level queries.
+   *
+   * Runs the same factory-level chain the hook does — invalidation, then
+   * `onSuccess`, or `onCanisterError`/`onError` on failure — so a mutation
+   * object behaves the same through both call paths. Only hook-level callbacks
+   * are absent, because there is no hook here to supply them.
+   *
+   * The error is rethrown after the callbacks run, so `await execute(...)`
+   * still rejects for the caller.
+   *
    * Use this in route loaders, scripts, or server-side code.
    */
   const execute = async (
     args: ReactorArgs<Service, Method, Transform>
   ): Promise<ReactorReturnOk<Service, Method, Transform>> => {
-    const result = await callFn(args)
+    let result: ReactorReturnOk<Service, Method, Transform>
+    try {
+      result = await callFn(args)
+    } catch (error) {
+      if (isCanisterError(error)) {
+        factoryOnCanisterError?.(error, args)
+      }
+      // No mutation context or instance exists on the imperative path.
+      factoryOnError?.(
+        error as Parameters<NonNullable<typeof factoryOnError>>[0],
+        args,
+        undefined as never,
+        undefined as never
+      )
+      throw error
+    }
+
     if (factoryInvalidateQueries) {
       await invalidateAll(reactor.queryClient, factoryInvalidateQueries)
     }
+    await factoryOnSuccess?.(
+      result,
+      args,
+      undefined as never,
+      undefined as never
+    )
     return result
   }
 

package/src/createQuery.ts

@@ -30,6 +30,7 @@ import type {
   ReactorArgs,
   TransformKey,
 } from "@ic-reactor/core"
+import { useMemo } from "react"
 import {
   QueryKey,
   useQuery,
@@ -44,8 +45,8 @@ import type {
   QueryResult,
   QueryFactoryConfig,
   NoInfer,
-} from "./types"
-import { buildChainedSelect } from "./utils"
+} from "./types.js"
+import { buildChainedSelect } from "./utils.js"
 
 // ============================================================================
 // Internal Implementation
@@ -110,6 +111,12 @@ const createQueryImpl = <
 
   const useQueryHook = ((options?: UseQueryHookOptions) => {
     const baseOptions = reactor.getQueryOptions(params)
+    // Memoized so the observer's select-result cache can hit; see
+    // buildChainedSelect. `select` comes from the factory config and is stable.
+    const chainedSelect = useMemo(
+      () => buildChainedSelect(select, options?.select),
+      [options?.select]
+    )
     return useQuery(
       {
         queryKey: baseOptions.queryKey,
@@ -117,7 +124,7 @@ const createQueryImpl = <
         ...rest,
         ...options,
         queryFn: baseOptions.queryFn,
-        select: buildChainedSelect(select, options?.select),
+        select: chainedSelect,
       },
       reactor.queryClient
     )

package/src/createSuspenseInfiniteQuery.ts

@@ -24,6 +24,7 @@
  * const allPosts = data.pages.flatMap(page => page.posts)
  */
 
+import { useMemo } from "react"
 import type {
   Reactor,
   FunctionName,
@@ -45,8 +46,12 @@ import {
   InfiniteQueryObserverOptions,
 } from "@tanstack/react-query"
 import { CallConfig } from "@icp-sdk/core/agent"
-import { NoInfer } from "./types"
-import { mergeFactoryQueryKey, normalizeQueryData } from "./utils"
+import { NoInfer } from "./types.js"
+import {
+  buildChainedSelect,
+  mergeFactoryQueryKey,
+  normalizeQueryData,
+} from "./utils.js"
 
 type SuspenseInfiniteFactoryCallOptions = {
   queryKey?: QueryKey
@@ -137,6 +142,15 @@ export interface SuspenseInfiniteQueryConfig<
   queryKey?: QueryKey
   /** Function to get args from page parameter */
   getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>
+  /**
+   * Narrows what the cache key derives from the call arguments.
+   *
+   * By default the key is scoped by `getArgs(initialPageParam)`, so two
+   * infinite queries on the same method with different arguments stay in
+   * separate cache entries. Supply this when those args embed the cursor and
+   * only part of them identifies the query.
+   */
+  getKeyArgs?: (args: ReactorArgs<Service, Method, Transform>) => unknown
 }
 
 /**
@@ -152,17 +166,11 @@ export type SuspenseInfiniteQueryFactoryConfig<
     TPageParam
   >,
 > = Omit<
+  // `getArgs` is supplied per factory call. `getKeyArgs` is inherited from
+  // SuspenseInfiniteQueryConfig, which now applies it for every infinite query.
   SuspenseInfiniteQueryConfig<Service, Method, Transform, TPageParam, Selected>,
   "getArgs"
-> & {
-  /**
-   * Optional key-args derivation for factory calls.
-   * Receives the resolved args from `getArgs(initialPageParam)` and should return
-   * a stable serializable representation of the logical query identity
-   * (typically excluding pagination/cursor fields).
-   */
-  getKeyArgs?: (args: ReactorArgs<Service, Method, Transform>) => unknown
-}
+>
 
 // ============================================================================
 // Hook Interface
@@ -301,6 +309,7 @@ const createSuspenseInfiniteQueryImpl = <
     queryKey: customQueryKey,
     initialPageParam,
     getArgs,
+    getKeyArgs,
     getNextPageParam,
     getPreviousPageParam,
     maxPages,
@@ -309,12 +318,18 @@ const createSuspenseInfiniteQueryImpl = <
     ...rest
   } = config
 
-  // Get query key from actor manager
+  // Fold the call arguments into the key — see the matching comment in
+  // createInfiniteQuery. Without them every infinite query on a method shares
+  // one cache entry, because the arguments live in a `getArgs` closure rather
+  // than in the config.
   const getQueryKey = (): QueryKey => {
+    const initialArgs = getArgs(initialPageParam)
+    const keyArgs = getKeyArgs?.(initialArgs) ?? initialArgs
+
     return reactor.generateQueryKey(
       {
         functionName,
-        queryKey: customQueryKey,
+        queryKey: mergeFactoryQueryKey(customQueryKey, undefined, keyArgs),
       },
       callConfig
     )
@@ -370,14 +385,12 @@ const createSuspenseInfiniteQueryImpl = <
     Selected,
     TError
   > = (options: any): any => {
-    // Chain the selects: raw -> config.select -> options.select
-    const chainedSelect = (rawData: TInfiniteData) => {
-      const firstPass = select ? select(rawData) : rawData
-      if (options?.select) {
-        return options.select(firstPass)
-      }
-      return firstPass
-    }
+    // Memoized and identity-preserving; see buildChainedSelect for why the
+    // function identity matters to the observer's select-result cache.
+    const chainedSelect = useMemo(
+      () => buildChainedSelect(select as never, options?.select),
+      [options?.select]
+    )
 
     return useSuspenseInfiniteQuery(
       {
@@ -550,12 +563,13 @@ export function createSuspenseInfiniteQueryFactory<
     getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>,
     options?: SuspenseInfiniteFactoryCallOptions
   ) => {
-    const initialArgs = getArgs(config.initialPageParam)
-    const keyArgs = config.getKeyArgs?.(initialArgs) ?? initialArgs
+    // Only the caller-supplied segments are merged here; the args-derived
+    // segment is added by the impl, which does it for every infinite query.
+    // Applying it in both places would append the args twice.
     const queryKey = mergeFactoryQueryKey(
       config.queryKey,
       options?.queryKey,
-      keyArgs
+      undefined
     )
 
     return createSuspenseInfiniteQueryImpl<
@@ -565,15 +579,13 @@ export function createSuspenseInfiniteQueryFactory<
       TPageParam,
       Selected
     >(reactor, {
-      ...(({ getKeyArgs: _getKeyArgs, ...rest }) => rest)(
-        config as SuspenseInfiniteQueryFactoryConfig<
-          Service,
-          Method,
-          Transform,
-          TPageParam,
-          Selected
-        >
-      ),
+      ...(config as SuspenseInfiniteQueryFactoryConfig<
+        Service,
+        Method,
+        Transform,
+        TPageParam,
+        Selected
+      >),
       queryKey,
       getArgs,
     } as SuspenseInfiniteQueryConfig<