better-auth-firestore 1.0.0

package/dist/firestore.d.ts

@@ -0,0 +1,9 @@
+import { type AppOptions } from "firebase-admin/app";
+import { type Firestore } from "firebase-admin/firestore";
+/**
+ * Initialize or reuse a Firestore instance safely (useful in serverless).
+ * If an app with the provided name exists, reuse it; otherwise initialize.
+ */
+export declare function initFirestore(options?: AppOptions & {
+    name?: string;
+}): Firestore;

package/dist/firestore.js

@@ -0,0 +1,16 @@
+import { getApps, initializeApp } from "firebase-admin/app";
+import { getFirestore, initializeFirestore, } from "firebase-admin/firestore";
+/**
+ * Initialize or reuse a Firestore instance safely (useful in serverless).
+ * If an app with the provided name exists, reuse it; otherwise initialize.
+ */
+export function initFirestore(options = {}) {
+    // Reuse existing app by name if exists, otherwise initialize
+    const apps = getApps();
+    const app = options.name
+        ? apps.find((a) => a.name === options.name)
+        : apps[0];
+    if (app)
+        return getFirestore(app);
+    return initializeFirestore(initializeApp(options, options.name));
+}

package/dist/index-utils.d.ts

@@ -0,0 +1,28 @@
+import type { Firestore } from "firebase-admin/firestore";
+import type { NamingStrategy } from "./types";
+export interface FirestoreIndexField {
+    fieldPath: string;
+    order: "ASCENDING" | "DESCENDING";
+}
+export interface FirestoreIndex {
+    collectionGroup: string;
+    queryScope: "COLLECTION" | "COLLECTION_GROUP";
+    fields: FirestoreIndexField[];
+}
+/**
+ * Returns all required Firestore index definitions for Better Auth adapter.
+ * Supports both default and snake_case naming strategies.
+ */
+export declare function getRequiredIndexes(namingStrategy?: NamingStrategy): FirestoreIndex[];
+/**
+ * Creates Firestore indexes programmatically using the Firestore REST API.
+ * Note: Firebase Admin SDK doesn't have direct index creation methods,
+ * so this function provides a helper to format indexes for manual creation
+ * or uses the REST API if credentials are available.
+ *
+ * @param firestore - Firestore instance
+ * @param projectId - Firebase project ID
+ * @param namingStrategy - Naming strategy to use ("default" or "snake_case")
+ * @returns Array of index definitions that can be used to create indexes
+ */
+export declare function createFirestoreIndexes(firestore: Firestore, projectId: string, namingStrategy?: NamingStrategy): Promise<FirestoreIndex[]>;

package/dist/index-utils.js

