> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bookivox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Installer les SDK Bookivox étape par étape : prérequis, création de la clé API, environnements Python et Node, configuration, premier appel de vérification et dépannage.

Ce guide couvre l'installation complète : prérequis, création de la clé API,
environnement isolé, configuration, premier appel de vérification et résolution
des erreurs les plus fréquentes.

## 1. Prérequis

| Outil | Version minimale | Vérifier |
| - | - | - |
| Python | **3.11** | `python3 --version` |
| Node.js | **18** | `node --version` |
| Compte Bookivox | aucune | [app.bookivox.com](https://app.bookivox.com) |

```bash theme={null}
python3 --version   # Python 3.11.x minimum
node --version      # v18.x minimum
```

> [!NOTE]
>
> Le SDK Python utilise les `TypedDict` avec champs requis (PEP 655) : Python 3.10
> et antérieur ne sont pas supportés. Le SDK TypeScript est **ESM uniquement** et
> s'appuie sur le `fetch` global, disponible nativement à partir de Node 18.

## 2. Créer une clé API

Les SDK s'authentifient avec une clé d'organisation, transmise dans l'en-tête
`X-API-Key`.

**1. Ouvrir la page Clés API**

Rendez-vous dans [Clés API](https://docs.bookivox.com/workspace/api-keys.md), dans l'espace de travail
qui contient les agents à piloter.

**2. Créer une clé**

Donnez-lui un nom explicite (`prod-backend`, `ci-deploy`, `poste-alice`) :
vous pourrez ainsi la révoquer sans impacter les autres usages.

**3. Copier la clé immédiatement**

La valeur complète (`bookeys_sk-...`) n'est affichée **qu'une seule fois**.
Si vous la perdez, révoquez-la et créez-en une nouvelle.

**4. La stocker hors du code**

Variable d'environnement, gestionnaire de secrets, ou `bookivox login` pour
un usage local. Jamais dans un fichier versionné.

> [!WARNING]
>
> Une clé API donne accès à **toutes les ressources de son organisation**. Ne
> l'exposez jamais dans un frontend, une application mobile, un dépôt public ou
> une capture d'écran. Si elle a fuité, révoquez-la immédiatement.

## 3. Installer le SDK Python

### Créer un environnement isolé

```bash theme={null}
# macOS / Linux
python3 -m venv .venv
source .venv/bin/activate
```

```powershell theme={null}
# Windows (PowerShell)
py -3 -m venv .venv
.venv\Scripts\Activate.ps1
```

Une fois l'environnement activé, l'invite de commande affiche `(.venv)` et
`python` pointe vers l'interpréteur du projet.

### Installer le paquet

> [tab] pip
>
> ```bash theme={null}
> pip install bookivox
> ```

> [tab] uv
>
> ```bash theme={null}
> uv add bookivox
> ```

> [tab] poetry
>
> ```bash theme={null}
> poetry add bookivox
> ```

Le paquet Python contient **le SDK et la CLI** : une seule dépendance à
installer. Il tire uniquement `httpx` comme dépendance runtime.

### Vérifier l'installation

```bash theme={null}
python -c "import bookivox_sdk; print(bookivox_sdk.__version__)"
# 0.1.1
```

```bash theme={null}
bookivox --version
# bookivox 0.1.1
```

Si l'une des deux commandes échoue, voir la section
[Dépannage](#depannage).

## 4. Installer le SDK TypeScript

```bash theme={null}
npm install @bookivox/sdk
```

> [tab] pnpm
>
> ```bash theme={null}
> pnpm add @bookivox/sdk
> ```

> [tab] yarn
>
> ```bash theme={null}
> yarn add @bookivox/sdk
> ```

> [tab] bun
>
> ```bash theme={null}
> bun add @bookivox/sdk
> ```

Le paquet n'a **aucune dépendance runtime** et embarque ses déclarations de
types (`.d.ts`) : rien d'autre à installer.

### Configuration TypeScript recommandée

```json theme={null}
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "lib": ["ES2022", "DOM"]
  }
}
```

* Le paquet est en **ESM** (`"type": "module"`). Utilisez `import`, pas
  `require` (voir le [dépannage](#depannage)).
* `lib: ["DOM"]` fournit le type de `fetch` et de `AbortSignal` quand vous
  n'utilisez pas `@types/node` récent.
* Avec un bundler (Vite, Next.js, esbuild), `moduleResolution: "Bundler"`
  convient également.

### Vérifier l'installation

```bash theme={null}
npm ls @bookivox/sdk
```

```ts theme={null}
import { Bookivox } from "@bookivox/sdk";

console.log(new Bookivox({ apiKey: "bookeys_sk-test" }).constructor.name);
// Bookivox
```

> [!WARNING]
>
> N'appelez **jamais** l'API Bookivox depuis un navigateur ou une application
> mobile avec une clé API : la clé serait visible par n'importe quel utilisateur.
> Le SDK côté navigateur est utilisable uniquement derrière une couche serveur
> qui détient le secret.

## 5. Configurer l'authentification

L'ordre de résolution est identique dans les deux SDK : argument explicite,
puis variable d'environnement, puis valeur par défaut.

| Priorité | Python | TypeScript |
| - | - | - |
| 1 | `Bookivox(api_key=...)` | `new Bookivox({ apiKey })` |
| 2 | `BOOKIVOX_API_KEY` | `BOOKIVOX_API_KEY` |
| 3 | CLI : fichier local (`bookivox login`) | aucune |

### Variable d'environnement

```bash theme={null}
# macOS / Linux
export BOOKIVOX_API_KEY="bookeys_sk-..."
```

```powershell theme={null}
# Windows (PowerShell)
$env:BOOKIVOX_API_KEY = "bookeys_sk-..."
```

```dotenv theme={null}
# .env : ne jamais commiter ce fichier
BOOKIVOX_API_KEY=bookeys_sk-...
```

Avec Python, chargez ce fichier via `python-dotenv` (`pip install python-dotenv`)
ou `direnv` ; ne l'importez pas à la main dans le code applicatif.

> [!NOTE]
>
> L'origine de l'API est fixée à `https://api.bookivox.com` : elle n'est pas
> configurable, ni par variable d'environnement, ni par argument du client.

## 6. Premier appel de vérification

> [accordion] Python
>
> ```python theme={null}
> import os
> from bookivox_sdk import Bookivox, AuthenticationError
>
> try:
>     with Bookivox(api_key=os.environ["BOOKIVOX_API_KEY"]) as client:
>         workflows = client.list_workflows()
>         print(f"{len(workflows)} agent(s) dans l'organisation")
> except AuthenticationError:
>     raise SystemExit("Clé API invalide ou révoquée.")
> ```

> [accordion] TypeScript
>
> ```ts theme={null}
> import { Bookivox, AuthenticationError } from "@bookivox/sdk";
>
> const client = new Bookivox({ apiKey: process.env.BOOKIVOX_API_KEY! });
>
> try {
>   const workflows = await client.listWorkflows();
>   console.log(`${workflows.length} agent(s) dans l'organisation`);
> } catch (error) {
>   if (error instanceof AuthenticationError) {
>     throw new Error("Clé API invalide ou révoquée.");
>   }
>   throw error;
> }
> ```
>
> Lancez ce fichier avec `node` (ou `tsx`/`ts-node`) : le SDK est ESM.

> [accordion] CLI
>
> ```bash theme={null}
> bookivox login --api-key "$BOOKIVOX_API_KEY"
> bookivox config
> bookivox workflows list --json | head
> ```

Si cet appel renvoie une liste (même vide), l'installation, le réseau et
l'authentification sont fonctionnels. Une liste vide signifie simplement que
l'organisation ne contient encore aucun agent.

## 7. Installer depuis le dépôt GitHub

Pour auditer le code, installer une version précise ou passer par un registre
privé, installez directement depuis le dépôt public :

```bash theme={null}
# Python : depuis une archive ou un tag Git
pip install "bookivox @ git+https://github.com/limitless-influence-ai/bookivox-sdk.git@v0.1.1#subdirectory=python"
```

```bash theme={null}
# TypeScript : depuis un tarball npm ou le dépôt cloné
git clone https://github.com/limitless-influence-ai/bookivox-sdk.git
cd bookivox-sdk/typescript && npm install && npm run build
npm install /chemin/absolu/vers/bookivox-sdk/typescript
```

```bash theme={null}
# Ou à partir des archives fournies par l'équipe Bookivox
pip install ./bookivox-0.1.1-py3-none-any.whl
```

```bash theme={null}
npm install ./bookivox-sdk-0.1.1.tgz
```

La CLI est incluse dans la wheel Python : aucune installation séparée.

> [!WARNING]
>
> Épinglez toujours un tag (`@v0.1.1`) plutôt que la branche `main` : le dépôt
> évolue entre deux publications, et `main` peut contenir du code non publié.

## 8. Mettre à jour et désinstaller

```bash theme={null}
pip install --upgrade bookivox
pip uninstall bookivox
```

```bash theme={null}
npm update @bookivox/sdk
npm uninstall @bookivox/sdk
```

En Python, la version installée est lisible via `bookivox_sdk.__version__` ;
côté npm, utilisez `npm ls @bookivox/sdk`. Épinglez la version dans votre
`requirements.txt` / `package.json` pour des déploiements reproductibles.

## Dépannage

| Symptôme | Cause probable | Solution |
| - | - | - |
| `ModuleNotFoundError: No module named 'bookivox_sdk'` | Environnement virtuel non activé, ou paquet installé dans un autre interpréteur | `which python` doit pointer dans `.venv` ; réinstallez après activation |
| `bookivox: command not found` | Répertoire des scripts absent du `PATH` (`~/.local/bin`, `.venv/bin`, `Scripts`) | Activez le venv, ou ajoutez le dossier au `PATH` |
| `ERROR: Could not find a version that satisfies the requirement bookivox` | Nom ou version erroné, ou index du registre pas encore propagé | Vérifiez l'orthographe (`bookivox`), réessayez après quelques minutes ; sinon installez depuis le dépôt GitHub ou la wheel fournie ([section 7](#7-installer-depuis-le-dépôt-github)) |
| `401 AuthenticationError` | Clé invalide, révoquée ou d'un autre environnement | Vérifiez avec `bookivox config`, régénérez la clé |
| `403 PermissionDeniedError` | Clé sans droit sur la ressource ou l'organisation | Utilisez une clé de l'espace de travail concerné |
| `429 RateLimitError` | Trop de requêtes simultanées | Respectez `retry_after`, réduisez la concurrence, le SDK rejoue déjà les GET |
| `SSLCertVerificationError` / proxy d'entreprise | Certificat interne non reconnu | Injectez un `httpx.Client(verify=...)` via `http_client` (Python) ou un `fetch` instrumenté (TypeScript) |
| `ReferenceError: fetch is not defined` (Node) | Node antérieur à 18 | Mettez Node à jour, ou fournissez `fetch` via l'option du client |
| `Error [ERR_REQUIRE_ESM]` | `require()` sur un paquet ESM | Utilisez `import`, ou `await import("@bookivox/sdk")` |
| `Cannot find module '@bookivox/sdk'` (TS) | `moduleResolution` incompatible | `NodeNext` ou `Bundler` |
| `fetch failed` / `ECONNREFUSED` | Réseau, DNS ou proxy | Vérifiez la connectivité sortante vers `https://api.bookivox.com` |

> [card] [SDK Python](https://docs.bookivox.com/sdk/python.md)
>
> Méthodes, modèles typés et gestion des erreurs.

> [card] [SDK TypeScript](https://docs.bookivox.com/sdk/typescript.md)
>
> Client ESM, typage généré, annulation.

> [card] [CLI bookivox](https://docs.bookivox.com/sdk/cli.md)
>
> Login sécurisé, commandes et codes de sortie.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.