wiq-cli 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8732206776c88ba1c9d5630407e3a7a4ba6386e528cb5a7a36b2b7c8bcda3dc
-  data.tar.gz: 499116e3d7977c22e0f44759ea59406c49265e865def76300353de0052dbf5b0
+  metadata.gz: ee99cfc6ad08abdf7e1318883bcfa3ecc45635d2d521de150ed1622d867b0ebc
+  data.tar.gz: d9b6f3d18c731b4ddfe1060a03a40310e4d58b940d1f00f97dd3ef480f22dd74
 SHA512:
-  metadata.gz: 34f253c3bfcf4a7702348287da3a3e8c2458dbc818d20a73849e1b14574b9d7b38767113dd099ea065142d80e1415669813ca54199e9d61326452a6daf6f6b04
-  data.tar.gz: 80df40a51028efe1926961e2c556a8fab8a46d28757f28360ef12d258003fbdaea031ea2933690e07a33f7729f6e165cea4db33a5491722d44eaa8e7d323498e
+  metadata.gz: 89f8f34ae2184fab2069c8a0d51eaf53936dcb69e538e2fd7c0f659900e1be6ea3ee2f43101726ecb25bcd933a77beb20b2b954af4facbbfb248f4f0e40ae914
+  data.tar.gz: b63afbb5f6755e1821f268d0a797fc1d1f12d97148f790aa340ad0ec55bdf86df91ee649d003caaabe33351e91a25f848217fd6e26da09c3cf6dcc136b173d15

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`**,
@@ -144,10 +151,14 @@ Last updated: 2026-05-12 (after L1 ships).
 - **Echo `request_id`** in the response body or `X-Request-ID` header,
   for support correlation. Today the CLI can't give a customer a request
   ID to ship to support.
-- **Real location/site filter on events.** `Event.location` is free-text
-  and not in `ransackable_attributes`. WIQ team has flagged a structured
-  location concept as roadmap. Until then the CLI deliberately exposes
-  no `--site` flag.
+- ~~**Real location/site filter on events.**~~ — SHIPPED (June 2026,
+  wre-506). The backend grew a structured Location model. The CLI now
+  exposes `wiq locations list|show` plus `--location` flags on
+  `events list` (repeatable → `location_ids[]`), `rosters list`
+  (`q[location_id_eq]`), `paid_sessions list`, `wrestlers list`,
+  `metrics show`, and `reports run` (args.location_id, honored by 13
+  report types). The legacy free-text `Event.location` remains for old
+  rows; serialized `location` is the display form.
 - **Subdomain discovery flow for `wiq auth login`.** PAT settings URL
   lives at `<team-subdomain>.wrestlingiq.com/settings/personal_access_tokens`.
   If a customer doesn't know their subdomain, the CLI can't deep-link

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.
@@ -468,13 +522,16 @@ Other registration surface:
 - `expand=event_invites,event_bookings,private_lessons` — comma-separated
   CSV; pulls in nested data on the events index/show.
 - `Event.ransackable_attributes` allows
-  `id, name, start_at, end_at, event_type, paid_session_id`. **`location`
-  is not ransackable today.** A real location filter is on the WIQ
-  backend roadmap (it will replace the free-text `location` column with a
-  structured concept); until that ships the CLI doesn't expose a
-  location/site flag. Users who need it can fetch the date range, write
-  the results to a file, and post-process — that's not the CLI's problem
-  to solve in v1.
+  `id, name, start_at, end_at, event_type, paid_session_id`. The
+  free-text `location` column is still not ransackable, but the
+  structured location filter shipped (June 2026): pass `location_ids[]`
+  (repeatable, dedicated param handled in `apply_event_filters`, not
+  Ransack) to filter on the event's `location_id`. Events with no
+  `location_id` are excluded from a filtered listing. The serialized
+  `location` field is now `Event#display_location` — the structured
+  Location's name when set, else the legacy free text — and `location_id`
+  is serialized alongside it. The CLI exposes this as
+  `wiq events list --location <id> [<id>...]`.
 - Soft deletes: events use `acts_as_paranoid`; the index calls
   `.without_deleted`. No "include deleted" param exposed.
 - `POST /api/v1/events` — recurring practice creation:
