gloo-email 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 738fcacc7475ef8b8404861a76e59b6711fdd54a7423429d442f79bddf29316e
+  data.tar.gz: d6cfda322d190c5ebede7d8d3d811e30b89b752dafeef32f526b2a61503aa362
+SHA512:
+  metadata.gz: cf5c545dad112ea64891fed3fd235a657c95b2a6dfa365aadf375279613089a9f1b78fb072145f2ee30a00debd8ea4a90e2d94fd32c773e05b4c18730fc1f2ee
+  data.tar.gz: 8f46e2fd256810f41cb87fdb026e218062920b510bc5ee8c574589b3e273b7ffc1ab0a5f62a01086bfde0c72034e08912a787ede5446b7c270fc59324a59118e

data/README.md

@@ -0,0 +1,21 @@
+# gloo-email
+
+A core gloo library for sending and fetching emails.
+
+## Usage
+
+Load this library in a gloo script:
+
+```gloo
+> load lib email
+```
+
+## Objects
+
+- `email_smtp` — SMTP configuration, used to send email
+- `email_imap` — an IMAP connection, used to fetch email
+- `email` — an email message (recipient, sender, subject, body)
+
+## Full Reference
+
+Every object's children and messages are documented in-app once the library is loaded — e.g. `help> object email_smtp`.

data/lib/config.rb

@@ -0,0 +1,19 @@
+# 
+# An Mail Server Configuration
+# 
+
+class Config
+
+  attr_accessor :host, :port, :username, :password
+  
+  # 
+  # Initialize a new SMTP email sender.
+  # 
+  def initialize( host, port, username, password )
+    @host = host
+    @port = port
+    @username = username
+    @password = password
+  end
+
+end

data/lib/email_imap.rb

@@ -0,0 +1,201 @@
+#
+# An email IMAP object
+#
+require 'net/imap'
+require 'mail'
+
+class EmailImap < Gloo::Core::Obj
+
+  KEYWORD = 'email_imap'.freeze
+  SERVER = 'server'.freeze
+  PORT = 'port'.freeze
+  USERNAME = 'username'.freeze
+  PASSWORD = 'password'.freeze
+  MAILBOX = 'mailbox'.freeze
+  MESSAGES = 'messages'.freeze
+  SEARCH = 'UNSEEN'.freeze
+
+  #
+  # The name of the object type.
+  #
+  def self.typename
+    return KEYWORD
+  end
+
+  #
+  # The short name of the object type.
+  # Same as the typename.
+  #
+  def self.short_typename
+    return KEYWORD
+  end
+
+  # 
+  # Get the email server host.
+  #
+  def server
+    return find_child_value SERVER
+  end
+
+  #
+  # Get the email server port.
+  #
+  def port
+    return find_child_value PORT
+  end
+
+  #
+  # Get the email username.
+  #
+  def username
+    return find_child_value USERNAME
+  end
+
+  #
+  # Get the email password.
+  #
+  def password
+    return find_child_value PASSWORD
+  end
+
+  #
+  # Get the email mailbox.
+  #
+  def mailbox
+    return find_child_value MAILBOX
+  end
+
+
+  # ---------------------------------------------------------------------
+  #    Children
+  # ---------------------------------------------------------------------
+
+  # Does this object have children to add when an object
+  # is created in interactive mode?
+  # This does not apply during obj load, etc.
+  def add_children_on_create?
+    return true
+  end
+
+  # Add children to this object.
+  # This is used by containers to add children needed
+  # for default configurations.
+  def add_default_children
+    fac = @engine.factory
+    fac.create_string SERVER, '', self
+    fac.create_string PORT, '', self
+    fac.create_string USERNAME, '', self
+    fac.create_string PASSWORD, '', self
+    fac.create_string MAILBOX, '', self
+    fac.create_can MESSAGES, self
+  end
+
+
+  # ---------------------------------------------------------------------
+  #    Messages
+  # ---------------------------------------------------------------------
+
+  #
+  # Get a list of message names that this object receives.
+  #
+  def self.messages
+    return super + [ 'fetch' ]
+  end
+
+  #
+  # Fetch emails from the IMAP server.
+  #
+  def msg_fetch
+    # Connect to the email server
+    imap = Net::IMAP.new(server, port, true)
+    imap.login(username, password)
+    imap.select(mailbox)
+
+    # Search for messages matching filter
+    ids = imap.search([SEARCH])
+
+    if ids.empty?
+      puts "No new messages."
+    else
+      ids.each do |msg_id|
+        raw_message = imap.fetch( msg_id, "RFC822" )[0].attr["RFC822"]
+        mail = Mail.read_from_string( raw_message )
+        process_message( mail )
+      end
+    end
+
+    # -----------------------------
+    # CLEAN UP
+    # -----------------------------
+    imap.logout
+    imap.disconnect  
+  end
+
+  #
+  # Process a single email message
+  #
+  def process_message( mail )
+    from = mail.from.join(', ')
+    to = mail.to.join(', ')
+    subject = mail.subject
+    dt = mail.date
+    body = mail.body.decoded
+
+    msg_can = find_child MESSAGES
+    
+    msg = msg_can.find_add_child( msg_can.children.length.to_s, 'email' )
+    o = msg.find_add_child( 'from', 'string' )
+    o.set_value from
+    o = msg.find_add_child( 'to', 'string' )
+    o.set_value to
+    o = msg.find_add_child( 'subject', 'string' )
+    o.set_value subject
+    o = msg.find_add_child( 'date', 'string' )
+    o.set_value dt
+    o = msg.find_add_child( 'body', 'text' )
+    o.set_value body
+  end
+
+  # ---------------------------------------------------------------------
+  #    Object Documentation
+  # ---------------------------------------------------------------------
+
+  #
+  # Get the object's documentation data.
+  #
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :shortcut => KEYWORD,
+      :description => 'An IMAP email connection, used to fetch ' \
+        'unseen messages from a mailbox.',
+      :children => [
+        'server (string) — The IMAP server host.',
+        'port (string) — The IMAP server port.',
+        'username (string) — The username with which to connect.',
+        "password (string) — The user's password.",
+        'mailbox (string) — The mailbox to select (e.g. INBOX).',
+        'messages (container) — Populated by fetch: one child per unseen message found, each an email object with from/to/subject/date/body.'
+      ],
+      :messages => [
+        'fetch — Connect to the IMAP server, select the mailbox, and fetch all unseen messages, adding each as a child of messages. Logs out and disconnects when done.'
+      ],
+      :notes => 'No vault documentation exists for this object type — ' \
+        'this was authored directly from the code.',
+      :examples => <<~EXAMPLES.strip
+        mail [can] :
+          inbox [email_imap] :
+            server : imap.example.com
+            port : 993
+            username : me@example.com
+            password : secret
+            mailbox : INBOX
+
+          on_load [script] :
+            tell mail.inbox to fetch
+            list mail.inbox.messages
+      EXAMPLES
+    }
+  end
+
+end

