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

package/dist/errors/index.d.ts

@@ -0,0 +1,118 @@
+import { NullishType } from "../display/types";
+/**
+ * Interface representing the generic shape of an API error.
+ */
+export interface ApiError {
+    code: string;
+    message: NullishType<string>;
+    details: NullishType<Map<string, string>>;
+}
+/**
+ * Error thrown when there's an issue calling the canister.
+ * This includes network errors, agent errors, canister not found, etc.
+ */
+export declare class CallError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Error thrown when the canister returns an Err result.
+ * The `err` property contains the typed error value from the canister.
+ *
+ * It also supports accessing `code`, `message`, and `details` directly
+ * if the error object follows the common API error format or is a variant.
+ *
+ * @typeParam E - The type of the error value from the canister
+ */
+export declare class CanisterError<E = unknown> extends Error {
+    /** The raw error value from the canister */
+    readonly err: E;
+    /** The error code, extracted from the error object or variant key */
+    readonly code: string;
+    /** Optional error details Map */
+    readonly details: NullishType<Map<string, string>>;
+    constructor(err: E);
+    /**
+     * Type guard to check if an error object follows the API error format.
+     */
+    static isApiError(error: unknown): error is ApiError;
+    /**
+     * Factory method to create a CanisterError from any error.
+     * If the input is already a CanisterError, it returns it.
+     * If it's an API error shape, it wraps it.
+     * Otherwise, it creates a new CanisterError with an "UNKNOWN_ERROR" code.
+     */
+    static create(error: unknown, message?: string): CanisterError;
+}
+/**
+ * Type guard to check if an error is a CanisterError.
+ * Preserves the generic type E from the input when used in type narrowing.
+ *
+ * @example
+ * ```typescript
+ * // err is typed as CanisterError<TransferError> | CallError
+ * if (isCanisterError(err)) {
+ *   // err.err is typed as TransferError (preserved!)
+ *   console.log(err.err)
+ * }
+ * ```
+ */
+export declare function isCanisterError<E>(error: CanisterError<E> | CallError): error is CanisterError<E>;
+export declare function isCanisterError(error: unknown): error is CanisterError<unknown>;
+/**
+ * Type guard to check if an error is a CallError
+ */
+export declare function isCallError(error: unknown): error is CallError;
+/**
+ * Represents a single validation issue
+ */
+export interface ValidationIssue {
+    /** Path to the invalid field (e.g., ["to", "amount"]) */
+    path: (string | number)[];
+    /** Human-readable error message */
+    message: string;
+    /** Validation code (e.g., "required", "min_length") */
+    code?: string;
+}
+/**
+ * Error thrown when argument validation fails before calling the canister.
+ * Contains detailed information about which fields failed validation.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await reactor.callMethod({
+ *     functionName: "transfer",
+ *     args: [{ to: "", amount: -100 }],
+ *   })
+ * } catch (error) {
+ *   if (isValidationError(error)) {
+ *     console.log(error.issues)
+ *     // [
+ *     //   { path: ["to"], message: "Recipient is required" },
+ *     //   { path: ["amount"], message: "Amount must be positive" }
+ *     // ]
+ *   }
+ * }
+ * ```
+ */
+export declare class ValidationError extends Error {
+    /** Array of validation issues */
+    readonly issues: ValidationIssue[];
+    /** The method name that failed validation */
+    readonly methodName: string;
+    constructor(methodName: string, issues: ValidationIssue[]);
+    /**
+     * Get issues for a specific field path
+     */
+    getIssuesForPath(path: string): ValidationIssue[];
+    /**
+     * Check if a specific field has errors
+     */
+    hasErrorForPath(path: string): boolean;
+}
+/**
+ * Type guard to check if an error is a ValidationError
+ */
+export declare function isValidationError(error: unknown): error is ValidationError;
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC5B,OAAO,EAAE,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAC1C;AAED;;;GAGG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,SAAgB,KAAK,CAAC,EAAE,OAAO,CAAA;gBAEnB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAU7C;AAED;;;;;;;;GAQG;AACH,qBAAa,aAAa,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,KAAK;IACnD,4CAA4C;IAC5C,SAAgB,GAAG,EAAE,CAAC,CAAA;IACtB,qEAAqE;IACrE,SAAgB,IAAI,EAAE,MAAM,CAAA;IAC5B,iCAAiC;IACjC,SAAgB,OAAO,EAAE,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;gBAE7C,GAAG,EAAE,CAAC;IAsDlB;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ;IAQpD;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa;CAkB/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,GAClC,KAAK,IAAI,aAAa,CAAC,CAAC,CAAC,CAAA;AAC5B,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAAC,OAAO,CAAC,CAAA;AAOhF;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAMD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;IACzB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,iCAAiC;IACjC,SAAgB,MAAM,EAAE,eAAe,EAAE,CAAA;IACzC,6CAA6C;IAC7C,SAAgB,UAAU,EAAE,MAAM,CAAA;gBAEtB,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE;IAazD;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,EAAE;IAIjD;;OAEG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAGvC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E"}

