@proofkit/fmodata 0.1.0-alpha.4 → 0.1.0-alpha.7

package/src/client/record-builder.ts

@@ -5,13 +5,16 @@ import type {
   ODataRecordMetadata,
   ODataFieldResponse,
   InferSchemaType,
+  ExecuteOptions,
 } from "../types";
 import type { TableOccurrence } from "./table-occurrence";
 import type { BaseTable } from "./base-table";
+import { transformTableName, transformResponseFields, getTableIdentifiers } from "../transform";
 import { QueryBuilder } from "./query-builder";
 import { validateSingleResponse } from "../validation";
 import { type FFetchOptions } from "@fetchkit/ffetch";
-import { z } from "zod/v4";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+// import type { z } from "zod/v4";
 
 // Helper type to extract schema from a TableOccurrence
 type ExtractSchemaFromOccurrence<O> =
@@ -68,18 +71,60 @@ export class RecordBuilder<
   private navigateRelation?: string;
   private navigateSourceTableName?: string;
 
+  private databaseUseEntityIds: boolean;
+
   constructor(config: {
     occurrence?: Occ;
     tableName: string;
     databaseName: string;
     context: ExecutionContext;
     recordId: string | number;
+    databaseUseEntityIds?: boolean;
   }) {
     this.occurrence = config.occurrence;
     this.tableName = config.tableName;
     this.databaseName = config.databaseName;
     this.context = config.context;
     this.recordId = config.recordId;
+    this.databaseUseEntityIds = config.databaseUseEntityIds ?? false;
+  }
+
+  /**
+   * 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,
+    };
+  }
+
+  /**
+   * 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();
   }
 
   getSingleField<K extends keyof T>(field: K): RecordBuilder<T, true, K, Occ> {
@@ -105,7 +150,7 @@ export class RecordBuilder<
   ): QueryBuilder<
     ExtractSchemaFromOccurrence<
       FindNavigationTarget<Occ, RelationName>
-    > extends Record<string, z.ZodType>
+    > extends Record<string, StandardSchemaV1>
       ? InferSchemaType<
           ExtractSchemaFromOccurrence<FindNavigationTarget<Occ, RelationName>>
         >
@@ -127,9 +172,14 @@ export class RecordBuilder<
       context: this.context,
     });
     // Store the navigation info - we'll use it in execute
+    // Transform relation name to FMTID if using entity IDs
+    const relationId = targetOccurrence
+      ? transformTableName(targetOccurrence)
+      : relationName;
+
     (builder as any).isNavigate = true;
     (builder as any).navigateRecordId = this.recordId;
-    (builder as any).navigateRelation = relationName;
+    (builder as any).navigateRelation = relationId;
 
     // If this RecordBuilder came from a navigated EntitySet, we need to preserve that base path
     if (
@@ -142,74 +192,91 @@ export class RecordBuilder<
       (builder as any).navigateBaseRelation = this.navigateRelation;
     } else {
       // Normal record navigation: /tableName('recordId')/relation
-      (builder as any).navigateSourceTableName = this.tableName;
+      // Transform source table name to FMTID if using entity IDs
+      const sourceTableId = this.occurrence
+        ? transformTableName(this.occurrence)
+        : this.tableName;
+      (builder as any).navigateSourceTableName = sourceTableId;
     }
 
     return builder;
   }
 
   async execute(
-    options?: RequestInit & FFetchOptions,
+    options?: RequestInit & FFetchOptions & { useEntityIds?: boolean },
   ): Promise<
     Result<IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata>
   > {
-    try {
-      let url: string;
-
-      // Build the base URL depending on whether this came from a navigated EntitySet
-      if (
-        this.isNavigateFromEntitySet &&
-        this.navigateSourceTableName &&
-        this.navigateRelation
-      ) {
-        // From navigated EntitySet: /sourceTable/relation('recordId')
-        url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;
-      } else {
-        // Normal record: /tableName('recordId')
-        url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
-      }
+    let url: string;
 
-      if (this.operation === "getSingleField" && this.operationParam) {
-        url += `/${this.operationParam}`;
-      }
+    // Build the base URL depending on whether this came from a navigated EntitySet
+    if (
+      this.isNavigateFromEntitySet &&
+      this.navigateSourceTableName &&
+      this.navigateRelation
+    ) {
+      // From navigated EntitySet: /sourceTable/relation('recordId')
+      url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;
+    } else {
+      // Normal record: /tableName('recordId') - use FMTID if configured
+      const tableId = this.getTableId(options?.useEntityIds ?? this.databaseUseEntityIds);
+      url = `/${this.databaseName}/${tableId}('${this.recordId}')`;
+    }
 
-      const response = await this.context._makeRequest(url, options);
+    if (this.operation === "getSingleField" && this.operationParam) {
+      url += `/${this.operationParam}`;
+    }
 
-      // Handle single field operation
-      if (this.operation === "getSingleField") {
-        // Single field returns a JSON object with @context and value
-        const fieldResponse = response as ODataFieldResponse<T>;
-        return { data: fieldResponse.value as any, error: undefined };
-      }
+    const mergedOptions = this.mergeExecuteOptions(options);
+    const result = await this.context._makeRequest(url, mergedOptions);
 
-      // Get schema from occurrence if available
-      const schema = this.occurrence?.baseTable?.schema;
+    if (result.error) {
+      return { data: undefined, error: result.error };
+    }
+
+    let response = result.data;
+
+    // Handle single field operation
+    if (this.operation === "getSingleField") {
+      // Single field returns a JSON object with @context and value
+      const fieldResponse = response as ODataFieldResponse<T>;
+      return { data: fieldResponse.value as any, error: undefined };
+    }
 
-      // Validate the single record response
-      const validation = await validateSingleResponse<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 = mergedOptions.useEntityIds ?? false;
+    
+    if (this.occurrence?.baseTable && shouldUseIds) {
+      response = transformResponseFields(
         response,
-        schema,
-        undefined, // No selected fields for record.get()
-        undefined, // No expand configs
-        "exact", // Expect exactly one record
+        this.occurrence.baseTable,
+        undefined, // No expand configs for simple get
       );
+    }
 
-      if (!validation.valid) {
-        return { data: undefined, error: validation.error };
-      }
+    // Get schema from occurrence if available
+    const schema = this.occurrence?.baseTable?.schema;
 
-      // Handle null response
-      if (validation.data === null) {
-        return { data: null as any, error: undefined };
-      }
+    // Validate the single record response
+    const validation = await validateSingleResponse<any>(
+      response,
+      schema,
+      undefined, // No selected fields for record.get()
+      undefined, // No expand configs
+      "exact", // Expect exactly one record
+    );
+
+    if (!validation.valid) {
+      return { data: undefined, error: validation.error };
+    }
 
-      return { data: validation.data, error: undefined };
-    } catch (error) {
-      return {
-        data: undefined,
-        error: error instanceof Error ? error : new Error(String(error)),
-      };
+    // Handle null response
+    if (validation.data === null) {
+      return { data: null as any, error: undefined };
     }
+
+    return { data: validation.data, error: undefined };
   }
 
   getRequestConfig(): { method: string; url: string; body?: any } {
@@ -224,8 +291,9 @@ export class RecordBuilder<
       // From navigated EntitySet: /sourceTable/relation('recordId')
       url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;
     } else {
-      // Normal record: /tableName('recordId')
-      url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
+      // For batch operations, use database-level setting (no per-request override available here)
+      const tableId = this.getTableId(this.databaseUseEntityIds);
+      url = `/${this.databaseName}/${tableId}('${this.recordId}')`;
     }
 
     if (this.operation === "getSingleField" && this.operationParam) {
@@ -237,4 +305,69 @@ export class RecordBuilder<
       url,
     };
   }
+
+  toRequest(baseUrl: string): Request {
+    const config = this.getRequestConfig();
+    const fullUrl = `${baseUrl}${config.url}`;
+
+    return new Request(fullUrl, {
+      method: config.method,
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+    });
+  }
+
+  async processResponse(
+    response: Response,
+    options?: ExecuteOptions,
+  ): Promise<
+    Result<IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata>
+  > {
+    const rawResponse = await response.json();
+
+    // Handle single field operation
+    if (this.operation === "getSingleField") {
+      // Single field returns a JSON object with @context and value
+      const fieldResponse = rawResponse as ODataFieldResponse<T>;
+      return { data: fieldResponse.value as any, error: undefined };
+    }
+
+    // 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 simple get
+      );
+    }
+
+    // Get schema from occurrence if available
+    const schema = this.occurrence?.baseTable?.schema;
+
+    // Validate the single record response
+    const validation = await validateSingleResponse<any>(
+      transformedResponse,
+      schema,
+      undefined, // No selected fields for record.get()
+      undefined, // No expand configs
+      "exact", // Expect exactly one record
+    );
+
+    if (!validation.valid) {
+      return { data: undefined, error: validation.error };
+    }
+
+    // Handle null response
+    if (validation.data === null) {
+      return { data: null as any, error: undefined };
+    }
+
+    return { data: validation.data, error: undefined };
+  }
 }

package/src/client/response-processor.ts

@@ -0,0 +1,103 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { BaseTable } from "./base-table";
+import type { ExecuteOptions } from "../types";
+import type { ExpandValidationConfig } from "../validation";
+import { ValidationError, ResponseStructureError } from "../errors";
+import { transformResponseFields } from "../transform";
+import { validateListResponse, validateRecord } from "../validation";
+
+// Type for raw OData responses
+export type ODataResponse<T = unknown> = T & {
+  "@odata.context"?: string;
+  "@odata.count"?: number;
+};
+
+export type ODataListResponse<T = unknown> = ODataResponse<{
+  value: T[];
+}>;
+
+export type ODataRecordResponse<T = unknown> = ODataResponse<
+  T & {
+    "@id"?: string;
+    "@editLink"?: string;
+  }
+>;
+
+/**
+ * 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
+ */
+export function applyFieldTransformation<T extends Record<string, unknown>>(
+  response: ODataResponse<T> | ODataListResponse<T>,
+  baseTable: BaseTable<Record<string, StandardSchemaV1>, any, any, any>,
+  expandConfigs?: ExpandValidationConfig[],
+): ODataResponse<T> | ODataListResponse<T> {
+  return transformResponseFields(response, baseTable, expandConfigs) as
+    | ODataResponse<T>
+    | ODataListResponse<T>;
+}
+
+/**
+ * Apply schema validation and transformation to data
+ */
+export async function applyValidation<T extends Record<string, unknown>>(
+  data: T | T[],
+  schema?: Record<string, StandardSchemaV1>,
+  selectedFields?: (keyof T)[],
+  expandConfigs?: ExpandValidationConfig[],
+): Promise<
+  | { valid: true; data: T | T[] }
+  | { valid: false; error: ValidationError | ResponseStructureError }
+> {
+  if (Array.isArray(data)) {
+    // Validate as a list
+    const validation = await validateListResponse<T>(
+      { value: data },
+      schema,
+      selectedFields as string[] | undefined,
+      expandConfigs,
+    );
+    if (!validation.valid) {
+      return { valid: false, error: validation.error };
+    }
+    return { valid: true, data: validation.data };
+  } else {
+    // Validate as a single record
+    const validation = await validateRecord<T>(
+      data,
+      schema,
+      selectedFields,
+      expandConfigs,
+    );
+    if (!validation.valid) {
+      return { valid: false, error: validation.error };
+    }
+    return { valid: true, data: validation.data };
+  }
+}
+
+/**
+ * Extract value array from OData list response, or wrap single record in array
+ */
+export function extractListValue<T>(
+  response: ODataListResponse<T> | ODataRecordResponse<T>,
+): T[] {
+  if ("value" in response && Array.isArray(response.value)) {
+    return response.value;
+  }
+  // Single record responses return the record directly
+  return [response as T];
+}

