@proofkit/fmodata 0.1.0-alpha.1 → 0.1.0-alpha.10

package/src/client/insert-builder.ts

@@ -4,21 +4,41 @@ import type {
   Result,
   ODataRecordMetadata,
   InferSchemaType,
+  ExecuteOptions,
+  ConditionallyWithODataAnnotations,
 } from "../types";
 import type { TableOccurrence } from "./table-occurrence";
 import { validateSingleResponse } from "../validation";
 import { type FFetchOptions } from "@fetchkit/ffetch";
+import {
+  transformFieldNamesToIds,
+  transformTableName,
+  transformResponseFields,
+  getTableIdentifiers,
+} from "../transform";
+import { InvalidLocationHeaderError } from "../errors";
+
+export type InsertOptions = {
+  return?: "minimal" | "representation";
+};
 
 export class InsertBuilder<
   T extends Record<string, any>,
   Occ extends TableOccurrence<any, any, any, any> | undefined = undefined,
-> implements ExecutableBuilder<T & ODataRecordMetadata>
+  ReturnPreference extends "minimal" | "representation" = "representation",
+> implements
+    ExecutableBuilder<
+      ReturnPreference extends "minimal" ? { ROWID: number } : T
+    >
 {
   private occurrence?: Occ;
   private tableName: string;
   private databaseName: string;
   private context: ExecutionContext;
   private data: Partial<T>;
+  private returnPreference: ReturnPreference;
+
+  private databaseUseEntityIds: boolean;
 
   constructor(config: {
     occurrence?: Occ;
@@ -26,68 +46,358 @@ export class InsertBuilder<
     databaseName: string;
     context: ExecutionContext;
     data: Partial<T>;
+    returnPreference?: ReturnPreference;
+    databaseUseEntityIds?: boolean;
   }) {
     this.occurrence = config.occurrence;
     this.tableName = config.tableName;
     this.databaseName = config.databaseName;
     this.context = config.context;
     this.data = config.data;
+    this.returnPreference = (config.returnPreference ||
+      "representation") as ReturnPreference;
+    this.databaseUseEntityIds = config.databaseUseEntityIds ?? false;
   }
 
-  async execute(
-    options?: RequestInit & FFetchOptions,
-  ): Promise<Result<T & ODataRecordMetadata>> {
-    try {
-      const url = `/${this.databaseName}/${this.tableName}`;
-
-      // Make POST request with JSON body
-      const response = await this.context._makeRequest(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify(this.data),
-        ...options,
-      });
-
-      // Get schema from occurrence if available
-      const schema = this.occurrence?.baseTable?.schema;
-
-      // Validate the response (FileMaker returns the created record)
-      const validation = await validateSingleResponse<T>(
-        response,
-        schema,
-        undefined, // No selected fields for insert
-        undefined, // No expand configs
-        "exact", // Expect exactly one record
+  /**
+   * Helper to merge database-level useEntityIds with per-request options
+   */
+  private mergeExecuteOptions(
+    options?: RequestInit & FFetchOptions & ExecuteOptions,
+  ): RequestInit & FFetchOptions & { useEntityIds?: boolean } {
+    // If useEntityIds is not set in options, use the database-level setting
+    return {
+      ...options,
+      useEntityIds: options?.useEntityIds ?? this.databaseUseEntityIds,
+    };
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * Parse ROWID from Location header
+   * Expected formats:
+   * - contacts(ROWID=4583)
+   * - contacts('some-uuid')
+   */
+  private parseLocationHeader(locationHeader: string | undefined): number {
+    if (!locationHeader) {
+      throw new InvalidLocationHeaderError(
+        "Location header is required but was not provided",
       );
+    }
+
+    // Try to match ROWID=number pattern
+    const rowidMatch = locationHeader.match(/ROWID=(\d+)/);
+    if (rowidMatch && rowidMatch[1]) {
+      return parseInt(rowidMatch[1], 10);
+    }
 
-      if (!validation.valid) {
-        return { data: undefined, error: validation.error };
+    // Try to extract value from parentheses and parse as number
+    const parenMatch = locationHeader.match(/\(['"]?([^'"]+)['"]?\)/);
+    if (parenMatch && parenMatch[1]) {
+      const value = parenMatch[1];
+      const numValue = parseInt(value, 10);
+      if (!isNaN(numValue)) {
+        return numValue;
       }
+    }
 
-      // Handle null response (shouldn't happen for insert, but handle it)
-      if (validation.data === null) {
-        return {
-          data: undefined,
-          error: new Error("Insert operation returned null response"),
-        };
+    throw new InvalidLocationHeaderError(
+      `Could not extract ROWID from Location header: ${locationHeader}`,
+      locationHeader,
+    );
+  }
+
+  /**
+   * Gets the table ID (FMTID) if using entity IDs, otherwise returns the table name
+   * @param useEntityIds - Optional override for entity ID usage
+   */
+  private getTableId(useEntityIds?: boolean): string {
+    if (!this.occurrence) {
+      return this.tableName;
+    }
+
+    const contextDefault = this.context._getUseEntityIds?.() ?? false;
+    const shouldUseIds = useEntityIds ?? contextDefault;
+
+    if (shouldUseIds) {
+      const identifiers = getTableIdentifiers(this.occurrence);
+      if (!identifiers.id) {
+        throw new Error(
+          `useEntityIds is true but TableOccurrence "${identifiers.name}" does not have an fmtId defined`
+        );
+      }
+      return identifiers.id;
+    }
+
+    return this.occurrence.getTableName();
+  }
+
+  async execute<EO extends ExecuteOptions>(
+    options?: RequestInit & FFetchOptions & EO,
+  ): Promise<
+    Result<
+      ReturnPreference extends "minimal"
+        ? { ROWID: number }
+        : ConditionallyWithODataAnnotations<
+            T,
+            EO["includeODataAnnotations"] extends true ? true : false
+          >
+    >
+  > {
+    // Merge database-level useEntityIds with per-request options
+    const mergedOptions = this.mergeExecuteOptions(options);
+    
+    // Get table identifier with override support
+    const tableId = this.getTableId(mergedOptions.useEntityIds);
+    const url = `/${this.databaseName}/${tableId}`;
+
+    // Transform field names to FMFIDs if using entity IDs
+    // Only transform if useEntityIds resolves to true (respects per-request override)
+    const shouldUseIds = mergedOptions.useEntityIds ?? false;
+    
+    const transformedData = this.occurrence?.baseTable && shouldUseIds
+      ? transformFieldNamesToIds(this.data, this.occurrence.baseTable)
+      : this.data;
+
+    // Set Prefer header based on return preference
+    const preferHeader =
+      this.returnPreference === "minimal"
+        ? "return=minimal"
+        : "return=representation";
+
+    // Make POST request with JSON body
+    const result = await this.context._makeRequest<any>(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Prefer: preferHeader,
+        ...((mergedOptions as any)?.headers || {}),
+      },
+      body: JSON.stringify(transformedData),
+      ...mergedOptions,
+    });
+
+    if (result.error) {
+      return { data: undefined, error: result.error };
+    }
+
+    // Handle return=minimal case
+    if (this.returnPreference === "minimal") {
+      // The response should be empty (204 No Content)
+      // _makeRequest will return { _location: string } when there's a Location header
+      const responseData = result.data as any;
+
+      if (!responseData || !responseData._location) {
+        throw new InvalidLocationHeaderError(
+          "Location header is required when using return=minimal but was not found in response",
+        );
       }
 
-      return { data: validation.data, error: undefined };
-    } catch (error) {
+      const rowid = this.parseLocationHeader(responseData._location);
+      return { data: { ROWID: rowid } as any, error: undefined };
+    }
+
+    let response = result.data;
+
+    // Transform response field IDs back to names if using entity IDs
+    // Only transform if useEntityIds resolves to true (respects per-request override)
+    if (this.occurrence?.baseTable && shouldUseIds) {
+      response = transformResponseFields(
+        response,
+        this.occurrence.baseTable,
+        undefined, // No expand configs for insert
+      );
+    }
+
+    // Get schema from occurrence if available
+    const schema = this.occurrence?.baseTable?.schema;
+
+    // Validate the response (FileMaker returns the created record)
+    const validation = await validateSingleResponse<T>(
+      response,
+      schema,
+      undefined, // No selected fields for insert
+      undefined, // No expand configs
+      "exact", // Expect exactly one record
+    );
+
+    if (!validation.valid) {
+      return { data: undefined, error: validation.error };
+    }
+
+    // Handle null response (shouldn't happen for insert, but handle it)
+    if (validation.data === null) {
       return {
         data: undefined,
-        error: error instanceof Error ? error : new Error(String(error)),
+        error: new Error("Insert operation returned null response"),
       };
     }
+
+    // Strip OData annotations unless explicitly requested
+    const finalData = this.stripODataAnnotationsIfNeeded(
+      validation.data,
+      options,
+    );
+
+    return { data: finalData as any, error: undefined };
   }
 
   getRequestConfig(): { method: string; url: string; body?: any } {
+    // For batch operations, use database-level setting (no per-request override available here)
+    const tableId = this.getTableId(this.databaseUseEntityIds);
+
+    // Transform field names to FMFIDs if using entity IDs
+    const transformedData = this.occurrence?.baseTable && this.databaseUseEntityIds
+      ? transformFieldNamesToIds(this.data, this.occurrence.baseTable)
+      : this.data;
+
     return {
       method: "POST",
-      url: `/${this.databaseName}/${this.tableName}`,
-      body: JSON.stringify(this.data),
+      url: `/${this.databaseName}/${tableId}`,
+      body: JSON.stringify(transformedData),
     };
   }
+
+  toRequest(baseUrl: string): Request {
+    const config = this.getRequestConfig();
+    const fullUrl = `${baseUrl}${config.url}`;
+
+    // Set Prefer header based on return preference
+    const preferHeader =
+      this.returnPreference === "minimal"
+        ? "return=minimal"
+        : "return=representation";
+
+    return new Request(fullUrl, {
+      method: config.method,
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        Prefer: preferHeader,
+      },
+      body: config.body,
+    });
+  }
+
+  async processResponse(
+    response: Response,
+    options?: ExecuteOptions,
+  ): Promise<
+    Result<ReturnPreference extends "minimal" ? { ROWID: number } : T>
+  > {
+    // Handle 204 No Content (common in batch/changeset operations)
+    // FileMaker uses return=minimal for changeset operations regardless of Prefer header
+    if (response.status === 204) {
+      // Check for Location header (for return=minimal)
+      if (this.returnPreference === "minimal") {
+        const locationHeader =
+          response.headers.get("Location") || response.headers.get("location");
+        if (locationHeader) {
+          const rowid = this.parseLocationHeader(locationHeader);
+          return { data: { ROWID: rowid } as any, error: undefined };
+        }
+        throw new InvalidLocationHeaderError(
+          "Location header is required when using return=minimal but was not found in response",
+        );
+      }
+
+      // For 204 responses without return=minimal, FileMaker doesn't return the created entity
+      // This is valid OData behavior for changeset operations
+      // We return a success indicator but no actual data
+      return {
+        data: {} as any,
+        error: undefined,
+      };
+    }
+
+    // If we expected return=minimal but got a body, that's unexpected
+    if (this.returnPreference === "minimal") {
+      throw new InvalidLocationHeaderError(
+        "Expected 204 No Content for return=minimal, but received response with body",
+      );
+    }
+
+    let rawResponse;
+    try {
+      rawResponse = await response.json();
+    } catch (err) {
+      // If parsing fails with 204, handle it gracefully
+      if (response.status === 204) {
+        return {
+          data: {} as any,
+          error: undefined,
+        };
+      }
+      return {
+        data: undefined,
+        error: {
+          name: "ResponseParseError",
+          message: `Failed to parse response JSON: ${err instanceof Error ? err.message : "Unknown error"}`,
+          timestamp: new Date(),
+        } as any,
+      };
+    }
+
+    // Transform response field IDs back to names if using entity IDs
+    // Only transform if useEntityIds resolves to true (respects per-request override)
+    const shouldUseIds = options?.useEntityIds ?? this.databaseUseEntityIds;
+    
+    let transformedResponse = rawResponse;
+    if (this.occurrence?.baseTable && shouldUseIds) {
+      transformedResponse = transformResponseFields(
+        rawResponse,
+        this.occurrence.baseTable,
+        undefined, // No expand configs for insert
+      );
+    }
+
+    // Get schema from occurrence if available
+    const schema = this.occurrence?.baseTable?.schema;
+
+    // Validate the response (FileMaker returns the created record)
+    const validation = await validateSingleResponse<T>(
+      transformedResponse,
+      schema,
+      undefined, // No selected fields for insert
+      undefined, // No expand configs
+      "exact", // Expect exactly one record
+    );
+
+    if (!validation.valid) {
+      return { data: undefined, error: validation.error };
+    }
+
+    // Handle null response (shouldn't happen for insert, but handle it)
+    if (validation.data === null) {
+      return {
+        data: undefined,
+        error: new Error("Insert operation returned null response"),
+      };
+    }
+
+    // Strip OData annotations unless explicitly requested
+    const finalData = this.stripODataAnnotationsIfNeeded(
+      validation.data,
+      options,
+    );
+
+    return { data: finalData as any, error: undefined };
+  }
 }