@wishknish/knishio-client-ts 0.9.5 → 0.9.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-ts",
-  "version": "0.9.5",
+  "version": "0.9.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,32 +58,30 @@
     "fips-203"
   ],
   "dependencies": {
-    "@noble/post-quantum": "^0.5.4",
-    "@thumbmarkjs/thumbmarkjs": "^0.19.1",
-    "@urql/core": "^5.2.0",
-    "graphql": "^16.11.0",
-    "graphql-ws": "^6.0.7",
-    "isomorphic-fetch": "^3.0.0",
-    "jssha": "^3.3.1",
+    "@noble/post-quantum": "^0.7.0",
+    "@urql/core": "^6.0.3",
+    "graphql": "^16.14.2",
+    "graphql-ws": "^6.2.1",
+    "jssha": "^3.3.2",
     "tslib": "^2.8.1",
-    "wonka": "^6.3.5",
+    "wonka": "^6.3.6",
     "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@types/isomorphic-fetch": "^0.0.39",
     "@types/jssha": "^3.0.0",
-    "@types/node": "^22",
-    "@typescript-eslint/eslint-plugin": "^8.63.0",
-    "@typescript-eslint/parser": "^8.63.0",
-    "@vitest/coverage-v8": "^4.1.10",
-    "eslint": "^9",
-    "prettier": "^3",
+    "@types/node": "^26",
+    "@typescript-eslint/eslint-plugin": "^8.67.0",
+    "@typescript-eslint/parser": "^8.67.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^10",
+    "prettier": "^3.9.6",
     "tsup": "^8.5.1",
-    "tsx": "^4.23.0",
+    "tsx": "^4.23.12",
     "typescript": "^5",
-    "vite": "^7",
-    "vite-plugin-dts": "^5.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
+  },
+  "resolutions": {
+    "wonka": "6.3.6"
   },
   "browserslist": [
     "> 1%",
@@ -103,7 +101,6 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui",
-    "dev": "vite",
     "prepublishOnly": "npm run build",
     "selftest": "npm run build && node self-test.cjs"
   },

package/src/KnishIOClient.ts

@@ -104,6 +104,7 @@ import MutationLinkIdentifier from '@/mutation/MutationLinkIdentifier'
 import MutationPeering from '@/mutation/MutationPeering'
 import MutationAppendRequest from '@/mutation/MutationAppendRequest'
 import MutationProposeMolecule from '@/mutation/MutationProposeMolecule'
+import MutationReplenishToken from '@/mutation/MutationReplenishToken'
 
 // Response imports
 import ResponseProposeMolecule from '@/response/ResponseProposeMolecule'
