# Addon: MSAL — Angular

Referencia ejecutable para **project-addons**. Identificadores: `addon_id = msal`, `tecnologia = angular`.

## Contrato para el agente (leer primero)

| ID | Regla |
| -- | ----- |
| S1 | **Parar sin aplicar pasos** si el proyecto no es Angular **21+** o no usa `ApplicationConfig` / `app.config.ts` como en esta receta. |
| S2 | Ejecutar secciones **solo** en el [orden fijo](#orden-de-ejecución-no-alterar); no reordenar ni omitir secciones salvo que la referencia diga “si no aplica”. |
| S3 | Directorio de terminal para `npm install`: raíz del `package.json` de la app Angular (en monorepo: el paquete correcto, no asumir raíz del repo). |
| S4 | Valores reales de MSAL para entornos no desarrollo: no inventar secretos; usar placeholders según sección 2. |

| Campo | Valor |
| ----- | ----- |
| **Tecnología** | Angular (standalone / `app.config.ts`) |
| **Versión mínima de Angular** | **21** |
| **Paquetes** | `@factor_ec/msal`, `@factor_ec/utils`, `@azure/msal-angular` |
| **Manejador** | **npm** únicamente (`npm install …`). |

## Cuándo usar / cuándo no

- **Usar:** Angular **21+**, `app.config.ts` + `ApplicationConfig`, paquete `@factor_ec/msal`.
- **No usar tal cual:** Angular menor a 21, no Angular, solo `AppModule` sin `app.config.ts`, u otro framework.

## Orden de ejecución (no alterar)

1. [Instalar dependencias](#1-instalar-dependencias)
2. [Entornos](#2-modelo-y-archivos-en-srcenvironments)
3. [`app.config.ts`](#3-srcappappconfigts)
4. [Cierre](#4-después-de-este-addon-checklist)

---

## 1. Instalar dependencias

```bash
npm install @factor_ec/msal @factor_ec/utils @azure/msal-angular
```

---

## 2. Modelo y archivos en `src/environments`

### 2.1 Modelo (`environment.ts` base u homólogo)

- El tipo `Environment` debe incluir `msal: MsalConfig` importado de `@factor_ec/msal`.
- No duplicar la forma de `MsalConfig`: usar el tipo del paquete.

```typescript
import { MsalConfig } from '@factor_ec/msal';

export interface Environment {
  production: boolean;
  // ... resto de propiedades ya existentes
  msal: MsalConfig;
}
```

### 2.2 Campos concretos

Los nombres de propiedades los define `MsalConfig` en `@factor_ec/msal`. Al pedir datos al usuario, usar los nombres del tipo actual del paquete.

### 2.3 Valores solo para desarrollo

Antes de editar `environment.development.ts`, obtener del usuario (o del chat si ya los dio):

- `clientId`
- `authority`
- `redirectUri`
- `postLogoutRedirectUri` (si aplica)

### 2.4 `environment.development.ts`

Rellenar el objeto `msal` con los valores de desarrollo obtenidos.

### 2.5 Otros `environment*.ts`

En **todos** los demás (`environment.ts`, `environment.production.ts`, `environment.staging.ts`, etc., según existan): añadir `msal` con la **misma forma** que `MsalConfig`, usando `''` en campos obligatorios. Opcionales: `''` u omitir si el tipo y el proyecto lo permiten.

Ejemplo mínimo en un entorno no desarrollo:

```typescript
msal: {
  clientId: '',
  authority: '',
  redirectUri: '',
  postLogoutRedirectUri: '', // omitir si es opcional y el tipo lo permite
},
```

---

## 3. `src/app/app.config.ts`

Fusionar con los `providers` existentes. No eliminar `provideRouter`, HTTP u otros salvo lo indicado en 3.1.

### 3.1 Imports y `environment`

Ajustar la ruta relativa según la ubicación real de `app.config.ts`:

- Si está en `src/app/`: suele ser `import { environment } from '../environments/environment';`
- Si está en `src/`: puede ser `import { environment } from './environments/environment';`

### 3.2 Providers MSAL

```typescript
import { ApplicationConfig } from '@angular/core';
import { MSAL_INSTANCE } from '@azure/msal-angular';
import { MSAL_CONFIG, createMsalInstance } from '@factor_ec/msal';
import { environment } from '../environments/environment'; // ajustar

export const appConfig: ApplicationConfig = {
  providers: [
    { provide: MSAL_CONFIG, useValue: environment.msal },
    {
      provide: MSAL_INSTANCE,
      useFactory: createMsalInstance,
      deps: [MSAL_CONFIG],
    },
    // ... conservar el resto de providers del proyecto
  ],
};
```

### 3.3 `AuthProvider` → `AuthService`

Imports:

- `AuthProvider` desde `@factor_ec/utils`
- `AuthService` desde `@factor_ec/msal`

```typescript
import { AuthProvider } from '@factor_ec/utils';
import { AuthService } from '@factor_ec/msal';
```

- **Si ya existe** `{ provide: AuthProvider, useClass: … }`: cambiar a `useClass: AuthService`, importar `AuthProvider` desde `@factor_ec/utils`, y quitar la clase antigua que dejara de usarse aquí.
- **Si no existe:** añadir `{ provide: AuthProvider, useClass: AuthService }` a `providers`.

---

## 4. Después de este addon (checklist)

Completar manualmente o vía CI/secretos los valores reales de `msal` en staging/producción cuando corresponda (no violar política de no secretos en repo).

### Checklist de verificación (agente)

- [ ] `npm install @factor_ec/msal @factor_ec/utils @azure/msal-angular` en el directorio correcto del `package.json`.
- [ ] Tipo `Environment` incluye `msal: MsalConfig` desde `@factor_ec/msal`.
- [ ] Usuario consultado para dev; `environment.development.ts` con valores reales de desarrollo.
- [ ] Resto de `environment*.ts` con `msal` en forma mínima (`''` donde obligue el tipo).
- [ ] `app.config.ts`: `MSAL_CONFIG`, `MSAL_INSTANCE`, `createMsalInstance`, `useValue: environment.msal`; import de `environment` correcto; resto de providers conservados salvo reemplazo de 3.3.
- [ ] `{ provide: AuthProvider, useClass: AuthService }` con imports de 3.3.