studio-engine 0.41.0 → 0.43.0

data/app/services/studio/email_catalog.rb

@@ -61,6 +61,12 @@ module Studio
   module EmailCatalog
     PURPOSE = "email_banner".freeze
 
+    # The LOGO is a separate purpose, not a variant of the banner. They are
+    # different pictures with different rules: a banner is 3:1 artwork that may be
+    # an animated GIF, a logo is a small transparent mark. Sharing one purpose
+    # would make "revert the banner" and "revert the logo" the same row.
+    LOGO_PURPOSE = "email_logo".freeze
+
     # What an email is FOR. Transactional = sent in response to something the
     # recipient did; marketing = sent because we decided to. Kept because
     # turf-monster's catalog carried it and the distinction drives real policy
@@ -74,12 +80,22 @@ module Studio
     #   type          — :transactional or :marketing.
     #   preview       — callable returning a Mail, or nil.
     Entry = Struct.new(:key, :label, :description, :default_asset, :type, :preview,
-                       :default_origin, :aspect_ratio, keyword_init: true) do
+                       :default_origin, :background_origin, :aspect_ratio, :background, :logo, :scrim,
+                       :header, :header_fallback, :subtext, :subject, :body, :cta_text, :cta_color, :cta_enabled, :supports_cta,
+                       keyword_init: true) do
       def to_s = key
       def previewable? = preview.respond_to?(:call)
       # nil-safe: an Entry built directly (the STANDARD seed) may carry no type.
       def marketing? = type.to_s == "marketing"
 
+      # Can this email render a button AT ALL? An email's view has to have
+      # somewhere to send the reader — the sign-in link has a token URL, a
+      # "you're subscribed" note has nothing. OPT-IN, because an entry that has
+      # not said yes cannot be assumed to have a destination, and a Call-to-action
+      # card offered for an email whose template ignores it is a dead control:
+      # the operator ticks the box, saves, and no button ever appears.
+      def supports_cta? = supports_cta == true
+
       # WHOSE artwork default_asset names. Recorded at registration rather than
       # inferred later: by the time the page asks, a resolved asset path looks
       # identical whether the file came from the gem or from the host, and
@@ -88,6 +104,24 @@ module Studio
       # passes default_asset for is that host's own.
       def engine_artwork? = default_origin.to_s != "app"
 
+      # Does THIS APP's artwork layer?
+      #
+      # True when the app registered a background itself — that is the host
+      # saying "layer this email", whatever else it registered. Also true when
+      # the app has registered no artwork at all, so an app that touches nothing
+      # keeps the engine's layered banner.
+      #
+      # False only in the case this exists for: the app registered its OWN flat
+      # asset and merely INHERITED a background it never asked for. turf-monster
+      # is exactly that — its magic_link carries a baked-in .jpg and inherits the
+      # engine's island art — and drawing live text over a picture it never sends
+      # is the failure this whole feature exists to prevent.
+      def layered?
+        return true if background_origin.to_s == "app"
+
+        engine_artwork?
+      end
+
       # The shape of THIS email's banner — the box the page draws and the ratio
       # the upload cropper enforces. Per-entry because the engine's own artwork
       # is 3:1 while turf-monster's eight banners are 2:1; one global constant
@@ -103,23 +137,84 @@ module Studio
         label: "Magic-link sign-in",
         description: "Passwordless sign-in link. Sent whenever someone asks to sign in by email.",
         default_asset: "emails/magic-link.gif",
