wiq-cli 0.1.0

data/lib/wiq/commands/charges.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class Charges < Base
+      # Match Charge.statuses in app/models/charge.rb. Values are
+      # integer-backed via Rails enum (`enum status: { successful: 0, failed: 1 }`).
+      # Ransack 4.x does NOT auto-translate enum strings on integer columns,
+      # so the CLI translates here before sending q[status_eq]. Without this
+      # translation Ransack silently drops the predicate and returns every
+      # row — the kind of failure that's worse than a 422.
+      STATUS_TO_INT = { "successful" => 0, "failed" => 1 }.freeze
+      STATUSES = STATUS_TO_INT.keys.freeze
+      DEFAULT_PER_PAGE = 50
+
+      desc "list", "List charges (finance: admin coach only)"
+      long_desc <<~DESC
+        Returns charges (payment attempts) across the team. Useful for
+        answering "did this family pay X?" or "what's been failing
+        lately?"
+
+        Auth: admin-only (Pundit scope filters non-admin coach PATs to
+        empty results, parent/wrestler PATs return 403).
+
+        Filters translate to Ransack server-side:
+          --status                 successful | failed (enum is two-valued)
+          --billing-profile <id>   q[billing_profile_id_eq] — the
+                                   parent/family who paid. Discover via
+                                   `wiq billing_profiles show <profile_id>
+                                   --profile-type ParentProfile`.
+          --chargeable-type <str>  q[chargeable_type_eq] — the kind of
+                                   thing paid for. Common values:
+                                   BillingSubscriptionInvoice, Registration,
+                                   Donation, FundraiserContribution,
+                                   OnlineStoreOrder. (Verify against the
+                                   actual data — these are model class
+                                   names, not strings the API documents.)
+          --since <YYYY-MM-DD>     q[created_at_gteq]
+          --until <YYYY-MM-DD>     q[created_at_lteq]
+
+        Each row is rich — billing_profile.billable (the person paying),
+        chargeable (what they paid for), wrestlers[] (the kids the charge
+        is associated with), refunds, payout, coupon, category. Default
+        page size is 50 since charges accumulate fast; use --all for
+        exhaustive scans (paired with --since to bound the window).
+
+        **Critical caveat for failed-payment analysis.** A `failed` charge
+        is NOT actionable on its own — Stripe/Justifi retry subscriptions
+        automatically, and customers retry registrations after card
+        declines. Always cross-check that no `successful` charge exists
+        for the same (billing_profile_id, chargeable_id, chargeable_type)
+        tuple AFTER the failure timestamp. See `wiq workflows show
+        failed-payments-recent` for the canonical pattern.
+      DESC
+      method_option :status, type: :string, enum: STATUSES,
+                             desc: "Filter to successful or failed charges"
+      method_option :billing_profile, type: :numeric,
+                                      desc: "Restrict to one billing_profile id"
+      method_option :chargeable_type, type: :string,
+                                      desc: "Filter by chargeable model name (e.g. BillingSubscriptionInvoice)"
+      method_option :since, type: :string, desc: "Earliest created_at (YYYY-MM-DD)"
+      method_option :until, type: :string, desc: "Latest created_at (YYYY-MM-DD)"
+      method_option :per_page, type: :numeric, default: DEFAULT_PER_PAGE,
+                               desc: "Page size (default 50)"
+      method_option :all, type: :boolean, default: false,
+                          desc: "Follow pagination until exhausted"
+      def list
+        params = build_list_params
+        records, total = fetch_index("/api/v1/charges", params, key: "charges")
+        render_index(
+          records, total: total,
+          summary: "Listed #{records.size} charges#{summary_filters_suffix}.",
+          breadcrumbs: [
+            { "cmd" => "wiq billing_profiles show <id> --profile-type ParentProfile",
+              "description" => "Look up the family behind a billing_profile_id" },
+            { "cmd" => "wiq workflows show failed-payments-recent",
+              "description" => "Canonical failed-payment cross-check workflow" }
+          ]
+        )
+      end
+
+      no_commands do
+        def build_list_params
+          params = { "per_page" => options[:per_page] || DEFAULT_PER_PAGE }
+          params["q[status_eq]"] = STATUS_TO_INT.fetch(options[:status]) if options[:status]
+          params["q[billing_profile_id_eq]"] = options[:billing_profile] if options[:billing_profile]
+          params["q[chargeable_type_eq]"] = options[:chargeable_type] if options[:chargeable_type]
+          params["q[created_at_gteq]"] = options[:since] if options[:since]
+          params["q[created_at_lteq]"] = options[:until] if options[:until]
+          params
+        end
+
+        def summary_filters_suffix
+          bits = []
+          bits << "status=#{options[:status]}" if options[:status]
+          bits << "billing_profile=#{options[:billing_profile]}" if options[:billing_profile]
+          bits << "since=#{options[:since]}" if options[:since]
+          bits << "until=#{options[:until]}" if options[:until]
+          bits.empty? ? "" : " (#{bits.join(", ")})"
+        end
+      end
+    end
+  end
+end

