Résilience — retry, chunking, helpers

Retry automatique

Par défaut, le SDK retry 3 fois sur :

• HTTP 408, 429, 500, 502, 503, 504
• erreurs réseau : ECONNRESET, ETIMEDOUT, ECONNREFUSED, ENETUNREACH, ENOTFOUND, EAI_AGAIN

avec un backoff exponentiel (1s → 2s → 4s, jitter ±500 ms, plafond 10s).

// Personnaliser
const client = SpmClient.getClient('v1', apiKey, {
  retry: {
    maxRetries: 5,
    backoffBaseMs: 2000,
    backoffCapMs: 30000,
    retryableStatus: [429, 502, 503, 504],
  },
});

// Désactiver
const client = SpmClient.getClient('v1', apiKey, { retry: false });

Quand toutes les tentatives échouent, l'enveloppe renvoie ok: false avec error.retryable et error.attempts :

const res = await SpmOrders.bulkSave(client, orders);
if (!res.ok && res.error.retryable) {
  // ré-essayer plus tard / mettre en file d'attente
}

Chunking optionnel

Passez un gros tableau : le SDK le découpe en batches alignés sur la limite de l'API et agrège les résultats.

const hugeArray = Array(500).fill().map((_, i) => ({ /* customer data */ }));

const res = await SpmCustomers.bulkSave(client, hugeArray, { chunk: true });

console.log(res.data.sent_count);   // total agrégé
console.log(res.data.chunks);       // détail par chunk (10 × 50)

Par défaut, chunkSize vaut la valeur alignée sur l'API :

Ressource	CHUNK_SIZE
SpmCustomDataRecords	20
SpmCustomers, SpmCustomersAddresses, SpmProducts, SpmProductsImages, SpmProductsVariations, SpmOrders, SpmVouchers	50
SpmCustomersGroups, SpmProductsCategories, SpmProductsManufacturers, SpmOrdersCarriers, SpmOrdersStatuses	100

await SpmProducts.bulkSave(client, items, { chunk: true, chunkSize: 25 }); // override
console.log(SpmCustomers.CHUNK_SIZE); // 50

Helpers partagés

const { SpmHelpers } = require('@shopimind/sdk-shopimind');

SpmHelpers.chunk(array, 50);
// → [[...50], [...50], ...]

SpmHelpers.mergeResponses([envelope1, envelope2, ...]);
// → envelope agrégée : data.sent_count, data.rejected_count, data.chunks[]

SpmHelpers.extractCounts(envelope);
// → { sent: N, rejected: M, failed: K }

SpmHelpers.isRetryable(error);
// → true si l'erreur/enveloppe est retryable (429 / 5xx / réseau)

SpmHelpers.formatError(envelope);
// → { message, code, statusCode, retryable, attempts, details }
//   sûr à sérialiser pour des logs structurés

Pattern de synchronisation robuste

Combinez bulkSave({ chunk: true }) (découpage + agrégation) avec le retry intégré et SpmHelpers.formatError pour des logs exploitables — vous obtenez une synchro résistante aux pics de charge et aux indisponibilités transitoires sans écrire de boucle de retry.