🧱 ziegel

Appearance

@breadstone/ziegel-intl-commerce ​

MIT LicenseTypeScriptnpm

International commerce and financial services utilities for the ziegel framework. Provides IBAN validation, BIC/SWIFT codes, country-specific commerce information, and financial data handling.

Financial I18n: Specialized internationalization support for commerce, banking, and financial applications with robust validation and formatting.

🚀 Overview ​

@breadstone/ziegel-intl-commerce provides:

  • IBAN Support: Complete IBAN validation, parsing, formatting, and country-specific handling
  • BIC/SWIFT Codes: Bank Identifier Code validation and processing
  • Country Commerce Info: Country-specific commerce data, payment methods, and financial regulations
  • Financial Validation: Robust validation utilities for financial identifiers and formats
  • Payment System Abstractions: Interfaces for international payment processing

📦 Installation ​

bash
npm install @breadstone/ziegel-intl-commerce
# or
yarn add @breadstone/ziegel-intl-commerce

🧩 Features & Usage Examples ​

IBAN Processing ​

typescript
import { Iban, IIbanLike } from '@breadstone/ziegel-intl-commerce';

// Create and validate IBAN
const iban = new Iban('DE89370400440532013000');
console.log(iban.isValid); // true
console.log(iban.countryCode); // "DE"
console.log(iban.formatted); // "DE89 3704 0044 0532 0130 00"

// Work with IBAN-like objects
class CustomIban implements IIbanLike {
  constructor(private value: string) {}
  get iban() { return this.value; }
  get isValid() { return Iban.validate(this.value); }
}

BIC/SWIFT Code Handling ​

typescript
import { IBicLike } from '@breadstone/ziegel-intl-commerce';

class BicCode implements IBicLike {
  constructor(private code: string) {}

  get bankCode(): string {
    return this.code.substring(0, 4);
  }

  get countryCode(): string {
    return this.code.substring(4, 6);
  }

  get locationCode(): string {
    return this.code.substring(6, 8);
  }
}

const bic = new BicCode('DEUTDEFF');
console.log(bic.bankCode); // "DEUT"
console.log(bic.countryCode); // "DE"

Country Commerce Information ​

typescript
import { CountryInfo, ICountryInfoLike } from '@breadstone/ziegel-intl-commerce';

const germanyInfo = new CountryInfo('DE');
console.log(germanyInfo.ibanLength); // 22
console.log(germanyInfo.supportedPaymentMethods);
console.log(germanyInfo.currencyCode); // "EUR"

// Custom country info implementation
class CustomCountryInfo implements ICountryInfoLike {
  constructor(private code: string) {}

  get countryCode() { return this.code; }
  get paymentRegulations() { return this.getRegulations(); }

  private getRegulations() {
    // Return country-specific payment regulations
    return {};
  }
}

Financial Data Validation ​

typescript
import { Iban } from '@breadstone/ziegel-intl-commerce';

// Batch IBAN validation
const ibanCodes = [
  'DE89370400440532013000',
  'GB82WEST12345698765432',
  'INVALID_IBAN'
];

const validationResults = ibanCodes.map(code => ({
  iban: code,
  isValid: new Iban(code).isValid,
  country: new Iban(code).countryCode
}));

console.log(validationResults);
// [
//   { iban: 'DE89...', isValid: true, country: 'DE' },
//   { iban: 'GB82...', isValid: true, country: 'GB' },
//   { iban: 'INVALID...', isValid: false, country: null }
// ]

📚 Package import points ​

typescript
import {
    // IBAN utilities
    Iban, IIbanLike,

    // BIC/SWIFT utilities
    IBicLike,

    // Country commerce information
    CountryInfo, ICountryInfoLike
} from '@breadstone/ziegel-intl-commerce';

📚 API Documentation ​

For detailed API documentation, visit: API Docs

  • @breadstone/ziegel-core: Foundation utilities and type definitions
  • @breadstone/ziegel-intl: Core internationalization support
  • @breadstone/ziegel-intl-units: Units of measurement and conversion

License ​

MIT

Issues ​

Please report bugs and feature requests in the Issue Tracker showBreakdown: true }); // Result: "119,00 € (inkl. 19,00 € MwSt.)"


### Currency Selection UX

```typescript
// Provide currency detection and selection
const currencyDetector = new CurrencyDetector({
  sources: ['geolocation', 'browser', 'user-preference'],
  fallback: 'USD'
});

const detectedCurrency = await currencyDetector.detectCurrency();

Performance Optimization ​

Caching Strategies ​

typescript
import { CommerceCache } from '@ziegel/intl-commerce';

const cache = new CommerceCache({
  priceFormats: { ttl: 300000, maxSize: 1000 },
  exchangeRates: { ttl: 3600000, maxSize: 100 },
  productTranslations: { ttl: 86400000, maxSize: 5000 }
});

Lazy Loading ​

typescript
// Load currency data on demand
const lazyCurrencyLoader = new LazyCurrencyLoader({
  preloadCurrencies: ['USD', 'EUR'],
  loadOnDemand: true
});

Migration Guide ​

From react-currency-format ​

typescript
// Before
import CurrencyFormat from 'react-currency-format';

<CurrencyFormat
  value={price}
  displayType="text"
  thousandSeparator={true}
  prefix="$"
/>

// After
import { usePriceFormatter } from '@ziegel/intl-commerce/react';

function PriceDisplay({ price }) {
  const formatPrice = usePriceFormatter();
  return <span&gt;{formatPrice(price, 'USD')}</span&gt;;
}

API Reference ​

For complete API documentation, see the API Reference.