@carlgo11/simpleimfparser 0.0.0 → 0.0.1-a

package/.github/workflows/publish.yaml

@@ -0,0 +1,51 @@
+name: Publish package
+on:
+  release:
+    types:
+      - published
+jobs:
+  test:
+    name: Test code
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npm test
+
+  publish:
+    name: Publish package
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      matrix:
+        registry:
+          - gpr
+          - npm
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: ${{ matrix.registry == 'gpr' && 'https://npm.pkg.github.com/' || 'https://registry.npmjs.org/' }}
+      - name: Extract version from tag
+        id: extract_version
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+      - name: Update package.json version
+        run: |
+          jq ".version = \"$VERSION\"" package.json > package.tmp.json
+          mv package.tmp.json package.json
+      - run: npm install
+      - run: npm run build
+      - name: Publish package
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ matrix.registry == 'gpr' && secrets.GITHUB_TOKEN || secrets.npm_token }}

package/.github/workflows/test.yaml

@@ -0,0 +1,14 @@
+name: Test package
+on: push
+jobs:
+  test:
+    name: Test package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npm test
+      - run: npm run build

package/.gitignore

@@ -3,3 +3,4 @@ dist
 package-lock.json
 .*
 !.gitignore
+!.github

package/README.md

@@ -0,0 +1,59 @@
+# Simple IMF Parser
+
+A TypeScript library for parsing Internet Message Format (IMF) emails, extracting headers, envelope details, and message bodies while providing useful utilities for email manipulation.
+
+## Features
+- Parses raw IMF emails from **string** or **stream** input
+- Supports **header parsing** (including multi-line folding)
+- Provides a structured **Email class** with helper functions:
+  - `getHeader(name)` – Retrieve a header
+  - `addHeader(name, value)` – Add a new header
+  - `removeHeader(name)` – Remove a header
+  - `getBody()` – Get the email body
+- Handles **multiple headers** with the same name (e.g., `Received` headers)
+- Supports **UTF-8 names & addresses** (RFC 6532)
+
+## Installation
+```sh
+npm install @carlgo11/simpleimfparser
+```
+
+## Usage
+
+### Parsing an Email
+```ts
+import parseEmail from '@carlgo11/simpleimfparser';
+import fs from 'fs';
+
+(async () => {
+  const rawData = fs.readFileSync('test-email.eml', 'utf-8');
+  const envelope = {
+    from: 'alice@example.com',
+    to: ['bob@example.com'],
+    senderIP: '192.168.1.1'
+  };
+
+  const email = await parseEmail(rawData, envelope);
+  
+  console.log('Subject:', email.getHeader('subject'));
+  console.log('Body:', email.getBody());
+})();
+```
+
+### Working with Headers
+```ts
+email.addHeader('X-Custom-Header', 'Hello World');
+email.removeHeader('Received');
+console.log(email.getHeader('from'));
+```
+
+### Extracting Envelope Details
+```ts
+console.log(email.envelope.senderIP); // 192.168.1.1
+console.log(email.envelope.to); // ['bob@example.com']
+```
+
+### Recompiling Email Object to IMF Format
+```ts
+email.toString();
+```

package/dist/index.js

@@ -0,0 +1,8 @@
+import { Email } from './types/Email.js';
+import parseEnvelope from './parsers/parseEnvelope.js';
+import parseMessage from './parsers/parseMessage.js';
+export default async function parseEmail(rawData, envelope) {
+    const parsedEnvelope = await parseEnvelope(envelope);
+    const { headers, body } = await parseMessage(rawData);
+    return new Email(parsedEnvelope, headers, body);
+}

package/dist/parsers/parseEnvelope.js

@@ -0,0 +1,9 @@
+/**
+ * Parses envelope metadata from the SMTP transaction.
+ * @param envelope - Envelope data object
+ * @returns Parsed Envelope object
+ */
+export default async function parseEnvelope(envelope) {
+    // TODO: Implement envelope parsing logic
+    return envelope;
+}

package/dist/parsers/parseHeaders.js

