@withautonomi/autonomi 0.5.3 → 0.6.1

package/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
-edition = "2021"
+edition = "2024"
 name = "autonomi-nodejs"
-version = "0.1.1"
+version = "0.2.1"
 description = "NodeJS bindings for the autonomi client"
 license = "GPL-3.0"
 
@@ -9,7 +9,7 @@ license = "GPL-3.0"
 crate-type = ["cdylib"]
 
 [dependencies]
-autonomi = { path = "../autonomi", version = "0.5.3" }
+autonomi = { path = "../autonomi", version = "0.6.1" }
 bytes = { version = "1.0.1", features = ["serde"] }
 eyre = "0.6.12"
 futures = "0.3"
@@ -20,5 +20,8 @@ serde = { version = "1.0.133", features = ["derive", "rc"] }
 serde_json = "1.0"
 tokio = { version = "1", features = ["full"] }
 
+[lints]
+workspace = true
+
 [build-dependencies]
 napi-build = "2.0.1"

package/README.md

@@ -31,23 +31,23 @@ For example usage, see the [`__test__`](./__test__) directory. Replace `import {
 
 # Contributing, compilation and publishing
 
-To contribute or develop on the source code directly, we need a few requirements.
+To contribute or develop on the source code directly, Node.js must be installed (installation instructions [here](https://nodejs.org/en/download)).
 
-- Yarn
-  - `npm install --global yarn`
-- We need the NAPI RS CLI tool
-  - `yarn global add @napi-rs/cli`
+With Node.js installed, change the working directory to `autonomi-nodejs/`:
+```console
+$ cd ./autonomi-nodejs/
+```
 
-Install the dependencies for the project:
+Then install the dependencies for the project:
 ```console
-$ yarn install
+$ npm install
 ```
 
 ## Build
 
-Then build using the `napi` CLI:
+Then build using the build script (which calls the `napi` CLI):
 ```console
-$ npx napi build
+$ npm run build
 ```
 
 ## Running tests
@@ -55,9 +55,9 @@ $ npx napi build
 Run the `test` script:
 
 ```console
-yarn test
+npm test
 # Or run a specific test
-yarn test __test__/register.spec.mjs -m 'registers errors'
+npm test __test__/register.spec.mjs -m 'registers errors'
 ```
 
 ## Publishing
@@ -73,4 +73,4 @@ It's a good practice to have an unreleased version number ready to go. So if `0.
 
 ### Workflow
 
-Use the 'JS publish to NPM' workflow (`nodejs-publish.yml`) to publish the package from `main` or a tag. This workflow has to be manually dispatched through GitHub.
+Use the 'Node.js (release)' workflow (`nodejs-publish.yml`) to publish the package from `main` or a tag. This workflow has to be manually dispatched through GitHub.

package/build.rs

@@ -1,5 +1,3 @@
-extern crate napi_build;
-
 fn main() {
     napi_build::setup();
 }

package/examples/simple_example_scratchpad.mjs

@@ -0,0 +1,64 @@
+// Copyright 2025 MaidSafe.net limited.
+//
+// This SAFE Network Software is licensed to you under The General Public License (GPL), version 3.
+// Unless required by applicable law or agreed to in writing, the SAFE Network Software distributed
+// under the GPL Licence is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. Please review the Licences for the specific language governing
+// permissions and limitations relating to use of the SAFE Network Software.
+
+import { Client, SecretKey, Wallet, Network, PaymentOption } from '@withautonomi/autonomi';
+
+async function scratchpadExample() {
+    try {
+        // Initialize client and wallet
+        const client = await Client.initLocal();
+        const network = new Network(true);  // Use testnet for local development
+        // For mainnet use: new Network(false)
+        const privateKey = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
+        const wallet = Wallet.newFromPrivateKey(network, privateKey);
+        const payment = PaymentOption.fromWallet(wallet);
+
+        // Create secret key for scratchpad
+        const key = SecretKey.random();
+        const publicKey = key.publicKey();
+
+        // Check cost
+        const estimatedCost = await client.scratchpadCost(publicKey);
+        console.log(`Estimated scratchpad cost: ${estimatedCost}`);
+
+        // Create scratchpad
+        const contentType = 42n;
+        const initialData = Buffer.from("Hello, Autonomi!");
+        const { cost: actualCost, addr } = await client.scratchpadCreate(key, contentType, initialData, payment);
+        console.log(`Created at ${addr.toHex()}`);
+        console.log(`Actual cost: ${actualCost}`);
+
+        // Get scratchpad
+        const scratchpad = await client.scratchpadGet(addr);
+        console.assert(scratchpad.counter() === 0n);
+        console.log(`Retrieved scratchpad with counter: ${scratchpad.counter()}`);
+        
+        // Decrypt content
+        const decrypted = scratchpad.decryptData(key);
+        console.assert(Buffer.compare(decrypted, initialData) === 0);
+        console.log("✓ Decrypted content matches initial data");
+
+        // Update scratchpad (free)
+        const newData = Buffer.from("Updated content!");
+        await client.scratchpadUpdate(key, contentType, newData);
+        console.log("✓ Scratchpad updated successfully");
+
+        // Get updated scratchpad
+        const updated = await client.scratchpadGet(addr);
+        console.assert(updated.counter() === 1n);
+        const updatedContent = updated.decryptData(key);
+        console.assert(Buffer.compare(updatedContent, newData) === 0);
+        console.log(`✓ Updated scratchpad verified with counter: ${updated.counter()}`);
+        console.log("✓ All scratchpad operations completed successfully!");
+
+    } catch (error) {
+        console.error('Error:', error.message);
+    }
+}
+
+scratchpadExample();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withautonomi/autonomi",
-  "version": "0.5.3",
+  "version": "0.6.1",
   "description": "NodeJS bindings for Autonomi client",
   "main": "index.js",
   "types": "index.d.ts",
