@wishknish/knishio-client-js 0.7.5 → 0.7.7

package/package.json

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

package/src/KnishIOClient.js

@@ -73,6 +73,7 @@ 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 MutationLinkIdentifier from './mutation/MutationLinkIdentifier.js'
 import MutationCreateWallet from './mutation/MutationCreateWallet.js'
 import MutationRequestAuthorizationGuest from './mutation/MutationRequestAuthorizationGuest.js'
 import TransferBalanceException from './exception/TransferBalanceException.js'
@@ -456,6 +457,26 @@ export default class KnishIOClient {
     secret = secret || this.getSecret()
     bundle = bundle || this.getBundle()
 
+    // For non-USER source wallets (V/B isotopes), capture the current USER
+    // ContinuID position BEFORE overwriting the client's remainder wallet.
+    // This position is needed by addContinuIdAtom() for previousPosition metadata.
+    let continuIdPosition = null
+    if (sourceWallet && sourceWallet.token !== 'USER') {
+      if (this.lastMoleculeQuery &&
+        this.getRemainderWallet() &&
+        this.getRemainderWallet().token === 'USER' &&
+        this.lastMoleculeQuery.response() &&
+        this.lastMoleculeQuery.response().success()
+      ) {
+        // Carry-forward: use last successful USER remainder wallet position
+        continuIdPosition = this.getRemainderWallet().position
+      } else {
+        // Query server for current ContinuID position
+        const userWallet = await this.getSourceWallet()
+        continuIdPosition = userWallet ? userWallet.position : null
+      }
+    }
+
     // Sets the source wallet as the last remainder wallet (to maintain ContinuID)
     if (!sourceWallet &&
       this.lastMoleculeQuery &&
@@ -485,7 +506,8 @@ export default class KnishIOClient {
       sourceWallet,
       remainderWallet: this.getRemainderWallet(),
       cellSlug: this.getCellSlug(),
-      version: this.getServerSdkVersion()
+      version: this.getServerSdkVersion(),
+      continuIdPosition
     })
   }
 
