@proofkit/fmdapi 5.0.0-beta.0

package/src/adapters/fetch-base.ts

@@ -0,0 +1,339 @@
+import type {
+  AllLayoutsMetadataResponse,
+  CreateResponse,
+  DeleteResponse,
+  GetResponse,
+  LayoutMetadataResponse,
+  PortalRanges,
+  RawFMResponse,
+  ScriptResponse,
+  ScriptsMetadataResponse,
+  UpdateResponse,
+} from "../client-types.js";
+import { FileMakerError } from "../client-types.js";
+import type {
+  Adapter,
+  BaseRequest,
+  ContainerUploadOptions,
+  CreateOptions,
+  DeleteOptions,
+  FindOptions,
+  GetOptions,
+  LayoutMetadataOptions,
+  ListOptions,
+  UpdateOptions,
+} from "./core.js";
+import type {
+  BaseFetchAdapterOptions,
+  GetTokenArguments,
+} from "./fetch-base-types.js";
+
+export type ExecuteScriptOptions = BaseRequest & {
+  script: string;
+  scriptParam?: string;
+};
+
+export class BaseFetchAdapter implements Adapter {
+  protected server: string;
+  protected db: string;
+  private refreshToken: boolean;
+  baseUrl: URL;
+
+  constructor(options: BaseFetchAdapterOptions & { refreshToken?: boolean }) {
+    this.server = options.server;
+    this.db = options.db;
+    this.refreshToken = options.refreshToken ?? false;
+    this.baseUrl = new URL(
+      `${this.server}/fmi/data/vLatest/databases/${this.db}`,
+    );
+
+    if (this.db === "") throw new Error("Database name is required");
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  protected getToken = async (args?: GetTokenArguments): Promise<string> => {
+    // method must be implemented in subclass
+    throw new Error("getToken method not implemented by Fetch Adapter");
+  };
+
+  protected request = async (params: {
+    url: string;
+    body?: object | FormData;
+    query?: Record<string, string>;
+    method?: string;
+    retry?: boolean;
+    portalRanges?: PortalRanges;
+    timeout?: number;
+    fetchOptions?: RequestInit;
+  }): Promise<unknown> => {
+    const {
+      query,
+      body,
+      method = "GET",
+      retry = false,
+      fetchOptions = {},
+    } = params;
+
+    const url = new URL(`${this.baseUrl}${params.url}`);
+
+    if (query) {
+      const { _sort, ...rest } = query;
+      const searchParams = new URLSearchParams(rest);
+      if (query.portalRanges && typeof query.portalRanges === "object") {
+        for (const [portalName, value] of Object.entries(
+          query.portalRanges as PortalRanges,
+        )) {
+          if (value) {
+            if (value.offset && value.offset > 0) {
+              searchParams.set(
+                `_offset.${portalName}`,
+                value.offset.toString(),
+              );
+            }
+            if (value.limit) {
+              searchParams.set(`_limit.${portalName}`, value.limit.toString());
+            }
+          }
+        }
+      }
+      if (_sort) {
+        searchParams.set("_sort", JSON.stringify(_sort));
+      }
+      searchParams.delete("portalRanges");
+      url.search = searchParams.toString();
+    }
+
+    if (body && "portalRanges" in body) {
+      for (const [portalName, value] of Object.entries(
+        body.portalRanges as PortalRanges,
+      )) {
+        if (value) {
+          if (value.offset && value.offset > 0) {
+            url.searchParams.set(
+              `_offset.${portalName}`,
+              value.offset.toString(),
+            );
+          }
+          if (value.limit) {
+            url.searchParams.set(
+              `_limit.${portalName}`,
+              value.limit.toString(),
+            );
+          }
+        }
+      }
+      delete body.portalRanges;
+    }
+
+    const controller = new AbortController();
+    let timeout: NodeJS.Timeout | null = null;
+    if (params.timeout)
+      timeout = setTimeout(() => controller.abort(), params.timeout);
+
+    const token = await this.getToken({ refresh: retry });
+
+    const headers = new Headers(fetchOptions?.headers);
+    headers.set("Authorization", `Bearer ${token}`);
+
+    // Only set Content-Type for JSON bodies
+    if (!(body instanceof FormData)) {
+      headers.set("Content-Type", "application/json");
+    }
+
+    const res = await fetch(url.toString(), {
+      ...fetchOptions,
+      method,
+      body:
+        body instanceof FormData
+          ? body
+          : body
+            ? JSON.stringify(body)
+            : undefined,
+      headers,
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      signal: controller.signal,
+    });
+
+    if (timeout) clearTimeout(timeout);
+
+    let respData: RawFMResponse;
+    try {
+      respData = await res.json();
+    } catch {
+      respData = {};
+    }
+
+    if (!res.ok) {
+      if (
+        respData?.messages?.[0].code === "952" &&
+        !retry &&
+        this.refreshToken
+      ) {
+        // token expired, get new token and retry once
+        return this.request({ ...params, retry: true });
+      } else {
+        throw new FileMakerError(
+          respData?.messages?.[0].code ?? "500",
+          `Filemaker Data API failed with (${res.status}): ${JSON.stringify(
+            respData,
+            null,
+            2,
+          )}`,
+        );
+      }
+    }
+
+    return respData.response;
+  };
+
+  public list = async (opts: ListOptions): Promise<GetResponse> => {
+    const { data, layout } = opts;
+
+    const resp = await this.request({
+      url: `/layouts/${layout}/records`,
+      query: data as Record<string, string>,
+      fetchOptions: opts.fetch,
+      timeout: opts.timeout,
+    });
+    return resp as GetResponse;
+  };
+
+  public get = async (opts: GetOptions): Promise<GetResponse> => {
+    const { data, layout } = opts;
+    const resp = await this.request({
+      url: `/layouts/${layout}/records/${data.recordId}`,
+      fetchOptions: opts.fetch,
+      timeout: opts.timeout,
+    });
+    return resp as GetResponse;
+  };
+
+  public find = async (opts: FindOptions): Promise<GetResponse> => {
+    const { data, layout } = opts;
+    const resp = await this.request({
+      url: `/layouts/${layout}/_find`,
+      body: data,
+      method: "POST",
+      fetchOptions: opts.fetch,
+      timeout: opts.timeout,
+    });
+    return resp as GetResponse;
+  };
+
+  public create = async (opts: CreateOptions): Promise<CreateResponse> => {
+    const { data, layout } = opts;
+    const resp = await this.request({
+      url: `/layouts/${layout}/records`,
+      body: data,
+      method: "POST",
+      fetchOptions: opts.fetch,
+      timeout: opts.timeout,
+    });
+    return resp as CreateResponse;
+  };
+
+  public update = async (opts: UpdateOptions): Promise<UpdateResponse> => {
+    const {
+      data: { recordId, ...data },
+      layout,
+    } = opts;
+    const resp = await this.request({
+      url: `/layouts/${layout}/records/${recordId}`,
+      body: data,
+      method: "PATCH",
+      fetchOptions: opts.fetch,
+      timeout: opts.timeout,
+    });
+    return resp as UpdateResponse;
+  };
+
+  public delete = async (opts: DeleteOptions): Promise<DeleteResponse> => {
+    const { data, layout } = opts;
+    const resp = await this.request({
+      url: `/layouts/${layout}/records/${data.recordId}`,
+      method: "DELETE",
+      fetchOptions: opts.fetch,
+      timeout: opts.timeout,
+    });
+    return resp as DeleteResponse;
+  };
+
+  public layoutMetadata = async (
+    opts: LayoutMetadataOptions,
+  ): Promise<LayoutMetadataResponse> => {
+    return (await this.request({
+      url: `/layouts/${opts.layout}`,
+      fetchOptions: opts.fetch,
+      timeout: opts.timeout,
+    })) as LayoutMetadataResponse;
+  };
+
+  /**
+   * Execute a script within the database
+   */
+  public executeScript = async (opts: ExecuteScriptOptions) => {
+    const { script, scriptParam, layout } = opts;
+    const resp = await this.request({
+      url: `/layouts/${layout}/script/${script}`,
+      query: scriptParam ? { "script.param": scriptParam } : undefined,
+      fetchOptions: opts.fetch,
+      timeout: opts.timeout,
+    });
+    return resp as ScriptResponse;
+  };
+
+  /**
+   * Returns a list of available layouts on the database.
+   */
+  public layouts = async (opts?: Omit<BaseRequest, "layout">) => {
+    return (await this.request({
+      url: "/layouts",
+      fetchOptions: opts?.fetch,
+      timeout: opts?.timeout,
+    })) as AllLayoutsMetadataResponse;
+  };
+
+  /**
+   * Returns a list of available scripts on the database.
+   */
+  public scripts = async (opts?: Omit<BaseRequest, "layout">) => {
+    return (await this.request({
+      url: "/scripts",
+      fetchOptions: opts?.fetch,
+      timeout: opts?.timeout,
+    })) as ScriptsMetadataResponse;
+  };
+
+  public containerUpload = async (opts: ContainerUploadOptions) => {
+    let url = `/layouts/${opts.layout}/records/${opts.data.recordId}/containers/${opts.data.containerFieldName}`;
+    if (opts.data.repetition) url += `/${opts.data.repetition}`;
+    const formData = new FormData();
+    formData.append("upload", opts.data.file);
+
+    await this.request({
+      url,
+      method: "POST",
+      body: formData,
+      timeout: opts.timeout,
+      fetchOptions: opts.fetch,
+    });
+  };
+
+  /**
+   * Set global fields for the current session
+   */
+  public globals = async (
+    opts: Omit<BaseRequest, "layout"> & {
+      globalFields: Record<string, string | number>;
+    },
+  ) => {
+    return (await this.request({
+      url: "/globals",
+      method: "PATCH",
+      body: { globalFields: opts.globalFields },
+      fetchOptions: opts?.fetch,
+      timeout: opts?.timeout,
+    })) as Record<string, never>;
+  };
+}

package/src/adapters/fetch.ts

@@ -0,0 +1,95 @@
+import { FileMakerError } from "../client-types.js";
+import memoryStore from "../tokenStore/memory.js";
+import type { TokenStoreDefinitions } from "../tokenStore/types.js";
+import type {
+  BaseFetchAdapterOptions,
+  GetTokenArguments,
+} from "./fetch-base-types.js";
+import { BaseFetchAdapter } from "./fetch-base.js";
+
+export interface FetchAdapterOptions extends BaseFetchAdapterOptions {
+  auth: {
+    username: string;
+    password: string;
+  };
+  tokenStore?: TokenStoreDefinitions;
+}
+
+export class FetchAdapter extends BaseFetchAdapter {
+  private username: string;
+  private password: string;
+  private tokenStore: Omit<TokenStoreDefinitions, "getKey">;
+  private getTokenKey: Required<TokenStoreDefinitions>["getKey"];
+
+  constructor(args: FetchAdapterOptions) {
+    super({ ...args, refreshToken: true });
+    this.username = args.auth.username;
+    this.password = args.auth.password;
+    this.tokenStore = args.tokenStore ?? memoryStore();
+    this.getTokenKey =
+      args.tokenStore?.getKey ?? (() => `${args.server}/${args.db}`);
+
+    if (this.username === "") throw new Error("Username is required");
+    if (this.password === "") throw new Error("Password is required");
+  }
+
+  /**
+   * Gets a FileMaker Data API token for authentication.
+   *
+   * This token is **NOT** guaranteed to be valid, since it expires 15 minutes after the last use. Pass `refresh=true` to forcibly get a fresh token
+   *
+   * @param args.refresh - If true, forces getting a new token instead of using cached token
+   * @internal This method is intended for internal use, you should not need to use it in most cases.
+   */
+  public override getToken = async (
+    args?: GetTokenArguments,
+  ): Promise<string> => {
+    const { refresh = false } = args ?? {};
+    let token: string | null = null;
+    if (!refresh) {
+      token = await this.tokenStore.getToken(this.getTokenKey());
+    }
+
+    if (!token) {
+      const res = await fetch(`${this.baseUrl}/sessions`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Basic ${Buffer.from(
+            `${this.username}:${this.password}`,
+          ).toString("base64")}`,
+        },
+      });
+
+      if (!res.ok) {
+        const data = await res.json();
+        throw new FileMakerError(
+          data.messages[0].code,
+          data.messages[0].message,
+        );
+      }
+      token = res.headers.get("X-FM-Data-Access-Token");
+      if (!token) throw new Error("Could not get token");
+      this.tokenStore.setToken(this.getTokenKey(), token);
+    }
+
+    return token;
+  };
+
+  public disconnect = async (): Promise<void> => {
+    const token = await this.tokenStore.getToken(this.getTokenKey());
+    if (token) {
+      await this.request({
+        url: `/sessions/${token}`,
+        method: "DELETE",
+        fetchOptions: {
+          headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+          },
+        },
+      });
+      this.tokenStore.clearToken(this.getTokenKey());
+    }
+  };
+}

package/src/adapters/otto.ts

@@ -0,0 +1,59 @@
+import { BaseFetchAdapter } from "./fetch-base.js";
+import type { BaseFetchAdapterOptions } from "./fetch-base-types.js";
+
+export type Otto3APIKey = `KEY_${string}`;
+export type OttoFMSAPIKey = `dk_${string}`;
+export type OttoAPIKey = Otto3APIKey | OttoFMSAPIKey;
+
+export function isOtto3APIKey(key: string): key is Otto3APIKey {
+  return key.startsWith("KEY_");
+}
+export function isOttoFMSAPIKey(key: string): key is OttoFMSAPIKey {
+  return key.startsWith("dk_");
+}
+export function isOttoAPIKey(key: string): key is OttoAPIKey {
+  return isOtto3APIKey(key) || isOttoFMSAPIKey(key);
+}
+
+export function isOttoAuth(auth: unknown): auth is OttoAuth {
+  if (typeof auth !== "object" || auth === null) return false;
+  return "apiKey" in auth;
+}
+
+type OttoAuth =
+  | {
+      apiKey: Otto3APIKey;
+      ottoPort?: number;
+    }
+  | { apiKey: OttoFMSAPIKey; ottoPort?: never };
+
+export type OttoAdapterOptions = BaseFetchAdapterOptions & {
+  auth: OttoAuth;
+};
+
+export class OttoAdapter extends BaseFetchAdapter {
+  private apiKey: OttoAPIKey | Otto3APIKey;
+  private port: number | undefined;
+
+  constructor(options: OttoAdapterOptions) {
+    super({ ...options, refreshToken: false });
+    this.apiKey = options.auth.apiKey;
+    this.port = options.auth.ottoPort;
+
+    if (this.apiKey.startsWith("KEY_")) {
+      // otto v3 uses port 3030
+      this.baseUrl.port = (this.port ?? 3030).toString();
+    } else if (this.apiKey.startsWith("dk_")) {
+      // otto v4 uses default port, but with /otto prefix
+      this.baseUrl.pathname = `otto/${this.baseUrl.pathname.replace(/^\/+|\/+$/g, "")}`;
+    } else {
+      throw new Error(
+        "Invalid Otto API key format. Must start with 'KEY_' (Otto v3) or 'dk_' (OttoFMS)",
+      );
+    }
+  }
+
+  protected override getToken = async (): Promise<string> => {
+    return this.apiKey;
+  };
+}