@proofkit/fmodata 0.1.0-alpha.8 → 0.1.0-beta.23

package/src/client/error-parser.ts

@@ -0,0 +1,41 @@
+import { type FMODataErrorType, HTTPError, ODataError, SchemaLockedError } from "../errors";
+import { safeJsonParse } from "./sanitize-json";
+
+/**
+ * Parses an error response and returns an appropriate error object.
+ * This helper is used by builder processResponse methods to handle error responses
+ * consistently, particularly important for batch operations where errors need to be
+ * properly parsed from the response body.
+ *
+ * @param response - The Response object (may be from batch or direct request)
+ * @param url - The URL that was requested (for error context)
+ * @returns An appropriate error object (ODataError, SchemaLockedError, or HTTPError)
+ */
+export async function parseErrorResponse(response: Response, url: string): Promise<FMODataErrorType> {
+  // Try to parse error body if it's JSON
+  let errorBody: { error?: { code?: string | number; message?: string } } | undefined;
+
+  try {
+    if (response.headers.get("content-type")?.includes("application/json")) {
+      errorBody = await safeJsonParse<typeof errorBody>(response);
+    }
+  } catch {
+    // Ignore JSON parse errors - we'll fall back to HTTPError
+  }
+
+  // Check if it's an OData error response
+  if (errorBody?.error) {
+    const errorCode = errorBody.error.code;
+    const errorMessage = errorBody.error.message || response.statusText;
+
+    // Check for schema locked error (code 303)
+    if (errorCode === "303" || errorCode === 303) {
+      return new SchemaLockedError(url, errorMessage, errorBody.error);
+    }
+
+    return new ODataError(url, errorMessage, String(errorCode), errorBody.error);
+  }
+
+  // Fall back to generic HTTPError
+  return new HTTPError(url, response.status, response.statusText, errorBody);
+}

package/src/client/filemaker-odata.ts

@@ -1,26 +1,35 @@
 import createClient, {
-  FFetchOptions,
-  TimeoutError,
   AbortError,
+  CircuitOpenError,
+  type FFetchOptions,
   NetworkError,
   RetryLimitError,
-  CircuitOpenError,
+  TimeoutError,
 } from "@fetchkit/ffetch";
+import { get } from "es-toolkit/compat";
+import { HTTPError, ODataError, ResponseParseError, SchemaLockedError } from "../errors";
+import { createLogger, type InternalLogger, type Logger } from "../logger";
 import type { Auth, ExecutionContext, Result } from "../types";
-import { HTTPError, ODataError, SchemaLockedError } from "../errors";
+import { getAcceptHeader } from "../types";
 import { Database } from "./database";
