@wishknish/knishio-client-ts 0.8.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-ts",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "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",
@@ -71,17 +71,12 @@
   },
   "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",
@@ -100,10 +95,12 @@
     "build:test": "tsup src/index.ts --format esm,cjs,iife --tsconfig tsconfig.build.json --clean",
     "build:dev": "tsup src/index.ts --format esm,cjs --dts --sourcemap --watch",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src --ext .ts,.tsx --fix",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
     "format": "prettier --write \"src/**/*.{ts,tsx}\"",
-    "test": "vitest",
-    "test:coverage": "vitest --coverage",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui",
     "dev": "vite",
     "prepublishOnly": "npm run build",

package/src/KnishIOClient.ts

@@ -50,7 +50,8 @@ import Decimal from '@/libraries/Decimal'
 import GraphQLClient from '@/libraries/GraphQLClient'
 import {
   generateBundleHash,
-  generateSecret
+  generateSecret,
+  generateBatchId
 } from '@/libraries/crypto'
 import Molecule from '@/core/Molecule'
 import Wallet from '@/core/Wallet'
@@ -80,7 +81,6 @@ import QueryBatchHistory from '@/query/QueryBatchHistory'
 import QueryAtom from '@/query/QueryAtom'
 import QueryPolicy from '@/query/QueryPolicy'
 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'