package/dist/errors/index.js

@@ -0,0 +1,204 @@
+/**
+ * Error thrown when there's an issue calling the canister.
+ * This includes network errors, agent errors, canister not found, etc.
+ */
+export class CallError extends Error {
+    constructor(message, cause) {
+        super(message);
+        Object.defineProperty(this, "cause", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "CallError";
+        this.cause = cause;
+        // Maintains proper stack trace for where our error was thrown
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, CallError);
+        }
+    }
+}
+/**
+ * Error thrown when the canister returns an Err result.
+ * The `err` property contains the typed error value from the canister.
+ *
+ * It also supports accessing `code`, `message`, and `details` directly
+ * if the error object follows the common API error format or is a variant.
+ *
+ * @typeParam E - The type of the error value from the canister
+ */
+export class CanisterError extends Error {
+    constructor(err) {
+        let code;
+        let message;
+        let details = undefined;
+        let isApiShape = false;
+        if (typeof err === "object" && err !== null) {
+            // 1. Check for structured ApiError shape (has code)
+            if ("code" in err && typeof err.code === "string") {
+                code = err.code;
+                isApiShape = true;
+                if ("message" in err && typeof err.message === "string") {
+                    message = err.message;
+                }
+                if ("details" in err) {
+                    details = err.details;
+                }
+            }
+            // 2. Check for ic-reactor transformed variant shape (_type)
+            else if ("_type" in err && typeof err._type === "string") {
+                code = err._type;
+            }
+            // 3. Simple variant check (single key object)
+            else {
+                const keys = Object.keys(err);
+                if (keys.length === 1) {
+                    code = keys[0];
+                }
+            }
+        }
+        const finalCode = code ?? "UNKNOWN_ERROR";
+        const finalMessage = message ??
+            (typeof err === "object" && err !== null
+                ? JSON.stringify(err, (_, v) => (typeof v === "bigint" ? v.toString() : v), 2)
+                : String(err));
+        super(isApiShape ? finalMessage : `Canister Error: ${finalMessage}`);
+        /** The raw error value from the canister */
+        Object.defineProperty(this, "err", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The error code, extracted from the error object or variant key */
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Optional error details Map */
+        Object.defineProperty(this, "details", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "CanisterError";
+        this.err = err;
+        this.code = finalCode;
+        this.details = details;
+        // Maintains proper stack trace for where our error was thrown
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, CanisterError);
+        }
+    }
+    /**
+     * Type guard to check if an error object follows the API error format.
+     */
+    static isApiError(error) {
+        if (typeof error !== "object" || error === null) {
+            return false;
+        }
+        return "code" in error && "message" in error && "details" in error;
+    }
+    /**
+     * Factory method to create a CanisterError from any error.
+     * If the input is already a CanisterError, it returns it.
+     * If it's an API error shape, it wraps it.
+     * Otherwise, it creates a new CanisterError with an "UNKNOWN_ERROR" code.
+     */
+    static create(error, message) {
+        if (error instanceof CanisterError) {
+            return error;
+        }
+        if (CanisterError.isApiError(error)) {
+            return new CanisterError(error);
+        }
+        return new CanisterError({
+            code: "UNKNOWN_ERROR",
+            message: error instanceof Error
+                ? error.message
+                : message || "An unknown error occurred",
+            details: undefined,
+        });
+    }
+}
+export function isCanisterError(error) {
+    return error instanceof CanisterError;
+}
+/**
+ * Type guard to check if an error is a CallError
+ */
+export function isCallError(error) {
+    return error instanceof CallError;
+}
+/**
+ * Error thrown when argument validation fails before calling the canister.
+ * Contains detailed information about which fields failed validation.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await reactor.callMethod({
+ *     functionName: "transfer",
+ *     args: [{ to: "", amount: -100 }],
+ *   })
+ * } catch (error) {
+ *   if (isValidationError(error)) {
+ *     console.log(error.issues)
+ *     // [
+ *     //   { path: ["to"], message: "Recipient is required" },
+ *     //   { path: ["amount"], message: "Amount must be positive" }
+ *     // ]
+ *   }
+ * }
+ * ```
+ */
+export class ValidationError extends Error {
+    constructor(methodName, issues) {
+        const messages = issues.map((i) => i.message).join(", ");
+        super(`Validation failed for "${methodName}": ${messages}`);
+        /** Array of validation issues */
+        Object.defineProperty(this, "issues", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The method name that failed validation */
+        Object.defineProperty(this, "methodName", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "ValidationError";
+        this.methodName = methodName;
+        this.issues = issues;
+        // Maintains proper stack trace for where our error was thrown
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ValidationError);
+        }
+    }
+    /**
+     * Get issues for a specific field path
+     */
+    getIssuesForPath(path) {
+        return this.issues.filter((issue) => issue.path.includes(path));
+    }
+    /**
+     * Check if a specific field has errors
+     */
+    hasErrorForPath(path) {
+        return this.issues.some((issue) => issue.path.includes(path));
+    }
+}
+/**
+ * Type guard to check if an error is a ValidationError
+ */
+export function isValidationError(error) {
+    return error instanceof ValidationError;
+}
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

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

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-export * from "./createReactorCore";
-export * from "./createReactorStore";
-export * from "./createCandidAdapter";
-export * from "./createActorManager";
-export * from "./createAgentManager";
-export * as classes from "./classes";
-export * as types from "./types";
-export * as utils from "./utils";
+export * from "./reactor";
+export * from "./client";
+export * from "./utils";
+export * from "./display";
+export * from "./display-reactor";
+export * from "./types";
+export * from "./errors";
+export * from "./version";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,mBAAmB,CAAA;AACjC,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA"}

