Utilities di wr.customer (Auth & Account)
Questi metodi sono disponibili tramite la prop wr.customer e permettono di gestire l'intero ciclo di vita dell'utente: dall'autenticazione alla sicurezza dell'account, fino alla gestione dei dati personali.
Autenticazione e Sessione
Gestiscono l'accesso, la registrazione e il mantenimento della sessione utente.
| Metodo | Argomenti | Descrizione |
|---|---|---|
| login | { email, password, platform, region? } | Esegue l'accesso. Se l'utente ha la 2FA attiva, restituisce un flag requires2FA e aggiorna lo stato per mostrare il modulo del codice di verifica. |
| signup | { email, password, confirmPassword, displayName, platform, region? } | Registra un nuovo account. Invia automaticamente l'email di verifica all'indirizzo fornito. |
| logout | - | Termina la sessione corrente, rimuove i token di sicurezza e resetta lo stato del cliente. |
| refreshAccessToken | - | Rinnova il token di accesso utilizzando il deviceId. Viene solitamente invocato in background per mantenere la sessione attiva. |
Sicurezza e Recupero Account
Metodi dedicati alla protezione dell'account e alla gestione delle credenziali.
| Metodo | Argomenti | Descrizione |
|---|---|---|
| requestPasswordReset | email: string | Avvia la procedura di recupero password inviando un link sicuro all'utente. |
| requestResendEmailVerification | - | Invia nuovamente l'email di conferma per attivare l'account. |
| request2FASetup | - | Inizia la configurazione dell'autenticazione a due fattori, restituendo il segreto o il QR code. |
| confirm2FA | { email, code, challengeId } | Verifica il codice OTP fornito dall'utente per completare il login o il setup della sicurezza. |
| requestAccountDeletion | - | Invia una richiesta formale di cancellazione dell'account e di tutti i dati associati. |
Tutte le utilities di wr.customer integrano un sistema di notifiche automatico (Toast) che informa l'utente sull'esito dell'operazione, utilizzando le traduzioni (locale) configurate nel sistema per messaggi di errore o successo.
Gestione Indirizzi
Queste utilities permettono di gestire il set di indirizzi (spedizione e fatturazione) salvati nel profilo dell'utente. Il sistema gestisce automaticamente l'invalidazione della cache per garantire che la lista sia sempre aggiornata dopo ogni modifica.
| Metodo | Argomenti | Descrizione |
|---|---|---|
| getAddresses | - | Recupera la lista completa degli indirizzi dell'utente. Se i dati sono già presenti nella cache locale (customer_addresses_list), restituisce la versione salvata per ottimizzare le prestazioni. |
| createAddress | addressData: Object | Crea un nuovo indirizzo nel profilo. Dopo il successo, invalida la cache e forza un ricaricamento della lista indirizzi. |
| updateAddress | id: string, addressData: Object | Aggiorna i dati di un indirizzo esistente identificato dal suo ID. |
| deleteAddress | id: string | Rimuove permanentemente un indirizzo dal profilo dell'utente. |
Le funzioni di creazione, modifica ed eliminazione invocano internamente clearAddressListCache. Questo assicura che qualsiasi componente che utilizzi getAddresses o che sia in ascolto sullo stato degli indirizzi riceva immediatamente i dati aggiornati senza interventi manuali da parte dello sviluppatore.
Ordini e Abbonamenti
Questi metodi permettono di recuperare lo storico degli acquisti e lo stato dei servizi ricorrenti (abbonamenti) associati all'account dell'utente.
| Metodo | Argomenti | Descrizione |
|---|---|---|
| fetchOrders | query: Object | Recupera l'elenco degli ordini effettuati dal cliente. Supporta parametri di query per filtri, ordinamento o paginazione. |
| fetchSubscriptions | query: Object | Recupera l'elenco degli abbonamenti (subscriptions) attivi o passati legati al profilo dell'utente. |
Parametro di query
Esempio:
{
"sortBy": "createdAt",
"sortDirection": "desc",
"page": 1,
"limit": 10,
}
Entrambi i metodi aggiornano automaticamente lo stato globale degli ordini e delle sottoscrizioni. In caso di errore durante il recupero (es. sessione scaduta), il sistema gestisce autonomamente il reindirizzamento o la notifica all'utente tramite i messaggi di localizzazione configurati.
Wishlist (Preferiti)
Queste utilities permettono di gestire la lista dei desideri dell'utente. La wishlist in webround.com è progettata per essere rapida e sempre sincronizzata; per questo motivo, non è paginata e prevede un limite massimo di 50 elementi.
| Metodo | Argomenti | Descrizione |
|---|---|---|
| fetchWishlist | - | Recupera tutti gli elementi salvati nei preferiti. Se la lista è già presente nello stato globale, restituisce i dati locali per un accesso istantaneo. |
| toggleWishlist | variantId: string | Aggiunge o rimuove una variante specifica dai preferiti. Il metodo gestisce internamente la logica di "toggle" e aggiorna reattivamente sia lo stato della UI che la cache globale. |
- Limite Elementi: La wishlist può contenere un massimo di 50 elementi. Una volta raggiunto il limite, è necessario rimuovere un articolo prima di aggiungerne uno nuovo.
- Assenza di Paginazione: Poiché il volume di dati è limitato, la lista viene sempre restituita nella sua interezza per semplificare la visualizzazione in componenti come slider o griglie dedicate.
- Sincronizzazione Cache:
toggleWishlistaggiorna la cache in background, garantendo che il feedback visivo per l'utente sia correttamente sincronizzato con la vista utente.
Recensioni (Reviews)
Queste utilities permettono all'utente di gestire i propri feedback sui prodotti acquistati. Le recensioni sono legate alla specifica variante del prodotto e supportano operazioni di creazione, modifica e rimozione.
| Metodo | Argomenti | Descrizione |
|---|---|---|
| getMyReviews | query: Object | Recupera l'elenco delle recensioni scritte dall'utente autenticato. Supporta filtri e paginazione tramite l'oggetto query. |
| createReview | variantId: string, reviewData: Object | Invia una nuova recensione per una specifica variante. |
| updateReview | reviewId: string, reviewData: Object | Modifica una recensione esistente identificata dal suo ID univoco. |
| deleteReview | reviewId: string | Rimuove permanentemente una recensione dal sistema. |
Ogni operazione aggiorna automaticamente lo stato globale delle recensioni (REVIEW_LIST). Al termine di ogni azione (creazione, aggiornamento o eliminazione), il sistema mostra un messaggio di conferma (Toast) utilizzando le chiavi di localizzazione del negozio per informare l'utente del successo dell'operazione.
Gestione Carrello (Cart)
Queste utilities permettono di manipolare il carrello dell'utente. Il sistema utilizza internamente una useCartStrategy che decide autonomamente se operare in locale (per utenti guest) o in remoto (per utenti autenticati), garantendo la persistenza dei dati.
| Metodo | Argomenti | Descrizione |
|---|---|---|
| getCartItems | - | Recupera la lista aggiornata dei CartItem. Viene invocato automaticamente al cambio del token di accesso per garantire la sincronizzazione. |
| addCartItem | input: Object | Aggiunge un prodotto al carrello. Richiede un oggetto dettagliato includendo skuId, priceId, quantity, e i metadati della variante (variantName, coverUrl, ecc.) per supportare una corretta visualizzazione anche per utenti non autenticati. |
| updateCartItem | itemId: string, quantity: number | Modifica la quantità di una riga esistente nel carrello. Gestisce automaticamente lo stato di caricamento e i messaggi di conferma. |
| removeCartItem | itemId: string | Rimuove permanentemente un articolo dal carrello. |
| mergeCart | - | Esegue il "merge" del carrello locale (guest) nel carrello remoto dell'account. Viene solitamente chiamato subito dopo il login. |
| validatePromotionCodes | codes, currency, total, skuIds, lang | Valida un array di codici promozionali rispetto al contenuto attuale del carrello e alla valuta selezionata. |
| invalidateAndReloadCart | - | Forza il ricaricamento completo del carrello dal server per aggiornare prezzi, sconti e disponibilità. |
Dettaglio Input addCartItem
Per garantire una UI reattiva e un corretto funzionamento anche per gli utenti autenticati, il metodo addCartItem richiede i metadati della variante. Questo permette al carrello di mostrare l'articolo aggiunto istantaneamente senza attendere una nuova fetch dal server. Gli utenti non autenticati non prevedono una conservazione server-side dei dati del carrello. Bensì, caricano tutto in locale e comunicano con le API solo in caso di modifiche, oppure in caso di check di disponibilità degli elementi del carrello.
{
skuId: string;
priceId: string;
quantity: number;
variantName: string;
variantSlug: string;
coverUrl: string;
variantOptions: { optionName: string, optionValue: string }[];
}
Tutti i metodi del carrello (eccetto mergeCart) attivano automaticamente dei Toast di caricamento e successo. I messaggi sono estratti direttamente dall'oggetto locale del SiteContext, permettendo una localizzazione completa dei feedback (es. "Aggiungo prodotti..." -> "Prodotti aggiunti!").
Certamente. È fondamentale precisare che la validazione dei codici promozionali non è una semplice verifica testuale, ma un calcolo contestuale che dipende dal contenuto attuale del carrello.
Ecco la specifica aggiornata per il metodo:
Dettaglio input validatePromotionCodes
Il metodo validatePromotionCodes analizza l'applicabilità di uno o più coupon basandosi sulla sessione di acquisto corrente.
| Argomento | Tipo | Descrizione |
|---|---|---|
| codes | string[] | Array dei codici sconto inseriti dall'utente (Max 10). |
| cartTotal | number | Il totale lordo attuale del carrello su cui calcolare lo sconto. |
| cartCurrency | CurrencyCode | La valuta del carrello (es. EUR, USD). |
| skuIds | string[] | Elenco degli ID SKU presenti nel carrello (utilizzati per verificare sconti specifici su prodotti). |
| langCode | LangCode | La lingua dell'utente, utilizzata per restituire messaggi di errore localizzati dal motore di validazione. |
La validazione tramite questo metodo conferma l'applicabilità del codice e fornisce un feedback immediato all'utente. Tuttavia, l'applicazione economica definitiva del risparmio avviene sempre sul server durante la fase finale di checkout per garantire la massima sicurezza contro manipolazioni del client.
Questo metodo è utile solo a scopo visualizzativo e non determina in alcuna misura il comportamento in fase di checkout, che rivaluterà tutto in base agli elementi del carrello.
Preferenze e Dati Personali
Queste utilities permettono di gestire le impostazioni del profilo e i consensi dell'utente autenticato.
| Metodo | Argomenti | Descrizione |
|---|---|---|
| toggleNewsletter | value: boolean | Aggiorna lo stato di iscrizione alla newsletter. Il metodo sincronizza il nuovo valore con il server e aggiorna immediatamente l'oggetto customer nello stato globale. |
Gestione dello Stato e Feedback
Il metodo toggleNewsletter è ottimizzato per fornire un feedback immediato e mantenere i dati coerenti:
- Aggiornamento Reattivo: Dopo la chiamata al server, viene eseguito il dispatch di
SET_CUSTOMER. Questo assicura che qualsiasi componente della UI (come toggle o checkbox nelle impostazioni) rifletta istantaneamente la scelta dell'utente. - Messaggistica Localizzata: Il sistema utilizza chiavi specifiche (
newsletterSubscribed/newsletterUnsubscribed) per mostrare toast di successo differenti a seconda che l'utente si stia iscrivendo o disiscrivendo. - Integrazione con il Profilo: La proprietà
newsletterfa parte del data type Customer, garantendo che la preferenza sia persistente tra diverse sessioni e dispositivi.
Sebbene attualmente focalizzato sulla newsletter, questo set di API è progettato per gestire in futuro l'aggiornamento di altri dati del profilo utente (come displayName o preferenze di localizzazione) attraverso il medesimo meccanismo di sincronizzazione dello stato.