Client serveur

Référence des sous-clients de MitoeraClient. Les deux SDK exposent les mêmes noms de méthodes ; seules la syntaxe et la nature du retour (Promise en JS, valeur directe en PHP) diffèrent.

client.holds · client.sessions · client.events · client.charts
client.categories · client.apiKeys · client.workspaces · client.reporting

holds

Le cycle de vie des sièges. Toutes les méthodes prennent le holdToken de la session concernée.

Méthode	Retour	Description
hold(eventId, seatKeys, holdToken)	HoldResponse	Bloque temporairement des sièges
book(eventId, seatKeys, holdToken)	BookResponse	Confirme la réservation
release(eventId, seatKeys, holdToken)	—	Libère des sièges
changeStatus(eventId, seatKeys, status)	—	Force un statut (available, hold, booked, canceled)

JavaScript / TypeScript

const hold = await client.holds.hold(eventId, ['A-1', 'A-2'], holdToken);
hold.holdToken;        // string
hold.seatKeys;         // string[]
hold.expiresAt;        // Date
hold.durationSeconds;  // number

const book = await client.holds.book(eventId, ['A-1', 'A-2'], holdToken);
book.bookedSeats;      // string[]
book.eventId;          // string
book.bookedAt;         // Date

await client.holds.release(eventId, ['A-1'], holdToken);
await client.holds.changeStatus(eventId, ['A-3'], 'canceled');

PHP

$hold = $client->holds->hold($eventId, ['A-1', 'A-2'], $holdToken);
$hold->holdToken;        // string
$hold->seatKeys;         // string[]
$hold->expiresAt;        // DateTimeImmutable
$hold->durationSeconds;  // int

$book = $client->holds->book($eventId, ['A-1', 'A-2'], $holdToken);
$book->bookedSeats;      // string[]
$book->eventId;          // string
$book->bookedAt;         // DateTimeImmutable

$client->holds->release($eventId, ['A-1'], $holdToken);
$client->holds->changeStatus($eventId, ['A-3'], 'canceled');

sessions

Méthode	Retour	Description
create(eventId)	SessionResponse	Ouvre une session pour un événement
refresh(sessionToken)	SessionResponse	Prolonge une session

JavaScript / TypeScript

const session = await client.sessions.create(eventId);
session.sessionToken;  // à transmettre au widget
session.holdToken;     // à garder côté serveur
session.expiresIn;     // secondes

const renewed = await client.sessions.refresh(session.sessionToken);

PHP

$session = $client->sessions->create($eventId);
$session->sessionToken;  // à transmettre au widget
$session->holdToken;     // à garder côté serveur
$session->expiresIn;     // secondes

$renewed = $client->sessions->refresh($session->sessionToken);

events

Méthode	Retour	Description
listAll()	EventResponse[]	Tous les événements du workspace
get(eventId)	EventResponse	Un événement par UUID
findByIdentifier(identifier)	EventResponse	Un événement par slug
listSeats(eventId, seatKeys?)	SeatStatusMap	Statuts des sièges
bulkUpdateSeats(eventId, seatKeys, status)	int	Change le statut en masse, renvoie le nombre de sièges touchés
create(title, identifier, chartId?)	EventResponse	Crée un événement
update(eventId, fields)	EventResponse	Met à jour titre et identifiant
linkChart(eventId, chartId)	—	Associe un plan publié
delete(eventId)	—	Supprime l'événement

SeatStatusMap

listSeats() ne renvoie pas un tableau brut mais un objet interrogeable :

JavaScript / TypeScript

const map = await client.events.listSeats(eventId);

map.available();          // string[]
map.held();               // string[]
map.booked();             // string[]
map.isAvailable('A-1');   // boolean

for (const [seatKey, status] of map) {
  console.log(seatKey, status);
}

PHP

$map = $client->events->listSeats($eventId);

$map->available();          // string[]
$map->held();               // string[]
$map->booked();             // string[]
$map->isAvailable('A-1');   // bool

foreach ($map as $seatKey => $status) {
    echo "$seatKey : $status\n";
}

held() interroge le statut hold

Le nom de la méthode et la valeur transmise par l'API diffèrent : map.held() renvoie les sièges dont le statut vaut hold. Si vous comparez les statuts à la main plutôt que par ces méthodes, c'est 'hold' qu'il faut tester, jamais 'held'.

Passer seatKeys en second argument limite la réponse à ces sièges — utile pour vérifier une poignée de places sans rapatrier une salle entière. Effet de bord utile : un siège du plan jamais manipulé est créé en available au lieu d'être absent de la réponse.

