Bookivox Documentation

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

python3 --version   # Python 3.11.x minimum
node --version      # v18.x minimum

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.

Ouvrir la page Clés API

Rendez-vous dans Clés API, dans l’espace de travail qui contient les agents à piloter.

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.

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.

La stocker hors du code

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

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é

# macOS / Linux
python3 -m venv .venv
source .venv/bin/activate

# 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

pip
uv
poetry

pip install bookivox

uv add bookivox

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

python -c "import bookivox_sdk; print(bookivox_sdk.__version__)"
# 0.1.1

bookivox --version
# bookivox 0.1.1

Si l’une des deux commandes échoue, voir la section Dépannage.

4. Installer le SDK TypeScript

npm install @bookivox/sdk

pnpm
yarn
bun

pnpm add @bookivox/sdk

yarn add @bookivox/sdk

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

{
  "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).
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

npm ls @bookivox/sdk

import { Bookivox } from "@bookivox/sdk";

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

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

# macOS / Linux
export BOOKIVOX_API_KEY="bookeys_sk-..."

# Windows (PowerShell)
$env:BOOKIVOX_API_KEY = "bookeys_sk-..."

# .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.

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

Python

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.")

TypeScript

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.

CLI

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 :

# 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"

# 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

# Ou à partir des archives fournies par l'équipe Bookivox
pip install ./bookivox-0.1.1-py3-none-any.whl

npm install ./bookivox-sdk-0.1.1.tgz

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

É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

pip install --upgrade bookivox
pip uninstall bookivox

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)
`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`

SDK officiels

Installation

1. Prérequis

2. Créer une clé API

3. Installer le SDK Python

Créer un environnement isolé

Installer le paquet

Vérifier l’installation

4. Installer le SDK TypeScript

Configuration TypeScript recommandée

Vérifier l’installation

5. Configurer l’authentification

Variable d’environnement

6. Premier appel de vérification

7. Installer depuis le dépôt GitHub

8. Mettre à jour et désinstaller

Dépannage

SDK Python

SDK TypeScript

CLI bookivox

​1. Prérequis

​2. Créer une clé API

​3. Installer le SDK Python

​Créer un environnement isolé

​Installer le paquet

​Vérifier l’installation

​4. Installer le SDK TypeScript

​Configuration TypeScript recommandée

​Vérifier l’installation

​5. Configurer l’authentification

​Variable d’environnement

​6. Premier appel de vérification

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

​8. Mettre à jour et désinstaller

​Dépannage

SDK Python

SDK TypeScript

CLI bookivox

1. Prérequis

2. Créer une clé API

3. Installer le SDK Python

Créer un environnement isolé

Installer le paquet

Vérifier l’installation

4. Installer le SDK TypeScript

Configuration TypeScript recommandée

Vérifier l’installation

5. Configurer l’authentification

Variable d’environnement

6. Premier appel de vérification

7. Installer depuis le dépôt GitHub

8. Mettre à jour et désinstaller

Dépannage