package/src/client/schema-manager.ts

@@ -0,0 +1,246 @@
+import type { FFetchOptions } from "@fetchkit/ffetch";
+import type { ExecutionContext } from "../types";
+
+type GenericField = {
+  name: string;
+  nullable?: boolean;
+  primary?: boolean;
+  unique?: boolean;
+  global?: boolean;
+  repetitions?: number;
+};
+
+type StringField = GenericField & {
+  type: "string";
+  maxLength?: number;
+  default?: "USER" | "USERNAME" | "CURRENT_USER";
+};
+
+type NumericField = GenericField & {
+  type: "numeric";
+};
+
+type DateField = GenericField & {
+  type: "date";
+  default?: "CURRENT_DATE" | "CURDATE";
+};
+
+type TimeField = GenericField & {
+  type: "time";
+  default?: "CURRENT_TIME" | "CURTIME";
+};
+
+type TimestampField = GenericField & {
+  type: "timestamp";
+  default?: "CURRENT_TIMESTAMP" | "CURTIMESTAMP";
+};
+
+type ContainerField = GenericField & {
+  type: "container";
+  externalSecurePath?: string;
+};
+
+export type Field =
+  | StringField
+  | NumericField
+  | DateField
+  | TimeField
+  | TimestampField
+  | ContainerField;
+
+export type {
+  StringField,
+  NumericField,
+  DateField,
+  TimeField,
+  TimestampField,
+  ContainerField,
+};
+
+type FileMakerField = Omit<Field, "type" | "repetitions" | "maxLength"> & {
+  type: string;
+};
+
+type TableDefinition = {
+  tableName: string;
+  fields: FileMakerField[];
+};
+
+export class SchemaManager {
+  public constructor(
+    private readonly databaseName: string,
+    private readonly context: ExecutionContext,
+  ) {}
+
+  public async createTable(
+    tableName: string,
+    fields: Field[],
+    options?: RequestInit & FFetchOptions,
+  ): Promise<TableDefinition> {
+    const result = await this.context._makeRequest<TableDefinition>(
+      `/${this.databaseName}/FileMaker_Tables`,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          tableName,
+          fields: fields.map(SchemaManager.compileFieldDefinition),
+        }),
+        ...options,
+      },
+    );
+
+    if (result.error) {
+      throw result.error;
+    }
+
+    return result.data;
+  }
+
+  public async addFields(
+    tableName: string,
+    fields: Field[],
+    options?: RequestInit & FFetchOptions,
+  ): Promise<TableDefinition> {
+    const result = await this.context._makeRequest<TableDefinition>(
+      `/${this.databaseName}/FileMaker_Tables/${tableName}`,
+      {
+        method: "PATCH",
+        body: JSON.stringify({
+          fields: fields.map(SchemaManager.compileFieldDefinition),
+        }),
+        ...options,
+      },
+    );
+
+    if (result.error) {
+      throw result.error;
+    }
+
+    return result.data;
+  }
+
+  public async deleteTable(
+    tableName: string,
+    options?: RequestInit & FFetchOptions,
+  ): Promise<void> {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Tables/${tableName}`,
+      { method: "DELETE", ...options },
+    );
+
+    if (result.error) {
+      throw result.error;
+    }
+  }
+
+  public async deleteField(
+    tableName: string,
+    fieldName: string,
+    options?: RequestInit & FFetchOptions,
+  ): Promise<void> {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Tables/${tableName}/${fieldName}`,
+      {
+        method: "DELETE",
+        ...options,
+      },
+    );
+
+    if (result.error) {
+      throw result.error;
+    }
+  }
+
+  public async createIndex(
+    tableName: string,
+    fieldName: string,
+    options?: RequestInit & FFetchOptions,
+  ): Promise<{ indexName: string }> {
+    const result = await this.context._makeRequest<{ indexName: string }>(
+      `/${this.databaseName}/FileMaker_Indexes/${tableName}`,
+      {
+        method: "POST",
+        body: JSON.stringify({ indexName: fieldName }),
+        ...options,
+      },
+    );
+
+    if (result.error) {
+      throw result.error;
+    }
+
+    return result.data;
+  }
+
+  public async deleteIndex(
+    tableName: string,
+    fieldName: string,
+    options?: RequestInit & FFetchOptions,
+  ): Promise<void> {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Indexes/${tableName}/${fieldName}`,
+      {
+        method: "DELETE",
+        ...options,
+      },
+    );
+
+    if (result.error) {
+      throw result.error;
+    }
+  }
+
+  private static compileFieldDefinition(field: Field): FileMakerField {
+    let type: string = field.type;
+    const repetitions = field.repetitions;
+
+    // Handle string fields - convert to varchar and add maxLength if present
+    if (field.type === "string") {
+      type = "varchar";
+      const stringField = field as StringField;
+      if (stringField.maxLength !== undefined) {
+        type += `(${stringField.maxLength})`;
+      }
+    }
+
+    // Add repetitions suffix if present
+    if (repetitions !== undefined) {
+      type += `[${repetitions}]`;
+    }
+
+    // Build the result object, excluding type, maxLength, and repetitions
+    const result: any = {
+      name: field.name,
+      type,
+    };
+
+    // Add optional properties that FileMaker expects
+    if (field.nullable !== undefined) result.nullable = field.nullable;
+    if (field.primary !== undefined) result.primary = field.primary;
+    if (field.unique !== undefined) result.unique = field.unique;
+    if (field.global !== undefined) result.global = field.global;
+
+    // Add type-specific properties
+    if (field.type === "string") {
+      const stringField = field as StringField;
+      if (stringField.default !== undefined)
+        result.default = stringField.default;
+    } else if (field.type === "date") {
+      const dateField = field as DateField;
+      if (dateField.default !== undefined) result.default = dateField.default;
+    } else if (field.type === "time") {
+      const timeField = field as TimeField;
+      if (timeField.default !== undefined) result.default = timeField.default;
+    } else if (field.type === "timestamp") {
+      const timestampField = field as TimestampField;
+      if (timestampField.default !== undefined)
+        result.default = timestampField.default;
+    } else if (field.type === "container") {
+      const containerField = field as ContainerField;
+      if (containerField.externalSecurePath !== undefined)
+        result.externalSecurePath = containerField.externalSecurePath;
+    }
+
+    return result as FileMakerField;
+  }
+}