@altazion/commerce-sdk-core

Client HTTP universel pour l'API Altazion Commerce. Fonctionne dans tous les environnements JavaScript (navigateur, Node.js, SSR) sans dépendances tierces — uniquement fetch natif.

Installation

npm install @altazion/commerce-sdk-core

Utilisation rapide

import { CommerceClient } from '@altazion/commerce-sdk-core'

const client = new CommerceClient({
  baseUrl: 'https://votre-api.altazion.com',
  siteUrl: 'https://votre-site.com',
})

// Récupérer la session courante
const session = await client.session.getSession()

// Récupérer le panier
const cart = await client.cart.getCart()

// Rechercher des produits
const results = await client.catalog.search({ q: 'chaussures', offset: 0, length: 20 })

Modules disponibles

| Module | Description | |---|---| | client.session | Session utilisateur / kiosque | | client.cart | Panier (ajout, modification, suppression, coupons) | | client.catalog | Produits, catégories, recherche, suggestions | | client.shipping | Modes de livraison, points relais | | client.stores | Magasins physiques et horaires | | client.marketing | Contenus marketing personnalisés |

Fonctionnalités

• Cache SharedWorker + IndexedDB — mise en cache des réponses, stratègies configurables (cache-first, network-first, network-only)
• ConnectivityManager — détection de connectivité en temps réel avec API d'abonnement
• Dual session — bascule automatiquement en mode kiosque si le user-agent est Altazion Device Shell
• TypeScript — types complets générés depuis la spécification OpenAPI

Options de configuration

const client = new CommerceClient({
  baseUrl: 'https://votre-api.altazion.com', // obligatoire
  siteUrl: 'https://votre-site.com',          // URL canonique du site
  defaultCacheStrategy: 'cache-first',        // stratégie de cache par défaut
})

Mode CDN (sans bundler)

<script src="https://cdn.jsdelivr.net/npm/@altazion/commerce-sdk-core/dist/index.iife.js"></script>
<script>
  const client = new AltazionCommerceCore.CommerceClient({
    baseUrl: 'https://votre-api.altazion.com'
  })
</script>

Gestion des erreurs

import { AltazionApiError, OfflineError } from '@altazion/commerce-sdk-core'

try {
  await client.cart.addItem('REF-001', 1)
} catch (err) {
  if (err instanceof OfflineError) {
    // Le terminal est hors ligne : les mutations sont refusées immédiatement
  } else if (err instanceof AltazionApiError) {
    console.error(err.status, err.problem)
  }
}

Résumé panier local

Le module cart maintient désormais un résumé local dérivé du panier complet.

• client.cart.peekSummary() retourne le dernier snapshot en mémoire sans I/O ;
• client.cart.getSummary() retourne le snapshot mémoire ou persistant, puis lance un lazy reload si le résumé est périmé ;
• client.cart.refreshSummary() force une relecture du panier et régénère le résumé.

Le résumé expose notamment :

• le total TTC global ;
• la quantité totale ;
• le nombre de références principales ;
• un détail par contentType avec total TTC, nombre de références principales, nombre de lignes principales et quantité principale.

const summary = await client.cart.getSummary()

console.log(summary?.totalAmountWithTax)
console.log(summary?.contents)

Bridge host borne

Le package core expose aussi un bridge léger vers le host WebView des bornes pour piloter les périphériques remontés par le shell embarqué.

import { CommerceClient, PeripheralTpe } from '@altazion/commerce-sdk-core'

const client = new CommerceClient({
  baseUrl: 'https://votre-api.altazion.com',
})

client.devices.initialize()

const tpe = client.devices.findPeripheralByType('TPE')[0] as PeripheralTpe | undefined

tpe?.on((notification) => {
  console.log(notification.kind, notification.getNormalizedPayload())
})

tpe?.onSuccess((type, orderGuid, notification) => {
  console.log(type, orderGuid, notification.getNormalizedPayload())
})

tpe?.makePayment('order-guid', 'CMD123', 'mrg-guid', 42.5, 'EUR')

Capacités couvertes dans cette première reprise :

• découverte des périphériques remontés par le host via DeviceManager.Init ;
• dispatch des notifications TPE:*, BARCODE:* et des mises à jour d'état ;
• normalisation des payloads host via notification.getNormalizedPayload() pour absorber les variantes anciennes ;
• commandes shell shell.state-change et app.status-update ;
• mode mock pour les templates et les développements hors borne.

Licence

Propriétaire — © Altazion SAS. Tous droits réservés.