# API TypeScript

Utilisez Sovrium comme bibliothèque dans votre projet TypeScript. Importez `start`, `build` et le type `AppConfig` pour un contrôle programmatique complet avec une configuration typée.

```typescript
import { start, build, generateAppJsonSchema, validateConfig } from 'sovrium'
import type { AppConfig, SimpleServer, ValidateConfigResult } from 'sovrium'

// All config types are available:
// PageConfig, TableConfig, ThemeConfig, AuthConfig,
// ComponentConfig, LanguageConfig, AnalyticsConfig, ...
```

## Pourquoi TypeScript ?

Utiliser Sovrium par programmation vous offre des avantages au-delà du CLI.

### Sécurité des types

Le type `AppConfig` fournit l'autocomplétion pour chaque propriété et type de champ. Détectez les erreurs à la compilation, pas à l'exécution.

### Contrôle programmatique

Générez la configuration dynamiquement, composez des schémas et intégrez Sovrium dans des applications existantes.

### Intégration à l'IDE

IntelliSense complet dans VS Code et JetBrains — documentation au survol, accès à la définition et erreurs de type.

## `start(app, options?)`

Démarre un serveur de développement à partir d'un objet de configuration typé. Retourne une instance de serveur dotée d'une méthode `stop()`.

```typescript
import { start } from 'sovrium'

const server = await start({
  name: 'my-app',
})

console.log(`Server running at ${server.url}`)
```

### `StartOptions`

Deuxième argument optionnel pour configurer le serveur.

| Propriété   | Description                                                                       |
| ----------- | --------------------------------------------------------------------------------- |
| `port`      | Numéro de port (0–65535). 0 sélectionne un port disponible. Par défaut : 3000.    |
| `hostname`  | Nom d'hôte du serveur. Par défaut : `localhost`.                                  |
| `publicDir` | Répertoire de fichiers statiques. Les fichiers sont servis à leur chemin relatif. |

```typescript
import { start } from 'sovrium'

const server = await start(
  {
    name: 'my-app',
    tables: [
      {
        id: 1,
        name: 'tasks',
        fields: [
          { id: 1, name: 'title', type: 'single-line-text', required: true },
          { id: 2, name: 'done', type: 'checkbox' },
        ],
      },
    ],
  },
  {
    port: 8080,
    hostname: '0.0.0.0',
    publicDir: './public',
  }
)
```

## `build(app, options?)`

Génère un site statique à partir d'un objet de configuration typé.

### `GenerateStaticOptions`

Deuxième argument optionnel pour contrôler la sortie statique.

| Propriété            | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| `outputDir`          | Répertoire de sortie. Par défaut : `./static`.              |
| `baseUrl`            | URL de base pour le sitemap et les liens canoniques.        |
| `basePath`           | Préfixe de chemin pour les déploiements en sous-répertoire. |
| `deployment`         | Plateforme cible : `github-pages` ou `generic`.             |
| `languages`          | Tableau de codes de langue pour la génération.              |
| `defaultLanguage`    | Code de langue par défaut.                                  |
| `generateSitemap`    | Génère `sitemap.xml`. Par défaut : `false`.                 |
| `generateRobotsTxt`  | Génère `robots.txt`. Par défaut : `false`.                  |
| `hydration`          | Active l'hydratation côté client. Par défaut : `false`.     |
| `generateManifest`   | Génère `manifest.json` pour les PWA. Par défaut : `false`.  |
| `bundleOptimization` | Stratégie de découpage : `split` ou `none`.                 |
| `publicDir`          | Répertoire de ressources statiques à copier dans la sortie. |

```typescript
import { build } from 'sovrium'

await build(
  {
    name: 'my-site',
    pages: [
      {
        name: 'home',
        path: '/',
        sections: [
          { type: 'heading', content: 'Welcome' },
          { type: 'paragraph', content: 'Built with Sovrium.' },
        ],
      },
    ],
  },
  {
    outputDir: './dist',
    baseUrl: 'https://example.com',
    deployment: 'github-pages',
    generateSitemap: true,
    generateRobotsTxt: true,
  }
)
```

## `generateAppJsonSchema()`

Génère le JSON Schema (Draft-07) de la configuration d'application Sovrium. Retourne un objet simple, adapté à la sérialisation ou à un usage programmatique.

```typescript
import { generateAppJsonSchema } from 'sovrium'

const schema = generateAppJsonSchema()
Bun.write('app.schema.json', JSON.stringify(schema, null, 2))
```

## `validateConfig(config)`

Valide une valeur inconnue par rapport à l'AppSchema Sovrium. Retourne un objet résultat indiquant si la configuration est valide, avec la configuration analysée ou le détail des erreurs.

```typescript
import { validateConfig } from 'sovrium'

const result = validateConfig({ name: 'My App' })
if (result.valid) {
  console.log(result.config.name)
} else {
  console.error(result.errors)
}
```