data/lib/email_msg.rb

@@ -0,0 +1,165 @@
+#
+# An email message object
+#
+class EmailMsg < Gloo::Core::Obj
+
+  KEYWORD = 'email'.freeze
+  SUBJECT = 'subject'.freeze
+  BODY = 'body'.freeze
+  TO = 'to'.freeze
+  FROM = 'from'.freeze
+  WHEN = 'when'.freeze
+
+  #
+  # The name of the object type.
+  #
+  def self.typename
+    return KEYWORD
+  end
+
+  #
+  # The short name of the object type.
+  # Same as the typename.
+  #
+  def self.short_typename
+    return KEYWORD
+  end
+
+  # 
+  # Get the email subject.
+  #
+  def subject
+    return find_child_value SUBJECT
+  end
+  
+  # Get the email body.
+  #
+  def body
+    return find_child_value BODY
+  end
+  
+  # Get the email to.
+  #
+  def to
+    return find_child_value TO
+  end
+  
+  # Get the email from.
+  #
+  def from
+    return find_child_value FROM
+  end
+
+  # 
+  # Get the mail message to send.
+  # 
+  # Returns:
+  #   A mail message.
+  # 
+  def get_msg
+    return Msg.new( to, from, subject, body )
+  end
+
+
+  # ---------------------------------------------------------------------
+  #    Children
+  # ---------------------------------------------------------------------
+
+  # Does this object have children to add when an object
+  # is created in interactive mode?
+  # This does not apply during obj load, etc.
+  def add_children_on_create?
+    return true
+  end
+
+  # Add children to this object.
+  # This is used by containers to add children needed
+  # for default configurations.
+  def add_default_children
+    fac = @engine.factory
+    fac.create_string TO, '', self
+    fac.create_string FROM, '', self
+    fac.create_string SUBJECT, '', self
+    fac.create_text BODY, '', self
+  end
+
+
+  # ---------------------------------------------------------------------
+  #    Messages
+  # ---------------------------------------------------------------------
+
+  #
+  # Get a list of message names that this object receives.
+  #
+  def self.messages
+    return super + [ 'send' ]
+  end
+
+  #
+  # Send an email.
+  #
+  def msg_send
+    if @params&.token_count&.positive?
+      smtp_pn = Gloo::Core::Pn.new( @engine, @params.tokens.first )
+      unless smtp_pn&.exists?
+        @engine.err 'SMTP server does not exist'
+        return
+      end
+    else
+      @engine.err 'Email Message is required'
+      return
+    end
+    config = smtp_pn.resolve.get_config
+    msg = get_msg
+
+    smtp = Smtp.new( @engine, config )
+    smtp.send msg
+  end
+
+  # ---------------------------------------------------------------------
+  #    Object Documentation
+  # ---------------------------------------------------------------------
+
+  #
+  # Get the object's documentation data.
+  #
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :shortcut => KEYWORD,
+      :description => 'An email message — the recipient, sender, ' \
+        'subject and body to send.',
+      :children => [
+        'to (string) — The recipient email address.',
+        'from (string) — The sender email address.',
+        'subject (string) — The email subject.',
+        'body (text) — The email body.'
+      ],
+      :messages => [
+        'send ({smtp.path}) — Send this message using the given SMTP configuration object. A parameter is required: the path to an email_smtp object.'
+      ],
+      :notes => 'No vault documentation exists for this object type — ' \
+        'this was authored directly from the code.',
+      :examples => <<~EXAMPLES.strip
+        mail [can] :
+          smtp [email_smtp] :
+            server : smtp.example.com
+            port : 587
+            username : me@example.com
+            password : secret
+
+          msg [email] :
+            to : someone@example.com
+            from : me@example.com
+            subject : Hello
+            body [text] : BEGIN
+              A message sent from gloo.
+              END
+
+          on_load [script] :
+            tell mail.msg to send (mail.smtp)
+      EXAMPLES
+    }
+  end
+
+end

