Zero Carbon ERP Config SDK

A comprehensive TypeScript SDK providing emission configurations and calculation utilities for carbon footprint tracking across 24+ industries. Now with full backend compatibility - use the same SDK on both frontend (React) and backend (Node.js) applications.

Installation

npm install erp-config-sdk

Features

• 🏭 24+ Industry-specific emission configurations
• 📘 RCO module configuration parsed from the ERP template sheets
• 🔒 Type-safe emission data structures with deep type safety
• 🖥️ Full backend compatibility - No React dependencies in data output
• 📊 Carbon intensity calculations
• ⚡ Emission source generators
• 🗺️ Industry mapping utilities
• 🎨 React Icons integration (frontend only)
• ⚙️ UI feature configurations
• 🔧 Granular configuration functions for precise data access

Backend vs Frontend Usage

🖥️ Backend Usage (Node.js, API servers)

Perfect for backend applications, APIs, and server-side processing:

import { 
  getAllConfig,
  getUserNameBackendConfig,
  getIndustryBackendConfig,
  getCombinedBackendConfig,
  type BackendIndustryConfig,
  type BackendUserConfig
} from 'erp-config-sdk';

// Get all configurations (no React components)
const allConfigs = getAllConfig();

// Get specific industry configuration  
const cementConfig = getIndustryBackendConfig('Cement');

// Get user-specific configuration
const gasLabConfig = getUserNameBackendConfig('gas lab');

// Get combined configuration (user overrides + industry)
const combinedConfig = getCombinedBackendConfig('Cement', 'gas lab');

⚛️ Frontend Usage (React applications)

Full React integration with icons and UI components:

import { 
  getIndustryConfig,
  getUIFeatures,
  type IndustryConfig 
} from 'erp-config-sdk';

// Get configuration with React icons
const config = getIndustryConfig('Cement');
const uiFeatures = getUIFeatures('manufacturing');
const rcoSheets = config.rco;

Industries Supported

• Alloy Manufacturing
• Aluminum Production
• Automobile/Automotive
• Aviation
• Banking & Financial Services
• Cement Production
• Chemical Manufacturing
• Construction
• Food & Beverage
• Information Technology
• Leather & Textiles
• Logistics & Transportation
• Manufacturing
• Metal Processing
• Oil & Gas/Petrochemicals
• Packaging
• Pharmaceuticals
• Pulp & Paper
• Real Estate
• Shipping & Maritime
• Steel Production
• Telecommunications
• Textile Manufacturing
• Utilities & Energy

Backend Functions

Core Backend Functions

getAllConfig(): AllConfigurations

Returns all industry and user configurations in backend-compatible format.

const allConfigs = getAllConfig();
console.log(allConfigs.industries.Cement.scope1); // Array of backend scopes
console.log(allConfigs.userConfigs['gas lab']); // User-specific config

getIndustryBackendConfig(industryName: string): BackendIndustryConfig | undefined

Get complete configuration for a specific industry.

const cementConfig = getIndustryBackendConfig('Cement');
if (cementConfig) {
  console.log(`Scope1 items: ${cementConfig.scope1.length}`);
  console.log(`Scope2 items: ${cementConfig.scope2.length}`);
  console.log(`Scope3 items: ${cementConfig.scope3.length}`);
  console.log(`RCO sheets: ${cementConfig.rco.length}`);
}

getUserNameBackendConfig(username: string): BackendUserConfig | undefined

Get user-specific configurations by username.

const gasLabUser = getUserNameBackendConfig('gas lab');
if (gasLabUser) {
  console.log('User has custom scope1:', gasLabUser.scope1?.length || 0);
  console.log('User has water management:', !!gasLabUser.waterManagement);
}

getCombinedBackendConfig(industryName: string, username?: string): BackendIndustryConfig | undefined

Get combined configuration where user settings override industry defaults.

// Industry config only
const industry = getCombinedBackendConfig('Cement');

// Combined with user overrides
const combined = getCombinedBackendConfig('Cement', 'gas lab');

// User-specific configurations will override industry defaults

Deep Type Safety

All backend functions provide complete type safety from root to leaf properties:

Core Backend Types

// Product-level typing
type BackendProduct = {
  name: string;
  unit: string;
  type: string;
  calorificValue: number;
  emissionFactor: number;
  energyConversionFactor?: number;
};

