@wishknish/knishio-client-js 0.7.6 → 0.7.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-js",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "type": "module",
   "productName": "Knish.IO Javascript SDK Client",
   "description": "JavaScript implementation of the Knish.IO SDK to consume Knish.IO GraphQL APIs.",

package/src/KnishIOClient.js

@@ -96,6 +96,7 @@ import QueryAtom from './query/QueryAtom.js'
 import QueryPolicy from './query/QueryPolicy.js'
 import QueryMetaTypeViaAtom from './query/QueryMetaTypeViaAtom.js'
 import QueryMetaTypeViaMolecule from './query/QueryMetaTypeViaMolecule.js'
+import QueryEmbeddingStatus from './query/QueryEmbeddingStatus.js'
 import MutationCreateRule from './mutation/MutationCreateRule.js'
 import MutationDepositBufferToken from './mutation/MutationDepositBufferToken.js'
 import MutationWithdrawBufferToken from './mutation/MutationWithdrawBufferToken.js'
@@ -253,6 +254,7 @@ export default class KnishIOClient {
     this.$__secret = ''
     this.$__bundle = ''
     this.remainderWallet = null
+    this.$__capabilityCache = {}
   }
 
   /**
@@ -288,6 +290,21 @@ export default class KnishIOClient {
     }
   }
 
+  /**
+   * Sets the WebSocket (subscription) endpoint for this session.
+   *
+   * `setUri()` only updates the HTTP endpoint; the subscription socket is built once
+   * at construction from the `socket.socketUri` passed in. This lets a caller re-point
+   * the socket when the endpoint changes (F-8a, E2E gauntlet 2026-06-02).
+   *
+   * @param {string} socketUri
+   */
+  setSocketUri (socketUri) {
+    if (this.$__client && typeof this.$__client.setSocketUri === 'function') {
+      this.$__client.setSocketUri({ socketUri, appKey: 'knishio' })
+    }
+  }
+
   /**
    * Retrieves the endpoint URI for this session
    *
@@ -457,6 +474,26 @@ 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 = 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
+      } else {
+        // Query server for current ContinuID position
+        const userWallet = await this.getSourceWallet()
+        continuIdPosition = userWallet ? userWallet.position : null
+      }
+    }
+
     // Sets the source wallet as the last remainder wallet (to maintain ContinuID)
     if (!sourceWallet &&
       this.lastMoleculeQuery &&
@@ -486,7 +523,8 @@ export default class KnishIOClient {
       sourceWallet,
       remainderWallet: this.getRemainderWallet(),
       cellSlug: this.getCellSlug(),
-      version: this.getServerSdkVersion()
+      version: this.getServerSdkVersion(),
+      continuIdPosition
     })
   }
 
@@ -885,6 +923,74 @@ export default class KnishIOClient {
     return response
   }
 
+  /**
+   * Probes the connected server to check whether it supports a named root query field.
+   * Result is cached per URI so the network round-trip happens at most once per URI.
+   *
+   * Uses GraphQL introspection which is universally supported by spec-compliant servers.
+   *
+   * @param {string} fieldName - The root Query field name to check (e.g. 'embeddingStatus')
+   * @return {Promise<boolean>}
+   */
+  async hasQueryField (fieldName) {
+    const uri = this.getUri()
+    const cacheKey = `${ uri }::${ fieldName }`
+
+    if (typeof this.$__capabilityCache[cacheKey] === 'boolean') {
+      return this.$__capabilityCache[cacheKey]
+    }
+
+    try {
+      const result = await this.$__client.query({
+        query: '{ __schema { queryType { fields { name } } } }',
+        variables: {}
+      })
+
+      const fields = result?.data?.__schema?.queryType?.fields || []
+      const supported = fields.some(f => f.name === fieldName)
+      this.$__capabilityCache[cacheKey] = supported
+      return supported
+    } catch (err) {
+      this.log('warn', `KnishIOClient::hasQueryField() - Capability probe for '${ fieldName }' failed: ${ err.message }`)
+      this.$__capabilityCache[cacheKey] = false
+      return false
+    }
+  }
+
+  /**
+   * Queries embedding status for one or more meta instances (DataBraid observability).
+   *
+   * If the connected server does not support the embeddingStatus query,
+   * returns null without throwing an error (graceful degradation).
+   *
+   * Single mode: queryEmbeddingStatus({ metaType: 'product', metaId: 'SKU-001' })
+   * Bulk mode:   queryEmbeddingStatus({ instances: [{ metaType: 'product', metaId: 'SKU-001' }, ...] })
+   *
+   * @param {string|null} metaType - Metadata type (single-instance mode)
+   * @param {string|null} metaId - Instance identifier (single-instance mode)
+   * @param {Array<{metaType: string, metaId: string}>|null} instances - Bulk mode input
+   * @return {Promise<ResponseEmbeddingStatus|null>} Response with payload(), or null if unsupported
+   */
+  async queryEmbeddingStatus ({
+    metaType = null,
+    metaId = null,
+    instances = null
+  }) {
+    this.log('info', `KnishIOClient::queryEmbeddingStatus() - Checking embedding status for metaType: ${ metaType || '(bulk)' }...`)
+
+    const supported = await this.hasQueryField('embeddingStatus')
+
+    if (!supported) {
+      this.log('warn', 'KnishIOClient::queryEmbeddingStatus() - Server does not support embeddingStatus query. Returning null.')
+      return null
+    }
+
+    const query = this.createQuery(QueryEmbeddingStatus)
+    const variables = QueryEmbeddingStatus.createVariables({ metaType, metaId, instances })
+
+    return this.executeQuery(query, variables)
+  }
+
   /**
    * Query batch to get cascading meta instances by batchID
    *
@@ -1425,7 +1531,12 @@ export default class KnishIOClient {
     metaId,
     policy = {}
   }) {
-    // Create a molecule
+    // Create a molecule. F-3 (E2E gauntlet 2026-06-02): the ContinuID-rejection bug
+    // here was NOT this construction — it was molecule.addPolicyAtom() signing the
+    // R-isotope atom from a fresh random wallet (now fixed in Molecule.addPolicyAtom
+    // to use this.sourceWallet). A policy is a policy-only R-atom (no rules), so this
+    // path is kept as-is: routing through createRule with an empty rule list would
+    // fail the SDK's own `Check::isotopeR() - No rules!` validation.
     const molecule = await this.createMolecule({})
     molecule.addPolicyAtom({
       metaType,
@@ -1964,7 +2075,7 @@ export default class KnishIOClient {
     molecule.sign({
       bundle: this.getBundle()
     })
-    molecule.check()
+    molecule.check(sourceWallet)
 
     // Create & execute a mutation
     const query = await this.createMoleculeMutation({

package/src/Molecule.js

@@ -86,7 +86,8 @@ export default class Molecule {
     sourceWallet = null,
     remainderWallet = null,
     cellSlug = null,
-    version = null
+    version = null,
+    continuIdPosition = null
   }) {
     this.status = null
     this.molecularHash = null
@@ -95,6 +96,7 @@ export default class Molecule {
     this.secret = secret
     this.bundle = bundle
     this.sourceWallet = sourceWallet
+    this.continuIdPosition = continuIdPosition
     this.atoms = []
     this.parentHashes = []
     if (version !== null && Object.prototype.hasOwnProperty.call(versions, version)) {
@@ -343,8 +345,12 @@ export default class Molecule {
     // These are atom meta fields (not core fields), so they don't affect molecular hash.
     const continuIdMeta = {}
 
-    // previousPosition: the source wallet's position being consumed
-    if (this.sourceWallet && this.sourceWallet.position) {
+    // previousPosition: the current USER ContinuID position being consumed.
+    // For non-USER source wallets (V/B isotopes), use the explicitly passed
+    // continuIdPosition from createMolecule() instead of the TOKEN wallet position.
+    if (this.continuIdPosition) {
+      continuIdMeta.previousPosition = this.continuIdPosition
+    } else if (this.sourceWallet && this.sourceWallet.position) {
       continuIdMeta.previousPosition = this.sourceWallet.position
     }
 
@@ -387,14 +393,14 @@ export default class Molecule {
     const atomMeta = new AtomMeta(meta)
     atomMeta.addPolicy(policy)
 
-    const wallet = Wallet.create({
-      secret: this.secret,
-      bundle: this.sourceWallet.bundle,
-      token: 'USER'
-    })
-
+    // F-3 (E2E gauntlet 2026-06-02): sign the policy (R-isotope) atom from the
+    // established ContinuID source wallet, NOT a freshly-derived Wallet.create() at a
+    // random position. As the signing (first) atom in createPolicy(), a fresh-wallet
+    // position is unknown to the validator → "ContinuID chain validation failed:
+    // signing position … not found as wallet" (a different position each retry). This
+    // mirrors createRule(), which adds its R-atom at this.sourceWallet.
     this.addAtom(Atom.create({
-      wallet,
+      wallet: this.sourceWallet,
       isotope: 'R',
       metaType,
       metaId,
@@ -464,11 +470,29 @@ export default class Molecule {
       throw new BalanceInsufficientException()
     }
 
+    // Create burn address wallet (null bundle = token destruction)
+    const burnWallet = new Wallet({
+      bundle: '0000000000000000000000000000000000000000000000000000000000000000',
+      token: this.sourceWallet.token
+    })
+
+    // V-atom 1: Debit full balance from source
     this.addAtom(Atom.create({
       isotope: 'V',
       wallet: this.sourceWallet,
-      value: -amount
+      value: -this.sourceWallet.balance
     }))
+
+    // V-atom 2: Credit burn amount to burn address
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: burnWallet,
+      value: amount,
+      metaType: 'walletBundle',
+      metaId: burnWallet.bundle
+    }))
+
+    // V-atom 3: Remainder back to source identity
     this.addAtom(Atom.create({
       isotope: 'V',
       wallet: this.remainderWallet,

package/src/index.js

@@ -85,6 +85,7 @@ import QueryBalance from './query/QueryBalance.js'
 import QueryBatch from './query/QueryBatch.js'
 import QueryBatchHistory from './query/QueryBatchHistory.js'
 import QueryContinuId from './query/QueryContinuId.js'
+import QueryEmbeddingStatus from './query/QueryEmbeddingStatus.js'
 import QueryMetaType from './query/QueryMetaType.js'
 import QueryMetaTypeViaAtom from './query/QueryMetaTypeViaAtom.js'
 import QueryMetaTypeViaMolecule from './query/QueryMetaTypeViaMolecule.js'
@@ -132,6 +133,7 @@ import ResponseCreateMeta from './response/ResponseCreateMeta.js'
 import ResponseCreateRule from './response/ResponseCreateRule.js'
 import ResponseCreateToken from './response/ResponseCreateToken.js'
 import ResponseCreateWallet from './response/ResponseCreateWallet.js'
+import ResponseEmbeddingStatus from './response/ResponseEmbeddingStatus.js'
 import ResponseLinkIdentifier from './response/ResponseLinkIdentifier.js'
 import ResponseMetaType from './response/ResponseMetaType.js'
 import ResponseMetaTypeViaAtom from './response/ResponseMetaTypeViaAtom.js'
@@ -245,6 +247,7 @@ export {
   QueryBatch,
   QueryBatchHistory,
   QueryContinuId,
+  QueryEmbeddingStatus,
   QueryMetaType,
   QueryMetaTypeViaAtom,
   QueryMetaTypeViaMolecule,
@@ -286,6 +289,7 @@ export {
   ResponseCreateRule,
   ResponseCreateToken,
   ResponseCreateWallet,
+  ResponseEmbeddingStatus,
   ResponseLinkIdentifier,
   ResponseMetaType,
   ResponseMetaTypeViaAtom,

package/src/libraries/urql/UrqlClientWrapper.js

@@ -5,7 +5,7 @@ import {
   fetchExchange
 } from '@urql/core'
 import { createClient as createWSClient } from 'graphql-ws'
-import { pipe, map } from 'wonka'
+import { pipe, map, subscribe } from 'wonka'
 
 class UrqlClientWrapper {
   constructor ({ serverUri, socket = null, encrypt = false }) {
@@ -82,15 +82,19 @@ class UrqlClientWrapper {
   subscribe (request, closure) {
     const { query, variables, operationName } = request
 
-    const { unsubscribe } = pipe(
+    // F-22 fix: wonka v3 — `subscribe` is a function applied via pipe, not a
+    // method on the result. The pipe-with-subscribe expression returns the
+    // subscription object directly (already shaped as `{ unsubscribe }`).
+    const subscription = pipe(
       this.$__client.subscription(query, variables),
       map(result => {
         closure(this.formatResponse(result))
-      })
-    ).subscribe(() => {})
+      }),
+      subscribe(() => {})
+    )
 
     // Store subscription for later cleanup
-    this.$__subscriptionManager.set(operationName, { unsubscribe })
+    this.$__subscriptionManager.set(operationName, subscription)
 
     return {
       unsubscribe: () => this.unsubscribe(operationName)

package/src/query/QueryEmbeddingStatus.js

@@ -0,0 +1,132 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        Powered by Knish.IO: Connecting a Decentralized World
+
+Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
+
+License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
+*/
+import Query from './Query.js'
+import ResponseEmbeddingStatus from '../response/ResponseEmbeddingStatus.js'
+import { gql } from '@urql/core'
+
+/**
+ * Query for retrieving DataBraid embedding status for meta instances.
+ *
+ * Supports both single-instance and bulk modes:
+ * - Single: { metaType: 'product', metaId: 'SKU-001' }
+ * - Bulk:   { instances: [{ metaType: 'product', metaId: 'SKU-001' }, ...] }
+ *
+ * Returns embedding state (PENDING, STALE, COMPLETE) for each instance,
+ * allowing apps to render spinner badges and completion indicators.
+ *
+ * NOTE: Only available on servers with EMBEDDING_ENABLED=true.
+ * Use KnishIOClient.queryEmbeddingStatus() which handles capability
+ * detection and returns null for unsupported servers.
+ */
+export default class QueryEmbeddingStatus extends Query {
+  /**
+   * @param {UrqlClientWrapper} graphQLClient
+   * @param {KnishIOClient} knishIOClient
+   */
+  constructor (graphQLClient, knishIOClient) {
+    super(graphQLClient, knishIOClient)
+
+    this.$__query = gql`query( $metaType: String, $metaId: String, $instances: [EmbeddingStatusInput!] ) {
+      embeddingStatus( metaType: $metaType, metaId: $metaId, instances: $instances ) {
+        metaType,
+        metaId,
+        state,
+        totalMetas,
+        embeddedCount,
+        embeddedAt,
+        model
+      }
+    }`
+  }
+
+  /**
+   * Builds a GraphQL-friendly variables object for embedding status queries.
+   *
+   * Single mode: createVariables({ metaType: 'product', metaId: 'SKU-001' })
+   * Bulk mode:   createVariables({ instances: [{ metaType: 'product', metaId: 'SKU-001' }, ...] })
+   *
+   * @param {string|null} metaType
+   * @param {string|null} metaId
+   * @param {Array<{metaType: string, metaId: string}>|null} instances
+   * @return {{}}
+   */
+  static createVariables ({
+    metaType = null,
+    metaId = null,
+    instances = null
+  }) {
+    const variables = {}
+
+    if (instances && instances.length > 0) {
+      variables.instances = instances
+    }
+
+    if (metaType) {
+      variables.metaType = metaType
+    }
+
+    if (metaId) {
+      variables.metaId = metaId
+    }
+
+    return variables
+  }
+
+  /**
+   * Returns a Response object
+   *
+   * @param {object} json
+   * @return {ResponseEmbeddingStatus}
+   */
+  createResponse (json) {
+    return new ResponseEmbeddingStatus({
+      query: this,
+      json
+    })
+  }
+}

