@prmichaelsen/firebase-admin-sdk-v8 2.2.0 → 2.2.2

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Collection iteration functions: `listDocuments()`, `iterateCollection()`, and `countDocuments()`
+- Automatic pagination support for large collections
+- Support for iterating with filters and ordering
+
+### Changed
+- **BREAKING**: `fromFirestoreValue()` now throws an error for unknown Firestore value types instead of returning `null`
+- Removed debug console.log statements from production code in `auth.ts`
+
+### Fixed
+- Silent failures in Firestore data conversion now throw descriptive errors
+
+## [2.2.1] - 2026-02-12
+
+### Added
+- Modular Firestore architecture with separate modules for converters, operations, query-builder, transforms, and path-validation
+- Comprehensive path validation for Firestore operations
+- Support for subcollection queries
+
+### Changed
+- Refactored Firestore implementation into modular structure
+- Improved error messages for path validation
+
+### Fixed
+- Subcollection query support using correct REST API endpoints
+- Path validation for nested collections
+
+## [2.2.0] - Previous Release
+
+### Added
+- Firebase Storage support with signed URLs
+- Custom token creation and sign-in
+- Support for Firebase v10 session tokens
+- Field transforms (serverTimestamp, increment, arrayUnion, arrayRemove, delete)
+- Batch write operations
+- Advanced query support (where, orderBy, limit)
+
+### Changed
+- Improved token verification to support both v9 and v10 token formats
+- Enhanced error handling across all modules
+
+### Fixed
+- Public key caching and rotation handling
+- Token verification for multiple issuer formats
+
+## [2.1.0] - Initial Release
+
+### Added
+- Core Firebase Admin SDK functionality for Cloudflare Workers
+- Authentication with ID token verification
+- Firestore CRUD operations via REST API
+- Service account configuration
+- X.509 certificate handling
+- JWT token generation

package/README.md

@@ -514,8 +514,9 @@ For better query performance:
 
 | Feature | Supported | Notes |
 |---------|-----------|-------|
-| ID Token Verification | ✅ | Via firebase-auth-cloudflare-workers |
-| Custom Token Creation | ❌ | Not yet implemented |
+| ID Token Verification | ✅ | Supports v9 and v10 token formats |
+| Custom Token Creation | ✅ | createCustomToken() |
+| Custom Token Exchange | ✅ | signInWithCustomToken() |
 | User Management | ❌ | Not yet implemented |
 | Firestore CRUD | ✅ | Full support |
 | Firestore Queries | ✅ | where, orderBy, limit, cursors |
@@ -524,7 +525,7 @@ For better query performance:
 | **Realtime Listeners** | **❌** | **See explanation below** |
 | Field Values | ✅ | increment, arrayUnion, serverTimestamp, etc. |
 | Realtime Database | ❌ | Not planned |
-| Cloud Storage | ❌ | Not yet implemented |
+| Cloud Storage | ✅ | Upload, download, delete, signed URLs |
 | Cloud Messaging | ❌ | Not yet implemented |
 
 ## ⚠️ Realtime Listeners Not Supported
