better-auth-instantdb 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 daveyplate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# Better Auth InstantDB Adapter
+
+A seamless integration between [Better Auth](https://better-auth.com) and [InstantDB](https://www.instantdb.com) that allows you to use InstantDB as your authentication database.
+
+[Better Auth UI Integration](https://better-auth-ui.com/data/instantdb)
+
+- *Own Your Auth*
+
+𝕏 [@daveycodez](https://x.com/daveycodez)
+
+## Installation
+
+```bash
+bun add better-auth-instantdb@latest
+```
+
+## Features
+
+- 🔐 **Complete Authentication**: Leverage Better Auth's authentication features with InstantDB as your database
+- 🔄 **Session Sync**: Automatically synchronize auth sessions between Better Auth and InstantDB
+- 🛠️ **Customizable**: Configure the adapter to match your specific needs
+- 🧩 **Type-Safe**: Fully typed with TypeScript for improved developer experience
+
+## Usage
+
+### Basic Setup
+
+First you need to add the InstantDB Adapter to your Better Auth config.
+
+#### auth.ts
+```typescript
+import { betterAuth } from "better-auth"
+import { instantDBAdapter } from "better-auth-instantdb"
+import { init } from "@instantdb/admin"
+import schema from "@/instant.schema"
+
+// Create InstantDB admin client
+export const adminDb = init({
+  schema,
+  appId: process.env.VITE_INSTANT_APP_ID as string,
+  adminToken: process.env.INSTANT_ADMIN_TOKEN,
+  useDateObjects: true
+})
+
+// Create Better Auth instance with InstantDB adapter
+export const auth = betterAuth({
+  database: instantDBAdapter({
+    db: adminDb,
+    usePlural: true, // Optional: set to true if your schema uses plural table names
+    debugLogs: false  // Optional: set to true to see detailed logs
+  }),
+  // Other Better Auth configuration options
+  emailAndPassword: {
+    enabled: true
+  },
+})
+```
+
+### Client-Side Usage
+
+Synchronize authentication state between Better Auth and InstantDB:
+
+#### providers.tsx
+```typescript
+import authClient from "@/lib/auth-client"
+import { init } from "@instantdb/react"
+import { useInstantAuth } from "better-auth-instantdb"
+
+// Initialize InstantDB client
+const db = init({ 
+    appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID
+})
+
+export function Providers({ children }) {
+  return (
+      <>
+        <InstantAuth db={db} authClient={authClient} persistent />
+
+        {children}
+      </>
+  )
+}
+```
+
+## InstantDB Schema and Permissions Setup
+
+⚠️ **Important**: You can now use Better Auth cli to generate InstantDB schema, but you must manually configure permissions, for now.
+
+### 1. Create Schema File
+
+Run the following command in terminal:
+
+```bash
+npx @better-auth/cli generate
+```
+
+### 2. Create Permissions File
+
+Create an `instant.perms.ts` file to secure your schema:
+
+```typescript
+// instant.perms.ts
+import type { InstantRules } from "@instantdb/react";
+
+const rules = {
+  // Prevent creation of new attributes without explicit schema changes
+  attrs: {
+    allow: {
+      $default: "false",
+    },
+  },
+  // Auth entities permissions
+  users: {
+    bind: ["isOwner", "auth.id != null && auth.id == data.id"],
+    allow: {
+      view: "isOwner",
+      create: "false",
+      delete: "false",
+      update: "isOwner && (newData.email == data.email) && (newData.emailVerified == data.emailVerified) && (newData.createdAt == data.createdAt)",
+    },
+  },
+  accounts: {
+    bind: ["isOwner", "auth.id != null && auth.id == data.userId"],
+    allow: {
+      view: "isOwner",
+      create: "false",
+      delete: "false",
+      update: "false",
+    },
+  },
+  sessions: {
+    bind: ["isOwner", "auth.id != null && auth.id == data.userId"],
+    allow: {
+      view: "isOwner",
+      create: "false",
+      delete: "false",
+      update: "false",
+    },
+  },
+  verifications: {
+    allow: {
+      $default: "false"
+    }
+  },
+  // Optional permissions (public profile example)
+  profiles: {
+    bind: ["isOwner", "auth.id != null && auth.id == data.id"],
+    allow: {
+      view: "true",
+      create: "false",
+      delete: "false",
+      update: "isOwner",
+    },
+  },
+  // Add your custom entity permissions here
+} satisfies InstantRules;
+
+export default rules;
+```
+
+### 3. Push Schema and Permissions to InstantDB
+
+After creating these files, use the InstantDB CLI to push them to your app:
+
+```bash
+# Push schema
+npx instant-cli@latest push schema
+
+# Push permissions
+npx instant-cli@latest push perms
+```
+
+### 4. Initialize InstantDB with Your Schema
+
+Update your client-side InstantDB initialization to use your schema:
+
+#### /database/instant.ts
+```typescript
+import { init } from "@instantdb/react"
+import schema from "../../instant.schema"
+
+export const db = init({
+    appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID,
+    schema
+})
+```
+
+## API Reference
+
+### `instantDBAdapter(options)`
+
+Creates an adapter that allows Better Auth to use InstantDB as its database.
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `db` | `InstantAdminDatabase` | (required) | An InstantDB admin client instance |
+| `usePlural` | `boolean` | `true` | Set to `false` if your schema uses singular table names |
+| `debugLogs` | `boolean` | `false` | Set to `true` to enable detailed logging |
+
+### `useInstantAuth({ db, useSession })`
+
+A React hook that synchronizes authentication state between Better Auth and InstantDB.
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `db` | `InstantReactWebDatabase` | An InstantDB client instance |
+| `authClient` | `AuthClient` | The `authClient` from Better Auth |
+| `persistent` | `boolean?` | Whether to enable offline persistence for session |
+
+## License
+
+MIT

package/dist/adapter/create-schema.d.ts

@@ -0,0 +1,9 @@
+import type { BetterAuthDBSchema } from "@better-auth/core/db";
+/**
+ * Creates InstantDB links from Better Auth schema references
+ */
+export declare function createLinks(tables: BetterAuthDBSchema, usePlural: boolean): Record<string, any>;
+/**
+ * Creates an InstantDB schema file from Better Auth schema format
+ */
+export declare function createSchema(tables: BetterAuthDBSchema, usePlural: boolean): string;

package/dist/adapter/create-schema.js

@@ -0,0 +1,178 @@
+import { fieldNameToLabel } from "../lib/utils";
+/**
+ * Converts a Better Auth field type to InstantDB field type
+ */
+function convertFieldType(field, modelName, fieldKey) {
+    const { type, required, unique, sortable } = field;
+    // Handle type as string or array
+    const typeStr = Array.isArray(type) ? type[0] : type;
+    let fieldType;
+    switch (typeStr) {
+        case "string":
+            fieldType = "i.string()";
+            break;
+        case "boolean":
+            fieldType = "i.boolean()";
+            break;
+        case "date":
+            fieldType = "i.date()";
+            break;
+        case "number":
+            fieldType = "i.number()";
+            break;
+        case "json":
+            fieldType = "i.json()";
+            break;
+        case "number[]":
+            fieldType = "i.json()";
+            break;
+        case "string[]":
+            fieldType = "i.json()";
+            break;
+        default:
+            fieldType = "i.string()"; // Default to string for unknown types
+    }
+    // Apply modifiers
+    if (unique) {
+        fieldType += ".unique()";
+    }
+    // Only make optional if required is explicitly false
+    // If required is true, never make it optional (even if defaultValue exists)
+    if (required === false) {
+        fieldType += ".optional()";
+    }
+    // Add indexed if sortable
+    if (sortable) {
+        fieldType += ".indexed()";
+    }
+    // For user model, ensure all fields except email end with optional()
+    if (modelName === "user" &&
+        fieldKey !== "email" &&
+        !fieldType.endsWith(".optional()")) {
+        fieldType += ".optional()";
+    }
+    return fieldType;
+}
+/**
+ * Gets the InstantDB entity name for a given model name
+ */
+function getEntityName(modelName, tableKey, usePlural) {
+    if (modelName === "user") {
+        return "$users";
+    }
+    return usePlural ? `${tableKey}s` : tableKey;
+}
+/**
+ * Converts a table/model name to camelCase for link names
+ */
+function toCamelCase(str) {
+    return str.charAt(0).toLowerCase() + str.slice(1);
+}
+/**
+ * Creates InstantDB links from Better Auth schema references
+ */
+export function createLinks(tables, usePlural) {
+    const links = {};
+    const entityNameMap = {};
+    // First pass: build entity name mapping
+    for (const [key, table] of Object.entries(tables)) {
+        const { modelName } = table;
+        entityNameMap[modelName] = getEntityName(modelName, key, usePlural);
+    }
+    // Second pass: find all references and create links
+    for (const [key, table] of Object.entries(tables)) {
+        const { modelName, fields } = table;
+        const sourceEntityName = getEntityName(modelName, key, usePlural);
+        for (const [fieldKey, field] of Object.entries(fields)) {
+            const { references } = field;
+            if (references) {
+                const { model: targetModel, onDelete } = references;
+                const targetEntityName = entityNameMap[targetModel];
+                if (!targetEntityName) {
+                    console.warn(`Warning: Could not find entity name for model "${targetModel}" referenced by ${modelName}.${fieldKey}`);
+                    continue;
+                }
+                // Generate forward label from field name, using target model if field doesn't end with "id"
+                const forwardLabel = fieldNameToLabel(fieldKey, targetModel);
+                // Generate link name: {sourceTable}{forwardLabel}
+                // e.g., "invitations" + "Inviter" -> "invitationsInviter"
+                const sourceTableName = sourceEntityName.replace("$", "");
+                const forwardLabelCapitalized = forwardLabel.charAt(0).toUpperCase() +
+                    toCamelCase(forwardLabel.slice(1));
+                const linkName = `${sourceTableName}${forwardLabelCapitalized}`;
+                // Generate reverse label (use source entity name without $ prefix)
+                const reverseLabel = sourceEntityName.replace("$", "");
+                // Create link definition
+                links[linkName] = {
+                    forward: {
+                        on: sourceEntityName,
+                        has: "one",
+                        label: forwardLabel,
+                        onDelete: onDelete || "cascade"
+                    },
+                    reverse: {
+                        on: targetEntityName,
+                        has: "many",
+                        label: reverseLabel
+                    }
+                };
+            }
+        }
+    }
+    return links;
+}
+/**
+ * Creates an InstantDB schema file from Better Auth schema format
+ */
+export function createSchema(tables, usePlural) {
+    const entities = {};
+    for (const [key, table] of Object.entries(tables)) {
+        const { modelName, fields } = table;
+        // For other tables, use the key as entity name
+        const entityFields = [];
+        for (const [fieldKey, field] of Object.entries(fields)) {
+            const fieldType = convertFieldType(field, modelName, fieldKey);
+            entityFields.push(`${fieldKey}: ${fieldType}`);
+        }
+        // Pluralize table name if usePlural is true
+        const namespace = modelName === "user" ? "$users" : usePlural ? `${key}s` : key;
+        entities[namespace] =
+            `i.entity({\n      ${entityFields.join(",\n      ")}\n    })`;
+    }
+    // Generate links from references
+    const links = createLinks(tables, usePlural);
+    // Generate the schema file content
+    const entitiesString = Object.entries(entities)
+        .map(([name, definition]) => `    ${name}: ${definition}`)
+        .join(",\n");
+    // Format links as string
+    const linksString = Object.entries(links)
+        .map(([linkName, linkDef]) => {
+        const forward = linkDef.forward;
+        const reverse = linkDef.reverse;
+        return `    ${linkName}: {
+      forward: {
+        on: "${forward.on}",
+        has: "${forward.has}",
+        label: "${forward.label}"${forward.onDelete ? `,\n        onDelete: "${forward.onDelete}"` : ""}
+      },
+      reverse: {
+        on: "${reverse.on}",
+        has: "${reverse.has}",
+        label: "${reverse.label}"
+      }
+    }`;
+    })
+        .join(",\n");
+    const linksSection = linksString ? `,\n  links: {\n${linksString}\n  }` : "";
+    return `// Docs: https://www.instantdb.com/docs/modeling-data
+
+import { i } from "@instantdb/react"
+
+export const authSchema = i.schema({
+  entities: {
+${entitiesString}
+  }${linksSection}
+})
+`;
+}

package/dist/adapter/instant-adapter.d.ts

@@ -0,0 +1,25 @@
+import { type InstantAdminDatabase } from "@instantdb/admin";
+import { type DBAdapterDebugLogOption, type Where } from "better-auth/adapters";
+/**
+ * The InstantDB adapter config options.
+ */
+interface InstantAdapterConfig {
+    /**
+     * The InstantDB admin database instance.
+     */
+    db: InstantAdminDatabase<any, any>;
+    /**
+     * If the table names in the schema are plural.
+     */
+    usePlural?: boolean;
+    /**
+     * Helps you debug issues with the adapter.
+     */
+    debugLogs?: DBAdapterDebugLogOption;
+}
+/**
+ * The InstantDB adapter.
+ */
+export declare const instantAdapter: ({ db, usePlural, debugLogs }: InstantAdapterConfig) => import("better-auth/adapters").AdapterFactory;
+export declare function parseWhere(where?: Where[]): Record<string, unknown>;
+export {};