wiq-cli 0.1.0

data/lib/wiq/introspection.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Wiq
+  # Walks Thor's command registry and produces a stable JSON shape for agents
+  # to introspect the CLI surface in one call.
+  #
+  # Schema (nested):
+  #   {
+  #     "name": "wiq",
+  #     "version": "0.1.0",
+  #     "global_options": [ ... ],
+  #     "top_level_commands": [ ... ],
+  #     "groups": [ { "name": "...", "description": "...", "commands": [ ... ] } ]
+  #   }
+  module Introspection
+    # Thor auto-generates these on every Thor::Group subclass; they're not
+    # useful for agents and would just bloat the dump.
+    INTERNAL_COMMANDS = %w[help tree].freeze
+
+    module_function
+
+    def dump_tree(root: Wiq::CLI)
+      {
+        "name" => "wiq",
+        "version" => Wiq::VERSION,
+        "global_options" => dump_options(Wiq::Commands::Base.class_options),
+        "top_level_commands" => dump_commands(root.commands, klass: root),
+        "groups" => root.subcommand_classes.sort.map do |name, klass|
+          dump_group(name, klass, root)
+        end
+      }
+    end
+
+    def dump_group(name, klass, root)
+      {
+        "name" => name,
+        "description" => root.commands[name]&.description,
+        "commands" => dump_commands(klass.commands, klass: klass)
+      }
+    end
+
+    def dump_commands(commands, klass:)
+      aliases = method_to_alias(klass)
+      commands
+        .reject { |k, _| INTERNAL_COMMANDS.include?(k) || subcommand_name?(klass, k) }
+        .map { |k, cmd| dump_command(cmd, display_name: aliases[k] || k) }
+        .sort_by { |row| row["name"] }
+    end
+
+    def dump_command(cmd, display_name:)
+      {
+        "name" => display_name,
+        "description" => cmd.description,
+        "long_description" => cmd.long_description,
+        "usage" => cmd.usage,
+        "options" => dump_options(cmd.options)
+      }
+    end
+
+    # Thor's `map` declares user-facing command aliases. `map "run" => :run_report`
+    # means when a user types `wiq reports run`, Thor dispatches to method
+    # :run_report. Internally Thor stores the command under "run_report" — the
+    # method name — but agents need to see "run" (the name they type).
+    # Build a reverse map: method_name (String) => alias_name (String).
+    #
+    # Flag-style aliases (--version, -v) are also registered via `map` for
+    # convenience but they're not command names — skip them.
+    def method_to_alias(klass)
+      return {} unless klass.respond_to?(:map)
+
+      klass.map.each_with_object({}) do |(alias_name, method_name), h|
+        alias_str = alias_name.to_s
+        next if alias_str.start_with?("-")
+
+        h[method_name.to_s] = alias_str
+      end
+    end
+
+    def dump_options(options)
+      options.sort.map do |name, opt|
+        row = {
+          "name" => name.to_s,
+          "type" => opt.type.to_s,
+          "required" => opt.required?,
+          "description" => opt.description
+        }
+        row["default"] = opt.default unless opt.default.nil?
+        row["enum"] = opt.enum if opt.enum
+        row
+      end
+    end
+
+    # When a class registers a `subcommand "foo", FooClass`, Thor also adds
+    # a placeholder command named "foo" to the parent's commands hash. Skip
+    # those when listing the parent's own commands — they're rendered as
+    # groups, not commands.
+    def subcommand_name?(klass, command_name)
+      return false unless klass.respond_to?(:subcommand_classes)
+
+      klass.subcommand_classes.key?(command_name)
+    end
+  end
+end