@@ -642,9 +699,12 @@ PaidSession-overlap convention proves load-bearing for many customers.
    demand. Until then, jbuilders are the source of truth.
 2. `request_id` echoed in response body and/or `X-Request-ID` header for
    support correlation.
-3. Real location/site filter on `GET /api/v1/events` (when the backend
-   gets a structured location concept). Until then the CLI doesn't expose
-   a flag.
+3. ~~Real location/site filter on `GET /api/v1/events`~~ — SHIPPED
+   (June 2026, wre-506). Structured Location model + `location_ids[]` on
+   events, `location_id` on paid_sessions/wrestlers/metrics/reports,
+   `q[location_id_eq]` on rosters, and a `GET /api/v1/locations`
+   resource. All exposed in the CLI via `wiq locations` and `--location`
+   flags.
 4. Subdomain discovery for `wiq auth login`. The PAT settings URL lives at
    `<team-subdomain>.wrestlingiq.com/settings/personal_access_tokens`; if
    the customer doesn't know their subdomain, the CLI can't deep-link

data/lib/wiq/cli.rb

@@ -65,6 +65,9 @@ module Wiq
     desc "rosters SUBCOMMAND", "Rosters (list, show)"
     subcommand "rosters", Wiq::Commands::Rosters
 
+    desc "locations SUBCOMMAND", "Team locations / sites — ID discovery for --location flags (list, show)"
+    subcommand "locations", Wiq::Commands::Locations
+
     desc "prospects SUBCOMMAND", "Prospect pipeline — individual kids (list, show, summary)"
     subcommand "prospects", Wiq::Commands::Prospects
 
@@ -80,6 +83,9 @@ 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
 

data/lib/wiq/commands/events.rb

@@ -25,18 +25,25 @@ module Wiq
           --event-type     One of `wiq events types` (practice, dual_meet, ...)
           --roster         One or more roster ids (the API joins through
                            roster_events)
+          --location       One or more location ids (structured Location
+                           records; discover via `wiq locations list`)
           --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.
+        Location caveat: --location matches the event's own structured
+        location_id. Events with NO location set are excluded from a
+        filtered listing — they only appear when you don't filter. The
+        legacy free-text `location` field still exists on old events; the
+        serialized `location` value is the display form (structured record
+        when set, else the free text).
 
         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 :location, type: :array,
+                               desc: "One or more location ids (events with no location are excluded)"
       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,
@@ -53,6 +60,9 @@ module Wiq
         if options[:roster]
           options[:roster].each { |rid| (params["roster_ids[]"] ||= []) << rid }
         end
