Module: Studio::EmailCatalog

Defined in:
app/services/studio/email_catalog.rb

Overview

The shared email catalog: every email an app sends, what kind it is, how to build a live preview of it, and the banner image it ships with.

Named for the prior art it absorbs. turf-monster built ::EmailCatalog + Admin::EmailsController first and left a note on both saying this manager "moves into the shared studio-engine email framework (Phase 2)". This is Phase 2 — so the engine takes the name, the shape (key / name / type / description / preview builder), and the live-preview page, and adds the banner-image half. turf-monster then deletes its copy instead of running two email pages side by side.

Was Studio::EmailImage, which is now a delegating shim — see app/services/studio/email_image.rb. The old name outlived its meaning the moment an entry carried a type and a preview builder alongside its image.

Two layers: inherited default, app-owned override

.resolved_url(key) => app's own ImageCache row (its S3 bucket)  # app-owned
                 -> the engine's default gem asset            # inherited
                 -> nil                                       # no image

.url(key) stays the PRE-REGISTRY contract — this app's own image or nil — so every caller written before the registry keeps its behavior until its app adopts. See the note on #url; getting this wrong swaps a host's committed artwork for the engine placeholder in live email.

Defaults RIDE THE GEM (app/assets/images/emails/*), so a brand-new app with an empty bucket sends good-looking email on day one and needs no cross-app S3 permission. Uploading on an app's /admin/emails writes to THAT app's bucket and THAT app's ImageCache row — which is exactly "the asset now belongs to this app". Every app has its own bucket and its own image_caches table, so an override never leaks between apps.

Registering

The engine pre-registers the two every Studio app sends (STANDARD below), so hosts inherit them without declaring anything. A host adds its own workflows from an initializer, mirroring Studio::ModelPage.register:

# config/initializers/studio_emails.rb
Rails.application.config.to_prepare do
Studio::EmailCatalog.register("winnings",
  label: "Contest winnings",
  description: "Sent when a player wins a contest.",
  type: :transactional,
  preview: -> { ContestMailer.winnings(Entry.where.not(rank: nil).first) })
end

Re-registering a key updates it in place and keeps its position, so a host can relabel an inherited email without reordering the page.

Preview

preview is a callable returning a Mail — the app builds it from whatever sample data it likes. It is what powers the live preview on /admin/emails/:key. It runs ONLY on that admin page, never in a delivery path, and every call is wrapped: an entry whose builder raises shows the error on the page rather than 500ing the manager. An entry without one still lists and still manages its banner; it just has nothing to preview.

Defined Under Namespace

Classes: Entry

Constant Summary collapse

PURPOSE = 
"email_banner".freeze
LOGO_PURPOSE =

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.

"email_logo".freeze
TYPES =

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 (unsubscribe requirements, send-time rules, which from-address is used).

%i[transactional marketing].freeze
DEFAULT_TYPE = 
:transactional
STANDARD =

The emails EVERY Studio app sends. Pre-registered, so a host inherits both without declaring anything.

[
  {
    key: "magic_link",
    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: 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: "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",
    # NO logo: KEY, and adding one back is the bug. It seeded
    # "emails/logo-horizontal.png" — the McRITCHIE STUDIO wordmark — into
    # every host that registers this email without naming a logo of its own,
    # because register() merges on `logo.presence` and an omitted key
    # inherits. Full reasoning under NO DEFAULT LOGO below; the guards are in
    # test/integration/newsletter_email_test.rb.
    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
ASPECT_RATIO =

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.

2.0
MAX_WIDTH = 
1200
"#1A1535".freeze
LOOPBACK_HOSTS = 
%w[localhost 127.0.0.1 0.0.0.0 ::1].freeze

Class Method Summary collapse

Class Method Details

.absolute_asset_url(asset) ⇒ Object 



559
560
561
562
563
564
565
566
567
568
569
570
 
# File 'app/services/studio/email_catalog.rb', line 559

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

.app_artwork?(key) ⇒ Boolean

True when the live banner belongs to this app either way — uploaded here or committed here. What the page's summary line counts.

Returns:

  • (Boolean) 


401
 
# File 'app/services/studio/email_catalog.rb', line 401

def app_artwork?(key) = %i[app app_asset].include?(source(key))

.app_owned?(key) ⇒ Boolean

Returns:

  • (Boolean) 


572
 
# File 'app/services/studio/email_catalog.rb', line 572

def app_owned?(key) = source(key) == :app

.asset_path(asset) ⇒ Object

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.



775
776
777
778
779
780
781
 
# File 'app/services/studio/email_catalog.rb', line 775

def asset_path(asset)
  return nil if asset.nil? || asset.empty?

  ActionController::Base.helpers.asset_path(asset).presence
rescue StandardError
  nil
end

.background_url(key) ⇒ Object

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.



552
553
554
555
556
 
# File 'app/services/studio/email_catalog.rb', line 552

def background_url(key)
  return nil unless entry(key)&.layered?

  url(key) || absolute_asset_url(entry(key)&.background)
end

.body(key, name: nil) ⇒ Object

--- 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.



447
448
449
450
451
452
 
# File 'app/services/studio/email_catalog.rb', line 447

def body(key, name: nil)
  template = saved(key, :body) || entry(key)&.body
  return nil if template.blank?

  Studio::Banner.interpolate(template, name).presence
end

.cta_color(key) ⇒ Object

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.



463
464
465
 
# File 'app/services/studio/email_catalog.rb', line 463

def cta_color(key)
  saved(key, :cta_color) || entry(key)&.cta_color || Studio.theme_primary
end

.cta_enabled?(key) ⇒ Boolean

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.

Returns:

  • (Boolean) 


470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
 
# File 'app/services/studio/email_catalog.rb', line 470

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

.cta_text(key, name: nil) ⇒ Object 



454
455
456
457
458
459
 
# File 'app/services/studio/email_catalog.rb', line 454

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

.default_asset_path(key) ⇒ Object

Root-relative path to the FLAT artwork — what the 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.



767
768
769
 
# File 'app/services/studio/email_catalog.rb', line 767

def default_asset_path(key)
  asset_path(entry(key)&.default_asset.presence || entry(key)&.background)
end

.default_url(key) ⇒ Object

Absolute URL to the inherited default asset — what a mailer needs. Uses action_mailer.asset_host (set per env), falling back to the mailer's default_url_options host. Returns the bare path if neither is configured, which still renders in the local inbox preview.



787
788
789
790
791
792
793
794
 
# File 'app/services/studio/email_catalog.rb', line 787

def default_url(key)
  path = default_asset_path(key)
  return nil if path.nil?
  return path if path.start_with?("http")

  host = mailer_asset_host
  host ? "#{host}#{path}" : path
end

.delete_object(key) ⇒ Object 



905
906
907
908
909
 
# File 'app/services/studio/email_catalog.rb', line 905

def delete_object(key)
  Studio::S3.delete(key: key)
rescue StandardError
  nil
end

.entries ⇒ Object

Every registered email, in display order: the standard two first, then the host's own in declaration order.



324
325
326
 
# File 'app/services/studio/email_catalog.rb', line 324

def entries
  registry.values
end

.entry(key) ⇒ Object 



328
329
330
 
# File 'app/services/studio/email_catalog.rb', line 328

def entry(key)
  registry[key.to_s]
end

.ext_for(content_type) ⇒ Object

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.



895
896
897
898
899
900
901
902
903
 
# File 'app/services/studio/email_catalog.rb', line 895

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

.footer ⇒ Object

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.



493
494
495
496
497
 
# File 'app/services/studio/email_catalog.rb', line 493

def footer
  (Studio::EmailSetting.footer || {}).compact
rescue StandardError
  {}
end

.header_fallback(key) ⇒ Object

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 !".



433
434
435
 
# File 'app/services/studio/email_catalog.rb', line 433

def header_fallback(key)
  saved(key, :header_fallback) || entry(key)&.header_fallback || entry(key)&.label
end

.header_template(key) ⇒ Object

The header TEMPLATE — it may contain name. Interpolation happens in Studio::Banner, which is the only place that knows the recipient.



426
427
428
 
# File 'app/services/studio/email_catalog.rb', line 426

def header_template(key)
  saved(key, :header) || entry(key)&.header || entry(key)&.label
end

.keys ⇒ Object 



332
333
334
 
# File 'app/services/studio/email_catalog.rb', line 332

def keys
  registry.keys
end

.known?(key) ⇒ Boolean

Returns:

  • (Boolean) 


336
337
338
 
# File 'app/services/studio/email_catalog.rb', line 336

def known?(key)
  registry.key?(key.to_s)
end

.label(key) ⇒ Object 



341
342
343
 
# File 'app/services/studio/email_catalog.rb', line 341

def label(key)
  entry(key)&.label || key.to_s.humanize
end

.logo_record(key) ⇒ Object 



725
726
727
728
729
 
# File 'app/services/studio/email_catalog.rb', line 725

def logo_record(key)
  return nil unless table_ready?

  ::ImageCache.find_by(owner: nil, purpose: LOGO_PURPOSE, variant: key.to_s)
end

.logo_url(key) ⇒ Object 



557
 
# File 'app/services/studio/email_catalog.rb', line 557

def logo_url(key)       = absolute_asset_url(entry(key)&.)

.mailer_asset_host ⇒ Object

The origin an email's banner URL hangs off. action_mailer.asset_host when the host sets one (turf-monster does, per env); otherwise built from the mailer's default_url_options.

That fallback has to reconstruct a real origin, not just the hostname. default_url_options is routinely "localhost", port: 3001 — taking :host alone and prefixing "https://&quot; yields https://localhost, which is the wrong scheme AND the wrong port, and the banner comes back ERR_CONNECTION_REFUSED. Caught by opening the preview page on a worktree stack; every dev/QA preview took that path.



854
855
856
857
858
859
860
861
862
863
864
865
866
 
# File 'app/services/studio/email_catalog.rb', line 854

def mailer_asset_host
  configured = Rails.application.config.action_mailer.asset_host.presence
  return configured if configured

  options = ActionMailer::Base.default_url_options || {}
  host = options[:host].presence
  return nil if host.nil?
  return host if host.start_with?("http")

  "#{mailer_protocol(options, host)}://#{host}#{mailer_port_suffix(options)}"
rescue StandardError
  nil
end

.mailer_port_suffix(options) ⇒ Object

Ports are part of the origin, and omitting one sends the reader to :443. The scheme defaults are left off so a normal URL stays normal.



880
881
882
883
884
885
 
# File 'app/services/studio/email_catalog.rb', line 880

def mailer_port_suffix(options)
  port = options[:port]
  return "" if port.blank? || [80, 443].include?(port.to_i)

  ":#{port}"
end

.mailer_protocol(options, host) ⇒ Object

Honor an explicit :protocol. Otherwise https — EXCEPT on loopback, which is a dev stack with no TLS. Defaulting the other way would downgrade every production app that sets only "mcritchie.studio".



871
872
873
874
875
876
 
# File 'app/services/studio/email_catalog.rb', line 871

def mailer_protocol(options, host)
  explicit = options[:protocol].presence
  return explicit.to_s.sub(%r{://\z}, "") if explicit

  LOOPBACK_HOSTS.include?(host.downcase) ? "http" : "https"
end

.normalize_type(type) ⇒ Object

Unknown types fall back to :transactional rather than raising — a typo in an initializer must not take the host's boot down over a display label.



317
318
319
320
 
# File 'app/services/studio/email_catalog.rb', line 317

def normalize_type(type)
  symbol = type.to_s.strip.downcase.to_sym
  TYPES.include?(symbol) ? symbol : DEFAULT_TYPE
end

.preview_asset_path(key) ⇒ Object

What the manager DRAWS, which is a different question from what the flat 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.



711
712
713
714
715
 
# File 'app/services/studio/email_catalog.rb', line 711

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

.preview_error(key) ⇒ Object

The reason the last preview_mail(key) returned nil, or nil if it did not fail. Set by preview_mail; read by the page so it can say WHY.



605
606
607
 
# File 'app/services/studio/email_catalog.rb', line 605

def preview_error(key)
  (@preview_errors ||= {})[key.to_s]
end

.preview_html(key) ⇒ Object

The rendered HTML body of the preview, for the iframe. nil when the email has no builder or the builder failed.



611
612
613
614
615
616
617
618
619
 
# File 'app/services/studio/email_catalog.rb', line 611

def preview_html(key)
  mail = preview_mail(key)
  return nil if mail.nil?

  (mail.html_part&.body || mail.body).to_s
rescue StandardError => e
  (@preview_errors ||= {})[key.to_s] = "#{e.class}: #{e.message}"
  nil
end

.preview_mail(key) ⇒ Object

Build the sample Mail for this email, or nil.

NEVER raises. A preview builder is host code running against whatever sample data happens to be in this environment — an empty table, a fixture that moved, a mailer whose signature changed. Any of those must show up as a message ON the preview page, not as a 500 that takes the whole email manager down with it. Returns nil; ask #preview_error for the reason.



591
592
593
594
595
596
597
598
599
600
601
 
# File 'app/services/studio/email_catalog.rb', line 591

def preview_mail(key)
  callable = entry(key)&.preview
  return nil unless callable.respond_to?(:call)

  @preview_errors ||= {}
  @preview_errors.delete(key.to_s)
  force_message(callable.call)
rescue StandardError, ScriptError => e
  (@preview_errors ||= {})[key.to_s] = "#{e.class}: #{e.message}"
  nil
end

.preview_subject(key) ⇒ Object 



621
622
623
 
# File 'app/services/studio/email_catalog.rb', line 621

def preview_subject(key)
  preview_mail(key)&.subject
end

.preview_url(key) ⇒ Object

What the ADMIN PAGE previews. Same two layers as resolved_url, but a default stays a root-relative asset path so it renders correctly on 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).



680
681
682
 
# File 'app/services/studio/email_catalog.rb', line 680

def preview_url(key)
  url(key) || preview_asset_path(key)
end

.previewable?(key) ⇒ Boolean

--- Preview -----------------------------------------------------------

Returns:

  • (Boolean) 


576
577
578
 
# File 'app/services/studio/email_catalog.rb', line 576

def previewable?(key)
  entry(key)&.previewable? || false
end

.ratio(key) ⇒ Object

This email's banner shape, falling back to the shared default.



404
 
# File 'app/services/studio/email_catalog.rb', line 404

def ratio(key) = entry(key)&.ratio || ASPECT_RATIO

.record(key) ⇒ Object

The ImageCache row holding this app's override, or nil (nothing uploaded / table not installed yet). Nil-safe so the mailer renders before any upload.



719
720
721
722
723
 
# File 'app/services/studio/email_catalog.rb', line 719

def record(key)
  return nil unless table_ready?

  ::ImageCache.find_by(owner: nil, purpose: PURPOSE, variant: key.to_s)
end

.register(key, label: nil, description: nil, default_asset: nil, type: nil, preview: 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) ⇒ Object

Register (or update) an email workflow. Returns the key.

Every keyword is OPTIONAL and omitting one on a re-register KEEPS the existing value — that is what lets a host relabel an inherited email, or attach a preview builder to it, without restating its artwork.



275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
 
# File 'app/services/studio/email_catalog.rb', line 275

def register(key, label: nil, description: nil, default_asset: nil, type: nil, preview: 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(
    key: key,
    label: label || existing&.label || key.humanize,
    description: description || existing&.description,
    default_asset: default_asset.nil? ? existing&.default_asset : default_asset.presence,
    type: normalize_type(type || existing&.type),
    preview: preview || existing&.preview,
    # Passing artwork here makes it THIS APP's artwork — that is the only
    # moment anyone can know. Omitting it keeps whatever the entry already
    # 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,
    # 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: .nil? ? existing&. : .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

.registered?(key) ⇒ Boolean

Returns:

  • (Boolean) 


339
 
# File 'app/services/studio/email_catalog.rb', line 339

def registered?(key) = known?(key)

.registry ⇒ Object

Seeded through the SAME normalization register() uses, so a standard entry is indistinguishable from a host-registered one (its type is a real symbol, not nil) and every reader can trust the shape.



363
364
365
366
367
368
369
370
371
 
# File 'app/services/studio/email_catalog.rb', line 363

def registry
  @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],
                                 background: attrs[:background], logo: attrs[:logo],
                                 scrim: attrs[:scrim])
  end
end

.reset! ⇒ Object

Drops host registrations back to the standard two. For tests and for to_prepare re-registration.



353
354
355
356
357
358
 
# File 'app/services/studio/email_catalog.rb', line 353

def reset!
  @registry = nil
  @preview_errors = nil
  registry
  nil
end

.resolved_logo_url(key) ⇒ Object

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.



513
514
515
516
517
518
519
 
# File 'app/services/studio/email_catalog.rb', line 513

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

.resolved_url(key) ⇒ Object

What ACTUALLY SHIPS on this email — the two-layer resolution. Absolute, so it resolves from an inbox. App-owned override first, then the inherited engine default, then nil (the mailer renders bannerless).

This is what a mailer should call once its app has adopted the registry. The engine's own UserMailer already does, which is what gives an app with an empty bucket branded email on day one.



672
673
674
 
# File 'app/services/studio/email_catalog.rb', line 672

def resolved_url(key)
  url(key) || default_url(key)
end

.revert(key) ⇒ Object

Drop this app's override and fall back to the inherited default. Returns true when a row was removed.



824
825
826
827
828
829
830
831
832
 
# File 'app/services/studio/email_catalog.rb', line 824

def revert(key)
  row = record(key)
  return false if row.nil?

  previous = row.s3_key
  row.destroy!
  delete_object(previous) if previous.present?
  true
end

.revert_logo(key) ⇒ Object 



752
753
754
755
756
757
758
759
760
 
# File 'app/services/studio/email_catalog.rb', line 752

def (key)
  row = logo_record(key)
  return false if row.nil?

  previous = row.s3_key
  row.destroy!
  delete_object(previous) if previous.present?
  true
end

.saved(key, field) ⇒ Object

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.



524
525
526
527
528
 
# File 'app/services/studio/email_catalog.rb', line 524

def saved(key, field)
  Studio::EmailSetting.copy_for(key, field)
rescue StandardError
  nil
end

.scrim(key) ⇒ Object

Saved by the operator > registered by the app > engine default.



412
413
414
415
416
 
# File 'app/services/studio/email_catalog.rb', line 412

def scrim(key)
  Studio::EmailSetting.scrim_for(key) || entry(key)&.scrim
rescue StandardError
  entry(key)&.scrim
end

.scrim_percent(key) ⇒ Object 



530
531
532
533
 
# File 'app/services/studio/email_catalog.rb', line 530

def scrim_percent(key)
  value = scrim(key) || Studio::Banner::DEFAULT_SCRIM
  (value.to_f * 100).round
end

.source(key) ⇒ Object

Where the live banner for this email actually comes from:

:app            — uploaded on this app's /admin/emails (ImageCache row
                in this app's bucket). Revertible.
:app_asset      — registered by this app, committed in its own repo.
:engine_default — the shared artwork that ships in the gem.
:none           — no image at all; the email sends bannerless.

:default USED to cover the middle two together, and the page said "Shared Studio artwork, shipped with the engine" for both — so turf-monster's own eight banners were announced as the engine's. Telling the operator the wrong provenance is the same failure this page was built to end (the page it replaced claimed "No image yet" about an email that was visibly sending one).

:app is deliberately unchanged: turf-monster's suite on main asserts it, and consumer CI runs consumers' default branch.



392
393
394
395
396
397
 
# File 'app/services/studio/email_catalog.rb', line 392

def source(key)
  return :app if record(key)
  return :none unless default_asset_path(key)

  entry(key)&.engine_artwork? ? :engine_default : :app_asset
end

.store(key, io:, content_type: nil) ⇒ Object

Upload bytes to this app's bucket + upsert its ImageCache row (replacing any prior object). Returns the ::ImageCache. Raises on failure after cleaning up the new object.



808
809
810
811
812
813
814
815
816
817
818
819
820
 
# File 'app/services/studio/email_catalog.rb', line 808

def store(key, io:, content_type: nil)
  s3_key = "email_banners/#{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: 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

.store_logo(key, io:, content_type: nil) ⇒ Object 



738
739
740
741
742
743
744
745
746
747
748
749
750
 
# File 'app/services/studio/email_catalog.rb', line 738

def (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

.subject_for(key, name: nil) ⇒ Object

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.



502
503
504
505
506
507
 
# File 'app/services/studio/email_catalog.rb', line 502

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

.subtext(key) ⇒ Object 



437
438
439
 
# File 'app/services/studio/email_catalog.rb', line 437

def subtext(key)
  saved(key, :subtext) || entry(key)&.subtext
end

.table_ready? ⇒ Boolean

Reference ImageCache directly so Zeitwerk autoloads it — defined?() does NOT trigger autoload, so it would read "undefined" for a not-yet-loaded const.

Returns:

  • (Boolean) 


838
839
840
841
842
 
# File 'app/services/studio/email_catalog.rb', line 838

def table_ready?
  ::ImageCache.table_exists?
rescue NameError, ActiveRecord::ActiveRecordError
  false
end

.type(key) ⇒ Object 



580
581
582
 
# File 'app/services/studio/email_catalog.rb', line 580

def type(key)
  entry(key)&.type || DEFAULT_TYPE
end

.uploaded_logo_url(key) ⇒ Object

An uploaded logo for this email, or nil to inherit.



732
733
734
735
736
 
# File 'app/services/studio/email_catalog.rb', line 732

def uploaded_logo_url(key)
  logo_record(key)&.url
rescue StandardError
  nil
end

.uploads_available? ⇒ Boolean

Whether THIS app can accept an upload. False when the host never set Studio.s3_bucket_prefix — /admin/emails then shows inherited defaults read-only rather than 500ing on the first upload.

Returns:

  • (Boolean) 


801
802
803
 
# File 'app/services/studio/email_catalog.rb', line 801

def uploads_available?
  Studio::S3.configured? && table_ready?
end

.url(key) ⇒ Object

THIS APP'S OWN image only — nil when nothing has been uploaded here.

This is the PRE-REGISTRY contract, kept EXACTLY: url has always meant "the admin-managed override, or nil", and callers were written to fall back themselves. turf-monster's mailer is the live example:

@banner_url = Studio::EmailImage.url(:magic_link) || email_banner_url("magic-link-banner.jpg")

Making url resolve to the engine default would make that || dead code and silently replace turf-monster's own branded 1200x600 banner with the engine's PLACEHOLDER in real sign-in email. A method whose signature is unchanged but whose return value flips from nil to a value is not additive. So the new two-layer resolution lives in resolved_url, and every existing caller keeps the behavior it was written against until its app adopts.



661
662
663
 
# File 'app/services/studio/email_catalog.rb', line 661

def url(key)
  record(key)&.url
end

.variants ⇒ Object

Legacy shape — key => label. Kept because it is the API the pre-registry admin page and any host that read VARIANTS were written against.



347
348
349
 
# File 'app/services/studio/email_catalog.rb', line 347

def variants
  registry.transform_values(&:label)
end