officerdev/platform

Fork 0

Files

T

pastilhas e36908cb0b opengraph stuff

2026-02-24 21:47:36 +00:00

9.3 KiB

Raw Blame History

Node.js Skill Enhancements - Gaps Filled

Summary

The Node.js/TypeScript skill has been enhanced with 3 new advanced recipes to address gaps in email handling that Python had out-of-the-box.

What Was Added

1. ✅ Send Email with Multiple Attachments

Location: SKILL-nodejs.md → Common Recipes section

What it does:

Send a single email with multiple file attachments
Automatic MIME type detection (PDF, DOCX, XLSX, etc.)
Proper boundary management (no manual boundary per file)
Graceful error handling (skips files that can't be attached)

Key features:

await sendMessageWithMultipleAttachments(
  gmail,
  "user@example.com",
  "Subject",
  "Body text",
  ["/path/to/file1.pdf", "/path/to/file2.xlsx"]
);

Why it matters:

Python's EmailMessage.add_attachment() makes this trivial
Node.js manual MIME construction was complex
Now provides comparable ease of use

Comparison:

Python	Node.js Before	Node.js After
✅ `message.add_attachment()` × N	❌ Manual boundary for each	✅ Built-in MIME helper
Easy to add 3+ files	Hard to manage boundaries	Easy
Safe MIME detection	Manual	✅ Auto-detect

2. ✅ Extract Attachments from Received Email

Location: SKILL-nodejs.md → Common Recipes section

What it does:

Download and save attachments from received emails to disk
Handles proper base64url decoding
Returns metadata about each attachment
Creates output directory automatically

Key features:

const attachments = await extractAttachments(
  gmail,
  messageId,
  "./downloads"  // Save directory
);

// Returns:
// [
//   {
//     filename: "report.pdf",
//     mimeType: "application/pdf",
//     size: 245000,
//     attachmentId: "...",
//     messageId: "..."
//   }
// ]

Why it matters:

Python has built-in email parsing: from email.parser import BytesParser
Node.js had NO recipe for this critical feature
This was a major gap

What you can now do:

✅ Batch download all attachments from a message
✅ Get attachment metadata without saving
✅ Process attachments programmatically
✅ Filter by filename/MIME type

3. ✅ Parse and Decode Full Email Body

Location: SKILL-nodejs.md → Common Recipes section

What it does:

Extract ALL email components in one call
Properly decode multipart messages
Extract both plain text AND HTML versions
List all attachments with metadata
Return properly typed object

Key features:

const email = await parseFullEmail(gmail, messageId);

// Returns:
{
  id: "...",
  threadId: "...",
  labelIds: ["INBOX"],
  snippet: "...",
  headers: {
    subject: "Email Subject",
    from: "sender@example.com",
    to: "recipient@example.com",
    cc: "",
    date: "Mon, 24 Feb 2025 12:46:16 +0000"
  },
  body: "Plain text version of email",
  html: "<html>HTML version of email</html>",
  attachments: [
    {
      filename: "document.pdf",
      mimeType: "application/pdf",
      attachmentId: "..."
    }
  ]
}

Why it matters:

Python's email parsing is trivial with standard library
Node.js had NO recipe for parsing multipart emails
This was a critical missing feature

What you can now do:

✅ Extract all email data in one call
✅ Handle both plain text and HTML formats
✅ Automatically detect and list attachments
✅ Build email clients, filters, automation

4. ✅ Added Methods to GmailHelper Class

The GmailHelper class now includes:

parseFullEmail(messageId) - Parse complete email with all components

This makes it available via:

const helper = new GmailHelper(auth);
const email = await helper.parseFullEmail(messageId);

Updated Feature Parity Table

Capability	Python	Node.js	Status
Read emails	✅	✅	✅ Equal
Send simple emails	✅	✅	✅ Equal
Send with attachment	✅ Easy	✅ Now Easy	✅ Equal
Send with multiple attachments	✅ Easy	✅ Now Easy	✅ FIXED
Parse received emails	✅ Easy	✅ Now Easy	✅ FIXED
Extract attachments	✅ Easy	✅ Now Easy	✅ FIXED
Manage labels	✅	✅	✅ Equal
Handle threads	✅	✅	✅ Equal
Error handling	✅	✅ Better	✅ Node.js wins
Type safety	❌	✅	✅ Node.js wins

Real-World Use Cases Now Possible in Node.js

1. Email Forwarding Bot

// Get unread emails
const messages = await listInboxMessages(10);

// For each message
for (const msg of messages) {
  // Parse the full email
  const email = await parseFullEmail(msg.id);
  
  // Extract attachments
  const attachments = await extractAttachments(msg.id, "./attachments");
  
  // Forward with attachments
  await sendMessageWithMultipleAttachments(
    gmail,
    "forward@example.com",
    `Fwd: ${email.headers.subject}`,
    email.body,
    attachments.map(a => `./attachments/${a.filename}`)
  );
}

2. Document Processing Pipeline

// Search for emails with invoices
const invoices = await searchMessages(
  'has:attachment filename:invoice after:2025/01/01'
);

// For each invoice email
for (const inv of invoices) {
  const email = await parseFullEmail(inv.id);
  const attachments = await extractAttachments(inv.id, "./invoices");
  
  // Process each PDF
  for (const att of attachments) {
    if (att.mimeType === "application/pdf") {
      // Send to document processing service
      await processInvoice(att.filename);
    }
  }
}

3. Email Archive Tool

// Search for all emails from a period
const archived = await searchMessages('after:2024/01/01 before:2024/12/31');

// For each, extract full content
for (const msg of archived) {
  const email = await parseFullEmail(msg.id);
  
  // Save to JSON
  fs.writeFileSync(
    `archive/${msg.id}.json`,
    JSON.stringify(email, null, 2)
  );
  
  // Save attachments
  await extractAttachments(msg.id, `archive/${msg.id}/attachments`);
}

Code Quality Improvements

Helper Functions Added

getMimeType() - Detect MIME types by file extension (23 common types)
decodeBase64Url() - Properly handle Gmail's base64url encoding

Error Handling

Try/catch blocks in all recipes
Graceful degradation (e.g., skip files that can't attach)
Helpful error messages

Type Safety

Full TypeScript annotations where possible
Proper return types for parsed emails
Attachment metadata interfaces

Documentation Updates

New Recipe Sections

Send Email with Multiple Attachments
- 100+ lines of documented code
- MIME type helper function
- Usage example
Extract Attachments from Received Email
- Complete attachment download workflow
- Directory creation
- Metadata return
- Usage example
Parse and Decode Full Email Body
- Handles multipart messages
- Extracts both text and HTML
- Lists attachments
- Usage example

Code Examples

Each recipe has working, copy-paste-ready code
All functions are properly typed
Error handling included
Usage examples provided

What's the Difference From Python Now?

Still Better in Python

🐍 Standard library has EmailMessage and email.parser
🐍 Slightly less code for simple cases
🐍 Built-in MIME utilities

Now Equal or Better in Node.js

✅ Multiple attachments - same difficulty now
✅ Parse emails - same functionality now
✅ Extract attachments - same functionality now
✅ Type safety - TypeScript better than Python
✅ Performance - async/await non-blocking
✅ Error handling - better patterns

Testing the New Features

Test Multiple Attachments

npx ts-node << 'EOF'
import { authenticate } from './auth';
const gmail = await authenticate();

// Send test email with 3 files
await sendMessageWithMultipleAttachments(
  gmail,
  "test@example.com",
  "Test Files",
  "Here are test files",
  ["./package.json", "./README.md", "./tsconfig.json"]
);
EOF

Test Email Parsing

npx ts-node << 'EOF'
import { authenticate } from './auth';
const gmail = await authenticate();

// Get first email
const messages = await gmail.users.messages.list({ userId: 'me', maxResults: 1 });
if (messages.data.messages?.[0]) {
  const email = await parseFullEmail(gmail, messages.data.messages[0].id);
  console.log(JSON.stringify(email, null, 2));
}
EOF

Test Attachment Extraction

npx ts-node << 'EOF'
import { authenticate } from './auth';
const gmail = await authenticate();

// Find an email with attachments
const withAttach = await gmail.users.messages.list({
  userId: 'me',
  q: 'has:attachment',
  maxResults: 1
});

if (withAttach.data.messages?.[0]) {
  const attachments = await extractAttachments(
    gmail,
    withAttach.data.messages[0].id,
    "./test-downloads"
  );
  console.log("Downloaded:", attachments);
}
EOF

Summary

✅ All Python-specific gaps have been closed

The Node.js/TypeScript skill now has complete feature parity with Python for:

Sending emails with multiple attachments
Parsing received emails
Extracting attachments from emails
Full email body decoding

Plus Node.js has advantages in:

Type safety (TypeScript)
Performance (non-blocking async)
Better error patterns
Integration with modern web services

Status: COMPLETE PARITY ✅

9.3 KiB Raw Blame History Unescape Escape

Node.js Skill Enhancements - Gaps Filled

Summary

What Was Added

1. ✅ Send Email with Multiple Attachments

2. ✅ Extract Attachments from Received Email

3. ✅ Parse and Decode Full Email Body

4. ✅ Added Methods to GmailHelper Class

Updated Feature Parity Table

Real-World Use Cases Now Possible in Node.js

1. Email Forwarding Bot

2. Document Processing Pipeline

3. Email Archive Tool

Code Quality Improvements

Helper Functions Added

Error Handling

Type Safety

Documentation Updates

New Recipe Sections

Code Examples

What's the Difference From Python Now?

Still Better in Python

Now Equal or Better in Node.js

Testing the New Features

Test Multiple Attachments

Test Email Parsing

Test Attachment Extraction

Summary

9.3 KiB

Raw Blame History