+        if options[:location]
+          options[:location].each { |lid| (params["location_ids[]"] ||= []) << lid }
+        end
 
         records, total = fetch_index("/api/v1/events", params, key: "events")
         render_index(

data/lib/wiq/commands/locations.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class Locations < Base
+      desc "list", "List the team's structured locations (sites/gyms)"
+      long_desc <<~DESC
+        Locations are WIQ's structured multi-site concept — a named place
+        (with optional street address) that rosters, events, paid sessions,
+        wrestlers, metrics, and reports can be scoped to. Single-site clubs
+        typically have zero or one; multi-site clubs use them to slice
+        everything per gym.
+
+        Archived locations are hidden by default; pass --include-archived
+        to see them. Ordered by name server-side.
+
+        This is the ID-discovery surface for every --location flag in the
+        CLI:
+          wiq rosters list --location <id>
+          wiq events list --location <id> [...more ids]
+          wiq wrestlers list --location <id>
+          wiq paid_sessions list --location <id>
+          wiq metrics show <name> --location <id>
+          wiq reports run <Type> --location <id>
+      DESC
+      method_option :include_archived, type: :boolean, default: false,
+                                       desc: "Include archived locations"
+      method_option :all, type: :boolean, default: false
+      def list
+        params = { "per_page" => 100 }
+        params["include_archived"] = true if options[:include_archived]
+
+        records, total = fetch_index("/api/v1/locations", params, key: "locations")
+        render_index(
+          records, total: total,
+          summary: "Listed #{records.size} locations#{options[:include_archived] ? " (including archived)" : ""}.",
+          breadcrumbs: [
+            { "cmd" => "wiq locations show <id>", "description" => "Inspect a single location" },
+            { "cmd" => "wiq rosters list --location <id>", "description" => "Rosters at a location" },
+            { "cmd" => "wiq metrics show mrr --location <id>",
+              "description" => "Finance metrics scoped to a location (admin only)" }
+          ]
+        )
+      end
+
+      desc "show ID", "Fetch a single location"
+      long_desc <<~DESC
+        Full location payload: id, name, address_line1, address_line2,
+        city, state, postal_code, country, archived.
+      DESC
+      def show(id)
+        location = client.get("/api/v1/locations/#{id}")
+        render(location,
+               summary: "Location #{location["id"]} — #{location["name"]}",
+               breadcrumbs: [
+                 { "cmd" => "wiq rosters list --location #{location["id"]}",
+                   "description" => "Rosters at this location" },
+                 { "cmd" => "wiq wrestlers list --location #{location["id"]}",
+                   "description" => "Wrestlers on any roster at this location" }
+               ])
+      end
+    end
+  end
+end

data/lib/wiq/commands/metrics.rb

@@ -62,6 +62,13 @@ module Wiq
         Intervals: hourly, daily, weekly, monthly. Invalid values are
         silently coerced to `daily` server-side.
 
+        --location <id> scopes every metric to one structured location
+        (discover ids via `wiq locations list`). CAUTION: the server
+        validates the id against the team's own locations and silently
+        falls back to ALL locations when it doesn't match — a typo'd or
+        foreign id returns team-wide numbers, not an error. The CLI echoes
+        the requested location in `meta` so you can sanity-check.
+
         Currency metrics return integer cents (divide by 100 for dollars).
         Non-currency metrics return raw counts.
       DESC
@@ -70,6 +77,8 @@ module Wiq
                                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 :location, type: :numeric,
+                               desc: "Scope to one location id (unknown ids silently mean ALL locations)"
       method_option :no_comparison, type: :boolean, default: false,
                                     desc: "Drop comparison_series/comparison_total from output"
       def show(name)
@@ -91,6 +100,7 @@ module Wiq
           params["start_date"] = options[:start_date]
           params["end_date"] = options[:end_date]
         end
+        params["location_id"] = options[:location] if options[:location]
 
         payload = client.get("/api/v1/metrics/#{name}", params)
         metrics = payload["metrics"] || {}
@@ -106,9 +116,13 @@ module Wiq
           data["comparison_total"] = metrics["comparison_total"]
         end
 
+        meta = { "currency_unit" => CURRENCY_METRICS.include?(name) ? "cents" : "count" }
+        meta["location_id"] = options[:location] if options[:location]
+
         render(data,
-               summary: "metric=#{name} range=#{options[:range]} interval=#{options[:interval]}",
-               meta: { "currency_unit" => CURRENCY_METRICS.include?(name) ? "cents" : "count" },
+               summary: "metric=#{name} range=#{options[:range]} interval=#{options[:interval]}" \
+                        "#{options[:location] ? " location=#{options[:location]}" : ""}",
+               meta: meta,
                breadcrumbs: [
                  { "cmd" => "wiq metrics list", "description" => "See all supported metrics" }
                ])

data/lib/wiq/commands/paid_sessions.rb

@@ -20,6 +20,10 @@ module Wiq
           recurring_registerable, not_recurring, not_recurring_with_archived,
           not_archived, dropin, trial, trial_or_dropin
 
+        --location <id> filters server-side to sessions stamped with that
+        structured location (discover ids via `wiq locations list`).
+        Sessions with no location are excluded when the filter is on.
+
         --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.
@@ -30,11 +34,13 @@ module Wiq
         you usually don't need a follow-up call.
       DESC
       method_option :type, type: :string, enum: PRESET_TYPES, desc: "Preset scope filter"
+      method_option :location, type: :numeric, desc: "Filter to sessions at one location id"
       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]
