Overview

• Elevar's prototyping feature allows payloads for each server side destination to be routed into GCP's pub sub for transformation. This allows us to complete offbeat client requests to add/remove/change existing requests.

Setup

Project Details

• GCP project name: elevar-prototyping

IDE/IDX

• This project should be run in IDX https://idx.dev/
• Use the "Import a repo" option and provide it the address of this repo https://github.com/elephantsneverforget/elevar-prototyping
• IDX will import the repo and setup the environment for you

Gcloud

• Install gcloud cli if it's not already installed (which it should be)
• Run $ gcloud auth login to login, use your personal elevar email
• See the projects associated with the account by running $ gcloud projects list
• Select the relevant project, $ gcloud config set project elevar-prototyping
• If you'd like, list all currently running cloud run v2 functions gcloud run services list

Github - Skip this unless you have issues with connecting to the repo from the CLI

• Login to Github using $ gh auth login
• Use git as normal $ git add/git push/git pull etc...

VS Code

• Install the "ESLint" VS code extension
• Install the "Prettier" code extension
• Install the Javascript debugger extension "vscode-js-debug"

NPM Install

• Run $ npm install in the root of the repo and in any company you are testing

Starter Template

• Use the bulletproof/ga4_purchase_event as a starting point for your new company function
• Once copied run $ npm install to install any relevant libraries before you begin testing locally
• Modify index.js and write appropriate tests
• If you are working with a different channel ensure you get an appropriate fixture from that channel and save it in the fixtures folder

Create Topic

• Manually create the topic you'll be using in cloud console. The topic should always include the company name

Creating Fixture Events For Your Tests

• Create a function manually in cloud console that simply logs the cloudEvent from Elevar something like console.log(JSON.stringify(cloudEvent, null, 2));
• Go to the logs and copy/paste the event
• You'll notice that the logs may have added a jsonPayload key. This is a log feature, but you should remove it in your fixture
• Structure should be cloudEvent.data.message.data
• Add your fixture to the fixtures folder
• Use the fixture in your testing

Shared NPM Package

• Login to npm on the command line. Currently the package is published under [email protected]
• Shared utilities and fixtures live in the /shared folder
• This is an npm package pubsubproto-shared-elevar
• Should you need to make changes to the shared folder you should:

1. Update the code in the /shored_node_module folder
2. Write tests
3. Bump the version in shared/package.json
4. Push the new package version by running $ npm publish from the /shared_node_module directory
5. In all company code implementations, update the package to the version you just pushed
6. Run $ npm install in the company directory

*** If you make changes to the module, you must update any company connectors that reference it and test locally before pushing the function to GCP ***

Tests

• Write tests and run $ vitest from the root of the project
• $ viteset will run tests on both your company specific implementaions and on the shared_node_module. If you want to only test your new company code user $ vitest /src/company/path_to_test_file.js

Deployment

• Go to the directory of the company where your index.js file is
• Run the following command. Note that if you are updating an existing function the same command should be run.

gcloud functions deploy name_of_function_in_gcp \
  --gen2 \
  --runtime=nodejs20 \
  --region=us-central1 \
  --source=. \ # Assumes you are running the command in the dir with the index.js file that contains the function
  --entry-point=processMessage \ # "processMessage" is the name of the function. for example `const processMessage = (cloudEvent) => {...`
  --trigger-topic=YOUR_TOPIC_NAME # Ensure the topic is created in GCP

• Name the function in cloud console. Click on the function checkbox. Click labels. Add key as name and value as function_name