gopromotional-event-planner 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 669cde9f18ffe0247e676e6d896f66ab9a9912e078ee926eb4079158ffe5a33d
+  data.tar.gz: e2d25654ae355a5fad56fd3684abbddcea548d49c017ab46444f2f3a720aa3b1
+SHA512:
+  metadata.gz: 670fa9c1725886ad2b9d571cf0442e45feeada7a8e12e41905eeee483a92ead68d02aae905d05b189a427b5ac6b45c63a94b6d3a54da62ef1bb50c5a45bb49c7
+  data.tar.gz: c3deaa384b0be635f4428603315420b2ffb3a5999a73c1297cd6f5254f1fbf7d99b52d7abcc60978a117596767bbdf9c6ff14b9383bf4d4f3100031d27918e7a

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,59 @@
+# gopromotional-event-planner
+
+Plan an event or trade show from the command line or your code: a countdown, a 12-step planning timeline with due dates, an estimate of how many giveaway items to order, and the latest order date for printed merchandise in working days.
+
+- **Countdown** to the event in days, and in weeks + days.
+- **Planning timeline**: 12 tasks from 8 weeks out to the post-event follow-up, each with a due date, days left and an overdue flag.
+- **Giveaway quantity**: attendees × days × uptake × items per person, plus a buffer, rounded up.
+- **Order-by date**: production + delivery + safety margin counted back in working days (Mon–Fri).
+
+## Install
+
+```sh
+gem install gopromotional-event-planner
+# or in a Gemfile:
+gem "gopromotional-event-planner"
+```
+
+## Command line
+
+```console
+$ gopromotional-event-planner countdown 2026-12-03 --today 2026-10-19
+45 days to go (6 weeks 3 days) until 2026-12-03.
+
+$ gopromotional-event-planner giveaways --attendees 500 --days 2 --uptake 0.6
+Order 660 items (600 expected + 60 buffer).
+
+$ gopromotional-event-planner order-by 2026-12-03 --today 2026-10-19
+Order by 2026-11-12 (15 working days before the event), 24 days from today.
+
+$ gopromotional-event-planner timeline 2026-12-03 --today 2026-10-19
+! 2026-10-08  Confirm budget and attendee estimate  (overdue)
+! 2026-10-15  Book the venue  (overdue)
+  2026-10-22  Order branded merchandise and giveaways
+  2026-10-29  Send invitations or open registration
+  2026-11-05  Confirm speakers and agenda
+...
+```
+
+Every command accepts `--json` for machine-readable output. Run `gopromotional-event-planner --help` for all options.
+
+## Library
+
+```ruby
+require "gopromotional/event_planner"
+EP = GoPromotional::EventPlanner
+
+EP.countdown("2026-12-03", today: "2026-10-19")[:days]              # => 45
+EP.giveaway_quantity(attendees: 500, days: 2)                        # => {base: 600, buffer: 60, total: 660}
+EP.order_by_date("2026-12-03", today: "2026-10-19")[:order_by]       # => "2026-11-12"
+EP.timeline("2026-12-03", today: "2026-10-19").select { |r| r[:overdue] }
+```
+
+Pure Ruby, no runtime dependencies, Ruby 3.0+. `require "gopromotional-event-planner"` also works.
+
+## Links
+
+- Website: [https://www.gopromotional.co.uk/](https://www.gopromotional.co.uk/)
+- Source code: [https://github.com/nbkdevs/GoPromotional](https://github.com/nbkdevs/GoPromotional) (`packages/homepage/rubygems`)
+- Licence: MIT

data/exe/gopromotional-event-planner

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

data/lib/gopromotional/event_planner/cli.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../event_planner"
+
+module GoPromotional
+  module EventPlanner
+    # Command line interface: countdown | timeline | giveaways | order-by
+    module CLI
+      USAGE = <<~TXT
+        Usage: gopromotional-event-planner <command> [options]
+
+        Commands:
+          countdown <date>                 days until the event
+          timeline <date>                  planning checklist with due dates
+          giveaways --attendees N [--days N] [--uptake 0.6] [--per-person 1] [--buffer 0.1]
+          order-by <date> [--production 10] [--delivery 3] [--safety 2]
+
+        Options: --json, --today YYYY-MM-DD, -v/--version, -h/--help
+      TXT
+
+      module_function
+
+      def run(argv, out: $stdout, err: $stderr)
+        o = { json: false, today: Date.today.iso8601, days: 1.0, uptake: 0.6, per_person: 1.0, buffer: 0.1,
+              production: 10, delivery: 3, safety: 2 }
+        parser = OptionParser.new do |p|
+          p.banner = USAGE
+          p.on("--json") { o[:json] = true }
+          p.on("--today DATE") { |v| o[:today] = v }
+          p.on("--attendees N", Float) { |v| o[:attendees] = v }
+          p.on("--days N", Float) { |v| o[:days] = v }
+          p.on("--uptake N", Float) { |v| o[:uptake] = v }
+          p.on("--per-person N", Float) { |v| o[:per_person] = v }
+          p.on("--buffer N", Float) { |v| o[:buffer] = v }
+          p.on("--production N", Integer) { |v| o[:production] = v }
+          p.on("--delivery N", Integer) { |v| o[:delivery] = v }
+          p.on("--safety N", Integer) { |v| o[:safety] = 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
+        need_date = -> { args.first or raise ArgumentError, "#{cmd} needs an event date (YYYY-MM-DD)" }
+        case cmd
+        when "countdown"
+          r = EventPlanner.countdown(need_date.call, today: o[:today])
+          text = case r[:status]
+                 when "today" then "#{r[:event_date]} is today."
+                 when "upcoming" then "#{r[:days]} days to go (#{r[:weeks]} weeks #{r[:remainder_days]} days) until #{r[:event_date]}."
+                 else "#{r[:event_date]} was #{-r[:days]} days ago."
+                 end
+        when "timeline"
+          r = EventPlanner.timeline(need_date.call, today: o[:today])
+          text = r.map { |x| "#{x[:overdue] ? '!' : ' '} #{x[:due]}  #{x[:task]}#{x[:overdue] ? '  (overdue)' : ''}" }.join("\n")
+        when "giveaways"
+          raise ArgumentError, "giveaways needs --attendees N" unless o[:attendees]
+          r = EventPlanner.giveaway_quantity(attendees: o[:attendees], days: o[:days], uptake: o[:uptake],
+                                             per_person: o[:per_person], buffer: o[:buffer])
+          text = "Order #{r[:total]} items (#{r[:base]} expected + #{r[:buffer]} buffer)."
+        when "order-by"
+          r = EventPlanner.order_by_date(need_date.call, production_days: o[:production], delivery_days: o[:delivery],
+                                                         safety_days: o[:safety], today: o[:today])
+          text = "Order by #{r[:order_by]} (#{r[:working_days]} working days before the event)"
+          text += r[:late] ? " - that is #{-r[:days_from_today]} days ago, so ask about express production." : ", #{r[:days_from_today]} days from today."
+        when nil
+          out.puts USAGE
+          return 0
+        else
+          raise ArgumentError, %(Unknown command "#{cmd}". Run with --help.)
+        end
+        out.puts(o[:json] ? JSON.pretty_generate(r) : text)
+        0
+      rescue ArgumentError, OptionParser::ParseError => e
+        err.puts "Error: #{e.message}"
+        2
+      end
+    end
+  end
+end

data/lib/gopromotional/event_planner/version.rb

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

data/lib/gopromotional/event_planner.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "event_planner/version"
+
+module GoPromotional
+  # Event planning helpers: countdown, planning timeline, giveaway quantities and order-by dates.
+  module EventPlanner
+    TimelineItem = Struct.new(:offset_days, :category, :task, keyword_init: true)
+
+    TIMELINE_TEMPLATE = [
+      [56, "planning", "Confirm budget and attendee estimate"],
+      [49, "venue", "Book the venue"],
+      [42, "merchandise", "Order branded merchandise and giveaways"],
+      [35, "comms", "Send invitations or open registration"],
+      [28, "programme", "Confirm speakers and agenda"],
+      [21, "venue", "Arrange catering"],
+      [14, "merchandise", "Approve print proofs and signage"],
+      [7, "comms", "Send a reminder to attendees"],
+      [3, "logistics", "Confirm deliveries and the staffing rota"],
+      [1, "logistics", "Pack the event kit and giveaways"],
+      [0, "logistics", "Event day: set up the stand and registration"],
+      [-2, "comms", "Send thank-you and follow-up messages"]
+    ].map { |o, c, t| TimelineItem.new(offset_days: o, category: c, task: t).freeze }.freeze
+
+    module_function
+
+    # Accept a Date or an ISO YYYY-MM-DD string.
+    def to_date(value)
+      return value if value.is_a?(Date)
+      s = value.to_s.strip
+      raise ArgumentError, %(Invalid date "#{value}" (expected YYYY-MM-DD)) unless s.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+      begin
+        Date.iso8601(s)
+      rescue Date::Error
+        raise ArgumentError, %(Invalid calendar date "#{s}")
+      end
+    end
+
+    # Days until an event, split into weeks and days.
+    def countdown(event_date, today: Date.today)
+      ev = to_date(event_date)
+      now = to_date(today)
+      days = (ev - now).to_i
+      {
+        event_date: ev.iso8601, today: now.iso8601, days: days,
+        weeks: days.abs / 7, remainder_days: days.abs % 7,
+        status: days.positive? ? "upcoming" : (days.zero? ? "today" : "past")
+      }
+    end
+
+    # Planning tasks with due dates, sorted by date. With today: each row gets :days_left and :overdue.
+    def timeline(event_date, today: nil, template: TIMELINE_TEMPLATE)
+      ev = to_date(event_date)
+      now = today && to_date(today)
+      template.map do |item|
+        due = ev - item.offset_days
+        row = { task: item.task, category: item.category, offset_days: item.offset_days, due: due.iso8601 }
+        if now
+          row[:days_left] = (due - now).to_i
+          row[:overdue] = due < now
+        end
+        row
+      end.sort_by { |r| r[:due] }
+    end
+
+    def ceil_clean(x)
+      ((x * 1e6).round / 1e6).ceil
+    end
+
+    # Giveaway items: attendees x days x uptake x per_person, plus a buffer (both rounded up).
+    def giveaway_quantity(attendees:, days: 1, uptake: 0.6, per_person: 1, buffer: 0.1)
+      { attendees: attendees, days: days, uptake: uptake, per_person: per_person, buffer: buffer }.each do |name, v|
+        unless v.is_a?(Numeric) && v.finite? && v >= 0
+          raise ArgumentError, "#{name} must be a non-negative number"
+        end
+      end
+      raise ArgumentError, "uptake must be between 0 and 1" if uptake > 1
+      base = ceil_clean(attendees * days * uptake * per_person)
+      extra = ceil_clean(base * buffer)
+      { base: base, buffer: extra, total: base + extra }
+    end
+
+    # Step back n working days (Monday to Friday).
+    def subtract_working_days(day, n)
+      d = to_date(day)
+      left = n
+      while left.positive?
+        d -= 1
+        left -= 1 if d.cwday <= 5
+      end
+      d
+    end
+
+    # Latest order date for printed merchandise: production + delivery + safety, in working days.
+    def order_by_date(event_date, production_days: 10, delivery_days: 3, safety_days: 2, today: nil)
+      { production_days: production_days, delivery_days: delivery_days, safety_days: safety_days }.each do |name, v|
+        raise ArgumentError, "#{name} must be a non-negative integer" unless v.is_a?(Integer) && v >= 0
+      end
+      working = production_days + delivery_days + safety_days
+      by = subtract_working_days(event_date, working)
+      out = { order_by: by.iso8601, working_days: working }
+      if today
+        out[:days_from_today] = (by - to_date(today)).to_i
+        out[:late] = out[:days_from_today].negative?
+      end
+      out
+    end
+  end
+end

data/lib/gopromotional-event-planner.rb

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

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: gopromotional-event-planner
+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: 'Plan an event or trade show from the command line or your code: a countdown,
+  a 12-step planning timeline with due dates, an estimate of how many giveaway items
+  to order, and the latest order date for printed merchandise in working days.'
+executables:
+- gopromotional-event-planner
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/gopromotional-event-planner
+- lib/gopromotional-event-planner.rb
+- lib/gopromotional/event_planner.rb
+- lib/gopromotional/event_planner/cli.rb
+- lib/gopromotional/event_planner/version.rb
+homepage: https://www.gopromotional.co.uk/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.gopromotional.co.uk/
+  source_code_uri: https://github.com/nbkdevs/GoPromotional/tree/main/packages/homepage/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: Event countdown, planning timeline, giveaway quantities and print order-by
+  dates.
+test_files: []