Merge branch 'develop' into develop

Author: bl00dymarie

.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(yarn type-check)",
+      "Bash(yarn test)"
+    ]
+  }
+}

.claudeignore

@@ -0,0 +1,31 @@
+# Dependencies and build output
+
+node_modules/
+dist/
+coverage/
+
+# Environment secrets
+
+.env
+.env.\*
+!.env.example
+
+# Logs
+
+\*.log
+logs/
+
+# Docker volumes / data
+
+postgres-data/
+
+# OS / editor noise
+
+.DS*Store
+*.swp
+\_.swo
+
+# Large lock files (yarn.lock is still useful for context)
+
+package-lock.json
+yarn.lock

.github/workflows/.ci.yml

@@ -14,6 +14,7 @@ jobs:
   build:
     runs-on: ubuntu-24.04
     env:
+      FRONTEND_APP_URL: ${{ secrets.FRONTEND_APP_URL }}
       SIMPLYBOOK_CREDENTIALS: '{"login": "login"}'
       STORYBLOK_PUBLIC_TOKEN: ${{ secrets.STORYBLOK_PUBLIC_TOKEN }}
       STORYBLOK_WEBHOOK_SECRET: ${{ secrets.STORYBLOK_WEBHOOK_SECRET }}

.github/workflows/community-issue-comment.yml

@@ -31,7 +31,7 @@ jobs:
     steps:
       - name: Post assignee issue comment
         id: assigned-comment
-        uses: actions/github-script@v8 # https://github.com/actions/github-script
+        uses: actions/github-script@v9 # https://github.com/actions/github-script
         with:
           github-token: ${{secrets.GITHUB_TOKEN}}
           script: |
@@ -59,7 +59,7 @@ jobs:
     steps:
       - name: Post stale issue comment
         id: stale-label-comment
-        uses: actions/github-script@v8 # https://github.com/actions/github-script
+        uses: actions/github-script@v9 # https://github.com/actions/github-script
         with:
           github-token: ${{secrets.GITHUB_TOKEN}}
           script: |

.github/workflows/create-release-pr.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Create Pull Request
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const { repo, owner } = context.repo;

.github/workflows/scan-and-label-forks.yml

@@ -20,7 +20,7 @@ jobs:
     steps:
       - name: Label PR for Sensitive Files
         # https://github.com/actions/labeler
-        uses: actions/labeler@634933edcd8ababfe52f92936142cc22ac488b1b
+        uses: actions/labeler@f27b608878404679385c85cfa523b85ccb86e213
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           configuration-path: .github/configs/labeler.yml

CLAUDE.md

@@ -0,0 +1,86 @@
+# Bloom Backend
+
+NestJS/TypeScript REST API for a trauma-healing support platform. PostgreSQL via TypeORM, deployed on Render.
+
+## Tech Stack
+
+- **Runtime:** Node.js 22.x, TypeScript
+- **Framework:** NestJS
+- **Database:** PostgreSQL 17 + TypeORM 0.3.x
+- **Package manager:** Yarn 1.x
+- **Tests:** Jest (unit `*.spec.ts`, e2e in `test/`)
+
+## Development
+
+```bash
+# Start (Docker recommended)
+docker-compose up
+
+# Or manually
+yarn
+yarn start:dev          # hot reload on localhost:35001
+
+# Lint / format
+yarn lint
+yarn format
+```
+
+## Testing
+
+```bash
+yarn test                          # unit tests
+yarn test:watch                    # watch mode
+yarn test:cov                      # with coverage
+yarn test:e2e                      # end-to-end
+
+# Run a specific test file
+yarn jest src/path/to/file.spec.ts --no-coverage
+```
+
+## Database / Migrations
+
+```bash
+yarn migration:generate            # generate migration from entity changes
+yarn migration:run                 # apply pending migrations
+yarn migration:revert              # revert last migration
+yarn migration:show                # show migration status
+```
+
+Entities live in `src/entities/`. Migrations in `src/migrations/`.
+
+## Project Structure
+
+```
+src/
+  auth/                  authentication
+  user/                  user management
+  partner/               partner orgs + access control
+  course/                courses & user progress
+  session/               therapy sessions & feedback
+  resource/              learning resources
+  subscription/          subscription management
+  reporting/             analytics & Slack reporting
+  webhooks/              inbound webhooks (Slack, Zapier, Mailchimp, SimplyBook)
+  api/                   outbound API clients (GA4, Mailchimp, SimplyBook, Slack, Zapier)
+  event-logger/          event tracking
+  firebase/              Firebase integration
+  front-chat/            Front (chat) integration
+  entities/              TypeORM entity definitions
+  migrations/            TypeORM migration files
+  utils/                 shared utilities
+  main.ts                app entry point
+  typeorm.config.ts      DB connection config
+```
+
+## Key Integrations
+
+Firebase (auth), Storyblok (CMS), SimplyBook (appointments), Mailchimp (email), Slack, Front (chat/support), GA4, Rollbar (errors), New Relic (APM), Render (hosting)
+
+## CI
+
+GitHub Actions (`.github/workflows/.ci.yml`): Prettier → ESLint → Jest → build. Runs on PRs and pushes to `develop`.
+
+## Branch Strategy
+
+- `develop` — main integration branch; open PRs against this
+- `main` — production