Sous le capot, l'API renvoie un objet indexé par clé de siège (voir Événements) ; SeatStatusMap encapsule cette forme pour vous éviter de la manipuler directement.

charts

Méthode	Retour	Description
listAll()	ChartResponse[]	Tous les plans du workspace
get(chartId)	ChartResponse	Un plan par UUID
create(name)	ChartResponse	Crée un plan vide
update(chartId, fields)	ChartResponse	Renomme, modifie
setObjects(chartId, objects)	ChartResponse	Remplace les objets du plan (sièges, rangées, formes)
publish(chartId)	ChartResponse	Publie le plan
markPending(chartId)	ChartResponse	Repasse le plan en attente de republication
delete(chartId)	—	Supprime le plan

Le SDK PHP expose en plus archive(chartId).

JavaScript / TypeScript

const chart = await client.charts.create('Salle Olympia');
await client.charts.setObjects(chart.id, objects);
await client.charts.publish(chart.id);

chart.status;          // 'draft' | 'published' | 'archived'
chart.pendingChanges;  // boolean — modifié depuis la dernière publication

PHP

$chart = $client->charts->create('Salle Olympia');
$client->charts->setObjects($chart->id, $objects);
$client->charts->publish($chart->id);

$chart->isPublished();   // bool
$chart->isDraft();       // bool
$chart->pendingChanges;  // bool

categories

Les catégories sont rattachées à un plan : toutes les méthodes prennent un chartId.

Méthode	Retour	Description
listForChart(chartId)	CategoryResponse[]	Catégories du plan
get(chartId, categoryKey)	CategoryResponse	Une catégorie
create(chartId, name, color, …)	CategoryResponse	Crée une catégorie
update(chartId, categoryKey, fields)	CategoryResponse	Modifie nom et couleur
delete(chartId, categoryKey)	—	Supprime la catégorie

En PHP, create() accepte deux paramètres supplémentaires : ?string $key = null et int|float $price = 0. Le prix est ignoré par l'API — le modèle de catégorie ne comporte aucun champ de tarif.

JavaScript / TypeScript

await client.categories.create(chartId, 'Carré Or', '#E8602A');
await client.categories.update(chartId, categoryKey, { name: 'Carré Or+' });

PHP

$client->categories->create($chartId, 'Carré Or', '#E8602A');
$client->categories->update($chartId, $categoryKey, ['name' => 'Carré Or+']);

apiKeys

Méthode	Retour	Description
listAll()	ApiKeyResponse[]	Clés du workspace (sans les secrets)
create(name, scope)	ApiKeyCreatedResponse	Crée une clé — scope vaut PUBLIC ou BACKOFFICE
delete(apiKeyId)	—	Révoque une clé, avec effet immédiat

Le secret n'est renvoyé qu'à la création. Il n'existe aucun moyen de le relire ensuite.

workspaces

Méthode	Retour	Description
listAll()	WorkspaceResponse[]	Workspaces accessibles
getCurrent()	WorkspaceResponse	Workspace de la clé courante
create(name)	WorkspaceResponse	Crée un workspace
switchTo(workspaceId)	WorkspaceResponse	Bascule le contexte
invite(email, role)	—	Invite un membre — role vaut MEMBER par défaut
listMembers()	WorkspaceMember[]	Membres du workspace

reporting

Méthode	Retour	Description
monthly(…)	MonthlyUsage[]	Sièges vendus par mois
byEvent(…)	EventUsage[]	Sièges vendus par événement
seatList(eventId)	object	Détail des sièges d'un événement
workspaces(…)	WorkspaceUsage[]	Consommation par workspace

Les filtres se passent par objet nommé en JS ({ year, month, userId }) et par arguments positionnels en PHP (monthly(?string $userId, ?int $year)).

Exceptions

Classe	Levée quand
AuthException	Clé absente, mal formée, invalide ou révoquée — 401 et 403
ApiException	Toute autre erreur renvoyée par l'API — porte statusCode et le message serveur
MitoeraException	Racine de la hiérarchie

En PHP (SDK ≥ v1.0.1), AuthException hérite d'ApiException :

AuthException  ⟶  ApiException  ⟶  MitoeraException  ⟶  RuntimeException

Conséquence : ordonnez toujours les catch du plus spécifique au plus général, sinon le bloc AuthException devient inatteignable. statusCode vaut 0 pour les erreurs de configuration levées avant tout appel réseau.

Voir Codes d'erreur pour la correspondance entre statusCode et cause.