@wishknish/knishio-client-ts 0.7.4 → 0.7.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-ts",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "productName": "Knish.IO TypeScript SDK Client",
   "description": "TypeScript implementation of the Knish.IO SDK to consume Knish.IO GraphQL APIs with enhanced type safety.",
   "license": "GPL-3.0-or-later",
@@ -58,24 +58,30 @@
     "fips-203"
   ],
   "dependencies": {
-    "@noble/post-quantum": "^0.5.2",
+    "@noble/post-quantum": "^0.5.4",
     "@thumbmarkjs/thumbmarkjs": "^0.19.1",
     "@urql/core": "^5.2.0",
     "graphql": "^16.11.0",
-    "graphql-ws": "^6.0.6",
+    "graphql-ws": "^6.0.7",
     "isomorphic-fetch": "^3.0.0",
     "jssha": "^3.3.1",
+    "tslib": "^2.8.1",
     "wonka": "^6.3.5",
     "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/isomorphic-fetch": "^0.0.39",
+    "@types/jest": "^30.0.0",
     "@types/jssha": "^3.0.0",
     "@types/node": "^22.8.1",
+    "@types/pg": "^8.10.0",
     "@typescript-eslint/eslint-plugin": "^8.15.0",
     "@typescript-eslint/parser": "^8.15.0",
     "eslint": "^9.16.0",
+    "jest": "^30.2.0",
+    "pg": "^8.11.0",
     "prettier": "^3.4.2",
+    "ts-jest": "^29.4.6",
     "tsup": "^8.3.5",
     "tsx": "^4.20.5",
     "typescript": "^5.6.3",
@@ -109,7 +115,7 @@
     "README.md",
     "LICENSE"
   ],
-  "packageManager": "yarn@4.10.3",
+  "packageManager": "yarn@4.6.0",
   "engines": {
     "node": ">=18.0.0"
   }

package/src/AuthToken.ts

@@ -162,12 +162,18 @@ export default class AuthToken {
     return this.$__encrypt
   }
 
+  /**
+   * Get expire interval in milliseconds (matching JS SDK pattern)
+   */
+  getExpireInterval(): number {
+    return (this.$__expiresAt * 1000) - Date.now()
+  }
+
   /**
    * Check if token is expired
    */
   isExpired(): boolean {
-    const now = Math.floor(Date.now() / 1000)
-    return now >= this.$__expiresAt
+    return !this.$__expiresAt || this.getExpireInterval() < 0
   }
 
   /**

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,
@@ -429,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()
     })
   }
 
@@ -477,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,
@@ -511,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
   }
 
   /**
@@ -566,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()
     }
 
@@ -615,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
@@ -630,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
   }
 
   /**
@@ -756,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()
     }
 
@@ -786,7 +867,7 @@ export default class KnishIOClient {
 
     const response = await this.executeQuery(walletQuery, {
       bundleHash: bundle || this.getBundle(),
-      tokenSlug: token,
+      token,
       unspent
     })
 
@@ -851,6 +932,7 @@ export default class KnishIOClient {
     count = null,
     countBy = null,
     throughAtom = true,
+    throughMolecule = false,
     values = null,
     keys = null,
     atomValues = null
@@ -866,6 +948,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 +958,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 +993,7 @@ export default class KnishIOClient {
     } else {
       query = this.createQuery(QueryMetaType)
       variables = QueryMetaType.createVariables({
-        metaType,
+        metaType: metaType,
         metaId,
         key,
         value,
@@ -910,6 +1009,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 +1408,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 +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 || '',
@@ -1369,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({
@@ -1461,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
@@ -1516,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
     })
 
@@ -1587,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
     })
 
@@ -1624,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
@@ -1764,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,
@@ -1909,6 +2056,7 @@ export default class KnishIOClient {
 
   /**
    * Request profile authentication token
+   * Matches JavaScript SDK requestProfileAuthToken implementation
    */
   async requestProfileAuthToken({
     secret,
@@ -1916,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)
@@ -1945,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
   // =============================================================================