@ic-reactor/react 2.0.1 → 3.0.0-beta.2

package/README.md

@@ -1,121 +1,317 @@
-`@ic-reactor/react` is a comprehensive React library designed to streamline interactions with the Internet Computer (IC) blockchain. It provides React hooks and utilities for efficient state management, authentication, and interaction with IC actors.
+# @ic-reactor/react
+
+<div align="center">
+  <strong>The Ultimate React Hooks for the Internet Computer.</strong>
+  <br><br>
+  
+  [![npm version](https://img.shields.io/npm/v/@ic-reactor/react.svg)](https://www.npmjs.com/package/@ic-reactor/react)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+  [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+</div>
+
+---
+
+Connect your React application to the Internet Computer Blockchain with full [TanStack Query](https://tanstack.com/query) integration for caching, suspense, and infinite queries.
 
 ## Features
 
-- **React Hooks Integration**: Custom hooks for managing blockchain actor states and authentication within React applications.
-- **Type-Safe Actor Interactions**: Type-safe interaction with IC actors using the provided actor declaration file.
-- **Efficient State Management**: Utilize the power of Zustand for global state management in React components.
-- **Asynchronous Data Handling**: Easy handling of asynchronous operations related to IC actors.
-- **Authentication Support**: Integrated hooks for managing authentication with the IC blockchain.
-- **Auto-Refresh and Query Capabilities**: Support for auto-refreshing data and querying IC actors.
+- ⚛️ **TanStack Query Integration** — Full power of React Query (caching, refetching, suspense, infinite queries)
+- � **End-to-End Type Safety** — Automatic type inference from your Candid files
+- � **Auto Transformations** — `DisplayReactor` converts BigInt to string, Principal to text, and more
+- 📦 **Result Unwrapping** — Automatic `Ok`/`Err` handling from Candid Result types
+- 🔐 **Authentication** — Easy-to-use hooks with Internet Identity integration
+- 🏗️ **Multi-Actor Support** — Manage multiple canisters with shared authentication
 
 ## Installation
 
-Install the package using npm:
-
 ```bash
-npm install @ic-reactor/react
-```
+# With npm
+npm install @ic-reactor/react @tanstack/react-query @icp-sdk/core
 
-or using yarn:
+# With pnpm
+pnpm add @ic-reactor/react @tanstack/react-query @icp-sdk/core
 
-```bash
-yarn add @ic-reactor/react
+# Optional: For Internet Identity authentication
+npm install @icp-sdk/auth
 ```
 
-## Usage
+## Quick Start
 
-Here's a simple example to get you started:
+### 1. Setup ClientManager and Reactor
 
-First, create an actor declaration file:
+```typescript
+// src/reactor.ts
+import { ClientManager, Reactor } from "@ic-reactor/react"
+import { QueryClient } from "@tanstack/react-query"
+import { idlFactory, type _SERVICE } from "./declarations/my_canister"
 
-```ts
-// actor.ts
-import { canisterId, idlFactory, actor } from "declaration/actor"
-import { createReactor } from "@ic-reactor/react"
+// Create query client for caching
+export const queryClient = new QueryClient()
 
-type Actor = typeof actor
+// Create client manager (handles identity and agent)
+export const clientManager = new ClientManager({
+  queryClient,
+  withProcessEnv: true, // Reads DFX_NETWORK from environment
+})
 
-export const { useActorStore, useAuth, useQueryCall } = createReactor<Actor>({
-  canisterId,
+// Create reactor for your canister
+export const backend = new Reactor<_SERVICE>({
+  clientManager,
   idlFactory,
-  host: "https://localhost:4943",
+  canisterId: "rrkah-fqaaa-aaaaa-aaaaq-cai",
 })
 ```
 
-Then, use the `useQueryCall` hook to call your canister method:
-
-```jsx
-// Balance.tsx
-import { useQueryCall } from "./actor"
-
-const Balance = ({ principal }) => {
-  const { call, data, loading, error } = useQueryCall({
-    functionName: "get_balance",
-    args: [principal],
-    refetchInterval: 1000,
-    refetchOnMount: true,
-    onLoading: () => console.log("Loading..."),
-    onSuccess: (data) => console.log("Success!", data),
-    onError: (error) => console.log("Error!", error),
-  })
+### 2. Create Hooks
+
+```typescript
+// src/hooks.ts
+import { createActorHooks, createAuthHooks } from "@ic-reactor/react"
+import { backend, clientManager } from "./reactor"
+
+// Create actor hooks for queries and mutations
+export const { useActorQuery, useActorMutation, useActorSuspenseQuery } =
+  createActorHooks(backend)
+
+// Create auth hooks for login/logout
+export const { useAuth, useUserPrincipal } = createAuthHooks(clientManager)
+```
+
+### 3. Setup Provider (not required) and Use in Components
+
+```tsx
+// src/App.tsx
+import { QueryClientProvider } from "@tanstack/react-query"
+import { queryClient } from "./reactor"
+import { useAuth, useActorQuery, useActorMutation } from "./hooks"
 
+function App() {
   return (
-    <div>
-      <button onClick={call} disabled={loading}>
-        {loading ? "Loading..." : "Refresh"}
-      </button>
-      {loading && <p>Loading...</p>}
-      {data && <p>Balance: {data}</p>}
-      {error && <p>Error: {error}</p>}
-    </div>
+    <QueryClientProvider client={queryClient}>
+      <AuthButton />
+      <Greeting />
+    </QueryClientProvider>
   )
 }
 
-export default Balance
+function AuthButton() {
+  const { login, logout, isAuthenticated, principal } = useAuth()
+
+  return isAuthenticated ? (
+    <button onClick={() => logout()}>
+      Logout {principal?.toText().slice(0, 8)}...
+    </button>
+  ) : (
+    <button onClick={() => login()}>Login with Internet Identity</button>
+  )
+}
+
+function Greeting() {
+  // Query: Fetch data (auto-cached!)
+  const { data, isPending, error } = useActorQuery({
+    functionName: "greet",
+    args: ["World"],
+  })
+
+  if (isPending) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
+
+  return <h1>{data}</h1>
+}
 ```
 
-## Authentication
+## Core Concepts
 
-`@ic-reactor/react` provides a custom hook for managing authentication with the IC blockchain. To use it, first create an authentication declaration file:
+### Reactor vs DisplayReactor
 
-```jsx
-// Login.tsx
-import { useAuth } from "./actor"
+| Feature       | `Reactor`        | `DisplayReactor`            |
+| ------------- | ---------------- | --------------------------- |
+| Types         | Raw Candid types | Display-friendly types      |
+| BigInt        | `bigint`         | `string`                    |
+| Principal     | `Principal`      | `string`                    |
+| Vec nat8      | `Uint8Array`     | <= 96 bytes: `string` (hex) |
+| Result        | Unwrapped        | Unwrapped                   |
+| Form-friendly | No               | Yes                         |
 
-const Login = () => {
-  const {
-    login,
-    logout,
-    loginLoading,
-    loginError,
-    identity,
-    authenticating,
-    authenticated,
-  } = useAuth()
+```typescript
+import { DisplayReactor } from "@ic-reactor/react"
 
-  return (
-    <div>
-      <h2>Login:</h2>
-      <div>
-        {loginLoading && <div>Loading...</div>}
-        {loginError ? <div>{JSON.stringify(loginError)}</div> : null}
-        {identity && <div>{identity.getPrincipal().toText()}</div>}
-      </div>
-      {authenticated ? (
-        <div>
-          <button onClick={logout}>Logout</button>
-        </div>
-      ) : (
-        <div>
-          <button onClick={login} disabled={authenticating}>
-            Login
-          </button>
-        </div>
-      )}
-    </div>
-  )
+// DisplayReactor for form-friendly UI work
+const backend = new DisplayReactor<_SERVICE>({
+  clientManager,
+  idlFactory,
+  canisterId: "rrkah-fqaaa-aaaaa-aaaaq-cai",
+})
+
+// Now hooks return strings instead of bigint/Principal
+const { data } = useActorQuery({
+  functionName: "icrc1_balance_of",
+  args: [{ owner: "aaaaa-aa", subaccount: [] }], // strings!
+})
+// data is "100000000" instead of 100000000n
+```
+
+## Hooks Reference
+
+### Actor Hooks (from `createActorHooks`)
+
+| Hook                            | Description                                    |
+| ------------------------------- | ---------------------------------------------- |
+| `useActorQuery`                 | Standard queries with loading states           |
+| `useActorSuspenseQuery`         | Suspense-enabled queries (data always defined) |
+| `useActorInfiniteQuery`         | Paginated/infinite scroll queries              |
+| `useActorSuspenseInfiniteQuery` | Suspense infinite queries                      |
+| `useActorMutation`              | State-changing operations                      |
+
+### Auth Hooks (from `createAuthHooks`)
+
+| Hook               | Description                         |
+| ------------------ | ----------------------------------- |
+| `useAuth`          | Login, logout, authentication state |
+| `useAgentState`    | Agent initialization state          |
+| `useUserPrincipal` | Current user's Principal            |
+
+## Query Examples
+
+### Standard Query
+
+```tsx
+const { data, isPending, error } = useActorQuery({
+  functionName: "get_user",
+  args: ["user-123"],
+  staleTime: 5 * 60 * 1000, // 5 minutes
+})
+```
+
+### Suspense Query
+
+```tsx
+// Parent must have <Suspense> boundary
+function UserProfile() {
+  // data is never undefined with suspense!
+  const { data } = useActorSuspenseQuery({
+    functionName: "get_user",
+    args: ["user-123"],
+  })
+
+  return <div>{data.name}</div>
 }
+```
+
+### Infinite Query
+
+```tsx
+const { data, fetchNextPage, hasNextPage } = useActorInfiniteQuery({
+  functionName: "get_posts",
+  initialPageParam: 0,
+  getNextPageParam: (lastPage, pages) => pages.length * 10,
+  args: (pageParam) => [{ offset: pageParam, limit: 10 }],
+})
+```
+
+## Mutation Examples
+
+### Basic Mutation
+
+```tsx
+const { mutate, isPending, error } = useActorMutation({
+  functionName: "update_profile",
+  onSuccess: (result) => {
+    console.log("Profile updated!", result)
+  },
+})
+
+// Call the mutation
+mutate([{ name: "Alice", bio: "Hello IC!" }])
+```
+
+## Query Factories
+
+Create reusable query configurations with factory functions:
+
+```typescript
+import {
+  createQuery,
+  createSuspenseQuery,
+  createMutation,
+} from "@ic-reactor/react"
+
+// Static query (no args at call time)
+export const tokenNameQuery = createSuspenseQuery(backend, {
+  functionName: "icrc1_name",
+})
+
+// In component:
+const { data } = tokenNameQuery.useSuspenseQuery()
+```
+
+### Factory with Dynamic Args
+
+```typescript
+import { createSuspenseQueryFactory } from "@ic-reactor/react"
+
+// Factory for balance queries
+export const getBalance = createSuspenseQueryFactory(backend, {
+  functionName: "icrc1_balance_of",
+  select: (balance) => `${balance} tokens`,
+})
 
-export default Login
+// In component - pass args at call time
+const { data } = getBalance.useSuspenseQuery({
+  args: [{ owner: userPrincipal, subaccount: [] }],
+})
 ```
+
+## Advanced: Direct Reactor Usage
+
+Access reactor methods directly for manual cache management:
+
+```typescript
+// Fetch and cache
+await backend.fetchQuery({
+  functionName: "get_user",
+  args: ["user-123"],
+})
+
+// Get cached data (no fetch)
+const cached = backend.getQueryData({
+  functionName: "get_user",
+  args: ["user-123"],
+})
+
+// Invalidate cache to trigger refetch
+backend.invalidateQueries({
+  functionName: "get_user",
+})
+
+// Direct call without caching
+const result = await backend.callMethod({
+  functionName: "update_user",
+  args: [{ name: "Alice" }],
+})
+```
+
+## Re-exports
+
+`@ic-reactor/react` re-exports everything from `@ic-reactor/core`, so you typically only need one import:
+
+```typescript
+// Everything from one package
+import {
+  ClientManager,
+  Reactor,
+  DisplayReactor,
+  createActorHooks,
+  createAuthHooks,
+  createQuery,
+  CanisterError,
+} from "@ic-reactor/react"
+```
+
+## Documentation
+
+For comprehensive guides and API reference, visit the [documentation site](https://b3pay.github.io/ic-reactor/v3).
+
+## License
+
+MIT © [Behrad Deylami](https://github.com/b3hr4d)

package/dist/createActorHooks.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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, BaseActor, FunctionName, TransformKey } from "@ic-reactor/core";
+import { UseQueryResult, UseSuspenseQueryResult, UseInfiniteQueryResult, UseSuspenseInfiniteQueryResult, UseMutationResult, InfiniteData } from "@tanstack/react-query";
+import { InfiniteQueryConfig } from "./createInfiniteQuery";
+import { SuspenseInfiniteQueryConfig } from "./createSuspenseInfiniteQuery";
+import { QueryConfig, SuspenseQueryConfig, MutationConfig } from "./types";
+export type ActorHooks<A, T extends TransformKey> = {
+    useActorQuery: {
+        <M extends FunctionName<A>>(config: QueryConfig<A, M, T, ReactorReturnOk<A, M, T>>): UseQueryResult<ReactorReturnOk<A, M, T>, ReactorReturnErr<A, M, T>>;
+        <M extends FunctionName<A>, TData>(config: QueryConfig<A, M, T, TData>): UseQueryResult<TData, ReactorReturnErr<A, M, T>>;
+    };
+    useActorSuspenseQuery: {
+        <M extends FunctionName<A>>(config: SuspenseQueryConfig<A, M, T, ReactorReturnOk<A, M, T>>): UseSuspenseQueryResult<ReactorReturnOk<A, M, T>, ReactorReturnErr<A, M, T>>;
+        <M extends FunctionName<A>, TData>(config: SuspenseQueryConfig<A, M, T, TData>): UseSuspenseQueryResult<TData, ReactorReturnErr<A, M, T>>;
+    };
+    useActorInfiniteQuery: <M extends FunctionName<A>, TPageParam = unknown>(config: InfiniteQueryConfig<A, M, T, TPageParam>) => UseInfiniteQueryResult<InfiniteData<ReactorReturnOk<A, M, T>, TPageParam>, ReactorReturnErr<A, M, T>>;
+    useActorSuspenseInfiniteQuery: <M extends FunctionName<A>, TPageParam = unknown>(config: SuspenseInfiniteQueryConfig<A, M, T, TPageParam>) => UseSuspenseInfiniteQueryResult<InfiniteData<ReactorReturnOk<A, M, T>, TPageParam>, ReactorReturnErr<A, M, T>>;
+    useActorMutation: <M extends FunctionName<A>>(config: MutationConfig<A, M, T>) => UseMutationResult<ReactorReturnOk<A, M, T>, ReactorReturnErr<A, M, T>>;
+};
+export declare function createActorHooks<A>(reactor: DisplayReactor<A>): ActorHooks<A, "display">;
+export declare function createActorHooks<A = BaseActor, T extends TransformKey = "candid">(reactor: Reactor<A, T>): ActorHooks<A, T>;
+//# sourceMappingURL=createActorHooks.d.ts.map

package/dist/createActorHooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createActorHooks.d.ts","sourceRoot":"","sources":["../src/createActorHooks.ts"],"names":[],"mappings":"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"}

package/dist/createActorHooks.js

@@ -0,0 +1,30 @@
+import { createQuery } from "./createQuery";
+import { createSuspenseQuery } from "./createSuspenseQuery";
+import { createInfiniteQuery } from "./createInfiniteQuery";
+import { createSuspenseInfiniteQuery, } from "./createSuspenseInfiniteQuery";
+import { createMutation } from "./createMutation";
+export function createActorHooks(reactor) {
+    return {
+        useActorQuery: ((config) => {
+            const { select, ...options } = config;
+            return createQuery(reactor, config).useQuery(options);
+        }),
+        useActorSuspenseQuery: ((config) => {
+            const { select, ...options } = config;
+            return createSuspenseQuery(reactor, config).useSuspenseQuery(options);
+        }),
+        useActorInfiniteQuery: ((config) => {
+            const { select, ...options } = config;
+            return createInfiniteQuery(reactor, config).useInfiniteQuery(options);
+        }),
+        useActorSuspenseInfiniteQuery: ((config) => {
+            const { select, ...options } = config;
+            return createSuspenseInfiniteQuery(reactor, config).useSuspenseInfiniteQuery(options);
+        }),
+        useActorMutation: ((config) => {
+            const { onSuccess, refetchQueries, ...options } = config;
+            return createMutation(reactor, config).useMutation(options);
+        }),
+    };
+}
+//# sourceMappingURL=createActorHooks.js.map

package/dist/createActorHooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createActorHooks.js","sourceRoot":"","sources":["../src/createActorHooks.ts"],"names":[],"mappings":"AAmCA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,EAAE,mBAAmB,EAAuB,MAAM,uBAAuB,CAAA;AAChF,OAAO,EACL,2BAA2B,GAE5B,MAAM,+BAA+B,CAAA;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAwDjD,MAAM,UAAU,gBAAgB,CAC9B,OAAsB;IAEtB,OAAO;QACL,aAAa,EAAE,CAAC,CAAC,MAAW,EAAE,EAAE;YAC9B,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,GAAG,MAAM,CAAA;YACrC,OAAO,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;QACvD,CAAC,CAAsC;QAEvC,qBAAqB,EAAE,CAAC,CAAC,MAAW,EAAE,EAAE;YACtC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,GAAG,MAAM,CAAA;YACrC,OAAO,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAA;QACvE,CAAC,CAA8C;QAE/C,qBAAqB,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE;YACjC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,GAAG,MAAM,CAAA;YACrC,OAAO,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAA;QACvE,CAAC,CAA8C;QAE/C,6BAA6B,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE;YACzC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,GAAG,MAAM,CAAA;YACrC,OAAO,2BAA2B,CAChC,OAAO,EACP,MAAM,CACP,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAA;QACrC,CAAC,CAAsD;QAEvD,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE;YAC5B,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,EAAE,GAAG,MAAM,CAAA;YACxD,OAAO,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;QAC7D,CAAC,CAAyC;KAC3C,CAAA;AACH,CAAC"}

package/dist/createAuthHooks.d.ts

@@ -0,0 +1,37 @@
+import { ClientManager, AgentState } from "@ic-reactor/core";
+import { Principal } from "@icp-sdk/core/principal";
+import { Identity } from "@icp-sdk/core/agent";
+import { AuthClientLoginOptions } from "@icp-sdk/auth/client";
+export interface UseAuthReturn {
+    authenticate: () => Promise<Identity | undefined>;
+    login: (options?: AuthClientLoginOptions) => Promise<void>;
+    logout: (options?: {
+        returnTo?: string;
+    }) => Promise<void>;
+    isAuthenticated: boolean;
+    isAuthenticating: boolean;
+    principal: Principal | null;
+    identity: Identity | null;
+    error: Error | undefined;
+}
+export interface CreateAuthHooksReturn {
+    useAgentState: () => AgentState;
+    useUserPrincipal: () => Principal | null;
+    useAuth: () => UseAuthReturn;
+}
+/**
+ * Create authentication hooks for managing user sessions with Internet Identity.
+ *
+ * @example
+ * const { useAuth, useUserPrincipal, useAgentState } = createAuthHooks(clientManager)
+ *
+ * function App() {
+ *   const { login, logout, principal, isAuthenticated } = useAuth()
+ *
+ *   return isAuthenticated
+ *     ? <button onClick={logout}>Logout {principal?.toText()}</button>
+ *     : <button onClick={login}>Login with II</button>
+ * }
+ */
+export declare const createAuthHooks: (clientManager: ClientManager) => CreateAuthHooksReturn;
+//# sourceMappingURL=createAuthHooks.d.ts.map

package/dist/createAuthHooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAuthHooks.d.ts","sourceRoot":"","sources":["../src/createAuthHooks.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAa,MAAM,kBAAkB,CAAA;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAE7D,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAA;IACjD,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,sBAAsB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1D,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1D,eAAe,EAAE,OAAO,CAAA;IACxB,gBAAgB,EAAE,OAAO,CAAA;IACzB,SAAS,EAAE,SAAS,GAAG,IAAI,CAAA;IAC3B,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAA;IACzB,KAAK,EAAE,KAAK,GAAG,SAAS,CAAA;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,UAAU,CAAA;IAC/B,gBAAgB,EAAE,MAAM,SAAS,GAAG,IAAI,CAAA;IACxC,OAAO,EAAE,MAAM,aAAa,CAAA;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,GAC1B,eAAe,aAAa,KAC3B,qBAiGF,CAAA"}

package/dist/createAuthHooks.js

@@ -0,0 +1,94 @@
+import { useSyncExternalStore, useEffect, useRef, useMemo } from "react";
+/**
+ * Create authentication hooks for managing user sessions with Internet Identity.
+ *
+ * @example
+ * const { useAuth, useUserPrincipal, useAgentState } = createAuthHooks(clientManager)
+ *
+ * function App() {
+ *   const { login, logout, principal, isAuthenticated } = useAuth()
+ *
+ *   return isAuthenticated
+ *     ? <button onClick={logout}>Logout {principal?.toText()}</button>
+ *     : <button onClick={login}>Login with II</button>
+ * }
+ */
+export const createAuthHooks = (clientManager) => {
+    /**
+     * Subscribe to agent state changes.
+     * Returns the current agent state (agent, isInitialized, etc.)
+     */
+    const useAgentState = () => useSyncExternalStore((callback) => clientManager.subscribeAgentState(callback), () => clientManager.agentState, 
+    // Server snapshot - provide initial state for SSR
+    () => clientManager.agentState);
+    /**
+     * Subscribe to authentication state changes.
+     * Returns auth state (isAuthenticated, isAuthenticating, identity, error)
+     */
+    const useAuthState = () => useSyncExternalStore((callback) => clientManager.subscribeAuthState(callback), () => clientManager.authState, 
+    // Server snapshot - provide initial state for SSR
+    () => clientManager.authState);
+    /**
+     * Main authentication hook that provides login/logout methods and auth state.
+     * Automatically initializes the session on first use, restoring any previous session.
+     *
+     * @example
+     * function AuthButton() {
+     *   const { login, logout, isAuthenticated, isAuthenticating } = useAuth()
+     *
+     *   if (isAuthenticated) {
+     *     return <button onClick={logout}>Logout</button>
+     *   }
+     *   return (
+     *     <button onClick={login} disabled={isAuthenticating}>
+     *       {isAuthenticating ? "Connecting..." : "Login"}
+     *     </button>
+     *   )
+     * }
+     */
+    const useAuth = () => {
+        const { login, logout, authenticate } = clientManager;
+        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
+        useEffect(() => {
+            if (!initializedRef.current) {
+                initializedRef.current = true;
+                clientManager.initialize();
+            }
+        }, []);
+        const principal = useMemo(() => (identity ? identity.getPrincipal() : null), [identity]);
+        return {
+            authenticate,
+            login,
+            logout,
+            isAuthenticated,
+            isAuthenticating,
+            principal,
+            identity,
+            error,
+        };
+    };
+    /**
+     * Get the current user's Principal.
+     * Returns null if not authenticated.
+     *
+     * @example
+     * function UserInfo() {
+     *   const principal = useUserPrincipal()
+     *   if (!principal) return null
+     *   return <span>Logged in as: {principal.toText()}</span>
+     * }
+     */
+    const useUserPrincipal = () => {
+        const { identity } = useAuthState();
+        return identity ? identity.getPrincipal() : null;
+    };
+    return {
+        useAuth,
+        useAgentState,
+        useUserPrincipal,
+    };
+};
+//# sourceMappingURL=createAuthHooks.js.map

package/dist/createAuthHooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAuthHooks.js","sourceRoot":"","sources":["../src/createAuthHooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAuBxE;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,aAA4B,EACL,EAAE;IACzB;;;OAGG;IACH,MAAM,aAAa,GAAG,GAAe,EAAE,CACrC,oBAAoB,CAClB,CAAC,QAAQ,EAAE,EAAE,CAAC,aAAa,CAAC,mBAAmB,CAAC,QAAQ,CAAC,EACzD,GAAG,EAAE,CAAC,aAAa,CAAC,UAAU;IAC9B,kDAAkD;IAClD,GAAG,EAAE,CAAC,aAAa,CAAC,UAAU,CAC/B,CAAA;IAEH;;;OAGG;IACH,MAAM,YAAY,GAAG,GAAc,EAAE,CACnC,oBAAoB,CAClB,CAAC,QAAQ,EAAE,EAAE,CAAC,aAAa,CAAC,kBAAkB,CAAC,QAAQ,CAAC,EACxD,GAAG,EAAE,CAAC,aAAa,CAAC,SAAS;IAC7B,kDAAkD;IAClD,GAAG,EAAE,CAAC,aAAa,CAAC,SAAS,CAC9B,CAAA;IAEH;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,OAAO,GAAG,GAAkB,EAAE;QAClC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,aAAa,CAAA;QACrD,MAAM,EAAE,eAAe,EAAE,gBAAgB,EAAE,QAAQ,EAAE,KAAK,EAAE,GAC1D,YAAY,EAAE,CAAA;QAEhB,8DAA8D;QAC9D,MAAM,cAAc,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;QAEpC,6DAA6D;QAC7D,SAAS,CAAC,GAAG,EAAE;YACb,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC;gBAC5B,cAAc,CAAC,OAAO,GAAG,IAAI,CAAA;gBAC7B,aAAa,CAAC,UAAU,EAAE,CAAA;YAC5B,CAAC;QACH,CAAC,EAAE,EAAE,CAAC,CAAA;QAEN,MAAM,SAAS,GAAG,OAAO,CACvB,GAAG,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EACjD,CAAC,QAAQ,CAAC,CACX,CAAA;QAED,OAAO;YACL,YAAY;YACZ,KAAK;YACL,MAAM;YACN,eAAe;YACf,gBAAgB;YAChB,SAAS;YACT,QAAQ;YACR,KAAK;SACN,CAAA;IACH,CAAC,CAAA;IAED;;;;;;;;;;OAUG;IACH,MAAM,gBAAgB,GAAG,GAAqB,EAAE;QAC9C,MAAM,EAAE,QAAQ,EAAE,GAAG,YAAY,EAAE,CAAA;QACnC,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;IAClD,CAAC,CAAA;IAED,OAAO;QACL,OAAO;QACP,aAAa;QACb,gBAAgB;KACjB,CAAA;AACH,CAAC,CAAA"}