@@ -0,0 +1,65 @@
+/**
+ * Parses headers from a raw IMF header string.
+ * @param rawHeaders - The raw headers as a string
+ * @returns A dictionary of headers (handling duplicates)
+ */
+export default function parseHeaders(rawHeaders) {
+    const headers = {};
+    const lines = rawHeaders.split(/\r\n|\n/);
+    let currentKey = null;
+    let currentValue = '';
+    for (const line of lines) {
+        if (line.startsWith(' ') || line.startsWith('\t')) {
+            // Handle folded headers (continuation lines)
+            if (currentKey) {
+                if (Array.isArray(headers[currentKey])) {
+                    headers[currentKey][headers[currentKey].length - 1] += ' ' + line.trim();
+                }
+                else {
+                    headers[currentKey] += ' ' + line.trim();
+                }
+            }
+            else {
+                throw new Error('Header folding found without a preceding header field.');
+            }
+        }
+        else {
+            // Store previous header before starting a new one
+            if (currentKey) {
+                if (headers[currentKey]) {
+                    if (Array.isArray(headers[currentKey])) {
+                        headers[currentKey].push(currentValue);
+                    }
+                    else {
+                        headers[currentKey] = [headers[currentKey], currentValue];
+                    }
+                }
+                else {
+                    headers[currentKey] = currentValue;
+                }
+            }
+            // Extract new header key-value pair
+            const match = line.match(/^([!#$%&'*+\-.0-9A-Z^_`a-z|~]+):\s*(.*)$/);
+            if (!match) {
+                throw new Error(`Invalid header format: "${line}"`);
+            }
+            currentKey = match[1].toLowerCase(); // Convert key to lowercase
+            currentValue = match[2];
+        }
+    }
+    // Store the last header
+    if (currentKey) {
+        if (headers[currentKey]) {
+            if (Array.isArray(headers[currentKey])) {
+                headers[currentKey].push(currentValue);
+            }
+            else {
+                headers[currentKey] = [headers[currentKey], currentValue];
+            }
+        }
+        else {
+            headers[currentKey] = currentValue;
+        }
+    }
+    return headers;
+}

package/dist/parsers/parseMessage.js

@@ -0,0 +1,30 @@
+import { Readable } from 'node:stream';
+import parseHeaders from './parseHeaders.js';
+import streamToString from '../utils/streamToString.js';
+/**
+ * Parses the raw email message (headers + body).
+ * @param rawData - Raw IMF email (string or stream)
+ * @returns Parsed email components
+ */
+export default async function parseMessage(rawData) {
+    let rawEmail;
+    if (typeof rawData === 'string') {
+        rawEmail = rawData;
+    }
+    else if (rawData instanceof Readable) {
+        rawEmail = await streamToString(rawData);
+    }
+    else {
+        throw new TypeError('Invalid rawData type. Expected a string or a Readable stream.');
+    }
+    const headerBoundary = rawEmail.indexOf('\r\n\r\n');
+    const rawHeaders = rawEmail.slice(0, headerBoundary);
+    const body = rawEmail.slice(headerBoundary + 4);
+    if (body.length === 0) {
+        throw new Error('Header and Body must be separated by \\r\\n\\r\\n');
+    }
+    return {
+        headers: parseHeaders(rawHeaders),
+        body,
+    };
+}

package/dist/types/Attachment.js

@@ -0,0 +1 @@
+export {};

package/dist/types/Email.js

@@ -0,0 +1,55 @@
+export class Email {
+    envelope;
+    headers;
+    body;
+    attachments;
+    constructor(envelope, headers, body, attachments) {
+        this.envelope = envelope;
+        this.headers = headers;
+        this.body = body;
+        this.attachments = attachments || [];
+    }
+    /**
+     * Get a header value (case-insensitive).
+     */
+    getHeader(name) {
+        return this.headers[name.toLowerCase()];
+    }
+    /**
+     * Add or update a header.
+     */
+    addHeader(name, value) {
+        const key = name.toLowerCase();
+        if (this.headers[key]) {
+            if (Array.isArray(this.headers[key])) {
+                this.headers[key].push(value);
+            }
+            else {
+                this.headers[key] = [this.headers[key], value];
+            }
+        }
+        else {
+            this.headers[key] = value;
+        }
+    }
+    /**
+     * Remove a header.
+     */
+    removeHeader(name) {
+        delete this.headers[name.toLowerCase()];
+    }
+    /**
+     * Get the email body (prefers text, fallback to HTML).
+     */
+    getBody() {
+        return this.body || '';
+    }
+    toString() {
+        let _headers = '';
+        Object.entries(this.headers).forEach(([k, v]) => _headers += `${camelize(k)}: ${v}\r\n`);
+        return `${_headers}\r\n\r\n${this.body}`;
+    }
+}
+function camelize(str) {
+    return str.replace(/(\w)(\w*)/g, function (g0, g1, g2) { return g1.toUpperCase() + g2.toLowerCase(); });
+}

package/dist/types/Envelope.js

@@ -0,0 +1 @@
+export {};

package/dist/types/Sender.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/streamToString.js

@@ -0,0 +1,13 @@
+/**
+ * Converts a Readable Stream to a string.
+ * @param stream - Input stream
+ * @returns Promise resolving to the string content
+ */
+export default async function streamToString(stream) {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        stream.on('data', chunk => (data += chunk));
+        stream.on('end', () => resolve(data));
+        stream.on('error', reject);
+    });
+}

package/package.json

@@ -1,18 +1,35 @@
 {
   "type": "module",
-  "main": "src/index.ts",
+  "main": "dist/index.js",
   "name": "@carlgo11/simpleimfparser",
-  "version": "0.0.0",
+  "description": "Simple IMF parser",
+  "version": "0.0.1a",
+  "license": "GPL-3.0",
+  "author": "Carlgo11",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/carlgo11/SimpleIMFParser.git"
+  },
+  "bugs": {
+    "url": "https://github.com/carlgo11/SimpleIMFParser/issues"
+  },
+  "homepage": "https://github.com/carlgo11/SimpleIMFParser#readme",
   "scripts": {
     "start": "node src/index.ts",
-    "test": "node --import tsx --test test/*.test.ts test/**/*.test.ts"
+    "test": "node --import tsx --test test/*.test.ts test/**/*.test.ts",
+    "build": "npx tsc"
   },
   "private": false,
+  "dependencies": {
+    "@types/node": "^22.10.7"
+  },
   "devDependencies": {
     "@faker-js/faker": "^9.4.0",
-    "@types/node": "^22.10.7",
     "ts-node": "^10.9.2",
     "tsx": "^4.19.2",
     "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=20"
   }
 }

