@wishknish/knishio-client-js 0.8.0 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-js",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "type": "module",
   "productName": "Knish.IO Javascript SDK Client",
   "description": "JavaScript implementation of the Knish.IO SDK to consume Knish.IO GraphQL APIs.",

package/src/Atom.js

@@ -212,7 +212,7 @@ export default class Atom {
 
   /**
    * 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.
    *
@@ -226,15 +226,15 @@ export default class Atom {
     const {
       includeOtsFragments = true,
       validateFields = false
-    } = options;
+    } = options
 
     try {
       // Validate required fields if requested
       if (validateFields) {
-        const requiredFields = ['position', 'walletAddress', 'isotope', 'token'];
+        const requiredFields = ['position', 'walletAddress', 'isotope', 'token']
         for (const field of requiredFields) {
           if (!this[field]) {
-            throw new Error(`Required field '${field}' is missing or empty`);
+            throw new Error(`Required field '${field}' is missing or empty`)
           }
         }
       }
@@ -258,23 +258,22 @@ export default class Atom {
         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;
+        serialized.otsFragment = this.otsFragment
       }
 
-      return serialized;
-
+      return serialized
     } catch (error) {
-      throw new Error(`Atom serialization failed: ${error.message}`);
+      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.
    *
@@ -289,18 +288,18 @@ export default class Atom {
     const {
       validateStructure = true,
       strictMode = false
-    } = options;
+    } = options
 
     try {
       // Parse JSON safely
-      const data = typeof json === 'string' ? JSON.parse(json) : json;
+      const data = typeof json === 'string' ? JSON.parse(json) : json
 
       // Validate required fields in strict mode
       if (strictMode || validateStructure) {
-        const requiredFields = ['position', 'walletAddress', 'isotope', 'token'];
+        const requiredFields = ['position', 'walletAddress', 'isotope', 'token']
         for (const field of requiredFields) {
           if (!data[field]) {
-            throw new Error(`Required field '${field}' is missing or empty`);
+            throw new Error(`Required field '${field}' is missing or empty`)
           }
         }
       }
@@ -318,20 +317,19 @@ export default class Atom {
         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;
+        atom.otsFragment = data.otsFragment
       }
       if (data.createdAt) {
-        atom.createdAt = data.createdAt;
+        atom.createdAt = data.createdAt
       }
 
-      return atom;
-
+      return atom
     } catch (error) {
-      throw new Error(`Atom deserialization failed: ${error.message}`);
+      throw new Error(`Atom deserialization failed: ${error.message}`)
     }
   }
 

package/src/KnishIOClient.js

@@ -127,7 +127,8 @@ export default class KnishIOClient {
     client = null,
     socket = null,
     serverSdkVersion = 3,
-    logging = false
+    logging = false,
+    defaultRequestPolicy = null
   }) {
     this.initialize({
       uri,
@@ -135,7 +136,8 @@ export default class KnishIOClient {
       socket,
       client,
       serverSdkVersion,
-      logging
+      logging,
+      defaultRequestPolicy
     })
   }
 
@@ -155,11 +157,16 @@ export default class KnishIOClient {
     socket = null,
     client = null,
     serverSdkVersion = 3,
-    logging = false
+    logging = false,
+    defaultRequestPolicy = null
   }) {
     this.reset()
 
     this.$__logging = logging
+    // Client-level urql request policy applied to reads that omit a per-call
+    // policy. A long-lived server/sync client set to 'network-only' never serves
+    // a stale cache-first read; browser/SPA consumers leave this null (cache-first).
+    this.$__defaultRequestPolicy = defaultRequestPolicy
     this.$__authTokenObjects = {}
     this.$__authInProcess = false
     this.abortControllers = new Map()
@@ -247,6 +254,25 @@ export default class KnishIOClient {
     return this.$__serverSdkVersion
   }
 
+  /**
+   * Returns the client-level default urql request policy (or null)
+   *
+   * @return {string|null}
+   */
+  getDefaultRequestPolicy () {
+    return this.$__defaultRequestPolicy || null
+  }
+
+  /**
+   * Sets the client-level default urql request policy applied to reads that
+   * omit a per-call policy (e.g. 'network-only' for a long-lived server client)
+   *
+   * @param {string|null} policy - 'cache-first'|'cache-only'|'network-only'|'cache-and-network'|null
+   */
+  setDefaultRequestPolicy (policy) {
+    this.$__defaultRequestPolicy = policy
+  }
+
   /**
    * Reset common properties
    */
@@ -255,6 +281,7 @@ export default class KnishIOClient {
     this.$__bundle = ''
     this.remainderWallet = null
     this.$__capabilityCache = {}
+    this.$__defaultRequestPolicy = null
   }
 
   /**
@@ -555,15 +582,15 @@ export default class KnishIOClient {
    * @param molecule
    */
   async createMoleculeMutation ({
-    mutationClass,
+    mutationClass: MutationClass,
     molecule = null
   }) {
-    this.log('info', `KnishIOClient::createMoleculeQuery() - Creating a new ${ mutationClass.name } query...`)
+    this.log('info', `KnishIOClient::createMoleculeQuery() - Creating a new ${ MutationClass.name } query...`)
 
     // If you don't supply the molecule, we'll generate one for you
     const _molecule = molecule || await this.createMolecule({})
 
-    const mutation = new mutationClass(this.client(), this, _molecule)
+    const mutation = new MutationClass(this.client(), this, _molecule)
 
     if (!(mutation instanceof MutationProposeMolecule)) {
       throw new CodeException(`${ this.constructor.name }::createMoleculeMutation() - This method only accepts MutationProposeMolecule!`)
@@ -580,7 +607,7 @@ export default class KnishIOClient {
    * @param variables
    * @returns {Promise<*>}
    */
-  async executeQuery (query, variables = null) {
+  async executeQuery (query, variables = null, context = {}) {
     // Check and refresh authorization token if needed
     // Guard with $__authInProcess to prevent concurrent auth requests
     if (this.$__authToken && this.$__authToken.isExpired() && !this.$__authInProcess) {
@@ -601,13 +628,25 @@ export default class KnishIOClient {
     this.abortControllers.set(queryKey, abortController)
 
     try {
+      // Apply the client-level default request policy when neither the caller
+      // nor the query's own createQueryContext specifies one, so a long-lived
+      // server/sync client (defaultRequestPolicy:'network-only') never serves a
+      // stale cache-first read. Precedence: a query's own createQueryContext
+      // (e.g. ContinuId's network-only, applied in Query.execute's merge) >
+      // per-call context.requestPolicy > this client default > urql default.
+      const requestContext = { ...context }
+      if (this.$__defaultRequestPolicy && !requestContext.requestPolicy) {
+        requestContext.requestPolicy = this.$__defaultRequestPolicy
+      }
+
       // Use the existing query execution method, but add the abort signal
       const result = await query.execute({
         variables,
         context: {
           fetchOptions: {
             signal: abortController.signal
-          }
+          },
+          ...requestContext
         }
       })
 
@@ -839,7 +878,8 @@ export default class KnishIOClient {
     throughMolecule = false,
     values = null,
     keys = null,
-    atomValues = null
+    atomValues = null,
+    requestPolicy = null
   }) {
     this.log('info', `KnishIOClient::queryMeta() - Querying metaType: ${ metaType }, metaId: ${ metaId }...`)
 
@@ -903,7 +943,7 @@ export default class KnishIOClient {
       })
     }
 
-    return this.executeQuery(query, variables)
+    return this.executeQuery(query, variables, requestPolicy ? { requestPolicy } : {})
   }
 
   /**

package/src/Molecule.js

@@ -264,7 +264,13 @@ export default class Molecule {
         const condition = totalCondition ? mappedHashArray[index] < 8 : mappedHashArray[index] > -8
 
         if (condition) {
-          const process = totalCondition ? [++mappedHashArray[index], ++total] : [--mappedHashArray[index], --total]
+          if (totalCondition) {
+            ++mappedHashArray[index]
+            ++total
+          } else {
+            --mappedHashArray[index]
+            --total
+          }
 
           if (total === 0) {
             break
@@ -716,7 +722,7 @@ export default class Molecule {
   }) {
     // Calculate final amount from all recipients
     let amount = 0
-    for (const [recipientBundle, recipientAmount] of Object.entries(recipients || {})) {
+    for (const recipientAmount of Object.values(recipients || {})) {
       amount += recipientAmount
     }
     if (this.sourceWallet.balance - amount < 0) {
@@ -1184,7 +1190,7 @@ export default class Molecule {
     const {
       includeValidationContext = false,
       includeOtsFragments = true
-    } = options;
+    } = options
 
     try {
       // Core molecule properties (server-compatible fields only)
@@ -1199,7 +1205,7 @@ export default class Molecule {
         atoms: this.atoms.map(atom => atom.toJSON({
           includeOtsFragments
         }))
-      };
+      }
 
       // Parent molecular hashes for DAG linkage (only include when non-empty
       // to maintain backward compatibility with servers that don't support it)
@@ -1225,7 +1231,7 @@ export default class Molecule {
             tokenUnits: this.sourceWallet.tokenUnits || [],
             tradeRates: this.sourceWallet.tradeRates || {},
             molecules: this.sourceWallet.molecules || {}
-          };
+          }
         }
 
         if (this.remainderWallet) {
@@ -1241,14 +1247,13 @@ export default class Molecule {
             tokenUnits: this.remainderWallet.tokenUnits || [],
             tradeRates: this.remainderWallet.tradeRates || {},
             molecules: this.remainderWallet.molecules || {}
-          };
+          }
         }
       }
 
-      return serialized;
-
+      return serialized
     } catch (error) {
-      throw new Error(`Molecule serialization failed: ${error.message}`);
+      throw new Error(`Molecule serialization failed: ${error.message}`)
     }
   }
 
@@ -1269,16 +1274,16 @@ export default class Molecule {
     const {
       includeValidationContext = false,
       validateStructure = true
-    } = options;
+    } = options
 
     try {
       // Parse JSON safely
-      const data = typeof json === 'string' ? JSON.parse(json) : json;
+      const data = typeof json === 'string' ? JSON.parse(json) : json
 
       // Validate required fields in strict mode
       if (validateStructure) {
         if (!data.molecularHash || !Array.isArray(data.atoms)) {
-          throw new Error('Invalid molecule data: missing molecularHash or atoms array');
+          throw new Error('Invalid molecule data: missing molecularHash or atoms array')
         }
       }
 
@@ -1288,24 +1293,24 @@ export default class Molecule {
         bundle: data.bundle || null,
         cellSlug: data.cellSlug || null,
         version: data.version || null
-      });
+      })
 
       // Populate core properties
-      molecule.status = data.status;
-      molecule.molecularHash = data.molecularHash;
-      molecule.createdAt = data.createdAt || String(+new Date());
-      molecule.cellSlugOrigin = data.cellSlugOrigin;
-      molecule.parentHashes = Array.isArray(data.parentHashes) ? [...data.parentHashes] : [];
+      molecule.status = data.status
+      molecule.molecularHash = data.molecularHash
+      molecule.createdAt = data.createdAt || String(+new Date())
+      molecule.cellSlugOrigin = data.cellSlugOrigin
+      molecule.parentHashes = Array.isArray(data.parentHashes) ? [...data.parentHashes] : []
 
       // Reconstruct atoms array with proper Atom instances
       if (Array.isArray(data.atoms)) {
         molecule.atoms = data.atoms.map((atomData, index) => {
           try {
-            return Atom.fromJSON(atomData);
+            return Atom.fromJSON(atomData)
           } catch (error) {
-            throw new Error(`Failed to reconstruct atom ${index}: ${error.message}`);
+            throw new Error(`Failed to reconstruct atom ${index}: ${error.message}`)
           }
-        });
+        })
       }
 
       // Reconstruct validation context if available and requested
@@ -1319,17 +1324,17 @@ export default class Molecule {
             bundle: data.sourceWallet.bundle,
             batchId: data.sourceWallet.batchId,
             characters: data.sourceWallet.characters
-          });
+          })
 
           // Set additional properties for validation context
-          molecule.sourceWallet.balance = String(data.sourceWallet.balance != null ? data.sourceWallet.balance : 0);
-          molecule.sourceWallet.address = data.sourceWallet.address;
+          molecule.sourceWallet.balance = String(data.sourceWallet.balance != null ? data.sourceWallet.balance : 0)
+          molecule.sourceWallet.address = data.sourceWallet.address
           if (data.sourceWallet.pubkey) {
-            molecule.sourceWallet.pubkey = data.sourceWallet.pubkey;
+            molecule.sourceWallet.pubkey = data.sourceWallet.pubkey
           }
-          molecule.sourceWallet.tokenUnits = data.sourceWallet.tokenUnits || [];
-          molecule.sourceWallet.tradeRates = data.sourceWallet.tradeRates || {};
-          molecule.sourceWallet.molecules = data.sourceWallet.molecules || {};
+          molecule.sourceWallet.tokenUnits = data.sourceWallet.tokenUnits || []
+          molecule.sourceWallet.tradeRates = data.sourceWallet.tradeRates || {}
+          molecule.sourceWallet.molecules = data.sourceWallet.molecules || {}
         }
 
         if (data.remainderWallet) {
@@ -1341,24 +1346,23 @@ export default class Molecule {
             bundle: data.remainderWallet.bundle,
             batchId: data.remainderWallet.batchId,
             characters: data.remainderWallet.characters
-          });
+          })
 
           // Set additional properties for validation context
-          molecule.remainderWallet.balance = String(data.remainderWallet.balance != null ? data.remainderWallet.balance : 0);
-          molecule.remainderWallet.address = data.remainderWallet.address;
+          molecule.remainderWallet.balance = String(data.remainderWallet.balance != null ? data.remainderWallet.balance : 0)
+          molecule.remainderWallet.address = data.remainderWallet.address
           if (data.remainderWallet.pubkey) {
-            molecule.remainderWallet.pubkey = data.remainderWallet.pubkey;
+            molecule.remainderWallet.pubkey = data.remainderWallet.pubkey
           }
-          molecule.remainderWallet.tokenUnits = data.remainderWallet.tokenUnits || [];
-          molecule.remainderWallet.tradeRates = data.remainderWallet.tradeRates || {};
-          molecule.remainderWallet.molecules = data.remainderWallet.molecules || {};
+          molecule.remainderWallet.tokenUnits = data.remainderWallet.tokenUnits || []
+          molecule.remainderWallet.tradeRates = data.remainderWallet.tradeRates || {}
+          molecule.remainderWallet.molecules = data.remainderWallet.molecules || {}
         }
       }
 
-      return molecule;
-
+      return molecule
     } catch (error) {
-      throw new Error(`Molecule deserialization failed: ${error.message}`);
+      throw new Error(`Molecule deserialization failed: ${error.message}`)
     }
   }
 

package/src/Wallet.js

@@ -283,11 +283,11 @@ export default class Wallet {
    * Initializes the ML-KEM key pair
    */
   initializeMLKEM () {
-    // Generate a 64-byte (512-bit) seed from the Knish.IO private key  
+    // Generate a 64-byte (512-bit) seed from the Knish.IO private key
     // Use deterministic approach: generateSecret(key, 128) → 128 hex chars = 64 bytes
-    const seedHex = generateSecret(this.key, 128)  // 128 hex chars = 64 bytes
+    const seedHex = generateSecret(this.key, 128) // 128 hex chars = 64 bytes
 
-    // Convert the hex string to a Uint8Array  
+    // Convert the hex string to a Uint8Array
     const seed = new Uint8Array(64)
     for (let i = 0; i < 64; i++) {
       seed[i] = parseInt(seedHex.substr(i * 2, 2), 16)

package/src/instance/Rules/Callback.js

@@ -52,6 +52,7 @@ import { isNumeric } from '../../libraries/strings.js'
 import { intersect } from '../../libraries/array.js'
 import CodeException from '../../exception/CodeException.js'
 
+/* eslint-disable accessor-pairs -- intentional setter-only fluent rule builder; values are read directly via __field, no getter needed */
 export default class Callback {
   /**
    *

package/src/instance/Rules/Meta.js

@@ -47,9 +47,7 @@ License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
 
 export default class Meta {
-  constructor ({}) {
-    const args = arguments[0]
-
+  constructor (args = {}) {
     for (const key in args) {
       this[`__${ key }`] = args[key]
     }

package/src/instance/Rules/Rule.js

@@ -51,6 +51,7 @@ import Condition from './Condition.js'
 import RuleArgumentException from './exception/RuleArgumentException.js'
 import MetaMissingException from '../../exception/MetaMissingException.js'
 
+/* eslint-disable accessor-pairs -- intentional setter-only fluent rule builder; values are read directly via __field, no getter needed */
 export default class Rule {
   /**
    *

package/src/libraries/strings.js

@@ -1,5 +1,6 @@
 import Hex from './Hex.js'
 
+/* eslint-disable no-extend-native -- intentional guarded String.prototype polyfill (trim) + SDK camel/snake-case helpers relied on across the codebase */
 if (!String.prototype.trim) {
   String.prototype.trim = function () {
     return this.replace(/^[\s\uFEFF\xA0]+|[\s\uFEFF\xA0]+$/g, '')

package/src/libraries/urql/UrqlClientWrapper.js

@@ -67,15 +67,56 @@ class UrqlClientWrapper {
     })
   }
 
+  /**
+   * Builds the urql operation options forwarded with a query/mutation.
+   *
+   * Forwards the requestPolicy (so a long-lived client does not serve stale
+   * cache-first reads) and, when the caller supplied a per-query abort signal,
+   * the signal too — while re-supplying the X-Auth-Token header. urql REPLACES
+   * (not merges) the client-level fetchOptions with any operation-context
+   * fetchOptions (createRequestOperation builds the op context as
+   * {...baseOpts, ...opts}), so forwarding fetchOptions WITHOUT the header would
+   * drop X-Auth-Token and break auth. The header here is byte-identical to the
+   * client-level one set in createUrqlClient.
+   *
+   * @param {object} context
+   * @returns {object|undefined}
+   */
+  buildRequestOptions (context) {
+    if (!context) {
+      return undefined
+    }
+    const opts = {}
+    if (context.requestPolicy) {
+      opts.requestPolicy = context.requestPolicy
+    }
+    const callerSignal = context.fetchOptions && context.fetchOptions.signal
+    if (callerSignal) {
+      // Combine the per-query abort signal with the 60s timeout so either can
+      // cancel the request; fall back to the caller signal where AbortSignal.any
+      // is unavailable.
+      const signal = (typeof AbortSignal !== 'undefined' && typeof AbortSignal.any === 'function')
+        ? AbortSignal.any([callerSignal, AbortSignal.timeout(60000)])
+        : callerSignal
+      opts.fetchOptions = {
+        headers: { 'X-Auth-Token': this.$__authToken },
+        signal
+      }
+    }
+    return Object.keys(opts).length ? opts : undefined
+  }
+
   async query (request) {
-    const { query, variables } = request
-    const result = await this.$__client.query(query, variables).toPromise()
+    const { query, variables, context } = request
+    const opts = this.buildRequestOptions(context)
+    const result = await this.$__client.query(query, variables || {}, opts).toPromise()
     return this.formatResponse(result)
   }
 
   async mutate (request) {
-    const { mutation, variables } = request
-    const result = await this.$__client.mutation(mutation, variables).toPromise()
+    const { mutation, variables, context } = request
+    const opts = this.buildRequestOptions(context)
+    const result = await this.$__client.mutation(mutation, variables || {}, opts).toPromise()
     return this.formatResponse(result)
   }
 

package/src/query/QueryPolicy.js

@@ -48,7 +48,7 @@ License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 
 import Query from './Query.js'
 import ResponsePolicy from '../response/ResponsePolicy.js'
-import { gql } from "@urql/core";
+import { gql } from '@urql/core'
 
 export default class QueryPolicy extends Query {
   /**

package/src/response/Response.js

@@ -176,7 +176,7 @@ export default class Response {
   /**
    * Enhanced interface methods for standardized response handling
    */
-  
+
   /**
    * Get error reason (alias for error() to match standardized interface)
    * @return {string|null}
@@ -247,7 +247,7 @@ export default class Response {
    */
   debug (label = null) {
     const debugPrefix = label ? `[${label}]` : `[${this.constructor.name}]`
-    
+
     if (this.success()) {
       console.debug(`${debugPrefix} Success:`, {
         payload: this.payload(),
@@ -261,7 +261,7 @@ export default class Response {
         rawData: this.$__response
       })
     }
-    
+
     return this
   }
 

package/src/response/ResponseActiveSession.js

@@ -46,7 +46,6 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
 
-import Query from '../query/Query.js'
 import Response from './Response.js'
 
 export default class ResponseActiveSession extends Response {

package/src/response/ResponseAtom.js

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

package/src/response/ResponseAuthorizationGuest.js

@@ -46,7 +46,6 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
 
-import Query from '../query/Query.js'
 import Response from './Response.js'
 import Dot from '../libraries/Dot.js'
 import InvalidResponseException from '../exception/InvalidResponseException.js'

package/src/response/ResponseBalance.js

@@ -45,7 +45,6 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
-import Query from '../query/Query.js'
 import Response from './Response.js'
 import ResponseWalletList from './ResponseWalletList.js'
 

package/src/response/ResponseContinuId.js

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

package/src/response/ResponseLinkIdentifier.js

@@ -45,7 +45,6 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
-import Query from '../query/Query.js'
 import Response from './Response.js'
 import Dot from '../libraries/Dot.js'
 

package/src/response/ResponseMetaType.js

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

package/src/response/ResponseMetaTypeViaAtom.js

@@ -46,7 +46,6 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
 
-import Query from '../query/Query.js'
 import Response from './Response.js'
 
 export default class ResponseMetaTypeViaAtom extends Response {