sfmc_emailer 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 239758da91fdc505fd377b2c9172189080ea70c8fce9c134676fce57c25ceb9f
+  data.tar.gz: 2acca7c2385a445ecf177714c32844edbf716af7604c99cbea348efde1b2eeca
+SHA512:
+  metadata.gz: 83baaeca028d0e4240470505c6e2fc12d962944d834998280cdfe095c3fd16377cd74525f5525c08b406735557206a7364392f11648a8eff593eab7a5e35ad50
+  data.tar.gz: a88a332638e599815165adc83636fad1974db6fcc05d7ed11b674cd49ca9e67a7eb28ab3f3e9afdc2dc172a58ccc9ca6528c86db2f2e4d86bdfde9d0edf88ae3

data/lib/sfmc/assets/asset.rb

@@ -0,0 +1,7 @@
+module SFMC
+  module Assets
+    class Asset < SFMCBase
+      endpoint "/asset/v1/content/assets"
+    end
+  end
+end

data/lib/sfmc/authentication.rb

@@ -0,0 +1,25 @@
+module SFMC
+  class Authentication < SFMCBase
+    endpoint "/v2/token"
+
+    AUTH_PARAMS = {
+      client_id: SFMCBase.client_id,
+      client_secret: SFMCBase.client_secret,
+      grant_type: 'client_credentials',
+    }.freeze
+    private_constant :AUTH_PARAMS
+
+    def self.set_bearer_token(refresh: false)
+      # Ensures the token is present & not expired
+      token_invalid = SFMCBase.access_token.nil? || SFMCBase.access_token_expires_at < Time.now
+      return unless refresh || token_invalid
+
+      set_base_uri 'auth'
+      response = create(nil, AUTH_PARAMS, true)
+
+      SFMCBase.access_token = response.access_token
+      SFMCBase.access_token_expires_at = Time.now + response.expires_in
+      SFMCBase.headers Authorization: "Bearer #{SFMCBase.access_token}"
+    end
+  end
+end

data/lib/sfmc/contacts/contact_key.rb

@@ -0,0 +1,24 @@
+module SFMC
+  module Contacts
+    class ContactKey < SFMCBase
+      endpoint "/contacts/v1/addresses/email/search"
+
+      def self.find(emails, max = 1)
+        emails = [emails] unless emails.is_a? Array
+
+        params = {
+          channelAddressList: emails,
+          maximumCount: max,
+        }
+        response = create(nil, params)
+
+        response.channelAddressResponseEntities.map do |channel|
+          key = channel[:contactKeyDetails].first[:contactKey]
+          raise SFMC::Errors::NotFoundError if key.nil?
+
+          key
+        end
+      end
+    end
+  end
+end

data/lib/sfmc/errors.rb

@@ -0,0 +1,37 @@
+module SFMC
+  module Errors
+    # rubocop:disable Layout/EmptyLineBetweenDefs
+    class BadRequestError < StandardError; end
+    class UnauthorizedError < StandardError; end
+    class ForbiddenError < StandardError; end
+    class NotFoundError < StandardError; end
+    class UnprocessableEntityError < StandardError; end
+    class APIError < StandardError; end
+    # rubocop:enable Layout/EmptyLineBetweenDefs
+
+    def error_class(code)
+      case code.to_i
+      when 400
+        BadRequestError
+      when 401
+        UnauthorizedError
+      when 403
+        ForbiddenError
+      when 404
+        NotFoundError
+      when 422
+        UnprocessableEntityError
+      else
+        APIError
+      end
+    end
+
+    def error_message(response)
+      error = response.parsed_response
+      documentation_msg = ", Documentation: #{error['documentation']}"
+      add_documentation = error['documentation'].present?
+
+      "#{response.code}, API error code: #{error['errorcode']}, Message: #{error['message']}" + (add_documentation ? documentation_msg : '')
+    end
+  end
+end

data/lib/sfmc/helpers.rb

