Installer et configurer le SDK

Préparer votre environnement de développement

Avant de coder votre première application, vous devez installer le SDK et configurer votre espace de travail. Cette leçon vous guide pas à pas, de l’installation des dépendances à la vérification que tout fonctionne.

Prérequis techniques

Assurez-vous d’avoir les outils suivants installés :

• Node.js 20+ — le runtime JavaScript (vérifiez avec node --version)
• npm 10+ ou pnpm — le gestionnaire de paquets
• Git — pour le versioning
• Un éditeur de code — VS Code recommandé, avec l’extension OpenAI

Créer un compte développeur OpenAI

Si vous n’avez pas encore d’accès développeur, rendez-vous sur le portail développeurs d’OpenAI :

1. Connectez-vous à votre compte OpenAI
2. Accédez à la section Apps Developer dans les paramètres
3. Acceptez les conditions d’utilisation du programme développeur
4. Générez une clé API Apps SDK (distincte de la clé API standard)

Cette clé sera utilisée pour authentifier vos requêtes pendant le développement et les tests.

Installer le SDK

Le SDK est disponible en TypeScript (principal) et en Python. Dans ce cours, nous utilisons TypeScript.

# Créer un nouveau projet
mkdir mon-app-chatgpt
cd mon-app-chatgpt
npm init -y

# Installer le SDK
npm install @openai/apps-sdk

# Installer les dépendances de développement
npm install -D typescript @types/node tsx

Initialiser TypeScript

npx tsc --init

Modifiez votre tsconfig.json pour activer les options nécessaires :

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true
  },
  "include": ["src/**/*"]
}

Configurer le manifest de l’application

Chaque app ChatGPT nécessite un fichier chatgpt-app.json à la racine du projet. C’est la carte d’identité de votre application.

{
  "name": "Mon Application",
  "slug": "mon-application",
  "description": "Description courte de ce que fait votre app",
  "version": "1.0.0",
  "runtime": "node",
  "entry": "src/index.ts",
  "permissions": ["actions", "widgets"],
  "auth": {
    "type": "oauth2",
    "clientId": "${OAUTH_CLIENT_ID}"
  },
  "actions": "./src/actions/schema.json",
  "widgets": "./src/widgets/"
}

Champs obligatoires

Configurer les variables d’environnement

Créez un fichier .env à la racine (ne le commitez jamais) :

# .env
OPENAI_APPS_API_KEY=sk-apps-xxxxxxxxxxxxx
OPENAI_APP_SLUG=mon-application
NODE_ENV=development

Et un fichier .env.example pour documenter les variables nécessaires :

# .env.example
OPENAI_APPS_API_KEY=
OPENAI_APP_SLUG=
NODE_ENV=development

Structure de projet recommandée

mon-app-chatgpt/
├── src/
│   ├── index.ts          # Point d'entrée
│   ├── actions/
│   │   ├── schema.json   # Schéma OpenAPI des actions
│   │   └── handlers.ts   # Logique des actions
│   ├── widgets/
│   │   └── dashboard.ts  # Définitions de widgets
│   └── utils/
│       └── auth.ts       # Helpers d'authentification
├── chatgpt-app.json      # Manifest de l'app
├── tsconfig.json
├── package.json
└── .env

Vérifier l’installation

Créez un fichier src/index.ts minimal pour vérifier que tout fonctionne :

import { ChatGPTApp } from "@openai/apps-sdk";

const app = new ChatGPTApp({
  slug: process.env.OPENAI_APP_SLUG!,
});

app.action("hello", {
  description: "Retourne un message de bienvenue",
  handler: async () => {
    return { message: "Votre SDK est correctement installé !" };
  },
});

app.start();
console.log("App démarrée avec succès");

Lancez le serveur de développement :

npx tsx src/index.ts

Si vous voyez le message de confirmation, votre environnement est prêt.

Points clés à retenir

• Le SDK nécessite Node.js 20+ et un compte développeur OpenAI
• Le fichier chatgpt-app.json est le manifest obligatoire de votre app
• La structure du projet sépare actions, widgets et utilitaires
• Les variables d’environnement contiennent vos clés API — ne les commitez jamais
• Vérifiez l’installation avec un fichier index.ts minimal avant d’aller plus loin