Ressources & méthodes

Cette page inventorie tout ce que @shopimind/sdk-js expose : 28 exports nommés = 6 classes d'infrastructure + 22 ressources (une classe statique par domaine de l'API). Les classes d'infrastructure sont SpmClient, SpmClientException, SpmApiError, SpmRequestValidator, SpmWebhookSignature et SpmHelpers ; les conventions communes à toutes les méthodes sont décrites plus bas.

Pour rappel, l'URL de base est https://core.shopimind.com/v1 et l'authentification se fait par la clé API de boutique dans l'en-tête spm-api-key. Voir aussi Périmètre & versions.

Comment s'appellent les méthodes

Toutes les méthodes de ressource sont statiques et prennent le client en premier argument :

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

// Client pour l'API v1, authentifié par la clé API de la boutique (en-tête spm-api-key)
const client = SpmClient.getClient('v1', process.env.SHOPIMIND_API_KEY!);

// Lecture — liste paginée
const res = await SpmCustomers.list(client, { limit: 50 });
if (!res.ok) {
  throw new Error(res.error.message); // rien n'est "throw" par le SDK : on teste res.ok
}
console.log(res.data.data); // ⚠️ payload métier double-niché : res.data.data

// Écriture en lot avec découpage automatique
const saved = await SpmCustomers.bulkSave(client, customers, { chunk: true });

Pas d'instance configurée

On n'appelle jamais client.customers.list(...). Le pattern est toujours SpmRessource.methode(client, …) — la classe est statique, le client est un argument.

Les 22 ressources

La colonne CHUNK_SIZE indique la taille de lot par défaut appliquée par bulkSave / bulkUpdate quand vous passez { chunk: true }. Les ressources sans valeur ne définissent pas de CHUNK_SIZE propre (repli générique à 50 si le découpage est demandé).

Ressource	Endpoint	Méthodes	CHUNK_SIZE
SpmShopConnection	shop/connection	saveConfiguration	—
SpmCustomers	customers	bulkSave · bulkUpdate · delete · bulkDelete · get · list · listGroups · (instance) save · update	50
SpmCustomersAddresses	customers/{customerId}/addresses	bulkSave · bulkSaveAll · bulkUpdate · delete · bulkDelete · list · (instance) save · update	50
SpmCustomersGroups	customers-groups	bulkSave · bulkUpdate · delete · bulkDelete · list · (instance) save · update	100
SpmProducts	products	bulkSave · bulkUpdate · delete · bulkDelete · list · (instance) save · update	50
SpmProductsCategories	products-categories	bulkSave · bulkUpdate · delete · bulkDelete · list · (instance) save · update	100
SpmProductsImages	products/{productId}/images	bulkSave · bulkSaveAll · bulkUpdate · delete · bulkDelete · (instance) save · update · pas de list	50
SpmProductsManufacturers	products-manufacturers	bulkSave · bulkUpdate · delete · bulkDelete · list · (instance) save · update	100
SpmProductsVariations	products/{productId}/variations	bulkSave · bulkSaveAll · bulkUpdate · delete · bulkDelete · (instance) save · update · pas de list	50
SpmOrders	orders	bulkSave · bulkUpdate · delete · bulkDelete · get · getByReference · list · (instance) save · update	50
SpmOrdersCarriers	orders-carriers	bulkSave · bulkUpdate · delete · bulkDelete · list · (instance) save · update	100
SpmOrdersStatuses	orders-statuses	bulkSave · bulkUpdate · delete · bulkDelete · list · (instance) save · update	100
SpmVouchers	vouchers	bulkSave · bulkUpdate · delete · bulkDelete · list · (instance) save · update	50
SpmNewsletterSubscribers	newsletter-subscribers	bulkSave · bulkUpdate · (instance) save · update	50
SpmDataSources	data-sources	list · create · update · delete	—
SpmIntegrationConfig	integration-config	get · set	—
SpmCustomDataDefinitions	custom-data-definitions	list · get · create · update (= extend) · extend · activate · deactivate · delete · listOverrides · updateOverrides	—
SpmCustomDataRecords	custom-data-records/{definitionId}	bulkSave · list · update · delete · bulkDelete	20
SpmContacts	contacts, contact-consent-history, contact-messages-reject	get · list · listLists · listTags · listCustomDataDefinitions · listConsentHistory · listMessagesReject — lecture seule	—
SpmEvents	events	create · update · list · listHistories · get · delete · trigger	—
SpmCarts	carts	list — lecture seule	—
SpmLists	lists	list · get · create · update · delete · listContacts	—

