wiq-cli 0.4.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee99cfc6ad08abdf7e1318883bcfa3ecc45635d2d521de150ed1622d867b0ebc
-  data.tar.gz: d9b6f3d18c731b4ddfe1060a03a40310e4d58b940d1f00f97dd3ef480f22dd74
+  metadata.gz: ec283a11b87c6ba8e2f8db5bf5a56f5e02fbf092aa3fb93fab54d08660553aa3
+  data.tar.gz: 1afd0ade5f5de6770c74acdd5d3fb0f2c68721f1537b0344a2ab6a401f32a400
 SHA512:
-  metadata.gz: 89f8f34ae2184fab2069c8a0d51eaf53936dcb69e538e2fd7c0f659900e1be6ea3ee2f43101726ecb25bcd933a77beb20b2b954af4facbbfb248f4f0e40ae914
-  data.tar.gz: b63afbb5f6755e1821f268d0a797fc1d1f12d97148f790aa340ad0ec55bdf86df91ee649d003caaabe33351e91a25f848217fd6e26da09c3cf6dcc136b173d15
+  metadata.gz: 93172776f6f73aac7093aa64b04bade0de00cc633f6b8e17b6a4c3a7898c3b8148fc98b9ccb108ab22df639b2e56c26b167e6f85ed22013cadd444f4d1fac574
+  data.tar.gz: 075e0ab62fb1098c04a0a7714825eef7ea0b8ad450e1d21703cbf2fe6c60b8d58f8ca2d2616ba6b8ead65ec9237db681737408476692aab9b0443847637d2ebc

data/README.md

@@ -7,9 +7,10 @@
 > recommended for production-critical automation. Pin your gem version
 > if you build anything load-bearing on top of it.
 