+        params["location_id"] = options[:location] if options[:location]
 
         records, total = fetch_index("/api/v1/paid_sessions", params, key: "paid_sessions")
 

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/reports.rb

@@ -26,7 +26,7 @@ module Wiq
       TYPES = {
         # ── Roster tab ───────────────────────────────────────────────
         "RosterReport" => {
-          args: %w[roster_id append_property_ids include_archived_roster_tags],
+          args: %w[roster_id location_id append_property_ids include_archived_roster_tags],
           dates: :optional,
           desc: "Roster snapshot — name, weight class, academic class, age",
           recommended: true,
@@ -41,8 +41,11 @@ module Wiq
                  "to roster at\" column (roster_memberships.created_at — when the " \
                  "wrestler landed on the roster, NOT their registration date), " \
                  "populated only for a specific --roster <id> (id > 0), not " \
-                 "--roster 0. --v1 returns fuller per-wrestler objects but drops " \
-                 "that column.",
+                 "--roster 0. With --location <id> instead, the report scopes to " \
+                 "wrestlers on any roster at that location (one row each) and " \
+                 "\"Added to roster at\" becomes their EARLIEST membership across " \
+                 "that location's rosters. --v1 returns fuller per-wrestler " \
+                 "objects but drops that column.",
           example: "wiq reports run RosterReport --roster 42"
         },
         "FullExportWrestlerReport" => {
@@ -67,52 +70,52 @@ module Wiq
 
         # ── USAW / AAU tab ───────────────────────────────────────────
         "UsawReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :optional,
           desc: "All USA Wrestling card info on file, one row per wrestler",
           recommended: true,
           notes: "UI hides this tab when USAW collection is off (team setting)."
         },
         "UsawExpiredReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :optional,
           desc: "Wrestlers missing or with expired USAW memberships",
           notes: "Output is also a bulk-purchase upload format for USAW's system."
         },
         "UsawExportReport" => {
-          args: %w[roster_id paid_session_id],
+          args: %w[roster_id location_id paid_session_id],
           dates: :optional,
           desc: "USAW bulk-purchase upload format",
           notes: "Only report that accepts paid_session_id=0 to mean " \
                  "\"all sessions\"."
         },
         "AauReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :optional,
           desc: "All AAU card info on file, one row per wrestler",
           recommended: true,
           notes: "UI hides this tab when AAU collection is off (team setting)."
         },
         "AauExpiredReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :optional,
           desc: "Wrestlers missing or with expired AAU memberships"
         },
         "AauExportReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :optional,
           desc: "AAU bulk-purchase upload format"
         },
 
         # ── Stats tab ────────────────────────────────────────────────
         "WinLossReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :required,
           desc: "Wins and losses per wrestler",
           recommended: true
         },
         "RosterStatsReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :required,
           desc: "Wrestling stats per wrestler (takedowns, nearfall, etc.)",
           recommended: true
@@ -133,8 +136,10 @@ module Wiq
           recommended: true,
           notes: "One row per wrestler over the date range — totals across all " \
                  "their check-ins in the window. If you want one row per " \