@@ -0,0 +1,23 @@
+module SFMC::Helpers
+  def init(config)
+    @subdomain = config[:subdomain]
+    @client_id = config[:client_id]
+    @client_secret = config[:client_secret]
+    @default_send_classification = config[:default_send_classification]
+    @default_subscriber_list = config[:default_subscriber_list]
+    @default_data_extension = config[:default_data_extension]
+    @default_bcc = config[:default_bcc]
+  end
+
+  def set_base_uri(protocol = 'rest')
+    base_uri "https://#{SFMC::SFMCBase.subdomain}.#{protocol}.marketingcloudapis.com"
+  end
+
+  def get_subscriber_key(email_address)
+    begin
+      SFMC::Contacts::ContactKey.find(email_address).first
+    rescue SFMC::Errors::NotFoundError
+      SecureRandom.uuid
+    end
+  end
+end

data/lib/sfmc/sfmc_base.rb

@@ -0,0 +1,85 @@
+require 'httparty'
+
+module SFMC
+  class SFMCBase
+    include HTTParty
+    extend SFMC::Helpers
+    extend SFMC::Errors
+
+    format :json
+
+    NAME_TO_METHOD = {
+      find: :get,
+      create: :post,
+      update: :patch,
+      destroy: :delete,
+    }.freeze
+
+    class << self
+      # This protects against an invalid access token, for instance if the SFMC password was changed
+      def authenticate_and_retry(method, endpoint, params, retry_count)
+        SFMC::Authentication.set_bearer_token refresh: true
+        request method, endpoint, params, retry_count - 1
+      end
+
+      def request(http_method, endpoint, params = {}, retry_count = 1, is_authenticating: false)
+        unless is_authenticating
+          set_base_uri
+          SFMC::Authentication.set_bearer_token
+        end
+
+        received = method(http_method).call(endpoint, body: params, headers: SFMCBase.headers)
+        payload = OpenStruct.new(received.with_indifferent_access)
+
+        return payload if received.response.is_a? Net::HTTPSuccess
+
+        raise error_class(received.code), error_message(received) unless received.code == 401 && retry_count > 0
+
+        # The access token was invalidated. In this case, by default, we will retry once
+        authenticate_and_retry http_method, endpoint, params, retry_count
+      end
+
+      protected
+
+      attr_accessor :access_token,
+                    :access_token_expires_at,
+                    :subdomain,
+                    :client_id,
+                    :client_secret,
+                    :default_send_classification,
+                    :default_subscriber_list,
+                    :default_data_extension,
+                    :default_bcc
+
+      def endpoint(path)
+        return if defined? @endpoint_defined
+
+        @endpoint_defined = true
+        extend @endpoint_module = Module.new
+
+        # Defines the CRUD methods find, create, update, and destroy
+        # Each method optionally accepts an id of a resource, params, and auth
+        # The auth param should never be used directly
+        @endpoint_module.module_eval do
+          NAME_TO_METHOD.each do |name, method|
+            define_method(name) do |id = nil, params = nil, auth = false|
+              path_with_id = path + "/#{id}"
+
+              request method, path_with_id, params, is_authenticating: auth
+            end
+          end
+
+          # Defines a resource query method
+          # The query param is the query to be sent,
+          # and the optional fields param, when set, will only return those specific fields
+          define_method("query") do |query, fields = nil|
+            query += "&$fields=#{URI::Parser.new.escape(fields)}" unless fields.nil?
+            full_query = query.presence ? "?$filter=#{query}" : ''
+
+            find(full_query)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sfmc/transactional/email.rb

