wiq-cli 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bffdea54163c5b95a5cab8b219d3e5cb3a898a059d7edce13afa8ae02928b27a
-  data.tar.gz: 0f9e49529c6bc9fb37b75761e581d1de90a186107242a6c3092fcca55687f9ba
+  metadata.gz: eb99112754a10af0b80b20d71425f95e864fb28a3db78a1c3d0e7d75340ebf8f
+  data.tar.gz: ee12d73a7e5053dd48540c73c35e4327bb3f4456998f3182725b2a1d40a99403
 SHA512:
-  metadata.gz: 57f4ccba1f18ca17207739d051e94fcfb1b52b712c2d87e97fc64951acd4041d37a69f6d89d262dfde73cc44d278549d6ac9af02b67a572e3dd549dd2c58cd95
-  data.tar.gz: a317f13e135ab5b7a20f24b7f0c8a6640cbf84afc6a0a3e8d38d9d6483a537c302289f479b1cac0d454ca9c10485ebbcf453804decf4cdf02dbd73b822b0b933
+  metadata.gz: 92e5c6842312a60ad606f711b5c6893c2a2c761e181b0c999dcf0fcb6bb1e92f8cc3b25dadd6c365656b91f7b242666b43131e5680ec440036c67868f04eb794
+  data.tar.gz: a4e06d43acf373996c31593b6a736555ab9b5aa71a4d7c0baf606f8dc76fa090f3ae7519820ec04ed6ca1167375b977261d12312bca2fe07b70de86f902430e6

data/docs/deferred.md

@@ -68,9 +68,16 @@ Last updated: 2026-05-12 (after L1 ships).
   --all flag, base payload kept tight. Filters translate to Ransack
   (--first-name, --last-name, --weight-class, --academic-class, --age,
   --roster, --profile-type) + legacy free-text --query. --expand opts
-  into rosters / registration_answers per row. Multi-roster
+  into rosters / registration_answers / notification_preferences
+  (coach-only, Aug 2026 — see wiq_api_notes.md) per row. Multi-roster
   intersection deferred (API supports it; CLI surface didn't justify
   the complexity for v1). `wiq wrestlers show <id>` paired.