-                 "check-in event use CheckInFeedReport. The UI doesn't expose " \
-                 "a roster picker; counts span the whole team.",
+                 "check-in event use CheckInFeedReport. Always team-wide: the " \
+                 "model ignores roster_id AND location_id args. For a " \
+                 "location-scoped attendance report use CheckInReport " \
+                 "--location <id> instead.",
           example: "wiq reports run CheckInSummaryReport --start 2026-05-01 --end 2026-05-31"
         },
         "CheckInFeedReport" => {
@@ -144,11 +149,12 @@ module Wiq
           recommended: true,
           notes: "Useful for \"who came to the club today and what registrations " \
                  "did they have at check-in time.\" Larger payload than the " \
-                 "summary.",
+                 "summary. Always team-wide: the model ignores roster_id AND " \
+                 "location_id args.",
           example: "wiq reports run CheckInFeedReport --start 2026-05-01 --end 2026-05-31"
         },
         "PracticeAttendanceReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :required,
           desc: "Practice-event attendance roll-up across a date range",
           recommended: false,
@@ -159,7 +165,7 @@ module Wiq
                  "use CheckInSummaryReport or CheckInFeedReport instead."
         },
         "LastPracticeAttendedReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :optional,
           desc: "Days since last practice attended, per wrestler",
           recommended: true,
@@ -167,7 +173,7 @@ module Wiq
                  "practice in a while — particularly for seasonal clubs."
         },
         "ChurnRiskReport" => {
-          args: %w[roster_id days_threshold],
+          args: %w[roster_id location_id days_threshold],
           dates: :optional,
           desc: "Active recurring subscribers who haven't checked in within a window",
           recommended: true,
@@ -178,7 +184,7 @@ module Wiq
           example: "wiq reports run ChurnRiskReport --roster 0 --days-threshold 30"
         },
         "CheckInReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :required,
           desc: "Extended attendance — one row per check-in INCLUDING Q&A responses",
           notes: "UI labels this \"Attendance Extended (with questions).\" Same " \
@@ -333,6 +339,14 @@ module Wiq
         Common args (only those documented in TYPES are honored
         server-side):
           --roster <id>            roster_id (0 = all rosters)
+          --location <id>          location_id — scope the wrestler set to
+                                   one location (wrestlers on ANY roster at
+                                   that location, deduped to one row each).
+                                   Precedence: a specific --roster <id> (> 0)
+                                   WINS over --location; pass --location
+                                   alone (or with --roster 0) to get
+                                   location scoping. Discover ids via
+                                   `wiq locations list`.
           --paid-session <id>      paid_session_id (0 = all, UsawExport only)
           --event <id>             event_id (EventStatsReport)
           --fundraiser <id>        fundraiser_id (Fundraiser* reports)
@@ -369,6 +383,9 @@ module Wiq
       method_option :start, type: :string, desc: "YYYY-MM-DD"
       method_option :end, type: :string, desc: "YYYY-MM-DD"
       method_option :roster, type: :numeric, desc: "args.roster_id (0 = all rosters)"
+      method_option :location, type: :numeric,
+                               desc: "args.location_id — scope wrestlers to one location " \
+                                     "(a specific --roster <id> > 0 takes precedence)"
       method_option :paid_session, type: :numeric, desc: "args.paid_session_id"
       method_option :event, type: :numeric, desc: "args.event_id"
       method_option :fundraiser, type: :numeric, desc: "args.fundraiser_id"
@@ -529,6 +546,7 @@ module Wiq
 
           args = {}
           args["roster_id"] = options[:roster] if options[:roster] || options[:roster] == 0
+          args["location_id"] = options[:location] if options[:location]
           args["paid_session_id"] = options[:paid_session] if options[:paid_session] || options[:paid_session] == 0
           args["event_id"] = options[:event] if options[:event]
           args["fundraiser_id"] = options[:fundraiser] if options[:fundraiser]

data/lib/wiq/commands/rosters.rb

@@ -17,12 +17,19 @@ module Wiq
                                 exact name. Some teams tag rosters with
                                 conventions like "2025-26".
 
