@wishknish/knishio-client-ts 0.7.6 → 0.7.8

package/README.md

@@ -253,6 +253,73 @@ This document will explain both ways.
   console.log(fingerprintData);
   ```
 
+### DataBraid: Embedding Status (Observability)
+
+When the validator has DataBraid embeddings enabled (`EMBEDDING_ENABLED=true`), the SDK can query the embedding state of meta assets. This allows apps to render UI indicators such as spinner badges for in-progress embeddings or completion checkmarks.
+
+The SDK automatically detects whether the connected server supports this feature. If it does not, `queryEmbeddingStatus()` returns `null` instead of throwing an error.
+
+- Query embedding status for a **single Meta Asset**:
+
+  ```typescript
+  import type { EmbeddingStatusItem } from '@wishknish/knishio-client-ts'
+
+  const response = await client.queryEmbeddingStatus({
+    metaType: 'Vehicle',
+    metaId: 'VIN-12345'
+  });
+
+  if (response) {
+    const items: EmbeddingStatusItem[] | null = response.payload();
+    // items[0] = {
+    //   metaType: 'Vehicle',
+    //   metaId: 'VIN-12345',
+    //   state: 'COMPLETE',     // 'PENDING' | 'STALE' | 'COMPLETE'
+    //   totalMetas: 5,         // Total meta rows for this instance
+    //   embeddedCount: 5,      // Rows with embeddings
+    //   embeddedAt: 1713100800, // Unix timestamp of last embedding
+    //   model: 'nomic-embed-text-v1.5'
+    // }
+  } else {
+    // Server does not support embedding status
+  }
+  ```
+
+- **Bulk** embedding status for multiple assets in a single request:
+
+  ```typescript
+  const response = await client.queryEmbeddingStatus({
+    instances: [
+      { metaType: 'Vehicle', metaId: 'VIN-12345' },
+      { metaType: 'Vehicle', metaId: 'VIN-67890' },
+      { metaType: 'Profile', metaId: 'user_42' }
+    ]
+  });
+
+  if (response) {
+    const items = response.payload();
+    // items.length === 3, one per input, in the same order
+    for (const item of items!) {
+      console.log(`${item.metaType}:${item.metaId} → ${item.state}`);
+    }
+  }
+  ```
+
+- **Capability detection** — check if the server supports a query field before calling it:
+
+  ```typescript
+  const supported: boolean = await client.hasQueryField('embeddingStatus');
+  // true if the server's GraphQL schema includes the field, false otherwise
+  // Result is cached per URI — no repeated network round-trips
+  ```
+
+  **Embedding States:**
+  | State | Meaning | Suggested UI |
+  |-------|---------|-------------|
+  | `PENDING` | No embeddings generated yet | Spinner / gray badge |
+  | `STALE` | Embeddings exist but model has changed | Refresh indicator |
+  | `COMPLETE` | All meta rows have current-model embeddings | Green checkmark |
+
 ## Advanced Usage: Working with Molecules
 
 For more granular control, you can work directly with Molecules:
@@ -419,6 +486,7 @@ This method involves individually building Atoms and Molecules, triggering the s
     1. `QueryBalance` and `QueryContinuId` -> returns a `Wallet` instance
     2. `QueryWalletList` -> returns a list of `Wallet` instances
     3. `MutationProposeMolecule`, `MutationRequestAuthorization`, `MutationCreateIdentifier`, `MutationLinkIdentifier`, `MutationClaimShadowWallet`, `MutationCreateToken`, `MutationRequestTokens`, and `MutationTransferTokens` -> returns molecule metadata
+    4. `QueryEmbeddingStatus` -> returns an array of `EmbeddingStatusItem` objects (`{ metaType, metaId, state, totalMetas, embeddedCount, embeddedAt, model }`)
 
 ## Getting Help
 

package/dist/index.cjs

@@ -4809,6 +4809,7 @@ var Molecule = class _Molecule {
   remainderWallet;
   atoms;
   version;
+  continuIdPosition;
   parentHashes;
   local;
   /**
@@ -4821,7 +4822,8 @@ var Molecule = class _Molecule {
     sourceWallet = null,
     remainderWallet = null,
     cellSlug = null,
-    version = null
+    version = null,
+    continuIdPosition = null
   } = {}) {
     this.status = null;
     this.molecularHash = null;
@@ -4830,6 +4832,7 @@ var Molecule = class _Molecule {
     this.secret = secret;
     this.bundle = bundle;
     this.sourceWallet = sourceWallet;
+    this.continuIdPosition = continuIdPosition;
     this.atoms = [];
     this.parentHashes = [];
     const versionRegistry = versions_default;
@@ -4907,7 +4910,9 @@ var Molecule = class _Molecule {
       });
     }
     const continuIdMeta = {};
-    if (this.sourceWallet && this.sourceWallet.position) {
+    if (this.continuIdPosition) {
+      continuIdMeta.previousPosition = this.continuIdPosition;
+    } else if (this.sourceWallet && this.sourceWallet.position) {
       continuIdMeta.previousPosition = this.sourceWallet.position;
     }
     if (this.remainderWallet.pubkey) {
@@ -4936,13 +4941,8 @@ var Molecule = class _Molecule {
   }) {
     const atomMeta = new AtomMeta(meta);
     atomMeta.addPolicy(policy);
-    const wallet = Wallet.create({
-      secret: this.secret,
-      bundle: this.sourceWallet.bundle,
-      token: "USER"
-    });
     this.addAtom(Atom.create({
-      wallet,
+      wallet: this.sourceWallet,
       isotope: "R",
       metaType,
       metaId,
@@ -5251,10 +5251,21 @@ var Molecule = class _Molecule {
     if (Number(this.sourceWallet.balance) - amount < 0) {
       throw new BalanceInsufficientException();
     }
+    const burnWallet = new Wallet({
+      bundle: "0000000000000000000000000000000000000000000000000000000000000000",
+      token: this.sourceWallet.token
+    });
     this.addAtom(Atom.create({
       isotope: "V",
       wallet: this.sourceWallet,
-      value: -amount
+      value: -Number(this.sourceWallet.balance)
+    }));
+    this.addAtom(Atom.create({
+      isotope: "V",
+      wallet: burnWallet,
+      value: amount,
+      metaType: "walletBundle",
+      metaId: burnWallet.bundle
     }));
     this.addAtom(Atom.create({
       isotope: "V",
@@ -5916,6 +5927,20 @@ var GraphQLClient = class {
       encrypt: this.cipherLink
     });
   }
+  /**
+   * F-8a (cross-SDK parity, 2026-06-03): re-point the GraphQL-subscription WebSocket
+   * without changing the HTTP endpoint. `setUri` only updates `serverUri`, leaving the
+   * subscription socket pinned to whatever was passed at construction; this lets a
+   * caller re-derive the socket when the endpoint changes.
+   */
+  setSocketUri(socketUri) {
+    this.socketUri = socketUri;
+    this.$__client = this.createUrqlClient({
+      serverUri: this.serverUri,
+      socket: { socketUri },
+      encrypt: this.cipherLink
+    });
+  }
   socketDisconnect() {
     if (this.socketUri) {
       this.unsubscribeAll();
@@ -8816,9 +8841,91 @@ var QueryMetaTypeViaMolecule = class extends Query {
   }
 };
 
+// src/response/ResponseEmbeddingStatus.ts
+init_Response();
+var ResponseEmbeddingStatus = class extends exports.Response {
+  /**
+   * Class constructor
+   */
+  constructor({
+    query,
+    json
+  }) {
+    super({
+      query,
+      json,
+      dataKey: "data.embeddingStatus"
+    });
+  }
+  /**
+   * Returns the array of embedding status items, or null if empty.
+   */
+  payload() {
+    const items = this.data();
+    if (!items || !Array.isArray(items) || items.length === 0) {
+      return null;
+    }
+    return items;
+  }
+};
+var QueryEmbeddingStatus = class extends Query {
+  /**
+   * Create new QueryEmbeddingStatus instance
+   */
+  constructor(graphQLClient, knishIOClient) {
+    super(graphQLClient, knishIOClient);
+    this.$__query = core.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' }, ...] })
+   */
+  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
+   */
+  createResponse(json) {
+    return new ResponseEmbeddingStatus({
+      query: this,
+      json
+    });
+  }
+};
+
 // src/response/ResponseProposeMolecule.ts
 init_Response();
 init_Dot();
+init_MolecularHashMismatchException();
+init_SignatureMismatchException();
+init_AtomIndexException();
 var ResponseProposeMolecule = class extends exports.Response {
   $__clientMolecule;
   /**
@@ -8890,6 +8997,47 @@ var ResponseProposeMolecule = class extends exports.Response {
   reason() {
     return exports.Dot.get(this.data(), "reason", "Invalid response from server");
   }
+  /**
+   * Map this rejection to a typed SDK exception when the failure mode is one
+   * we know about. Returns null on success or for rejections we don't have a
+   * typed class for.
+   *
+   * This is the single place pattern-matching against validator reason strings
+   * lives — consumers (KnishIOClient cache invalidation, callers needing to
+   * branch on failure mode) can `instanceof`-switch on the result instead.
+   * Future validator versions can rephrase reasons (or populate a structured
+   * field in the response payload) without breaking callers.
+   */
+  toException() {
+    if (this.success()) return null;
+    const reason = this.reason();
+    const lc = reason.toLowerCase();
+    if (/molecularhashmismatch|hash.*mismatch/.test(lc)) {
+      return new exports.MolecularHashMismatchException(reason, {
+        details: { reason },
+        code: "HASH_MISMATCH"
+      });
+    }
+    if (/ots.*position.*reuse|position.*already.*used|ots.*verification/.test(lc)) {
+      return new exports.SignatureMismatchException(reason, {
+        details: { reason },
+        code: "OTS_VERIFICATION_FAILED"
+      });
+    }
+    if (/continuid.*chain|previousposition|chain.*violation/.test(lc)) {
+      return new exports.AtomIndexException(reason, {
+        details: { reason },
+        code: "INDEX_CONFLICT"
+      });
+    }
+    if (/signature.*verification|signature.*invalid/.test(lc)) {
+      return new exports.SignatureMismatchException(reason, {
+        details: { reason },
+        code: "VERIFICATION_FAILED"
+      });
+    }
+    return null;
+  }
   /**
    * Returns payload object
    * Matches JavaScript SDK payload method exactly
@@ -9927,6 +10075,13 @@ var KnishIOClient = class {
   $__remainderWallet = null;
   lastMoleculeQuery = null;
   abortControllers = /* @__PURE__ */ new Map();
+  $__capabilityCache = {};
+  // Promise-chain mutex serializing MutationProposeMolecule submissions on this
+  // client. Without it, concurrent createMolecule() calls both query the same
+  // ContinuID position and both sign with it — the second is rejected with
+  // OTS position reuse. Auth-token flow (MutationRequestAuthorization) inherits
+  // from MutationProposeMolecule so it's covered by the same lock.
+  $__moleculeChain = Promise.resolve();
   /**
    * Enhanced constructor with standardized configuration validation (Phase 2 Enhancement)
    */
@@ -10051,6 +10206,7 @@ var KnishIOClient = class {
     this.$__authToken = null;
     this.$__remainderWallet = null;
     this.lastMoleculeQuery = null;
+    this.$__capabilityCache = {};
   }
   /**
    * Get the GraphQL client
@@ -10071,6 +10227,19 @@ var KnishIOClient = class {
       this.$__client.setUri(this.getRandomUri());
     }
   }
+  /**
+   * Sets the WebSocket (subscription) endpoint for this session.
+   *
+   * F-8a (cross-SDK parity, 2026-06-03): `setUri` only updates the HTTP endpoint; the
+   * subscription socket is built once from the `socket.socketUri` passed at
+   * construction. This lets a caller re-point the socket when the endpoint changes
+   * (mirrors the JS SDK's `setSocketUri`).
+   */
+  setSocketUri(socketUri) {
+    if (this.$__client && "setSocketUri" in this.$__client) {
+      this.$__client.setSocketUri(socketUri);
+    }
+  }
   /**
    * Gets the Knish.IO server URIs
    */
@@ -10144,6 +10313,17 @@ var KnishIOClient = class {
     this.log("info", "KnishIOClient::createMolecule() - Creating a new molecule...");
     secret = secret || this.getSecret();
     bundle = bundle || this.getBundle();
+    let continuIdPosition = null;
+    if (sourceWallet && sourceWallet.token !== "USER") {
+      if (this.lastMoleculeQuery && this.getRemainderWallet() && this.getRemainderWallet()?.token === "USER" && this.lastMoleculeQuery.response() && this.lastMoleculeQuery.response()?.success()) {
+        continuIdPosition = this.getRemainderWallet()?.position || null;
+        this.log("info", `KnishIOClient::createMolecule() - Captured USER ContinuID position ${continuIdPosition?.substring(0, 16)}... for non-USER source wallet`);
+      } else {
+        const userWallet = await this.getSourceWallet();
+        continuIdPosition = userWallet?.position || null;
+        this.log("info", `KnishIOClient::createMolecule() - Queried USER ContinuID position ${continuIdPosition?.substring(0, 16)}... for non-USER source wallet`);
+      }
+    }
     if (!sourceWallet && this.lastMoleculeQuery && this.getRemainderWallet()?.token === "USER" && this.lastMoleculeQuery.response() && this.lastMoleculeQuery.response()?.success()) {
       sourceWallet = this.getRemainderWallet();
       this.log("info", `KnishIOClient::createMolecule() - Using carry-forward remainder wallet at position ${sourceWallet?.position?.substring(0, 16)}...`);
@@ -10163,7 +10343,8 @@ var KnishIOClient = class {
       sourceWallet,
       remainderWallet: this.getRemainderWallet(),
       cellSlug: this.getCellSlug(),
-      version: this.getServerSdkVersion()
+      version: this.getServerSdkVersion(),
+      continuIdPosition
     });
   }
   /**
@@ -10182,6 +10363,23 @@ var KnishIOClient = class {
     this.lastMoleculeQuery = mutation;
     return mutation;
   }
+  /**
+   * Serializes the given async work behind a per-client promise chain. Used to
+   * guarantee that at most one MutationProposeMolecule submission runs at a
+   * time on this client — query position, sign, submit, observe response must
+   * complete before the next one starts, or two callers race for the same OTS
+   * position and the second gets rejected.
+   *
+   * `.then(fn, fn)` runs fn whether the previous holder resolved or rejected;
+   * the queue's `.catch` swallows the rejection so a single failure doesn't
+   * poison every subsequent caller, while the rejection still propagates to
+   * the caller whose fn threw.
+   */
+  withMoleculeLock(fn) {
+    const result = this.$__moleculeChain.then(fn, fn);
+    this.$__moleculeChain = result.catch(() => void 0);
+    return result;
+  }
   /**
    * Executes a query or mutation
    */
@@ -10194,8 +10392,34 @@ var KnishIOClient = class {
         encrypt: this.$__encrypt
       });
     }
+    if (query instanceof MutationProposeMolecule) {
+      return await this.withMoleculeLock(async () => {
+        const response = await query.execute({ variables: variables || {} });
+        this.handlePositionDrift(response);
+        return response;
+      });
+    }
     return await query.execute({ variables: variables || {} });
   }
+  /**
+   * When a ProposeMolecule submission is rejected for a position-related
+   * reason (OTS reuse, ContinuID chain violation, molecular hash mismatch),
+   * the cached remainder wallet and lastMoleculeQuery are stale — the
+   * validator's chain has advanced past what we know. Clear them so the next
+   * createMolecule call re-queries queryContinuId for the authoritative
+   * position. Other failure modes (network, malformed meta, bad signature
+   * bytes) don't imply drift; leave cached state alone.
+   */
+  handlePositionDrift(response) {
+    if (!(response instanceof ResponseProposeMolecule)) return;
+    const exc = response.toException();
+    if (!exc) return;
+    if (exc instanceof exports.MolecularHashMismatchException || exc instanceof exports.AtomIndexException || exc instanceof exports.SignatureMismatchException && exc.code === "OTS_VERIFICATION_FAILED") {
+      this.$__remainderWallet = null;
+      this.lastMoleculeQuery = null;
+      this.log("warn", `KnishIOClient::executeQuery() - position drift detected (${exc.name}/${exc.code}); cleared cached remainder wallet`);
+    }
+  }
   /**
    * Sets the secret for this session
    */
@@ -10575,6 +10799,63 @@ var KnishIOClient = class {
     }
     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 fieldName - The root Query field name to check (e.g. 'embeddingStatus')
+   * @returns true if the server schema includes the field, false otherwise
+   */
+  async hasQueryField(fieldName) {
+    const uri = this.$__client.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 data = result?.data;
+      const fields = 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' }, ...] })
+   *
+   * @returns Response with payload(), or null if the server does not support this query
+   */
+  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 cascading meta instances for batchId
    */
@@ -10894,8 +11175,10 @@ var KnishIOClient = class {
         amount: amount || 0
       });
     }
+    const remainderWallet = sourceWallet.createRemainder(this.getSecret());
     const molecule = await this.createMolecule({
-      sourceWallet
+      sourceWallet,
+      remainderWallet
     });
     const mutation = await this.createMoleculeMutation({
       mutationClass: MutationTransferTokens,
@@ -11191,7 +11474,15 @@ var KnishIOClient = class {
         amount
       });
     }
-    const mutation = await this.createMoleculeMutation({ mutationClass: MutationDepositBufferToken });
+    const remainderWallet = sourceWallet.createRemainder(this.getSecret());
+    const molecule = await this.createMolecule({
+      sourceWallet,
+      remainderWallet
+    });
+    const mutation = await this.createMoleculeMutation({
+      mutationClass: MutationDepositBufferToken,
+      molecule
+    });
     await mutation.fillMolecule({
       amount: typeof amount === "string" ? Number(amount) : amount,
       tradeRates
@@ -11556,6 +11847,7 @@ exports.QueryAtom = QueryAtom;
 exports.QueryBalance = QueryBalance;
 exports.QueryBatch = QueryBatch;
 exports.QueryContinuId = QueryContinuId;
+exports.QueryEmbeddingStatus = QueryEmbeddingStatus;
 exports.QueryMetaType = QueryMetaType;
 exports.QueryMetaTypeViaAtom = QueryMetaTypeViaAtom;
 exports.QueryWalletBundle = QueryWalletBundle;
@@ -11567,6 +11859,7 @@ exports.ResponseContinuId = ResponseContinuId;
 exports.ResponseCreateMeta = ResponseCreateMeta;
 exports.ResponseCreateToken = ResponseCreateToken;
 exports.ResponseCreateWallet = ResponseCreateWallet;
+exports.ResponseEmbeddingStatus = ResponseEmbeddingStatus;
 exports.ResponseMetaType = ResponseMetaType;
 exports.ResponseMetaTypeViaAtom = ResponseMetaTypeViaAtom;
 exports.ResponsePeering = ResponsePeering;