// Emission item typing
type BackendEmissionItem = {
  item: string;
  emissionFactor: number;
  unit: string;
};

// Equipment category typing
type BackendEquipmentCategory = {
  category: string;
  items: BackendEmissionItem[];
};

// Scope configuration typing (no React components)
type BackendScope = {
  name: string;
  icon?: string; // String instead of React component
  scope: string;
  unit: string;
  subProducts: BackendProduct[]; // Fully typed products
  desc: string;
  group?: string;
  className?: string;
};

// Complete industry configuration
type BackendIndustryConfig = {
  scope1: BackendScope[];
  scope2: BackendScope[];
  scope3: BackendScope3Item[];
  rco: BackendScope3Item[];
  additionalScopes?: {
    [key: string]: BackendAdditionalScopeItem[];
  };
};

Data Access Examples

// Access emission factors with full type safety
const config = getIndustryBackendConfig('Cement');
if (config?.scope1[0]?.subProducts[0]) {
  const product = config.scope1[0].subProducts[0];
  
  // All properties are typed and accessible
  const factor: number = product.emissionFactor;
  const unit: string = product.unit;
  const name: string = product.name;
}

// Access scope3 emission data
if (config?.scope3[0]?.subProducts[0]?.items[0]) {
  const emissionItem = config.scope3[0].subProducts[0].items[0];
  
  // Fully typed emission data
  const itemName: string = emissionItem.item;
  const factor: number = emissionItem.emissionFactor;
  const unit: string = emissionItem.unit;
}

Frontend Integration (React)

When using in React applications, you get the same data plus React components:

import { 
  getIndustryConfig, 
  EmissionData, 
  IndustryConfig,
  calculateEmissionFootprint,
  getIndustryFromCompanyName 
} from 'erp-config-sdk';

// Get configuration for a specific industry (includes React icons)
const automobileConfig = getIndustryConfig('automobile');

// Get industry mapping from company name
const industry = getIndustryFromCompanyName('Tesla Motors');

// Type-safe emission data
const emissionData: EmissionData = {
  scope1: 1200,
  scope2: 800,
  scope3: 2400,
  total: 4400
};

React Components with Icons

import { FaIndustry } from 'react-icons/fa';
import { getUIFeatures, getIndustryConfig } from 'erp-config-sdk';

const features = getUIFeatures('manufacturing');
const config = getIndustryConfig('Manufacturing');

function IndustryCard() {
  const IconComponent = config.scope1[0]?.icon || FaIndustry;
  
  return (
    <div>
      <IconComponent size={24} />
      <span>{config.scope1[0]?.name}</span>
    </div>
  );
}

Configuration Structure

Each industry provides comprehensive emission configurations:

• Scope 1 Emissions: Direct emissions from company operations
• Scope 2 Emissions: Indirect emissions from purchased energy
• Scope 3 Emissions: Indirect emissions from value chain activities
• Additional Scopes: Water management and other custom scopes
• UI Features: Icon mappings and display configurations (frontend)
• Deep Type Safety: Complete typing from root to all nested properties

Data Structure Overview

// Complete configuration structure
interface AllConfigurations {
  industries: {
    [industryName: string]: {
      scope1: BackendScope[];        // Direct emissions
      scope2: BackendScope[];        // Energy emissions  
      scope3: BackendScope3Item[];   // Value chain emissions
      additionalScopes?: {           // Custom scopes
        waterManagement: BackendAdditionalScopeItem[];
      };
    };
  };
  userConfigs: {
    [username: string]: {
      scope1?: BackendScope[];
      scope2?: BackendScope[];
      scope3?: BackendScope3Item[];
      waterManagement?: BackendScope;
    };
  };
}

Real-World Usage Examples

Backend API Example

// Express.js API endpoint
app.get('/api/emissions/:industry', (req, res) => {
  const { industry } = req.params;
  const { username } = req.query;
  
  // Get appropriate configuration
  const config = username 
    ? getCombinedBackendConfig(industry, username)
    : getIndustryBackendConfig(industry);
    
  if (!config) {
    return res.status(404).json({ error: 'Industry not found' });
  }
  
  // Return JSON-serialized configuration
  res.json({
    industry,
    username,
    configuration: config,
    scope1Count: config.scope1.length,
    scope2Count: config.scope2.length,
    scope3Count: config.scope3.length
  });
});