data/lib/wiq/commands/check_ins.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class CheckIns < Base
+      # Match CheckIn.statuses in app/models/check_in.rb (integer-backed
+      # Rails enum). Ransack 4.x does not translate enum strings on integer
+      # columns, so the CLI translates here. Without this, q[status_eq]
+      # silently drops and returns all check-ins regardless of status.
+      STATUS_TO_INT = {
+        "unknown" => 0,
+        "present" => 1,
+        "absent" => 2,
+        "excused" => 3,
+        "unexcused" => 4,
+        "late" => 5,
+        "injured" => 6,
+        "other" => 7
+      }.freeze
+      STATUSES = STATUS_TO_INT.keys.freeze
+
+      desc "event EVENT_ID", "List check-ins for an event"
+      long_desc <<~DESC
+        Every check-in row for a single event. Each row carries the
+        wrestler profile, the event reference, the status (Rails enum:
+        unknown, present, absent, excused, unexcused, late, injured, other),
+        and the registration_answers captured at check-in time.
+
+        Discover event ids via `wiq events list --start ... --end ...`.
+      DESC
+      method_option :status, type: :string, enum: STATUSES,
+                             desc: "Filter by check-in status"
+      method_option :all, type: :boolean, default: false, desc: "Follow pagination until exhausted"
+      def event(event_id)
+        params = { "per_page" => 50 }
+        params["q[status_eq]"] = STATUS_TO_INT.fetch(options[:status]) if options[:status]
+        records, total = fetch_index("/api/v1/events/#{event_id}/check_ins", params, key: "check_ins")
+        render_index(
+          records, total: total,
+          summary: "Listed #{records.size} check-ins for event #{event_id}.",
+          breadcrumbs: [
+            { "cmd" => "wiq events show #{event_id}", "description" => "See the event itself" }
+          ]
+        )
+      end
+
+      desc "wrestler WRESTLER_ID", "List a wrestler's check-ins"
+      long_desc <<~DESC
+        Cross-event view: every check-in this wrestler has ever had,
+        sorted newest-first. Use --since YYYY-MM-DD to scope.
+
+        For roster-wide attendance use `wiq check_ins summary` or
+        `wiq reports run LastPracticeAttendedReport --roster <id>`.
+      DESC
+      method_option :since, type: :string, desc: "Earliest created_at date (YYYY-MM-DD)"
+      method_option :all, type: :boolean, default: false
+      def wrestler(wrestler_id)
+        params = { "per_page" => 50 }
+        params["q[created_at_gteq]"] = options[:since] if options[:since]
+        records, total = fetch_index("/api/v1/wrestlers/#{wrestler_id}/check_ins", params, key: "check_ins")
+        render_index(
+          records, total: total,
+          summary: "Listed #{records.size} check-ins for wrestler #{wrestler_id}.",
+          breadcrumbs: [
+            { "cmd" => "wiq wrestlers show #{wrestler_id}",
+              "description" => "See the wrestler's profile" },
+            { "cmd" => "wiq reports run LastPracticeAttendedReport --roster <id>",
+              "description" => "Find ghost wrestlers across a roster" }
+          ]
+        )
+      end
+
+      desc "summary", "Run a CheckInSummaryReport (default) or CheckInFeedReport for a date range"
+      long_desc <<~DESC
+        Convenience wrapper around `wiq reports run`. Default report type
+        is CheckInSummaryReport — one row per wrestler with totals.
+        Pass --feed to switch to CheckInFeedReport (one row per check-in,
+        useful for "who came today" or capturing arrival times).
+
+        The CLI submits the report, then polls until status=ready (unless
+        --no-wait). Both reports are non-finance, so any CoachProfile PAT
+        on the team can run them.
+
+        For Q&A capture at check-in time, use
+        `wiq reports run CheckInReport` (the "with questions" variant).
+      DESC
+      method_option :start, type: :string, required: true, desc: "YYYY-MM-DD"
+      method_option :end, type: :string, required: true, desc: "YYYY-MM-DD"
+      method_option :roster, type: :numeric, desc: "Restrict to a single roster"
+      method_option :feed, type: :boolean, default: false,
+                           desc: "Use CheckInFeedReport (raw rows) instead of the summary aggregate"
+      method_option :wait, type: :boolean, default: true
+      method_option :timeout, type: :numeric, default: 300, desc: "Max seconds to wait"
+      def summary
+        report_type = options[:feed] ? "CheckInFeedReport" : "CheckInSummaryReport"
+        args = {}
+        args["roster_id"] = options[:roster] if options[:roster]
+
+        body = {
+          report: {
+            type: report_type,
+            version: "v1",
+            name: "CLI #{report_type} #{options[:start]}..#{options[:end]}",
+            start_at: options[:start],
+            end_at: options[:end],
+            args: args
+          }
+        }
+
+        report = client.post("/api/v1/reports", body)
+        if options[:wait]
+          report = Reports.poll(client, report["id"], timeout: options[:timeout])
+        end
+
+        render(report,
+               summary: "#{report_type} ##{report["id"]} status=#{report["status"]}.",
+               breadcrumbs: [
+                 { "cmd" => "wiq reports show #{report["id"]}", "description" => "Refetch later" },
+                 { "cmd" => "wiq reports types", "description" => "See other recommended report types" }
+               ])
+      end
+    end
+  end
+end