+        --location <id> filters server-side (Ransack q[location_id_eq]) to
+        rosters stamped with that structured location. Discover ids via
+        `wiq locations list`. Rosters with no location are excluded when
+        the filter is on. Each roster row embeds its location object (or
+        null) so you can also group client-side without the filter.
+
         Each roster row embeds roster_syncers and taggings, which is what
         --season uses to filter without needing extra calls.
       DESC
       method_option :season, type: :numeric,
                              desc: "Filter to rosters whose syncers point at paid sessions overlapping this year"
       method_option :season_tag, type: :string, desc: "Filter to rosters carrying this tag"
+      method_option :location, type: :numeric, desc: "Filter to rosters at one location id"
       method_option :archived, type: :boolean, desc: "Show only archived (true) or active (false)"
       method_option :all, type: :boolean, default: false
       def list
@@ -30,6 +37,7 @@ module Wiq
         unless options[:archived].nil?
           params["q[archived_eq]"] = options[:archived]
         end
+        params["q[location_id_eq]"] = options[:location] if options[:location]
 
         records, total = fetch_index("/api/v1/rosters", params, key: "rosters")
 

data/lib/wiq/commands/wrestlers.rb

@@ -20,6 +20,10 @@ module Wiq
           --first-name         q[first_name_cont]
           --last-name          q[last_name_cont]
           --roster <id>        q[rosters_id_eq] — filter to one roster
+          --location <id>      location_id (dedicated param, not Ransack) —
+                               wrestlers on ANY roster at that location.
+                               Composes with the other filters. Discover
+                               ids via `wiq locations list`.
           --weight-class       q[weight_class_numeric_eq] — exact numeric
           --academic-class     q[academic_class_eq] (senior, junior, …)
           --age                q[age_eq]
@@ -31,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
@@ -43,6 +53,8 @@ module Wiq
       method_option :first_name, type: :string, desc: "First name (contains)"
       method_option :last_name, type: :string, desc: "Last name (contains)"
       method_option :roster, type: :numeric, desc: "Filter to a single roster id"
+      method_option :location, type: :numeric,
+                               desc: "Filter to wrestlers on any roster at this location id"
       method_option :weight_class, type: :string,
                                    desc: "Weight class (exact numeric, e.g. 132)"
       method_option :academic_class, type: :string,
@@ -52,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
@@ -78,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"]}",
@@ -107,12 +125,14 @@ module Wiq
           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["q[rosters_id_eq]"] = options[:roster] if options[:roster]
+          params["location_id"] = options[:location] if options[:location]
           params["q[weight_class_numeric_eq]"] = options[:weight_class] if options[:weight_class]
           params["q[academic_class_eq]"] = options[:academic_class] if options[:academic_class]
           params["q[age_eq]"] = options[:age] if options[:age]
           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
 
@@ -130,6 +150,7 @@ module Wiq
           bits = []
           bits << "matching #{options[:query].inspect}" if options[:query]
           bits << "in roster #{options[:roster]}" if options[:roster]
+          bits << "at location #{options[:location]}" if options[:location]
           bits << "weight class #{options[:weight_class]}" if options[:weight_class]
           bits << "profile_type=#{options[:profile_type]}" if profile_type_filter? && options[:profile_type] != "teammate"
           bits.empty? ? "" : " (#{bits.join(", ")})"

data/lib/wiq/version.rb

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

data/lib/wiq.rb

@@ -20,11 +20,13 @@ require "wiq/commands/registrations"
 require "wiq/commands/metrics"
 require "wiq/commands/events"
 require "wiq/commands/rosters"
+require "wiq/commands/locations"
 require "wiq/commands/prospects"
 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/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, or online store orders. 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?", 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, 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
@@ -223,9 +223,14 @@ join date is in the default output.
   resolves to paid_session ids whose date range overlaps the calendar
   year, then filters client-side. There's no first-class Season entity
   in WIQ.