@@ -1248,8 +1270,7 @@ export default class KnishIOClient {
     const query = await this.createMoleculeMutation({
         mutationClass: MutationCreateRule,
         molecule: await this.createMolecule({
-          secret: this.getSecret(),
-          sourceWallet: await this.getSourceWallet()
+          secret: this.getSecret()
         })
       }
     )
@@ -1285,8 +1306,7 @@ export default class KnishIOClient {
     const query = await this.createMoleculeMutation({
         mutationClass: MutationCreateMeta,
         molecule: await this.createMolecule({
-          secret: this.getSecret(),
-          sourceWallet: await this.getSourceWallet()
+          secret: this.getSecret()
         })
       }
     )
@@ -1318,8 +1338,7 @@ export default class KnishIOClient {
     const query = await this.createMoleculeMutation({
       mutationClass: MutationPeering,
       molecule: await this.createMolecule({
-        secret: this.getSecret(),
-        sourceWallet: await this.getSourceWallet()
+        secret: this.getSecret()
       })
     })
 
@@ -1351,8 +1370,7 @@ export default class KnishIOClient {
     const query = await this.createMoleculeMutation({
       mutationClass: MutationAppendRequest,
       molecule: await this.createMolecule({
-        secret: this.getSecret(),
-        sourceWallet: await this.getSourceWallet()
+        secret: this.getSecret()
       })
     })
 
@@ -1395,6 +1413,25 @@ export default class KnishIOClient {
     return await this.executeQuery(query)
   }
 
+  /**
+   * Links an identifier to the current wallet bundle
+   *
+   * @param {string} type - The type of the identifier.
+   * @param {string} contact - The contact associated with the identifier.
+   * @returns {Promise<ResponseLinkIdentifier>} - A promise that resolves to the link result.
+   */
+  async linkIdentifier ({
+    type,
+    contact
+  }) {
+    const query = this.createQuery(MutationLinkIdentifier)
+    return await this.executeQuery(query, {
+      bundle: this.getBundle(),
+      type,
+      content: contact
+    })
+  }
+
   /**
    * Creates a policy for a given metaType and metaId.
    *
@@ -1473,7 +1510,7 @@ export default class KnishIOClient {
 
     return this.executeQuery(walletQuery, {
       bundleHash: bundle || this.getBundle(),
-      tokenSlug: token,
+      token,
       unspent
     })
       .then((response) => {
@@ -1948,7 +1985,7 @@ export default class KnishIOClient {
     molecule.sign({
       bundle: this.getBundle()
     })
-    molecule.check()
+    molecule.check(sourceWallet)
 
     // Create & execute a mutation
     const query = await this.createMoleculeMutation({
@@ -2131,7 +2168,7 @@ export default class KnishIOClient {
       // Map server payload field names (time/key) to AuthToken constructor names (expiresAt/pubkey)
       const authToken = AuthToken.create({
         token: response.token(),
-        expiresAt: response.time(),
+        expiresAt: response.expiresAt(),
         pubkey: response.pubKey(),
         encrypt: response.encrypt()
       }, wallet)
@@ -2188,7 +2225,7 @@ export default class KnishIOClient {
       // Map server payload field names (time/key) to AuthToken constructor names (expiresAt/pubkey)
       const authToken = AuthToken.create({
         token: response.token(),
-        expiresAt: response.time(),
+        expiresAt: response.expiresAt(),
         pubkey: response.pubKey(),
         encrypt: response.encrypt()
       }, wallet)

package/src/Molecule.js

@@ -86,7 +86,8 @@ export default class Molecule {
     sourceWallet = null,
     remainderWallet = null,
     cellSlug = null,
-    version = null
+    version = null,
+    continuIdPosition = null
   }) {
     this.status = null
     this.molecularHash = null
@@ -95,6 +96,7 @@ export default class Molecule {
     this.secret = secret
     this.bundle = bundle
     this.sourceWallet = sourceWallet
+    this.continuIdPosition = continuIdPosition
     this.atoms = []
     this.parentHashes = []
     if (version !== null && Object.prototype.hasOwnProperty.call(versions, version)) {
@@ -343,8 +345,12 @@ export default class Molecule {
     // These are atom meta fields (not core fields), so they don't affect molecular hash.
     const continuIdMeta = {}
 
-    // previousPosition: the source wallet's position being consumed
-    if (this.sourceWallet && this.sourceWallet.position) {
+    // previousPosition: the current USER ContinuID position being consumed.
+    // For non-USER source wallets (V/B isotopes), use the explicitly passed
+    // continuIdPosition from createMolecule() instead of the TOKEN wallet position.
+    if (this.continuIdPosition) {
+      continuIdMeta.previousPosition = this.continuIdPosition
+    } else if (this.sourceWallet && this.sourceWallet.position) {
       continuIdMeta.previousPosition = this.sourceWallet.position
     }
 
@@ -464,11 +470,29 @@ export default class Molecule {
       throw new BalanceInsufficientException()
     }
 
+    // Create burn address wallet (null bundle = token destruction)
+    const burnWallet = new Wallet({
+      bundle: '0000000000000000000000000000000000000000000000000000000000000000',
+      token: this.sourceWallet.token
+    })
+
+    // V-atom 1: Debit full balance from source
     this.addAtom(Atom.create({
       isotope: 'V',
       wallet: this.sourceWallet,
-      value: -amount
+      value: -this.sourceWallet.balance
     }))
+
+    // V-atom 2: Credit burn amount to burn address
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: burnWallet,
+      value: amount,
+      metaType: 'walletBundle',
+      metaId: burnWallet.bundle
+    }))
+
+    // V-atom 3: Remainder back to source identity
     this.addAtom(Atom.create({
       isotope: 'V',
       wallet: this.remainderWallet,

package/src/index.js

@@ -46,17 +46,112 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
  */
 
+// =============================================================================
+// CORE CLASSES
+// =============================================================================
+
 import Atom from './Atom.js'
+import AtomMeta from './AtomMeta.js'
 import Molecule from './Molecule.js'
 import Wallet from './Wallet.js'
 import Meta from './Meta.js'
+import AuthToken from './AuthToken.js'
+import TokenUnit from './TokenUnit.js'
+import PolicyMeta from './PolicyMeta.js'
 import KnishIOClient from './KnishIOClient.js'
-import MutationPeering from './mutation/MutationPeering.js'
-import MutationAppendRequest from './mutation/MutationAppendRequest.js'
+
+// Validation
+import CheckMolecule from './libraries/CheckMolecule.js'
+
+// Utilities
+import Dot from './libraries/Dot.js'
+import Decimal from './libraries/Decimal.js'
+
+// =============================================================================
+// BASE CLASSES
+// =============================================================================
+
+import Query from './query/Query.js'
+import Mutation from './mutation/Mutation.js'
+import Response from './response/Response.js'
+
+// =============================================================================
+// QUERY CLASSES
+// =============================================================================
+
+import QueryActiveSession from './query/QueryActiveSession.js'
+import QueryAtom from './query/QueryAtom.js'
+import QueryBalance from './query/QueryBalance.js'
+import QueryBatch from './query/QueryBatch.js'
+import QueryBatchHistory from './query/QueryBatchHistory.js'
+import QueryContinuId from './query/QueryContinuId.js'
+import QueryMetaType from './query/QueryMetaType.js'
+import QueryMetaTypeViaAtom from './query/QueryMetaTypeViaAtom.js'
 import QueryMetaTypeViaMolecule from './query/QueryMetaTypeViaMolecule.js'
-import ResponsePeering from './response/ResponsePeering.js'
+import QueryPolicy from './query/QueryPolicy.js'
+import QueryToken from './query/QueryToken.js'
+import QueryUserActivity from './query/QueryUserActivity.js'
+import QueryWalletBundle from './query/QueryWalletBundle.js'
+import QueryWalletList from './query/QueryWalletList.js'
+
+// =============================================================================
+// MUTATION CLASSES
+// =============================================================================
+
+import MutationActiveSession from './mutation/MutationActiveSession.js'
+import MutationAppendRequest from './mutation/MutationAppendRequest.js'
+import MutationClaimShadowWallet from './mutation/MutationClaimShadowWallet.js'
+import MutationCreateIdentifier from './mutation/MutationCreateIdentifier.js'
+import MutationCreateMeta from './mutation/MutationCreateMeta.js'
+import MutationCreateRule from './mutation/MutationCreateRule.js'
+import MutationCreateToken from './mutation/MutationCreateToken.js'
+import MutationCreateWallet from './mutation/MutationCreateWallet.js'
+import MutationDepositBufferToken from './mutation/MutationDepositBufferToken.js'
+import MutationLinkIdentifier from './mutation/MutationLinkIdentifier.js'
+import MutationPeering from './mutation/MutationPeering.js'
+import MutationProposeMolecule from './mutation/MutationProposeMolecule.js'
+import MutationRequestAuthorization from './mutation/MutationRequestAuthorization.js'
+import MutationRequestAuthorizationGuest from './mutation/MutationRequestAuthorizationGuest.js'
+import MutationRequestTokens from './mutation/MutationRequestTokens.js'
+import MutationTransferTokens from './mutation/MutationTransferTokens.js'
+import MutationWithdrawBufferToken from './mutation/MutationWithdrawBufferToken.js'
+
+// =============================================================================
+// RESPONSE CLASSES
+// =============================================================================
+
+import ResponseActiveSession from './response/ResponseActiveSession.js'
 import ResponseAppendRequest from './response/ResponseAppendRequest.js'
+import ResponseAtom from './response/ResponseAtom.js'
+import ResponseAuthorizationGuest from './response/ResponseAuthorizationGuest.js'
+import ResponseBalance from './response/ResponseBalance.js'
+import ResponseClaimShadowWallet from './response/ResponseClaimShadowWallet.js'
+import ResponseContinuId from './response/ResponseContinuId.js'
+import ResponseCreateIdentifier from './response/ResponseCreateIdentifier.js'
+import ResponseCreateMeta from './response/ResponseCreateMeta.js'
+import ResponseCreateRule from './response/ResponseCreateRule.js'
+import ResponseCreateToken from './response/ResponseCreateToken.js'
+import ResponseCreateWallet from './response/ResponseCreateWallet.js'
+import ResponseLinkIdentifier from './response/ResponseLinkIdentifier.js'
+import ResponseMetaType from './response/ResponseMetaType.js'
+import ResponseMetaTypeViaAtom from './response/ResponseMetaTypeViaAtom.js'
 import ResponseMetaTypeViaMolecule from './response/ResponseMetaTypeViaMolecule.js'
+import ResponsePeering from './response/ResponsePeering.js'
+import ResponsePolicy from './response/ResponsePolicy.js'
+import ResponseProposeMolecule from './response/ResponseProposeMolecule.js'
+import ResponseQueryActiveSession from './response/ResponseQueryActiveSession.js'
+import ResponseQueryUserActivity from './response/ResponseQueryUserActivity.js'
+import ResponseRequestAuthorization from './response/ResponseRequestAuthorization.js'
+import ResponseRequestAuthorizationGuest from './response/ResponseRequestAuthorizationGuest.js'
+import ResponseRequestTokens from './response/ResponseRequestTokens.js'
+import ResponseTransferTokens from './response/ResponseTransferTokens.js'
+import ResponseWalletBundle from './response/ResponseWalletBundle.js'
+import ResponseWalletList from './response/ResponseWalletList.js'
+
+// =============================================================================
+// LIBRARY FUNCTIONS
+// =============================================================================
+
 import {
   base64ToHex,
   bufferToHexString,
@@ -65,34 +160,149 @@ import {
   hexStringToBuffer,
   hexToBase64,
   isHex,
+  isNumeric,
   randomString
 } from './libraries/strings.js'
+
 import {
+  generateBatchId,
   generateBundleHash,
   generateSecret,
   shake256
 } from './libraries/crypto.js'
 
+import {
+  chunkArray,
+  deepCloning,
+  diff,
+  intersect
+} from './libraries/array.js'
+
+// =============================================================================
+// EXCEPTION SYSTEM
+// =============================================================================
+
 export {
+  AtomIndexException,
+  AtomsMissingException,
+  AuthorizationRejectedException,
+  BalanceInsufficientException,
+  BatchIdException,
+  CodeException,
+  InvalidResponseException,
+  MetaMissingException,
+  MolecularHashMismatchException,
+  MolecularHashMissingException,
+  NegativeAmountException,
+  PolicyInvalidException,
+  SignatureMalformedException,
+  SignatureMismatchException,
+  StackableUnitAmountException,
+  StackableUnitDecimalsException,
+  TransferBalanceException,
+  TransferMalformedException,
+  TransferMismatchedException,
+  TransferRemainderException,
+  TransferToSelfException,
+  TransferUnbalancedException,
+  UnauthenticatedException,
+  WalletShadowException,
+  WrongTokenTypeException
+} from './exception/index.js'
+
+// =============================================================================
+// NAMED EXPORTS
+// =============================================================================
+
+export {
+  // Core classes
   Atom,
+  AtomMeta,
   Molecule,
   Wallet,
   Meta,
+  AuthToken,
+  TokenUnit,
+  PolicyMeta,
   KnishIOClient,
 
-  // queries
+  // Validation
+  CheckMolecule,
+
+  // Utilities
+  Dot,
+  Decimal,
+
+  // Base classes
+  Query,
+  Mutation,
+  Response,
+
+  // Queries
+  QueryActiveSession,
+  QueryAtom,
+  QueryBalance,
+  QueryBatch,
+  QueryBatchHistory,
+  QueryContinuId,
+  QueryMetaType,
+  QueryMetaTypeViaAtom,
   QueryMetaTypeViaMolecule,
+  QueryPolicy,
+  QueryToken,
+  QueryUserActivity,
+  QueryWalletBundle,
+  QueryWalletList,
 
-  // mutations
-  MutationPeering,
+  // Mutations
+  MutationActiveSession,
   MutationAppendRequest,
+  MutationClaimShadowWallet,
+  MutationCreateIdentifier,
+  MutationCreateMeta,
+  MutationCreateRule,
+  MutationCreateToken,
+  MutationCreateWallet,
+  MutationDepositBufferToken,
+  MutationLinkIdentifier,
+  MutationPeering,
+  MutationProposeMolecule,
+  MutationRequestAuthorization,
+  MutationRequestAuthorizationGuest,
+  MutationRequestTokens,
+  MutationTransferTokens,
+  MutationWithdrawBufferToken,
 
-  // responses
-  ResponsePeering,
+  // Responses
+  ResponseActiveSession,
   ResponseAppendRequest,
+  ResponseAtom,
+  ResponseAuthorizationGuest,
+  ResponseBalance,
+  ResponseClaimShadowWallet,
+  ResponseContinuId,
+  ResponseCreateIdentifier,
+  ResponseCreateMeta,
+  ResponseCreateRule,
+  ResponseCreateToken,
+  ResponseCreateWallet,
+  ResponseLinkIdentifier,
+  ResponseMetaType,
+  ResponseMetaTypeViaAtom,
   ResponseMetaTypeViaMolecule,
+  ResponsePeering,
+  ResponsePolicy,
+  ResponseProposeMolecule,
+  ResponseQueryActiveSession,
+  ResponseQueryUserActivity,
+  ResponseRequestAuthorization,
+  ResponseRequestAuthorizationGuest,
+  ResponseRequestTokens,
+  ResponseTransferTokens,
+  ResponseWalletBundle,
+  ResponseWalletList,
 
-  // strings
+  // String utilities
   chunkSubstr,
   base64ToHex,
   bufferToHexString,
@@ -100,10 +310,18 @@ export {
   hexStringToBuffer,
   hexToBase64,
   isHex,
+  isNumeric,
   randomString,
 
-  // crypto
+  // Crypto utilities
   generateSecret,
   generateBundleHash,
-  shake256
+  generateBatchId,
+  shake256,
+
+  // Array utilities
+  chunkArray,
+  deepCloning,
+  diff,
+  intersect
 }

package/src/query/QueryContinuId.js

@@ -75,6 +75,14 @@ export default class QueryContinuId extends Query {
     }`
   }
 
+  /**
+   * Force network-only for ContinuID queries to prevent URQL cache from
+   * returning stale wallet positions after mutations advance the ContinuID chain
+   */
+  createQueryContext () {
+    return { requestPolicy: 'network-only' }
+  }
+
   /**
    * Returns a Response object
    *

package/src/query/QueryWalletList.js

@@ -60,8 +60,8 @@ export default class QueryWalletList extends Query {
   constructor (graphQLClient, knishIOClient) {
     super(graphQLClient, knishIOClient)
 
-    this.$__query = gql`query( $bundleHash: String, $tokenSlug: String ) {
-      Wallet( bundleHash: $bundleHash, tokenSlug: $tokenSlug ) {
+    this.$__query = gql`query( $bundleHash: String, $token: String ) {
+      Wallet( bundleHash: $bundleHash, token: $token ) {
         address,
         bundleHash,
         token {

package/src/response/ResponseRequestAuthorization.js

@@ -76,7 +76,7 @@ export default class ResponseRequestAuthorization extends ResponseProposeMolecul
   }
 
   /**
-   * Returns timestamp
+   * Returns raw time value from payload
    *
    * @return {string}
    */
@@ -84,6 +84,39 @@ export default class ResponseRequestAuthorization extends ResponseProposeMolecul
     return this.payloadKey('time')
   }
 
+  /**
+   * Returns the expiration timestamp as Unix seconds.
+   * Handles both server formats:
+   * - PHP server: time = lifetime in ms, expiresAt = Unix timestamp in payload
+   * - Rust server: time = Unix timestamp in seconds
+   *
+   * @return {number}
+   */
+  expiresAt () {
+    // Try the explicit expiresAt payload key first (PHP server provides this)
+    try {
+      const ea = this.payloadKey('expiresAt')
+      if (ea) {
+        return Number(ea)
+      }
+    } catch (_e) {
+      // Not available in payload, fall back
+    }
+
+    // Use time field with heuristic detection
+    const timeValue = Number(this.time())
+
+    // If timeValue looks like a valid Unix timestamp (>= year 2020), use directly
+    // Rust server sets time = Unix timestamp in seconds
+    if (timeValue >= 1577836800) {
+      return timeValue
+    }
+
+    // Otherwise, time is a lifetime in milliseconds (PHP server format)
+    // Convert to Unix timestamp: now_seconds + lifetime_seconds
+    return Math.floor(Date.now() / 1000) + Math.floor(timeValue / 1000)
+  }
+
   /**
    *
    * @return {string}

package/src/response/ResponseRequestAuthorizationGuest.js

@@ -120,7 +120,7 @@ export default class ResponseRequestAuthorizationGuest extends Response {
   }
 
   /**
-   * Returns timestamp
+   * Returns raw time value from payload
    *
    * @return {*}
    */
@@ -128,6 +128,37 @@ export default class ResponseRequestAuthorizationGuest extends Response {
     return this.payloadKey('time')
   }
 
+  /**
+   * Returns the expiration timestamp as Unix seconds.
+   * Handles both server formats:
+   * - PHP server: time = lifetime in ms, expiresAt = Unix timestamp in payload
+   * - Rust server: time = Unix timestamp in seconds
+   *
+   * @return {number}
+   */
+  expiresAt () {
+    // Try the explicit expiresAt payload key first (PHP server provides this)
+    try {
+      const ea = this.payloadKey('expiresAt')
+      if (ea) {
+        return Number(ea)
+      }
+    } catch (_e) {
+      // Not available in payload, fall back
+    }
+
+    // Use time field with heuristic detection
+    const timeValue = Number(this.time())
+
+    // If timeValue looks like a valid Unix timestamp (>= year 2020), use directly
+    if (timeValue >= 1577836800) {
+      return timeValue
+    }
+
+    // Otherwise, time is a lifetime in milliseconds (PHP server format)
+    return Math.floor(Date.now() / 1000) + Math.floor(timeValue / 1000)
+  }
+
   /**
    * Returns timestamp
    *