@wishknish/knishio-client-ts 0.7.6 → 0.7.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-ts",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "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",

package/src/KnishIOClient.ts

@@ -84,6 +84,7 @@ import QueryUserActivity from '@/query/QueryUserActivity'
 import QueryToken from '@/query/QueryToken'
 import QueryMetaTypeViaAtom from '@/query/QueryMetaTypeViaAtom'
 import QueryMetaTypeViaMolecule from '@/query/QueryMetaTypeViaMolecule'
+import QueryEmbeddingStatus from '@/query/QueryEmbeddingStatus'
 
 // Mutation imports
 import MutationCreateToken from '@/mutation/MutationCreateToken'
@@ -102,6 +103,10 @@ import MutationRequestAuthorizationGuest from '@/mutation/MutationRequestAuthori
 import MutationLinkIdentifier from '@/mutation/MutationLinkIdentifier'
 import MutationPeering from '@/mutation/MutationPeering'
 import MutationAppendRequest from '@/mutation/MutationAppendRequest'
+import MutationProposeMolecule from '@/mutation/MutationProposeMolecule'
+
+// Response imports
+import ResponseProposeMolecule from '@/response/ResponseProposeMolecule'
 
 // Subscribe imports
 import CreateMoleculeSubscribe from '@/subscribe/CreateMoleculeSubscribe'
@@ -116,7 +121,10 @@ import {
   TransferBalanceException,
   WalletShadowException,
   StackableUnitAmountException,
-  AuthorizationRejectedException
+  AuthorizationRejectedException,
+  MolecularHashMismatchException,
+  SignatureMismatchException,
+  AtomIndexException
 } from '@/exception'
 
 // Type imports
