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

package/src/client/webhook-builder.ts

@@ -0,0 +1,265 @@
+import { type FMTable, getTableName } from "../orm";
+import { type Column, isColumn } from "../orm/column";
+import { FilterExpression } from "../orm/operators";
+import type { ExecuteMethodOptions, ExecutionContext } from "../types";
+import { formatSelectFields } from "./builders/select-utils";
+
+export interface Webhook<TableName = string> {
+  webhook: string;
+  headers?: Record<string, string>;
+  tableName: TableName;
+  notifySchemaChanges?: boolean;
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+  select?: string | Column<any, any, any>[];
+  filter?: string | FilterExpression;
+}
+
+/**
+ * Webhook information returned by the API
+ */
+export interface WebhookInfo {
+  webHookID: number;
+  tableName: string;
+  url: string;
+  headers?: Record<string, string>;
+  notifySchemaChanges: boolean;
+  select: string;
+  filter: string;
+  pendingOperations: unknown[];
+}
+
+/**
+ * Response from listing all webhooks
+ */
+export interface WebhookListResponse {
+  Status: string;
+  WebHook: WebhookInfo[];
+}
+
+/**
+ * Response from adding a webhook
+ */
+export interface WebhookAddResponse {
+  webHookResult: {
+    webHookID: number;
+  };
+}
+
+export class WebhookManager {
+  private readonly databaseName: string;
+  private readonly context: ExecutionContext;
+
+  constructor(databaseName: string, context: ExecutionContext) {
+    this.databaseName = databaseName;
+    this.context = context;
+  }
+
+  /**
+   * Adds a new webhook to the database.
+   * @param webhook - The webhook configuration object
+   * @param webhook.webhook - The webhook URL to call
+   * @param webhook.tableName - The FMTable instance for the table to monitor
+   * @param webhook.headers - Optional custom headers to include in webhook requests
+   * @param webhook.notifySchemaChanges - Whether to notify on schema changes
+   * @param webhook.select - Optional field selection (string or array of Column references)
+   * @param webhook.filter - Optional filter (string or FilterExpression)
+   * @returns Promise resolving to the created webhook data with ID
+   * @example
+   * ```ts
+   * const result = await db.webhook.add({
+   *   webhook: "https://example.com/webhook",
+   *   tableName: contactsTable,
+   *   headers: { "X-Custom-Header": "value" },
+   * });
+   * // result.webHookResult.webHookID contains the new webhook ID
+   * ```
+   * @example
+   * ```ts
+   * // Using filter expressions and column arrays (same DX as query builder)
+   * const result = await db.webhook.add({
+   *   webhook: "https://example.com/webhook",
+   *   tableName: contacts,
+   *   filter: eq(contacts.name, "John"),
+   *   select: [contacts.name, contacts.PrimaryKey],
+   * });
+   * ```
+   */
+  async add(webhook: Webhook<FMTable>, options?: ExecuteMethodOptions): Promise<WebhookAddResponse> {
+    // Extract the string table name from the FMTable instance
+    const tableName = getTableName(webhook.tableName);
+
+    // Get useEntityIds setting (check options first, then context, default to false)
+    const useEntityIds = options?.useEntityIds ?? this.context._getUseEntityIds?.() ?? false;
+
+    // Transform filter if it's a FilterExpression
+    let filter: string | undefined;
+    if (webhook.filter !== undefined) {
+      if (webhook.filter instanceof FilterExpression) {
+        filter = webhook.filter.toODataFilter(useEntityIds);
+      } else {
+        filter = webhook.filter;
+      }
+    }
+
+    // Transform select if it's an array of Columns
+    let select: string | undefined;
+    if (webhook.select !== undefined) {
+      if (Array.isArray(webhook.select)) {
+        // Extract field identifiers from columns or use strings as-is
+        const fieldNames = webhook.select.map((item) => {
+          if (isColumn(item)) {
+            return item.getFieldIdentifier(useEntityIds);
+          }
+          return String(item);
+        });
+        // Use formatSelectFields to properly format the select string
+        select = formatSelectFields(fieldNames, webhook.tableName, useEntityIds);
+      } else {
+        // Already a string, use as-is
+        select = webhook.select;
+      }
+    }
+
+    // Create request body with string table name and transformed filter/select
+    const requestBody: {
+      webhook: string;
+      headers?: Record<string, string>;
+      tableName: string;
+      notifySchemaChanges?: boolean;
+      select?: string;
+      filter?: string;
+    } = {
+      webhook: webhook.webhook,
+      tableName,
+    };
+
+    if (webhook.headers !== undefined) {
+      requestBody.headers = webhook.headers;
+    }
+    if (webhook.notifySchemaChanges !== undefined) {
+      requestBody.notifySchemaChanges = webhook.notifySchemaChanges;
+    }
+    if (select !== undefined) {
+      requestBody.select = select;
+    }
+    if (filter !== undefined) {
+      requestBody.filter = filter;
+    }
+
+    const result = await this.context._makeRequest<WebhookAddResponse>(`/${this.databaseName}/Webhook.Add`, {
+      method: "POST",
+      body: JSON.stringify(requestBody),
+      ...options,
+    });
+
+    if (result.error) {
+      throw result.error;
+    }
+
+    return result.data;
+  }
+
+  /**
+   * Deletes a webhook by ID.
+   * @param webhookId - The ID of the webhook to delete
+   * @returns Promise that resolves when the webhook is deleted
+   * @example
+   * ```ts
+   * await db.webhook.remove(1);
+   * ```
+   */
+  async remove(webhookId: number, options?: ExecuteMethodOptions): Promise<void> {
+    const result = await this.context._makeRequest(`/${this.databaseName}/Webhook.Delete(${webhookId})`, {
+      method: "POST",
+      ...options,
+    });
+
+    if (result.error) {
+      throw result.error;
+    }
+  }
+
+  /**
+   * Gets a webhook by ID.
+   * @param webhookId - The ID of the webhook to retrieve
+   * @returns Promise resolving to the webhook data
+   * @example
+   * ```ts
+   * const webhook = await db.webhook.get(1);
+   * // webhook.webHookID, webhook.tableName, webhook.url, etc.
+   * ```
+   */
+  async get(webhookId: number, options?: ExecuteMethodOptions): Promise<WebhookInfo> {
+    const result = await this.context._makeRequest<WebhookInfo>(
+      `/${this.databaseName}/Webhook.Get(${webhookId})`,
+      options,
+    );
+
+    if (result.error) {
+      throw result.error;
+    }
+
+    return result.data;
+  }
+
+  /**
+   * Lists all webhooks.
+   * @returns Promise resolving to webhook list response with status and webhooks array
+   * @example
+   * ```ts
+   * const result = await db.webhook.list();
+   * // result.Status contains the status
+   * // result.WebHook contains the array of webhooks
+   * ```
+   */
+  async list(options?: ExecuteMethodOptions): Promise<WebhookListResponse> {
+    const result = await this.context._makeRequest<WebhookListResponse>(
+      `/${this.databaseName}/Webhook.GetAll`,
+      options,
+    );
+
+    if (result.error) {
+      throw result.error;
+    }
+
+    return result.data;
+  }
+
+  /**
+   * Invokes a webhook by ID, optionally for specific row IDs.
+   * @param webhookId - The ID of the webhook to invoke
+   * @param options - Optional configuration
+   * @param options.rowIDs - Array of row IDs to trigger the webhook for
+   * @returns Promise resolving to the invocation result (type unknown until API behavior is confirmed)
+   * @example
+   * ```ts
+   * // Invoke for all rows
+   * await db.webhook.invoke(1);
+   *
+   * // Invoke for specific rows
+   * await db.webhook.invoke(1, { rowIDs: [63, 61] });
+   * ```
+   */
+  async invoke(
+    webhookId: number,
+    options?: { rowIDs?: number[] },
+    executeOptions?: ExecuteMethodOptions,
+  ): Promise<unknown> {
+    const body: { rowIDs?: number[] } = {};
+    if (options?.rowIDs !== undefined) {
+      body.rowIDs = options.rowIDs;
+    }
+
+    const result = await this.context._makeRequest<unknown>(`/${this.databaseName}/Webhook.Invoke(${webhookId})`, {
+      method: "POST",
+      body: Object.keys(body).length > 0 ? JSON.stringify(body) : undefined,
+      ...executeOptions,
+    });
+
+    if (result.error) {
+      throw result.error;
+    }
+
+    return result.data;
+  }
+}

