@axova/shared 1.0.0

package/CONFIGURATION_GUIDE.md

@@ -0,0 +1 @@
+ 

package/README.md

@@ -0,0 +1,384 @@
+# 🚀 Axova Shared Package
+
+A comprehensive shared utilities and configuration package for the Axova platform, providing centralized services, configurations, and utilities for all microservices.
+
+## 📋 Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Service Profiles](#service-profiles)
+- [Features](#features)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [API Reference](#api-reference)
+- [Migration Guide](#migration-guide)
+
+## 🌟 Overview
+
+The Axova Shared Package provides:
+
+- **Service-specific configuration profiles** for all microservices
+- **Centralized database management** with connection pooling
+- **Kafka event streaming** with type-safe event handling
+- **Comprehensive audit logging** with sensitive data masking
+- **Service authentication** with JWT and internal service communication
+- **Type-safe schemas** and interfaces for all services
+- **Utility functions** for common operations
+
+## 📦 Installation
+
+```bash
+npm install @axova/shared
+```
+
+## 🎯 Service Profiles
+
+The package includes pre-configured profiles for all Axova services:
+
+| Service | Profile | Default Port | Description |
+|---------|---------|--------------|-------------|
+| **Store Service** | `STORE_SERVICE_PROFILE` | 3001 | Store management, customization, and content |
+| **Compliance Service** | `COMPLIANCE_SERVICE_PROFILE` | 3002 | Compliance monitoring and violation management |
+| **Product Service** | `PRODUCT_SERVICE_PROFILE` | 3003 | Product catalog and variant management |
+| **Admin API Service** | `ADMIN_API_SERVICE_PROFILE` | 3004 | Administrative operations and user management |
+| **Inventory Core Service** | `INVENTORY_SERVICE_PROFILE` | 3005 | Inventory tracking and warehouse management |
+
+## ✨ Features
+
+### 🔧 Configuration Management
+- **Environment-based configuration** with sensible defaults
+- **Service-specific profiles** with customizable features
+- **Validation and error handling** for configurations
+- **Hot-reloading support** for development
+
+### 🎭 Audit Logging
+- **Comprehensive audit trails** for all service operations
+- **Sensitive data masking** for security compliance
+- **Buffered logging** with configurable flush intervals
+- **Risk level assessment** and categorization
+- **Real-time event streaming** via Kafka
+
+### 🚀 Kafka Integration
+- **Type-safe event handling** with strong typing
+- **Automatic producer/consumer management**
+- **Dead letter queue support** for failed messages
+- **Partition-aware processing** for scalability
+
+### 🔐 Security & Authentication
+- **Service-to-service authentication** with JWT
+- **API key management** and validation
+- **Role-based access control** (RBAC)
+- **Request context tracking** for audit trails
+
+## ⚙️ Configuration
+
+### Basic Service Initialization
+
+```typescript
+import { initializeServiceWithProfile } from '@axova/shared';
+
+// Initialize service with its profile
+const serviceConfig = await initializeServiceWithProfile('store-service');
+
+// Access configuration
+console.log('Service Port:', serviceConfig.profile.base.port);
+console.log('Features:', serviceConfig.profile.features);
+
+// Check feature flags
+if (serviceConfig.isFeatureEnabled('auditLogging')) {
+  console.log('Audit logging is enabled');
+}
+
+// Environment checks
+if (serviceConfig.isDevelopment()) {
+  console.log('Running in development mode');
+}
+```
+
+### Environment Variables
+
+Each service supports comprehensive environment-based configuration:
+
+```env
+# Base Configuration
+PORT=3001
+HOST=0.0.0.0
+NODE_ENV=production
+
+# Database Configuration
+DATABASE_URL=postgresql://user:pass@localhost:5432/axova_db
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_USER=axova_user
+POSTGRES_PASSWORD=secure_password
+POSTGRES_DB=axova_store_db
+DB_SSL=true
+DB_POOL_SIZE=15
+
+# Kafka Configuration
+KAFKA_ENABLED=true
+KAFKA_BROKERS=localhost:9092,localhost:9093
+KAFKA_CLIENT_ID=store-service
+KAFKA_GROUP_ID=store-service-group
+KAFKA_SSL=false
+KAFKA_USERNAME=
+KAFKA_PASSWORD=
+
+# Redis Configuration (if applicable)
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=redis_password
+REDIS_DB=0
+REDIS_TTL=3600
+
+# Audit Configuration
+AUDIT_ENABLED=true
+AUDIT_LEVEL=comprehensive
+AUDIT_BUFFER_SIZE=100
+AUDIT_FLUSH_INTERVAL=5000
+AUDIT_MASK_SENSITIVE=true
+
+# Service Authentication
+INTERNAL_SECRET=your_internal_secret
+SERVICE_TOKEN_EXPIRY=1h
+
+# CORS Configuration
+CORS_ORIGINS=http://localhost:3000,https://app.axova.com
+RATE_LIMIT_MAX=100
+RATE_LIMIT_WINDOW=1 minute
+
+# Feature Flags
+ENABLE_REAL_TIME_SYNC=true
+ENABLE_AUDIT_LOGGING=true
+ENABLE_ADVANCED_ANALYTICS=false
+```
+
+## 🚀 Usage
+
+### 1. Service Initialization
+
+```typescript
+import { 
+  initializeServiceWithProfile,
+  createKafkaInstance,
+  createServiceAuthenticator,
+  createAuditLogger,
+  db
+} from '@axova/shared';
+
+async function initializeService() {
+  // Get service configuration
+  const config = await initializeServiceWithProfile('store-service');
+  
+  // Initialize Kafka
+  const kafka = createKafkaInstance(config.kafkaConfig);
+  await kafka.initializeProducer();
+  
+  // Initialize service authentication
+  const serviceAuth = createServiceAuthenticator(config.serviceAuthConfig);
+  
+  // Initialize audit logger
+  const auditLogger = createAuditLogger({
+    serviceName: config.profile.base.serviceName,
+    bufferSize: config.profile.audit.bufferSize,
+    flushInterval: config.profile.audit.flushInterval,
+    sensitiveFieldMasking: config.profile.audit.sensitiveFieldMasking,
+  });
+  
+  return { config, kafka, serviceAuth, auditLogger, db };
+}
+```
+
+### 2. Event Publishing
+
+```typescript
+import { createKafkaInstance, KAFKA_TOPICS } from '@axova/shared';
+
+const kafka = createKafkaInstance(kafkaConfig);
+
+// Publish a store creation event
+await kafka.publishEvent(KAFKA_TOPICS.STORE_CREATED, {
+  id: 'event-id',
+  type: 'store.created',
+  source: 'store-service',
+  version: '1.0',
+  timestamp: new Date().toISOString(),
+  data: {
+    storeId: 'store-123',
+    userId: 'user-456',
+    storeName: 'My Amazing Store',
+    domain: 'amazing-store.myaxova.com'
+  }
+});
+```
+
+### 3. Audit Logging
+
+```typescript
+import { createAuditLogger } from '@axova/shared';
+
+const auditLogger = createAuditLogger({
+  serviceName: 'store-service',
+  bufferSize: 100,
+});
+
+// Log a store creation
+const auditEntry = auditLogger.log({
+  eventType: 'CREATE',
+  eventCategory: 'DATA_ACTION',
+  action: 'store_create',
+  resource: 'store',
+  resourceId: 'store-123',
+  performedBy: 'user-456',
+  performedByType: 'USER',
+  changes: {
+    after: { name: 'My Store', domain: 'mystore.com' }
+  },
+  riskLevel: 'LOW',
+  success: true
+});
+
+// Quick action builders
+auditLogger.quick.dataCreate('store', 'store-123', 'user-456', storeData);
+auditLogger.quick.dataUpdate('store', 'store-123', 'user-456', changes);
+auditLogger.quick.permissionChange('user-789', 'admin-123', roleChanges);
+```
+
+### 4. Database Operations
+
+```typescript
+import { db, stores, storeBlogs } from '@axova/shared';
+import { eq } from 'drizzle-orm';
+
+// Query stores
+const userStores = await db
+  .select()
+  .from(stores)
+  .where(eq(stores.userId, 'user-123'));
+
+// Create a new store blog post
+const newBlog = await db
+  .insert(storeBlogs)
+  .values({
+    storeId: 'store-123',
+    title: 'My First Blog Post',
+    content: 'Hello world!',
+    published: true
+  })
+  .returning();
+```
+
+### 5. Service Authentication
+
+```typescript
+import { createServiceAuthenticator } from '@axova/shared';
+
+const serviceAuth = createServiceAuthenticator({
+  internalSecret: process.env.INTERNAL_SECRET!,
+  tokenExpiry: '1h'
+});
+
+// Generate service token
+const token = serviceAuth.generateServiceToken('store-service', {
+  permissions: ['read:stores', 'write:stores']
+});
+
+// Verify service token
+const decoded = serviceAuth.verifyServiceToken(token);
+console.log('Service:', decoded.service);
+console.log('Permissions:', decoded.permissions);
+```
+
+## 📚 API Reference
+
+### Configuration Profiles
+
+#### `getServiceProfile(serviceName: ServiceName): ServiceProfile`
+Get the configuration profile for a specific service.
+
+#### `initializeServiceWithProfile(serviceName: ServiceName)`
+Initialize a service with its profile and return configured instances.
+
+#### `validateServiceConfig(profile: ServiceProfile)`
+Validate a service configuration and return validation results.
+
+### Event Management
+
+#### `createKafkaInstance(config: AxovaKafkaConfig): AxovaKafka`
+Create a Kafka instance with the provided configuration.
+
+#### `kafka.publishEvent(topic: KafkaTopic, event: AxovaEvent)`
+Publish an event to a specific Kafka topic.
+
+#### `kafka.onEvent<T>(eventType: string, handler: EventHandler<T>)`
+Register an event handler for a specific event type.
+
+### Audit Logging
+
+#### `createAuditLogger(config: AuditLoggerConfig): AuditLogger`
+Create an audit logger instance with the provided configuration.
+
+#### `auditLogger.log(entry: Partial<AuditLogEntry>): string`
+Log an audit entry and return the audit ID.
+
+#### Quick Action Builders
+- `auditLogger.quick.dataCreate(resource, resourceId, userId, data)`
+- `auditLogger.quick.dataUpdate(resource, resourceId, userId, changes)`
+- `auditLogger.quick.dataDelete(resource, resourceId, userId)`
+- `auditLogger.quick.permissionChange(targetUserId, changedBy, changes)`
+
+### Database
+
+#### `db: NodePgDatabase`
+Drizzle ORM database instance with connection pooling.
+
+#### Schema Exports
+All database schemas are available for import:
+- Store schemas: `stores`, `storeBlogs`, `storeContacts`, etc.
+- Product schemas: `products`, `variants`, `collections`, etc.
+- Inventory schemas: `inventory`, `warehouses`, `posLocations`, etc.
+- Compliance schemas: `complianceViolations`, `appeals`, etc.
+
+## 🔄 Migration Guide
+
+### From Previous Version
+
+If you're migrating from a previous version of the shared package:
+
+1. **Update imports:**
+   ```typescript
+   // Old
+   import { getKafkaConfigFromEnv } from '@axova/shared';
+   
+   // New
+   import { initializeServiceWithProfile } from '@axova/shared';
+   const config = await initializeServiceWithProfile('your-service');
+   ```
+
+2. **Use service profiles:**
+   ```typescript
+   // Old - manual configuration
+   const kafkaConfig = getKafkaConfigFromEnv();
+   
+   // New - service profile
+   const { kafkaConfig, profile } = await initializeServiceWithProfile('store-service');
+   ```
+
+3. **Update environment variables:**
+   Follow the new environment variable naming conventions shown above.
+
+## 🤝 Contributing
+
+1. Make changes to the shared package
+2. Run `npm run build` to compile TypeScript
+3. Test changes in dependent services
+4. Update documentation as needed
+5. Submit pull request with detailed description
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+---
+
+**Built with ❤️ by the Axova Team** 

package/SCHEMA_ORGANIZATION.md

@@ -0,0 +1,209 @@
+# Axova Fusion - Database Schema Organization
+
+## Overview
+
+The database schemas have been organized by service domain within the shared package for better maintainability, reusability, and efficiency. Each service has its own dedicated schema folder with comprehensive table definitions, relationships, and performance optimizations.
+
+## Schema Structure
+
+```
+packages/shared/src/schemas/
+├── store/
+│   └── store-schema.ts          # Core store, business details, contacts, social, blogs
+├── compliance/
+│   └── compliance-schema.ts     # Compliance status, violations, actions, policies, appeals
+├── audit/
+│   └── audit-schema.ts          # Immutable audit logs, aggregations, trails
+├── notification/
+│   └── notification-schema.ts   # Templates, notifications, preferences, events
+├── ai-moderation/
+│   └── ai-moderation-schema.ts  # Content scans, moderation rules
+├── admin/
+│   └── admin-schema.ts          # Admin users, actions, review queues
+└── index.ts                     # Centralized exports
+```
+
+## Service Schema Mapping
+
+| Service | Schema Location | Primary Tables | Purpose |
+|---------|-----------------|----------------|---------|
+| **Store Service** | `store/store-schema.ts` | stores, storeBusinessDetails, storeContacts, storeSocialProfiles, storeBlogs | Core store metadata and lifecycle management |
+| **Compliance Service** | `compliance/compliance-schema.ts` | storeCompliance, complianceViolations, complianceActions, storePolicies, appeals | Verification, violations, bans, policies, appeals |
+| **Audit Service** | `audit/audit-schema.ts` | auditLogs, auditLogAggregations, auditTrails | Immutable action logging and forensic trails |
+| **Notification Service** | `notification/notification-schema.ts` | notificationTemplates, notifications, notificationPreferences, notificationEvents | Multi-channel messaging and delivery tracking |
+| **AI Moderation Service** | `ai-moderation/ai-moderation-schema.ts` | contentScans, moderationRules | Content scanning and violation detection |
+| **Admin API Service** | `admin/admin-schema.ts` | adminUsers, adminActions, reviewQueues | Internal admin operations and review workflows |
+
+## Enhanced Features
+
+### 1. Performance Optimizations
+- **Comprehensive Indexing**: Strategic indexes for all common query patterns
+- **Composite Indexes**: Multi-column indexes for complex filtering
+- **Partial Indexes**: Conditional indexes for specific scenarios
+- **Query-Specific Indexes**: Tailored for business logic patterns
+
+### 2. Data Integrity
+- **Foreign Key Constraints**: Proper referential integrity
+- **Unique Constraints**: Prevent data duplication
+- **Check Constraints**: Business rule enforcement
+- **Cascade Rules**: Proper cleanup on deletions
+
+### 3. Scalability Features
+- **Partition-Ready**: Designed for future partitioning
+- **Aggregation Tables**: Pre-computed metrics for performance
+- **Immutable Design**: Append-only patterns for audit tables
+- **Efficient Storage**: Optimized data types and JSONB usage
+
+### 4. Business Intelligence
+- **Rich Metadata**: Comprehensive context tracking
+- **Analytics-Ready**: Built-in metrics and KPIs
+- **Reporting Indexes**: Optimized for business intelligence queries
+- **Time-Series Data**: Proper temporal data handling
+
+## Key Schema Enhancements
+
+### Store Schema Enhancements
+- **Enhanced Business Details**: Legal structures, verification levels, industry classification
+- **Advanced Contact Management**: Business hours, communication preferences, emergency contacts
+- **Social Media Strategy**: Platform analytics, posting schedules, engagement tracking
+- **Content Management**: SEO metadata, localization, engagement metrics
+
+### Compliance Schema Enhancements
+- **Multi-Level Compliance**: Different verification tiers and compliance scores
+- **Advanced Violation Tracking**: Detection methods, confidence scores, impact assessment
+- **Comprehensive Actions**: Approval workflows, effectiveness tracking, reversal support
+- **Policy Management**: Versioning, approval workflows, compliance standards tracking
+- **Appeals System**: Multi-level review, SLA tracking, communication history
+
+### Audit Schema Enhancements
+- **Immutable Design**: Append-only with integrity verification
+- **Rich Context**: Geographic, device, and business context
+- **Performance Metrics**: Duration, size, and efficiency tracking
+- **Risk Assessment**: Security and compliance impact scoring
+- **Aggregation Support**: Pre-computed metrics for performance
+
+### Notification Schema Enhancements
+- **Multi-Channel Templates**: Email, SMS, push, in-app support
+- **Advanced Personalization**: Variable substitution, conditional logic
+- **Delivery Tracking**: Comprehensive status and event tracking
+- **Preference Management**: Granular control over notification preferences
+- **Analytics Integration**: Open, click, and engagement tracking
+
+### AI Moderation Enhancements
+- **Provider Agnostic**: Support for multiple AI moderation services
+- **Custom Rules**: Flexible rule engine for business-specific requirements
+- **Confidence Scoring**: Detailed confidence and category breakdowns
+- **Deduplication**: Content hashing for efficient processing
+- **Cost Tracking**: API usage and cost monitoring
+
+### Admin Schema Enhancements
+- **Role-Based Access**: Granular permission system
+- **Action Tracking**: Comprehensive admin action logging
+- **Review Workflows**: Queue management with SLA tracking
+- **Approval Processes**: Multi-level approval workflows
+- **Performance Monitoring**: Efficiency and workload tracking
+
+## Database Configuration
+
+Each service has its own Drizzle configuration pointing to the appropriate schema:
+
+```typescript
+// apps/{service}/drizzle.config.ts
+export default defineConfig({
+  schema: '../../packages/shared/src/schemas/{service}/{service}-schema.ts',
+  out: './drizzle',
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+});
+```
+
+## Usage Examples
+
+### Importing Schemas
+```typescript
+// Import all schemas
+import * from '@axova/shared/schemas';
+
+// Import specific service schemas
+import { stores, storeBusinessDetails } from '@axova/shared/schemas/store';
+import { storeCompliance, complianceViolations } from '@axova/shared/schemas/compliance';
+import { auditLogs } from '@axova/shared/schemas/audit';
+```
+
+### Service Integration
+```typescript
+// In compliance service
+import { db, storeCompliance, complianceViolations } from '@axova/shared';
+
+const createComplianceRecord = async (storeId: string) => {
+  return await db.insert(storeCompliance).values({
+    storeId,
+    isVerified: false,
+    complianceScore: 100,
+    riskLevel: 'LOW'
+  });
+};
+```
+
+## Migration Strategy
+
+1. **Backwards Compatibility**: Legacy exports maintained in `models/store-schema.ts`
+2. **Gradual Migration**: Services can migrate to new schemas incrementally
+3. **Consistent Interface**: All schemas follow the same patterns and conventions
+4. **Shared Utilities**: Common patterns and utilities available across all schemas
+
+## Performance Considerations
+
+### Indexing Strategy
+- **Primary Access Patterns**: Indexed based on service-specific query patterns
+- **Cross-Service Queries**: Foreign key indexes for service-to-service lookups
+- **Analytics Queries**: Specialized indexes for reporting and business intelligence
+- **Time-Based Queries**: Temporal indexes for audit trails and activity tracking
+
+### Query Optimization
+- **Selective Columns**: Avoid SELECT * patterns
+- **Proper Joins**: Efficient relationship traversal
+- **Pagination Support**: Cursor-based pagination for large datasets
+- **Aggregation Tables**: Pre-computed summaries for heavy analytics
+
+### Storage Optimization
+- **JSONB Usage**: Structured but flexible data storage
+- **Text vs VARCHAR**: Appropriate type selection for content
+- **Timestamp Precision**: Timezone-aware timestamps throughout
+- **Null Handling**: Proper null vs default value strategies
+
+## Monitoring and Maintenance
+
+### Performance Monitoring
+- Query execution time tracking
+- Index usage statistics
+- Connection pool monitoring
+- Slow query identification
+
+### Data Quality
+- Constraint violation monitoring
+- Data consistency checks
+- Reference integrity validation
+- Business rule compliance
+
+### Capacity Planning
+- Table growth tracking
+- Storage utilization monitoring
+- Index size optimization
+- Partition planning for large tables
+
+## Future Enhancements
+
+### Planned Improvements
+- **Partitioning Strategy**: For large, time-series tables
+- **Read Replicas**: For analytical workloads
+- **Materialized Views**: For complex reporting queries
+- **Archive Strategy**: For historical data management
+
+### Scalability Roadmap
+- **Horizontal Partitioning**: By tenant/store for massive scale
+- **Service-Specific Databases**: When individual services require different storage strategies
+- **Caching Strategy**: Redis integration for hot data
+- **Event Sourcing**: For critical business events 

package/dist/configs/index.d.ts

@@ -0,0 +1,85 @@
+export interface BaseServiceConfig {
+    serviceName: string;
+    port: number;
+    host: string;
+    environment: "development" | "staging" | "production";
+    cors: {
+        origins: string[];
+        credentials: boolean;
+    };
+    rateLimiting: {
+        max: number;
+        timeWindow: string;
+    };
+}
+export interface DatabaseConfig {
+    url: string;
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+    ssl: boolean;
+    poolSize: number;
+}
+export interface KafkaServiceConfig {
+    enabled: boolean;
+    clientId: string;
+    groupId: string;
+    topics: string[];
+    autoCommit: boolean;
+}
+export interface RedisConfig {
+    host: string;
+    port: number;
+    password?: string;
+    db: number;
+    ttl: number;
+}
+export interface AuditConfig {
+    enabled: boolean;
+    level: "minimal" | "standard" | "comprehensive";
+    bufferSize: number;
+    flushInterval: number;
+    sensitiveFieldMasking: boolean;
+}
+export interface ServiceProfile {
+    base: BaseServiceConfig;
+    database: DatabaseConfig;
+    kafka: KafkaServiceConfig;
+    redis?: RedisConfig;
+    audit: AuditConfig;
+    features: Record<string, boolean>;
+    customConfig?: Record<string, unknown>;
+}
+export declare const STORE_SERVICE_PROFILE: ServiceProfile;
+export declare const COMPLIANCE_SERVICE_PROFILE: ServiceProfile;
+export declare const PRODUCT_SERVICE_PROFILE: ServiceProfile;
+export declare const INVENTORY_SERVICE_PROFILE: ServiceProfile;
+export declare const ADMIN_API_SERVICE_PROFILE: ServiceProfile;
+export declare const OXA_SERVICE_PROFILE: ServiceProfile;
+export type ServiceName = "store-service" | "compliance-service" | "product-service" | "inventory-core-service" | "admin-api-service" | "oxa-service";
+export declare const SERVICE_PROFILES: Record<ServiceName, ServiceProfile>;
+/**
+ * Get configuration profile for a specific service
+ */
+export declare function getServiceProfile(serviceName: ServiceName): ServiceProfile;
+/**
+ * Initialize service with its profile and return configured instances
+ */
+export declare function initializeServiceWithProfile(serviceName: ServiceName): Promise<{
+    profile: ServiceProfile;
+    kafkaConfig: import("../events/kafka").AxovaKafkaConfig;
+    serviceAuthConfig: import("../middleware/serviceAuth").ServiceAuthConfig;
+    isFeatureEnabled: (feature: string) => boolean;
+    getCustomConfig: (key: string) => unknown;
+    isDevelopment: () => boolean;
+    isProduction: () => boolean;
+}>;
+/**
+ * Validate service configuration
+ */
+export declare function validateServiceConfig(profile: ServiceProfile): {
+    valid: boolean;
+    errors: string[];
+};