adserver-dashboard 1.0.0

package/PCM/docs/TEST_CASES.md

@@ -0,0 +1,422 @@
+# DOOH AdServer API - Test Cases Documentation
+
+## Overview
+
+This document provides a comprehensive list of all E2E test cases covering the DOOH AdServer API. All tests use source `influence` and cover positive (happy path) and negative (error handling) scenarios.
+
+**Total Test Cases: 143**
+- Positive Scenarios: 61
+- Negative Scenarios: 21
+- Workflow/Integration Tests: 39
+- Dual ID Resolution Tests: 22
+
+---
+
+## Test Categories Summary
+
+| # | Category | Test Count | Description |
+|---|----------|------------|-------------|
+| 1 | PROGRAMMATIC - GUARANTEED | 18 | Full workflow: create, read, update, creatives |
+| 2 | PROGRAMMATIC - PREFERRED_DEAL | 2 | CPS cost type, auction type verification |
+| 3 | PROGRAMMATIC - PRIVATE_AUCTION | 7 | First price auction, VIDEO creatives |
+| 4 | PROGRAMMATIC - EVERGREEN_PMP | 6 | Second price auction, AUDIO creatives |
+| 5 | DIRECT Mode | 13 | Targeting, planning, aggregation |
+| 6 | Deal List Filtering | 8 | Search, filter, pagination |
+| 7 | Validation Rules | 8 | Schema validation, constraints |
+| 8 | Inventory Assignment | 3 | Inventory creation with line items |
+| 9 | Schedule Array Tests | 3 | Schedule rules validation |
+| 10 | Auto-Calculation | 8 | Metrics aggregation |
+| 11 | DIRECT Targeting Edge Cases | 14 | Demographics, geofencing, deliveryTargeting |
+| 12 | PROGRAMMATIC Targeting | 7 | Targeting acceptance, deliveryTargeting rejection |
+| 13 | Edge Cases - Validation | 11 | Error handling, constraints |
+| 14 | Cleanup | 3 | Archive workflow |
+
+---
+
+## 1. PROGRAMMATIC Mode - GUARANTEED Deal (18 tests)
+
+### Positive Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should create a GUARANTEED deal | Creates deal with all required fields, buyers, seller |
+| should get deal by dealId with full details | Retrieves deal using generated dealId |
+| should get deal by UUID | Retrieves deal using internal UUID |
+| should create a DISPLAY line item | Creates line item with resolutions, pacing, schedule |
+| should get line item by id with full details | Retrieves line item with all nested data |
+| should update deal status to APPROVED | Status transition for creative assignment |
+| should get line items by dealId | Lists all line items for a deal |
+| should get line item by externalId | Retrieves using external identifier |
+| should update line item | Updates bidFloor, deliveryGoal |
+| should assign DISPLAY creative with matching resolution | Creative assignment workflow |
+| should approve pending creative | Creative approval workflow |
+| should get creatives by dealId | Lists creatives for deal |
+| should get creatives by lineItemId | Lists creatives for line item |
+| should get creative by creativeId | Retrieves by creativeId |
+| should get creative by UUID | Retrieves by internal UUID |
+
+### Negative Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should reject creative with mismatched resolution | Resolution validation |
+| should reject creative with mismatched type | Type validation (DISPLAY vs VIDEO) |
+| should not allow rejecting approved creative | Status transition constraint |
+
+---
+
+## 2. PROGRAMMATIC Mode - PREFERRED_DEAL (2 tests)
+
+| Test Case | Type | Description |
+|-----------|------|-------------|
+| should create a PREFERRED_DEAL with CPS cost type | Positive | CPS allowed for non-guaranteed |
+| should verify PREFERRED_DEAL has auctionType 3 | Positive | Fixed price auction |
+
+---
+
+## 3. PROGRAMMATIC Mode - PRIVATE_AUCTION (7 tests)
+
+### Positive Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should create a PRIVATE_AUCTION with first price auction | auctionType 1 |
+| should verify PRIVATE_AUCTION has auctionType 1 | Auction type validation |
+| should create VIDEO line item | VIDEO creativeType with duration |
+| should update PRIVATE_AUCTION deal status to APPROVED | Status workflow |
+| should assign VIDEO creative | VIDEO creative assignment |
+| should reject VIDEO creative | Creative rejection workflow |
+
+### Negative Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should not allow approving rejected creative | Status transition constraint |
+
+---
+
+## 4. PROGRAMMATIC Mode - EVERGREEN_PMP (6 tests)
+
+| Test Case | Type | Description |
+|-----------|------|-------------|
+| should create an EVERGREEN_PMP with second price auction | Positive | auctionType 2 |
+| should verify EVERGREEN_PMP has auctionType 2 | Positive | Auction type validation |
+| should update EVERGREEN_PMP deal status to APPROVED | Positive | Status workflow |
+| should create AUDIO line item | Positive | AUDIO creativeType |
+| should assign AUDIO creative (no resolution required) | Positive | AUDIO creative assignment |
+| should approve AUDIO creative | Positive | Approval workflow |
+
+---
+
+## 5. DIRECT Mode (13 tests)
+
+### Positive Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should create a DIRECT deal | Full DIRECT deal with brand, clientType |
+| should verify DIRECT deal has correct mode and type | Mode/type validation |
+| should create DIRECT line item with comprehensive targeting | Demographics, venueTypes, geofencing |
+| should return comprehensive targeting in DIRECT line item response | Response structure |
+| should update DIRECT line item targeting | Targeting update |
+| should assign creative to DIRECT line item | Creative assignment |
+| should create DIRECT line item with planning data | Capacity, allocation, estimates, pricing |
+| should return planning data in DIRECT line item response | Planning response |
+| should update DIRECT line item planning data | Planning update |
+| should verify updated planning data persisted | Persistence check |
+| should aggregate planning from line items to deal level | Deal-level aggregation |
+| should create second DIRECT line item for aggregation test | Multi-item setup |
+| should correctly aggregate planning from multiple line items | Multiple item aggregation |
+
+---
+
+## 6. Deal List Filtering (8 tests)
+
+| Test Case | Type | Description |
+|-----------|------|-------------|
+| should get all deals | Positive | List endpoint |
+| should filter deals by mode=PROGRAMMATIC | Positive | Mode filter |
+| should filter deals by mode=DIRECT | Positive | Mode filter |
+| should filter deals by dealType | Positive | Type filter |
+| should filter deals by status | Positive | Status filter |
+| should search deals by name | Positive | Search functionality |
+| should filter deals by date range | Positive | Date filtering |
+| should paginate deals | Positive | Pagination (limit, offset) |
+
+---
+
+## 7. Validation Rules (8 tests)
+
+### Negative Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should reject GUARANTEED deal with CPS cost type | CPS not allowed for GUARANTEED |
+| should reject PROGRAMMATIC deal with dealType=DIRECT | Invalid dealType |
+| should reject DIRECT deal with dealType=GUARANTEED | Invalid dealType |
+| should reject line item with invalid creativeType | Enum validation |
+| should reject line item with missing required fields | Required field validation |
+| should reject line item with invalid resolution format | Resolution pattern |
+| should reject deal with missing required fields | Required field validation |
+| should reject invalid mode value | Enum validation |
+
+---
+
+## 8. Inventory Assignment (4 tests)
+
+| Test Case | Type | Description |
+|-----------|------|-------------|
+| should create line item with inventories array | Positive | Inventory creation |
+| should return inventories in line item response | Positive | Response includes inventories |
+| should allow same inventory to be assigned to multiple line items | Positive | Shared inventory across line items |
+| should update line item inventories | Positive | Inventory update |
+
+---
+
+## 9. Schedule Array Tests (3 tests)
+
+| Test Case | Type | Description |
+|-----------|------|-------------|
+| should accept schedule with DEFAULT rule | Positive | Default schedule |
+| should accept schedule with all rule types | Positive | DEFAULT, WEEKDAY, WEEKEND, CUSTOM |
+| should reject schedule with invalid type | Negative | Type validation |
+
+---
+
+## 10. Auto-Calculation Edge Tests (8 tests)
+
+| Test Case | Type | Description |
+|-----------|------|-------------|
+| should create a deal for auto-calculation testing | Positive | Setup |
+| should auto-calculate deal dates from line items | Positive | startDate/endDate aggregation |
+| should auto-calculate lineItemsCount from active line items | Positive | Count aggregation |
+| should auto-calculate timezoneId from first line item | Positive | Timezone inheritance |
+| should auto-calculate unique publishers count | Positive | Publishers aggregation |
+| should auto-calculate programmatic metrics from line items | Positive | impressions, netCost aggregation |
+| should update deal auto-calculated fields when line item archived | Positive | Recalculation on archive |
+| should archive auto-calculation test deal | Positive | Cleanup |
+
+---
+
+## 11. DIRECT Targeting Edge Cases (14 tests)
+
+### Positive Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should create DIRECT deal for targeting edge tests | Setup |
+| should accept DIRECT line item with empty targeting object | Empty object allowed |
+| should accept DIRECT line item with partial demographics | Partial data allowed |
+| should accept DIRECT line item with venueTypes using dot-notation | Hierarchical venue types |
+| should accept DIRECT line item with geofencing polygon (exclusion zone) | Polygon with included=false |
+| should accept DIRECT line item with weather-based deliveryTargeting | Weather signals |
+| should accept DIRECT line item with metadata version tracking | Metadata fields |
+| should accept partial update of targeting only | Partial PUT |
+| should archive targeting edge test deal | Cleanup |
+
+### Negative Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should reject DIRECT line item with invalid gender value | Gender enum validation |
+| should reject DIRECT line item with invalid geometry type | Geometry type validation |
+| should reject DIRECT line item with invalid temperature unit | Unit enum validation |
+| should reject DIRECT line item with invalid inventoryFilteredBy value | Array value validation |
+| should reject DIRECT line item with invalid venueTaxonomyFormat | Format validation |
+
+---
+
+## 12. PROGRAMMATIC Mode Targeting (7 tests)
+
+### Positive Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should create PROGRAMMATIC deal for rejection tests | Setup |
+| should create PROGRAMMATIC line item WITHOUT targeting (baseline) | Baseline creation |
+| should accept targeting for PROGRAMMATIC line item | Demographics, venueTypes, geofencing |
+| should accept PROGRAMMATIC line item with geofencing | Polygon + locations |
+| should update PROGRAMMATIC line item targeting and verify persistence | Update + GET verification |
+| should archive programmatic rejection test deal | Cleanup |
+
+### Negative Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should reject deliveryTargeting for PROGRAMMATIC line item | DIRECT-only validation |
+| should reject PROGRAMMATIC line item update with deliveryTargeting | Update rejection with error payload |
+
+---
+
+## 13. Edge Cases - Validation & Error Handling (11 tests)
+
+### Positive Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should create DIRECT deal for inventory planning tests | Setup |
+| should create DIRECT line item with inventory-level planning | Inventory planning |
+| should retrieve line items and verify inventories | Inventory retrieval |
+| should handle empty schedule array | Empty array allowed |
+| should accept schedule with all rule types | Multiple schedule rules |
+| should archive edge test deal | Cleanup |
+
+### Negative Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should reject DIRECT deal missing required fields | Required validation |
+| should reject invalid dealType for PROGRAMMATIC mode | Type constraint |
+| should reject line item with invalid schedule type | Schedule validation |
+| should reject duplicate externalId with detailed error message | Unique constraint with details |
+| should handle GET non-existent deal | 404 response |
+| should handle GET non-existent line item | 404 response |
+
+---
+
+## 14. Dual ID Resolution - UUID or dealId (22 tests)
+
+All endpoints now accept either UUID (`id` field) or dealId (`deal_id` field) for deal lookups.
+
+| Test Case | Type | Description |
+|-----------|------|-------------|
+| should create a deal for dual ID testing | Setup | Creates test deal |
+| should GET deal by dealId | Positive | Traditional lookup |
+| should GET deal by UUID (id field) | Positive | UUID lookup |
+| should PUT deal by UUID | Positive | Update via UUID |
+| should create line item for dual ID testing | Setup | Creates test line item |
+| should GET line items using deal UUID | Positive | List via UUID |
+| should GET line item using deal UUID and line item id | Positive | Nested UUID lookup |
+| should GET line item using deal UUID and externalId | Positive | Mixed identifier lookup |
+| should PUT line item using deal UUID | Positive | Update via UUID |
+| should POST creative using deal UUID | Positive | Create via UUID |
+| should GET creatives using deal UUID | Positive | List creatives via UUID |
+| should GET creatives using deal UUID and line item externalId | Positive | Nested list via UUID |
+| should GET single creative using deal UUID | Positive | Single creative via UUID |
+| should GET creative by creative UUID using deal UUID | Positive | Dual UUID lookup |
+| should POST approve creative using deal UUID | Positive | Approve via UUID |
+| should create another creative for reject test | Setup | Creates test creative |
+| should POST reject creative using deal UUID | Positive | Reject via UUID |
+| should create creative for delete test | Setup | Creates test creative |
+| should DELETE creative using deal UUID | Positive | Delete via UUID |
+| should DELETE creative by creative UUID using deal UUID | Positive | Dual UUID delete |
+| should archive deal using UUID | Positive | Archive via UUID |
+| should verify archived deal by UUID | Positive | Verify status via UUID |
+
+---
+
+## 15. Cleanup - Archive Deals (2 tests)
+
+| Test Case | Type | Description |
+|-----------|------|-------------|
+| should archive (soft delete) deals | Positive | Soft delete workflow |
+| should verify archived deals have ARCHIVED status | Positive | Status verification |
+
+---
+
+## Test Execution
+
+### Run All Tests
+```bash
+npm test
+```
+
+### Run Tests with Verbose Output
+```bash
+node --test --test-reporter spec tests/e2e-comprehensive.test.js
+```
+
+### Expected Results
+- All 149 tests should pass
+- No null values in critical fields
+- All workflows covered (create, read, update, archive, approve, reject)
+
+---
+
+## API Workflows Covered
+
+| Workflow | Endpoints Tested |
+|----------|------------------|
+| **Create** | POST /deals, POST /line-items, POST /creatives |
+| **Read** | GET /deals, GET /deals/:id, GET /line-items, GET /creatives |
+| **Update** | PUT /deals/:id, PUT /line-items/:id |
+| **List** | GET /deals (with filters, search, pagination) |
+| **Archive** | DELETE /deals/:id (soft delete) |
+| **Assign** | POST /creatives (assignment to line items) |
+| **Approve** | POST /creatives/:id with decision: APPROVED |
+| **Reject** | POST /creatives/:id with decision: REJECTED |
+| **Schedule** | Line item schedule array management |
+| **Planning** | DIRECT mode planning data (capacity, allocation, estimates, pricing) |
+| **Targeting** | Both modes: demographics, venueTypes, geofencing |
+| **DeliveryTargeting** | DIRECT only: weather signals |
+
+---
+
+## Coverage Summary
+
+| Feature | PROGRAMMATIC | DIRECT |
+|---------|--------------|--------|
+| Deal CRUD | ✅ | ✅ |
+| Line Item CRUD | ✅ | ✅ |
+| Creative CRUD | ✅ | ✅ |
+| Inventory Assignment | ✅ | ✅ |
+| Targeting | ✅ | ✅ |
+| DeliveryTargeting | ❌ (rejected) | ✅ |
+| Planning | ❌ | ✅ |
+| Schedule Management | ✅ | ✅ |
+| Pacing | ✅ | ✅ |
+| Status Workflow | ✅ | ✅ |
+| Creative Approval | ✅ | ✅ |
+| Creative Rejection | ✅ | ✅ |
+| Auto-Calculation | ✅ | ✅ |
+| Aggregation | ✅ | ✅ |
+| Extended Fields (priority, customFees, frequencyCap, trafficAllocation, inventorySource) | ✅ | ✅ |
+| Base Price Fields (bidFloorBase, pricing.cpmBase, pricing.estimatedCostBase) | ✅ | ✅ |
+
+---
+
+## 15. Line Item Extended Fields (10 tests)
+
+### Positive Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should create line item with priority field | Priority value 1-10 for scheduling |
+| should create line item with customFees array | Array of fee objects (name, amount, type, invoiced) |
+| should create line item with frequencyCap | Object with period (hour/day/week/month/lifetime) and target |
+| should create line item with trafficAllocation | Percentage field 0-100 for traffic distribution |
+| should create line item with inventorySource | String field for inventory origin tracking |
+| should update line item extended fields | All extended fields can be updated |
+| should return extended fields in GET response | Fields appear in line item detail response |
+
+### Negative Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should reject priority outside valid range (1-10) | Validation: priority must be 1-10 |
+| should reject percentage fee amount > 100 | Validation: percentage fees max 100% |
+| should reject trafficAllocation outside range (0-100) | Validation: allocation percentage bounds |
+
+---
+
+## 16. Base Price Fields (6 tests)
+
+### Positive Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should create PROGRAMMATIC line item with bidFloorBase | Base bid floor before custom fees |
+| should create DIRECT line item with pricing.cpmBase | Base CPM before custom fees |
+| should create DIRECT line item with pricing.estimatedCostBase | Base estimated cost before custom fees |
+| should update base price fields | All base price fields can be updated |
+| should return bidFloorBase in programmatic object | Field appears in GET response under programmatic |
+| should return pricing base fields in direct object | cpmBase and estimatedCostBase appear in GET response under direct.pricing |
+
+---
+
+## 17. DIRECT_PUBLISHER_SPLIT Import - Account & Advertiser (10 tests)
+
+### Positive Scenarios
+| Test Case | Description |
+|-----------|-------------|
+| should capture full account and advertiser from import payload | All account (userId, companyName, companyId, externalId) and advertiser (id, seatId, name) fields are persisted on the deal |
+| should persist all 4 account fields and return them via GET | userId, companyName, companyId, externalId all retrievable on deal GET |
+| should persist all 3 advertiser fields and return them via GET | id, seatId, name all retrievable on deal GET |
+| should import with only account (no advertiser) | Deal created successfully, account captured, advertiser defaults to {} |
+| should import with only advertiser (no account) | Deal created successfully, advertiser captured, account is null |
+| should import without account or advertiser | Deal created successfully, both fields absent/default |
+| should capture account/advertiser with multi-publisher inventories | Account and advertiser persisted correctly alongside multiple line items from different publishers |
+| should accept partial account (userId and companyName only) | Missing companyId/externalId still allows import |
+| should accept partial advertiser (id and name, no seatId) | Missing seatId still allows import |
+| should return account/advertiser in convert endpoint preview | Convert endpoint includes both fields in converted deal object |
+
+---
+
+*Generated: February 2026*
+*Source: influence*
+*API Version: v1.6.0*

