Merge pull request #56 from momentohq/update-clients

chore: update READMEs and make api endpoint configurable in clients

.github/workflows/on-pull-request.yml

@@ -0,0 +1,21 @@
+name: on-pull-request
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Setup repo
+        uses: actions/checkout@v3
+
+      - name: Verify README generation
+        uses: momentohq/standards-and-practices/github-actions/oss-readme-template@gh-actions-v2
+        with:
+          project_status: official
+          project_stability: stable
+          project_type: other
+          template_file: ./README.template.md
+          output_file: .README.md

.github/workflows/on-push-to-main.yml

@@ -0,0 +1,23 @@
+name: on-push-to-main
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Setup repo
+        uses: actions/checkout@v3
+        with:
+          token: ${{ secrets.MOMENTO_MACHINE_USER_GITHUB_TOKEN }}
+
+      - name: Generate README
+        uses: momentohq/standards-and-practices/github-actions/generate-and-commit-oss-readme@gh-actions-v2
+        with:
+          project_status: official
+          project_stability: stable
+          project_type: other
+          template_file: ./README.template.md
+          output_file: .README.md

README.template.md

@@ -0,0 +1,22 @@
+{{ ossHeader }}
+
+## Multi-language Moderated Chat Demo
+
+This application uses Momento Webhooks to build a moderated, multi-language chat application. Users across a variety of client applications can chat with each other in multiple languages at the same time with profanity filtered out in real time. 
+
+You can try the chat app using our deployed [web app here](https://moderated-chat.vercel.app/).
+
+You can find the web app implementation, as well as additional client applications, of the moderated chat app in the following locations:
+
+- [Web (React + Vite)](./frontend/)
+- [iOS](./ios/)
+- [Android](./android/)
+- [Flutter](./flutter/)
+- [React Native](./react-native/)
+- [Unity](https://github.com/momentohq/momento-unity-demo)
+
+## Developing
+
+If you are interested in deploying your own version of a moderated chat app, you will need to deploy your own version of the backend infrastructure which uses Momento and AWS services. Please see the [infrastructure directory](./infrastructure/) for the overview and setup instructions.
+
+{{ ossFooter }}

android/ModeratedChat/app/src/main/java/software/momento/kotlin/moderatedchat/MainActivity.kt

@@ -97,7 +97,7 @@ import kotlin.collections.HashMap
 import kotlin.system.exitProcess
 import kotlin.time.Duration.Companion.seconds
 
-const val baseApiUrl = "https://57zovcekn0.execute-api.us-west-2.amazonaws.com/prod"
+const val baseApiUrl = "https://your-api-endpoint.com"
 var momentoApiToken: String = ""
 var tokenExpiresAt: Long = 0
 var topicClient: TopicClient? = null

android/README.md

@@ -1,7 +1,19 @@
 # Moderated Chat Using Android Client
 
+This directory contains an Android app version of the Moderated Chat demo.
+
+## Prerequisites
+
+- [Android Studio](https://developer.android.com/studio/install)
+
 ## Running the example using Android Studio
 
 1. Open the `android/ModeratedChat` directory in [Android Studio](https://developer.android.com/studio)
-2. Click the run button in the top bar or choose `Run 'app'` in the `Run` menu
 
+2. Edit the `baseApiUrl` variable to set your API endpoint.
+
+    ```kotlin
+    const val baseApiUrl = "https://your-api-endpoint.com"
+    ```
+
+3. Click the run button in the top bar or choose `Run 'app'` in the `Run` menu

flutter/moderated_chat/README.md

@@ -3,16 +3,31 @@
 A Flutter version of the Momento Moderated Chat demo. It currently only has a macOS implementation, but more are coming soon.
 
 ## Prerequisites
-Flutter. It can be installed by following the instructions [here](https://docs.flutter.dev/get-started/install).
 
-### macOS
-For mac specifically, you will need the Flutter SDK, [Xcode](https://developer.apple.com/xcode/), and [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#installation).
+- [Flutter is installed](https://docs.flutter.dev/get-started/install).
+
+### macOS prerequisites
+
+- [Xcode](https://developer.apple.com/xcode/)
+- [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#installation).
 
 ## Running the Demo
-From the flutter moderated_chat directory, call `flutter run` to start the app:
-```bash
-cd flutter/moderated_chat
-flutter run -d macos
-```
-Alternatively, you can open the project in VSCode or IntelliJ with the Flutter plugin and run the app from there.
 
+1. In the [lib/config.dart file](./lib/config.dart), specify the base URL for your API endpoints.
+
+    ```dart
+    class Config {
+      static const baseUrl = "https://your-api-endpoint.com";
+    }
+    ```
+
+2. From the flutter moderated_chat directory, call `flutter run` to start the app:
+
+    ```bash
+    cd flutter/moderated_chat
+    flutter run -d macos
+    ```
+
+    Alternatively, you can open the project in VSCode or IntelliJ with the Flutter plugin and run the app from there.
+
+Note: see [here](https://github.com/jonataslaw/get_cli/issues/263) if you are using Dart 3.5.0 and get an error about UnmodifiableUint8ListView.

flutter/moderated_chat/lib/config.dart

@@ -1,3 +1,3 @@
 class Config {
-  static const baseUrl = "https://57zovcekn0.execute-api.us-west-2.amazonaws.com/prod";
+  static const baseUrl = "https://your-api-endpoint.com";
 }

frontend/README.md

@@ -1,27 +1,26 @@
-# React + TypeScript + Vite
+# Web Moderated Chat App
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+This directory contains a React + TypeScript + Vite web app version of the Moderated Chat demo.
 
-Currently, two official plugins are available:
+## Prerequisites
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+- Node version 16 or higher is required
 
-## Expanding the ESLint configuration
+## Running the demo
 
-If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:
+Create a `.env` file to specify the base URL for your API endpoints.
 
-- Configure the top-level `parserOptions` property like this:
+```bash
+VITE_API_BASE_URL="https://your-api-endpoint.com"
+```
+
+Then run the web app:
 
-```js
-   parserOptions: {
-    ecmaVersion: 'latest',
-    sourceType: 'module',
-    project: ['./tsconfig.json', './tsconfig.node.json'],
-    tsconfigRootDir: __dirname,
-   },
+```bash
+npm install
+npm run dev
 ```
 
-- Replace `plugin:@typescript-eslint/recommended` to `plugin:@typescript-eslint/recommended-type-checked` or `plugin:@typescript-eslint/strict-type-checked`
-- Optionally add `plugin:@typescript-eslint/stylistic-type-checked`
-- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and add `plugin:react/recommended` & `plugin:react/jsx-runtime` to the `extends` list
+## Deploying to Vercel
+
+For [Vercel](https://vercel.com) deployments of the moderated chat app, you must also ensure the `VITE_API_BASE_URL` environment variable exists. You can create this using the Vercel console on the project's Settings > Environment Variables page.

frontend/src/api/translation.ts

@@ -2,9 +2,8 @@ import { type LanguageOption } from "../ChatApp";
 import { type ChatMessageEvent, type User } from "../shared/models";
 
 class TranslationApi {
-  // TODO: update API DOMAIN when moving to prod
-  private readonly baseUrl =
-    "https://chat-api.developer-mst-dev.preprod.a.momentohq.com";
+  private readonly baseUrl = import.meta.env.VITE_API_BASE_URL;
+
   async createToken(
     user: User,
   ): Promise<{ token: string; expiresAtEpoch: number }> {

frontend/src/vite-env.d.ts

@@ -1 +1,10 @@
 /// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_API_BASE_URL: string;
+  // more env variables may be added here
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

frontend/vite.config.ts

@@ -1,7 +1,11 @@
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
 
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [react()],
-})
+  define: {
+    "process.env": process.env,
+    VITE_API_BASE_URL: process.env.VITE_API_BASE_URL,
+  },
+});

infrastructure/README.md

@@ -1,14 +1,74 @@
-# Welcome to your CDK TypeScript project
+# Moderated Chat App Backend Infrastructure
 
-This is a blank project for CDK development with TypeScript.
+The [backend](../backend/) directory contains the Lambda functions used for initializing a Momento [cache](https://docs.momentohq.com/cache) and [webhook](https://docs.momentohq.com/topics/webhooks/overview), creating a [token vending machine](https://github.com/momentohq/client-sdk-javascript/tree/main/examples/nodejs/token-vending-machine), and serving API requests for the moderated chat application.
 
-The `cdk.json` file tells the CDK Toolkit how to execute your app.
+This directory contains the [AWS CDK](https://github.com/aws/aws-cdk) stack to deploy AWS resources.
 
-## Useful commands
+The main APIs used in this application are:
 
-* `npm run build`   compile typescript to js
-* `npm run watch`   watch for changes and compile
-* `npm run test`    perform the jest unit tests
-* `cdk deploy`      deploy this stack to your default AWS account/region
-* `cdk diff`        compare deployed stack with current state
-* `cdk synth`       emits the synthesized CloudFormation template
+- `POST /v1/translate` - webhook listener for momento topic events
+- `GET /v1/translate/latestMessages/<lang>` - returns the last 100 messages from the chat in the requested language
+- `GET /v1/translate/supportedLanguages` - returns the languages that the application currently supports
+- `GET /v1/translate/token/<username>` - returns a short lived token that allows <username> to publish to the `chat-publish` topic
+
+In order to run these apis, you will first need to create a secret stored in AWS Secrets Manager with the path `moderated-chat/demo/secrets`. You can use the [setup-secrets.sh script](./setup-secrets.sh) to deploy this secret to your AWS account.
+
+In the AWS console, you should verify that the secret contains key-value pairs in the format:
+
+```text
+{
+  momentoApiKey: "",
+  webhookSigningSecret: "",
+}
+```
+
+- `momentoApiKey` - your Momento API key with superuser permissions. This can be created via the [Momento Console](https://console.gomomento.com/api-keys). This api key will be used to vend short lived publish/subscribe api keys to the frontend.
+- `webhookSigningSecret` - the signing secret associated with the Momento Webhook. It is used to validate that requests are coming from Momento. This secret is updated by the custom resource lambda function when you deploy the backend infrastructure CDK stack.
+
+To deploy the CDK stack, you can edit and run the [build-and-deploy script](./build-and-deploy.sh).
+Or you can manually run each of these steps:
+
+1. Build the Lambda function code.
+
+    ```bash
+    cd backend/lambdas
+    npm install
+    npm run build
+    ```
+
+2. Build the CDK code.
+
+    ```bash
+    cd infrastructure
+    npm install
+    npm run build
+    ```
+
+3. Specify the API_DOMAIN environment variable.
+
+    ```bash
+    # The default is to use the API gateway URL that is provided when you deploy the backend stack.
+    export API_DOMAIN="default"
+
+    # Specifying your own domain name will direct your CDK stack to find an existing AWS Route53 
+    # hosted zone in your account and create a 'chat-api' subdomain for it.
+    export API_DOMAIN=${API_DOMAIN:-your-chosen-domain-name.com}
+    ```
+
+4. Deploy your backend stack.
+
+    ```bash
+    AWS_PROFILE=<my profile> AWS_REGION=<my region> npx cdk deploy
+    ```
+
+Once deployed, you can test your application using any of the client applications.
+
+If you used the `API_DOMAIN="default"` option, you'll want to save the API gateway URL that was printed out.
+This will be the base API URL you'll provide to the client applications.
+
+```bash
+Outputs:
+moderated-chat-translation-api-stack.moderatedchatrestapiEndpoint23439914 = https://something.something.something.amazonaws.com/prod/
+```
+
+If you used your own API domain name, you'll provide something like `https://chat-api.your-domain-name.com` to the client applications.

infrastructure/build-and-deploy.sh

@@ -12,7 +12,12 @@ rm -f cdk.context.json
 npm i
 npm run build
 
-# TODO: update API DOMAIN when moving to prod
-export API_DOMAIN=${API_DOMAIN:-developer-mst-dev.preprod.a.momentohq.com}
+# For Momento developers, to deploy to your dev account, you will need to have gone through the cell bootstrap
+# process at least once. Alternately, you can use a teammate's endpoint or use the preprod endpoint 
+# (search for Route53 hosted zones in the appropriate AWS accounts).
+# export API_DOMAIN=${API_DOMAIN:-your-chosen-domain-name.com}
+
+# The default is to use the API gateway URL that is provided when you deploy the backend stack.
+export API_DOMAIN="default"
 
 AWS_PROFILE=dev AWS_REGION=us-west-2 npx cdk deploy --require-approval never