Database Integration Example

// Store configurations in database
import { getAllConfig } from 'erp-config-sdk';

async function seedEmissionDatabase() {
  const allConfigs = getAllConfig();
  
  for (const [industryName, config] of Object.entries(allConfigs.industries)) {
    // Store industry configuration
    await db.collection('industries').doc(industryName).set({
      ...config,
      lastUpdated: new Date(),
      version: '1.0'
    });
    
    // Store individual emission factors for fast lookup
    config.scope1.forEach(async (scope, index) => {
      scope.subProducts.forEach(async (product, pIndex) => {
        await db.collection('emission_factors').add({
          industry: industryName,
          scope: 'scope1',
          scopeIndex: index,
          productIndex: pIndex,
          productName: product.name,
          emissionFactor: product.emissionFactor,
          unit: product.unit,
          type: product.type
        });
      });
    });
  }
}

Carbon Footprint Calculation Example

// Calculate emissions using SDK data
function calculateCarbonFootprint(
  industry: string, 
  consumptionData: { [productName: string]: number },
  username?: string
) {
  const config = getCombinedBackendConfig(industry, username);
  if (!config) throw new Error('Industry not found');
  
  let totalEmissions = 0;
  
  // Calculate scope 1 emissions
  config.scope1.forEach(scope => {
    scope.subProducts.forEach(product => {
      const consumption = consumptionData[product.name] || 0;
      const emissions = consumption * product.emissionFactor;
      totalEmissions += emissions;
      
      console.log(`${product.name}: ${consumption} ${product.unit} × ${product.emissionFactor} = ${emissions} kg CO2e`);
    });
  });
  
  return totalEmissions;
}

// Usage
const emissions = calculateCarbonFootprint('Cement', {
  'Coal': 1000,        // 1000 tonnes
  'Natural Gas': 500   // 500 cubic meters  
}, 'gas lab');

console.log(`Total emissions: ${emissions} kg CO2e`);

Types

The SDK exports comprehensive TypeScript types for both backend and frontend usage:

Backend Types (No React Dependencies)

// Import backend-compatible types
import type {
  AllConfigurations,
  BackendIndustryConfig,
  BackendUserConfig,
  BackendScope,
  BackendScope3Item,
  BackendProduct,
  BackendEmissionItem,
  BackendEquipmentCategory,
  BackendEmissions,
  BackendAdditionalScopeItem,
  BackendUserConfigs,
  BackendIndustries
} from 'erp-config-sdk';

// Usage example with full type safety
const handleIndustryConfig = (config: BackendIndustryConfig) => {
  config.scope1.forEach((scope: BackendScope) => {
    scope.subProducts.forEach((product: BackendProduct) => {
      const factor: number = product.emissionFactor;
      const unit: string = product.unit;
      // Full IntelliSense support
    });
  });
};

Frontend Types (With React Components)

// Import frontend types (includes React components)
import type {
  EmissionData,
  EmissionSource,
  ProcessedEmissionItem,
  IndustryConfig,
  CarbonIntensityData,
  BillsAnalyzed,
  Calculations,
  Scope,
  Scope3Item
} from 'erp-config-sdk';

Universal Types

// These types work in both backend and frontend
import type {
  FormData,
  ValidationError,
  FormValidationResult,
  BaseRequest,
  ApiResponse,
  IndustryType,
  FieldConfig,
  PlantNameConfig
} from 'erp-config-sdk';

API Reference

Backend Functions

| Function | Parameters | Return Type | Description | |----------|------------|-------------|-------------| | getAllConfig() | None | AllConfigurations | Get all industry and user configurations | | getIndustryBackendConfig() | industryName: string | BackendIndustryConfig \| undefined | Get specific industry configuration | | getUserNameBackendConfig() | username: string | BackendUserConfig \| undefined | Get user-specific configuration | | getCombinedBackendConfig() | industryName: string, username?: string | BackendIndustryConfig \| undefined | Get combined configuration with user overrides |

Frontend Functions

| Function | Parameters | Return Type | Description | |----------|------------|-------------|-------------| | getIndustryConfig() | industry: string, username?: string | IndustryConfig | Get industry config with React components | | getUserNameScopeConfig() | scopeKey, username?, defaultScope? | T | Get user-specific scope configuration |

