@proofkit/better-auth 0.3.1-beta.1 → 0.4.0-beta.11

package/skills/better-auth-setup/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: better-auth-setup
+description: >
+  Set up self-hosted authentication with better-auth using FileMaker as the
+  database backend. Covers FileMakerAdapter, FMServerConnection, betterAuth
+  config, migration via npx @proofkit/better-auth migrate, OData prerequisites,
+  fmodata privilege, Full Access credentials for schema modification, plugin
+  migration workflow, troubleshooting "filemaker is not supported" errors.
+type: core
+library: proofkit
+library_version: "0.4.0-beta.7"
+requires:
+  - fmodata-client
+sources:
+  - "proofgeist/proofkit:packages/better-auth/src/*.ts"
+  - "proofgeist/proofkit:apps/docs/content/docs/better-auth/*.mdx"
+---
+
+## Setup
+
+### Prerequisites
+
+- OData enabled on FileMaker Server
+- API credentials with `fmodata` privilege enabled
+- Read/write access to the better-auth tables
+- Full Access credentials available for schema migration (can differ from runtime credentials)
+
+### Install packages
+
+```bash
+pnpm add @proofkit/better-auth @proofkit/fmodata
+```
+
+### Configure auth.ts
+
+```ts
+import { betterAuth } from "better-auth";
+import { FMServerConnection } from "@proofkit/fmodata";
+import { FileMakerAdapter } from "@proofkit/better-auth";
+
+const connection = new FMServerConnection({
+  serverUrl: process.env.FM_SERVER_URL!,
+  auth: {
+    username: process.env.FM_USERNAME!,
+    password: process.env.FM_PASSWORD!,
+  },
+});
+
+const db = connection.database(process.env.FM_DATABASE!);
+
+export const auth = betterAuth({
+  database: FileMakerAdapter({ database: db }),
+  // add plugins, social providers, etc.
+});
+```
+
+`FileMakerAdapter` accepts a `FileMakerAdapterConfig`:
+
+- `database` (required) -- an fmodata `Database` instance
+- `debugLogs` (optional) -- enable adapter debug logging
+- `usePlural` (optional) -- set `true` if table names are plural
+
+The adapter maps Better Auth operations (create, findOne, findMany, update, delete, count) to OData requests via `db._makeRequest`. It does not support JSON columns, native dates, or native booleans -- all values are stored as strings/numbers.
+
+### Alternative: Data API key (OttoFMS 4.11+)
+
+```ts
+const connection = new FMServerConnection({
+  serverUrl: process.env.FM_SERVER_URL!,
+  auth: {
+    apiKey: process.env.OTTO_API_KEY!,
+  },
+});
+```
+
+OData must be enabled for the key.
+
+## Core Patterns
+
+### 1. Initial migration
+
+After configuring `auth.ts`, run the migration CLI to create tables and fields in FileMaker:
+
+```bash
+npx @proofkit/better-auth migrate
+```
+
+The CLI:
+
+1. Loads your `auth.ts` config (auto-detected or via `--config <path>`)
+2. Calls `getSchema()` from `better-auth/db` to determine required tables/fields
+3. Fetches current OData metadata via `db.getMetadata()`
+4. Computes a diff: tables to create, fields to add to existing tables
+5. Prints the migration plan and prompts for confirmation
+6. Executes via `db.schema.createTable()` and `db.schema.addFields()`
+
+Only schema is modified. No layouts or relationships are created.
+
+If your runtime credentials lack Full Access, override for migration only:
+
+```bash
+npx @proofkit/better-auth migrate --username "admin" --password "admin_pass"
+```
+
+Skip confirmation with `-y`:
+
+```bash
+npx @proofkit/better-auth migrate -y
+```
+
+### 2. Adding plugins and re-migrating
+
+When you add a Better Auth plugin (e.g. `twoFactor`, `organization`), it declares additional tables/fields. After updating `auth.ts`:
+
+```ts
+import { betterAuth } from "better-auth";
+import { twoFactor } from "better-auth/plugins";
+import { FMServerConnection } from "@proofkit/fmodata";
+import { FileMakerAdapter } from "@proofkit/better-auth";
+
+const connection = new FMServerConnection({
+  serverUrl: process.env.FM_SERVER_URL!,
+  auth: {
+    username: process.env.FM_USERNAME!,
+    password: process.env.FM_PASSWORD!,
+  },
+});
+
+const db = connection.database(process.env.FM_DATABASE!);
+
+export const auth = betterAuth({
+  database: FileMakerAdapter({ database: db }),
+  plugins: [twoFactor()],
+});
+```
+
+Re-run migration:
+
+```bash
+npx @proofkit/better-auth migrate
+```
+
+The planner diffs against existing metadata, so only new tables/fields are added. Existing tables are left untouched.
+
+### 3. Troubleshooting privilege errors
+
+When migration fails with OData error code `207`, the account lacks schema modification privileges. The CLI outputs:
+
+```
+Failed to create table "tableName": Cannot modify schema.
+The account used does not have schema modification privileges.
+Use --username and --password to provide Full Access credentials.
+```
+
+Fix: provide Full Access credentials via CLI flags. These are only used for migration, not at runtime.
+
+## Common Mistakes
+
+### [CRITICAL] Using better-auth CLI instead of @proofkit/better-auth
+
+Wrong:
+```bash
+npx better-auth migrate
+```
+
+Correct:
+```bash
+npx @proofkit/better-auth migrate
+```
+
+The standard better-auth CLI does not know about the FileMaker adapter and produces: `ERROR [Better Auth]: filemaker is not supported. If it is a custom adapter, please request the maintainer to implement createSchema`. The `@proofkit/better-auth` CLI loads your auth config, extracts the `Database` instance from the adapter, and handles migration via fmodata's schema API.
+
+Source: `apps/docs/content/docs/better-auth/troubleshooting.mdx`
+
+### [HIGH] Missing Full Access credentials for schema migration
+
+Wrong:
+```bash
+# Using runtime credentials that only have fmodata privilege
+npx @proofkit/better-auth migrate
+# Fails with OData error 207: Cannot modify schema
+```
+
+Correct:
+```bash
+npx @proofkit/better-auth migrate --username "full_access_user" --password "full_access_pass"
+```
+
+Schema modification (`db.schema.createTable`, `db.schema.addFields`) requires [Full Access] privileges. Standard API accounts with `fmodata` privilege can read/write data but cannot alter schema. The CLI accepts `--username` and `--password` flags to override credentials for migration only.
+
+Source: `packages/better-auth/src/cli/index.ts`, `packages/better-auth/src/migrate.ts`
+
+### [HIGH] Removing fields added by migration
+
+Wrong:
+```
+Manually deleting "unused" fields from better-auth tables in FileMaker
+```
+
+Correct:
+```
+Keep all fields created by migration, even if you don't plan to use them
+```
+
+Better Auth expects all schema fields to exist at runtime. The adapter issues OData requests that reference these fields. Removing them causes runtime errors when Better Auth attempts to read or write those columns.
+
+Source: `apps/docs/content/docs/better-auth/installation.mdx`
+
+### [HIGH] Forgetting to re-run migration after adding plugins
+
+Wrong:
+```ts
+// Added twoFactor() plugin to auth.ts but did not re-run migration
+export const auth = betterAuth({
+  database: FileMakerAdapter({ database: db }),
+  plugins: [twoFactor()],
+});
+// Runtime errors: tables/fields for twoFactor don't exist
+```
+
+Correct:
+```bash
+# After adding any plugin to auth.ts, always re-run:
+npx @proofkit/better-auth migrate
+```
+
+Each plugin declares additional tables and fields via `getSchema()`. The migration planner diffs the full schema (including plugins) against current OData metadata. Without re-running, the new tables/fields don't exist and Better Auth throws at runtime.
+
+Source: `apps/docs/content/docs/better-auth/installation.mdx`
+
+## References
+
+- **fmodata-client** -- Better Auth uses fmodata `Database` under the hood for all OData requests. `FMServerConnection` and `database()` must be configured before `FileMakerAdapter` can work. The adapter calls `db._makeRequest()` for CRUD and `db.schema.*` for migrations.

