A-Cube e-Receipts SDK

Overview

@a-cube-io/ereceipts-js-sdk is a production-ready TypeScript SDK for electronic receipt management, providing seamless multi-platform support across Browser, Node.js, and React Native environments. Built with modern tooling and strict type safety, it offers enterprise-grade reliability with an intuitive developer experience.

Key Achievements

• 🌍 Multi-Platform Support: Single codebase for Browser, Node.js, and React Native
• 🔒 Type-Safe Implementation: Full TypeScript with Zod schema validation
• 💾 Intelligent Caching: IndexedDB for browser, optimized storage strategies
• 📦 Modern Build System: Rollup with tree-shaking and code-splitting
• 🔐 mTLS Authentication: Integration with expo-mutual-tls for secure API calls
• ⚡ Optimized Performance: Lazy loading and efficient memory management
• 🎯 Developer-Friendly API: Intuitive hooks and utilities for React/React Native
• 📊 Production-Ready: Used in live A-Cube products (Pempel Dashboard, Invoice Dashboard)

View on GitHub | NPM Package

Technical Architecture

System Design

The SDK implements a layered architecture with platform-specific optimizations:

┌─────────────────────────────────────────────────┐
│        Application Layer (React/RN/Node)        │
│      Custom Hooks & Utility Functions           │
└────────────────┬────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────┐
│         Core SDK Layer (TypeScript)             │
│   Receipt Management • Validation • Caching     │
└──────┬──────────────────────────────┬──────────┘
       │                              │
┌──────▼─────────┐          ┌─────────▼──────────┐
│ Browser Layer  │          │  Native Layer      │
│ - IndexedDB    │          │  - AsyncStorage    │
│ - LocalStorage │          │  - SQLite          │
│ - Fetch API    │          │  - Expo Modules    │
└────────────────┘          └────────────────────┘

Module Exports Structure

The SDK provides optimized entry points for each platform:

Package Exports (package.json):

{
  "exports": {
    ".": {
      "react-native": "./dist/index.native.js",
      "browser": "./dist/index.esm.js",
      "node": "./dist/index.cjs.js",
      "import": "./dist/index.esm.js",
      "require": "./dist/index.cjs.js",
      "types": "./dist/index.d.ts"
    },
    "./react": {
      "import": "./dist/react.esm.js",
      "require": "./dist/react.cjs.js",
      "types": "./dist/react.d.ts"
    }
  }
}

Platform Resolution:

• React Native: Optimized bundle without browser-specific APIs
• Browser: ESM format with IndexedDB support
• Node.js: CommonJS format for server-side usage
• React Hooks: Separate entry point for hooks (@a-cube-io/ereceipts-js-sdk/react)

Core Features

1. Receipt Management System

The SDK provides comprehensive receipt lifecycle management:

Receipt Operations

import { EReceiptsSDK } from '@a-cube-io/ereceipts-js-sdk'
 
// Initialize SDK
const sdk = new EReceiptsSDK({
  apiUrl: 'https://api.acubeapi.com',
  authToken: 'user-jwt-token',
  enableCache: true,
  cacheTTL: 3600000 // 1 hour
})
 
// Fetch receipts with automatic caching
const receipts = await sdk.getReceipts({
  startDate: '2025-01-01',
  endDate: '2025-12-31',
  status: 'validated'
})
 
// Get single receipt (from cache if available)
const receipt = await sdk

React Hooks Integration

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. Type-Safe Validation with Zod

All API responses and data structures validated at runtime:

import { z } from 'zod'
 
// Receipt schema
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. Intelligent Caching System

Multi-layer caching strategy optimized for each platform:

Browser Implementation (IndexedDB)

class BrowserCacheManager {
  private db: IDBDatabase
 
