# Runbook

## Purpose

This runbook lists practical checks for running, debugging, and maintaining the API wrapper.

## Health Checks

There is no dedicated health endpoint in the local code. Basic health should be checked by:

1. Confirming the process starts.
2. Confirming routes register from S3.
3. Calling a known low-risk endpoint with valid auth.
4. Checking console and CloudWatch logs.

## Startup Checklist

- Python dependencies installed from `requirements.txt`.
- PHP CLI is installed.
- `wkhtmltopdf` is installed.
- `.env` or runtime environment variables are present.
- AWS credentials can read S3 schemas.
- MySQL credentials are valid.
- The current host prefix exists in the auth schema.
- Route schema includes the endpoint under an enabled `app_name`.

## Request Debugging Flow

### 1. Route Not Found

Check:

- Is the endpoint present in `api_wrapper/api/routes.json`?
- Is it under `test1` or `mconnect`, or another enabled app group in `app.py`?
- Does the route method match the client method?
- Did the app restart after route schema changes?

### 2. Authentication Fails

Check:

- `Host` header prefix matches auth schema domain.
- Route config has expected `auth` entries.
- Basic/JWT auth entry exists for the domain.
- DB query configured in auth schema returns a row.
- JWT decode key and algorithm are correct.
- IP whitelist is disabled or client IP is present in allowed IP list.

### 3. Schema Not Found

Check selected path logic:

- admin source path if `source` header is used
- merchant-level path
- category-level path
- `SOLAR_CATEGORY_ID` behavior for category naming

Look for `schema_path` logs or add temporary logging if needed.

### 4. Validation Fails

Check:

- Request payload shape.
- `requestBody.content` JSON Schema.
- Required fields.
- Field-level `message` objects.
- GET query params, because GET requests are converted into request body state.

### 5. Rule Or Function Fails

Check:

- Condition operator and operands.
- Resolver expressions such as `$request.*`, `$env.*`, `$token.*`, and state references.
- Whether `functions.init` created expected state.
- Whether a function returned a `CF300` style response.

### 6. Persistence Fails

Check:

- MySQL connection variables.
- Generated SQL query shape from schema.
- Required state keys used in query params.
- Insert/update values.
- Raw SQL syntax.
- One-row vs multi-row result shape assumptions.

### 7. Response Is Missing Or Wrong

Check:

- Response block exists for returned `cf_code`.
- `status_code` exists under response content.
- Response values resolve correctly.
- Component calls in response content use correct argument format.
- Response actions do not fail silently.

## Logs

`print_log()` does two things:

1. Prints locally.
2. Sends to CloudWatch through `CloudWatchLogHandler`.

Current hardcoded CloudWatch destination:

```text
log group: /aws/api_wrapper
log stream: mconnect
```

CloudWatch failures are printed locally.

## Common Operational Risks

| Risk | Why It Matters |
| --- | --- |
| S3 schema changes bypass code review | They can alter auth, DB writes, external calls, and responses |
| Raw SQL in schemas | A malformed query can break production behavior |
| `calculate` uses `eval()` | Expressions must not contain untrusted arbitrary strings |
| PHP script path is container-specific | Local runs may fail encryption/decryption |
| Missing schema response block | Pipeline can fail after business logic completes |
| External API timeouts | Karza/Pirimid calls can block request completion |
| Silent `None` from resolver | Missing keys may surface later as confusing failures |

## Feature Release Checklist

For every feature addition or update:

- Update S3 route schema if endpoint/method/auth changed.
- Update S3 auth schema if auth behavior changed.
- Update merchant/category/admin endpoint schema.
- Update endpoint doc under `documentation/endpoints/`.
- Update `documentation/operations.md` for new operation usage.
- Update `documentation/key-resolution.md` for new shared state keys or resolver patterns.
- Update `documentation/database.md` for table/column changes.
- Update integration docs if Karza, Pirimid, S3 upload, encryption, or another external service changed.
- Test success, auth failure, validation failure, business failure, and external dependency failure paths.