wiq-cli 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cac3732fa4c286907bce03d6ac62765477d828507719a29074873a9f9b90bde2
-  data.tar.gz: c686b4e1fb901e6554727c7030eb63d66cd70f659ca95345db2124b0ec6c9138
+  metadata.gz: b8732206776c88ba1c9d5630407e3a7a4ba6386e528cb5a7a36b2b7c8bcda3dc
+  data.tar.gz: 499116e3d7977c22e0f44759ea59406c49265e865def76300353de0052dbf5b0
 SHA512:
-  metadata.gz: 970cfd866b44f27e8be608f8ddb40b147521bc241557637e545b21e23ec490d6e5a6ca8b6252b9f1c5f5a0ece7d1ad4a12f6457b80e1131c0beef691a5e65a3d
-  data.tar.gz: 22e94b802d4b4209c32131919733b68937775515a0b089ce764c1496758b281562e5532b708258351bac66c78f2db138eaefa9b55987dcb68671112ef2272ca5
+  metadata.gz: 34f253c3bfcf4a7702348287da3a3e8c2458dbc818d20a73849e1b14574b9d7b38767113dd099ea065142d80e1415669813ca54199e9d61326452a6daf6f6b04
+  data.tar.gz: 80df40a51028efe1926961e2c556a8fab8a46d28757f28360ef12d258003fbdaea031ea2933690e07a33f7729f6e165cea4db33a5491722d44eaa8e7d323498e

data/docs/wiq_api_notes.md

@@ -246,6 +246,29 @@ file with the WIQ team.
 
 - `POST /api/v1/reports`
   - Body: `{ "report": { "type": "<ReportClass>", "version": "v1"|"vrow", "name": "...", "start_at": "YYYY-MM-DD", "end_at": "YYYY-MM-DD", "args": { ... } } }`
+  - **`version` — v1 vs vrow.** `:version` is in the controller permit
+    list (`reports_controller.rb#report_params`). Despite both being
+    accepted everywhere, version only changes output for three reports —
+    `RosterReport`, `UsawReport`, `PaidSessionAccountingReport` — which
+    branch in `generate_ver_result!` (`v1?` → structured JSON objects,
+    `vrow?` → row/CSV with a leading header row). All three implement
+    both; no report is v1-only. Every other report overrides
+    `generate_ver_result!` and emits rows regardless of version. vrow is
+    the de facto standard, so the CLI defaults to it (uniform row shape
+    across all reports) and exposes the legacy structured shape via
+    `wiq reports run … --v1`.
+  - **`RosterReport` "Added to roster at" lives only in vrow.** The vrow
+    path calls `get_wrestlers_and_roster(include_roster_memberships: true)`
+    (`report.rb`), which `.select`s
+    `roster_memberships.created_at as added_to_roster_at` and emits it as
+    the `"Added to roster at"` column. The v1 path renders wrestlers via
+    `_wrestler_profile.json.jbuilder`, which has no such field. The join
+    only happens for a specific roster (`roster_id > 0`); `roster_id: 0`
+    ("all wrestlers") takes the else branch and the value is nil — a
+    wrestler can be on multiple rosters, so the join date is per-roster.
+    The roster index/show jbuilder (`_roster.json.jbuilder`) exposes only
+    `stats.roster_memberships_count`, never per-membership timestamps, so
+    vrow RosterReport is the sole API path to this data.
   - Permitted `args` keys (`reports_controller.rb#report_params`):
     `paid_session_id, roster_id, fundraiser_id, online_store_id, event_id,
     include_archived_roster_tags, append_property_ids[]`.

data/lib/wiq/commands/reports.rb

@@ -36,8 +36,14 @@ module Wiq
                  "--visibility private if admin) to surface intake data as " \
                  "extra columns. Skip questions with a deleted_at — they're " \
                  "still in the index payload but won't render. roster_id=0 " \
-                 "means \"all rosters\". Each appended question becomes a column.",
-          example: "wiq reports run RosterReport --roster 42 --append-properties 17 23"
+                 "means \"all rosters\". Each appended question becomes a column. " \
+                 "The default row/CSV shape (web Download) carries the \"Added " \
+                 "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.",
+          example: "wiq reports run RosterReport --roster 42"
         },
         "FullExportWrestlerReport" => {
           args: %w[],
@@ -341,6 +347,24 @@ module Wiq
         cap, default 5-minute timeout. Pass --no-wait to return the
         report row immediately after submission (status=queued or
         processing) and poll later with `wiq reports show <id> --wait`.
+
+        Result shape (vrow default / --v1):
+          The CLI requests the row/CSV shape (version "vrow") by default —
+          `result.rows.objects` with the first row being the headers, the
+          exact layout behind the "Download" buttons in the WIQ web UI.
+          Most reports emit only this shape and ignore the version.
+
+          For RosterReport, vrow is the ONLY shape carrying the "Added to
+          roster at" column (roster_memberships.created_at — when a
+          wrestler landed on that roster, distinct from their registration
+          date). That column is populated only for a specific roster: pass
+          --roster <id> with id > 0, NOT --roster 0 ("all wrestlers"),
+          since a wrestler can sit on multiple rosters.
+
+          Pass --v1 for the legacy structured-JSON shape. Only
+          RosterReport, UsawReport, and PaidSessionAccountingReport differ
+          under it (fuller per-wrestler objects); for those reports v1
+          drops the "Added to roster at" column.
       DESC
       method_option :start, type: :string, desc: "YYYY-MM-DD"
       method_option :end, type: :string, desc: "YYYY-MM-DD"
