@wishknish/knishio-client-ts 0.7.6 → 0.7.8

package/dist/index.js

@@ -4803,6 +4803,7 @@ var Molecule = class _Molecule {
   remainderWallet;
   atoms;
   version;
+  continuIdPosition;
   parentHashes;
   local;
   /**
@@ -4815,7 +4816,8 @@ var Molecule = class _Molecule {
     sourceWallet = null,
     remainderWallet = null,
     cellSlug = null,
-    version = null
+    version = null,
+    continuIdPosition = null
   } = {}) {
     this.status = null;
     this.molecularHash = null;
@@ -4824,6 +4826,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;
@@ -4901,7 +4904,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) {
@@ -4930,13 +4935,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,
@@ -5245,10 +5245,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",
@@ -5910,6 +5921,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();
@@ -8810,9 +8835,91 @@ var QueryMetaTypeViaMolecule = class extends Query {
   }
 };
 
+// src/response/ResponseEmbeddingStatus.ts
+init_Response();
+var ResponseEmbeddingStatus = class extends 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 = 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 Response {
   $__clientMolecule;
   /**
@@ -8884,6 +8991,47 @@ var ResponseProposeMolecule = class extends Response {
   reason() {
     return 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 MolecularHashMismatchException(reason, {
+        details: { reason },
+        code: "HASH_MISMATCH"
+      });
+    }
+    if (/ots.*position.*reuse|position.*already.*used|ots.*verification/.test(lc)) {
+      return new SignatureMismatchException(reason, {
+        details: { reason },
+        code: "OTS_VERIFICATION_FAILED"
+      });
+    }
+    if (/continuid.*chain|previousposition|chain.*violation/.test(lc)) {
+      return new AtomIndexException(reason, {
+        details: { reason },
+        code: "INDEX_CONFLICT"
+      });
+    }
+    if (/signature.*verification|signature.*invalid/.test(lc)) {
+      return new SignatureMismatchException(reason, {
+        details: { reason },
+        code: "VERIFICATION_FAILED"
+      });
+    }
+    return null;
+  }
   /**
    * Returns payload object
    * Matches JavaScript SDK payload method exactly
@@ -9921,6 +10069,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)
    */
@@ -10045,6 +10200,7 @@ var KnishIOClient = class {
     this.$__authToken = null;
     this.$__remainderWallet = null;
     this.lastMoleculeQuery = null;
+    this.$__capabilityCache = {};
   }
   /**
    * Get the GraphQL client
@@ -10065,6 +10221,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
    */
@@ -10138,6 +10307,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)}...`);
@@ -10157,7 +10337,8 @@ var KnishIOClient = class {
       sourceWallet,
       remainderWallet: this.getRemainderWallet(),
       cellSlug: this.getCellSlug(),
-      version: this.getServerSdkVersion()
+      version: this.getServerSdkVersion(),
+      continuIdPosition
     });
   }
   /**
@@ -10176,6 +10357,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
    */
@@ -10188,8 +10386,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 MolecularHashMismatchException || exc instanceof AtomIndexException || exc instanceof 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
    */
@@ -10569,6 +10793,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
    */
@@ -10888,8 +11169,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,
@@ -11185,7 +11468,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
@@ -11521,6 +11812,6 @@ var KnishIO = {
   SDK_INFO
 };
 
-export { Atom, AtomIndexException, AtomMeta, AtomsMissingException, AuthToken, BaseException, COMPATIBLE_SERVER_VERSIONS, CRYPTO_CONSTANTS, CheckMolecule, DevUtils, Dot, EXCEPTION_CODES, EXCEPTION_TYPES, EXTENDED_COMPATIBILITY_TEST_VECTORS, ExceptionFactory, GraphQLClient, InvalidResponseException, KnishIO, KnishIOClient, Meta, MolecularHashMismatchException, Molecule, Mutation, MutationAppendRequest, MutationCreateMeta, MutationCreateToken, MutationCreateWallet, MutationPeering, MutationProposeMolecule, MutationRequestAuthorization, MutationRequestTokens, MutationTransferTokens, PolicyMeta, Query, QueryAtom, QueryBalance, QueryBatch, QueryContinuId, QueryMetaType, QueryMetaTypeViaAtom, QueryWalletBundle, QueryWalletList, Response, ResponseAppendRequest, ResponseAtom, ResponseBalance, ResponseContinuId, ResponseCreateMeta, ResponseCreateToken, ResponseCreateWallet, ResponseMetaType, ResponseMetaTypeViaAtom, ResponsePeering, ResponseProposeMolecule, ResponseRequestAuthorization, ResponseRequestTokens, ResponseTransferTokens, ResponseWalletBundle, ResponseWalletList, SDK_INFO, SDK_NAME, SDK_VERSION, SignatureMismatchException, TokenUnit, TransferBalanceException, Wallet, WalletCredentialException, base64ToHex, bufferToHexString, capitalize, charsetBaseConvert, chunkArray, chunkSubstr, configureSDK, convertToBase17, createBundleHash, createMolecularHash, createPosition, createTokenSlug, createWalletAddress, deepCloning, diff, enumerateMolecularHash, generateBatchId, generateBundleHash, generateOTSSignature, generatePosition, generateSecret, generateWalletAddress, generateWalletKey, getSDKConfig, hexStringToBuffer, hexToBase64, intersect, isAtomIsotope, isBundleHash, isHex, isHexString, isMolecularHash, isNumeric, isPosition2 as isPosition, isWalletAddress2 as isWalletAddress, normalizeMolecularHash, randomString, runCompatibilityTests, runExtendedCompatibilityTests, shake256, toCamelCase, toSnakeCase, truncate, validateBundleHash, validateMolecularHashForSignature, validateOTSSignature, validatePosition, validateSecret, validateWalletAddress, verifyOTSSignature };
+export { Atom, AtomIndexException, AtomMeta, AtomsMissingException, AuthToken, BaseException, COMPATIBLE_SERVER_VERSIONS, CRYPTO_CONSTANTS, CheckMolecule, DevUtils, Dot, EXCEPTION_CODES, EXCEPTION_TYPES, EXTENDED_COMPATIBILITY_TEST_VECTORS, ExceptionFactory, GraphQLClient, InvalidResponseException, KnishIO, KnishIOClient, Meta, MolecularHashMismatchException, Molecule, Mutation, MutationAppendRequest, MutationCreateMeta, MutationCreateToken, MutationCreateWallet, MutationPeering, MutationProposeMolecule, MutationRequestAuthorization, MutationRequestTokens, MutationTransferTokens, PolicyMeta, Query, QueryAtom, QueryBalance, QueryBatch, QueryContinuId, QueryEmbeddingStatus, QueryMetaType, QueryMetaTypeViaAtom, QueryWalletBundle, QueryWalletList, Response, ResponseAppendRequest, ResponseAtom, ResponseBalance, ResponseContinuId, ResponseCreateMeta, ResponseCreateToken, ResponseCreateWallet, ResponseEmbeddingStatus, ResponseMetaType, ResponseMetaTypeViaAtom, ResponsePeering, ResponseProposeMolecule, ResponseRequestAuthorization, ResponseRequestTokens, ResponseTransferTokens, ResponseWalletBundle, ResponseWalletList, SDK_INFO, SDK_NAME, SDK_VERSION, SignatureMismatchException, TokenUnit, TransferBalanceException, Wallet, WalletCredentialException, base64ToHex, bufferToHexString, capitalize, charsetBaseConvert, chunkArray, chunkSubstr, configureSDK, convertToBase17, createBundleHash, createMolecularHash, createPosition, createTokenSlug, createWalletAddress, deepCloning, diff, enumerateMolecularHash, generateBatchId, generateBundleHash, generateOTSSignature, generatePosition, generateSecret, generateWalletAddress, generateWalletKey, getSDKConfig, hexStringToBuffer, hexToBase64, intersect, isAtomIsotope, isBundleHash, isHex, isHexString, isMolecularHash, isNumeric, isPosition2 as isPosition, isWalletAddress2 as isWalletAddress, normalizeMolecularHash, randomString, runCompatibilityTests, runExtendedCompatibilityTests, shake256, toCamelCase, toSnakeCase, truncate, validateBundleHash, validateMolecularHashForSignature, validateOTSSignature, validatePosition, validateSecret, validateWalletAddress, verifyOTSSignature };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map