@dfinity/pic 0.12.0-b0

package/README.md

@@ -0,0 +1,73 @@
+# Pic JS
+
+Pic JS is a library for interacting with a local instance of `pocket-ic` from TypeScript.
+
+The `pocket-ic` is a canister testing platform for the [Internet Computer](https://internetcomputer.org/). It is a standalone executable that can be used to test canisters locally, without the need to deploy them to a full replica.
+
+Other languages available include [Python](https://github.com/dfinity/pocketic-py/) and [Rust](https://github.com/dfinity/ic/tree/master/packages/pocket-ic).
+
+## Installation
+
+```shell
+npm i -D @dfinity/pic
+```
+
+Install peer dependencies if they are not already installed:
+
+```shell
+npm i -D @dfinity/{agent,candid,identity,principal}
+```
+
+## Usage
+
+The easiest way to use PocketIC is to use `setupCanister` convenience method:
+
+```ts
+import { PocketIc } from '@dfinity/pic';
+import { _SERVICE, idlFactory } from '../declarations';
+
+const wasmPath = resolve('..', '..', 'canister.wasm');
+
+const pic = await PocketIc.create();
+const fixture = await pic.setupCanister<_SERVICE>(idlFactory, wasmPath);
+const { actor } = fixture;
+
+// perform tests...
+
+await pic.tearDown();
+```
+
+If more control is needed, then the `createCanister`, `installCode` and `createActor` methods can be used directly:
+
+```ts
+import { PocketIc } from '@dfinity/pic';
+import { _SERVICE, idlFactory } from '../declarations';
+
+const wasmPath = resolve('..', '..', 'canister.wasm');
+
+const pic = await PocketIc.create();
+
+const canisterId = await pic.createCanister();
+await pic.installCode(canisterId, wasmPath);
+const actor = pic.createActor<_SERVICE>(idlFactory, canisterId);
+
+// perform tests...
+
+await pic.tearDown();
+```
+
+## Documentation
+
+More detailed documentation is available over at [dfinity.github.io/pic-js](https://dfinity.github.io/pic-js/).
+
+## Examples
+
+All examples are written in [TypeScript](https://www.typescriptlang.org/) with [Jest](https://jestjs.io/) as the test runner,
+but `@dfinity/pic` can be used with JavaScript and any other testing runner, such as [NodeJS](https://nodejs.org/dist/latest-v20.x/docs/api/test.html), [bun](https://bun.sh/docs/cli/test) or [Mocha](https://mochajs.org/).
+
+- The [Counter](https://github.com/dfinity/pic-js/tree/main/examples/counter/README.md) example demonstrates how to work with a simple canister as well as init arguments, canister upgrades and WASM reinstallation.
+- The [Clock](https://github.com/dfinity/pic-js/tree/main/examples/clock/README.md) example demonstrates how to work with the replica's system time, canister timers as well as checking for canister existence and cycle management.
+- The [Todo](https://github.com/dfinity/pic-js/tree/main/examples/todo/README.md) example demonstrates how to work with more complex canisters, identities, canister upgrades, and stable memory management.
+- The [Multicanister](https://github.com/dfinity/pic-js/tree/main/examples/multicanister/README.md) example demonstrates how to work with multiple canisters and multiple subnets.
+- The [NNS Proxy](https://github.com/dfinity/pic-js/tree/main/examples/nns_proxy/README.md) example demonstrates how to work with an NNS state directory.
+- [Google Search](https://github.com/dfinity/pic-js/tree/main/examples/google_search/README.md) example demonstrates how to mock HTTPS Outcalls.

package/dist/error.d.ts

@@ -0,0 +1,21 @@
+export declare class BinStartError extends Error {
+    constructor(cause: Error);
+}
+export declare class BinStartMacOSArmError extends Error {
+    constructor(cause: Error);
+}
+export declare class BinNotFoundError extends Error {
+    constructor(picBinPath: string);
+}
+export declare class BinTimeoutError extends Error {
+    constructor();
+}
+export declare class ServerRequestTimeoutError extends Error {
+    constructor();
+}
+export declare class InstanceDeletedError extends Error {
+    constructor();
+}
+export declare class TopologyValidationError extends Error {
+    constructor();
+}

package/dist/error.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TopologyValidationError = exports.InstanceDeletedError = exports.ServerRequestTimeoutError = exports.BinTimeoutError = exports.BinNotFoundError = exports.BinStartMacOSArmError = exports.BinStartError = void 0;
+class BinStartError extends Error {
+    constructor(cause) {
+        super(`There was an error starting the PocketIC Binary.
+
+Original error: ${cause.name} ${cause.message}.
+${cause.stack}`, { cause });
+    }
+}
+exports.BinStartError = BinStartError;
+class BinStartMacOSArmError extends Error {
+    constructor(cause) {
+        super(`There was an error starting the PocketIC Binary.
+
+It seems you are running on an Apple Silicon Mac. The PocketIC binary can not run with the ARM architecture on Apple Silicon Macs.
+Please install and enable Rosetta if it is not enabled and try again.
+
+Original error: ${cause.name} ${cause.message}.
+${cause.stack}`, { cause });
+    }
+}
+exports.BinStartMacOSArmError = BinStartMacOSArmError;
+class BinNotFoundError extends Error {
+    constructor(picBinPath) {
+        super(`Could not find the PocketIC binary. The PocketIC binary could not be found at ${picBinPath}. Please try installing @dfinity/pic again.`);
+    }
+}
+exports.BinNotFoundError = BinNotFoundError;
+class BinTimeoutError extends Error {
+    constructor() {
+        super('The PocketIC binary took too long to start. Please try again.');
+    }
+}
+exports.BinTimeoutError = BinTimeoutError;
+class ServerRequestTimeoutError extends Error {
+    constructor() {
+        super('A request to the PocketIC server timed out.');
+    }
+}
+exports.ServerRequestTimeoutError = ServerRequestTimeoutError;
+class InstanceDeletedError extends Error {
+    constructor() {
+        super('This PocketIC instance has been torn down. Please create a new instance before interacting further with PocketIC.');
+    }
+}
+exports.InstanceDeletedError = InstanceDeletedError;
+class TopologyValidationError extends Error {
+    constructor() {
+        super('The provided subnet configuration is invalid. At least one subnet must be configured and the number of both application and system subnets must be at least 0 (non-negative).');
+    }
+}
+exports.TopologyValidationError = TopologyValidationError;
+//# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":";;;AAAA,MAAa,aAAc,SAAQ,KAAK;IACtC,YAAY,KAAY;QACtB,KAAK,CACH;;kBAEY,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO;EAC3C,KAAK,CAAC,KAAK,EAAE,EACT,EAAE,KAAK,EAAE,CACV,CAAC;IACJ,CAAC;CACF;AAVD,sCAUC;AAED,MAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,KAAY;QACtB,KAAK,CACH;;;;;kBAKY,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO;EAC3C,KAAK,CAAC,KAAK,EAAE,EACT,EAAE,KAAK,EAAE,CACV,CAAC;IACJ,CAAC;CACF;AAbD,sDAaC;AAED,MAAa,gBAAiB,SAAQ,KAAK;IACzC,YAAY,UAAkB;QAC5B,KAAK,CACH,iFAAiF,UAAU,6CAA6C,CACzI,CAAC;IACJ,CAAC;CACF;AAND,4CAMC;AAED,MAAa,eAAgB,SAAQ,KAAK;IACxC;QACE,KAAK,CAAC,+DAA+D,CAAC,CAAC;IACzE,CAAC;CACF;AAJD,0CAIC;AAED,MAAa,yBAA0B,SAAQ,KAAK;IAClD;QACE,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACvD,CAAC;CACF;AAJD,8DAIC;AAED,MAAa,oBAAqB,SAAQ,KAAK;IAC7C;QACE,KAAK,CACH,mHAAmH,CACpH,CAAC;IACJ,CAAC;CACF;AAND,oDAMC;AAED,MAAa,uBAAwB,SAAQ,KAAK;IAChD;QACE,KAAK,CACH,+KAA+K,CAChL,CAAC;IACJ,CAAC;CACF;AAND,0DAMC"}

package/dist/http2-client.d.ts

@@ -0,0 +1,27 @@
+export interface RequestOptions {
+    method: Method;
+    path: string;
+    headers?: RequestHeaders;
+    body?: Uint8Array;
+}
+export type RequestHeaders = RequestInit['headers'];
+export interface JsonGetRequest {
+    path: string;
+    headers?: RequestHeaders;
+}
+export interface JsonPostRequest<B> {
+    path: string;
+    headers?: RequestHeaders;
+    body?: B;
+}
+export type ResponseHeaders = ResponseInit['headers'];
+export type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';
+export declare const JSON_HEADER: RequestHeaders;
+export declare class Http2Client {
+    private readonly baseUrl;
+    private readonly processingTimeoutMs;
+    constructor(baseUrl: string, processingTimeoutMs: number);
+    request(init: RequestOptions): Promise<Response>;
+    jsonGet<R extends {}>(init: JsonGetRequest): Promise<R>;
+    jsonPost<B, R extends {}>(init: JsonPostRequest<B>): Promise<R>;
+}

package/dist/http2-client.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Http2Client = exports.JSON_HEADER = void 0;
+const error_1 = require("./error");
+const util_1 = require("./util");
+exports.JSON_HEADER = {
+    'Content-Type': 'application/json',
+};
+class Http2Client {
+    baseUrl;
+    processingTimeoutMs;
+    constructor(baseUrl, processingTimeoutMs) {
+        this.baseUrl = baseUrl;
+        this.processingTimeoutMs = processingTimeoutMs;
+    }
+    request(init) {
+        const timeoutAbortController = new AbortController();
+        const requestAbortController = new AbortController();
+        const cancelAfterTimeout = async () => {
+            return await new Promise((_, reject) => {
+                const timeoutId = setTimeout(() => {
+                    requestAbortController.abort();
+                    reject(new error_1.ServerRequestTimeoutError());
+                }, this.processingTimeoutMs);
+                timeoutAbortController.signal.addEventListener('abort', () => {
+                    clearTimeout(timeoutId);
+                    reject(new error_1.ServerRequestTimeoutError());
+                });
+            });
+        };
+        const makeRequest = async () => {
+            const url = `${this.baseUrl}${init.path}`;
+            const res = await fetch(url, {
+                method: init.method,
+                headers: init.headers,
+                body: init.body,
+                signal: requestAbortController.signal,
+            });
+            timeoutAbortController.abort();
+            return res;
+        };
+        return Promise.race([makeRequest(), cancelAfterTimeout()]);
+    }
+    async jsonGet(init) {
+        // poll the request until it is successful or times out
+        return await (0, util_1.poll)(async () => {
+            const res = await this.request({
+                method: 'GET',
+                path: init.path,
+                headers: { ...init.headers, ...exports.JSON_HEADER },
+            });
+            const resBody = (await res.json());
+            if (!resBody) {
+                return resBody;
+            }
+            // server encountered an error, throw and try again
+            if ('message' in resBody) {
+                console.error('PocketIC server encountered an error', resBody.message);
+                throw new Error(resBody.message);
+            }
+            // the server has started processing or is busy
+            if ('state_label' in resBody) {
+                // the server is too busy to process the request, throw and try again
+                if (res.status === 409) {
+                    throw new Error('Server busy');
+                }
+                // the server has started processing the request
+                // this shouldn't happen for GET requests, throw and try again
+                if (res.status === 202) {
+                    throw new Error('Server started processing');
+                }
+                // something weird happened, throw and try again
+                throw new Error('Unknown state');
+            }
+            // the request was successful, exit the loop
+            return resBody;
+        }, { intervalMs: POLLING_INTERVAL_MS, timeoutMs: this.processingTimeoutMs });
+    }
+    async jsonPost(init) {
+        const reqBody = init.body
+            ? new TextEncoder().encode(JSON.stringify(init.body))
+            : undefined;
+        // poll the request until it is successful or times out
+        return await (0, util_1.poll)(async () => {
+            const res = await this.request({
+                method: 'POST',
+                path: init.path,
+                headers: { ...init.headers, ...exports.JSON_HEADER },
+                body: reqBody,
+            });
+            const resBody = (await res.json());
+            if ((0, util_1.isNil)(resBody)) {
+                return resBody;
+            }
+            // server encountered an error, throw and try again
+            if ('message' in resBody) {
+                console.error('PocketIC server encountered an error', resBody.message);
+                throw new Error(resBody.message);
+            }
+            // the server has started processing or is busy
+            if ('state_label' in resBody) {
+                // the server is too busy to process the request, throw and try again
+                if (res.status === 409) {
+                    throw new Error('Server busy');
+                }
+                // the server has started processing the request, poll until it is done
+                if (res.status === 202) {
+                    return await (0, util_1.poll)(async () => {
+                        const stateRes = await this.request({
+                            method: 'GET',
+                            path: `/read_graph/${resBody.state_label}/${resBody.op_id}`,
+                        });
+                        const stateBody = (await stateRes.json());
+                        // the server encountered an error, throw and try again
+                        if ((0, util_1.isNil)(stateBody) ||
+                            'message' in stateBody ||
+                            'state_label' in stateBody) {
+                            throw new Error('Polling has not succeeded yet');
+                        }
+                        // the request was successful, exit the loop
+                        return stateBody;
+                    }, {
+                        intervalMs: POLLING_INTERVAL_MS,
+                        timeoutMs: this.processingTimeoutMs,
+                    });
+                }
+                // something weird happened, throw and try again
+                throw new Error('Unknown state');
+            }
+            // the request was successful, exit the loop
+            return resBody;
+        }, { intervalMs: POLLING_INTERVAL_MS, timeoutMs: this.processingTimeoutMs });
+    }
+}
+exports.Http2Client = Http2Client;
+const POLLING_INTERVAL_MS = 10;
+//# sourceMappingURL=http2-client.js.map

package/dist/http2-client.js.map

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

package/dist/identity.d.ts

@@ -0,0 +1,74 @@
+import { Identity } from '@dfinity/agent';
+/**
+ * Create an Identity from a seed phrase.
+ * The seed phrase can be any arbitrary string.
+ *
+ * The Identity is generated deterministically from the seed phrase,
+ * so subsequent calls to this function with the same seed phrase will
+ * produce the same Identity.
+ *
+ * This is useful for tests where a persistent Identity is necessary
+ * but it's easier to store the seed phrase than the Identity itself.
+ *
+ * @category API
+ * @param seedPhrase The seed phrase to create the identity from. Can be any arbitrary string.
+ * @returns An identity created from the seed phrase.
+ *
+ * @see [Identity](https://agent-js.icp.xyz/agent/interfaces/Identity.html)
+ *
+ * @example
+ * ```ts
+ * import { PocketIc, PocketIcServer, createIdentity } from '@dfinity/pic';
+ * import { AnonymousIdentity } from '@dfinity/agent';
+ * import { _SERVICE, idlFactory } from '../declarations';
+ *
+ * const wasmPath = resolve('..', '..', 'canister.wasm');
+ *
+ * const picServer = await PocketIcServer.create();
+ * const pic = await PocketIc.create(picServer.getUrl());
+ * const fixture = await pic.setupCanister<_SERVICE>(idlFactory, wasmPath);
+ * const { actor } = fixture;
+ *
+ * const bob = createIdentity('SuperSecretSeedPhraseForBob');
+ * actor.setIdentity(bob);
+ *
+ * await pic.tearDown();
+ * await picServer.stop();
+ * ```
+ */
+export declare function createIdentity(seedPhrase: string): Identity;
+/**
+ * Create an Identity from a randomly generated bip39 seed phrase.
+ * Subsequent calls to this function will produce different Identities
+ * with an extremely low probability of collision.
+ *
+ * This is useful for tests where it is important to avoid conflicts arising
+ * from multiple identities accessing the same canister and maintaining
+ * the necessary seed phrases would become cumbersome.
+ *
+ * @category API
+ * @returns An identity created from a random seed phrase.
+ *
+ * @see [Identity](https://agent-js.icp.xyz/agent/interfaces/Identity.html)
+ *
+ * @example
+ * ```ts
+ * import { PocketIc, PocketIcServer, generateRandomIdentity } from '@dfinity/pic';
+ * import { AnonymousIdentity } from '@dfinity/agent';
+ * import { _SERVICE, idlFactory } from '../declarations';
+ *
+ * const wasmPath = resolve('..', '..', 'canister.wasm');
+ *
+ * const picServer = await PocketIcServer.create();
+ * const pic = await PocketIc.create(picServer.getUrl());
+ * const fixture = await pic.setupCanister<_SERVICE>(idlFactory, wasmPath);
+ * const { actor } = fixture;
+ *
+ * const bob = generateRandomIdentity();
+ * actor.setIdentity(bob);
+ *
+ * await pic.tearDown();
+ * await picServer.stop();
+ * ```
+ */
+export declare function generateRandomIdentity(): Identity;

package/dist/identity.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createIdentity = createIdentity;
+exports.generateRandomIdentity = generateRandomIdentity;
+const node_crypto_1 = require("node:crypto");
+const bip39_1 = require("bip39");
+const identity_1 = require("@dfinity/identity");
+/**
+ * Create an Identity from a seed phrase.
+ * The seed phrase can be any arbitrary string.
+ *
+ * The Identity is generated deterministically from the seed phrase,
+ * so subsequent calls to this function with the same seed phrase will
+ * produce the same Identity.
+ *
+ * This is useful for tests where a persistent Identity is necessary
+ * but it's easier to store the seed phrase than the Identity itself.
+ *
+ * @category API
+ * @param seedPhrase The seed phrase to create the identity from. Can be any arbitrary string.
+ * @returns An identity created from the seed phrase.
+ *
+ * @see [Identity](https://agent-js.icp.xyz/agent/interfaces/Identity.html)
+ *
+ * @example
+ * ```ts
+ * import { PocketIc, PocketIcServer, createIdentity } from '@dfinity/pic';
+ * import { AnonymousIdentity } from '@dfinity/agent';
+ * import { _SERVICE, idlFactory } from '../declarations';
+ *
+ * const wasmPath = resolve('..', '..', 'canister.wasm');
+ *
+ * const picServer = await PocketIcServer.create();
+ * const pic = await PocketIc.create(picServer.getUrl());
+ * const fixture = await pic.setupCanister<_SERVICE>(idlFactory, wasmPath);
+ * const { actor } = fixture;
+ *
+ * const bob = createIdentity('SuperSecretSeedPhraseForBob');
+ * actor.setIdentity(bob);
+ *
+ * await pic.tearDown();
+ * await picServer.stop();
+ * ```
+ */
+function createIdentity(seedPhrase) {
+    const hash = (0, node_crypto_1.createHash)('sha256');
+    hash.update(seedPhrase);
+    const digest = hash.digest('hex').slice(0, 32);
+    const encodedDigest = new TextEncoder().encode(digest);
+    return identity_1.Ed25519KeyIdentity.generate(encodedDigest);
+}
+function generateMnemonic() {
+    const entropy = (0, node_crypto_1.randomBytes)(16);
+    return (0, bip39_1.entropyToMnemonic)(entropy);
+}
+/**
+ * Create an Identity from a randomly generated bip39 seed phrase.
+ * Subsequent calls to this function will produce different Identities
+ * with an extremely low probability of collision.
+ *
+ * This is useful for tests where it is important to avoid conflicts arising
+ * from multiple identities accessing the same canister and maintaining
+ * the necessary seed phrases would become cumbersome.
+ *
+ * @category API
+ * @returns An identity created from a random seed phrase.
+ *
+ * @see [Identity](https://agent-js.icp.xyz/agent/interfaces/Identity.html)
+ *
+ * @example
+ * ```ts
+ * import { PocketIc, PocketIcServer, generateRandomIdentity } from '@dfinity/pic';
+ * import { AnonymousIdentity } from '@dfinity/agent';
+ * import { _SERVICE, idlFactory } from '../declarations';
+ *
+ * const wasmPath = resolve('..', '..', 'canister.wasm');
+ *
+ * const picServer = await PocketIcServer.create();
+ * const pic = await PocketIc.create(picServer.getUrl());
+ * const fixture = await pic.setupCanister<_SERVICE>(idlFactory, wasmPath);
+ * const { actor } = fixture;
+ *
+ * const bob = generateRandomIdentity();
+ * actor.setIdentity(bob);
+ *
+ * await pic.tearDown();
+ * await picServer.stop();
+ * ```
+ */
+function generateRandomIdentity() {
+    const mnemonic = generateMnemonic();
+    return createIdentity(mnemonic);
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":";;AA0CA,wCAOC;AA0CD,wDAIC;AA/FD,6CAAsD;AACtD,iCAA0C;AAE1C,gDAAuD;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,SAAgB,cAAc,CAAC,UAAkB;IAC/C,MAAM,IAAI,GAAG,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACxB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/C,MAAM,aAAa,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAEvD,OAAO,6BAAkB,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,gBAAgB;IACvB,MAAM,OAAO,GAAG,IAAA,yBAAW,EAAC,EAAE,CAAC,CAAC;IAEhC,OAAO,IAAA,yBAAiB,EAAC,OAAO,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,SAAgB,sBAAsB;IACpC,MAAM,QAAQ,GAAG,gBAAgB,EAAE,CAAC;IAEpC,OAAO,cAAc,CAAC,QAAQ,CAAC,CAAC;AAClC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './identity';
+export * from './pocket-ic-actor';
+export * from './pocket-ic-deferred-actor';
+export * from './pocket-ic-server-types';
+export * from './pocket-ic-server';
+export * from './pocket-ic-types';
+export * from './pocket-ic';

package/dist/index.js

@@ -0,0 +1,24 @@
+"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 __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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./identity"), exports);
+__exportStar(require("./pocket-ic-actor"), exports);
+__exportStar(require("./pocket-ic-deferred-actor"), exports);
+__exportStar(require("./pocket-ic-server-types"), exports);
+__exportStar(require("./pocket-ic-server"), exports);
+__exportStar(require("./pocket-ic-types"), exports);
+__exportStar(require("./pocket-ic"), exports);
+//# 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,6CAA2B;AAC3B,oDAAkC;AAClC,6DAA2C;AAC3C,2DAAyC;AACzC,qDAAmC;AACnC,oDAAkC;AAClC,8CAA4B"}

package/dist/management-canister.d.ts

@@ -0,0 +1,45 @@
+import { IDL } from '@dfinity/candid';
+import { Principal } from '@dfinity/principal';
+export declare const MANAGEMENT_CANISTER_ID: Principal;
+export interface CanisterSettings {
+    controllers: [] | [Principal[]];
+    compute_allocation: [] | [bigint];
+    memory_allocation: [] | [bigint];
+    freezing_threshold: [] | [bigint];
+    reserved_cycles_limit: [] | [bigint];
+}
+export declare const CanisterSettings: IDL.RecordClass;
+export interface CreateCanisterRequest {
+    settings: [] | [CanisterSettings];
+    amount: [] | [bigint];
+    specified_id: [] | [Principal];
+}
+export declare function encodeCreateCanisterRequest(arg: CreateCanisterRequest): Uint8Array;
+export interface CreateCanisterResponse {
+    canister_id: Principal;
+}
+export declare function decodeCreateCanisterResponse(arg: Uint8Array): CreateCanisterResponse;
+export interface StartCanisterRequest {
+    canister_id: Principal;
+}
+export declare function encodeStartCanisterRequest(arg: StartCanisterRequest): Uint8Array;
+export interface StopCanisterRequest {
+    canister_id: Principal;
+}
+export declare function encodeStopCanisterRequest(arg: StopCanisterRequest): Uint8Array;
+export interface InstallCodeRequest {
+    arg: Uint8Array;
+    wasm_module: Uint8Array;
+    mode: {
+        reinstall?: null;
+        upgrade?: null;
+        install?: null;
+    };
+    canister_id: Principal;
+}
+export declare function encodeInstallCodeRequest(arg: InstallCodeRequest): Uint8Array;
+export interface UpdateCanisterSettingsRequest {
+    canister_id: Principal;
+    settings: CanisterSettings;
+}
+export declare function encodeUpdateCanisterSettingsRequest(arg: UpdateCanisterSettingsRequest): Uint8Array;

package/dist/management-canister.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CanisterSettings = exports.MANAGEMENT_CANISTER_ID = void 0;
+exports.encodeCreateCanisterRequest = encodeCreateCanisterRequest;
+exports.decodeCreateCanisterResponse = decodeCreateCanisterResponse;
+exports.encodeStartCanisterRequest = encodeStartCanisterRequest;
+exports.encodeStopCanisterRequest = encodeStopCanisterRequest;
+exports.encodeInstallCodeRequest = encodeInstallCodeRequest;
+exports.encodeUpdateCanisterSettingsRequest = encodeUpdateCanisterSettingsRequest;
+const candid_1 = require("@dfinity/candid");
+const principal_1 = require("@dfinity/principal");
+const util_1 = require("./util");
+exports.MANAGEMENT_CANISTER_ID = principal_1.Principal.fromText('aaaaa-aa');
+exports.CanisterSettings = candid_1.IDL.Record({
+    controllers: candid_1.IDL.Opt(candid_1.IDL.Vec(candid_1.IDL.Principal)),
+    compute_allocation: candid_1.IDL.Opt(candid_1.IDL.Nat),
+    memory_allocation: candid_1.IDL.Opt(candid_1.IDL.Nat),
+    freezing_threshold: candid_1.IDL.Opt(candid_1.IDL.Nat),
+    reserved_cycles_limit: candid_1.IDL.Opt(candid_1.IDL.Nat),
+});
+const CreateCanisterRequest = candid_1.IDL.Record({
+    settings: candid_1.IDL.Opt(exports.CanisterSettings),
+    amount: candid_1.IDL.Opt(candid_1.IDL.Nat),
+    specified_id: candid_1.IDL.Opt(candid_1.IDL.Principal),
+});
+function encodeCreateCanisterRequest(arg) {
+    return new Uint8Array(candid_1.IDL.encode([CreateCanisterRequest], [arg]));
+}
+const CreateCanisterResponse = candid_1.IDL.Record({
+    canister_id: candid_1.IDL.Principal,
+});
+function decodeCreateCanisterResponse(arg) {
+    const payload = (0, util_1.decodeCandid)([CreateCanisterResponse], arg);
+    if ((0, util_1.isNil)(payload)) {
+        throw new Error('Failed to decode CreateCanisterResponse');
+    }
+    return payload;
+}
+const StartCanisterRequest = candid_1.IDL.Record({
+    canister_id: candid_1.IDL.Principal,
+});
+function encodeStartCanisterRequest(arg) {
+    return new Uint8Array(candid_1.IDL.encode([StartCanisterRequest], [arg]));
+}
+const StopCanisterRequest = candid_1.IDL.Record({
+    canister_id: candid_1.IDL.Principal,
+});
+function encodeStopCanisterRequest(arg) {
+    return new Uint8Array(candid_1.IDL.encode([StopCanisterRequest], [arg]));
+}
+const InstallCodeRequest = candid_1.IDL.Record({
+    arg: candid_1.IDL.Vec(candid_1.IDL.Nat8),
+    wasm_module: candid_1.IDL.Vec(candid_1.IDL.Nat8),
+    mode: candid_1.IDL.Variant({
+        reinstall: candid_1.IDL.Null,
+        upgrade: candid_1.IDL.Null,
+        install: candid_1.IDL.Null,
+    }),
+    canister_id: candid_1.IDL.Principal,
+});
+function encodeInstallCodeRequest(arg) {
+    return new Uint8Array(candid_1.IDL.encode([InstallCodeRequest], [arg]));
+}
+const UpdateCanisterSettingsRequest = candid_1.IDL.Record({
+    canister_id: candid_1.IDL.Principal,
+    settings: exports.CanisterSettings,
+});
+function encodeUpdateCanisterSettingsRequest(arg) {
+    return new Uint8Array(candid_1.IDL.encode([UpdateCanisterSettingsRequest], [arg]));
+}
+//# sourceMappingURL=management-canister.js.map

package/dist/management-canister.js.map

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