@ic-reactor/core 3.0.3-beta.4 → 3.0.3

package/src/types/reactor.ts

@@ -0,0 +1,188 @@
+import type {
+  ActorMethod,
+  ActorSubclass,
+  CallConfig,
+  PollingOptions,
+} from "@icp-sdk/core/agent"
+import type { Principal } from "@icp-sdk/core/principal"
+import type { QueryKey } from "@tanstack/query-core"
+import type { ClientManager } from "../client"
+import type { CallError, CanisterError } from "../errors"
+import type { OkResult, ErrResult } from "./result"
+import type { DisplayOf, ActorDisplayCodec } from "../display"
+
+export interface DefaultActorType {
+  [key: string]: ActorMethod<any, any>
+}
+
+export type BaseActor<T = DefaultActorType> = ActorSubclass<T>
+
+export type FunctionName<A = BaseActor> = Extract<keyof A, string>
+
+export type FunctionType = "query" | "update"
+
+export type CanisterId = string | Principal
+
+// Extracts the argument types of an ActorMethod
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ActorMethodParameters<T> =
+  T extends ActorMethod<infer Args, any> ? Args : never
+
+// Extracts the return type of an ActorMethod
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ActorMethodReturnType<T> =
+  T extends ActorMethod<any, infer Ret> ? Ret : never
+
+export interface ReactorParameters {
+  clientManager: ClientManager
+  name: string
+  idlFactory: (IDL: any) => any
+  canisterId?: CanisterId
+  pollingOptions?: PollingOptions
+}
+
+export type ActorMethodType<A, M extends keyof A> = {
+  (...args: ActorMethodParameters<A[M]>): Promise<ActorMethodReturnType<A[M]>>
+  withOptions: (
+    options?: CallConfig
+  ) => (
+    ...args: ActorMethodParameters<A[M]>
+  ) => Promise<ActorMethodReturnType<A[M]>>
+}
+
+/**
+ * Registry for argument transformations.
+ * Users can augment this interface to add custom transforms:
+ *
+ * @example
+ * ```typescript
+ * // In your code, augment the module
+ * declare module '@ic-reactor/core' {
+ *   interface TransformArgsRegistry<T> {
+ *     myCustom: MyCustomArgTransform<T>
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Helper to extract arguments type for codecs (unwraps single argument tuples).
+ */
+export type ArgsType<T> = T extends readonly [infer U]
+  ? U
+  : T extends readonly []
+    ? null
+    : T
+
+export interface TransformArgsRegistry<T> {
+  candid: T
+  display: AsDisplayArgs<T>
+}
+
+/**
+ * Registry for return type transformations.
+ * Users can augment this interface to add custom transforms:
+ *
+ * @example
+ * ```typescript
+ * declare module '@ic-reactor/core' {
+ *   interface TransformReturnRegistry<T> {
+ *     myCustom: MyCustomReturnTransform<T>
+ *   }
+ * }
+ * ```
+ */
+// @ts-expect-error - A is used in module augmentation
+export interface TransformReturnRegistry<T, A = BaseActor> {
+  candid: T
+  display: DisplayOf<T>
+}
+
+/**
+ * Helper type to transform args array elements using ToDisplay
+ */
+export type AsDisplayArgs<T> = T extends readonly unknown[]
+  ? { [K in keyof T]: DisplayOf<T[K]> }
+  : DisplayOf<T>
+
+/**
+ * Union of all available transform keys.
+ * Automatically includes any user-defined transforms via module augmentation.
+ */
+export type TransformKey = keyof TransformArgsRegistry<unknown>
+
+/**
+ * Apply argument transformation based on the transform key.
+ * Looks up the transform in TransformArgsRegistry.
+ */
+export type ReactorArgs<
+  A,
+  M extends FunctionName<A>,
+  Transform extends TransformKey = "candid",
+> = TransformArgsRegistry<ActorMethodParameters<A[M]>>[Transform]
+
+/**
+ * Apply return type transformation based on the transform key.
+ * Looks up the transform in TransformReturnRegistry.
+ */
+export type ReactorReturnOk<
+  A,
+  M extends FunctionName<A>,
+  Transform extends TransformKey = "candid",
+> = TransformReturnRegistry<OkResult<ActorMethodReturnType<A[M]>>, A>[Transform]
+
+export type ReactorReturnErr<
+  A,
+  M extends FunctionName<A>,
+  Transform extends TransformKey = "candid",
+> =
+  | CanisterError<
+      TransformReturnRegistry<
+        ErrResult<ActorMethodReturnType<A[M]>>,
+        A
+      >[Transform]
+    >
+  | CallError
+
+/**
+ * Helper type for actor method codecs returend by getCodec
+ */
+export interface ActorMethodCodecs<A, M extends FunctionName<A>> {
+  args: ActorDisplayCodec<
+    ArgsType<ActorMethodParameters<A[M]>>,
+    DisplayOf<ArgsType<ActorMethodParameters<A[M]>>>
+  >
+  result: ActorDisplayCodec<
+    ActorMethodReturnType<A[M]>,
+    DisplayOf<ActorMethodReturnType<A[M]>>
+  >
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// REACTOR QUERY PARAMS - Reusable parameter types for reactor methods
+// ══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Basic query parameters for reactor cache operations.
+ * Used by: generateQueryKey, getQueryData
+ */
+export interface ReactorQueryParams<
+  A,
+  M extends FunctionName<A>,
+  T extends TransformKey = "candid",
+> {
+  functionName: M
+  args?: ReactorArgs<A, M, T>
+  queryKey?: QueryKey
+}
+
+/**
+ * Query parameters with optional call configuration.
+ * Used by: getQueryOptions, fetchQuery, callMethod
+ */
+export interface ReactorCallParams<
+  A,
+  M extends FunctionName<A>,
+  T extends TransformKey = "candid",
+> extends ReactorQueryParams<A, M, T> {
+  callConfig?: CallConfig
+}

package/src/types/result.ts

@@ -0,0 +1,50 @@
+export type UnwrapOkErrResult<T> = T extends { Ok: infer U }
+  ? U
+  : T extends { ok: infer U }
+    ? U
+    : T extends { Err: infer E }
+      ? E
+      : T extends { err: infer E }
+        ? E
+        : T
+
+/**
+ * Extract the Ok value from a Result type.
+ * Supports both uppercase (Ok/Err - Rust) and lowercase (ok/err - Motoko).
+ * - If T is { Ok: U } or { ok: U }, returns U
+ * - If T is { Err: E } or { err: E }, returns never (filters it out from unions)
+ * - If T is { Ok: U } | { Err: E }, returns U (the Err variant is filtered out)
+ * - Otherwise, returns T as-is
+ */
+export type OkResult<T> = T extends { Err: unknown }
+  ? never
+  : T extends { err: unknown }
+    ? never
+    : T extends { Ok: infer U }
+      ? U
+      : T extends { ok: infer U }
+        ? U
+        : T
+
+export type ErrResult<T> = T extends { Ok: unknown }
+  ? never
+  : T extends { ok: unknown }
+    ? never
+    : T extends { Err: infer E }
+      ? E
+      : T extends { err: infer E }
+        ? E
+        : never
+
+/**
+ * Check if T is a Result type ({ Ok: U } | { Err: E } or { ok: U } | { err: E })
+ */
+export type IsOkErrResultType<T> = T extends { Ok: unknown }
+  ? true
+  : T extends { ok: unknown }
+    ? true
+    : T extends { Err: unknown }
+      ? true
+      : T extends { err: unknown }
+        ? true
+        : false

package/src/types/transform.ts

@@ -0,0 +1,29 @@
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (
+  x: infer I
+) => void
+  ? I
+  : never
+
+// The "Last" type extracts the last member of a union type
+type Last<T> =
+  UnionToIntersection<T extends any ? (x: T) => void : never> extends (
+    x: infer L
+  ) => void
+    ? L
+    : never
+
+/// Convert a union type to a tuple type (order is not guaranteed)
+/// (Note: there are several variants of this trick – choose one that suits your needs.)
+export type UnionToTuple<T, L = Last<T>> = [T] extends [never]
+  ? []
+  : [...UnionToTuple<Exclude<T, L>>, L]
+
+export type IsBlobType<T> = T extends Uint8Array
+  ? true
+  : T extends number[]
+    ? number[] extends T
+      ? true
+      : false
+    : false
+
+export type IsOptionalType<T> = [T] extends [[] | [any]] ? true : false

package/src/types/variant.ts

@@ -0,0 +1,39 @@
+export type IsCandidVariant<T> = [T] extends [CandidVariantToIntersection<T>]
+  ? false
+  : true
+
+export type CandidVariantToIntersection<U> = (
+  U extends object ? (k: U) => void : never
+) extends (k: infer I) => void
+  ? I
+  : never
+
+export type CandidVariantKey<T> = T extends any ? keyof T : never
+
+export type CandidVariantValue<T, K extends CandidVariantKey<T>> =
+  T extends Record<K, infer U> ? U : never
+
+export type CandidVariant<T> =
+  IsCandidVariant<T> extends true
+    ? {
+        _type: CandidVariantKey<T> & string
+      } & {
+        [K in CandidVariantKey<T> & string as CandidVariantValue<
+          T,
+          K
+        > extends null
+          ? never
+          : K]: CandidVariantValue<T, K>
+      }
+    : T
+
+/**
+ * A type that represents the extracted key and value from a variant
+ * Designed to be used with the extractVariant function
+ */
+export type CandidKeyValue<T> = T extends infer U
+  ? [
+      CandidVariantKey<U> & string,
+      CandidVariantValue<U, CandidVariantKey<U> & string>,
+    ]
+  : never

package/src/utils/agent.ts

@@ -0,0 +1,201 @@
+import type {
+  ApiQueryResponse,
+  HttpAgent,
+  HttpDetailsResponse,
+  PollingOptions,
+  SubmitResponse,
+} from "@icp-sdk/core/agent"
+import { Principal } from "@icp-sdk/core/principal"
+
+import {
+  isV2ResponseBody,
+  isV4ResponseBody,
+  Certificate,
+  lookupResultToBuffer,
+  pollForResponse,
+  QueryResponseStatus,
+  UncertifiedRejectErrorCode,
+  RejectError,
+  UncertifiedRejectUpdateErrorCode,
+  CertifiedRejectErrorCode,
+  MissingRootKeyErrorCode,
+  ExternalError,
+  UnknownError,
+  UnexpectedErrorCode,
+} from "@icp-sdk/core/agent"
+
+// ══════════════════════════════════════════════════════════════════════
+// QUERY CALL RESPONSE PROCESSING
+// ══════════════════════════════════════════════════════════════════════
+
+/**
+ * Process a query call response following the exact logic from @icp-sdk/core/agent Actor.
+ *
+ * @param response - The query call response options
+ * @returns The raw reply bytes
+ * @throws CallError if the query was rejected
+ */
+export function processQueryCallResponse(
+  response: ApiQueryResponse,
+  canisterId: Principal,
+  methodName: string
+): Uint8Array {
+  switch (response.status) {
+    case QueryResponseStatus.Rejected: {
+      const uncertifiedRejectErrorCode = new UncertifiedRejectErrorCode(
+        response.requestId,
+        response.reject_code,
+        response.reject_message,
+        response.error_code,
+        response.signatures
+      )
+      uncertifiedRejectErrorCode.callContext = {
+        canisterId,
+        methodName,
+        httpDetails: response.httpDetails,
+      }
+      throw RejectError.fromCode(uncertifiedRejectErrorCode)
+    }
+
+    case QueryResponseStatus.Replied:
+      return response.reply.arg
+  }
+}
+
+// ══════════════════════════════════════════════════════════════════════
+// UPDATE CALL RESPONSE PROCESSING
+// ══════════════════════════════════════════════════════════════════════
+
+/**
+ * Process an update call response following the exact logic from @icp-sdk/core/agent Actor.
+ *
+ * This handles:
+ * - V4 responses with embedded certificate (sync call response)
+ * - V2 responses with immediate rejection
+ * - 202 responses that require polling
+ *
+ * @param result - The submit response from agent.call()
+ * @param canisterId - The target canister ID
+ * @param methodName - The method name being called
+ * @param agent - The HTTP agent
+ * @param pollingOptions - Options for polling
+ * @param blsVerify - Optional BLS verification function
+ * @returns The raw reply bytes
+ * @throws RejectError if the call was rejected
+ * @throws UnknownError if the response format is unexpected
+ */
+export async function processUpdateCallResponse(
+  result: SubmitResponse,
+  canisterId: Principal,
+  methodName: string,
+  agent: HttpAgent,
+  pollingOptions: PollingOptions
+): Promise<Uint8Array> {
+  let reply: Uint8Array | undefined
+  let certificate: Certificate | undefined
+
+  if (isV4ResponseBody(result.response.body)) {
+    if (agent.rootKey == null) {
+      throw ExternalError.fromCode(new MissingRootKeyErrorCode())
+    }
+    const cert = result.response.body.certificate
+    certificate = await Certificate.create({
+      certificate: cert,
+      rootKey: agent.rootKey,
+      principal: { canisterId },
+      agent,
+    })
+
+    const path = [new TextEncoder().encode("request_status"), result.requestId]
+    const status = new TextDecoder().decode(
+      lookupResultToBuffer(certificate.lookup_path([...path, "status"]))
+    )
+
+    switch (status) {
+      case "replied":
+        reply = lookupResultToBuffer(
+          certificate.lookup_path([...path, "reply"])
+        )
+        break
+      case "rejected": {
+        // Find rejection details in the certificate
+        const rejectCode = new Uint8Array(
+          lookupResultToBuffer(
+            certificate.lookup_path([...path, "reject_code"])
+          )!
+        )[0]
+        const rejectMessage = new TextDecoder().decode(
+          lookupResultToBuffer(
+            certificate.lookup_path([...path, "reject_message"])
+          )!
+        )
+
+        const error_code_buf = lookupResultToBuffer(
+          certificate.lookup_path([...path, "error_code"])
+        )
+        const error_code = error_code_buf
+          ? new TextDecoder().decode(error_code_buf)
+          : undefined
+
+        const certifiedRejectErrorCode = new CertifiedRejectErrorCode(
+          result.requestId,
+          rejectCode,
+          rejectMessage,
+          error_code
+        )
+        certifiedRejectErrorCode.callContext = {
+          canisterId,
+          methodName,
+          httpDetails: result.response,
+        }
+        throw RejectError.fromCode(certifiedRejectErrorCode)
+      }
+    }
+  } else if (isV2ResponseBody(result.response.body)) {
+    const { reject_code, reject_message, error_code } = result.response.body
+    const errorCode = new UncertifiedRejectUpdateErrorCode(
+      result.requestId,
+      reject_code,
+      reject_message,
+      error_code
+    )
+    errorCode.callContext = {
+      canisterId,
+      methodName,
+      httpDetails: result.response,
+    }
+    throw RejectError.fromCode(errorCode)
+  }
+
+  // Fall back to polling if we receive an Accepted response code
+  if (result.response.status === 202) {
+    // Contains the certificate and the reply from the boundary node
+    const response = await pollForResponse(
+      agent,
+      canisterId,
+      result.requestId,
+      pollingOptions
+    )
+    certificate = response.certificate
+    reply = response.reply
+  }
+
+  if (reply !== undefined) {
+    return reply
+  }
+
+  // Unexpected response format
+  const httpDetails = {
+    ...result.response,
+    requestDetails: result.requestDetails,
+  } as HttpDetailsResponse
+  const errorCode = new UnexpectedErrorCode(
+    `Call was returned undefined. We cannot determine if the call was successful or not.`
+  )
+  errorCode.callContext = {
+    canisterId,
+    methodName,
+    httpDetails,
+  }
+  throw UnknownError.fromCode(errorCode)
+}

package/src/utils/candid.ts

@@ -0,0 +1,112 @@
+import {
+  CandidVariant,
+  CandidVariantKey,
+  CandidVariantValue,
+  CandidKeyValue,
+} from "../types"
+
+/**
+ * Creates a Candid variant from a string value.
+ * @param str - The string to convert into a variant
+ * @returns An object representing the Candid variant
+ */
+export function createNullVariant<T extends string>(str: T): Record<T, null> {
+  return { [str]: null } as Record<T, null>
+}
+
+/**
+ * Creates a Candid variant from a record.
+ * @param variant - The record to convert into a variant
+ * @returns An object representing the Candid variant
+ */
+export function createVariant<T extends Record<string, any>>(
+  variant: T
+): CandidVariant<T> {
+  const keys = Object.keys(variant)
+  if (keys.length !== 1) {
+    throw new Error(`
+      Invalid variant: must have exactly one key but found ${keys.length} keys: ${keys.map(
+        (key) => `${key}: ${variant[key]}`
+      )}
+    `)
+  }
+  const key = keys[0] as keyof T
+  const value = variant[key]
+
+  return {
+    _type: key,
+    ...(value !== null ? { [key]: value } : {}),
+  } as CandidVariant<T>
+}
+
+/**
+ * Extract variant key and value from a variant type
+ * Works with types like:
+ * type User = { 'Business': BusinessUser } | { 'Individual': IndividualUser }
+ *
+ * @template T - The variant type
+ * @returns A tuple containing the key and value of the variant
+ * @throws Error if the variant object does not have exactly one key
+ */
+export function getVariantKeyValue<T extends Record<string, any>>(
+  variant: T
+): CandidKeyValue<T> {
+  const keys = Object.keys(variant)
+  if (keys.length !== 1) {
+    const msg = `Invalid variant: must have exactly one key but found ${keys.length} keys: ${keys}`
+    throw new Error(msg)
+  }
+  const key = keys[0] as CandidKeyValue<T>[0]
+  const value = variant[key] as CandidKeyValue<T>[1]
+
+  return [key, value] as CandidKeyValue<T>
+}
+
+/**
+ * Extracts the key from a Candid variant type.
+ * Variants in Candid are represented as objects with a single key-value pair.
+ * @param variant - The variant object
+ * @returns The key of the variant
+ */
+export function getVariantKey<T extends Record<string, any>>(
+  variant: T
+): CandidVariantKey<T> {
+  const keys = Object.keys(variant)
+  if (keys.length !== 1) {
+    throw new Error(
+      `Invalid variant: must have exactly one key but found ${keys}`
+    )
+  }
+  return keys[0] as CandidVariantKey<T>
+}
+
+/**
+ * Extracts the value from a Candid variant type.
+ * @param variant - The variant object
+ * @returns The value associated with the variant's key
+ */
+export function getVariantValue<
+  T extends Record<string, any>,
+  K extends CandidVariantKey<T> = CandidVariantKey<T>,
+>(variant: T): CandidVariantValue<T, K> {
+  return variant[getVariantKey(variant)]
+}
+
+export function getVariantValueByKey<
+  T extends Record<string, any>,
+  K extends CandidVariantKey<T>,
+>(variant: T, key: K): CandidVariantValue<T, K> {
+  if (getVariantKey(variant) !== key) {
+    throw new Error(
+      `Variant key mismatch: expected ${key}, got ${getVariantKey(variant)}`
+    )
+  }
+  return variant[key]
+}
+
+export function isKeyMatchVariant<
+  T extends Record<string, any>,
+  K extends CandidVariantKey<T>,
+>(variant: T, key: K): variant is T & Record<K, unknown> {
+  return getVariantKey(variant) === key
+}

package/src/utils/constants.ts

@@ -0,0 +1,12 @@
+export const REMOTE_HOSTS = [".github.dev", ".gitpod.io"]
+
+export const LOCAL_HOSTS = ["localhost", "127.0.0.1"]
+
+export const IC_HOST_NETWORK_URI = "https://ic0.app"
+
+export const LOCAL_HOST_NETWORK_URI = "http://127.0.0.1:4943"
+
+export const IC_INTERNET_IDENTITY_PROVIDER = "https://id.ai"
+
+export const LOCAL_INTERNET_IDENTITY_PROVIDER =
+  "http://rdmx6-jaaaa-aaaaa-aaadq-cai.localhost:4943"