+- ~~**`wiq parents list/show`**~~ SHIPPED narrow (Aug 2026, alongside
+  the `expand_notification_preferences` param from wrestling PR #2460).
+  Filters: --query (legacy name search), --first-name / --last-name
+  (Ransack). --expand notification_preferences (coach-only). Slim
+  payload by design (id, user_id, type, names); no wrestler refs —
+  family linkage stays on the wrestlers side.
 - **`wiq url parse <url>`** — extract team/roster/event IDs from WIQ web
   URLs. Initial-plan item; useful for agents pasted URLs by humans.
 - **`wiq paid_sessions create/update`**, **`wiq rosters create/update`**,

data/docs/wiq_api_notes.md

@@ -390,6 +390,60 @@ them. PATs minted by parents/wrestlers will 403 here.
   shape (`category`, `subcategory`, `detail_category`, `total_net_amount`)
   — special-case it in the formatter.
 
+## Wrestlers + parents: `expand_notification_preferences`
+
+Shipped Aug 2026 (wrestling PR #2460). All four endpoints accept
+`expand_notification_preferences=true`:
+
+- `GET /api/v1/wrestlers` / `GET /api/v1/wrestlers/:id`
+- `GET /api/v1/parents` / `GET /api/v1/parents/:id`
+
+When set, each profile gains two fields, mirroring the "Notified via"
+section on the web profile pages:
+
+```json
+{
+  "wiq_app_installed": true,
+  "notification_preferences": {
+    "email": true, "sms": false, "push": true, "push_user_pref": true
+  }
+}
+```
+
+Things to know:
+
+- **Coach-gated, silently.** `expand_notification_preferences?` in
+  `base_controller.rb` requires `current_profile.coach?`. A parent- or
+  wrestler-bound PAT gets a normal 200 with the fields simply absent —
+  no error. Don't diagnose missing fields as a bug; check the PAT's
+  profile type first (`wiq auth status`).
+- **Nullable prefs.** `notification_preference` is a `has_one` that may
+  not exist; each key can be `null` (rendered via `np&.email` etc.).
+  Treat `null` as "no explicit preference recorded", not "off".
+- The controller eager-loads `:notification_preference` only when the
+  flag is set, so the index cost is opt-in.
+
+CLI exposure: `wiq wrestlers list|show --expand notification_preferences`
+(composes with `rosters`, `registration_answers` in the same CSV) and
+`wiq parents list|show --expand notification_preferences`.
+
+While we're here, the parents endpoints themselves
+(`app/controllers/api/v1/parents_controller.rb`):
+
+- Index scope is `team.parent_profiles.teammates` ordered by first
+  name — guest parents (camp signups) are excluded. Policy scope:
+  coaches see the whole team (roster-restricted coaches see only their
+  allowed parents), wrestlers see their own guardians, parents see
+  nobody.
+- Filters: legacy `?query=` name search, plus Ransack limited to
+  `id, first_name, last_name` (`ParentProfile.ransackable_attributes`).
+- The jbuilder payload is slim: `id, user_id, type, first_name,
+  last_name, full_name` (+ the expand fields above). No wrestler refs —
+  walk the family from the wrestler side (`wiq wrestlers show <id>`
+  embeds parent refs).
+- `show` uses `ParentProfile.with_deleted` — soft-deleted parents still
+  resolve by id.
+
 ## Check-ins (attendance)
 
 Two index endpoints + create/update on the event-scoped path.

data/lib/wiq/cli.rb

@@ -83,10 +83,16 @@ module Wiq
     desc "wrestlers SUBCOMMAND", "Search wrestlers — narrow ID-discovery surface (list, show)"
     subcommand "wrestlers", Wiq::Commands::Wrestlers
 
+    desc "parents SUBCOMMAND", "Search parents — narrow ID-discovery surface (list, show)"
+    subcommand "parents", Wiq::Commands::Parents
+
     desc "charges SUBCOMMAND", "Payment history — list charges by family, status, type, date (admin only)"
     subcommand "charges", Wiq::Commands::Charges
 
     desc "billing_profiles SUBCOMMAND", "Look up a parent or coach's billing profile (admin only)"
     subcommand "billing_profiles", Wiq::Commands::BillingProfiles
+
+    desc "payouts SUBCOMMAND", "Bank payouts / deposits — list and show (admin only)"
+    subcommand "payouts", Wiq::Commands::Payouts
   end
 end

data/lib/wiq/commands/parents.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class Parents < Base
+      DEFAULT_PER_PAGE = 20
+
+      desc "list", "Search parents — narrow ID-discovery surface"
+      long_desc <<~DESC
+        Narrow listing over the team's parent profiles (teammates only —
+        guest parents from camp signups are excluded server-side). Rows
+        are slim: id, user_id, type, first_name, last_name, full_name.
+        Sorted by first name. Default page size is 20; there's no --all
+        flag.
+
+        Filters:
+          --query        free-text name search (legacy `?query=`)
+          --first-name   q[first_name_cont]
+          --last-name    q[last_name_cont]
+
+        --expand opts into a wider payload:
+          notification_preferences  Adds wiq_app_installed + a
+                                    notification_preferences object
+                                    (email, sms, push, push_user_pref)
+                                    per parent — "which parents can we
+                                    reach, and how?". Coach PATs only;
+                                    the server silently omits it for
+                                    parent/wrestler tokens.
+
+        The parent → wrestler linkage is NOT in this payload. To see a
+        family's kids, go the other direction: `wiq wrestlers show <id>`
+        embeds parent refs, or `wiq wrestlers list --query <last name>`.
+      DESC
+      method_option :query, type: :string, desc: "Free-text name search"
+      method_option :first_name, type: :string, desc: "First name (contains)"
+      method_option :last_name, type: :string, desc: "Last name (contains)"
+      method_option :expand, type: :string,
+                             desc: "CSV: notification_preferences"
+      method_option :per_page, type: :numeric, default: DEFAULT_PER_PAGE,
+                               desc: "Page size (default 20; narrow surface)"
+      def list
+        params = build_list_params
+
+        records, total = fetch_index("/api/v1/parents", params, key: "parent_profiles")
+        render_index(
+          records, total: total,
+          summary: "Listed #{records.size} parents#{summary_filters_suffix}.",
+          breadcrumbs: [
+            { "cmd" => "wiq parents show <id>", "description" => "Drill into one parent" },
+            { "cmd" => "wiq billing_profiles show <id> --profile-type ParentProfile",
+              "description" => "Billing profile for a parent (admin only)" },
+            { "cmd" => "wiq wrestlers list --last-name <name>",
+              "description" => "Find the family's wrestlers (parent refs embedded)" }
+          ]
+        )
+      end
+
+      desc "show ID", "Fetch a single parent profile"
+      long_desc <<~DESC
+        Single-parent drill-down. Same slim payload as the index (id,
+        user_id, type, names); soft-deleted parents still resolve here.
+
+        Pass --expand for additional sections:
+          notification_preferences  wiq_app_installed + notification_preferences
+                                    (email, sms, push, push_user_pref) —
+                                    "can this parent be reached, and how?"
+                                    Coach PATs only; silently omitted for
+                                    parent/wrestler tokens.
+      DESC
+      method_option :expand, type: :string,
+                             desc: "CSV: notification_preferences"
+      def show(id)
+        params = {}
+        params["expand_notification_preferences"] = true if expand_includes?("notification_preferences")
+        parent = client.get("/api/v1/parents/#{id}", params)
+        render(parent,
+               summary: "Parent #{parent["id"]} — #{parent["full_name"]}",
+               breadcrumbs: [
+                 { "cmd" => "wiq billing_profiles show #{parent["id"]} --profile-type ParentProfile",
+                   "description" => "Billing profile for this parent (admin only)" },
+                 { "cmd" => "wiq wrestlers list --last-name #{parent["last_name"]}",
+                   "description" => "Likely wrestlers for this family" }
+               ])
+      end
+
+      no_commands do
+        # Extracted so the spec can verify the option → query-param mapping
+        # without round-tripping a real Faraday connection.
+        def build_list_params
+          params = { "per_page" => options[:per_page] || DEFAULT_PER_PAGE }
+          params["query"] = options[:query] if options[:query]
+          params["q[first_name_cont]"] = options[:first_name] if options[:first_name]
+          params["q[last_name_cont]"] = options[:last_name] if options[:last_name]
+          params["expand_notification_preferences"] = true if expand_includes?("notification_preferences")
+          params
+        end
+
+        def expand_includes?(part)
+          return false unless options[:expand]
+
+          options[:expand].split(",").map(&:strip).include?(part)
+        end
+
+        def summary_filters_suffix
+          bits = []
+          bits << "matching #{options[:query].inspect}" if options[:query]
+          bits << "first name ~ #{options[:first_name].inspect}" if options[:first_name]
+          bits << "last name ~ #{options[:last_name].inspect}" if options[:last_name]
+          bits.empty? ? "" : " (#{bits.join(", ")})"
+        end
+      end
+    end
+  end
+end

data/lib/wiq/commands/payouts.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class Payouts < Base
+      # Payout.status is a plain text column mirroring the billing
+      # partner's normalized status — no integer-enum translation needed
+      # (unlike Charge.status). Common values below; the column is not
+      # constrained server-side, so --status stays free-form.
+      COMMON_STATUSES = %w[paid in_transit scheduled].freeze
+      BILLING_PARTNERS = %w[stripe justifi].freeze
+      DEFAULT_PER_PAGE = 25
+
+      desc "list", "List bank payouts / deposits (finance: admin coach only)"
+      long_desc <<~DESC
+        Returns payouts — the batched deposits Stripe or Justifi (WIQ
+        Payments) sends to the club's bank account. Useful for "when does
+        our money arrive?", "what landed in the bank last week?", and
+        reconciling a bank statement line against WIQ charges.
+
+        Auth: admin-only (Pundit scope filters non-admin coach PATs to
+        empty results; parent/wrestler PATs return 403).
+
+        Filters translate to Ransack server-side (allowlist: deposits_at,
+        status, billing_partner, amount, created_at):
+          --status <str>           q[status_eq]. Common values: paid,
+                                   in_transit, scheduled. Free-form —
+                                   the column mirrors the billing
+                                   partner's status strings.
+          --billing-partner <str>  q[billing_partner_eq] — stripe | justifi
+                                   (justifi is branded "WIQ Payments").
+          --since <YYYY-MM-DD>     q[deposits_at_gteq]
+          --until <YYYY-MM-DD>     q[deposits_at_lteq]
+
+        --since/--until filter on deposits_at (when the money reaches the
+        bank), not created_at — that's the date a treasurer reconciling a
+        bank statement cares about. Rows come back newest-deposit first.
+
+        Money fields are integer cents. Each row: amount (net deposit),
+        payments_count/payments_total, refunds_count/refunds_total,
+        fees_total, status, deposits_at, billing_partner, description,
+        and destination (bank name + last4). Payouts accrue slowly (a
+        few per week), so default page size is #{DEFAULT_PER_PAGE}; pass
+        --all with --since to bound an exhaustive scan.
+
+        To see which individual charges landed in a payout, go through
+        the charges side: each `wiq charges list` row embeds its payout,
+        so filter charges by date window and group on payout.id.
+      DESC
+      method_option :status, type: :string,
+                             desc: "Filter by status (common: #{COMMON_STATUSES.join(", ")})"
+      method_option :billing_partner, type: :string, enum: BILLING_PARTNERS,
+                                      desc: "Filter by billing partner (stripe | justifi)"
+      method_option :since, type: :string, desc: "Earliest deposits_at (YYYY-MM-DD)"
+      method_option :until, type: :string, desc: "Latest deposits_at (YYYY-MM-DD)"
+      method_option :per_page, type: :numeric, default: DEFAULT_PER_PAGE,
+                               desc: "Page size (default #{DEFAULT_PER_PAGE})"
+      method_option :all, type: :boolean, default: false,
+                          desc: "Follow pagination until exhausted"
+      def list
+        params = build_list_params
+        records, total = fetch_index("/api/v1/payouts", params, key: "payouts")
+        render_index(
+          records, total: total,
+          summary: "Listed #{records.size} payouts#{summary_filters_suffix}.",
+          breadcrumbs: [
+            { "cmd" => "wiq payouts show <id>",
+              "description" => "Inspect a single payout" },
+            { "cmd" => "wiq charges list --since <date> --until <date> --all",
+              "description" => "Charges in a window — each row embeds its payout for reconciliation" }
+          ]
+        )
+      end
+
+      desc "show ID", "Fetch a single payout"
+      long_desc <<~DESC
+        Full payout payload: amount, currency, status, deposits_at,
+        payments_count/payments_total, refunds_count/refunds_total,
+        fees_total, billing_partner (+ billing_partner_id, the Stripe/
+        Justifi payout id like po_...), delivery_method, description, and
+        destination bank account (holder name, bank name, last4,
+        account type). Money fields are integer cents.
+
+        Auth: admin-only; a payout outside the PAT's team returns 403.
+      DESC
+      def show(id)
+        payout = client.get("/api/v1/payouts/#{id}")
+        render(payout,
+               summary: "Payout #{payout["id"]} — #{payout["status"]}, " \
+                        "#{format_cents(payout["amount"])} deposited #{payout["deposits_at"]}",
+               breadcrumbs: [
+                 { "cmd" => "wiq charges list --since <date> --until <date> --all",
+                   "description" => "Find this payout's charges (rows embed payout.id)" }
+               ])
+      end
+
+      no_commands do
+        def build_list_params
+          params = { "per_page" => options[:per_page] || DEFAULT_PER_PAGE }
+          params["q[status_eq]"] = options[:status] if options[:status]
+          params["q[billing_partner_eq]"] = options[:billing_partner] if options[:billing_partner]
+          params["q[deposits_at_gteq]"] = options[:since] if options[:since]
+          params["q[deposits_at_lteq]"] = options[:until] if options[:until]
+          params
+        end
+
+        def summary_filters_suffix
+          bits = []
+          bits << "status=#{options[:status]}" if options[:status]
+          bits << "billing_partner=#{options[:billing_partner]}" if options[:billing_partner]
+          bits << "since=#{options[:since]}" if options[:since]
+          bits << "until=#{options[:until]}" if options[:until]
+          bits.empty? ? "" : " (#{bits.join(", ")})"
+        end
+
+        def format_cents(cents)
+          return "?" unless cents.is_a?(Numeric)
+
+          format("$%.2f", cents / 100.0)
+        end
+      end
+    end
+  end
+end

data/lib/wiq/commands/wrestlers.rb

@@ -35,8 +35,14 @@ module Wiq
         client-side.
 
         --expand opts into a wider payload:
-          rosters                Adds full roster details per wrestler
-          registration_answers   Adds intake-form answers per wrestler
+          rosters                   Adds full roster details per wrestler
+          registration_answers      Adds intake-form answers per wrestler
+          notification_preferences  Adds wiq_app_installed + a
+                                    notification_preferences object
+                                    (email, sms, push, push_user_pref)
+                                    per wrestler. Coach PATs only — the
+                                    server silently omits it for
+                                    parent/wrestler tokens.
 
         Base payload is already wider than most index endpoints (parents,
         coach_guardians, profile_photos, basic roster refs all render by
@@ -58,7 +64,7 @@ module Wiq
                                    desc: "Default 'teammate' matches the WIQ web UI default; " \
                                          "'all' removes the filter entirely"
       method_option :expand, type: :string,
-                             desc: "CSV: rosters, registration_answers"
+                             desc: "CSV: rosters, registration_answers, notification_preferences"
       method_option :per_page, type: :numeric, default: DEFAULT_PER_PAGE,
                                desc: "Page size (default 20; narrow surface)"
       def list
@@ -84,15 +90,21 @@ module Wiq
         rosters refs).
 
         Pass --expand for additional sections:
-          rosters                Full roster details with tags
-          registration_answers   Intake-form answers
+          rosters                   Full roster details with tags
+          registration_answers      Intake-form answers
+          notification_preferences  wiq_app_installed + notification_preferences
+                                    (email, sms, push, push_user_pref) —
+                                    "can this family be reached, and how?"
+                                    Coach PATs only; silently omitted for
+                                    parent/wrestler tokens.
       DESC
       method_option :expand, type: :string,
-                             desc: "CSV: rosters, registration_answers"
+                             desc: "CSV: rosters, registration_answers, notification_preferences"
       def show(id)
         params = {}
         params["expand_rosters"] = true if expand_includes?("rosters")
         params["expand_registration_answers"] = true if expand_includes?("registration_answers")
+        params["expand_notification_preferences"] = true if expand_includes?("notification_preferences")
         wrestler = client.get("/api/v1/wrestlers/#{id}", params)
         render(wrestler,
                summary: "Wrestler #{wrestler["id"]} — #{wrestler["full_name"] || wrestler["display_name"]}",
@@ -120,6 +132,7 @@ module Wiq
           params["q[profile_type_eq]"] = options[:profile_type] if profile_type_filter?
           params["expand_rosters"] = true if expand_includes?("rosters")
           params["expand_registration_answers"] = true if expand_includes?("registration_answers")
+          params["expand_notification_preferences"] = true if expand_includes?("notification_preferences")
           params
         end
 

data/lib/wiq/version.rb

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

data/lib/wiq.rb

@@ -26,6 +26,8 @@ require "wiq/commands/prospect_families"
 require "wiq/commands/workflows"
 require "wiq/commands/setup"
 require "wiq/commands/wrestlers"
+require "wiq/commands/parents"
 require "wiq/commands/charges"
 require "wiq/commands/billing_profiles"
+require "wiq/commands/payouts"
 require "wiq/cli"

data/share/skills/wiq/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wiq
-description: Use this skill when the user asks about their WrestlingIQ data — rosters, attendance, check-ins, paid sessions and registrations, the prospects/leads pipeline, financial metrics, reports, USAW/AAU memberships, fundraising, online store orders, or per-location/site breakdowns for multi-gym clubs. The `wiq` CLI provides read-only access to /api/v1 via personal access tokens. Recognize phrasings like "how is our pipeline?", "who came to practice this week?", "show me the roster", "what's our MRR?", "which kids need USAW renewal?", "how is the Eastside gym doing?", or anything that maps to a wrestling club's admin workflows.
+description: Use this skill when the user asks about their WrestlingIQ data — rosters, attendance, check-ins, paid sessions and registrations, the prospects/leads pipeline, financial metrics, payouts/bank deposits, reports, USAW/AAU memberships, fundraising, online store orders, or per-location/site breakdowns for multi-gym clubs. The `wiq` CLI provides read-only access to /api/v1 via personal access tokens. Recognize phrasings like "how is our pipeline?", "who came to practice this week?", "show me the roster", "what's our MRR?", "which kids need USAW renewal?", "how is the Eastside gym doing?", or anything that maps to a wrestling club's admin workflows.
 ---
 
 # WrestlingIQ CLI Skill
@@ -284,6 +284,25 @@ charge for the same `(billing_profile_id, chargeable_id,
 chargeable_type)` tuple exists AFTER the failure's `created_at`. The
 canonical pattern is in `wiq workflows show failed-payments-recent`.
 
+### Payouts (bank deposits)
+
+For "when does our money hit the bank?" / "what deposited last week?" /
+bank-statement reconciliation — use the payouts surface (admin PAT only):
+
+```bash
+wiq payouts list --since 2026-08-01 --until 2026-08-18   # deposits in a window
+wiq payouts list --status in_transit                     # money on the way
+wiq payouts show <id>                                    # one deposit's detail
+```
+
+`--since/--until` filter on `deposits_at` (bank arrival date), not
+`created_at`. `Payout.status` is a plain string column (paid,
+in_transit, scheduled, ...) — no integer-enum translation, unlike
+charges. All
+money fields are integer cents. To see which charges make up a payout,
+go through charges: each `wiq charges list` row embeds its `payout`,
+so pull charges for the date window and group by `payout.id`.
+
 To go from a wrestler name to a billing_profile_id:
 
 ```bash
@@ -343,6 +362,25 @@ For exhaustive exports go through `wiq reports run RosterReport`
 `profile_type=teammate` (matching the WIQ web UI default); pass
 `--profile-type alumnus|guest|all` to widen.
 
+For "can this family be reached, and how?" questions, add
+`--expand notification_preferences` to `wrestlers list|show` or
+`parents list|show`. Each row gains `wiq_app_installed` plus a
+`notification_preferences` object (`email`, `sms`, `push`,
+`push_user_pref`; `null` means no explicit preference recorded). Coach
+PATs only — with a parent/wrestler token the server returns 200 with
+the fields silently absent, so a missing field means "check the
+token's profile type", not "API bug".
+
+### Parents
+
+`wiq parents list [--query <name>] [--first-name X] [--last-name Y]`
+and `wiq parents show <id>` — slim payload (id, user_id, names) over
+the team's teammate parents. There are no wrestler refs on a parent
+row; to walk a family, start from the wrestler side
+(`wiq wrestlers show <id>` embeds parent refs). Main uses: parent-first
+ID discovery for `wiq billing_profiles show <id> --profile-type
+ParentProfile`, and the notification-reachability expand above.
+
 ## Locations (multi-site clubs)
 
 WIQ has a structured Location model (name + street address, per team).

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wiq-cli
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - WrestlingIQ
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-02 00:00:00.000000000 Z
+date: 2026-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -93,6 +93,8 @@ files:
 - lib/wiq/commands/locations.rb
 - lib/wiq/commands/metrics.rb
 - lib/wiq/commands/paid_sessions.rb
+- lib/wiq/commands/parents.rb
+- lib/wiq/commands/payouts.rb
 - lib/wiq/commands/prospect_families.rb
 - lib/wiq/commands/prospects.rb
 - lib/wiq/commands/registrations.rb