firebase-rest-firestore 1.2.0 → 1.6.0

package/dist/esm/client.js

@@ -0,0 +1,1180 @@
+import { getFirestoreToken } from "./utils/auth";
+import { buildCommitWrite, convertFromFirestoreDocument, convertToFirestoreDocument, convertToFirestoreValue, extractFieldTransforms, } from "./utils/converter";
+import { getFirestoreBasePath } from "./utils/path";
+import { formatPrivateKey } from "./utils/config";
+import { createFirestorePath } from "./utils/path";
+/**
+ * Generate a random 20-character document ID (same alphabet as the Firebase SDKs).
+ */
+function generateAutoId() {
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+    let id = "";
+    for (let i = 0; i < 20; i++) {
+        id += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return id;
+}
+/**
+ * Firestore client class
+ */
+export class FirestoreClient {
+    /**
+     * Constructor
+     * @param config Firestore configuration object
+     */
+    constructor(config) {
+        this.token = null;
+        this.tokenExpiry = 0;
+        this.configChecked = false;
+        this.debug = false;
+        this.config = config;
+        this.pathUtil = createFirestorePath(config, config.debug || false);
+        this.debug = !!config.debug;
+        // Log configuration if debug is enabled
+        if (this.debug) {
+            console.log("Firestore client initialized with config:", JSON.stringify(this.config, null, 2));
+        }
+    }
+    /**
+     * Check configuration parameters
+     * @private
+     */
+    checkConfig() {
+        if (this.configChecked) {
+            return;
+        }
+        // 必須パラメータのチェック
+        const requiredParams = ["projectId"];
+        // Only require auth parameters when not using emulator
+        if (!this.config.useEmulator) {
+            requiredParams.push("privateKey", "clientEmail");
+        }
+        const missingParams = requiredParams.filter(param => !this.config[param]);
+        if (missingParams.length > 0) {
+            throw new Error(`Missing required Firestore configuration parameters: ${missingParams.join(", ")}`);
+        }
+        this.configChecked = true;
+    }
+    /**
+     * Get authentication token (with caching)
+     */
+    async getToken() {
+        // Check settings before operation
+        this.checkConfig();
+        // In emulator mode, we don't need a token
+        if (this.config.useEmulator) {
+            if (this.debug) {
+                console.log("Emulator mode: skipping token generation");
+            }
+            return "emulator-fake-token";
+        }
+        const now = Date.now();
+        // トークンが期限切れか未取得の場合は新しく取得
+        if (!this.token || now >= this.tokenExpiry) {
+            if (this.debug) {
+                console.log("Generating new auth token");
+            }
+            this.token = await getFirestoreToken(this.config);
+            // 50分後に期限切れとする（実際は1時間）
+            this.tokenExpiry = now + 50 * 60 * 1000;
+        }
+        return this.token;
+    }
+    /**
+     * Prepare request headers
+     * @param additionalHeaders Additional headers
+     * @returns Prepared headers object
+     * @private
+     */
+    async prepareHeaders(additionalHeaders = {}) {
+        const headers = {
+            "Content-Type": "application/json",
+            ...additionalHeaders,
+        };
+        // Only add auth token for production environment
+        if (!this.config.useEmulator) {
+            const token = await this.getToken();
+            headers["Authorization"] = `Bearer ${token}`;
+        }
+        else if (this.debug) {
+            console.log("Using emulator mode, skipping authorization header");
+        }
+        return headers;
+    }
+    /**
+     * Build the fully-qualified Firestore reference value for a document path,
+     * e.g. `projects/{projectId}/databases/{databaseId}/documents/{path}`.
+     * Used to encode a DocumentReference without exposing internal path helpers.
+     * @param documentPath Document path (ex: "users/uid/posts/postId")
+     */
+    getReferenceValue(documentPath) {
+        return this.pathUtil.getParentReference(documentPath);
+    }
+    /**
+     * Apply a single write through the `documents:commit` endpoint. This is the
+     * only REST path that supports field transforms (e.g. server timestamps).
+     * @param collectionName Collection path
+     * @param documentId Document ID
+     * @param fields Already-converted Firestore field values
+     * @param transforms Field transforms to apply after the update
+     * @param currentDocument Optional precondition (e.g. `{ exists: false }`)
+     * @private
+     */
+    async commit(collectionName, documentId, fields, transforms, currentDocument) {
+        const documentName = this.pathUtil.getParentReference(`${collectionName}/${documentId}`);
+        const write = buildCommitWrite(documentName, fields, transforms, currentDocument);
+        const url = `${this.pathUtil.getBasePath()}:commit`;
+        if (this.debug) {
+            console.log(`Committing write to: ${url}`, JSON.stringify(write));
+        }
+        const headers = await this.prepareHeaders();
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ writes: [write] }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            if (this.debug) {
+                console.error(`Error response: ${errorText}`);
+            }
+            const error = new Error(`Firestore API error: ${response.statusText || response.status} - ${errorText}`);
+            error.status = response.status;
+            error.alreadyExists =
+                response.status === 409 || /ALREADY_EXISTS/.test(errorText);
+            throw error;
+        }
+    }
+    /**
+     * Commit a write and read the document back, so the resolved transform
+     * values (e.g. the server timestamp) are returned to the caller.
+     * @private
+     */
+    async commitAndRead(collectionName, documentId, fields, transforms, currentDocument) {
+        await this.commit(collectionName, documentId, fields, transforms, currentDocument);
+        const saved = await this.get(collectionName, documentId);
+        if (!saved) {
+            throw new Error(`Document ${collectionName}/${documentId} could not be read back after commit`);
+        }
+        return saved;
+    }
+    /**
+     * Get collection reference
+     * @param path Collection path
+     * @returns CollectionReference instance
+     */
+    collection(path) {
+        // Configuration check is performed at the time of actual operation
+        return new CollectionReference(this, path);
+    }
+    /**
+     * Get document reference
+     * @param path Document path
+     * @returns DocumentReference instance
+     */
+    doc(path) {
+        // Configuration check is performed at the time of actual operation
+        const parts = path.split("/");
+        if (parts.length % 2 !== 0) {
+            throw new Error("Invalid document path. Document path must point to a document, not a collection.");
+        }
+        const collectionPath = parts.slice(0, parts.length - 1).join("/");
+        const docId = parts[parts.length - 1];
+        return new DocumentReference(this, collectionPath, docId);
+    }
+    /**
+     * Get collection group reference
+     * @param path Collection group ID
+     * @returns CollectionGroup instance
+     */
+    collectionGroup(path) {
+        return new CollectionGroup(this, path);
+    }
+    /**
+     * Add document to Firestore
+     * @param collectionName Collection name
+     * @param data Data to add
+     * @returns Added document
+     */
+    async add(collectionName, data) {
+        // Check settings before operation
+        this.checkConfig();
+        if (this.debug) {
+            console.log(`Adding document to collection: ${collectionName}`, data);
+        }
+        // When the data contains field transforms (e.g. serverTimestamp), the
+        // create must go through the commit endpoint with a client-generated ID.
+        const { fields: plainData, transforms } = extractFieldTransforms(data);
+        if (transforms.length > 0) {
+            return this.addWithTransforms(collectionName, plainData, transforms);
+        }
+        const url = this.pathUtil.getCollectionPath(collectionName);
+        const firestoreData = convertToFirestoreDocument(data);
+        if (this.debug) {
+            console.log(`Making request to: ${url}`, firestoreData);
+        }
+        const headers = await this.prepareHeaders();
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(firestoreData),
+        });
+        if (this.debug) {
+            console.log(`Response status: ${response.status}`);
+        }
+        if (!response.ok) {
+            const errorText = await response.text();
+            if (this.debug) {
+                console.error(`Error response: ${errorText}`);
+            }
+            throw new Error(`Firestore API error: ${response.statusText || response.status} - ${errorText}`);
+        }
+        const result = (await response.json());
+        return convertFromFirestoreDocument(result);
+    }
+    /**
+     * Create a document that contains field transforms (e.g. serverTimestamp)
+     * with an auto-generated ID. Uses the commit endpoint with an
+     * `exists: false` precondition and retries on the (astronomically unlikely)
+     * ID collision, mirroring the uniqueness of server-generated IDs.
+     * @private
+     */
+    async addWithTransforms(collectionName, plainData, transforms) {
+        const fields = convertToFirestoreDocument(plainData).fields;
+        const maxAttempts = 5;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const documentId = generateAutoId();
+            try {
+                return await this.commitAndRead(collectionName, documentId, fields, transforms, { exists: false });
+            }
+            catch (error) {
+                const collided = error?.alreadyExists;
+                if (collided && attempt < maxAttempts - 1) {
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw new Error("Failed to generate a unique document ID after multiple attempts");
+    }
+    /**
+     * Get document
+     * @param collectionName Collection name
+     * @param documentId Document ID
+     * @returns Retrieved document (null if it doesn't exist)
+     */
+    async get(collectionName, documentId) {
+        // Check settings before operation
+        this.checkConfig();
+        if (this.debug) {
+            console.log(`Getting document from collection: ${collectionName}, documentId: ${documentId}`);
+        }
+        const url = this.pathUtil.getDocumentPath(collectionName, documentId);
+        if (this.debug) {
+            console.log(`Making request to: ${url}`);
+        }
+        const headers = await this.prepareHeaders();
+        try {
+            const response = await fetch(url, {
+                method: "GET",
+                headers,
+            });
+            if (this.debug) {
+                console.log(`Response status: ${response.status}`);
+            }
+            // Capture response text for debugging
+            const responseText = await response.text();
+            if (this.debug) {
+                console.log(`Response text: ${responseText.substring(0, 200)}${responseText.length > 200 ? "..." : ""}`);
+            }
+            if (response.status === 404) {
+                return null;
+            }
+            if (!response.ok) {
+                throw new Error(`Firestore API error: ${response.statusText || response.status} - ${responseText}`);
+            }
+            // Parse the response text
+            const result = JSON.parse(responseText);
+            return convertFromFirestoreDocument(result);
+        }
+        catch (error) {
+            console.error("Error in get method:", error);
+            throw error;
+        }
+    }
+    /**
+     * Update document
+     * @param collectionName Collection name
+     * @param documentId Document ID
+     * @param data Data to update
+     * @returns Updated document
+     */
+    async update(collectionName, documentId, data) {
+        // Check settings before operation
+        this.checkConfig();
+        if (this.debug) {
+            console.log(`Updating document in collection: ${collectionName}, documentId: ${documentId}`, data);
+        }
+        const url = this.pathUtil.getDocumentPath(collectionName, documentId);
+        if (this.debug) {
+            console.log(`Making request to: ${url}`);
+        }
+        // Get existing document and merge
+        const existingDoc = await this.get(collectionName, documentId);
+        if (existingDoc) {
+            // Check for nested fields
+            // Check if data contains dot notation keys (e.g., "favorites.color")
+            const updateData = { ...data };
+            const dotNotationKeys = Object.keys(data).filter(key => key.includes("."));
+            if (dotNotationKeys.length > 0) {
+                // スプレッド演算子でコピーして元のオブジェクトを変更しないようにする
+                const result = { ...existingDoc };
+                // 通常のキーを先に適用
+                Object.keys(data)
+                    .filter(key => !key.includes("."))
+                    .forEach(key => {
+                    result[key] = data[key];
+                });
+                // ドット記法のキーを処理
+                dotNotationKeys.forEach(path => {
+                    const parts = path.split(".");
+                    let current = result;
+                    // 最後のパーツ以外をたどってネストしたオブジェクトに到達
+                    for (let i = 0; i < parts.length - 1; i++) {
+                        const part = parts[i];
+                        // パスが存在しない場合は新しいオブジェクトを作成
+                        if (!current[part] || typeof current[part] !== "object") {
+                            current[part] = {};
+                        }
+                        current = current[part];
+                    }
+                    // 最後のパーツに値を設定
+                    const lastPart = parts[parts.length - 1];
+                    current[lastPart] = data[path];
+                    // 元のデータからドット記法のキーを削除
+                    delete updateData[path];
+                });
+                data = result;
+            }
+            else {
+                // 通常のマージ
+                data = { ...existingDoc, ...data };
+            }
+        }
+        // Route writes that contain field transforms (e.g. serverTimestamp)
+        // through the commit endpoint; the merged document is sent as the update.
+        const { fields: plainData, transforms } = extractFieldTransforms(data);
+        if (transforms.length > 0) {
+            const fields = convertToFirestoreDocument(plainData).fields;
+            return this.commitAndRead(collectionName, documentId, fields, transforms);
+        }
+        const firestoreData = convertToFirestoreDocument(data);
+        const headers = await this.prepareHeaders();
+        const response = await fetch(url, {
+            method: "PATCH",
+            headers,
+            body: JSON.stringify(firestoreData),
+        });
+        if (this.debug) {
+            console.log(`Response status: ${response.status}`);
+        }
+        if (!response.ok) {
+            const errorText = await response.text();
+            if (this.debug) {
+                console.error(`Error response: ${errorText}`);
+            }
+            throw new Error(`Firestore API error: ${response.statusText || response.status} - ${errorText}`);
+        }
+        const result = (await response.json());
+        return convertFromFirestoreDocument(result);
+    }
+    /**
+     * Delete document
+     * @param collectionName Collection name
+     * @param documentId Document ID
+     * @returns true if deletion successful
+     */
+    async delete(collectionName, documentId) {
+        // Check settings before operation
+        this.checkConfig();
+        if (this.debug) {
+            console.log(`Deleting document from collection: ${collectionName}, documentId: ${documentId}`);
+        }
+        const url = this.pathUtil.getDocumentPath(collectionName, documentId);
+        if (this.debug) {
+            console.log(`Making request to: ${url}`);
+        }
+        // Different header handling for emulator
+        const headers = {};
+        // Only add auth token for production environment
+        if (!this.config.useEmulator) {
+            const token = await this.getToken();
+            headers["Authorization"] = `Bearer ${token}`;
+        }
+        const response = await fetch(url, {
+            method: "DELETE",
+            headers,
+        });
+        if (this.debug) {
+            console.log(`Response status: ${response.status}`);
+        }
+        if (!response.ok) {
+            const errorText = await response.text();
+            if (this.debug) {
+                console.error(`Error response: ${errorText}`);
+            }
+            throw new Error(`Firestore API error: ${response.statusText || response.status} - ${errorText}`);
+        }
+        return true;
+    }
+    /**
+     * Query documents in a collection
+     * @param collectionPath Collection path
+     * @param options Query options
+     * @param allDescendants Whether to include descendant collections
+     * @returns Array of documents matching the query
+     */
+    async query(collectionPath, options = {}, allDescendants = false) {
+        // Check settings before operation
+        this.checkConfig();
+        try {
+            // Parse the collection path
+            const segments = collectionPath.split("/");
+            const collectionId = segments[segments.length - 1];
+            // Get the proper runQuery URL from our path helper
+            const queryUrl = this.pathUtil.getRunQueryPath(collectionPath);
+            if (this.debug) {
+                console.log(`Executing query on collection: ${collectionPath}`);
+                console.log(`Using runQuery URL: ${queryUrl}`);
+            }
+            // Create the structured query
+            const requestBody = {
+                structuredQuery: {
+                    from: [
+                        {
+                            collectionId,
+                            allDescendants,
+                        },
+                    ],
+                },
+            };
+            // Add where filters if present
+            if (options.where && options.where.length > 0) {
+                // Map our operators to Firestore REST API operators
+                const opMap = {
+                    "==": "EQUAL",
+                    "!=": "NOT_EQUAL",
+                    "<": "LESS_THAN",
+                    "<=": "LESS_THAN_OR_EQUAL",
+                    ">": "GREATER_THAN",
+                    ">=": "GREATER_THAN_OR_EQUAL",
+                    "array-contains": "ARRAY_CONTAINS",
+                    in: "IN",
+                    "array-contains-any": "ARRAY_CONTAINS_ANY",
+                    "not-in": "NOT_IN",
+                };
+                // Single where clause
+                if (options.where.length === 1) {
+                    const filter = options.where[0];
+                    const firestoreOp = opMap[filter.op] || filter.op;
+                    requestBody.structuredQuery.where = {
+                        fieldFilter: {
+                            field: { fieldPath: filter.field },
+                            op: firestoreOp,
+                            value: convertToFirestoreValue(filter.value),
+                        },
+                    };
+                }
+                // Multiple where clauses (AND)
+                else {
+                    requestBody.structuredQuery.where = {
+                        compositeFilter: {
+                            op: "AND",
+                            filters: options.where.map(filter => {
+                                const firestoreOp = opMap[filter.op] || filter.op;
+                                return {
+                                    fieldFilter: {
+                                        field: { fieldPath: filter.field },
+                                        op: firestoreOp,
+                                        value: convertToFirestoreValue(filter.value),
+                                    },
+                                };
+                            }),
+                        },
+                    };
+                }
+            }
+            // Add order by if present
+            if (options.orderBy) {
+                requestBody.structuredQuery.orderBy = [
+                    {
+                        field: { fieldPath: options.orderBy },
+                        direction: options.orderDirection || "ASCENDING",
+                    },
+                ];
+            }
+            // Add limit if present
+            if (options.limit) {
+                requestBody.structuredQuery.limit = options.limit;
+            }
+            // Add offset if present
+            if (options.offset) {
+                requestBody.structuredQuery.offset = options.offset;
+            }
+            if (this.debug) {
+                console.log(`Request payload:`, JSON.stringify(requestBody, null, 2));
+            }
+            // Use the existing prepareHeaders method for authentication consistency
+            const headers = await this.prepareHeaders();
+            const response = await fetch(queryUrl, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(requestBody),
+            });
+            // Collect response for debugging
+            const responseText = await response.text();
+            if (this.debug) {
+                console.log(`API Response:`, responseText);
+            }
+            if (!response.ok) {
+                throw new Error(`Firestore API error: ${response.status} - ${responseText}`);
+            }
+            // Parse the response
+            const results = JSON.parse(responseText);
+            if (this.debug) {
+                console.log(`Results count: ${results?.length || 0}`);
+            }
+            // Process the results
+            if (!Array.isArray(results)) {
+                return [];
+            }
+            const convertedResults = results
+                .filter(item => item.document)
+                .map(item => convertFromFirestoreDocument(item.document));
+            if (this.debug) {
+                console.log(`Converted results:`, convertedResults);
+            }
+            return convertedResults;
+        }
+        catch (error) {
+            console.error("Query execution error:", error);
+            throw error;
+        }
+    }
+    /**
+     * ドキュメントを作成または上書き
+     * @param collectionName コレクション名
+     * @param documentId ドキュメントID
+     * @param data ドキュメントデータ
+     * @returns 作成されたドキュメントのリファレンス
+     */
+    async createWithId(collectionName, documentId, data) {
+        // 操作前に設定をチェック
+        this.checkConfig();
+        // Route writes that contain field transforms (e.g. serverTimestamp)
+        // through the commit endpoint (which creates the document if absent).
+        const { fields: plainData, transforms } = extractFieldTransforms(data);
+        if (transforms.length > 0) {
+            const fields = convertToFirestoreDocument(plainData).fields;
+            return this.commitAndRead(collectionName, documentId, fields, transforms);
+        }
+        const url = `${getFirestoreBasePath(this.config.projectId, this.config.databaseId, this.config)}/${collectionName}/${documentId}`;
+        const firestoreData = convertToFirestoreDocument(data);
+        const token = await this.getToken();
+        const response = await fetch(url, {
+            method: "PATCH",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(firestoreData),
+        });
+        if (!response.ok) {
+            throw new Error(`Firestore API error: ${response.statusText}`);
+        }
+        const result = (await response.json());
+        return convertFromFirestoreDocument(result);
+    }
+}
+/**
+ * Collection reference class
+ */
+export class CollectionReference {
+    constructor(client, path) {
+        this.client = client;
+        this._path = path;
+        this._queryConstraints = {
+            where: [],
+        };
+    }
+    /**
+     * Get collection path
+     */
+    get path() {
+        return this._path;
+    }
+    /**
+     * Whether to include all descendant collections
+     */
+    get allDescendants() {
+        return false;
+    }
+    /**
+     * Get document reference
+     * @param documentPath Document ID (auto-generated if omitted)
+     * @returns DocumentReference instance
+     */
+    doc(documentPath) {
+        const docId = documentPath || this._generateId();
+        return new DocumentReference(this.client, this.path, docId);
+    }
+    /**
+     * Add document (ID is auto-generated)
+     * @param data Document data
+     * @returns Reference to the created document
+     */
+    async add(data) {
+        const result = await this.client.add(this.path, data);
+        const docId = result.id;
+        return new DocumentReference(this.client, this.path, docId);
+    }
+    /**
+     * Add filter condition
+     * @param fieldPath Field path
+     * @param opStr Operator
+     * @param value Value
+     * @returns Query instance
+     */
+    where(fieldPath, opStr, value) {
+        const query = new Query(this.client, this.path, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        // Operator conversion
+        let firestoreOp;
+        switch (opStr) {
+            case "==":
+                firestoreOp = "EQUAL";
+                break;
+            case "!=":
+                firestoreOp = "NOT_EQUAL";
+                break;
+            case "<":
+                firestoreOp = "LESS_THAN";
+                break;
+            case "<=":
+                firestoreOp = "LESS_THAN_OR_EQUAL";
+                break;
+            case ">":
+                firestoreOp = "GREATER_THAN";
+                break;
+            case ">=":
+                firestoreOp = "GREATER_THAN_OR_EQUAL";
+                break;
+            case "array-contains":
+                firestoreOp = "ARRAY_CONTAINS";
+                break;
+            case "in":
+                firestoreOp = "IN";
+                break;
+            case "array-contains-any":
+                firestoreOp = "ARRAY_CONTAINS_ANY";
+                break;
+            case "not-in":
+                firestoreOp = "NOT_IN";
+                break;
+            default:
+                firestoreOp = opStr;
+        }
+        query._queryConstraints.where.push({
+            field: fieldPath,
+            op: firestoreOp,
+            value,
+        });
+        return query;
+    }
+    /**
+     * Add sorting condition
+     * @param fieldPath Field path
+     * @param directionStr Sort direction ('asc' or 'desc')
+     * @returns Query instance
+     */
+    orderBy(fieldPath, directionStr = "asc") {
+        const query = new Query(this.client, this.path, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        query._queryConstraints.orderBy = fieldPath;
+        query._queryConstraints.orderDirection =
+            directionStr === "asc" ? "ASCENDING" : "DESCENDING";
+        return query;
+    }
+    /**
+     * Set limit on number of results
+     * @param limit Maximum number
+     * @returns Query instance
+     */
+    limit(limit) {
+        const query = new Query(this.client, this.path, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        query._queryConstraints.limit = limit;
+        return query;
+    }
+    /**
+     * Set number of documents to skip
+     * @param offset Number to skip
+     * @returns Query instance
+     */
+    offset(offset) {
+        const query = new Query(this.client, this.path, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        query._queryConstraints.offset = offset;
+        return query;
+    }
+    /**
+     * Execute query
+     * @returns QuerySnapshot instance
+     */
+    async get() {
+        const results = await this.client.query(this.path, this._queryConstraints, this.allDescendants);
+        return new QuerySnapshot(results);
+    }
+    /**
+     * Generate random ID
+     * @returns Random ID
+     */
+    _generateId() {
+        return generateAutoId();
+    }
+}
+/**
+ * Document reference class
+ */
+export class DocumentReference {
+    constructor(client, collectionPath, docId) {
+        this.client = client;
+        this.collectionPath = collectionPath;
+        this.docId = docId;
+    }
+    /**
+     * Get document ID
+     */
+    get id() {
+        return this.docId;
+    }
+    /**
+     * Get document path
+     */
+    get path() {
+        return `${this.collectionPath}/${this.docId}`;
+    }
+    /**
+     * Fully-qualified Firestore reference value for this document, e.g.
+     * `projects/{projectId}/databases/{databaseId}/documents/{path}`.
+     */
+    get referenceValue() {
+        return this.client.getReferenceValue(this.path);
+    }
+    /**
+     * Get parent collection reference
+     */
+    get parent() {
+        return new CollectionReference(this.client, this.collectionPath);
+    }
+    /**
+     * Get subcollection
+     * @param collectionPath Subcollection name
+     * @returns CollectionReference instance
+     */
+    collection(collectionPath) {
+        return new CollectionReference(this.client, `${this.path}/${collectionPath}`);
+    }
+    /**
+     * Get document
+     * @returns DocumentSnapshot instance
+     */
+    async get() {
+        const data = await this.client.get(this.collectionPath, this.docId);
+        return new DocumentSnapshot(this.docId, data);
+    }
+    /**
+     * Create or overwrite document
+     * @param data Document data
+     * @param options Options (merge is not currently supported)
+     * @returns WriteResult instance
+     */
+    async set(data, options) {
+        // Get existing document
+        const existingDoc = await this.client.get(this.collectionPath, this.docId);
+        if (existingDoc) {
+            // If existing document exists, update
+            const mergedData = options?.merge ? { ...existingDoc, ...data } : data;
+            await this.client.update(this.collectionPath, this.docId, mergedData);
+        }
+        else {
+            // New creation
+            await this.client.createWithId(this.collectionPath, this.docId, data);
+        }
+        return new WriteResult();
+    }
+    /**
+     * Update document
+     * @param data Update data
+     * @returns WriteResult instance
+     */
+    async update(data) {
+        await this.client.update(this.collectionPath, this.docId, data);
+        return new WriteResult();
+    }
+    /**
+     * Delete document
+     * @returns WriteResult instance
+     */
+    async delete() {
+        await this.client.delete(this.collectionPath, this.docId);
+        return new WriteResult();
+    }
+}
+/**
+ * Collection group
+ */
+export class CollectionGroup {
+    constructor(client, path) {
+        this.client = client;
+        this.path = path;
+        this._queryConstraints = {
+            where: [],
+        };
+    }
+    /**
+     * Whether to include all descendant collections
+     */
+    get allDescendants() {
+        return true;
+    }
+    /**
+     * Add filter condition
+     * @param fieldPath Field path
+     * @param opStr Operator
+     * @param value Value
+     * @returns Query instance
+     */
+    where(fieldPath, opStr, value) {
+        const query = new Query(this.client, this.path, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        // Operator conversion
+        let firestoreOp;
+        switch (opStr) {
+            case "==":
+                firestoreOp = "EQUAL";
+                break;
+            case "!=":
+                firestoreOp = "NOT_EQUAL";
+                break;
+            case "<":
+                firestoreOp = "LESS_THAN";
+                break;
+            case "<=":
+                firestoreOp = "LESS_THAN_OR_EQUAL";
+                break;
+            case ">":
+                firestoreOp = "GREATER_THAN";
+                break;
+            case ">=":
+                firestoreOp = "GREATER_THAN_OR_EQUAL";
+                break;
+            case "array-contains":
+                firestoreOp = "ARRAY_CONTAINS";
+                break;
+            case "in":
+                firestoreOp = "IN";
+                break;
+            case "array-contains-any":
+                firestoreOp = "ARRAY_CONTAINS_ANY";
+                break;
+            case "not-in":
+                firestoreOp = "NOT_IN";
+                break;
+            default:
+                firestoreOp = opStr;
+        }
+        query._queryConstraints.where.push({
+            field: fieldPath,
+            op: firestoreOp,
+            value,
+        });
+        return query;
+    }
+    /**
+     * Add sorting condition
+     * @param fieldPath Field path
+     * @param directionStr Sort direction ('asc' or 'desc')
+     * @returns Query instance
+     */
+    orderBy(fieldPath, directionStr = "asc") {
+        const query = new Query(this.client, this.path, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        query._queryConstraints.orderBy = fieldPath;
+        query._queryConstraints.orderDirection =
+            directionStr === "asc" ? "ASCENDING" : "DESCENDING";
+        return query;
+    }
+    /**
+     * Set limit on number of results
+     * @param limit Maximum number
+     * @returns Query instance
+     */
+    limit(limit) {
+        const query = new Query(this.client, this.path, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        query._queryConstraints.limit = limit;
+        return query;
+    }
+    /**
+     * Set number of documents to skip
+     * @param offset Number to skip
+     * @returns Query instance
+     */
+    offset(offset) {
+        const query = new Query(this.client, this.path, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        query._queryConstraints.offset = offset;
+        return query;
+    }
+    /**
+     * Execute query
+     * @returns QuerySnapshot instance
+     */
+    async get() {
+        const results = await this.client.query(this.path, this._queryConstraints, this.allDescendants);
+        return new QuerySnapshot(results);
+    }
+}
+/**
+ * Query class
+ */
+export class Query {
+    constructor(client, collectionPath, constraints, allDescendants) {
+        this.client = client;
+        this.collectionPath = collectionPath;
+        this._queryConstraints = constraints;
+        this.allDescendants = allDescendants;
+    }
+    /**
+     * Add filter condition
+     * @param fieldPath Field path
+     * @param opStr Operator
+     * @param value Value
+     * @returns Query instance
+     */
+    where(fieldPath, opStr, value) {
+        const query = new Query(this.client, this.collectionPath, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        // Operator conversion
+        let firestoreOp;
+        switch (opStr) {
+            case "==":
+                firestoreOp = "EQUAL";
+                break;
+            case "!=":
+                firestoreOp = "NOT_EQUAL";
+                break;
+            case "<":
+                firestoreOp = "LESS_THAN";
+                break;
+            case "<=":
+                firestoreOp = "LESS_THAN_OR_EQUAL";
+                break;
+            case ">":
+                firestoreOp = "GREATER_THAN";
+                break;
+            case ">=":
+                firestoreOp = "GREATER_THAN_OR_EQUAL";
+                break;
+            case "array-contains":
+                firestoreOp = "ARRAY_CONTAINS";
+                break;
+            case "in":
+                firestoreOp = "IN";
+                break;
+            case "array-contains-any":
+                firestoreOp = "ARRAY_CONTAINS_ANY";
+                break;
+            case "not-in":
+                firestoreOp = "NOT_IN";
+                break;
+            default:
+                firestoreOp = opStr;
+        }
+        query._queryConstraints.where.push({
+            field: fieldPath,
+            op: firestoreOp,
+            value,
+        });
+        return query;
+    }
+    /**
+     * Add sorting condition
+     * @param fieldPath Field path
+     * @param directionStr Sort direction ('asc' or 'desc')
+     * @returns Query instance
+     */
+    orderBy(fieldPath, directionStr = "asc") {
+        const query = new Query(this.client, this.collectionPath, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        query._queryConstraints.orderBy = fieldPath;
+        query._queryConstraints.orderDirection =
+            directionStr === "asc" ? "ASCENDING" : "DESCENDING";
+        return query;
+    }
+    /**
+     * Set limit on number of results
+     * @param limit Maximum number
+     * @returns Query instance
+     */
+    limit(limit) {
+        const query = new Query(this.client, this.collectionPath, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        query._queryConstraints.limit = limit;
+        return query;
+    }
+    /**
+     * Set number of documents to skip
+     * @param offset Number to skip
+     * @returns Query instance
+     */
+    offset(offset) {
+        const query = new Query(this.client, this.collectionPath, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        query._queryConstraints.offset = offset;
+        return query;
+    }
+    /**
+     * Execute query
+     * @returns QuerySnapshot instance
+     */
+    async get() {
+        const results = await this.client.query(this.collectionPath, this._queryConstraints, this.allDescendants);
+        return new QuerySnapshot(results);
+    }
+}
+/**
+ * Query result class
+ */
+export class QuerySnapshot {
+    constructor(results) {
+        this._docs = results.map(doc => {
+            const { id, ...data } = doc;
+            return new DocumentSnapshot(id, data);
+        });
+    }
+    /**
+     * Array of documents in the result
+     */
+    get docs() {
+        return this._docs;
+    }
+    /**
+     * Whether the result is empty
+     */
+    get empty() {
+        return this._docs.length === 0;
+    }
+    /**
+     * Number of results
+     */
+    get size() {
+        return this._docs.length;
+    }
+    /**
+     * Execute callback for each document
+     * @param callback Callback function to execute for each document
+     */
+    forEach(callback) {
+        this._docs.forEach(callback);
+    }
+}
+/**
+ * Document snapshot class
+ */
+export class DocumentSnapshot {
+    constructor(id, data) {
+        this._id = id;
+        this._data = data;
+    }
+    /**
+     * Document ID
+     */
+    get id() {
+        return this._id;
+    }
+    /**
+     * Whether the document exists
+     */
+    get exists() {
+        return this._data !== null;
+    }
+    /**
+     * Get document data
+     * @returns Document data (undefined if it doesn't exist)
+     */
+    data() {
+        return this._data || undefined;
+    }
+}
+/**
+ * Write result class
+ */
+export class WriteResult {
+    constructor() {
+        this.writeTime = new Date();
+    }
+}
+/**
+ * Create a new Firestore client instance
+ * @param config Firestore configuration object
+ * @returns FirestoreClient instance
+ *
+ * @example
+ * // Connect to default database
+ * const db = createFirestoreClient({
+ *   projectId: 'your-project-id',
+ *   privateKey: 'your-private-key',
+ *   clientEmail: 'your-client-email'
+ * });
+ *
+ * // Connect to a different named database
+ * const customDb = createFirestoreClient({
+ *   projectId: 'your-project-id',
+ *   privateKey: 'your-private-key',
+ *   clientEmail: 'your-client-email',
+ *   databaseId: 'your-database-id'
+ * });
+ *
+ * // Connect to local emulator (no auth required)
+ * const emulatorDb = createFirestoreClient({
+ *   projectId: 'demo-project',
+ *   useEmulator: true,
+ *   emulatorHost: '127.0.',
+ *   emulatorPort: 8080,
+ *   debug: true // Optional: enables detailed logging
+ * });
+ */
+export function createFirestoreClient(config) {
+    // Check private key format
+    if (config.privateKey) {
+        config = {
+            ...config,
+            privateKey: formatPrivateKey(config.privateKey),
+        };
+    }
+    return new FirestoreClient(config);
+}