Add Claris ID auth support

- add Claris ID login flow for fmodata
- wire CLI and typegen env/config support
- update docs and tests

Author: eluce2

.changeset/early-eels-smile.md

@@ -0,0 +1,6 @@
+---
+"@proofkit/fmodata": minor
+"@proofkit/typegen": minor
+---
+
+Add Claris ID auth support for `fmodata` FileMaker Cloud connections, including CLI and typegen env/config support.

apps/docs/src/app/(home)/page.tsx

@@ -26,51 +26,34 @@ export default function HomePage() {
       <div className="mx-auto flex w-full max-w-screen-lg flex-col items-center justify-center">
         <div className="relative flex h-[500px] w-full flex-col items-center justify-center overflow-hidden rounded-lg bg-background">
           <InteractiveGridPattern
-            className={cn(
-              "absolute inset-0 [mask-image:radial-gradient(400px_circle_at_center,white,transparent)]",
-            )}
+            className={cn("absolute inset-0 [mask-image:radial-gradient(400px_circle_at_center,white,transparent)]")}
             height={40}
             squares={[80, 80]}
             squaresClassName="hover:fill-brand/50"
             style={{ zIndex: 0 }}
             width={40}
           />
-          <Image
-            alt="ProofKit Logo"
-            className="pointer-events-none z-10"
-            src={ProofKitLogo}
-            width={400}
-          />
+          <Image alt="ProofKit Logo" className="pointer-events-none z-10" src={ProofKitLogo} width={400} />
         </div>
 
         <div className="mt-8 w-full space-y-8 text-center">
-          <h1 className="font-bold text-4xl">
-            A collection of tools for FileMaker-aware TypeScript applications
-          </h1>
+          <h1 className="font-bold text-4xl">A collection of tools for FileMaker-aware TypeScript applications</h1>
           <p className="font-medium text-gray-500 text-xl">
-            For new and experienced developers alike, the ProofKit toolset is
-            the best way to build web apps connected to FileMaker data, or rich,
-            interactive interfaces in a FileMaker webviewer.
+            For new and experienced developers alike, the ProofKit toolset is the best way to build web apps connected
+            to FileMaker data, or rich, interactive interfaces in a FileMaker webviewer.
           </p>
 
           <Cards className="px-4 text-left">
             <Card href="/docs/cli" icon={<Terminal />} title="ProofKit CLI">
-              A command line tool to start a new project, or easily apply
-              templates and common patterns with{" "}
-              <span className="underline">no JavaScript experience</span>{" "}
-              required.
+              A command line tool to start a new project, or easily apply templates and common patterns with{" "}
+              <span className="underline">no JavaScript experience</span> required.
             </Card>
             <Card href="/docs/typegen" icon={<Code />} title={"Typegen"}>
-              Automatically generate runtime validators and TypeScript files
-              from your own FileMaker layouts or table occurrences.
+              Automatically generate runtime validators and TypeScript files from your own FileMaker layouts or table
+              occurrences.
             </Card>
-            <Card
-              href="/docs/fmdapi"
-              icon={<WebhookIcon />}
-              title="Filemaker Data API"
-            >
-              A type-safe API for your FileMaker layouts. Easily connect without
-              worrying about token management.
+            <Card href="/docs/fmdapi" icon={<WebhookIcon />} title="Filemaker Data API">
+              A type-safe API for your FileMaker layouts. Easily connect without worrying about token management.
             </Card>
             <Card
               href="/docs/fmodata"
@@ -84,16 +67,11 @@ export default function HomePage() {
                 </span>
               }
             >
-              A strongly-typed OData API client with full TypeScript inference,
-              runtime validation, and a fluent query builder.
+              A strongly-typed OData API client with full TypeScript inference, runtime validation, and a fluent query
+              builder.
             </Card>
-            <Card
-              href="/docs/webviewer"
-              icon={<Globe />}
-              title="FileMaker Webviewer"
-            >
-              Use async functions in WebViewer code to execute and get the
-              result of a FileMaker script.
+            <Card href="/docs/webviewer" icon={<Globe />} title="FileMaker Webviewer">
+              Use async functions in WebViewer code to execute and get the result of a FileMaker script.
             </Card>
             <Card
               href="/docs/better-auth"
@@ -107,8 +85,7 @@ export default function HomePage() {
                 </span>
               }
             >
-              Own your authentication with FileMaker and the extensible
-              Better-Auth framework.
+              Own your authentication with FileMaker and the extensible Better-Auth framework.
             </Card>
           </Cards>
 
@@ -118,8 +95,7 @@ export default function HomePage() {
             <div className="flex flex-col text-left">
               <h2 className="mb-4 font-bold text-3xl">Quick Start</h2>
               <p className="mb-0 text-gray-600 text-lg">
-                Use the ProofKit CLI to launch a full-featured Next.js app in
-                minutes—no prior experience required.
+                Use the ProofKit CLI to launch a full-featured Next.js app in minutes—no prior experience required.
               </p>
             </div>
 
@@ -152,11 +128,9 @@ export default function HomePage() {
                 Built for AI Agents
               </h2>
               <p className="mb-0 text-gray-600 text-lg">
-                Every ProofKit package ships with agent skills — built from
-                decades of combined FileMaker integration experience at Proof —
-                that give AI coding tools like Claude Code and Cursor the
-                context they need to write correct, production-ready FileMaker
-                code from day one.
+                Every ProofKit package ships with agent skills — built from decades of combined FileMaker integration
+                experience at Proof — that give AI coding tools like Claude Code and Cursor the context they need to
+                write correct, production-ready FileMaker code from day one.
               </p>
             </div>
 
@@ -167,9 +141,8 @@ export default function HomePage() {
                   Expert knowledge built in
                 </div>
                 <p className="text-gray-500 text-sm">
-                  Agent skills cover API patterns, edge cases, and common
-                  mistakes so your AI agent avoids the pitfalls that trip up
-                  even experienced developers.
+                  Agent skills cover API patterns, edge cases, and common mistakes so your AI agent avoids the pitfalls
+                  that trip up even experienced developers.
                 </p>
               </div>
               <div className="flex flex-col gap-2 rounded-lg border p-4">
@@ -178,9 +151,8 @@ export default function HomePage() {
                   Type-safe by default
                 </div>
                 <p className="text-gray-500 text-sm">
-                  Schemas generated from your FileMaker field names plus runtime
-                  validators catch bugs early — whether code is written by you
-                  or your AI agent.
+                  Schemas generated from your FileMaker field names plus runtime validators catch bugs early — whether
+                  code is written by you or your AI agent.
                 </p>
               </div>
               <div className="flex flex-col gap-2 rounded-lg border p-4">
@@ -189,9 +161,8 @@ export default function HomePage() {
                   Works with any agent
                 </div>
                 <p className="text-gray-500 text-sm">
-                  Skills are bundled with each package — just install and your
-                  AI coding tool picks them up automatically. Compatible with
-                  Claude Code, Cursor, Windsurf, and more.
+                  Skills are bundled with each package — just install and your AI coding tool picks them up
+                  automatically. Compatible with Claude Code, Cursor, Windsurf, and more.
                 </p>
               </div>
             </div>

apps/docs/src/app/docs/(docs)/layout.tsx

@@ -16,12 +16,7 @@ export default function Layout({ children }: { children: ReactNode }) {
           <div className="mt-2 flex items-center justify-center text-muted-foreground text-xs">
             <p>
               Made with ❤️ by{" "}
-              <a
-                className="underline"
-                href="http://proof.sh"
-                rel="noopener"
-                target="_blank"
-              >
+              <a className="underline" href="http://proof.sh" rel="noopener" target="_blank">
                 Proof
               </a>
             </p>

apps/docs/src/app/docs/templates/layout.tsx

@@ -86,12 +86,7 @@ export default async function Layout({ children }: { children: ReactNode }) {
           <div className="mt-2 flex items-center justify-center text-muted-foreground text-xs">
             <p>
               Made with ❤️ by{" "}
-              <a
-                className="underline"
-                href="http://proof.sh"
-                rel="noopener noreferrer"
-                target="_blank"
-              >
+              <a className="underline" href="http://proof.sh" rel="noopener noreferrer" target="_blank">
                 Proof
               </a>
             </p>

packages/fmodata/README.md

@@ -40,6 +40,12 @@ const connection = new FMServerConnection({
     // OttoFMS API key
     apiKey: "your-api-key",
 
+    // or Claris ID for FileMaker Cloud
+    // clarisId: {
+    //   username: "your@claris-id.com",
+    //   password: "password",
+    // },
+
     // or username and password
     // username: "admin",
     // password: "password",
@@ -96,7 +102,7 @@ OData relies entirely on the table occurances in the relationship graph for data
 
 ### Server Connection
 
-The client can authenticate using username/password or API key:
+The client can authenticate using username/password, Otto API key, or Claris ID for FileMaker Cloud:
 
 ```typescript
 // Username and password authentication
@@ -115,8 +121,26 @@ const connection = new FMServerConnection({
     apiKey: "your-api-key",
   },
 });
+
+// Claris ID authentication for FileMaker Cloud
+const connection = new FMServerConnection({
+  serverUrl: "https://your-filemaker-cloud-host.com",
+  auth: {
+    clarisId: {
+      username: "your@claris-id.com",
+      password: "password",
+    },
+  },
+});
 ```
 
+Notes for Claris ID auth:
+
+- Use a Claris ID account, not an external IdP account.
+- Tokens are managed internally and refreshed automatically.
+- Claris ID tokens are valid for about one hour.
+- MFA is not supported.
+
 ### Schema Definitions
 
 This library relies on a schema-first approach for good type-safety and optional runtime validation. Use **`fmTableOccurrence()`** with field builders to create your schemas. This provides full TypeScript type inference for field names in queries.

packages/fmodata/package.json

@@ -61,6 +61,7 @@
   },
   "dependencies": {
     "@fetchkit/ffetch": "^4.2.0",
+    "amazon-cognito-identity-js": "^6.3.16",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.2",
     "dotenv": "^16.6.1",

packages/fmodata/skills/fmodata-client/SKILL.md

@@ -33,13 +33,17 @@ const connection = new FMServerConnection({
   auth: { username: "admin", password: "secret" },
   // OR with OttoFMS API key:
   // auth: { apiKey: "your-otto-api-key" },
+  // OR with Claris ID for FileMaker Cloud:
+  // auth: { clarisId: { username: "you@claris-id.com", password: "secret" } },
   fetchClientOptions: {
     retries: 2,
     timeout: 30000,
   },
 });
 ```
 
+For FileMaker Cloud, use a Claris ID account, not an external IdP account. MFA-backed Claris ID accounts are not supported.
+
 ### 2. Create a database reference
 
 ```ts

packages/fmodata/src/cli/index.ts

@@ -21,6 +21,8 @@ program
   .option("--database <name>", `FM database name [env: ${ENV_NAMES.db}]`)
   .option("--username <user>", `FM username [env: ${ENV_NAMES.username}]`)
   .option("--password <pass>", `FM password [env: ${ENV_NAMES.password}]`)
+  .option("--claris-id-username <user>", `Claris ID username [env: ${ENV_NAMES.clarisIdUsername}]`)
+  .option("--claris-id-password <pass>", `Claris ID password [env: ${ENV_NAMES.clarisIdPassword}]`)
   .option("--api-key <key>", `OttoFMS API key [env: ${ENV_NAMES.apiKey}]`)
   .option("--pretty", "Output as table (default: JSON)", false);
 

packages/fmodata/src/cli/utils/connection.ts

@@ -6,6 +6,8 @@ export const ENV_NAMES = {
   db: "FM_DATABASE",
   username: "FM_USERNAME",
   password: "FM_PASSWORD",
+  clarisIdUsername: "CLARIS_ID_USERNAME",
+  clarisIdPassword: "CLARIS_ID_PASSWORD",
   apiKey: "OTTO_API_KEY",
 } as const;
 
@@ -14,6 +16,8 @@ export interface ConnectionOptions {
   database?: string;
   username?: string;
   password?: string;
+  clarisIdUsername?: string;
+  clarisIdPassword?: string;
   apiKey?: string;
 }
 
@@ -28,21 +32,43 @@ export function buildConnection(opts: ConnectionOptions): BuiltConnection {
   const apiKey = opts.apiKey ?? process.env[ENV_NAMES.apiKey];
   const username = opts.username ?? process.env[ENV_NAMES.username];
   const password = opts.password ?? process.env[ENV_NAMES.password];
+  const clarisIdUsername = opts.clarisIdUsername ?? process.env[ENV_NAMES.clarisIdUsername];
+  const clarisIdPassword = opts.clarisIdPassword ?? process.env[ENV_NAMES.clarisIdPassword];
 
   if (!server) {
     throw new Error(`Missing required: --server or ${ENV_NAMES.server} environment variable`);
   }
   if (!database) {
     throw new Error(`Missing required: --database or ${ENV_NAMES.db} environment variable`);
   }
-  if (!(apiKey || username)) {
-    throw new Error(`Missing required auth: --api-key (${ENV_NAMES.apiKey}) or --username (${ENV_NAMES.username})`);
+  if (!(apiKey || clarisIdUsername || username)) {
+    throw new Error(
+      `Missing required auth: --api-key (${ENV_NAMES.apiKey}), --claris-id-username (${ENV_NAMES.clarisIdUsername}), or --username (${ENV_NAMES.username})`,
+    );
+  }
+  if (!apiKey && clarisIdUsername && !clarisIdPassword) {
+    throw new Error(`Missing required: --claris-id-password (${ENV_NAMES.clarisIdPassword}) when using Claris ID auth`);
   }
   if (!apiKey && username && !password) {
     throw new Error(`Missing required: --password (${ENV_NAMES.password}) when using username auth`);
   }
 
-  const auth = apiKey ? { apiKey } : { username: username as string, password: password as string };
+  let auth:
+    | { apiKey: string }
+    | { clarisId: { username: string; password: string } }
+    | { username: string; password: string };
+  if (apiKey) {
+    auth = { apiKey };
+  } else if (clarisIdUsername) {
+    auth = {
+      clarisId: {
+        username: clarisIdUsername as string,
+        password: clarisIdPassword as string,
+      },
+    };
+  } else {
+    auth = { username: username as string, password: password as string };
+  }
   const connection = new FMServerConnection({ serverUrl: server, auth });
   const db = connection.database(database);
   return { connection, db };

packages/fmodata/src/client/amazon-cognito-identity-js.d.ts

@@ -0,0 +1,55 @@
+declare module "amazon-cognito-identity-js" {
+  export class CognitoRefreshToken {
+    constructor(data: { RefreshToken: string });
+  }
+
+  export class CognitoAccessToken {
+    constructor(data: { AccessToken: string });
+    getJwtToken(): string;
+  }
+
+  export class CognitoIdToken {
+    constructor(data: { IdToken: string });
+    getJwtToken(): string;
+  }
+
+  export class CognitoUserSession {
+    constructor(data: {
+      AccessToken: CognitoAccessToken;
+      IdToken: CognitoIdToken;
+      RefreshToken: CognitoRefreshToken;
+    });
+    isValid(): boolean;
+    getIdToken(): CognitoIdToken;
+    getAccessToken(): CognitoAccessToken;
+    getRefreshToken(): CognitoRefreshToken;
+  }
+
+  export class AuthenticationDetails {
+    constructor(data: { Username: string; Password: string });
+    getUsername(): string;
+  }
+
+  export class CognitoUserPool {
+    constructor(data: { UserPoolId: string; ClientId: string });
+  }
+
+  export class CognitoUser {
+    constructor(data: { Username: string; Pool: CognitoUserPool });
+    authenticateUser(
+      details: AuthenticationDetails,
+      callbacks: {
+        onSuccess: (session: CognitoUserSession) => void;
+        onFailure: (error: unknown) => void;
+        mfaRequired?: (...args: unknown[]) => void;
+        totpRequired?: (...args: unknown[]) => void;
+        selectMFAType?: (...args: unknown[]) => void;
+        mfaSetup?: (...args: unknown[]) => void;
+      },
+    ): void;
+    refreshSession(
+      refreshToken: CognitoRefreshToken,
+      callback: (error: unknown, session: CognitoUserSession | null) => void,
+    ): void;
+  }
+}