SDK A-Cube e-Receipts

Aperçu

@a-cube-io/ereceipts-js-sdk est un SDK TypeScript prêt pour la production pour la gestion des reçus électroniques, offrant un support multi-plateforme transparent sur les environnements Browser, Node.js et React Native. Construit avec des outils modernes et une type safety stricte, il offre une fiabilité de niveau entreprise avec une expérience développeur intuitive.

Réalisations Clés

• 🌍 Support Multi-Plateforme: Base de code unique pour Browser, Node.js et React Native
• 🔒 Implémentation Type-Safe: TypeScript complet avec validation de schéma Zod
• 💾 Mise en Cache Intelligente: IndexedDB pour navigateur, stratégies de stockage optimisées
• 📦 Système de Build Moderne: Rollup avec tree-shaking et code-splitting
• 🔐 Authentification mTLS: Intégration avec expo-mutual-tls pour appels API sécurisés
• ⚡ Performance Optimisée: Chargement paresseux et gestion efficace de la mémoire
• 🎯 API Developer-Friendly: Hooks et utilitaires intuitifs pour React/React Native
• 📊 Prêt pour la Production: Utilisé dans les produits A-Cube en production (Pempel Dashboard, Invoice Dashboard)

Voir sur GitHub | Package NPM

Architecture Technique

Conception du Système

Le SDK implémente une architecture en couches avec des optimisations spécifiques à la plateforme:

┌─────────────────────────────────────────────────┐
│     Couche Application (React/RN/Node)          │
│      Hooks Personnalisés & Utilitaires          │
└────────────────┬────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────┐
│         Couche SDK Core (TypeScript)            │
│   Gestion Reçus • Validation • Mise en Cache   │
└──────┬──────────────────────────────┬──────────┘
       │                              │
┌──────▼─────────┐          ┌─────────▼──────────┐
│ Couche         │          │  Couche Native     │
│ Navigateur     │          │  - AsyncStorage    │
│ - IndexedDB    │          │  - SQLite          │
│ - LocalStorage │          │  - Modules Expo    │
│ - Fetch API    │          │                    │
└────────────────┘          └────────────────────┘

Fonctionnalités Principales

1. Système de Gestion des Reçus

Le SDK fournit une gestion complète du cycle de vie des reçus:

Opérations sur les Reçus

import { EReceiptsSDK } from '@a-cube-io/ereceipts-js-sdk'
 
// Initialiser le SDK
const sdk = new EReceiptsSDK({
  apiUrl: 'https://api.acubeapi.com',
  authToken: 'user-jwt-token',
  enableCache: true,
  cacheTTL: 3600000 // 1 heure
})
 
// Récupérer les reçus avec mise en cache automatique
const receipts = await sdk.getReceipts({
  startDate: '2025-01-01',
  endDate: '2025-12-31',
  status: 'validated'
})
 
// Obtenir un seul reçu (depuis le cache si disponible)
const receipt = await sdk.getReceipt('receipt-id-123')
 
// Télécharger le PDF du reçu
const pdfBlob = await sdk.downloadReceiptPDF('receipt-id-123')

Intégration 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. Validation Type-Safe avec Zod

Toutes les réponses API et structures de données validées au runtime:

import { z } from 'zod'
 
// Schéma de reçu
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. Système de Mise en Cache Intelligent

Stratégie de mise en cache multi-couche optimisée pour chaque plateforme:

Implémentation Navigateur (IndexedDB)

• Indexation: Index sur date, status, merchantName pour requêtes rapides
• Opérations Batch: Écritures bulk pour performances optimales
• Gestion Métadonnées: Timestamp dernière sync pour invalidation cache

Implémentation React Native (AsyncStorage)

• Préfixe Cache: Organisation des clés avec namespace
• Multi-Get/Set: Opérations batch pour réduire latence
• Gestion Mémoire: Stratégie d'éviction LRU

4. Intégration Authentification mTLS

Intégration transparente avec @a-cube-io/expo-mutual-tls pour appels API sécurisés:

import ExpoMutualTls from '@a-cube-io/expo-mutual-tls'
import { EReceiptsSDK } from '@a-cube-io/ereceipts-js-sdk'
 
// Configurer mTLS
await ExpoMutualTls.configureP12('ereceipts-app', true)
await ExpoMutualTls.storeP12(certificateData, password)
 
// Le SDK utilise automatiquement mTLS pour les appels API
const sdk = new EReceiptsSDK({
  apiUrl: 'https://api.acubeapi.com',
  useMTLS: true,
  authToken: 'user-jwt-token'
})
 
// Tous les appels API utilisent l'authentification par certificat client
const receipts = await sdk.getReceipts() 

Caractéristiques de Performance

Benchmarks

Empreinte Mémoire

• SDK Core: ~500KB (minifié)
• Dépendances: ~1.5MB (axios + zod + idb)
• Mémoire Runtime: ~5-10MB (100 reçus en cache)
• Stockage IndexedDB: ~2KB par reçu

Exemple d'Intégration

Application React Native Complète

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 =

Leçons Apprises & Meilleures Pratiques

Décisions Architecturales

✅ Ce Qui A Bien Fonctionné:

• Stratégie d'exports multi-plateforme (conditions react-native/browser/node)
• Zod pour validation runtime + vérification compile-time TypeScript
• Bundle React hooks séparé pour meilleur tree-shaking
• IndexedDB pour cache navigateur (supérieur à LocalStorage)

📚 Points Clés:

• Builds spécifiques à la plateforme critiques pour optimisation taille bundle
• Validation runtime essentielle pour intégrité données API
• Stratégie de cache doit considérer scénarios hors ligne
• Intégration mTLS nécessite initialisation async soignée

Stack Technique

Langages & Frameworks

• TypeScript (5.0+) - Implémentation type-safe
• React (18.2+) - Hooks et utilitaires
• React Native (0.72+) - Support mobile

Outils de Build

• Rollup (4.0+) - Module bundler avec tree-shaking
• TypeScript Compiler - Génération de types
• Jest (29.5+) - Framework de tests

Dépendances Core

• axios (1.6+) - Client HTTP
• idb (8.0+) - Wrapper IndexedDB pour navigateur
• zod (4.0+) - Validation schéma runtime
• @a-cube-io/expo-mutual-tls - Authentification mTLS

Conclusion

@a-cube-io/ereceipts-js-sdk démontre le développement de SDK multi-plateforme prêt pour la production avec un focus sur type safety, performance et expérience développeur. Le projet équilibre avec succès:

• ✅ Support Multi-plateforme: Base de code unique pour web, mobile et serveur
• ✅ Type Safety: Validation compile-time + runtime
• ✅ Performance: Mise en cache intelligente et builds optimisés
• ✅ Sécurité: Intégration mTLS pour appels API authentifiés
• ✅ Expérience Développeur: React hooks et conception API intuitive
• ✅ Utilisation Production: Battle-tested dans Pempel Dashboard et Invoice Dashboard

Dépôt: Dépôt interne A-Cube Package: @a-cube-io/ereceipts-js-sdk Licence: MIT