nestjs-firebase-admin 0.4.5 → 0.5.6

package/docs/services/admin-service.md

@@ -0,0 +1,99 @@
+# Admin Service
+
+The `AdminService` is the core service that manages the Firebase Admin SDK initialization and configuration. This service is automatically injected when you import the `AdminModule`.
+
+## Features
+
+- Firebase Admin SDK initialization
+- Multiple app instances support
+- Credential management
+- App lifecycle management
+- TypeScript type support
+
+## Usage Example
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { AdminService } from 'nestjs-firebase-admin';
+
+@Injectable()
+export class FirebaseService {
+  constructor(private readonly adminService: AdminService) {}
+
+  // Get the default app instance
+  getApp() {
+    return this.adminService.getApp;
+  }
+
+  // Get all initialized apps
+  getApps() {
+    return this.adminService.getApps;
+  }
+
+  // Delete an app instance
+  async deleteApp(app) {
+    await this.adminService.deleteApp(app);
+  }
+
+  // Get default credentials
+  getDefaultCredentials() {
+    return this.adminService.applicationDefault();
+  }
+
+  // Get the Firebase Admin SDK instance
+  getAdmin() {
+    return this.adminService.admin();
+  }
+}
+```
+
+## Available Methods
+
+| Method | Description | Documentation |
+|--------|-------------|---------------|
+| `getApp` | Gets the default Firebase app instance | [Get App](https://firebase.google.com/docs/reference/admin/node/firebase-admin.app#getapp) |
+| `getApps` | Gets all initialized Firebase apps | [Get Apps](https://firebase.google.com/docs/reference/admin/node/firebase-admin.app#getapps) |
+| `deleteApp(app)` | Deletes a Firebase app instance | [Delete App](https://firebase.google.com/docs/reference/admin/node/firebase-admin.app#deleteapp) |
+| `applicationDefault(httpAgent?)` | Gets default credentials | [Application Default](https://firebase.google.com/docs/reference/admin/node/firebase-admin.credential#applicationdefault) |
+| `admin()` | Gets the Firebase Admin SDK instance | [Admin SDK](https://firebase.google.com/docs/admin/setup) |
+
+## Configuration
+
+The service can be configured through the `AdminModule` using either synchronous or asynchronous registration:
+
+### Synchronous Registration
+
+```ts
+AdminModule.register({
+  credential: {
+    projectId: 'my-project-id',
+    clientEmail: 'my-client-email',
+    privateKey: 'my-private-key',
+  },
+  databaseURL: 'https://my-project-id.firebaseio.com',
+})
+```
+
+### Asynchronous Registration
+
+```ts
+AdminModule.registerAsync({
+  useFactory: async () => ({
+    credential: {
+      projectId: 'my-project-id',
+      clientEmail: 'my-client-email',
+      privateKey: 'my-private-key',
+    },
+    databaseURL: 'https://my-project-id.firebaseio.com',
+  }),
+})
+```
+
+## App Lifecycle
+
+The service manages the lifecycle of Firebase app instances:
+
+1. **Initialization**: Apps are initialized when the module is registered
+2. **Access**: Apps can be accessed through `getApp` or `getApps`
+3. **Cleanup**: Apps can be deleted using `deleteApp`
+4. **Multiple Instances**: Multiple app instances can be managed simultaneously

package/docs/services/auth-service.md

@@ -0,0 +1,123 @@
+# Auth Service
+
+The `AuthService` provides a clean and type-safe interface for managing Firebase Authentication. This service is automatically injected when you import the `AdminModule`.
+
+## Features
+
+- User management (create, read, update, delete)
+- Custom token generation
+- ID token verification
+- Custom claims management
+- User listing and pagination
+- Email and phone number authentication
+- TypeScript type support
+
+## Usage Example
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { AuthService } from 'nestjs-firebase-admin';
+
+@Injectable()
+export class UsersService {
+  constructor(private readonly authService: AuthService) {}
+
+  // Create a new user
+  async createUser(email: string, password: string) {
+    return this.authService.createUser({
+      email,
+      password,
+      emailVerified: false,
+    });
+  }
+
+  // Get user by UID
+  async getUser(uid: string) {
+    return this.authService.getUser(uid);
+  }
+
+  // Update user profile
+  async updateProfile(uid: string, displayName: string, photoURL: string) {
+    return this.authService.updateUser(uid, {
+      displayName,
+      photoURL,
+    });
+  }
+
+  // Set custom claims
+  async setUserRole(uid: string, role: string) {
+    return this.authService.setCustomUserClaims(uid, { role });
+  }
+
+  // Verify ID token
+  async verifyToken(idToken: string) {
+    return this.authService.verifyIdToken(idToken);
+  }
+
+  // List users with pagination
+  async listUsers(pageSize: number = 100) {
+    return this.authService.listUsers(pageSize);
+  }
+}
+```
+
+## Available Methods
+
+| Method | Description | Documentation |
+|--------|-------------|---------------|
+| `createUser(properties)` | Creates a new user | [Create User](https://firebase.google.com/docs/auth/admin/manage-users#create_a_user) |
+| `getUser(uid)` | Gets a user by UID | [Get User](https://firebase.google.com/docs/auth/admin/manage-users#retrieve_user_data) |
+| `getUserByEmail(email)` | Gets a user by email | [Get User by Email](https://firebase.google.com/docs/auth/admin/manage-users#retrieve_user_data) |
+| `getUserByPhoneNumber(phoneNumber)` | Gets a user by phone number | [Get User by Phone](https://firebase.google.com/docs/auth/admin/manage-users#retrieve_user_data) |
+| `updateUser(uid, properties)` | Updates a user's properties | [Update User](https://firebase.google.com/docs/auth/admin/manage-users#update_a_user) |
+| `deleteUser(uid)` | Deletes a user | [Delete User](https://firebase.google.com/docs/auth/admin/manage-users#delete_a_user) |
+| `createCustomToken(uid, claims?)` | Creates a custom token | [Custom Tokens](https://firebase.google.com/docs/auth/admin/create-custom-tokens) |
+| `verifyIdToken(idToken)` | Verifies an ID token | [Verify ID Token](https://firebase.google.com/docs/auth/admin/verify-id-tokens) |
+| `setCustomUserClaims(uid, claims)` | Sets custom claims | [Custom Claims](https://firebase.google.com/docs/auth/admin/custom-claims) |
+| `listUsers(maxResults?, pageToken?)` | Lists users with pagination | [List Users](https://firebase.google.com/docs/auth/admin/manage-users#list_all_users) |
+
+## User Properties
+
+When creating or updating a user, you can specify the following properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `email` | string | The user's email address |
+| `emailVerified` | boolean | Whether the email is verified |
+| `phoneNumber` | string | The user's phone number |
+| `password` | string | The user's password |
+| `displayName` | string | The user's display name |
+| `photoURL` | string | The user's profile photo URL |
+| `disabled` | boolean | Whether the user account is disabled |
+
+## Custom Claims
+
+Custom claims can be used to define user roles and permissions. They are included in the ID token and can be accessed on the client side.
+
+Example:
+
+```ts
+// Set admin role
+await authService.setCustomUserClaims(uid, { role: 'admin' });
+
+// Set multiple roles
+await authService.setCustomUserClaims(uid, { 
+  roles: ['admin', 'editor'],
+  premium: true 
+});
+```
+
+## Token Verification
+
+The service provides methods for token verification and custom token generation:
+
+```ts
+// Verify ID token
+const decodedToken = await authService.verifyIdToken(idToken);
+console.log(decodedToken.uid);
+
+// Create custom token
+const customToken = await authService.createCustomToken(uid, {
+  role: 'admin'
+});
+```

package/docs/services/database-service.md

@@ -0,0 +1,65 @@
+# Database Service
+
+The `DatabaseService` provides a clean and type-safe interface for interacting with the Firebase Realtime Database. This service is automatically injected when you import the `AdminModule`.
+
+## Features
+
+- Full CRUD operations (Create, Read, Update, Delete)
+- TypeScript type support
+- Asynchronous methods with Promises
+- Database reference handling
+- List operations with unique keys
+
+## Usage Example
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { DatabaseService } from 'nestjs-firebase-admin';
+
+@Injectable()
+export class UsersService {
+  constructor(private readonly databaseService: DatabaseService) {}
+
+  // Get data from a path
+  async getUser(userId: string) {
+    return this.databaseService.get<User>(`users/${userId}`);
+  }
+
+  // Set data at a path
+  async createUser(userId: string, userData: User) {
+    await this.databaseService.set(`users/${userId}`, userData);
+  }
+
+  // Update specific fields
+  async updateUser(userId: string, updates: Partial<User>) {
+    await this.databaseService.update(`users/${userId}`, updates);
+  }
+
+  // Remove data
+  async deleteUser(userId: string) {
+    await this.databaseService.remove(`users/${userId}`);
+  }
+
+  // Add to a list
+  async addUser(userData: User) {
+    const newKey = await this.databaseService.push('users', userData);
+    return newKey;
+  }
+
+  // Get a database reference
+  async getUsersRef() {
+    return this.databaseService.ref('users');
+  }
+}
+```
+
+## Available Methods
+
+| Method | Description | Documentation |
+|--------|-------------|---------------|
+| `ref(path)` | Gets a reference to a specific path | [Firebase Ref](https://firebase.google.com/docs/database/admin/retrieve-data#section-queries) |
+| `get<T>(path)` | Retrieves data from a specific path | [Read Data](https://firebase.google.com/docs/database/admin/retrieve-data#section-read-once) |
+| `set<T>(path, data)` | Sets data at a specific path | [Set Data](https://firebase.google.com/docs/database/admin/save-data#section-set) |
+| `update<T>(path, data)` | Updates specific fields at a path | [Update Data](https://firebase.google.com/docs/database/admin/save-data#section-update) |
+| `remove(path)` | Removes data from a specific path | [Delete Data](https://firebase.google.com/docs/database/admin/save-data#section-delete) |
+| `push<T>(path, data)` | Adds data to a list | [Push Data](https://firebase.google.com/docs/database/admin/save-data#section-push) |

package/docs/services/firestore-service.md

@@ -0,0 +1,69 @@
+# Firestore Service
+
+The `FirestoreService` provides a clean and type-safe interface for interacting with Cloud Firestore. This service is automatically injected when you import the `AdminModule`.
+
+## Features
+
+- Full CRUD operations (Create, Read, Update, Delete)
+- TypeScript type support
+- Collection and document management
+- Query support
+- Batch operations
+- Transaction support
+
+## Usage Example
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { FirestoreService } from 'nestjs-firebase-admin';
+
+@Injectable()
+export class UsersService {
+  constructor(private readonly firestoreService: FirestoreService) {}
+
+  // Get a document
+  async getUser(userId: string) {
+    return this.firestoreService.get<User>(`users/${userId}`);
+  }
+
+  // Create or update a document
+  async createUser(userId: string, userData: User) {
+    await this.firestoreService.set(`users/${userId}`, userData);
+  }
+
+  // Update specific fields
+  async updateUser(userId: string, updates: Partial<User>) {
+    await this.firestoreService.update(`users/${userId}`, updates);
+  }
+
+  // Delete a document
+  async deleteUser(userId: string) {
+    await this.firestoreService.delete(`users/${userId}`);
+  }
+
+  // Add a document with auto-generated ID
+  async addUser(userData: User) {
+    return this.firestoreService.add('users', userData);
+  }
+
+  // Query documents
+  async getActiveUsers() {
+    return this.firestoreService.query<User>('users', 
+      (q) => q.where('status', '==', 'active')
+    );
+  }
+}
+```
+
+## Available Methods
+
+| Method | Description | Documentation |
+|--------|-------------|---------------|
+| `collection<T>(path)` | Gets a reference to a collection | [Firestore Collections](https://firebase.google.com/docs/firestore/manage-data/structure-data) |
+| `doc<T>(path)` | Gets a reference to a document | [Firestore Documents](https://firebase.google.com/docs/firestore/manage-data/structure-data) |
+| `get<T>(path)` | Retrieves a document's data | [Read Data](https://firebase.google.com/docs/firestore/query-data/get-data) |
+| `set<T>(path, data, options?)` | Sets a document's data | [Set Data](https://firebase.google.com/docs/firestore/manage-data/add-data) |
+| `update<T>(path, data)` | Updates specific fields | [Update Data](https://firebase.google.com/docs/firestore/manage-data/add-data#update-data) |
+| `delete(path)` | Deletes a document | [Delete Data](https://firebase.google.com/docs/firestore/manage-data/delete-data) |
+| `add<T>(path, data)` | Adds a document with auto-generated ID | [Add Data](https://firebase.google.com/docs/firestore/manage-data/add-data) |
+| `query<T>(path, ...constraints)` | Queries a collection | [Query Data](https://firebase.google.com/docs/firestore/query-data/queries) |

package/docs/services/messaging-service.md

@@ -0,0 +1,87 @@
+# Messaging Service
+
+The `MessagingService` provides a clean and type-safe interface for sending messages through Firebase Cloud Messaging (FCM). This service is automatically injected when you import the `AdminModule`.
+
+## Features
+
+- Send messages to individual devices
+- Send multicast messages to multiple devices
+- Topic messaging
+- Conditional messaging
+- Message customization
+- TypeScript type support
+
+## Usage Example
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { MessagingService } from 'nestjs-firebase-admin';
+
+@Injectable()
+export class NotificationService {
+  constructor(private readonly messagingService: MessagingService) {}
+
+  // Send a message to a single device
+  async sendToDevice(deviceToken: string, title: string, body: string) {
+    await this.messagingService.send({
+      token: deviceToken,
+      notification: {
+        title,
+        body,
+      },
+    });
+  }
+
+  // Send a message to multiple devices
+  async sendToDevices(deviceTokens: string[], title: string, body: string) {
+    await this.messagingService.sendMulticast({
+      tokens: deviceTokens,
+      notification: {
+        title,
+        body,
+      },
+    });
+  }
+
+  // Send a message to a topic
+  async sendToTopic(topic: string, title: string, body: string) {
+    await this.messagingService.send({
+      topic,
+      notification: {
+        title,
+        body,
+      },
+    });
+  }
+
+  // Subscribe devices to a topic
+  async subscribeToTopic(topic: string, deviceTokens: string[]) {
+    await this.messagingService.subscribeToTopic(deviceTokens, topic);
+  }
+
+  // Unsubscribe devices from a topic
+  async unsubscribeFromTopic(topic: string, deviceTokens: string[]) {
+    await this.messagingService.unsubscribeFromTopic(deviceTokens, topic);
+  }
+}
+```
+
+## Available Methods
+
+| Method | Description | Documentation |
+|--------|-------------|---------------|
+| `send(message)` | Sends a message to a device or topic | [Send Messages](https://firebase.google.com/docs/cloud-messaging/send-message) |
+| `sendMulticast(message)` | Sends a message to multiple devices | [Send Multicast](https://firebase.google.com/docs/cloud-messaging/send-message#send-messages-to-multiple-devices) |
+| `subscribeToTopic(tokens, topic)` | Subscribes devices to a topic | [Topic Management](https://firebase.google.com/docs/cloud-messaging/manage-topics) |
+| `unsubscribeFromTopic(tokens, topic)` | Unsubscribes devices from a topic | [Topic Management](https://firebase.google.com/docs/cloud-messaging/manage-topics) |
+
+## Message Types
+
+The service supports various message types:
+
+- **Notification Messages**: Simple messages with title and body
+- **Data Messages**: Custom key-value pairs
+- **Combined Messages**: Both notification and data
+- **Android Messages**: Android-specific configurations
+- **APNS Messages**: iOS-specific configurations
+- **Webpush Messages**: Web-specific configurations

package/docs/testing.md

@@ -0,0 +1,67 @@
+# Testing
+
+This document provides instructions on how to run tests for the `nestjs-firebase-admin` project.
+
+## Prerequisites
+
+Ensure you have the following installed:
+
+- **Node.js**: >= 20
+- **NPM**: >= 10
+
+Install the dependencies:
+
+```bash
+npm install
+```
+
+## Running Tests
+
+### Unit Tests
+
+To run unit tests, use the following command:
+
+```bash
+npm test
+```
+
+### Coverage Tests
+
+To generate a code coverage report, run:
+
+```bash
+npm run test:cov
+```
+
+The coverage report will be available in the `coverage/` directory.
+
+### Watch Mode Tests
+
+To run tests in watch mode, use:
+
+```bash
+npm run test:watch
+```
+
+### Debug Tests
+
+To debug tests, use:
+
+```bash
+npm run test:debug
+```
+
+## Testing Tools
+
+This project uses the following tools for testing:
+
+- **Jest**: A JavaScript testing framework.
+- **@nestjs/testing**: Utilities for testing NestJS applications.
+
+## Mocking
+
+Mock implementations are provided for Firebase services to ensure tests do not make actual calls to Firebase. These mocks are located in the `lib/tests/mocks/` directory.
+
+## Continuous Integration
+
+Tests are automatically run in CI pipelines using GitHub Actions and CircleCI. Refer to the respective configuration files for more details.

package/index.html

@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+    <meta charset="UTF-8">
+    <title>NestJS Firebase Admin</title>
+    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+    <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+    <link rel="icon" type="image/png"
+        href="https://raw.githubusercontent.com/hebertcisco/nestjs-firebase-admin/refs/heads/main/art/logo.png" />
+    <meta name="description"
+        content="NestJS Firebase Admin is a NestJS module that provides a simple and efficient way to integrate Firebase Admin SDK into your NestJS applications.">
+    <meta name="keywords" content="NestJS, Firebase, Admin SDK, Module, Integration">
+    <meta name="author" content="Hebert Cisco">
+    <meta name="theme-color" content="#1E2830">
+</head>
+
+<body>
+    <div id="app"></div>
+    <script>
+        window.$docsify = {
+            name: 'NestJS Firebase Admin',
+            repo: 'hebertcisco/nestjs-firebase-admin',
+            subMaxLevel: 3,
+            loadSidebar: 'docs/_sidebar.md',
+            auto2top: true,
+            subMaxLevel: 3,
+            maxLevel: 3,
+            themeColor: '#1E2830',
+            noCompileLinks: ['benchmarks/.*'],
+            search: {
+                placeholder: 'Search documentation...',
+                maxAge: 86400000,
+                paths: 'auto',
+                placeholder: 'Search',
+                noData: 'No results found!',
+                depth: 6
+            },
+            pagination: {
+                previousText: 'Previous',
+                nextText: 'Next',
+                crossChapter: true,
+                crossChapterText: true
+            },
+            plugins: [
+                function (hook, vm) {
+                    hook.beforeEach(function (content) {
+                        return content + '\n\n---\n\nLast updated: {docsify-updated}';
+                    });
+                }
+            ]
+        }
+    </script>
+    <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/docsify-pagination/dist/docsify-pagination.min.js"></script>
+</body>
+
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nestjs-firebase-admin",
-  "version": "0.4.5",
+  "version": "0.5.6",
   "description": "Firebase Admin SDK for Nestjs",
   "author": "Hebert Cisco",
   "license": "MIT",
@@ -31,9 +31,9 @@
     "postversion": "git push && git push --tags"
   },
   "dependencies": {
-    "@nestjs/common": "10.4.17",
+    "@nestjs/common": "^7.0.0 || ^8.0.0 || ^9.2.1 || ^10.2.1",
     "@nestjs/core": "10.4.13",
-    "@nestjs/platform-express": "10.4.13",
+    "@nestjs/platform-express": "^10.4.17",
     "firebase-admin": "12.7.0",
     "nest-shared": "^5.0.6"
   },
@@ -60,7 +60,7 @@
     "lint-staged": "15.2.10",
     "prettier": "^3.4.2",
     "reflect-metadata": "0.2.2",
-    "release-it": "16.3.0",
+    "release-it": "^19.0.2",
     "rimraf": "5.0.10",
     "rxjs": "7.8.1",
     "supertest": "^7.1.0",

package/dist/modules/admin/admin.service.spec.d.ts

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