package/src/index.ts

@@ -1,7 +1,7 @@
 import { Readable } from 'node:stream';
-import { Email } from './types/Email';
-import parseEnvelope from './parsers/parseEnvelope';
-import parseMessage from './parsers/parseMessage';
+import { Email } from './types/Email.js';
+import parseEnvelope from './parsers/parseEnvelope.js';
+import parseMessage from './parsers/parseMessage.js';
 
 export default async function parseEmail(
   rawData: string | Readable,

package/src/parsers/parseEnvelope.ts

@@ -1,4 +1,4 @@
-import Envelope from '../types/Envelope';
+import Envelope from '../types/Envelope.js';
 
 /**
  * Parses envelope metadata from the SMTP transaction.

package/src/parsers/parseMessage.ts

@@ -1,6 +1,6 @@
 import { Readable } from 'node:stream';
-import parseHeaders from './parseHeaders';
-import streamToString from '../utils/streamToString';
+import parseHeaders from './parseHeaders.js';
+import streamToString from '../utils/streamToString.js';
 
 /**
  * Parses the raw email message (headers + body).

package/src/types/Email.ts

@@ -1,4 +1,4 @@
-import Envelope from './Envelope';
+import Envelope from './Envelope.js';
 
 export class Email {
   envelope: Envelope;

package/src/types/Envelope.ts

@@ -1,4 +1,4 @@
-import Sender from './Sender';
+import Sender from './Sender.js';
 
 export default interface Envelope {
   id: string;

package/test/index.test.ts

@@ -2,9 +2,10 @@ import { describe, it } from 'node:test';
 import { faker } from '@faker-js/faker';
 import assert from 'node:assert';
 import parseEmail from '../src';
+import { Readable } from 'node:stream';
 
 describe('simpleIMFParser', () => {
-  it('Should parse valid message', async () => {
+  it('Should parse valid message (string)', async () => {
     const headers: Record<string, string> = {
       'Subject': faker.lorem.sentence(),
       'MESSAGE-ID': `${faker.string.uuid()}@${faker.internet.domainName()}`,
@@ -12,10 +13,28 @@ describe('simpleIMFParser', () => {
       'To': `${faker.person.fullName()} <${faker.internet.email()}>`,
     };
     const headersString = Object.entries(headers).map(([key, value]) => `${key}: ${value}`).join('\r\n');
-    const body = faker.lorem.paragraphs(5).replace('\n', '\r\n');
+    const body = faker.lorem.paragraphs(5, '\r\n');
 
     const full_email = `${headersString}\r\n\r\n${body}`;
     const email = await parseEmail(full_email, {});
     assert.ok(email.toString());
   });
+
+   it('Should parse valid message (stream)', async () => {
+    const headers: Record<string, string> = {
+      'from': `"${faker.person.fullName()}" <${faker.internet.email()}>`,
+      'To': `${faker.person.fullName()} <${faker.internet.email({allowSpecialCharacters: true})}>`,
+      'Subject': faker.lorem.sentence(),
+      'MESSAGE-ID': `${faker.string.uuid()}@${faker.internet.domainName()}`,
+    };
+    const headersString = Object.entries(headers).map(([key, value]) => `${key}: ${value}`).join('\r\n');
+    const body = faker.lorem.paragraphs(5, '\r\n');
+
+    const full_email = `${headersString}\r\n\r\n${body}`;
+
+    const email = await parseEmail(Readable.from(full_email), {});
+    assert.ok(email.toString());
+  });
+
+
 });

package/tsconfig.json

@@ -1,10 +1,15 @@
 {
   "compilerOptions": {
-    "target": "ES2024",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
-    "module": "commonjs",                                /* Specify what module code is generated. */
-    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
-    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
-    "strict": true,                                      /* Enable all strict type-checking options. */
-    "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
-  }
+    "target": "ES2024",
+    "module": "nodenext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "./dist"
+  },
+  "include": [
+    "./src/**/*",
+    "./src/*"
+  ]
 }