@prmichaelsen/firebase-admin-sdk-v8 2.0.19 → 2.0.21

package/.github/workflows/e2e-tests.yml

@@ -0,0 +1,50 @@
+name: E2E Tests
+
+on:
+  push:
+    branches: [ mainline ]
+  pull_request:
+    branches: [ mainline ]
+  workflow_dispatch: # Allow manual trigger
+
+jobs:
+  e2e-tests:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Run unit tests
+        run: npm test
+      
+      - name: Create service account file
+        run: |
+          echo '${{ secrets.FIREBASE_SERVICE_ACCOUNT }}' > service-account.json
+      
+      - name: Run e2e tests with coverage
+        run: npm run test:e2e -- --coverage
+        env:
+          NODE_ENV: test
+      
+      - name: Upload e2e coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage/lcov.info
+          flags: e2etests
+          name: codecov-e2e
+          fail_ci_if_error: false
+      
+      - name: Clean up service account file
+        if: always()
+        run: rm -f service-account.json

package/.github/workflows/test.yml

@@ -0,0 +1,44 @@
+name: Unit Tests
+
+on:
+  push:
+    branches: [ mainline, develop ]
+  pull_request:
+    branches: [ mainline, develop ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Run unit tests
+        run: npm test
+      
+      - name: Run build
+        run: npm run build
+      
+      - name: Upload coverage to Codecov (Node 20 only)
+        if: matrix.node-version == 20
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage/lcov.info
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false

package/README.md

@@ -2,8 +2,11 @@
 
 > Firebase Admin SDK for Cloudflare Workers and edge runtimes using REST APIs
 
-[![npm version](https://img.shields.io/npm/v/firebase-admin-sdk-v8.svg)](https://www.npmjs.com/package/firebase-admin-sdk-v8)
+[![npm version](https://img.shields.io/npm/v/@prmichaelsen/firebase-admin-sdk-v8.svg)](https://www.npmjs.com/package/@prmichaelsen/firebase-admin-sdk-v8)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Unit Tests](https://github.com/prmichaelsen/firebase-admin-sdk-v8/actions/workflows/test.yml/badge.svg)](https://github.com/prmichaelsen/firebase-admin-sdk-v8/actions/workflows/test.yml)
+[![E2E Tests](https://github.com/prmichaelsen/firebase-admin-sdk-v8/actions/workflows/e2e-tests.yml/badge.svg)](https://github.com/prmichaelsen/firebase-admin-sdk-v8/actions/workflows/e2e-tests.yml)
+[![codecov](https://codecov.io/gh/prmichaelsen/firebase-admin-sdk-v8/branch/mainline/graph/badge.svg)](https://codecov.io/gh/prmichaelsen/firebase-admin-sdk-v8)
 
 This library provides Firebase Admin SDK functionality for Cloudflare Workers and other edge runtimes. It uses REST APIs and JWT token generation instead of the Node.js Admin SDK, making it compatible with environments that don't support Node.js.
 
@@ -25,7 +28,7 @@ This library provides Firebase Admin SDK functionality for Cloudflare Workers an
 ## 📦 Installation
 
 ```bash
-npm install firebase-admin-sdk-v8
+npm install @prmichaelsen/firebase-admin-sdk-v8
 ```
 
 ## 🚀 Quick Start
@@ -78,7 +81,7 @@ FIREBASE_PROJECT_ID=your-project-id
 ### 2. Verify ID Tokens
 
 ```typescript
-import { verifyIdToken, getUserFromToken } from 'firebase-admin-sdk-v8';
+import { verifyIdToken, getUserFromToken } from '@prmichaelsen/firebase-admin-sdk-v8';
 
 const authHeader = request.headers.get('authorization');
 const idToken = authHeader?.split('Bearer ')[1];
@@ -94,7 +97,7 @@ try {
 ### 3. Basic Firestore Operations
 
 ```typescript
-import { setDocument, getDocument, updateDocument, FieldValue } from 'firebase-admin-sdk-v8';
+import { setDocument, getDocument, updateDocument, FieldValue } from '@prmichaelsen/firebase-admin-sdk-v8';
 
 // Set a document (create or overwrite)
 await setDocument('users', 'user123', {
@@ -116,7 +119,7 @@ await updateDocument('users', 'user123', {
 ### 4. Advanced Queries
 
 ```typescript
-import { queryDocuments } from 'firebase-admin-sdk-v8';
+import { queryDocuments } from '@prmichaelsen/firebase-admin-sdk-v8';
 
 const activeUsers = await queryDocuments('users', {
   where: [
@@ -397,7 +400,7 @@ export default {
 ### Leaderboard Example
 
 ```typescript
-import { queryDocuments, updateDocument, FieldValue } from 'firebase-admin-sdk-v8';
+import { queryDocuments, updateDocument, FieldValue } from '@prmichaelsen/firebase-admin-sdk-v8';
 
 async function getTopPlayers(limit = 10) {
   return await queryDocuments('players', {
@@ -418,7 +421,7 @@ async function updatePlayerScore(playerId: string, points: number) {
 ### Bulk Operations Example
 
 ```typescript
-import { batchWrite, FieldValue } from 'firebase-admin-sdk-v8';
+import { batchWrite, FieldValue } from '@prmichaelsen/firebase-admin-sdk-v8';
 
 async function bulkUpdateUsers(userIds: string[], updates: any) {
   const operations = userIds.map(userId => ({
@@ -518,11 +521,132 @@ For better query performance:
 | Firestore Queries | ✅ | where, orderBy, limit, cursors |
 | Firestore Batch | ✅ | Up to 500 operations |
 | Firestore Transactions | ❌ | Not yet implemented |
+| **Realtime Listeners** | **❌** | **See explanation below** |
 | Field Values | ✅ | increment, arrayUnion, serverTimestamp, etc. |
 | Realtime Database | ❌ | Not planned |
 | Cloud Storage | ❌ | Not yet implemented |
 | Cloud Messaging | ❌ | Not yet implemented |
 
+## ⚠️ Realtime Listeners Not Supported
+
+This library **does not support** Firestore realtime listeners (`onSnapshot()`). Here's why:
+
+### Technical Limitation
+
+**This library uses the Firestore REST API**, which is:
+- ✅ Stateless (request/response only)
+- ✅ Compatible with edge runtimes (Cloudflare Workers, Vercel Edge)
+- ❌ **No persistent connections**
+- ❌ **No server-push capabilities**
+- ❌ **No streaming support**
+
+**Realtime listeners require**:
+- Persistent connections (WebSocket or gRPC)
+- Bidirectional streaming
+- Server-push architecture
+
+The Firestore REST API simply doesn't provide these capabilities.
+
+### Why Not Implement gRPC?
+
+While Firestore does offer a gRPC API with streaming support, implementing it would require:
+
+1. **Complex Protocol Implementation**
+   - HTTP/2 framing
+   - gRPC message framing
+   - Protobuf encoding/decoding
+   - Authentication flow
+   - Reconnection logic
+   - ~100+ hours of development
+
+2. **Runtime Limitations**
+   - Cloudflare Workers doesn't support full gRPC (only gRPC-Web)
+   - gRPC-Web requires a proxy server
+   - Can't connect directly to Firestore's gRPC endpoint
+   - Would only work in Durable Objects, not regular Workers
+
+3. **Maintenance Burden**
+   - Must keep up with Firestore protocol changes
+   - Complex debugging and error handling
+   - High ongoing maintenance cost
+
+### Alternatives
+
+If you need realtime updates, consider these approaches:
+
+#### 1. **Polling (Simple)**
+```typescript
+// Poll for changes every 5 seconds
+setInterval(async () => {
+  const doc = await getDocument('users', 'user123');
+  // Handle updates
+}, 5000);
+```
+
+**Pros**: Simple, works everywhere
+**Cons**: 5-second delay, polling costs
+
+#### 2. **Durable Objects + Polling (Better)**
+```typescript
+// Durable Object polls once, broadcasts to many clients
+export class FirestoreSync {
+  async poll() {
+    const doc = await getDocument('users', 'user123');
+    // Broadcast to all connected WebSocket clients
+    for (const ws of this.sessions) {
+      ws.send(JSON.stringify(doc));
+    }
+  }
+}
+```
+
+**Pros**: One poll serves many clients, WebSocket push to clients
+**Cons**: Still polling-based, Cloudflare-specific
+
+#### 3. **Hybrid Architecture (Best)**
+```typescript
+// Use firebase-admin-node for realtime in Node.js
+import admin from 'firebase-admin';
+
+admin.firestore().collection('users').doc('user123')
+  .onSnapshot((snapshot) => {
+    // True realtime updates
+    console.log('Update:', snapshot.data());
+  });
+
+// Use this library for CRUD in edge functions
+import { getDocument } from '@prmichaelsen/firebase-admin-sdk-v8';
+const doc = await getDocument('users', 'user123');
+```
+
+**Pros**: True realtime where needed, edge performance for CRUD
+**Cons**: Requires separate Node.js service
+
+#### 4. **Firebase Client SDK (Frontend)**
+```typescript
+// Use Firebase Client SDK in browser/mobile
+import { onSnapshot, doc } from 'firebase/firestore';
+
+onSnapshot(doc(db, 'users', 'user123'), (snapshot) => {
+  console.log('Update:', snapshot.data());
+});
+```
+
+**Pros**: True realtime, built-in, well-supported
+**Cons**: Client-side only, requires Firebase Auth
+
+### Recommendation
+
+- **For edge runtimes**: Use polling or Durable Objects pattern
+- **For true realtime**: Use `firebase-admin-node` in Node.js
+- **For client apps**: Use Firebase Client SDK
+- **For hybrid**: Use this library for CRUD + Node.js for realtime
+
+### Related
+
+- [firebase-admin-node](https://github.com/firebase/firebase-admin-node) - Full Admin SDK with realtime support
+- [Firebase Client SDK](https://firebase.google.com/docs/firestore/query-data/listen) - Client-side realtime listeners
+
 ## 🗺️ Roadmap
 
 - [ ] Custom token creation

package/package.json

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

package/firebase.json

@@ -1,9 +0,0 @@
-{
-  "projects": {
-    "default": "prmichaelsen-firebase-e2e"
-  },
-  "firestore": {
-    "rules": "firestore.rules",
-    "indexes": "firestore.indexes.json"
-  }
-}

package/firestore.indexes.json

@@ -1,33 +0,0 @@
-{
-  "indexes": [
-    {
-      "collectionGroup": "e2e-tests",
-      "queryScope": "COLLECTION",
-      "fields": [
-        {
-          "fieldPath": "_test",
-          "order": "ASCENDING"
-        },
-        {
-          "fieldPath": "age",
-          "order": "ASCENDING"
-        }
-      ]
-    },
-    {
-      "collectionGroup": "messages",
-      "queryScope": "COLLECTION",
-      "fields": [
-        {
-          "fieldPath": "_test",
-          "order": "ASCENDING"
-        },
-        {
-          "fieldPath": "timestamp",
-          "order": "ASCENDING"
-        }
-      ]
-    }
-  ],
-  "fieldOverrides": []
-}

package/firestore.rules

@@ -1,11 +0,0 @@
-rules_version = '2';
-
-service cloud.firestore {
-  match /databases/{database}/documents {
-    // Allow all reads and writes for testing
-    // WARNING: These rules are for testing only!
-    match /{document=**} {
-      allow read, write: if true;
-    }
-  }
-}

package/jest.config.js

@@ -1,12 +0,0 @@
-module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  roots: ['<rootDir>/src'],
-  testMatch: ['**/*.spec.ts'],
-  moduleFileExtensions: ['ts', 'js'],
-  collectCoverageFrom: [
-    'src/**/*.ts',
-    '!src/**/*.d.ts',
-    '!src/**/*.spec.ts',
-  ],
-};

package/jest.e2e.config.js

@@ -1,14 +0,0 @@
-module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  testMatch: ['**/*.e2e.ts'],
-  testTimeout: 30000, // 30 seconds for real API calls
-  roots: ['<rootDir>/src'],
-  collectCoverageFrom: [
-    'src/**/*.ts',
-    '!src/**/*.spec.ts',
-    '!src/**/*.e2e.ts',
-    '!src/types.ts',
-    '!src/index.ts',
-  ],
-};

package/service-account.json

@@ -1,13 +0,0 @@
-{
-  "type": "service_account",
-  "project_id": "prmichaelsen-firebase-e2e",
-  "private_key_id": "84caabb8515ec5fab4caa53a0f85405c270d5cd4",
-  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC/0n8V7m7vCQ9/\n5FGYL5V20pQxliUMF/ycNBSV/xHrXAvTMxyMEjFK8Tg9sBLdYhuxC488lnwm3/o+\nn5JkckQ2AyzXX6mi+camwxdLXmT97kXqdFLisO4PY7Fv6HvvMgRQqysj7aJkyiz7\nrAs0DpQq1L70sBFdVLiScPH9FFnuV0EeyOTuVgYwGYk1L76/U7bb3WLNCmcmtG+Y\nt4BNzyMqFgtIdXCQFVBQf9HXy3x5xk8a1rrkf7pEuiwK0PXCDIVH7GYX4xCiQ1qs\nYF4IunNFhcwu1hk5XTIDSVrIn/qLPMZvEcBqHxIJd5JvePjx5hPP81b1mrGUVske\nsaRimjxxAgMBAAECggEAAWNKVG7KslkMRH5y5q56yYbMLVsAPp5SehDYZfNtU5jG\nucr2CxS7SDxcOKS0UOdmUDlyBQaztED3mbS5hZeGuHtSZjvaHtnpdDMXe+NIHhw3\nY520LHwKOjtG69/bPFz4x1qjBRoG4Zgi4NlFpXqbhinO4zdTkNYi6xBSd+R0oshP\nSo59lQvs8e3bMD4f4uTl7JxUifjVM64R3gCkH6AbGqU01wg8UzsllCf0fQM04w8i\nq1oVjhBVWYYVE7w2H+EU+LdiRSRET+Vrk5dtBL3vI6yckvGmxTBMnkK2gTFAAR6F\nnN4NKlUsiFol9WVRY3tdRNOnStjlORDyerSEFQaqhwKBgQDfAa5ddxBVbxUS3E2a\nnGJRA44fYlRyZf9KnJdz8uWsCvuG7UYbe2bp7TxlpEXdTG6Vqu/hhYWd/msmhupZ\nc+YFg1HWE1Ee+nQv7iwAD+okfncnKGIC65XjwaSEMRGrmtxBL6Qq4yxn/Yug/8YR\nniGRQKuMtJ2ZA0p41vI6Mkt7kwKBgQDcM7eQQ5482FcXuOfUlPoiWnd+pF5mNrU1\ngKoxdsXMYRKyTGMPLrOKqsf6kisQUlA48vWRCQOa9QBSjHktfOt2EZ3mNQz5k3AR\n/dIjCGf+ATr2P9Sc0uo7sA20XB62wmG+t2A/vxf9WzBAgdDk6nENB4nz6lL9xcak\ngvVt2vXSawKBgQCV6JRk4f/J3oVFC3DjaRKyMPid4kSwLh6B8mfhGrwHfc59cgz5\ntmeFAuPh057fV1zTIXhlmpMqlPdEi9cHUOCkfhVKGewjLetiuPE9DXWxGI5SdVQF\ncIZu9yH3duDRAaXj7/mklteoBAmTrbxg5XLdKKLpUBTM4ihyuNNWCa8yHwKBgCYK\noTnBFMM6NMGaZiKpohTxQBeW2eAar2+QzNZCyKUoWAyJecuTq9zW6Dl3qwzky4sr\nHhVyUzcgAHBCaGTdYehB3t94ZsdvGztgeD8pIp4VJFSKbnaxUVoCbjusdnnoVu6V\ny4D3yHMyn8FlK+uAPQudM835u2CwHEMrhK731uQFAoGBAKO0crVWuY1EP1RLSyLK\nIS3uUgbauBbQlE4ZPBTi84vXCZjN/53obFgkPHJ5tdjxj6C8x58jgHg/Hufyvbib\ngOQQxadM90UBumlzA8lV7A9jvL2ryfop9ketnVO5hPvB4O8iw9Z1R+25FeM9ZFJI\nqmEjiy9Nhmvpvur+FZ85qcRm\n-----END PRIVATE KEY-----\n",
-  "client_email": "firebase-adminsdk-fbsvc@prmichaelsen-firebase-e2e.iam.gserviceaccount.com",
-  "client_id": "103889460014910902622",
-  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
-  "token_uri": "https://oauth2.googleapis.com/token",
-  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
-  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-fbsvc%40prmichaelsen-firebase-e2e.iam.gserviceaccount.com",
-  "universe_domain": "googleapis.com"
-}