wiq-cli 0.1.0

data/lib/wiq/cli.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Wiq
+  class CLI < Thor
+    package_name "wiq"
+
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "version", "Print the CLI version"
+    def version
+      puts Wiq::VERSION
+    end
+    map %w[--version -v] => :version
+
+    desc "commands", "Dump the full command tree as JSON for agent discovery"
+    long_desc <<~DESC
+      Walks the Thor command registry and emits the entire CLI surface as
+      structured JSON. Schema:
+
+        { name, version, global_options[], top_level_commands[],
+          groups: [ { name, description, commands: [
+            { name, description, long_description, usage,
+              options: [ { name, type, required, default?, enum?, description } ]
+            }
+          ] } ] }
+
+      Recommended first call for any agent: pipe to a file, cache it, then
+      pick a command and invoke it directly. No HTTP, no auth required.
+
+      `global_options` lists --host, --as, --json, --agent — these apply
+      uniformly to every command and aren't repeated per-command.
+    DESC
+    def commands
+      puts JSON.pretty_generate(Wiq::Introspection.dump_tree)
+    end
+
+    desc "doctor", "Diagnose env, network, token, and config sources"
+    subcommand "doctor", Wiq::Commands::Doctor
+
+    desc "auth SUBCOMMAND", "Manage authentication (login, status, logout, list)"
+    subcommand "auth", Wiq::Commands::Auth
+
+    desc "check_ins SUBCOMMAND", "Attendance + check-ins (event, wrestler, summary)"
+    subcommand "check_ins", Wiq::Commands::CheckIns
+
+    desc "reports SUBCOMMAND", "Reports (run, show, types)"
+    subcommand "reports", Wiq::Commands::Reports
+
+    desc "paid_sessions SUBCOMMAND", "Paid sessions / registration data (list, show)"
+    subcommand "paid_sessions", Wiq::Commands::PaidSessions
+
+    desc "registrations SUBCOMMAND", "Registration questions + answers"
+    subcommand "registrations", Wiq::Commands::Registrations
+
+    desc "metrics SUBCOMMAND", "Dashboard metrics (list, show)"
+    subcommand "metrics", Wiq::Commands::Metrics
+
+    desc "events SUBCOMMAND", "Calendar events (list, show)"
+    subcommand "events", Wiq::Commands::Events
+
+    desc "rosters SUBCOMMAND", "Rosters (list, show)"
+    subcommand "rosters", Wiq::Commands::Rosters
+
+    desc "prospects SUBCOMMAND", "Prospect pipeline — individual kids (list, show, summary)"
+    subcommand "prospects", Wiq::Commands::Prospects
+
+    desc "prospect_families SUBCOMMAND", "Prospect pipeline — households (list, show, notes)"
+    subcommand "prospect_families", Wiq::Commands::ProspectFamilies
+
+    desc "workflows SUBCOMMAND", "Named multi-step recipes for common club-admin questions (list, show)"
+    subcommand "workflows", Wiq::Commands::Workflows
+
+    desc "setup SUBCOMMAND", "Install integration files (Claude Code skill, future: Cursor, etc.)"
+    subcommand "setup", Wiq::Commands::Setup
+
+    desc "wrestlers SUBCOMMAND", "Search wrestlers — narrow ID-discovery surface (list, show)"
+    subcommand "wrestlers", Wiq::Commands::Wrestlers
+
+    desc "charges SUBCOMMAND", "Payment history — list charges by family, status, type, date (admin only)"
+    subcommand "charges", Wiq::Commands::Charges
+
+    desc "billing_profiles SUBCOMMAND", "Look up a parent or coach's billing profile (admin only)"
+    subcommand "billing_profiles", Wiq::Commands::BillingProfiles
+  end
+end

