@wishknish/knishio-client-js 0.6.4 → 0.7.4

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@wishknish/knishio-client-js",
-  "version": "0.6.4",
+  "version": "0.7.4",
+  "type": "module",
   "productName": "Knish.IO Javascript SDK Client",
   "description": "JavaScript implementation of the Knish.IO SDK to consume Knish.IO GraphQL APIs.",
   "license": "GPL-3.0-or-later",
   "repository": {
     "type": "git",
-    "url": "https://github.com/WishKnish/KnishIO-Client-JS.git"
+    "url": "git+https://github.com/WishKnish/KnishIO-Client-JS.git"
   },
   "contributors": [
     {
@@ -15,12 +16,6 @@
       "homepage": "https://wishknish.com",
       "role": "developer"
     },
-    {
-      "name": "Vladimir Makarov",
-      "email": "vladimir@wishknish.com",
-      "homepage": "https://wishknish.com",
-      "role": "developer"
-    },
     {
       "name": "Yuri Kizilov",
       "email": "yuriy@wishknish.com",
@@ -28,44 +23,64 @@
       "role": "developer"
     }
   ],
-  "main": "dist/client.iife.js",
-  "module": "dist/client.es.js",
-  "commonjs": "dist/client.cjs.js",
+  "main": "dist/client.cjs.js",
+  "module": "dist/client.es.mjs",
+  "browser": "dist/client.iife.js",
+  "exports": {
+    ".": {
+      "browser": "./dist/client.iife.js",
+      "import": "./dist/client.es.mjs",
+      "require": "./dist/client.cjs.js"
+    },
+    "./src": "./src/index.js",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
   "keywords": [
     "wishknish",
     "knishio",
     "blockchain",
     "dag",
     "client",
-    "graphql"
+    "graphql",
+    "xmss",
+    "post-quantum",
+    "quantum-safe",
+    "sdk",
+    "javascript",
+    "ml-kem768",
+    "cryptography",
+    "crystals-kyber",
+    "fips-202",
+    "fips-203"
   ],
   "dependencies": {
-    "@noble/post-quantum": "^0.4.0",
+    "@noble/post-quantum": "^0.5.4",
     "@thumbmarkjs/thumbmarkjs": "^0.19.1",
-    "@urql/core": "^5.1.1",
-    "graphql": "^16.10.0",
-    "graphql-ws": "^6.0.4",
+    "@urql/core": "^5.2.0",
+    "graphql": "^16.12.0",
+    "graphql-ws": "^6.0.7",
     "isomorphic-fetch": "^3.0.0",
     "jssha": "^3.3.1",
-    "wonka": "^6.3.4"
+    "wonka": "^6.3.5"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
-    "@rollup/plugin-babel": "^6.0.4",
-    "@rollup/plugin-commonjs": "^28.0.3",
-    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-babel": "^6.1.0",
+    "@rollup/plugin-commonjs": "^28.0.9",
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "buffer": "^6.0.3",
     "esbuild-jest": "^0.5.0",
     "eslint": "^8.57.1",
     "eslint-config-standard": "^17.1.0",
-    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-n": "^16.6.2",
     "eslint-plugin-promise": "^6.6.0",
-    "eslint-plugin-vue": "^9.32.0",
-    "esmock": "^2.7.0",
+    "eslint-plugin-vue": "^9.33.0",
+    "esmock": "^2.7.3",
     "jest": "^29.7.0",
-    "rollup": "^4.34.8",
-    "vite": "^6.1.1"
+    "rollup": "^4.57.1",
+    "vite": "^6.4.1"
   },
   "browserslist": [
     "> 1%",
@@ -76,9 +91,14 @@
     "build": "vite build --config build/vite.config.mjs",
     "lint": "eslint --ext .js src",
     "test": "jest",
-    "test:coverage": "jest --coverage"
+    "test:coverage": "jest --coverage",
+    "selftest": "npm run build && node tests/scripts/self-test.js",
+    "integration-test": "npm run build && node tests/scripts/integration-test.js",
+    "prepublishOnly": "npm run build"
   },
   "files": [
-    "/src"
-  ]
+    "/src",
+    "/dist"
+  ],
+  "packageManager": "yarn@4.9.2"
 }

