stormeo-sdk

SDK officiel pour intégrer un site React / Node custom (sans CMS) à StormeoOS — la solution de pilotage de parc de sites pour agences web.

Installation

npm install stormeo-sdk

Compatible Node 18+ (utilise fetch global et WebCrypto natifs). Fonctionne aussi côté browser/edge runtimes (Cloudflare Workers, Vercel Edge…).

Démarrage rapide

1. Pairing initial (une fois)

Dans le wizard StormeoOS :

• Choisir "Site personnalisé (React/Node)" comme plateforme
• Copier le token affiché (stm_pair_xxxxxxxx)

Puis dans votre app :

import { StormeoClient } from "stormeo-sdk";

const result = await StormeoClient.pair("https://beta.stormeo.io", {
  token: process.env.STORMEO_TOKEN!,        // token du wizard
  siteUrl: "https://mon-app.com",
  framework: "next",
  runtimeVersion: process.version,
});

// Persistez result.apiKey + result.apiSecret en DB ou env vars
console.log("apiKey:", result.apiKey);
console.log("apiSecret:", result.apiSecret);

2. Usage runtime

import { StormeoClient } from "stormeo-sdk";

const stormeo = new StormeoClient({
  instanceUrl: "https://beta.stormeo.io",
  apiKey: process.env.STORMEO_API_KEY!,
  apiSecret: process.env.STORMEO_API_SECRET!,
});

// Pulse périodique (recommandé 5 min)
setInterval(() => stormeo.heartbeat({ framework: "next" }), 5 * 60_000);

// Track un event
await stormeo.trackEvent("order.created", { orderId: 42, total: 99.90 });

// Ou un batch
await stormeo.trackEvents([
  { eventType: "user.signed_up", entityId: 1, metadata: { plan: "pro" } },
  { eventType: "page.viewed", metadata: { path: "/pricing" } },
]);

API

new StormeoClient(opts)

| Option | Type | Défaut | Description | |---|---|---|---| | instanceUrl | string | — | URL de l'instance StormeoOS (ex: https://beta.stormeo.io) | | apiKey | string | — | Reçu de /api/plugin/pair (stm_<base64url>) | | apiSecret | string | — | Reçu de /api/plugin/pair — sensible (env var !) | | timeoutMs | number | 10000 | Timeout par requête | | fetch | typeof fetch | globalThis.fetch | Custom fetch (bun, undici…) | | logger | { debug?, warn?, error? } | silent | Logger custom |

client.heartbeat(payload?)

Pulse périodique. Met à jour lastHeartbeatAt côté StormeoOS et sert d'indicateur "site actif" dans l'UI.

await stormeo.heartbeat({
  framework: "next",
  runtimeVersion: "20.11.0",
  pluginVersion: "1.0.0",
  healthSnapshot: { /* libre */ },
});

client.trackEvent(eventType, metadata?)

Raccourci pour pousser 1 event. Retourne { success, ingested: 1 }.

await stormeo.trackEvent("order.paid", { orderId: 42, amount: 199.90 });

client.trackEvents(events[])

Push N events (max 100 par appel — split auto au-delà).

await stormeo.trackEvents([
  { eventType: "page.published", entityType: "page", entityId: 12, entityLabel: "Pricing" },
  { eventType: "user.invited", metadata: { email: "[email protected]" } },
]);

Schema event :

{
  eventType: string;       // requis, max 100 chars (ex: "order.created")
  entityType?: string;     // ex: "order", "user", "page"
  entityId?: number;
  entityLabel?: string;    // libellé human-readable pour la timeline
  metadata?: Record<string, unknown>;  // payload libre (JSON)
  occurredAt?: Date | string;          // ISO string ou Date, défaut: maintenant
}

client.syncContent(payload)

Sync de contenu structuré (pages / posts). Réutilise l'endpoint sync-content-extended des plugins WP/PS. Pour un site custom, préférez trackEvents plus flexible.

StormeoClient.pair(instanceUrl, opts) (statique)

Pairing initial avec le token du wizard. Retourne { apiKey, apiSecret, connectorId, websiteId, instanceUrl }. À appeler une seule fois au boot puis stocker les credentials.

const result = await StormeoClient.pair("https://beta.stormeo.io", {
  token: "stm_pair_xxx",
  siteUrl: "https://app.com",
  siteName: "Mon App",        // optionnel
  framework: "express",       // optionnel
  runtimeVersion: "20.x",     // optionnel
});

Erreurs

Toutes les méthodes lèvent StormeoApiError en cas d'erreur :

import { StormeoApiError } from "stormeo-sdk";

try {
  await stormeo.heartbeat();
} catch (err) {
  if (err instanceof StormeoApiError) {
    console.error("Status:", err.status);   // ex: 401, 403, 500
    console.error("Body:", err.body);       // payload JSON serveur
  }
}

Retry automatique sur 429 (rate limit) et 503 (service unavailable) avec backoff selon Retry-After.

Sécurité

• apiSecret ne doit jamais être exposé côté client (browser bundle). Utilisez le SDK uniquement côté serveur / edge runtime sécurisé.
• Toutes les requêtes vers /api/plugin/v2/* sont signées HMAC-SHA256 (timestamp + body) — résistance aux replay attacks (tolérance ±5 min).
• Le pairing token est unique-use, expire après 24h.

Exemples

• Express — pairing auto + heartbeat + track event
• Next.js Route Handler — singleton + fire-and-forget

Licence

MIT — © Stormeo.io