pike13 0.1.0.beta → 0.1.0

data/lib/pike13/api/v3/desk/person_plans.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+module Pike13
+  module API
+    module V3
+      module Desk
+        # Person Plans resource
+        # Comprehensive data about passes and plans that are available for use or on hold
+        #
+        # @example Basic query
+        #   Pike13::Reporting::PersonPlans.query(
+        #     fields: ['person_plan_id', 'full_name', 'plan_name', 'is_available', 'start_date']
+        #   )
+        #
+        # @example Query available memberships
+        #   Pike13::Reporting::PersonPlans.query(
+        #     fields: ['full_name', 'plan_name', 'start_date', 'end_date', 'remaining_visit_count'],
+        #     filter: [
+        #       'and',
+        #       [
+        #         ['eq', 'is_available', true],
+        #         ['eq', 'grants_membership', true]
+        #       ]
+        #     ]
+        #   )
+        #
+        # @example Group by plan type
+        #   Pike13::Reporting::PersonPlans.query(
+        #     fields: ['person_plan_count', 'is_available_count', 'is_on_hold_count'],
+        #     group: 'plan_type'
+        #   )
+        class PersonPlans < Base
+          class << self
+            # Execute a person plans query
+            #
+            # @param fields [Array<String>] Fields to return (detail or summary fields)
+            # @param filter [Array, nil] Filter criteria (optional)
+            # @param group [String, nil] Grouping field (optional)
+            # @param sort [Array<String>, nil] Sort order (optional)
+            # @param page [Hash, nil] Pagination options (optional)
+            # @param total_count [Boolean] Whether to return total count (optional)
+            # @return [Hash] Query result with rows, fields, and metadata
+            #
+            # @see https://developer.pike13.com/docs/api/v3/reports/person-plans
+            def query(fields:, filter: nil, group: nil, sort: nil, page: nil, total_count: nil)
+              query_params = { fields: fields }
+              query_params[:filter] = filter if filter
+              query_params[:group] = group if group
+              query_params[:sort] = sort if sort
+              query_params[:page] = page if page
+              query_params[:total_count] = total_count if total_count
+
+              super("person_plans", query_params)
+            end
+
+            # Available detail fields (when not grouping)
+            DETAIL_FIELDS = %w[
+              account_manager_emails
+              account_manager_names
+              account_manager_phones
+              allowed_visit_count
+              are_visits_shared
+              base_price
+              business_id
+              business_name
+              business_subdomain
+              canceled_at
+              canceled_by
+              canceled_by_account_id
+              cancellation_fee_amount
+              charged_cancellation_fee_amount
+              commitment_length
+              completed_visit_count
+              currency_code
+              deactivated_at
+              email
+              end_date
+              exhausted_at
+              first_name
+              first_visit_date
+              first_visit_day
+              first_visit_instructor_names
+              first_visit_time
+              first_visit_to_next_plan
+              franchise_id
+              full_name
+              grants_membership
+              has_cancellation_fee
+              home_location_name
+              invoice_interval_count
+              invoice_interval_unit
+              is_available
+              is_canceled
+              is_cancellation_fee_charged
+              is_complimentary_pass
+              is_deactivated
+              is_deleted
+              is_ended
+              is_exhausted
+              is_first_membership
+              is_first_plan
+              is_last_hold_indefinite
+              is_on_hold
+              is_primary_participant
+              key
+              last_hold_by
+              last_hold_by_account_id
+              last_hold_end_date
+              last_hold_start_date
+              last_name
+              last_usable_date
+              last_visit_date
+              last_visit_day
+              last_visit_time
+              last_visit_to_next_plan
+              latest_invoice_autobill
+              latest_invoice_due_date
+              latest_invoice_item_amount
+              latest_invoice_past_due
+              lifetime_used_visit_count
+              middle_name
+              next_plan_grants_membership
+              next_plan_id
+              next_plan_name
+              next_plan_revenue_category
+              next_plan_start_date
+              next_plan_type
+              person_id
+              person_plan_id
+              plan_id
+              plan_location_id
+              plan_location_name
+              plan_name
+              plan_product_id
+              plan_type
+              primary_staff_name
+              product_id
+              product_name
+              remaining_commitment
+              remaining_visit_count
+              revenue_category
+              rollover_count
+              start_date
+              start_date_to_first_visit
+              start_date_to_next_plan
+              stop_renewing_after_commitment
+              term_acceptance_required
+              term_accepted
+              used_for_initial_visit
+              used_visit_count
+              visit_refresh_interval_count
+              visit_refresh_interval_unit
+            ].freeze
+
+            # Available summary fields (when grouping)
+            SUMMARY_FIELDS = %w[
+              avg_first_visit_to_next_plan
+              avg_last_visit_to_next_plan
+              avg_start_date_to_first_visit
+              avg_start_date_to_next_plan
+              business_id_summary
+              business_subdomain_summary
+              grants_membership_count
+              has_cancellation_fee_count
+              is_available_count
+              is_canceled_count
+              is_complimentary_pass_count
+              is_first_membership_count
+              is_first_plan_count
+              is_on_hold_count
+              latest_invoice_past_due_count
+              next_plan_count
+              next_plan_grants_membership_percent
+              next_plan_on_visit_date_percent
+              next_plan_out_of_visited_percent
+              next_plan_percent
+              next_plan_within_week_percent
+              person_count
+              person_plan_count
+              plan_count
+              total_cancellation_fee_amount
+              total_charged_cancellation_fee_amount
+              total_count
+              total_latest_invoice_item_amount
+              total_lifetime_used_visit_count
+              total_used_for_initial_visit
+              total_used_visit_count
+              visited_count
+              visited_percent
+            ].freeze
+
+            # Available grouping fields
+            GROUPINGS = %w[
+              are_visits_shared
+              business_id
+              business_name
+              business_subdomain
+              canceled_by
+              canceled_by_account_id
+              end_date
+              first_visit_date
+              first_visit_instructor_names
+              first_visit_month_start_date
+              first_visit_quarter_start_date
+              first_visit_week_mon_start_date
+              first_visit_week_sun_start_date
+              first_visit_year_start_date
+              full_name
+              grants_membership
+              has_cancellation_fee
+              home_location_name
+              is_available
+              is_canceled
+              is_cancellation_fee_charged
+              is_complimentary_pass
+              is_deleted
+              is_first_membership
+              is_first_plan
+              is_last_hold_indefinite
+              is_on_hold
+              last_hold_by
+              last_hold_by_account_id
+              last_hold_end_date
+              last_hold_start_date
+              last_usable_date
+              last_usable_month_start_date
+              last_usable_quarter_start_date
+              last_usable_week_mon_start_date
+              last_usable_week_sun_start_date
+              last_usable_year_start_date
+              last_visit_date
+              last_visit_month_start_date
+              last_visit_quarter_start_date
+              last_visit_week_mon_start_date
+              last_visit_week_sun_start_date
+              last_visit_year_start_date
+              latest_invoice_autobill
+              latest_invoice_due_date
+              latest_invoice_past_due
+              person_id
+              plan_id
+              plan_location_id
+              plan_location_name
+              plan_name
+              plan_product_id
+              plan_type
+              primary_staff_name
+              product_id
+              product_name
+              revenue_category
+              start_date
+              start_month_start_date
+              start_quarter_start_date
+              start_week_mon_start_date
+              start_week_sun_start_date
+              start_year_start_date
+              stop_renewing_after_commitment
+              used_for_initial_visit
+            ].freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pike13/api/v3/desk/staff_members.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Pike13
+  module API
+    module V3
+      module Desk
+        # Staff Members resource
+        # All staff member data — from tenure and events to birthdays and custom fields
+        #
+        # @example Basic query
+        #   Pike13::Reporting::StaffMembers.query(
+        #     fields: ['person_id', 'full_name', 'email', 'role', 'person_state']
+        #   )
+        #
+        # @example Query active staff members
+        #   Pike13::Reporting::StaffMembers.query(
+        #     fields: ['full_name', 'email', 'role', 'tenure', 'future_events'],
+        #     filter: ['eq', 'person_state', 'active']
+        #   )
+        #
+        # @example Group by role
+        #   Pike13::Reporting::StaffMembers.query(
+        #     fields: ['person_count', 'total_future_events', 'total_past_events'],
+        #     group: 'role'
+        #   )
+        class StaffMembers < Base
+          class << self
+            # Execute a staff members query
+            #
+            # @param fields [Array<String>] Fields to return (detail or summary fields)
+            # @param filter [Array, nil] Filter criteria (optional)
+            # @param group [String, nil] Grouping field (optional)
+            # @param sort [Array<String>, nil] Sort order (optional)
+            # @param page [Hash, nil] Pagination options (optional)
+            # @param total_count [Boolean] Whether to return total count (optional)
+            # @return [Hash] Query result with rows, fields, and metadata
+            #
+            # @see https://developer.pike13.com/docs/api/v3/reports/staff_members
+            def query(fields:, filter: nil, group: nil, sort: nil, page: nil, total_count: nil)
+              query_params = { fields: fields }
+              query_params[:filter] = filter if filter
+              query_params[:group] = group if group
+              query_params[:sort] = sort if sort
+              query_params[:page] = page if page
+              query_params[:total_count] = total_count if total_count
+
+              super("staff_members", query_params)
+            end
+
+            # Available detail fields (when not grouping)
+            DETAIL_FIELDS = %w[
+              address
+              age
+              also_client
+              attendance_not_completed_events
+              birthdate
+              business_id
+              business_name
+              business_subdomain
+              city
+              country_code
+              currency_code
+              custom_fields
+              days_until_birthday
+              email
+              first_name
+              franchise_id
+              full_name
+              future_events
+              home_location_id
+              home_location_name
+              key
+              last_name
+              middle_name
+              past_events
+              person_id
+              person_state
+              phone
+              postal_code
+              role
+              show_to_clients
+              staff_since_date
+              state_code
+              street_address
+              street_address2
+              tenure
+              tenure_group
+            ].freeze
+
+            # Available summary fields (when grouping)
+            SUMMARY_FIELDS = %w[
+              also_client_count
+              business_id_summary
+              business_subdomain_summary
+              demoted_staff_count
+              person_count
+              total_attendance_not_completed_events
+              total_count
+              total_future_events
+              total_past_events
+            ].freeze
+
+            # Available grouping fields
+            GROUPINGS = %w[
+              age
+              also_client
+              business_id
+              business_name
+              business_subdomain
+              home_location_name
+              person_state
+              role
+              show_to_clients
+              staff_since_date
+              staff_since_month_start_date
+              staff_since_quarter_start_date
+              staff_since_week_mon_start_date
+              staff_since_week_sun_start_date
+              staff_since_year_start_date
+              tenure_group
+            ].freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pike13/api/v3/desk/transactions.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Pike13
+  module API
+    module V3
+      module Desk
+        # Transactions resource
+        # Data about the money moving through your business
+        #
+        # @example Basic query
+        #   Pike13::Reporting::Transactions.query(
+        #     fields: ['transaction_id', 'transaction_date', 'net_paid_amount', 'payment_method']
+        #   )
+        #
+        # @example Query by date range
+        #   Pike13::Reporting::Transactions.query(
+        #     fields: ['transaction_date', 'net_paid_amount', 'invoice_payer_name', 'payment_method'],
+        #     filter: ['btw', 'transaction_date', '2024-01-01', '2024-12-31']
+        #   )
+        #
+        # @example Group by payment method
+        #   Pike13::Reporting::Transactions.query(
+        #     fields: ['total_net_paid_amount', 'transaction_count'],
+        #     group: 'payment_method'
+        #   )
+        class Transactions < Base
+          class << self
+            # Execute a transactions query
+            #
+            # @param fields [Array<String>] Fields to return (detail or summary fields)
+            # @param filter [Array, nil] Filter criteria (optional)
+            # @param group [String, nil] Grouping field (optional)
+            # @param sort [Array<String>, nil] Sort order (optional)
+            # @param page [Hash, nil] Pagination options (optional)
+            # @param total_count [Boolean] Whether to return total count (optional)
+            # @return [Hash] Query result with rows, fields, and metadata
+            #
+            # @see https://developer.pike13.com/docs/api/v3/reports/transactions
+            def query(fields:, filter: nil, group: nil, sort: nil, page: nil, total_count: nil)
+              query_params = { fields: fields }
+              query_params[:filter] = filter if filter
+              query_params[:group] = group if group
+              query_params[:sort] = sort if sort
+              query_params[:page] = page if page
+              query_params[:total_count] = total_count if total_count
+
+              super("transactions", query_params)
+            end
+
+            # Available detail fields (when not grouping)
+            DETAIL_FIELDS = %w[
+              business_id
+              business_name
+              business_subdomain
+              commission_recipient_name
+              created_by_name
+              credit_card_name
+              currency_code
+              error_message
+              external_payment_name
+              failed_at
+              failed_date
+              franchise_id
+              invoice_autobill
+              invoice_due_date
+              invoice_id
+              invoice_number
+              invoice_payer_email
+              invoice_payer_home_location
+              invoice_payer_id
+              invoice_payer_name
+              invoice_payer_phone
+              invoice_payer_primary_staff_name_at_sale
+              invoice_state
+              key
+              net_paid_amount
+              net_paid_revenue_amount
+              net_paid_tax_amount
+              payment_method
+              payment_method_detail
+              payment_transaction_id
+              payments_amount
+              processing_method
+              processor_transaction_id
+              refunds_amount
+              sale_location_name
+              transaction_amount
+              transaction_at
+              transaction_autopay
+              transaction_date
+              transaction_id
+              transaction_state
+              transaction_type
+              voided_at
+            ].freeze
+
+            # Available summary fields (when grouping)
+            SUMMARY_FIELDS = %w[
+              business_id_summary
+              business_subdomain_summary
+              failed_count
+              invoice_count
+              settled_count
+              total_count
+              total_net_ach_paid_amount
+              total_net_american_express_paid_amount
+              total_net_amex_processing_paid_amount
+              total_net_cash_paid_amount
+              total_net_check_paid_amount
+              total_net_credit_paid_amount
+              total_net_discover_paid_amount
+              total_net_external_paid_amount
+              total_net_global_pay_processing_paid_amount
+              total_net_mastercard_paid_amount
+              total_net_other_credit_card_paid_amount
+              total_net_other_processing_paid_amount
+              total_net_paid_amount
+              total_net_paid_revenue_amount
+              total_net_paid_tax_amount
+              total_net_visa_paid_amount
+              total_payments_amount
+              total_refunds_amount
+              transaction_autopay_count
+              transaction_count
+            ].freeze
+
+            # Available grouping fields
+            GROUPINGS = %w[
+              business_id
+              business_name
+              business_subdomain
+              commission_recipient_name
+              created_by_name
+              credit_card_name
+              external_payment_name
+              failed_date
+              failed_month_start_date
+              failed_quarter_start_date
+              failed_week_mon_start_date
+              failed_week_sun_start_date
+              failed_year_start_date
+              invoice_autobill
+              invoice_due_date
+              invoice_id
+              invoice_number
+              invoice_payer_home_location
+              invoice_payer_id
+              invoice_payer_name
+              invoice_payer_primary_staff_name_at_sale
+              invoice_state
+              payment_method
+              processing_method
+              sale_location_name
+              transaction_autopay
+              transaction_date
+              transaction_month_start_date
+              transaction_quarter_start_date
+              transaction_state
+              transaction_type
+              transaction_week_mon_start_date
+              transaction_week_sun_start_date
+              transaction_year_start_date
+            ].freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pike13/http_client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "httparty"
+require "json"
 
 module Pike13
   # HTTParty-based HTTP client for Pike13 API
