wiq-cli 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee99cfc6ad08abdf7e1318883bcfa3ecc45635d2d521de150ed1622d867b0ebc
-  data.tar.gz: d9b6f3d18c731b4ddfe1060a03a40310e4d58b940d1f00f97dd3ef480f22dd74
+  metadata.gz: eb99112754a10af0b80b20d71425f95e864fb28a3db78a1c3d0e7d75340ebf8f
+  data.tar.gz: ee12d73a7e5053dd48540c73c35e4327bb3f4456998f3182725b2a1d40a99403
 SHA512:
-  metadata.gz: 89f8f34ae2184fab2069c8a0d51eaf53936dcb69e538e2fd7c0f659900e1be6ea3ee2f43101726ecb25bcd933a77beb20b2b954af4facbbfb248f4f0e40ae914
-  data.tar.gz: b63afbb5f6755e1821f268d0a797fc1d1f12d97148f790aa340ad0ec55bdf86df91ee649d003caaabe33351e91a25f848217fd6e26da09c3cf6dcc136b173d15
+  metadata.gz: 92e5c6842312a60ad606f711b5c6893c2a2c761e181b0c999dcf0fcb6bb1e92f8cc3b25dadd6c365656b91f7b242666b43131e5680ec440036c67868f04eb794
+  data.tar.gz: a4e06d43acf373996c31593b6a736555ab9b5aa71a4d7c0baf606f8dc76fa090f3ae7519820ec04ed6ca1167375b977261d12312bca2fe07b70de86f902430e6

data/lib/wiq/cli.rb

@@ -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/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/version.rb

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

data/lib/wiq.rb

@@ -29,4 +29,5 @@ 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wiq-cli
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - WrestlingIQ
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-08 00:00:00.000000000 Z
+date: 2026-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -94,6 +94,7 @@ files:
 - 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