-        aspect_ratio: 3.0
+        aspect_ratio: 2.0,
+        # Layered artwork: the background animates, the greeting is live HTML on
+        # top. default_asset above stays the flat <img> for a mailer that has not
+        # adopted the layered banner.
+        background: "emails/magic-link-background.gif",
+        logo: "emails/logo-horizontal.png",
+        # The DEFAULT wording, overridable per app on /admin/emails. {name} is
+        # filled from whoever the mailer says the recipient is.
+        header: "Welcome {name}!",
+        header_fallback: "Your Magic Link",
+        subtext: "your sign-in link is below",
+        subject: "Your {app} sign-in link",
+        body: "Tap the button below to sign in to {app} — no password needed. " \
+              "If you don't have an account yet, we'll create one for you.",
+        # The token URL is the destination, so this email really does have a button.
+        supports_cta: true,
+        cta_text: "Sign in to {app}"
       },
       {
-        key: "email_change_confirmation",
-        label: "Email change confirmation",
-        description: "Confirms a new address before the change takes effect.",
-        default_asset: "emails/email-change-confirmation.gif",
-        aspect_ratio: 3.0
+        key: "newsletter_subscribed",
+        label: "Newsletter subscribed",
+        description: "Welcomes someone who has just joined the mailing list.",
+        aspect_ratio: 2.0,
+        # LAYERED-NATIVE: no default_asset. A flat asset is the pre-layered
+        # fallback — artwork with the words baked in, for a mailer that only
+        # knows how to render an <img>. Studio::NewsletterMailer has known how to
+        # layer since the day it was written, so a baked-in copy of the same
+        # picture would be a second thing to keep in sync and never be shown.
+        background: "emails/newsletter-subscribed-background.gif",
+        logo: "emails/logo-horizontal.png",
+        header: "Welcome {name}!",
+        header_fallback: "You're subscribed!",
+        subtext: "you're on the list",
+        subject: "You're subscribed to {app}",
+        body: "Thanks for subscribing to {app}. We'll send the occasional note " \
+              "about what we're building — no more often than it's worth your time.",
+        # NO BUTTON, and no card offering one: a new subscriber has nowhere to be
+        # sent, so subscribed.html.erb renders none and never will.
+        supports_cta: false,
+        # The engine ships this email's preview because it can: the mailer takes
+        # a bare address, so no host sample data is involved. Every other entry's
+        # builder needs records only the host has — this one does not, and an
+        # inherited email with no preview is a row on every app's manager that
+        # cannot be looked at.
+        preview: -> { Studio::NewsletterMailer.subscribed("preview@example.com", name: "Alex") }
       }
     ].freeze
 
-    # Banners render full-bleed at 600px in a 600px card. 1200x600 is the
-    # right cut: 2:1, retina-sharp at render width, and small enough to stay
-    # out of an inbox clipping limit.
+    # The FALLBACK shape, for an email that states none. 2:1 because that is what
+    # turf-monster's eight banners are, and changing it would recrop all of them.
+    #
+    # The engine's own two entries now declare 2.0 as well, and their backgrounds
+    # are 1200x600 — but the ratio stays per-entry, because that is what lets a
+    # host register artwork of a different shape without recropping everyone's.
     ASPECT_RATIO = 2.0
     MAX_WIDTH = 1200
 
+    # NO DEFAULT LOGO, deliberately.
+    #
+    # It was emails/logo-horizontal.png — the white "McRITCHIE STUDIO" wordmark —
+    # and every consumer inherits this layout without defining its own. That put
+    # Studio branding into turf-monster's entire player-facing mail set, which
+    # today carries none, plus moms-app, mcritchie-industries, acquisition-studio
+    # and rolio, with no opt-in and no host-side change.
+    #
+    # It also contradicted the rule at the top of this file: the url / resolved_url
+    # split exists so the engine cannot swap a host's artwork for the engine's in
+    # live email. A footer logo is the same swap by another route.
+    #
+    # Each app opts in on /admin/emails by pasting its own mark.
+
+    # The footer band. Dark on purpose: it closes the white card, and a light
+    # sign-off floating under body copy reads as part of the message rather than
+    # the end of it. Hard-coded rather than derived from the theme because a
+    # host's primary can be light, and white-on-light is unreadable — the one
+    # thing this band must never be.
+    FOOTER_BACKGROUND = "#1A1535".freeze
+
     module_function
 
     # --- Registry ----------------------------------------------------------
@@ -130,7 +225,9 @@ module Studio
     # existing value — that is what lets a host relabel an inherited email, or
     # attach a preview builder to it, without restating its artwork.
     def register(key, label: nil, description: nil, default_asset: nil, type: nil, preview: nil,
-                 aspect_ratio: nil)
+                 aspect_ratio: nil, background: nil, logo: nil, scrim: nil,
+                 header: nil, header_fallback: nil, subtext: nil, subject: nil,
+                 body: nil, cta_text: nil, cta_color: nil, cta_enabled: nil, supports_cta: nil)
       key = key.to_s
       existing = registry[key]
       registry[key] = Entry.new(
@@ -145,7 +242,24 @@ module Studio
         # had, so a host relabelling an inherited email does not accidentally
         # claim the engine's picture as its own.
         default_origin: default_asset.nil? ? (existing&.default_origin || :engine) : :app,
-        aspect_ratio: aspect_ratio || existing&.aspect_ratio
+        # WHOSE background this is, recorded the same way and for the same
+        # reason: by the time anyone asks, an inherited background and a
+        # host-registered one are indistinguishable, and guessing is what this
+        # records to avoid. A host passing background: is ASKING to layer.
+        background_origin: background.nil? ? (existing&.background_origin || :engine) : :app,
+        aspect_ratio: aspect_ratio || existing&.aspect_ratio,
+        background: background.nil? ? existing&.background : background.presence,
+        logo: logo.nil? ? existing&.logo : logo.presence,
+        scrim: scrim.nil? ? existing&.scrim : scrim,
+        header: header.nil? ? existing&.header : header.presence,
+        header_fallback: header_fallback.nil? ? existing&.header_fallback : header_fallback.presence,
+        subtext: subtext.nil? ? existing&.subtext : subtext.presence,
+        subject: subject.nil? ? existing&.subject : subject.presence,
+        body: body.nil? ? existing&.body : body.presence,
+        cta_text: cta_text.nil? ? existing&.cta_text : cta_text.presence,
+        cta_color: cta_color.nil? ? existing&.cta_color : cta_color.presence,
+        cta_enabled: cta_enabled.nil? ? existing&.cta_enabled : cta_enabled,
+        supports_cta: supports_cta.nil? ? existing&.supports_cta : supports_cta
       )
       key
     end
