# Key Resolution

## Purpose

Schemas use dynamic string references instead of hard-coded Python values. `key_resolver.py` resolves those references at runtime.

The resolver is used by:

- operations
- query builders
- response generation
- authentication queries
- function blocks
- component calls

## Supported Reference Types

### Literal Values

Numeric strings, empty strings, `.`, and booleans are returned directly or as simple string conversions.

Examples:

```text
100
.
true
```

### Generated Request ID

`request_id` resolves to a new UUID string.

Example:

```json
{
  "operation": "setData",
  "stateKey": "request_id",
  "value": "request_id"
}
```

### Current Timestamp

`datetime.CUR_TIMESTAMP` resolves through `helper_functions.resolve_date()`.

Current format:

```text
YYYY-MM-DD, HH:MM:SS
```

Example:

```json
{
  "created_at": "datetime.CUR_TIMESTAMP"
}
```

### Environment Variables

Use `$env.<NAME>`.

Example:

```text
$env.AWS_BUCKET
$env.CF_ENDPOINT
$env.SECRET_KEY
```

### Request Body

Use `$request.<path>`.

Examples:

```text
$request.name
$request.profession.professionDetails.monthlyIncome
$request.addresses[0].pincode
```

For GET requests, `authentication.py` converts query parameters into `request.get_json`, so `$request.*` can also refer to query params.

### Auth Headers

Use `$auth.<Header-Name>`.

Examples:

```text
$auth.Authorization
$auth.client_id
$auth.client_secret
```

The resolver reads these from `request.headers`.

### JWT Payload

Use `$token.<key>`.

Example:

```text
$token.merchant_id
```

JWT payload is stored in Flask `g` during authentication.

### Request-Scoped State

Use `$<state_key>` or `$<state_key>.<nested_key>`.

Examples:

```text
$merchant_id
$merchant_details.merchant_name
$consumer_application_id
$response.return_code
```

State values are stored with:

```python
helper_functions.set_data(key, value)
```

And read with:

```python
helper_functions.get_data(key)
```

### Component Calls

Use:

```text
function_name->arg1,arg2
```

The resolver delegates to `Components.execute_component()`.

Examples:

```text
encrypt->$request.phone
json_loads->$some_json_state
format_offer->$offers
```

Components can call:

- `EncryptDecrypt.encrypt`
- `EncryptDecrypt.decrypt`
- `json.loads`
- methods on `StaticFunctions`

## Common State Keys

| State key | Set by | Purpose |
| --- | --- | --- |
| `request` | `AuthenticationSchema.request_prep()` | Prepared request body/query params |
| `token` | JWT authentication | Decoded JWT payload |
| `merchant_details` | `AuthenticationSchema.get_details()` | Merchant database row |
| `schema_path` | `APIWrapper.schema_path_creation()` | Selected S3 endpoint schema path |
| `response` | validation/operation/response generation | Current response data |
| `{table}_{auto_id}` | insert operations | Last inserted row ID |
| custom keys | schema functions/operations | Intermediate request-scoped values |

## Resolver Limitations

- Request array indexing only supports simple indexes such as `addresses[0]`.
- Nested state resolution expects dictionary-like objects.
- Missing keys often return `None` and may only be logged, so schema authors should validate required fields explicitly.
- Component argument parsing is comma-based.
- `calculate` expressions are resolved token-by-token after splitting by spaces.

## Documentation Requirement For New State Keys

When a feature adds important state keys, document them in the endpoint doc and, if reused across endpoints, add them to this file.