data/lib/wiq/commands/doctor.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class Doctor < Base
+      desc "check", "Diagnose env, network, token, and config sources"
+      long_desc <<~DESC
+        Runs a sequence of diagnostic checks:
+
+          1. Ruby version (>= 3.1 required)
+          2. Credentials path (~/.config/wiq/credentials.json)
+          3. Resolved host + source (--host > env > config > store > prod)
+          4. Resolved alias + source
+          5. Token presence + source
+          6. Live reachability + auth probe via
+             `GET /api/v1/personal_access_tokens`
+          7. Bound profile (display_name, type, team) for the calling token
+
+        Exits non-zero if any check fails. Agents should run this first
+        when handed an unfamiliar shell to confirm they can actually call
+        the API.
+      DESC
+      def check_all
+        checks = []
+
+        checks << check("Ruby version", RUBY_VERSION,
+                        ok: Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.1.0"),
+                        hint: "wiq-cli requires Ruby >= 3.1")
+
+        cfg = Wiq::Config.load(symbolized_options)
+        trace = cfg.trace
+        checks << check("Credentials path", Wiq::Credentials.path, ok: true)
+
+        checks << check("Host", trace[:host] || "(unset)",
+                        ok: !trace[:host].nil?,
+                        hint: trace[:host_source] || "Run `wiq auth login` to configure.")
+
+        checks << check("Alias", trace[:alias] || "(unresolved)",
+                        ok: !trace[:alias].nil?,
+                        hint: trace[:alias_source])
+
+        checks << check("Token", trace[:token_present] ? "present" : "missing",
+                        ok: trace[:token_present],
+                        hint: trace[:token_source])
+
+        if trace[:host] && trace[:token_present]
+          begin
+            client = Wiq::Client.new(cfg)
+            rows, = client.collect_all(
+              "/api/v1/personal_access_tokens",
+              { "per_page" => 100 },
+              key: "personal_access_tokens"
+            )
+            prefix = cfg.token[0, 12]
+            match = rows.find { |r| r["token_prefix"] == prefix }
+            if match
+              profile = match["profile"] || {}
+              checks << check("Reachability + auth", "200 OK", ok: true)
+              checks << check("Bound profile",
+                              "#{profile["display_name"]} (#{profile["type"]}) @ #{profile["team_name"]}",
+                              ok: !profile["display_name"].nil?)
+            else
+              checks << check("Reachability + auth", "200 OK", ok: true)
+              checks << check("Bound profile", "(token not in own user's PAT list?)",
+                              ok: false,
+                              hint: "Unexpected — the calling PAT should always appear in this list.")
+            end
+          rescue Wiq::APIError => e
+            checks << check("Reachability + auth", "#{e.status} #{e.code}", ok: false, hint: e.hint)
+          rescue Faraday::Error => e
+            checks << check("Reachability + auth", e.message, ok: false,
+                            hint: "Check the host URL and your network.")
+          end
+        else
+          checks << check("Reachability + auth", "skipped", ok: false, hint: "Host or token missing.")
+        end
+
+        all_ok = checks.all? { |c| c["ok"] }
+        render(checks, summary: all_ok ? "All checks passed." : "Some checks failed.")
+        exit(1) unless all_ok
+      end
+
+      map "check" => :check_all
+      default_task :check_all
+
+      no_commands do
+        def check(name, value, ok:, hint: nil)
+          { "name" => name, "value" => value, "ok" => ok, "hint" => hint }.compact
+        end
+      end
+    end
+  end
+end