@@ -358,6 +382,11 @@ module Wiq
                                      desc: "args.days_threshold (ChurnRiskReport)"
       method_option :name, type: :string, desc: "Display name (default: CLI <type> <range>)"
       method_option :season, type: :numeric, desc: "Resolve to paid_session_id via overlap with calendar year"
+      method_option :v1, type: :boolean, default: false,
+                         desc: "Request the legacy v1 structured-JSON shape instead of the default " \
+                               "row/CSV (vrow). Only RosterReport/UsawReport/PaidSessionAccountingReport " \
+                               "differ; v1 returns fuller per-wrestler objects but drops RosterReport's " \
+                               "\"Added to roster at\" column."
       method_option :wait, type: :boolean, default: true
       method_option :timeout, type: :numeric, default: 300
       map "run" => :run_report
@@ -367,7 +396,7 @@ module Wiq
         body = {
           report: {
             type: type,
-            version: "v1",
+            version: report_version,
             name: options[:name] || default_name(type),
             start_at: options[:start],
             end_at: options[:end],
@@ -469,6 +498,18 @@ module Wiq
       end
 
       no_commands do
+        # The API recognizes two report versions: "vrow" (the row/CSV shape
+        # behind the web Download buttons) and "v1" (legacy structured JSON).
+        # Only RosterReport/UsawReport/PaidSessionAccountingReport branch on
+        # it; every other report emits rows regardless. vrow is the de facto
+        # standard and is the only shape carrying RosterReport's "Added to
+        # roster at" column, so the CLI defaults to it for a uniform surface.
+        # --v1 is an escape hatch to the fuller structured objects on those
+        # three reports.
+        def report_version
+          options[:v1] ? "v1" : "vrow"
+        end
+
         def build_args(type)
           if options[:season]
             resolver = Wiq::SeasonResolver.new(client)

data/lib/wiq/version.rb

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

data/share/skills/wiq/SKILL.md

@@ -172,6 +172,11 @@ Key reports an agent should know by heart:
   within N days (7, 14, 30, 60, 90). Requires `--days-threshold`.
 - **`RosterReport`** — Roster snapshot with optional custom columns via
   `--append-properties <q_ids>`. Discover ids via `wiq registrations questions`.
+  The default (row/CSV) shape carries the **"Added to roster at"** column
+  (`roster_memberships.created_at` — when a wrestler landed on that roster,
+  NOT their registration date). Requires a specific `--roster <id>` (id > 0);
+  it's blank for `--roster 0`. `--v1` returns fuller per-wrestler objects but
+  drops that column.
 - **`LastPracticeAttendedReport`** — "Who hasn't been to practice in a
   while?"
 - **`PaidSessionAccountingReport`** (admin_only) — Line-item charges for
@@ -194,6 +199,18 @@ wiq reports run <Type> --start <date> --end <date> [args]
 processing → ready` (terminal) | `failed` (terminal). `result` is the
 type-specific jsonb payload.
 
+**Result shape — vrow default (`--v1` escape hatch).** The CLI requests
+the row/CSV shape (`version: "vrow"`) by default: `result.rows.objects`
+with the first row being the header — identical to the web "Download"
+buttons, and a uniform shape across every report type. Most reports emit
+only this shape and ignore the version. Only `RosterReport`, `UsawReport`,
+and `PaidSessionAccountingReport` also support a legacy v1 shape
+(structured JSON objects) via `--v1`, which returns fuller per-wrestler
+data but drops RosterReport's **"Added to roster at"** column. If a user
+asks when a wrestler joined a roster (e.g. roster-join → first-practice
+latency), `wiq reports run RosterReport --roster <id>` is the answer — the
+join date is in the default output.
+
 ## Common gotchas
 
 - **`roster_id=0` = "all rosters"** in report args. UI convention; if

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wiq-cli
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - WrestlingIQ
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-22 00:00:00.000000000 Z
+date: 2026-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor