@proofkit/fmodata 0.1.0-alpha.11 → 0.1.0-alpha.12

package/src/client/query-builder.ts

@@ -10,6 +10,7 @@ import type {
   ConditionallyWithODataAnnotations,
   ExtractSchemaFromOccurrence,
 } from "../types";
+import { getAcceptHeader } from "../types";
 import type { Filter } from "../filter-types";
 import type { TableOccurrence } from "./table-occurrence";
 import type { BaseTable } from "./base-table";
@@ -24,6 +25,7 @@ import {
   transformResponseFields,
   getTableIdentifiers,
 } from "../transform";
+import { safeJsonParse } from "./sanitize-json";
 
 /**
  * Default maximum number of records to return in a list query.
@@ -182,23 +184,6 @@ export class QueryBuilder<
     };
   }
 
-  /**
-   * Helper to conditionally strip OData annotations based on options
-   */
-  private stripODataAnnotationsIfNeeded<T extends Record<string, any>>(
-    data: T,
-    options?: ExecuteOptions,
-  ): T {
-    // Only include annotations if explicitly requested
-    if (options?.includeODataAnnotations === true) {
-      return data;
-    }
-
-    // Strip OData annotations
-    const { "@id": _id, "@editLink": _editLink, ...rest } = data;
-    return rest as T;
-  }
-
   /**
    * Gets the table ID (FMTID) if using entity IDs, otherwise returns the table name
    * @param useEntityIds - Optional override for entity ID usage
@@ -592,6 +577,22 @@ export class QueryBuilder<
     // Look up target occurrence from navigation
     const targetOccurrence = this.occurrence?.navigation[relation as string];
 
+    // Helper function to get defaultSelect fields from target occurrence
+    const getDefaultSelectFields = (): string[] | undefined => {
+      if (!targetOccurrence) return undefined;
+      const defaultSelect = targetOccurrence.defaultSelect;
+      if (defaultSelect === "schema") {
+        const schema = targetOccurrence.baseTable?.schema;
+        if (schema) {
+          return [...new Set(Object.keys(schema))];
+        }
+      } else if (Array.isArray(defaultSelect)) {
+        return [...new Set(defaultSelect)];
+      }
+      // If "all", return undefined (no select restriction)
+      return undefined;
+    };
+
     if (callback) {
       // Create a new QueryBuilder for the target occurrence
       const targetBuilder = new QueryBuilder<any>({
@@ -622,6 +623,14 @@ export class QueryBuilder<
         ...configuredBuilder.queryOptions,
       };
 
+      // If callback didn't provide select, apply defaultSelect from target occurrence
+      if (!expandOptions.select) {
+        const defaultFields = getDefaultSelectFields();
+        if (defaultFields) {
+          expandOptions.select = defaultFields;
+        }
+      }
+
       // If the configured builder has nested expands, we need to include them
       if (configuredBuilder.expandConfigs.length > 0) {
         // Build nested expand string from the configured builder's expand configs
@@ -641,8 +650,16 @@ export class QueryBuilder<
 
       this.expandConfigs.push(expandConfig);
     } else {
-      // Simple expand without callback
-      this.expandConfigs.push({ relation: relation as string });
+      // Simple expand without callback - apply defaultSelect if available
+      const defaultFields = getDefaultSelectFields();
+      if (defaultFields) {
+        this.expandConfigs.push({
+          relation: relation as string,
+          options: { select: defaultFields },
+        });
+      } else {
+        this.expandConfigs.push({ relation: relation as string });
+      }
     }
 
     return this as any;
@@ -858,13 +875,10 @@ export class QueryBuilder<
           }
 
           const record = Array.isArray(records) ? records[0] : records;
-          const stripped = this.stripODataAnnotationsIfNeeded(record, options);
-          return { data: stripped as any, error: undefined };
+          return { data: record as any, error: undefined };
         } else {
           const records = resp.value ?? [];
-          const stripped = records.map((record: any) =>
-            this.stripODataAnnotationsIfNeeded(record, options),
-          );
+          const stripped = records.map((record: any) => record);
           return { data: stripped as any, error: undefined };
         }
       }
@@ -889,10 +903,7 @@ export class QueryBuilder<
         if (!validation.valid) {
           return { data: undefined, error: validation.error };
         }
-        const stripped = validation.data
-          ? this.stripODataAnnotationsIfNeeded(validation.data, options)
-          : null;
-        return { data: stripped as any, error: undefined };
+        return { data: validation.data as any, error: undefined };
       } else {
         const validation = await validateListResponse<T>(
           response,
@@ -903,10 +914,7 @@ export class QueryBuilder<
         if (!validation.valid) {
           return { data: undefined, error: validation.error };
         }
-        const stripped = validation.data.map((record) =>
-          this.stripODataAnnotationsIfNeeded(record, options),
-        );
-        return { data: stripped as any, error: undefined };
+        return { data: validation.data as any, error: undefined };
       }
     }
 
@@ -971,13 +979,10 @@ export class QueryBuilder<
           }
 
           const record = Array.isArray(records) ? records[0] : records;
-          const stripped = this.stripODataAnnotationsIfNeeded(record, options);
-          return { data: stripped as any, error: undefined };
+          return { data: record as any, error: undefined };
         } else {
           const records = resp.value ?? [];
-          const stripped = records.map((record: any) =>
-            this.stripODataAnnotationsIfNeeded(record, options),
-          );
+          const stripped = records.map((record: any) => record);
           return { data: stripped as any, error: undefined };
         }
       }
@@ -1002,10 +1007,7 @@ export class QueryBuilder<
         if (!validation.valid) {
           return { data: undefined, error: validation.error };
         }
-        const stripped = validation.data
-          ? this.stripODataAnnotationsIfNeeded(validation.data, options)
-          : null;
-        return { data: stripped as any, error: undefined };
+        return { data: validation.data as any, error: undefined };
       } else {
         const validation = await validateListResponse<T>(
           response,
@@ -1016,10 +1018,7 @@ export class QueryBuilder<
         if (!validation.valid) {
           return { data: undefined, error: validation.error };
         }
-        const stripped = validation.data.map((record) =>
-          this.stripODataAnnotationsIfNeeded(record, options),
-        );
-        return { data: stripped as any, error: undefined };
+        return { data: validation.data as any, error: undefined };
       }
     }
 
@@ -1096,15 +1095,11 @@ export class QueryBuilder<
         }
 
         const record = Array.isArray(records) ? records[0] : records;
-        const stripped = this.stripODataAnnotationsIfNeeded(record, options);
-        return { data: stripped as any, error: undefined };
+        return { data: record as any, error: undefined };
       } else {
         // Handle list response structure
         const records = resp.value ?? [];
-        const stripped = records.map((record: any) =>
-          this.stripODataAnnotationsIfNeeded(record, options),
-        );
-        return { data: stripped as any, error: undefined };
+        return { data: records as any, error: undefined };
       }
     }
 
@@ -1126,11 +1121,8 @@ export class QueryBuilder<
       if (!validation.valid) {
         return { data: undefined, error: validation.error };
       }
-      const stripped = validation.data
-        ? this.stripODataAnnotationsIfNeeded(validation.data, options)
-        : null;
       return {
-        data: stripped as any,
+        data: validation.data as any,
         error: undefined,
       };
     } else {
@@ -1143,11 +1135,8 @@ export class QueryBuilder<
       if (!validation.valid) {
         return { data: undefined, error: validation.error };
       }
-      const stripped = validation.data.map((record) =>
-        this.stripODataAnnotationsIfNeeded(record, options),
-      );
       return {
-        data: stripped as any,
+        data: validation.data as any,
         error: undefined,
       };
     }
@@ -1223,8 +1212,9 @@ export class QueryBuilder<
       return queryParams ? `${path}${queryParams}` : path;
     }
 
-    // Default case: return table name with query params
-    return `/${this.tableName}${queryParams}`;
+    // Default case: return table ID (respects entity ID settings) with query params
+    const tableId = this.getTableId(this.databaseUseEntityIds);
+    return `/${tableId}${queryParams}`;
   }
 
   getRequestConfig(): { method: string; url: string; body?: any } {
@@ -1280,9 +1270,13 @@ export class QueryBuilder<
         url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}${queryString}`;
       }
     } else if (this.isCountMode) {
-      url = `/${this.databaseName}/${this.tableName}/$count${queryString}`;
+      // Use getTableId to respect entity ID settings (for batch operations)
+      const tableId = this.getTableId(this.databaseUseEntityIds);
+      url = `/${this.databaseName}/${tableId}/$count${queryString}`;
     } else {
-      url = `/${this.databaseName}/${this.tableName}${queryString}`;
+      // Use getTableId to respect entity ID settings (for batch operations)
+      const tableId = this.getTableId(this.databaseUseEntityIds);
+      url = `/${this.databaseName}/${tableId}${queryString}`;
     }
 
     return {
@@ -1291,7 +1285,7 @@ export class QueryBuilder<
     };
   }
 
-  toRequest(baseUrl: string): Request {
+  toRequest(baseUrl: string, options?: ExecuteOptions): Request {
     const config = this.getRequestConfig();
     const fullUrl = `${baseUrl}${config.url}`;
 
@@ -1299,7 +1293,7 @@ export class QueryBuilder<
       method: config.method,
       headers: {
         "Content-Type": "application/json",
-        Accept: "application/json",
+        Accept: getAcceptHeader(options?.includeODataAnnotations),
       },
     });
   }
@@ -1325,10 +1319,10 @@ export class QueryBuilder<
       return { data: [] as any, error: undefined };
     }
 
-    // Parse the response body
+    // Parse the response body (using safeJsonParse to handle FileMaker's invalid JSON with unquoted ? values)
     let rawData;
     try {
-      rawData = await response.json();
+      rawData = await safeJsonParse(response);
     } catch (err) {
       // Check if it's an empty body error (common with 204 responses)
       if (err instanceof SyntaxError && response.status === 204) {
@@ -1400,15 +1394,11 @@ export class QueryBuilder<
         }
 
         const record = Array.isArray(records) ? records[0] : records;
-        const stripped = this.stripODataAnnotationsIfNeeded(record, options);
-        return { data: stripped as any, error: undefined };
+        return { data: record as any, error: undefined };
       } else {
         // Handle list response structure
         const records = resp.value ?? [];
-        const stripped = records.map((record: any) =>
-          this.stripODataAnnotationsIfNeeded(record, options),
-        );
-        return { data: stripped as any, error: undefined };
+        return { data: records as any, error: undefined };
       }
     }
 
@@ -1437,11 +1427,7 @@ export class QueryBuilder<
         return { data: null as any, error: undefined };
       }
 
-      const stripped = this.stripODataAnnotationsIfNeeded(
-        validation.data,
-        options,
-      );
-      return { data: stripped as any, error: undefined };
+      return { data: validation.data as any, error: undefined };
     }
 
     // List mode
@@ -1456,9 +1442,6 @@ export class QueryBuilder<
       return { data: undefined, error: validation.error };
     }
 
-    const stripped = validation.data.map((record) =>
-      this.stripODataAnnotationsIfNeeded(record, options),
-    );
-    return { data: stripped as any, error: undefined };
+    return { data: validation.data as any, error: undefined };
   }
 }

package/src/client/record-builder.ts

@@ -9,6 +9,7 @@ import type {
   WithSystemFields,
   ConditionallyWithODataAnnotations,
 } from "../types";
+import { getAcceptHeader } from "../types";
 import type { TableOccurrence } from "./table-occurrence";
 import type { BaseTable } from "./base-table";
 import {
@@ -17,8 +18,12 @@ import {
   getTableIdentifiers,
   transformFieldNamesArray,
 } from "../transform";
+import { safeJsonParse } from "./sanitize-json";
 import { QueryBuilder } from "./query-builder";
-import { validateSingleResponse, type ExpandValidationConfig } from "../validation";
+import {
+  validateSingleResponse,
+  type ExpandValidationConfig,
+} from "../validation";
 import { type FFetchOptions } from "@fetchkit/ffetch";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 import { QueryOptions } from "odata-query";
@@ -185,7 +190,7 @@ export class RecordBuilder<
       const identifiers = getTableIdentifiers(this.occurrence);
       if (!identifiers.id) {
         throw new Error(
-          `useEntityIds is true but TableOccurrence "${identifiers.name}" does not have an fmtId defined`
+          `useEntityIds is true but TableOccurrence "${identifiers.name}" does not have an fmtId defined`,
         );
       }
       return identifiers.id;
@@ -303,6 +308,22 @@ export class RecordBuilder<
     // Look up target occurrence from navigation
     const targetOccurrence = this.occurrence?.navigation[relation as string];
 
+    // Helper function to get defaultSelect fields from target occurrence
+    const getDefaultSelectFields = (): string[] | undefined => {
+      if (!targetOccurrence) return undefined;
+      const defaultSelect = targetOccurrence.defaultSelect;
+      if (defaultSelect === "schema") {
+        const schema = targetOccurrence.baseTable?.schema;
+        if (schema) {
+          return [...new Set(Object.keys(schema))];
+        }
+      } else if (Array.isArray(defaultSelect)) {
+        return [...new Set(defaultSelect)];
+      }
+      // If "all", return undefined (no select restriction)
+      return undefined;
+    };
+
     // Create new builder with updated types
     const newBuilder = new RecordBuilder<
       T,
@@ -359,6 +380,14 @@ export class RecordBuilder<
         ...(configuredBuilder as any).queryOptions,
       };
 
+      // If callback didn't provide select, apply defaultSelect from target occurrence
+      if (!expandOptions.select) {
+        const defaultFields = getDefaultSelectFields();
+        if (defaultFields) {
+          expandOptions.select = defaultFields;
+        }
+      }
+
       // If the configured builder has nested expands, we need to include them
       if ((configuredBuilder as any).expandConfigs?.length > 0) {
         // Build nested expand string from the configured builder's expand configs
@@ -378,8 +407,16 @@ export class RecordBuilder<
 
       newBuilder.expandConfigs.push(expandConfig);
     } else {
-      // Simple expand without callback
-      newBuilder.expandConfigs.push({ relation: relation as string });
+      // Simple expand without callback - apply defaultSelect if available
+      const defaultFields = getDefaultSelectFields();
+      if (defaultFields) {
+        newBuilder.expandConfigs.push({
+          relation: relation as string,
+          options: { select: defaultFields },
+        });
+      } else {
+        newBuilder.expandConfigs.push({ relation: relation as string });
+      }
     }
 
     return newBuilder;
@@ -612,22 +649,6 @@ export class RecordBuilder<
     return `?${parts.join("&")}`;
   }
 
-  /**
-   * Helper to conditionally strip OData annotations based on options
-   */
-  private stripODataAnnotationsIfNeeded<R extends Record<string, any>>(
-    data: R,
-    options?: ExecuteOptions,
-  ): R {
-    // Only include annotations if explicitly requested
-    if (options?.includeODataAnnotations === true) {
-      return data;
-    }
-
-    // Strip OData annotations
-    const { "@id": _id, "@editLink": _editLink, ...rest } = data;
-    return rest as R;
-  }
 
   async execute<EO extends ExecuteOptions>(
     options?: RequestInit & FFetchOptions & EO,
@@ -720,13 +741,7 @@ export class RecordBuilder<
       return { data: null as any, error: undefined };
     }
 
-    // Strip OData annotations if not requested
-    const stripped = this.stripODataAnnotationsIfNeeded(
-      validation.data,
-      options,
-    );
-
-    return { data: stripped as any, error: undefined };
+    return { data: validation.data as any, error: undefined };
   }
 
   getRequestConfig(): { method: string; url: string; body?: any } {
@@ -774,7 +789,9 @@ export class RecordBuilder<
     ) {
       path = `/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;
     } else {
-      path = `/${this.tableName}('${this.recordId}')`;
+      // Use getTableId to respect entity ID settings (same as getRequestConfig)
+      const tableId = this.getTableId(this.databaseUseEntityIds);
+      path = `/${tableId}('${this.recordId}')`;
     }
 
     if (this.operation === "getSingleField" && this.operationParam) {
@@ -785,7 +802,7 @@ export class RecordBuilder<
     return `${path}${queryString}`;
   }
 
-  toRequest(baseUrl: string): Request {
+  toRequest(baseUrl: string, options?: ExecuteOptions): Request {
     const config = this.getRequestConfig();
     const fullUrl = `${baseUrl}${config.url}`;
 
@@ -793,7 +810,7 @@ export class RecordBuilder<
       method: config.method,
       headers: {
         "Content-Type": "application/json",
-        Accept: "application/json",
+        Accept: getAcceptHeader(options?.includeODataAnnotations),
       },
     });
   }
@@ -804,7 +821,8 @@ export class RecordBuilder<
   ): Promise<
     Result<RecordReturnType<T, IsSingleField, FieldKey, Selected, Expands>>
   > {
-    const rawResponse = await response.json();
+    // Use safeJsonParse to handle FileMaker's invalid JSON with unquoted ? values
+    const rawResponse = await safeJsonParse(response);
 
     // Handle single field operation
     if (this.operation === "getSingleField") {
@@ -853,12 +871,6 @@ export class RecordBuilder<
       return { data: null as any, error: undefined };
     }
 
-    // Strip OData annotations if not requested
-    const stripped = this.stripODataAnnotationsIfNeeded(
-      validation.data,
-      options,
-    );
-
-    return { data: stripped as any, error: undefined };
+    return { data: validation.data as any, error: undefined };
   }
 }

package/src/client/response-processor.ts

@@ -23,19 +23,6 @@ export type ODataRecordResponse<T = unknown> = ODataResponse<
   }
 >;
 
-/**
- * Strip OData annotations from a single record
- */
-export function stripODataAnnotations<T extends Record<string, unknown>>(
-  record: ODataRecordResponse<T>,
-  options?: ExecuteOptions,
-): T {
-  if (options?.includeODataAnnotations === true) {
-    return record as T;
-  }
-  const { "@id": _id, "@editLink": _editLink, ...rest } = record;
-  return rest as T;
-}
 
 /**
  * Transform field IDs back to names using the base table configuration

package/src/client/sanitize-json.ts

@@ -0,0 +1,66 @@
+/**
+ * FileMaker OData API sometimes returns invalid JSON containing unquoted `?`
+ * characters as field values (e.g., `"fieldName": ?`), which causes JSON.parse()
+ * to fail. This module provides utilities to sanitize such responses before parsing.
+ */
+
+import { ResponseParseError } from "../errors";
+
+/**
+ * Sanitizes FileMaker OData JSON responses by replacing unquoted `?` values with `null`.
+ *
+ * FileMaker uses `?` to represent undefined/null values in its OData responses,
+ * but this is not valid JSON. This function converts those to proper `null` values.
+ *
+ * The regex uses two patterns:
+ * 1. `/:\s*\?(?=\s*[,}\]])/g` - for values in objects (after `:`)
+ * 2. `/(?<=[\[,])\s*\?(?=\s*[,\]])/g` - for values in arrays (after `[` or `,`)
+ *
+ * @param text - The raw response text from FileMaker OData API
+ * @returns Sanitized JSON string with `?` values replaced by `null`
+ *
+ * @example
+ * sanitizeFileMakerJson('{"field1": "valid", "field2": ?, "field3": null}')
+ * // Returns: '{"field1": "valid", "field2": null, "field3": null}'
+ */
+export function sanitizeFileMakerJson(text: string): string {
+  // Replace unquoted ? values in objects (after colon)
+  // Also handles arrays when the array is a value in an object
+  let result = text.replace(/:\s*\?(?=\s*[,}\]])/g, ": null");
+
+  // Replace unquoted ? values directly in arrays (not after colon)
+  // e.g., [1, ?, 3] -> [1, null, 3]
+  result = result.replace(/(?<=[\[,])\s*\?(?=\s*[,\]])/g, " null");
+
+  return result;
+}
+
+/**
+ * Safely parses a Response body as JSON, handling FileMaker's invalid JSON responses.
+ *
+ * This function reads the response as text first, sanitizes any invalid `?` values,
+ * and then parses the sanitized JSON. This approach handles the case where FileMaker
+ * returns a Content-Type of application/json but the body contains invalid JSON.
+ *
+ * @param response - The fetch Response object
+ * @returns Parsed JSON data
+ * @throws ResponseParseError if the JSON is still invalid after sanitization (includes sanitized text for debugging)
+ */
+export async function safeJsonParse<T = unknown>(
+  response: Response,
+): Promise<T> {
+  const text = await response.text();
+  const sanitized = sanitizeFileMakerJson(text);
+  try {
+    return JSON.parse(sanitized) as T;
+  } catch (err) {
+    throw new ResponseParseError(
+      response.url,
+      `Failed to parse response as JSON: ${err instanceof Error ? err.message : "Unknown error"}`,
+      {
+        rawText: sanitized,
+        cause: err instanceof Error ? err : undefined,
+      },
+    );
+  }
+}

package/src/client/update-builder.ts

@@ -5,6 +5,7 @@ import type {
   WithSystemFields,
   ExecuteOptions,
 } from "../types";
+import { getAcceptHeader } from "../types";
 import type { TableOccurrence } from "./table-occurrence";
 import type { BaseTable } from "./base-table";
 import { QueryBuilder } from "./query-builder";
@@ -331,7 +332,7 @@ export class ExecutableUpdateBuilder<
     };
   }
 
-  toRequest(baseUrl: string): Request {
+  toRequest(baseUrl: string, options?: ExecuteOptions): Request {
     const config = this.getRequestConfig();
     const fullUrl = `${baseUrl}${config.url}`;
 
@@ -339,7 +340,7 @@ export class ExecutableUpdateBuilder<
       method: config.method,
       headers: {
         "Content-Type": "application/json",
-        Accept: "application/json",
+        Accept: getAcceptHeader(options?.includeODataAnnotations),
       },
       body: config.body,
     });

package/src/errors.ts

@@ -151,6 +151,22 @@ export class InvalidLocationHeaderError extends FMODataError {
   }
 }
 
+export class ResponseParseError extends FMODataError {
+  readonly kind = "ResponseParseError" as const;
+  readonly url: string;
+  readonly rawText?: string;
+
+  constructor(
+    url: string,
+    message: string,
+    options?: { rawText?: string; cause?: Error },
+  ) {
+    super(message, options?.cause ? { cause: options.cause } : undefined);
+    this.url = url;
+    this.rawText = options?.rawText;
+  }
+}
+
 // ============================================
 // Type Guards
 // ============================================
@@ -185,6 +201,12 @@ export function isRecordCountMismatchError(
   return error instanceof RecordCountMismatchError;
 }
 
+export function isResponseParseError(
+  error: unknown,
+): error is ResponseParseError {
+  return error instanceof ResponseParseError;
+}
+
 export function isFMODataError(error: unknown): error is FMODataError {
   return error instanceof FMODataError;
 }
@@ -214,4 +236,5 @@ export type FMODataErrorType =
   | ValidationError
   | ResponseStructureError
   | RecordCountMismatchError
-  | InvalidLocationHeaderError;
+  | InvalidLocationHeaderError
+  | ResponseParseError;

package/src/index.ts

@@ -62,12 +62,14 @@ export {
   ValidationError,
   ResponseStructureError,
   RecordCountMismatchError,
+  ResponseParseError,
   isHTTPError,
   isValidationError,
   isODataError,
   isSchemaLockedError,
   isResponseStructureError,
   isRecordCountMismatchError,
+  isResponseParseError,
   isFMODataError,
 } from "./errors";