Merge branch 'master' into kb/add-usage-guide

Co-authored-by: Trent Larson <trent@trentlarson.com>
Reviewed-on: #116
Co-authored-by: trentlarson <trent@trentlarson.com>
Co-committed-by: trentlarson <trent@trentlarson.com>

docs/README.md

@@ -0,0 +1,66 @@
+# TimeSafari Docs
+
+## Generating PDF from Markdown on OSx
+
+This uses Pandoc and BasicTex (LaTeX) Installed through Homebrew.
+
+### Set Up
+
+```bash 
+# See https://daniel.feldroy.com/posts/setting-up-latex-on-mac-os-x
+brew install pandoc
+
+brew install basictex
+
+pandoc keystore-migration.md -o keystore-migration.pdf
+
+# Setting up LaTex packages
+
+# First update tlmgr
+sudo tlmgr update --self
+
+# Then install LaTex packages
+sudo tlmgr install titlesec
+sudo tlmgr install framed
+sudo tlmgr install threeparttable
+sudo tlmgr install wrapfig
+sudo tlmgr install multirow
+sudo tlmgr install enumitem
+sudo tlmgr install bbding
+sudo tlmgr install titling  # Required for the fancy headers used
+sudo tlmgr install tabu
+sudo tlmgr install mdframed
+sudo tlmgr install tcolorbox
+sudo tlmgr install textpos
+sudo tlmgr install import
+sudo tlmgr install varwidth
+sudo tlmgr install needspace
+sudo tlmgr install tocloft  # Required for \tableofcontents generation
+sudo tlmgr install ntheorem
+sudo tlmgr install environ
+sudo tlmgr install trimspaces
+sudo tlmgr install lastpage  # Enables Page X of Y
+sudo tlmgr install collection-fontsrecommended # And set up fonts
+sudo tlmgr install libertine # The main font the doc uses
+
+
+```
+
+### Usage
+
+Use the `pandoc` command to generate a PDF.
+
+```bash
+pandoc usage-guide.md -o usage-guide.pdf 
+```
+
+And you can open the PDF with the `open` command.
+
+```bash
+open usage-guide.pdf
+```
+
+Or use this one-liner
+```bash
+pandoc usage-guide.md -o usage-guide.pdf && open usage-guide.pdf
+```

docs/usage-guide.md