data/lib/wiq/output.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Wiq
+  # Three output modes:
+  #   --json   full envelope (ok/data/summary/meta) for agents that want structure
+  #   --agent  bare JSON of `data` for headless scripts
+  #   default  pretty JSON to a TTY, or --agent equivalent when piped
+  module Output
+    module_function
+
+    def render(data, summary: nil, breadcrumbs: [], meta: {}, options: {})
+      mode = pick_mode(options)
+      case mode
+      when :json
+        puts JSON.pretty_generate(envelope(data, summary: summary, breadcrumbs: breadcrumbs, meta: meta))
+      when :agent
+        puts JSON.generate(data)
+      when :pretty
+        puts JSON.pretty_generate(data)
+        puts "" unless data.nil? || (data.respond_to?(:empty?) && data.empty?)
+        puts "→ #{summary}" if summary
+        if meta && !meta.empty?
+          meta_line = meta.map { |k, v| "#{k}=#{v}" }.join("  ")
+          puts "  #{meta_line}"
+        end
+      end
+    end
+
+    def render_error(err, options: {})
+      mode = pick_mode(options)
+      payload = {
+        "ok" => false,
+        "error" => err.message,
+        "code" => err.respond_to?(:code) ? err.code : "error",
+        "hint" => (err.respond_to?(:hint) ? err.hint : nil),
+        "details" => (err.respond_to?(:details) ? err.details : nil)
+      }.compact
+
+      case mode
+      when :json, :agent
+        warn JSON.generate(payload)
+      else
+        warn "✖ #{payload["error"]} [#{payload["code"]}]"
+        warn "  hint: #{payload["hint"]}" if payload["hint"]
+      end
+    end
+
+    def pick_mode(options)
+      options ||= {}
+      return :agent if options[:agent] || options["agent"]
+      return :json  if options[:json]  || options["json"]
+      $stdout.tty? ? :pretty : :agent
+    end
+
+    def envelope(data, summary:, breadcrumbs:, meta:)
+      {
+        "ok" => true,
+        "data" => data,
+        "summary" => summary,
+        "breadcrumbs" => breadcrumbs,
+        "meta" => meta
+      }.compact
+    end
+  end
+end

data/lib/wiq/pagination.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Wiq
+  # Parses the WIQ pagination headers:
+  #   Link: <https://host/api/v1/foo?page=2>; rel="next", <...>; rel="last"
+  #   TotalCount: 123
+  module Pagination
+    module_function
+
+    # Returns { "next" => "...url...", "prev" => "...", "first" => "...", "last" => "..." }.
+    def parse_link(header)
+      return {} if header.nil? || header.empty?
+
+      header.split(",").each_with_object({}) do |part, acc|
+        url_part, *params = part.split(";").map(&:strip)
+        next unless url_part&.start_with?("<") && url_part.end_with?(">")
+
+        url = url_part[1..-2]
+        rel = params.find { |p| p.start_with?("rel=") }
+        next unless rel
+
+        rel_value = rel.sub(/\Arel="?/, "").sub(/"?\z/, "")
+        acc[rel_value] = url
+      end
+    end
+
+    def next_url(link_header)
+      parse_link(link_header)["next"]
+    end
+
+    def total_count(headers)
+      # Header is literally `TotalCount` (case-insensitive via Faraday).
+      v = headers["TotalCount"] || headers["totalcount"] || headers["Totalcount"]
+      v && Integer(v)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/wiq/season_resolver.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Wiq
+  # Translates `--season <year>` into a set of PaidSession ids. No first-class
+  # Season exists in WIQ; we approximate by finding paid sessions whose
+  # [start_at, end_at] window overlaps the calendar year.
+  class SeasonResolver
+    def initialize(client)
+      @client = client
+    end
+
+    # Returns the array of paid_session hashes that overlap `year`.
+    def paid_sessions_for(year)
+      year = Integer(year)
+      start_of_year = "#{year}-01-01"
+      end_of_year = "#{year}-12-31"
+
+      sessions, = @client.collect_all(
+        "/api/v1/paid_sessions",
+        {
+          "q[start_at_lteq]" => end_of_year,
+          "q[end_at_gteq]" => start_of_year,
+          "per_page" => 100
+        },
+        key: "paid_sessions"
+      )
+      sessions
+    end
+
+    def paid_session_ids_for(year)
+      paid_sessions_for(year).map { |ps| ps["id"] }
+    end
+
+    # Filter an array of rosters (as returned by /api/v1/rosters) to those
+    # whose roster_syncers point at any paid session id in `ids`.
+    def filter_rosters_by_ids(rosters, ids)
+      id_set = ids.to_set
+      rosters.select do |roster|
+        syncers = roster["roster_syncers"] || []
+        syncers.any? { |rs| id_set.include?(rs["paid_session_id"]) }
+      end
+    end
+  end
+end
+
+require "set"

data/lib/wiq/version.rb

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