@@ -202,7 +316,9 @@ module Studio
       @registry ||= STANDARD.each_with_object({}) do |attrs, out|
         out[attrs[:key]] = Entry.new(**attrs, type: normalize_type(attrs[:type]),
                                      preview: attrs[:preview], default_origin: :engine,
-                                     aspect_ratio: attrs[:aspect_ratio])
+                                     aspect_ratio: attrs[:aspect_ratio],
+                                     background: attrs[:background], logo: attrs[:logo],
+                                     scrim: attrs[:scrim])
       end
     end
 
@@ -239,6 +355,172 @@ module Studio
     # This email's banner shape, falling back to the shared default.
     def ratio(key) = entry(key)&.ratio || ASPECT_RATIO
 
+    # --- layered banner artwork ---------------------------------------------
+    #
+    # Absolute URLs, because a mail client fetches these from an inbox and a
+    # root-relative path resolves against nothing there.
+
+    # Saved by the operator > registered by the app > engine default.
+    def scrim(key)
+      Studio::EmailSetting.scrim_for(key) || entry(key)&.scrim
+    rescue StandardError
+      entry(key)&.scrim
+    end
+
+    # --- the banner's words -------------------------------------------------
+    #
+    # Same order as the tint, for the same reason: the operator is the one
+    # looking at the artwork. Each falls back to the registry, then to a
+    # sensible default, so an email that nobody has configured still reads.
+
+    # The header TEMPLATE — it may contain {name}. Interpolation happens in
+    # Studio::Banner, which is the only place that knows the recipient.
+    def header_template(key)
+      saved(key, :header) || entry(key)&.header || entry(key)&.label
+    end
+
+    # What the header says when no name is known. A magic link is often the
+    # first contact we have with someone, so "Welcome {name}!" must have
+    # somewhere to land that is not "Welcome !".
+    def header_fallback(key)
+      saved(key, :header_fallback) || entry(key)&.header_fallback || entry(key)&.label
+    end
+
+    def subtext(key)
+      saved(key, :subtext) || entry(key)&.subtext
+    end
+
+    # --- the email below the banner ------------------------------------------
+    #
+    # Same resolution as the banner's words: operator > registry > default. A
+    # mailer reads these instead of hard-coding copy, which is what makes the
+    # cards on /admin/emails real rather than decorative.
+
+    def body(key, name: nil)
+      template = saved(key, :body) || entry(key)&.body
+      return nil if template.blank?
+
+      Studio::Banner.interpolate(template, name).presence
+    end
+
+    def cta_text(key, name: nil)
+      template = saved(key, :cta_text) || entry(key)&.cta_text
+      return nil if template.blank?
+
+      Studio::Banner.interpolate(template, name).presence
+    end
+
+    # The app's primary unless this email says otherwise — a button that matches
+    # the banner above it by default, and can be made to stand out per email.
+    def cta_color(key)
+      saved(key, :cta_color) || entry(key)&.cta_color || Studio.theme_primary
+    end
+
+    # Shown unless someone said no. Defaults to TRUE for an email that has CTA
+    # text, because the button is the point of a transactional email; an email
+    # with no text has nothing to render either way.
+    def cta_enabled?(key)
+      # An email whose template cannot render a button is never "enabled", no
+      # matter what is stored — otherwise a value saved before the capability was
+      # declared keeps claiming a button that cannot appear.
+      return false unless entry(key)&.supports_cta?
+
+      operator = begin
+        Studio::EmailSetting.cta_enabled_for(key)
+      rescue StandardError
+        nil
+      end
+      return operator unless operator.nil?
+
+      registered = entry(key)&.cta_enabled
+      return registered unless registered.nil?
+
+      true
+    end
+
+    # The shared footer — the same on every email this app sends.
+    #
+    # The operator's footer, or nothing. An app that has not set one renders no
+    # band at all — the engine ships no branding of its own into a host's email.
+    def footer
+      (Studio::EmailSetting.footer || {}).compact
+    rescue StandardError
+      {}
+    end
+
+    # The subject line, resolved the same way and supporting the same {name}
+    # placeholder. A mailer calls this instead of hard-coding a string, which is
+    # what makes the field on /admin/emails real rather than decorative.
+    def subject_for(key, name: nil)
+      template = saved(key, :subject) || entry(key)&.subject
+      return nil if template.blank?
+
+      Studio::Banner.interpolate(template, name).presence
+    end
+
+    # nil when the operator has hidden the logo — distinct from "none saved",
+    # which inherits the registry's.
+    # Hidden > uploaded here > a URL the operator typed > the registry's.
+    # "Hidden" comes first because it is the one answer the others cannot express.
+    def resolved_logo_url(key)
+      return nil if Studio::EmailSetting.hide_logo?(key)
+
+      uploaded_logo_url(key) || saved(key, :logo_url) || logo_url(key)
+    rescue StandardError
+      logo_url(key)
+    end
+
+    # An operator-saved field, or nil. Rescues because these are read on a
+    # delivery path: a settings table that is missing, locked, or mid-migration
+    # must degrade to the registry default rather than fail the send.
+    def saved(key, field)
+      Studio::EmailSetting.copy_for(key, field)
+    rescue StandardError
+      nil
+    end
+
+    def scrim_percent(key)
+      value = scrim(key) || Studio::Banner::DEFAULT_SCRIM
+      (value.to_f * 100).round
+    end
+
+    # THE APP'S OWN UPLOAD WINS, then the registered artwork. Same two layers as
+    # resolved_url, and for the same reason: uploading on /admin/emails is how an
+    # operator says "this picture is ours now".
+    #
+    # Reading only the registry made the Upload button a control that lies on a
+    # LAYERED email — the upload landed, the page showed it, the provenance badge
+    # flipped to "Uploaded here", and the email kept sending the gem's artwork
+    # because the layered banner never looked at the row.
+    #
+    # NIL UNLESS THIS EMAIL LAYERS. A host registering its own flat
+    # default_asset sends that picture, and the background it merely INHERITED is
+    # the engine's — nothing sends it. But a host that registers a background of
+    # its OWN is asking to layer, and layered? is what tells the two apart.
+    #
+    # This is the ONE place that decision is made. Every reader asks this method
+    # rather than re-deriving it: the list row used to carry its own copy of the
+    # guard, and the copy went stale the moment the guard moved here.
+    def background_url(key)
+      return nil unless entry(key)&.layered?
+
+      url(key) || absolute_asset_url(entry(key)&.background)
+    end
+    def logo_url(key)       = absolute_asset_url(entry(key)&.logo)
+
+    def absolute_asset_url(asset)
+      return nil if asset.blank?
+
+      path = ActionController::Base.helpers.asset_path(asset)
+      return nil if path.blank?
+      return path if path.start_with?("http")
+
+      host = mailer_asset_host
+      host ? "#{host}#{path}" : path
+    rescue StandardError
+      nil
+    end
+
     def app_owned?(key) = source(key) == :app
 
     # --- Preview -----------------------------------------------------------
