@simtlix/simfinity-js-client 1.0.6 → 3.19.0

package/src/SimfinityClient.js

@@ -1,69 +1,6 @@
-if (typeof globalThis.fetch !== 'function') {
-  throw new Error(
-    'SimfinityClient requires a global fetch implementation. ' +
-    'Use Node.js 18+ (which includes native fetch) or provide a fetch polyfill.'
-  );
-}
-const _fetch = globalThis.fetch.bind(globalThis);
-
-const INTROSPECTION_QUERY = `
-  query IntrospectionQuery {
-    __schema {
-      queryType { name }
-      mutationType { name }
-      types {
-        name
-        kind
-        fields {
-          name
-          type {
-            kind name
-            ofType {
-              kind name
-              ofType {
-                kind name
-                ofType {
-                  kind name
-                  ofType {
-                    kind name
-                  }
-                }
-              }
-            }
-          }
-          args {
-            name
-            type {
-              kind name
-              ofType {
-                kind name
-                ofType {
-                  kind name
-                  ofType {
-                    kind name
-                    ofType {
-                      kind name
-                    }
-                  }
-                }
-              }
-            }
-          }
-          extensions {
-            relation {
-              displayField
-              embedded
-              connectionField
-            }
-            stateMachine
-            readOnly
-          }
-        }
-        enumValues { name }
-      }
-    }
-  }
-`;
+import { normalizeDescriptor, introspectionQuery } from './metadata.js';
+import { SelectionTree } from './selection.js';
+import { transformRootInput, transformDelta } from './inputs.js';
 
 function unwrapType(typeRef) {
   let isList = false;
@@ -106,6 +43,8 @@ function isDateTimeScalar(name) {
     || n === 'isodate' || n === 'graphqldate' || n === 'graphqldatetime';
 }
 
+const canAutoSelect = (field) => !field.args?.some((arg) => arg.type.kind === 'NON_NULL' && !arg.hasDefault);
+
 function isScalarOrEnum(kind) {
   return kind === 'SCALAR' || kind === 'ENUM';
 }
@@ -131,77 +70,14 @@ function typeRefToString(typeRef) {
 // into a GraphQL selection set string.
 // ---------------------------------------------------------------------------
 
-class SelectionTree {
-  constructor() {
-    this.scalars = new Set();
-    this.children = new Map();
-  }
-
-  addScalars(fieldNames) {
-    for (const name of fieldNames.trim().split(/\s+/)) {
-      if (name) this.scalars.add(name);
-    }
-  }
-
-  addSelection(selectionString) {
-    const tokens = selectionString.trim().split(/\s+/);
-    let i = 0;
-    while (i < tokens.length) {
-      const token = tokens[i];
-      if (token === '{' || token === '}') { i++; continue; }
-      if (i + 1 < tokens.length && tokens[i + 1] === '{') {
-        let depth = 1;
-        let j = i + 2;
-        while (j < tokens.length && depth > 0) {
-          if (tokens[j] === '{') depth++;
-          else if (tokens[j] === '}') depth--;
-          j++;
-        }
-        const inner = tokens.slice(i + 2, j - 1).join(' ');
-        if (!this.children.has(token)) {
-          this.children.set(token, new SelectionTree());
-        }
-        this.children.get(token).addSelection(inner);
-        i = j;
-      } else {
-        this.scalars.add(token);
-        i++;
-      }
-    }
-  }
-
-  addNested(dottedPath, fieldNames) {
-    const segments = dottedPath.split('.');
-    let node = this;
-    for (const segment of segments) {
-      if (!node.children.has(segment)) {
-        node.children.set(segment, new SelectionTree());
-      }
-      node = node.children.get(segment);
-    }
-    node.addScalars(fieldNames);
-  }
-
-  serialize() {
-    const parts = [...this.scalars];
-    for (const [name, child] of this.children) {
-      const childStr = child.serialize();
-      if (childStr) parts.push(`${name} { ${childStr} }`);
-    }
-    return parts.join(' ');
-  }
-
-  isEmpty() {
-    return this.scalars.size === 0 && this.children.size === 0;
-  }
-}
-
 // ---------------------------------------------------------------------------
 // QueryBuilder -- chainable builder returned by SimfinityClient.find()
 // ---------------------------------------------------------------------------
 
 class QueryBuilder {
-  constructor(client, typeName) {
+  constructor(client, typeName, queryInfo = null) {
+    this._queryInfo = queryInfo;
+    this._collectionArguments = new Map();
     this._client = client;
     this._typeName = typeName;
     this._variables = {};
@@ -213,7 +89,9 @@ class QueryBuilder {
   // -- Filtering -----------------------------------------------------------
 
   where(field, operatorOrTerms, value, value2) {
-    if (Array.isArray(operatorOrTerms)) {
+    if (operatorOrTerms && typeof operatorOrTerms === 'object' && !Array.isArray(operatorOrTerms)) {
+      this._variables[field] = { ...operatorOrTerms };
+    } else if (Array.isArray(operatorOrTerms)) {
       if (this._variables[field]?.terms) {
         this._variables[field].terms.push(...operatorOrTerms);
       } else {
@@ -227,6 +105,35 @@ class QueryBuilder {
     return this;
   }
 
+  filter(group) {
+    if (!group || typeof group !== 'object' || Array.isArray(group)) throw new Error('filter() expects a QLFilterGroup');
+    return this.and([group]);
+  }
+
+  or(groups) {
+    if (!Array.isArray(groups)) {
+      throw new Error('or() expects an array of QLFilterGroup objects');
+    }
+    if (this._variables.OR) {
+      this._variables.OR.push(...groups);
+    } else {
+      this._variables.OR = [...groups];
+    }
+    return this;
+  }
+
+  and(groups) {
+    if (!Array.isArray(groups)) {
+      throw new Error('and() expects an array of QLFilterGroup objects');
+    }
+    if (this._variables.AND) {
+      this._variables.AND.push(...groups);
+    } else {
+      this._variables.AND = [...groups];
+    }
+    return this;
+  }
+
   // -- Relation Field Selection --------------------------------------------
 
   joinCollection(path, fields, filter) {
@@ -284,99 +191,28 @@ class QueryBuilder {
 
   // -- Execution -----------------------------------------------------------
 
-  async exec() {
-    const queryInfo = this._client._findPluralQuery(this._typeName);
-    if (!queryInfo) {
-      throw new Error(`No plural query found for type '${this._typeName}'`);
-    }
-
-    if (!this._hasExplicitFields) {
-      const autoFields = this._client._getScalarFields(this._typeName);
-      this._selectionTree.addScalars(autoFields);
-    }
-
-    const selectionSet = this._autoSelection || this._selectionTree.serialize();
-    if (!selectionSet) {
-      throw new Error(`No fields to select for type '${this._typeName}'`);
-    }
-
-    const varDefs = [];
-    const variables = {};
-    const argMappings = [];
-
-    for (const [key, val] of Object.entries(this._variables)) {
-      const arg = queryInfo.args.find(a => a.name === key);
-      if (arg) {
-        varDefs.push(`$${key}: ${typeRefToString(arg.type)}`);
-        variables[key] = val;
-        argMappings.push(`${key}: $${key}`);
-      }
-    }
-
-    const varDefsStr = varDefs.length > 0 ? `(${varDefs.join(', ')})` : '';
-    const argsBlock = argMappings.length > 0 ? `(${argMappings.join(', ')})` : '';
-    const query = `query${varDefsStr} { ${queryInfo.name}${argsBlock} { ${selectionSet} } }`;
-
-    const response = await this._client._sendRequest(query, variables);
-    if (response.errors && !response.data?.[queryInfo.name]) {
-      const error = new Error(`GraphQL errors: ${JSON.stringify(response.errors)}`);
-      error.graphQLErrors = response.errors;
-      throw error;
-    }
-
-    const result = response.data[queryInfo.name];
-
-    if (response.extensions) {
-      result.__extensions = response.extensions;
-    }
+  collectionArgs(path, args) {
+    if (!args || typeof args !== 'object' || Array.isArray(args)) throw new Error('collectionArgs expects an argument object');
+    this._collectionArguments.set(path, { ...args }); return this;
+  }
 
-    return result;
+  async exec() {
+    const { data, extensions } = await this.execWithMeta();
+    if (data !== null && typeof data === 'object' && extensions) data.__extensions = extensions;
+    return data;
   }
 
   async execWithMeta() {
-    const queryInfo = this._client._findPluralQuery(this._typeName);
-    if (!queryInfo) {
-      throw new Error(`No plural query found for type '${this._typeName}'`);
-    }
-
-    if (!this._hasExplicitFields) {
-      const autoFields = this._client._getScalarFields(this._typeName);
-      this._selectionTree.addScalars(autoFields);
-    }
-
-    const selectionSet = this._autoSelection || this._selectionTree.serialize();
-    if (!selectionSet) {
-      throw new Error(`No fields to select for type '${this._typeName}'`);
-    }
-
-    const varDefs = [];
-    const variables = {};
-    const argMappings = [];
-
-    for (const [key, val] of Object.entries(this._variables)) {
-      const arg = queryInfo.args.find(a => a.name === key);
-      if (arg) {
-        varDefs.push(`$${key}: ${typeRefToString(arg.type)}`);
-        variables[key] = val;
-        argMappings.push(`${key}: $${key}`);
-      }
-    }
-
-    const varDefsStr = varDefs.length > 0 ? `(${varDefs.join(', ')})` : '';
-    const argsBlock = argMappings.length > 0 ? `(${argMappings.join(', ')})` : '';
-    const query = `query${varDefsStr} { ${queryInfo.name}${argsBlock} { ${selectionSet} } }`;
-
-    const response = await this._client._sendRequest(query, variables);
-    if (response.errors && !response.data?.[queryInfo.name]) {
-      const error = new Error(`GraphQL errors: ${JSON.stringify(response.errors)}`);
-      error.graphQLErrors = response.errors;
-      throw error;
-    }
-    return {
-      data: response.data[queryInfo.name],
-      extensions: response.extensions || null,
-    };
+    const queryInfo = this._queryInfo || this._client._findPluralQuery(this._typeName);
+    if (!queryInfo) throw new Error(`No plural query found for type '${this._typeName}'`);
+    if (!this._hasExplicitFields) this._selectionTree.addScalars(this._client._getScalarFields(this._typeName));
+    const tree = this._autoSelection ? new SelectionTree() : this._selectionTree;
+    if (this._autoSelection) tree.addSelection(this._autoSelection);
+    const response = await this._client._requestOperation('query', queryInfo, this._variables, tree, this._collectionArguments);
+    this._client._checkErrors(response, queryInfo.name, true);
+    return { data: response.data?.[queryInfo.name], extensions: response.extensions || null };
   }
+
 }
 
 // ---------------------------------------------------------------------------
@@ -404,7 +240,9 @@ class AggregateBuilder {
   }
 
   where(field, operatorOrTerms, value, value2) {
-    if (Array.isArray(operatorOrTerms)) {
+    if (operatorOrTerms && typeof operatorOrTerms === 'object' && !Array.isArray(operatorOrTerms)) {
+      this._variables[field] = { ...operatorOrTerms };
+    } else if (Array.isArray(operatorOrTerms)) {
       if (this._variables[field]?.terms) {
         this._variables[field].terms.push(...operatorOrTerms);
       } else {
@@ -418,6 +256,35 @@ class AggregateBuilder {
     return this;
   }
 
+  filter(group) {
+    if (!group || typeof group !== 'object' || Array.isArray(group)) throw new Error('filter() expects a QLFilterGroup');
+    return this.and([group]);
+  }
+
+  or(groups) {
+    if (!Array.isArray(groups)) {
+      throw new Error('or() expects an array of QLFilterGroup objects');
+    }
+    if (this._variables.OR) {
+      this._variables.OR.push(...groups);
+    } else {
+      this._variables.OR = [...groups];
+    }
+    return this;
+  }
+
+  and(groups) {
+    if (!Array.isArray(groups)) {
+      throw new Error('and() expects an array of QLFilterGroup objects');
+    }
+    if (this._variables.AND) {
+      this._variables.AND.push(...groups);
+    } else {
+      this._variables.AND = [...groups];
+    }
+    return this;
+  }
+
   page(page, size, count) {
     const pagination = { page, size };
     if (count !== undefined) pagination.count = count;
@@ -449,29 +316,9 @@ class AggregateBuilder {
       facts: this._facts,
     };
 
-    const varDefs = [];
-    const variables = {};
-    const argMappings = [];
+    const response = await this._client._requestOperation('query', queryInfo, this._variables, 'groupId facts');
+    this._client._checkErrors(response, queryInfo.name);
 
-    for (const [key, val] of Object.entries(this._variables)) {
-      const arg = queryInfo.args.find(a => a.name === key);
-      if (arg) {
-        varDefs.push(`$${key}: ${typeRefToString(arg.type)}`);
-        variables[key] = val;
-        argMappings.push(`${key}: $${key}`);
-      }
-    }
-
-    const varDefsStr = varDefs.length > 0 ? `(${varDefs.join(', ')})` : '';
-    const argsBlock = argMappings.length > 0 ? `(${argMappings.join(', ')})` : '';
-    const query = `query${varDefsStr} { ${queryInfo.name}${argsBlock} { groupId facts } }`;
-
-    const response = await this._client._sendRequest(query, variables);
-    if (response.errors) {
-      const error = new Error(`GraphQL errors: ${JSON.stringify(response.errors)}`);
-      error.graphQLErrors = response.errors;
-      throw error;
-    }
     return response.data[queryInfo.name];
   }
 }
@@ -489,6 +336,14 @@ export default class SimfinityClient {
    *        perform auth in your app and set tokens inside this callback or a closure it sees.
    */
   constructor(endpoint, options = {}) {
+    if (options.descriptor !== undefined && options.descriptorEndpoint !== undefined) throw new Error('descriptor and descriptorEndpoint are mutually exclusive');
+    if (options.introspection !== undefined && !['extended', 'standard'].includes(options.introspection)) throw new Error('Invalid introspection mode');
+    this._options = options;
+    this._descriptor = null;
+    this._fetch = options.fetch || ((...args) => {
+      if (typeof globalThis.fetch !== 'function') throw new Error('SimfinityClient requires fetch or options.fetch');
+      return globalThis.fetch(...args);
+    });
     this._endpoint = endpoint;
     this._types = new Map();
     this._queries = new Map();
@@ -505,14 +360,49 @@ export default class SimfinityClient {
   // -- Initialization ------------------------------------------------------
 
   async init() {
-    const response = await this._sendRequest(INTROSPECTION_QUERY);
-    if (response.errors) {
-      throw new Error(`Introspection failed: ${JSON.stringify(response.errors)}`);
+    let descriptor = this._options.descriptor;
+    if (this._options.descriptorEndpoint !== undefined) {
+      const headers = {};
+      if (this._prepareHeaders) await this._prepareHeaders(headers);
+      const response = await this._fetch(this._options.descriptorEndpoint, { method: 'GET', headers });
+      if (!response.ok) throw new Error(`Descriptor HTTP request failed (${response.status})`);
+      descriptor = await response.json();
+    }
+    let schema;
+    if (descriptor !== undefined) {
+      const normalized = normalizeDescriptor(descriptor);
+      schema = normalized.schema; descriptor = normalized.descriptor;
+    } else {
+      const response = await this._sendRequest(introspectionQuery(this._options.introspection !== 'standard'));
+      if (response.errors) { const error = new Error(`Introspection failed: ${JSON.stringify(response.errors)}`); error.graphQLErrors = response.errors; throw error; }
+      schema = response.data?.__schema;
+      if (!schema || !Array.isArray(schema.types)) throw new Error('Invalid introspection response');
     }
-    this._parseIntrospection(response.data.__schema);
+    const draft = new SimfinityClient(this._endpoint);
+    draft._parseIntrospection(schema);
+    draft._descriptor = descriptor || null;
+    if (descriptor) draft._applyDescriptor(descriptor);
+    for (const key of ['_types', '_queries', '_mutations', '_typeNameToPlural', '_typeNameToSingular', '_typeNameToAggregate', '_queryNameToType', '_descriptor']) this[key] = draft[key];
     this._initialized = true;
   }
 
+  getDescriptor() { return this._descriptor; }
+
+  _applyDescriptor(descriptor) {
+    this._typeNameToPlural.clear(); this._typeNameToSingular.clear(); this._typeNameToAggregate.clear();
+    for (const [typeName, type] of Object.entries(descriptor.types)) {
+      for (const [kind, map] of [['list', this._typeNameToPlural], ['get', this._typeNameToSingular], ['aggregate', this._typeNameToAggregate]]) {
+        if (type.endpoints?.[kind]) map.set(typeName, type.endpoints[kind]);
+      }
+    }
+    for (const [root, registry] of [['query', this._queries], ['mutation', this._mutations]]) {
+      for (const [name, operation] of Object.entries(descriptor.operations[root])) {
+        Object.assign(registry.get(name), operation, { returnType: registry.get(name).returnType, args: registry.get(name).args,
+          category: operation.operation === 'transition' ? 'stateTransition' : operation.operation, typeName: operation.type });
+      }
+    }
+  }
+
   _parseIntrospection(schema) {
     const queryTypeName = schema.queryType?.name;
     const mutationTypeName = schema.mutationType?.name;
@@ -525,20 +415,22 @@ export default class SimfinityClient {
   _buildTypesRegistry(types) {
     for (const type of types) {
       if (type.name.startsWith('__')) continue;
-      const validKinds = ['OBJECT', 'ENUM', 'SCALAR', 'INPUT_OBJECT'];
+      const validKinds = ['OBJECT', 'ENUM', 'SCALAR', 'INPUT_OBJECT', 'INTERFACE', 'UNION'];
       if (!validKinds.includes(type.kind)) continue;
 
       const typeInfo = {
         name: type.name,
         kind: type.kind,
-        fields: (type.fields || []).map(f => ({
+        fields: (type.fields || type.inputFields || []).map(f => ({
           name: f.name,
           type: unwrapType(f.type),
           rawType: f.type,
-          args: (f.args || []).map(a => ({ name: a.name, type: a.type })),
+          args: (f.args || []).map(a => ({ ...a, hasDefault: a.hasDefault ?? (a.defaultValue != null) })),
           extensions: f.extensions || null,
+          hasDefault: f.hasDefault ?? (f.defaultValue != null), defaultValue: f.defaultValue,
         })),
         enumValues: (type.enumValues || []).map(v => v.name),
+        baseScalar: type.baseScalar, possibleTypes: type.possibleTypes?.map((value) => typeof value === 'string' ? value : value.name), interfaces: type.interfaces?.map((value) => typeof value === 'string' ? value : value.name), isOneOf: type.isOneOf,
       };
       this._types.set(type.name, typeInfo);
     }
@@ -552,7 +444,8 @@ export default class SimfinityClient {
       const returnType = unwrapType(field.type);
       const queryInfo = {
         name: field.name,
-        args: (field.args || []).map(a => ({ name: a.name, type: a.type })),
+        description: field.description,
+        args: (field.args || []).map(a => ({ ...a, hasDefault: a.hasDefault ?? (a.defaultValue != null) })),
         returnType,
         rawReturnType: field.type,
       };
@@ -566,13 +459,19 @@ export default class SimfinityClient {
       }
     }
 
-    for (const [typeName, pluralName] of this._typeNameToPlural) {
-      const aggName = `${pluralName}_aggregate`;
-      if (this._queries.has(aggName)) {
-        this._typeNameToAggregate.set(typeName, aggName);
-      }
+    for (const typeName of this._typeNameToPlural.keys()) {
+      const candidates = [...this._queries.values()].filter((query) => query.returnType.name === typeName && query.returnType.isList && !query.args.some((arg) => arg.name === 'aggregation'));
+      const canonical = candidates.filter((query) => this._queries.has(`${query.name}_aggregate`));
+      const selected = canonical.length === 1 ? canonical[0] : canonical.length === 0 && candidates.length === 1 ? candidates[0] : null;
+      if (selected) {
+        this._typeNameToPlural.set(typeName, selected.name);
+        if (canonical.length === 1) this._typeNameToAggregate.set(typeName, `${selected.name}_aggregate`);
+      } else this._typeNameToPlural.delete(typeName);
+    }
+    for (const typeName of this._typeNameToSingular.keys()) {
+      const candidates = [...this._queries.values()].filter((query) => query.returnType.name === typeName && !query.returnType.isList && query.args.some((arg) => arg.name === 'id'));
+      if (candidates.length !== 1) this._typeNameToSingular.delete(typeName);
     }
-
     this._queryNameToType = new Map();
     for (const [typeName, queryName] of this._typeNameToPlural) {
       this._queryNameToType.set(queryName, typeName);
@@ -592,7 +491,8 @@ export default class SimfinityClient {
       const returnType = unwrapType(field.type);
       const mutationInfo = {
         name: field.name,
-        args: (field.args || []).map(a => ({ name: a.name, type: a.type })),
+        description: field.description,
+        args: (field.args || []).map(a => ({ ...a, hasDefault: a.hasDefault ?? (a.defaultValue != null) })),
         returnType,
         rawReturnType: field.type,
         category: 'custom',
@@ -606,7 +506,18 @@ export default class SimfinityClient {
 
   _classifyMutation(mutationInfo, knownTypeNames) {
     const name = mutationInfo.name;
+    for (const kind of ['add', 'update', 'delete']) {
+      if (mutationInfo.description === kind && name.startsWith(kind) && knownTypeNames.includes(mutationInfo.returnType.name)) {
+        Object.assign(mutationInfo, { category: kind, typeName: mutationInfo.returnType.name }); return;
+      }
+    }
     for (const typeName of knownTypeNames) {
+      const singular = this._typeNameToSingular.get(typeName);
+      const suffix = `_${singular}`;
+      if (mutationInfo.returnType.name === typeName && singular && name.endsWith(suffix)
+        && this._types.get(typeName)?.fields.some((field) => field.extensions?.stateMachine)) {
+        Object.assign(mutationInfo, { category: 'stateTransition', typeName, action: name.slice(0, -suffix.length) }); return;
+      }
       if (name === `add${typeName}`) {
         Object.assign(mutationInfo, { category: 'add', typeName });
         return;
@@ -640,7 +551,7 @@ export default class SimfinityClient {
     const typeInfo = this._types.get(typeName);
     if (!typeInfo) return 'id';
     const scalars = typeInfo.fields
-      .filter(f => f.type.kind === 'SCALAR' || f.type.kind === 'ENUM')
+      .filter(f => (f.type.kind === 'SCALAR' || f.type.kind === 'ENUM') && canAutoSelect(f))
       .map(f => f.name);
     return scalars.length > 0 ? scalars.join(' ') : 'id';
   }
@@ -675,14 +586,71 @@ export default class SimfinityClient {
     }
     const headers = { 'Content-Type': 'application/json' };
     if (this._prepareHeaders) {
-      this._prepareHeaders(headers);
+      await this._prepareHeaders(headers);
     }
-    const response = await _fetch(this._endpoint, {
+    const response = await this._fetch(this._endpoint, {
       method: 'POST',
       headers,
       body: JSON.stringify(body),
     });
-    return response.json();
+    let envelope;
+    try { envelope = await response.json(); } catch { throw new Error(`Invalid JSON response (HTTP ${response.status})`); }
+    if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope)
+      || (envelope.errors !== undefined && (!Array.isArray(envelope.errors) || envelope.errors.length === 0 || envelope.errors.some((error) => !error || typeof error.message !== 'string')))
+      || (!Object.hasOwn(envelope, 'data') && !envelope.errors)
+      || (envelope.data !== undefined && envelope.data !== null && (typeof envelope.data !== 'object' || Array.isArray(envelope.data)))) throw new Error('Invalid GraphQL response');
+    if (!response.ok && !envelope.errors) throw new Error(`HTTP request failed (${response.status})`);
+    return envelope;
+  }
+
+  _checkErrors(response, name, partial = false) {
+    if (response.errors && (!partial || !response.data?.[name])) {
+      const error = new Error(`GraphQL errors: ${JSON.stringify(response.errors)}`);
+      error.graphQLErrors = response.errors; throw error;
+    }
+  }
+
+  async _requestOperation(kind, info, provided = {}, selection, collectionArguments = new Map()) {
+    const definitions = []; const variables = {}; const mappings = [];
+    for (const [name, value] of Object.entries(provided)) {
+      if (value === undefined) continue;
+      const arg = info.args.find((item) => item.name === name);
+      if (!arg) throw new Error(`Unknown ${kind} argument ${info.name}.${name}`);
+      definitions.push(`$${name}: ${typeRefToString(arg.type)}`); variables[name] = value; mappings.push(`${name}: $${name}`);
+    }
+    const context = { types: this._types, arguments: collectionArguments, used: new Set(), variable: (ref, value) => {
+      let name = `c${definitions.length}`; while (Object.hasOwn(variables, name)) name += '_';
+      variables[name] = value; definitions.push(`$${name}: ${typeRefToString(ref)}`); return name;
+    } };
+    const composite = ['OBJECT', 'INTERFACE', 'UNION'].includes(info.returnType.kind);
+    let fields = '';
+    if (composite) {
+      const tree = selection instanceof SelectionTree ? selection : new SelectionTree();
+      if (!(selection instanceof SelectionTree)) tree.addSelection(selection || this._getScalarFields(info.returnType.name));
+      fields = tree.serialize(context, info.returnType.name);
+      if (!fields) throw new Error(`No fields to select for ${info.name}`);
+    }
+    for (const path of collectionArguments.keys()) if (!context.used.has(path)) throw new Error(`Collection path is not selected: ${path}`);
+    const document = `${kind}${definitions.length ? `(${definitions.join(', ')})` : ''} { ${info.name}${mappings.length ? `(${mappings.join(', ')})` : ''}${fields ? ` { ${fields} }` : ''} }`;
+    return this._sendRequest(document, variables);
+  }
+
+  async query(name, args = {}, fields) {
+    this._ensureInitialized(); const info = this._queries.get(name);
+    if (!info) throw new Error(`Query '${name}' not found`);
+    const response = await this._requestOperation('query', info, args, fields);
+    this._checkErrors(response, name); return response.data?.[name];
+  }
+
+  getViews(typeName) {
+    this._ensureInitialized();
+    return [...this._queries.values()].filter((info) => info.view && (!typeName || info.typeName === typeName));
+  }
+
+  findView(name, params = {}) {
+    this._ensureInitialized(); const info = this._queries.get(name);
+    if (!info?.returnType.isList || (this._descriptor && !info.view)) throw new Error(`View '${name}' not found`);
+    const builder = new QueryBuilder(this, info.returnType.name, info); builder._variables = { ...params }; return builder;
   }
 
   // -- Query Methods -------------------------------------------------------
@@ -718,7 +686,7 @@ export default class SimfinityClient {
           searchField = 'name';
         } else {
           const firstScalar = typeInfo.fields.find(f =>
-            isScalarOrEnum(f.type.kind) && f.name !== 'id'
+            isScalarOrEnum(f.type.kind) && f.name !== 'id',
           );
           searchField = firstScalar?.name || 'id';
         }
@@ -784,7 +752,7 @@ export default class SimfinityClient {
     const transformedInput = options.transform
       ? this.transformInput(typeName, input, { mode: 'create', ...options })
       : input;
-    return this._executeMutation(`add${typeName}`, typeName, { input: transformedInput }, fields);
+    return this._executeMutation(this._mutationName(typeName, 'add'), typeName, { input: transformedInput }, fields);
   }
 
   async update(typeName, id, input, fields, options = {}) {
@@ -793,15 +761,39 @@ export default class SimfinityClient {
       ? this.transformInput(typeName, input, { mode: 'update', ...options })
       : input;
     return this._executeMutation(
-      `update${typeName}`, typeName,
+      this._mutationName(typeName, 'update'), typeName,
       { input: { id, ...transformedInput } },
       fields,
     );
   }
 
-  async delete(typeName, id, fields) {
+  async delete(typeName, id, fields, options = {}) {
     this._ensureInitialized();
-    return this._executeMutation(`delete${typeName}`, typeName, { id }, fields);
+    return this._executeMutation(this._mutationName(typeName, 'delete'), typeName, { id, ...(options.version !== undefined ? { version: options.version } : {}) }, fields);
+  }
+
+  _mutationName(typeName, kind) {
+    if (this._descriptor) {
+      const name = this._descriptor.types[typeName]?.endpoints?.[kind];
+      if (!name) throw new Error(`No ${kind} mutation for '${typeName}'`);
+      return name;
+    }
+    return [...this._mutations.values()].find((info) => info.category === kind && info.typeName === typeName)?.name || `${kind}${typeName}`;
+  }
+
+  _inputTypeName(typeName, kind) {
+    const descriptor = this._descriptor?.types[typeName]?.inputs?.[kind];
+    if (descriptor) return descriptor;
+    const info = this._mutations.get(this._mutationName(typeName, kind));
+    const input = info?.args.find((arg) => arg.name === 'input');
+    return input ? unwrapType(input.type).name : null;
+  }
+
+  async transaction(operations, fields = 'id', options = {}) {
+    this._ensureInitialized();
+    const info = options.name ? this._mutations.get(options.name) : [...this._mutations.values()].find((item) => item.category === 'transaction');
+    if (!info || (this._descriptor && info.category !== 'transaction') || (!this._descriptor && !options.name)) throw new Error('Generated transaction not found; introspection requires an explicit transaction name');
+    return this._executeMutation(info.name, info.returnType.name, { operations }, fields);
   }
 
   // -- State Machine -------------------------------------------------------
@@ -884,35 +876,10 @@ export default class SimfinityClient {
   // -- Shared Mutation Executor --------------------------------------------
 
   async _executeMutation(mutationName, typeName, providedArgs, fields) {
-    const mutationInfo = this._mutations.get(mutationName);
-    if (!mutationInfo) {
-      throw new Error(`Mutation '${mutationName}' not found`);
-    }
-
-    const selectionSet = this._resolveFields(typeName, fields);
-    const varDefs = [];
-    const variables = {};
-    const argMappings = [];
-
-    for (const arg of mutationInfo.args) {
-      if (providedArgs[arg.name] !== undefined) {
-        varDefs.push(`$${arg.name}: ${typeRefToString(arg.type)}`);
-        variables[arg.name] = providedArgs[arg.name];
-        argMappings.push(`${arg.name}: $${arg.name}`);
-      }
-    }
-
-    const varDefsStr = varDefs.length > 0 ? `(${varDefs.join(', ')})` : '';
-    const argsBlock = argMappings.length > 0 ? `(${argMappings.join(', ')})` : '';
-    const query = `mutation${varDefsStr} { ${mutationName}${argsBlock} { ${selectionSet} } }`;
-
-    const response = await this._sendRequest(query, variables);
-    if (response.errors) {
-      const error = new Error(`GraphQL errors: ${JSON.stringify(response.errors)}`);
-      error.graphQLErrors = response.errors;
-      throw error;
-    }
-    return response.data[mutationName];
+    const info = this._mutations.get(mutationName);
+    if (!info) throw new Error(`Mutation '${mutationName}' not found`);
+    const response = await this._requestOperation('mutation', info, providedArgs, fields);
+    this._checkErrors(response, mutationName); return response.data?.[mutationName];
   }
 
   // -- Schema Getters ------------------------------------------------------
@@ -946,7 +913,7 @@ export default class SimfinityClient {
     for (const field of typeInfo.fields) {
       const { name, type: unwrapped, rawType, extensions } = field;
 
-      if (isListType(rawType)) continue;
+      if (isListType(rawType) || !canAutoSelect(field)) continue;
 
       if (isScalarOrEnum(unwrapped.kind)) {
         fieldSelections.push(name);
@@ -955,7 +922,7 @@ export default class SimfinityClient {
         fieldTypeByColumn[name] = unwrapped.name || unwrapped.kind || 'SCALAR';
       } else if (unwrapped.kind === 'OBJECT' && unwrapped.name) {
         const objType = this._types.get(unwrapped.name);
-        const objFields = objType?.fields || [];
+        const objFields = (objType?.fields || []).filter((candidate) => isScalarOrEnum(candidate.type.kind) && !candidate.type.isList && canAutoSelect(candidate));
         const objFieldNames = new Set(objFields.map(f => f.name));
         const isEmbedded = extensions?.relation?.embedded === true;
 
@@ -967,7 +934,7 @@ export default class SimfinityClient {
           chosenDisplay = 'name';
         } else {
           const firstScalar = objFields.find(f =>
-            isScalarOrEnum(f.type.kind) && !f.type.isList
+            isScalarOrEnum(f.type.kind) && !f.type.isList,
           );
           chosenDisplay = firstScalar?.name || null;
         }
@@ -981,6 +948,7 @@ export default class SimfinityClient {
           else if (objFields[0]) subFields.add(objFields[0].name);
         }
 
+        if (subFields.size === 0) continue;
         const subSelection = [...subFields].join(' ');
         fieldSelections.push(`${name} { ${subSelection} }`);
         columns.push(name);
@@ -996,13 +964,13 @@ export default class SimfinityClient {
       }
     }
 
-    const hasId = typeInfo.fields.some(f => f.name === 'id');
+    const hasId = typeInfo.fields.some(f => f.name === 'id' && canAutoSelect(f));
     if (hasId && !fieldSelections.includes('id')) {
       fieldSelections.unshift('id');
     }
 
     return {
-      selection: fieldSelections.join('\n'),
+      selection: fieldSelections.join('\n') || '__typename',
       columns,
       sortFieldByColumn,
       fieldTypeByColumn,
@@ -1036,7 +1004,7 @@ export default class SimfinityClient {
     if (objFieldNames.includes('name')) return 'name';
 
     const firstScalar = objectType.fields.find(f =>
-      isScalarOrEnum(f.type.kind) && !f.type.isList
+      isScalarOrEnum(f.type.kind) && !f.type.isList,
     );
     return firstScalar?.name || null;
   }
@@ -1149,8 +1117,12 @@ export default class SimfinityClient {
   // -- Mutation Input Transformation -----------------------------------------
 
   transformInput(typeName, rawInput, options = {}) {
+    this._ensureInitialized(); return transformRootInput(this, typeName, rawInput, options);
+  }
+
+  _legacyTransformInput(typeName, rawInput, options = {}) {
     this._ensureInitialized();
-    const { skipFields = [], transientFields = [], mode = 'create' } = options;
+    const { skipFields = [], transientFields = [] } = options;
     const typeInfo = this._types.get(typeName);
     if (!typeInfo) return { ...rawInput };
 
@@ -1184,7 +1156,7 @@ export default class SimfinityClient {
     return this._deepRemoveTypename(transformed);
   }
 
-  _transformEmbeddedInput(objectTypeName, value, options = {}) {
+  _transformEmbeddedInput(objectTypeName, value) {
     if (!value || typeof value !== 'object') return value;
     const typeInfo = this._types.get(objectTypeName);
     if (!typeInfo?.fields) return value;
@@ -1243,93 +1215,7 @@ export default class SimfinityClient {
   // -- Collection Delta Mutations --------------------------------------------
 
   transformCollectionDelta(collectionTypeName, delta, options = {}) {
-    this._ensureInitialized();
-    const { connectionField = null } = options;
-    const result = {};
-
-    if (delta.added && delta.added.length > 0) {
-      result.added = delta.added.map(item => {
-        let clean = { ...item };
-
-        delete clean.__status;
-        delete clean.__originalData;
-
-        if (connectionField && clean[connectionField] !== undefined) {
-          delete clean[connectionField];
-        }
-
-        if (clean.id && typeof clean.id === 'string' && clean.id.startsWith('temp_')) {
-          delete clean.id;
-        }
-
-        clean = this._cleanCollectionItem(collectionTypeName, clean);
-        clean = this._deepRemoveTypename(clean);
-        return clean;
-      });
-    }
-
-    if (delta.updated && delta.updated.length > 0) {
-      result.updated = delta.updated.map(item => {
-        let clean = { ...item };
-
-        delete clean.__status;
-        delete clean.__originalData;
-
-        if (connectionField && clean[connectionField] !== undefined) {
-          delete clean[connectionField];
-        }
-
-        clean = this._cleanCollectionItem(collectionTypeName, clean);
-        clean = this._deepRemoveTypename(clean);
-        return clean;
-      });
-    }
-
-    if (delta.deleted && delta.deleted.length > 0) {
-      result.deleted = delta.deleted.map(item => {
-        if (typeof item === 'string') return item;
-        if (typeof item === 'object' && item.id) return item.id;
-        return item;
-      });
-    }
-
-    return result;
-  }
-
-  _cleanCollectionItem(collectionTypeName, item) {
-    const typeInfo = this._types.get(collectionTypeName);
-    if (!typeInfo?.fields) return item;
-
-    const cleaned = { ...item };
-
-    for (const field of typeInfo.fields) {
-      const { name, type: unwrapped, rawType, extensions } = field;
-      if (cleaned[name] === undefined) continue;
-
-      if (extensions?.stateMachine === true) {
-        delete cleaned[name];
-        continue;
-      }
-
-      if (unwrapped.kind === 'OBJECT' && !extensions?.relation?.embedded) {
-        const val = cleaned[name];
-        if (val && typeof val === 'object' && 'id' in val) {
-          cleaned[name] = { id: val.id };
-        }
-        continue;
-      }
-
-      if (isNumericScalar(unwrapped.name) && typeof cleaned[name] === 'string') {
-        cleaned[name] = Number(cleaned[name]);
-      }
-      if (isDateTimeScalar(unwrapped.name) && typeof cleaned[name] === 'string') {
-        if (/^\d{4}-\d{2}-\d{2}$/.test(cleaned[name])) {
-          cleaned[name] = `${cleaned[name]}T00:00:00.000Z`;
-        }
-      }
-    }
-
-    return cleaned;
+    this._ensureInitialized(); return transformDelta(this, collectionTypeName, delta, options);
   }
 
   // -- Guard ---------------------------------------------------------------
@@ -1339,4 +1225,12 @@ export default class SimfinityClient {
       throw new Error('Client not initialized. Call init() first.');
     }
   }
+
+  // -- Static Helpers -------------------------------------------------------
+
+  static condition(field, operator, value, path) {
+    const cond = { field, operator, value };
+    if (path !== undefined) cond.path = path;
+    return { conditions: [cond] };
+  }
 }