@@ -1836,27 +1837,55 @@ export default class KnishIOClient {
   }
 
   /**
-   * Replenish tokens
+   * Replenish a non-finite token supply.
+   * Matches JS SDK KnishIOClient.replenishToken (KnishIOClient.js:2195-2231).
    */
   async replenishToken({
     token,
     amount = null,
     units = null,
-    sourceWallet: _sourceWallet = null
+    sourceWallet = null
   }: {
     token: TokenSlug | string
     amount?: number | string | null
-    units?: string[] | null
+    units?: Array<[string, string, Record<string, any>?]> | null
     sourceWallet?: Wallet | null
   }): Promise<Response> {
     this.log('info', `KnishIOClient::replenishToken() - Replenishing ${amount || 'units'} of ${token}...`)
 
-    // Similar to requestTokens but with specific replenishment logic
-    return this.requestTokens({
-      token,
-      amount,
-      units
+    if (!sourceWallet) {
+      sourceWallet = (await this.queryBalance({ token }))?.payload() as Wallet | null
+    }
+    if (!sourceWallet) {
+      throw new TransferBalanceException('Source wallet is missing or invalid.')
+    }
+
+    // Remainder wallet (same token, so the V-isotope pair conserves)
+    const remainderWallet = sourceWallet.createRemainder(this.getSecret())
+
+    const molecule = await this.createMolecule({
+      sourceWallet,
+      remainderWallet
+    })
+    molecule.replenishToken({
+      amount: Number(amount ?? 0),
+      units: units ?? []
     })
+    molecule.sign({ bundle: this.getBundle() })
+    molecule.check()
+
+    const mutation = await this.createMoleculeMutation({
+      mutationClass: MutationReplenishToken,
+      molecule
+    })
+
+    const response = await this.executeQuery(mutation)
+
+    if (!response) {
+      throw new CodeException('Token replenishment failed')
+    }
+
+    return response
   }
 
   /**

package/src/core/AtomMeta.ts

@@ -47,6 +47,7 @@ License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
 */
 
 import Meta, { type NormalizedMeta } from './Meta'
+import PolicyMeta from './PolicyMeta'
 
 // Configuration constants matching JS SDK
 const USE_META_CONTEXT = false
@@ -172,12 +173,19 @@ export default class AtomMeta {
    * @return This instance for chaining
    */
   addPolicy(policy: Record<string, any>): AtomMeta {
-    // For now, just stringify the policy
-    // TODO: Implement PolicyMeta class if needed
+    // Normalise through PolicyMeta before serialising. PolicyMeta.fillDefault adds a default
+    // entry for every meta key not already covered by the caller's policy, so the stored string
+    // carries materially more than the input — and this string is hashed into the atom, so a
+    // raw JSON.stringify(policy) diverges from every other SDK.
+    // Matches JS SDK AtomMeta.addPolicy (AtomMeta.js:170-175), including passing
+    // Object.keys(this.meta): `meta` is a NormalizedMeta[] in both SDKs, so these are array
+    // indices rather than meta key names. Faithful to the JS behaviour — do not "correct" it.
+    const policyMeta = new PolicyMeta(policy, Object.keys(this.meta))
+
     this.merge({
-      policy: JSON.stringify(policy)
+      policy: policyMeta.toJson()
     })
-    
+
     return this
   }
 

package/src/core/Molecule.ts

@@ -755,6 +755,67 @@ export default class Molecule {
     return this
   }
 
+  /**
+   * Replenishes non-finite token supplies.
+   * Matches JS SDK Molecule.replenishToken (Molecule.js:521-566) exactly.
+   *
+   * Two orderings here are load-bearing for the molecular hash and must not be reordered:
+   * the remainder balance is computed BEFORE the source balance is overwritten, and the
+   * source V-atom is added BEFORE the remainder V-atom.
+   */
+  replenishToken({
+    amount,
+    units = []
+  }: {
+    amount: number
+    units?: Array<[string, string, Record<string, any>?]>
+  }): Molecule {
+    if (amount < 0) {
+      throw new NegativeAmountException('Molecule::replenishToken() - Amount to replenish must be positive!')
+    }
+
+    if (!this.sourceWallet || !this.remainderWallet) {
+      throw new Error('Source and remainder wallets required for token replenishment')
+    }
+
+    if (units.length) {
+      // Prepare token units to formatted style
+      const formatted = Wallet.getTokenUnits(units)
+
+      // Merge token units with source wallet & new items
+      this.remainderWallet.tokenUnits = this.sourceWallet.tokenUnits
+      for (const unit of formatted) {
+        this.remainderWallet.tokenUnits.push(unit)
+      }
+      this.remainderWallet.balance = String(this.remainderWallet.tokenUnits.length)
+
+      // Override first atom's token units to replenish values
+      this.sourceWallet.tokenUnits = formatted
+      this.sourceWallet.balance = String(this.sourceWallet.tokenUnits.length)
+    } else {
+      // Update wallet's balances
+      this.remainderWallet.balance = String(Number(this.sourceWallet.balance) + amount)
+      this.sourceWallet.balance = String(amount)
+    }
+
+    // Initializing a new Atom to remove tokens from source
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: this.sourceWallet,
+      value: Number(this.sourceWallet.balance)
+    }))
+
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: this.remainderWallet,
+      value: Number(this.remainderWallet.balance),
+      metaType: 'walletBundle',
+      metaId: this.remainderWallet.bundle!
+    }))
+
+    return this
+  }
+
   /**
    * Initialize authorization request
    * Creates U-isotope (authorization) atom for requesting auth token

package/src/core/Wallet.ts

@@ -51,6 +51,7 @@ import { randomString, chunkSubstr, isHex } from '@/libraries/strings'
 import { generateBundleHash, generateSecret, shake256, generateBatchId } from '@/libraries/crypto'
 import WalletCredentialException from '@/exception/WalletCredentialException'
 import { isBundleHash } from '@/types'
+import TokenUnit from '@/core/TokenUnit'
 // Post-quantum cryptography for ML-KEM768 key encapsulation
 import { ml_kem768 } from '@noble/post-quantum/ml-kem.js'
 
@@ -271,12 +272,13 @@ export default class Wallet {
   }
 
   /**
-   * Get formatted token units from raw data
-   * Stub implementation for now
+   * Map raw token-unit tuples to TokenUnit instances.
+   * Matches JS SDK Wallet.getTokenUnits (Wallet.js:190-196). The serialised shape reaches hashed
+   * atom meta via AtomMeta.setAtomWallet -> JSON.stringify(getTokenUnitsData()), so returning raw
+   * tuples here would diverge from every other SDK.
    */
