Installation — JavaScript / TypeScript

Le paquet @mitoera/sdk couvre les deux côtés : un point d'entrée serveur (Node 18+) et un point d'entrée navigateur.

Point d'entrée	Import	Usage	Environnement
Serveur	@mitoera/sdk	MitoeraClient, clé secrète	Node uniquement
Navigateur	@mitoera/sdk/browser	SeatingChart, ChartDesigner, clé publique	Navigateur

L'entrée principale n'est pas utilisable côté client

@mitoera/sdk encode ses identifiants avec Buffer, qui n'existe pas dans un navigateur. L'importer dans du code client casse le build — et y exposerait de toute façon votre clé secrète. Côté navigateur, c'est @mitoera/sdk/browser, qui en est exempt.

Prérequis

• Node.js 18 ou plus — le SDK utilise le fetch natif
• ESM et CommonJS sont fournis ; les définitions TypeScript sont incluses
• Aucune dépendance de production

Installer

npm install @mitoera/sdk

Version courante : 0.1.0, licence MIT. Le paquet ne tire aucune dépendance.

Version 0.x

L'API TypeScript n'est pas figée : une 0.x peut introduire des ruptures. Épinglez la version si votre chaîne de build ne le fait pas déjà.

Autres méthodes, si vous avez besoin d'un commit précis plutôt que d'une version publiée :

tag Git

npm install github:todymic/mitoera-ts-sdk#v0.1.0

package.json

{
  "dependencies": {
    "@mitoera/sdk": "^0.1.0"
  }
}

Initialiser le client

import { MitoeraClient } from '@mitoera/sdk';

const client = new MitoeraClient({
  keyId:  process.env.MITOERA_KEY_ID!,   // pk_live_… ou pk_test_…
  secret: process.env.MITOERA_SECRET!,   // sk_…
});

En CommonJS :

const { MitoeraClient } = require('@mitoera/sdk');

Options du constructeur

Option	Type	Défaut	Description
keyId	string	—	Identifiant de clé. Requis
secret	string	—	Secret de la clé. Requis
baseUrl	string	https://api.mitoera.com	Utile pour pointer une instance locale
mode	'sandbox' | 'production'	déduit de keyId	Force l'environnement
timeoutMs	number	30000	Timeout HTTP en millisecondes

Le mode se déduit du préfixe de la clé (pk_test_ → sandbox) ; mode ne sert qu'à forcer ce comportement.

Vérifier que ça marche

const charts = await client.charts.listAll();
console.log(`${charts.length} plan(s) dans le workspace`);

Une AuthException ici signifie que la paire keyId/secret est refusée. Une liste vide est un succès : le workspace n'a simplement pas encore de plan.

Gérer les erreurs

Trois exceptions, toutes exportées par le paquet :

import { MitoeraClient, ApiException, AuthException } from '@mitoera/sdk';

try {
  await client.holds.hold(eventId, ['A-1'], holdToken);
} catch (e) {
  if (e instanceof AuthException) {
    // Clé absente, invalide ou révoquée
  } else if (e instanceof ApiException) {
    console.error(e.statusCode, e.message);  // ex. 409 « One or more seats are not available »
  } else {
    throw e;  // erreur réseau ou bug applicatif
  }
}

MitoeraException est la classe parente : l'attraper capture les deux autres.

Exemple complet — un endpoint de réservation

import express from 'express';
import { MitoeraClient, ApiException } from '@mitoera/sdk';

const app = express();
app.use(express.json());

const client = new MitoeraClient({
  keyId:  process.env.MITOERA_KEY_ID!,
  secret: process.env.MITOERA_SECRET!,
});

// 1. La page de réservation demande une session
app.post('/api/panier', async (req, res) => {
  const event = await client.events.findByIdentifier(req.body.slug);
  const session = await client.sessions.create(event.id);

  res.json({
    eventId:      event.id,
    sessionToken: session.sessionToken,   // → widget
    expiresIn:    session.expiresIn,
  });
  // holdToken : à conserver en session serveur, pas à renvoyer au client
});

// 2. Après paiement, on confirme
app.post('/api/confirmer', async (req, res) => {
  try {
    const book = await client.holds.book(
      req.body.eventId,
      req.body.seatKeys,
      req.session.holdToken,
    );
    res.json({ seats: book.bookedSeats });
  } catch (e) {
    if (e instanceof ApiException && e.statusCode === 409) {
      return res.status(409).json({ error: 'Un siège vient d\'être pris' });
    }
    throw e;
  }
});

app.listen(3000);

Suite

• Client serveur — toutes les méthodes et leurs retours
• SeatingChart — le widget côté navigateur, en TypeScript
• Brancher un paiement — le flux complet