-import { TableOccurrence } from "./table-occurrence";
+import { safeJsonParse } from "./sanitize-json";
+
+const TRAILING_SLASH_REGEX = /\/+$/;
 
 export class FMServerConnection implements ExecutionContext {
-  private fetchClient: ReturnType<typeof createClient>;
-  private serverUrl: string;
-  private auth: Auth;
-  private useEntityIds: boolean = false;
+  private readonly fetchClient: ReturnType<typeof createClient>;
+  private readonly serverUrl: string;
+  private readonly auth: Auth;
+  private useEntityIds = false;
+  private includeSpecialColumns = false;
+  private readonly logger: InternalLogger;
   constructor(config: {
     serverUrl: string;
     auth: Auth;
     fetchClientOptions?: FFetchOptions;
+    logger?: Logger;
   }) {
+    this.logger = createLogger(config.logger);
     this.fetchClient = createClient({
       retries: 0,
       ...config.fetchClientOptions,
@@ -31,8 +40,8 @@ export class FMServerConnection implements ExecutionContext {
       url.protocol = "https:";
     }
     // Remove any trailing slash from pathname
-    url.pathname = url.pathname.replace(/\/+$/, "");
-    this.serverUrl = url.toString().replace(/\/+$/, "");
+    url.pathname = url.pathname.replace(TRAILING_SLASH_REGEX, "");
+    this.serverUrl = url.toString().replace(TRAILING_SLASH_REGEX, "");
     this.auth = config.auth;
   }
 
@@ -52,12 +61,36 @@ export class FMServerConnection implements ExecutionContext {
     return this.useEntityIds;
   }
 
+  /**
+   * @internal
+   * Sets whether to include special columns (ROWID and ROWMODID) in requests
+   */
+  _setIncludeSpecialColumns(includeSpecialColumns: boolean): void {
+    this.includeSpecialColumns = includeSpecialColumns;
+  }
+
+  /**
+   * @internal
+   * Gets whether to include special columns (ROWID and ROWMODID) in requests
+   */
+  _getIncludeSpecialColumns(): boolean {
+    return this.includeSpecialColumns;
+  }
+
   /**
    * @internal
    * Gets the base URL for OData requests
    */
   _getBaseUrl(): string {
-    return `${this.serverUrl}${"apiKey" in this.auth ? `/otto` : ""}/fmi/odata/v4`;
+    return `${this.serverUrl}${"apiKey" in this.auth ? "/otto" : ""}/fmi/odata/v4`;
+  }
+
+  /**
+   * @internal
+   * Gets the logger instance
+   */
+  _getLogger(): InternalLogger {
+    return this.logger;
   }
 
   /**
@@ -65,13 +98,32 @@ export class FMServerConnection implements ExecutionContext {
    */
   async _makeRequest<T>(
     url: string,
-    options?: RequestInit & FFetchOptions & { useEntityIds?: boolean },
+    options?: RequestInit &
+      FFetchOptions & {
+        useEntityIds?: boolean;
+        includeSpecialColumns?: boolean;
+      },
   ): Promise<Result<T>> {
-    const baseUrl = `${this.serverUrl}${"apiKey" in this.auth ? `/otto` : ""}/fmi/odata/v4`;
+    const logger = this._getLogger();
+    const baseUrl = `${this.serverUrl}${"apiKey" in this.auth ? "/otto" : ""}/fmi/odata/v4`;
     const fullUrl = baseUrl + url;
 
     // Use per-request override if provided, otherwise use the database-level setting
     const useEntityIds = options?.useEntityIds ?? this.useEntityIds;
+    const includeSpecialColumns = options?.includeSpecialColumns ?? this.includeSpecialColumns;
+
+    // Get includeODataAnnotations from options (it's passed through from execute options)
+    // biome-ignore lint/suspicious/noExplicitAny: Type assertion for optional property access
+    const includeODataAnnotations = (options as any)?.includeODataAnnotations;
+
+    // Build Prefer header as comma-separated list when multiple preferences are set
+    const preferValues: string[] = [];
+    if (useEntityIds) {
+      preferValues.push("fmodata.entity-ids");
+    }
+    if (includeSpecialColumns) {
+      preferValues.push("fmodata.include-specialcolumns");
+    }
 
     const headers = {
       Authorization:
@@ -79,25 +131,23 @@ export class FMServerConnection implements ExecutionContext {
           ? `Bearer ${this.auth.apiKey}`
           : `Basic ${btoa(`${this.auth.username}:${this.auth.password}`)}`,
       "Content-Type": "application/json",
-      Accept: "application/json",
-      ...(useEntityIds ? { Prefer: "fmodata.entity-ids" } : {}),
+      Accept: getAcceptHeader(includeODataAnnotations),
+      ...(preferValues.length > 0 ? { Prefer: preferValues.join(", ") } : {}),
       ...(options?.headers || {}),
     };
 
+    // Prepare loggableHeaders by omitting the Authorization key
+    const { Authorization, ...loggableHeaders } = headers;
+    logger.debug("Request headers:", loggableHeaders);
+
     // TEMPORARY WORKAROUND: Hopefully this feature will be fixed in the ffetch library
     // Extract fetchHandler and headers separately, only for tests where we're overriding the fetch handler per-request
     const fetchHandler = options?.fetchHandler;
-    const {
-      headers: _headers,
-      fetchHandler: _fetchHandler,
-      ...restOptions
-    } = options || {};
+    const { headers: _headers, fetchHandler: _fetchHandler, ...restOptions } = options || {};
 
     // If fetchHandler is provided, create a temporary client with it
     // Otherwise use the existing client
-    const clientToUse = fetchHandler
-      ? createClient({ retries: 0, fetchHandler })
-      : this.fetchClient;
+    const clientToUse = fetchHandler ? createClient({ retries: 0, fetchHandler }) : this.fetchClient;
 
     try {
       const finalOptions = {
@@ -105,22 +155,16 @@ export class FMServerConnection implements ExecutionContext {
         headers,
       };
 
-      // For batch requests, use native fetch to avoid any potential serialization issues with ffetch
-      const resp = url.includes("/$batch")
-        ? await fetch(fullUrl, {
-            method: finalOptions.method,
-            headers: finalOptions.headers,
-            body: finalOptions.body,
-          })
-        : await clientToUse(fullUrl, finalOptions);
+      const resp = await clientToUse(fullUrl, finalOptions);
+      logger.debug(`${finalOptions.method ?? "GET"} ${resp.status} ${fullUrl}`);
 
       // Handle HTTP errors
       if (!resp.ok) {
         // Try to parse error body if it's JSON
-        let errorBody;
+        let errorBody: { error?: { code?: string | number; message?: string } } | undefined;
         try {
           if (resp.headers.get("content-type")?.includes("application/json")) {
-            errorBody = await resp.json();
+            errorBody = await safeJsonParse<typeof errorBody>(resp);
           }
         } catch {
           // Ignore JSON parse errors
@@ -135,33 +179,19 @@ export class FMServerConnection implements ExecutionContext {
           if (errorCode === "303" || errorCode === 303) {
             return {
               data: undefined,
-              error: new SchemaLockedError(
-                fullUrl,
-                errorMessage,
-                errorBody.error,
-              ),
+              error: new SchemaLockedError(fullUrl, errorMessage, errorBody.error),
             };
           }
 
           return {
             data: undefined,
-            error: new ODataError(
-              fullUrl,
-              errorMessage,
-              errorCode,
-              errorBody.error,
-            ),
+            error: new ODataError(fullUrl, errorMessage, String(errorCode), errorBody.error),
           };
         }
 
         return {
           data: undefined,
-          error: new HTTPError(
-            fullUrl,
-            resp.status,
-            resp.statusText,
-            errorBody,
-          ),
+          error: new HTTPError(fullUrl, resp.status, resp.statusText, errorBody),
         };
       }
 
@@ -169,15 +199,14 @@ export class FMServerConnection implements ExecutionContext {
       // FileMaker may return this with 204 No Content or 200 OK
       const affectedRows = resp.headers.get("fmodata.affected_rows");
       if (affectedRows !== null) {
-        return { data: parseInt(affectedRows, 10) as T, error: undefined };
+        return { data: Number.parseInt(affectedRows, 10) as T, error: undefined };
       }
 
       // Handle 204 No Content with no body
       if (resp.status === 204) {
         // Check for Location header (used for insert with return=minimal)
         // Use optional chaining for safety with mocks that might not have proper headers
-        const locationHeader =
-          resp.headers?.get?.("Location") || resp.headers?.get?.("location");
+        const locationHeader = resp.headers?.get?.("Location") || resp.headers?.get?.("location");
         if (locationHeader) {
           // Return the location header so InsertBuilder can extract ROWID
           return { data: { _location: locationHeader } as T, error: undefined };
@@ -187,12 +216,12 @@ export class FMServerConnection implements ExecutionContext {
 
       // Parse response
       if (resp.headers.get("content-type")?.includes("application/json")) {
-        const data = await resp.json();
+        const data = await safeJsonParse<T & { error?: { code?: string | number; message?: string } }>(resp);
 
         // Check for embedded OData errors
-        if (data.error) {
-          const errorCode = data.error.code;
-          const errorMessage = data.error.message || "Unknown OData error";
+        if (get(data, "error", null)) {
+          const errorCode = get(data, "error.code", null);
+          const errorMessage = get(data, "error.message", "Unknown OData error");
 
           // Check for schema locked error (code 303)
           if (errorCode === "303" || errorCode === 303) {
@@ -204,7 +233,7 @@ export class FMServerConnection implements ExecutionContext {
 
           return {
             data: undefined,
-            error: new ODataError(fullUrl, errorMessage, errorCode, data.error),
+            error: new ODataError(fullUrl, errorMessage, String(errorCode), data.error),
           };
         }
 
@@ -224,6 +253,11 @@ export class FMServerConnection implements ExecutionContext {
         return { data: undefined, error: err };
       }
 
+      // Handle JSON parse errors (ResponseParseError from safeJsonParse)
+      if (err instanceof ResponseParseError) {
+        return { data: undefined, error: err };
+      }
+
       // Unknown error - wrap it as NetworkError
       return {
         data: undefined,
@@ -232,16 +266,14 @@ export class FMServerConnection implements ExecutionContext {
     }
   }
 
-  database<
-    const Occurrences extends readonly TableOccurrence<any, any, any, any>[],
-  >(
+  database<IncludeSpecialColumns extends boolean = false>(
     name: string,
     config?: {
-      occurrences?: Occurrences | undefined;
       useEntityIds?: boolean;
+      includeSpecialColumns?: IncludeSpecialColumns;
     },
-  ): Database<Occurrences> {
-    return new Database(name, this, config);
+  ): Database<IncludeSpecialColumns> {
+    return new Database<IncludeSpecialColumns>(name, this, config);
   }
 
   /**
@@ -251,7 +283,7 @@ export class FMServerConnection implements ExecutionContext {
   async listDatabaseNames(): Promise<string[]> {
     const result = await this._makeRequest<{
       value?: Array<{ name: string }>;
-    }>("/");
+    }>("/$metadata", { headers: { Accept: "application/json" } });
     if (result.error) {
       throw result.error;
     }