@ic-reactor/react 3.12.5 → 4.0.0-beta.1

package/src/auth/local-ii-probe.ts

@@ -1,147 +0,0 @@
-/**
- * Ask a locally deployed Internet Identity canister what it actually serves.
- *
- * `localInternetIdentityProvider` builds `http://<id>.localhost:<port>/authorize`,
- * the id.ai-era path. Whether that works depends on which Internet Identity
- * build is installed, and the window is narrow:
- *
- * - up to `release-2025-03-07`, the SPA lived at `/` and used a `#authorize`
- *   fragment; `/authorize` is not an asset
- * - `release-2026-01-05` through `release-2026-03-16` serve `/authorize`
- * - from `release-2026-03-23` the frontend left the canister entirely (the id.ai
- *   split), so `/authorize` 404s even on `.raw`
- *
- * Outside that window the login popup renders the gateway's
- * "Response Verification Error" page and the app simply waits until the user
- * closes it. Nothing points at the cause.
- *
- * Asking the canister over the agent avoids the gateway, so the answer is about
- * the canister's assets rather than about how the gateway felt about them.
- */
-
-import { Actor, type HttpAgent } from "@icp-sdk/core/agent"
-import { IDL } from "@icp-sdk/core/candid"
-
-/** The `http_request` query every asset-serving canister exposes. */
-const httpInterface: IDL.InterfaceFactory = ({ IDL }) => {
-  const HeaderField = IDL.Tuple(IDL.Text, IDL.Text)
-  return IDL.Service({
-    http_request: IDL.Func(
-      [
-        IDL.Record({
-          method: IDL.Text,
-          url: IDL.Text,
-          headers: IDL.Vec(HeaderField),
-          body: IDL.Vec(IDL.Nat8),
-        }),
-      ],
-      [
-        IDL.Record({
-          status_code: IDL.Nat16,
-          headers: IDL.Vec(HeaderField),
-          body: IDL.Vec(IDL.Nat8),
-        }),
-      ],
-      ["query"]
-    ),
-  })
-}
-
-interface HttpCapableActor {
-  http_request: (request: {
-    method: string
-    url: string
-    headers: [string, string][]
-    body: Uint8Array
-  }) => Promise<{ status_code: number }>
-}
-
-/** Where a given Internet Identity build expects the sign-in flow to start. */
-export type AuthorizePath = "/authorize" | "/#authorize"
-
-export interface LocalIiProbe {
-  /** The path that works, or `null` when the canister serves no sign-in UI. */
-  path: AuthorizePath | null
-  /**
-   * The probe could not reach a conclusion — the canister was unreachable, or
-   * it does not expose `http_request` at all. Callers keep their existing
-   * behaviour rather than blocking a login that might well work.
-   */
-  inconclusive: boolean
-}
-
-async function statusOf(
-  actor: HttpCapableActor,
-  url: string
-): Promise<number | undefined> {
-  try {
-    const response = await actor.http_request({
-      method: "GET",
-      url,
-      headers: [],
-      body: new Uint8Array(),
-    })
-    return response.status_code
-  } catch {
-    return undefined
-  }
-}
-
-/**
- * Determine which authorize path a locally deployed Internet Identity serves.
- *
- * Never throws. A probe that cannot answer returns `inconclusive`, because a
- * diagnostic that blocks a working setup is worse than the failure it explains.
- */
-export async function probeLocalInternetIdentity(
-  agent: HttpAgent,
-  canisterId: string
-): Promise<LocalIiProbe> {
-  let actor: HttpCapableActor
-  try {
-    actor = Actor.createActor<HttpCapableActor>(httpInterface, {
-      agent,
-      canisterId,
-    })
-  } catch {
-    return { path: "/authorize", inconclusive: true }
-  }
-
-  const authorize = await statusOf(actor, "/authorize")
-
-  // The canister does not answer http_request at all — not an asset canister,
-  // not deployed, or the replica is down. Not our call to make.
-  if (authorize === undefined) {
-    return { path: "/authorize", inconclusive: true }
-  }
-
-  if (authorize >= 200 && authorize < 300) {
-    return { path: "/authorize", inconclusive: false }
-  }
-
-  // Pre-2026 builds serve the SPA at the root and drive the flow from a
-  // `#authorize` fragment, which is a path the gateway never sees.
-  const root = await statusOf(actor, "/")
-  if (root !== undefined && root >= 200 && root < 300) {
-    return { path: "/#authorize", inconclusive: false }
-  }
-
-  return { path: null, inconclusive: false }
-}
-
-/**
- * The error a login gets when the installed build serves no sign-in UI, in
- * place of a 503 page inside a popup the app cannot see.
- */
-export function localInternetIdentityUnavailableError(
-  canisterId: string
-): Error {
-  return new Error(
-    `[ic-reactor] The Internet Identity canister ${canisterId} does not serve a sign-in UI: ` +
-      `neither /authorize nor / returned a page. Internet Identity builds from ` +
-      `release-2026-03-23 onward moved their frontend out of the canister (the id.ai split) ` +
-      `and cannot be used locally. Install internet_identity_dev.wasm from release-2026-03-16, ` +
-      `the newest build that still self-serves /authorize, or point \`identityProvider\` at a ` +
-      `provider you host yourself.`
-  )
-}