@@ -348,7 +630,40 @@ module Studio
     # whatever host and port this app is being viewed on (an absolute mailer
     # asset_host is set for the inbox, not for a browser on localhost:3042).
     def preview_url(key)
-      url(key) || default_asset_path(key)
+      url(key) || preview_asset_path(key)
+    end
+
+    # What the manager DRAWS, which is a different question from what the flat
+    # <img> fallback sends — so it resolves in the opposite order.
+    #
+    # LAYERED FIRST. magic_link ships both: `emails/magic-link.gif`, the old
+    # banner with "Your Magic Link" baked into the picture, and
+    # `emails/magic-link-background.gif`, the artwork the layered banner draws
+    # live text on top of. A mailer that has adopted layering sends the SECOND
+    # one — so previewing the first showed the operator a picture no inbox
+    # receives, and did it convincingly, because baked-in words look like a real
+    # banner. Same failure as the "No image" badge, one door further along: the
+    # page answering from the field it happened to read instead of from what
+    # ships.
+    #
+    # The flat asset stays the fallback, for a host still on the engine's own
+    # unlayered UserMailer — there, the baked-text banner IS what arrives.
+    #
+    # Unless this email does not LAYER, in which case it previews exactly what
+    # the flat resolution sends — same method, so the two cannot disagree.
+    #
+    # THE SAME QUESTION background_url ASKS, so it must ask it the same way.
+    # This guard read engine_artwork? while background_url read layered?, and the
+    # two answer differently for a host that registers its own background: the
+    # mailer sent the layered banner while /admin/email_images and the detail
+    # page's "Artwork" frame both drew the flat asset. That frame is where
+    # "Modify image" lives, and an upload writes the row background_url reads
+    # FIRST — so the operator was shown one picture and told it was the one the
+    # button would replace.
+    def preview_asset_path(key)
+      return default_asset_path(key) unless entry(key)&.layered?
+
+      asset_path(entry(key)&.background.presence || entry(key)&.default_asset)
     end
 
     # The ImageCache row holding this app's override, or nil (nothing uploaded /
