schematichq 1.5.2 → 1.5.3

data/lib/schematic/credits/leases/wire_client.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Schematic
+  module Credits
+    module Leases
+      # What the server says a lease is after an acquire or an extend. It is
+      # also what installs a lease into a store: the local balance is derived,
+      # never supplied.
+      LeaseGrant = Struct.new(:lease_id, :company_id, :credit_type_id, :granted_amount, :expires_at,
+                              keyword_init: true)
+
+      # The lease lifecycle over the generated API client. Separated from
+      # LeaseManager so tests and the conformance runner can script the wire.
+      #
+      # Both calls take the client's default retry policy. Acquire is safe to
+      # retry because the server hands back the slot's existing active lease
+      # rather than opening a second one. An extend is an increment, so a retry
+      # after a lost response would grant the tranche twice; the request carries
+      # an idempotency key minted once per extend to collapse them.
+      class ApiWireClient
+        def initialize(credits_client:)
+          @credits = credits_client
+        end
+
+        def acquire(company_id:, credit_type_id:, requested_amount:, expires_at:, request_options: {})
+          response = @credits.acquire_credit_lease(
+            request_options: request_options,
+            company_id: company_id,
+            credit_type_id: credit_type_id,
+            # Rounded up, not to nearest: the API takes a whole number, and a
+            # shortfall of 10.4 asked for as 10 leaves the retried reserve short
+            # by the same fraction every time.
+            requested_amount: Leases.wire_quantity(requested_amount),
+            expires_at: expires_at.utc.iso8601
+          )
+          grant_from(response)
+        end
+
+        def extend(lease_id:, additional_amount:, expires_at:, idempotency_key: nil, request_options: {})
+          body = {
+            lease_id: lease_id,
+            additional_amount: Leases.wire_quantity(additional_amount),
+            expires_at: expires_at.utc.iso8601,
+            # The key is minted once here, outside the retry loop, so every
+            # attempt of this extend carries the same one and the server folds
+            # them into a single increment. A caller that already minted one
+            # keeps it: the manager does, so its single-flight followers settle
+            # against the same key.
+            idempotency_key: idempotency_key || SecureRandom.uuid
+          }
+          grant_from(@credits.extend_credit_lease(request_options: request_options, **body))
+        end
+
+        def release(lease_id:, request_options: {})
+          @credits.release_credit_lease(request_options: request_options, lease_id: lease_id)
+          nil
+        end
+
+        private
+
+        def grant_from(response)
+          data = response&.data
+          raise "credit lease response carried no data" if data.nil?
+
+          LeaseGrant.new(
+            lease_id: data.id,
+            company_id: data.company_id,
+            credit_type_id: data.credit_type_id,
+            granted_amount: data.granted_amount.to_f,
+            expires_at: parse_time(data.expires_at)
+          )
+        end
+
+        def parse_time(value)
+          Leases.parse_api_time(value)
+        end
+      end
+    end
+  end
+end

data/lib/schematic/credits/types/acquire_credit_lease_request_body.rb

@@ -11,6 +11,8 @@ module Schematic
         field :expires_at, -> { String }, optional: true, nullable: false
 
         field :requested_amount, -> { Integer }, optional: false, nullable: false
+
+        field :user_id, -> { String }, optional: true, nullable: false
       end
     end
   end

data/lib/schematic/credits/types/create_credit_spend_policy_request_body.rb

@@ -10,9 +10,13 @@ module Schematic
 
         field :label, -> { String }, optional: true, nullable: false
 
-        field :max_per_draw, -> { Integer }, optional: false, nullable: false
+        field :max_per_draw, -> { Integer }, optional: true, nullable: false
 
         field :user_id, -> { String }, optional: true, nullable: false
+
+        field :window_amount, -> { Integer }, optional: true, nullable: false
+
+        field :window_unit, -> { Schematic::Types::CreditSpendWindowUnit }, optional: true, nullable: false
       end
     end
   end

data/lib/schematic/credits/types/extend_credit_lease_request_body.rb