README.md

@@ -29,7 +29,7 @@ Technologies Used:
 - [Simplybook](https://simplybook.me/en/) - Appointment booking system used for therapy
 - [Slack](https://api.slack.com/messaging/webhooks) - Slack webhooks to send messages to the team
 - [Rollbar](https://rollbar.com/) - Error reporting
-- [Crisp](https://crisp.chat/en/) - User messaging
+- [Front](https://front.com) - User messaging
 - [Mailchimp](https://mailchimp.com/developer/marketing/) - Transactional email
 - [Docker](https://www.docker.com/) - Containers for api and db
 - [Render](https://render.com) - Build, deploy and operate staging and production apps

docs/configure-env.md

@@ -35,16 +35,18 @@ FIREBASE_MEASUREMENT_ID=
 # REQUIRED VARIABLES FOR TESTING
 #---------------------------------------------------------------
 # MOCK VALUES (can replace with real values or new mocks in same format)
-SIMPLYBOOK_CREDENTIALS='{"login":"testlogin","password":"testpassword","company":"testcompany"}'
+SIMPLYBOOK_CREDENTIALS='{"login":"testlogin","password":"api_user_key_customapikey","company":"testcompany"}'
 SIMPLYBOOK_COMPANY_NAME=testcompany
+SIMPLYBOOK_WEBHOOK_SECRET=generate-your-own-secret
+SIMPLYBOOK_TOTP_SECRET= # Required when 2FA is enabled on the Simplybook admin account
 
 # OPTIONAL VARIABLES
 #---------------------------------------------------------------
 ROLLBAR_ENV=development # Rollbar logging
 ROLLBAR_TOKEN= # Rollbar logging
-ZAPIER_TOKEN= # Zapier automation
+ZAPIER_TOKEN= # Zapier automation (legacy - see SIMPLYBOOK_WEBHOOK_SECRET)
 SLACK_WEBHOOK_URL= # Slack messaging bots
-CRISP_TOKEN= # Crisp chat
+FRONT_SUPPORT_EMAIL= # (optional) Front sender address used to distinguish agent replies in chat history; defaults to support@bloom.chayn.co
 MAILCHIMP_API_KEY= # Email messaging
 RESPOND_IO_CREATE_CONTACT_WEBHOOK= # RESPOND.IO
 RESPOND_IO_DELETE_CONTACT_WEBHOOK= # RESPOND.IO
@@ -61,3 +63,21 @@ The frontend and backend each have _required_ and _optional_ environment variabl
 Note: Variables provided by Chayn are public, not linked to production, and subject to change at any time. Check for updates if you are experiencing problems. The absence of some optional environment variables may result in test failures. If you require an optional environment variable and cannot acquire it yourself (some must be connected to Chayn in some way), please reach out to the team in GitHub’s issue discussions.
 
 **Please notify us if creating new environment variables in your PR so we can add it to Render before release deployment.**
+
+## Simplybook Variables
+
+`SIMPLYBOOK_CREDENTIALS` must be a JSON string with the following shape:
+
+```json
+{ "login": "<api_user_key_or_login>", "password": "<password>", "company": "<company_login>" }
+```
+
+For production, use a Simplybook **API User Key** (`api_user_key_...`) as the `login` value — this bypasses IP verification restrictions on the admin API.
+
+`SIMPLYBOOK_WEBHOOK_SECRET` is the shared secret used to authenticate incoming webhooks from Simplybook at `POST /api/webhooks/simplybook-admin`. Configure the same value as the `?token=` query parameter in the Simplybook webhook callback URL:
+
+```
+https://<your-domain>/api/webhooks/simplybook-admin?token=<SIMPLYBOOK_WEBHOOK_SECRET>
+```
+
+`SIMPLYBOOK_TOTP_SECRET` is required when 2FA is enabled on the Simplybook admin account. It is the base32 TOTP secret shown during 2FA setup (the same secret you scan into an authenticator app). Leave unset if 2FA is not enabled.

docs/local-development.md

@@ -4,36 +4,40 @@
 
 To run Bloom's backend:
 
-1. Install prerequisites
-2. Configure environment variables
-3. Install dependencies
-4. Run the app using Docker, Dev Containers, or Manually
-5. Populate the database
+1. [Install prerequisites](#1-prerequisites)
+2. [Configure environment variables](#2-configure-environment-variables)
+3. [Install dependencies](#3-install-dependencies-with-yarn)
+4. [Run the app using Docker, Dev Containers, or Manually](#4-run-the-app-locally)
+5. [Populate the database](#5-populate-the-database-and-database-migrations)
 
 To test the backend:
 
-- Run unit tests
-- Run e2e integration tests from the frontend for full-stack contributions
+6. [Run unit tests](#6-unit-testing)
+7. [Run e2e integration tests from the frontend for full-stack contributions](#7-format-and-linting)
 
-## Prerequisites
+- [Git Flow and Deployment](#git-flow-and-deployment)
+- [APIs](#apis)
+
+
+## 1. Prerequisites
 
 - NodeJS v22.x
 - Yarn v1.x
 - Docker and / or PostgreSQL
 
 _Recommended Minimum System Requirements: CPU: Quad-core 2.5 GHz (i5/Ryzen 5), Memory: 16 GB RAM, Storage: 512 GB, OS: Linux, macOS, Windows, or WSL2 (latest versions), Internet Connection: For accessing dependencies and external APIs/services._
 
-## Configure Environment Variables
+## 2. Configure Environment Variables
 
 See [configure-env.md](configure-env.md) for instructions on configuring environment variables.
 
-## Install dependencies with yarn
+## 3. Install dependencies with yarn
 
 ```bash
 yarn
 ```
 
-## Run the App Locally
+## 4. Run the App Locally
 
 There are 3 methods you can use to run Bloom’s backend locally:
 
@@ -97,7 +101,13 @@ You should see this in the shell output:
 Listening on localhost:35001, CTRL+C to stop
 ```
 
-## Unit Testing
+## 5. Populate the Database and Database Migrations
+
+Populating your local database with test data is required for running Cypress integration tests and testing Bloom’s full-stack functionality.
+
+See the [database-guide.md](database-guide.md) for instructions.
+
+## 6. Unit Testing
 
 To run all unit tests
 
@@ -111,7 +121,7 @@ To have your unit tests running in the background as you change code:
 yarn test:watch
 ```
 
-## Format and Linting
+## 7. Format and Linting
 
 Linting and formatting are provided by [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/). We recommend VSCode users to utilize the workspace settings in [.vscode/settings.json](.vscode/settings.json) and install the extensions in [.vscode/extensions](.vscode/extensions.json) for automated consistency.
 
@@ -135,12 +145,6 @@ Run format and fix:
 yarn format
 ```
 
-# Populate the Database and Database Migrations
-
-Populating your local database with test data is required for running Cypress integration tests and testing Bloom’s full-stack functionality.
-
-See the [database-guide.md](database-guide.md) for instructions.
-
 # Git Flow and Deployment
 
 **The develop branch is our source of truth, not main.** Fork from `develop`, create new feature branch, then when your PR is merged, `develop` will automatically merge into the main branch for deployment to production. Keep your branch updated by rebasing and merging feature/bug branches into `develop` as you code.