package/src/adapter.ts

@@ -1,19 +1,7 @@
 /** biome-ignore-all lint/suspicious/noExplicitAny: library code */
+import type { Database } from "@proofkit/fmodata";
 import { logger } from "better-auth";
-import { type CleanedWhere, createAdapter, type DBAdapterDebugLogOption } from "better-auth/adapters";
-import buildQuery from "odata-query";
-import { prettifyError, z } from "zod/v4";
-import { createRawFetch, type FmOdataConfig } from "./odata";
-
-const configSchema = z.object({
-  debugLogs: z.unknown().optional(),
-  usePlural: z.boolean().optional(),
-  odata: z.object({
-    serverUrl: z.url(),
-    auth: z.union([z.object({ username: z.string(), password: z.string() }), z.object({ apiKey: z.string() })]),
-    database: z.string().endsWith(".fmp12"),
-  }),
-});
+import { type CleanedWhere, createAdapterFactory, type DBAdapterDebugLogOption } from "better-auth/adapters";
 
 export interface FileMakerAdapterConfig {
   /**
@@ -24,27 +12,12 @@ export interface FileMakerAdapterConfig {
    * If the table names in the schema are plural.
    */
   usePlural?: boolean;
-
   /**
-   * Connection details for the FileMaker server.
+   * The fmodata Database instance to use for all OData requests.
    */
-  odata: FmOdataConfig;
-}
-
-export interface AdapterOptions {
-  config: FileMakerAdapterConfig;
+  database: Database;
 }
 
