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

package/README.md

@@ -1,283 +1,506 @@
-The `@ic-reactor/core` package provides a streamlined way to interact with the Internet Computer (IC). It simplifies agent and actor management, ensuring type-safe communication with canisters. This package offers utilities for creating and managing IC agents, enabling seamless interaction through a friendly API.
+# @ic-reactor/core
 
-## Installation
+<div align="center">
+  <strong>The Core Library for Internet Computer Applications</strong>
+  <br><br>
+  
+  [![npm version](https://img.shields.io/npm/v/@ic-reactor/core.svg)](https://www.npmjs.com/package/@ic-reactor/core)
+  [![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>
 
-To get started with `@ic-reactor/core`, you can install the package using npm or Yarn:
+---
 
-**Using npm:**
+Framework-agnostic core library for building type-safe Internet Computer applications with [TanStack Query](https://tanstack.com/query) integration.
 
-```bash
-npm install @ic-reactor/core
-```
+> **Note**: For React applications, use [`@ic-reactor/react`](../react) instead, which re-exports everything from this package plus React-specific hooks.
+
+## Features
 
-**Using Yarn:**
+- 🔒 **End-to-End Type Safety** — From Candid to your application
+- ⚡ **TanStack Query Integration** — Automatic caching, background refetching, optimistic updates
+- 🔄 **Auto Transformations** — `DisplayReactor` converts BigInt to string, Principal to text
+- 📦 **Result Unwrapping** — Automatic `Ok`/`Err` handling from Candid Result types
+- 🔐 **Internet Identity** — Built-in authentication with session restoration
+- 🏗️ **Multi-Canister Support** — Shared authentication across canisters
+
+## Installation
 
 ```bash
-yarn add @ic-reactor/core
+# Core library
+npm install @ic-reactor/core @icp-sdk/core @tanstack/query-core
+
+# Optional: For Internet Identity authentication
+npm install @icp-sdk/auth
 ```
 
-or you can use the UMD version:
+## Core Concepts
 
-```html
-<script src="https://github.com/B3Pay/ic-reactor/releases/download/v2.0.0/ic-reactor-core.min.js"></script>
+### Architecture Overview
+
+```
+┌─────────────────┐    ┌──────────────┐    ┌─────────────────────┐
+│  ClientManager  │───▶│   Reactor    │───▶│  TanStack Query     │
+│  (Agent + Auth) │    │  (Canister)  │    │  (Caching Layer)    │
+└─────────────────┘    └──────────────┘    └─────────────────────┘
+         │                    │
+         │              ┌─────▼─────┐
+         │              │ Display   │
+         │              │ Reactor   │
+         │              └───────────┘
+         │              (Type Transforms)
+         ▼
+┌─────────────────┐
+│ Internet        │
+│ Identity        │
+└─────────────────┘
 ```
 
-### Using `createReactorCore`
+## Quick Start
 
-For ease of use, the `createReactorCore` factory function automatically sets up a new Reactor instance, managing the agent and its state internally, and providing a simple API for authenticating, querying, and updating actors.
+### 1. Create ClientManager
 
-**Example:**
+The `ClientManager` handles the IC agent, authentication, and query client:
 
 ```typescript
-import { createReactorCore } from "@ic-reactor/core"
-import { candid, canisterId, idlFactory } from "./declarations/candid"
+import { ClientManager } from "@ic-reactor/core"
+import { QueryClient } from "@tanstack/query-core"
 
-type Candid = typeof candid
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { staleTime: 5 * 60 * 1000 }, // 5 minutes
+  },
+})
 
-const { queryCall, updateCall, getPrincipal, login } =
-  createReactorCore<Candid>({
-    canisterId,
-    idlFactory,
-    withProcessEnv: true, // will use process.env.DFX_NETWORK
-  })
+const clientManager = new ClientManager({
+  queryClient,
+  withProcessEnv: true, // Reads DFX_NETWORK from environment
+})
+
+// Initialize agent and restore session
+await clientManager.initialize()
 ```
 
-You can find All available methods are returned from the `createReactorCore` function [here](https://b3pay.github.io/ic-reactor/interfaces/core.types.CreateReactorCoreReturnType.html).
+### 2. Create Reactor
+
+The `Reactor` class wraps a canister with type-safe methods and caching:
 
 ```typescript
-// later in your code
-await login({
-  onSuccess: () => {
-    console.log("Logged in successfully")
-  },
-  onError: (error) => {
-    console.error("Failed to login:", error)
-  },
+import { Reactor } from "@ic-reactor/core"
+import { idlFactory, type _SERVICE } from "./declarations/my_canister"
+
+const backend = new Reactor<_SERVICE>({
+  clientManager,
+  idlFactory,
+  canisterId: "rrkah-fqaaa-aaaaa-aaaaq-cai",
 })
+```
 
-// queryCall, will automatically call and return a promise with the result
-const { dataPromise, call } = queryCall({
-  functionName: "icrc1_balance_of",
-  args: [{ owner: getPrincipal(), subaccount: [] }],
+### 3. Call Methods
+
+```typescript
+// Direct call (no caching)
+const greeting = await backend.callMethod({
+  functionName: "greet",
+  args: ["World"],
 })
 
-console.log(await dataPromise)
-
-// updateCall
-const { call, subscribe } = updateCall({
-  functionName: "icrc1_transfer",
-  args: [
-    {
-      to: { owner: getPrincipal(), subaccount: [] },
-      amount: BigInt(10000000000),
-      fee: [],
-      memo: [],
-      created_at_time: [],
-      from_subaccount: [],
-    },
-  ],
+// Fetch with caching
+const cachedGreeting = await backend.fetchQuery({
+  functionName: "greet",
+  args: ["World"],
 })
-// subscribe to the update call
-subscribe(({ loading, error, data }) => {
-  console.log({ loading, error, data })
+
+// Get from cache (no network call)
+const fromCache = backend.getQueryData({
+  functionName: "greet",
+  args: ["World"],
 })
 
-const result = await call()
-console.log(result)
+// Invalidate cache
+backend.invalidateQueries({ functionName: "greet" })
 ```
 
-### Managing Multiple Actors
+## ClientManager API
+
+### Constructor Options
 
-When interacting with multiple canisters using `@ic-reactor/core`, you need one agent manager for each canister. This way, you can create separate reactor for each canister. This enables modular interaction with different services on the Internet Computer,
-and allows you to manage the state of each actor independently.
-Here's how to adjust the example to handle methods that require multiple arguments:
+```typescript
+interface ClientManagerParameters {
+  queryClient: QueryClient // TanStack Query client
+  port?: number // Local replica port (default: 4943)
+  withLocalEnv?: boolean // Force local network
+  withProcessEnv?: boolean // Read DFX_NETWORK from env
+  agentOptions?: HttpAgentOptions // Custom agent options
+  authClient?: AuthClient // Pre-configured auth client
+}
+```
 
-Fist you need to create a agent manager:
+### Authentication Methods
 
 ```typescript
-// agent.ts
-import { createAgentManager } from "@ic-reactor/core"
+// Initialize agent and restore previous session
+await clientManager.initialize()
+
+// Trigger login flow (opens Internet Identity)
+await clientManager.login({
+  identityProvider: "https://identity.ic0.app", // optional, auto-detected
+  onSuccess: () => console.log("Logged in!"),
+  onError: (error) => console.error(error),
+})
+
+// Logout and revert to anonymous identity
+await clientManager.logout()
 
-export const agentManager = createAgentManager() // Connects to IC network by default
+// Manually authenticate (restore session)
+const identity = await clientManager.authenticate()
 ```
 
-Then you can create a Actor for each canister:
+### State Subscriptions
 
 ```typescript
-// Assuming you've already set up `candidA`, `candidB`, and `agentManager`
-import { createActorManager } from "@ic-reactor/core"
-import * as candidA from "./declarations/candidA"
-import * as candidB from "./declarations/candidB"
-import { agentManager } from "./agent"
-
-type CandidA = typeof candidA.candidA
-type CandidB = typeof candidB.candidB
-
-const actorA = createActorManager<CandidA>({
-  agentManager,
-  canisterId: candidA.canisterId,
-  idlFactory: candidA.idlFactory,
+// Subscribe to agent state changes
+const unsubAgent = clientManager.subscribeAgentState((state) => {
+  console.log("Agent state:", state.isInitialized, state.network)
 })
 
-const actorB = createActorManager<CandidB>({
-  agentManager,
-  canisterId: candidB.canisterId,
-  idlFactory: candidB.idlFactory,
+// Subscribe to auth state changes
+const unsubAuth = clientManager.subscribeAuthState((state) => {
+  console.log("Auth state:", state.isAuthenticated, state.identity)
 })
+
+// Subscribe to identity changes
+const unsubIdentity = clientManager.subscribe((identity) => {
+  console.log("New identity:", identity.getPrincipal().toText())
+})
+
+// Cleanup
+unsubAgent()
+unsubAuth()
+unsubIdentity()
 ```
 
-You can now use the `actorA` and `actorB` instances to interact with their respective canisters:
+### Properties
 
 ```typescript
-const { dataPromise: version } = actorA.queryCall({
-  functionName: "version",
+clientManager.agent // HttpAgent instance
+clientManager.agentState // { isInitialized, isInitializing, error, network, isLocalhost }
+clientManager.authState // { identity, isAuthenticated, isAuthenticating, error }
+clientManager.queryClient // TanStack QueryClient
+clientManager.network // "ic" | "local"
+clientManager.isLocal // boolean
+```
+
+## Reactor API
+
+### Constructor Options
+
+```typescript
+interface ReactorParameters<A> {
+  clientManager: ClientManager
+  idlFactory: IDL.InterfaceFactory
+  canisterId: string | Principal
+  name?: string // Optional display name
+  pollingOptions?: PollingOptions // Custom polling for update calls
+}
+```
+
+### Core Methods
+
+```typescript
+// Call a canister method (auto-detects query vs update)
+const result = await reactor.callMethod({
+  functionName: "my_method",
+  args: [arg1, arg2],
+  callConfig: { effectiveCanisterId: ... }, // optional
 })
-console.log("Response from CanisterA method:", await version)
 
-const { dataPromise: balance } = actorB.queryCall({
-  functionName: "balance",
-  args: [principal, []],
+// Fetch and cache data
+const data = await reactor.fetchQuery({
+  functionName: "get_data",
+  args: [],
 })
-console.log("Response from CanisterB method:", await balance)
+
+// Get cached data (synchronous, no network)
+const cached = reactor.getQueryData({
+  functionName: "get_data",
+  args: [],
+})
+
+// Invalidate cached queries
+reactor.invalidateQueries() // all queries for this canister
+reactor.invalidateQueries({ functionName: "get_data" }) // specific method
+reactor.invalidateQueries({ functionName: "get_user", args: ["user-1"] }) // specific args
+
+// Get query options for TanStack Query
+const options = reactor.getQueryOptions({ functionName: "get_data" })
 ```
 
-### Using Candid Adapter
+### Properties
+
+```typescript
+reactor.canisterId // Principal
+reactor.service // IDL.ServiceClass
+reactor.queryClient // TanStack QueryClient
+reactor.agent // HttpAgent
+reactor.name // string
+```
+
+## DisplayReactor
+
+`DisplayReactor` extends `Reactor` with automatic type transformations for UI-friendly values:
+
+### Type Transformations
 
-The `CandidAdapter` class is used to interact with a canister and retrieve its Candid interface definition. It provides methods to fetch the Candid definition either from the canister's metadata or by using a temporary hack method.
-If both methods fail, it throws an error.
+| Candid Type                      | Reactor (raw) | DisplayReactor |
+| -------------------------------- | ------------- | -------------- |
+| `nat`, `int`                     | `bigint`      | `string`       |
+| `nat8/16/32/64`, `int8/16/32/64` | `bigint`      | `string`       |
+| `Principal`                      | `Principal`   | `string`       |
+| `vec nat8` (≤32 bytes)           | `Uint8Array`  | `string` (hex) |
+| `Result<Ok, Err>`                | Unwrapped     | Unwrapped      |
+
+### Usage
 
 ```typescript
-import { createCandidAdapter } from "@ic-reactor/core"
-import { agentManager } from "./agent"
+import { DisplayReactor } from "@ic-reactor/core"
+
+const backend = new DisplayReactor<_SERVICE>({
+  clientManager,
+  idlFactory,
+  canisterId: "rrkah-fqaaa-aaaaa-aaaaq-cai",
+})
+
+// Args and results use display-friendly types
+const balance = await backend.callMethod({
+  functionName: "icrc1_balance_of",
+  args: [{ owner: "aaaaa-aa", subaccount: [] }], // string instead of Principal
+})
+// balance is "100000000" (string) instead of 100000000n (bigint)
+```
+
+### Form Validation
 
-const candidAdapter = createCandidAdapter({ agentManager })
+`DisplayReactor` supports validators for mutation arguments:
 
-const canisterId = "ryjl3-tyaaa-aaaaa-aaaba-cai"
+```typescript
+import { DisplayReactor, ValidationError } from "@ic-reactor/core"
 
-// Usage example
+const backend = new DisplayReactor<_SERVICE>({
+  clientManager,
+  idlFactory,
+  canisterId: "...",
+  validators: {
+    transfer: (args) => {
+      const [{ to, amount }] = args
+      const issues = []
+
+      if (!to || to.length < 5) {
+        issues.push({ path: ["to"], message: "Invalid recipient" })
+      }
+      if (!amount || parseFloat(amount) <= 0) {
+        issues.push({ path: ["amount"], message: "Amount must be positive" })
+      }
+
+      return issues.length > 0 ? { success: false, issues } : { success: true }
+    },
+  },
+})
+
+// Validate before calling
+const result = await backend.validate("transfer", [{ to: "", amount: "0" }])
+if (!result.success) {
+  console.log(result.issues) // [{ path: ["to"], message: "Invalid recipient" }, ...]
+}
+
+// Or call with validation (throws ValidationError on failure)
 try {
-  const definition = await candidAdapter.getCandidDefinition(canisterId)
-  console.log(definition)
+  await backend.callMethodWithValidation({
+    functionName: "transfer",
+    args: [{ to: "", amount: "0" }],
+  })
 } catch (error) {
-  console.error(error)
+  if (error instanceof ValidationError) {
+    console.log(error.issues)
+  }
 }
 ```
 
-### Using `createReactorCore` with `CandidAdapter`
+## Error Handling
 
-You can use the `candidAdapter` to fetch the Candid definition and then pass it to the `createReactorCore` function.
+### Error Types
 
 ```typescript
-import { createReactorCore, createCandidAdapter } from "@ic-reactor/core"
-import { agentManager } from "./agent"
+import {
+  CallError,
+  CanisterError,
+  ValidationError,
+  isCallError,
+  isCanisterError,
+  isValidationError,
+} from "@ic-reactor/core"
+```
 
-const candidAdapter = createCandidAdapter({ agentManager })
+| Error Type         | Description                                              |
+| ------------------ | -------------------------------------------------------- |
+| `CallError`        | Network/agent errors (canister not found, timeout, etc.) |
+| `CanisterError<E>` | Canister returned an `Err` result                        |
+| `ValidationError`  | Argument validation failed (DisplayReactor)              |
 
-const canisterId = "ryjl3-tyaaa-aaaaa-aaaba-cai" // NNS ICP Ledger Canister
+### Handling Errors
 
-// Usage example
+```typescript
 try {
-  const { idlFactory } = await candidAdapter.getCandidDefinition(canisterId)
-  const { callMethod } = createReactorCore({
-    agentManager,
-    canisterId,
-    idlFactory,
+  await backend.callMethod({
+    functionName: "transfer",
+    args: [{ to: principal, amount: 100n }],
   })
-
-  const name = await callMethod("name")
-  console.log(name) // { name: 'Internet Computer' }
 } catch (error) {
-  console.error(error)
+  if (isCanisterError(error)) {
+    // Business logic error from canister
+    console.log("Canister error:", error.code, error.err)
+    // error.err is typed based on your Candid Result type
+  } else if (isCallError(error)) {
+    // Network/agent error
+    console.log("Network error:", error.message)
+  } else if (isValidationError(error)) {
+    // Validation error (DisplayReactor only)
+    console.log("Validation failed:", error.issues)
+  }
 }
 ```
 
-### Using store to lower level control
-
-If you require more control over the state management, you can use the `createReactorStore` function to create a store that provides methods for querying and updating actors.
+### CanisterError Properties
 
 ```typescript
-import { createReactorStore } from "@ic-reactor/core"
-import { candid, canisterId, idlFactory } from "./declarations/candid"
+interface CanisterError<E> {
+  err: E // The raw error value from canister
+  code: string // Error code (from variant key or "code" field)
+  message: string // Human-readable message
+  details?: Map<string, string> // Optional details
+}
+```
 
-type Candid = typeof candid
+## Utilities
 
-const { agentManager, callMethod } = createReactorStore<Candid>({
-  canisterId,
-  idlFactory,
-})
+### Result Unwrapping
 
-// Usage example
-await agentManager.authenticate()
-const authClient = agentManager.getAuth()
+Results are automatically unwrapped. The `extractOkResult` utility handles both uppercase (`Ok`/`Err`) and lowercase (`ok`/`err`) variants:
 
-authClient?.login({
-  onSuccess: () => {
-    console.log("Logged in successfully")
-  },
-  onError: (error) => {
-    console.error("Failed to login:", error)
-  },
+```typescript
+import { extractOkResult } from "@ic-reactor/core"
+
+// Candid: Result<Text, TransferError>
+// Returns the Ok value or throws CanisterError with the Err value
+const result = extractOkResult({ Ok: "success" }) // "success"
+const result2 = extractOkResult({ ok: "success" }) // "success"
+```
+
+### Query Key Generation
+
+```typescript
+const queryKey = reactor.generateQueryKey({
+  functionName: "get_user",
+  args: ["user-123"],
 })
+// ["canister-id", "get_user", "serialized-args"]
+```
+
+## TypeScript Types
 
-// Call a method
-const version = callMethod("version")
+### Actor Types
 
-console.log("Response from version method:", await version)
+```typescript
+import type {
+  FunctionName, // Method names from actor service
+  ActorMethodParameters, // Parameter types for a method
+  ActorMethodReturnType, // Return type for a method
+  ReactorArgs, // Args with optional transforms
+  ReactorReturnOk, // Return type (Ok extracted from Result)
+  ReactorReturnErr, // Error type (Err from Result)
+} from "@ic-reactor/core"
 ```
 
-**IC Agent Example:**
+### State Types
 
 ```typescript
-// agent.ts
-import { createAgentManager } from "@ic-reactor/core"
+import type { AgentState, AuthState } from "@ic-reactor/core"
+
+interface AgentState {
+  isInitialized: boolean
+  isInitializing: boolean
+  error: Error | undefined
+  network: "ic" | "local" | undefined
+  isLocalhost: boolean
+}
 
-export const agentManager = createAgentManager() // Connects to IC network by default
+interface AuthState {
+  identity: Identity | null
+  isAuthenticated: boolean
+  isAuthenticating: boolean
+  error: Error | undefined
+}
 ```
 
-**Local Agent Example:**
+## Advanced Usage
 
-For development purposes, you might want to connect to a local instance of the IC network:
+### Multiple Canisters
 
 ```typescript
-// agent.ts
-import { createAgentManager } from "@ic-reactor/core"
+const clientManager = new ClientManager({ queryClient, withProcessEnv: true })
 
-export const agentManager = createAgentManager({
-  withLocalEnv: true,
-  port: 8000, // Default port is 4943
+// All reactors share the same agent and authentication
+const backend = new Reactor<Backend>({
+  clientManager,
+  idlFactory: backendIdl,
+  canisterId: "...",
+})
+const ledger = new DisplayReactor<Ledger>({
+  clientManager,
+  idlFactory: ledgerIdl,
+  canisterId: "...",
 })
+const nft = new Reactor<NFT>({
+  clientManager,
+  idlFactory: nftIdl,
+  canisterId: "...",
+})
+
+// Login once, all canisters use the same identity
+await clientManager.login()
 ```
 
-Alternatively, you can specify a host directly:
+### Custom Polling Options
 
 ```typescript
-// agent.ts
-import { createAgentManager } from "@ic-reactor/core"
-
-export const agentManager = createAgentManager({
-  host: "http://localhost:8000",
+const backend = new Reactor<_SERVICE>({
+  clientManager,
+  idlFactory,
+  canisterId: "...",
+  pollingOptions: {
+    maxRetries: 5,
+    strategyFactory: () => /* custom strategy */,
+  },
 })
 ```
 
-### Creating an Actor Manager
-
-You can use Actor Managers to create your implementation of an actor. This allows you to manage the actor's lifecycle and state, as well as interact with the actor's methods.
+### Direct Agent Access
 
 ```typescript
-// actor.ts
-import { createActorManager } from "@ic-reactor/core"
-import { candid, canisterId, idlFactory } from "./declarations/candid"
-import { agentManager } from "./agent"
+// Get subnet ID
+const subnetId = await backend.subnetId()
 
-type Candid = typeof candid
+// Read subnet state
+const state = await backend.subnetState({ paths: [...] })
 
-const candidActor = createActorManager<Candid>({
-  agentManager,
-  canisterId,
-  idlFactory,
-})
-
-// Usage example
-const data = await candidActor.callMethod("version")
-console.log(data)
+// Access underlying agent
+const agent = backend.agent
 ```
+
+## 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)