data/lib/wiq/client.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+require "uri"
+
+module Wiq
+  # Thin wrapper around Faraday that:
+  #   - Adds Authorization: Bearer <pat>
+  #   - Parses JSON requests and responses
+  #   - Retries on 429 and 5xx (Retry-After honored)
+  #   - Translates non-2xx responses into Wiq::APIError
+  #   - Exposes paginate(path, params) that walks the Link: rel=next chain
+  class Client
+    USER_AGENT = "wiq-cli/#{Wiq::VERSION}"
+
+    attr_reader :host
+
+    def initialize(config)
+      @config = config
+      config.require_host!
+      @host = config.host
+      @token = config.token
+    end
+
+    def get(path, params = {})
+      request(:get, path, params: params)
+    end
+
+    def post(path, body = {})
+      request(:post, path, body: body)
+    end
+
+    def put(path, body = {})
+      request(:put, path, body: body)
+    end
+
+    def delete(path, params = {})
+      request(:delete, path, params: params)
+    end
+
+    # Yields each page's records until rel=next runs out.
+    # All /api/v1 index endpoints wrap their array under the resource name
+    # (e.g. `{"rosters": [...]}`) — callers must pass `key:` so we can unwrap.
+    # Yields (records_array, response, total_count).
+    def paginate(path, params = {}, key:)
+      url = absolute(path)
+      first = true
+      loop do
+        resp = first ? request(:get, path, params: params, raw: true)
+                     : request(:get, url, raw: true)
+        first = false
+        records = extract_records(resp.body, key)
+        total = Pagination.total_count(resp.headers)
+        yield records, resp, total
+        url = Pagination.next_url(resp.headers["Link"] || resp.headers["link"])
+        break unless url
+      end
+    end
+
+    # Collects every page of an index into a single array.
+    def collect_all(path, params = {}, key:)
+      all = []
+      total = nil
+      paginate(path, params, key: key) do |records, _resp, t|
+        total ||= t
+        all.concat(records)
+      end
+      [all, total]
+    end
+
+    private
+
+    def extract_records(body, key)
+      return Array(body) if body.is_a?(Array)
+      return [] if body.nil?
+      raise Error.new("Expected wrapped index response with key #{key.inspect}, got #{body.class}",
+                      code: "unexpected_response") unless body.is_a?(Hash)
+
+      Array(body[key.to_s] || body[key.to_sym])
+    end
+
+    def request(method, path_or_url, params: {}, body: nil, raw: false)
+      url = path_or_url.start_with?("http") ? path_or_url : absolute(path_or_url)
+
+      response = connection.public_send(method) do |req|
+        req.url(url)
+        req.params.update(params) if params && !params.empty?
+        req.body = body if body
+      end
+
+      if response.status >= 400
+        raise APIError.new(
+          status: response.status,
+          body: response.body,
+          request_id: response.headers["X-Request-Id"]
+        )
+      end
+
+      raw ? response : response.body
+    end
+
+    def absolute(path)
+      base = @host.sub(%r{/+\z}, "")
+      path = path.start_with?("/") ? path : "/#{path}"
+      "#{base}#{path}"
+    end
+
+    def connection
+      @connection ||= Faraday.new do |f|
+        f.request :json
+        f.request :retry,
+                  max: 3,
+                  interval: 0.5,
+                  backoff_factor: 2,
+                  retry_statuses: [429, 500, 502, 503, 504],
+                  methods: %i[get head]
+        f.response :json, content_type: /\bjson\z/
+        f.headers["Accept"] = "application/json"
+        f.headers["User-Agent"] = USER_AGENT
+        f.headers["Authorization"] = "Bearer #{@token}" if @token
+        f.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/wiq/commands/auth.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Wiq
+  module Commands
+    class Auth < Base
+      desc "login", "Store a personal access token for a WIQ host"
+      long_desc <<~DESC
+        Stores a PAT in ~/.config/wiq/credentials.json (mode 0600) keyed by
+        host + alias.
+
+        First-time login slots into "default" automatically. If "default" is
+        already taken, pass --as <alias> to create a separate slot — this is
+        how the CLI supports multiple WIQ accounts (different clubs, different
+        roles) on the same host.
+
+        Customers mint PATs at <host>/settings/personal_access_tokens. The
+        plaintext is shown once at creation; paste it into this command (or
+        use --token).
+
+        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.
+      DESC
+      method_option :token, type: :string, desc: "PAT value (otherwise prompted interactively)"
+      method_option :force, type: :boolean, default: false,
+                            desc: "Overwrite an existing entry at this host+alias slot"
+      def login
+        default_host = Wiq::Config::PRODUCTION_HOST
+        host = options[:host] || prompt("WIQ host URL [#{default_host}]: ")
+        host = host.to_s.strip
+        host = default_host if host.empty?
+        unless host.start_with?("http")
+          raise Wiq::ConfigError.new("Host must be an absolute URL, got #{host.inspect}.",
+                                     code: "invalid_host")
+        end
+
+        token = options[:token] || prompt_secret("Personal access token: ")
+        token = token.to_s.strip
+        unless token.start_with?("wiq_pat_")
+          raise Wiq::ConfigError.new("Token does not start with `wiq_pat_`.",
+                                     code: "invalid_token",
+                                     hint: "Mint a PAT at <host>/settings/personal_access_tokens.")
+        end
+
+        alias_name = pick_login_alias(host, options[:as])
+
+        if Wiq::Credentials.for_host(host, alias_name) && !options[:force]
+          raise Wiq::AliasConflictError.new(host, alias_name)
+        end
+
+        cfg = Wiq::Config.new
+        cfg.instance_variable_set(:@host, host)
+        cfg.instance_variable_set(:@token, token)
+        client = Wiq::Client.new(cfg)
+
+        metadata = lookup_token_metadata(client, token)
+
+        Wiq::Credentials.store(
+          host: host,
+          alias_name: alias_name,
+          token: token,
+          token_prefix: metadata[:token_prefix],
+          name: metadata[:name],
+          profile: metadata[:profile]
+        )
+
+        render(
+          {
+            "host" => host,
+            "alias" => alias_name,
+            "token_prefix" => metadata[:token_prefix],
+            "name" => metadata[:name],
+            "profile" => metadata[:profile],
+            "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]),
+          breadcrumbs: [
+            { "cmd" => "wiq auth status --as #{alias_name}",
+              "description" => "Verify the stored token works" },
+            { "cmd" => "wiq auth list", "description" => "See all stored credentials" }
+          ]
+        )
+      end
+
+      desc "status", "Show the configured host, alias, and bound profile"
+      long_desc <<~DESC
+        Resolves the configuration chain (--host/--as flags → env vars →
+        .wiq/config.json → credentials store) and reports which source won.
+
+        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,
+        revoked token, host unreachable), the error appears in `live_error`
+        rather than aborting the command — local state is always shown.
+
+        Useful as the first call when an agent inherits a configured shell:
+        verifies host, alias, profile binding, and team in one shot.
+      DESC
+      def status
+        cfg = Wiq::Config.load(symbolized_options)
+        raise Wiq::HostUnsetError unless cfg.host
+
+        store_entry = cfg.alias_name ? Wiq::Credentials.for_host(cfg.host, cfg.alias_name) || {} : {}
+        live_metadata = nil
+        live_error = nil
+        if cfg.token
+          begin
+            client = Wiq::Client.new(cfg)
+            live_metadata = lookup_token_metadata(client, cfg.token)
+          rescue Wiq::APIError, Faraday::Error => e
+            live_error = e.message
+          end
+        end
+
+        data = {
+          "host" => cfg.host,
+          "host_source" => cfg.sources[:host],
+          "alias" => cfg.alias_name,
+          "alias_source" => cfg.sources[:alias],
+          "token_present" => !cfg.token.nil?,
+          "token_source" => cfg.sources[:token],
+          "token_prefix" => store_entry["token_prefix"],
+          "stored_name" => store_entry["name"],
+          "stored_profile" => store_entry["profile"],
+          "live_name" => live_metadata&.dig(:name),
+          "live_last_used_at" => live_metadata&.dig(:last_used_at),
+          "live_profile" => live_metadata&.dig(:profile),
+          "live_error" => live_error
+        }.compact
+
+        summary =
+          if !cfg.token
+            cfg.alias_name ? "No token stored for alias #{cfg.alias_name.inspect}." \
+                          : "No alias resolvable for this host."
+          else
+            profile_summary("Token reachable (alias=#{cfg.alias_name})",
+                            live_metadata&.dig(:profile) || store_entry["profile"])
+          end
+
+        render(data, summary: summary)
+      end
+
+      desc "logout", "Remove a stored credential slot"
+      long_desc <<~DESC
+        Removes a single stored credential by host + alias. The PAT is NOT
+        revoked server-side — to revoke, use the web UI at
+        <host>/settings/personal_access_tokens. Logout just clears the
+        local file entry.
+      DESC
+      def logout
+        cfg = Wiq::Config.load(symbolized_options)
+        raise Wiq::HostUnsetError unless cfg.host
+        unless cfg.alias_name
+          aliases = Wiq::Credentials.aliases_for(cfg.host)
+          raise Wiq::AmbiguousAliasError.new(cfg.host, aliases) unless aliases.empty?
+
+          render({ "host" => cfg.host, "removed" => false },
+                 summary: "No credentials stored for #{cfg.host}.")
+          return
+        end
+
+        removed = Wiq::Credentials.remove(cfg.host, cfg.alias_name)
+        render(
+          { "host" => cfg.host, "alias" => cfg.alias_name, "removed" => removed },
+          summary: removed ? "Cleared #{cfg.alias_name.inspect} for #{cfg.host}." \
+                          : "No credential stored at #{cfg.host} / #{cfg.alias_name.inspect}."
+        )
+      end
+
+      desc "list", "List all stored credentials across hosts and aliases"
+      long_desc <<~DESC
+        Dumps every stored credential across all hosts and aliases. Never
+        includes the raw token (only token_prefix); safe to share or log.
+
+        Useful for agents inheriting a shared shell — they can see what's
+        available before invoking commands.
+      DESC
+      def list
+        entries = Wiq::Credentials.all_entries
+        render_index(
+          entries,
+          summary: "Stored credentials: #{entries.size}.",
+          breadcrumbs: [
+            { "cmd" => "wiq auth status --as <alias>", "description" => "Inspect a specific slot" }
+          ]
+        )
+      end
+
+      no_commands do
+        def prompt(label)
+          $stderr.print(label)
+          $stdin.gets.to_s.chomp
+        end
+
+        def prompt_secret(label)
+          $stderr.print(label)
+          val = $stdin.noecho(&:gets).to_s.chomp
+          $stderr.puts ""
+          val
+        rescue Errno::ENOTTY, IOError
+          $stdin.gets.to_s.chomp
+        end
+
+        # Decide which slot to write to. Explicit --as wins. Otherwise:
+        # - empty bucket → "default"
+        # - "default" free → "default"
+        # - "default" taken → demand --as
+        def pick_login_alias(host, requested)
+          return requested if requested && !requested.empty?
+
+          existing = Wiq::Credentials.aliases_for(host)
+          return Wiq::Credentials::DEFAULT_ALIAS if existing.empty?
+          return Wiq::Credentials::DEFAULT_ALIAS unless existing.include?(Wiq::Credentials::DEFAULT_ALIAS)
+
+          raise Wiq::ConfigError.new(
+            "An entry already exists at #{host} under alias \"default\".",
+            code: "alias_required",
+            hint: "Pass --as <name> to store under a different slot, or --force to overwrite default."
+          )
+        end
+
+        def lookup_token_metadata(client, token)
+          prefix = token[0, 12]
+          rows, = client.collect_all(
+            "/api/v1/personal_access_tokens",
+            { "per_page" => 100 },
+            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
+
+          {
+            token_prefix: match["token_prefix"],
+            name: match["name"],
+            last_used_at: match["last_used_at"],
+            profile: match["profile"]
+          }
+        end
+
+        def profile_summary(prefix, profile)
+          return "#{prefix}." 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}."
+        end
+      end
+    end
+  end
+end