@@ -0,0 +1,51 @@
+module SFMC
+  module Transactional
+    class Email < SFMCBase
+      endpoint "/messaging/v1/email/messages"
+
+      # If an email hasn't ever been sent then we will not have an email send definition
+      # We're waiting a minute for the send definition to fully be initialized
+      # Thankfully this is a rare edge case
+      def self.create_email_send_definition_and_retry(name, to, params)
+        asset = SFMC::Assets::Asset.query("name eq '#{name}'", 'customerKey')
+        raise SFMC::Errors::BadRequestError, "No emails found with name #{name}" if asset.count == 0
+
+        consumer_key = asset.items.first["customerKey"]
+
+        SFMC::Transactional::SendDefinition.create(name, consumer_key)
+
+        # Even though the send def is "Active" it won't function for another minute
+        delay(run_at: 70.seconds.from_now).send_email(email: name, to: to, params: params, create_email_if_needed: false)
+      end
+
+      # Will attempt once to create a new email send definition if one isn't found
+      def self.send_email(email:, to:, params: {}, create_email_if_needed: true)
+        subscriber_key = get_subscriber_key(to)
+        message_key = SecureRandom.uuid
+        data_extension_params = {
+          SubscriberKey: subscriber_key,
+          EmailAddress: to,
+          **params,
+        }
+
+        email_params = {
+          definitionKey: email,
+          recipient: {
+            contactKey: subscriber_key,
+            to: to,
+            attributes: data_extension_params,
+          },
+        }
+
+        # If SFMC::Errors::NotFoundError is raised then we need to create an email send definition
+        begin
+          create(message_key, email_params)
+        rescue SFMC::Errors::NotFoundError
+          raise unless create_email_if_needed
+
+          create_email_send_definition_and_retry(email, to, params)
+        end
+      end
+    end
+  end
+end

data/lib/sfmc/transactional/send_definition.rb

@@ -0,0 +1,40 @@
+module SFMC
+  module Transactional
+    class SendDefinition < SFMCBase
+      endpoint "/messaging/v1/email/definitions"
+
+      def self.refresh(definition_key)
+        update definition_key, status: 'Inactive'
+        update definition_key, status: 'Active'
+      end
+
+      def self.create(
+        definition_key,
+        customer_key,
+        send_classification = nil,
+        subscriber_list = nil,
+        data_extension = nil,
+        bcc = []
+      )
+        params = {
+          classification: SFMCBase.default_send_classification || send_classification,
+          definitionKey: definition_key,
+          name: definition_key,
+          status: 'Active',
+          subscriptions: {
+            list: SFMCBase.default_subscriber_list || subscriber_list,
+            dataExtension: SFMCBase.default_data_extension || data_extension,
+          },
+          content: {
+            customerKey: customer_key,
+          },
+          options: {
+            bcc: SFMCBase.default_bcc || bcc,
+          },
+        }
+
+        super(nil, params)
+      end
+    end
+  end
+end

data/lib/sfmc/triggered/email.rb

@@ -0,0 +1,20 @@
+module SFMC
+  module Triggered
+    class Email < SFMCBase
+      def self.send_email(email:, to:, params: {})
+        endpoint_url = "/messaging/v1/messageDefinitionSends/key:#{email}/send"
+        email_params = {
+          To: {
+            Address: to,
+            SubscriberKey: get_subscriber_key(to),
+            ContactAttributes: {
+              SubscriberAttributes: params,
+            },
+          },
+        }
+
+        request(:post, endpoint_url, email_params.as_json)
+      end
+    end
+  end
+end

data/lib/sfmc_emailer.rb

@@ -0,0 +1,9 @@
+require 'sfmc/errors'
+require 'sfmc/helpers'
+require 'sfmc/sfmc_base'
+require 'sfmc/authentication'
+require 'sfmc/assets/asset'
+require 'sfmc/contacts/contact_key'
+require 'sfmc/transactional/email'
+require 'sfmc/transactional/send_definition'
+require 'sfmc/triggered/email'

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: sfmc_emailer
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Angel Ruiz-Bates
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-10-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.20'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.20'
+description: API wrapper for Salesforce Marketing Cloud's Transactional and Triggered
+  Send APIs
+email: angeljrbt@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/sfmc/assets/asset.rb
+- lib/sfmc/authentication.rb
+- lib/sfmc/contacts/contact_key.rb
+- lib/sfmc/errors.rb
+- lib/sfmc/helpers.rb
+- lib/sfmc/sfmc_base.rb
+- lib/sfmc/transactional/email.rb
+- lib/sfmc/transactional/send_definition.rb
+- lib/sfmc/triggered/email.rb
+- lib/sfmc_emailer.rb
+homepage: https://rubygems.org/gems/sfmc_emailer
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+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: 3.1.6
+signing_key:
+specification_version: 4
+summary: API wrapper for SFMC
+test_files: []