@dfinity/agent - npm Package Compare versions

Comparing version 0.10.4 to 0.11.0

lib/cjs/agent/api.d.ts

 import { Principal } from '@dfinity/principal';
 import { RequestId } from '../request_id';
 import { JsonObject } from '@dfinity/candid';
+import { Identity } from '..';
 /**
@@ -140,2 +141,18 @@ * Codes used by the replica for rejecting a message.
     fetchRootKey(): Promise<ArrayBuffer>;
+    /**
+     * If an application needs to invalidate an identity under certain conditions, an `Agent` may expose an `invalidateIdentity` method.
+     * Invoking this method will set the inner identity used by the `Agent` to `null`.
+     *
+     * A use case for this would be - after a certain period of inactivity, a secure application chooses to invalidate the identity of any `HttpAgent` instances. An invalid identity can be replaced by `Agent.replaceIdentity`
+     */
+    invalidateIdentity?(): void;
+    /**
+     * If an application needs to replace an identity under certain conditions, an `Agent` may expose a `replaceIdentity` method.
+     * Invoking this method will set the inner identity used by the `Agent` to a newly provided identity.
+     *
+     * A use case for this would be - after authenticating using `@dfinity/auth-client`, you can replace the `AnonymousIdentity` of your `Actor` with a `DelegationIdentity`.
+     *
+     * ```Actor.agentOf(defaultActor).replaceIdentity(await authClient.getIdentity());```
+     */
+    replaceIdentity?(identity: Identity): void;
 }

lib/cjs/agent/http/index.d.ts

@@ -30,2 +30,15 @@ import { JsonObject } from '@dfinity/candid';
     };
+    /**
+     * Prevents the agent from providing a unique {@link Nonce} with each call.
+     * Enabling may cause rate limiting of identical requests
+     * at the boundary nodes.
+     *
+     * To add your own nonce generation logic, you can use the following:
+     * @example
+     * import {makeNonceTransform, makeNonce} from '@dfinity/agent';
+     * const agent = new HttpAgent({ disableNonce: true });
+     * agent.addTransform(makeNonceTransform(makeNonce);
+     * @default false
+     */
+    disableNonce?: boolean;
 }
@@ -32,0 +45,0 @@ export declare class HttpAgent implements Agent {

lib/cjs/agent/http/index.js

@@ -154,2 +154,6 @@ "use strict";
         this._identity = Promise.resolve(options.identity || new auth_1.AnonymousIdentity());
+        // Add a nonce transform to ensure calls are unique
+        if (!options.disableNonce) {
+            this.addTransform(transforms_1.makeNonceTransform(types_1.makeNonce));
+        }
     }
@@ -156,0 +160,0 @@ addTransform(fn, priority = fn.priority || 0) {

lib/cjs/agent/http/types.js

@@ -17,6 +17,8 @@ "use strict";
     const view = new DataView(buffer);
-    const value = BigInt(+Date.now()) * BigInt(100000) + BigInt(Math.floor(Math.random() * 100000));
-    view.setBigUint64(0, value);
-    // tslint:disable-next-line:no-bitwise
-    view.setBigUint64(1, value >> BigInt(64));
+    const now = BigInt(+Date.now());
+    const randHi = Math.floor(Math.random() * 0xffffffff);
+    const randLo = Math.floor(Math.random() * 0xffffffff);
+    view.setBigUint64(0, now);
+    view.setUint32(8, randHi);
+    view.setUint32(12, randLo);
     return buffer;
@@ -23,0 +25,0 @@ }

lib/cjs/canisters/management_idl.js

@@ -10,21 +10,63 @@ "use strict";
     const canister_id = IDL.Principal;
