@proofkit/fmodata 0.1.0-alpha.2 → 0.1.0-alpha.20

package/src/client/response-processor.ts

@@ -0,0 +1,89 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { FMTable } from "../orm/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;
+  }
+>;
+
+/**
+ * Transform field IDs back to names using the table configuration
+ */
+export function applyFieldTransformation<T extends Record<string, unknown>>(
+  response: ODataResponse<T> | ODataListResponse<T>,
+  table: FMTable<any, any>,
+  expandConfigs?: ExpandValidationConfig[],
+): ODataResponse<T> | ODataListResponse<T> {
+  return transformResponseFields(response, table, 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/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/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;
+  }
+}