@@ -57,9 +57,9 @@
     "includeVersion": true
   },
   "optionalDependencies": {
-    "@withautonomi/autonomi-win32-x64-msvc": "0.5.3",
-    "@withautonomi/autonomi-darwin-x64": "0.5.3",
-    "@withautonomi/autonomi-linux-x64-gnu": "0.5.3",
-    "@withautonomi/autonomi-darwin-arm64": "0.5.3"
+    "@withautonomi/autonomi-win32-x64-msvc": "0.6.1",
+    "@withautonomi/autonomi-darwin-x64": "0.6.1",
+    "@withautonomi/autonomi-linux-x64-gnu": "0.6.1",
+    "@withautonomi/autonomi-darwin-arm64": "0.6.1"
   }
 }

package/src/lib.rs

@@ -1,3 +1,6 @@
+// Allow unused_async as NAPI bindings may require async signatures
+#![allow(clippy::unused_async)]
+
 use std::{path::PathBuf, str::FromStr};
 
 use autonomi::{AttoTokens, Bytes, Chunk, Multiaddr, Signature};
@@ -279,6 +282,28 @@ impl Client {
             .map_err(map_error)
     }
 
+    /// Update an existing pointer from a specific pointer to point to a new target on the network.
+    ///
+    /// This will increment the counter of the pointer and update the target.
+    /// This function is used internally by `pointer_update` after the pointer has been retrieved from the network.
+    /// To skip the retrieval step if you already have the pointer, use this function directly.
+    /// This function will return the new pointer after it has been updated.
+    #[napi]
+    pub async fn pointer_update_from(
+        &self,
+        current: &Pointer,
+        owner: &SecretKey,
+        target: &PointerTarget,
+    ) -> Result<Pointer> {
+        let new_pointer = self
+            .0
+            .pointer_update_from(&current.0, &owner.0, target.0.clone())
+            .await
+            .map_err(map_error)?;
+
+        Ok(Pointer(new_pointer))
+    }
+
     /// Calculate the cost of storing a pointer
     #[napi]
     pub async fn pointer_cost(&self, key: &PublicKey) -> Result</* AttoTokens */ String> {
@@ -392,6 +417,36 @@ impl Client {
             .map_err(map_error)
     }
 
+    /// Update an existing scratchpad from a specific scratchpad to the network.
+    ///
+    /// This will increment the counter of the scratchpad and update the content.
+    /// This function is used internally by `scratchpad_update` after the scratchpad has been retrieved from the network.
+    /// To skip the retrieval step if you already have the scratchpad, use this function directly.
+    /// This function will return the new scratchpad after it has been updated.
+    #[napi]
+    pub async fn scratchpad_update_from(
+        &self,
+        current: &Scratchpad,
+        owner: &SecretKey,
+        content_type: BigInt, // `u64`
+        data: Buffer,
+    ) -> Result<Scratchpad> {
+        let content_type = big_int_to_u64(content_type, "content_type")?;
+
+        let new_scratchpad = self
+            .0
+            .scratchpad_update_from(
+                &current.0,
+                &owner.0,
+                content_type,
+                &Bytes::copy_from_slice(&data),
+            )
+            .await
+            .map_err(map_error)?;
+
+        Ok(Scratchpad(new_scratchpad))
+    }
+
     /// Get the cost of creating a new Scratchpad
     #[napi]
     pub async fn scratchpad_cost(&self, owner: &PublicKey) -> Result</* AttoTokens */ String> {
@@ -574,7 +629,7 @@ impl Client {
     /// Upload the content of all files in a directory to the network.
     /// The directory is recursively walked and each file is uploaded to the network.
     ///
-    /// The data maps of these (private) files are not uploaded but returned within
+    /// The datamaps of these (private) files are not uploaded but returned within
     /// the PrivateArchive return type.
 
     #[napi]
@@ -665,9 +720,9 @@ impl Client {
 
     /// Upload the content of all files in a directory to the network. The directory is recursively walked and each file is uploaded to the network.
     ///
-    /// The data maps of these files are uploaded on the network, making the individual files publicly available.
+    /// The datamaps of these files are uploaded on the network, making the individual files publicly available.
     ///
-    /// This returns, but does not upload (!),the PublicArchive containing the data maps of the uploaded files.
+    /// This returns, but does not upload (!),the PublicArchive containing the datamaps of the uploaded files.
     #[napi]
     pub async fn dir_content_upload_public(
         &self,
@@ -732,9 +787,9 @@ impl Client {
 
     /// Get the user data from the vault
     #[napi]
-    pub async fn get_user_data_from_vault(&self, secret_key: &VaultSecretKey) -> Result<UserData> {
+    pub async fn vault_get_user_data(&self, secret_key: &VaultSecretKey) -> Result<UserData> {
         self.0
-            .get_user_data_from_vault(&secret_key.0)
+            .vault_get_user_data(&secret_key.0)
             .await
             .map(UserData)
             .map_err(map_error)
@@ -744,14 +799,14 @@ impl Client {
     ///
     /// Returns the total cost of the put operation
     #[napi]
-    pub async fn put_user_data_to_vault(
+    pub async fn vault_put_user_data(
         &self,
         secret_key: &VaultSecretKey,
         payment_option: &PaymentOption,
         user_data: &UserData,
     ) -> Result</* AttoTokens */ String> {
         self.0
-            .put_user_data_to_vault(&secret_key.0, payment_option.0.clone(), user_data.0.clone())
+            .vault_put_user_data(&secret_key.0, payment_option.0.clone(), user_data.0.clone())
             .await
             .map(|c| c.to_string())
             .map_err(map_error)
@@ -761,15 +816,11 @@ impl Client {
     ///
     /// Returns the content type of the bytes in the vault.
     #[napi]
-    pub async fn fetch_and_decrypt_vault(
+    pub async fn vault_get(
         &self,
         secret_key: &VaultSecretKey,
     ) -> Result</* (Bytes, VaultContentType) */ tuple_result::FetchAndDecryptVault> {
-        let (data, content_type) = self
-            .0
-            .fetch_and_decrypt_vault(&secret_key.0)
-            .await
-            .map_err(map_error)?;
+        let (data, content_type) = self.0.vault_get(&secret_key.0).await.map_err(map_error)?;
 
         Ok(tuple_result::FetchAndDecryptVault { data, content_type })
     }
@@ -800,7 +851,7 @@ impl Client {
     /// It is recommended to use the hash of the app name or unique identifier as the content type.
 
     #[napi]
-    pub async fn write_bytes_to_vault(
+    pub async fn vault_put(
         &self,
         data: Buffer,
         payment_option: &PaymentOption,
@@ -810,7 +861,7 @@ impl Client {
         let data = Bytes::copy_from_slice(&data);
 
         self.0
-            .write_bytes_to_vault(
+            .vault_put(
                 data,
                 payment_option.0.clone(),
                 &secret_key.0,
@@ -821,6 +872,46 @@ impl Client {
             .map_err(map_error)
     }
 
+    /// @deprecated Use `vault_get_user_data` instead. This function will be removed in a future version.
+    #[napi]
+    pub async fn get_user_data_from_vault(&self, secret_key: &VaultSecretKey) -> Result<UserData> {
+        self.vault_get_user_data(secret_key).await
+    }
+
+    /// @deprecated Use `vault_put_user_data` instead. This function will be removed in a future version.
+    #[napi]
+    pub async fn put_user_data_to_vault(
+        &self,
+        secret_key: &VaultSecretKey,
+        payment_option: &PaymentOption,
+        user_data: &UserData,
+    ) -> Result</* AttoTokens */ String> {
+        self.vault_put_user_data(secret_key, payment_option, user_data)
+            .await
+    }
+
+    /// @deprecated Use `vault_get` instead. This function will be removed in a future version.
+    #[napi]
+    pub async fn fetch_and_decrypt_vault(
+        &self,
+        secret_key: &VaultSecretKey,
+    ) -> Result</* (Bytes, VaultContentType) */ tuple_result::FetchAndDecryptVault> {
+        self.vault_get(secret_key).await
+    }
+
+    /// @deprecated Use `vault_put` instead. This function will be removed in a future version.
+    #[napi]
+    pub async fn write_bytes_to_vault(
+        &self,
+        data: Buffer,
+        payment_option: &PaymentOption,
+        secret_key: &VaultSecretKey,
+        content_type: &VaultContentType,
+    ) -> Result</* AttoTokens */ String> {
+        self.vault_put(data, payment_option, secret_key, content_type)
+            .await
+    }
+
     // Registers
 
     /// Get the register history, starting from the root to the latest entry.
@@ -1541,6 +1632,14 @@ impl Network {
         let network = autonomi::Network::new(local).map_err(map_error)?;
         Ok(Self(network))
     }
+
+    #[napi]
+    pub fn from_string(name: String) -> Result<Self> {
+        let network = autonomi::Network::from_str(&name).map_err(|()| {
+            napi::Error::new(Status::InvalidArg, format!("Invalid network name '{name}'"))
+        })?;
+        Ok(Self(network))
+    }
 }
 
 #[napi]
@@ -2071,7 +2170,7 @@ impl PrivateArchive {
             .collect()
     }
 
-    /// List all data maps of the files in the archive
+    /// List all datamaps of the files in the archive
     #[napi]
     pub fn data_maps(&self) -> Vec<DataMapChunk> {
         self.0.data_maps().into_iter().map(DataMapChunk).collect()