@@ -11,6 +11,8 @@ module Schematic
         field :expires_at, -> { String }, optional: true, nullable: false
 
         field :idempotency_key, -> { String }, optional: true, nullable: false
+
+        field :user_id, -> { String }, optional: true, nullable: false
       end
     end
   end

data/lib/schematic/credits/types/get_credit_spend_policy_usage_params.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Credits
+    module Types
+      # Input parameters
+      class GetCreditSpendPolicyUsageParams < Internal::Types::Model
+        field :billing_credit_id, -> { String }, optional: true, nullable: false
+
+        field :company_id, -> { String }, optional: true, nullable: false
+
+        field :user_ids, -> { Internal::Types::Array[String] }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/credits/types/get_credit_spend_policy_usage_request.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Credits
+    module Types
+      class GetCreditSpendPolicyUsageRequest < Internal::Types::Model
+        field :billing_credit_id, -> { String }, optional: true, nullable: false
+
+        field :company_id, -> { String }, optional: false, nullable: false
+
+        field :user_ids, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/credits/types/get_credit_spend_policy_usage_response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Credits
+    module Types
+      class GetCreditSpendPolicyUsageResponse < Internal::Types::Model
+        field :data, -> { Internal::Types::Array[Schematic::Types::CreditSpendPolicyResponseData] }, optional: false, nullable: false
+
+        field :params, -> { Schematic::Credits::Types::GetCreditSpendPolicyUsageParams }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/credits/types/update_credit_spend_policy_request_body.rb

@@ -9,6 +9,10 @@ module Schematic
         field :label, -> { String }, optional: true, nullable: false
 
         field :max_per_draw, -> { Integer }, optional: true, nullable: false
+
+        field :window_amount, -> { Integer }, optional: true, nullable: false
+
+        field :window_unit, -> { Schematic::Types::CreditSpendWindowUnit }, optional: true, nullable: false
       end
     end
   end

data/lib/schematic/datastream/client.rb

@@ -146,7 +146,11 @@ module Schematic
       # Raises DataStream::EvaluationError when the flag cannot be evaluated
       # locally (e.g. flag not in cache, rules engine unavailable), so the caller
       # can fall back to the API path.
-      def check_flag(eval_ctx, flag_key)
+      # options carries the caller's preflight (a simulated usage, an
+      # event-scoped usage, or a per-credit cost) through to the engine, so a
+      # client-side evaluation gates on the post-call balance. Nil evaluates the
+      # flag as it stands.
+      def check_flag(eval_ctx, flag_key, options = nil)
         flag = get_flag(flag_key)
         raise EvaluationError, "flag '#{flag_key}' not found in cache" unless flag
 
@@ -172,12 +176,22 @@ module Schematic
         end
 
         @logger.debug("Evaluating flag with rules engine: flag=#{flag_key}, company=#{company&.dig(:id)}, user=#{user&.dig(:id)}")
-        result = @rules_engine.check_flag(flag, company, user)
+        result = @rules_engine.check_flag_with_options(flag, company, user, options)
         @logger.debug("Rules engine evaluation result: value=#{result[:value]}, reason=#{result[:reason]}")
         result[:flag_key] = flag_key
         result
       end
 
+      # Evaluate a flag against an explicit company and user with preflight
+      # options, skipping the cache lookups check_flag does. The credit-lease
+      # path has already resolved both entities and needs to gate against a
+      # substituted credit balance, which only it can build.
+      def check_flag_with_options(flag, company, user, options)
+        raise EvaluationError, "rules engine not available" unless @rules_engine&.initialized?
+
+        @rules_engine.check_flag_with_options(flag, company, user, options)
+      end
+
       def update_company_metrics(company_keys, event_name, quantity)
         company = @company_cache.get_by_keys(company_keys)
         return unless company
@@ -231,6 +245,10 @@ module Schematic
         return cached if cached
 
         return nil if @replicator_mode