@@ -121,6 +121,7 @@ import {
   TransferBalanceException,
   WalletShadowException,
   StackableUnitAmountException,
+  StackableUnitDecimalsException,
   AuthorizationRejectedException,
   MolecularHashMismatchException,
   SignatureMismatchException,
@@ -136,7 +137,9 @@ import type {
   MetaType,
   MetaId,
   BatchId,
-  MetaFilter
+  MetaFilter,
+  RequestPolicy,
+  TransferRecipientInput
 } from '@/types'
 
 /**
@@ -152,6 +155,10 @@ export default class KnishIOClient {
   private $__client!: GraphQLClient
   private $__serverSdkVersion: number = 3
   private $__logging: boolean = false
+  // Default urql request policy applied to reads when the caller doesn't pass
+  // one. null = urql's default (cache-first). Server/sync clients set this to
+  // 'network-only' so a long-lived client never serves a stale cached read.
+  private $__defaultRequestPolicy: RequestPolicy | null = null
   private $__authTokenObjects: Record<string, AuthToken | null> = {}
   private $__authToken: AuthToken | null = null
   private $__authInProcess: boolean = false
@@ -176,6 +183,7 @@ export default class KnishIOClient {
     socket?: { socketUri: string | null; appKey?: string } | null
     serverSdkVersion?: number
     logging?: boolean
+    defaultRequestPolicy?: RequestPolicy | null
   }) {
     // Phase 2 Enhancement: Use standardized configuration validation
     const standardValidationResult = ConfigValidator.validateClientConfig(config)
@@ -213,14 +221,19 @@ export default class KnishIOClient {
       serverSdkVersion = 3,
       logging = false
     } = validatedConfig
-    
+    // Read from the RAW config: defaultRequestPolicy is an optional add-on the
+    // strict schema now permits, but the validated/inferred shape may not carry
+    // it depending on the parser, so take it straight from the caller's config.
+    const defaultRequestPolicy = (config.defaultRequestPolicy ?? null) as RequestPolicy | null
+
     this.initialize({
       uri: uri as string | string[],
       cellSlug: cellSlug as string | null,
       socket: socket as { socketUri: string | null; appKey?: string } | null,
       client: client as GraphQLClient | null,
       serverSdkVersion,
-      logging
+      logging,
+      defaultRequestPolicy
     })
   }
 
@@ -233,7 +246,8 @@ export default class KnishIOClient {
     socket = null,
     client = null,
     serverSdkVersion = 3,
-    logging = false
+    logging = false,
+    defaultRequestPolicy = null
   }: {
     uri: string | string[]
     cellSlug?: string | null
@@ -241,6 +255,7 @@ export default class KnishIOClient {
     client?: GraphQLClient | null
     serverSdkVersion?: number
     logging?: boolean
+    defaultRequestPolicy?: RequestPolicy | null
   }): void {
     this.reset()
 
@@ -269,6 +284,9 @@ export default class KnishIOClient {
     })
 
     this.$__serverSdkVersion = serverSdkVersion
+    // Config (not session state) — set here, NOT cleared in reset(), mirroring
+    // serverSdkVersion. A re-initialize updates it.
+    this.$__defaultRequestPolicy = defaultRequestPolicy
   }
 
   /**
@@ -324,6 +342,22 @@ export default class KnishIOClient {
     return this.$__serverSdkVersion
   }
 
+  /**
+   * Gets the client's default urql request policy (null = urql default).
+   */
+  getDefaultRequestPolicy(): RequestPolicy | null {
+    return this.$__defaultRequestPolicy
+  }
+
+  /**
+   * Sets the default urql request policy applied to reads that don't specify
+   * one. Pass 'network-only' on a long-lived server/sync client so it never
+   * serves a stale cached read; null restores urql's default (cache-first).
+   */
+  setDefaultRequestPolicy(policy: RequestPolicy | null): void {
+    this.$__defaultRequestPolicy = policy
+  }
+
   /**
    * Reset common properties
    */
@@ -596,7 +630,16 @@ export default class KnishIOClient {
 
     // Execute the query/mutation, forwarding any urql context (e.g.
     // requestPolicy) assembled by the caller (queryMeta) / createQueryContext().
-    return await query.execute({ variables: variables || {}, context })
+    // When the caller did NOT specify a request policy, fall back to this
+    // client's defaultRequestPolicy (e.g. a long-lived server/sync client set
+    // to 'network-only' so it never serves a stale read from the urql cache —
+    // removing the footgun of having to pass network-only on every call).
+    // Precedence: per-call context.requestPolicy > client default > a query's
+    // own createQueryContext() (e.g. ContinuId) > urql default.
+    const effectiveContext = (this.$__defaultRequestPolicy && !(context as Record<string, any>).requestPolicy)
+      ? { requestPolicy: this.$__defaultRequestPolicy, ...context }
+      : context
+    return await query.execute({ variables: variables || {}, context: effectiveContext })
   }
 
   /**
@@ -760,6 +803,96 @@ export default class KnishIOClient {
     return await this.executeQuery(query)
   }
 
+  /**
+   * Fund N recipients from a single source in ONE molecule (multi-recipient sibling of
+   * transferToken). Each recipient gets its own subset of stackable units (or a fungible
+   * amount); a remainder returns the rest to the sender. Conserves:
+   * -balance + Σamounts + (balance - Σ) === 0.
+   *
+   * @param token - token slug
+   * @param recipients - destinations (bundleHash + units OR amount + optional batchId)
+   * @param sourceWallet - optional pre-resolved source (defaults to the client's own wallet)
+   */
+  async transferTokens({
+    token,
+    recipients,
+    sourceWallet = null
+  }: {
+    token: string
+    recipients: TransferRecipientInput[]
+    sourceWallet?: Wallet | null
+  }): Promise<Response | null> {
+    // Per-recipient amount: stackable -> unit count; fungible -> explicit amount (never both)
+    const amounts: number[] = recipients.map(recipient => {
+      const unitCount = recipient.units ? recipient.units.length : 0
+      if (unitCount > 0) {
+        if (recipient.amount !== null && recipient.amount !== undefined && recipient.amount > 0) {
+          throw new StackableUnitAmountException()
+        }
+        return unitCount
+      }
+      return recipient.amount ?? 0
+    })
+
+    const total = amounts.reduce((sum, amount) => sum + amount, 0)
+
+    // Resolve the source (queryBalance now carries tokenUnits, so the split below sees real units)
+    if (sourceWallet === null) {
+      sourceWallet = await this.querySourceWallet({
+        token,
+        amount: total
+      })
+    }
+
+    if (sourceWallet === null || Decimal.cmp(Number(sourceWallet.balance), total) < 0) {
+      throw new TransferBalanceException()
+    }
+
+    // Build a shadow recipient wallet per destination + assign a distinct batch id
+    const recipientWallets: Wallet[] = recipients.map(recipient => {
+      const recipientWallet = Wallet.create({
+        bundle: recipient.bundleHash,
+        token
+      })
+      if (recipient.batchId !== null && recipient.batchId !== undefined) {
+        recipientWallet.batchId = recipient.batchId
+      } else {
+        recipientWallet.initBatchId({ sourceWallet: sourceWallet as Wallet })
+      }
+      return recipientWallet
+    })
+
+    // Canonical remainder (carries the source's token/characters; reuses the source batch id)
+    const remainderWallet = sourceWallet.createRemainder(this.getSecret())
+
+    // Stackable (NFT): partition the source's tokenUnits across source (SENT union), each
+    // recipient (its subset), and remainder (KEPT) BEFORE the molecule is built. No-op for fungible.
+    if (recipients.some(recipient => recipient.units && recipient.units.length > 0)) {
+      sourceWallet.splitUnitsMulti(
+        recipients.map(recipient => recipient.units ?? []),
+        recipientWallets,
+        remainderWallet
+      )
+    }
+
+    const molecule = await this.createMolecule({
+      sourceWallet,
+      remainderWallet
+    })
+
+    const query = await this.createMoleculeMutation({
+      mutationClass: MutationTransferTokens,
+      molecule
+    })
+
+    query.fillMoleculeMulti({
+      recipientWallets,
+      amounts
+    })
+
+    return await this.executeQuery(query)
+  }
+
   /**
    * Request authorization token (guest or profile)
    *
@@ -1395,51 +1528,6 @@ export default class KnishIOClient {
     }) as Promise<Response>
   }
 
-  /**
-   * Query user activity
-   */
-  async queryUserActivity({
-    bundleHash,
-    metaType,
-    metaId,
-    ipAddress = null,
-    browser = null,
-    osCpu = null,
-    resolution = null,
-    timeZone = null,
-    countBy = null,
-    interval = null
-  }: {
-    bundleHash: BundleHash | string
-    metaType: MetaType | string
-    metaId: MetaId | string
-    ipAddress?: string | null
-    browser?: string | null
-    osCpu?: string | null
-    resolution?: string | null
-    timeZone?: string | null
-    countBy?: string | null
-    interval?: string | null
-  }): Promise<Response> {
-    const query = this.createQuery(QueryUserActivity)
-
-    const variables: Record<string, any> = {
-      bundleHash,
-      metaType,
-      metaId
-    }
-
-    if (ipAddress !== null) variables.ipAddress = ipAddress
-    if (browser !== null) variables.browser = browser
-    if (osCpu !== null) variables.osCpu = osCpu
-    if (resolution !== null) variables.resolution = resolution
-    if (timeZone !== null) variables.timeZone = timeZone
-    if (countBy !== null) variables.countBy = countBy
-    if (interval !== null) variables.interval = interval
-
-    return this.executeQuery(query, variables) as Promise<Response>
-  }
-
   /**
    * Query token information
    */
@@ -1579,7 +1667,7 @@ export default class KnishIOClient {
     amount = null,
     meta = null,
     batchId = null,
-    units: _units = null
+    units = null
   }: {
     token: TokenSlug | string
     amount?: number | string | null
@@ -1589,6 +1677,33 @@ export default class KnishIOClient {
   }): Promise<Response> {
     this.log('info', `KnishIOClient::createToken() - Creating token ${token}...`)
 
+    const tokenMeta: Record<string, any> = meta || {}
+    const fungibility = tokenMeta.fungibility
+    let resolvedAmount: number | string = amount ?? 0
+
+    // For a stackable token, ensure a batch ID is present (mirror JS createToken)
+    if (fungibility === 'stackable') {
+      tokenMeta.batchId = batchId || generateBatchId({})
+    }
+
+    // Token-unit initialization for stackable / nonfungible tokens: the unit IDs ARE the supply.
+    // Meta values are sent as strings (the validator's MetaItemInput.value is a GraphQL String).
+    if (
+      (fungibility === 'stackable' || fungibility === 'nonfungible' || fungibility === 'non-fungible') &&
+      units && units.length > 0
+    ) {
+      if (Number(tokenMeta.decimals ?? 0) > 0) {
+        throw new StackableUnitDecimalsException()
+      }
+      if (Number(amount ?? 0) > 0) {
+        throw new StackableUnitAmountException()
+      }
+      resolvedAmount = units.length
+      tokenMeta.splittable = '1'
+      tokenMeta.decimals = '0'
+      tokenMeta.tokenUnits = JSON.stringify(units)
+    }
+
     // Create the molecule mutation
     const mutation = await this.createMoleculeMutation({ mutationClass: MutationCreateToken })
 
@@ -1603,8 +1718,8 @@ export default class KnishIOClient {
     // Initialize the create token mutation
     await mutation.fillMolecule({
       recipientWallet,
-      amount: amount ?? 0,
-      meta
+      amount: resolvedAmount,
+      meta: tokenMeta
     })
 
     // Execute the mutation
@@ -2292,9 +2407,17 @@ export default class KnishIOClient {
       molecule
     })
 
-    // Initialize the profile auth mutation
+    // Initialize the profile auth mutation.
+    // PQ-transport Phase E: convey the AUTH source wallet's ML-KEM768 public key as a SIGNED
+    // walletPubkey U-atom meta, so the validator can encrypt CipherHash responses back to THIS
+    // wallet (the one that decrypts them). Signed → MITM can't swap the target. Conveyed
+    // unconditionally (parity with JS/Kotlin/PHP), so even a plaintext auth primes enc_pubkey.
+    const authMeta: Record<string, string> = { encrypt: encrypt ? 'true' : 'false' }
+    if (wallet.pubkey) {
+      authMeta.walletPubkey = wallet.pubkey
+    }
     mutation.fillMolecule({
-      meta: { encrypt: encrypt ? 'true' : 'false' }
+      meta: authMeta
     })
 
     // Execute the mutation

package/src/constants.ts

@@ -231,8 +231,7 @@ export const QUERY_TYPES = [
   'Batch',
   'ActiveSession',
   'Policy',
-  'Token',
-  'UserActivity'
+  'Token'
 ] as const
 
 export type QueryType = typeof QUERY_TYPES[number]

package/src/core/Molecule.ts

@@ -319,6 +319,59 @@ export default class Molecule {
     return this
   }
 
+  /**
+   * Initialize a MULTI-recipient V-type molecule: one source debits its FULL balance to fund
+   * N recipients (each its own amount + stackable units) plus a remainder back to the sender.
+   * Multi-recipient sibling of initValue (WP line 544: fund multiple recipients with one
+   * transaction). recipientWallets is parallel to amounts.
+   */
+  initValues({
+    recipientWallets,
+    amounts
+  }: {
+    recipientWallets: Wallet[]
+    amounts: number[]
+  }): Molecule {
+    if (!this.sourceWallet) {
+      throw new Error('Source wallet required for value transfer')
+    }
+
+    const total = amounts.reduce((sum, amount) => sum + amount, 0)
+
+    if (Number(this.sourceWallet.balance) - total < 0) {
+      throw new BalanceInsufficientException()
+    }
+
+    // Source atom: debit the ENTIRE balance (UTXO drain); carries the SENT union of token units
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: this.sourceWallet,
+      value: -Number(this.sourceWallet.balance)
+    }))
+
+    // One atom per recipient: +amount_i, walletBundle -> recipient bundle, its own SENT units
+    recipientWallets.forEach((recipientWallet, i) => {
+      this.addAtom(Atom.create({
+        isotope: 'V',
+        wallet: recipientWallet,
+        value: amounts[i]!,
+        metaType: 'walletBundle',
+        metaId: recipientWallet.bundle!
+      }))
+    })
+
+    // Remainder atom: +(balance - total), walletBundle -> sender bundle, KEPT units
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: this.remainderWallet!,
+      value: Number(this.sourceWallet.balance) - total,
+      metaType: 'walletBundle',
+      metaId: this.remainderWallet!.bundle!
+    }))
+
+    return this
+  }
+
   /**
    * Sign the molecule with one-time signature
    * Matches JavaScript SDK sign method

package/src/core/Wallet.ts

@@ -349,6 +349,42 @@ export default class Wallet {
     remainderWallet.tokenUnits = remainderTokenUnits
   }
 
+  /**
+   * Split token units across MULTIPLE recipients (N-way sibling of splitUnits).
+   *
+   * The source retains the SENT union (all units leaving), each recipient gets its own
+   * subset, and the remainder keeps the KEPT units (those not assigned to any recipient).
+   * recipientUnitLists is parallel to recipientWallets. No-op when no units are sent.
+   *
+   * @param recipientUnitLists - per-recipient arrays of token unit IDs (parallel to recipientWallets)
+   * @param recipientWallets - destination wallets
+   * @param remainderWallet - wallet to receive the KEPT units
+   */
+  splitUnitsMulti(
+    recipientUnitLists: string[][],
+    recipientWallets: Wallet[],
+    remainderWallet: Wallet
+  ): void {
+    const sentIds = new Set<string>(recipientUnitLists.flat())
+
+    // Nothing to split (fungible transfer) — leave token units untouched
+    if (sentIds.size === 0) {
+      return
+    }
+
+    // Each recipient gets its own subset of the source's token units
+    recipientWallets.forEach((recipientWallet, i) => {
+      const ids = recipientUnitLists[i] ?? []
+      recipientWallet.tokenUnits = this.tokenUnits.filter(tokenUnit => ids.includes(tokenUnit.id))
+    })
+
+    // The remainder keeps everything not sent to any recipient (KEPT)
+    remainderWallet.tokenUnits = this.tokenUnits.filter(tokenUnit => !sentIds.has(tokenUnit.id))
+
+    // The source carries the SENT union (the ownership authority the validator reads)
+    this.tokenUnits = this.tokenUnits.filter(tokenUnit => sentIds.has(tokenUnit.id))
+  }
+
   /**
    * Get token units data
    * Stub for compatibility
@@ -410,6 +446,16 @@ export default class Wallet {
   }
 
   async decryptMessage(encryptedData: { cipherText: string; encryptedMessage: string }): Promise<any> {
+    const decryptedString = await this._mlkemDecryptToString(encryptedData)
+    return decryptedString === null ? null : JSON.parse(decryptedString)
+  }
+
+  /**
+   * ML-KEM768 decapsulate + AES-256-GCM decrypt → the RAW decrypted UTF-8 string (no JSON.parse).
+   * Shared by {@link decryptMessage} (which JSON.parses the result) and the PQ CipherHash transport
+   * ({@link decryptMyMessageML768}, which needs the raw response JSON text). PQ-transport Phase E.
+   */
+  async _mlkemDecryptToString(encryptedData: { cipherText: string; encryptedMessage: string }): Promise<string | null> {
     const { cipherText, encryptedMessage } = encryptedData
     let sharedSecret
     try {
@@ -438,9 +484,8 @@ export default class Wallet {
       console.info('Wallet::decryptMessage() - deserialized encrypted message', deserializedEncryptedMessage)
       return null
     }
-    let decryptedString
     try {
-      decryptedString = new TextDecoder().decode(decryptedUint8)
+      return new TextDecoder().decode(decryptedUint8)
     } catch (e) {
       console.warn('Wallet::decryptMessage() - Decoding failed', e)
       console.info('Wallet::decryptMessage() - my public key', this.pubkey)
@@ -449,7 +494,43 @@ export default class Wallet {
       console.info('Wallet::decryptMessage() - decrypted Uint8Array', decryptedUint8)
       return null
     }
-    return JSON.parse(decryptedString)
+  }
+
+  /**
+   * Canonical cross-SDK hashShare for a public key: standard base64 of SHAKE256(pubkey_utf8, 8 bytes)
+   * — byte-matches the validator's hash_share and the JS/Kotlin/PHP hashShare. `shake256(pubkey, 64)`
+   * = 64 bits = 8 bytes (hex) → hex-decode → standard base64 via serializeKey. PQ-transport Phase E.
+   */
+  hashShare(pubkey: string): string {
+    const hex = shake256(pubkey, 64)
+    const bytes = new Uint8Array(hex.length / 2)
+    for (let i = 0; i < bytes.length; i++) {
+      bytes[i] = parseInt(hex.substr(i * 2, 2), 16)
+    }
+    return this.serializeKey(bytes)
+  }
+
+  /**
+   * Post-quantum (ML-KEM768) CipherHash request envelope: a stringified single-recipient map
+   * `{ "<hashShare(recipientPubkey)>": {cipherText, encryptedMessage} }` (object-valued, via
+   * {@link encryptMessage}). Matches the Rust validator's CipherHash handler. PQ-transport Phase E.
+   */
+  async encryptStringML768(message: any, recipientPubkey: string): Promise<string> {
+    const envelope = await this.encryptMessage(message, recipientPubkey)
+    return JSON.stringify({ [this.hashShare(recipientPubkey)]: envelope })
+  }
+
+  /**
+   * Decrypt a CipherHash response map addressed to THIS wallet's ML-KEM pubkey
+   * (`hashShare(this.pubkey)`) → the RAW decrypted GraphQL response JSON text (NOT JSON.parsed;
+   * it replaces the HTTP response body for the normal parser). `null` if no entry / decrypt fails.
+   */
+  async decryptMyMessageML768(map: Record<string, { cipherText: string; encryptedMessage: string }>): Promise<string | null> {
+    const envelope = map[this.hashShare(this.pubkey)]
+    if (!envelope) {
+      return null
+    }
+    return this._mlkemDecryptToString(envelope)
   }
 
   // =============================================================================

package/src/libraries/Decimal.ts

@@ -72,7 +72,7 @@ export default class Decimal {
    * @param debug Enable debug logging
    * @returns 0 if equal, 1 if value1 > value2, -1 if value1 < value2
    */
-  static cmp(value1: number, value2: number, debug: boolean = false): number {
+  static cmp(value1: number, value2: number, _debug: boolean = false): number {
     const val1 = Decimal.val(value1) * MULTIPLIER
     const val2 = Decimal.val(value2) * MULTIPLIER