@@ -0,0 +1,316 @@
+---
+geometry: margin=1in
+header-includes:
+    - \usepackage{graphicx}
+    - \usepackage{titling}
+    - \usepackage{fancyhdr}
+    - \usepackage{lastpage}
+    - \pagestyle{fancy}
+    - \fancyhead[L]{Time Safari Usage Guide}
+    - \fancyhead[C]{Page \thepage\ of \pageref{LastPage}}
+    - \fancyhead[R]{}
+    - \fancyfoot[L]{}
+    - \fancyfoot[C]{}
+    - \fancyfoot[R]{\includegraphics[width=1cm]{images/timesafari-logo-binoculars.png}}
+    - \usepackage{tocloft}
+    - \usepackage{libertine}
+    - \renewcommand{\familydefault}{\sfdefault}
+    - \fancypagestyle{tocstyle}{
+      \fancyhead[L]{Time Safari Usage Guide}
+      \fancyhead[C]{Page \thepage\ of \pageref{LastPage}}
+      \fancyhead[R]{}
+      \fancyfoot[L]{}
+      \fancyfoot[C]{}
+      \fancyfoot[R]{\includegraphics[width=1cm]{images/timesafari-logo-binoculars.png}}}
+---
+
+\begin{titlepage}
+\centering
+\vspace*{\fill}
+{\huge\textbf{TimeSafari Usage guide}}
+
+\vspace{1cm}
+{\Large Signing up users, adding contacts, and adding gifts.}
+
+\vspace{1cm}
+\includegraphics[width=0.5\textwidth]{images/timesafari-logo.png}
+\vspace*{\fill}
+
+\vspace{1cm}
+{\Large Trent Larson, Kent Bull}
+
+\vspace{0.5cm}
+{\large 2024-06-25}
+
+\end{titlepage}
+
+\clearpage
+
+\begin{center}
+\includegraphics[width=2cm]{images/timesafari-logo-binoculars.png}
+\end{center}
+\tableofcontents
+
+\clearpage
+
+
+# Purpose of Document
+
+Both end-users and development team members need to know how to use TimeSafari. 
+This document serves to show how to use every feature of the TimeSafari platform.
+
+Sections of this document are geared specifically for software developers and quality assurance
+team members.
+
+Companion videos will also describe end-to-end workflows for the end-user.
+
+# TimeSafari 
+
+## Overview
+
+\pagebreak
+
+# 1 - End Users
+
+This section covers application usage for people who will use TimeSafari as intended. It is a
+simplified guide illustrating how to gain value from using TimeSafari.
+
+\pagebreak
+
+# 2 - Software Developers
+
+This section is tailored for software developers seeking to use the application during development,
+quality assurance, and testing.
+
+# Bootstrapping a local development environment
+
+The first concern a software developer has when working on TimeSafari is to set up a local
+development environment. This section will guide you through the process.
+
+## Prerequisites
+
+1. Have the following installed on your local machine:
+  - Node.js and NPM
+  - A web browser. For this guide, we will use Google Chrome.
+  - Git
+  - A code editor
+
+2. Create an API key on Infura. This is necessary for the Endorser API to connect to the Ethereum
+   blockchain. 
+  - You can create an account on Infura [here](https://infura.io/).\
+    Click "CREATE NEW API KEY" and label the key. Then click "API Keys" in the top menu bar to
+    be taken back to the list of keys.
+    
+    Click "VIEW STATS" on the key you want to use.   
+    
+    ![](images/01_infura-api-keys.png){ width=550px }
+  
+  - Go to the key detail page. Then click "MANAGE API KEY".
+  
+    ![](images/02-infura-key-detail.png){ width=550px }
+  
+  - Click the copy and paste button next to the string of alphanumeric characters.\
+    This is your API, also known as your project ID.
+  
+    ![](images/03-infura-api-key-id.png){width=550px }
+  
+  - Save this for later during the Endorser API setup. This will go in your `INFURA_PROJECT_ID` 
+    environment variable.
+    
+
+## Setup steps
+
+### 1. Clone the following repositories from their respective Git hosts:
+  - [TimeSafari Frontend](https://gitea.anomalistdesign.com/trent_larson/crowd-funder-for-time-pwa)\
+    This is a Progressive Web App (PWA) built with VueJS and TypeScript.
+    Note that the clone command here is different from the one you would use for GitHub.
+    
+```bash
+git clone git clone \
+  ssh://git@gitea.anomalistdesign.com:222/trent_larson/crowd-funder-for-time-pwa.git
+```
+  
+  - [TimeSafari Backend - Endorser API](https://github.com/trentlarson/endorser-ch)\
+    This is a NodeJS service providing the backend for TimeSafari.
+    
+    ```bash
+    git clone git@github.com:trentlarson/endorser-ch.git
+    ```
+
+\pagebreak
+
+### 2. Database creation
+
+#### Alternative 1 - use test data
+
+To generate a development database and perform user setup you can run a local test with instructions
+below to generate sample data. Then copy the test database, rename it to `-dev` as below:\
+`cp ../endorser-ch-test-local.sqlite3 ../endorser-ch-dev.sqlite3` \
+and rerun `npm run dev` to give yourself user #0 and others from the ETHR_CRED_DATA in [the endorser.ch test util file](https://github.com/trentlarson/endorser-ch/blob/master/test/util.js#L90)
+
+#### Alternative 2 - boostrap single seed user 
+
+In this method you will end up with two accounts in the database, one for the first boostrap user,
+and the second as the primary user you will use during testing. The first user will invite the
+second user to the app.
+
+1. Install dependencies and environment variables.\
+   In endorser-ch install dependencies and set up environment variables to allow starting it up in
+   development mode.
+   ```bash
+   cd endorser-ch
+   npm clean install  # or npm ci
+   cp .env.local .env
+   ```
+   Edit the .env file's INFURA_PROJECT_ID with the value you saved earlier in the
+   prerequisites.\
+   Then create the SQLite database by running `npm run flyway migrate` with environment variables
+   set correctly to select the default SQLite development user as follows.
+   ```bash
+   export NODE_ENV=dev 
+   export DBUSER=sa 
+   export DBPASS=sasa 
+   npm run flyway migrate
+   ``` 
+   The first run of flyway migrate may take some time to complete because the entire Flyway 
+   distribution must be downloaded prior to executing migrations.
+    
+   Successful output looks similar to the following:
+    
+```
+Database: jdbc:sqlite:../endorser-ch-dev.sqlite3 (SQLite 3.41)
+Schema history table "main"."flyway_schema_history" does not exist yet
+Successfully validated 10 migrations (execution time 00:00.034s)
+Creating Schema History table "main"."flyway_schema_history" ...
+Current version of schema "main": << Empty Schema >>
+Migrating schema "main" to version "1 - initial-anew"
+Migrating schema "main" to version "2 - registration"
+Migrating schema "main" to version "3 - plan project"
+Migrating schema "main" to version "4 - offer gave"
+Migrating schema "main" to version "5 - more confirmations"
+Migrating schema "main" to version "6 - providers urls"
+Migrating schema "main" to version "7 - hash nonce"
+Migrating schema "main" to version "8 - project location"
+Migrating schema "main" to version "9 - plan links"
+Migrating schema "main" to version "10 - gift or trade"
+Successfully applied 10 migrations to schema "main", now at version v10 (execution time 00:00.043s)
+A Flyway report has been generated here: /Users/kbull/code/timesafari/endorser-ch/report.html
+```
+
+\pagebreak
+
+2. Generate the first user in TimeSafari PWA and bootstrap that user in Endorser's database.\
+   As TimeSafari is an invite-only platform the first user must be manually bootstrapped since
+   no other users exist to be able to invite the first user. This first user must be added manually
+   to the SQLite database used by Endorser. In this setup you generate the first user from the PWA. 
+   
+   This user is automatically generated on first usage of the TimeSafari PWA. Bootstrapping that 
+   user is required so that this first user can register other users.
+   - Change directories into `crowd-funder-for-time-pwa`
+     
+     ```bash
+     cd ..
+     cd crowd-funder-for-time-pwa 
+     ```
+   
+   - Ensure the `.env.development` file exists and has the following values:
+   
+     ```env
+     VITE_DEFAULT_ENDORSER_API_SERVER=http://127.0.0.1:3000
+     ```
+   
+   - Install dependencies and run in dev mode. For now don't worry about configuring the app. All we
+     need is to generate the first root user and this happens automatically on app startup.
+  
+     ```bash
+     npm clean install  # or npm ci
+     npm run dev
+     ```
+  
+   - Open the app in a browser and go to the developer tools. It is recommended to use a completely
+     separate browser profile so you do not clear out your existing user account. We will be
+     completely resetting the PWA app state prior to generating the first user.
+   
+     In the Developer Tools go to the Application tab.
+     
+     ![](images/04-pwa-chrome-devtools.png){width=350px} 
+   
+     Click the "Clear site data" button and then refresh the page.
+   
+   - Click the account button in the bottom right corner of the page.
+   
+     ![](images/05-pwa-account-button.png){width=150px}
+   
+   - This will take you to the account page titled "Your Identity" on which you can see your DID,
+     a `did:ethr` DID in this case.
+   
+     ![](images/06-pwa-account-page.png){width=350px}
+   
+   - Copy the DID by selecting it and copying it to the clipboard or by clicking the copy and paste
+     button as shown in the image.
+   
+     ![](images/07-pwa-did-copied.png){width=200px}
+    
+     In our case this DID is:\
+     `did:ethr:0xe4B783c74c8B0e229524e44d0cD898D272E02CD6`
+   
+  - Add that DID to the following echoed SQL statement where it says `YOUR_DID`
+  
+    ```bash
+    echo "INSERT INTO registration (did, maxClaims, maxRegs, epoch) 
+    VALUES ('YOUR_DID', 100, 10000, 1719348718092);"
+    | sqlite3 ./endorser-ch-dev.sqlite3
+    ```
+    
+    and run this command in the parent directory just above the `endorser-ch` directory.
+    
+    It needs to be the parent directory of your `endorser-ch` repository because when 
+    `endorser-ch` creates the SQLite database it depends on it creates it in the parent directory
+    of `endorser-ch`.
+    
+  - You can verify with an SQL browser tool that your record has been added to the `registration`
+    table.
+  
+    ![](images/08-endorser-sqlite-row-added.png){width=350px}
+
+3. Then start the Endorser service in development mode with the following commands.
+  
+    ```bash
+    cd ./endorser-ch
+    export NODE_ENV=dev
+    npm run dev
+    ```
+  
+    This starts the Endorser service on port 3000.
+4. Create the second user by opening up a separate browser profile or incognito session, opening the
+   TimeSafari PWA at `http://localhost:8080`. You will see the yellow banner stating "Someone must
+   register you before you can give or offer."
+   
+   ![](images/09-pwa-second-profile-first-open.png){width=350px}
+   
+   - If you want to ensure you have a fresh user account then open the developer tools, clear the
+     Application data as before, and then refresh the page. This will generate a new user in the 
+     browser's IndexedDB database.
+5. Go to the second users' account page to copy the DID.
+    
+    ![](images/10-pwa-second-user-did.png){width=350px}
+
+6. Copy the DID and put it in the text bar on the "Your Contacts" page for the first account
+
+    ![](images/11-pwa-first-user-add-contact.png){width=350px}
+
+7. Click the "+" plus icon to add the user.
+
+    ![](images/12-pwa-first-user-contact-added.png){width=350px}
+
+8. Then click the register button to register the second user.
+
+    ![](images/13-pwa-first-user-register-second-user-btn.png){width=350px}
+
+9. Click "YES" on the dialog that shows up.
+
+    ![](images/14-pwa-first-user-register-yes.png){width=350px}
+
+    After this a notification will pop up indicating whether registration was successful or not.
+
+10. You have finished the initial set up of users.

src/libs/endorserServer.ts

@@ -407,7 +407,7 @@ export function contactForDid(
  * @param contact
  * @param allMyDids
  * @return { known: boolean, displayName: string, profileImageUrl?: string }
- *  where 'known' is true if the display name is some easily-recogizable name, false if it's a generic name like "Someone Unnamed"
+ *  where 'known' is true if they are in the contacts
  */
 export function didInfoForContact(
   did: string | undefined,
@@ -422,7 +422,7 @@ export function didInfoForContact(
   } else if (contact) {
     return {
       displayName: contact.name || "Contact With No Name",
-      known: !!contact.name,
+      known: !!contact,
       profileImageUrl: contact.profileImageUrl,
     };
   } else {

src/views/ContactsView.vue

@@ -109,7 +109,7 @@
               }"
               title="See more about this DID"
             >
-              <fa icon="circle-info" class="text-blue-500 ml-6" />
+              <fa icon="circle-info" class="text-blue-500 ml-4" />
             </router-link>
           </h2>
           <div class="text-sm truncate">

src/views/DiscoverView.vue

@@ -37,7 +37,7 @@
               isRemoteActive = false;
               searchLocal();
             "
-            v-bind:class="computedLocalTabClassNames()"
+            v-bind:class="computedLocalTabStyleClassNames()"
           >
             Nearby
             <span
@@ -57,7 +57,7 @@
               isLocalActive = false;
               searchAll();
             "
-            v-bind:class="computedRemoteTabClassNames()"
+            v-bind:class="computedRemoteTabStyleClassNames()"
           >
             Anywhere
             <span
@@ -422,7 +422,7 @@ export default class DiscoverView extends Vue {
     this.$router.push(route);
   }
 
-  public computedLocalTabClassNames() {
+  public computedLocalTabStyleClassNames() {
     return {
       "inline-block": true,
       "py-3": true,
@@ -440,7 +440,7 @@ export default class DiscoverView extends Vue {
     };
   }
 
-  public computedRemoteTabClassNames() {
+  public computedRemoteTabStyleClassNames() {
     return {
       "inline-block": true,
       "py-3": true,

src/views/HomeView.vue

@@ -64,98 +64,105 @@
         :to="{ name: 'quick-action-bvc' }"
         class="block text-center text-md font-bold bg-gradient-to-b from-blue-400 to-blue-700 shadow-[inset_0_-1px_0_0_rgba(0,0,0,0.5)] text-white mt-2 px-2 py-3 rounded-md"
       >
-        Bountiful Voluntaryist Community Actions</router-link
-      >
+        Bountiful Voluntaryist Community Actions
+      </router-link>
     </div>
 
-    <!-- show the actions for recognizing a give -->
     <div class="mb-8">
       <div v-if="isCreatingIdentifier">
         <p class="text-slate-500 text-center italic mt-4 mb-4">
           <fa icon="spinner" class="fa-spin-pulse" /> Loading&hellip;
         </p>
       </div>
-      <div
-        v-if="!activeDid && !isCreatingIdentifier"
-        class="bg-amber-200 rounded-md overflow-hidden text-center px-4 py-3 mb-4"
-      >
-        <p class="text-lg mb-3">
-          Want to connect with your contacts, or share contributions or
-          projects?
-        </p>
-        <router-link
-          :to="{ name: 'start' }"
-          class="block text-center text-md font-bold bg-gradient-to-b from-blue-400 to-blue-700 shadow-[inset_0_-1px_0_0_rgba(0,0,0,0.5)] text-white mt-2 px-2 py-3 rounded-md"
-        >
-          Create An Identifier</router-link
-        >
-      </div>
-
-      <div
-        v-else-if="!isRegistered"
-        class="bg-amber-200 rounded-md overflow-hidden text-center px-4 py-3 mb-4"
-      >
-        Someone must register you before you can give or offer.
-        <router-link
-          :to="{ name: 'contact-qr' }"
-          class="block text-center text-md font-bold bg-gradient-to-b from-blue-400 to-blue-700 shadow-[inset_0_-1px_0_0_rgba(0,0,0,0.5)] text-white mt-2 px-2 py-3 rounded-md"
-        >
-          Show Them Your Identifier Info
-        </router-link>
-      </div>
 
       <div v-else>
-        <!-- activeDid && isRegistered -->
-        <div class="mb-4">
-          <h2 class="text-xl font-bold">Record Something Given By:</h2>
+        <!-- !isCreatingIdentifier -->
+        <div
+          v-if="!activeDid"
+          class="bg-amber-200 rounded-md overflow-hidden text-center px-4 py-3 mb-4"
+        >
+          <p class="text-lg mb-3">
+            Want to connect with your contacts, or share contributions or
+            projects?
+          </p>
+          <router-link
+            :to="{ name: 'start' }"
+            class="block text-center text-md font-bold bg-gradient-to-b from-blue-400 to-blue-700 shadow-[inset_0_-1px_0_0_rgba(0,0,0,0.5)] text-white mt-2 px-2 py-3 rounded-md"
+          >
+            Create An Identifier
+          </router-link>
         </div>
 
-        <ul
-          class="grid grid-cols-4 sm:grid-cols-5 md:grid-cols-6 gap-x-3 gap-y-5 text-center mb-5"
+        <div
+          v-else-if="!isRegistered"
+          class="bg-amber-200 rounded-md overflow-hidden text-center px-4 py-3 mb-4"
         >
-          <li @click="openDialog()">
-            <img
-              src="../assets/blank-square.svg"
-              class="mx-auto border border-slate-300 rounded-md mb-1"
-            />
-            <h3
-              class="text-xs italic font-medium text-ellipsis whitespace-nowrap overflow-hidden"
-            >
-              Unnamed/Unknown
-            </h3>
-          </li>
-          <li
-            v-for="contact in allContacts.slice(0, 7)"
-            :key="contact.did"
-            @click="openDialog(contact)"
-          >
-            <EntityIcon
-              :contact="contact"
-              :iconSize="64"
-              class="mx-auto border border-slate-300 rounded-md mb-1 cursor-pointer"
-            />
-            <h3
-              class="text-xs font-medium text-ellipsis whitespace-nowrap overflow-hidden"
-            >
-              {{ contact.name || contact.did }}
-            </h3>
-          </li>
-        </ul>
-
-        <div class="flex justify-between">
+          <!-- activeDid && !isRegistered -->
+          Someone must register you before you can give kudos or make offers or
+          create projects... basically before doing anything.
           <router-link
-            v-if="allContacts.length >= 7"
-            :to="{ name: 'contact-gift' }"
-            class="block text-center text-md font-bold bg-gradient-to-b from-slate-400 to-slate-700 shadow-[inset_0_-1px_0_0_rgba(0,0,0,0.5)] text-white px-2 py-3 rounded-md"
+            :to="{ name: 'contact-qr' }"
+            class="block text-center text-md font-bold bg-gradient-to-b from-blue-400 to-blue-700 shadow-[inset_0_-1px_0_0_rgba(0,0,0,0.5)] text-white mt-2 px-2 py-3 rounded-md"
           >
-            Choose From All Contacts
+            Show Them Your Identifier Info
           </router-link>
-          <button
-            @click="openGiftedPrompts()"
-            class="block text-center text-md bg-gradient-to-b from-slate-400 to-slate-700 shadow-[inset_0_-1px_0_0_rgba(0,0,0,0.5)] text-white px-4 py-2 rounded-md"
+        </div>
+
+        <div v-else>
+          <!-- activeDid && isRegistered -->
+
+          <!-- show the actions for recognizing a give -->
+          <div class="mb-4">
+            <h2 class="text-xl font-bold">Record Something Given By:</h2>
+          </div>
+
+          <ul
+            class="grid grid-cols-4 sm:grid-cols-5 md:grid-cols-6 gap-x-3 gap-y-5 text-center mb-5"
           >
-            Ideas...
-          </button>
+            <li @click="openDialog()">
+              <img
+                src="../assets/blank-square.svg"
+                class="mx-auto border border-slate-300 rounded-md mb-1"
+              />
+              <h3
+                class="text-xs italic font-medium text-ellipsis whitespace-nowrap overflow-hidden"
+              >
+                Unnamed/Unknown
+              </h3>
+            </li>
+            <li
+              v-for="contact in allContacts.slice(0, 7)"
+              :key="contact.did"
+              @click="openDialog(contact)"
+            >
+              <EntityIcon
+                :contact="contact"
+                :iconSize="64"
+                class="mx-auto border border-slate-300 rounded-md mb-1 cursor-pointer"
+              />
+              <h3
+                class="text-xs font-medium text-ellipsis whitespace-nowrap overflow-hidden"
+              >
+                {{ contact.name || contact.did }}
+              </h3>
+            </li>
+          </ul>
+
+          <div class="flex justify-between">
+            <router-link
+              v-if="allContacts.length >= 7"
+              :to="{ name: 'contact-gift' }"
+              class="block text-center text-md font-bold bg-gradient-to-b from-slate-400 to-slate-700 shadow-[inset_0_-1px_0_0_rgba(0,0,0,0.5)] text-white px-2 py-3 rounded-md"
+            >
+              Choose From All Contacts
+            </router-link>
+            <button
+              @click="openGiftedPrompts()"
+              class="block text-center text-md bg-gradient-to-b from-slate-400 to-slate-700 shadow-[inset_0_-1px_0_0_rgba(0,0,0,0.5)] text-white px-4 py-2 rounded-md"
+            >
+              Ideas...
+            </button>
+          </div>
         </div>
       </div>
     </div>
@@ -200,14 +207,22 @@
             </div>
 
             <div class="grid grid-cols-12">
-              <span class="col-span-1 justify-self-start">
+              <span class="pt-1 col-span-1 justify-self-start">
                 <span>
                   <fa
-                    v-if="record.giver.known || record.receiver.known"
                     icon="circle-user"
-                    class="pt-1 text-slate-500"
+                    :class="
+                      computeKnownPersonIconStyleClassNames(
+                        record.giver.known || record.receiver.known,
+                      )
+                    "
+                    @click="toastUser('This involves your contacts.')"
+                  />
+                  <fa
+                    icon="gift"
+                    class="pl-3 text-slate-500"
+                    @click="toastUser('This is a gift.')"
                   />
-                  <fa v-else icon="gift" class="pt-1 pl-3 text-slate-500" />
                 </span>
               </span>
               <span class="col-span-10 justify-self-stretch">
@@ -758,5 +773,21 @@ export default class HomeView extends Vue {
   openFeedFilters() {
     (this.$refs.feedFilters as FeedFilters).open(this.reloadFeedOnChange);
   }
+
+  toastUser(message) {
+    this.$notify(
+      {
+        group: "alert",
+        type: "toast",
+        title: "FYI",
+        text: message,
+      },
+      2000,
+    );
+  }
+
+  computeKnownPersonIconStyleClassNames(known: boolean) {
+    return known ? "text-slate-500" : "text-slate-100";
+  }
 }
 </script>