@@ -162,9 +163,11 @@ module Pike13
       return nil if response.body.nil? || response.body.empty?
 
       parsed = response.parsed_response
+
+      # If parsed response is not a Hash (e.g., it's an Array), return as-is
       return parsed unless parsed.is_a?(Hash)
 
-      # Handle different response formats
+      # Handle different response formats for Hash responses
       if parsed.key?("data")
         parsed["data"]
       else

data/lib/pike13/http_client_v3.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "httparty"
+require "json"
+
+module Pike13
+  # HTTParty-based HTTP client for Pike13 v3 Reporting API
+  # V3 API uses JSON API 1.0 (application/vnd.api+json) and a different URL structure than v2
+  class HTTPClientV3
+    include HTTParty
+
+    attr_reader :base_url, :access_token
+
+    def initialize(base_url:, access_token:)
+      @base_url = base_url
+      @access_token = access_token
+    end
+
+    # POST request for v3 reporting queries
+    #
+    # @param path [String] The API endpoint path
+    # @param body [Hash] Request body
+    # @param params [Hash] Query parameters
+    # @return [Hash] Parsed response body
+    def post(path, body = {}, params = {})
+      handle_response do
+        self.class.post(
+          full_path(path),
+          body: body.to_json,
+          query: params,
+          headers: headers,
+          timeout: 30
+        )
+      end
+    end
+
+    private
+
+    # V3 API uses /desk/api/v3/reports/... structure instead of /api/v2/desk/...
+    def full_path(path)
+      "#{base_url}/#{path}"
+    end
+
+    def headers
+      {
+        "Authorization" => "Bearer #{access_token}",
+        "Content-Type" => "application/vnd.api+json",
+        "Accept" => "application/vnd.api+json"
+      }
+    end
+
+    def handle_response
+      response = yield
+      handle_status_code(response)
+    rescue HTTParty::Error => e
+      raise Pike13::ConnectionError, "Connection failed: #{e.message}"
+    end
+
+    def handle_status_code(response)
+      return parse_response_body(response) if response.code.between?(200, 299)
+
+      raise_error_for_status(response)
+    end
+
+    def raise_error_for_status(response)
+      case response.code
+      when 400 then raise Pike13::BadRequestError.new(response.body, http_status: response.code)
+      when 401 then raise Pike13::UnauthorizedError.new("Unauthorized", http_status: response.code)
+      when 404 then raise Pike13::NotFoundError.new("Resource not found", http_status: response.code)
+      when 422 then raise_validation_error(response)
+      when 429 then raise Pike13::RateLimitError.new("Rate limit exceeded", http_status: response.code)
+      when 500..599 then raise Pike13::ServerError.new("Server error", http_status: response.code)
+      else raise Pike13::APIError.new("Unexpected error", http_status: response.code)
+      end
+    end
+
+    def raise_validation_error(response)
+      parsed = parse_json_safely(response.body)
+      error_message = extract_error_message(parsed, response.body)
+      raise Pike13::ValidationError.new(error_message, http_status: response.code)
+    end
+
+    def parse_json_safely(body)
+      JSON.parse(body)
+    rescue StandardError
+      {}
+    end
+
+    def extract_error_message(parsed, fallback)
+      return fallback unless parsed.is_a?(Hash) && parsed["errors"]
+
+      parsed["errors"].is_a?(Array) ? parsed["errors"].first : parsed["errors"]
+    end
+
+    def parse_response_body(response)
+      return nil if response.body.nil? || response.body.empty?
+
+      response.parsed_response
+    end
+  end
+end