mpql 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: efb2efbefe64a0440d1fc21620820791b9c8dbf6298b6cc55b22cc70d54f4a55
+  data.tar.gz: a4dc264a5b02f0b7d6ee6e07f754bfebd4ef18b205cbb27a199f6238d49dcdb9
+SHA512:
+  metadata.gz: bbeb54de0e804fffe71383d78edd38d44e28070e8f1b0b89ae309ca927bf76ab9e564819a0e498e19d4ce73f9813567172488c89a738d0b361a1143a921189d6
+  data.tar.gz: 2441597897c95693cfe5b7a2fb41ffe628cf72afb3c9ec1d195af03b1dc7fb62a1650009f9d689a3da29cf14900c3cf49d840d900f6b81c160b405dc0e8961a6

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 tomorrowkey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,109 @@
+# mpql
+
+A command-line tool to execute MixPanel Query API requests. Designed for both human users and AI agents.
+
+## Installation
+
+```
+gem install mpql
+```
+
+## Configuration
+
+Create `~/.mpql.yml`:
+
+```yaml
+username: your-service-account-username
+secret: your-service-account-secret
+```
+
+Or use environment variables:
+
+```
+MIXPANEL_USERNAME=your-service-account-username
+MIXPANEL_SECRET=your-service-account-secret
+```
+
+## Usage
+
+### Segmentation
+
+```
+mpql segmentation --project-id 123456 --event "Signed Up" --from 7d --to today
+mpql segmentation --project-id 123456 --event "Page View" --from 2026-03-01 --to 2026-03-09 --on "properties.$browser" --unit day
+mpql segmentation --project-id 123456 --event "Purchase" --from 1m --to today --type unique --format tsv
+```
+
+### Funnels
+
+```
+mpql funnels --project-id 123456 --funnel-id 12345 --from 7d --to today
+mpql funnels --project-id 123456 --funnel-id 12345 --from 2026-03-01 --to 2026-03-09 --on "properties.$os"
+```
+
+### Retention
+
+```
+mpql retention --project-id 123456 --from 30d --to today
+mpql retention --project-id 123456 --from 2026-02-01 --to 2026-03-09 --born-event "Signed Up" --event "Login"
+```
+
+### Insights
+
+```
+mpql insights --project-id 123456 --bookmark-id 67890
+```
+
+### Cohorts
+
+```
+mpql cohorts --project-id 123456
+mpql cohorts --project-id 123456 --format table
+```
+
+### Export (Raw Event Data)
+
+```
+mpql export --project-id 123456 --event "ScreenView" --from 7d --to today
+mpql export --project-id 123456 --event "Signed Up" --from 2026-03-01 --to 2026-03-09
+```
+
+### Engage (User Profiles)
+
+```
+mpql engage --project-id 123456
+mpql engage --project-id 123456 --where 'properties["$email"] == "test@example.com"'
+mpql engage --project-id 123456 --distinct-id "user123"
+```
+
+### Date Formats
+
+- `yyyy-mm-dd` (e.g., `2026-03-01`)
+- `today`, `yesterday`
+- `Nd` - N days ago (e.g., `7d`)
+- `Nw` - N weeks ago (e.g., `2w`)
+- `Nm` - N months ago (e.g., `1m`)
+
+### Output Formats
+
+- `--format json` (default) - JSON output
+- `--format tsv` - Tab-separated values
+- `--format table` - ASCII table
+- `--raw` - Raw JSON without pretty-printing
+
+### Global Options
+
+- `--project-id` - MixPanel project ID (required)
+- `--region` - MixPanel region (`us`, `eu`, `in`). Defaults to `us`
+
+## Release
+
+1. Update the version number in `lib/mpql/version.rb`
+2. Commit the changes
+3. Run `rake release`
+
+This will create a git tag, build the gem, and push it to [rubygems.org](https://rubygems.org).
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.

data/exe/mpql

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "mpql"
+require "mpql/cli"
+
+Mpql::CLI.start(ARGV)

data/lib/mpql/cli.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "thor"
+require "json"
+require_relative "formatters/json_formatter"
+require_relative "formatters/tsv_formatter"
+require_relative "formatters/table_formatter"
+
+module Mpql
+  class CLI < Thor
+    # Exit with non-zero status on errors
+    def self.exit_on_failure?
+      true
+    end
+
+    class_option :format, type: :string, default: "json", enum: %w[json tsv table],
+                          desc: "Output format (json, tsv, table)"
+    class_option :raw, type: :boolean, default: false,
+                       desc: "Output raw JSON without pretty-printing"
+    class_option :region, type: :string, enum: %w[us eu in],
+                          desc: "MixPanel region (us, eu, in)"
+    class_option :project_id, type: :string, required: true,
+                              desc: "MixPanel project ID"
+
+    desc "segmentation", "Query segmentation data for an event"
+    long_desc <<~LONGDESC
+      Query segmentation data for a specific event, segmented by a property.
+
+      Examples:
+
+        mpql segmentation --project-id 123456 --event "Signed Up" --from 7d --to today
+
+        mpql segmentation --project-id 123456 --event "Page View" --from 2026-03-01 --to 2026-03-09 --on "properties.$browser" --unit day
+
+        mpql segmentation --project-id 123456 --event "Purchase" --from 1m --to today --type unique --format tsv
+
+      Date formats: yyyy-mm-dd, today, yesterday, Nd (days ago), Nw (weeks ago), Nm (months ago)
+    LONGDESC
+    option :event, type: :string, required: true, desc: "Event name"
+    option :from, type: :string, required: true, desc: "Start date"
+    option :to, type: :string, required: true, desc: "End date"
+    option :on, type: :string, desc: "Property expression to segment by"
+    option :unit, type: :string, enum: %w[minute hour day month], desc: "Time unit"
+    option :where, type: :string, desc: "Filter expression"
+    option :type, type: :string, enum: %w[general unique average], desc: "Analysis type"
+    option :limit, type: :numeric, desc: "Max number of property values to return"
+    def segmentation
+      result = client.segmentation(
+        event: options[:event],
+        from_date: parse_date(options[:from]),
+        to_date: parse_date(options[:to]),
+        **optional_params(:on, :unit, :where, :type, :limit)
+      )
+      output(result)
+    rescue Mpql::Error => e
+      error_exit(e)
+    end
+
+    desc "funnels", "Query funnel analysis data"
+    long_desc <<~LONGDESC
+      Query data for a saved funnel.
+
+      Examples:
+
+        mpql funnels --project-id 123456 --funnel-id 12345 --from 7d --to today
+
+        mpql funnels --project-id 123456 --funnel-id 12345 --from 2026-03-01 --to 2026-03-09 --on "properties.$os"
+    LONGDESC
+    option :funnel_id, type: :numeric, required: true, desc: "Funnel ID"
+    option :from, type: :string, required: true, desc: "Start date"
+    option :to, type: :string, required: true, desc: "End date"
+    option :on, type: :string, desc: "Property expression to segment by"
+    option :where, type: :string, desc: "Filter expression"
+    option :limit, type: :numeric, desc: "Max number of property values to return"
+    def funnels
+      result = client.funnels(
+        funnel_id: options[:funnel_id],
+        from_date: parse_date(options[:from]),
+        to_date: parse_date(options[:to]),
+        **optional_params(:on, :where, :limit)
+      )
+      output(result)
+    rescue Mpql::Error => e
+      error_exit(e)
+    end
+
+    desc "retention", "Query retention analysis data"
+    long_desc <<~LONGDESC
+      Query retention analysis data.
+
+      Examples:
+
+        mpql retention --project-id 123456 --from 30d --to today
+
+        mpql retention --project-id 123456 --from 2026-02-01 --to 2026-03-09 --born-event "Signed Up" --event "Login"
+    LONGDESC
+    option :from, type: :string, required: true, desc: "Start date"
+    option :to, type: :string, required: true, desc: "End date"
+    option :born_event, type: :string, desc: "Birth event name"
+    option :event, type: :string, desc: "Return event name"
+    option :retention_type, type: :string, enum: %w[birth compounded], desc: "Retention type"
+    option :on, type: :string, desc: "Property expression to segment by"
+    option :unit, type: :string, enum: %w[day week month], desc: "Bucket unit"
+    option :interval, type: :numeric, desc: "Bucket interval"
+    def retention
+      result = client.retention(
+        from_date: parse_date(options[:from]),
+        to_date: parse_date(options[:to]),
+        **optional_params(:born_event, :event, :retention_type, :on, :unit, :interval)
+      )
+      output(result)
+    rescue Mpql::Error => e
+      error_exit(e)
+    end
+
+    desc "insights", "Query a saved Insights report"
+    long_desc <<~LONGDESC
+      Query data from a saved Insights report by its bookmark ID.
+
+      Examples:
+
+        mpql insights --project-id 123456 --bookmark-id 67890
+    LONGDESC
+    option :bookmark_id, type: :numeric, required: true, desc: "Insights report bookmark ID"
+    def insights
+      result = client.insights(
+        bookmark_id: options[:bookmark_id],
+        **optional_params
+      )
+      output(result)
+    rescue Mpql::Error => e
+      error_exit(e)
+    end
+
+    desc "cohorts", "List saved cohorts"
+    long_desc <<~LONGDESC
+      List all saved cohorts in the project.
+
+      Examples:
+
+        mpql cohorts --project-id 123456
+
+        mpql cohorts --project-id 123456 --format table
+    LONGDESC
+    def cohorts
+      result = client.cohorts(**optional_params)
+      output(result)
+    rescue Mpql::Error => e
+      error_exit(e)
+    end
+
+    desc "engage", "Query user profiles"
+    long_desc <<~LONGDESC
+      Query user profiles using filter expressions.
+
+      Examples:
+
+        mpql engage --project-id 123456
+
+        mpql engage --project-id 123456 --where 'properties["$email"] == "test@example.com"'
+
+        mpql engage --project-id 123456 --distinct-id "user123"
+    LONGDESC
+    option :where, type: :string, desc: "Filter expression"
+    option :distinct_id, type: :string, desc: "Specific user distinct ID"
+    option :page, type: :numeric, desc: "Result page number (starting from 0)"
+    option :session_id, type: :string, desc: "Session ID for pagination"
+    def engage
+      result = client.engage(**optional_params(:where, :distinct_id, :page, :session_id))
+      output(result)
+    rescue Mpql::Error => e
+      error_exit(e)
+    end
+
+    desc "export", "Export raw event data"
+    long_desc <<~LONGDESC
+      Export raw event data for a specific event.
+
+      Examples:
+
+        mpql export --project-id 123456 --event "ScreenView" --from 7d --to today
+
+        mpql export --project-id 123456 --event "Signed Up" --from 2026-03-01 --to 2026-03-09
+    LONGDESC
+    option :event, type: :string, required: true, desc: "Event name"
+    option :from, type: :string, required: true, desc: "Start date"
+    option :to, type: :string, required: true, desc: "End date"
+    def export
+      result = client.export(
+        event: options[:event],
+        from_date: parse_date(options[:from]),
+        to_date: parse_date(options[:to])
+      )
+      output(result)
+    rescue Mpql::Error => e
+      error_exit(e)
+    end
+
+    desc "version", "Show mpql version"
+    def version
+      puts Mpql::VERSION
+    end
+
+    private
+
+    def client
+      apply_overrides
+      @client ||= Client.new
+    end
+
+    def apply_overrides
+      config = Mpql.configuration
+      config.region = options[:region] if options[:region]
+      config.project_id = options[:project_id]
+    end
+
+    def parse_date(value)
+      DateParser.parse(value)
+    end
+
+    def output(data)
+      formatter = case options[:format]
+                  when "tsv"
+                    Formatters::TsvFormatter.new(data)
+                  when "table"
+                    Formatters::TableFormatter.new(data)
+                  else
+                    Formatters::JsonFormatter.new(data, raw: options[:raw])
+                  end
+      $stdout.puts formatter.render
+    end
+
+    def error_exit(error)
+      exit_code = case error
+                  when AuthenticationError then 1
+                  when ApiError then 2
+                  when InputError then 3
+                  when ConfigurationError then 4
+                  else 1
+                  end
+
+      error_data = { error: error.class.name, message: error.message }
+      $stdout.puts JSON.generate(error_data)
+      exit exit_code
+    end
+
+    def optional_params(*keys)
+      return {} if keys.empty?
+
+      keys.each_with_object({}) do |key, hash|
+        hash[key] = options[key] if options[key]
+      end
+    end
+  end
+end

data/lib/mpql/client.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Mpql
+  class Client
+    def initialize(config = Mpql.configuration)
+      @config = config
+    end
+
+    def segmentation(event:, from_date:, to_date:, **options)
+      params = { event: event, from_date: from_date, to_date: to_date }.merge(options)
+      get("/api/query/segmentation", params)
+    end
+
+    def funnels(funnel_id:, from_date:, to_date:, **options)
+      params = { funnel_id: funnel_id, from_date: from_date, to_date: to_date }.merge(options)
+      get("/api/query/funnels", params)
+    end
+
+    def retention(from_date:, to_date:, **options)
+      params = { from_date: from_date, to_date: to_date }.merge(options)
+      get("/api/query/retention", params)
+    end
+
+    def insights(bookmark_id:, **options)
+      params = { bookmark_id: bookmark_id }.merge(options)
+      get("/api/query/insights", params)
+    end
+
+    def cohorts(**options)
+      post("/api/query/cohorts/list", options)
+    end
+
+    def engage(**options)
+      post("/api/query/engage", options)
+    end
+
+    def export(from_date:, to_date:, event:, **options)
+      params = { from_date: from_date, to_date: to_date, event: JSON.generate([event]) }.merge(options)
+      get_jsonl("/api/2.0/export", params)
+    end
+
+    private
+
+    def get(path, params)
+      @config.validate!
+      params[:project_id] = @config.project_id
+      uri = build_uri(path, params)
+      request = Net::HTTP::Get.new(uri)
+      execute(uri, request)
+    end
+
+    def get_jsonl(path, params)
+      @config.validate!
+      params[:project_id] = @config.project_id
+      uri = build_uri(path, params, base_url: @config.data_base_url)
+      request = Net::HTTP::Get.new(uri)
+      execute(uri, request, jsonl: true)
+    end
+
+    def post(path, params)
+      @config.validate!
+      params[:project_id] = @config.project_id
+      uri = build_uri(path)
+      request = Net::HTTP::Post.new(uri)
+      request.set_form_data(params)
+      execute(uri, request)
+    end
+
+    def execute(uri, request, jsonl: false)
+      request.basic_auth(@config.username, @config.secret)
+
+      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+        http.request(request)
+      end
+
+      handle_response(response, jsonl: jsonl)
+    end
+
+    def handle_response(response, jsonl: false)
+      case response.code.to_i
+      when 200
+        if jsonl
+          parse_jsonl(response.body)
+        else
+          JSON.parse(response.body)
+        end
+      when 401, 403
+        raise AuthenticationError, build_error_message(response)
+      else
+        raise ApiError, build_error_message(response)
+      end
+    end
+
+    def parse_jsonl(body)
+      body.each_line.filter_map do |line|
+        line = line.strip
+        next if line.empty?
+
+        JSON.parse(line)
+      end
+    end
+
+    def build_error_message(response)
+      body = begin
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        { "error" => response.body }
+      end
+
+      message = body["error"] || body["message"] || response.body
+      "HTTP #{response.code}: #{message}"
+    end
+
+    def build_uri(path, params = {}, base_url: @config.base_url)
+      uri = URI("#{base_url}#{path}")
+      uri.query = URI.encode_www_form(params.compact) unless params.empty?
+      uri
+    end
+  end
+end

data/lib/mpql/configuration.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Mpql
+  class Configuration
+    REGIONS = {
+      "us" => "https://mixpanel.com",
+      "eu" => "https://eu.mixpanel.com",
+      "in" => "https://in.mixpanel.com"
+    }.freeze
+
+    DATA_REGIONS = {
+      "us" => "https://data.mixpanel.com",
+      "eu" => "https://data-eu.mixpanel.com",
+      "in" => "https://data-in.mixpanel.com"
+    }.freeze
+
+    attr_accessor :username, :secret, :project_id, :region
+
+    def initialize
+      @username = nil
+      @secret = nil
+      @project_id = nil
+      @region = "us"
+
+      load_config_file
+      load_env
+    end
+
+    def base_url
+      REGIONS.fetch(@region, REGIONS["us"])
+    end
+
+    def data_base_url
+      DATA_REGIONS.fetch(@region, DATA_REGIONS["us"])
+    end
+
+    def validate!
+      errors = []
+      errors << "MIXPANEL_USERNAME is not set" unless @username
+      errors << "MIXPANEL_SECRET is not set" unless @secret
+      errors << "project_id is not set" unless @project_id
+
+      raise ConfigurationError, errors.join(", ") unless errors.empty?
+    end
+
+    private
+
+    def load_config_file
+      config_path = File.expand_path("~/.mpql.yml")
+      return unless File.exist?(config_path)
+
+      config = YAML.safe_load_file(config_path, permitted_classes: [Symbol])
+      return unless config.is_a?(Hash)
+
+      @username = config["username"] || config[:username]
+      @secret = config["secret"] || config[:secret]
+    end
+
+    def load_env
+      @username = ENV["MIXPANEL_USERNAME"] if ENV["MIXPANEL_USERNAME"]
+      @secret = ENV["MIXPANEL_SECRET"] if ENV["MIXPANEL_SECRET"]
+    end
+  end
+end

data/lib/mpql/date_parser.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Mpql
+  module DateParser
+    module_function
+
+    # Parse a date string into yyyy-mm-dd format.
+    #
+    # Supported formats:
+    #   - "today"      -> today's date
+    #   - "yesterday"  -> yesterday's date
+    #   - "Nd"         -> N days ago (e.g., "7d")
+    #   - "Nw"         -> N weeks ago (e.g., "3w")
+    #   - "Nm"         -> N months ago (e.g., "1m")
+    #   - "yyyy-mm-dd" -> passed through as-is
+    def parse(input)
+      case input.to_s.strip.downcase
+      when "today"
+        Date.today.strftime("%Y-%m-%d")
+      when "yesterday"
+        (Date.today - 1).strftime("%Y-%m-%d")
+      when /\A(\d+)d\z/
+        (Date.today - ::Regexp.last_match(1).to_i).strftime("%Y-%m-%d")
+      when /\A(\d+)w\z/
+        (Date.today - (::Regexp.last_match(1).to_i * 7)).strftime("%Y-%m-%d")
+      when /\A(\d+)m\z/
+        (Date.today << ::Regexp.last_match(1).to_i).strftime("%Y-%m-%d")
+      when /\A\d{4}-\d{2}-\d{2}\z/
+        Date.parse(input.strip).strftime("%Y-%m-%d")
+      else
+        raise InputError, "Invalid date format: '#{input}'. Use yyyy-mm-dd, today, yesterday, Nd, Nw, or Nm"
+      end
+    end
+  end
+end

data/lib/mpql/formatters/json_formatter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mpql
+  module Formatters
+    class JsonFormatter
+      def initialize(data, raw: false)
+        @data = data
+        @raw = raw
+      end
+
+      def render
+        if @raw
+          JSON.generate(@data)
+        else
+          JSON.pretty_generate(@data)
+        end
+      end
+    end
+  end
+end

data/lib/mpql/formatters/row_builder.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Mpql
+  module Formatters
+    class RowBuilder
+      attr_reader :headers, :rows
+
+      def initialize(data)
+        @headers, @rows = build_table(data)
+      end
+
+      private
+
+      def build_table(data)
+        case data
+        when Array
+          build_from_array(data)
+        when Hash
+          build_from_hash(data)
+        else
+          [nil, [[data]]]
+        end
+      end
+
+      def build_from_array(data)
+        return [nil, []] if data.empty?
+
+        if data.all?(Hash)
+          headers = data.flat_map(&:keys).uniq
+          rows = data.map { |item| headers.map { |h| item[h] } }
+          [headers, rows]
+        else
+          [nil, data.map { |item| [item] }]
+        end
+      end
+
+      def build_from_hash(data)
+        if segmentation_data?(data)
+          build_from_segmentation(data)
+        elsif engage_data?(data)
+          build_from_engage(data)
+        elsif funnel_data?(data)
+          build_from_funnel(data)
+        elsif retention_data?(data)
+          build_from_retention(data)
+        else
+          build_from_flat_hash(data)
+        end
+      end
+
+      def segmentation_data?(data)
+        data.key?("data") &&
+          data["data"].is_a?(Hash) &&
+          data["data"].key?("values") &&
+          data["data"].key?("series")
+      end
+
+      def build_from_segmentation(data)
+        series = data["data"]["series"]
+        values = data["data"]["values"]
+        headers = ["segment"] + series
+        rows = values.map do |segment, date_values|
+          [segment] + series.map { |date| date_values[date] }
+        end
+        [headers, rows]
+      end
+
+      def engage_data?(data)
+        data.key?("results") && data["results"].is_a?(Array)
+      end
+
+      def build_from_engage(data)
+        results = data["results"]
+        return [nil, []] if results.empty?
+
+        rows = results.map { |r| flatten_hash(r) }
+        headers = rows.flat_map(&:keys).uniq
+        table_rows = rows.map { |r| headers.map { |h| r[h] } }
+        [headers, table_rows]
+      end
+
+      def funnel_data?(data)
+        data.key?("data") &&
+          data["data"].is_a?(Hash) &&
+          data["data"].values.any? { |v| v.is_a?(Hash) && v.key?("steps") }
+      end
+
+      def build_from_funnel(data)
+        headers = %w[date step_idx event count step_conv_ratio overall_conv_ratio]
+        rows = []
+        data["data"].each do |date, date_data|
+          next unless date_data.is_a?(Hash) && date_data["steps"].is_a?(Array)
+
+          date_data["steps"].each_with_index do |step, idx|
+            rows << [
+              date,
+              idx + 1,
+              step["event"],
+              step["count"],
+              step["step_conv_ratio"],
+              step["overall_conv_ratio"]
+            ]
+          end
+        end
+        [headers, rows]
+      end
+
+      def retention_data?(data)
+        data.key?("data") &&
+          data["data"].is_a?(Hash) &&
+          !data["data"].key?("series")
+      end
+
+      def build_from_retention(data)
+        build_from_flat_hash(data)
+      end
+
+      def build_from_flat_hash(data)
+        flat = flatten_hash(data)
+        headers = %w[key value]
+        rows = flat.map { |k, v| [k, v] }
+        [headers, rows]
+      end
+
+      def flatten_hash(hash, prefix = nil)
+        hash.each_with_object({}) do |(key, value), result|
+          full_key = prefix ? "#{prefix}.#{key}" : key.to_s
+          case value
+          when Hash
+            result.merge!(flatten_hash(value, full_key))
+          when Array
+            if value.all?(Hash)
+              value.each_with_index do |item, i|
+                result.merge!(flatten_hash(item, "#{full_key}.#{i}"))
+              end
+            else
+              result[full_key] = value
+            end
+          else
+            result[full_key] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mpql/formatters/table_formatter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+require "terminal-table"
+require_relative "row_builder"
+
+module Mpql
+  module Formatters
+    class TableFormatter
+      def initialize(data)
+        @builder = RowBuilder.new(data)
+      end
+
+      def render
+        table = Terminal::Table.new(
+          headings: @builder.headers,
+          rows: @builder.rows.map { |row| row.map { |v| format_value(v) } }
+        )
+        table.to_s
+      end
+
+      private
+
+      def format_value(value)
+        case value
+        when nil
+          ""
+        when Hash, Array
+          JSON.generate(value)
+        else
+          value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/mpql/formatters/tsv_formatter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "row_builder"
+
+module Mpql
+  module Formatters
+    class TsvFormatter
+      def initialize(data)
+        @builder = RowBuilder.new(data)
+      end
+
+      def render
+        lines = []
+        lines << @builder.headers.join("\t") if @builder.headers
+        @builder.rows.each { |row| lines << row.map { |v| format_value(v) }.join("\t") }
+        lines.join("\n")
+      end
+
+      private
+
+      def format_value(value)
+        case value
+        when nil
+          ""
+        when String
+          value.gsub("\t", "\\t").gsub("\n", "\\n")
+        when Hash, Array
+          JSON.generate(value).gsub("\t", "\\t").gsub("\n", "\\n")
+        else
+          value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/mpql/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mpql
+  VERSION = "0.0.1"
+end

data/lib/mpql.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "mpql/version"
+
+module Mpql
+  class Error < StandardError; end
+  class AuthenticationError < Error; end
+  class ApiError < Error; end
+  class ConfigurationError < Error; end
+  class InputError < Error; end
+
+  autoload :Configuration, "mpql/configuration"
+  autoload :Client, "mpql/client"
+  autoload :DateParser, "mpql/date_parser"
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: mpql
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- tomorrowkey
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: terminal-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: A command-line tool to execute MixPanel Query API requests. Designed
+  for both human users and AI agents.
+executables:
+- mpql
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/mpql
+- lib/mpql.rb
+- lib/mpql/cli.rb
+- lib/mpql/client.rb
+- lib/mpql/configuration.rb
+- lib/mpql/date_parser.rb
+- lib/mpql/formatters/json_formatter.rb
+- lib/mpql/formatters/row_builder.rb
+- lib/mpql/formatters/table_formatter.rb
+- lib/mpql/formatters/tsv_formatter.rb
+- lib/mpql/version.rb
+homepage: https://github.com/tomorrowkey/mpql
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/tomorrowkey/mpql
+  changelog_uri: https://github.com/tomorrowkey/mpql/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: CLI tool for MixPanel Query API
+test_files: []