# ows-notifications service

## Prerequisites

* **Python 3.13+**
* **uv**: Fast Python package installer and resolver.
* **Docker & Docker Compose**: For containerized development.

---

## Configuration

### 1. Environment variables

Before running the application, you must set up your local environment variables.
We use `.env.shadow` as a template.

1. **Copy the template:**
   `cp .env.shadow .env`

2. **Populate .env:** Open the file and fill in your specific credentials (AWS keys, SQS URIs, etc.).

### Split.io
Some endpoints integrate with [Split.io](https://www.split.io/).
If you don't want the process to attempt fetching from Split.io,
you can set the following environment variable in your `.env` file:

```
Environment=dev
```

In this case, you'll need to add a `.split` file at the `SPLIT_FILE_PATH` (usually root of the project).

### 2. AWS
You need to set up [AWS profiles](https://www.notion.so/0bb005a6ec2b499a8190682d121617e4?v=d6a9e7b57f6443758b08053661f947fd) for `Orchard Prod` and `Shared Services`

> ⚠️ Make sure you have [AWS CLI installed and your credentials are properly configured](https://www.notion.so/AWS-Access-f841b9dd815d4443a80e96a86c92cd2f).

### 3. ows-requests

In PROD and QA environments, to accept and authorize incoming and outgoing
requests, make sure you have the right DynamoDB permissions, as highlighted
in the corresponding [tech design](https://docs.google.com/document/d/1eHoI_BddTFMi15yCaHS6KvhSSoTrMEd3WwJINIpgNpM/edit).

### 4. getstream.io

Some endpoints integrate with [GetStream.io](https://getstream.io/).
1. If you don't already have access, create a DevOps ticket in the SYS project in JIRA requesting an account for getstream.io
2. Copy access key and secret from [dev-notifications](https://dashboard.getstream.io/app/37616/feeds/overview) application
3. Use the below commands to set getstream permissions for your local env
4. Optionally, you can store them in .env for reference.

```
export STREAM_API_KEY=<KEY GOES HERE>
export STREAM_API_SECRET=<SECRET GOES HERE>
export STREAM_API_REGION=us-east
```

### 5. neo4j

Some endpoints connect to neo4j.
1. If you don't already have access, create a DevOps ticket in the SYS project in JIRA requesting access to dev neo4j cluster
2. Use the below commands to set neo4j permissions for your local env
3. Escape `$` in password as `\$` if necessary
4. Optionally, you can store them in .env for reference.
```
export NEO4J_URL=neo4j+ssc://dev-neo4j-cluster.dev.theorchard.io
export NEO4J_USERNAME=<USERNAME GOES HERE>
export NEO4J_PASSWORD="<PASSWORD GOES HERE>"
```
> ⚠️ Be sure to use quotes around password

---

## Getting Started

### 1. Environment Setup
Initialize the virtual environment and install all dependencies
(including dev tools and pre-commit hooks):
```bash
make install
```

### 2. Local Development
To run the service locally using `dev.py` (useful for fast debugging):
```bash
make run
```

### 3. Docker Development
Run the service inside a containerized environment.
```bash
# Standard dev run (Hot-reload enabled via volume mount)
make docker/run

# Run with Datadog Agent profile enabled
make docker/run_dd
```

---

## Testing & Quality Control

### Execution
The testing suite uses `pytest`.
You can run specific tests or pass extra arguments (like `-v`) using the `ARGS` variable.

* **Run default unit tests:** `make test`
* **Run specific test:** `make test TEST_PATH=tests/unit/api ARGS="-v"`
* **Run integration tests:** `make test_integration`

### Coverage
* **Terminal report:** `make test_cov`
* **XML report for CI:** `make test_cov_report`

---

## Linting and Formatting

We use **Ruff** for linting/formatting and **Ty** for fast static type checking.

| Task | Command | Description                                         |
| :--- | :--- |:----------------------------------------------------|
| **Check All** | `make check` | Runs format check, linting, type check, and tests.  |
| **Fix All** | `make fix` | Automatically applies formatting and linting fixes. |
| **Type Check**| `make type_check`| Runs the `ty` type checker.                         |

---

## Maintenance

* **Clean caches:** `make clean`
* **Full Reset:** `make clean_all` (Removes `.venv` and all caches)