@@ -359,14 +674,60 @@ module Studio
       ::ImageCache.find_by(owner: nil, purpose: PURPOSE, variant: key.to_s)
     end
 
-    # Root-relative path to the inherited default asset, or nil when the email
-    # has no default registered or the host's pipeline cannot resolve it.
+    def logo_record(key)
+      return nil unless table_ready?
+
+      ::ImageCache.find_by(owner: nil, purpose: LOGO_PURPOSE, variant: key.to_s)
+    end
+
+    # An uploaded logo for this email, or nil to inherit.
+    def uploaded_logo_url(key)
+      logo_record(key)&.url
+    rescue StandardError
+      nil
+    end
+
+    def store_logo(key, io:, content_type: nil)
+      s3_key = "email_logos/#{key}-#{SecureRandom.hex(4)}#{ext_for(content_type)}"
+      Studio::S3.upload(key: s3_key, body: io.read, content_type: content_type,
+                        cache_control: "public, max-age=300")
+      record = ::ImageCache.find_or_initialize_by(owner: nil, purpose: LOGO_PURPOSE, variant: key.to_s)
+      previous = record.s3_key
+      record.update!(s3_key: s3_key)
+      delete_object(previous) if previous.present? && previous != s3_key
+      record
+    rescue StandardError
+      delete_object(s3_key)
+      raise
+    end
+
+    def revert_logo(key)
+      row = logo_record(key)
+      return false if row.nil?
+
+      previous = row.s3_key
+      row.destroy!
+      delete_object(previous) if previous.present?
+      true
+    end
+
+    # Root-relative path to the FLAT artwork — what the <img> fallback sends.
+    # Flat first, then the layered background as a last resort so a
+    # layered-native email (newsletter_subscribed registers no flat asset,
+    # because it never renders one) still has something rather than nothing.
+    # See preview_asset_path above for why the manager resolves the other way.
     def default_asset_path(key)
-      asset = entry(key)&.default_asset
+      asset_path(entry(key)&.default_asset.presence || entry(key)&.background)
+    end
+
+    # Shared tail of both resolutions: a logical asset name to a root-relative
+    # path, or nil when there is no asset or the host's pipeline cannot resolve
+    # it. Rescues broadly because a missing asset must degrade to "no image",
+    # never take the manager down.
+    def asset_path(asset)
       return nil if asset.nil? || asset.empty?
 
-      path = ActionController::Base.helpers.asset_path(asset)
-      path.presence
+      ActionController::Base.helpers.asset_path(asset).presence
     rescue StandardError
       nil
     end
@@ -477,11 +838,18 @@ module Studio
 
     LOOPBACK_HOSTS = %w[localhost 127.0.0.1 0.0.0.0 ::1].freeze
 
+    # GIF is listed because animated banners are uploaded whole — they bypass the
+    # cropper, which would flatten them to a single PNG frame. Without this branch
+    # a GIF was stored under a ".png" key: the object's Content-Type was still
+    # image/gif so it played, but the URL said otherwise, and anything that trusts
+    # an extension (a CDN, a proxy, a person reading the bucket) was told the
+    # wrong thing.
     def ext_for(content_type)
       case content_type.to_s
       when %r{png}    then ".png"
       when %r{jpe?g}  then ".jpg"
       when %r{webp}   then ".webp"
+      when %r{gif}    then ".gif"
       else ".png"
       end
     end