data/lib/wiq/workflows.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+module Wiq
+  # Named multi-step recipes mapping a human question to a CLI command
+  # sequence. Discovery via `wiq workflows list` / `wiq workflows show NAME`.
+  #
+  # Per-entry schema:
+  #   name         kebab-case slug (the lookup key — also keys the hash)
+  #   category     one of CATEGORIES (used to group `list` output)
+  #   question     natural-language framing — what an agent matches against
+  #   parameters   structured list of placeholders:
+  #                  [{ name:, type:, required:, default?:, enum?:, description?: }]
+  #                type is one of "date", "integer", "string"
+  #   recipe       ordered list of command strings using two substitution
+  #                conventions:
+  #                  <name>          → required substitution (must match a
+  #                                    declared required parameter)
+  #                  [--flag <name>] → optional bracket; drop the whole
+  #                                    expression if the parameter is unset
+  #   admin_only   true when the workflow depends on at least one admin-only
+  #                report or admin-only metric (non-admin coach PATs 403)
+  #   notes        agent-facing guidance (when relevant)
+  module Workflows
+    CATEGORIES = %w[attendance leads roster finance memberships fundraising store].freeze
+
+    ALL = {
+      # ── Attendance / check-ins ──────────────────────────────────
+      "attendance-last-month" => {
+        name: "attendance-last-month",
+        category: "attendance",
+        question: "How many practices did each wrestler attend last month?",
+        parameters: [
+          { name: "start_date", type: "date", required: true },
+          { name: "end_date", type: "date", required: true },
+          { name: "roster_id", type: "integer", required: false, default: 0,
+            description: "0 = all rosters" }
+        ],
+        recipe: [
+          "wiq reports run CheckInSummaryReport --start <start_date> --end <end_date> [--roster <roster_id>]"
+        ],
+        notes: "Useful to build a leaderboard of check-ins at your wrestling club."
+      },
+
+      "who-came-today" => {
+        name: "who-came-today",
+        category: "attendance",
+        question: "Who showed up at the club today?",
+        parameters: [
+          { name: "today_date", type: "date", required: true,
+            description: "Today's date in the team's timezone (YYYY-MM-DD)" }
+        ],
+        recipe: [
+          "wiq reports run CheckInFeedReport --start <today_date> --end <today_date>"
+        ],
+        notes: "The feed includes registration type per check-in, so the agent " \
+               "can filter the result client-side to answer follow-ups like " \
+               "'who used a trial pass today' or 'who came without an active " \
+               "subscription'."
+      },
+
+      "churn-risk" => {
+        name: "churn-risk",
+        category: "attendance",
+        question: "Which subscribers are at risk of canceling because they haven't checked in lately?",
+        parameters: [
+          { name: "days_threshold", type: "integer", required: true,
+            enum: [7, 14, 30, 60, 90],
+            description: "Window of inactivity, in days. Any value outside the enum falls back to 30." }
+        ],
+        recipe: [
+          "wiq reports run ChurnRiskReport --roster 0 --days-threshold <days_threshold>"
+        ]
+      },
+
+      # ── Leads pipeline (Prospect is the internal name) ──────────
+      "overdue-followups" => {
+        name: "overdue-followups",
+        category: "leads",
+        question: "Which lead families have a stale follow-up?",
+        parameters: [],
+        recipe: [
+          "wiq prospect_families list --attention needs_attention --sort oldest_followup"
+        ],
+        notes: "WIQ calls these 'prospects' internally but 'leads' in the UI — " \
+               "both terms refer to the same thing."
+      },
+
+      # ── Roster ops ──────────────────────────────────────────────
+      "growth-across-seasons" => {
+        name: "growth-across-seasons",
+        category: "roster",
+        question: "How has roster size changed across seasons?",
+        parameters: [
+          { name: "year_a", type: "integer", required: true,
+            description: "Earlier season year (e.g. 2025)" },
+          { name: "year_b", type: "integer", required: true,
+            description: "Later season year (e.g. 2026)" }
+        ],
+        recipe: [
+          "wiq paid_sessions list --season <year_a>",
+          "wiq rosters list --season <year_a>",
+          "wiq paid_sessions list --season <year_b>",
+          "wiq rosters list --season <year_b>"
+        ],
+        notes: "Client-side compare — no first-class growth report exists. " \
+               "Clubs are typically seasonal, so the natural comparison is " \
+               "season-vs-season (e.g. 2025 season vs 2026 season). Before " \
+               "running, clarify whether the user wants a full calendar-year " \
+               "diff or a specific roster/registration vs another."
+      },
+
+      "roster-by-zip" => {
+        name: "roster-by-zip",
+        category: "roster",
+        question: "What zip codes does our roster cover?",
+        parameters: [
+          { name: "address_question_id", type: "integer", required: true,
+            description: "RegAddressQuestion id, discoverable via " \
+                         "`wiq registrations questions --visibility public`" },
+          { name: "roster_id", type: "integer", required: false, default: 0,
+            description: "0 = all rosters; pass a specific id to scope" }
+        ],
+        recipe: [
+          "wiq registrations questions --visibility public",
+          "wiq reports run RosterReport --roster <roster_id> --append-properties <address_question_id>"
+        ],
+        notes: "Address (with zip) is captured via a registration question, " \
+               "not stored on the wrestler directly. RosterReport with " \
+               "--append-properties surfaces it as a column. Step 1 of the " \
+               "recipe discovers the question id if the agent doesn't know it."
+      },
+
+      # ── Finance (admin-only) ────────────────────────────────────
+      "revenue-snapshot" => {
+        name: "revenue-snapshot",
+        category: "finance",
+        question: "How are we doing financially over the last quarter?",
+        parameters: [],
+        recipe: [
+          "wiq metrics show net_volume --range 3m",
+          "wiq metrics show mrr --range 3m",
+          "wiq metrics show active_subscribers --range 3m"
+        ],
+        admin_only: true,
+        notes: "Three calls because we deliberately didn't ship a `metrics " \
+               "dashboard` convenience command — the agent fans out and " \
+               "composes the answer. net_volume and mrr return integer cents."
+      },
+
+      "revenue-by-category" => {
+        name: "revenue-by-category",
+        category: "finance",
+        question: "How is revenue broken down across categories (e.g. Level 1 vs Level 2 subscriptions)?",
+        parameters: [
+          { name: "range", type: "string", required: false, default: "3m",
+            enum: ["today", "7d", "4w", "3m", "12m", "year to date", "custom"],
+            description: "Time window for the breakdown." }
+        ],
+        recipe: [
+          "wiq metrics show category_breakdown_net --range <range>"
+        ],
+        admin_only: true,
+        notes: "Returns revenue grouped by category → subcategory → " \
+               "detail_category. Common asks: comparing subscription tiers " \
+               "(Level 1 vs Level 2), comparing registration revenue vs " \
+               "donation revenue, or seeing which revenue source is growing. " \
+               "Values are integer cents."
+      },
+
+      "paid-session-accounting" => {
+        name: "paid-session-accounting",
+        category: "finance",
+        question: "Give me a line-item breakdown for this registration session.",
+        parameters: [
+          { name: "paid_session_id", type: "integer", required: true,
+            description: "Discoverable via `wiq paid_sessions list`" }
+        ],
+        recipe: [
+          "wiq reports run PaidSessionAccountingReport --paid-session <paid_session_id>"
+        ],
+        admin_only: true
+      },
+
+      "failed-payments-recent" => {
+        name: "failed-payments-recent",
+        category: "finance",
+        question: "Which families have outstanding failed payments (after filtering out failures that were later retried successfully)?",
+        parameters: [
+          { name: "since_date", type: "date", required: true,
+            description: "Earliest created_at to scan from (YYYY-MM-DD)" }
+        ],
+        recipe: [
+          "wiq charges list --status failed --since <since_date> --all"
+        ],
+        admin_only: true,
+        notes: "CRITICAL: a failed charge alone is NOT actionable. " \
+               "Stripe/Justifi retry subscriptions automatically and " \
+               "customers retry registrations after card declines, so most " \
+               "failures resolve themselves. The cross-check is mandatory:\n\n" \
+               "After the step-1 list returns, for EACH failed charge:\n" \
+               "  1. Note its billing_profile_id, chargeable_id, " \
+               "chargeable_type, and created_at.\n" \
+               "  2. Run `wiq charges list --billing-profile <id> " \
+               "--status successful --since <failure_created_at> --all`.\n" \
+               "  3. Drop the failed charge if any returned successful " \
+               "charge has matching chargeable_id AND chargeable_type.\n\n" \
+               "What remains is the actionable set: failures with no later " \
+               "successful retry on the same item. Surface those to the " \
+               "user with family name + amount + chargeable description."
+      },
+
+      "family-payment-history" => {
+        name: "family-payment-history",
+        category: "finance",
+        question: "What has this family paid (or tried to pay) recently?",
+        parameters: [
+          { name: "billing_profile_id", type: "integer", required: true,
+            description: "Discover via `wiq billing_profiles show <profile_id> --profile-type ParentProfile`" },
+          { name: "since_date", type: "date", required: false, default: "90 days ago",
+            description: "Earliest created_at; default is roughly 90 days back when omitted client-side" }
+        ],
+        recipe: [
+          "wiq charges list --billing-profile <billing_profile_id> [--since <since_date>] --all"
+        ],
+        admin_only: true,
+        notes: "Returns the family's charge history — both successful and " \
+               "failed attempts, with the chargeable description (what was " \
+               "paid for) on each row. To go from a wrestler name to a " \
+               "billing_profile_id: `wiq wrestlers list --query \"Name\"`, " \
+               "then `wiq wrestlers show <id>` to find the parent profile " \
+               "id, then `wiq billing_profiles show <parent_id> " \
+               "--profile-type ParentProfile`."
+      },
+
+      "scholarship-audit" => {
+        name: "scholarship-audit",
+        category: "finance",
+        question: "Where is scholarship money going?",
+        parameters: [
+          { name: "start_date", type: "date", required: true },
+          { name: "end_date", type: "date", required: true }
+        ],
+        recipe: [
+          "wiq reports run ScholarshipAuditReport --start <start_date> --end <end_date>"
+        ],
+        admin_only: true,
+        notes: "Also requires team.payments_enabled — the UI hides the tab " \
+               "otherwise, but the API just returns empty data."
+      },
+
+      # ── Memberships (USAW / AAU) ────────────────────────────────
+      "usaw-renewal-batch" => {
+        name: "usaw-renewal-batch",
+        category: "memberships",
+        question: "Which wrestlers need their USAW renewed before our next event?",
+        parameters: [
+          { name: "roster_id", type: "integer", required: false, default: 0,
+            description: "0 = all rosters" }
+        ],
+        recipe: [
+          "wiq reports run UsawExpiredReport [--roster <roster_id>]"
+        ],
+        notes: "Output is a bulk-purchase upload format usable directly in " \
+               "USAW's system."
+      },
+
+      "aau-renewal-batch" => {
+        name: "aau-renewal-batch",
+        category: "memberships",
+        question: "Which wrestlers need their AAU memberships renewed?",
+        parameters: [
+          { name: "roster_id", type: "integer", required: false, default: 0,
+            description: "0 = all rosters" }
+        ],
+        recipe: [
+          "wiq reports run AauExpiredReport [--roster <roster_id>]"
+        ],
+        notes: "Output is a bulk-purchase upload format usable directly in " \
+               "AAU's system."
+      },
+
+      # ── Fundraising ─────────────────────────────────────────────
+      "fundraiser-status" => {
+        name: "fundraiser-status",
+        category: "fundraising",
+        question: "How is our active fundraiser doing?",
+        parameters: [
+          { name: "fundraiser_id", type: "integer", required: true,
+            description: "Discoverable via `wiq fundraisers list` (not yet on the CLI surface — " \
+                         "open the WIQ web UI for now)" }
+        ],
+        recipe: [
+          "wiq reports run FundraiserSummaryReport --fundraiser <fundraiser_id>"
+        ],
+        admin_only: true
+      },
+
+      # ── Online store ────────────────────────────────────────────
+      "store-orders" => {
+        name: "store-orders",
+        category: "store",
+        question: "What's been sold in our online store?",
+        parameters: [
+          { name: "online_store_id", type: "integer", required: true,
+            description: "Discoverable via the WIQ web UI (not yet on the CLI surface)" }
+        ],
+        recipe: [
+          "wiq reports run OnlineStoreSummaryReport --online-store <online_store_id>"
+        ],
+        admin_only: true
+      }
+    }.freeze
+  end
+end

data/lib/wiq.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "wiq/version"
+require "wiq/errors"
+require "wiq/credentials"
+require "wiq/config"
+require "wiq/output"
+require "wiq/pagination"
+require "wiq/client"
+require "wiq/season_resolver"
+require "wiq/introspection"
+require "wiq/workflows"
+require "wiq/commands/base"
+require "wiq/commands/auth"
+require "wiq/commands/doctor"
+require "wiq/commands/check_ins"
+require "wiq/commands/reports"
+require "wiq/commands/paid_sessions"
+require "wiq/commands/registrations"
+require "wiq/commands/metrics"
+require "wiq/commands/events"
+require "wiq/commands/rosters"
+require "wiq/commands/prospects"
+require "wiq/commands/prospect_families"
+require "wiq/commands/workflows"
+require "wiq/commands/setup"
+require "wiq/commands/wrestlers"
+require "wiq/commands/charges"
+require "wiq/commands/billing_profiles"
+require "wiq/cli"