@@ -150,6 +158,13 @@ export default class KnishIOClient {
   private $__remainderWallet: Wallet | null = null
   private lastMoleculeQuery: Mutation | null = null
   private abortControllers: Map<string, AbortController> = new Map()
+  private $__capabilityCache: Record<string, boolean> = {}
+  // 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.
+  private $__moleculeChain: Promise<unknown> = Promise.resolve()
 
   /**
    * Enhanced constructor with standardized configuration validation (Phase 2 Enhancement)
@@ -320,6 +335,7 @@ export default class KnishIOClient {
     this.$__authToken = null
     this.$__remainderWallet = null
     this.lastMoleculeQuery = null
+    this.$__capabilityCache = {}
   }
 
   /**
@@ -344,6 +360,20 @@ export default class KnishIOClient {
     }
   }
 
+  /**
+   * 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: string): void {
+    if (this.$__client && 'setSocketUri' in this.$__client) {
+      (this.$__client as any).setSocketUri(socketUri)
+    }
+  }
+
   /**
    * Gets the Knish.IO server URIs
    */
@@ -433,6 +463,28 @@ 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: string | null = 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 || null
+        this.log('info', `KnishIOClient::createMolecule() - Captured USER ContinuID position ${continuIdPosition?.substring(0, 16)}... for non-USER source wallet`)
+      } else {
+        // Query server for current ContinuID position
+        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`)
+      }
+    }
+
     // Sets the source wallet as the last remainder wallet (to maintain ContinuID)
     if (!sourceWallet &&
       this.lastMoleculeQuery &&
@@ -463,7 +515,8 @@ export default class KnishIOClient {
       sourceWallet,
       remainderWallet: this.getRemainderWallet()!,
       cellSlug: this.getCellSlug(),
-      version: this.getServerSdkVersion()
+      version: this.getServerSdkVersion(),
+      continuIdPosition
     })
   }
 
@@ -494,6 +547,24 @@ export default class KnishIOClient {
     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.
+   */
+  private withMoleculeLock<T>(fn: () => Promise<T>): Promise<T> {
+    const result = (this.$__moleculeChain as Promise<unknown>).then(fn, fn) as Promise<T>
+    this.$__moleculeChain = result.catch(() => undefined)
+    return result
+  }
+
   /**
    * Executes a query or mutation
    */
@@ -509,10 +580,42 @@ export default class KnishIOClient {
       })
     }
 
+    if (query instanceof MutationProposeMolecule) {
+      return await this.withMoleculeLock(async () => {
+        const response = await query.execute({ variables: variables || {} })
+        this.handlePositionDrift(response)
+        return response
+      })
+    }
+
     // Execute the query
     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.
+   */
+  private handlePositionDrift(response: Response | null): void {
+    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
    */
@@ -1037,6 +1140,76 @@ 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 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: string): Promise<boolean> {
+    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 as Record<string, any> | undefined
+      const fields: Array<{ name: string }> = data?.__schema?.queryType?.fields || []
+      const supported = fields.some((f: { name: string }) => f.name === fieldName)
+      this.$__capabilityCache[cacheKey] = supported
+      return supported
+    } catch (err: any) {
+      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
+  }: {
+    metaType?: string | null
+    metaId?: string | null
+    instances?: Array<{ metaType: string; metaId: string }> | null
+  }): Promise<Response | 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
    */
@@ -1496,9 +1669,13 @@ export default class KnishIOClient {
       })
     }
 
-    // Create molecule with the source wallet (same pattern as transferToken)
+    // Create remainder wallet from source (must be same token for V-isotope conservation)
+    const remainderWallet = sourceWallet.createRemainder(this.getSecret())
+
+    // Create molecule with the token-specific source and remainder wallets
     const molecule = await this.createMolecule({
-      sourceWallet
+      sourceWallet,
+      remainderWallet
     })
 
     // Create a transfer to null address (burn)
@@ -1955,8 +2132,20 @@ export default class KnishIOClient {
       })
     }
 
+    // Create remainder wallet from source (must be same token)
+    const remainderWallet = sourceWallet.createRemainder(this.getSecret())
+
+    // Build the molecule with the token-specific source and remainder wallets
+    const molecule = await this.createMolecule({
+      sourceWallet,
+      remainderWallet
+    })
+
     // Create the molecule mutation
-    const mutation = await this.createMoleculeMutation({ mutationClass: MutationDepositBufferToken })
+    const mutation = await this.createMoleculeMutation({
+      mutationClass: MutationDepositBufferToken,
+      molecule
+    })
 
     // Initialize the deposit buffer token mutation
     await mutation.fillMolecule({

package/src/core/Molecule.ts

@@ -78,6 +78,7 @@ export default class Molecule {
   public remainderWallet: Wallet | null
   public atoms: Atom[]
   public version: string | null | undefined
+  public continuIdPosition: string | null
   public parentHashes: string[]
   public local?: number
 
@@ -91,7 +92,8 @@ export default class Molecule {
     sourceWallet = null,
     remainderWallet = null,
     cellSlug = null,
-    version = null
+    version = null,
+    continuIdPosition = null
   }: {
     secret?: string | null
     bundle?: string | null
@@ -99,6 +101,7 @@ export default class Molecule {
     remainderWallet?: Wallet | null
     cellSlug?: string | null
     version?: string | number | null
+    continuIdPosition?: string | null
   } = {}) {
     this.status = null
     this.molecularHash = null
@@ -107,6 +110,7 @@ export default class Molecule {
     this.secret = secret
     this.bundle = bundle
     this.sourceWallet = sourceWallet
+    this.continuIdPosition = continuIdPosition
     this.atoms = []
     this.parentHashes = []
 
@@ -209,8 +213,12 @@ export default class Molecule {
     // ContinuID metadata for chain integrity validation
     const continuIdMeta: Record<string, any> = {}
 
-    // 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
     }
 
@@ -251,14 +259,13 @@ 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 (cross-SDK parity, 2026-06-03): 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 atom in createPolicy(), a fresh-wallet position
+    // is unknown to the validator → "ContinuID chain validation failed: signing
+    // position … not found as wallet". Mirrors createRule(), which uses this.sourceWallet.
     this.addAtom(Atom.create({
-      wallet,
+      wallet: this.sourceWallet!,
       isotope: 'R',
       metaType,
       metaId,
@@ -661,13 +668,29 @@ export default class Molecule {
       throw new BalanceInsufficientException()
     }
 
-    // Burn tokens by removing from source (matching JS SDK)
+    // 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: -Number(this.sourceWallet.balance)
     }))
-    // Remainder atom (matching JS SDK)
+
+    // 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.ts

@@ -94,6 +94,9 @@ export { default as QueryAtom } from './query/QueryAtom'
 export { default as QueryMetaType } from './query/QueryMetaType'
 export { default as QueryMetaTypeViaAtom } from './query/QueryMetaTypeViaAtom'
 
+// DataBraid Embedding Observability
+export { default as QueryEmbeddingStatus } from './query/QueryEmbeddingStatus'
+
 // Phase 2 Tier 2 Priority 3: Essential Query Operations
 export { default as QueryContinuId } from './query/QueryContinuId'
 export { default as QueryBatch } from './query/QueryBatch'
@@ -134,6 +137,10 @@ export { default as ResponseCreateMeta } from './response/ResponseCreateMeta'
 export { default as ResponseMetaType } from './response/ResponseMetaType'
 export { default as ResponseMetaTypeViaAtom } from './response/ResponseMetaTypeViaAtom'
 
+// DataBraid Embedding Observability
+export { default as ResponseEmbeddingStatus } from './response/ResponseEmbeddingStatus'
+export type { EmbeddingStatusItem } from './response/ResponseEmbeddingStatus'
+
 // Phase 2 Tier 2 Priority 2: Token Operations
 export { default as ResponseCreateToken } from './response/ResponseCreateToken'
 export { default as ResponseRequestTokens } from './response/ResponseRequestTokens'

package/src/libraries/GraphQLClient.ts

@@ -301,6 +301,21 @@ export default class GraphQLClient implements IGraphQLClient {
     })
   }
 
+  /**
+   * 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: string): void {
+    this.socketUri = socketUri
+    this.$__client = this.createUrqlClient({
+      serverUri: this.serverUri,
+      socket: { socketUri },
+      encrypt: this.cipherLink
+    })
+  }
+
   socketDisconnect(): void {
     if (this.socketUri) {
       this.unsubscribeAll()

package/src/query/QueryEmbeddingStatus.ts

@@ -0,0 +1,130 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        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 Query from './Query'
+import ResponseEmbeddingStatus from '../response/ResponseEmbeddingStatus'
+import { gql } from '@urql/core'
+import type { GraphQLClient } from '../types/graphql'
+import type KnishIOClient from '../KnishIOClient'
+
+/**
+ * QueryEmbeddingStatus - Query for retrieving DataBraid embedding status.
+ *
+ * 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 {
+  /**
+   * Create new QueryEmbeddingStatus instance
+   */
+  constructor(graphQLClient: GraphQLClient, knishIOClient: 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
+  }: {
+    metaType?: string | null
+    metaId?: string | null
+    instances?: Array<{ metaType: string; metaId: string }> | null
+  } = {}): Record<string, any> {
+    const variables: Record<string, any> = {}
+
+    if (instances && instances.length > 0) {
+      variables.instances = instances
+    }
+
+    if (metaType) {
+      variables.metaType = metaType
+    }
+
+    if (metaId) {
+      variables.metaId = metaId
+    }
+
+    return variables
+  }
+
+  /**
+   * Returns a Response object
+   */
+  override createResponse(json: any): ResponseEmbeddingStatus {
+    return new ResponseEmbeddingStatus({
+      query: this,
+      json
+    })
+  }
+}

package/src/response/ResponseEmbeddingStatus.ts

@@ -0,0 +1,107 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        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 type Query from '../query/Query'
+import Response from './Response'
+
+/**
+ * EmbeddingStatusItem shape returned by the server.
+ */
+export interface EmbeddingStatusItem {
+  /** Metadata type (echoed from input) */
+  metaType: string
+  /** Instance identifier (echoed from input) */
+  metaId: string
+  /** Embedding state: 'PENDING' | 'STALE' | 'COMPLETE' */
+  state: 'PENDING' | 'STALE' | 'COMPLETE'
+  /** Total meta rows for this instance */
+  totalMetas: number
+  /** Rows with current-model embeddings */
+  embeddedCount: number
+  /** Unix epoch of most recent embedding, or null */
+  embeddedAt: number | null
+  /** Model name used for embeddings, or null */
+  model: string | null
+}
+
+/**
+ * ResponseEmbeddingStatus - Response for EmbeddingStatus Query
+ *
+ * Payload is an array of EmbeddingStatusItem objects.
+ */
+export default class ResponseEmbeddingStatus extends Response {
+  /**
+   * Class constructor
+   */
+  constructor({
+    query,
+    json
+  }: {
+    query: Query
+    json: any
+  }) {
+    super({
+      query,
+      json,
+      dataKey: 'data.embeddingStatus'
+    })
+  }
+
+  /**
+   * Returns the array of embedding status items, or null if empty.
+   */
+  override payload(): EmbeddingStatusItem[] | null {
+    const items = this.data()
+
+    if (!items || !Array.isArray(items) || items.length === 0) {
+      return null
+    }
+
+    return items as EmbeddingStatusItem[]
+  }
+}