package/src/Atom.js

@@ -46,11 +46,11 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
 import JsSHA from 'jssha'
-import { charsetBaseConvert } from './libraries/strings'
-import Meta from './Meta'
-import AtomMeta from './AtomMeta'
-import AtomsMissingException from './exception/AtomsMissingException'
-import versions from './versions/index'
+import { charsetBaseConvert } from './libraries/strings.js'
+import Meta from './Meta.js'
+import AtomMeta from './AtomMeta.js'
+import AtomsMissingException from './exception/AtomsMissingException.js'
+import versions from './versions/index.js'
 
 /**
  * Atom class used to form microtransactions within a Molecule
@@ -176,6 +176,8 @@ export default class Atom {
     }
 
     // Create the final atom's object
+    // walletAddress is null for atoms without a pre-existing wallet (e.g., recipient V-atoms).
+    // toJSON() serializes null as '' for GraphQL compatibility; hash computation treats both identically.
     return new Atom({
       position: wallet ? wallet.position : null,
       walletAddress: wallet ? wallet.address : null,
@@ -208,6 +210,131 @@ export default class Atom {
     return target
   }
 
+  /**
+   * Returns JSON-ready object for cross-SDK compatibility (2025 JS best practices)
+   * 
+   * Provides clean serialization of atomic operations with optional OTS fragments.
+   * Follows 2025 JavaScript best practices with proper type safety and validation.
+   *
+   * @param {Object} options - Serialization options
+   * @param {boolean} options.includeOtsFragments - Include OTS signature fragments (default: true)
+   * @param {boolean} options.validateFields - Validate required fields (default: false)
+   * @return {Object} JSON-serializable object
+   * @throws {Error} If atom is in invalid state for serialization
+   */
+  toJSON (options = {}) {
+    const {
+      includeOtsFragments = true,
+      validateFields = false
+    } = options;
+
+    try {
+      // Validate required fields if requested
+      if (validateFields) {
+        const requiredFields = ['position', 'walletAddress', 'isotope', 'token'];
+        for (const field of requiredFields) {
+          if (!this[field]) {
+            throw new Error(`Required field '${field}' is missing or empty`);
+          }
+        }
+      }
+
+      // Core atom properties (always included)
+      // Coerce null position/walletAddress/token to empty string for GraphQL compatibility.
+      // The molecular hash computation (getHashableValues) already treats null as '' (line 448),
+      // so this coercion does NOT change the hash. Required because the Rust validator's
+      // GraphQL schema uses String! (non-null) with #[graphql(default)] for these fields,
+      // which accepts omitted values but rejects explicit null.
+      const serialized = {
+        position: this.position ?? '',
+        walletAddress: this.walletAddress ?? '',
+        isotope: this.isotope,
+        token: this.token ?? '',
+        value: this.value,
+        batchId: this.batchId,
+        metaType: this.metaType,
+        metaId: this.metaId,
+        meta: this.meta || [],
+        index: this.index,
+        createdAt: this.createdAt,
+        version: this.version
+      };
+
+      // Optional OTS fragments (can be large, so optional)
+      if (includeOtsFragments && this.otsFragment) {
+        serialized.otsFragment = this.otsFragment;
+      }
+
+      return serialized;
+
+    } catch (error) {
+      throw new Error(`Atom serialization failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Creates an Atom instance from JSON data (2025 JS best practices)
+   * 
+   * Handles cross-SDK atom deserialization with robust error handling.
+   * Essential for reconstructing atoms from other SDK implementations.
+   *
+   * @param {string|Object} json - JSON string or object to deserialize
+   * @param {Object} options - Deserialization options
+   * @param {boolean} options.validateStructure - Validate required fields (default: true)
+   * @param {boolean} options.strictMode - Strict validation mode (default: false)
+   * @return {Atom} Reconstructed atom instance
+   * @throws {Error} If JSON is invalid or required fields are missing
+   */
+  static fromJSON (json, options = {}) {
+    const {
+      validateStructure = true,
+      strictMode = false
+    } = options;
+
+    try {
+      // Parse JSON safely
+      const data = typeof json === 'string' ? JSON.parse(json) : json;
+
+      // Validate required fields in strict mode
+      if (strictMode || validateStructure) {
+        const requiredFields = ['position', 'walletAddress', 'isotope', 'token'];
+        for (const field of requiredFields) {
+          if (!data[field]) {
+            throw new Error(`Required field '${field}' is missing or empty`);
+          }
+        }
+      }
+
+      // Create atom instance with required fields
+      const atom = new Atom({
+        position: data.position,
+        walletAddress: data.walletAddress,
+        isotope: data.isotope,
+        token: data.token,
+        value: data.value,
+        batchId: data.batchId,
+        metaType: data.metaType,
+        metaId: data.metaId,
+        meta: data.meta,
+        index: data.index,
+        version: data.version
+      });
+
+      // Set additional properties that may not be in constructor
+      if (data.otsFragment) {
+        atom.otsFragment = data.otsFragment;
+      }
+      if (data.createdAt) {
+        atom.createdAt = data.createdAt;
+      }
+
+      return atom;
+
+    } catch (error) {
+      throw new Error(`Atom deserialization failed: ${error.message}`);
+    }
+  }
+
   /**
    * Produces a hash of the atoms inside a molecule.
    * Used to generate the molecularHash field for Molecules.

package/src/AtomMeta.js

@@ -46,8 +46,8 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
 
-import PolicyMeta from './PolicyMeta'
-import Meta from './Meta'
+import PolicyMeta from './PolicyMeta.js'
+import Meta from './Meta.js'
 
 const USE_META_CONTEXT = false
 const DEFAULT_META_CONTEXT = 'https://www.schema.org'
@@ -94,10 +94,7 @@ export default class AtomMeta {
    * @returns {AtomMeta}
    */
   setAtomWallet (wallet) {
-    const walletMeta = {
-      pubkey: wallet.pubkey,
-      characters: wallet.characters
-    }
+    const walletMeta = {}
 
     // Add token units meta key
     if (wallet.tokenUnits && wallet.tokenUnits.length) {
@@ -108,8 +105,10 @@ export default class AtomMeta {
       walletMeta.tradeRates = JSON.stringify(wallet.tradeRates)
     }
 
-    // Merge all wallet's metas
-    this.merge(walletMeta)
+    // Merge all wallet's metas (if any)
+    if (Object.keys(walletMeta).length > 0) {
+      this.merge(walletMeta)
+    }
     return this
   }
 

package/src/AuthToken.js

@@ -46,7 +46,7 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
 
-import Wallet from './Wallet'
+import Wallet from './Wallet.js'
 
 /**
  *

package/src/KnishIOClient.js

@@ -45,60 +45,62 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
  */
-import Dot from './libraries/Dot'
-import Decimal from './libraries/Decimal'
+import Dot from './libraries/Dot.js'
+import Decimal from './libraries/Decimal.js'
 import {
   generateBatchId,
   generateBundleHash,
   generateSecret
-} from './libraries/crypto'
-import Molecule from './Molecule'
-import Wallet from './Wallet'
-import AuthToken from './AuthToken'
-import QueryContinuId from './query/QueryContinuId'
-import QueryWalletBundle from './query/QueryWalletBundle'
-import QueryWalletList from './query/QueryWalletList'
-import QueryBalance from './query/QueryBalance'
-import QueryMetaType from './query/QueryMetaType'
-import QueryBatch from './query/QueryBatch'
-import QueryBatchHistory from './query/QueryBatchHistory'
-import MutationRequestAuthorization from './mutation/MutationRequestAuthorization'
-import MutationCreateToken from './mutation/MutationCreateToken'
-import MutationRequestTokens from './mutation/MutationRequestTokens'
-import MutationTransferTokens from './mutation/MutationTransferTokens'
-import MutationProposeMolecule from './mutation/MutationProposeMolecule'
-import MutationCreateIdentifier from './mutation/MutationCreateIdentifier'
-import MutationClaimShadowWallet from './mutation/MutationClaimShadowWallet'
-import MutationCreateMeta from './mutation/MutationCreateMeta'
-import MutationCreateWallet from './mutation/MutationCreateWallet'
-import MutationRequestAuthorizationGuest from './mutation/MutationRequestAuthorizationGuest'
-import TransferBalanceException from './exception/TransferBalanceException'
-import CodeException from './exception/CodeException'
-import UnauthenticatedException from './exception/UnauthenticatedException'
-import WalletShadowException from './exception/WalletShadowException'
-import StackableUnitDecimalsException from './exception/StackableUnitDecimalsException'
-import StackableUnitAmountException from './exception/StackableUnitAmountException'
-import CreateMoleculeSubscribe from './subscribe/CreateMoleculeSubscribe'
-import WalletStatusSubscribe from './subscribe/WalletStatusSubscribe'
-import ActiveWalletSubscribe from './subscribe/ActiveWalletSubscribe'
-import ActiveSessionSubscribe from './subscribe/ActiveSessionSubscribe'
-import MutationActiveSession from './mutation/MutationActiveSession'
-import QueryActiveSession from './query/QueryActiveSession'
-import QueryUserActivity from './query/QueryUserActivity'
-import QueryToken from './query/QueryToken'
-import BatchIdException from './exception/BatchIdException'
-import AuthorizationRejectedException from './exception/AuthorizationRejectedException'
-import QueryAtom from './query/QueryAtom'
-import QueryPolicy from './query/QueryPolicy'
-import QueryMetaTypeViaAtom from './query/QueryMetaTypeViaAtom'
-import MutationCreateRule from './mutation/MutationCreateRule'
-import MutationDepositBufferToken from './mutation/MutationDepositBufferToken'
-import MutationWithdrawBufferToken from './mutation/MutationWithdrawBufferToken'
+} from './libraries/crypto.js'
+import Molecule from './Molecule.js'
+import Wallet from './Wallet.js'
+import AuthToken from './AuthToken.js'
+import QueryContinuId from './query/QueryContinuId.js'
+import QueryWalletBundle from './query/QueryWalletBundle.js'
+import QueryWalletList from './query/QueryWalletList.js'
+import QueryBalance from './query/QueryBalance.js'
+import QueryMetaType from './query/QueryMetaType.js'
+import QueryBatch from './query/QueryBatch.js'
+import QueryBatchHistory from './query/QueryBatchHistory.js'
+import MutationRequestAuthorization from './mutation/MutationRequestAuthorization.js'
+import MutationCreateToken from './mutation/MutationCreateToken.js'
+import MutationRequestTokens from './mutation/MutationRequestTokens.js'
+import MutationTransferTokens from './mutation/MutationTransferTokens.js'
+import MutationProposeMolecule from './mutation/MutationProposeMolecule.js'
+import MutationCreateIdentifier from './mutation/MutationCreateIdentifier.js'
+import MutationClaimShadowWallet from './mutation/MutationClaimShadowWallet.js'
+import MutationCreateMeta from './mutation/MutationCreateMeta.js'
+import MutationPeering from './mutation/MutationPeering.js'
+import MutationAppendRequest from './mutation/MutationAppendRequest.js'
+import MutationCreateWallet from './mutation/MutationCreateWallet.js'
+import MutationRequestAuthorizationGuest from './mutation/MutationRequestAuthorizationGuest.js'
+import TransferBalanceException from './exception/TransferBalanceException.js'
+import CodeException from './exception/CodeException.js'
+import UnauthenticatedException from './exception/UnauthenticatedException.js'
+import WalletShadowException from './exception/WalletShadowException.js'
+import StackableUnitDecimalsException from './exception/StackableUnitDecimalsException.js'
+import StackableUnitAmountException from './exception/StackableUnitAmountException.js'
+import CreateMoleculeSubscribe from './subscribe/CreateMoleculeSubscribe.js'
+import WalletStatusSubscribe from './subscribe/WalletStatusSubscribe.js'
+import ActiveWalletSubscribe from './subscribe/ActiveWalletSubscribe.js'
+import ActiveSessionSubscribe from './subscribe/ActiveSessionSubscribe.js'
+import MutationActiveSession from './mutation/MutationActiveSession.js'
+import QueryActiveSession from './query/QueryActiveSession.js'
+import QueryUserActivity from './query/QueryUserActivity.js'
+import QueryToken from './query/QueryToken.js'
+import BatchIdException from './exception/BatchIdException.js'
+import AuthorizationRejectedException from './exception/AuthorizationRejectedException.js'
+import QueryAtom from './query/QueryAtom.js'
+import QueryPolicy from './query/QueryPolicy.js'
+import QueryMetaTypeViaAtom from './query/QueryMetaTypeViaAtom.js'
+import MutationCreateRule from './mutation/MutationCreateRule.js'
+import MutationDepositBufferToken from './mutation/MutationDepositBufferToken.js'
+import MutationWithdrawBufferToken from './mutation/MutationWithdrawBufferToken.js'
 import {
   getFingerprint,
   getFingerprintData
 } from '@thumbmarkjs/thumbmarkjs'
-import UrqlClientWrapper from './libraries/urql/UrqlClientWrapper'
+import UrqlClientWrapper from './libraries/urql/UrqlClientWrapper.js'
 
 /**
  * Base client class providing a powerful but user-friendly wrapper
@@ -250,16 +252,6 @@ export default class KnishIOClient {
     this.remainderWallet = null
   }
 
-  /**
-   * Returns the currently defined Cell identifier for this session
-   *
-   * @deprecated Please use getCellSlug() instead
-   * @return {string|null}
-   */
-  cellSlug () {
-    return this.getCellSlug()
-  }
-
   /**
    * Returns the currently defined Cell identifier for this session
    *
@@ -302,16 +294,6 @@ export default class KnishIOClient {
     return this.$__client.getUri()
   }
 
-  /**
-   * Retrieves the endpoint URI for this session
-   *
-   * @deprecated Please use getUri() instead
-   * @returns {string}
-   */
-  uri () {
-    return this.getUri()
-  }
-
   /**
    * Returns the GraphQL client class session
    *
@@ -331,8 +313,8 @@ export default class KnishIOClient {
           secret: this.$__secret,
           cellSlug: this.$__cellSlug,
           encrypt: this.$__encrypt
-        }).then(() => {
-          // Success
+        }).catch(err => {
+          this.log('warn', `KnishIOClient::client() - Background authorization failed: ${ err.message }`)
         })
       } else {
         // Use stored authorization data
@@ -559,7 +541,8 @@ export default class KnishIOClient {
    */
   async executeQuery (query, variables = null) {
     // Check and refresh authorization token if needed
-    if (this.$__authToken && this.$__authToken.isExpired()) {
+    // Guard with $__authInProcess to prevent concurrent auth requests
+    if (this.$__authToken && this.$__authToken.isExpired() && !this.$__authInProcess) {
       this.log('info', 'KnishIOClient::executeQuery() - Access token is expired. Getting new one...')
       await this.requestAuthToken({
         secret: this.$__secret,
@@ -836,7 +819,8 @@ export default class KnishIOClient {
         countBy,
         values,
         keys,
-        atomValues
+        atomValues,
+        cellSlug: this.getCellSlug()
       })
     } else {
       /**
@@ -852,14 +836,12 @@ export default class KnishIOClient {
         filter,
         queryArgs,
         count,
-        countBy
+        countBy,
+        cellSlug: this.getCellSlug()
       })
     }
 
     return this.executeQuery(query, variables)
-      .then((response) => {
-        return response.payload()
-      })
   }
 
   /**
@@ -1281,6 +1263,69 @@ export default class KnishIOClient {
     return await this.executeQuery(query)
   }
 
+  /**
+   * Builds and executes a molecule to register a peer node via P-isotope
+   *
+   * @param {string} host - The peer host URL to register
+   * @returns {Promise<ResponsePeering>} - A Promise that resolves with the peering response.
+   */
+  async registerPeer ({
+    host
+  }) {
+    /**
+     * @type {MutationPeering}
+     */
+    const query = await this.createMoleculeMutation({
+      mutationClass: MutationPeering,
+      molecule: await this.createMolecule({
+        secret: this.getSecret(),
+        sourceWallet: await this.getSourceWallet()
+      })
+    })
+
+    query.fillMolecule({
+      host
+    })
+
+    return await this.executeQuery(query)
+  }
+
+  /**
+   * Builds and executes a molecule to submit an append request via A-isotope
+   *
+   * @param {string} metaType - The target MetaType to append to
+   * @param {string} metaId - The target MetaId to append to
+   * @param {string} action - The action to perform
+   * @param {object} [meta={}] - Additional metadata
+   * @returns {Promise<ResponseAppendRequest>} - A Promise that resolves with the append request response.
+   */
+  async appendRequest ({
+    metaType,
+    metaId,
+    action,
+    meta = {}
+  }) {
+    /**
+     * @type {MutationAppendRequest}
+     */
+    const query = await this.createMoleculeMutation({
+      mutationClass: MutationAppendRequest,
+      molecule: await this.createMolecule({
+        secret: this.getSecret(),
+        sourceWallet: await this.getSourceWallet()
+      })
+    })
+
+    query.fillMolecule({
+      metaType,
+      metaId,
+      action,
+      meta
+    })
+
+    return await this.executeQuery(query)
+  }
+
   /**
    * Builds and executes a molecule to create a new identifier on the ledger
    *
@@ -2038,7 +2083,13 @@ export default class KnishIOClient {
     // Did the authorization molecule get accepted?
     if (response.success()) {
       // Create & set an auth token from the response data
-      const authToken = AuthToken.create(response.payload(), wallet)
+      // Map server payload field names (time/key) to AuthToken constructor names (expiresAt/pubkey)
+      const authToken = AuthToken.create({
+        token: response.token(),
+        expiresAt: response.time(),
+        pubkey: response.pubKey(),
+        encrypt: response.encrypt()
+      }, wallet)
       this.setAuthToken(authToken)
     } else {
       throw new AuthorizationRejectedException(`KnishIOClient::requestGuestAuthToken() - Authorization attempt rejected by ledger. Reason: ${ response.reason() }`)
@@ -2089,7 +2140,13 @@ export default class KnishIOClient {
     // Did the authorization molecule get accepted?
     if (response.success()) {
       // Create & set an auth token from the response data
-      const authToken = AuthToken.create(response.payload(), wallet)
+      // Map server payload field names (time/key) to AuthToken constructor names (expiresAt/pubkey)
+      const authToken = AuthToken.create({
+        token: response.token(),
+        expiresAt: response.time(),
+        pubkey: response.pubKey(),
+        encrypt: response.encrypt()
+      }, wallet)
       this.setAuthToken(authToken)
     } else {
       throw new AuthorizationRejectedException(`KnishIOClient::requestProfileAuthToken() - Authorization attempt rejected by ledger. Reason: ${ response.reason() }`)

package/src/Meta.js

@@ -59,14 +59,18 @@ export default class Meta {
   static normalizeMeta (meta) {
     // Ensuring that only object-based meta gets normalized
     if (Array.isArray(meta)) {
-      return meta
+      return meta.map(entry => ({
+        key: entry.key,
+        value: entry.value == null ? null : String(entry.value)
+      }))
     }
 
     // Converting object-based meta into array-based notation
     const target = []
     for (const property in meta) {
       if (Object.prototype.hasOwnProperty.call(meta, property)) {
-        target.push({ key: property, value: meta[property] })
+        const raw = meta[property]
+        target.push({ key: property, value: raw == null ? null : String(raw) })
       }
     }