+        # A request sent over a closed socket is dropped without an error, so
+        # waiting on it just burns the resource timeout. Answer now and let the
+        # caller fall back.
+        return nil unless connected?
 
         request_entity(ENTITY_TYPE_COMPANY, keys, @pending_companies) do |_data|
           @company_cache.get_by_keys(keys)
@@ -242,6 +260,7 @@ module Schematic
         return cached if cached
 
         return nil if @replicator_mode
+        return nil unless connected?
 
         request_entity(ENTITY_TYPE_USER, keys, @pending_users) do |_data|
           @user_cache.get_by_keys(keys)
@@ -513,6 +532,17 @@ module Schematic
         @logger.info("Replicator is no longer ready") if was_ready
         @logger.warn("Replicator health check error: #{e.message}")
       end
+
+      # The cached company for these keys, without the fetch get_company falls
+      # back to. prewarm polls this to resolve a company id from secondary keys.
+      def get_cached_company(keys)
+        @company_cache.get_by_keys(keys)
+      end
+
+      # Cache-first flag and entity lookups, declared public after their
+      # definitions. The credit-lease check path resolves the flag, the company,
+      # and the user itself before evaluating, so it needs all three.
+      public :get_flag, :get_company, :get_user, :get_cached_company
     end
   end
 end

data/lib/schematic/entitlements/client.rb

@@ -1196,6 +1196,171 @@ module Schematic
         end
       end
 
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :company_id
+      # @option params [String, nil] :end_time
+      # @option params [String, nil] :start_time
+      #
+      # @example
+      #   client.entitlements.get_company_user_usage_metrics(
+      #     company_id: "company_id",
+      #     end_time: "2024-01-15T09:30:00Z",
+      #     start_time: "2024-01-15T09:30:00Z"
+      #   )
+      #
+      # @return [Schematic::Entitlements::Types::GetCompanyUserUsageMetricsResponse]
+      def get_company_user_usage_metrics(request_options: {}, **params)
+        params = Schematic::Internal::Types::Utils.normalize_keys(params)
+        query_params = {}
+        query_params["company_id"] = params[:company_id] if params.key?(:company_id)
+        query_params["end_time"] = params[:end_time] if params.key?(:end_time)
+        query_params["start_time"] = params[:start_time] if params.key?(:start_time)
+
+        request = Schematic::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "user-usage-by-company/metrics",
+          query: query_params,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Schematic::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          (response.body.to_s.empty? ? nil : Schematic::Entitlements::Types::GetCompanyUserUsageMetricsResponse.load(response.body))
+        else
+          error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :company_id
+      # @option params [String, nil] :end_time
+      # @option params [String, nil] :feature_id
+      # @option params [Schematic::Types::UserUsageMetric] :metric
+      # @option params [Integer, nil] :limit
+      # @option params [Integer, nil] :offset
+      # @option params [String, nil] :start_time
+      #
+      # @example
+      #   client.entitlements.list_company_user_usage(
+      #     company_id: "company_id",
+      #     end_time: "2024-01-15T09:30:00Z",
+      #     feature_id: "feature_id",
+      #     metric: "credits",
+      #     limit: 1000000,
+      #     offset: 1000000,
+      #     start_time: "2024-01-15T09:30:00Z"
+      #   )
+      #
+      # @return [Schematic::Entitlements::Types::ListCompanyUserUsageResponse]
+      def list_company_user_usage(request_options: {}, **params)
+        params = Schematic::Internal::Types::Utils.normalize_keys(params)
+        query_params = {}
+        query_params["company_id"] = params[:company_id] if params.key?(:company_id)
+        query_params["end_time"] = params[:end_time] if params.key?(:end_time)
+        query_params["feature_id"] = params[:feature_id] if params.key?(:feature_id)
+        query_params["metric"] = params[:metric] if params.key?(:metric)
+        query_params["limit"] = params[:limit] if params.key?(:limit)
+        query_params["offset"] = params[:offset] if params.key?(:offset)
+        query_params["start_time"] = params[:start_time] if params.key?(:start_time)
+
+        request = Schematic::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "user-usage-by-company/users",
+          query: query_params,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Schematic::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          (response.body.to_s.empty? ? nil : Schematic::Entitlements::Types::ListCompanyUserUsageResponse.load(response.body))
+        else
+          error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :company_id
+      # @option params [String, nil] :end_time
+      # @option params [String, nil] :feature_id
+      # @option params [Schematic::Types::UserUsageMetric] :metric
+      # @option params [Integer, nil] :limit
+      # @option params [Integer, nil] :offset
+      # @option params [String, nil] :start_time
+      #
+      # @example
+      #   client.entitlements.count_company_user_usage(
+      #     company_id: "company_id",
+      #     end_time: "2024-01-15T09:30:00Z",
+      #     feature_id: "feature_id",
+      #     metric: "credits",
+      #     limit: 1000000,
+      #     offset: 1000000,
+      #     start_time: "2024-01-15T09:30:00Z"
+      #   )
+      #
+      # @return [Schematic::Entitlements::Types::CountCompanyUserUsageResponse]
+      def count_company_user_usage(request_options: {}, **params)
+        params = Schematic::Internal::Types::Utils.normalize_keys(params)
+        query_params = {}
+        query_params["company_id"] = params[:company_id] if params.key?(:company_id)
+        query_params["end_time"] = params[:end_time] if params.key?(:end_time)
+        query_params["feature_id"] = params[:feature_id] if params.key?(:feature_id)
+        query_params["metric"] = params[:metric] if params.key?(:metric)
+        query_params["limit"] = params[:limit] if params.key?(:limit)
+        query_params["offset"] = params[:offset] if params.key?(:offset)
+        query_params["start_time"] = params[:start_time] if params.key?(:start_time)
+
+        request = Schematic::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "user-usage-by-company/users/count",
+          query: query_params,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Schematic::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          (response.body.to_s.empty? ? nil : Schematic::Entitlements::Types::CountCompanyUserUsageResponse.load(response.body))
+        else
+          error_class = Schematic::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
       # @param request_options [Hash]
       # @param params [Hash]
       # @option request_options [String] :base_url