-const defaultConfig: Required<FileMakerAdapterConfig> = {
-  debugLogs: false,
-  usePlural: false,
-  odata: {
-    serverUrl: "",
-    auth: { username: "", password: "" },
-    database: "",
-  },
-};
-
 // Regex patterns for field validation and ISO date detection
 const FIELD_SPECIAL_CHARS_REGEX = /[\s_]/;
 const ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?$/;
@@ -155,41 +128,59 @@ export function parseWhere(where?: CleanedWhere[]): string {
   return clauses.join(" ");
 }
 
-export const FileMakerAdapter = (_config: FileMakerAdapterConfig = defaultConfig) => {
-  const parsed = configSchema.loose().safeParse(_config);
+/**
+ * Build an OData query string from parameters.
+ */
+function buildQueryString(params: {
+  top?: number;
+  skip?: number;
+  filter?: string;
+  orderBy?: string;
+  select?: string[];
+}): string {
+  const parts: string[] = [];
+  if (params.top !== undefined) {
+    parts.push(`$top=${params.top}`);
+  }
+  if (params.skip !== undefined) {
+    parts.push(`$skip=${params.skip}`);
+  }
+  if (params.filter) {
+    parts.push(`$filter=${encodeURIComponent(params.filter)}`);
+  }
+  if (params.orderBy) {
+    parts.push(`$orderby=${encodeURIComponent(params.orderBy)}`);
+  }
+  if (params.select?.length) {
+    parts.push(`$select=${params.select.map(encodeURIComponent).join(",")}`);
+  }
+  return parts.length > 0 ? `?${parts.join("&")}` : "";
+}
 
-  if (!parsed.success) {
-    throw new Error(`Invalid configuration: ${prettifyError(parsed.error)}`);
+export const FileMakerAdapter = (config: FileMakerAdapterConfig) => {
+  if (!config.database || typeof config.database !== "object") {
+    throw new Error("FileMakerAdapter requires a `database` (fmodata Database instance).");
   }
-  const config = parsed.data;
 
-  const { fetch } = createRawFetch({
-    ...config.odata,
-    logging: config.debugLogs ? "verbose" : "none",
-  });
+  const db = config.database;
 
-  const adapterFactory = createAdapter({
+  const adapterFactory = createAdapterFactory({
     config: {
       adapterId: "filemaker",
       adapterName: "FileMaker",
-      usePlural: config.usePlural ?? false, // Whether the table names in the schema are plural.
-      debugLogs: config.debugLogs ?? false, // Whether to enable debug logs.
-      supportsJSON: false, // Whether the database supports JSON. (Default: false)
-      supportsDates: false, // Whether the database supports dates. (Default: true)
-      supportsBooleans: false, // Whether the database supports booleans. (Default: true)
-      supportsNumericIds: false, // Whether the database supports auto-incrementing numeric IDs. (Default: true)
+      usePlural: config.usePlural ?? false,
+      debugLogs: config.debugLogs ?? false,
+      supportsJSON: false,
+      supportsDates: false,
+      supportsBooleans: false,
+      supportsNumericIds: false,
     },
     adapter: () => {
       return {
         create: async ({ data, model }) => {
-          if (model === "session") {
-            console.log("session", data);
-          }
-
-          const result = await fetch(`/${model}`, {
+          const result = await db._makeRequest<Record<string, any>>(`/${model}`, {
             method: "POST",
-            body: data,
-            output: z.looseObject({ id: z.string() }),
+            body: JSON.stringify(data),
           });
 
           if (result.error) {
@@ -202,15 +193,12 @@ export const FileMakerAdapter = (_config: FileMakerAdapterConfig = defaultConfig
           const filter = parseWhere(where);
           logger.debug("$filter", filter);
 
-          const query = buildQuery({
+          const query = buildQueryString({
             filter: filter.length > 0 ? filter : undefined,
           });
 
-          const result = await fetch(`/${model}/$count${query}`, {
-            method: "GET",
-            output: z.object({ value: z.number() }),
-          });
-          if (!result.data) {
+          const result = await db._makeRequest<{ value: number }>(`/${model}/$count${query}`);
+          if (result.error) {
             throw new Error("Failed to count records");
           }
           return (result.data?.value as any) ?? 0;
@@ -219,15 +207,12 @@ export const FileMakerAdapter = (_config: FileMakerAdapterConfig = defaultConfig
           const filter = parseWhere(where);
           logger.debug("$filter", filter);
 
-          const query = buildQuery({
+          const query = buildQueryString({
             top: 1,
             filter: filter.length > 0 ? filter : undefined,
           });
 
-          const result = await fetch(`/${model}${query}`, {
-            method: "GET",
-            output: z.object({ value: z.array(z.any()) }),
-          });
+          const result = await db._makeRequest<{ value: any[] }>(`/${model}${query}`);
           if (result.error) {
             throw new Error("Failed to find record");
           }
@@ -237,7 +222,7 @@ export const FileMakerAdapter = (_config: FileMakerAdapterConfig = defaultConfig
           const filter = parseWhere(where);
           logger.debug("FIND MANY", { where, filter });
 
-          const query = buildQuery({
+          const query = buildQueryString({
             top: limit,
             skip: offset,
             orderBy: sortBy ? `${sortBy.field} ${sortBy.direction ?? "asc"}` : undefined,
@@ -245,10 +230,7 @@ export const FileMakerAdapter = (_config: FileMakerAdapterConfig = defaultConfig
           });
           logger.debug("QUERY", query);
 
-          const result = await fetch(`/${model}${query}`, {
-            method: "GET",
-            output: z.object({ value: z.array(z.any()) }),
-          });
+          const result = await db._makeRequest<{ value: any[] }>(`/${model}${query}`);
           logger.debug("RESULT", result);
 
           if (result.error) {
@@ -259,54 +241,44 @@ export const FileMakerAdapter = (_config: FileMakerAdapterConfig = defaultConfig
         },
         delete: async ({ model, where }) => {
           const filter = parseWhere(where);
-          console.log("DELETE", { model, where, filter });
           logger.debug("$filter", filter);
 
           // Find a single id matching the filter
-          const query = buildQuery({
+          const query = buildQueryString({
             top: 1,
             select: [`"id"`],
             filter: filter.length > 0 ? filter : undefined,
           });
 
-          const toDelete = await fetch(`/${model}${query}`, {
-            method: "GET",
-            output: z.object({ value: z.array(z.object({ id: z.string() })) }),
-          });
+          const toDelete = await db._makeRequest<{ value: { id: string }[] }>(`/${model}${query}`);
 
           const id = toDelete.data?.value?.[0]?.id;
           if (!id) {
-            // Nothing to delete
             return;
           }
 
-          const result = await fetch(`/${model}('${id}')`, {
+          const result = await db._makeRequest(`/${model}('${id}')`, {
             method: "DELETE",
           });
           if (result.error) {
-            console.log("DELETE ERROR", result.error);
             throw new Error("Failed to delete record");
           }
         },
         deleteMany: async ({ model, where }) => {
           const filter = parseWhere(where);
-          console.log("DELETE MANY", { model, where, filter });
 
           // Find all ids matching the filter
-          const query = buildQuery({
+          const query = buildQueryString({
             select: [`"id"`],
             filter: filter.length > 0 ? filter : undefined,
           });
 
-          const rows = await fetch(`/${model}${query}`, {
-            method: "GET",
-            output: z.object({ value: z.array(z.object({ id: z.string() })) }),
-          });
+          const rows = await db._makeRequest<{ value: { id: string }[] }>(`/${model}${query}`);
 
           const ids = rows.data?.value?.map((r: any) => r.id) ?? [];
           let deleted = 0;
           for (const id of ids) {
-            const res = await fetch(`/${model}('${id}')`, {
+            const res = await db._makeRequest(`/${model}('${id}')`, {
               method: "DELETE",
             });
             if (!res.error) {
@@ -319,16 +291,14 @@ export const FileMakerAdapter = (_config: FileMakerAdapterConfig = defaultConfig
           const filter = parseWhere(where);
           logger.debug("UPDATE", { model, where, update });
           logger.debug("$filter", filter);
+
           // Find one id to update
-          const query = buildQuery({
+          const query = buildQueryString({
             select: [`"id"`],
             filter: filter.length > 0 ? filter : undefined,
           });
 
-          const existing = await fetch(`/${model}${query}`, {
-            method: "GET",
-            output: z.object({ value: z.array(z.object({ id: z.string() })) }),
-          });
+          const existing = await db._makeRequest<{ value: { id: string }[] }>(`/${model}${query}`);
           logger.debug("EXISTING", existing.data);
 
           const id = existing.data?.value?.[0]?.id;
@@ -336,9 +306,9 @@ export const FileMakerAdapter = (_config: FileMakerAdapterConfig = defaultConfig
             return null;
           }
 
-          const patchRes = await fetch(`/${model}('${id}')`, {
+          const patchRes = await db._makeRequest(`/${model}('${id}')`, {
             method: "PATCH",
-            body: update,
+            body: JSON.stringify(update),
           });
           logger.debug("PATCH RES", patchRes.data);
           if (patchRes.error) {
@@ -346,32 +316,27 @@ export const FileMakerAdapter = (_config: FileMakerAdapterConfig = defaultConfig
           }
 
           // Read back the updated record
-          const readBack = await fetch(`/${model}('${id}')`, {
-            method: "GET",
-            output: z.record(z.string(), z.unknown()),
-          });
+          const readBack = await db._makeRequest<Record<string, unknown>>(`/${model}('${id}')`);
           logger.debug("READ BACK", readBack.data);
           return (readBack.data as any) ?? null;
         },
         updateMany: async ({ model, where, update }) => {
           const filter = parseWhere(where);
+
           // Find all ids matching the filter
-          const query = buildQuery({
+          const query = buildQueryString({
             select: [`"id"`],
             filter: filter.length > 0 ? filter : undefined,
           });
 
-          const rows = await fetch(`/${model}${query}`, {
-            method: "GET",
-            output: z.object({ value: z.array(z.object({ id: z.string() })) }),
-          });
+          const rows = await db._makeRequest<{ value: { id: string }[] }>(`/${model}${query}`);
 
           const ids = rows.data?.value?.map((r: any) => r.id) ?? [];
           let updated = 0;
           for (const id of ids) {
-            const res = await fetch(`/${model}('${id}')`, {
+            const res = await db._makeRequest(`/${model}('${id}')`, {
               method: "PATCH",
-              body: update,
+              body: JSON.stringify(update),
             });
             if (!res.error) {
               updated++;
@@ -383,7 +348,15 @@ export const FileMakerAdapter = (_config: FileMakerAdapterConfig = defaultConfig
     },
   });
 
-  // Expose the FileMaker config for CLI access
-  (adapterFactory as any).filemakerConfig = config as FileMakerAdapterConfig;
-  return adapterFactory;
+  // Expose the Database instance for CLI access.
+  // Set on both the factory function (for pre-getAdapter extraction)
+  // and the returned adapter (for post-getAdapter extraction).
+  const originalFactory = adapterFactory;
+  const wrappedFactory = ((options: unknown) => {
+    const adapter = (originalFactory as (opts: unknown) => Record<string, unknown>)(options);
+    adapter.database = db;
+    return adapter;
+  }) as typeof adapterFactory;
+  (wrappedFactory as unknown as { database: Database }).database = db;
+  return wrappedFactory;
 };