gopromotional-mugday 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 69228c57c9dde5eba70528abf2843f0ce85c359cea5ecc5a0206bb25bd74dcc4
+  data.tar.gz: 3a7e4e8ced9a1c97727d1f74cd745c74ef5ccca1ad500899c23cb58606b3b88f
+SHA512:
+  metadata.gz: 5a3a844ac2e27fceda0e1eacba245668f2e2358e79d1609dbe9a0e6db226116b62a9633172529e76cf9cd7ea22a075eece2d32aa70ddc29577a25a0fdf142b18
+  data.tar.gz: 2daf36484f85c470f95ccf8848da637ec95cfd5347110fcd16966eccde6c18d6a4960d330911171de2f9708c7755f37f9ef751dd15fd8c4a371257dd0338255f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GoPromotional
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,76 @@
+# gopromotional-mugday
+
+Log coffee, tea and other drinks with typical caffeine values, compare the day's total with a limit (400 mg adult, 200 mg in pregnancy), estimate how much caffeine is still in your system, find out when it should drop below a sleep-friendly level, and track how often you used a reusable cup. Typical values only; not medical advice.
+
+- **16 drinks** with typical caffeine (espresso 63 mg, filter coffee 140 mg, tea 75 mg, cola 40 mg...), or pass your own mg.
+- **Daily total** against a limit: 400 mg (adult) or 200 mg (pregnancy), or your own.
+- **Caffeine in your system** using a 5-hour half-life (configurable).
+- **Sleep-ready time**: when the level should fall below a threshold (default 50 mg), rounded up to 15 minutes.
+- **Reusable-cup stats** for the last 7 days.
+- Plain **JSON log** shared by the npm, PyPI, crates.io and RubyGems versions.
+
+## Install
+
+```sh
+gem install gopromotional-mugday
+# or in a Gemfile:
+gem "gopromotional-mugday"
+```
+
+## Command line
+
+```console
+$ gopromotional-mugday drinks
+espresso               63 mg  (30 ml)
+double-espresso       126 mg  (60 ml)
+americano             126 mg  (350 ml)
+latte                 126 mg  (350 ml)
+cappuccino            126 mg  (350 ml)
+...
+
+$ gopromotional-mugday add flat-white --time 2026-10-19T08:00 --reusable
+Logged flat-white (126 mg, reusable cup). Today: 126/400 mg.
+
+$ gopromotional-mugday add tea --time 2026-10-19T11:00 --reusable
+Logged tea (75 mg, reusable cup). Today: 201/400 mg.
+
+$ gopromotional-mugday add filter-coffee --time 2026-10-19T14:00
+Logged filter-coffee (140 mg). Today: 341/400 mg.
+
+$ gopromotional-mugday today --date 2026-10-19
+2026-10-19: 341 mg from 3 drink(s); 59 mg left of 400 mg.
+
+$ gopromotional-mugday in-system --at 2026-10-19T22:00
+About 81 mg of caffeine still in your system at 2026-10-19T22:00 (half-life 5 h).
+
+$ gopromotional-mugday sleep-ready
+Below 50 mg from about 2026-10-20 01:30.
+
+$ gopromotional-mugday cups --date 2026-10-19
+Last 7 days: 2 reusable, 1 disposable (67% reusable).
+```
+
+Every command accepts `--json` for machine-readable output. Run `gopromotional-mugday --help` for all options.
+
+Data is kept in `~/.gopromotional-mugday.json` (set `GOPROMOTIONAL_MUGDAY_FILE` or pass `--file` to use another file). The JSON format is the same across the npm, PyPI, crates.io and RubyGems versions, so you can switch tools without losing your log.
+
+## Library
+
+```ruby
+require "gopromotional/mugday"
+M = GoPromotional::Mugday
+
+log = M::CaffeineLog.new                        # limit 400 mg, half-life 5 h
+log.add("flat-white", time: "2026-10-19T08:00", reusable: true)
+log.add("filter-coffee", time: "2026-10-19T14:00")
+log.day("2026-10-19")[:total]                   # => 266
+log.sleep_ready(50)                             # => "2026-10-20T00:00"
+```
+
+Pure Ruby, no runtime dependencies, Ruby 3.0+. `require "gopromotional-mugday"` also works.
+
+## Links
+
+- Website: [branded travel mugs for event marketing](https://www.gopromotional.co.uk/branded-products/travel-mugs)
+- Source code: [https://github.com/nbkdevs/GoPromotional](https://github.com/nbkdevs/GoPromotional) (`packages/travel-mugs/rubygems`)
+- Licence: MIT

data/exe/gopromotional-mugday

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/gopromotional/mugday/cli"
+exit GoPromotional::Mugday::CLI.run(ARGV)

data/lib/gopromotional/mugday/cli.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../mugday"
+
+module GoPromotional
+  module Mugday
+    # Command line interface: drinks | add | today | in-system | sleep-ready | cups | undo
+    module CLI
+      USAGE = <<~TXT
+        Usage: gopromotional-mugday <command> [options]
+
+        Commands:
+          drinks                                typical caffeine per drink
+          add <drink> [--time T] [--mg N] [--reusable]
+          today [--date D] [--limit N]          total for a day
+          in-system [--at T]                    caffeine still in your system
+          sleep-ready [--threshold 50]          when caffeine drops below a threshold
+          cups [--date D]                       reusable vs disposable cups, last 7 days
+          undo                                  remove the last drink
+
+        Options: --file PATH (default $GOPROMOTIONAL_MUGDAY_FILE or ~/.gopromotional-mugday.json), --json
+        Times are YYYY-MM-DDTHH:MM. Caffeine values are typical figures; not medical advice.
+      TXT
+
+      module_function
+
+      def default_file
+        env = ENV.fetch("GOPROMOTIONAL_MUGDAY_FILE", "")
+        env.empty? ? File.join(Dir.home, ".gopromotional-mugday.json") : env
+      end
+
+      def run(argv, out: $stdout, err: $stderr)
+        o = { json: false, reusable: false, threshold: 50.0 }
+        parser = OptionParser.new do |p|
+          p.banner = USAGE
+          p.on("--json") { o[:json] = true }
+          p.on("--file PATH") { |v| o[:file] = v }
+          p.on("--time T") { |v| o[:time] = v }
+          p.on("--mg N", Float) { |v| o[:mg] = v }
+          p.on("--reusable") { o[:reusable] = true }
+          p.on("--date D") { |v| o[:date] = v }
+          p.on("--limit N", Float) { |v| o[:limit] = v }
+          p.on("--at T") { |v| o[:at] = v }
+          p.on("--threshold N", Float) { |v| o[:threshold] = v }
+          p.on("-v", "--version") { out.puts VERSION; return 0 }
+          p.on("-h", "--help") { out.puts USAGE; return 0 }
+        end
+        args = parser.parse(argv)
+        cmd = args.shift
+        n = ->(x) { Mugday.num(x) }
+        case cmd
+        when nil
+          out.puts USAGE
+          return 0
+        when "drinks"
+          out.puts(o[:json] ? JSON.pretty_generate(DRINKS) :
+            DRINKS.map { |k, v| "#{k.ljust(20)} #{v[:mg].to_s.rjust(4)} mg#{v[:ml].positive? ? "  (#{v[:ml]} ml)" : ''}" })
+          return 0
+        end
+        path = o[:file] || default_file
+        log = File.exist?(path) ? CaffeineLog.from_json(File.read(path, encoding: "utf-8")) : CaffeineLog.new
+        save = -> { File.write(path, "#{log.to_json}\n") }
+        case cmd
+        when "add"
+          raise ArgumentError, "add needs a drink name (see `drinks`)" if args.empty?
+          e = log.add(args.join(" "), time: o[:time] || Mugday.now_local, mg: o[:mg] && n.(o[:mg]), reusable: o[:reusable])
+          save.call
+          d = log.day(e.time[0, 10])
+          r = e.to_h
+          text = "Logged #{e.drink} (#{n.(e.mg)} mg#{e.reusable ? ', reusable cup' : ''}). Today: #{n.(d[:total])}/#{n.(d[:limit])} mg."
+        when "today"
+          r = log.day(o[:date], limit: o[:limit] && n.(o[:limit]))
+          text = "#{r[:date]}: #{n.(r[:total])} mg from #{r[:drinks]} drink(s); " +
+                 (r[:over].positive? ? "#{n.(r[:over])} mg over the #{n.(r[:limit])} mg limit." : "#{n.(r[:remaining])} mg left of #{n.(r[:limit])} mg.")
+        when "in-system"
+          at = o[:at] || Mugday.now_local
+          r = { at: at, mg: log.in_system(at) }
+          text = "About #{r[:mg]} mg of caffeine still in your system at #{at} (half-life #{n.(log.half_life_hours)} h)."
+        when "sleep-ready"
+          raise ArgumentError, "--threshold must be above 0" unless o[:threshold].positive?
+          t = log.sleep_ready(o[:threshold])
+          r = { threshold: n.(o[:threshold]), time: t }
+          text = t ? "Below #{n.(o[:threshold])} mg from about #{t.tr('T', ' ')}." : "No drinks logged."
+        when "cups"
+          r = log.cups(o[:date])
+          text = "Last 7 days: #{r[:reusable]} reusable, #{r[:disposable]} disposable (#{r[:rate]}% reusable)."
+        when "undo"
+          e = log.undo
+          save.call
+          r = e&.to_h
+          text = e ? "Removed #{e.drink} at #{e.time}." : "Nothing to undo."
+        else
+          raise ArgumentError, %(Unknown command "#{cmd}". Run with --help.)
+        end
+        out.puts(o[:json] ? JSON.pretty_generate(r) : text)
+        0
+      rescue ArgumentError, OptionParser::ParseError, SystemCallError, JSON::ParserError => e
+        err.puts "Error: #{e.message}"
+        2
+      end
+    end
+  end
+end

data/lib/gopromotional/mugday/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module GoPromotional
+  module Mugday
+    VERSION = "1.0.0"
+  end
+end

data/lib/gopromotional/mugday.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "date"
+require "json"
+require_relative "mugday/version"
+
+module GoPromotional
+  # Caffeine and coffee intake tracker: typical caffeine per drink, daily totals against a limit, an
+  # estimate of caffeine still in your system (half-life model), a "sleep-ready" time and reusable-cup
+  # stats. Values are typical figures; real drinks vary. Not medical advice.
+  module Mugday
+    DRINKS = {
+      "espresso" => { mg: 63, ml: 30 }, "double-espresso" => { mg: 126, ml: 60 },
+      "americano" => { mg: 126, ml: 350 }, "latte" => { mg: 126, ml: 350 },
+      "cappuccino" => { mg: 126, ml: 350 }, "flat-white" => { mg: 126, ml: 220 },
+      "filter-coffee" => { mg: 140, ml: 300 }, "instant-coffee" => { mg: 100, ml: 300 },
+      "cold-brew" => { mg: 155, ml: 350 }, "decaf-coffee" => { mg: 3, ml: 300 },
+      "tea" => { mg: 75, ml: 300 }, "green-tea" => { mg: 30, ml: 300 },
+      "cola" => { mg: 40, ml: 330 }, "energy-drink" => { mg: 80, ml: 250 },
+      "hot-chocolate" => { mg: 5, ml: 300 }, "dark-chocolate-50g" => { mg: 25, ml: 0 }
+    }.freeze
+    LIMITS = { adult: 400, pregnant: 200, single_dose: 200 }.freeze
+    DEFAULT_HALF_LIFE_HOURS = 5
+    TIME = /\A(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})\z/
+    EPOCH = Date.new(1970, 1, 1)
+
+    module_function
+
+    def round_half_up(x) = (x + 0.5).floor
+    def norm(name) = name.to_s.strip.downcase.gsub(/[\s_]+/, "-")
+    def num(x) = x.is_a?(Float) && x == x.floor ? x.to_i : x
+
+    # "YYYY-MM-DDTHH:MM" (naive local time) to minutes since 1970-01-01.
+    def to_minutes(value)
+      m = TIME.match(value.to_s.strip) or raise ArgumentError, %(Invalid time "#{value}" (expected YYYY-MM-DDTHH:MM))
+      y, mo, d, h, mi = m.captures.map(&:to_i)
+      raise ArgumentError, %(Invalid time "#{value}") unless Date.valid_date?(y, mo, d) && h < 24 && mi < 60
+      (Date.new(y, mo, d) - EPOCH).to_i * 1440 + h * 60 + mi
+    end
+
+    def from_minutes(minutes)
+      day, rem = minutes.divmod(1440)
+      format("%sT%02d:%02d", (EPOCH + day).iso8601, rem / 60, rem % 60)
+    end
+
+    def now_local = Time.now.strftime("%Y-%m-%dT%H:%M")
+
+    def lookup_drink(name)
+      k = norm(name)
+      info = DRINKS[k] or raise ArgumentError, %(Unknown drink "#{name}". Known: #{DRINKS.keys.join(', ')} (or pass mg yourself))
+      { drink: k, **info }
+    end
+
+    Drink = Struct.new(:drink, :mg, :time, :reusable) do
+      def to_h = { "drink" => drink, "mg" => Mugday.num(mg), "time" => time, "reusable" => reusable }
+    end
+
+    # Caffeine log. The JSON file format ({limit, halfLifeHours, entries}) is shared with the npm,
+    # PyPI and crates.io versions.
+    class CaffeineLog
+      attr_accessor :limit, :half_life_hours
+      attr_reader :entries
+
+      def initialize(limit: LIMITS[:adult], half_life_hours: DEFAULT_HALF_LIFE_HOURS, entries: [])
+        @limit = limit
+        @half_life_hours = half_life_hours
+        @entries = []
+        entries.each do |e|
+          e = e.to_h.transform_keys(&:to_s)
+          add(e["drink"], time: e["time"], mg: e["mg"], reusable: e["reusable"] || false)
+        end
+      end
+
+      def self.from_json(data)
+        d = data.is_a?(String) ? JSON.parse(data) : (data || {})
+        new(limit: d.fetch("limit", LIMITS[:adult]),
+            half_life_hours: d["halfLifeHours"] || d["half_life_hours"] || DEFAULT_HALF_LIFE_HOURS,
+            entries: d.fetch("entries", []))
+      end
+
+      def to_h = { "limit" => Mugday.num(limit), "halfLifeHours" => Mugday.num(half_life_hours), "entries" => entries.map(&:to_h) }
+      def to_json(*_args) = JSON.pretty_generate(to_h)
+
+      # Log a drink. mg overrides the typical value (handy for unknown drinks).
+      def add(drink, time: nil, mg: nil, reusable: false)
+        name = Mugday.norm(drink)
+        if mg.nil?
+          info = Mugday.lookup_drink(drink)
+          name = info[:drink]
+          mg = info[:mg]
+        end
+        raise ArgumentError, "mg must be between 0 and 1000" unless mg.is_a?(Numeric) && mg >= 0 && mg <= 1000
+        e = Drink.new(name, mg, Mugday.from_minutes(Mugday.to_minutes(time || Mugday.now_local)), reusable ? true : false)
+        @entries << e
+        @entries.sort_by!.with_index { |x, i| [Mugday.to_minutes(x.time), i] }
+        e
+      end
+
+      def undo = @entries.pop
+      def for_day(day) = @entries.select { |e| e.time[0, 10] == day }
+
+      def day(day = nil, limit: nil)
+        d = day || Mugday.now_local[0, 10]
+        lim = limit || @limit
+        items = for_day(d)
+        total = items.sum(&:mg)
+        { date: d, drinks: items.size, total: total, limit: lim, remaining: [0, lim - total].max, over: [0, total - lim].max }
+      end
+
+      def level(t)
+        @entries.sum do |e|
+          dt = t - Mugday.to_minutes(e.time)
+          dt >= 0 ? e.mg * (0.5**(dt / 60.0 / @half_life_hours)) : 0
+        end
+      end
+
+      # Estimated caffeine (mg) still in the body at `at`.
+      def in_system(at = nil) = Mugday.round_half_up(level(Mugday.to_minutes(at || Mugday.now_local)))
+
+      # Earliest time (rounded up to 15 min) caffeine falls below threshold, if nothing more is drunk.
+      def sleep_ready(threshold = 50)
+        return nil if @entries.empty?
+        last = Mugday.to_minutes(@entries.last.time)
+        lv = level(last)
+        return Mugday.from_minutes(last) if lv <= threshold
+        minutes = @half_life_hours * 60 * Math.log2(lv / threshold.to_f)
+        Mugday.from_minutes(((last + minutes) / 15.0).ceil * 15)
+      end
+
+      # Reusable vs disposable cups over the 7 days ending on end_day.
+      def cups(end_day = nil)
+        e = Mugday.to_minutes("#{end_day || Mugday.now_local[0, 10]}T00:00") / 1440
+        week = @entries.select { |x| d = Mugday.to_minutes("#{x.time[0, 10]}T00:00") / 1440; d > e - 7 && d <= e }
+        reusable = week.count(&:reusable)
+        { reusable: reusable, disposable: week.size - reusable,
+          rate: week.empty? ? 0 : Mugday.round_half_up(reusable * 100.0 / week.size) }
+      end
+    end
+  end
+end

data/lib/gopromotional-mugday.rb

@@ -0,0 +1 @@
+require_relative "gopromotional/mugday"

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: gopromotional-mugday
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- GoPromotional
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Log coffee, tea and other drinks with typical caffeine values, compare
+  the day's total with a limit (400 mg adult, 200 mg in pregnancy), estimate how much
+  caffeine is still in your system, find out when it should drop below a sleep-friendly
+  level, and track how often you used a reusable cup. Typical values only; not medical
+  advice.
+executables:
+- gopromotional-mugday
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/gopromotional-mugday
+- lib/gopromotional-mugday.rb
+- lib/gopromotional/mugday.rb
+- lib/gopromotional/mugday/cli.rb
+- lib/gopromotional/mugday/version.rb
+homepage: https://www.gopromotional.co.uk/branded-products/travel-mugs
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.gopromotional.co.uk/branded-products/travel-mugs
+  source_code_uri: https://github.com/nbkdevs/GoPromotional/tree/main/packages/travel-mugs/rubygems
+  bug_tracker_uri: https://github.com/nbkdevs/GoPromotional/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Caffeine tracker with half-life estimate, sleep-ready time and reusable-cup
+  stats.
+test_files: []