Découpage en lots (chunking)

Le découpage n'est actif que si vous passez { chunk: true } et que la donnée est un tableau ; sinon le tableau part en une seule requête. Le lot par défaut suit le CHUNK_SIZE de la ressource, surchargeable via { chunkSize: N }. Détails et agrégation des réponses dans Résilience.

Particularités à connaître

• SpmProductsImages et SpmProductsVariations n'ont pas de méthode list. Vous poussez images et variations (y compris à plat via bulkSaveAll, parent embarqué dans chaque item), mais vous ne les relisez pas par le SDK.
• SpmCarts et SpmContacts sont en lecture seule. Les paniers se créent côté ShopiMind à partir des commandes que vous poussez via SpmOrders ; les contacts sont une vue consolidée, alimentée par vos clients.
• SpmCustomDataRecords est asynchrone côté serveur : l'ingestion passe par Kafka. Un 200 signifie « accepté », pas « persisté ». Le lot est plafonné à 20 enregistrements par requête (bulkSave et bulkDelete).
• bulkDelete est un POST (vers …/bulk-delete), pas un DELETE.
• Routes spéciales : SpmOrders.get → orders/id/{id}, SpmOrders.getByReference → orders/reference/{reference}, SpmEvents.trigger → events/trigger/{codeName}. Les mises à jour de SpmCustomDataDefinitions, SpmCustomDataRecords, SpmLists et SpmEvents sont des PATCH (la mise à jour de définition passe par PATCH …/{id}/extend ; la mise à jour d'un enregistrement passe par PATCH …/{definitionId}/{recordId}).

label_source & id_data_source

label_source est injecté automatiquement dans les corps POST / PUT des ressources de synchronisation de données (clients, produits, commandes, bons et leurs sous-ressources) pour en tracer l'origine ; il est volontairement omis pour les endpoints de configuration et de lecture. id_data_source rattache une donnée à sa source. Voir Sources de données.

Classes d'infrastructure

En plus des ressources, le SDK exporte six classes transverses.

Export	Rôle
SpmClient	Fabrique du client HTTP : SpmClient.getClient('v1', apiKey, options?). Voir Installation et Utilisation.
SpmClientException	Type d'exception levé sur les erreurs de configuration (par exemple une baseUrl invalide passée à getClient). Le SDK ne le lève jamais sur un échec HTTP — ceux-ci sont encodés dans l'enveloppe { ok, statusCode, data, error }.
SpmApiError	Erreur levée uniquement par SpmHelpers.unwrapOrThrow (le mode exception opt-in). Elle porte statusCode, code et l'enveloppe d'origine.
SpmRequestValidator	Primitive de sécurité du canal connecteur — voir l'encart ci-dessous.
SpmWebhookSignature	Primitive de sécurité du canal intégration — voir l'encart ci-dessous.
SpmHelpers	Sac d'utilitaires : chunk, mergeResponses, extractCounts, isRetryable, formatError, unwrapOrThrow — voir Résilience.

Deux primitives de sécurité

Le SDK expose deux primitives de signature, une par canal.

• SpmRequestValidator — canal connecteur. C'est la primitive de sécurité des connecteurs CMS, toujours active. Le corps est « imploded » (trié au 1er niveau) puis signé par HMAC-SHA256 avec une clé dérivée sha256(secret), et comparé en md5 à temps constant ; en-têtes Shopimind-Token et Shopimind-Client-Identifiant.
• SpmWebhookSignature — canal intégration. Vérifie les webhooks d'intégration via un HMAC-SHA256 horodaté sur ${timestamp}.${rawBody}, avec fenêtre anti-rejeu et comparaison timing-safe ; en-têtes x-shopimind-timestamp et x-shopimind-signature (helper verifyFromHeaders). Voir Webhooks d'intégration.

Pour aller plus loin

• → Utilisation — l'enveloppe de réponse, la lecture du payload double-niché à res.data.data, écrire en lot.
• → Résilience — retries, chunking, agrégation, helpers.
• → Types TypeScript — les DTO exacts de chaque entité.