-Read-only command-line interface for [WrestlingIQ](https://www.wrestlingiq.com).
+Command-line interface for [WrestlingIQ](https://www.wrestlingiq.com).
 Designed to be driven by both humans and AI agents (Claude Code, Cursor,
-etc.) via per-user personal access tokens (PATs).
+etc.) via per-user personal access tokens (PATs). Every token can read;
+tokens minted with a write scope can also work the leads pipeline.
 
 ## Getting started
 
@@ -39,6 +40,13 @@ coach, your CLI will be able to run admin reports; if you're not, it
 won't. Either way, the token can be revoked anytime from the same
 page.
 
+Tokens are read-only unless you tick a write permission when minting
+one. Today that's **Create and edit leads** (`prospects:write`) and
+**Create reports** (`reports:write`). A team admin has to enable each
+capability for the club first under **Settings → API Access**; the
+token picker only offers what the team allows. Scopes are fixed for the
+life of a token — to change them, revoke it and mint a new one.
+
 ### 3. Log in
 
 ```bash
@@ -81,6 +89,7 @@ Now you can ask Claude things like:
 ```bash
 wiq rosters list                                            # Browse rosters
 wiq prospects summary                                       # Pipeline dashboard
+wiq prospects advance 123 trial_scheduled                   # Move a lead forward (needs prospects:write)
 wiq events list --start 2026-05-01 --end 2026-05-31         # Calendar
 wiq workflows list                                          # Curated multi-step recipes
 wiq reports types                                           # 36 report types w/ recommendations
@@ -135,9 +144,11 @@ output (the CLI never logs your token — paste the full JSON safely).
 
 ## Status
 
-v0.1.0 — 29 commands across 16 groups, 117 RSpec smoke examples.
-Reads-only except for report submission (the API's canonical async
-pattern). Write commands deferred — see `docs/deferred.md`.
+v0.6.1 — reads across every group, plus report submission and a
+scoped write surface for the prospects pipeline (`prospect_families
+create/update/note`, `prospects create/update/advance`) gated by the
+`prospects:write` token scope. Other write commands deferred — see
+`docs/deferred.md`.
 
 ## License
 

data/docs/deferred.md

@@ -81,17 +81,14 @@ Last updated: 2026-05-12 (after L1 ships).
 - **`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`**,
-  etc. — every write path on every resource. v1 is reads-only except
-  report submission. Cherry-pick as customers ask.
-- **Prospect write commands.** API supports `POST /prospect_families`,
-  `PATCH /prospect_families/:id` (incl. assigned_coach), `DELETE`,
-  `POST /prospect_families/:id/prospects`, `PATCH /prospects/:id`
-  (incl. stage transitions via `advance_to!`), and
-  `POST /prospect_families/:id/notes` (with `clear_follow_up_for[]` /
-  `add_follow_up_for[]` side-effect params). Reads-only in v1 — most
-  pipeline edits happen in the drawer UI today, and exposing
-  stage-transition writes without first watching agents use them is
-  asking for trouble.
+  etc. — every other write path. Each needs a server-side capability in
+  `ApiCapability::REGISTRY` first (writes fail closed without one), then
+  a CLI command. Cherry-pick as customers ask.
+- **Prospect deletes.** Shipped in v0.6.0: `prospect_families
+  create/update/note` and `prospects create/update/advance` behind the
+  `prospects:write` scope. `DELETE /prospect_families/:id` and
+  `DELETE /prospects/:id` remain out of reach — destroy actions are in
+  no API capability server-side, by design.
 
 ## Packaging / distribution
 
@@ -133,16 +130,10 @@ Last updated: 2026-05-12 (after L1 ships).
 
 ## Backend asks (push back to WIQ app team)
 
-- **`GET /api/v1/prospects?query=<str>` 500s on ambiguous ORDER BY.**
-  Found during the Phase 5 agent telemetry pass. The controller does
-  `Prospect.joins(:prospect_family).merge(ProspectFamily.search(query))
-  .order(created_at: :desc)` — both `prospects` and `prospect_families`
-  have `created_at`, so the join makes the order ambiguous. One-line
-  fix on the WIQ-app side: change to
-  `.order("prospects.created_at DESC")` (or
-  `.order(Prospect.arel_table[:created_at].desc)`). The CLI documents
-  the workaround (use `wiq prospect_families list --query` — same
-  matches, returns families with prospects embedded) until this ships.
+- ~~**`GET /api/v1/prospects?query=<str>` 500s on ambiguous ORDER BY.**~~ —
+  SHIPPED (WIQ-app commit 7ac9d90a5, 2026-05-21, qualifies the ORDER BY
+  as `prospects.created_at`). `wiq prospects list --query` works; the
+  KNOWN BUG note was removed from its long_desc in v0.6.0.
 
 
 - ~~**`days_threshold` permit fix on `Api::V1::ReportsController`**~~ —

data/docs/wiq_api_notes.md

@@ -288,13 +288,49 @@ file with the WIQ team.
     permit list as of the May 2026 WIQ-app fix. The CLI's
     `--days-threshold` flag lands unchanged on the model.
 
+**PAT write capabilities (`Api::V1::BaseController#enforce_pat_restrictions`):**
+
+PAT traffic is read-only by default. A non-GET request succeeds only when
+`ApiCapability.for(controller, action)` resolves to a capability that
+(a) the team has enabled (`Team#api_write_capabilities`, editable by an
+admin at `/settings/team/api_access`) and (b) the token carries
+(`PersonalAccessToken#scopes`, immutable after mint, coach tokens only).
+Registry today:
+
+| Capability | Actions |
+| --- | --- |
+| `prospects:write` | `prospect_families#create/#update`, `prospects#create/#update`, `prospect_family_notes#create` |
+| `reports:write` | `reports#create` |
+
+Unregistered writes (every `destroy`, everything else) fail closed with
+`"This endpoint is not writable with a personal access token."` The other
+two denials name the capability verbatim — the CLI regexes on them:
+
+| Body | CLI `code` |
+| --- | --- |
+| `This endpoint is not writable with a personal access token.` | `pat_write_unsupported` |
+| `This team has not enabled <cap> for API access. …` | `capability_disabled_for_team` |
+| `This token lacks the <cap> scope. Revoke it and mint a new token …` | `token_missing_scope` |
+
+Team policy is re-checked per request, so an admin turning a capability
+off disables every token holding it immediately. Every PAT call writes an
+audit row (`PersonalAccessTokenAuditJob`) carrying the capability + scopes.
+`GET /api/v1/personal_access_tokens` now includes `scopes: [...]` per
+token; the CLI stores it at login and shows it in `auth status` / `doctor`.
+
+Prospect-specific PAT rule (`ProspectsController#update`): stage changes
+are not forced for token callers, so `advance_to!` refuses downgrades and
+moves out of a terminal stage. The controller turns that silent no-op
+into a 422 `"Stage cannot move from <a> to <b> with a personal access
+token …"` → CLI code `stage_transition_refused`.
+
 **Auth model (POST /api/v1/reports):**
 
 - Every report POST requires a `CoachProfile`-bound PAT on the same team
-  (`coach_belongs_to_team?` in `ReportPolicy#create?`). Parent/wrestler
-  PATs return 403 with body `"Personal access tokens are read-only..."`
-  via `enforce_pat_restrictions` — reports is the one write currently on
-  the PAT allowlist.
+  (`coach_belongs_to_team?` in `ReportPolicy#create?`) AND the
+  `reports:write` capability (backfilled onto every existing team and
+  token when per-token scopes shipped, so nothing changed for existing
+  scripts). See "PAT write capabilities" below.
 - A subset of report types — the 9 listed in `Report.finance_types`
   (Membership, PaidSessionAccounting, RecurringDonor, DonationTransaction,
   FundraiserSummary, FundraiserAccounting, InProgressRegistration,
@@ -343,7 +379,7 @@ DiscountedSubscriptionsReport, **DonationTransactionReport**,
 PaidSessionAddOnDetailReport, PaidSessionAddOnSummaryReport,
 **PracticeAttendanceReport**, **RecurringDonorReport**, RegistrationAnswerReport,
 **RegistrationFinanceSummaryReport**, **RosterReport**, **RosterStatsReport**,
-**ScholarshipAuditReport**, SessionRegistrationAnswerReport,
+**ScholarshipAuditReport**, **SessionRegistrationAnswerReport**,
 TeamRegistrationRosterReport, UsawExpiredReport, UsawExportReport, UsawReport,
 **WinLossReport**, **WrestlersWithoutSubscriptionsReport**`
 

data/lib/wiq/cli.rb

@@ -68,10 +68,10 @@ module Wiq
     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)"
+    desc "prospects SUBCOMMAND", "Prospect pipeline — individual kids (list, show, summary; create, update, advance need prospects:write)"
     subcommand "prospects", Wiq::Commands::Prospects
 
-    desc "prospect_families SUBCOMMAND", "Prospect pipeline — households (list, show, notes)"
+    desc "prospect_families SUBCOMMAND", "Prospect pipeline — households (list, show, notes, stage_changes, linked_answers; create, update, note need prospects:write)"
     subcommand "prospect_families", Wiq::Commands::ProspectFamilies
 
     desc "workflows SUBCOMMAND", "Named multi-step recipes for common club-admin questions (list, show)"
@@ -91,5 +91,8 @@ module Wiq
 
     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/client.rb

@@ -9,7 +9,8 @@ module Wiq
   # Thin wrapper around Faraday that:
   #   - Adds Authorization: Bearer <pat>
   #   - Parses JSON requests and responses
-  #   - Retries on 429 and 5xx (Retry-After honored)
+  #   - Retries on 429 and 5xx (Retry-After honored) — GET/HEAD only, so a
+  #     write is never replayed
   #   - Translates non-2xx responses into Wiq::APIError
   #   - Exposes paginate(path, params) that walks the Link: rel=next chain
   class Client
@@ -36,6 +37,10 @@ module Wiq
       request(:put, path, body: body)
     end
 
+    def patch(path, body = {})
+      request(:patch, path, body: body)
+    end
+
     def delete(path, params = {})
       request(:delete, path, params: params)
     end

data/lib/wiq/commands/auth.rb

@@ -21,8 +21,14 @@ module Wiq
 
         Verification: the CLI hits `GET /api/v1/personal_access_tokens` to
         confirm the token works AND fetch the bound profile (display_name,
-        team_name, type) in one round trip. That metadata is shown after
-        login and stored alongside the token.
+        team_name, type) plus the token's write `scopes` in one round trip.
+        That metadata is shown after login and stored alongside the token.
+
+        Scopes: every PAT can read. Writes need a capability (currently
+        prospects:write, reports:write) that the team admin has enabled
+        under Settings → API Access AND that the token was minted with.
+        Scopes are immutable — to change them, revoke and mint a new
+        token, then re-run this command with --force.
       DESC
       method_option :token, type: :string, desc: "PAT value (otherwise prompted interactively)"
       method_option :force, type: :boolean, default: false,
@@ -64,7 +70,8 @@ module Wiq
           token: token,
           token_prefix: metadata[:token_prefix],
           name: metadata[:name],
-          profile: metadata[:profile]
+          profile: metadata[:profile],
+          scopes: metadata[:scopes]
         )
 
         render(
@@ -74,10 +81,11 @@ module Wiq
             "token_prefix" => metadata[:token_prefix],
             "name" => metadata[:name],
             "profile" => metadata[:profile],
+            "scopes" => metadata[:scopes],
             "stored_at" => Wiq::Credentials.for_host(host, alias_name)["stored_at"]
           }.compact,
           summary: profile_summary("Stored PAT for #{host} as #{alias_name.inspect}",
-                                   metadata[:profile]),
+                                   metadata[:profile], metadata[:scopes]),
           breadcrumbs: [
             { "cmd" => "wiq auth status --as #{alias_name}",
               "description" => "Verify the stored token works" },
@@ -93,7 +101,9 @@ module Wiq
 
         Performs a best-effort live probe against
         `/api/v1/personal_access_tokens` to confirm the token still works
-        and surface the live last_used_at. If the probe fails (network,
+        and surface the live last_used_at and write `scopes` (empty =
+        read-only). Check `live_scopes` before attempting a write command
+        such as `wiq prospects advance`. If the probe fails (network,
         revoked token, host unreachable), the error appears in `live_error`
         rather than aborting the command — local state is always shown.
 
@@ -126,9 +136,11 @@ module Wiq
           "token_prefix" => store_entry["token_prefix"],
           "stored_name" => store_entry["name"],
           "stored_profile" => store_entry["profile"],
+          "stored_scopes" => store_entry["scopes"],
           "live_name" => live_metadata&.dig(:name),
           "live_last_used_at" => live_metadata&.dig(:last_used_at),
           "live_profile" => live_metadata&.dig(:profile),
+          "live_scopes" => live_metadata&.dig(:scopes),
           "live_error" => live_error
         }.compact
 
@@ -138,7 +150,8 @@ module Wiq
                           : "No alias resolvable for this host."
           else
             profile_summary("Token reachable (alias=#{cfg.alias_name})",
-                            live_metadata&.dig(:profile) || store_entry["profile"])
+                            live_metadata&.dig(:profile) || store_entry["profile"],
+                            live_metadata ? live_metadata[:scopes] : store_entry["scopes"])
           end
 
         render(data, summary: summary)
@@ -231,25 +244,36 @@ module Wiq
             key: "personal_access_tokens"
           )
           match = rows.find { |r| r["token_prefix"] == prefix }
-          return { token_prefix: prefix, name: nil, last_used_at: nil, profile: nil } unless match
+          return { token_prefix: prefix, name: nil, last_used_at: nil, profile: nil, scopes: nil } unless match
 
           {
             token_prefix: match["token_prefix"],
             name: match["name"],
             last_used_at: match["last_used_at"],
-            profile: match["profile"]
+            profile: match["profile"],
+            # Servers predating per-token scopes omit the key; treat as read-only.
+            scopes: Array(match["scopes"])
           }
         end
 
-        def profile_summary(prefix, profile)
-          return "#{prefix}." unless profile
+        def profile_summary(prefix, profile, scopes = nil)
+          scope_note =
+            if scopes.nil?
+              nil
+            elsif scopes.empty?
+              "scopes: read-only"
+            else
+              "scopes: #{scopes.join(", ")}"
+            end
+          return [prefix, scope_note].compact.join("; ") + "." unless profile
 
           who = profile["display_name"]
           where = profile["team_name"]
           kind = profile["type"]
           tail = [who, where].compact.reject(&:empty?).join(" @ ")
           tail += " (#{kind})" if kind && !kind.empty?
-          tail.empty? ? "#{prefix}." : "#{prefix} — #{tail}."
+          head = tail.empty? ? prefix : "#{prefix} — #{tail}"
+          [head, scope_note].compact.join("; ") + "."
         end
       end
     end

data/lib/wiq/commands/doctor.rb

@@ -15,6 +15,9 @@ module Wiq
           6. Live reachability + auth probe via
              `GET /api/v1/personal_access_tokens`
           7. Bound profile (display_name, type, team) for the calling token
+          8. Write scopes on the token (empty = read-only; writes such as
+             `wiq prospects advance` need the matching capability enabled
+             by the team AND present on the token)
 
         Exits non-zero if any check fails. Agents should run this first
         when handed an unfamiliar shell to confirm they can actually call
@@ -59,6 +62,12 @@ module Wiq
               checks << check("Bound profile",
                               "#{profile["display_name"]} (#{profile["type"]}) @ #{profile["team_name"]}",
                               ok: !profile["display_name"].nil?)
+              scopes = Array(match["scopes"])
+              checks << check("Write scopes",
+                              scopes.empty? ? "none (read-only)" : scopes.join(", "),
+                              ok: true,
+                              hint: scopes.empty? ? "Reads only. Mint a token with prospects:write to use " \
+                                                    "prospect write commands." : nil)
             else
               checks << check("Reachability + auth", "200 OK", ok: true)
               checks << check("Bound profile", "(token not in own user's PAT list?)",

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