sponsored_logs 0.1.0

data/lib/sponsored_logs/report/app/helpers/sponsored_logs/reports_helper.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module SponsoredLogs
+  module ReportsHelper
+    STATUS_COLORS = {
+      active: "#16a34a",
+      scheduled: "#2563eb",
+      ended: "#6b7280",
+      evergreen: "#7c3aed"
+    }.freeze
+
+    BAR_HEIGHT = 22
+    BAR_GAP = 10
+    LABEL_WIDTH = 320
+    TRACK_WIDTH = 360
+    VALUE_PAD = 8
+    BAR_COLOR = "#4f46e5"
+
+    # Render a horizontal bar chart as inline SVG from report ad rows.
+    # `value` picks the numeric field per row; `format` renders the label.
+    #
+    def bar_chart(ads, value:, format:)
+      rows = ads.map { |ad| [ad[:text], value.call(ad).to_f] }
+                .sort_by { |(_text, v)| -v }
+      return content_tag(:p, "No data yet.", class: "empty") if rows.empty?
+
+      max = rows.map { |(_t, v)| v }.max
+      max = 1.0 if max <= 0
+
+      height = rows.size * (BAR_HEIGHT + BAR_GAP)
+      width = LABEL_WIDTH + TRACK_WIDTH + 90
+
+      bars = rows.each_with_index.map do |(text, v), i|
+        y = i * (BAR_HEIGHT + BAR_GAP)
+        bar_w = ((v / max) * TRACK_WIDTH).round(2)
+        svg_bar(text, format.call(v), y, bar_w)
+      end.join
+
+      content_tag(
+        :svg,
+        raw(bars),
+        xmlns: "http://www.w3.org/2000/svg",
+        viewBox: "0 0 #{width} #{height}",
+        role: "img",
+        class: "chart",
+        style: "width:100%;max-width:#{width}px;height:auto;"
+      )
+    end
+
+    # Colored pill for an ad's flight status (:active/:scheduled/:ended/:evergreen).
+    #
+    def status_badge(status)
+      status ||= :evergreen
+      color = STATUS_COLORS.fetch(status, STATUS_COLORS[:evergreen])
+      content_tag(:span, status.to_s, class: "badge",
+                                      style: "background:#{color};")
+    end
+
+    # Human-readable flight window; an em dash when the ad has no bounds.
+    #
+    def flight_window(starts_at, ends_at)
+      return "\u2014" if starts_at.nil? && ends_at.nil?
+
+      from = starts_at ? starts_at.strftime("%Y-%m-%d") : "\u2026"
+      to = ends_at ? ends_at.strftime("%Y-%m-%d") : "\u2026"
+      "#{from} \u2192 #{to}"
+    end
+
+    # A campaign detail table for a set of report rows, sorted by descending
+    # spend. Returns nil for an empty set so callers can skip the section.
+    #
+    def campaign_table(rows)
+      return if rows.nil? || rows.empty?
+
+      header = content_tag(:thead, content_tag(:tr,
+                                               safe_join([
+                                                           content_tag(:th, "Creative"),
+                                                           content_tag(:th, "Status"),
+                                                           content_tag(:th, "Flight"),
+                                                           content_tag(:th, "Impressions", class: "num"),
+                                                           content_tag(:th, "CPM", class: "num"),
+                                                           content_tag(:th, "Spend", class: "num")
+                                                         ])))
+
+      body = content_tag(:tbody, safe_join(
+                                   rows.sort_by { |ad| -ad[:spend] }.map { |ad| campaign_row(ad) }
+                                 ))
+
+      content_tag(:table, safe_join([header, body]))
+    end
+
+    private
+
+    def campaign_row(ad)
+      content_tag(:tr, safe_join([
+                                   content_tag(:td, ad[:text]),
+                                   content_tag(:td, status_badge(ad[:status])),
+                                   content_tag(:td, flight_window(ad[:starts_at], ad[:ends_at]), class: "flight"),
+                                   content_tag(:td, ad[:impressions], class: "num"),
+                                   content_tag(:td, "$#{format("%.2f", ad[:cpm])}", class: "num"),
+                                   content_tag(:td, "$#{format("%.2f", ad[:spend])}", class: "num")
+                                 ]))
+    end
+
+    def svg_bar(label, value_label, y, bar_w)
+      text_y = y + (BAR_HEIGHT / 2) + 4
+      label_text = esc(truncate_label(label))
+      value_text = esc(value_label)
+
+      %(
+        <text x="0" y="#{text_y}" class="bar-label">#{label_text}</text>
+        <rect x="#{LABEL_WIDTH}" y="#{y}" width="#{TRACK_WIDTH}" height="#{BAR_HEIGHT}" class="bar-track"/>
+        <rect x="#{LABEL_WIDTH}" y="#{y}" width="#{bar_w}" height="#{BAR_HEIGHT}" class="bar-fill"/>
+        <text x="#{LABEL_WIDTH + bar_w + VALUE_PAD}" y="#{text_y}" class="bar-value">#{value_text}</text>
+      )
+    end
+
+    # Truncate the raw text first, then escape, so we never slice through an
+    # HTML entity.
+    #
+    def truncate_label(text)
+      raw_text = text.to_s
+      raw_text.length > 46 ? "#{raw_text[0, 45]}\u2026" : raw_text
+    end
+
+    def esc(value)
+      ERB::Util.html_escape(value.to_s)
+    end
+  end
+end

