RubyGems - txbr - Versions diffs - 1.1.1 → 2.0.0 - Mend

txbr 1.1.1 → 2.0.0

Files changed (26) hide show

checksums.yaml +4 -4
data/README.md +16 -10
data/lib/txbr.rb +11 -23
data/lib/txbr/braze_api.rb +4 -20
data/lib/txbr/campaign.rb +39 -0
data/lib/txbr/campaign_handler.rb +24 -0
data/lib/txbr/campaigns_api.rb +29 -0
data/lib/txbr/content_tag.rb +64 -0
data/lib/txbr/email_template.rb +9 -40
data/lib/txbr/email_template_handler.rb +1 -1
data/lib/txbr/email_templates_api.rb +33 -0
data/lib/txbr/liquid.rb +5 -0
data/lib/txbr/liquid/connected_content_tag.rb +99 -0
data/lib/txbr/metadata.rb +30 -0
data/lib/txbr/request_methods.rb +0 -2
data/lib/txbr/template.rb +54 -0
data/lib/txbr/template_group.rb +50 -0
data/lib/txbr/version.rb +1 -1
data/spec/campaign_spec.rb +136 -0
data/spec/campaigns_api_spec.rb +71 -0
data/spec/email_template_spec.rb +25 -10
data/spec/{braze_api_spec.rb → email_templates_api_spec.rb} +11 -48
data/spec/shared_examples/api_errors.rb +40 -0
data/spec/uploader_spec.rb +10 -4
metadata +16 -4
data/lib/txbr/email_template_component.rb +0 -96

checksums.yaml CHANGED

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62e08fd199a92f5d5f3023cd24e118384402b8124cfb70922e06ac727a8ed609
-  data.tar.gz: fb507665ce3f234fcab1c1b8a34954b3458f23639f41dd5b4b53423c8d2725ff
+  metadata.gz: 9d1499776cb6db1539a2d2701bfddd4e182f9b3246b28d13e245e97426002902
+  data.tar.gz: 4b4ad8fb50db7bc76fa87e0435df0de19e0d6809dc215584eb0e8b403de97b5c
 SHA512:
-  metadata.gz: 55a839b383684e07541c2af875074e69c7fe5eff1d0d90f1a684b1d4621a226d4550bf611e5186f7d0ed81775d9d89ee8f7e9305eeb5ee458fdbc198e257300d
-  data.tar.gz: 401b4b866e1805a26a782aba41ceb62a200a3aab02591279ed149b92282af4c048be93160d666d8b052feff0bf0fb97fe68a30c9733462f3ba2d805b242353fb
+  metadata.gz: da9cf5bef80c81a529717678d384a5e3eae78d26b8e4cffd0b53ca78ac8cd4cb10690d5a0211b16082ca20f719a60345e63a62be3b9598f9e1290322135485a3
+  data.tar.gz: 6d026e747fda2c285f3a792b46babbe2dc85e71d7fb27168b097efaac820188fc2c7a75cb6e5a0b7d8a7162e9503ace863674cce4635f2e655053c2f36da990a

data/README.md CHANGED

@@ -17,7 +17,7 @@ Here's an example template for the impatient:
   <head>
     {% assign project_slug = "my_transifex_project" %}
     {% assign resource_slug = "my_transifex_resource" %}