package/PCM/index.js

@@ -0,0 +1,106 @@
+import express from 'express';
+import cors from 'cors';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import swaggerUi from 'swagger-ui-express';
+import swaggerJsdoc from 'swagger-jsdoc';
+import sequelize, { testConnection } from './src/config/db.js';
+import { requestLogger } from './src/middleware/logger.js';
+import { errorHandler } from './src/middleware/errorHandler.js';
+import dealsRouter from './src/routes/deals.js';
+import lineItemsRouter from './src/routes/lineItems.js';
+import creativesRouter from './src/routes/creatives.js';
+import systemRouter from './src/routes/system.js';
+import digitalSignageRouter from './src/routes/digitalSignage.js';
+import approvalRouter from './src/routes/approval.js';
+import { swaggerOptions } from './src/config/swagger.js';
+import { setupAssociations } from './src/models/associations.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const app = express();
+const PORT = process.env.PORT || 5000;
+
+const swaggerSpec = swaggerJsdoc(swaggerOptions);
+
+app.use(cors());
+app.use(express.json());
+
+app.use(requestLogger);
+
+app.get('/', (req, res) => {
+  res.json({ 
+    message: 'DOOH AdServer API - v1.0', 
+    status: 'running',
+    documentation: {
+      swagger: '/api-docs',
+      swaggerJson: '/api-docs.json',
+      testCases: '/docs/test-cases',
+      apiReference: '/docs/api-reference'
+    }
+  });
+});
+
+app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
+
+// Endpoint to download Swagger spec as JSON
+app.get('/api-docs.json', (req, res) => {
+  res.setHeader('Content-Type', 'application/json');
+  res.setHeader('Content-Disposition', 'attachment; filename="dooh-adserver-api-spec.json"');
+  res.json(swaggerSpec);
+});
+
+// Documentation endpoints
+app.get('/docs/test-cases', (req, res) => {
+  const filePath = path.join(__dirname, 'docs', 'TEST_CASES.md');
+  fs.readFile(filePath, 'utf8', (err, data) => {
+    if (err) {
+      return res.status(404).json({ error: 'Test cases documentation not found' });
+    }
+    res.setHeader('Content-Type', 'text/markdown; charset=utf-8');
+    res.send(data);
+  });
+});
+
+app.get('/docs/api-reference', (req, res) => {
+  const filePath = path.join(__dirname, 'replit.md');
+  fs.readFile(filePath, 'utf8', (err, data) => {
+    if (err) {
+      return res.status(404).json({ error: 'API reference documentation not found' });
+    }
+    res.setHeader('Content-Type', 'text/markdown; charset=utf-8');
+    res.send(data);
+  });
+});
+
+app.use('/api/v1/rest', systemRouter);
+app.use('/api/v1/rest/deals', dealsRouter);
+app.use('/api/v1/rest/deals/:dealId/line-items', lineItemsRouter);
+app.use('/api/v1/rest/deals/:dealId/creatives', creativesRouter);
+app.use('/api/v1/rest/deals/:dealId/line-items/:lineItemId/creatives', creativesRouter);
+
+app.use('/api/v2/rest/ds', digitalSignageRouter);
+
+app.use('/api/v1/public/approval', approvalRouter);
+
+app.use(errorHandler);
+
+const startServer = async () => {
+  try {
+    await testConnection();
+    
+    setupAssociations();
+    
+    app.listen(PORT, '0.0.0.0', () => {
+      console.log(`DOOH AdServer running on port ${PORT}`);
+      console.log(`Base path: /api/v1/rest`);
+    });
+  } catch (error) {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+  }
+};
+
+startServer();