data/lib/email_smtp.rb

@@ -0,0 +1,166 @@
+#
+# An email SMTP configuration object
+#
+require 'config'
+require 'msg'
+require 'smtp'
+
+class EmailSmtp < Gloo::Core::Obj
+
+  KEYWORD = 'email_smtp'.freeze
+  SERVER = 'server'.freeze
+  PORT = 'port'.freeze
+  USERNAME = 'username'.freeze
+  PASSWORD = 'password'.freeze
+
+
+  #
+  # The name of the object type.
+  #
+  def self.typename
+    return KEYWORD
+  end
+
+  #
+  # The short name of the object type.
+  # Same as the typename.
+  #
+  def self.short_typename
+    return KEYWORD
+  end
+
+  # 
+  # Get the email server.
+  #
+  def server
+    return find_child_value SERVER
+  end
+
+  # Get the email port.
+  #
+  def port
+    return find_child_value PORT
+  end
+
+  # Get the email username.
+  #
+  def username
+    return find_child_value USERNAME
+  end
+
+  # Get the email password.
+  #
+  def password
+    return find_child_value PASSWORD
+  end
+
+
+  # ---------------------------------------------------------------------
+  #    Children
+  # ---------------------------------------------------------------------
+
+  # Does this object have children to add when an object
+  # is created in interactive mode?
+  # This does not apply during obj load, etc.
+  def add_children_on_create?
+    return true
+  end
+
+  # Add children to this object.
+  # This is used by containers to add children needed
+  # for default configurations.
+  def add_default_children
+    fac = @engine.factory
+    fac.create_string SERVER, '', self
+    fac.create_string PORT, '', self
+    fac.create_string USERNAME, '', self
+    fac.create_string PASSWORD, '', self
+  end
+
+
+  # ---------------------------------------------------------------------
+  #    Messages
+  # ---------------------------------------------------------------------
+
+  #
+  # Get a list of message names that this object receives.
+  #
+  def self.messages
+    return super + [ 'send' ]
+  end
+
+  #
+  # Send an email.
+  #
+  def msg_send
+    if @params&.token_count&.positive?
+      msg_pn = Gloo::Core::Pn.new( @engine, @params.tokens.first )
+      unless msg_pn&.exists?
+        @engine.err 'Email Message does not exist'
+        return
+      end
+    else
+      @engine.err 'Email Message is required'
+      return
+    end
+    msg = msg_pn.resolve.get_msg
+
+    smtp = Smtp.new( @engine, get_config )
+    smtp.send msg
+  end
+
+  #
+  # Get the configuration for this SMTP server.
+  #
+  def get_config
+    config = Config.new( server, port, username, password )
+    return config
+  end
+
+  # ---------------------------------------------------------------------
+  #    Object Documentation
+  # ---------------------------------------------------------------------
+
+  #
+  # Get the object's documentation data.
+  #
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :shortcut => KEYWORD,
+      :description => 'An email SMTP configuration object, used to ' \
+        'send email messages.',
+      :children => [
+        'server (string) — The SMTP server host.',
+        'port (string) — The SMTP server port.',
+        'username (string) — The username with which to connect.',
+        "password (string) — The user's password."
+      ],
+      :messages => [
+        'send ({message.path}) — Send the given email message object using this SMTP configuration. A parameter is required: the path to an email message object.'
+      ],
+      :notes => 'No vault documentation exists for this object type — ' \
+        'this was authored directly from the code.',
+      :examples => <<~EXAMPLES.strip
+        mail [can] :
+          smtp [email_smtp] :
+            server : smtp.example.com
+            port : 587
+            username : me@example.com
+            password [alias] : mail.get_passwd.result
+
+          msg [email] :
+            to : someone@example.com
+            from : me@example.com
+            subject : Hello
+            body [text] : BEGIN
+              A message sent from gloo.
+              END
+
+          on_load [script] :
+            tell mail.smtp to send (mail.msg)
+      EXAMPLES
+    }
+  end
+
+end