data/lib/schematic/entitlements/types/count_company_user_usage_params.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Entitlements
+    module Types
+      # Input parameters
+      class CountCompanyUserUsageParams < Internal::Types::Model
+        field :company_id, -> { String }, optional: true, nullable: false
+
+        field :end_time, -> { String }, optional: true, nullable: false
+
+        field :feature_id, -> { String }, optional: true, nullable: false
+
+        field :limit, -> { Integer }, optional: true, nullable: false
+
+        field :metric, -> { Schematic::Types::UserUsageMetric }, optional: true, nullable: false
+
+        field :offset, -> { Integer }, optional: true, nullable: false
+
+        field :start_time, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/entitlements/types/count_company_user_usage_request.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Entitlements
+    module Types
+      class CountCompanyUserUsageRequest < Internal::Types::Model
+        field :company_id, -> { String }, optional: false, nullable: false
+
+        field :end_time, -> { String }, optional: true, nullable: false
+
+        field :feature_id, -> { String }, optional: true, nullable: false
+
+        field :metric, -> { Schematic::Types::UserUsageMetric }, optional: false, nullable: false
+
+        field :limit, -> { Integer }, optional: true, nullable: false
+
+        field :offset, -> { Integer }, optional: true, nullable: false
+
+        field :start_time, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/entitlements/types/count_company_user_usage_response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Entitlements
+    module Types
+      class CountCompanyUserUsageResponse < Internal::Types::Model
+        field :data, -> { Schematic::Types::CountResponse }, optional: false, nullable: false
+
+        field :params, -> { Schematic::Entitlements::Types::CountCompanyUserUsageParams }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/entitlements/types/get_company_user_usage_metrics_params.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Entitlements
+    module Types
+      # Input parameters
+      class GetCompanyUserUsageMetricsParams < Internal::Types::Model
+        field :company_id, -> { String }, optional: true, nullable: false
+
+        field :end_time, -> { String }, optional: true, nullable: false
+
+        field :start_time, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/entitlements/types/get_company_user_usage_metrics_request.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Entitlements
+    module Types
+      class GetCompanyUserUsageMetricsRequest < Internal::Types::Model
+        field :company_id, -> { String }, optional: false, nullable: false
+
+        field :end_time, -> { String }, optional: true, nullable: false
+
+        field :start_time, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/entitlements/types/get_company_user_usage_metrics_response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Entitlements
+    module Types
+      class GetCompanyUserUsageMetricsResponse < Internal::Types::Model
+        field :data, -> { Schematic::Types::CompanyUserUsageMetricsResponseData }, optional: false, nullable: false
+
+        field :params, -> { Schematic::Entitlements::Types::GetCompanyUserUsageMetricsParams }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/entitlements/types/list_company_user_usage_params.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Entitlements
+    module Types
+      # Input parameters
+      class ListCompanyUserUsageParams < Internal::Types::Model
+        field :company_id, -> { String }, optional: true, nullable: false
+
+        field :end_time, -> { String }, optional: true, nullable: false
+
+        field :feature_id, -> { String }, optional: true, nullable: false
+
+        field :limit, -> { Integer }, optional: true, nullable: false
+
+        field :metric, -> { Schematic::Types::UserUsageMetric }, optional: true, nullable: false
+
+        field :offset, -> { Integer }, optional: true, nullable: false
+
+        field :start_time, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/entitlements/types/list_company_user_usage_request.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Entitlements
+    module Types
+      class ListCompanyUserUsageRequest < Internal::Types::Model
+        field :company_id, -> { String }, optional: false, nullable: false
+
+        field :end_time, -> { String }, optional: true, nullable: false
+
+        field :feature_id, -> { String }, optional: true, nullable: false
+
+        field :metric, -> { Schematic::Types::UserUsageMetric }, optional: false, nullable: false
+
+        field :limit, -> { Integer }, optional: true, nullable: false
+
+        field :offset, -> { Integer }, optional: true, nullable: false
+
+        field :start_time, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/entitlements/types/list_company_user_usage_response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Entitlements
+    module Types
+      class ListCompanyUserUsageResponse < Internal::Types::Model
+        field :data, -> { Schematic::Types::CompanyUserUsageResponseData }, optional: false, nullable: false
+
+        field :params, -> { Schematic::Entitlements::Types::ListCompanyUserUsageParams }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/plangroups/client.rb