data/lib/wiq/commands/events.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class Events < Base
+      # Canonical event_type strings from app/models/event.rb. Surfaced via
+      # `wiq events types` so agents don't have to guess.
+      TYPES = {
+        "practice" => "Practice events. The default for most clubs.",
+        "dual_meet" => "Dual meet — match-style competition against one opposing team.",
+        "tournament" => "Tournament — bracket-style competition with many opponents.",
+        "scramble" => "Scramble — open mat / informal competition.",
+        "private_lesson" => "Private lesson — one-on-one or small-group paid session. " \
+                            "Filtered out of the default `events list` unless you opt in.",
+        "other" => "Miscellaneous events that don't fit the other types."
+      }.freeze
+
+      desc "list", "List events in a date range"
+      long_desc <<~DESC
+        Fetches events between --start and --end (inclusive). Dates are parsed
+        in the team's default timezone server-side, so pass plain YYYY-MM-DD —
+        the CLI does not need timezone awareness.
+
+        Filters apply server-side:
+          --event-type     One of `wiq events types` (practice, dual_meet, ...)
+          --roster         One or more roster ids (the API joins through
+                           roster_events)
+          --expand         CSV of event_invites,event_bookings,private_lessons.
+                           Drops nested data into each event row.
+
+        There is no server-side location/site filter today — `Event.location`
+        is free-text and not in `ransackable_attributes`. A location-aware
+        backend is on the WIQ roadmap; until then post-process client-side.
+
+        Use --all to walk every page; default is page 1, per_page=100.
+      DESC
+      method_option :start, type: :string, required: true, desc: "YYYY-MM-DD (team timezone)"
+      method_option :end, type: :string, required: true, desc: "YYYY-MM-DD (team timezone)"
+      method_option :roster, type: :array, desc: "One or more roster ids"
+      method_option :event_type, type: :string, enum: %w[practice dual_meet tournament scramble private_lesson other],
+                                 desc: "Filter to one event_type (see `wiq events types`)"
+      method_option :expand, type: :string,
+                             desc: "CSV: event_invites, event_bookings, private_lessons"
+      method_option :all, type: :boolean, default: false
+      def list
+        params = {
+          "start" => options[:start],
+          "end" => options[:end],
+          "per_page" => 100
+        }
+        params["event_type"] = options[:event_type] if options[:event_type]
+        params["expand"] = options[:expand] if options[:expand]
+        if options[:roster]
+          options[:roster].each { |rid| (params["roster_ids[]"] ||= []) << rid }
+        end
+
+        records, total = fetch_index("/api/v1/events", params, key: "events")
+        render_index(
+          records, total: total,
+          summary: "Listed #{records.size} events #{options[:start]}..#{options[:end]}.",
+          breadcrumbs: [
+            { "cmd" => "wiq events show <id>", "description" => "Inspect a single event" },
+            { "cmd" => "wiq check_ins event <id>", "description" => "See check-ins for an event" }
+          ]
+        )
+      end
+
+      desc "show ID", "Fetch a single event"
+      long_desc <<~DESC
+        Single-event drill-down. The base payload covers all the obvious
+        fields (name, type, start/end, location, color, roster_events,
+        team_scores, paid_session).
+
+        Pass --expand to inline related collections:
+          event_invites      Per-invitee RSVP status
+          event_bookings     Per-bookee status (private lessons, paid drop-ins)
+          private_lessons    Linked private lessons + nested bookings
+
+        Soft-deleted events are not returned.
+      DESC
+      method_option :expand, type: :string,
+                             desc: "CSV: event_invites, event_bookings, private_lessons"
+      def show(id)
+        params = {}
+        params["expand"] = options[:expand] if options[:expand]
+        event = client.get("/api/v1/events/#{id}", params)
+        render(event,
+               summary: "Event #{event["id"]} — #{event["name"]}",
+               breadcrumbs: [
+                 { "cmd" => "wiq check_ins event #{event["id"]}", "description" => "See check-ins" },
+                 { "cmd" => "wiq reports run EventStatsReport --event #{event["id"]}",
+                   "description" => "Run per-event stats" }
+               ])
+      end
+
+      desc "types", "Print the canonical event_type strings"
+      long_desc <<~DESC
+        Static enum sourced from app/models/event.rb. Use these values with
+        --event-type on `wiq events list`. Note that the API will accept
+        any string in the event_type column, but values outside this list
+        won't filter anything useful.
+      DESC
+      def types
+        rows = TYPES.map { |type, desc| { "event_type" => type, "description" => desc } }
+        render_index(rows, summary: "Canonical event_type values.")
+      end
+    end
+  end
+end

