@ic-reactor/core 3.0.1-beta.0 → 3.0.1

package/src/reactor.ts

@@ -0,0 +1,461 @@
+import type {
+  CallConfig,
+  PollingOptions,
+  ReadStateOptions,
+} from "@icp-sdk/core/agent"
+import type { ClientManager } from "./client"
+import type { QueryKey, FetchQueryOptions } from "@tanstack/query-core"
+import type {
+  ReactorParameters,
+  BaseActor,
+  ActorMethodParameters,
+  ActorMethodReturnType,
+  FunctionName,
+  TransformKey,
+  ReactorArgs,
+  ReactorReturnOk,
+  ReactorQueryParams,
+  ReactorCallParams,
+  CanisterId,
+} from "./types/reactor"
+
+import { DEFAULT_POLLING_OPTIONS } from "@icp-sdk/core/agent"
+import { IDL } from "@icp-sdk/core/candid"
+import { Principal } from "@icp-sdk/core/principal"
+import { generateKey, extractOkResult } from "./utils/helper"
+import {
+  processQueryCallResponse,
+  processUpdateCallResponse,
+} from "./utils/agent"
+import { CallError, CanisterError, ValidationError } from "./errors"
+import { safeGetCanisterEnv } from "@icp-sdk/core/agent/canister-env"
+
+/**
+ * Reactor class for interacting with IC canisters.
+ *
+ * This class provides core functionality for:
+ * - Direct agent calls using agent.call() and agent.query()
+ * - Query caching with TanStack Query integration
+ * - Method calls with result unwrapping
+ *
+ * @typeParam A - The actor service type
+ * @typeParam T - The type transformation to apply (default: candid = raw Candid types)
+ */
+export class Reactor<A = BaseActor, T extends TransformKey = "candid"> {
+  /** Phantom type brand for inference - never assigned at runtime */
+  declare readonly _actor: A
+  public readonly transform: TransformKey = "candid"
+  public clientManager: ClientManager
+  public name: string
+  public canisterId: Principal
+  public service: IDL.ServiceClass
+  public pollingOptions: PollingOptions
+
+  constructor(config: ReactorParameters) {
+    this.clientManager = config.clientManager
+    this.name = config.name
+    this.pollingOptions =
+      "pollingOptions" in config && config.pollingOptions
+        ? config.pollingOptions
+        : DEFAULT_POLLING_OPTIONS
+
+    const { idlFactory } = config
+    if (!idlFactory) {
+      throw new Error(`[ic-reactor] idlFactory is missing for ${this.name}`)
+    }
+
+    let canisterId = config.canisterId
+
+    if (!canisterId) {
+      const env = safeGetCanisterEnv()
+      const key = `PUBLIC_CANISTER_ID:${this.name}`
+      canisterId = env?.[key]
+
+      if (!canisterId) {
+        console.warn(
+          `[ic-reactor] ${this.name} canister ID not found in ic_env cookie`
+        )
+        canisterId = "aaaaa-aa" // Fallback
+      }
+    }
+
+    this.canisterId = Principal.from(canisterId)
+    this.service = idlFactory({ IDL })
+
+    // Register this canister ID for delegation during login
+    this.clientManager.registerCanisterId(this.canisterId.toString(), this.name)
+  }
+
+  /**
+   * Set the canister ID for this reactor.
+   * Useful for dynamically switching between canisters of the same type (e.g., multiple ICRC tokens).
+   *
+   * @param canisterId - The new canister ID (as string or Principal)
+   *
+   * @example
+   * ```typescript
+   * // Switch to a different ledger canister
+   * ledgerReactor.setCanisterId("ryjl3-tyaaa-aaaaa-aaaba-cai")
+   *
+   * // Then use queries/mutations as normal
+   * const { data } = icrc1NameQuery.useQuery()
+   * ```
+   */
+  public setCanisterId(canisterId: CanisterId): void {
+    this.canisterId = Principal.from(canisterId)
+    // Register the new canister ID for delegation
+    this.clientManager.registerCanisterId(this.canisterId.toString(), this.name)
+  }
+
+  /**
+   * Set the canister name for this reactor.
+   * Useful for dynamically switching between canisters of the same type (e.g., multiple ICRC tokens).
+   *
+   * @param name - The new canister name
+   *
+   * @example
+   * ```typescript
+   * // Switch to a different ledger canister
+   * ledgerReactor.setCanisterName("icrc1")
+   *
+   * // Then use queries/mutations as normal
+   * const { data } = icrc1NameQuery.useQuery()
+   * ```
+   */
+  public setCanisterName(name: string): void {
+    this.name = name
+  }
+
+  protected verifyCanister() {
+    // Optional: add any verification logic here
+  }
+
+  /**
+   * Get the service interface (IDL.ServiceClass) for this reactor.
+   * Useful for introspection and codec generation.
+   * @returns The service interface
+   */
+  public getServiceInterface(): IDL.ServiceClass {
+    return this.service
+  }
+
+  /**
+   * Get the function class for a specific method.
+   * @param methodName - The name of the method
+   * @returns The function class or null if not found
+   */
+  protected getFuncClass<M extends FunctionName<A>>(
+    methodName: M
+  ): IDL.FuncClass | null {
+    const field = this.service._fields.find(([name]) => name === methodName)
+    return field ? field[1] : null
+  }
+
+  /**
+   * Check if a method is a query method (query or composite_query).
+   */
+  public isQueryMethod<M extends FunctionName<A>>(methodName: M): boolean {
+    const func = this.getFuncClass(methodName)
+    if (!func) return false
+    return (
+      func.annotations.includes("query") ||
+      func.annotations.includes("composite_query")
+    )
+  }
+
+  // ══════════════════════════════════════════════════════════════════════
+  // TRANSFORMATION METHODS
+  // ══════════════════════════════════════════════════════════════════════
+
+  /**
+   * Transform arguments before calling the method.
+   * Default implementation returns arguments as-is.
+   */
+  protected transformArgs<M extends FunctionName<A>>(
+    _methodName: M,
+    args?: ReactorArgs<A, M, T>
+  ): ActorMethodParameters<A[M]> {
+    if (!args) {
+      return [] as unknown as ActorMethodParameters<A[M]>
+    }
+    return args as ActorMethodParameters<A[M]>
+  }
+
+  /**
+   * Transform the result after calling the method.
+   * Default implementation extracts Ok value from Result types.
+   */
+  protected transformResult<M extends FunctionName<A>>(
+    _methodName: M,
+    result: ActorMethodReturnType<A[M]>
+  ): ReactorReturnOk<A, M, T> {
+    return extractOkResult(result) as ReactorReturnOk<A, M, T>
+  }
+
+  // ══════════════════════════════════════════════════════════════════════
+  // QUERY KEY GENERATION
+  // ══════════════════════════════════════════════════════════════════════
+
+  public generateQueryKey<M extends FunctionName<A>>(
+    params: ReactorQueryParams<A, M, T>
+  ): QueryKey {
+    const queryKeys: any[] = [this.canisterId.toString(), params.functionName]
+
+    if (params.args) {
+      const argKey = generateKey(params.args)
+      queryKeys.push(argKey)
+    }
+    if (params.queryKey) {
+      queryKeys.push(...params.queryKey)
+    }
+
+    return queryKeys
+  }
+
+  // ══════════════════════════════════════════════════════════════════════
+  // QUERY OPTIONS
+  // ══════════════════════════════════════════════════════════════════════
+
+  public getQueryOptions<M extends FunctionName<A>>(
+    params: ReactorCallParams<A, M, T>
+  ): FetchQueryOptions<ReactorReturnOk<A, M, T>> {
+    return {
+      queryKey: this.generateQueryKey(params),
+      queryFn: () => this.callMethod(params),
+    }
+  }
+
+  /**
+   * Invalidate cached queries for this canister.
+   * This will mark matching queries as stale and trigger a refetch for any active queries.
+   *
+   * @param params - Optional parameters to filter the invalidation
+   *
+   * @example
+   * ```typescript
+   * // Invalidate all queries for this canister
+   * reactor.invalidateQueries()
+   *
+   * // Invalidate only 'getUser' queries
+   * reactor.invalidateQueries({ functionName: 'getUser' })
+   *
+   * // Invalidate 'getUser' query for specific user
+   * reactor.invalidateQueries({ functionName: 'getUser', args: ['user-1'] })
+   * ```
+   */
+  public invalidateQueries<M extends FunctionName<A>>(
+    params?: Partial<ReactorQueryParams<A, M, T>>
+  ) {
+    const queryKey = params
+      ? this.generateQueryKey({
+          functionName: params.functionName as M,
+          args: params.args,
+          queryKey: params.queryKey,
+        })
+      : [this.canisterId.toString()]
+
+    this.queryClient.invalidateQueries({
+      queryKey,
+    })
+  }
+
+  // ══════════════════════════════════════════════════════════════════════
+  // METHOD CALLS - Using agent.call() and agent.query() directly
+  // ══════════════════════════════════════════════════════════════════════
+
+  /**
+   * Call a canister method directly using agent.call() or agent.query().
+   * This is the recommended approach for interacting with canisters.
+   *
+   * @example
+   * ```typescript
+   * // Query method
+   * const result = await reactor.callMethod({
+   *   functionName: 'greet',
+   *   args: ['world'],
+   * });
+   *
+   * // Update method with options
+   * const result = await reactor.callMethod({
+   *   functionName: 'transfer',
+   *   args: [{ to: principal, amount: 100n }],
+   *   callConfig: { effectiveCanisterId: principal },
+   * });
+   * ```
+   */
+  public async callMethod<M extends FunctionName<A>>(
+    params: Omit<ReactorCallParams<A, M, T>, "queryKey">
+  ): Promise<ReactorReturnOk<A, M, T>> {
+    try {
+      const func = this.getFuncClass(params.functionName)
+      if (!func) {
+        throw new Error(`Method ${String(params.functionName)} not found`)
+      }
+
+      // Transform args
+      const transformedArgs = this.transformArgs(
+        params.functionName,
+        params.args
+      )
+
+      // Encode arguments using Candid
+      const arg = IDL.encode(func.argTypes, transformedArgs)
+
+      // Determine if this is a query or update call
+      const isQuery =
+        func.annotations.includes("query") ||
+        func.annotations.includes("composite_query")
+
+      // Execute the call
+      let rawResponse: Uint8Array
+      if (isQuery) {
+        rawResponse = await this.executeQuery(
+          String(params.functionName),
+          arg,
+          params.callConfig
+        )
+      } else {
+        rawResponse = await this.executeCall(
+          String(params.functionName),
+          arg,
+          params.callConfig
+        )
+      }
+
+      // Decode the result
+      const decoded = IDL.decode(func.retTypes, rawResponse)
+
+      // Handle single, zero, and multiple return values appropriately
+      const response = (
+        decoded.length === 0
+          ? undefined
+          : decoded.length === 1
+            ? decoded[0]
+            : decoded
+      ) as ActorMethodReturnType<A[M]>
+
+      return this.transformResult(params.functionName, response)
+    } catch (error) {
+      // Re-throw CanisterError as-is (business logic error from canister)
+      if (error instanceof CanisterError || error instanceof ValidationError) {
+        throw error
+      }
+
+      const message = `Failed to call method "${String(params.functionName)}": `
+
+      // Wrap other errors in CallError (network/agent issues)
+      if (error instanceof Error) {
+        throw new CallError(message + error.message, error)
+      }
+
+      throw new CallError(message + String(error), error)
+    }
+  }
+
+  /**
+   * Fetch data from the canister and cache it using React Query.
+   * This method ensures the data is in the cache and returns it.
+   */
+  public async fetchQuery<M extends FunctionName<A>>(
+    params: ReactorCallParams<A, M, T>
+  ): Promise<ReactorReturnOk<A, M, T>> {
+    const options = this.getQueryOptions(params)
+    return this.queryClient.ensureQueryData<ReactorReturnOk<A, M, T>>(options)
+  }
+
+  /**
+   * Get the current data from the cache without fetching.
+   */
+  public getQueryData<M extends FunctionName<A>>(
+    params: ReactorQueryParams<A, M, T>
+  ): ReactorReturnOk<A, M, T> | undefined {
+    const queryKey = this.generateQueryKey(params)
+    return this.queryClient.getQueryData<ReactorReturnOk<A, M, T>>(queryKey)
+  }
+
+  /**
+   * Execute a query call using agent.query()
+   */
+  protected async executeQuery(
+    methodName: string,
+    arg: Uint8Array,
+    callConfig?: CallConfig
+  ): Promise<Uint8Array> {
+    const agent = this.clientManager.agent
+    const effectiveCanisterId =
+      callConfig?.effectiveCanisterId ?? this.canisterId
+
+    const response = await agent.query(this.canisterId, {
+      methodName,
+      arg,
+      effectiveCanisterId,
+    })
+
+    return processQueryCallResponse(response, this.canisterId, methodName)
+  }
+
+  /**
+   * Execute an update call using agent.call()
+   */
+  protected async executeCall(
+    methodName: string,
+    arg: Uint8Array,
+    callConfig?: CallConfig
+  ): Promise<Uint8Array> {
+    const agent = this.clientManager.agent
+
+    const response = await agent.call(this.canisterId, {
+      methodName,
+      arg,
+      effectiveCanisterId: callConfig?.effectiveCanisterId,
+      nonce: callConfig?.nonce,
+    })
+
+    return await processUpdateCallResponse(
+      response,
+      this.canisterId,
+      methodName,
+      agent,
+      this.pollingOptions
+    )
+  }
+
+  // ══════════════════════════════════════════════════════════════════════
+  // SUBNET
+  // ══════════════════════════════════════════════════════════════════════
+
+  /**
+   * Get the subnet ID for this canister.
+   */
+  public async subnetId() {
+    return this.clientManager.agent.getSubnetIdFromCanister(this.canisterId)
+  }
+
+  /**
+   * Get the subnet state for this canister.
+   */
+  public async subnetState(options: ReadStateOptions) {
+    const subnetId = await this.subnetId()
+    return this.clientManager.agent.readSubnetState(subnetId, options)
+  }
+
+  // ══════════════════════════════════════════════════════════════════════
+  // GETTERS
+  // ══════════════════════════════════════════════════════════════════════
+
+  /**
+   * Get the query client from clientManager.
+   * This is the recommended way to access the query client for direct queries.
+   */
+  get queryClient() {
+    return this.clientManager.queryClient
+  }
+
+  /**
+   * Get the agent from clientManager.
+   * This is the recommended way to access the agent for direct calls.
+   */
+  get agent() {
+    return this.clientManager.agent
+  }
+}

