@proofgeist/fmdapi

Claris FileMaker Data API Client for TypeScript

This package is designed to make working with the FileMaker Data API much easier. Here's just a few key features:

• Handles token refresh for you automatically
• Otto Data API proxy support
• TypeScript support for easy auto-completion of your fields
• Automated type generation based on layout metadata
• Supports both node and edge runtimes with a customizable token store
• Customizable adapters allow usage even within the FileMaker WebViewer.

Installation

This library requires zod as a peer depenency and Node 18 or later

npm install @proofgeist/fmdapi zod

yarn add @proofgeist/fmdapi zod

Upgrading to v4

Version 4 changes the way the client is created to allow for Custom Adapters, but the methods on the client remain the same. If you are using the codegen CLI tool, simply re-run codegen after upgrading to apply the changes.

Quick Start

Note: For the best experience, use the codegen tool to generate layout-specific clients and get autocomplete hints in your IDE with your actual field names. This minimal example just demonstrates the basic setup

Add the following envnironment variables to your project's .env file:

FM_DATABASE=filename.fmp12
FM_SERVER=https://filemaker.example.com

# if you want to use the OttoFMS Data API Proxy
OTTO_API_KEY=dk_123456...789
# otherwise
FM_USERNAME=admin
FM_PASSWORD=password

Initialize the client with credentials, depending on your adapter

// to use the OttoFMS Data API Proxy
import { DataApi, OttoAdapter } from "@proofgeist/fmdapi";
const client = DataApi({
  adapter: new OttoAdapter({
    auth: { apiKey: process.env.OTTO_API_KEY },
    db: process.env.FM_DATABASE,
    server: process.env.FM_SERVER,
  }),
});

// to use the raw Data API
import { DataApi, FetchAdapter } from "@proofgeist/fmdapi";
const client = DataApi({
  adapter: new FetchAdapter({
    auth: {
      username: process.env.FM_USERNAME,
      password: process.env.FM_PASSWORD,
    },
    db: process.env.FM_DATABASE,
    server: process.env.FM_SERVER,
  }),
});

Then, use the client to query your FileMaker database. View all available methods here.

Basic Example:

const result = await client.list({ layout: "Contacts" });

TypeScript Support

The basic client will return the generic FileMaker response object by default. You can also create a type for your exepcted response and get a fully typed response that includes your own fields.

type TContact = {
  name: string;
  email: string;
  phone: string;
};
const result = await client.list<TContact>({ layout: "Contacts" });

💡 TIP: For a more ergonomic TypeScript experience, use the included codegen tool to generate these types based on your FileMaker layout metadata.

For full docs, see the wiki

Edge Runtime Support (v3.0+)

Since version 3.0 uses the native fetch API, it is compatible with edge runtimes, but there are some additional considerations to avoid overwhelming your FileMaker server with too many connections. If you are developing for the edge, be sure to implement one of the following strategies:

• ✅ Use a custom token store (see above) with a persistent storage method such as Upstash
• ✅ Use a proxy such as the Otto Data API Proxy which handles management of the access tokens itself.
  • Providing an API key to the client instead of username/password will automatically use the Otto proxy