package/src/auth/types.ts

@@ -1,200 +0,0 @@
-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 {
-  data: Uint8Array
-  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, and
- * IC Reactor normalizes whichever of these you pass into that thunk.
- */
-export type IdentityAttributeNonce =
-  Uint8Array | Promise<Uint8Array> | (() => Uint8Array | Promise<Uint8Array>)
-
-export interface IdentityAttributeRequest {
-  keys: string[]
-  nonce: IdentityAttributeNonce
-}
-
-export interface IdentityAttributeValues {
-  email?: string
-  name?: string
-  verified_email?: string
-  [key: string]: string | undefined
-}
-
-export interface IdentityAttributeResult {
-  principal: string
-  requestedKeys: string[]
-  signedAttributes: SignedIdentityAttributes
-  decodedAttributes: IdentityAttributeValues
-  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 {
-  maxTimeToLive?: bigint
-  targets?: Principal[]
-}
-
-export interface AuthenticationSignInOptions
-  extends AuthClientSignInOptions, AuthenticationClientOptions {
-  onSuccess?: () => void | Promise<void>
-  onError?: (error?: string) => void | Promise<void>
-}
-
-export interface RequestIdentityAttributesParameters extends AuthenticationClientOptions {
-  keys: string[]
-  nonce: IdentityAttributeNonce
-  /**
-   * Sign in as part of the same identity-provider interaction.
-   * @default true
-   */
-  signIn?: boolean
-  maxTimeToLive?: bigint
-  targets?: Principal[]
-}
-
-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
-}
-
-/**
- * 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: {
-    keys: string[]
-    // `@icp-sdk/auth` v8 takes a thunk, so it can journal the value and replay
-    // the same bytes through a redirect flow.
-    nonce: () => Promise<Uint8Array>
-  }): Promise<SignedIdentityAttributes>
-}
-
-export interface AuthState {
-  identity: Identity | null
-  isAuthenticating: boolean
-  isAuthenticated: boolean
-  error: Error | undefined
-}

package/src/createActorHooks.ts

@@ -1,220 +0,0 @@
-/**
- * Actor Hooks Factory - Creates a full set of React hooks for a reactor instance.
- *
- * This is the primary entry point for using the library in React applications.
- * It generates type-safe hooks for:
- * - Queries (useActorQuery)
- * - Suspense Queries (useActorSuspenseQuery)
- * - Infinite Queries (useActorInfiniteQuery)
- * - Suspense Infinite Queries (useActorSuspenseInfiniteQuery)
- * - Mutations (useActorMutation)
- *
- * @example
- * const { useActorQuery, useActorMutation } = createActorHooks(reactor)
- *
- * // In component
- * const { data } = useActorQuery({ functionName: 'get_user' })
- * const { mutate } = useActorMutation({ functionName: 'update_user' })
- */
-import {
-  Reactor,
-  DisplayReactor,
-  ReactorReturnErr,
-  ReactorReturnOk,
-  ReactorQueryData,
-  BaseActor,
-  FunctionName,
-  ReactorArgs,
-  TransformKey,
-} from "@ic-reactor/core"
-import {
-  UseQueryResult,
-  UseSuspenseQueryResult,
-  UseInfiniteQueryResult,
-  UseSuspenseInfiniteQueryResult,
-  UseMutationResult,
-  InfiniteData,
-} from "@tanstack/react-query"
-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.js"
-import type { CallConfig } from "@icp-sdk/core/agent"
-import { InfiniteQueryConfig } from "./createInfiniteQuery.js"
-import { SuspenseInfiniteQueryConfig } from "./createSuspenseInfiniteQuery.js"
-import { QueryConfig, SuspenseQueryConfig, MutationConfig } from "./types.js"
-
-/**
- * The bound query hooks forward their config to `useActorQuery` and
- * `useActorSuspenseQuery`, which take `callConfig`. `QueryConfig` is shared with
- * `createQuery`, which does not use it, so it is added here and not there.
- */
-type WithCallConfig<Config> = Config & {
-  /** Agent call configuration (canisterId override, effectiveCanisterId, etc.) */
-  callConfig?: CallConfig
-}
-
-export type ActorHooks<Service, Transform extends TransformKey> = {
-  useActorQuery: {
-    <Method extends FunctionName<Service>>(
-      config: WithCallConfig<
-        QueryConfig<
-          Service,
-          Method,
-          Transform,
-          ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>
-        >
-      >
-    ): UseQueryResult<
-      ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-      ReactorReturnErr<Service, Method, Transform>
-    >
-    <Method extends FunctionName<Service>, TData>(
-      config: WithCallConfig<QueryConfig<Service, Method, Transform, TData>>
-    ): UseQueryResult<TData, ReactorReturnErr<Service, Method, Transform>>
-  }
-
-  useActorSuspenseQuery: {
-    <Method extends FunctionName<Service>>(
-      config: WithCallConfig<
-        SuspenseQueryConfig<
-          Service,
-          Method,
-          Transform,
-          ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>
-        >
-      >
-    ): UseSuspenseQueryResult<
-      ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-      ReactorReturnErr<Service, Method, Transform>
-    >
-    <Method extends FunctionName<Service>, TData>(
-      config: WithCallConfig<
-        SuspenseQueryConfig<Service, Method, Transform, TData>
-      >
-    ): UseSuspenseQueryResult<
-      TData,
-      ReactorReturnErr<Service, Method, Transform>
-    >
-  }
-
-  // `Selected` is what `select` returns, so `select` can reshape the pages the
-  // way `createInfiniteQuery` allows. Without `select` it stays `InfiniteData`.
-  useActorInfiniteQuery: <
-    Method extends FunctionName<Service>,
-    TPageParam = unknown,
-    Selected = InfiniteData<
-      ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-      TPageParam
-    >,
-  >(
-    config: InfiniteQueryConfig<
-      Service,
-      Method,
-      Transform,
-      TPageParam,
-      Selected
-    >
-  ) => UseInfiniteQueryResult<
-    Selected,
-    ReactorReturnErr<Service, Method, Transform>
-  >
-
-  useActorSuspenseInfiniteQuery: <
-    Method extends FunctionName<Service>,
-    TPageParam = unknown,
-    Selected = InfiniteData<
-      ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-      TPageParam
-    >,
-  >(
-    config: SuspenseInfiniteQueryConfig<
-      Service,
-      Method,
-      Transform,
-      TPageParam,
-      Selected
-    >
-  ) => UseSuspenseInfiniteQueryResult<
-    Selected,
-    ReactorReturnErr<Service, Method, Transform>
-  >
-
-  useActorMutation: <
-    Method extends FunctionName<Service>,
-    TOnMutateResult = unknown,
-  >(
-    config: MutationConfig<Service, Method, Transform, TOnMutateResult>
-  ) => UseMutationResult<
-    ReactorReturnOk<Service, Method, Transform>,
-    ReactorReturnErr<Service, Method, Transform>,
-    // Without this TVariables defaults to `unknown` and mutate/mutateAsync
-    // accept anything; the standalone hook and createMutation both pass it.
-    ReactorArgs<Service, Method, Transform>,
-    TOnMutateResult
-  >
-
-  useActorMethod: <Method extends FunctionName<Service>>(
-    config: Omit<
-      UseActorMethodParameters<Service, Method, Transform>,
-      "reactor"
-    >
-  ) => ReturnType<typeof useActorMethod<Service, Method, Transform>>
-}
-
-export function createActorHooks<Service>(
-  reactor: DisplayReactor<Service>
-): ActorHooks<Service, "display">
-
-export function createActorHooks<
-  Service = BaseActor,
-  Transform extends TransformKey = "candid",
->(reactor: Reactor<Service, Transform>): ActorHooks<Service, Transform>
-
-export function createActorHooks<Service, Transform extends TransformKey>(
-  reactor: Reactor<Service, Transform>
-): ActorHooks<Service, Transform> {
-  return {
-    useActorQuery: ((config: any) =>
-      useActorQuery({ ...config, reactor })) as ActorHooks<
-      Service,
-      Transform
-    >["useActorQuery"],
-
-    useActorSuspenseQuery: ((config: any) =>
-      useActorSuspenseQuery({ ...config, reactor })) as ActorHooks<
-      Service,
-      Transform
-    >["useActorSuspenseQuery"],
-
-    useActorInfiniteQuery: ((config: any) =>
-      useActorInfiniteQuery({ ...config, reactor })) as ActorHooks<
-      Service,
-      Transform
-    >["useActorInfiniteQuery"],
-
-    useActorSuspenseInfiniteQuery: ((config: any) =>
-      useActorSuspenseInfiniteQuery({ ...config, reactor })) as ActorHooks<
-      Service,
-      Transform
-    >["useActorSuspenseInfiniteQuery"],
-
-    useActorMutation: ((config: any) =>
-      useActorMutation({ ...config, reactor })) as ActorHooks<
-      Service,
-      Transform
-    >["useActorMutation"],
-
-    useActorMethod: (config) =>
-      useActorMethod({ ...config, reactor } as UseActorMethodParameters<
-        Service,
-        any,
-        Transform
-      >),
-  }
-}