## `AppConfig`

Le type principal pour typer vos objets de configuration JSON ou YAML. Importez-le depuis `sovrium` pour obtenir une autocomplétion et une vérification de type complètes.

| Propriété      | Description                                                                                                          |
| -------------- | -------------------------------------------------------------------------------------------------------------------- |
| `name`         | Nom de l'application. En minuscules, compatible npm (par ex. `my-app`, `@org/app`).                                  |
| `version?`     | Chaîne de version SemVer (par ex. `1.0.0`).                                                                          |
| `description?` | Description de l'application en une seule ligne.                                                                     |
| `tables?`      | Tableau de définitions de tables de données avec champs, index et contraintes.                                       |
| `theme?`       | Jetons de design : couleurs, polices, espacement, animations, points de rupture, ombres, borderRadius.               |
| `pages?`       | Tableau de configurations de pages avec métadonnées, sections et scripts.                                            |
| `forms?`       | Définitions de formulaires autonomes qui capturent des soumissions ou déclenchent des automatisations.               |
| `auth?`        | Configuration d'authentification : stratégies, rôles, plugins (admin, organization).                                 |
| `languages?`   | Configuration multilingue : langues prises en charge, langue par défaut, traductions.                                |
| `components?`  | Tableau de modèles de composants réutilisables avec substitution de variables.                                       |
| `automations?` | Workflows pilotés par événements : déclencheurs plus actions séquentielles.                                          |
| `actions?`     | Modèles d'actions réutilisables référencés depuis les automatisations via `$ref`.                                    |
| `connections?` | Identifiants de services externes (OAuth2, clé API, basic, bearer).                                                  |
| `agents?`      | Agents IA agissant sous un rôle d'authentification avec des outils restreints.                                       |
| `buckets?`     | Conteneurs de stockage de fichiers nommés avec des limites et des permissions par bucket.                            |
| `env?`         | Variables d'environnement d'automatisation déclarées, référencées comme `$env.NAME`.                                 |
| `analytics?`   | Analytique intégrée respectueuse de la vie privée. Définissez `true` pour les valeurs par défaut ou passez un objet. |

```typescript
import type { AppConfig } from 'sovrium'

const config: AppConfig = {
  name: 'my-app',
  version: '1.0.0',
  description: 'My application',
  tables: [/* ... */],
  theme: {/* ... */},
  pages: [/* ... */],
  auth: {/* ... */},
  languages: {/* ... */},
  components: [/* ... */],
  analytics: true,
}
```

:::callout
**Complexité incrémentale.** Seul `name` est obligatoire. Ajoutez `tables`, `theme`, `pages`, `auth`, `languages`, `components` et `analytics` à mesure que vous en avez besoin.
:::

## Référence des types

Types TypeScript supplémentaires exportés depuis le paquet `sovrium`. Importez-les avec `import type { ... } from "sovrium"`.

### `SimpleServer`

Retourné par `start()`. Une interface légère vers le serveur en cours d'exécution.

| Propriété | Description                                                                                   |
| --------- | --------------------------------------------------------------------------------------------- |
| `url`     | URL du serveur incluant le protocole et le port (par ex. `"http://localhost:3000"`).          |
| `stop()`  | Arrête proprement le serveur. Retourne une Promise qui se résout lorsque l'arrêt est terminé. |

```typescript
import { start } from 'sovrium'
import type { SimpleServer } from 'sovrium'

const server: SimpleServer = await start({ name: 'my-app' })
console.log(server.url) // "http://localhost:3000"
await server.stop() // graceful shutdown
```

### `PageConfig`

Configuration d'une page unique. Élément de `AppConfig['pages']`.

```typescript
const page: PageConfig = {
  name: 'home',
  path: '/',
  sections: [{ type: 'heading', content: 'Welcome' }],
}
```

### `TableConfig`

Configuration d'une table de données unique. Élément de `AppConfig['tables']`.

```typescript
const table: TableConfig = {
  id: 1,
  name: 'tasks',
  fields: [{ id: 1, name: 'title', type: 'single-line-text' }],
}
```

### `ComponentConfig`

Modèle de composant réutilisable avec des espaces réservés de variables. Élément de `AppConfig['components']`.

```typescript
const hero: ComponentConfig = {
  name: 'hero',
  type: 'section',
  children: [{ type: 'heading', content: '$title' }],
}
```

### `ThemeConfig`

Jetons de design pour les couleurs, la typographie, l'espacement, les ombres et plus encore.

```typescript
const theme: ThemeConfig = {
  colors: { primary: '#3b82f6' },
  fonts: { sans: 'Inter, sans-serif' },
}
```

### `AuthConfig`

Stratégies d'authentification, rôles et configuration des plugins.

