Metal Pricing Engine

Production-ready, domain-first metal pricing engine factory.

A robust, TypeScript-first library for fetching and normalizing metal prices (Gold, Silver, Platinum, Palladium) in any currency. Designed with Domain-Driven Design (DDD) principles, it supports pluggable providers for both metal prices and FX rates.

Features

• Domain-Driven Design: Strongly typed domain models Metal, Currency, Money.
• Pluggable Architecture: Easily swap out MetalMarketProvider or FXRateProvider (e.g., Metals-API, Fixer.io, or your own mock).
• Resilience: Built-in caching (TTL), error handling, and fallback strategies.
• Precision Control: Configurable rounding policies per metal (e.g., Gold to 2 decimals, Silver to 3).
• Zero-Dependency Core: The core domain logic is pure and testable.

Installation

npm install metal-pricing-engine

Basic Usage

Here's how to initialize the client and fetch a price.

import { 
    createMetalPriceClient, 
    Metal, 
    Currency, 
    MockMetalProvider, 
    MockFXProvider 
} from 'metal-pricing-engine';

async function main() {
    // 1. Initialize the client with providers
    const client = createMetalPriceClient({
        metalProvider: new MockMetalProvider(), // Or use a real provider
        fxProvider: new MockFXProvider(),       // Or use a real provider
        ttl: { defaultMs: 10000 }               // Cache for 10 seconds
    });

    // 2. Fetch Gold Price in USD
    const goldPrice = await client.getMetalPrice({
        metal: Metal.GOLD,
        currency: Currency.USD,
    });

    console.log(`Gold Price: ${goldPrice.price} ${goldPrice.currency}`);
    // Output: Gold Price: 1850.50 USD

    // 3. Fetch Silver Price in EUR (Automatic FX Conversion)
    const silverPrice = await client.getMetalPrice({
        metal: Metal.SILVER,
        currency: Currency.EUR,
    });
    
    console.log(`Silver Price: ${silverPrice.price} ${silverPrice.currency}`);
}

main().catch(console.error);

API Reference

createMetalPriceClient(config)

Creates a new instance of the pricing engine.

• config.metalProvider: Instance implementing MetalMarketProvider.
• config.fxProvider: Instance implementing FXRateProvider.
• config.ttl: Cache configuration.

client.getMetalPrice(request)

Fetches the current spot price.

• request.metal: Enum Metal.GOLD, Metal.SILVER, etc.
• request.currency: Enum Currency.USD, Currency.EUR, etc.

Architecture

This project follows a Hexagonal Architecture (Ports & Adapters):

• Domain: Core business logic (Money, Metal, PricingService).
• Ports: Interfaces for external dependencies (MetalMarketProvider, FXRateProvider).
• Adapters: Concrete implementations (Metals-API, ECB, Mocks).

License

ISC