wiq-cli 0.1.0

data/lib/wiq/commands/prospect_families.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class ProspectFamilies < Base
+      SORT_OPTIONS = %w[newest oldest_followup oldest_contact next_trial].freeze
+
+      desc "list", "List prospect families (one row per household)"
+      long_desc <<~DESC
+        Returns one row per family (household). Each row embeds:
+          - All the family's prospects (one per kid) inline
+          - The most recent `last_contact` note (activity_type, author,
+            occurred_at) preloaded as has_one
+          - The family's registration_answers, with question prompts
+
+        `--query` searches BOTH family contact (name, email, phone — with
+        digit-stripped phone matching) AND child first/last names via a
+        subquery on the prospects table. A "Johnny" search matches either
+        a parent named Johnny OR a child named Johnny; you'll see which
+        from the `child_first_name` field on the embedded prospects.
+
+        Filters mirror `wiq prospects list`, plus:
+          --question-id <id> + --answer-value <str>   Filter by a specific
+                                                       registration answer
+                                                       (both flags required)
+          --sort                                       newest (default for
+                                                       "All Leads"),
+                                                       oldest_followup
+                                                       (default when
+                                                       --attention=needs_attention),
+                                                       oldest_contact (NULLs
+                                                       first — never-contacted
+                                                       families surface), or
+                                                       next_trial
+      DESC
+      method_option :query, type: :string,
+                            desc: "Free-text search (bypasses other filters)"
+      method_option :attention, type: :string, enum: Prospects::ATTENTION_MODES,
+                                desc: "Pipeline cut: needs_attention or handled"
+      method_option :stage, type: :string, enum: Prospects::STAGES,
+                            desc: "Families with at least one prospect in this stage"
+      method_option :assigned_to_me, type: :boolean, default: false,
+                                     desc: "Only families assigned to the calling coach"
+      method_option :assigned_coach, type: :numeric,
+                                     desc: "Only families assigned to this coach_profile id"
+      method_option :question_id, type: :numeric,
+                                  desc: "Registration question id to filter by (pair with --answer-value)"
+      method_option :answer_value, type: :string,
+                                   desc: "Registration answer value (pair with --question-id)"
+      method_option :sort, type: :string, enum: SORT_OPTIONS,
+                           desc: "Override default sort. Default depends on --attention."
+      method_option :all, type: :boolean, default: false
+      def list
+        params = { "per_page" => 50 }
+        if options[:query]
+          params["query"] = options[:query]
+        else
+          params["attention_mode"] = options[:attention] if options[:attention]
+          params["stage"] = options[:stage] if options[:stage]
+          if options[:assigned_to_me]
+            params["assigned_to"] = "me"
+          elsif options[:assigned_coach]
+            params["assigned_coach_id"] = options[:assigned_coach]
+          end
+          if options[:question_id] && options[:answer_value]
+            params["question_id"] = options[:question_id]
+            params["answer_value"] = options[:answer_value]
+          elsif options[:question_id] || options[:answer_value]
+            raise Wiq::Error.new("--question-id and --answer-value must be passed together.",
+                                 code: "missing_question_pair")
+          end
+        end
+        params["sort"] = options[:sort] if options[:sort]
+
+        records, total = fetch_index("/api/v1/prospect_families", params, key: "prospect_families")
+        render_index(
+          records, total: total,
+          summary: "Listed #{records.size} prospect families.",
+          breadcrumbs: [
+            { "cmd" => "wiq prospect_families show <id>", "description" => "Drill into one family" },
+            { "cmd" => "wiq prospect_families notes <id>", "description" => "See contact log" },
+            { "cmd" => "wiq prospects summary", "description" => "Pipeline dashboard" }
+          ]
+        )
+      end
+
+      desc "show ID", "Fetch a single prospect family"
+      long_desc <<~DESC
+        Full family payload: contact info (name/email/phone), source
+        ("How did you hear about us?"), linked guardian (parent profile),
+        assigned coach, the most recent `last_contact` summary, every
+        prospect (kid) sorted by created_at, and every registration_answer
+        with its question prompt.
+      DESC
+      def show(id)
+        family = client.get("/api/v1/prospect_families/#{id}")
+        render(family,
+               summary: "Family #{family["id"]} — #{family["contact_name"]} (#{family["prospects"].size} prospects).",
+               breadcrumbs: [
+                 { "cmd" => "wiq prospect_families notes #{family["id"]}",
+                   "description" => "See contact log for this family" },
+                 { "cmd" => "wiq prospects show <prospect_id>", "description" => "Drill into one kid" }
+               ])
+      end
+
+      desc "notes FAMILY_ID", "List notes / contact log for a prospect family"
+      long_desc <<~DESC
+        Contact log for a family — every Note row with
+        noteable_type=ProspectFamily, sorted newest-first. Each row:
+        author (name + profile type), created_at, activity_type
+        (e.g. phone_call, email, text, in_person, dm), and the note
+        body in both rich content + plain_content.
+      DESC
+      method_option :all, type: :boolean, default: false
+      def notes(family_id)
+        records, total = fetch_index("/api/v1/prospect_families/#{family_id}/notes",
+                                     { "per_page" => 50 },
+                                     key: "notes")
+        render_index(
+          records, total: total,
+          summary: "Listed #{records.size} notes for family #{family_id}.",
+          breadcrumbs: [
+            { "cmd" => "wiq prospect_families show #{family_id}", "description" => "Back to the family" }
+          ]
+        )
+      end
+    end
+  end
+end

