SDK A-Cube e-Receipts

Panoramica

@a-cube-io/ereceipts-js-sdk è un SDK TypeScript production-ready per la gestione di ricevute elettroniche, che fornisce supporto multi-piattaforma senza soluzione di continuità su Browser, Node.js e ambienti React Native. Costruito con strumenti moderni e rigida type safety, offre affidabilità di livello enterprise con un'esperienza sviluppatore intuitiva.

Risultati Chiave

• 🌍 Supporto Multi-Piattaforma: Singolo codebase per Browser, Node.js e React Native
• 🔒 Implementazione Type-Safe: TypeScript completo con validazione schema Zod
• 💾 Caching Intelligente: IndexedDB per browser, strategie di storage ottimizzate
• 📦 Sistema di Build Moderno: Rollup con tree-shaking e code-splitting
• 🔐 Autenticazione mTLS: Integrazione con expo-mutual-tls per chiamate API sicure
• ⚡ Performance Ottimizzate: Lazy loading e gestione efficiente della memoria
• 🎯 API Developer-Friendly: Hook e utility intuitive per React/React Native
• 📊 Production-Ready: Utilizzato nei prodotti A-Cube live (Pempel Dashboard, Invoice Dashboard)

Vedi su GitHub | Pacchetto NPM

Architettura Tecnica

Design del Sistema

L'SDK implementa un'architettura a livelli con ottimizzazioni specifiche per piattaforma:

┌─────────────────────────────────────────────────┐
│     Livello Applicazione (React/RN/Node)        │
│      Hook Personalizzati & Utility               │
└────────────────┬────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────┐
│         Livello SDK Core (TypeScript)           │
│   Gestione Ricevute • Validazione • Caching    │
└──────┬──────────────────────────────┬──────────┘
       │                              │
┌──────▼─────────┐          ┌─────────▼──────────┐
│ Livello        │          │  Livello Native    │
│ Browser        │          │  - AsyncStorage    │
│ - IndexedDB    │          │  - SQLite          │
│ - LocalStorage │          │  - Moduli Expo     │
│ - Fetch API    │          │                    │
└────────────────┘          └────────────────────┘

Funzionalità Principali

1. Sistema di Gestione Ricevute

L'SDK fornisce una gestione completa del ciclo di vita delle ricevute:

Operazioni sulle Ricevute

import { EReceiptsSDK } from '@a-cube-io/ereceipts-js-sdk'
 
// Inizializza SDK
const sdk = new EReceiptsSDK({
  apiUrl: 'https://api.acubeapi.com',
  authToken: 'user-jwt-token',
  enableCache: true,
  cacheTTL: 3600000 // 1 ora
})
 
// Recupera ricevute con caching automatico
const receipts = await sdk.getReceipts({
  startDate: '2025-01-01',
  endDate: '2025-12-31',
  status: 'validated'
})
 
// Ottieni singola ricevuta (dalla cache se disponibile)
const receipt = await sdk.getReceipt('receipt-id-123')
 
// Scarica PDF della ricevuta
const pdfBlob = await sdk.downloadReceiptPDF('receipt-id-123')

Integrazione React Hooks

import { useReceipts, useReceipt } from '@a-cube-io/ereceipts-js-sdk/react'
 