Utility Functions

| Function | Parameters | Return Type | Description | |----------|------------|-------------|-------------| | formatEmissions() | value: number | string | Format emission values for display | | generateEmissionSources() | scope: string | EmissionSource[] | Generate emission sources | | getUIFeatures() | industry: string | UIFeature | Get UI configurations | | getIndustryFromCompanyName() | name: string | string | Map company name to industry |

Advanced Usage

Custom Emission Calculations

import { 
  formatEmissions,
  generateEmissionSources,
  getIndustryBackendConfig
} from 'erp-config-sdk';

// Get configuration and calculate emissions
const config = getIndustryBackendConfig('Steel');
if (config) {
  const coalProduct = config.scope1[0]?.subProducts.find(p => p.name === 'Coal');
  if (coalProduct) {
    const emissions = 1000 * coalProduct.emissionFactor; // 1000 tonnes of coal
    const formatted = formatEmissions(emissions); // "1,234.57"
    console.log(`Coal emissions: ${formatted} kg CO2e`);
  }
}

Dependencies

Production Dependencies

• TypeScript: Full type safety and IntelliSense support
• Emission Factor Data: Comprehensive emission factors for 24+ industries

Peer Dependencies (Frontend Only)

{
  "react-icons": "^4.0.0"
}

Note: React Icons are only required for frontend usage. Backend applications do not need React dependencies.

Backend vs Frontend Compatibility

| Feature | Backend | Frontend | |---------|---------|----------| | Configuration Data | ✅ Full access | ✅ Full access | | Type Safety | ✅ Complete | ✅ Complete | | JSON Serialization | ✅ Native | ✅ Native | | React Icons | ❌ Not included | ✅ Included | | Bundle Size | 🔥 Minimal | 📦 Standard | | Node.js Compatible | ✅ Yes | ❌ No | | Browser Compatible | ❌ No | ✅ Yes |

Migration Guide

Upgrading from Frontend-Only Usage

If you were previously using the SDK only in frontend applications:

// Before (frontend only)
import { getIndustryConfig } from 'erp-config-sdk';
const config = getIndustryConfig('Cement');

// After (backend compatible) 
import { getIndustryBackendConfig } from 'erp-config-sdk';
const config = getIndustryBackendConfig('Cement');
// Note: Icons will be strings instead of React components

New Backend-First Applications

For new backend applications, use the backend functions from the start:

import { 
  getAllConfig,
  getIndustryBackendConfig,
  getUserNameBackendConfig,
  getCombinedBackendConfig 
} from 'erp-config-sdk';

// All functions return data without React dependencies

Contributing

Contributions are welcome! Please ensure all changes:

• Include appropriate TypeScript types
• Maintain backward compatibility
• Support both backend and frontend usage
• Include tests for new functionality
• Follow the existing code style

Adding New Industries

To add a new industry configuration:

1. Create a new file in src/config/industries/
2. Define scope1, scope2, and scope3 configurations
3. Export the configuration from src/config/industries/index.ts
4. Add the industry to INDUSTRIES_CONFIG in src/config/index.ts
5. Update the README with the new industry

Adding Backend Functions

When adding new backend functions:

1. Ensure no React dependencies in output
2. Provide complete TypeScript definitions
3. Transform all nested data to backend-compatible format
4. Export from both config and main index files
5. Add comprehensive JSDoc documentation

Support

For questions, issues, or feature requests:

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📚 Documentation: Full API Documentation
• 💬 Community: Discord Support Server

Changelog

Latest Updates

v2.0.0 - Backend Compatibility Release

• ✨ Added getAllConfig() for complete backend access
• ✨ Added getUserNameBackendConfig() for user-specific configs
• ✨ Added getIndustryBackendConfig() for industry-specific configs
• ✨ Added getCombinedBackendConfig() for merged configurations
• 🔒 Complete type safety from root to leaf properties
• 🖥️ Full backend compatibility without React dependencies
• 📦 Deep transformation of all nested data structures
• 🎯 Granular access to specific configurations

v1.x - Frontend-focused releases

• React Icons integration
• Industry-specific configurations
• Carbon intensity calculations

License

MIT License - see LICENSE file for details.