data/lib/wiq/commands/prospects.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class Prospects < Base
+      STAGES = %w[inquiry trial_scheduled trialing trial_complete converted didnt_join archived].freeze
+      ATTENTION_MODES = %w[needs_attention handled].freeze
+
+      desc "list", "List individual prospects (one row per kid)"
+      long_desc <<~DESC
+        Returns one row per prospect (kid), sorted newest-first.
+
+        Funnel stages: inquiry → trial_scheduled → trialing →
+        trial_complete → converted (terminal) | didnt_join (terminal) |
+        archived (terminal).
+
+        Filters:
+          --query              Free-text search across BOTH family contact
+                               (name/email/phone) AND child first/last
+                               name. Backed by the ProspectFamily.search
+                               scope which unions both via a subquery.
+                               When set, ALL other filters are bypassed
+                               server-side.
+
+                               KNOWN BUG: `wiq prospects list --query …`
+                               currently returns HTTP 500 due to an
+                               ambiguous-column ORDER BY on the
+                               prospect↔prospect_family join. Workaround:
+                               use `wiq prospect_families list --query …`
+                               instead (same search scope, same matches,
+                               returns the family with its prospects
+                               nested inline).
+          --attention          needs_attention | handled
+          --stage              One funnel stage
+          --assigned-to-me     Only families assigned to the calling coach
+          --assigned-coach <id>  Same, for any coach by id
+
+        Pair with `wiq prospect_families list` to see leads at the
+        household level instead.
+      DESC
+      method_option :query, type: :string,
+                            desc: "Free-text search across family name/email/phone (bypasses other filters)"
+      method_option :attention, type: :string, enum: ATTENTION_MODES,
+                                desc: "Pipeline cut: needs_attention or handled"
+      method_option :stage, type: :string, enum: STAGES,
+                            desc: "Filter to one funnel stage"
+      method_option :assigned_to_me, type: :boolean, default: false,
+                                     desc: "Only prospects on a family assigned to the calling coach"
+      method_option :assigned_coach, type: :numeric,
+                                     desc: "Only prospects on a family assigned to this coach_profile id"
+      method_option :all, type: :boolean, default: false
+      def list
+        params = { "per_page" => 50 }
+        if options[:query]
+          params["query"] = options[:query]
+        else
+          params["attention_mode"] = options[:attention] if options[:attention]
+          params["stage"] = options[:stage] if options[:stage]
+          if options[:assigned_to_me]
+            params["assigned_to"] = "me"
+          elsif options[:assigned_coach]
+            params["assigned_coach_id"] = options[:assigned_coach]
+          end
+        end
+
+        records, total = fetch_index("/api/v1/prospects", params, key: "prospects")
+        render_index(records, total: total,
+                              summary: "Listed #{records.size} prospects.",
+                              breadcrumbs: breadcrumbs)
+      end
+
+      desc "show ID", "Fetch a single prospect"
+      long_desc <<~DESC
+        Full prospect payload: child name + DOB + academic class,
+        experience_level, current stage + stage_changed_at, all the
+        funnel timestamps (trial_scheduled_at, trial_completed_at,
+        converted_at, archived_at), needs_follow_up + follow_up_reason,
+        days_in_stage and days_since_follow_up, plus the linked
+        wrestler_profile (if converted), paid_session (if trialing),
+        and conversion_billing_subscription with plan name (if converted
+        on a recurring sub).
+      DESC
+      def show(id)
+        prospect = client.get("/api/v1/prospects/#{id}")
+        render(prospect,
+               summary: "Prospect #{prospect["id"]} — #{prospect["child_first_name"]} #{prospect["child_last_name"]} (stage=#{prospect["stage"]}).",
+               breadcrumbs: [
+                 { "cmd" => "wiq prospect_families show #{prospect["prospect_family_id"]}",
+                   "description" => "Family this prospect belongs to" },
+                 { "cmd" => "wiq prospect_families notes #{prospect["prospect_family_id"]}",
+                   "description" => "Contact log for the family" }
+               ])
+      end
+
+      desc "summary", "Pipeline dashboard: counts per stage + conversion rate"
+      long_desc <<~DESC
+        Single-call dashboard. Returns an unwrapped object (not paginated)
+        with stage-bucketed counts, needs-action totals, family totals,
+        and an aggregate conversion_rate.
+
+        Cohort options for the conversion calculation:
+          --start-date / --end-date    Explicit window (must be paired)
+          --conversion-days N          Look-back of 30, 60, 90, or 180
+                                       days (default 90)
+
+        Both numerator and denominator are pinned to the same cohort
+        (prospects created in the window). Without that pin, an old
+        prospect converting now would push the rate past 100%.
+
+        Best agent entry point for "how's our pipeline?" — single round
+        trip, structured numbers.
+      DESC
+      method_option :start_date, type: :string,
+                                 desc: "Cohort window start (YYYY-MM-DD). Requires --end-date."
+      method_option :end_date, type: :string,
+                               desc: "Cohort window end (YYYY-MM-DD). Requires --start-date."
+      method_option :conversion_days, type: :numeric, enum: [30, 60, 90, 180],
+                                      desc: "Look-back window in days when no explicit dates (default 90)"
+      def summary
+        params = {}
+        if options[:start_date] && options[:end_date]
+          params["start_date"] = options[:start_date]
+          params["end_date"] = options[:end_date]
+        elsif options[:start_date] || options[:end_date]
+          raise Wiq::Error.new("--start-date and --end-date must be passed together.",
+                               code: "missing_cohort_dates")
+        end
+        params["conversion_days"] = options[:conversion_days] if options[:conversion_days]
+
+        data = client.get("/api/v1/prospects/summary", params)
+        render(data,
+               summary: "Prospect pipeline: #{data["needs_action_count"]} need action, " \
+                        "#{data["active_trials_count"]} active trials, " \
+                        "conversion=#{data["conversion_rate"]}%.",
+               breadcrumbs: [
+                 { "cmd" => "wiq prospects list --attention needs_attention",
+                   "description" => "Drill into leads needing action" },
+                 { "cmd" => "wiq prospect_families list --sort oldest_followup",
+                   "description" => "Queue of families ordered by stalest follow-up" }
+               ])
+      end
+
+      no_commands do
+        def breadcrumbs
+          [
+            { "cmd" => "wiq prospects summary", "description" => "Pipeline dashboard" },
+            { "cmd" => "wiq prospect_families list", "description" => "List by family instead of by kid" }
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/wiq/commands/registrations.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class Registrations < Base
+      desc "questions", "List the team's registration questions"
+      long_desc <<~DESC
+        Every registration question the team has authored. Useful for:
+
+          - Discovering question ids to pass to
+            `wiq reports run RosterReport --append-properties ...`
+          - Auditing what the team is collecting at signup
+          - Finding the team's address question(s) so you can join zip
+            codes (the `RegAddressQuestion` type) to a wrestler
+
+        Each row exposes `prompt`, `type` (e.g. RegTextQuestion,
+        RegAddressQuestion, RegYesNoQuestion), `for_type` (who the
+        question applies to), `is_public`, `coach_visibility`, and
+        `display_order`.
+
+        Skip rows whose `deleted_at` is set — they're still in the index
+        payload but no longer asked.
+      DESC
+      method_option :all, type: :boolean, default: false
+      def questions
+        records, total = fetch_index("/api/v1/registration_questions", { "per_page" => 100 }, key: "registration_questions")
+        render_index(
+          records, total: total,
+          summary: "Listed #{records.size} registration questions.",
+          breadcrumbs: [
+            { "cmd" => "wiq reports run RosterReport --append-properties <id1> <id2>",
+              "description" => "Surface these as columns on a roster report" }
+          ]
+        )
+      end
+
+      desc "answers", "List a profile's registration answers"
+      long_desc <<~DESC
+        Returns the registration answers for a specific profile (wrestler,
+        parent, or coach). Useful for spot-checking what a family submitted
+        at signup.
+
+          --profile-type   WrestlerProfile | ParentProfile | CoachProfile
+          --profile        Profile id
+          --session        Restrict to a specific paid_session
+          --visibility     public | private (admin only for private)
+
+        Privacy note: Pundit gates private answers — a non-admin coach PAT
+        will get the public subset only.
+      DESC
+      method_option :profile, type: :numeric, required: true, desc: "Profile id"
+      method_option :profile_type, type: :string, required: true,
+                                   enum: %w[WrestlerProfile ParentProfile CoachProfile],
+                                   desc: "Profile class"
+      method_option :session, type: :numeric, desc: "Restrict to a paid session id"
+      method_option :visibility, type: :string, enum: %w[public private], desc: "Visibility filter"
+      method_option :all, type: :boolean, default: false
+      def answers
+        params = {
+          "profile_id" => options[:profile],
+          "profile_type" => options[:profile_type],
+          "per_page" => 50
+        }
+        params["session_id"] = options[:session] if options[:session]
+        params["visibility"] = options[:visibility] if options[:visibility]
+
+        records, total = fetch_index("/api/v1/registration_answers", params, key: "registration_answers")
+        render_index(
+          records, total: total,
+          summary: "Listed #{records.size} answers for #{options[:profile_type]} #{options[:profile]}.",
+          breadcrumbs: [
+            { "cmd" => "wiq registrations questions", "description" => "See the corresponding questions" }
+          ]
+        )
+      end
+    end
+  end
+end