data/lib/wiq/commands/base.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Wiq
+  module Commands
+    # Parent class for every subcommand group. Defines the cross-cutting
+    # --host / --json / --agent options and the helpers each command uses.
+    class Base < Thor
+      class_option :host, type: :string,
+                          desc: "WIQ host URL (overrides env + config + credential store)"
+      class_option :as, type: :string,
+                        desc: "Credential alias to use (overrides env + config + sole/default)"
+      class_option :json, type: :boolean, default: false,
+                          desc: "Output the full JSON envelope"
+      class_option :agent, type: :boolean, default: false,
+                           desc: "Output bare JSON of `data` with no envelope or colors"
+
+      def self.exit_on_failure?
+        true
+      end
+
+      no_commands do
+        def config
+          @config ||= Wiq::Config.load(symbolized_options)
+        end
+
+        def client
+          @client ||= begin
+            config.require_token!
+            Wiq::Client.new(config)
+          end
+        end
+
+        def symbolized_options
+          @symbolized_options ||= options.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+        end
+
+        def render(data, summary: nil, breadcrumbs: [], meta: {})
+          Wiq::Output.render(data, summary: summary, breadcrumbs: breadcrumbs,
+                                   meta: meta.merge("host" => config.host).compact,
+                                   options: symbolized_options)
+        end
+
+        def render_index(records, total: nil, page: nil, summary: nil, breadcrumbs: [])
+          meta = { "count" => records.size }
+          meta["total"] = total if total
+          meta["page"] = page if page
+          render(records, summary: summary, breadcrumbs: breadcrumbs, meta: meta)
+        end
+
+        def fetch_index(path, params, key:)
+          if options[:all]
+            records, total = client.collect_all(path, params, key: key)
+            [records, total, nil]
+          else
+            records = []
+            total = nil
+            client.paginate(path, params, key: key) do |page_records, _resp, t|
+              records = page_records
+              total = t
+              break
+            end
+            [records, total, nil]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/wiq/commands/billing_profiles.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class BillingProfiles < Base
+      VALID_PROFILE_TYPES = %w[ParentProfile CoachProfile].freeze
+
+      desc "show PROFILE_ID", "Look up a parent or coach's billing profile"
+      long_desc <<~DESC
+        Fetches the billing profile (payment-method metadata + Stripe/Justifi
+        linkage) for a specific parent or coach profile.
+
+        Path: GET /api/v1/billing_profiles/<profile_type>/<profile_id>.
+
+        WrestlerProfile is not supported — wrestlers themselves don't have
+        billing profiles in WIQ. To find which family paid for a given
+        wrestler, walk via `wiq wrestlers show <id>` to find the parents
+        array, then call this for one of the parent profile ids.
+
+        Returns: id, email, billing_partner (stripe | justifi),
+        default_payment_method_{last4, brand, exp_month, exp_year}, and
+        the embedded billable profile (full_name, type).
+
+        Pass --for-update to get a setup_intent for card-on-file updates;
+        not relevant for read-only agent flows.
+      DESC
+      method_option :profile_type, type: :string, required: true,
+                                   enum: VALID_PROFILE_TYPES,
+                                   desc: "ParentProfile | CoachProfile (WrestlerProfile not supported)"
+      method_option :for_update, type: :boolean, default: false,
+                                 desc: "Include setup_intent + billing_partner_key for card updates"
+      def show(profile_id)
+        params = {}
+        params["for_update"] = true if options[:for_update]
+
+        billing_profile = client.get(
+          "/api/v1/billing_profiles/#{options[:profile_type]}/#{profile_id}",
+          params
+        )
+        render(billing_profile,
+               summary: "Billing profile #{billing_profile["id"]} for " \
+                        "#{options[:profile_type]} #{profile_id}.",
+               breadcrumbs: [
+                 { "cmd" => "wiq charges list --billing-profile #{billing_profile["id"]}",
+                   "description" => "Payment history for this family" },
+                 { "cmd" => "wiq charges list --billing-profile #{billing_profile["id"]} --status failed --since <date>",
+                   "description" => "Recent failed charges" }
+               ])
+      end
+    end
+  end
+end