package/src/response/ResponseEmbeddingStatus.js

@@ -0,0 +1,100 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        Powered by Knish.IO: Connecting a Decentralized World
+
+Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
+
+License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
+*/
+
+import Response from './Response.js'
+
+/**
+ * Response for EmbeddingStatus Query
+ *
+ * Payload is an array of EmbeddingStatusItem objects:
+ *   { metaType, metaId, state, totalMetas, embeddedCount, embeddedAt, model }
+ *
+ * state is one of: 'PENDING' | 'STALE' | 'COMPLETE'
+ */
+export default class ResponseEmbeddingStatus extends Response {
+  /**
+   * Class constructor
+   *
+   * @param {Query} query
+   * @param {object} json
+   */
+  constructor ({
+    query,
+    json
+  }) {
+    super({
+      query,
+      json,
+      dataKey: 'data.embeddingStatus'
+    })
+  }
+
+  /**
+   * Returns the array of embedding status items, or null if empty.
+   *
+   * Each item contains:
+   * - metaType {string} - Metadata type (echoed from input)
+   * - metaId {string} - Instance identifier (echoed from input)
+   * - state {string} - PENDING | STALE | COMPLETE
+   * - totalMetas {number} - Total meta rows for this instance
+   * - embeddedCount {number} - Rows with current-model embeddings
+   * - embeddedAt {number|null} - Unix epoch of most recent embedding
+   * - model {string|null} - Model name used for embeddings
+   *
+   * @return {Array<object>|null}
+   */
+  payload () {
+    const items = this.data()
+
+    if (!items || !Array.isArray(items) || items.length === 0) {
+      return null
+    }
+
+    return items
+  }
+}