@bernierllc/email-campaign-management 1.0.1

package/.eslintrc.cjs

@@ -0,0 +1,45 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+    ecmaFeatures: {
+      jsx: true
+    }
+  },
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:react/recommended',
+    'plugin:react-hooks/recommended'
+  ],
+  plugins: ['@typescript-eslint', 'react', 'react-hooks'],
+  env: {
+    node: true,
+    es6: true,
+    browser: true
+  },
+  settings: {
+    react: {
+      version: 'detect'
+    }
+  },
+  rules: {
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/no-explicit-any': 'warn',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    'react/react-in-jsx-scope': 'off',
+    'react/prop-types': 'off',
+    'jsx-a11y/control-has-associated-label': 'off',
+    'jsx-a11y/click-events-have-key-events': 'off',
+    'jsx-a11y/no-noninteractive-element-interactions': 'off'
+  }
+};

package/README.md

@@ -0,0 +1,316 @@
+# @bernierllc/email-campaign-management
+
+Marketing email campaign management UI with visual workflow builder, A/B testing, and real-time analytics.
+
+## Installation
+
+```bash
+npm install @bernierllc/email-campaign-management
+```
+
+## Peer Dependencies
+
+This package requires React 18+ as a peer dependency:
+
+```bash
+npm install react react-dom
+```
+
+## Usage
+
+### Basic Campaign Dashboard
+
+```tsx
+import { CampaignDashboard } from '@bernierllc/email-campaign-management';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <CampaignDashboard campaignId="campaign-123" />
+    </QueryClientProvider>
+  );
+}
+```
+
+### Campaign Builder
+
+```tsx
+import { CampaignBuilder } from '@bernierllc/email-campaign-management';
+
+function CreateCampaign() {
+  const handleSave = (campaign) => {
+    console.log('Campaign saved:', campaign);
+    // Save to your backend
+  };
+
+  return (
+    <CampaignBuilder
+      onSave={handleSave}
+      onPublish={(campaign) => console.log('Publishing:', campaign)}
+    />
+  );
+}
+```
+
+### Campaign List
+
+```tsx
+import { CampaignList } from '@bernierllc/email-campaign-management';
+
+function MyCampaigns() {
+  return (
+    <CampaignList
+      onSelectCampaign={(campaign) => {
+        console.log('Selected:', campaign);
+      }}
+    />
+  );
+}
+```
+
+### Using Campaign Store (Zustand)
+
+```tsx
+import { useCampaignStore } from '@bernierllc/email-campaign-management';
+
+function CampaignManager() {
+  const {
+    campaigns,
+    loading,
+    fetchCampaigns,
+    createCampaign,
+    updateCampaign
+  } = useCampaignStore();
+
+  useEffect(() => {
+    fetchCampaigns();
+  }, []);
+
+  const handleCreate = async () => {
+    await createCampaign({
+      name: 'New Campaign',
+      type: 'drip',
+      status: 'draft',
+      workflow: { id: 'w1', nodes: [], edges: [] },
+      audience: { type: 'all' },
+      schedule: { type: 'immediate' }
+    });
+  };
+
+  return (
+    <div>
+      {campaigns.map(campaign => (
+        <div key={campaign.id}>{campaign.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Workflow Validation
+
+```tsx
+import { useWorkflowValidation } from '@bernierllc/email-campaign-management';
+import type { CampaignWorkflow } from '@bernierllc/email-campaign-management';
+
+function WorkflowEditor({ workflow }: { workflow: CampaignWorkflow }) {
+  const validation = useWorkflowValidation(workflow);
+
+  return (
+    <div>
+      {!validation.valid && (
+        <div className="errors">
+          {validation.errors.map((error, i) => (
+            <p key={i}>{error}</p>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### Components
+
+#### `CampaignDashboard`
+
+Displays campaign analytics and performance metrics.
+
+**Props:**
+- `campaignId: string` - ID of the campaign to display
+
+#### `CampaignBuilder`
+
+Campaign creation and editing interface with workflow builder.
+
+**Props:**
+- `campaign?: Campaign` - Existing campaign to edit (optional)
+- `onSave: (campaign: Partial<Campaign>) => void` - Save handler
+- `onPublish?: (campaign: Campaign) => void` - Publish handler (optional)
+
+#### `CampaignList`
+
+List of all campaigns with filtering and selection.
+
+**Props:**
+- `onSelectCampaign?: (campaign: Campaign) => void` - Selection handler (optional)
+
+### Hooks
+
+#### `useCampaignStore()`
+
+Zustand store for campaign state management.
+
+**Returns:**
+```typescript
+{
+  campaigns: Campaign[];
+  activeCampaign: Campaign | null;
+  loading: boolean;
+  error: string | null;
+  fetchCampaigns: () => Promise<void>;
+  createCampaign: (campaign: Partial<Campaign>) => Promise<Campaign | null>;
+  updateCampaign: (id: string, updates: Partial<Campaign>) => Promise<void>;
+  deleteCampaign: (id: string) => Promise<void>;
+  setActiveCampaign: (campaign: Campaign | null) => void;
+}
+```
+
+#### `useCampaignMetrics(campaignId: string)`
+
+React Query hook for fetching campaign metrics.
+
+**Returns:** Query result with `CampaignMetrics` data
+
+#### `useEmailMetrics(campaignId: string)`
+
+React Query hook for fetching email-level metrics.
+
+**Returns:** Query result with `EmailMetrics[]` data
+
+#### `useWorkflowValidation(workflow: CampaignWorkflow)`
+
+Validates workflow structure.
+
+**Returns:**
+```typescript
+{
+  valid: boolean;
+  errors: string[];
+}
+```
+
+### Types
+
+```typescript
+interface Campaign {
+  id: string;
+  name: string;
+  description?: string;
+  type: 'one-time' | 'drip' | 'welcome' | 'nurture' | 'automated';
+  status: 'draft' | 'scheduled' | 'active' | 'paused' | 'completed';
+  workflow: CampaignWorkflow;
+  audience: AudienceConfig;
+  schedule: ScheduleConfig;
+  abTest?: ABTestConfig;
+  createdAt: Date;
+  updatedAt: Date;
+  createdBy: string;
+}
+
+interface CampaignMetrics {
+  campaignId: string;
+  sent: number;
+  delivered: number;
+  bounced: number;
+  opened: number;
+  clicked: number;
+  converted: number;
+  unsubscribed: number;
+  openRate: number;
+  clickRate: number;
+  conversionRate: number;
+  lastUpdated: Date;
+}
+```
+
+See full type definitions in [src/types](./src/types).
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# API Configuration
+REACT_APP_API_URL=http://localhost:3000/api
+
+# Feature Flags
+REACT_APP_ENABLE_AB_TESTING=true
+REACT_APP_ENABLE_ANALYTICS=true
+
+# Metrics Configuration
+REACT_APP_METRICS_REFRESH_INTERVAL=30000  # 30 seconds
+
+# Workflow Limits
+REACT_APP_MAX_WORKFLOW_NODES=50
+
+# Defaults
+REACT_APP_DEFAULT_TIMEZONE=America/New_York
+```
+
+### Runtime Configuration
+
+```tsx
+import { setConfig } from '@bernierllc/email-campaign-management';
+
+setConfig({
+  apiUrl: 'https://api.example.com',
+  enableABTesting: true,
+  metricsRefreshInterval: 60000
+});
+```
+
+## Features
+
+- **Campaign Builder**: Visual workflow editor for creating email sequences
+- **A/B Testing**: Configure and monitor A/B test campaigns
+- **Real-time Analytics**: Live campaign performance metrics
+- **Audience Segmentation**: Target specific user segments
+- **Campaign Scheduling**: Schedule campaigns or trigger based on events
+- **Campaign Library**: Save, clone, and reuse campaign templates
+
+## Integration Status
+
+- **Logger**: integrated - UI actions, errors, and performance logging
+- **Docs-Suite**: ready - TypeDoc format
+- **NeverHub**: optional - Real-time event updates and campaign coordination
+
+## Dependencies
+
+This package integrates with:
+- `@bernierllc/email-sender` - Email delivery
+- `@bernierllc/email-webhook-events` - Event tracking
+- `@bernierllc/logger` - Logging infrastructure
+
+## Architecture Notes
+
+**CRITICAL DEPENDENCY**: This package requires `@bernierllc/workflow-ui` from the content-suite, which provides the visual workflow builder component. Until that package is published, the workflow canvas will show a placeholder.
+
+## Examples
+
+See the [examples](./examples) directory for complete working examples:
+- Basic campaign creation
+- A/B test setup
+- Analytics dashboard integration
+- Custom workflow builders
+
+## License
+
+Copyright (c) 2025 Bernier LLC. All rights reserved.
+
+This file is licensed to the client under a limited-use license. The client may use and modify this code only within the scope of the project it was delivered for. Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.

package/__tests__/api/campaigns.test.ts

@@ -0,0 +1,217 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import {
+  getCampaigns,
+  getCampaign,
+  createCampaign,
+  updateCampaign,
+  deleteCampaign,
+  getCampaignMetrics,
+  getEmailMetrics
+} from '../../src/api/campaigns';
+import { apiClient } from '../../src/api/client';
+import { CampaignType } from '../../src/types';
+
+jest.mock('../../src/api/client', () => ({
+  apiClient: {
+    get: jest.fn(),
+    post: jest.fn(),
+    put: jest.fn(),
+    delete: jest.fn()
+  }
+}));
+
+const mockApiClient = apiClient as jest.Mocked<typeof apiClient>;
+
+describe('campaigns API', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('getCampaigns', () => {
+    it('should call apiClient.get with correct endpoint', async () => {
+      const mockResponse = { success: true, data: [] };
+      mockApiClient.get.mockResolvedValueOnce(mockResponse);
+
+      const result = await getCampaigns();
+
+      expect(mockApiClient.get).toHaveBeenCalledWith('/campaigns');
+      expect(result).toEqual(mockResponse);
+    });
+
+    it('should return error response on failure', async () => {
+      const mockError = { success: false, error: 'Failed to fetch' };
+      mockApiClient.get.mockResolvedValueOnce(mockError);
+
+      const result = await getCampaigns();
+
+      expect(result).toEqual(mockError);
+    });
+  });
+
+  describe('getCampaign', () => {
+    it('should call apiClient.get with campaign ID', async () => {
+      const mockResponse = { success: true, data: { id: 'campaign-123' } };
+      mockApiClient.get.mockResolvedValueOnce(mockResponse);
+
+      const result = await getCampaign('campaign-123');
+
+      expect(mockApiClient.get).toHaveBeenCalledWith('/campaigns/campaign-123');
+      expect(result).toEqual(mockResponse);
+    });
+
+    it('should handle non-existent campaign', async () => {
+      const mockError = { success: false, error: 'Campaign not found' };
+      mockApiClient.get.mockResolvedValueOnce(mockError);
+
+      const result = await getCampaign('nonexistent');
+
+      expect(result).toEqual(mockError);
+    });
+  });
+
+  describe('createCampaign', () => {
+    it('should call apiClient.post with campaign data', async () => {
+      const campaignData = { name: 'New Campaign', type: 'one-time' as CampaignType };
+      const mockResponse = { success: true, data: { id: 'new-id', ...campaignData } };
+      mockApiClient.post.mockResolvedValueOnce(mockResponse);
+
+      const result = await createCampaign(campaignData);
+
+      expect(mockApiClient.post).toHaveBeenCalledWith('/campaigns', campaignData);
+      expect(result).toEqual(mockResponse);
+    });
+
+    it('should handle validation errors', async () => {
+      const mockError = { success: false, error: 'Name is required' };
+      mockApiClient.post.mockResolvedValueOnce(mockError);
+
+      const result = await createCampaign({});
+
+      expect(result).toEqual(mockError);
+    });
+  });
+
+  describe('updateCampaign', () => {
+    it('should call apiClient.put with campaign ID and updates', async () => {
+      const updates = { name: 'Updated Name' };
+      const mockResponse = { success: true, data: { id: 'campaign-123', name: 'Updated Name' } };
+      mockApiClient.put.mockResolvedValueOnce(mockResponse);
+
+      const result = await updateCampaign('campaign-123', updates);
+
+      expect(mockApiClient.put).toHaveBeenCalledWith('/campaigns/campaign-123', updates);
+      expect(result).toEqual(mockResponse);
+    });
+
+    it('should handle update failures', async () => {
+      const mockError = { success: false, error: 'Update failed' };
+      mockApiClient.put.mockResolvedValueOnce(mockError);
+
+      const result = await updateCampaign('campaign-123', { name: '' });
+
+      expect(result).toEqual(mockError);
+    });
+  });
+
+  describe('deleteCampaign', () => {
+    it('should call apiClient.delete with campaign ID', async () => {
+      const mockResponse = { success: true };
+      mockApiClient.delete.mockResolvedValueOnce(mockResponse);
+
+      const result = await deleteCampaign('campaign-123');
+
+      expect(mockApiClient.delete).toHaveBeenCalledWith('/campaigns/campaign-123');
+      expect(result).toEqual(mockResponse);
+    });
+
+    it('should handle delete failures', async () => {
+      const mockError = { success: false, error: 'Cannot delete active campaign' };
+      mockApiClient.delete.mockResolvedValueOnce(mockError);
+
+      const result = await deleteCampaign('active-campaign');
+
+      expect(result).toEqual(mockError);
+    });
+  });
+
+  describe('getCampaignMetrics', () => {
+    it('should call apiClient.get with metrics endpoint', async () => {
+      const mockMetrics = {
+        success: true,
+        data: {
+          campaignId: 'campaign-123',
+          sent: 1000,
+          delivered: 950,
+          bounced: 50,
+          opened: 400,
+          clicked: 100,
+          converted: 20,
+          unsubscribed: 5,
+          openRate: 40,
+          clickRate: 10,
+          conversionRate: 2,
+          lastUpdated: new Date()
+        }
+      };
+      mockApiClient.get.mockResolvedValueOnce(mockMetrics);
+
+      const result = await getCampaignMetrics('campaign-123');
+
+      expect(mockApiClient.get).toHaveBeenCalledWith('/campaigns/campaign-123/metrics');
+      expect(result).toEqual(mockMetrics);
+    });
+
+    it('should handle metrics not available', async () => {
+      const mockError = { success: false, error: 'Metrics not available yet' };
+      mockApiClient.get.mockResolvedValueOnce(mockError);
+
+      const result = await getCampaignMetrics('new-campaign');
+
+      expect(result).toEqual(mockError);
+    });
+  });
+
+  describe('getEmailMetrics', () => {
+    it('should call apiClient.get with email metrics endpoint', async () => {
+      const mockMetrics = {
+        success: true,
+        data: [
+          { emailId: 'email-1', opened: true, clicked: false },
+          { emailId: 'email-2', opened: true, clicked: true }
+        ]
+      };
+      mockApiClient.get.mockResolvedValueOnce(mockMetrics);
+
+      const result = await getEmailMetrics('campaign-123');
+
+      expect(mockApiClient.get).toHaveBeenCalledWith('/campaigns/campaign-123/emails/metrics');
+      expect(result).toEqual(mockMetrics);
+    });
+
+    it('should handle no emails sent yet', async () => {
+      const mockResponse = { success: true, data: [] };
+      mockApiClient.get.mockResolvedValueOnce(mockResponse);
+
+      const result = await getEmailMetrics('draft-campaign');
+
+      expect(result.success).toBe(true);
+      expect(result.data).toEqual([]);
+    });
+
+    it('should handle fetch failure', async () => {
+      const mockError = { success: false, error: 'Service unavailable' };
+      mockApiClient.get.mockResolvedValueOnce(mockError);
+
+      const result = await getEmailMetrics('campaign-123');
+
+      expect(result).toEqual(mockError);
+    });
+  });
+});