Périmètre et versions

@shopimind/sdk-js est le client JavaScript/TypeScript officiel de l'API ShopiMind. Cette page décrit précisément son rôle (et ses limites), sa compatibilité à l'exécution et sa politique de versionnage.

Ce que fait le SDK : le transport sortant

Le SDK est un client HTTP sortant : votre code appelle l'API ShopiMind. Il n'écoute ni ne reçoit rien — il émet des requêtes vers https://core.shopimind.com/v1.

import { SpmClient, SpmCustomers } from '@shopimind/sdk-js';

// Client for the v1 API, authenticated with the shop's API key (spm-api-key header)
const client = SpmClient.getClient('v1', process.env.SHOPIMIND_API_KEY!);

// Read — paginated list
const res = await SpmCustomers.list(client, { limit: 50 });
if (!res.ok) {
  throw new Error(res.error.message); // the SDK never throws: check res.ok
}
console.log(res.data.data); // ⚠️ business payload double-nested: res.data.data

// Bulk write with automatic chunking
const saved = await SpmCustomers.bulkSave(client, customers, { chunk: true });

Concrètement, le SDK fournit :

• La synchronisation e-commerce — clients, produits, commandes, bons de réduction, et leurs sous-ressources (adresses, images, déclinaisons, transporteurs, statuts, catégories, fabricants).
• Les lectures — get / list / getByReference / listGroups selon la ressource.
• Les données personnalisées — définitions et enregistrements (custom data).
• Les contacts — fiches, listes, tags, historique de consentement, messages rejetés (lecture seule).
• Les événements, listes, KPI personnalisés et paniers (lecture seule).
• La connexion de boutique, les sources de données et la configuration d'intégration.

La liste exhaustive des ressources et méthodes : → Ressources et méthodes.

Authentification : une seule direction

Le SDK envoie la clé API de boutique dans l'en-tête spm-api-key. C'est la seule clé qu'il manipule, et elle ne sert qu'au trafic sortant (votre code → ShopiMind). Voir → Authentification.

Vérifier les requêtes entrantes : deux primitives

Le transport décrit ci-dessus est sortant (votre code → ShopiMind). Pour les requêtes entrantes (ShopiMind → votre code), le SDK fournit deux primitives de vérification de signature — une par canal. Choisissez celle qui correspond à qui émet la requête.

SpmRequestValidator — canal connecteur (modules CMS)

Quand ShopiMind appelle votre module CMS (synchronisation de données, génération de bons…), il signe le corps avec un schéma « imploded » : le corps est trié au premier niveau, passé en HMAC-SHA256 (clé = sha256(secret)), puis comparé en md5 à temps constant. La signature arrive dans l'en-tête Shopimind-Token et l'identifiant client dans Shopimind-Client-Identifiant.

import { SpmRequestValidator } from '@shopimind/sdk-js';

// CMS modules send a form-urlencoded body → parse it first.
const body = SpmRequestValidator.parseFormData(rawBody);

const { valid, error } = SpmRequestValidator.validateRequest({
  clientId: headers['shopimind-client-identifiant'],
  hmacToken: headers['shopimind-token'],
  body,
  apiIdentification: config.clientId, // id configured in the module
  apiPassword: config.apiKey,         // the shop's API key
});

if (!valid) {
  // error: 'Invalid HMAC token', 'Invalid client ID', 'Missing … header'…  → respond 401
  return;
}
// → authenticated request: handle it.

parseFormData filtre aussi les clés dangereuses (__proto__, constructor, prototype) — une défense contre la pollution de prototype.

SpmWebhookSignature — canal intégration (webhooks)

Quand ShopiMind envoie un webhook à votre intégration (activation, désactivation, événements de cycle de vie…), il signe ${timestamp}.${rawBody} en HMAC-SHA256. La vérification est horodatée : une fenêtre de tolérance (anti-rejeu) rejette les requêtes trop anciennes, et la comparaison est à temps constant.

import { SpmWebhookSignature } from '@shopimind/sdk-js';

const result = SpmWebhookSignature.verifyFromHeaders(
  rawBody,                 // the RAW body string — never the already-parsed object
  headers,
  webhookSecret,           // the integration's shared secret
  {
    timestampHeader: 'x-shopimind-timestamp',
    signatureHeader: 'x-shopimind-signature',
    toleranceSeconds: 300, // anti-replay window (default: 300s)
  },
);

if (!result.ok) {
  // result.reason: 'signature_mismatch', 'timestamp_out_of_tolerance', 'missing_signature_headers'…
  return; // → respond 401
}
// → authenticated webhook.

Vérifiez le corps BRUT

SpmWebhookSignature calcule la signature sur la chaîne brute reçue. Vérifiez-la avant tout parsing JSON (ou conservez la chaîne d'origine) : reparser puis re-sérialiser change les octets et invalide la signature.

Récapitulatif — trois cas

• Sortant (votre code → ShopiMind) : le SDK envoie la clé spm-api-key.
• Entrant — connecteur (ShopiMind → module CMS) : SpmRequestValidator (Shopimind-Token / Shopimind-Client-Identifiant).
• Entrant — intégration (ShopiMind → votre intégration) : SpmWebhookSignature (x-shopimind-timestamp / x-shopimind-signature).

Le kit d'intégration JavaScript s'appuie sur SpmWebhookSignature pour vérifier automatiquement les webhooks d'intégration. Voir → Webhooks d'intégration.

Compatibilité

Élément	Prise en charge
Node.js	≥ 18 (engines.node : >=18.17.0)
Modules	ESM uniquement — import (pas de build CommonJS)
Langage	TypeScript (types embarqués) ou JavaScript ESM
Dépendance à l'exécution	axios (unique, installée automatiquement)
Version d'API ciblée	v1 (via SpmClient.getClient('v1', …))

ESM uniquement

@shopimind/sdk-js est distribué en ESM pur : il n'expose pas de build CommonJS. Utilisez import { … } from '@shopimind/sdk-js'. Un require(...) échouera — basculez votre projet en ESM (le champ "type": "module" du package.json) ou utilisez un import() dynamique.

L'installation et les prérequis détaillés : → Installation.

Versions (SemVer)

Le SDK suit le versionnage sémantique MAJOR.MINOR.PATCH :

Incrément	Quand	Exemple
PATCH	Correctif sans changement d'API	fix de retry, coquille
MINOR	Ajout rétrocompatible	nouvelle méthode, nouvelle option
MAJOR	Rupture (signature, retrait)	renommage de champ, retrait de méthode

La version courante est 1.0.0. L'API publique est stable et suit pleinement le SemVer : aucune rupture n'interviendra hors d'un incrément majeur — épinglez une version pour des installations reproductibles.

Versions du SDK et de l'API

La version du SDK (1.0.0) et la version de l'API REST (v1, dans le préfixe d'URL) sont indépendantes. Mettre à jour le SDK ne change pas la version d'API que vous ciblez via SpmClient.getClient('v1', …).