package/src/types/client.ts

@@ -0,0 +1,110 @@
+import type { HttpAgent, HttpAgentOptions, Identity } from "@icp-sdk/core/agent"
+import type { AuthClient } from "@icp-sdk/auth/client"
+import type { QueryClient } from "@tanstack/query-core"
+
+/**
+ * Parameters for configuring a ClientManager instance.
+ *
+ * @property {QueryClient} queryClient - The TanStack QueryClient used for caching and state management.
+ * @property {number} [port] - The port used for the local IC replica (default is 4943).
+ * @property {HttpAgentOptions} [agentOptions] - Optional configuration for the underlying HttpAgent.
+ * @property {boolean} [withLocalEnv] - If true, configures the agent for a local environment.
+ * @property {boolean} [withProcessEnv] - If true, auto-configures the agent based on process.env settings.
+ */
+export interface ClientManagerParameters {
+  /**
+   * The TanStack QueryClient used for caching and state management.
+   */
+  queryClient: QueryClient
+  /**
+   * Optional configuration for the underlying HttpAgent.
+   */
+  agentOptions?: HttpAgentOptions
+  /**
+   * The port used for the local IC replica (default is 4943).
+   */
+  port?: number
+  /**
+   * If true, configures the agent for a local environment.
+   */
+  withLocalEnv?: boolean
+  /**
+   * If true, auto-configures the agent based on process.env settings.
+   */
+  withProcessEnv?: boolean
+  /**
+   * Optional pre-initialized AuthClient instance.
+   * If provided, the manager will use this instance instead of dynamically importing
+   * and creating a new one from `@icp-sdk/auth`.
+   * This is useful for environments where dynamic imports are not supported or
+   * when you want to share an AuthClient instance across multiple managers.
+   */
+  authClient?: AuthClient
+  /**
+   * **EXPERIMENTAL** - If true, uses the canister environment from `@icp-sdk/core/agent/canister-env`
+   * to automatically configure the agent host and root key based on the `ic_env` cookie.
+   *
+   * ⚠️ This feature is experimental and may cause issues with update calls on localhost development.
+   * Use with caution and only when you need automatic environment detection from the IC SDK.
+   *
+   * @experimental
+   * @default false
+   */
+  withCanisterEnv?: boolean
+}
+
+/**
+ * Represents the state of an agent.
+ */
+export interface AgentState {
+  /**
+   * Indicates whether the agent has been initialized.
+   */
+  isInitialized: boolean
+
+  /**
+   * Indicates whether the agent is in the process of initializing.
+   */
+  isInitializing: boolean
+
+  /**
+   * Represents an error associated with the agent, if any.
+   */
+  error: Error | undefined
+
+  /**
+   * Represents the network associated with the agent, if any.
+   */
+  network: string | undefined
+
+  /**
+   * Indicates whether the agent is connected to a local network.
+   */
+  isLocalhost: boolean
+}
+
+/**
+ * Represents the authentication state of an agent.
+ */
+export interface AuthState {
+  identity: Identity | null
+
+  /**
+   * Indicates whether the authentication process is ongoing.
+   */
+  isAuthenticating: boolean
+
+  /**
+   * Indicates whether the agent is authenticated.
+   */
+  isAuthenticated: boolean
+
+  /**
+   * Represents any error that occurred during authentication.
+   */
+  error: Error | undefined
+}
+
+export interface UpdateAgentParameters extends HttpAgentOptions {
+  agent?: HttpAgent
+}