data/lib/sponsored_logs/report/app/views/sponsored_logs/reports/show.html.erb

@@ -0,0 +1,72 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Campaign Performance</title>
+  <style>
+    body { font-family: -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif;
+           margin: 2rem auto; max-width: 60rem; color: #1a1a1a; }
+    h1 { font-size: 1.4rem; margin-bottom: 0.25rem; }
+    .subtitle { color: #666; margin-top: 0; font-size: 0.9rem; }
+    .totals { display: flex; gap: 2rem; margin: 1.5rem 0; }
+    .totals div { background: #f4f4f6; border-radius: 8px; padding: 1rem 1.25rem; }
+    .totals .label { display: block; font-size: 0.75rem; text-transform: uppercase;
+                     letter-spacing: 0.05em; color: #888; }
+    .totals .value { font-size: 1.6rem; font-weight: 600; }
+    table { width: 100%; border-collapse: collapse; margin-top: 1rem; }
+    th, td { text-align: left; padding: 0.6rem 0.75rem; border-bottom: 1px solid #eee; }
+    th { font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.05em; color: #888; }
+    td.num, th.num { text-align: right; font-variant-numeric: tabular-nums; }
+    .empty { color: #888; font-style: italic; margin-top: 1.5rem; }
+    h2 { font-size: 0.95rem; text-transform: uppercase; letter-spacing: 0.05em;
+         color: #888; margin: 2rem 0 0.5rem; }
+    .chart { display: block; }
+    .chart .bar-label { font-size: 12px; fill: #333; }
+    .chart .bar-value { font-size: 12px; fill: #555; font-variant-numeric: tabular-nums; }
+    .chart .bar-track { fill: #f0f0f3; rx: 4; }
+    .chart .bar-fill { fill: #4f46e5; rx: 4; }
+    .badge { display: inline-block; padding: 0.15rem 0.5rem; border-radius: 999px;
+             color: #fff; font-size: 0.7rem; text-transform: uppercase;
+             letter-spacing: 0.03em; }
+    td.flight { font-variant-numeric: tabular-nums; color: #555; white-space: nowrap; }
+  </style>
+</head>
+<body>
+  <h1>Campaign Performance</h1>
+  <p class="subtitle">Sponsored message delivery report</p>
+
+  <div class="totals">
+    <div>
+      <span class="label">Impressions</span>
+      <span class="value"><%= @report[:impressions] %></span>
+    </div>
+    <div>
+      <span class="label">Total spend</span>
+      <span class="value">$<%= format("%.2f", @report[:spend]) %></span>
+    </div>
+  </div>
+
+  <% if @report[:ads].empty? %>
+    <p class="empty">No impressions delivered yet.</p>
+  <% else %>
+    <h2>Spend by advertiser</h2>
+    <%= bar_chart(@report[:ads], value: ->(ad) { ad[:spend] }, format: ->(v) { "$#{format('%.2f', v)}" }) %>
+
+    <h2>Impressions by advertiser</h2>
+    <%= bar_chart(@report[:ads], value: ->(ad) { ad[:impressions] }, format: ->(v) { v.to_i.to_s }) %>
+
+    <h2>Running campaigns</h2>
+    <%= campaign_table(@report[:ads]) %>
+  <% end %>
+
+  <% if @report[:upcoming].any? %>
+    <h2>Upcoming campaigns</h2>
+    <%= campaign_table(@report[:upcoming]) %>
+  <% end %>
+
+  <% if @report[:finished].any? %>
+    <h2>Finished campaigns</h2>
+    <%= campaign_table(@report[:finished]) %>
+  <% end %>
+</body>
+</html>

data/lib/sponsored_logs/report/config/routes.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+SponsoredLogs::Engine.routes.draw do
+  root to: "reports#show"
+
+  # Allow an explicit .json (or other) format suffix, e.g.
+  # /sponsored_logs_report.json, since the root route does not capture it.
+  #
+  get "(.:format)", to: "reports#show"
+end

data/lib/sponsored_logs/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SponsoredLogs
+  VERSION = "0.1.0"
+end

data/lib/sponsored_logs.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "logger"
+
+require_relative "sponsored_logs/version"
+require_relative "sponsored_logs/advertisers"
+require_relative "sponsored_logs/ads_file"
+require_relative "sponsored_logs/ledger/store/base"
+require_relative "sponsored_logs/ledger/store/memory"
+require_relative "sponsored_logs/ledger/store/redis"
+require_relative "sponsored_logs/ledger/store/active_record"
+require_relative "sponsored_logs/ledger/report"
+require_relative "sponsored_logs/configuration"
+require_relative "sponsored_logs/injector"
+require_relative "sponsored_logs/env"
+
+module SponsoredLogs
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # Activate ad insertion, applying any settings from the options hash (see
+    # Configuration#assign for the recognized keys). Settings can also be set
+    # ahead of time with configure { |c| ... }.
+    #
+    def sponsor!(opts = {})
+      configuration.assign(opts)
+
+      Injector.install!
+      @active = true
+
+      start_periodic_thread if configuration.periodic
+
+      self
+    end
+
+    def unsponsor!
+      @active = false
+      stop_periodic_thread
+      self
+    end
+
+    # Activate from ENV if SPONSORED_LOGS is set, applying any
+    # SPONSORED_LOGS_* overrides. No-op when the flag is absent, so the
+    # manual sponsor!/unsponsor! path is entirely unaffected.
+    #
+    def sponsor_from_env!(env = ENV)
+      return self unless Env.activate?(env)
+
+      sponsor!(Env.options(env))
+    end
+
+    def active?
+      @active == true
+    end
+
+    def maybe_emit(target: $stdout)
+      return unless active?
+      return unless rand < configuration.probability
+
+      emit(target)
+    end
+
+    def emit(target = configuration.output)
+      ad = Advertisers.pick(
+        configuration.ads,
+        mode: configuration.selection,
+        counts: ledger.impression_counts
+      )
+      return if ad.nil?
+
+      ledger.record(ad)
+      line = Advertisers.render(ad, configuration.ad_prefix)
+
+      if target.is_a?(Logger)
+        # Raw << avoids re-triggering our own Logger#add patch (infinite loop).
+        #
+        target << "#{line}\n"
+      else
+        target.write("#{line}\n")
+      end
+
+      line
+    end
+
+    # Rebuilt when the configured store changes, so swapping the store via
+    # sponsor!(store:) takes effect immediately.
+    #
+    def ledger
+      if @ledger.nil? || @ledger_store != configuration.store
+        @ledger = Ledger::Report.new(configuration.store)
+        @ledger_store = configuration.store
+      end
+      @ledger
+    end
+
+    # Accrued fake ad economics: per-ad impressions and spend, plus totals.
+    # Spend is rounded to cents here; the ledger keeps the raw values.
+    #
+    # Every ad appears in exactly one group, by status:
+    # - upcoming: :scheduled (window not started yet).
+    # - finished: :ended (window passed) or :exhausted (impression cap reached).
+    # - ads:      running campaigns (:active / :evergreen) that have served.
+    #
+    # Running rows are impression-driven (served ads only); upcoming and
+    # finished also include configured ads that have not served, so scheduled
+    # and completed campaigns still appear.
+    #
+    def report
+      grouped = grouped_report_rows
+
+      {
+        impressions: ledger.total_impressions,
+        spend: ledger.total_spend.round(2),
+        ads: grouped[:running],
+        upcoming: grouped[:upcoming],
+        finished: grouped[:finished]
+      }
+    end
+
+    # A formatted, log-friendly table of the current report, ready to print or
+    # log. Ads are listed by descending spend.
+    #
+    def report_text
+      data = report
+      rows = data[:ads].sort_by { |ad| -ad[:spend] }
+
+      width = rows.map { |ad| ad[:text].length }.push(4).max
+      lines = [format("%-#{width}s  %8s  %7s  %9s", "Ad", "Impr", "CPM", "Spend")]
+      lines << ("-" * (width + 30))
+
+      rows.each do |ad|
+        lines << format("%-#{width}s  %8d  %7.2f  %9.2f", ad[:text], ad[:impressions], ad[:cpm], ad[:spend])
+      end
+
+      lines << ("-" * (width + 30))
+      lines << format("%-#{width}s  %8d  %7s  %9.2f", "TOTAL", data[:impressions], "", data[:spend])
+      lines.join("\n")
+    end
+
+    def reset_ledger!
+      ledger.reset
+      self
+    end
+
+    private
+
+    # Map of ad text => normalized config metadata (weight/cpm/flight/cap),
+    # used to enrich report rows and drive status.
+    #
+    def ad_metadata
+      Advertisers.normalize(configuration.ads).to_h { |ad| [ad[:text], ad] }
+    end
+
+    # Partition every known ad (served or configured) into running / upcoming /
+    # finished report rows by flight-and-cap status.
+    #
+    def grouped_report_rows
+      now = Time.now
+      metas = ad_metadata
+      counts = ledger.impression_counts
+      served = ledger.entries.to_h { |entry| [entry.text, entry] }
+
+      grouped = Hash.new { |h, k| h[k] = [] }
+
+      (served.keys + metas.keys).uniq.each do |text|
+        meta = metas[text] || {}
+        status = Advertisers.status(meta, now, counts[text].to_i)
+        row = report_row(text, meta, served[text], status)
+
+        case status
+        when :scheduled then grouped[:upcoming] << row
+        when :ended, :exhausted then grouped[:finished] << row
+        else grouped[:running] << row if served[text]
+        end
+      end
+
+      grouped
+    end
+
+    # A single report row. Impressions/spend come from the ledger entry when the
+    # ad has served, otherwise zero; window/cap come from config metadata.
+    #
+    def report_row(text, meta, entry, status)
+      {
+        text: text,
+        impressions: entry ? entry.impressions : 0,
+        cpm: entry ? entry.cpm : meta[:cpm].to_f,
+        spend: entry ? entry.spend.round(2) : 0.0,
+        starts_at: meta[:starts_at],
+        ends_at: meta[:ends_at],
+        cap: meta[:cap],
+        status: status
+      }
+    end
+
+    def start_periodic_thread
+      stop_periodic_thread
+      @periodic_thread = Thread.new do
+        loop do
+          sleep(configuration.interval)
+          break unless active? && configuration.periodic
+
+          emit(configuration.output)
+        end
+      end
+    end
+
+    def stop_periodic_thread
+      @periodic_thread&.kill
+      @periodic_thread = nil
+    end
+  end
+end
+
+SponsoredLogs.sponsor_from_env!
+
+require_relative "sponsored_logs/railtie" if defined?(Rails::Railtie)
+require_relative "sponsored_logs/engine" if defined?(Rails::Engine)

metadata

@@ -0,0 +1,163 @@
+--- !ruby/object:Gem::Specification
+name: sponsored_logs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kerri Miller
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: |
+  Randomly and periodically inserts host-read sponsor messages from the top 10
+  podcast advertisers into your application logs. Opt-in and fully configurable.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/generators/sponsored_logs/install_generator.rb
+- lib/generators/sponsored_logs/templates/create_sponsored_logs_impressions.rb.tt
+- lib/sponsored_logs.rb
+- lib/sponsored_logs/ads_file.rb
+- lib/sponsored_logs/advertisers.rb
+- lib/sponsored_logs/configuration.rb
+- lib/sponsored_logs/engine.rb
+- lib/sponsored_logs/env.rb
+- lib/sponsored_logs/injector.rb
+- lib/sponsored_logs/ledger/report.rb
+- lib/sponsored_logs/ledger/store/active_record.rb
+- lib/sponsored_logs/ledger/store/base.rb
+- lib/sponsored_logs/ledger/store/memory.rb
+- lib/sponsored_logs/ledger/store/redis.rb
+- lib/sponsored_logs/railtie.rb
+- lib/sponsored_logs/report/app/controllers/sponsored_logs/reports_controller.rb
+- lib/sponsored_logs/report/app/helpers/sponsored_logs/reports_helper.rb
+- lib/sponsored_logs/report/app/views/sponsored_logs/reports/show.html.erb
+- lib/sponsored_logs/report/config/routes.rb
+- lib/sponsored_logs/version.rb
+homepage: https://github.com/kerrizor/sponsored_logs
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/kerrizor/sponsored_logs
+  bug_tracker_uri: https://github.com/kerrizor/sponsored_logs/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Inserts sponsor messages from leading advertisers into your logs.
+test_files: []