SDK JavaScript / TypeScript

@shopimind/sdk-js est le client officiel pour appeler l'API ShopiMind depuis Node.js. C'est un client sortant : votre code parle à l'API ShopiMind, authentifié par la clé API de votre boutique (en-tête spm-api-key).

• ESM uniquement — Node.js 18+, importé avec import { … } from '@shopimind/sdk-js'
• Dépendance runtime unique : axios
• Types .d.ts inclus — autocomplétion et vérification de types prêtes à l'emploi
• Retry automatique, chunking optionnel, format de retour uniforme (envelope { ok, statusCode, data, error })

L'URL de base est https://core.shopimind.com/v1.

ESM uniquement

Le SDK est publié exclusivement en ESM : require('@shopimind/sdk-js') ne fonctionne pas. Utilisez import, et un projet Node configuré en module ("type": "module" dans votre package.json, ou extension .mjs).

Installation

npm i @shopimind/sdk-js

Détails, registres et épinglage de version : voir Installation.

Démarrage rapide

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

// Client for the v1 API, authenticated by 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 is double-nested: res.data.data

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

Deux réflexes à retenir

1. Le SDK ne lève jamais d'exception sur une erreur HTTP : testez toujours res.ok et lisez res.error le cas échéant.
2. Le payload métier est double-niché : l'API enveloppe déjà ses réponses, donc la donnée utile se trouve à res.data.data.

Pourquoi le SDK plutôt que fetch ?

Sans SDK (fetch brut)	Avec le SDK
Vous gérez en-têtes, URL de base et sérialisation	SpmClient.getClient('v1', key)
Vous codez vos propres retries sur 408/429/5xx	Retry exponentiel intégré (avec jitter)
Vous découpez vos lots à la main	{ chunk: true } aligné sur les limites de l'API
try/catch partout, formes d'erreur variées	Envelope unique { ok, statusCode, data, error }
Pas de types	DTOs et .d.ts complets

Aller plus loin

• Installation — registres, versions, prérequis
• Utilisation — lecture, écriture, ressources imbriquées
• Résilience — retry, chunking, helpers
• Ressources & méthodes — la liste complète
• TypeScript — types et exemples
• Périmètre & versions — ce que couvre le SDK

Vous construisez une intégration ?

Pour recevoir des webhooks de ShopiMind et brancher votre application sur le cycle de vie d'une installation, utilisez le kit d'intégration JavaScript @shopimind/integration-kit-js : il monte le serveur de webhooks, vérifie la signature HMAC, et dépend du SDK et le ré-exporte, de sorte que vous importez les ressources et types du SDK directement depuis le kit. → Guide des intégrations