@wishknish/knishio-client-ts 0.7.4 → 0.7.7

package/src/KnishIOClient.ts

@@ -49,7 +49,8 @@ License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
 import Decimal from '@/libraries/Decimal'
 import GraphQLClient from '@/libraries/GraphQLClient'
 import {
-  generateBundleHash
+  generateBundleHash,
+  generateSecret
 } from '@/libraries/crypto'
 import Molecule from '@/core/Molecule'
 import Wallet from '@/core/Wallet'
@@ -57,6 +58,7 @@ import AuthToken from '@/AuthToken'
 import Query from '@/query/Query'
 import Mutation from '@/mutation/Mutation'
 import Response from '@/response/Response'
+import ResponseRequestAuthorization from '@/response/ResponseRequestAuthorization'
 
 // 2025 TypeScript: Zod validation integration
 import {
@@ -81,6 +83,7 @@ import QueryActiveSession from '@/query/QueryActiveSession'
 import QueryUserActivity from '@/query/QueryUserActivity'
 import QueryToken from '@/query/QueryToken'
 import QueryMetaTypeViaAtom from '@/query/QueryMetaTypeViaAtom'
+import QueryMetaTypeViaMolecule from '@/query/QueryMetaTypeViaMolecule'
 
 // Mutation imports
 import MutationCreateToken from '@/mutation/MutationCreateToken'
@@ -97,6 +100,8 @@ import MutationWithdrawBufferToken from '@/mutation/MutationWithdrawBufferToken'
 import MutationRequestAuthorization from '@/mutation/MutationRequestAuthorization'
 import MutationRequestAuthorizationGuest from '@/mutation/MutationRequestAuthorizationGuest'
 import MutationLinkIdentifier from '@/mutation/MutationLinkIdentifier'
+import MutationPeering from '@/mutation/MutationPeering'
+import MutationAppendRequest from '@/mutation/MutationAppendRequest'
 
 // Subscribe imports
 import CreateMoleculeSubscribe from '@/subscribe/CreateMoleculeSubscribe'
@@ -110,7 +115,8 @@ import {
   UnauthenticatedException,
   TransferBalanceException,
   WalletShadowException,
-  StackableUnitAmountException
+  StackableUnitAmountException,
+  AuthorizationRejectedException
 } from '@/exception'
 
 // Type imports
@@ -140,6 +146,7 @@ export default class KnishIOClient {
   private $__logging: boolean = false
   private $__authTokenObjects: Record<string, AuthToken | null> = {}
   private $__authToken: AuthToken | null = null
+  private $__authInProcess: boolean = false
   private $__remainderWallet: Wallet | null = null
   private lastMoleculeQuery: Mutation | null = null
   private abortControllers: Map<string, AbortController> = new Map()
@@ -331,6 +338,10 @@ export default class KnishIOClient {
     } else {
       this.$__uris = uri
     }
+    // Update the underlying GraphQL client's URI
+    if (this.$__client && 'setUri' in this.$__client) {
+      (this.$__client as any).setUri(this.getRandomUri())
+    }
   }
 
   /**
@@ -403,7 +414,8 @@ export default class KnishIOClient {
   }
 
   /**
-   * Creates a new molecule for a transaction
+   * Instantiates a new Molecule and prepares this client session to operate on it
+   * Matches JavaScript SDK createMolecule implementation
    */
   async createMolecule({
     secret = null,
@@ -421,6 +433,28 @@ 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: string | null = 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 || null
+        this.log('info', `KnishIOClient::createMolecule() - Captured USER ContinuID position ${continuIdPosition?.substring(0, 16)}... for non-USER source wallet`)
+      } else {
+        // Query server for current ContinuID position
+        const userWallet = await this.getSourceWallet()
+        continuIdPosition = userWallet?.position || null
+        this.log('info', `KnishIOClient::createMolecule() - Queried USER ContinuID position ${continuIdPosition?.substring(0, 16)}... for non-USER source wallet`)
+      }
+    }
+
     // Sets the source wallet as the last remainder wallet (to maintain ContinuID)
     if (!sourceWallet &&
       this.lastMoleculeQuery &&
@@ -429,19 +463,30 @@ export default class KnishIOClient {
       this.lastMoleculeQuery.response()?.success()
     ) {
       sourceWallet = this.getRemainderWallet()
+      this.log('info', `KnishIOClient::createMolecule() - Using carry-forward remainder wallet at position ${sourceWallet?.position?.substring(0, 16)}...`)
     }
 
     // Unable to use last remainder wallet; Figure out what wallet to use:
     if (!sourceWallet) {
-      // Get source wallet
       sourceWallet = await this.getSourceWallet()
     }
 
+    // Set the remainder wallet for the next transaction (always USER token for ContinuID)
+    this.setRemainderWallet(remainderWallet || Wallet.create({
+      secret: secret!,
+      bundle,
+      token: 'USER',
+      batchId: sourceWallet!.batchId,
+      characters: sourceWallet!.characters
+    }))
+
     return new Molecule({
       secret,
-      bundle,
       sourceWallet,
-      remainderWallet
+      remainderWallet: this.getRemainderWallet()!,
+      cellSlug: this.getCellSlug(),
+      version: this.getServerSdkVersion(),
+      continuIdPosition
     })
   }
 
@@ -477,7 +522,8 @@ export default class KnishIOClient {
    */
   async executeQuery(query: Query | Mutation, variables: Record<string, any> | null = null): Promise<Response | null> {
     // Check and refresh authorization token if needed
-    if (this.$__authToken && this.$__authToken.isExpired()) {
+    // Guard with $__authInProcess to prevent recursive auth refresh
+    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,
@@ -511,16 +557,29 @@ export default class KnishIOClient {
   }
 
   /**
-   * Gets source wallet - basic implementation
+   * Retrieves this session's wallet used for signing the next Molecule
+   * Queries ContinuID from the server to get the authoritative position
+   * Matches JavaScript SDK getSourceWallet implementation
    */
   async getSourceWallet(): Promise<Wallet> {
-    // For now, create a new wallet with the current secret
-    // In full implementation, this would query the ledger
-    return Wallet.create({
-      secret: this.getSecret(),
-      bundle: this.getBundle(),
-      token: 'USER'
-    })
+    // Match JavaScript SDK exactly: no try/catch, errors propagate
+    let sourceWallet: Wallet | null = (await this.queryContinuId({
+      bundle: this.getBundle()
+    }))?.payload() as Wallet | null
+
+    if (!sourceWallet) {
+      sourceWallet = new Wallet({
+        secret: this.getSecret()
+      })
+    } else {
+      sourceWallet.key = Wallet.generateKey({
+        secret: this.getSecret(),
+        token: sourceWallet.token,
+        position: sourceWallet.position!
+      })
+    }
+
+    return sourceWallet
   }
 
   /**
@@ -566,7 +625,7 @@ export default class KnishIOClient {
     }
 
     // Do you have enough tokens?
-    if (sourceWallet === null || Decimal.cmp(sourceWallet.balance, amount) < 0) {
+    if (sourceWallet === null || Decimal.cmp(Number(sourceWallet.balance), amount) < 0) {
       throw new TransferBalanceException()
     }
 
@@ -615,13 +674,18 @@ export default class KnishIOClient {
   }
 
   /**
-   * Request authorization token
+   * Request authorization token (guest or profile)
+   *
+   * @param secret - User secret for profile auth (null for guest)
+   * @param seed - Seed to generate secret (alternative to secret)
+   * @param cellSlug - Cell slug for scoped access
+   * @param encrypt - Whether to use encryption
    */
   async requestAuthToken({
-    secret: _secret = null,
-    seed: _seed = null,
-    cellSlug: _cellSlug = null,
-    encrypt: _encrypt = false
+    secret = null,
+    seed = null,
+    cellSlug = null,
+    encrypt = false
   }: {
     secret?: string | null
     seed?: string | null
@@ -630,12 +694,52 @@ export default class KnishIOClient {
   } = {}): Promise<Response | null> {
     // SDK versions 2 and below do not utilize an authorization token
     if (this.$__serverSdkVersion < 3) {
-      this.log('warn', 'KnishIOClient::authorize() - Server SDK version does not require an authorization...')
+      this.log('warn', 'KnishIOClient::requestAuthToken() - Server SDK version does not require authorization...')
       return null
     }
 
-    // For now, return null - full implementation would handle authorization
-    return null
+    // Generate a secret from the seed if provided
+    if (secret === null && seed) {
+      secret = generateSecret(seed)
+    }
+
+    // Set cell slug if provided
+    if (cellSlug) {
+      this.setCellSlug(cellSlug)
+    }
+
+    // Auth in process...
+    this.$__authInProcess = true
+
+    // Auth token response
+    let response: Response
+
+    // Authorized user (profile auth with secret)
+    if (secret) {
+      response = await this.requestProfileAuthToken({
+        secret,
+        encrypt
+      })
+    } else {
+      // Guest auth (no secret)
+      response = await this.requestGuestAuthToken({
+        cellSlug: cellSlug || this.getCellSlug(),
+        encrypt
+      })
+    }
+
+    // Log success
+    if (this.$__authToken) {
+      this.log('info', `KnishIOClient::requestAuthToken() - Successfully retrieved auth token...`)
+    }
+
+    // Handle encryption if needed
+    this.switchEncryption(encrypt)
+
+    // Auth process is stopped
+    this.$__authInProcess = false
+
+    return response
   }
 
   /**
@@ -756,7 +860,7 @@ export default class KnishIOClient {
 
     // Do you have enough tokens?
     const amountNum = typeof amount === 'string' ? Number(amount) : amount
-    if (sourceWallet === null || Decimal.cmp(sourceWallet.balance || 0, amountNum) < 0) {
+    if (sourceWallet === null || Decimal.cmp(Number(sourceWallet.balance || 0), amountNum) < 0) {
       throw new TransferBalanceException()
     }
 
@@ -786,7 +890,7 @@ export default class KnishIOClient {
 
     const response = await this.executeQuery(walletQuery, {
       bundleHash: bundle || this.getBundle(),
-      tokenSlug: token,
+      token,
       unspent
     })
 
@@ -851,6 +955,7 @@ export default class KnishIOClient {
     count = null,
     countBy = null,
     throughAtom = true,
+    throughMolecule = false,
     values = null,
     keys = null,
     atomValues = null
@@ -866,6 +971,7 @@ export default class KnishIOClient {
     count?: number | null
     countBy?: string | null
     throughAtom?: boolean | null
+    throughMolecule?: boolean | null
     values?: any[] | null
     keys?: string[] | null
     atomValues?: any[] | null
@@ -875,10 +981,26 @@ export default class KnishIOClient {
     let query: Query
     let variables: Record<string, any>
 
-    if (throughAtom) {
+    if (throughMolecule) {
+      query = this.createQuery(QueryMetaTypeViaMolecule)
+      variables = QueryMetaTypeViaMolecule.createVariables({
+        metaType: metaType,
+        metaId,
+        key,
+        value,
+        latest,
+        filter,
+        queryArgs,
+        countBy,
+        values,
+        keys,
+        atomValues,
+        cellSlug: this.getCellSlug()
+      })
+    } else if (throughAtom) {
       query = this.createQuery(QueryMetaTypeViaAtom)
       variables = QueryMetaTypeViaAtom.createVariables({
-        metaType,
+        metaType: metaType,
         metaId,
         key,
         value,
@@ -894,7 +1016,7 @@ export default class KnishIOClient {
     } else {
       query = this.createQuery(QueryMetaType)
       variables = QueryMetaType.createVariables({
-        metaType,
+        metaType: metaType,
         metaId,
         key,
         value,
@@ -910,6 +1032,34 @@ export default class KnishIOClient {
     return this.executeQuery(query, variables) as Promise<Response>
   }
 
+  /**
+   * Queries meta assets and verifies cryptographic integrity of associated molecules.
+   * Forces throughMolecule=true to ensure molecule data is available for verification.
+   * Returns the same response as queryMeta(), with an additional `integrity` field on the payload.
+   */
+  async queryMetaVerified(params: {
+    metaType: MetaType | string
+    metaId?: MetaId | string | null
+    key?: string | null
+    value?: string | null
+    latest?: boolean | null
+    fields?: string[] | null
+    filter?: MetaFilter[] | null
+    queryArgs?: Record<string, any> | null
+    count?: number | null
+    countBy?: string | null
+    values?: any[] | null
+    keys?: string[] | null
+    atomValues?: any[] | null
+  }): Promise<Response> {
+    const response = await this.queryMeta({ ...params, throughMolecule: true })
+    const payload = response.payload()
+    if (payload && typeof (response as any).verifyIntegrity === 'function') {
+      payload.integrity = (response as any).verifyIntegrity()
+    }
+    return response
+  }
+
   /**
    * Query cascading meta instances for batchId
    */
@@ -1281,7 +1431,7 @@ export default class KnishIOClient {
     const recipientWallet = new Wallet({
       secret: this.getSecret(),
       bundle: this.getBundle(),
-      token: token.toUpperCase(),
+      token,
       batchId: batchId as any
     })
 
@@ -1327,7 +1477,7 @@ export default class KnishIOClient {
 
     // Initialize the request tokens mutation
     await mutation.fillMolecule({
-      token: token.toUpperCase(),
+      token,
       amount: amount ?? 0,
       metaType: to || '',
       metaId: to || '',
@@ -1369,14 +1519,26 @@ export default class KnishIOClient {
       })
     }
 
+    // Create remainder wallet from source (must be same token for V-isotope conservation)
+    const remainderWallet = sourceWallet.createRemainder(this.getSecret())
+
+    // Create molecule with the token-specific source and remainder wallets
+    const molecule = await this.createMolecule({
+      sourceWallet,
+      remainderWallet
+    })
+
     // Create a transfer to null address (burn)
-    const mutation = await this.createMoleculeMutation({ mutationClass: MutationTransferTokens })
+    const mutation = await this.createMoleculeMutation({
+      mutationClass: MutationTransferTokens,
+      molecule
+    })
 
     // Create recipient wallet for burn address
     const recipientWallet = new Wallet({
       secret: this.getSecret(),
       bundle: '0000000000000000000000000000000000000000000000000000000000000000',
-      token: token.toUpperCase()
+      token
     })
 
     await mutation.fillMolecule({
@@ -1461,7 +1623,7 @@ export default class KnishIOClient {
     const newWallet = new Wallet({
       secret: this.getSecret(),
       bundle: this.getBundle(),
-      token: token.toUpperCase()
+      token
     })
 
     // Initialize the create wallet mutation
@@ -1516,7 +1678,7 @@ export default class KnishIOClient {
 
     // Initialize the claim shadow wallet mutation
     await mutation.fillMolecule({
-      token: token.toUpperCase() as TokenSlug,
+      token: token as TokenSlug,
       batchId: shadowWallet.batchId
     })
 
@@ -1587,14 +1749,20 @@ export default class KnishIOClient {
   }): Promise<Response> {
     this.log('info', `KnishIOClient::createMeta() - Creating metadata for ${metaType}:${metaId}...`)
 
-    // Create the molecule mutation
-    const mutation = await this.createMoleculeMutation({ mutationClass: MutationCreateMeta })
+    // Create the molecule mutation — let createMolecule() handle sourceWallet via
+    // carry-forward (remainder wallet from prior mutation) or server fallback
+    const mutation = await this.createMoleculeMutation({
+      mutationClass: MutationCreateMeta,
+      molecule: await this.createMolecule({
+        secret: this.getSecret()
+      })
+    })
 
     // Initialize the create meta mutation
     await mutation.fillMolecule({
-      metaType: metaType.toUpperCase(),
+      metaType,
       metaId,
-      meta,
+      meta: meta || {},
       policy
     })
 
@@ -1624,12 +1792,18 @@ export default class KnishIOClient {
   }): Promise<Response> {
     this.log('info', `KnishIOClient::createRule() - Creating rule for ${metaType}:${metaId}...`)
 
-    // Create the molecule mutation
-    const mutation = await this.createMoleculeMutation({ mutationClass: MutationCreateRule })
+    // Create the molecule mutation — let createMolecule() handle sourceWallet via
+    // carry-forward (remainder wallet from prior mutation) or server fallback
+    const mutation = await this.createMoleculeMutation({
+      mutationClass: MutationCreateRule,
+      molecule: await this.createMolecule({
+        secret: this.getSecret()
+      })
+    })
 
     // Initialize the create rule mutation
     await mutation.fillMolecule({
-      metaType: metaType.toUpperCase() as MetaType,
+      metaType: metaType as MetaType,
       metaId: metaId as MetaId,
       rule,
       policy
@@ -1764,10 +1938,10 @@ export default class KnishIOClient {
     // Create the mutation (extends Mutation directly, not MutationProposeMolecule)
     const mutation = this.createQuery(MutationActiveSession)
 
-    // Execute with variables
+    // Execute with variables (bundleHash matches GraphQL variable name)
     const response = await this.executeQuery(mutation, {
-      bundle: bundle || this.getBundle(),
-      metaType: metaType.toUpperCase(),
+      bundleHash: bundle || this.getBundle(),
+      metaType,
       metaId,
       ipAddress,
       browser,
@@ -1808,8 +1982,20 @@ export default class KnishIOClient {
       })
     }
 
+    // Create remainder wallet from source (must be same token)
+    const remainderWallet = sourceWallet.createRemainder(this.getSecret())
+
+    // Build the molecule with the token-specific source and remainder wallets
+    const molecule = await this.createMolecule({
+      sourceWallet,
+      remainderWallet
+    })
+
     // Create the molecule mutation
-    const mutation = await this.createMoleculeMutation({ mutationClass: MutationDepositBufferToken })
+    const mutation = await this.createMoleculeMutation({
+      mutationClass: MutationDepositBufferToken,
+      molecule
+    })
 
     // Initialize the deposit buffer token mutation
     await mutation.fillMolecule({
@@ -1909,6 +2095,7 @@ export default class KnishIOClient {
 
   /**
    * Request profile authentication token
+   * Matches JavaScript SDK requestProfileAuthToken implementation
    */
   async requestProfileAuthToken({
     secret,
@@ -1916,27 +2103,58 @@ export default class KnishIOClient {
   }: {
     secret: string
     encrypt?: boolean
-  }): Promise<Response> {
+  }): Promise<ResponseRequestAuthorization> {
     this.log('info', 'KnishIOClient::requestProfileAuthToken() - Requesting profile auth token...')
 
     // Set the secret
     this.setSecret(secret)
 
-    // Create the molecule mutation
-    const mutation = await this.createMoleculeMutation({ mutationClass: MutationRequestAuthorization })
+    // Generate a signing wallet with AUTH token (matching JavaScript SDK)
+    const wallet = new Wallet({
+      secret,
+      token: 'AUTH'
+    })
+
+    // Create a molecule with the AUTH wallet as source
+    const molecule = await this.createMolecule({
+      secret,
+      sourceWallet: wallet
+    })
+
+    // Create the mutation with this specific molecule
+    const mutation = await this.createMoleculeMutation({
+      mutationClass: MutationRequestAuthorization,
+      molecule
+    })
 
     // Initialize the profile auth mutation
-    await mutation.fillMolecule({
+    mutation.fillMolecule({
       meta: { encrypt: encrypt ? 'true' : 'false' }
     })
 
     // Execute the mutation
-    const response = await this.executeQuery(mutation)
+    const response = await this.executeQuery(mutation) as ResponseRequestAuthorization
 
     if (!response) {
       throw new CodeException('Profile auth token request failed')
     }
 
+    // Did the authorization molecule get accepted?
+    if (response.success()) {
+      // Create & set an auth token from the response data
+      const authToken = AuthToken.create({
+        token: response.token(),
+        expiresAt: response.expiresAt(),
+        encrypt: String(response.encrypt()) === 'true',
+        pubkey: response.pubKey()
+      }, wallet)
+      this.setAuthToken(authToken)
+    } else {
+      throw new AuthorizationRejectedException(
+        `KnishIOClient::requestProfileAuthToken() - Authorization attempt rejected by ledger. Reason: ${response.reason()}`
+      )
+    }
+
     // Handle encryption if needed
     if (encrypt) {
       this.switchEncryption(true)
@@ -1945,6 +2163,83 @@ export default class KnishIOClient {
     return response
   }
 
+  // =============================================================================
+  // MUTATION METHODS - PEERING & APPEND REQUEST
+  // =============================================================================
+
+  /**
+   * Register a peer node via P-isotope
+   * Matches JavaScript SDK registerPeer implementation exactly
+   */
+  async registerPeer({ host }: { host: string }): Promise<Response> {
+    this.log('info', `KnishIOClient::registerPeer() - Registering peer at ${host}...`)
+
+    // Create the molecule mutation — let createMolecule() handle sourceWallet via
+    // carry-forward (remainder wallet from prior mutation) or server fallback
+    const mutation = await this.createMoleculeMutation({
+      mutationClass: MutationPeering,
+      molecule: await this.createMolecule({
+        secret: this.getSecret()
+      })
+    })
+
+    // Fill the molecule with peering data
+    mutation.fillMolecule({ host })
+
+    // Execute the mutation
+    const response = await this.executeQuery(mutation)
+
+    if (!response) {
+      throw new CodeException('Peer registration failed')
+    }
+
+    return response
+  }
+
+  /**
+   * Submit an append request via A-isotope
+   * Matches JavaScript SDK appendRequest implementation exactly
+   */
+  async appendRequest({
+    metaType,
+    metaId,
+    action,
+    meta = {}
+  }: {
+    metaType: string
+    metaId: string
+    action: string
+    meta?: Record<string, any>
+  }): Promise<Response> {
+    this.log('info', `KnishIOClient::appendRequest() - Submitting append request for ${metaType}:${metaId}...`)
+
+    // Create the molecule mutation — let createMolecule() handle sourceWallet via
+    // carry-forward (remainder wallet from prior mutation) or server fallback
+    const mutation = await this.createMoleculeMutation({
+      mutationClass: MutationAppendRequest,
+      molecule: await this.createMolecule({
+        secret: this.getSecret()
+      })
+    })
+
+    // Fill the molecule with append request data
+    mutation.fillMolecule({
+      metaType,
+      metaId,
+      action,
+      meta
+    })
+
+    // Execute the mutation
+    const response = await this.executeQuery(mutation)
+
+    if (!response) {
+      throw new CodeException('Append request failed')
+    }
+
+    return response
+  }
+
   // =============================================================================
   // LEGACY/DEPRECATED METHODS
   // =============================================================================