function ReceiptsList() {
  const { receipts, loading, error, refresh } = useReceipts({
    startDate: '2025-01-01',
    endDate: '2025-12-31'
  })
 
  if (loading) return <LoadingSpinner />
  if (error) return <ErrorMessage error={error} />
 
  return (
    <div>
      {receipts.map(receipt => (

2. Validazione Type-Safe con Zod

Tutte le risposte API e le strutture dati validate at runtime:

import { z } from 'zod'
 
// Schema ricevuta
const ReceiptSchema = z.object({
  id: z.string().uuid(),
  merchantName: z.string().min(1),
  amount: z.number().positive(),
  currency: z.enum(['EUR', 'USD', 'GBP']),
  date: z.string().datetime(),
  status: z.enum(['pending', 'validated', 'rejected'

3. Sistema di Caching Intelligente

Strategia di caching multi-livello ottimizzata per ogni piattaforma:

Implementazione Browser (IndexedDB)

• Indicizzazione: Indici su data, status, merchantName per query veloci
• Operazioni Batch: Write bulk per performance ottimali
• Gestione Metadata: Timestamp ultimo sync per invalidazione cache

Implementazione React Native (AsyncStorage)

• Prefisso Cache: Organizzazione chiavi con namespace
• Multi-Get/Set: Operazioni batch per ridurre latenza
• Gestione Memoria: Strategia di eviction LRU

Strategia di Invalidazione Cache

• TTL-Based: Scadenza automatica dopo durata configurabile
• Manual Sync: Refresh triggherato dall'utente invalida la cache
• Smart Updates: Aggiornamenti parziali della cache per ricevute modificate
• Memory Management: Eviction LRU per limiti di storage browser

4. Integrazione Autenticazione mTLS

Integrazione seamless con @a-cube-io/expo-mutual-tls per chiamate API sicure:

import ExpoMutualTls from '@a-cube-io/expo-mutual-tls'
import { EReceiptsSDK } from '@a-cube-io/ereceipts-js-sdk'
 
// Configura mTLS
await ExpoMutualTls.configureP12('ereceipts-app', true)
await ExpoMutualTls.storeP12(certificateData, password)
 
// SDK usa automaticamente mTLS per chiamate API
const sdk = new EReceiptsSDK({
  apiUrl: 'https://api.acubeapi.com',
  useMTLS: true,
  authToken: 'user-jwt-token'
})
 
// Tutte le chiamate API usano autenticazione certificato client
const receipts = await sdk.getReceipts() // mTLS secured

Caratteristiche Performance

Benchmark

Footprint Memoria

• SDK Core: ~500KB (minified)
• Dipendenze: ~1.5MB (axios + zod + idb)
• Memoria Runtime: ~5-10MB (100 ricevute in cache)
• Storage IndexedDB: ~2KB per ricevuta

Strategie di Ottimizzazione

1. Lazy Loading: Hook React caricano solo quando necessario
2. Code Splitting: Bundle separati per React hooks
3. Tree Shaking: Codice non utilizzato eliminato dai bundler
4. Batch Operations: Write bulk IndexedDB per performance
5. Response Streaming: Dataset large processati incrementalmente

Esempio di Integrazione

App React Native Completa

import React, { useEffect } from 'react'
import { View, FlatList, Text, Button } from 'react-native'
import { useReceipts } from '@a-cube-io/ereceipts-js-sdk/react'
import ExpoMutualTls from '@a-cube-io/expo-mutual-tls'
 
export default function ReceiptsScreen() {
  const { receipts, loading, error, refresh, downloadPDF } = useReceipts({
    startDate: '2025-01-01',
    endDate: '2025-12-31'
  })
 
  useEffect(() => {
    const setupAuth =

Lezioni Apprese & Best Practice

Decisioni Architetturali

✅ Cosa Ha Funzionato Bene:

• Strategia export multi-piattaforma (condizioni react-native/browser/node)
• Zod per validazione runtime + controllo compile-time TypeScript
• Bundle React hooks separato per migliore tree-shaking
• IndexedDB per caching browser (superiore a LocalStorage)

📚 Punti Chiave:

• Build specifici per piattaforma critici per ottimizzazione bundle size
• Validazione runtime essenziale per integrità dati API
• Strategia caching deve considerare scenari offline
• Integrazione mTLS richiede attenta inizializzazione async

Stack Tecnico

Linguaggi & Framework

• TypeScript (5.0+) - Implementazione type-safe
• React (18.2+) - Hook e utility
• React Native (0.72+) - Supporto mobile

Strumenti di Build

• Rollup (4.0+) - Module bundler con tree-shaking
• TypeScript Compiler - Generazione tipi
• Jest (29.5+) - Testing framework

Dipendenze Core

• axios (1.6+) - Client HTTP
• idb (8.0+) - Wrapper IndexedDB per browser
• zod (4.0+) - Validazione schema runtime
• @a-cube-io/expo-mutual-tls - Autenticazione mTLS

Conclusione

@a-cube-io/ereceipts-js-sdk dimostra lo sviluppo di SDK multi-piattaforma production-ready con focus su type safety, performance ed esperienza sviluppatore. Il progetto bilancia con successo:

• ✅ Supporto Multi-piattaforma: Singolo codebase per web, mobile e server
• ✅ Type Safety: Validazione compile-time + runtime
• ✅ Performance: Caching intelligente e build ottimizzati
• ✅ Sicurezza: Integrazione mTLS per chiamate API autenticate
• ✅ Developer Experience: React hooks e design API intuitivo
• ✅ Utilizzo Production: Battle-tested in Pempel Dashboard e Invoice Dashboard

Repository: Repository interno A-Cube Pacchetto: @a-cube-io/ereceipts-js-sdk Licenza: MIT