@@ -649,10 +650,12 @@ onSnapshot(doc(db, 'users', 'user123'), (snapshot) => {
 
 ## 🗺️ Roadmap
 
-- [ ] Custom token creation
+- [x] Custom token creation ✅ (v2.2.0)
+- [x] Custom token exchange ✅ (v2.2.0)
+- [x] Cloud Storage operations ✅ (v2.2.0)
 - [ ] User management (create, update, delete users)
 - [ ] Firestore transactions
-- [ ] Cloud Storage operations
 - [ ] More comprehensive error handling
 - [ ] Rate limiting helpers
 - [ ] Retry logic for failed operations
+- [ ] Storage unit tests (currently only e2e)

package/dist/index.d.mts

@@ -480,6 +480,114 @@ declare function queryDocuments(collectionPath: string, options?: QueryOptions):
  */
 declare function batchWrite(operations: BatchWrite[]): Promise<BatchWriteResult>;
 
+/**
+ * Firebase Admin SDK v8 - Firestore Collection Iteration
+ * Convenience functions for iterating through collections
+ */
+
+/**
+ * List all documents in a collection
+ * This is a convenience wrapper around queryDocuments with no filters
+ *
+ * @param collectionPath - Collection path
+ * @param options - Query options (limit, orderBy, etc.)
+ * @returns Array of documents with id and data
+ * @throws {Error} If the operation fails
+ *
+ * @example
+ * ```typescript
+ * // List all users
+ * const users = await listDocuments('users');
+ *
+ * // List with pagination
+ * const firstPage = await listDocuments('users', { limit: 10 });
+ * const secondPage = await listDocuments('users', {
+ *   limit: 10,
+ *   startAfter: [firstPage[firstPage.length - 1].data.name]
+ * });
+ * ```
+ */
+declare function listDocuments(collectionPath: string, options?: QueryOptions): Promise<Array<{
+    id: string;
+    data: DataObject;
+}>>;
+/**
+ * Iterate through all documents in a collection
+ * Handles pagination automatically by fetching documents in batches
+ *
+ * @param collectionPath - Collection path
+ * @param callback - Function called for each document
+ * @param options - Iteration options
+ * @throws {Error} If the operation fails
+ *
+ * @example
+ * ```typescript
+ * // Process all messages
+ * await iterateCollection(
+ *   'users/user123/conversations/main/messages',
+ *   async (msg) => {
+ *     console.log('Processing message:', msg.id);
+ *     // Perform operations on each message
+ *   },
+ *   { batchSize: 100 }
+ * );
+ *
+ * // Iterate with ordering
+ * await iterateCollection(
+ *   'users',
+ *   async (user) => {
+ *     console.log('User:', user.data.name);
+ *   },
+ *   {
+ *     batchSize: 50,
+ *     orderBy: [{ field: 'createdAt', direction: 'ASCENDING' }]
+ *   }
+ * );
+ * ```
+ */
+declare function iterateCollection(collectionPath: string, callback: (doc: {
+    id: string;
+    data: DataObject;
+}) => Promise<void>, options?: {
+    batchSize?: number;
+    orderBy?: Array<{
+        field: string;
+        direction: 'ASCENDING' | 'DESCENDING';
+    }>;
+    where?: Array<{
+        field: string;
+        op: any;
+        value: any;
+    }>;
+}): Promise<void>;
+/**
+ * Count documents in a collection
+ * Note: This fetches all documents to count them, which may be expensive for large collections
+ *
+ * @param collectionPath - Collection path
+ * @param options - Query options (where filters)
+ * @returns Number of documents
+ * @throws {Error} If the operation fails
+ *
+ * @example
+ * ```typescript
+ * // Count all users
+ * const totalUsers = await countDocuments('users');
+ *
+ * // Count active users
+ * const activeUsers = await countDocuments('users', {
+ *   where: [{ field: 'active', op: '==', value: true }]
+ * });
+ * ```
+ */
+declare function countDocuments(collectionPath: string, options?: {
+    where?: Array<{
+        field: string;
+        op: any;
+        value: any;
+    }>;
+}): Promise<number>;
+
 /**
  * Firebase Storage client using Google Cloud Storage REST API
  * Compatible with edge runtimes (Cloudflare Workers, Vercel Edge, etc.)
@@ -760,4 +868,4 @@ declare function getAdminAccessToken(): Promise<string>;
  */
 declare function clearTokenCache(): void;
 
-export { type BatchWrite, type BatchWriteResult, type CustomClaims, type CustomTokenSignInResponse, type DataObject, type DecodedIdToken, type DocumentReference, type DownloadOptions, FieldValue, type FieldValue$1 as FieldValueSentinel, FieldValueType, type FileMetadata, type FirestoreDocument, type FirestoreValue, type ListFilesResult, type ListOptions, type QueryFilter, type QueryOptions, type QueryOrder, type ServiceAccount, type SetOptions, type SignedUrlOptions, type TokenResponse, type UpdateOptions, type UploadOptions, type UserInfo, type WhereFilterOp, addDocument, batchWrite, clearConfig, clearTokenCache, createCustomToken, deleteDocument, deleteFile, downloadFile, fileExists, generateSignedUrl, getAdminAccessToken, getAuth, getConfig, getDocument, getFileMetadata, getProjectId, getServiceAccount, getUserFromToken, initializeApp, listFiles, queryDocuments, setDocument, signInWithCustomToken, updateDocument, uploadFile, verifyIdToken };
+export { type BatchWrite, type BatchWriteResult, type CustomClaims, type CustomTokenSignInResponse, type DataObject, type DecodedIdToken, type DocumentReference, type DownloadOptions, FieldValue, type FieldValue$1 as FieldValueSentinel, FieldValueType, type FileMetadata, type FirestoreDocument, type FirestoreValue, type ListFilesResult, type ListOptions, type QueryFilter, type QueryOptions, type QueryOrder, type ServiceAccount, type SetOptions, type SignedUrlOptions, type TokenResponse, type UpdateOptions, type UploadOptions, type UserInfo, type WhereFilterOp, addDocument, batchWrite, clearConfig, clearTokenCache, countDocuments, createCustomToken, deleteDocument, deleteFile, downloadFile, fileExists, generateSignedUrl, getAdminAccessToken, getAuth, getConfig, getDocument, getFileMetadata, getProjectId, getServiceAccount, getUserFromToken, initializeApp, iterateCollection, listDocuments, listFiles, queryDocuments, setDocument, signInWithCustomToken, updateDocument, uploadFile, verifyIdToken };

package/dist/index.d.ts

@@ -480,6 +480,114 @@ declare function queryDocuments(collectionPath: string, options?: QueryOptions):
  */
 declare function batchWrite(operations: BatchWrite[]): Promise<BatchWriteResult>;
 
+/**
+ * Firebase Admin SDK v8 - Firestore Collection Iteration
+ * Convenience functions for iterating through collections
+ */
+
+/**
+ * List all documents in a collection
+ * This is a convenience wrapper around queryDocuments with no filters
+ *
+ * @param collectionPath - Collection path
+ * @param options - Query options (limit, orderBy, etc.)
+ * @returns Array of documents with id and data
+ * @throws {Error} If the operation fails
+ *
+ * @example
+ * ```typescript
+ * // List all users
+ * const users = await listDocuments('users');
+ *
+ * // List with pagination
+ * const firstPage = await listDocuments('users', { limit: 10 });
+ * const secondPage = await listDocuments('users', {
+ *   limit: 10,
+ *   startAfter: [firstPage[firstPage.length - 1].data.name]
+ * });
+ * ```
+ */
+declare function listDocuments(collectionPath: string, options?: QueryOptions): Promise<Array<{
+    id: string;
+    data: DataObject;
+}>>;
+/**
+ * Iterate through all documents in a collection
+ * Handles pagination automatically by fetching documents in batches
+ *
+ * @param collectionPath - Collection path
+ * @param callback - Function called for each document
+ * @param options - Iteration options
+ * @throws {Error} If the operation fails
+ *
+ * @example
+ * ```typescript
+ * // Process all messages
+ * await iterateCollection(
+ *   'users/user123/conversations/main/messages',
+ *   async (msg) => {
+ *     console.log('Processing message:', msg.id);
+ *     // Perform operations on each message
+ *   },
+ *   { batchSize: 100 }
+ * );
+ *
+ * // Iterate with ordering
+ * await iterateCollection(
+ *   'users',
+ *   async (user) => {
+ *     console.log('User:', user.data.name);
+ *   },
+ *   {
+ *     batchSize: 50,
+ *     orderBy: [{ field: 'createdAt', direction: 'ASCENDING' }]
+ *   }
+ * );
+ * ```
+ */
+declare function iterateCollection(collectionPath: string, callback: (doc: {
+    id: string;
+    data: DataObject;
+}) => Promise<void>, options?: {
+    batchSize?: number;
+    orderBy?: Array<{
+        field: string;
+        direction: 'ASCENDING' | 'DESCENDING';
+    }>;
+    where?: Array<{
+        field: string;
+        op: any;
+        value: any;
+    }>;
+}): Promise<void>;
+/**
+ * Count documents in a collection
+ * Note: This fetches all documents to count them, which may be expensive for large collections
+ *
+ * @param collectionPath - Collection path
+ * @param options - Query options (where filters)
+ * @returns Number of documents
+ * @throws {Error} If the operation fails
+ *
+ * @example
+ * ```typescript
+ * // Count all users
+ * const totalUsers = await countDocuments('users');
+ *
+ * // Count active users
+ * const activeUsers = await countDocuments('users', {
+ *   where: [{ field: 'active', op: '==', value: true }]
+ * });
+ * ```
+ */
+declare function countDocuments(collectionPath: string, options?: {
+    where?: Array<{
+        field: string;
+        op: any;
+        value: any;
+    }>;
+}): Promise<number>;
+
 /**
  * Firebase Storage client using Google Cloud Storage REST API
  * Compatible with edge runtimes (Cloudflare Workers, Vercel Edge, etc.)
@@ -760,4 +868,4 @@ declare function getAdminAccessToken(): Promise<string>;
  */
 declare function clearTokenCache(): void;
 
-export { type BatchWrite, type BatchWriteResult, type CustomClaims, type CustomTokenSignInResponse, type DataObject, type DecodedIdToken, type DocumentReference, type DownloadOptions, FieldValue, type FieldValue$1 as FieldValueSentinel, FieldValueType, type FileMetadata, type FirestoreDocument, type FirestoreValue, type ListFilesResult, type ListOptions, type QueryFilter, type QueryOptions, type QueryOrder, type ServiceAccount, type SetOptions, type SignedUrlOptions, type TokenResponse, type UpdateOptions, type UploadOptions, type UserInfo, type WhereFilterOp, addDocument, batchWrite, clearConfig, clearTokenCache, createCustomToken, deleteDocument, deleteFile, downloadFile, fileExists, generateSignedUrl, getAdminAccessToken, getAuth, getConfig, getDocument, getFileMetadata, getProjectId, getServiceAccount, getUserFromToken, initializeApp, listFiles, queryDocuments, setDocument, signInWithCustomToken, updateDocument, uploadFile, verifyIdToken };
+export { type BatchWrite, type BatchWriteResult, type CustomClaims, type CustomTokenSignInResponse, type DataObject, type DecodedIdToken, type DocumentReference, type DownloadOptions, FieldValue, type FieldValue$1 as FieldValueSentinel, FieldValueType, type FileMetadata, type FirestoreDocument, type FirestoreValue, type ListFilesResult, type ListOptions, type QueryFilter, type QueryOptions, type QueryOrder, type ServiceAccount, type SetOptions, type SignedUrlOptions, type TokenResponse, type UpdateOptions, type UploadOptions, type UserInfo, type WhereFilterOp, addDocument, batchWrite, clearConfig, clearTokenCache, countDocuments, createCustomToken, deleteDocument, deleteFile, downloadFile, fileExists, generateSignedUrl, getAdminAccessToken, getAuth, getConfig, getDocument, getFileMetadata, getProjectId, getServiceAccount, getUserFromToken, initializeApp, iterateCollection, listDocuments, listFiles, queryDocuments, setDocument, signInWithCustomToken, updateDocument, uploadFile, verifyIdToken };

package/dist/index.js

@@ -25,6 +25,7 @@ __export(index_exports, {
   batchWrite: () => batchWrite,
   clearConfig: () => clearConfig,
   clearTokenCache: () => clearTokenCache,
+  countDocuments: () => countDocuments,
   createCustomToken: () => createCustomToken,
   deleteDocument: () => deleteDocument,
   deleteFile: () => deleteFile,
@@ -40,6 +41,8 @@ __export(index_exports, {
   getServiceAccount: () => getServiceAccount,
   getUserFromToken: () => getUserFromToken,
   initializeApp: () => initializeApp,
+  iterateCollection: () => iterateCollection,
+  listDocuments: () => listDocuments,
   listFiles: () => listFiles,
   queryDocuments: () => queryDocuments,
   setDocument: () => setDocument,
@@ -228,14 +231,12 @@ async function fetchPublicKeys(issuer) {
   if (publicKeysCache && Date.now() < publicKeysCacheExpiry) {
     return publicKeysCache;
   }
-  console.log(`[fetchPublicKeys] Fetching from: ${endpoint}`);
   const response = await fetch(endpoint);
   if (!response.ok) {
     throw new Error(`Failed to fetch Firebase public keys from ${endpoint}`);
   }
   publicKeysCache = await response.json();
   publicKeysCacheExpiry = Date.now() + 36e5;
-  console.log(`[fetchPublicKeys] Fetched ${Object.keys(publicKeysCache || {}).length} keys`);
   return publicKeysCache;
 }
 function base64UrlDecode(str) {
@@ -311,7 +312,6 @@ async function verifyIdToken(idToken) {
     let publicKeys = await fetchPublicKeys(payload.iss);
     let publicKeyPem = publicKeys[header.kid];
     if (!publicKeyPem) {
-      console.log(`[verifyIdToken] Key ${header.kid} not found in cache, refreshing keys...`);
       publicKeysCache = null;
       publicKeysCacheExpiry = 0;
       publicKeys = await fetchPublicKeys(payload.iss);
@@ -578,7 +578,7 @@ function fromFirestoreValue(value) {
   if ("mapValue" in value) {
     return convertFromFirestoreFormat(value.mapValue.fields || {});
   }
-  return null;
+  throw new Error(`Unknown Firestore value type: ${JSON.stringify(value)}`);
 }
 function convertFromFirestoreFormat(fields) {
   if (!fields) {
@@ -1130,6 +1130,46 @@ async function batchWrite(operations) {
   return await response.json();
 }
 
+// src/firestore/iteration.ts
+async function listDocuments(collectionPath, options) {
+  return queryDocuments(collectionPath, options);
+}
+async function iterateCollection(collectionPath, callback, options) {
+  const batchSize = options?.batchSize || 100;
+  let lastDoc = null;
+  let hasMore = true;
+  while (hasMore) {
+    const queryOptions = {
+      limit: batchSize,
+      orderBy: options?.orderBy,
+      where: options?.where
+    };
+    if (lastDoc && options?.orderBy && options.orderBy.length > 0) {
+      const cursorValues = options.orderBy.map((order) => lastDoc.data[order.field]);
+      queryOptions.startAfter = cursorValues;
+    }
+    const docs = await queryDocuments(collectionPath, queryOptions);
+    for (const doc of docs) {
+      await callback(doc);
+    }
+    hasMore = docs.length === batchSize;
+    if (hasMore && docs.length > 0) {
+      lastDoc = docs[docs.length - 1];
+    }
+  }
+}
+async function countDocuments(collectionPath, options) {
+  let count = 0;
+  await iterateCollection(
+    collectionPath,
+    async () => {
+      count++;
+    },
+    { batchSize: 1e3, where: options?.where }
+  );
+  return count;
+}
+
 // src/storage/client.ts
 var STORAGE_API_BASE = "https://storage.googleapis.com/storage/v1";
 var UPLOAD_API_BASE = "https://storage.googleapis.com/upload/storage/v1";
@@ -1445,6 +1485,7 @@ async function generateSignedUrl(path, options) {
   batchWrite,
   clearConfig,
   clearTokenCache,
+  countDocuments,
   createCustomToken,
   deleteDocument,
   deleteFile,
@@ -1460,6 +1501,8 @@ async function generateSignedUrl(path, options) {
   getServiceAccount,
   getUserFromToken,
   initializeApp,
+  iterateCollection,
+  listDocuments,
   listFiles,
   queryDocuments,
   setDocument,

package/dist/index.mjs

@@ -176,14 +176,12 @@ async function fetchPublicKeys(issuer) {
   if (publicKeysCache && Date.now() < publicKeysCacheExpiry) {
     return publicKeysCache;
   }
-  console.log(`[fetchPublicKeys] Fetching from: ${endpoint}`);
   const response = await fetch(endpoint);
   if (!response.ok) {
     throw new Error(`Failed to fetch Firebase public keys from ${endpoint}`);
   }
   publicKeysCache = await response.json();
   publicKeysCacheExpiry = Date.now() + 36e5;
-  console.log(`[fetchPublicKeys] Fetched ${Object.keys(publicKeysCache || {}).length} keys`);
   return publicKeysCache;
 }
 function base64UrlDecode(str) {
@@ -259,7 +257,6 @@ async function verifyIdToken(idToken) {
     let publicKeys = await fetchPublicKeys(payload.iss);
     let publicKeyPem = publicKeys[header.kid];
     if (!publicKeyPem) {
-      console.log(`[verifyIdToken] Key ${header.kid} not found in cache, refreshing keys...`);
       publicKeysCache = null;
       publicKeysCacheExpiry = 0;
       publicKeys = await fetchPublicKeys(payload.iss);
@@ -526,7 +523,7 @@ function fromFirestoreValue(value) {
   if ("mapValue" in value) {
     return convertFromFirestoreFormat(value.mapValue.fields || {});
   }
-  return null;
+  throw new Error(`Unknown Firestore value type: ${JSON.stringify(value)}`);
 }
 function convertFromFirestoreFormat(fields) {
   if (!fields) {
@@ -1078,6 +1075,46 @@ async function batchWrite(operations) {
   return await response.json();
 }
 
+// src/firestore/iteration.ts
+async function listDocuments(collectionPath, options) {
+  return queryDocuments(collectionPath, options);
+}
+async function iterateCollection(collectionPath, callback, options) {
+  const batchSize = options?.batchSize || 100;
+  let lastDoc = null;
+  let hasMore = true;
+  while (hasMore) {
+    const queryOptions = {
+      limit: batchSize,
+      orderBy: options?.orderBy,
+      where: options?.where
+    };
+    if (lastDoc && options?.orderBy && options.orderBy.length > 0) {
+      const cursorValues = options.orderBy.map((order) => lastDoc.data[order.field]);
+      queryOptions.startAfter = cursorValues;
+    }
+    const docs = await queryDocuments(collectionPath, queryOptions);
+    for (const doc of docs) {
+      await callback(doc);
+    }
+    hasMore = docs.length === batchSize;
+    if (hasMore && docs.length > 0) {
+      lastDoc = docs[docs.length - 1];
+    }
+  }
+}
+async function countDocuments(collectionPath, options) {
+  let count = 0;
+  await iterateCollection(
+    collectionPath,
+    async () => {
+      count++;
+    },
+    { batchSize: 1e3, where: options?.where }
+  );
+  return count;
+}
+
 // src/storage/client.ts
 var STORAGE_API_BASE = "https://storage.googleapis.com/storage/v1";
 var UPLOAD_API_BASE = "https://storage.googleapis.com/upload/storage/v1";
@@ -1392,6 +1429,7 @@ export {
   batchWrite,
   clearConfig,
   clearTokenCache,
+  countDocuments,
   createCustomToken,
   deleteDocument,
   deleteFile,
@@ -1407,6 +1445,8 @@ export {
   getServiceAccount,
   getUserFromToken,
   initializeApp,
+  iterateCollection,
+  listDocuments,
   listFiles,
   queryDocuments,
   setDocument,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prmichaelsen/firebase-admin-sdk-v8",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Firebase Admin SDK for Cloudflare Workers and edge runtimes using REST APIs",
   "main": "dist/index.js",
   "module": "dist/index.mjs",