@@ -0,0 +1,51 @@
+/**
+ * Returns all required Firestore index definitions for Better Auth adapter.
+ * Supports both default and snake_case naming strategies.
+ */
+export function getRequiredIndexes(namingStrategy = "default") {
+    const isSnakeCase = namingStrategy === "snake_case";
+    const collectionName = isSnakeCase
+        ? "verification_tokens"
+        : "verificationTokens";
+    const createdAtField = isSnakeCase ? "created_at" : "createdAt";
+    return [
+        {
+            collectionGroup: collectionName,
+            queryScope: "COLLECTION",
+            fields: [
+                {
+                    fieldPath: "identifier",
+                    order: "ASCENDING",
+                },
+                {
+                    fieldPath: createdAtField,
+                    order: "DESCENDING",
+                },
+            ],
+        },
+    ];
+}
+/**
+ * Creates Firestore indexes programmatically using the Firestore REST API.
+ * Note: Firebase Admin SDK doesn't have direct index creation methods,
+ * so this function provides a helper to format indexes for manual creation
+ * or uses the REST API if credentials are available.
+ *
+ * @param firestore - Firestore instance
+ * @param projectId - Firebase project ID
+ * @param namingStrategy - Naming strategy to use ("default" or "snake_case")
+ * @returns Array of index definitions that can be used to create indexes
+ */
+export async function createFirestoreIndexes(firestore, projectId, namingStrategy = "default") {
+    const indexes = getRequiredIndexes(namingStrategy);
+    // Note: The Firebase Admin SDK doesn't provide direct methods to create indexes.
+    // Indexes must be created via:
+    // 1. Firebase Console (Firestore provides URLs in error messages)
+    // 2. Firebase CLI: `firebase deploy --only firestore:indexes`
+    // 3. Firestore REST API (requires additional authentication)
+    // This function returns the index definitions for reference.
+    // Users should deploy indexes using one of the methods above.
+    console.log(`[Firestore Indexes] ${indexes.length} index definition(s) generated for project: ${projectId}`);
+    console.log(`[Firestore Indexes] Deploy indexes using: firebase deploy --only firestore:indexes`);
+    return indexes;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { firestoreAdapter } from "./firebase-adapter";
+export { initFirestore } from "./firestore";
+export * from "./types";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { firestoreAdapter } from "./firebase-adapter";
+export { initFirestore } from "./firestore";
+export * from "./types";

package/dist/setup.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Generate a Firebase Console URL for creating the required Firestore composite index.
+ * This URL will pre-fill the index creation form with the correct configuration,
+ * similar to the URLs provided in Firestore error messages.
+ *
+ * @param projectId - Your Firebase project ID
+ * @param databaseId - Your Firestore database ID (defaults to "(default)")
+ * @param collectionName - The collection name (defaults to "verification")
+ * @returns A Firebase Console URL with pre-filled index configuration
+ */
+export declare function generateIndexSetupUrl(projectId: string, databaseId?: string, collectionName?: string): string;
+/**
+ * Get the index configuration object for the verification collection.
+ * This can be used to create firestore.indexes.json file.
+ */
+export declare function getIndexConfig(collectionName?: string): {
+    indexes: {
+        collectionGroup: string;
+        queryScope: string;
+        fields: {
+            fieldPath: string;
+            order: string;
+        }[];
+    }[];
+    fieldOverrides: never[];
+};

package/dist/setup.js

@@ -0,0 +1,93 @@
+/**
+ * Generate a Firebase Console URL for creating the required Firestore composite index.
+ * This URL will pre-fill the index creation form with the correct configuration,
+ * similar to the URLs provided in Firestore error messages.
+ *
+ * @param projectId - Your Firebase project ID
+ * @param databaseId - Your Firestore database ID (defaults to "(default)")
+ * @param collectionName - The collection name (defaults to "verification")
+ * @returns A Firebase Console URL with pre-filled index configuration
+ */
+export function generateIndexSetupUrl(projectId, databaseId = "(default)", collectionName = "verification") {
+    // For protobuf, use the original format (keep (default) as-is)
+    const protobufDatabaseId = databaseId;
+    // Construct the index resource path for protobuf
+    // Format: projects/{projectId}/databases/{databaseId}/collectionGroups/{collectionName}/indexes/
+    const indexPath = `projects/${projectId}/databases/${protobufDatabaseId}/collectionGroups/${collectionName}/indexes/`;
+    // Build protobuf-encoded message
+    // Based on Firebase's actual error message format:
+    // Field 1 (tag 0x0a, wire type 2): parent path (string)
+    const pathTag = Buffer.from([0x0a]); // Field 1, wire type 2
+    const pathLength = Buffer.from([indexPath.length]);
+    const pathData = Buffer.from(indexPath, "utf8");
+    // Field 2 (tag 0x10, wire type 0): query scope (1 = COLLECTION)
+    const scopeTag = Buffer.from([0x10, 0x01]); // Field 2, value 1
+    // Field 3 (tag 0x1a, wire type 2): fields array - identifier
+    const identifierField = Buffer.concat([
+        Buffer.from([0x1a, 0x0e]), // Field 3, length 14
+        Buffer.from([0x0a, 0x0a]), // Nested field 1, length 10
+        Buffer.from("identifier", "utf8"),
+        Buffer.from([0x10, 0x01]), // Nested field 2, value 1 (ASCENDING)
+    ]);
+    // Field 4 (tag 0x1a, wire type 2): fields array - createdAt
+    const createdAtField = Buffer.concat([
+        Buffer.from([0x1a, 0x0d]), // Field 3, length 13
+        Buffer.from([0x0a, 0x09]), // Nested field 1, length 9
+        Buffer.from("createdAt", "utf8"),
+        Buffer.from([0x10, 0x02]), // Nested field 2, value 2 (DESCENDING)
+    ]);
+    // Field 5 (tag 0x1a, wire type 2): fields array - __name__
+    const nameField = Buffer.concat([
+        Buffer.from([0x1a, 0x0c]), // Field 3, length 12
+        Buffer.from([0x0a, 0x08]), // Nested field 1, length 8
+        Buffer.from("__name__", "utf8"),
+        Buffer.from([0x10, 0x02]), // Nested field 2, value 2 (DESCENDING)
+    ]);
+    // Combine all parts
+    const protobuf = Buffer.concat([
+        pathTag,
+        pathLength,
+        pathData,
+        scopeTag,
+        identifierField,
+        createdAtField,
+        nameField,
+    ]);
+    const createComposite = protobuf.toString("base64");
+    // For default database, omit the database path entirely
+    if (databaseId === "(default)") {
+        return `https://console.firebase.google.com/project/${projectId}/firestore/indexes?create_composite=${createComposite}`;
+    }
+    // For custom databases, include the database path (convert (default) to -default- format)
+    const urlDatabaseId = databaseId === "(default)" ? "-default-" : databaseId;
+    return `https://console.firebase.google.com/project/${projectId}/firestore/databases/${urlDatabaseId}/indexes?create_composite=${createComposite}`;
+}
+/**
+ * Get the index configuration object for the verification collection.
+ * This can be used to create firestore.indexes.json file.
+ */
+export function getIndexConfig(collectionName = "verification") {
+    return {
+        indexes: [
+            {
+                collectionGroup: collectionName,
+                queryScope: "COLLECTION",
+                fields: [
+                    {
+                        fieldPath: "identifier",
+                        order: "ASCENDING",
+                    },
+                    {
+                        fieldPath: "createdAt",
+                        order: "DESCENDING",
+                    },
+                    {
+                        fieldPath: "__name__",
+                        order: "DESCENDING",
+                    },
+                ],
+            },
+        ],
+        fieldOverrides: [],
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+import type { DBAdapterDebugLogOption } from "better-auth/adapters";
+import type { AppOptions } from "firebase-admin/app";
+import type { Firestore } from "firebase-admin/firestore";
+export type NamingStrategy = "snake_case" | "default";
+export interface FirestoreCollectionsOverride {
+    users?: string;
+    sessions?: string;
+    accounts?: string;
+    verificationTokens?: string;
+}
+export interface FirestoreAdapterConfig extends AppOptions {
+    name?: string;
+    firestore?: Firestore;
+    namingStrategy?: NamingStrategy;
+    collections?: FirestoreCollectionsOverride;
+    debugLogs?: DBAdapterDebugLogOption;
+}
+export interface InternalNormalizedConfig {
+    firestore: Firestore;
+    preferSnakeCase: boolean;
+    collections: Required<Required<FirestoreAdapterConfig>["collections"]>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,27 @@
+import type { Firestore } from "firebase-admin/firestore";
+export type FieldMapper = {
+    toDb: (field: string) => string;
+    fromDb: (field: string) => string;
+};
+export declare function mapFieldsFactory(preferSnakeCase?: boolean): FieldMapper;
+export declare function getConverter<Document extends Record<string, any>>(options: {
+    excludeId?: boolean;
+    preferSnakeCase?: boolean;
+}): {
+    toFirestore(object: Document): Record<string, unknown>;
+    fromFirestore(snapshot: FirebaseFirestore.QueryDocumentSnapshot<Document>): Document;
+};
+export declare function getOneDoc<T>(querySnapshot: FirebaseFirestore.Query<T>): Promise<T | null>;
+export declare function getDoc<T>(docRef: FirebaseFirestore.DocumentReference<T>): Promise<T | null>;
+export declare function deleteDocs<T>(querySnapshot: FirebaseFirestore.Query<T>): Promise<void>;
+export declare function collectionsFactory(db: Firestore, preferSnakeCase: boolean | undefined, collections: {
+    users: string;
+    sessions: string;
+    accounts: string;
+    verificationTokens: string;
+}): {
+    users: FirebaseFirestore.CollectionReference<any, FirebaseFirestore.DocumentData>;
+    sessions: FirebaseFirestore.CollectionReference<any, FirebaseFirestore.DocumentData>;
+    accounts: FirebaseFirestore.CollectionReference<any, FirebaseFirestore.DocumentData>;
+    verification_tokens: FirebaseFirestore.CollectionReference<any, FirebaseFirestore.DocumentData>;
+};

package/dist/utils.js

@@ -0,0 +1,78 @@
+import { Timestamp } from "firebase-admin/firestore";
+const MAP_TO_FIRESTORE = {
+    userId: "user_id",
+    sessionToken: "session_token",
+    providerAccountId: "provider_account_id",
+    emailVerified: "email_verified",
+};
+const MAP_FROM_FIRESTORE = Object.fromEntries(Object.entries(MAP_TO_FIRESTORE).map(([k, v]) => [v, k]));
+const identity = (x) => x;
+export function mapFieldsFactory(preferSnakeCase) {
+    if (preferSnakeCase) {
+        return {
+            toDb: (field) => MAP_TO_FIRESTORE[field] ?? field,
+            fromDb: (field) => MAP_FROM_FIRESTORE[field] ?? field,
+        };
+    }
+    return { toDb: identity, fromDb: identity };
+}
+export function getConverter(options) {
+    const mapper = mapFieldsFactory(options?.preferSnakeCase);
+    return {
+        toFirestore(object) {
+            const document = {};
+            for (const key in object) {
+                if (key === "id")
+                    continue;
+                const value = object[key];
+                if (value !== undefined) {
+                    document[mapper.toDb(key)] = value;
+                }
+            }
+            return document;
+        },
+        fromFirestore(snapshot) {
+            const document = snapshot.data();
+            const object = {};
+            if (!options?.excludeId)
+                object.id = snapshot.id;
+            for (const key in document) {
+                let value = document[key];
+                if (value instanceof Timestamp)
+                    value = value.toDate();
+                object[mapper.fromDb(key)] = value;
+            }
+            return object;
+        },
+    };
+}
+export async function getOneDoc(querySnapshot) {
+    const querySnap = await querySnapshot.limit(1).get();
+    return querySnap.docs[0]?.data() ?? null;
+}
+export async function getDoc(docRef) {
+    const docSnap = await docRef.get();
+    return docSnap.data() ?? null;
+}
+export async function deleteDocs(querySnapshot) {
+    const querySnap = await querySnapshot.get();
+    for (const doc of querySnap.docs) {
+        await doc.ref.delete();
+    }
+}
+export function collectionsFactory(db, preferSnakeCase = false, collections) {
+    return {
+        users: db
+            .collection(collections.users)
+            .withConverter(getConverter({ preferSnakeCase })),
+        sessions: db
+            .collection(collections.sessions)
+            .withConverter(getConverter({ preferSnakeCase })),
+        accounts: db
+            .collection(collections.accounts)
+            .withConverter(getConverter({ preferSnakeCase })),
+        verification_tokens: db
+            .collection(collections.verificationTokens)
+            .withConverter(getConverter({ preferSnakeCase, excludeId: true })),
+    };
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "better-auth-firestore",
+  "version": "1.0.0",
+  "private": false,
+  "description": "Firestore adapter for Better Auth (Firebase Admin SDK)",
+  "author": "Slava Yultyyev <yultyyev@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rimraf dist",
+    "test": "./tests/test.sh",
+    "lint": "biome check --formatter-enabled=false",
+    "lint:fix": "biome check --write",
+    "lint:fix:unsafe": "biome check --write --unsafe",
+    "prepublishOnly": "pnpm run build"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@10.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yultyyev/better-auth-firestore.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "better-auth",
+    "firebase",
+    "firestore",
+    "adapter",
+    "authentication"
+  ],
+  "peerDependencies": {
+    "better-auth": "*",
+    "firebase-admin": ">=13",
+    "typescript": "^5.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.2",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/github": "^11.0.1",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^12.1.0",
+    "rimraf": "^6.0.1",
+    "semantic-release": "^24.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.5"
+  }
+}