data/lib/gloo-email.rb

@@ -0,0 +1,24 @@
+# 
+# Shim to allow `require 'gloo-email'`
+# 
+# This file is loaded when someone does `require 'gloo-email'`
+# 
+require 'email_smtp'
+require 'email_imap'
+require 'email_msg'
+
+# 
+# Registers the extension.
+# 
+class EmailInit < Gloo::Plugin::Base
+
+    # 
+    # Register verbs and objects.
+    # 
+    def register( callback )
+      callback.register_obj( EmailSmtp )
+      callback.register_obj( EmailImap )
+      callback.register_obj( EmailMsg )
+    end
+
+end

data/lib/msg.rb

@@ -0,0 +1,45 @@
+# 
+# A Simple email message object
+# 
+
+class Msg
+
+  attr_accessor :to, :from, :subject, :body
+  
+  # 
+  # Initialize a new email message.
+  # 
+  def initialize( to = nil, from = nil, subject = nil, body = nil )
+    @to = to
+    @from = from
+    @subject = subject
+    @body = body
+  end
+
+  # 
+  # Get the mail message to send.
+  # 
+  # Returns:
+  #   A mail message.
+  # 
+  def get_mail
+    mail = Mail.new
+    mail.from = @from
+    mail.to = @to
+    mail.subject = @subject
+    mail.body = @body
+    return mail
+  end
+
+  # 
+  # Convert the message to a string.
+  # This is used for debugging and logging.
+  # 
+  # Returns:
+  #   A string representation of the message.
+  # 
+  def to_s
+    return "Msg(to: #{@to}, from: #{@from}, subject: #{@subject}, body: #{@body})"
+  end
+
+end

data/lib/smtp.rb

@@ -0,0 +1,55 @@
+# 
+# An SMTP email sender
+# 
+require 'mail'
+require 'config'
+require 'msg'
+
+class Smtp
+
+  attr_accessor :config
+  
+  # 
+  # Initialize a new SMTP email sender.
+  # 
+  def initialize( engine, config )
+    @engine = engine
+    @config = config
+  end
+
+  # 
+  # Send an email message.
+  # 
+  def send msg
+    begin
+      configure
+      mail = msg.get_mail
+      mail.deliver!
+      @engine.log.info "Email sent successfully!"
+    rescue => ex
+      @engine.log_exception ex
+    end
+  end
+
+  # 
+  # Configure the SMTP settings.
+  # 
+  def configure
+    svr = @config.host
+    prt = @config.port
+    usr = @config.username
+    pwd = @config.password
+    
+    Mail.defaults do
+      delivery_method :smtp, {
+        address: svr,
+        port: prt,
+        user_name: usr,
+        password: pwd,
+        authentication: :plain,
+        enable_starttls_auto: true
+      }
+    end
+  end
+
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: gloo-email
+version: !ruby/object:Gem::Version
+  version: '1.0'
+platform: ruby
+authors:
+- Eric Crane
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.14.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.14.2
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 13.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 13.0.1
+description: Adds Gloo Email support to Gloo.
+email:
+- eric.crane@mac.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/config.rb
+- lib/email_imap.rb
+- lib/email_msg.rb
+- lib/email_smtp.rb
+- lib/gloo-email.rb
+- lib/msg.rb
+- lib/smtp.rb
+homepage: https://github.com/ecrane/gloo
+licenses:
+- MIT
+metadata:
+  gloo.type: core-library
+  documentation_uri: https://github.com/ecrane/gloo
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.17
+specification_version: 4
+summary: Gloo core library. Gloo Email support.
+test_files: []