@zerocarbon/erp-config-sdk 1.0.14 → 1.0.16

package/README.md

@@ -1,6 +1,6 @@
 # Zero Carbon ERP Config SDK
 
-A comprehensive TypeScript SDK providing emission configurations and calculation utilities for carbon footprint tracking across 24+ industries.
+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
 
@@ -10,13 +10,60 @@ npm install erp-config-sdk
 
 ## Features
 
-- 24+ Industry-specific emission configurations
-- Type-safe emission data structures  
-- Carbon intensity calculations
-- Emission source generators
-- Industry mapping utilities
-- React Icons integration
-- UI feature configurations
+- **🏭 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:
+
+```typescript
+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:
+
+```typescript
+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
 
@@ -45,7 +92,138 @@ npm install erp-config-sdk
 - Textile Manufacturing
 - Utilities & Energy
 
-## Basic Usage
+## Backend Functions
+
+### Core Backend Functions
+
+#### `getAllConfig(): AllConfigurations`
+Returns all industry and user configurations in backend-compatible format.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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:
 
 ```typescript
 import { 
@@ -54,9 +232,9 @@ import {
   IndustryConfig,
   calculateEmissionFootprint,
   getIndustryFromCompanyName 
-} from '@zerocarbon/erp-config-sdk';
+} from 'erp-config-sdk';
 
-// Get configuration for a specific industry
+// Get configuration for a specific industry (includes React icons)
 const automobileConfig = getIndustryConfig('automobile');
 
 // Get industry mapping from company name
@@ -71,60 +249,207 @@ const emissionData: EmissionData = {
 };
 ```
 
-## Industry Configuration Structure
+### React Components with Icons
+
+```typescript
+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>
+  );
+}
+```
 
-Each industry provides:
+## 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 2 Emissions**: Indirect emissions from purchased energy  
 - **Scope 3 Emissions**: Indirect emissions from value chain activities
-- **UI Features**: Icon mappings and display configurations
-- **API Endpoints**: Integration points for emission calculations
+- **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
 
-## Advanced Usage
-
-### Custom Emission Calculations
+### Data Structure Overview
 
 ```typescript
-import { 
-  formatEmissions,
-  generateEmissionSources,
-  BUSINESS_TRAVEL,
-  PURCHASED_ELECTRICITY_PRODUCTS 
-} from '@zerocarbon/erp-config-sdk';
+// 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
 
-// Format emission values
-const formatted = formatEmissions(1234.567); // "1,234.57"
+### Backend API Example
 
-// Generate emission sources for a category
-const sources = generateEmissionSources('SCOPE_1');
+```typescript
+// 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
+  });
+});
 ```
 
-### React Integration
+### Database Integration Example
 
 ```typescript
-import { FaIndustry } from 'react-icons/fa';
-import { getUIFeatures } from '@zerocarbon/erp-config-sdk';
+// 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
+        });
+      });
+    });
+  }
+}
+```
 
-const features = getUIFeatures('manufacturing');
-const Icon = features.icon || FaIndustry;
+### Carbon Footprint Calculation Example
 
-function IndustryCard() {
-  return (
-    <div>
-      <Icon size={24} />
-      <span>{features.title}</span>
-    </div>
-  );
+```typescript
+// 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:
+The SDK exports comprehensive TypeScript types for both backend and frontend usage:
+
+### Backend Types (No React Dependencies)
+
+```typescript
+// 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)
 
 ```typescript
-// Core emission types
+// Import frontend types (includes React components)
 import type {
   EmissionData,
   EmissionSource,
@@ -132,66 +457,195 @@ import type {
   IndustryConfig,
   CarbonIntensityData,
   BillsAnalyzed,
-  Calculations
-} from '@zerocarbon/erp-config-sdk';
+  Calculations,
+  Scope,
+  Scope3Item
+} from 'erp-config-sdk';
 ```
 
-## API
+### Universal Types
+
+```typescript
+// 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 |
 
-### Industry Configuration Functions
+### Frontend Functions
 
-- `getIndustryConfig(industry: string): IndustryConfig` - Get complete industry configuration
-- `getIndustryFromCompanyName(name: string): string` - Map company name to industry
+| 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 |
 
-### Emission Utilities
+### Utility Functions
 
-- `formatEmissions(value: number): string` - Format emission values for display
-- `generateEmissionSources(scope: string): EmissionSource[]` - Generate emission sources
-- `calculateEmissionFootprint(data: EmissionData): number` - Calculate total footprint
+| 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 |
 
-### Helper Functions
+## Advanced Usage
+
+### Custom Emission Calculations
 
-- `getUIFeatures(industry: string)` - Get UI configurations for industry
-- `getBillManager()` - Access bill management utilities
-- `getCarbonIntensityData()` - Access carbon intensity calculations
+```typescript
+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
 
-- **React Icons**: For industry-specific icons
+### Production Dependencies
 - **TypeScript**: Full type safety and IntelliSense support
+- **Emission Factor Data**: Comprehensive emission factors for 24+ industries
 
-## Peer Dependencies
-
+### Peer Dependencies (Frontend Only)
 ```json
 {
   "react-icons": "^4.0.0"
 }
 ```
 
-## Development
+**Note**: React Icons are only required for frontend usage. Backend applications do not need React dependencies.
 
-```bash
-# Install dependencies
-npm install
+## 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
 
-# Build the SDK
-npm run build
+### Upgrading from Frontend-Only Usage
 
-# Run linting
-npm run lint
+If you were previously using the SDK only in frontend applications:
 
-# Run type checking
-npm run type-check
+```typescript
+// 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
 ```
 
-## License
+### New Backend-First Applications
 
-MIT
+For new backend applications, use the backend functions from the start:
+
+```typescript
+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 and maintain backward compatibility.
+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 or issues, please contact the Zero Carbon ERP team.
+For questions, issues, or feature requests:
+
+- 📧 Email: support@zerocarbon-erp.com
+- 🐛 Issues: [GitHub Issues](https://github.com/your-org/erp-config-sdk/issues)
+- 📚 Documentation: [Full API Documentation](https://docs.zerocarbon-erp.com)
+- 💬 Community: [Discord Support Server](https://discord.gg/zerocarbon)
+
+## 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](LICENSE) file for details.