/**
 * TypeScript definitions for the FileMaker WebViewer JavaScript API
 *
 * These bindings cover the `FileMaker` global object injected into web viewers
 * by Claris FileMaker Pro / WebDirect (FileMaker 19+).
 *
 * @see https://help.claris.com/en/pro-help/content/scripting-javascript-in-web-viewers.html
 */

// ---------------------------------------------------------------------------
// Core FileMaker global namespace
// ---------------------------------------------------------------------------

/**
 * The `FileMaker` object is automatically injected into every web viewer's
 * JavaScript context by the FileMaker runtime.  It is **not** available in
 * ordinary browsers.
 *
 * ### Important notes
 * - All `PerformScript*` calls are **asynchronous** – FileMaker does not block
 *   JavaScript execution while the script runs.
 * - The object is only available after the web page has **finished loading**.
 * - The web viewer must have *"Allow JavaScript to perform FileMaker scripts"*
 *   enabled in its object settings.
 * - In WebDirect the page source must use the `data:text/html,` MIME prefix
 *   (not `data:text/html; charset=UTF-8,`) for these calls to work.
 */
export interface FileMakerAPI {
  /**
   * Calls a FileMaker script by name.
   *
   * Runs asynchronously – JavaScript does not wait for the script to finish
   * and no return value is provided back to JavaScript.
   *
   * @param script    - Name of the FileMaker script to execute (not
   *                    case-sensitive).
   * @param parameter - Optional string parameter accessible inside the script
   *                    via `Get(ScriptParameter)`.
   *
   * @example
   * FileMaker.PerformScript("Save Record", JSON.stringify({ id: 42 }));
   */
  PerformScript(script: string, parameter?: string): void

  /**
   * Calls a FileMaker script by name with an explicit concurrency option.
   *
   * Behaves identically to `PerformScript` when `option` is `"0"` (pause
   * current script).
   *
   * @param script    - Name of the FileMaker script to execute.
   * @param parameter - Optional string parameter for the script.
   * @param option    - How to handle any currently running script.
   *                    See {@link ScriptOption} for the full table.
   *
   * @example
   * // Run concurrently without disturbing existing scripts
   * FileMaker.PerformScriptWithOption("Sync Data", "", "3");
   */
  PerformScriptWithOption(script: string, parameter?: string, option?: ScriptOption): void
}

// ---------------------------------------------------------------------------
// Global augmentation
// ---------------------------------------------------------------------------

declare global {
  /**
   * Global `FileMaker` object injected by the FileMaker runtime.
   *
   * May be `undefined` when the page is loaded outside of a FileMaker web
   * viewer (e.g. in a regular browser during development).
   *
   * Always guard access with a runtime check:
   * ```ts
   * if (typeof FileMaker !== "undefined") {
   *   FileMaker.PerformScript("My Script");
   * }
   * ```
   */
  const FileMaker: FileMakerAPI | undefined
}