-    {% connected_content https://your_txbr_server.com/strings.json?project_slug={{project_slug}}&resource_slug={{resource_slug}}&locale={{${language} | default: 'en'}}&strings_format=YML :basic_auth txbr :save strings %}
+    {% connected_content https://your_txbr_server.com/strings.json?project_slug={{project_slug}}&resource_slug={{resource_slug}}&locale={{${language} | default: 'en'}}&strings_format=YML :basic_auth txbr :save strings :retry %}
   </head>
   <body>
     {{strings.header.title | default: "Buy my stuff!"}}
@@ -25,13 +25,17 @@ Here's an example template for the impatient:
 </html>
 ```
-There are several important bits in the example above:
+### The `connected_content` Tag
-1. Every template you would like Txbr to manage must contain these three required Liquid tags: `assign project_slug`, `assign resource_slug`, and `connected_content`. The first two correspond to the Transifex project and resource in which you would like to store the template's strings, and the third is the mechanism by which translations are fetched and inserted into the template when it is previewed or delivered.
-2. The project slug should correspond to a valid Transifex project. You'll need to create the project in Transifex, then copy the slug from the URL.
-3. The resource slug should be unique within the Transifex project and must only contain uppercase and lowercase letters, numbers, underscores (i.e. "_"), and dashes (i.e. "-"). It's a safe bet to simply use the template's API identifier found at the bottom of the template's configuration page. Txbr itself places no restrictons on and performs no validation against this field, so it can contain any custom slug you want.
-4. The `connected_content` tag fetches translated content from Transifex using the project and resource slugs you assigned earlier in the locale of the "current" user. When previewing your template, the locale can be set in the left-hand sidebar via a simulated current user.
-5. Notice the `{{strings.header.title | default: "Buy my stuff!}}` tag. This defines and fetches a string at the key `header.title`, with a default English value of "Buy my stuff!" Txbr uses this key and default value to construct the translation file it will submit to Transifex. Providing a default value allows for easy template construction and previewing, since your template probably won't be translated immediately. Braze will fall back to this value if the translation doesn't yet exist. Liquid tags that do not specify a default value will not be included in the submission to Transifex. Finally, pay close attention to the `strings.` prefix. It corresponds to the `connected_content` tag's `:save strings` option. The `:save` option tells Braze to store the translated strings in a template variable called `strings`, which can then be used to grab individual strings. The value given to `:save` must be the same value used as the key prefix. For example, simply typing `{{header.title}}` won't work.
+Every template you would like Txbr to manage should include at least one `connected_content` tag. Each tag must include a URL with `project_slug` and `resource_slug` as GET parameters. These correspond to the Transifex project and resource you would like to store the template's strings in.
+The project slug should correspond to a valid Transifex project. You'll need to create the project in Transifex, then copy the slug from the URL.
+The resource slug should be unique within the Transifex project and must only contain uppercase and lowercase letters, numbers, underscores (i.e. "\_"), and dashes (i.e. "-"). It's a safe bet to simply use the template's API identifier found at the bottom of the template's configuration page. Txbr itself places no restrictons on and performs no validation against this field, so it can contain any custom slug you want.
+### Translating Content
+Strings can be inserted into the template using liquid tags. For example, the `{{strings.header.title | default: "Buy my stuff!}}` tag above defines and fetches a string at the key `header.title`, with a default English value of "Buy my stuff!" Txbr uses this key and default value to construct the translation file it will ultimately submit to Transifex. Providing a default value allows for easy template construction and previewing, since your template probably won't be translated immediately. Braze will fall back to this value if the translation doesn't yet exist. Liquid tags that do not specify a default value will not be included in the submission to Transifex. Finally, pay close attention to the `strings.` prefix. It corresponds to the `connected_content` tag's `:save strings` option. The `:save` option tells Braze to store the translated strings in a template variable called `strings`, which can then be used to grab individual strings. The value given to `:save` must be the same value used as the key prefix. For example, simply typing `{{header.title}}` won't work.
 ### Enabling Translation
@@ -41,6 +45,8 @@ Template translation is enabled by default. To skip translating a given template
 {% assign translation_enabled = false %}
 ```
+**NOTE**: The `translation_enabled` variable assignment can be placed anywhere in the template, and affects the entire template. In other words, it does not just disable translations for content that comes after it. Its presence disables translations template-wide.
 Configuration
 ---
@@ -58,10 +64,10 @@ projects:
 ```
-1. The `handler_id` indicates what kind of content this project should contain. In this case, we're translating email templates, the only currently supported option.
+1. The `handler_id` indicates what kind of content this project should contain. In this case, we're translating email templates. Campaigns are also supported via the handler ID `campaigns`, and are configured using the same options as email templates.
 2. Your Transifex username and password should have access to the Transifex projects you want to submit content to. You can configure access via Transifex's access control system.
 3. The `strings_format` option must be one of [Transifex's supported formats](https://docs.transifex.com/formats/introduction).
-4. The `source_lang` option should be the language in which your source strings are written in. In other words, it should be the language in which the `default:` text is written in your template's Liquid tags.
+4. The `source_lang` option should be the language in which your source strings are written. In other words, it should be the language in which the `default:` text is written in your template's Liquid tags.
 ### Using Configuration
@@ -94,7 +100,7 @@ Txbr is both a library and a server. It provides access to Transifex resources v
 ### API Endpoint
-Txbr provides a single API endpoint for retrieving translated content from Transifex. You'll need to stand up a Txbr server somewhere and make it publicly available on the Internet. The URL to your server will be used in the `connected_content` tag in your Braze templates (see above).
+Txbr provides a single API endpoint for retrieving translated content from Transifex. You'll need to stand up a Txbr server somewhere and make it publicly available on the Internet. The URL to your server should then be used in the `connected_content` tag in your Braze templates (see above).
 The endpoint will be available at http://your_txbr_server.com/strings.json and accepts the following required GET parameters:

data/lib/txbr.rb CHANGED

@@ -3,14 +3,23 @@ require 'liquid'
 module Txbr
   autoload :Application,            'txbr/application'
   autoload :BrazeApi,               'txbr/braze_api'
+  autoload :Campaign,               'txbr/campaign'
+  autoload :CampaignHandler,        'txbr/campaign_handler'
+  autoload :CampaignsApi,           'txbr/campaigns_api'
+  autoload :ContentTag,             'txbr/content_tag'
   autoload :Commands,               'txbr/commands'
   autoload :Config,                 'txbr/config'
   autoload :EmailTemplate,          'txbr/email_template'
   autoload :EmailTemplateComponent, 'txbr/email_template_component'
   autoload :EmailTemplateHandler,   'txbr/email_template_handler'
+  autoload :EmailTemplatesApi,      'txbr/email_templates_api'
+  autoload :Liquid,                 'txbr/liquid'
+  autoload :Metadata,               'txbr/metadata'
   autoload :Project,                'txbr/project'
   autoload :RequestMethods,         'txbr/request_methods'
   autoload :StringsManifest,        'txbr/strings_manifest'
+  autoload :Template,               'txbr/template'
+  autoload :TemplateGroup,          'txbr/template_group'
   autoload :Uploader,               'txbr/uploader'
   autoload :Utils,                  'txbr/utils'
@@ -52,28 +61,7 @@ module Txbr
   end
   Txbr.register_handler('email-templates', Txbr::EmailTemplateHandler)
+  Txbr.register_handler('campaigns', Txbr::CampaignHandler)
-  class ConnectedContentTag < Liquid::Tag
-    # This is a regular expression to pull out the variable in
-    # which to store the value returned from the call made by
-    # the connected_content filter. For example, if
-    # connected_content makes a request to http://foo.com and is
-    # told to store the results in a variable called "strings",
-    # the API response will then be accessible via the normal
-    # Liquid variable mechanism, i.e. {{...}}. Say the API at
-    # foo.com returned something like {"bar":"baz"}, then the
-    # template might contain {{strings.bar}}, which would print
-    # out "baz".
-    PREFIX_RE = /:save\s+(#{Liquid::Lexer::IDENTIFIER})/
-    attr_reader :tag_name, :prefix
-    def initialize(tag_name, arg, *)
-      @tag_name = tag_name
-      @prefix = arg.match(PREFIX_RE).captures.first
-    end
-  end
-  Liquid::Template.register_tag(:connected_content, ConnectedContentTag)
+  ::Liquid::Template.register_tag(:connected_content, Txbr::Liquid::ConnectedContentTag)
 end

data/lib/txbr/braze_api.rb CHANGED

@@ -3,10 +3,6 @@ require 'faraday_middleware'
 module Txbr
   class BrazeApi
-    TEMPLATE_BATCH_SIZE = 35
-    TEMPLATE_LIST_PATH = 'templates/email/list'.freeze
-    TEMPLATE_INFO_PATH = 'templates/email/info'.freeze
     include RequestMethods
     attr_reader :api_key, :api_url
@@ -17,24 +13,12 @@ module Txbr
       @connection = connection
     end
-    def each_email_template(offset: 1, &block)
-      return to_enum(__method__, offset: offset) unless block_given?
-      loop do
-        templates = get_json(
-          TEMPLATE_LIST_PATH,
-          offset: offset,
-          limit: TEMPLATE_BATCH_SIZE
-        )
-        templates['templates'].each(&block)
-        offset += templates['templates'].size
-        break if templates['templates'].size < TEMPLATE_BATCH_SIZE
-      end
+    def email_templates
+      @email_templates ||= EmailTemplatesApi.new(self)
     end
-    def get_email_template_details(email_template_id:)
-      get_json(TEMPLATE_INFO_PATH, email_template_id: email_template_id)
+    def campaigns
+      @campaigns ||= CampaignsApi.new(self)
     end
     private

data/lib/txbr/campaign.rb ADDED

@@ -0,0 +1,39 @@
+require 'liquid'
+module Txbr
+  class Campaign
+    attr_reader :project, :campaign_id
+    def initialize(project, campaign_id)
+      @project = project
+      @campaign_id = campaign_id
+    end
+    def each_resource(&block)
+      return to_enum(__method__) unless block_given?
+      template_group.each_resource(&block)
+    end
+    private
+    def template_group
+      @template_group ||= TemplateGroup.new(campaign_name, templates, project)
+    end
+    def templates
+      details['messages'].map do |message_id, props|
+        Txbr::Template.new(message_id, ::Liquid::Template.parse(props['message']))
+      end
+    end
+    def campaign_name
+      details['name']
+    end
+    def details
+      @details ||= project.braze_api.campaigns.details(
+        campaign_id: campaign_id
+      )
+    end
+  end
+end

data/lib/txbr/campaign_handler.rb ADDED

@@ -0,0 +1,24 @@
+module Txbr
+  class CampaignHandler
+    attr_reader :project
+    def initialize(project)
+      @project = project
+    end
+    def each_resource(&block)
+      return to_enum(__method__) unless block_given?
+      each_campaign { |campaign| campaign.each_resource(&block) }
+    end
+    # private
+    def each_campaign
+      return to_enum(__method__) unless block_given?
+      project.braze_api.campaigns.each do |campaign|
+        yield Campaign.new(project, campaign['id'])
+      end
+    end
+  end
+end

data/lib/txbr/campaigns_api.rb ADDED

@@ -0,0 +1,29 @@
+module Txbr
+  class CampaignsApi
+    CAMPAIGN_BATCH_SIZE = 100  # from braze docs
+    CAMPAIGN_LIST_PATH = 'campaigns/list'.freeze
+    CAMPAIGN_DETAILS_PATH = 'campaigns/details'.freeze
+    attr_reader :braze_api
+    def initialize(braze_api)
+      @braze_api = braze_api
+    end
+    def each(&block)
+      return to_enum(__method__) unless block_given?
+      page = 0
+      loop do
+        campaigns = braze_api.get_json(CAMPAIGN_LIST_PATH, page: page)
+        campaigns['campaigns'].each(&block)
+        break if campaigns['campaigns'].size < CAMPAIGN_BATCH_SIZE
+        page += 1
+      end
+    end
+    def details(campaign_id:)
+      braze_api.get_json(CAMPAIGN_DETAILS_PATH, campaign_id: campaign_id)
+    end
+  end
+end

data/lib/txbr/content_tag.rb ADDED

@@ -0,0 +1,64 @@
+module Txbr
+  class ContentTag
+    attr_reader :liquid_template, :liquid_tag
+    def initialize(liquid_template, liquid_tag)
+      @liquid_template = liquid_template
+      @liquid_tag = liquid_tag
+    end
+    def metadata
+      @metadata ||= begin
+        # Render the template to implicitly populate the metadata hash inside
+        # the liquid tag object. We do this because we encourage templates to
+        # set local variables for the project and resource slugs. It's less
+        # error-prone to let Liquid do the template evaluation instead of
+        # grepping through the nodelist looking for assignment statements.
+        liquid_template.render
+        liquid_tag.metadata
+      end
+    end
+    def strings_manifest
+      @strings_manifest ||= StringsManifest.new.tap do |manifest|
+        extract_strings_from(liquid_template.root, manifest)
+      end
+    end
+    private
+    def extract_strings_from(root, manifest)
+      return unless root.nodelist
+      root.nodelist.each do |node|
+        case node
+          # We only care about Liquid variables, which are written
+          # like {{prefix.foo.bar}}. We identify the prefix (i.e.
+          # the first lookup, or path segment) to verify it's
+          # associated with a connected_content call. Then we add
+          # the prefix and the rest of the lookups to the strings
+          # manifest along with the value. The prefix is used to
+          # divide the strings into individual Transifex resources
+          # while the rest of the lookups form the string's key.
+          when ::Liquid::Variable
+            next unless node.name.is_a?(::Liquid::VariableLookup)
+            string_prefix = node.name.name
+            path = node.name.lookups
+            # the English translation (or whatever language your
+            # source strings are written in) is provided using
+            # Liquid's built-in "default" filter
+            next unless string_prefix == metadata.prefix
+            default = node.filters.find { |f| f.first == 'default' }
+            manifest.add(path, default&.last&.first)
+        end
+        if node.respond_to?(:nodelist)
+          extract_strings_from(node, manifest)
+        end
+      end
+    end
+  end
+end

data/lib/txbr/email_template.rb CHANGED

@@ -9,51 +9,20 @@ module Txbr
       @email_template_id = email_template_id
     end
-    def each_resource
+    def each_resource(&block)
       return to_enum(__method__) unless block_given?
-      strings_map.each_pair do |project_slug, resource_map|
-        resource_map.each_pair do |resource_slug, strings_manifest|
-          phrases = strings_manifest.each_string
-            .reject { |_, value| value.nil? }
-            .map do |path, value|
-              { 'key' => path.join('.'), 'string' => value }
-            end
-          next if phrases.empty?
-          resource = Txgh::TxResource.new(
-            project_slug,
-            resource_slug,
-            project.strings_format,
-            project.source_lang,
-            template_name,
-            {},   # lang_map (none)
-            nil   # translation_file (none)
-          )
-          yield Txgh::ResourceContents.from_phrase_list(resource, phrases)
-        end
-      end
+      template_group.each_resource(&block)
     end
     private
-    def strings_map
-      @strings_map ||= %w(body subject preheader).each_with_object({}) do |name, ret|
-        component = EmailTemplateComponent.new(
-          Liquid::Template.parse(details[name])
-        )
-        next unless component.assignments['project_slug']
-        next unless component.assignments['resource_slug']
-        next unless component.translation_enabled?
+    def template_group
+      @template_group ||= TemplateGroup.new(template_name, templates, project)
+    end
-        (ret[component.project_slug] ||= {}).tap do |proj_map|
-          (proj_map[component.resource_slug] ||= StringsManifest.new).tap do |manifest|
-            manifest.merge!(component.strings)
-          end
-        end
+    def templates
+      %w(body subject preheader).map do |name|
+        Txbr::Template.new(::Liquid::Template.parse(details[name]))
       end
     end
@@ -62,7 +31,7 @@ module Txbr
     end
     def details
-      @details ||= project.braze_api.get_email_template_details(
+      @details ||= project.braze_api.email_templates.details(
         email_template_id: email_template_id
       )
     end

data/lib/txbr/email_template_handler.rb CHANGED

@@ -16,7 +16,7 @@ module Txbr
     def each_template
       return to_enum(__method__) unless block_given?
-      project.braze_api.each_email_template do |tmpl|
+      project.braze_api.email_templates.each do |tmpl|
         yield EmailTemplate.new(project, tmpl['email_template_id'])
       end
     end

data/lib/txbr/email_templates_api.rb ADDED

@@ -0,0 +1,33 @@
+module Txbr
+  class EmailTemplatesApi
+    TEMPLATE_BATCH_SIZE = 35
+    TEMPLATE_LIST_PATH = 'templates/email/list'.freeze
+    TEMPLATE_DETAILS_PATH = 'templates/email/info'.freeze
+    attr_reader :braze_api
+    def initialize(braze_api)
+      @braze_api = braze_api
+    end
+    def each(offset: 1, &block)
+      return to_enum(__method__, offset: offset) unless block_given?
+      loop do
+        templates = braze_api.get_json(
+          TEMPLATE_LIST_PATH,
+          offset: offset,
+          limit: TEMPLATE_BATCH_SIZE
+        )
+        templates['templates'].each(&block)
+        offset += templates['templates'].size
+        break if templates['templates'].size < TEMPLATE_BATCH_SIZE
+      end
+    end
+    def details(email_template_id:)
+      braze_api.get_json(TEMPLATE_DETAILS_PATH, email_template_id: email_template_id)
+    end
+  end
+end

data/lib/txbr/liquid.rb ADDED

@@ -0,0 +1,5 @@
+module Txbr
+  module Liquid
+    autoload :ConnectedContentTag, 'txbr/liquid/connected_content_tag'
+  end
+end