wintoast 0.1.0 → 0.1.1

data/lib/wintoast/payload.rb

@@ -1,195 +0,0 @@
-# frozen_string_literal: true
-
-module Wintoast
-  # Wintoast::Payload — the ToastGeneric XML builder.
-  #
-  # A pure function with no OS calls: it turns a title/body plus presentation
-  # kwargs into the exact UTF-8 XML string that Wintoast.toast hands to the WinRT
-  # LoadXml call. Exposed publicly so you can inspect "what would you send?" and
-  # as the unit-test seam for the escaping / control-char / audio-table rules.
-  #
-  #   Wintoast::Payload.build("Build done", "42 files", audio: :mail)
-  #   # => "<toast>...<binding template=\"ToastGeneric\">...</toast>"
-  #
-  # It validates only the kwargs that affect the XML (attribution:, image:,
-  # hero:, circle:, audio:, duration:, scenario:). aumid:/tag:/group:/expires_*
-  # are WinRT properties, not part of the XML, and are NOT accepted here.
-  module Payload
-    module_function
-
-    # Accepted <audio> symbols -> the ms-winsoundevent token (without the
-    # "ms-winsoundevent:" prefix) and whether the sound loops. These are the
-    # ONLY sounds Windows honors for unpackaged apps; arbitrary file paths
-    # silently fall back to the default sound, so they are not accepted.
-    SHORT_SOUNDS = {
-      im:       "Notification.IM",
-      mail:     "Notification.Mail",
-      reminder: "Notification.Reminder",
-      sms:      "Notification.SMS"
-    }.freeze
-    private_constant :SHORT_SOUNDS
-
-    # Looping families: :alarm/:call plus :alarm2..:alarm10 / :call2..:call10.
-    # ms-winsoundevent uses "Looping.Alarm" (no 1) and "Looping.Alarm2".."10".
-    DURATIONS = %i[short long].freeze
-    private_constant :DURATIONS
-
-    SCENARIOS = {
-      alarm:         "alarm",
-      incoming_call: "incomingCall",
-      urgent:        "urgent"
-    }.freeze
-    private_constant :SCENARIOS
-
-    # Build the ToastGeneric XML. Returns a fresh, unfrozen UTF-8 String.
-    def build(title, body = nil,
-              attribution: nil,
-              image:       nil,
-              hero:        nil,
-              circle:      false,
-              audio:       :default,
-              duration:    :short,
-              scenario:    nil)
-      title_text = scrub_required(title, "title")
-      body_text  = body.nil?        ? nil : scrub_text(body, "body")
-      attr_text  = attribution.nil? ? nil : scrub_text(attribution, "attribution")
-
-      unless DURATIONS.include?(duration)
-        raise ArgumentError, "wintoast: duration: must be :short or :long, got #{duration.inspect}"
-      end
-      unless scenario.nil? || SCENARIOS.key?(scenario)
-        raise ArgumentError,
-              "wintoast: scenario: must be nil, :alarm, :incoming_call, or :urgent, got #{scenario.inspect}"
-      end
-
-      image_src = validate_image(image, "image")
-      hero_src  = validate_image(hero,  "hero")
-      if circle && image_src.nil?
-        raise ArgumentError, "wintoast: circle: true requires image:"
-      end
-
-      audio_xml = build_audio(audio)
-
-      toast_attrs = +""
-      toast_attrs << %( duration="long") if duration == :long
-      toast_attrs << %( scenario="#{SCENARIOS[scenario]}") if scenario
-
-      xml = +"<toast#{toast_attrs}>"
-      xml << "<visual><binding template=\"ToastGeneric\">"
-      xml << "<text>#{esc(title_text)}</text>"
-      xml << "<text>#{esc(body_text)}</text>" if body_text
-      xml << "<text placement=\"attribution\">#{esc(attr_text)}</text>" if attr_text
-      if image_src
-        crop = circle ? %( hint-crop="circle") : ""
-        xml << %(<image placement="appLogoOverride"#{crop} src="#{esc(image_src)}"/>)
-      end
-      if hero_src
-        xml << %(<image placement="hero" src="#{esc(hero_src)}"/>)
-      end
-      xml << "</binding></visual>"
-      xml << audio_xml if audio_xml
-      xml << "</toast>"
-      xml
-    end
-
-    # ---- validation / escaping helpers (module_function makes them callable) --
-
-    # Validate a String argument exists, normalize to UTF-8, and reject invalid
-    # UTF-8 BEFORE anything else (the §3.5 rule: never let bad bytes reach the C
-    # boundary — they would otherwise become a silently blank toast or a longjmp
-    # from the C conversion helper). Returns the UTF-8 String (control chars NOT
-    # yet scrubbed).
-    def normalize_utf8(value, label)
-      str = String.try_convert(value)
-      raise TypeError, "wintoast: #{label} must be a String, got #{value.class}" if str.nil?
-
-      str = str.encode(Encoding::UTF_8) unless str.encoding == Encoding::UTF_8
-      unless str.valid_encoding?
-        raise Wintoast::Error, "wintoast: invalid UTF-8 in #{label}"
-      end
-      str
-    rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError
-      # A string tagged in another encoding that cannot transcode to UTF-8.
-      raise Wintoast::Error, "wintoast: invalid UTF-8 in #{label}"
-    end
-
-    # Strip the C0 control characters that XML 1.0 forbids even as references
-    # (everything < 0x20 except TAB/LF/CR). Returns a scrubbed UTF-8 String.
-    def scrub_text(value, label)
-      normalize_utf8(value, label).gsub(/[\x00-\x08\x0b\x0c\x0e-\x1f]/, "")
-    end
-
-    # Like scrub_text but the result must be non-empty after scrubbing. A nil
-    # title is the "missing/empty" case (ArgumentError per §2.2), not a
-    # type error.
-    def scrub_required(value, label)
-      if value.nil?
-        raise ArgumentError, "wintoast: #{label} must be a non-empty string"
-      end
-
-      text = scrub_text(value, label)
-      if text.empty?
-        raise ArgumentError, "wintoast: #{label} must be a non-empty string"
-      end
-      text
-    end
-
-    # XML-escape the five metacharacters. Attribute positions are always
-    # double-quoted, so escaping " and ' covers both text and attribute use.
-    def esc(str)
-      str.gsub("&", "&amp;")
-         .gsub("<", "&lt;")
-         .gsub(">", "&gt;")
-         .gsub('"', "&quot;")
-         .gsub("'", "&apos;")
-    end
-
-    # Validate an image:/hero: path (nil passes through). Must be an absolute
-    # path to an existing regular file. Returns the scrubbed UTF-8 path or nil.
-    def validate_image(path, label)
-      return nil if path.nil?
-
-      str = normalize_utf8(path, label)
-      unless File.absolute_path?(str) && File.file?(str)
-        raise ArgumentError, "wintoast: #{label}: must be an absolute path to an existing file"
-      end
-      # Control chars are illegal in XML even in attributes; scrub for safety.
-      str.gsub(/[\x00-\x08\x0b\x0c\x0e-\x1f]/, "")
-    end
-
-    # Map audio: to an <audio> element string, or nil when the OS default is
-    # wanted (element omitted entirely).
-    def build_audio(audio)
-      case audio
-      when :default
-        nil
-      when false
-        %(<audio silent="true"/>)
-      when Symbol
-        if SHORT_SOUNDS.key?(audio)
-          %(<audio src="ms-winsoundevent:#{SHORT_SOUNDS[audio]}"/>)
-        elsif (token = looping_sound(audio))
-          %(<audio src="ms-winsoundevent:#{token}" loop="true"/>)
-        else
-          raise ArgumentError, "wintoast: unknown audio: #{audio.inspect}"
-        end
-      else
-        raise ArgumentError, "wintoast: unknown audio: #{audio.inspect}"
-      end
-    end
-
-    # :alarm / :alarm2..:alarm10 / :call / :call2..:call10 -> the Looping token,
-    # or nil if the symbol isn't a looping sound. :alarm1/:call1 and :alarm11+
-    # are rejected (Windows names them "Alarm" and "Alarm2".."Alarm10").
-    def looping_sound(sym)
-      m = /\A(alarm|call)([2-9]|10)?\z/.match(sym.to_s)
-      return nil unless m
-
-      base = m[1] == "alarm" ? "Alarm" : "Call"
-      "Notification.Looping.#{base}#{m[2]}"
-    end
-
-    private_class_method :normalize_utf8, :scrub_text, :scrub_required, :esc,
-                         :validate_image, :build_audio, :looping_sound
-  end
-end

data/lib/wintoast/version.rb

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