add readme for doorman-client

README.md

@@ -10,9 +10,9 @@ bun install
 
 Check out the individual READMEs in the monorepo to see how to run each component of Doorman
 
-- doorman-client (twilio function that runs when receiving buzzer call)
+- doorman-client (Twilio Function that triggers when receiving buzzer call)
-- doorman-api (backend API that manages Door state and configs)
+- doorman-api (Twilio Function API that manages Door state and configs)
-- doorman-ui (frontend React app)
+- doorman-ui (frontend React app, served by doorman-api)
 - doorman-schema (future home for all the zod schemas and basic validations)
 
 ## CI/CD workflows

packages/doorman-api/README.md

@@ -48,6 +48,10 @@ martin    243091  243061 93 17:57 pts/4    00:00:13 java -Xrs -Djava.library.pat
 kill 243091
 ```
 
+or if you want to kill all java processes (likely only this DDB local thing)
+
+`kill $(pidof java)`
+
 ## deployment
 
 this project deploys the UI and API to twilio functions https://doorman-6741-prod.twil.io

packages/doorman-api/src/local/localDdb.ts

@@ -69,7 +69,7 @@ const doorConfig: DoorConfig = {
   buzzer: testDoorBuzzer,
   pressKey: "4",
   discordUsers: [],
-  fallbackNumbers: [],
+  fallbackNumbers: ["1231231234"],
   pin: testDoorPin,
   buzzerCode: testDoorPin,
   timeout: 60,

packages/doorman-client/.env.local

@@ -0,0 +1,18 @@
+# twilio (not needed for dev)
+# ACCOUNT_SID=
+# AUTH_TOKEN=
+
+DOORMAN_URL=http://localhost:8080
+
+# metrics
+PUSHGATEWAY_URL=https://metrics.chromart.cc
+STAGE=$user-dev
+PUSHGATEWAY_USER=doorman
+PUSHGATEWAY_PW=doormanmetrics
+
+# logs
+LOKI_URL=https://logs.chromart.cc
+LOKI_USER=doorman
+LOKI_PW=doormanlogs
+
+NOTIFY_SECRET_KEY=discordnotifyme

packages/doorman-client/.gitignore

@@ -80,7 +80,6 @@ web_modules/
 .env.development.local
 .env.test.local
 .env.production.local
-.env.local
 
 # parcel-bundler cache (https://parceljs.org/)
 .cache

packages/doorman-client/README.md

@@ -1,51 +1,30 @@
-# Make your apartment buzzer smart with Twilio Functions
+# doorman-client
 
-I wanted to make my apartment buzzer acessible without a physical key, so I created these Twilio Functions to make my buzzer smarter. Features include:
+This is the Twilio Function that is triggered when receiving a call from a buzzer. In short, it's job is to talk to the doorman-api to determine the buzzers configuration and to check if the door should be auto unlocked, or dial through to a phone number on file.
 
-* Voice password (make your friends shout stupid things in public to get into your building!)
+## dependency services
-* PIN password, a classic
+This service has a hard dependency on doorman-api, specifically on the /api/door/info Function. if this is down, the buzzer client will not work.
-* No obvious weirdness or extra waiting for first-time guests or delivery people
-* Notify multiple people until someone picks up the phone - as long as one of the roommates pick up, you won't miss your package
 
-I kind of went overboard I think, given my original goal. But this was actually *really* easy to develop and set up. And also really cheap.
+It has soft dependencies on self hosted monitoring solutions:
+- Pushgateway (prometheus metrics)
+- Loki (logs)
 
-## How to set this up
+## running locally
 
-1. You could `git clone https://github.com/jlian/smart-door-buzzer-twilio-functions.git`, but it's not critical.
+NOTE: You'll want to make sure that doorman-api is also running locally first. .env.local is configured to use http://localhost:8080 as the doorman-api endpoint
-2. Get a Twilio account and valid Twilio number.
-3. Go to https://www.twilio.com/console/runtime/functions/manage and hit **+**.
-4. Add each of the 4 `.js` files into its own function with names that you'd remember.
-5. Go to https://www.twilio.com/console/runtime/functions/configure and configure the environment variables:
-  * `TWILIO_PHONE` with the Twilio number you bought
-  * `PASSPHRASE` for voice password
-  * `PASSCODE` for PIN
-  * `JOHN_PHONE` and others for your cellphone number
-5. Go to https://www.twilio.com/console/phone-numbers/incoming and select the phone number you bought earlier.
-6. Scroll to where it says **A call comes in**, select **Function**, and then the function that corresponds to `buzzer-activated.js`.
-7. Contact your HOA to make the Twilio number your buzzer number - this might be the hardest step.
 
-## How this works
+First install the necessary dependencies `bun install`.
 
-[Twilio Functions](https://www.twilio.com/functions) is pretty sweet. It's completely serverless so you don't need a VM or computer to keep running an app. It's perfect for something small scale like your apartment buzzer. The flow of this program goes like this:
+Run the doorman-client
 
-1. A call comes to the Twilio phone number, `buzzer-activated.js` runs.
+`bun run start`
-1. The [Gather](https://www.twilio.com/docs/api/twiml/gather) verb is used to get either a voice password or a 4-digit PIN.
-   1. If correct, `door-open.js` dials a `9` to the buzzer (my building's buzzer code, yours may be different), which opens the door.
-   1. If incorrect, `call-residents.js` calls all the residents until someone picks up and manually dial `9` to open the door.
-1. When everything is finished, `text-me.js` texts a specified number with info on what happened.
 
-## How much this costs
+To test doorman-client head over to 
 
-According to Twilio docs, collecting speech is charged at $.02 per 15 seconds. A Twilio number costs $1/month. Looking at my own billing dashboard, it never exceeds $2/month - pretty reasonable. 
+`http://localhost:4500/buzzer-activated?From=6133163433`
 
-## Twilio tooling
+This will simulate a buzzer calling from 6133163433 (the test buzzer)
-Using the twilio serverless toolbox you can locally run the functions and test.
 
-```
+If you let it poll for 10s then it should respond with Twilio xml saying to dial fallback numbers.
-bun run start
-```
 
-Deploy to your account with 
+If doorman-api is not running, it would always return with a `<Reject/>`
-```
-bun run deploy
-```

packages/doorman-client/package.json

@@ -5,7 +5,7 @@
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
     "watch-build": "bun run --watch src/index.ts",
-    "start-twilio": "twilio-run --live --port 4500",
+    "start-twilio": "twilio-run --live --load-system-env --env .env.local --port 4500",
     "start": "concurrently \"bun run watch-build\" \"bun run start-twilio\"",
     "build": "bun run src/index.ts",
     "deploy": "twilio-run promote --from=staging --to=prod --load-system-env --env .env.twiliotemplate",