```typescript
const auth: AuthConfig = {
  strategies: [{ type: 'emailAndPassword' }],
  roles: [{ name: 'admin' }, { name: 'member' }],
}
```

### `LanguageConfig`

Prise en charge multilingue avec traductions et détection de langue.

```typescript
const languages: LanguageConfig = {
  supported: ['en', 'fr'],
  default: 'en',
}
```

### `AnalyticsConfig`

Analytique intégrée respectueuse de la vie privée. Utilisez `true` pour les valeurs par défaut ou un objet pour des réglages personnalisés.

```typescript
// Simple: just enable defaults
const analytics: AnalyticsConfig = true

// Custom settings
const custom: AnalyticsConfig = { retentionDays: 90, excludedPaths: ['/admin'] }
```

### `GenerateStaticResult`

Retourné par `build()`. Contient le chemin du répertoire de sortie et la liste des fichiers générés.

| Propriété   | Description                                                                       |
| ----------- | --------------------------------------------------------------------------------- |
| `outputDir` | Chemin absolu du répertoire de sortie (par ex. `"./static"`).                     |
| `files`     | Tableau des chemins de fichiers générés pendant le build (HTML, CSS, ressources). |

```typescript
import { build } from 'sovrium'
import type { GenerateStaticResult } from 'sovrium'

const result: GenerateStaticResult = await build({
  name: 'my-site',
  pages: [/* ... */],
})
console.log(result.outputDir) // "./static"
console.log(result.files.length) // number of generated files
```

### `ValidateConfigResult`

Retourné par `validateConfig()`. Indique si la configuration est valide et fournit la configuration analysée ou le détail des erreurs.

| Propriété | Description                                                                 |
| --------- | --------------------------------------------------------------------------- |
| `valid`   | Booléen. `true` si la configuration est valide par rapport à l'AppSchema.   |
| `errors`  | Tableau d'objets d'erreurs de validation. Vide lorsque `valid` est `true`.  |
| `config`  | L'objet `AppConfig` analysé. Présent uniquement lorsque `valid` est `true`. |

```typescript
import { validateConfig } from 'sovrium'
import type { ValidateConfigResult } from 'sovrium'

const result: ValidateConfigResult = validateConfig({ name: 'my-app' })
console.log(result.valid) // true or false
console.log(result.errors) // validation error array (empty if valid)
console.log(result.config) // parsed AppConfig (if valid)
```

## Mode surveillance

En développement, utilisez le mode surveillance intégré de Bun pour redémarrer automatiquement votre script lorsque les fichiers changent.

```bash
bun --watch index.ts
```

:::callout
**Reload vs watch.** `bun --watch` redémarre l'ensemble du processus dès qu'un fichier importé change. Pour des changements de configuration uniquement, l'option `--watch` du CLI est plus efficace.
:::

## Exemples

Cas d'utilisation courants avec Sovrium en TypeScript.

### Serveur minimal

```typescript
import { start } from 'sovrium'

const server = await start({
  name: 'my-app',
})

console.log(`Server running at ${server.url}`)
```

### Avec des tables de données

```typescript
import { start } from 'sovrium'

const server = await start(
  {
    name: 'my-app',
    tables: [
      {
        id: 1,
        name: 'tasks',
        fields: [
          { id: 1, name: 'title', type: 'single-line-text', required: true },
          { id: 2, name: 'done', type: 'checkbox' },
        ],
      },
    ],
  },
  {
    port: 8080,
    hostname: '0.0.0.0',
    publicDir: './public',
  }
)
```

### Génération de site statique

```typescript
import { build } from 'sovrium'

await build(
  {
    name: 'my-site',
    pages: [
      {
        name: 'home',
        path: '/',
        sections: [
          { type: 'heading', content: 'Welcome' },
          { type: 'paragraph', content: 'Built with Sovrium.' },
        ],
      },
    ],
  },
  {
    outputDir: './dist',
    baseUrl: 'https://example.com',
    deployment: 'github-pages',
    generateSitemap: true,
    generateRobotsTxt: true,
  }
)
```

### Configuration dynamique

```typescript
import { start } from 'sovrium'
import type { AppConfig, PageConfig, TableConfig, ThemeConfig } from 'sovrium'

// Compose config from typed sub-configs
const theme: ThemeConfig = {
  colors: { primary: process.env.BRAND_COLOR ?? '#3b82f6' },
}

const tables: TableConfig[] = ['users', 'posts'].map((name, i) => ({
  id: i + 1,
  name,
  fields: [
    { id: 1, name: 'title', type: 'single-line-text' as const, required: true },
    { id: 2, name: 'created_at', type: 'date' as const, includeTime: true },
  ],
}))

const pages: PageConfig[] = [{ name: 'home', path: '/', sections: [] }]

const app: AppConfig = {
  name: 'dynamic-app',
  tables,
  pages,
  theme,
}

await start(app)
```