@nmipayments/nmi-core

Core utilities and shared types for NMI Embedded Components

Overview

@nmipayments/nmi-core is a foundational package that provides shared utilities, types, themes, and services used across all NMI Embedded Components. It serves as the common foundation for both Svelte and React implementations of NMI payment and reporting components.

Installation

npm install @nmipayments/nmi-core

What's Included

Types

• Payment Types: Payment method definitions, layout configurations, and API interfaces
• Appearance Types: Theme and styling configurations
• Core API Types: Token requests/responses and common data structures

Utilities

• fetchUtils: HTTP client utilities for API communication
• themeUtils: Theme application and CSS variable management
• densityUtils: Layout density and spacing calculations

Themes

• Default Themes: Pre-built light and dark themes
• Theme System: Extensible theming architecture with CSS custom properties

Services

• tokenService: Token validation and management utilities

Usage

Types

import type { 
  PaymentMethod, 
  Appearance, 
  NmiTokenRequest,
  NmiTokenResponse,
  LayoutType 
} from '@nmipayments/nmi-core';

const paymentConfig: {
  methods: PaymentMethod[];
  layout: LayoutType;
  appearance: Appearance;
} = {
  methods: ['card', 'ach'],
  layout: 'multiLine',
  appearance: {
    theme: 'light',
    layoutSpacing: 'default'
  }
};

Utilities

import { fetchUtils, themeUtils } from '@nmipayments/nmi-core';

// HTTP utilities
const response = await fetchUtils.post('/api/tokens', {
  amount: 1000,
  currency: 'USD'
});

// Theme utilities
themeUtils.applyTheme(document.body, {
  theme: 'dark',
  primaryColor: '#8b5cf6'
});

Themes

import { themes } from '@nmipayments/nmi-core';

// Access pre-built themes
const lightTheme = themes.light;
const darkTheme = themes.dark;

// Create custom theme
const customTheme = {
  ...themes.light,
  primaryColor: '#8b5cf6',
  borderRadius: '8px'
};

Services

import { tokenService } from '@nmipayments/nmi-core';

// Validate tokenization key format
const isValid = tokenService.validateTokenizationKey('your-key');

// Extract environment from key
const environment = tokenService.getEnvironment('your-key');

API Reference

PaymentMethod

type PaymentMethod = 'card' | 'ach' | 'apple-pay' | 'google-pay';

LayoutType

type LayoutType = 'singleLine' | 'multiLine' | 'stacked';

Appearance

interface Appearance {
  theme?: 'light' | 'dark';
  layoutSpacing?: 'compact' | 'default' | 'spacious';
  textSize?: 'small' | 'default' | 'large';
  radiusSize?: 'none' | 'small' | 'default' | 'large';
  primaryColor?: string;
  backgroundColor?: string;
  borderColor?: string;
  textColor?: string;
}

NmiTokenRequest

interface NmiTokenRequest {
  tokenization_key: string;
  amount?: string;
  currency?: string;
  [key: string]: any;
}

Framework Compatibility

This package is framework-agnostic and provides utilities that work in:

• Vanilla JavaScript/TypeScript
• Svelte (used by @nmipayments/nmi-pay and @nmipayments/nmi-reporting)
• React (used by React wrapper packages)
• Vue (future compatibility)
• Angular (future compatibility)

Bundle Information

• Format: ES modules and CommonJS
• Tree-shakeable: Yes, import only what you need
• TypeScript: Full TypeScript support with declaration files
• Dependencies: Zero runtime dependencies

Architecture

This package follows a modular architecture where each feature is separated into its own directory:

src/
├── types/          # TypeScript type definitions
├── utils/          # Utility functions
├── themes/         # Theme definitions
├── services/       # Shared services
└── index.ts        # Main export file

License

MIT