package/src/errors.ts

@@ -23,8 +23,10 @@ export class HTTPError extends FMODataError {
   readonly url: string;
   readonly status: number;
   readonly statusText: string;
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic response type from OData API
   readonly response?: any;
 
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic response type from OData API
   constructor(url: string, status: number, statusText: string, response?: any) {
     super(`HTTP ${status} ${statusText} for ${url}`);
     this.url = url;
@@ -63,8 +65,10 @@ export class ODataError extends FMODataError {
   readonly kind = "ODataError" as const;
   readonly url: string;
   readonly code?: string;
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic error details from OData API
   readonly details?: any;
 
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic error details from OData API
   constructor(url: string, message: string, code?: string, details?: any) {
     super(`OData error: ${message}`);
     this.url = url;
@@ -77,8 +81,10 @@ export class SchemaLockedError extends FMODataError {
   readonly kind = "SchemaLockedError" as const;
   readonly url: string;
   readonly code: string;
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic error details from OData API
   readonly details?: any;
 
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic error details from OData API
   constructor(url: string, message: string, details?: any) {
     super(`OData error: ${message}`);
     this.url = url;
@@ -106,10 +112,7 @@ export class ValidationError extends FMODataError {
       cause?: Error["cause"];
     },
   ) {
-    super(
-      message,
-      options?.cause !== undefined ? { cause: options.cause } : undefined,
-    );
+    super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
     this.field = options?.field;
     this.issues = issues;
     this.value = options?.value;
@@ -119,8 +122,10 @@ export class ValidationError extends FMODataError {
 export class ResponseStructureError extends FMODataError {
   readonly kind = "ResponseStructureError" as const;
   readonly expected: string;
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic response type from OData API
   readonly received: any;
 
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic response type from OData API
   constructor(expected: string, received: any) {
     super(`Invalid response structure: expected ${expected}`);
     this.expected = expected;
@@ -151,6 +156,30 @@ 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;
+  }
+}
+
+export class BatchTruncatedError extends FMODataError {
+  readonly kind = "BatchTruncatedError" as const;
+  readonly operationIndex: number;
+  readonly failedAtIndex: number;
+
+  constructor(operationIndex: number, failedAtIndex: number) {
+    super(`Operation ${operationIndex} was not executed because operation ${failedAtIndex} failed`);
+    this.operationIndex = operationIndex;
+    this.failedAtIndex = failedAtIndex;
+  }
+}
+
 // ============================================
 // Type Guards
 // ============================================
@@ -167,24 +196,26 @@ export function isODataError(error: unknown): error is ODataError {
   return error instanceof ODataError;
 }
 
-export function isSchemaLockedError(
-  error: unknown,
-): error is SchemaLockedError {
+export function isSchemaLockedError(error: unknown): error is SchemaLockedError {
   return error instanceof SchemaLockedError;
 }
 
-export function isResponseStructureError(
-  error: unknown,
-): error is ResponseStructureError {
+export function isResponseStructureError(error: unknown): error is ResponseStructureError {
   return error instanceof ResponseStructureError;
 }
 
-export function isRecordCountMismatchError(
-  error: unknown,
-): error is RecordCountMismatchError {
+export function isRecordCountMismatchError(error: unknown): error is RecordCountMismatchError {
   return error instanceof RecordCountMismatchError;
 }
 
+export function isResponseParseError(error: unknown): error is ResponseParseError {
+  return error instanceof ResponseParseError;
+}
+
+export function isBatchTruncatedError(error: unknown): error is BatchTruncatedError {
+  return error instanceof BatchTruncatedError;
+}
+
 export function isFMODataError(error: unknown): error is FMODataError {
   return error instanceof FMODataError;
 }
@@ -195,11 +226,11 @@ export function isFMODataError(error: unknown): error is FMODataError {
 
 // Re-export ffetch errors (they'll be imported from @fetchkit/ffetch)
 export type {
-  TimeoutError,
   AbortError,
+  CircuitOpenError,
   NetworkError,
   RetryLimitError,
-  CircuitOpenError,
+  TimeoutError,
 } from "@fetchkit/ffetch";
 
 export type FMODataErrorType =
@@ -214,4 +245,6 @@ export type FMODataErrorType =
   | ValidationError
   | ResponseStructureError
   | RecordCountMismatchError
-  | InvalidLocationHeaderError;
+  | InvalidLocationHeaderError
+  | ResponseParseError
+  | BatchTruncatedError;

package/src/index.ts

@@ -1,74 +1,119 @@
 // Barrel file - exports all public API from the client folder
-export { BaseTable, defineBaseTable } from "./client/base-table";
+/** biome-ignore-all lint/performance/noBarrelFile: Re-exporting all public API from the client folder */
+
+export type { FFetchOptions } from "@fetchkit/ffetch";
+// Re-export ffetch errors and types
 export {
-  TableOccurrence,
-  createTableOccurrence,
-  defineTableOccurrence,
-} from "./client/table-occurrence";
-export { FMServerConnection } from "./client/filemaker-odata";
+  AbortError,
+  CircuitOpenError,
+  NetworkError,
+  RetryLimitError,
+  TimeoutError,
+} from "@fetchkit/ffetch";
 
-// Type-only exports for TypeScript declaration file portability
-// Users get these instances from the builder pattern, not by direct instantiation
+// Type-only exports - for type annotations only, not direct instantiation
 export type { Database } from "./client/database";
 export type { EntitySet } from "./client/entity-set";
+// Main API - use these functions to create tables and occurrences
+export { FMServerConnection } from "./client/filemaker-odata";
 export type {
-  SchemaManager,
+  ContainerField,
+  DateField,
   Field,
-  StringField,
   NumericField,
-  DateField,
+  SchemaManager,
+  StringField,
   TimeField,
   TimestampField,
-  ContainerField,
 } from "./client/schema-manager";
-
-// Utility types for type annotations
-export type {
-  Result,
-  InferSchemaType,
-  InsertData,
-  UpdateData,
-  ODataRecordMetadata,
-  Metadata,
-} from "./types";
-
-// Filter types
 export type {
-  Filter,
-  TypedFilter,
-  FieldFilter,
-  StringOperators,
-  NumberOperators,
-  BooleanOperators,
-  DateOperators,
-  LogicalFilter,
-} from "./filter-types";
-
-// Re-export ffetch errors
-export {
-  TimeoutError,
-  AbortError,
-  NetworkError,
-  RetryLimitError,
-  CircuitOpenError,
-} from "@fetchkit/ffetch";
-
+  Webhook,
+  WebhookAddResponse,
+  WebhookInfo,
+  WebhookListResponse,
+} from "./client/webhook-builder";
+export type { FMODataErrorType } from "./errors";
 // Export our errors
 export {
+  BatchTruncatedError,
   FMODataError,
   HTTPError,
-  ODataError,
-  SchemaLockedError,
-  ValidationError,
-  ResponseStructureError,
-  RecordCountMismatchError,
+  isBatchTruncatedError,
+  isFMODataError,
   isHTTPError,
-  isValidationError,
   isODataError,
-  isSchemaLockedError,
-  isResponseStructureError,
   isRecordCountMismatchError,
-  isFMODataError,
+  isResponseParseError,
+  isResponseStructureError,
+  isSchemaLockedError,
+  isValidationError,
+  ODataError,
+  RecordCountMismatchError,
+  ResponseParseError,
+  ResponseStructureError,
+  SchemaLockedError,
+  ValidationError,
 } from "./errors";
-
-export type { FMODataErrorType } from "./errors";
+export type { Logger } from "./logger";
+// NEW ORM API - Drizzle-inspired field builders and operators
+export {
+  and,
+  asc,
+  // Column references
+  type Column,
+  calcField,
+  containerField,
+  contains,
+  dateField,
+  desc,
+  endsWith,
+  eq,
+  type FieldBuilder,
+  // Filter operators
+  type FilterExpression,
+  FMTable,
+  type FMTableWithColumns as TableOccurrenceResult,
+  // Table definition
+  fmTableOccurrence,
+  // Table helper functions
+  // getTableFields,
+  // getDefaultSelect,
+  // getBaseTableConfig,
+  // getFieldId,
+  // getFieldName,
+  // getTableId,
+  getTableColumns,
+  gt,
+  gte,
+  type InferTableSchema,
+  inArray,
+  isColumn,
+  isNotNull,
+  isNull,
+  lt,
+  lte,
+  ne,
+  not,
+  notInArray,
+  numberField,
+  // OrderBy operators
+  type OrderByExpression,
+  or,
+  startsWith,
+  // Field builders
+  textField,
+  timeField,
+  timestampField,
+} from "./orm/index";
+// Utility types for type annotations
+export type {
+  BatchItemResult,
+  BatchResult,
+  ExecuteMethodOptions,
+  ExecuteOptions,
+  FetchHandler,
+  InferSchemaType,
+  Metadata,
+  ODataRecordMetadata,
+  Result,
+} from "./types";

package/src/logger.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import type { LogLevel } from "./logger";
+import { shouldPublishLog } from "./logger";
+
+describe("shouldPublishLog", () => {
+  const testCases: {
+    currentLogLevel: LogLevel;
+    logLevel: LogLevel;
+    expected: boolean;
+  }[] = [
+    { currentLogLevel: "debug", logLevel: "debug", expected: true },
+    { currentLogLevel: "debug", logLevel: "info", expected: true },
+    { currentLogLevel: "debug", logLevel: "warn", expected: true },
+    { currentLogLevel: "debug", logLevel: "error", expected: true },
+    { currentLogLevel: "info", logLevel: "debug", expected: false },
+    { currentLogLevel: "info", logLevel: "info", expected: true },
+    { currentLogLevel: "info", logLevel: "warn", expected: true },
+    { currentLogLevel: "info", logLevel: "error", expected: true },
+    { currentLogLevel: "warn", logLevel: "debug", expected: false },
+    { currentLogLevel: "warn", logLevel: "info", expected: false },
+    { currentLogLevel: "warn", logLevel: "warn", expected: true },
+    { currentLogLevel: "warn", logLevel: "error", expected: true },
+    { currentLogLevel: "error", logLevel: "debug", expected: false },
+    { currentLogLevel: "error", logLevel: "info", expected: false },
+    { currentLogLevel: "error", logLevel: "warn", expected: false },
+    { currentLogLevel: "error", logLevel: "error", expected: true },
+  ];
+
+  for (const { currentLogLevel, logLevel, expected } of testCases) {
+    it(`should return "${expected}" when currentLogLevel is "${currentLogLevel}" and logLevel is "${logLevel}"`, () => {
+      expect(shouldPublishLog(currentLogLevel, logLevel)).toBe(expected);
+    });
+  }
+});