@wishknish/knishio-client-ts 0.7.2 → 0.7.6

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
@@ -121,7 +127,8 @@ import type {
   CellSlug,
   MetaType,
   MetaId,
-  BatchId
+  BatchId,
+  MetaFilter
 } from '@/types'
 
 /**
@@ -139,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()
@@ -330,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())
+    }
   }
 
   /**
@@ -402,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,
@@ -428,19 +441,29 @@ 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()
     })
   }
 
@@ -476,7 +499,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,
@@ -510,16 +534,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
   }
 
   /**
@@ -565,7 +602,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()
     }
 
@@ -614,13 +651,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
@@ -629,12 +671,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
   }
 
   /**
@@ -755,7 +837,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()
     }
 
@@ -785,7 +867,7 @@ export default class KnishIOClient {
 
     const response = await this.executeQuery(walletQuery, {
       bundleHash: bundle || this.getBundle(),
-      tokenSlug: token,
+      token,
       unspent
     })
 
@@ -849,7 +931,8 @@ export default class KnishIOClient {
     queryArgs = null,
     count = null,
     countBy = null,
-    throughAtom = null,
+    throughAtom = true,
+    throughMolecule = false,
     values = null,
     keys = null,
     atomValues = null
@@ -860,11 +943,12 @@ export default class KnishIOClient {
     value?: string | null
     latest?: boolean | null
     fields?: string[] | null
-    filter?: string | null
+    filter?: MetaFilter[] | null
     queryArgs?: Record<string, any> | null
     count?: number | null
     countBy?: string | null
     throughAtom?: boolean | null
+    throughMolecule?: boolean | null
     values?: any[] | null
     keys?: string[] | null
     atomValues?: any[] | null
@@ -872,50 +956,85 @@ export default class KnishIOClient {
     this.log('info', `KnishIOClient::queryMeta() - Querying metaType: ${metaType}, metaId: ${metaId}...`)
 
     let query: Query
-
-    if (throughAtom === true) {
+    let variables: Record<string, any>
+
+    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,
+        metaId,
+        key,
+        value,
+        latest,
+        filter,
+        queryArgs,
+        countBy,
+        values,
+        keys,
+        atomValues,
+        cellSlug: this.getCellSlug()
+      })
     } else {
       query = this.createQuery(QueryMetaType)
+      variables = QueryMetaType.createVariables({
+        metaType: metaType,
+        metaId,
+        key,
+        value,
+        latest,
+        filter,
+        queryArgs,
+        count,
+        countBy,
+        cellSlug: this.getCellSlug()
+      })
     }
 
-    const variables: Record<string, any> = {
-      metaType: metaType.toUpperCase(),
-      metaId
-    }
+    return this.executeQuery(query, variables) as Promise<Response>
+  }
 
-    if (filter !== null) {
-      variables.filter = filter
-    }
-    if (latest !== null) {
-      variables.latest = latest
-    }
-    if (key !== null) {
-      variables.key = key
-    }
-    if (value !== null) {
-      variables.value = value
-    }
-    if (queryArgs !== null) {
-      variables.queryArgs = queryArgs
-    }
-    if (count !== null) {
-      variables.count = count
-    }
-    if (countBy !== null) {
-      variables.countBy = countBy
-    }
-    if (values !== null) {
-      variables.values = values
-    }
-    if (keys !== null) {
-      variables.keys = keys
-    }
-    if (atomValues !== null) {
-      variables.atomValues = atomValues
+  /**
+   * 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 this.executeQuery(query, variables) as Promise<Response>
+    return response
   }
 
   /**
@@ -1008,42 +1127,43 @@ export default class KnishIOClient {
     metaId?: string | null
     indexes?: number[] | null
     index?: number | null
-    filter?: string | null
+    filter?: MetaFilter[] | null
     latest?: boolean | null
     queryArgs?: Record<string, any> | null
   } = {}): Promise<Response> {
+    this.log('info', 'KnishIOClient::queryAtom() - Querying atom instances')
+
     const query = this.createQuery(QueryAtom)
 
-    const variables: Record<string, any> = {}
-
-    // Add all non-null parameters to variables
-    if (molecularHashes !== null) variables.molecularHashes = molecularHashes
-    if (molecularHash !== null) variables.molecularHash = molecularHash
-    if (bundleHashes !== null) variables.bundleHashes = bundleHashes
-    if (bundleHash !== null) variables.bundleHash = bundleHash
-    if (positions !== null) variables.positions = positions
-    if (position !== null) variables.position = position
-    if (walletAddresses !== null) variables.walletAddresses = walletAddresses
-    if (walletAddress !== null) variables.walletAddress = walletAddress
-    if (isotopes !== null) variables.isotopes = isotopes
-    if (isotope !== null) variables.isotope = isotope
-    if (tokenSlugs !== null) variables.tokenSlugs = tokenSlugs
-    if (tokenSlug !== null) variables.tokenSlug = tokenSlug
-    if (cellSlugs !== null) variables.cellSlugs = cellSlugs
-    if (cellSlug !== null) variables.cellSlug = cellSlug
-    if (batchIds !== null) variables.batchIds = batchIds
-    if (batchId !== null) variables.batchId = batchId
-    if (values !== null) variables.values = values
-    if (value !== null) variables.value = value
-    if (metaTypes !== null) variables.metaTypes = metaTypes
-    if (metaType !== null) variables.metaType = metaType
-    if (metaIds !== null) variables.metaIds = metaIds
-    if (metaId !== null) variables.metaId = metaId
-    if (indexes !== null) variables.indexes = indexes
-    if (index !== null) variables.index = index
-    if (filter !== null) variables.filter = filter
-    if (latest !== null) variables.latest = latest
-    if (queryArgs !== null) variables.queryArgs = queryArgs
+    const variables = QueryAtom.createVariables({
+      molecularHashes,
+      molecularHash,
+      bundleHashes,
+      bundleHash,
+      positions,
+      position,
+      walletAddresses,
+      walletAddress,
+      isotopes,
+      isotope,
+      tokenSlugs,
+      tokenSlug,
+      cellSlugs,
+      cellSlug,
+      batchIds,
+      batchId,
+      values,
+      value,
+      metaTypes,
+      metaType,
+      metaIds,
+      metaId,
+      indexes,
+      index,
+      filter,
+      latest,
+      queryArgs
+    })
 
     return this.executeQuery(query, variables) as Promise<Response>
   }
@@ -1288,7 +1408,7 @@ export default class KnishIOClient {
     const recipientWallet = new Wallet({
       secret: this.getSecret(),
       bundle: this.getBundle(),
-      token: token.toUpperCase(),
+      token,
       batchId: batchId as any
     })
 
@@ -1334,7 +1454,7 @@ export default class KnishIOClient {
 
     // Initialize the request tokens mutation
     await mutation.fillMolecule({
-      token: token.toUpperCase(),
+      token,
       amount: amount ?? 0,
       metaType: to || '',
       metaId: to || '',
@@ -1376,14 +1496,22 @@ export default class KnishIOClient {
       })
     }
 
+    // Create molecule with the source wallet (same pattern as transferToken)
+    const molecule = await this.createMolecule({
+      sourceWallet
+    })
+
     // 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({
@@ -1468,7 +1596,7 @@ export default class KnishIOClient {
     const newWallet = new Wallet({
       secret: this.getSecret(),
       bundle: this.getBundle(),
-      token: token.toUpperCase()
+      token
     })
 
     // Initialize the create wallet mutation
@@ -1523,7 +1651,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
     })
 
@@ -1594,14 +1722,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
     })
 
@@ -1631,12 +1765,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
@@ -1771,10 +1911,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,
@@ -1916,6 +2056,7 @@ export default class KnishIOClient {
 
   /**
    * Request profile authentication token
+   * Matches JavaScript SDK requestProfileAuthToken implementation
    */
   async requestProfileAuthToken({
     secret,
@@ -1923,27 +2064,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)
@@ -1952,6 +2124,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
   // =============================================================================