package/src/types/display-reactor.ts

@@ -0,0 +1,73 @@
+// ============================================================================
+// Validation Types
+// ============================================================================
+
+import { ValidationIssue } from "../errors"
+import {
+  BaseActor,
+  FunctionName,
+  ReactorArgs,
+  ReactorParameters,
+} from "./reactor"
+
+/**
+ * Validation result returned by a validator function.
+ * Either success (true) or failure with issues.
+ */
+export type ValidationResult =
+  | { success: true }
+  | { success: false; issues: ValidationIssue[] }
+
+/**
+ * A validator function that validates method arguments.
+ * Receives display types (strings for Principal, bigint, etc.).
+ *
+ * @param args - The display-type arguments to validate
+ * @returns ValidationResult indicating success or failure with issues
+ *
+ * @example
+ * ```typescript
+ * // Validator receives display types
+ * reactor.registerValidator("transfer", ([input]) => {
+ *   const issues = []
+ *
+ *   // input.to is string (not Principal)
+ *   if (!input.to) {
+ *     issues.push({ path: ["to"], message: "Recipient is required" })
+ *   }
+ *
+ *   // input.amount is string (not bigint)
+ *   if (!/^\d+$/.test(input.amount)) {
+ *     issues.push({ path: ["amount"], message: "Must be a valid number" })
+ *   }
+ *
+ *   return issues.length > 0 ? { success: false, issues } : { success: true }
+ * })
+ * ```
+ */
+export type Validator<Args = unknown[]> = (
+  args: Args
+) => ValidationResult | Promise<ValidationResult>
+
+/**
+ * Validator that receives display types for a specific method.
+ */
+export type DisplayValidator<A, M extends FunctionName<A>> = Validator<
+  ReactorArgs<A, M, "display">
+>
+
+// ============================================================================
+// DisplayReactor Parameters
+// ============================================================================
+
+export interface DisplayReactorParameters<
+  A = BaseActor,
+> extends ReactorParameters {
+  /**
+   * Optional initial validators to register.
+   * Validators receive display types (strings for Principal, bigint, etc.)
+   */
+  validators?: Partial<{
+    [M in FunctionName<A>]: DisplayValidator<A, M>
+  }>
+}

package/src/types/index.ts

@@ -0,0 +1,6 @@
+export * from "./reactor"
+export * from "./client"
+export * from "./result"
+export * from "./transform"
+export * from "./variant"
+export * from "./display-reactor"