-    const wasm_module = IDL.Vec(IDL.Nat8);
-    const CanisterSettings = IDL.Record({
+    const definite_canister_settings = IDL.Record({
+        controllers: IDL.Vec(IDL.Principal),
+        freezing_threshold: IDL.Nat,
+        memory_allocation: IDL.Nat,
+        compute_allocation: IDL.Nat,
+    });
+    const canister_settings = IDL.Record({
+        controllers: IDL.Opt(IDL.Vec(IDL.Principal)),
+        freezing_threshold: IDL.Opt(IDL.Nat),
+        memory_allocation: IDL.Opt(IDL.Nat),
         compute_allocation: IDL.Opt(IDL.Nat),
-        memory_allocation: IDL.Opt(IDL.Nat),
     });
+    const wasm_module = IDL.Vec(IDL.Nat8);
     return IDL.Service({
-        provisional_create_canister_with_cycles: IDL.Func([IDL.Record({ amount: IDL.Opt(IDL.Nat), settings: IDL.Opt(CanisterSettings) })], [IDL.Record({ canister_id: canister_id })], []),
-        create_canister: IDL.Func([], [IDL.Record({ canister_id: canister_id })], []),
+        canister_status: IDL.Func([IDL.Record({ canister_id: canister_id })], [
+            IDL.Record({
+                status: IDL.Variant({
+                    stopped: IDL.Null,
+                    stopping: IDL.Null,
+                    running: IDL.Null,
+                }),
+                memory_size: IDL.Nat,
+                cycles: IDL.Nat,
+                settings: definite_canister_settings,
+                module_hash: IDL.Opt(IDL.Vec(IDL.Nat8)),
+            }),
+        ], []),
+        create_canister: IDL.Func([IDL.Record({ settings: IDL.Opt(canister_settings) })], [IDL.Record({ canister_id: canister_id })], []),
+        delete_canister: IDL.Func([IDL.Record({ canister_id: canister_id })], [], []),
+        deposit_cycles: IDL.Func([IDL.Record({ canister_id: canister_id })], [], []),
         install_code: IDL.Func([
             IDL.Record({
-                mode: IDL.Variant({ install: IDL.Null, reinstall: IDL.Null, upgrade: IDL.Null }),
+                arg: IDL.Vec(IDL.Nat8),
+                wasm_module: wasm_module,
+                mode: IDL.Variant({
+                    reinstall: IDL.Null,
+                    upgrade: IDL.Null,
+                    install: IDL.Null,
+                }),
                 canister_id: canister_id,
-                wasm_module: wasm_module,
-                arg: IDL.Vec(IDL.Nat8),
             }),
         ], [], []),
-        set_controller: IDL.Func([IDL.Record({ canister_id: canister_id, new_controller: IDL.Principal })], [], []),
+        provisional_create_canister_with_cycles: IDL.Func([
+            IDL.Record({
+                settings: IDL.Opt(canister_settings),
+                amount: IDL.Opt(IDL.Nat),
+            }),
+        ], [IDL.Record({ canister_id: canister_id })], []),
+        provisional_top_up_canister: IDL.Func([IDL.Record({ canister_id: canister_id, amount: IDL.Nat })], [], []),
+        raw_rand: IDL.Func([], [IDL.Vec(IDL.Nat8)], []),
+        start_canister: IDL.Func([IDL.Record({ canister_id: canister_id })], [], []),
+        stop_canister: IDL.Func([IDL.Record({ canister_id: canister_id })], [], []),
+        uninstall_code: IDL.Func([IDL.Record({ canister_id: canister_id })], [], []),
+        update_settings: IDL.Func([
+            IDL.Record({
+                canister_id: IDL.Principal,
+                settings: canister_settings,
+            }),
+        ], [], []),
     });
 };
 //# sourceMappingURL=management_idl.js.map

lib/cjs/canisters/management.d.ts

@@ -1,33 +0,8 @@
-import { ActorMethod, ActorSubclass, CallConfig } from '../actor';
-import { Principal } from '@dfinity/principal';
-export interface CanisterSettings {
-    controller: [] | [Principal];
-    compute_allocation: [] | [bigint];
-    memory_allocation: [] | [bigint];
-    freezing_threshold: [] | [bigint];
-}
-export interface ManagementCanisterRecord {
-    provisional_create_canister_with_cycles: ActorMethod<[{
-        amount: [] | [number];
-        settings: [] | [CanisterSettings];
-    }], {
-        canister_id: Principal;
-    }>;
-    install_code: ActorMethod<[{
-        mode: {
-            install: null;
-        } | {
-            reinstall: null;
-        } | {
-            upgrade: null;
-        };
-        canister_id: Principal;
-        wasm_module: number[];
-        arg: number[];
-    }], void>;
-}
+import { ActorSubclass, CallConfig } from '../actor';
+import _SERVICE from './management_service';
+export declare type ManagementCanisterRecord = _SERVICE;
 /**
- * Create a management canister actor.
+ * Create a management canister actor
  * @param config
  */
 export declare function getManagementCanister(config: CallConfig): ActorSubclass<ManagementCanisterRecord>;

lib/cjs/canisters/management.js

@@ -10,9 +10,8 @@ "use strict";
 const management_idl_1 = __importDefault(require("./management_idl"));
-/* tslint:enable */
 /**
- * Create a management canister actor.
+ * Create a management canister actor
  * @param config
  */
 function getManagementCanister(config) {
-    function transform(methodName, args, callConfig) {
+    function transform(_methodName, args, _callConfig) {
         const first = args[0];
@@ -19,0 +18,0 @@ let effectiveCanisterId = principal_1.Principal.fromHex('');

lib/esm/agent/api.d.ts

 import { Principal } from '@dfinity/principal';
 import { RequestId } from '../request_id';
 import { JsonObject } from '@dfinity/candid';
+import { Identity } from '..';
 /**
@@ -140,2 +141,18 @@ * Codes used by the replica for rejecting a message.
     fetchRootKey(): Promise<ArrayBuffer>;
+    /**
+     * If an application needs to invalidate an identity under certain conditions, an `Agent` may expose an `invalidateIdentity` method.
+     * Invoking this method will set the inner identity used by the `Agent` to `null`.
+     *
+     * A use case for this would be - after a certain period of inactivity, a secure application chooses to invalidate the identity of any `HttpAgent` instances. An invalid identity can be replaced by `Agent.replaceIdentity`
+     */
+    invalidateIdentity?(): void;
+    /**
+     * If an application needs to replace an identity under certain conditions, an `Agent` may expose a `replaceIdentity` method.
+     * Invoking this method will set the inner identity used by the `Agent` to a newly provided identity.
+     *
+     * A use case for this would be - after authenticating using `@dfinity/auth-client`, you can replace the `AnonymousIdentity` of your `Actor` with a `DelegationIdentity`.
+     *
+     * ```Actor.agentOf(defaultActor).replaceIdentity(await authClient.getIdentity());```
+     */
+    replaceIdentity?(identity: Identity): void;
 }

lib/esm/agent/http/index.d.ts

@@ -30,2 +30,15 @@ import { JsonObject } from '@dfinity/candid';
     };
+    /**
+     * Prevents the agent from providing a unique {@link Nonce} with each call.
+     * Enabling may cause rate limiting of identical requests
+     * at the boundary nodes.
+     *
+     * To add your own nonce generation logic, you can use the following:
+     * @example
+     * import {makeNonceTransform, makeNonce} from '@dfinity/agent';
+     * const agent = new HttpAgent({ disableNonce: true });
+     * agent.addTransform(makeNonceTransform(makeNonce);
+     * @default false
+     */
+    disableNonce?: boolean;
 }
@@ -32,0 +45,0 @@ export declare class HttpAgent implements Agent {

lib/esm/agent/http/index.js

@@ -7,4 +7,4 @@ import { Principal } from '@dfinity/principal';
 import { fromHex } from '../../utils/buffer';
-import { Expiry } from './transforms';
-import { SubmitRequestType, } from './types';
+import { Expiry, makeNonceTransform } from './transforms';
+import { makeNonce, SubmitRequestType, } from './types';
 export * from './transforms';
@@ -128,2 +128,6 @@ export { makeNonce } from './types';
         this._identity = Promise.resolve(options.identity || new AnonymousIdentity());
+        // Add a nonce transform to ensure calls are unique
+        if (!options.disableNonce) {
+            this.addTransform(makeNonceTransform(makeNonce));
+        }
     }
@@ -130,0 +134,0 @@ addTransform(fn, priority = fn.priority || 0) {

lib/esm/agent/http/types.js

@@ -14,8 +14,10 @@ // tslint:enable:camel-case
     const view = new DataView(buffer);
-    const value = BigInt(+Date.now()) * BigInt(100000) + BigInt(Math.floor(Math.random() * 100000));
-    view.setBigUint64(0, value);
-    // tslint:disable-next-line:no-bitwise
-    view.setBigUint64(1, value >> BigInt(64));
+    const now = BigInt(+Date.now());
+    const randHi = Math.floor(Math.random() * 0xffffffff);
+    const randLo = Math.floor(Math.random() * 0xffffffff);
+    view.setBigUint64(0, now);
+    view.setUint32(8, randHi);
+    view.setUint32(12, randLo);
     return buffer;
 }
 //# sourceMappingURL=types.js.map

lib/esm/canisters/management_idl.js

@@ -8,21 +8,63 @@ /**
     const canister_id = IDL.Principal;
-    const wasm_module = IDL.Vec(IDL.Nat8);
-    const CanisterSettings = IDL.Record({
+    const definite_canister_settings = IDL.Record({
+        controllers: IDL.Vec(IDL.Principal),
+        freezing_threshold: IDL.Nat,
+        memory_allocation: IDL.Nat,
+        compute_allocation: IDL.Nat,
+    });
+    const canister_settings = IDL.Record({
+        controllers: IDL.Opt(IDL.Vec(IDL.Principal)),
+        freezing_threshold: IDL.Opt(IDL.Nat),
+        memory_allocation: IDL.Opt(IDL.Nat),
         compute_allocation: IDL.Opt(IDL.Nat),
-        memory_allocation: IDL.Opt(IDL.Nat),
     });
+    const wasm_module = IDL.Vec(IDL.Nat8);
     return IDL.Service({
-        provisional_create_canister_with_cycles: IDL.Func([IDL.Record({ amount: IDL.Opt(IDL.Nat), settings: IDL.Opt(CanisterSettings) })], [IDL.Record({ canister_id: canister_id })], []),
-        create_canister: IDL.Func([], [IDL.Record({ canister_id: canister_id })], []),
+        canister_status: IDL.Func([IDL.Record({ canister_id: canister_id })], [
+            IDL.Record({
+                status: IDL.Variant({
+                    stopped: IDL.Null,
+                    stopping: IDL.Null,
+                    running: IDL.Null,
+                }),
+                memory_size: IDL.Nat,
+                cycles: IDL.Nat,
+                settings: definite_canister_settings,
+                module_hash: IDL.Opt(IDL.Vec(IDL.Nat8)),
+            }),
+        ], []),
+        create_canister: IDL.Func([IDL.Record({ settings: IDL.Opt(canister_settings) })], [IDL.Record({ canister_id: canister_id })], []),
+        delete_canister: IDL.Func([IDL.Record({ canister_id: canister_id })], [], []),
+        deposit_cycles: IDL.Func([IDL.Record({ canister_id: canister_id })], [], []),
         install_code: IDL.Func([
             IDL.Record({
-                mode: IDL.Variant({ install: IDL.Null, reinstall: IDL.Null, upgrade: IDL.Null }),
+                arg: IDL.Vec(IDL.Nat8),
+                wasm_module: wasm_module,
+                mode: IDL.Variant({
+                    reinstall: IDL.Null,
+                    upgrade: IDL.Null,
+                    install: IDL.Null,
+                }),
                 canister_id: canister_id,
-                wasm_module: wasm_module,
-                arg: IDL.Vec(IDL.Nat8),
             }),
         ], [], []),
-        set_controller: IDL.Func([IDL.Record({ canister_id: canister_id, new_controller: IDL.Principal })], [], []),
+        provisional_create_canister_with_cycles: IDL.Func([
+            IDL.Record({
+                settings: IDL.Opt(canister_settings),
+                amount: IDL.Opt(IDL.Nat),
+            }),
+        ], [IDL.Record({ canister_id: canister_id })], []),
+        provisional_top_up_canister: IDL.Func([IDL.Record({ canister_id: canister_id, amount: IDL.Nat })], [], []),
+        raw_rand: IDL.Func([], [IDL.Vec(IDL.Nat8)], []),
+        start_canister: IDL.Func([IDL.Record({ canister_id: canister_id })], [], []),
+        stop_canister: IDL.Func([IDL.Record({ canister_id: canister_id })], [], []),
+        uninstall_code: IDL.Func([IDL.Record({ canister_id: canister_id })], [], []),
+        update_settings: IDL.Func([
+            IDL.Record({
+                canister_id: IDL.Principal,
+                settings: canister_settings,
+            }),
+        ], [], []),
     });
 };
 //# sourceMappingURL=management_idl.js.map

lib/esm/canisters/management.d.ts

@@ -1,37 +0,8 @@
-import { ActorMethod, ActorSubclass, CallConfig } from '../actor';
-import { Principal } from '@dfinity/principal';
-export interface CanisterSettings {
-    controller: [] | [Principal];
-    compute_allocation: [] | [bigint];
-    memory_allocation: [] | [bigint];
-    freezing_threshold: [] | [bigint];
-}
-export interface ManagementCanisterRecord {
-    provisional_create_canister_with_cycles: ActorMethod<[
-        {
-            amount: [] | [number];
-            settings: [] | [CanisterSettings];
-        }
-    ], {
-        canister_id: Principal;
-    }>;
-    install_code: ActorMethod<[
-        {
-            mode: {
-                install: null;
-            } | {
-                reinstall: null;
-            } | {
-                upgrade: null;
-            };
-            canister_id: Principal;
-            wasm_module: number[];
-            arg: number[];
-        }
-    ], void>;
-}
+import { ActorSubclass, CallConfig } from '../actor';
+import _SERVICE from './management_service';
+export declare type ManagementCanisterRecord = _SERVICE;
 /**
- * Create a management canister actor.
+ * Create a management canister actor
  * @param config
  */
 export declare function getManagementCanister(config: CallConfig): ActorSubclass<ManagementCanisterRecord>;

lib/esm/canisters/management.js

 import { Actor } from '../actor';
 import { Principal } from '@dfinity/principal';
 import managementCanisterIdl from './management_idl';
-/* tslint:enable */
 /**
- * Create a management canister actor.
+ * Create a management canister actor
  * @param config
  */
 export function getManagementCanister(config) {
-    function transform(methodName, args, callConfig) {
+    function transform(_methodName, args, _callConfig) {
         const first = args[0];
@@ -12,0 +11,0 @@ let effectiveCanisterId = Principal.fromHex('');

package.json

 {
   "name": "@dfinity/agent",
-  "version": "0.10.4",
+  "version": "0.11.0",
   "author": "DFINITY Stiftung <[e-mail]>",
@@ -44,4 +44,4 @@ "license": "Apache-2.0",
   "peerDependencies": {
-    "@dfinity/candid": "^0.10.4",
-    "@dfinity/principal": "^0.10.4"
+    "@dfinity/candid": "^0.11.0",
+    "@dfinity/principal": "^0.11.0"
   },
@@ -63,3 +63,2 @@ "dependencies": {
     "jest": "^27.3.1",
-    "jest-expect-message": "^1.0.2",
     "node-fetch": "^2.6.7",
@@ -66,0 +65,0 @@ "text-encoding": "^0.7.0",

README.md

@@ -36,1 +36,31 @@ # @dfinity/agent
 ```
+
+## Using an Agent
+
+The agent is a low-level interface that the Actor uses to encode and decode messages to the Internet Computer. It provides `call`, `query` and `readState` methods to the Actor, as well as a few additional utilities. For the most part, calls through the agent are intended to be structured through an Actor, configured with a canister interface that can be automatically generated from a [Candid](https://github.com/dfinity/candid) interface.
+
+## Initializing an Actor
+
+The most common use for the agent is to create an actor. This is done by calling the `Actor.createActor` constructor:
+
+```
+Actor.createActor(interfaceFactory: InterfaceFactory, configuration: ActorConfig): ActorSubclass<T>
+```
+
+The `interfaceFactory` is a function that returns a runtime interface that the Actor uses to strucure calls to a canister. The interfaceFactory can be written manually, but it is recommended to use the `dfx generate` command to generate the interface for your project, or to use the `didc` tool to generate the interface for your project.
+
+### Inspecting an actor's agent
+
+Use the `Actor.agentOf` method to get the agent of an actor:
+
+```
+const defaultAgent = Actor.agentOf(defaultActor);
+```
+
+This is useful if you need to replace or invalidate the identity used by an actor's agent.
+
+For example, if you want to replace the identity of an actor's agent with a newly authenticated identity from [Internet Identity](https://identity.ic0.app), you can do so by calling the `Actor.replaceAgent` method:
+
+```
+defaultAgent.replaceIdentity(await authClient.getIdentity());
+```

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

491804

increased by3.47%

Dev dependency count

14

decreased by-6.67%

Number of package files

142

increased by4.41%

Lines of code

7126

increased by3.92%

Number of lines in readme file

66

increased by83.33%

Number of medium supply chain risk alerts

2

decreased by-33.33%

No dependency changes