data/lib/wiq/commands/metrics.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class Metrics < Base
+      NAMES = %w[
+        active_subscribers
+        cancelled_subscriptions
+        category_breakdown_net
+        charge_avg
+        charge_count
+        gross_volume
+        mrr
+        net_volume
+        new_subscriptions
+        renewed_subscriptions
+        revenue_per_subscriber
+      ].freeze
+
+      CURRENCY_METRICS = %w[
+        gross_volume net_volume mrr charge_avg revenue_per_subscriber
+        category_breakdown_net
+      ].freeze
+
+      VALID_RANGES = ["today", "7d", "4w", "3m", "12m", "year to date", "custom"].freeze
+      VALID_INTERVALS = %w[hourly daily weekly monthly].freeze
+
+      desc "list", "Print the supported metric names"
+      long_desc <<~DESC
+        Static enumeration of the dashboard metrics WIQ exposes at
+        /api/v1/metrics/<name>. The `currency` flag tells you whether
+        values are integer cents (true) or counts (false).
+
+        Auth: every metric requires `authorize :finances, :show?`, which
+        in practice means admin-coach. Non-admin PATs return 403.
+      DESC
+      def list
+        rows = NAMES.map do |n|
+          { "name" => n, "currency" => CURRENCY_METRICS.include?(n) }
+        end
+        render_index(rows,
+                     summary: "Use `wiq metrics show <name>` to fetch a specific metric. " \
+                              "Currency values are returned in integer cents.",
+                     breadcrumbs: [
+                       { "cmd" => "wiq metrics show mrr", "description" => "Example: monthly recurring revenue" }
+                     ])
+      end
+
+      desc "show NAME", "Fetch a single dashboard metric"
+      long_desc <<~DESC
+        Pulls /api/v1/metrics/<name> with the standard range/interval
+        params. The server returns both a primary_series and a
+        comparison_series (the previous period of the same length), plus
+        primary_total and comparison_total. The CLI drops the
+        server-rendered `charts[]` blob entirely — it's HTML for
+        Highcharts and not useful headless.
+
+        Ranges: today, 7d, 4w, 3m, 12m, "year to date", custom.
+        With --range custom you must pass --start-date and --end-date
+        (YYYY-MM-DD); comparison_series will be empty for custom ranges.
+
+        Intervals: hourly, daily, weekly, monthly. Invalid values are
+        silently coerced to `daily` server-side.
+
+        Currency metrics return integer cents (divide by 100 for dollars).
+        Non-currency metrics return raw counts.
+      DESC
+      method_option :range, type: :string, default: "7d", desc: VALID_RANGES.join(" | ")
+      method_option :interval, type: :string, default: "daily",
+                               enum: VALID_INTERVALS, desc: "interval_group"
+      method_option :start_date, type: :string, desc: "Required if --range=custom"
+      method_option :end_date, type: :string, desc: "Required if --range=custom"
+      method_option :no_comparison, type: :boolean, default: false,
+                                    desc: "Drop comparison_series/comparison_total from output"
+      def show(name)
+        unless VALID_RANGES.include?(options[:range])
+          raise Wiq::Error.new("Invalid --range #{options[:range].inspect}",
+                               code: "invalid_range",
+                               hint: "Valid: #{VALID_RANGES.join(", ")}")
+        end
+
+        params = {
+          "range" => options[:range],
+          "interval_group" => options[:interval]
+        }
+        if options[:range] == "custom"
+          unless options[:start_date] && options[:end_date]
+            raise Wiq::Error.new("--start-date and --end-date are required when --range=custom.",
+                                 code: "missing_custom_dates")
+          end
+          params["start_date"] = options[:start_date]
+          params["end_date"] = options[:end_date]
+        end
+
+        payload = client.get("/api/v1/metrics/#{name}", params)
+        metrics = payload["metrics"] || {}
+
+        data = {
+          "name" => name,
+          "currency" => CURRENCY_METRICS.include?(name),
+          "primary_series" => metrics["primary_series"],
+          "primary_total" => metrics["primary_total"]
+        }
+        unless options[:no_comparison]
+          data["comparison_series"] = metrics["comparison_series"]
+          data["comparison_total"] = metrics["comparison_total"]
+        end
+
+        render(data,
+               summary: "metric=#{name} range=#{options[:range]} interval=#{options[:interval]}",
+               meta: { "currency_unit" => CURRENCY_METRICS.include?(name) ? "cents" : "count" },
+               breadcrumbs: [
+                 { "cmd" => "wiq metrics list", "description" => "See all supported metrics" }
+               ])
+      end
+    end
+  end
+end

