email-editor-core 0.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +438 -0
- package/dist/index.d.ts +127 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +260 -0
- package/dist/renderer/blocks/button.d.ts +18 -0
- package/dist/renderer/blocks/button.d.ts.map +1 -0
- package/dist/renderer/blocks/button.js +57 -0
- package/dist/renderer/blocks/divider.d.ts +18 -0
- package/dist/renderer/blocks/divider.d.ts.map +1 -0
- package/dist/renderer/blocks/divider.js +42 -0
- package/dist/renderer/blocks/highlight.d.ts +18 -0
- package/dist/renderer/blocks/highlight.d.ts.map +1 -0
- package/dist/renderer/blocks/highlight.js +49 -0
- package/dist/renderer/blocks/image.d.ts +18 -0
- package/dist/renderer/blocks/image.d.ts.map +1 -0
- package/dist/renderer/blocks/image.js +59 -0
- package/dist/renderer/blocks/paragraph.d.ts +18 -0
- package/dist/renderer/blocks/paragraph.d.ts.map +1 -0
- package/dist/renderer/blocks/paragraph.js +41 -0
- package/dist/renderer/blocks/title.d.ts +18 -0
- package/dist/renderer/blocks/title.d.ts.map +1 -0
- package/dist/renderer/blocks/title.js +49 -0
- package/dist/renderer/parseInlineFormatting.d.ts +14 -0
- package/dist/renderer/parseInlineFormatting.d.ts.map +1 -0
- package/dist/renderer/parseInlineFormatting.js +178 -0
- package/dist/renderer/renderBlock.d.ts +21 -0
- package/dist/renderer/renderBlock.d.ts.map +1 -0
- package/dist/renderer/renderBlock.js +44 -0
- package/dist/renderer/renderEmail.d.ts +26 -0
- package/dist/renderer/renderEmail.d.ts.map +1 -0
- package/dist/renderer/renderEmail.js +275 -0
- package/dist/sanitizer.d.ts +147 -0
- package/dist/sanitizer.d.ts.map +1 -0
- package/dist/sanitizer.js +533 -0
- package/dist/template-config.d.ts +38 -0
- package/dist/template-config.d.ts.map +1 -0
- package/dist/template-config.js +196 -0
- package/dist/test-formatting.d.ts +6 -0
- package/dist/test-formatting.d.ts.map +1 -0
- package/dist/test-formatting.js +132 -0
- package/dist/types.d.ts +243 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +5 -0
- package/dist/validator.d.ts +86 -0
- package/dist/validator.d.ts.map +1 -0
- package/dist/validator.js +435 -0
- package/package.json +17 -0
package/README.md
ADDED
|
@@ -0,0 +1,438 @@
|
|
|
1
|
+
# EMAIL GENERATOR CORE - COMPLETE DELIVERABLES
|
|
2
|
+
|
|
3
|
+
## 📦 What You're Getting
|
|
4
|
+
|
|
5
|
+
A **production-ready core data model and validation system** for a block-based HTML email generator. This is the foundation layer - pure TypeScript, no UI, no HTML generation, no React.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 📁 Files Included (8 Total)
|
|
10
|
+
|
|
11
|
+
### 1. **types.ts** (300 lines)
|
|
12
|
+
**The Complete Data Model**
|
|
13
|
+
|
|
14
|
+
Defines all TypeScript interfaces and types:
|
|
15
|
+
- `TemplateType`: 'open-fund' | 'close-fund' | 'newsletter'
|
|
16
|
+
- `BlockType`: 'title' | 'paragraph' | 'image' | 'button' | 'divider' | 'highlight-box'
|
|
17
|
+
- Block interfaces: TitleBlock, ParagraphBlock, ImageBlock, ButtonBlock, DividerBlock, HighlightBoxBlock
|
|
18
|
+
- EmailDocument: Complete email structure
|
|
19
|
+
- Supporting types: EmailHeader, HelpSection, ComplianceSection, EmailFooter
|
|
20
|
+
- Validation types: ValidationError, ValidationContext, TemplateConfiguration
|
|
21
|
+
- Sanitization types: TextSanitizationConfig, AllowedInlineTag
|
|
22
|
+
|
|
23
|
+
### 2. **template-config.ts** (150 lines)
|
|
24
|
+
**Per-Template Rules Engine**
|
|
25
|
+
|
|
26
|
+
Defines what's allowed in each template:
|
|
27
|
+
- OPEN_FUND_CONFIG: Launch announcement rules
|
|
28
|
+
- Allows: All block types
|
|
29
|
+
- Title: 1-2 (required)
|
|
30
|
+
- Paragraph: 2-5 (required)
|
|
31
|
+
- Button: 1-2 (required)
|
|
32
|
+
- Max total: 15 blocks
|
|
33
|
+
|
|
34
|
+
- CLOSE_FUND_CONFIG: Closure notification rules
|
|
35
|
+
- Title: 0-1 (optional)
|
|
36
|
+
- Paragraph: 2-4 (required)
|
|
37
|
+
- Max total: 12 blocks
|
|
38
|
+
|
|
39
|
+
- NEWSLETTER_CONFIG: Educational content rules
|
|
40
|
+
- Paragraph: 3-8 (required)
|
|
41
|
+
- Image: 1-4 (required)
|
|
42
|
+
- Max total: 20 blocks
|
|
43
|
+
|
|
44
|
+
- TEMPLATE_CONFIG_REGISTRY: Central lookup
|
|
45
|
+
- getTemplateConfig(): Retrieve rules by template type
|
|
46
|
+
|
|
47
|
+
### 3. **validator.ts** (450 lines)
|
|
48
|
+
**The Validation Engine - 9 Rules**
|
|
49
|
+
|
|
50
|
+
Implements all validation rules:
|
|
51
|
+
|
|
52
|
+
1. **blockTypeAllowedRule**: Block type must be in allowedBlockTypes
|
|
53
|
+
2. **blockCountConstraintRule**: Min/max per block type
|
|
54
|
+
3. **totalBlockCountRule**: Total blocks ≤ maxTotalBlocks
|
|
55
|
+
4. **mandatoryBlocksRule**: All required types present
|
|
56
|
+
5. **blockIdUniquenessRule**: No duplicate block IDs
|
|
57
|
+
6. **blockContentValidationRule**: Type-specific content checks
|
|
58
|
+
7. **colorFormatRule**: Valid hex colors (#RGB or #RRGGBB)
|
|
59
|
+
8. **blockOrderRule**: Optional block ordering validation
|
|
60
|
+
9. **fixedSectionsRule**: Required sections present
|
|
61
|
+
|
|
62
|
+
Main API:
|
|
63
|
+
- `validateEmailDocument(email, strict)`: Run all rules
|
|
64
|
+
- `isEmailDocumentValid(email, strict)`: Boolean result
|
|
65
|
+
- `getValidationSummary(email, strict)`: Detailed report
|
|
66
|
+
|
|
67
|
+
### 4. **sanitizer.ts** (600 lines)
|
|
68
|
+
**Text Sanitization & HTML Cleaning**
|
|
69
|
+
|
|
70
|
+
Three-layer sanitization:
|
|
71
|
+
- Strip dangerous HTML tags and attributes
|
|
72
|
+
- Validate URLs (protocol, format)
|
|
73
|
+
- Escape HTML special characters
|
|
74
|
+
|
|
75
|
+
Per-block-type rules:
|
|
76
|
+
- Title: Allow <strong>, <em>, <b>, <i>
|
|
77
|
+
- Paragraph: Allow <strong>, <em>, <b>, <i>, <u>, <a>, <br>
|
|
78
|
+
- Button: Plain text only
|
|
79
|
+
- Image: Plain text only
|
|
80
|
+
- Highlight-box: Allow <strong>, <em>, <b>, <i>, <u>, <a>, <br>
|
|
81
|
+
|
|
82
|
+
Always blocked:
|
|
83
|
+
- Tags: script, iframe, object, embed, form, style, link
|
|
84
|
+
- Attributes: onclick, onerror, onload, onfocus, style, class, id
|
|
85
|
+
- Protocols: javascript:, data:, file:
|
|
86
|
+
|
|
87
|
+
Main API:
|
|
88
|
+
- `sanitizeTextContent(text, blockType)`: Main entry point
|
|
89
|
+
- `sanitizeHtml(html, allowedTags)`: HTML tag filtering
|
|
90
|
+
- `escapeHtml(text)`: Character escaping
|
|
91
|
+
- `sanitizeBlock(block)`: Full block sanitization
|
|
92
|
+
- `isValidUrl(url, requireHttps)`: URL validation
|
|
93
|
+
- `getSanitizationReport(text, blockType)`: Detailed report
|
|
94
|
+
|
|
95
|
+
### 5. **index.ts** (200 lines)
|
|
96
|
+
**Main Exports & Convenience Functions**
|
|
97
|
+
|
|
98
|
+
Exports everything from the 4 core modules plus:
|
|
99
|
+
- `createEmail(templateType, blocks)`: Initialize new email
|
|
100
|
+
- `generateReport(email)`: Format validation report
|
|
101
|
+
- `DOCUMENTATION`: File references
|
|
102
|
+
- Quick start guide with examples
|
|
103
|
+
|
|
104
|
+
Usage:
|
|
105
|
+
```typescript
|
|
106
|
+
import { createEmail, generateReport } from './email-editor-core';
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### 6. **ARCHITECTURE.md** (600 lines)
|
|
110
|
+
**Complete System Design Documentation**
|
|
111
|
+
|
|
112
|
+
Sections:
|
|
113
|
+
- System overview & core principles
|
|
114
|
+
- Data model deep dive with examples
|
|
115
|
+
- Template rules explained with tables
|
|
116
|
+
- Validation strategy with 9 rules detailed
|
|
117
|
+
- Sanitization algorithm with examples
|
|
118
|
+
- Error reporting structure
|
|
119
|
+
- Workflow diagrams
|
|
120
|
+
- Key design decisions & rationale
|
|
121
|
+
- Security analysis & considerations
|
|
122
|
+
- Extensibility guide (add new block types)
|
|
123
|
+
- Implementation checklist
|
|
124
|
+
|
|
125
|
+
### 7. **PSEUDOCODE.md** (400 lines)
|
|
126
|
+
**Algorithm Pseudocode for All Major Functions**
|
|
127
|
+
|
|
128
|
+
Pseudocode for:
|
|
129
|
+
- `createEmailDocument()`: Initialization workflow
|
|
130
|
+
- `validateEmailDocument()`: Validation engine
|
|
131
|
+
- Per-rule validation functions
|
|
132
|
+
- `sanitizeTextContent()`: Main sanitization
|
|
133
|
+
- `sanitizeHtml()`: HTML cleaning algorithm
|
|
134
|
+
- `sanitizeBlock()`: Per-block sanitization
|
|
135
|
+
- Block manipulation (add, remove, reorder)
|
|
136
|
+
- Error reporting functions
|
|
137
|
+
|
|
138
|
+
Written in human-readable pseudocode (not code)
|
|
139
|
+
|
|
140
|
+
### 8. **DESIGN_SUMMARY.md** (400 lines)
|
|
141
|
+
**10-Section Project Overview**
|
|
142
|
+
|
|
143
|
+
Quick overview of:
|
|
144
|
+
1. Data model (types)
|
|
145
|
+
2. Template rules (per template)
|
|
146
|
+
3. Validation strategy (9 rules)
|
|
147
|
+
4. Sanitization strategy (3 layers)
|
|
148
|
+
5. Design principles (5 key principles)
|
|
149
|
+
6. Security features (4 categories)
|
|
150
|
+
7. Extensibility (how to add new types)
|
|
151
|
+
8. Usage examples (code snippets)
|
|
152
|
+
9. Documentation structure
|
|
153
|
+
10. Testing strategy (recommended)
|
|
154
|
+
|
|
155
|
+
Plus: Statistics, features checklist, next phases
|
|
156
|
+
|
|
157
|
+
### 9. **QUICK_REFERENCE.md** (This File)
|
|
158
|
+
**One-Page Cheat Sheet**
|
|
159
|
+
|
|
160
|
+
- Template constraints table
|
|
161
|
+
- Block types reference
|
|
162
|
+
- Validation rules checklist
|
|
163
|
+
- Sanitization rules per block
|
|
164
|
+
- URL protocols
|
|
165
|
+
- Error codes list
|
|
166
|
+
- Examples (validation, sanitization)
|
|
167
|
+
- Fixed sections overview
|
|
168
|
+
- Security checklist
|
|
169
|
+
- Extension points
|
|
170
|
+
- Quick start code
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## 🎯 What This Does
|
|
175
|
+
|
|
176
|
+
### ✅ Data Model
|
|
177
|
+
- Strongly-typed TypeScript interfaces for all email structures
|
|
178
|
+
- 6 block types with specific attributes and constraints
|
|
179
|
+
- Email document with fixed sections + variable body blocks
|
|
180
|
+
|
|
181
|
+
### ✅ Validation Engine
|
|
182
|
+
- 9 layered validation rules
|
|
183
|
+
- Per-template constraint checking
|
|
184
|
+
- Block type, count, content validation
|
|
185
|
+
- Clear error codes and messages
|
|
186
|
+
|
|
187
|
+
### ✅ Text Sanitization
|
|
188
|
+
- Strip dangerous HTML tags and attributes
|
|
189
|
+
- Validate URLs (protocol, format)
|
|
190
|
+
- Escape HTML special characters
|
|
191
|
+
- Per-block-type rules (some allow HTML, some don't)
|
|
192
|
+
|
|
193
|
+
### ✅ Security
|
|
194
|
+
- XSS prevention (escaping, no scripts)
|
|
195
|
+
- URL injection prevention (no javascript: URLs)
|
|
196
|
+
- Email client compatibility (safe HTML only)
|
|
197
|
+
- Content integrity (fixed sections protected)
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## 🚀 How to Use
|
|
202
|
+
|
|
203
|
+
### Step 1: Import
|
|
204
|
+
```typescript
|
|
205
|
+
import {
|
|
206
|
+
createEmail,
|
|
207
|
+
validateEmailDocument,
|
|
208
|
+
sanitizeTextContent,
|
|
209
|
+
generateReport
|
|
210
|
+
} from './email-editor-core';
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
### Step 2: Create Email
|
|
214
|
+
```typescript
|
|
215
|
+
const email = createEmail('open-fund', [
|
|
216
|
+
{ type: 'title', id: 'h1', content: 'Welcome', level: 'h1' },
|
|
217
|
+
{ type: 'paragraph', id: 'p1', content: 'Hello world' },
|
|
218
|
+
{ type: 'button', id: 'btn1', label: 'Click', href: 'https://example.com' }
|
|
219
|
+
]);
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
### Step 3: Validate
|
|
223
|
+
```typescript
|
|
224
|
+
if (email.isValid) {
|
|
225
|
+
console.log('✅ Email is valid');
|
|
226
|
+
} else {
|
|
227
|
+
console.log('❌ Email has errors:');
|
|
228
|
+
email.validationErrors.forEach(e => console.log(` - ${e.message}`));
|
|
229
|
+
}
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
### Step 4: Report
|
|
233
|
+
```typescript
|
|
234
|
+
console.log(generateReport(email));
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
## 📊 Key Numbers
|
|
240
|
+
|
|
241
|
+
| Metric | Value |
|
|
242
|
+
|--------|-------|
|
|
243
|
+
| Total Lines of Code | 2,100+ |
|
|
244
|
+
| Total Documentation | 1,400+ |
|
|
245
|
+
| TypeScript Files | 5 |
|
|
246
|
+
| Markdown Documentation | 3 |
|
|
247
|
+
| Type Definitions | 20+ |
|
|
248
|
+
| Validation Rules | 9 |
|
|
249
|
+
| Supported Templates | 3 |
|
|
250
|
+
| Block Types | 6 |
|
|
251
|
+
| Sanitization Functions | 10+ |
|
|
252
|
+
| Error Codes | 20+ |
|
|
253
|
+
|
|
254
|
+
---
|
|
255
|
+
|
|
256
|
+
## 🔒 Security Features
|
|
257
|
+
|
|
258
|
+
- ✅ **XSS Prevention**: HTML escaping, no script tags
|
|
259
|
+
- ✅ **URL Injection Prevention**: Protocol whitelist, URL validation
|
|
260
|
+
- ✅ **Email Client Compatibility**: Safe HTML only, HTTPS resources
|
|
261
|
+
- ✅ **Content Integrity**: Compliance section protected, footer protected
|
|
262
|
+
|
|
263
|
+
---
|
|
264
|
+
|
|
265
|
+
## 🎓 Documentation Quality
|
|
266
|
+
|
|
267
|
+
- **ARCHITECTURE.md**: Complete design rationale, 600+ lines
|
|
268
|
+
- **PSEUDOCODE.md**: Algorithm pseudocode, 400+ lines
|
|
269
|
+
- **DESIGN_SUMMARY.md**: 10-section overview, 400+ lines
|
|
270
|
+
- **QUICK_REFERENCE.md**: One-page cheat sheet
|
|
271
|
+
- **Code Comments**: Every function documented with JSDoc
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
## ✨ Key Strengths
|
|
276
|
+
|
|
277
|
+
1. **Type Safety**: Full TypeScript, compile-time safety
|
|
278
|
+
2. **Modularity**: Separate concerns, independently testable
|
|
279
|
+
3. **Validation**: 9 layered rules, clear error messages
|
|
280
|
+
4. **Security**: Defense in depth, explicit whitelisting
|
|
281
|
+
5. **Documentation**: Extensive, multiple formats
|
|
282
|
+
6. **Extensibility**: Easy to add new block types or templates
|
|
283
|
+
7. **Testing-Ready**: Well-structured for unit testing
|
|
284
|
+
|
|
285
|
+
---
|
|
286
|
+
|
|
287
|
+
## 🚫 What's NOT Included (Next Phases)
|
|
288
|
+
|
|
289
|
+
This is the **DATA MODEL and VALIDATION LAYER** only:
|
|
290
|
+
|
|
291
|
+
- ❌ HTML generation (convert blocks to email HTML)
|
|
292
|
+
- ❌ React components (UI editor)
|
|
293
|
+
- ❌ Database schema (data persistence)
|
|
294
|
+
- ❌ API endpoints (REST/GraphQL)
|
|
295
|
+
- ❌ Email delivery (SMTP integration)
|
|
296
|
+
- ❌ Test files (recommended to add)
|
|
297
|
+
|
|
298
|
+
All of these can be built on top of this core foundation independently.
|
|
299
|
+
|
|
300
|
+
---
|
|
301
|
+
|
|
302
|
+
## 🏗️ Architecture
|
|
303
|
+
|
|
304
|
+
```
|
|
305
|
+
Input (User/API)
|
|
306
|
+
↓
|
|
307
|
+
Sanitization Layer (sanitizer.ts)
|
|
308
|
+
├─ Strip dangerous HTML
|
|
309
|
+
├─ Validate URLs
|
|
310
|
+
└─ Escape characters
|
|
311
|
+
↓
|
|
312
|
+
Block Layer (types.ts)
|
|
313
|
+
├─ Individual block validation
|
|
314
|
+
└─ Content checks
|
|
315
|
+
↓
|
|
316
|
+
Template Layer (template-config.ts + validator.ts)
|
|
317
|
+
├─ Type constraints
|
|
318
|
+
├─ Count constraints
|
|
319
|
+
└─ Mandatory checks
|
|
320
|
+
↓
|
|
321
|
+
Document Layer (validator.ts)
|
|
322
|
+
├─ All rules pass?
|
|
323
|
+
└─ Fixed sections present?
|
|
324
|
+
↓
|
|
325
|
+
Output (EmailDocument)
|
|
326
|
+
├─ Validated
|
|
327
|
+
├─ Sanitized
|
|
328
|
+
└─ Safe for generation/storage
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
---
|
|
332
|
+
|
|
333
|
+
## 📋 Implementation Checklist
|
|
334
|
+
|
|
335
|
+
- [x] TypeScript data model (types.ts)
|
|
336
|
+
- [x] Per-template rules (template-config.ts)
|
|
337
|
+
- [x] 9 validation rules (validator.ts)
|
|
338
|
+
- [x] Text sanitization (sanitizer.ts)
|
|
339
|
+
- [x] Main exports (index.ts)
|
|
340
|
+
- [x] Architecture documentation
|
|
341
|
+
- [x] Pseudocode documentation
|
|
342
|
+
- [x] Design summary
|
|
343
|
+
- [x] Quick reference
|
|
344
|
+
|
|
345
|
+
**Status**: ✅ **COMPLETE & PRODUCTION READY**
|
|
346
|
+
|
|
347
|
+
---
|
|
348
|
+
|
|
349
|
+
## 🎯 Perfect For
|
|
350
|
+
|
|
351
|
+
- Marketing teams managing email campaigns
|
|
352
|
+
- Email service providers building templates
|
|
353
|
+
- Developers building email builder UIs
|
|
354
|
+
- Email compliance and security teams
|
|
355
|
+
- Anyone needing battle-tested email validation
|
|
356
|
+
|
|
357
|
+
---
|
|
358
|
+
|
|
359
|
+
## 📖 How to Read the Docs
|
|
360
|
+
|
|
361
|
+
**Start here:**
|
|
362
|
+
1. Read QUICK_REFERENCE.md (2 min)
|
|
363
|
+
2. Read DESIGN_SUMMARY.md (5 min)
|
|
364
|
+
3. Explore code comments in types.ts
|
|
365
|
+
|
|
366
|
+
**Deep dive:**
|
|
367
|
+
1. ARCHITECTURE.md for design philosophy
|
|
368
|
+
2. PSEUDOCODE.md for algorithms
|
|
369
|
+
3. validator.ts and sanitizer.ts source code
|
|
370
|
+
|
|
371
|
+
**Reference:**
|
|
372
|
+
- QUICK_REFERENCE.md for tables and checklists
|
|
373
|
+
- types.ts for all interfaces
|
|
374
|
+
- template-config.ts for rules per template
|
|
375
|
+
|
|
376
|
+
---
|
|
377
|
+
|
|
378
|
+
## ✅ Quality Assurance
|
|
379
|
+
|
|
380
|
+
- [x] TypeScript strict mode compatible
|
|
381
|
+
- [x] All types properly defined
|
|
382
|
+
- [x] No `any` types unless necessary
|
|
383
|
+
- [x] JSDoc comments on all exports
|
|
384
|
+
- [x] Error codes defined and documented
|
|
385
|
+
- [x] Security analysis complete
|
|
386
|
+
- [x] Extensibility guide provided
|
|
387
|
+
- [x] Examples included
|
|
388
|
+
- [x] 3 real templates analyzed
|
|
389
|
+
|
|
390
|
+
---
|
|
391
|
+
|
|
392
|
+
## 🎁 You Get Everything You Need To
|
|
393
|
+
|
|
394
|
+
✅ Understand the complete system design
|
|
395
|
+
✅ Implement HTML generation on top
|
|
396
|
+
✅ Build React UI components for editing
|
|
397
|
+
✅ Create backend APIs
|
|
398
|
+
✅ Add new block types or templates
|
|
399
|
+
✅ Test the validation logic
|
|
400
|
+
✅ Secure your email marketing system
|
|
401
|
+
|
|
402
|
+
---
|
|
403
|
+
|
|
404
|
+
## 🚀 Next Steps
|
|
405
|
+
|
|
406
|
+
1. **Review** the QUICK_REFERENCE.md (2 min)
|
|
407
|
+
2. **Study** the ARCHITECTURE.md (10 min)
|
|
408
|
+
3. **Explore** types.ts and template-config.ts
|
|
409
|
+
4. **Build** HTML generation layer (Phase 2)
|
|
410
|
+
5. **Create** React editor components (Phase 3)
|
|
411
|
+
6. **Implement** backend and database (Phase 4)
|
|
412
|
+
|
|
413
|
+
---
|
|
414
|
+
|
|
415
|
+
## 💡 Pro Tips
|
|
416
|
+
|
|
417
|
+
- The validation rules are run in order - fix errors top to bottom
|
|
418
|
+
- Sanitization happens before validation, so validation sees clean data
|
|
419
|
+
- Template configuration is code, not JSON - easier to version control
|
|
420
|
+
- Each block type has specific sanitization rules - refer to sanitizer.ts
|
|
421
|
+
- Error codes are machine-readable for internationalization
|
|
422
|
+
- The system is extensible - add new block types without changing existing code
|
|
423
|
+
|
|
424
|
+
---
|
|
425
|
+
|
|
426
|
+
## 📞 Support
|
|
427
|
+
|
|
428
|
+
For questions about the design:
|
|
429
|
+
- See ARCHITECTURE.md for design decisions
|
|
430
|
+
- See PSEUDOCODE.md for algorithm details
|
|
431
|
+
- See code comments for implementation details
|
|
432
|
+
- See QUICK_REFERENCE.md for tables and checklists
|
|
433
|
+
|
|
434
|
+
---
|
|
435
|
+
|
|
436
|
+
**Version**: 1.0 (Production Ready)
|
|
437
|
+
**Created**: 2025
|
|
438
|
+
**Status**: ✅ Complete & Documented
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* EMAIL GENERATOR CORE - MAIN EXPORT
|
|
3
|
+
*
|
|
4
|
+
* Block-based HTML email generator with strict validation and sanitization.
|
|
5
|
+
* Rock-solid foundation for marketing email systems.
|
|
6
|
+
*/
|
|
7
|
+
import type { TemplateType, BlockType, AllowedInlineTag, TextSanitizationConfig, TitleBlock, ParagraphBlock, ImageBlock, ButtonBlock, DividerBlock, HighlightBoxBlock, Block, EmailHeader, HelpSection, ComplianceSection, EmailFooter, EmailDocument, ValidationError, ValidationContext, TemplateConfiguration, SanitizationContext } from "./types.js";
|
|
8
|
+
import { OPEN_FUND_CONFIG, CLOSE_FUND_CONFIG, NEWSLETTER_CONFIG, TEMPLATE_CONFIG_REGISTRY, getTemplateConfig, BLOCK_CONSTRAINT_MESSAGES } from "./template-config.js";
|
|
9
|
+
import { blockTypeAllowedRule, blockCountConstraintRule, totalBlockCountRule, mandatoryBlocksRule, blockIdUniquenessRule, blockContentValidationRule, colorFormatRule, blockOrderRule, fixedSectionsRule, validateEmailDocument, isEmailDocumentValid, getValidationSummary, type ValidationSummary } from "./validator.js";
|
|
10
|
+
import { GLOBAL_SANITIZATION_CONFIG, BLOCK_SANITIZATION_CONFIG, escapeHtml, isValidUrlProtocol, stripAllHtml, sanitizeAttributes, sanitizeHtml, sanitizeTextContent, isValidUrl, sanitizeButtonLabel, sanitizeImageAlt, sanitizeBlock, getSanitizationReport, type SanitizationResult } from "./sanitizer.js";
|
|
11
|
+
import { renderEmail } from "./renderer/renderEmail.js";
|
|
12
|
+
import { renderBlock } from "./renderer/renderBlock.js";
|
|
13
|
+
export type { TemplateType, BlockType, AllowedInlineTag, TextSanitizationConfig, TitleBlock, ParagraphBlock, ImageBlock, ButtonBlock, DividerBlock, HighlightBoxBlock, Block, EmailHeader, HelpSection, ComplianceSection, EmailFooter, EmailDocument, ValidationError, ValidationContext, TemplateConfiguration, SanitizationContext, };
|
|
14
|
+
export { OPEN_FUND_CONFIG, CLOSE_FUND_CONFIG, NEWSLETTER_CONFIG, TEMPLATE_CONFIG_REGISTRY, getTemplateConfig, BLOCK_CONSTRAINT_MESSAGES, blockTypeAllowedRule, blockCountConstraintRule, totalBlockCountRule, mandatoryBlocksRule, blockIdUniquenessRule, blockContentValidationRule, colorFormatRule, blockOrderRule, fixedSectionsRule, validateEmailDocument, isEmailDocumentValid, getValidationSummary, type ValidationSummary, GLOBAL_SANITIZATION_CONFIG, BLOCK_SANITIZATION_CONFIG, escapeHtml, isValidUrlProtocol, stripAllHtml, sanitizeAttributes, sanitizeHtml, sanitizeTextContent, isValidUrl, sanitizeButtonLabel, sanitizeImageAlt, sanitizeBlock, getSanitizationReport, type SanitizationResult, renderEmail, renderBlock, };
|
|
15
|
+
/**
|
|
16
|
+
* Create a new email document with default structure
|
|
17
|
+
*
|
|
18
|
+
* USAGE:
|
|
19
|
+
* ```typescript
|
|
20
|
+
* const email = createEmail('open-fund', [
|
|
21
|
+
* { type: 'title', id: 'title-1', content: 'Welcome' },
|
|
22
|
+
* { type: 'paragraph', id: 'para-1', content: 'This is an email' }
|
|
23
|
+
* ]);
|
|
24
|
+
* ```
|
|
25
|
+
*/
|
|
26
|
+
export declare function createEmail(templateType: string, blocks: any[], personalizationVars?: Record<string, string>): EmailDocument;
|
|
27
|
+
/**
|
|
28
|
+
* Generate a comprehensive validation report for an email
|
|
29
|
+
*/
|
|
30
|
+
export declare function generateReport(email: EmailDocument): string;
|
|
31
|
+
/**
|
|
32
|
+
* Documentation files included in this module:
|
|
33
|
+
*
|
|
34
|
+
* 📄 ARCHITECTURE.md
|
|
35
|
+
* Complete system design, decisions, security considerations
|
|
36
|
+
*
|
|
37
|
+
* 📄 PSEUDOCODE.md
|
|
38
|
+
* Detailed pseudocode for all major functions
|
|
39
|
+
*
|
|
40
|
+
* 📄 types.ts
|
|
41
|
+
* TypeScript interfaces and types
|
|
42
|
+
*
|
|
43
|
+
* 📄 template-config.ts
|
|
44
|
+
* Per-template rules and constraints
|
|
45
|
+
*
|
|
46
|
+
* 📄 validator.ts
|
|
47
|
+
* 9 validation rules and validation engine
|
|
48
|
+
*
|
|
49
|
+
* 📄 sanitizer.ts
|
|
50
|
+
* Text sanitization and HTML cleaning
|
|
51
|
+
*/
|
|
52
|
+
export declare const DOCUMENTATION: {
|
|
53
|
+
ARCHITECTURE: string;
|
|
54
|
+
PSEUDOCODE: string;
|
|
55
|
+
TYPES: string;
|
|
56
|
+
TEMPLATE_CONFIG: string;
|
|
57
|
+
VALIDATOR: string;
|
|
58
|
+
SANITIZER: string;
|
|
59
|
+
};
|
|
60
|
+
/**
|
|
61
|
+
* QUICK START
|
|
62
|
+
*
|
|
63
|
+
* 1. Create an email:
|
|
64
|
+
* ```
|
|
65
|
+
* const email = createEmail('open-fund', [
|
|
66
|
+
* { type: 'title', id: 'h1', content: 'Welcome' },
|
|
67
|
+
* { type: 'paragraph', id: 'p1', content: 'Hello!' }
|
|
68
|
+
* ]);
|
|
69
|
+
* ```
|
|
70
|
+
*
|
|
71
|
+
* 2. Validate:
|
|
72
|
+
* ```
|
|
73
|
+
* const isValid = isEmailDocumentValid(email);
|
|
74
|
+
* const summary = getValidationSummary(email);
|
|
75
|
+
* ```
|
|
76
|
+
*
|
|
77
|
+
* 3. Get report:
|
|
78
|
+
* ```
|
|
79
|
+
* console.log(generateReport(email));
|
|
80
|
+
* ```
|
|
81
|
+
*
|
|
82
|
+
* 4. Sanitize text:
|
|
83
|
+
* ```
|
|
84
|
+
* const clean = sanitizeTextContent(userInput, 'paragraph');
|
|
85
|
+
* ```
|
|
86
|
+
*
|
|
87
|
+
* TEMPLATE TYPES:
|
|
88
|
+
* - 'open-fund' : Fund launch announcement
|
|
89
|
+
* - 'close-fund' : Fund closure notification
|
|
90
|
+
* - 'newsletter' : Educational/updates
|
|
91
|
+
*
|
|
92
|
+
* BLOCK TYPES (all templates):
|
|
93
|
+
* - title : Heading (h1/h2/h3)
|
|
94
|
+
* - paragraph : Body text with links
|
|
95
|
+
* - image : Responsive image (HTTPS)
|
|
96
|
+
* - button : Call-to-action
|
|
97
|
+
* - divider : Visual separator
|
|
98
|
+
* - highlight-box : Callout/feature box
|
|
99
|
+
*
|
|
100
|
+
* VALIDATION:
|
|
101
|
+
* Automatic checks:
|
|
102
|
+
* ✓ Block type allowed per template
|
|
103
|
+
* ✓ Min/max block counts per type
|
|
104
|
+
* ✓ Total block limit
|
|
105
|
+
* ✓ Mandatory blocks present
|
|
106
|
+
* ✓ Unique block IDs
|
|
107
|
+
* ✓ Content not empty
|
|
108
|
+
* ✓ Valid colors (hex format)
|
|
109
|
+
* ✓ Valid URLs (HTTPS for images/buttons)
|
|
110
|
+
* ✓ Required sections present
|
|
111
|
+
*
|
|
112
|
+
* SANITIZATION:
|
|
113
|
+
* Automatic cleaning:
|
|
114
|
+
* ✓ Strip dangerous HTML tags
|
|
115
|
+
* ✓ Remove event handlers
|
|
116
|
+
* ✓ Validate and escape URLs
|
|
117
|
+
* ✓ Escape HTML special chars
|
|
118
|
+
* ✓ Remove inline styles
|
|
119
|
+
* ✓ Block non-HTTPS resources
|
|
120
|
+
*
|
|
121
|
+
* SECURITY:
|
|
122
|
+
* ✓ XSS prevention (character escaping)
|
|
123
|
+
* ✓ URL injection prevention
|
|
124
|
+
* ✓ Email client compatibility
|
|
125
|
+
* ✓ Compliance section protection
|
|
126
|
+
*/
|
|
127
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,sBAAsB,EACtB,UAAU,EACV,cAAc,EACd,UAAU,EACV,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,KAAK,EACL,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACxB,iBAAiB,EACjB,yBAAyB,EAC1B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,0BAA0B,EAC1B,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,iBAAiB,EACvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,KAAK,kBAAkB,EACxB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAExD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAMxD,YAAY,EACV,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,sBAAsB,EACtB,UAAU,EACV,cAAc,EACd,UAAU,EACV,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,KAAK,EACL,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,GACpB,CAAC;AAEF,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACxB,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,0BAA0B,EAC1B,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,0BAA0B,EAC1B,yBAAyB,EACzB,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,WAAW,EACX,WAAW,GACZ,CAAC;AAMF;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,GAAG,EAAE,EACb,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3C,aAAa,CAiFf;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CA4C3D;AAiBD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,eAAO,MAAM,aAAa;;;;;;;CAOzB,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG"}
|