-  static getTokenUnits(unitsData: any[]): any[] {
-    // TODO: Implement TokenUnit class if needed
-    return unitsData
+  static getTokenUnits(unitsData: Array<[string, string, Record<string, any>?]>): TokenUnit[] {
+    return unitsData.map(unitData => TokenUnit.createFromDB(unitData))
   }
 
   /**

package/src/index.ts

@@ -362,7 +362,7 @@ export {
 // MUST equal package.json's "version". The CI `version consistency` job enforces this via
 // .github/scripts/check-version.sh, which parses this exact line — keep the literal form
 // `export const SDK_VERSION = '<semver>'` intact so the gate can read it.
-export const SDK_VERSION = '0.9.5'
+export const SDK_VERSION = '0.9.6'
 export const SDK_NAME = 'KnishIO-Client-TS'
 export const COMPATIBLE_SERVER_VERSIONS = [4, 5]
 

package/src/libraries/GraphQLClient.ts

@@ -141,16 +141,30 @@ export default class GraphQLClient implements IGraphQLClient {
     return createClient({
       url: serverUri,
       exchanges,
-      // PQ-transport Phase E: when encryption is on, route fetch through the CipherHash wrapper
-      // (encrypt the request body to the validator's ML-KEM pubkey, decrypt the response).
-      // Omitted → urql uses the global fetch (plaintext).
-      ...(this.cipherLink ? { fetch: ((input: any, init: any) => this.cipherFetch(input, init)) as typeof fetch } : {}),
+      // urql 5 had no default and always POSTed; urql 6 defaults to 'within-url-limit', which
+      // URL-encodes short queries and sends NO body. That would silently disable the CipherHash
+      // envelope below — cipherFetch's `typeof init.body === 'string'` guard fails on a GET, so
+      // the query would leave as plaintext URL parameters with no error. Pin POST explicitly.
+      preferGetMethod: false,
+      // Always route through our own fetch. Two reasons: (1) PQ-transport Phase E — when
+      // encryption is on, cipherFetch wraps the request body in the CipherHash envelope and
+      // decrypts the response; (2) the 60s timeout. urql's makeFetchSource unconditionally
+      // overwrites init.signal with its own AbortController, so a signal returned from
+      // fetchOptions() is discarded and never fired. Combining it here is the only place it
+      // survives.
+      fetch: ((input: RequestInfo | URL, init?: RequestInit) => {
+        const timeoutSignal = AbortSignal.timeout(60000)
+        // Keep urql's own signal so teardown still aborts; AbortSignal.any needs Node >= 18.17.
+        const signal = init?.signal && typeof AbortSignal.any === 'function'
+          ? AbortSignal.any([init.signal, timeoutSignal])
+          : (init?.signal ?? timeoutSignal)
+        const timedInit: RequestInit = { ...init, signal }
+        return this.cipherLink ? this.cipherFetch(input, timedInit) : fetch(input, timedInit)
+      }) as typeof fetch,
       fetchOptions: () => ({
         headers: {
           'X-Auth-Token': this.$__authToken
-        },
-        // Add 60 second timeout
-        signal: AbortSignal.timeout(60000)
+        }
       })
     })
   }

package/src/libraries/UrqlClientWrapper.ts

@@ -155,12 +155,17 @@ class UrqlClientWrapper {
     return createClient({
       url: serverUri,
       exchanges,
+      // urql 6 defaults preferGetMethod to 'within-url-limit', sending short queries as GET with
+      // no body. Keep the urql-5 behaviour (always POST) so this client matches GraphQLClient and
+      // cannot silently change the wire format if it is ever put back into use.
+      preferGetMethod: false,
+      // No `signal` here: urql's makeFetchSource overwrites init.signal with its own
+      // AbortController, so a timeout passed through fetchOptions() is silently discarded and
+      // never fires. GraphQLClient applies its 60s timeout inside a wrapping `fetch` instead.
       fetchOptions: () => ({
         headers: {
           'X-Auth-Token': this.$__authToken
-        },
-        // Add 60 second timeout for debugging
-        signal: AbortSignal.timeout(60000)
+        }
       })
     })
   }

package/src/libraries/crypto.ts

@@ -659,13 +659,11 @@ export function verifyOTSSignature(
     const enumerated = enumerateMolecularHash(base17Hash)
     const normalized = normalizeMolecularHash(enumerated)
     
-    // Step 2: Process OTS fragments (handle compression if needed)
-    let ots = otsFragments
+    // Step 2: Fragments must be the uncompressed 2048-character form. Base64-compressed
+    // signatures are not supported and are rejected here rather than expanded.
+    const ots = otsFragments
     if (ots.length !== 2048) {
-      // If not 2048 chars, it might be base64 compressed - for now, assume uncompressed
-      if (ots.length !== 2048) {
-        return false // Invalid signature length
-      }
+      return false
     }
     
     // Step 3: Subdivide OTS into 16 segments of 128 characters each

package/src/mutation/MutationReplenishToken.ts

@@ -0,0 +1,28 @@
+/*
+        Powered by Knish.IO: Connecting a Decentralized World
+
+Please visit https://github.com/WishKnish/KnishIO-Client-TS for information.
+
+License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
+*/
+
+import MutationProposeMolecule from './MutationProposeMolecule'
+
+/**
+ * Mutation for replenishing a non-finite token supply.
+ *
+ * The JS SDK submits replenishment through `MutationProposeMolecule` directly
+ * (KnishIOClient.js:2226-2230), but that class is abstract here because it declares
+ * `fillMolecule`. This subclass exists to provide the concrete type; it inherits the identical
+ * `ProposeMolecule(molecule: $molecule)` document from the base, so the request on the wire is
+ * the same one the JS SDK sends.
+ *
+ * `fillMolecule` is intentionally a no-op: KnishIOClient.replenishToken builds the V-atom pair
+ * via Molecule.replenishToken, then signs and checks the molecule, before this mutation is
+ * constructed. There is nothing left to fill.
+ */
+export default class MutationReplenishToken extends MutationProposeMolecule {
+  override fillMolecule(): void {
+    // Intentionally empty — the molecule arrives fully built, signed and checked.
+  }
+}

package/src/schemas/index.ts

@@ -117,7 +117,7 @@ export const MetaIdSchema = z.string()
   .brand<'MetaId'>()
 
 export const BatchIdSchema = z.string()
-  .min(1, 'Batch ID cannot be empty')
+  .regex(/^[0-9a-fA-F]{64}$/, 'Batch ID must be 64 hexadecimal characters')
   .brand<'BatchId'>()
 
 export const CellSlugSchema = z.string()

package/src/types/assertions.ts

@@ -399,12 +399,12 @@ export function assertBatchId(
 ): asserts value is BatchId {
   if (!isBatchId(value)) {
     throw new AssertionError(
-      createAssertionMessage('BatchId (UUID format)', value, context),
+      createAssertionMessage('BatchId (64-character hex)', value, context),
       'BatchId',
       value,
       { 
         operation: 'batch_id_assertion',
-        expected: 'UUID v4 format',
+        expected: '64-character hexadecimal string',
         actual: value,
         field: context
       }

package/src/validation/schemas.ts

@@ -106,12 +106,12 @@ export const TokenSlugSchema = createBrandedSchema('TokenSlug',
 )
 
 export const BatchIdSchema = createBrandedSchema('BatchId',
-  // v3's `.uuid()` regex, inlined verbatim. Zod 4's `z.uuid()` additionally enforces the
-  // RFC 9562 version/variant nibbles and would reject batch IDs v3 accepted.
-  z.string().regex(
-    /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/,
-    'Invalid batch ID format'
-  )
+  // 64 hex characters. generateBatchId (src/libraries/crypto.ts) returns either
+  // shake256(molecularHash + index, 256) — 256 bits, 64 hex chars — or randomString(64) over the
+  // alphabet 'abcdef0123456789'. A UUID shape matches nothing this SDK can produce, so the
+  // previous 8-4-4-4-12 regex rejected every real batch ID. Agrees with isBatchId in
+  // src/types/guards.ts.
+  z.string().regex(/^[0-9a-fA-F]{64}$/, 'Invalid batch ID format')
 )
 
 export const CellSlugSchema = createBrandedSchema('CellSlug',