# App Configuration

This document describes the configuration options and mechanisms used in the App.

## Environment Variables

The application uses environment variables for configuration, which are injected into the application at runtime through `window.appConfig`.

### Runtime Environment Variables

Environment variables are loaded at runtime, not build time. This allows for different configurations in different environments without rebuilding the application.

#### Development Environment

In development, environment variables are loaded from `.env` files and injected into the application through `window.appConfig` by the Vite plugin.

#### Production Environment

In production (Docker), environment variables are loaded from the container environment and injected into the application through `window.appConfig` by the `docker-entrypoint.sh` script.

### Environment Variable Naming

- All environment variables used by the client application should start with `CLIENT_`
- These variables are converted to camelCase in `window.appConfig`
- Example: `CLIENT_API_URL` becomes `window.appConfig.apiUrl`

### Available Environment Variables

| Environment Variable | Description | Default Value |
|----------------------|-------------|---------------|
| `CLIENT_API_URL` | URL of the API server | Required, or can be set to "DETECT" for auto-detection |
| `CLIENT_BASE_PATH` | Base path of the application | "/" |
| `CLIENT_APP_NAME` | Name of the application | "App" |
| `CLIENT_DEBUG` | Enable debug mode | "false" |
| `CLIENT_MAP_TILE_ENDPOINT` | Endpoint for map tiles | "" |
| `CLIENT_MAP_TILE_API_KEY` | API key for map tiles | "" |

## URL Handling

The application uses the built-in `URL` class for proper URL handling to avoid issues with slashes and ensure consistent URL formatting.

### URL Utilities

The application includes utility functions in `src/shared/lib/url-utils.ts` for common URL operations:

#### `joinUrl(base, ...paths)`

Safely joins a base URL with path segments.

```typescript
// Example
const apiUrl = joinUrl('https://api.example.com', 'v1', 'users');
// Result: https://api.example.com/v1/users
```

#### `createHashUrl(base, basePath, hashPath)`

Creates a properly formatted hash URL with the hash fragment after the trailing slash of the base path.

```typescript
// Example
const url = createHashUrl('https://example.com', 'app', 'users/123');
// Result: https://example.com/app/#users/123
```

#### `normalizeUrl(url)`

Normalizes a URL by ensuring it has a trailing slash.

```typescript
// Example
const normalizedUrl = normalizeUrl('https://api.example.com/v1');
// Result: https://api.example.com/v1/
```

#### `cleanupUrl()`

Cleans up the current URL by removing query parameters and hash fragments.

```typescript
// Example: Current URL is https://example.com/app/?code=123#/callback
cleanupUrl();
// Result: https://example.com/app/
```

### Hash-Based Routing

The application uses hash-based routing (`/#`) instead of URL-based routing for better compatibility with static hosting and to avoid server configuration for deep linking.

- All routes are prefixed with `/#`
- The hash fragment always comes after the trailing slash of the base path
- Example: `https://example.com/app/#users` (correct) vs `https://example.com/app#users` (incorrect)

## OIDC Authentication

The application uses OIDC for authentication with the following configuration:

### OIDC Configuration

- The OIDC configuration is fetched from the API server at `/apiendpoint/oidc.json`
- The OIDC provider is separate from the API provider
- The API provider gives information about the OIDC provider location

### OIDC URLs

- Authority URL: The URL of the OIDC provider, normalized to ensure it has a trailing slash
- Redirect URI: The URL to redirect to after authentication, using hash-based routing
- Post-Logout Redirect URI: The URL to redirect to after logout, using hash-based routing

### OIDC Callback Handling

- After authentication, the callback URL is cleaned up to remove query parameters and hash fragments
- The user is redirected to the intended page or the home page

## API URL Configuration

The API URL can be configured in several ways:

### Static Configuration

Set the `CLIENT_API_URL` environment variable to the URL of the API server.

### Auto-Detection

Set the `CLIENT_API_URL` environment variable to `"DETECT"` to automatically detect the API URL based on the current window location.

The auto-detection logic:
1. Takes the current window location (e.g., `https://www.example.com/path1/path2/path3`)
2. Extracts the first path segment (e.g., `path1`)
3. Constructs a new URL with just the origin and first path segment (e.g., `https://www.example.com/path1/`)

Examples:
- `https://www.example.com/path1/path2/path3/` → `https://www.example.com/path1/`
- `https://www.example.com/` → `https://www.example.com/`
- `https://www.example.com/path1` → `https://www.example.com/path1/`

If auto-detection fails, a fatal error is logged and the application does not proceed.

## Accessing Configuration in Code

### API URL

```typescript
// Use OpenAPI.BASE for the normalized API URL
import { OpenAPI } from "@merchant-api/core/OpenAPI";

const apiUrl = OpenAPI.BASE;
```

### Other Configuration

```typescript
// Access environment variables through window.appConfig
const appName = window.appConfig.appName;
const debug = window.appConfig.debug;
```

## Development Scripts

### Generate App Config

```bash
npm run generate-app-config
```

Generates the `app-config.js` file in the `public` directory based on environment variables.

### Build

```bash
npm run build
```

Builds the application for production.

### Development Server

```bash
npm run dev
```

Starts the development server with hot reloading.