  async initialize() {
    this.db = await openDB('ereceipts-cache', 1, {
      upgrade(db) {
        // Receipts store
        const receiptsStore = db.createObjectStore('receipts', {
          keyPath: 'id'
        })
        receiptsStore.createIndex('date', 'date')
        receiptsStore.createIndex('status', 'status')
        receiptsStore.createIndex('merchantName', 'merchantName')

React Native Implementation (AsyncStorage)

class NativeCacheManager {
  private readonly CACHE_PREFIX = '@ereceipts:cache:'
 
  async cacheReceipts(receipts: Receipt[]) {
    const cacheEntries = receipts.map(receipt => [
      `${this.CACHE_PREFIX}${receipt.id}`,
      JSON.stringify(receipt)
    ])
 
    await AsyncStorage.multiSet(cacheEntries)
    await AsyncStorage.setItem(
      `${this.CACHE_PREFIX}lastSync`,
      Date

Cache Invalidation Strategy

• TTL-Based: Automatic expiration after configurable duration
• Manual Sync: User-triggered refresh invalidates cache
• Smart Updates: Partial cache updates for modified receipts
• Memory Management: LRU eviction for browser storage limits

4. mTLS Authentication Integration

Seamless integration with @a-cube-io/expo-mutual-tls for secure API calls:

import ExpoMutualTls from '@a-cube-io/expo-mutual-tls'
import { EReceiptsSDK } from '@a-cube-io/ereceipts-js-sdk'
 
// Configure mTLS
await ExpoMutualTls.configureP12('ereceipts-app', true)
await ExpoMutualTls.storeP12(certificateData, password)
 
// SDK automatically uses mTLS for API calls
const sdk = new EReceiptsSDK({
  apiUrl: 'https://api.acubeapi.com',
  useMTLS: true, // Enable mTLS authentication
  authToken: 'user-jwt-token'
})
 
// All API calls use client certificate authentication
const receipts = await sdk.getReceipts

Build Flow & Development Pipeline

Build Architecture

Source Files (TypeScript)
        ↓
┌───────────────────────────────┐
│      Rollup Build System       │
│  - TypeScript Compilation      │
│  - Code Splitting              │
│  - Tree Shaking                │
│  - Type Generation             │
└───────────┬───────────────────┘
            │
    ┌───────┴────────┐
    ▼                ▼
┌─────────┐    ┌──────────┐
│ ESM     │    │   CJS    │
│ Browser │    │  Node.js │
│ RN      │    │          │
└────┬────┘    └────┬─────┘
     │              │
     └──────┬───────┘
            ▼
    NPM Package (.tgz)

Rollup Configuration

rollup.config.js:

import typescript from '@rollup/plugin-typescript'
import resolve from '@rollup/plugin-node-resolve'
import commonjs from '@rollup/plugin-commonjs'
import replace from '@rollup/plugin-replace'
import dts from 'rollup-plugin-dts'
 
export default [
  // Main bundle (Browser/Node.js)
  {
    input: 'src/index.ts',
    output: [
      {
        file: 'dist/index.esm.js',
        format: 'esm',
        sourcemap: true
      },
      {
        file: 'dist/index.cjs.js',
        format: 'cjs',
        sourcemap: true

Build Scripts

package.json scripts:

{
  "scripts": {
    "build": "rollup -c",
    "build:dev": "npm run build && npm pack",
    "dev": "rollup -c -w",
    "test": "jest --passWithNoTests --detectOpenHandles",
    "test:watch": "npm run test -- --watch",
    "lint": "eslint src --ext .ts,.tsx",
    "typecheck": "npx tsc --noEmit",
    "prepublishOnly": "npm run build"
  }
}

TypeScript Configuration

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM"],
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "jsx": "react"
  },

Performance Characteristics

Benchmarks

Memory Footprint

• SDK Core: ~500KB (minified)
• Dependencies: ~1.5MB (axios + zod + idb)
• Runtime Memory: ~5-10MB (100 cached receipts)
• IndexedDB Storage: ~2KB per receipt

Optimization Strategies

1. Lazy Loading: React hooks load only when needed
2. Code Splitting: Separate bundles for React hooks
3. Tree Shaking: Unused code eliminated by bundlers
4. Batch Operations: IndexedDB bulk writes for performance
5. Response Streaming: Large datasets processed incrementally

Development Workflow

Local Development Setup

# 1. Install dependencies
npm install
 
# 2. Start watch mode for development
npm run dev
 
# 3. Run tests
npm test
 
# 4. Type checking
npm run typecheck
 
# 5. Lint code
npm run lint
 
# 6. Build for production
npm run build

Testing in Pempel Dashboard

# 1. Build SDK and create local package
cd acube-ereceipt
npm run build:dev  # Creates .tgz file
 
# 2. Install in Pempel Dashboard
cd ../pempel-dashboard
npm install ../acube-ereceipt/a-cube-io-ereceipts-js-sdk-0.1.0.tgz
 
# 3. Start Pempel Dashboard
npm start

Testing Strategy

Unit Tests (Jest):

import { EReceiptsSDK } from '../src'
 
describe('EReceiptsSDK', () => {
  let sdk: EReceiptsSDK
 
  beforeEach(() => {
    sdk = new EReceiptsSDK({
      apiUrl: 'https://test.api.com',
      authToken: 'test-token'
    })
  })
 
  test('should initialize correctly', () => {
    expect(sdk).toBeDefined()
    expect(sdk.apiUrl).toBe('https://test.api.com')
  })
 
  test('should validate receipt schema', () 

Integration Example

Complete React Native App

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(() =>

Lessons Learned & Best Practices

Architecture Decisions

✅ What Worked Well:

• Multi-platform exports strategy (react-native/browser/node conditions)
• Zod for runtime validation + TypeScript compile-time checking
• Separate React hooks bundle for better tree-shaking
• IndexedDB for browser caching (superior to LocalStorage)

📚 Key Takeaways:

• Platform-specific builds critical for bundle size optimization
• Runtime validation essential for API data integrity
• Caching strategy must account for offline scenarios
• mTLS integration requires careful async initialization

Performance Optimization

1. Bundle Size Management: Separate React hooks reduced core bundle by 40%
2. Lazy Initialization: Defer expensive operations until needed
3. Batch API Calls: Combine multiple requests to reduce network overhead
4. Intelligent Caching: TTL + manual invalidation prevents stale data

Developer Experience

1. TypeScript First: Strong typing catches bugs at compile time
2. React Hooks: Familiar API for React developers
3. Comprehensive Docs: JSDoc comments for all public APIs
4. Example Apps: Working examples in Pempel Dashboard

Future Enhancements

Planned Features

• Offline Queue: Queue operations when offline, sync when online
• Receipt Search: Full-text search across cached receipts
• Export Utilities: CSV/Excel export for accounting software
• Receipt Templates: Customizable PDF rendering
• GraphQL Support: Alternative to REST API
• React Query Integration: Option to use React Query for state management
• Receipt Analytics: Spending patterns and insights

Community Contributions

The SDK welcomes contributions in:

• Additional platform support (Flutter, Electron)
• Performance optimizations
• Testing coverage improvements
• Documentation enhancements
• Bug fixes and error handling

Technical Stack Summary

Languages & Frameworks

• TypeScript (5.0+) - Type-safe implementation
• React (18.2+) - Hooks and utilities
• React Native (0.72+) - Mobile support

Build Tools

• Rollup (4.0+) - Module bundler with tree-shaking
• TypeScript Compiler - Type generation
• Jest (29.5+) - Testing framework
• ESLint - Code quality

Core Dependencies

• axios (1.6+) - HTTP client
• idb (8.0+) - IndexedDB wrapper for browser
• zod (4.0+) - Runtime schema validation
• @a-cube-io/expo-mutual-tls - mTLS authentication

Development Dependencies

• @rollup/plugin-typescript - TypeScript compilation
• @rollup/plugin-node-resolve - Dependency resolution
• rollup-plugin-dts - Type definition bundling
• ts-jest - Jest TypeScript support

Conclusion

@a-cube-io/ereceipts-js-sdk demonstrates production-ready multi-platform SDK development with a focus on type safety, performance, and developer experience. The project successfully balances:

• ✅ Multi-platform Support: Single codebase for web, mobile, and server
• ✅ Type Safety: Compile-time + runtime validation
• ✅ Performance: Intelligent caching and optimized builds
• ✅ Security: mTLS integration for authenticated API calls
• ✅ Developer Experience: React hooks and intuitive API design
• ✅ Production Usage: Battle-tested in Pempel Dashboard and Invoice Dashboard

The SDK serves as an excellent reference for:

• Multi-platform NPM package development
• TypeScript SDK design patterns
• React/React Native integration
• Offline-first architecture
• mTLS authentication flows

Repository: Internal A-Cube repository Package: @a-cube-io/ereceipts-js-sdk License: MIT