package/dist/index.js

@@ -1,47 +1,9 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.utils = exports.types = exports.classes = void 0;
-__exportStar(require("./createReactorCore"), exports);
-__exportStar(require("./createReactorStore"), exports);
-__exportStar(require("./createCandidAdapter"), exports);
-__exportStar(require("./createActorManager"), exports);
-__exportStar(require("./createAgentManager"), exports);
-exports.classes = __importStar(require("./classes"));
-exports.types = __importStar(require("./types"));
-exports.utils = __importStar(require("./utils"));
+export * from "./reactor";
+export * from "./client";
+export * from "./utils";
+export * from "./display";
+export * from "./display-reactor";
+export * from "./types";
+export * from "./errors";
+export * from "./version";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,mBAAmB,CAAA;AACjC,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA"}

package/dist/reactor.d.ts

@@ -0,0 +1,133 @@
+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 } from "./types/reactor";
+import { IDL } from "@icp-sdk/core/candid";
+import { Principal } from "@icp-sdk/core/principal";
+/**
+ * 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 declare class Reactor<A = BaseActor, T extends TransformKey = "candid"> {
+    /** Phantom type brand for inference - never assigned at runtime */
+    readonly _actor: A;
+    readonly transform: T;
+    clientManager: ClientManager;
+    name: string;
+    canisterId: Principal;
+    service: IDL.ServiceClass;
+    pollingOptions: PollingOptions;
+    constructor(config: ReactorParameters<A>);
+    protected verifyCanister(): void;
+    /**
+     * Get the service interface (IDL.ServiceClass) for this reactor.
+     * Useful for introspection and codec generation.
+     * @returns The service interface
+     */
+    getServiceInterface(): IDL.ServiceClass;
+    /**
+     * 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;
+    /**
+     * Check if a method is a query method (query or composite_query).
+     */
+    protected isQueryMethod<M extends FunctionName<A>>(methodName: M): boolean;
+    /**
+     * 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]>;
+    /**
+     * 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>;
+    generateQueryKey<M extends FunctionName<A>>(params: ReactorQueryParams<A, M, T>): QueryKey;
+    getQueryOptions<M extends FunctionName<A>>(params: ReactorCallParams<A, M, T>): FetchQueryOptions<ReactorReturnOk<A, M, T>>;
+    /**
+     * 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'] })
+     * ```
+     */
+    invalidateQueries<M extends FunctionName<A>>(params?: Partial<ReactorQueryParams<A, M, T>>): void;
+    /**
+     * 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 },
+     * });
+     * ```
+     */
+    callMethod<M extends FunctionName<A>>(params: Omit<ReactorCallParams<A, M, T>, "queryKey">): Promise<ReactorReturnOk<A, M, T>>;
+    /**
+     * Fetch data from the canister and cache it using React Query.
+     * This method ensures the data is in the cache and returns it.
+     */
+    fetchQuery<M extends FunctionName<A>>(params: ReactorCallParams<A, M, T>): Promise<ReactorReturnOk<A, M, T>>;
+    /**
+     * Get the current data from the cache without fetching.
+     */
+    getQueryData<M extends FunctionName<A>>(params: ReactorQueryParams<A, M, T>): ReactorReturnOk<A, M, T> | undefined;
+    /**
+     * Execute a query call using agent.query()
+     */
+    protected executeQuery(methodName: string, arg: Uint8Array, callConfig?: CallConfig): Promise<Uint8Array>;
+    /**
+     * Execute an update call using agent.call()
+     */
+    protected executeCall(methodName: string, arg: Uint8Array, callConfig?: CallConfig): Promise<Uint8Array>;
+    /**
+     * Get the subnet ID for this canister.
+     */
+    subnetId(): Promise<Principal>;
+    /**
+     * Get the subnet state for this canister.
+     */
+    subnetState(options: ReadStateOptions): Promise<import("@icp-sdk/core/agent").ReadStateResponse>;
+    /**
+     * Get the query client from clientManager.
+     * This is the recommended way to access the query client for direct queries.
+     */
+    get queryClient(): import("@tanstack/query-core").QueryClient;
+    /**
+     * Get the agent from clientManager.
+     * This is the recommended way to access the agent for direct calls.
+     */
+    get agent(): import("@icp-sdk/core/agent").HttpAgent;
+}
+//# sourceMappingURL=reactor.d.ts.map

package/dist/reactor.d.ts.map

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