@edgedev/firebase 1.2.5 → 1.3.0

package/README.md

@@ -1,13 +1,15 @@
 # @edgedev/firebase
 
-This a collection of vue3 composables of firebase functions
+A Vue 3 / Nuxt 3 Plugin or Nuxt 3 global composable for firebase authentication and firestore.
 
 ### Table of Contents
 **[Installation](#installation)**  
+**[User Management and Collection Permissions](#user-management-and-collection-permissions)**  
 **[Firebase Authentication](#firebase-authentication)**  
 **[Firestore Basic Document Interactions](#firestore-Basic-document-interactions)**  
 **[Firestore Snapshot Listeners](#firestore-snapshot-listeners)**  
-**[Firestore Static Collection Data](#firestore-static-collection-data)** 
+**[Firestore Static Collection Data](#firestore-static-collection-data)**   
+**[Await and response](#await-and-responses)**
 
 # Installation
 
@@ -85,14 +87,197 @@ export default defineNuxtConfig({ ssr: false });
 ```
 
 
-#### After installing as a plugin you will need to include this in <script setup> in any component you want to use EdgeFirebase in:
+#### After installing as a plugin you will need to include this in "script setup" in any component you want to use EdgeFirebase in:
 ```javascript
 <script setup>
 import { inject } from "vue";
 const edgeFirebase = inject("edgeFirebase");
 </script>
 ```
+
+# User Management and Collection Permissions
+
+### Adding a User
+
+Users must be added before they can register with a login and password (the first user in the project will need to be added manual, see the section below "Root permissions and first user").  When adding a user you can pass role and/or special permissions and user meta data.  For more explanations on role and special permssions, see below.
+
+How to add a user:
+
+```javascript
+edgeFirebase.setUser({
+    email: "user@edgemarketingdesign.com",
+    roles: [
+      {
+        collectionPath: "myItems/subitems/things",
+        role: "user"
+      }
+    ],
+    specialPermissions: [
+      {
+        collectionPath: "otherthings",
+        permissions: { assign: false, write: true, read: true, delete: false}
+      }
+    ],
+    meta: { firstName: "John", lastName: "Doe", age: 28 } // This is just an example of meta, it can contain any fields and any number of fields.
+});
+```
+
+
+
+### Register User
+
+After someoene has been added as a user they will need to "self register" to begin using the system.  Only users that have been added already by someone with assign permissions can register.  The function also checks to make sure they aren't already registered.
+
+```javascript
+  edgeFirebase.registerUser({
+    email: "user@edgemarketingdesign.com",
+    password: "Password1234",
+    meta: {
+      firstName: "John",
+      lastName: "Doe"
+    } // This is just an example of meta, it can contain any fields and any number of fields.
+  });
+```
+
+
+
+### Explanation of permissions
+
+- **assign: boolean** - When a user has this permission for a collection they can assign other users to the collection and change permissions for that collection. For a user to be able run setUser, storeCollectionPermisions, storeUserRoles, removeUserRoles, storeUserSpecialPermissions, or removeUserSpecialPermissions, they must have assign access to any of the collection paths passed into those functions.
+- **write: boolean** - Allows a user to write documents to collection
+- **read: boolean** - Allows a user to read documents in a collection
+- **delete: boolean** - Allows a user to delete documents in a collection 
+
+### Collection permissions by role
+
+Each collection (including sub collections) will automatically have permissions keyed by role.  By default each collection and sub collection will receive the following permissions by role when created:
+
+- **admin:** assign: true, write: true, read: true, delete: true
+- **user:** assign: false, write:false, read: false, delete: false
+
+How to change role permissions for a specific collection:
+
+```javascript
+edgeFirebase.storeCollectionPermissions(
+    "myItems/subitems/things",  // Collection path
+    "user", // must be user or admin
+    {
+      assign: false,
+      write: false,
+      read: true,
+      delete: false
+    }
+ );
+```
+
+### User roles for collections
+
+Users are assigned roles based on collection paths.  A role assigned by a collection path that has sub collections will also determine what the user can do on all sub collections or a user can be assigned a role specifically for a sub collection only.  For example if a user is assigned as admin for "myItems/subitems/things" they will only have admin acces to that collection. But if the user is assigned as an admin for "myItems" they will have the admin permissions for "myItems" and all sub collections of "myItems".
+
+How to assign a user a role for a collection:
+
+```javascript
+  edgeFirebase.storeUserRoles(
+    "user@edgemarketingdesign.com",
+    "myItems/subitems/things",
+    "admin"
+  );
+```
+
+Remove a role from a user for a collection:
+
+```javascript
+  edgeFirebase.removeUserRoles(
+    "user@edgemarketingdesign.com",
+    "myItems/subitems/things"
+  );
+```
+
+### Root permissions and first user
+
+You can assign a user access to all collections in the entire project by giving them a role on "-", which is used to define the root collection path.  This would be for someone who is acting like a super admin.   If this is your first user, you will need to manually set them up in the Firstore console. Once a root user is added manually you can use this user to add other "root users" or setup other collections and assign roles to them.
+
+| ![root-collection-roles](./images/root-collection-roles.png) | ![root-user](./images/root-user.jpg) |
+| ------------------------------------------------------------ | ------------------------------------ |
+
+
+
+### User special permissions
+
+If you want to give a user a unique set of permissions for a collection that doesn't match the admin or user roles for that collection you can set "special permissions".
+
+```javascript
+  edgeFirebase.storeUserSpecialPermissions(
+    "user@edgemarketingdesign.com",
+    "myItems/subitems/things",
+    {
+      assign: false,
+      write: true,
+      read: true,
+      delete: true
+    }
+  );
+```
+
+Remove user special permissions:
+
+```javascript
+  edgeFirebase.removeUserSpecialPermissions(
+    "user@edgemarketingdesign.com",
+    "myItems/subitems/things"
+  );
+```
+
+
+
+### Remove user
+
+The remove user function doesn't actually delete the user completely from the system but instead removes all roles and special permissions that the user running the function has assign access for.  In this way the user is "removed" as far as the "assigning user" is concerned but the user will remain a user for collections that the "assign user" doesn't have access to.  
+
+```javascript
+edgeFirebase.removeUser("user@edgemarketingdesign.com");
+```
+
+
+
+### List Users
+
+This will list all users that are members of collections that the user running the function has assign access for, it will list them grouped by collections.
+
+```javascript
+const users = await edgeFirebase.listUsers();
+```
+
+```typescript
+interface usersByCollection {
+  [collectionPath: string]: [user];
+}
+```
+
+```typescript
+interface user {
+  email: string;
+  role: "admin" | "user" | null;
+  specialPermission: permissions | null;
+  userId: string;
+  docId: string;
+  uid: string;
+  last_updated: Date;
+}
+```
+
+
+
+### List Collections with Assign Access
+
+This function will list all collections that the user running it has assign access for. 
+
+```javascript
+const collections = await edgeFirebase.listCollectionsCanAssign();  // returns array of strings (collection paths)
+```
+
 # Firebase Authentication
+
 (currently only sign in with email and password is supported)
 
 If "persistence" is true, login will be saved locally, they can close their browser and when they open they will be logged in automatically.  If "persistence" is false login saved only for the session.
@@ -115,6 +300,27 @@ interface UserDataObject {
   loggedIn: boolean;
   logInError: boolean;
   logInErrorMessage: string;
+  meta: object;
+  roles: role[]; //see role below
+  specialPermissions: specialPermission[]; //see specialPermission bleow
+}
+
+// sub types of UserDataObject:
+interface role {
+  collectionPath: "-" | string; // - is root
+  role: "admin" | "user";
+}
+
+interface specialPermission {
+  collectionPath: "-" | string; // - is root
+  permissions: permissions; // see permissions below
+}
+
+interface permissions {
+  assign: boolean;
+  read: boolean;
+  write: boolean;
+  delete: boolean;
 }
 ```
 The reactive item **edgeFirebase.user.loggedIn** can be used in code or templates to determine if the user is logged in.
@@ -129,7 +335,7 @@ Here is a sample component using the login:
   <div>
     <div v-if="edgeFirebase.user.loggedIn">
       <button @click="edgeFirebase.logOut">Logout</button><br />
-      <AppUsers v-if="edgeFirebase.user.loggedIn" />
+      <ShowThings v-if="edgeFirebase.user.loggedIn" />
     </div>
     <div v-else>
       <input v-model="email" style="width: 400px" type="text" /><br />
@@ -164,8 +370,8 @@ Both adding and updating a document use the same function:  **edgeFirebase.store
 
 ```javascript
 <script setup>
-const addUser = {name: "bob"};
-edgeFirebase.storeDoc("users", addUser);
+const addItem = {title: "Cool Thing"};
+edgeFirebase.storeDoc("myItems", addItem);
 </script>
 ```
 Note: When a document is written to the collection several other keys are added that can be referenced:  **doc_created_at**(timestamp of doc creation), **last_updated**(timestamp document last written), **uid**(the user id of the user that updated or created the document).
@@ -175,7 +381,7 @@ If you want to query a single document from a collection use: **edgeFirebase.get
 ```javascript
 <script setup>
 const docId = "DrJRpDXVsEEqZu0UB8NT";
-const singleDoc = edgeFirebase.getDocData("users", docId);
+const singleDoc = edgeFirebase.getDocData("myItems", docId);
 </script>
 ```
 
@@ -184,7 +390,7 @@ To delete a document use: **edgeFirebase.removeDoc(collectionPath, docId)**
 ```javascript
 <script setup>
 const docId = "DrJRpDXVsEEqZu0UB8NT";
-const singleDoc = edgeFirebase.removeDoc("users", docId);
+const singleDoc = edgeFirebase.removeDoc("myItems", docId);
 </script>
 ```
 
@@ -193,15 +399,15 @@ const singleDoc = edgeFirebase.removeDoc("users", docId);
 To start a snapshot listen on a collection use: **edgeFirebase.startSnapshot(collectionPath)**
 ```javascript
 <script setup>
-edgeFirebase.startSnapshot("users");
+edgeFirebase.startSnapshot("myItems");
 </script>
 ```
 Once you have started a snapshot reactive data for that snapshot will be available with **edgeFirebase.data[collectionPath]**.  Each document in the data object is keyed with the DocumentId from FireStore.
 ```html
 <template>
   <div>
-    <div v-for="item in edgeFirebase.data.users" :key="item">
-      {{ item.name }}
+    <div v-for="item in edgeFirebase.data.myItems" :key="item">
+      {{ item.title }}
     </div>
   </div>
 </template>
@@ -224,17 +430,17 @@ interface FirestoreOrderBy {
 ##### Example with query, sort and limit:
 ```javascript
 <script setup>
-const query = [{field: "name", operator: "==", value="Bob"}];
-const sort = [{ field: "name", direction: "asc" }];
+const query = [{field: "title", operator: "==", value="Cool Thing"}];
+const sort = [{ field: "title", direction: "asc" }];
 const limit = 10;
-edgeFirebase.startSnapshot("users", query, sort, limit);
+edgeFirebase.startSnapshot("myItems", query, sort, limit);
 </setup>
 ```
 ### Stopping a snapshot listener
 To stop listening to a collection use: **edgeFirebase.stopSnapshot(collectionPath)**
 ```javascript
 <script setup>
-edgeFirebase.stopSnapshot("users");
+edgeFirebase.stopSnapshot("myItems");
 </setup>
 ```
 
@@ -242,7 +448,7 @@ edgeFirebase.stopSnapshot("users");
 To get static data from a collection use the Object: **edgeFirebase.SearchStaticData()**. Static search is done from a class to handle pagination better.
 ```javascript
 const staticSearch = new edgeFirebase.SearchStaticData();
-staticSearch.getData("users");
+staticSearch.getData("myItems");
 ```
 After initialized like above... Data will be available from **staticSearch.results.data**
 
@@ -271,7 +477,7 @@ for updating **staticSearch.results.data** the pagination data set.  There are a
 <template>
   <div>
     <div v-for="item in staticSearch.results.data" :key="item">
-      {{ item.name }}
+      {{ item.title }}
     </div>
     <div>
       <button
@@ -294,12 +500,34 @@ for updating **staticSearch.results.data** the pagination data set.  There are a
 <script setup>
 const staticSearch = new edgeFirebase.SearchStaticData();
 
-const query = [{field: "name", operator: "==", value="Bob"}];
-const sort = [{ field: "name", direction: "asc" }];
+const query = [{field: "title", operator: "==", value="Cool Thing"}];
+const sort = [{ field: "title", direction: "asc" }];
 const limit = 10;
 
-staticSearch.getData("users", query, sort, limit);
+staticSearch.getData("myItems", query, sort, limit);
 </script>
 ```
+
+
+# Await and responses
+
+All functions can be used in conjunction with "await" and will return a response that can be used.  
+
+```javascript
+const response = await edgeFirebase.startSnapshot("things");
+```
+
+reponse:
+
+```typescript
+interface actionResponse {
+  success: boolean;
+  message: string;
+}
+```
+
+
+
 ## License
+
 [ISC](https://choosealicense.com/licenses/isc/)