@@ -80,6 +80,7 @@ module Schematic
       #     proration_behavior: "create_prorations",
       #     show_as_monthly_prices: true,
       #     show_credits: true,
+      #     show_estimated_total: true,
       #     show_feature_description: true,
       #     show_hard_limit: true,
       #     show_period_toggle: true,
@@ -144,6 +145,7 @@ module Schematic
       #     proration_behavior: "create_prorations",
       #     show_as_monthly_prices: true,
       #     show_credits: true,
+      #     show_estimated_total: true,
       #     show_feature_description: true,
       #     show_hard_limit: true,
       #     show_period_toggle: true,

data/lib/schematic/plangroups/types/create_plan_group_request_body.rb

@@ -62,6 +62,8 @@ module Schematic
 
         field :show_credits, -> { Internal::Types::Boolean }, optional: false, nullable: false
 
+        field :show_estimated_total, -> { Internal::Types::Boolean }, optional: false, nullable: false
+
         field :show_feature_description, -> { Internal::Types::Boolean }, optional: false, nullable: false
 
         field :show_hard_limit, -> { Internal::Types::Boolean }, optional: false, nullable: false

data/lib/schematic/plangroups/types/update_plan_group_request_body.rb

@@ -64,6 +64,8 @@ module Schematic
 
         field :show_credits, -> { Internal::Types::Boolean }, optional: false, nullable: false
 
+        field :show_estimated_total, -> { Internal::Types::Boolean }, optional: false, nullable: false
+
         field :show_feature_description, -> { Internal::Types::Boolean }, optional: false, nullable: false
 
         field :show_hard_limit, -> { Internal::Types::Boolean }, optional: false, nullable: false