data/lib/wiq/commands/paid_sessions.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class PaidSessions < Base
+      PRESET_TYPES = %w[
+        registerable guest_registerable ends_in_future recurring_registerable
+        recurring not_recurring not_recurring_with_archived not_archived
+        dropin trial trial_or_dropin
+      ].freeze
+
+      desc "list", "List paid sessions"
+      long_desc <<~DESC
+        Paid sessions are WIQ's registration periods — recurring (monthly
+        subscriptions) and one-off (clinics, camps, drop-ins). They're the
+        thing you point most finance reports at.
+
+        --type accepts a preset server-side scope:
+          registerable, guest_registerable, ends_in_future, recurring,
+          recurring_registerable, not_recurring, not_recurring_with_archived,
+          not_archived, dropin, trial, trial_or_dropin
+
+        --season filters CLI-side to sessions whose [start_at, end_at] window
+        overlaps the given calendar year. Pair with --all to get an exhaustive
+        list.
+
+        Each row embeds a `stats` block with registration counts
+        (good_standing_registrations_count, overdue_registrations_count,
+        not_canceled_registrations_count, good_standing_members_count) so
+        you usually don't need a follow-up call.
+      DESC
+      method_option :type, type: :string, enum: PRESET_TYPES, desc: "Preset scope filter"
+      method_option :season, type: :numeric, desc: "Filter to sessions overlapping calendar year"
+      method_option :all, type: :boolean, default: false
+      def list
+        params = { "per_page" => 50 }
+        params[:type] = options[:type] if options[:type]
+
+        records, total = fetch_index("/api/v1/paid_sessions", params, key: "paid_sessions")
+
+        if options[:season]
+          year = Integer(options[:season])
+          y_start = "#{year}-01-01"
+          y_end = "#{year}-12-31"
+          records = records.select do |ps|
+            (ps["start_at"].to_s <= y_end) && ((ps["end_at"].to_s >= y_start) || ps["end_at"].nil?)
+          end
+        end
+
+        render_index(
+          records, total: total,
+          summary: "Listed #{records.size} paid sessions#{options[:season] ? " for #{options[:season]}" : ""}.",
+          breadcrumbs: [
+            { "cmd" => "wiq paid_sessions show <id>", "description" => "Inspect one session" },
+            { "cmd" => "wiq reports run PaidSessionAccountingReport --paid-session <id>",
+              "description" => "Line-item accounting (admin only)" }
+          ]
+        )
+      end
+
+      desc "show ID", "Fetch a single paid session"
+      long_desc <<~DESC
+        Full payload includes name, slug, start/end dates, session_type,
+        registration_open flag, capacity_limit, welcome/check-in/approval/denial
+        text, payment_options, roster_syncers, product + upsell_product,
+        and the `stats` count block.
+      DESC
+      def show(id)
+        ps = client.get("/api/v1/paid_sessions/#{id}")
+        render(ps,
+               summary: "Paid session #{ps["id"]} — #{ps["name"]}",
+               breadcrumbs: [
+                 { "cmd" => "wiq reports run PaidSessionAccountingReport --paid-session #{ps["id"]}",
+                   "description" => "Line-item accounting (admin only)" },
+                 { "cmd" => "wiq reports run SessionRegistrationAnswerReport --paid-session #{ps["id"]}",
+                   "description" => "Full Q&A export" }
+               ])
+      end
+    end
+  end
+end