# @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

```bash
npm install @altazion/commerce-sdk-core
```

## Utilisation rapide

```ts
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

```ts
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)

```html
<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

```ts
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.

```ts
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é.

  ```ts
  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.