> ## Documentation Index
> Fetch the complete documentation index at: https://api-documentation.kare-app.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI, SDK, publication

> Du schéma Zod au client typé, et comment cette doc est publiée

## Le flux

```mermaid theme={null}
flowchart TD
    Z["apps/api — routes + schémas Zod"] -->|yarn docs:openapi| S["openapi/{rs,bo,ad,pr}/openapi.json<br/>+ openapi/rs/asyncapi.json"]
    S --> C["pr-openapi : échoue si openapi/ n'est pas commité à jour"]
    S --> P["publish-docs : sync vers kare-docs"]
    S --> K["packages/rs-api · pr-api : types + client openapi-fetch"]
```

Personne ne maintient une spec à la main : elle est **générée depuis le code**. Chaque audience a ses
propres routes, donc sa propre spec. `rs` publie en plus une spec AsyncAPI pour ses WebSockets.

```bash theme={null}
cd apps/api && yarn docs:openapi
```

## Les packages clients

| Package                             | Contenu                                                                      |
| ----------------------------------- | ---------------------------------------------------------------------------- |
| `@kare/rs-api`                      | types générés + factory de client `openapi-fetch` pour l'audience `rs`       |
| `@kare/pr-api`                      | idem pour l'audience `pr`                                                    |
| `@kare/sdk`                         | client fetch OpenAPI historique, encore consommé par `backoffice` et `audit` |
| `@kare/core`                        | code partagé non-HTTP                                                        |
| `@kare/ui` / `@kare/error-boundary` | composants React partagés                                                    |
| `@kare/tsconfig`                    | configs TypeScript partagées                                                 |

Un front importe le client de **son** audience : les appels sont typés, et un changement d'API casse la
compilation du front immédiatement plutôt qu'à l'exécution.

<Note>
  `apps/provider` est entièrement sur `@kare/pr-api`. `apps/kare` migre module par module de
  `@kare/sdk` vers `@kare/rs-api` et dépend encore des deux. `backoffice` et `audit` sont sur
  `@kare/sdk`.
</Note>

## Publication de cette doc

`publish-docs.yml` part sur un push de `main` touchant `openapi/**` :

<Steps>
  <Step title="Changelog">
    Le numéro de PR est extrait du sujet du commit de squash (`(#123)`), puis
    `yarn docs:changelog` écrit le bloc dans `changelog/` de ce repo. Sans SHA de base ni numéro de
    PR (run manuel, push hors PR), l'étape est sautée.
  </Step>

  <Step title="Specs">
    `openapi/` remplace intégralement `api/` dans ce repo.
  </Step>

  <Step title="Commit">
    Un token de GitHub App pousse `chore: sync API specs + changelog from monorepo@<sha>`.
  </Step>
</Steps>

<Warning>
  Le workflow ne touche **que** `api/` et `changelog/`. Il ne met **pas** à jour `docs.json` : une
  nouvelle page de changelog doit être ajoutée à la navigation à la main.
</Warning>