@blinkdotnew/sdk 0.10.2 → 0.10.3

package/README.md

@@ -520,51 +520,217 @@ await blink.storage.remove('file1.jpg', 'file2.jpg')
 ### Notifications Operations
 
 ```typescript
-// Send a simple email
-const { success, messageId } = await blink.notifications.email({
+// 🔥 Email Notifications (NEW!) - Send emails with attachments, custom branding, and delivery tracking
+
+// Send a simple email - returns success status and message ID
+const result = await blink.notifications.email({
   to: 'customer@example.com',
   subject: 'Your order has shipped!',
   html: '<h1>Order Confirmation</h1><p>Your order #12345 is on its way.</p>'
 })
 
-// Send an email with attachments and custom sender
-const { success } = await blink.notifications.email({
+console.log(result.success)    // true/false - whether email was sent
+console.log(result.messageId)  // "msg_abc123..." - unique message identifier
+
+// Send with plain text fallback (recommended for better deliverability)
+const { success, messageId } = await blink.notifications.email({
+  to: 'customer@example.com',
+  subject: 'Welcome to our platform!',
+  html: '<h1>Welcome!</h1><p>Thanks for joining us.</p>',
+  text: 'Welcome!\n\nThanks for joining us.' // Plain text version
+})
+
+// Send an email with attachments and custom branding
+const result = await blink.notifications.email({
   to: ['team@example.com', 'manager@example.com'],
-  from: 'Blink Invoicing', // Custom sender name
-  replyTo: 'support@example.com',
-  subject: 'New Invoice',
-  html: '<p>Please find the invoice attached.</p>',
-  text: 'Please find the invoice attached.', // Plain text fallback
-  cc: 'manager@example.com',
-  bcc: 'archive@example.com',
+  from: 'invoices@mycompany.com', // Must be valid email address
+  replyTo: 'support@mycompany.com',
+  subject: 'New Invoice #12345',
+  html: `
+    <div style="font-family: Arial, sans-serif;">
+      <h2>Invoice Ready</h2>
+      <p>Please find the invoice attached.</p>
+    </div>
+  `,
+  text: 'Invoice Ready\n\nPlease find the invoice attached.',
+  cc: 'accounting@mycompany.com',
+  bcc: 'archive@mycompany.com',
   attachments: [
     { 
-      url: 'https://example.com/invoice.pdf', 
-      filename: 'invoice.pdf',
-      type: 'application/pdf'
+      url: 'https://mycompany.com/invoices/12345.pdf',
+      filename: 'Invoice-12345.pdf', // Custom filename
+      type: 'application/pdf'        // MIME type (optional)
+    },
+    {
+      url: 'https://mycompany.com/terms.pdf',
+      filename: 'Terms-of-Service.pdf'
     }
   ]
 })
 
-// Send to multiple recipients
-const { success } = await blink.notifications.email({
-  to: ['user1@example.com', 'user2@example.com'],
-  subject: 'Team Update',
-  html: '<h2>Weekly Update</h2><p>Here are this week\'s highlights...</p>'
+console.log(`Email ${result.success ? 'sent' : 'failed'}`)
+console.log(`Message ID: ${result.messageId}`)
+
+// Send to multiple recipients with different recipient types
+const { success, messageId } = await blink.notifications.email({
+  to: ['customer1@example.com', 'customer2@example.com'],
+  cc: ['manager@example.com'],
+  bcc: ['audit@example.com', 'backup@example.com'],
+  from: 'notifications@mycompany.com',
+  subject: 'Monthly Newsletter',
+  html: '<h2>This Month\'s Updates</h2><p>Here are the highlights...</p>'
 })
 
-// Error handling
+// Dynamic email content with user data
+const user = await blink.auth.me()
+const welcomeEmail = await blink.notifications.email({
+  to: user.email,
+  from: 'welcome@mycompany.com',
+  subject: `Welcome ${user.displayName}!`,
+  html: `
+    <h1>Hi ${user.displayName}!</h1>
+    <p>Welcome to our platform. Your account is now active.</p>
+    <p>Account ID: ${user.id}</p>
+    <a href="https://myapp.com/dashboard">Get Started</a>
+  `,
+  text: `Hi ${user.displayName}!\n\nWelcome to our platform. Your account is now active.\nAccount ID: ${user.id}\n\nGet Started: https://myapp.com/dashboard`
+})
+
+// Comprehensive error handling with detailed error information
 try {
-  await blink.notifications.email({
+  const result = await blink.notifications.email({
     to: 'customer@example.com',
-    subject: 'Welcome!',
-    html: '<p>Welcome to our service!</p>'
+    subject: 'Important Update',
+    html: '<p>This is an important update about your account.</p>'
   })
+  
+  if (result.success) {
+    console.log('✅ Email sent successfully!')
+    console.log('📧 Message ID:', result.messageId)
+  } else {
+    console.error('❌ Email failed to send')
+    // Handle failed send (retry logic, fallback notification, etc.)
+  }
+  
 } catch (error) {
   if (error instanceof BlinkNotificationsError) {
-    console.error('Failed to send email:', error.message)
+    console.error('❌ Email error:', error.message)
+    
+    // Common error scenarios:
+    // - "The 'to', 'subject', and either 'html' or 'text' fields are required."
+    // - "Invalid email address format"
+    // - "Attachment URL must be accessible"
+    // - "Failed to send email: Rate limit exceeded"
+    
+    // Handle specific error types
+    if (error.message.includes('Rate limit')) {
+      // Implement retry with backoff
+      console.log('⏳ Rate limited, will retry later')
+    } else if (error.message.includes('Invalid email')) {
+      // Log invalid email for cleanup
+      console.log('📧 Invalid email address, removing from list')
+    }
+  } else {
+    console.error('❌ Unexpected error:', error)
   }
 }
+
+// Email validation and best practices
+const validateAndSendEmail = async (recipient: string, subject: string, content: string) => {
+  // Basic validation
+  if (!recipient.includes('@') || !subject.trim() || !content.trim()) {
+    throw new Error('Invalid email parameters')
+  }
+  
+  try {
+    const result = await blink.notifications.email({
+      to: recipient,
+      from: 'noreply@mycompany.com',
+      subject: subject,
+      html: `
+        <div style="max-width: 600px; margin: 0 auto; font-family: Arial, sans-serif;">
+          <div style="background: #f8f9fa; padding: 20px; text-align: center;">
+            <h1 style="color: #333; margin: 0;">My Company</h1>
+          </div>
+          <div style="padding: 20px;">
+            ${content}
+          </div>
+          <div style="background: #f8f9fa; padding: 15px; text-align: center; font-size: 12px; color: #666;">
+            <p>© 2024 My Company. All rights reserved.</p>
+            <p><a href="https://mycompany.com/unsubscribe">Unsubscribe</a></p>
+          </div>
+        </div>
+      `,
+      text: content.replace(/<[^>]*>/g, '') // Strip HTML for text version
+    })
+    
+    return result
+  } catch (error) {
+    console.error(`Failed to send email to ${recipient}:`, error)
+    throw error
+  }
+}
+
+// Usage with validation
+try {
+  const result = await validateAndSendEmail(
+    'customer@example.com',
+    'Account Verification Required',
+    '<p>Please verify your account by clicking the link below.</p><a href="https://myapp.com/verify">Verify Account</a>'
+  )
+  console.log('Email sent with ID:', result.messageId)
+} catch (error) {
+  console.error('Email validation or sending failed:', error.message)
+}
+
+// Bulk email sending with error handling
+const sendBulkEmails = async (recipients: string[], subject: string, htmlContent: string) => {
+  const results = []
+  
+  for (const recipient of recipients) {
+    try {
+      const result = await blink.notifications.email({
+        to: recipient,
+        from: 'newsletter@mycompany.com',
+        subject,
+        html: htmlContent,
+        text: htmlContent.replace(/<[^>]*>/g, '')
+      })
+      
+      results.push({ 
+        recipient, 
+        success: result.success, 
+        messageId: result.messageId 
+      })
+      
+      // Rate limiting: wait between sends
+      await new Promise(resolve => setTimeout(resolve, 100))
+      
+    } catch (error) {
+      results.push({ 
+        recipient, 
+        success: false, 
+        error: error.message 
+      })
+    }
+  }
+  
+  return results
+}
+
+// Response format details:
+// ✅ Success response: { success: true, messageId: "msg_abc123..." }
+// ❌ The method throws BlinkNotificationsError on failure
+// 🔍 Error types: validation errors, rate limits, network issues, invalid attachments
+
+// Best practices:
+// 1. Always include both HTML and text versions for better deliverability
+// 2. Use valid email addresses for 'from' field (not display names)
+// 3. Keep HTML simple with inline CSS for email client compatibility
+// 4. Handle rate limits with retry logic
+// 5. Validate email addresses before sending
+// 6. Use message IDs for tracking and debugging
+// 7. Include unsubscribe links for compliance
 ```
 
 ### Analytics Operations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blinkdotnew/sdk",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "description": "Blink TypeScript SDK for client-side applications - Zero-boilerplate CRUD + auth + AI + analytics + notifications for modern SaaS/AI apps",
   "keywords": [
     "blink",