-- **`Event.location` is free-text and not filterable.** No `--site` or
-  `--location` flag exists yet. A structured location concept is on the
-  WIQ roadmap.
+- **Legacy free-text `Event.location` vs structured locations.** Old
+  events carry a free-text `location` string; the serialized `location`
+  field is the display form (structured Location name/address when
+  `location_id` is set, else the legacy text). `--location` filters only
+  match the structured `location_id` — events, rosters, and paid sessions
+  with NO location set are excluded from filtered listings, so an empty
+  filtered result doesn't mean "nothing happened", it may mean "nothing
+  is stamped with that location yet."
 - **Index responses are wrapped.** Every `/api/v1` index returns
   `{"<resource>": [...]}` — the CLI unwraps internally, but if you ever
   hit the API directly remember to unwrap.
@@ -338,13 +343,77 @@ 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).
+Multi-gym clubs stamp rosters, events, and paid sessions with a
+location; single-site clubs usually have none, and every `--location`
+flag is simply irrelevant for them.
+
+Discover ids first — this is the anchor for everything below:
+
+```bash
+wiq locations list                     # id, name, address, archived
+wiq locations list --include-archived
+```
+
+Then scope any of these surfaces:
+
+| Command | Flag | Semantics |
+| --- | --- | --- |
+| `wiq rosters list` | `--location <id>` | Rosters stamped with that location (`q[location_id_eq]`) |
+| `wiq events list` | `--location <id> [<id>...]` | Events at those locations (repeatable; unset-location events excluded) |
+| `wiq paid_sessions list` | `--location <id>` | Sessions stamped with that location |
+| `wiq wrestlers list` | `--location <id>` | Wrestlers on ANY roster at that location; composes with other filters |
+| `wiq metrics show <name>` | `--location <id>` | Per-location finance metrics (the payment-dashboard filter) |
+| `wiq reports run <Type>` | `--location <id>` | Scopes the wrestler set for the 13 location-aware report types |
+
+Three gotchas an agent must know:
+
+1. **Reports precedence:** a specific `--roster <id>` (> 0) WINS over
+   `--location` in report args. Pass `--location` alone (or with
+   `--roster 0`) to get location scoping. A wrestler on multiple rosters
+   at the location collapses to one row; RosterReport's "Added to roster
+   at" becomes their EARLIEST membership across that location's rosters.
+   `CheckInSummaryReport` / `CheckInFeedReport` ignore both args
+   entirely (always team-wide) — use `CheckInReport --location <id>` for
+   location-scoped attendance.
+2. **Metrics fail silent, not loud:** an unknown or foreign `--location`
+   id on `wiq metrics show` silently falls back to ALL locations —
+   team-wide numbers, no error. Verify the id against
+   `wiq locations list` before quoting per-site revenue to the user.
+3. **Nothing is auto-stamped retroactively.** Filters only match records
+   whose `location_id` is set. Empty filtered results on a club that
+   just adopted locations usually mean unstamped data, not zero
+   activity. Rosters/events/paid_sessions embed their `location` object
+   (or null) in list payloads, so you can check coverage cheaply.
+
 ## What's NOT available (yet)
 
 The CLI is read-only by design except for report submission. You
 cannot via this CLI:
 
 - Create/edit prospects, families, notes, check-ins, events, paid
-  sessions, rosters, or any other resource
+  sessions, rosters, locations, or any other resource
 - Mint, list, or revoke PATs (use the web UI at
   `<host>/settings/personal_access_tokens`)
 - Mark attendance, advance prospect stages, log contact notes

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wiq-cli
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - WrestlingIQ
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-29 00:00:00.000000000 Z
+date: 2026-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -90,8 +90,10 @@ files:
 - lib/wiq/commands/check_ins.rb
 - lib/wiq/commands/doctor.rb
 - lib/wiq/commands/events.rb
+- lib/wiq/commands/locations.rb
 - lib/wiq/commands/metrics.rb
 - lib/wiq/commands/paid_sessions.rb
+- lib/wiq/commands/parents.rb
 - lib/wiq/commands/prospect_families.rb
 - lib/wiq/commands/prospects.rb
 - lib/wiq/commands/registrations.rb