schematichq 1.4.2 → 1.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d21af200007a5f9fad7ebc682971bbad191e98c0b5f7cd10b691627651069c7
-  data.tar.gz: e944d620948b8acdb24d375eed9365982edf50c8ff089a6f4c74821cbb88a4c3
+  metadata.gz: beede11cf31a32d41acacecfcf43f24d415952cc1bfc02ae762593885d804030
+  data.tar.gz: ca42025157214fcc6b06ce6313ce591ed78d7f9e49f033f6aad432dcef691097
 SHA512:
-  metadata.gz: 980692b9e74fbbf6683623e2502bd5ef153d78f5c20245bdb5d3cc26787eaa142f6ac345ba5873acfb29a2fa93a2e0c0beab40717c692e5f3154d731219fad9d
-  data.tar.gz: 0f16bc4c9d391123750a85530d21a7a4a841cf8962d2cc867912f2935f0627e732cbff5c1c56ed677302704636290f962794066c18d9cb6f4e2d74dc63f3890d
+  metadata.gz: f36aa806e79e4dc3c547fd9580b021f616c1b187c659eb7f0784e28983cc5a1bf74f6c32b32edbca0234d0df3372b34aefb6974c0f2e21a059c6bfd56e91682d
+  data.tar.gz: e8fb63d038eedf92d7fd992b18cd94931d599abe632640cb44b482eada7161392c8a373e18494b44c5acfbba3909ef1b4b61d3120763538630d68c0ceb9a7105

data/.fern/metadata.json

@@ -13,6 +13,6 @@
       "webrick": ">= 1.0"
     }
   },
-  "originGitCommit": "3dc12b536625ca1efbb649f6c55df7da258c7e05",
-  "sdkVersion": "1.4.2"
+  "originGitCommit": "ad1cc528e658e3693935b819c9d22eed02d49017",
+  "sdkVersion": "1.4.4"
 }

data/README.md

@@ -127,7 +127,7 @@ client = Schematic::SchematicClient.new(
 client.close
 ```
 
-You can also adjust the log level of the built-in console logger:
+You can also adjust the log level of the built-in console logger via the `log_level` option:
 
 ```ruby
 require "schematichq"
@@ -135,11 +135,11 @@ require "schematichq"
 api_key = ENV["SCHEMATIC_API_KEY"]
 client = Schematic::SchematicClient.new(
   api_key: api_key,
-  logger: Schematic::ConsoleLogger.new(level: :debug)
+  log_level: :debug
 )
 ```
 
-If no logger is provided, the client will use a default console logger at the `:info` level that outputs to stderr.
+If no logger is provided, the client will use a default console logger at the `:warn` level that outputs to stderr. The `log_level` option only applies to this built-in logger; when you supply your own `logger`, its level is left untouched.
 
 ## Usage Examples
 
@@ -216,6 +216,36 @@ client.track({
 })
 ```
 
+#### Event options
+
+Both `track` and `identify` accept an `options:` keyword for optional event metadata. Only fields you set are sent.
+
+```ruby
+client.track(
+  { event: "query-tokens", company: { "id" => "your-company-id" }, quantity: 1500 },
+  options: {
+    # Dedupe key. Duplicate events with the same key are dropped
+    # server-side for 24 hours.
+    idempotency_key: "evt_2026_05_21_query_tokens",
+    # Timestamp the event occurred (Time or ISO 8601 String). Required
+    # when trusted_client_clock is true.
+    sent_at: Time.now.utc,
+    # Use sent_at as the effective event time instead of server receipt
+    # time. Requires a secret API key and sent_at.
+    trusted_client_clock: true,
+    # Import historical data without affecting billing. Requires a secret
+    # API key and trusted_client_clock.
+    backfill: false
+  }
+)
+
+client.identify(
+  { keys: { "user_id" => "your-user-id" }, name: "Wile E. Coyote" },
+  # identify only supports idempotency_key.
+  options: { idempotency_key: "ident_your-user-id" }
+)
+```
+
 ### Creating and updating companies
 
 Although it is faster to create companies and users via identify events, if you need to handle a response, you can use the companies API to upsert companies. Because you use your own identifiers to identify companies, rather than a Schematic company ID, creating and updating companies are both done via the same upsert operation:

data/WASM_VERSION

@@ -1 +1 @@
-0.1.0
+0.3.0

data/lib/schematic/accounts/client.rb

@@ -86,6 +86,50 @@ 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, nil] :ids
+      # @option params [String, nil] :q
+      # @option params [Integer, nil] :limit
+      # @option params [Integer, nil] :offset
+      #
+      # @return [Schematic::Accounts::Types::CountAccountMembersResponse]
+      def count_account_members(request_options: {}, **params)
+        params = Schematic::Internal::Types::Utils.normalize_keys(params)
+        query_param_names = %i[ids q limit offset]
+        query_params = {}
+        query_params["ids"] = params[:ids] if params.key?(:ids)
+        query_params["q"] = params[:q] if params.key?(:q)
+        query_params["limit"] = params[:limit] if params.key?(:limit)
+        query_params["offset"] = params[:offset] if params.key?(:offset)
+        params.except(*query_param_names)
+
+        request = Schematic::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "account-members/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)
+          Schematic::Accounts::Types::CountAccountMembersResponse.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/accounts/types/count_account_members_params.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Accounts
+    module Types
+      # Input parameters
+      class CountAccountMembersParams < Internal::Types::Model
+        field :ids, -> { Internal::Types::Array[String] }, optional: true, nullable: false
+        field :limit, -> { Integer }, optional: true, nullable: false
+        field :offset, -> { Integer }, optional: true, nullable: false
+        field :q, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/accounts/types/count_account_members_request.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Accounts
+    module Types
+      class CountAccountMembersRequest < Internal::Types::Model
+        field :ids, -> { String }, optional: true, nullable: false
+        field :q, -> { String }, optional: true, nullable: false
+        field :limit, -> { Integer }, optional: true, nullable: false
+        field :offset, -> { Integer }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/accounts/types/count_account_members_response.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Accounts
+    module Types
+      class CountAccountMembersResponse < Internal::Types::Model
+        field :data, -> { Schematic::Types::CountResponse }, optional: false, nullable: false
+        field :params, -> { Schematic::Accounts::Types::CountAccountMembersParams }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/billing/client.rb

@@ -442,6 +442,38 @@ 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] :billing_id
+      #
+      # @return [Schematic::Billing::Types::DeletePaymentMethodByExternalIdResponse]
+      def delete_payment_method_by_external_id(request_options: {}, **params)
+        params = Schematic::Internal::Types::Utils.normalize_keys(params)
+        request = Schematic::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "DELETE",
+          path: "billing/payment-methods/#{URI.encode_uri_component(params[:billing_id].to_s)}",
+          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)
+          Schematic::Billing::Types::DeletePaymentMethodByExternalIdResponse.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/billing/types/delete_payment_method_by_external_id_response.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Billing
+    module Types
+      class DeletePaymentMethodByExternalIdResponse < Internal::Types::Model
+        field :data, -> { Schematic::Types::DeleteResponse }, optional: false, nullable: false
+        field :params, -> { Internal::Types::Hash[String, Object] }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/client.rb

@@ -10,7 +10,7 @@ module Schematic
       @raw_client = Schematic::Internal::Http::RawClient.new(
         base_url: base_url || Schematic::Environment::DEFAULT,
         headers: {
-          "User-Agent" => "schematichq/1.4.2",
+          "User-Agent" => "schematichq/1.4.4",
           "X-Fern-Language" => "Ruby",
           "X-Schematic-Api-Key" => api_key.to_s
         }

data/lib/schematic/companies/client.rb

@@ -24,6 +24,7 @@ module Schematic
       # @option params [String, nil] :plan_id
       # @option params [String, nil] :plan_ids
       # @option params [String, nil] :plan_version_id
+      # @option params [String, nil] :plan_version_ids
       # @option params [String, nil] :q
       # @option params [String, nil] :sort_order_column
       # @option params [Schematic::Types::SortDirection, nil] :sort_order_direction
@@ -40,7 +41,7 @@ module Schematic
       # @return [Schematic::Companies::Types::ListCompaniesResponse]
       def list_companies(request_options: {}, **params)
         params = Schematic::Internal::Types::Utils.normalize_keys(params)
-        query_param_names = %i[credit_type_ids has_scheduled_downgrade ids monetized_subscriptions plan_id plan_ids plan_version_id q sort_order_column sort_order_direction subscription_statuses subscription_types with_entitlement_for without_feature_override_for without_plan without_subscription with_subscription limit offset]
+        query_param_names = %i[credit_type_ids has_scheduled_downgrade ids monetized_subscriptions plan_id plan_ids plan_version_id plan_version_ids q sort_order_column sort_order_direction subscription_statuses subscription_types with_entitlement_for without_feature_override_for without_plan without_subscription with_subscription limit offset]
         query_params = {}
         query_params["credit_type_ids"] = params[:credit_type_ids] if params.key?(:credit_type_ids)
         query_params["has_scheduled_downgrade"] = params[:has_scheduled_downgrade] if params.key?(:has_scheduled_downgrade)
@@ -49,6 +50,7 @@ module Schematic
         query_params["plan_id"] = params[:plan_id] if params.key?(:plan_id)
         query_params["plan_ids"] = params[:plan_ids] if params.key?(:plan_ids)
         query_params["plan_version_id"] = params[:plan_version_id] if params.key?(:plan_version_id)
+        query_params["plan_version_ids"] = params[:plan_version_ids] if params.key?(:plan_version_ids)
         query_params["q"] = params[:q] if params.key?(:q)
         query_params["sort_order_column"] = params[:sort_order_column] if params.key?(:sort_order_column)
         query_params["sort_order_direction"] = params[:sort_order_direction] if params.key?(:sort_order_direction)
@@ -203,6 +205,7 @@ module Schematic
       # @option params [String, nil] :plan_id
       # @option params [String, nil] :plan_ids
       # @option params [String, nil] :plan_version_id
+      # @option params [String, nil] :plan_version_ids
       # @option params [String, nil] :q
       # @option params [String, nil] :sort_order_column
       # @option params [Schematic::Types::SortDirection, nil] :sort_order_direction
@@ -219,7 +222,7 @@ module Schematic
       # @return [Schematic::Companies::Types::CountCompaniesResponse]
       def count_companies(request_options: {}, **params)
         params = Schematic::Internal::Types::Utils.normalize_keys(params)
-        query_param_names = %i[credit_type_ids has_scheduled_downgrade ids monetized_subscriptions plan_id plan_ids plan_version_id q sort_order_column sort_order_direction subscription_statuses subscription_types with_entitlement_for without_feature_override_for without_plan without_subscription with_subscription limit offset]
+        query_param_names = %i[credit_type_ids has_scheduled_downgrade ids monetized_subscriptions plan_id plan_ids plan_version_id plan_version_ids q sort_order_column sort_order_direction subscription_statuses subscription_types with_entitlement_for without_feature_override_for without_plan without_subscription with_subscription limit offset]
         query_params = {}
         query_params["credit_type_ids"] = params[:credit_type_ids] if params.key?(:credit_type_ids)
         query_params["has_scheduled_downgrade"] = params[:has_scheduled_downgrade] if params.key?(:has_scheduled_downgrade)
@@ -228,6 +231,7 @@ module Schematic
         query_params["plan_id"] = params[:plan_id] if params.key?(:plan_id)
         query_params["plan_ids"] = params[:plan_ids] if params.key?(:plan_ids)
         query_params["plan_version_id"] = params[:plan_version_id] if params.key?(:plan_version_id)
+        query_params["plan_version_ids"] = params[:plan_version_ids] if params.key?(:plan_version_ids)
         query_params["q"] = params[:q] if params.key?(:q)
         query_params["sort_order_column"] = params[:sort_order_column] if params.key?(:sort_order_column)
         query_params["sort_order_direction"] = params[:sort_order_direction] if params.key?(:sort_order_direction)

data/lib/schematic/companies/types/count_companies_params.rb

@@ -14,6 +14,7 @@ module Schematic
         field :plan_id, -> { String }, optional: true, nullable: false
         field :plan_ids, -> { Internal::Types::Array[String] }, optional: true, nullable: false
         field :plan_version_id, -> { String }, optional: true, nullable: false
+        field :plan_version_ids, -> { Internal::Types::Array[String] }, optional: true, nullable: false
         field :q, -> { String }, optional: true, nullable: false
         field :sort_order_column, -> { String }, optional: true, nullable: false
         field :sort_order_direction, -> { Schematic::Types::SortDirection }, optional: true, nullable: false

data/lib/schematic/companies/types/count_companies_request.rb

@@ -11,6 +11,7 @@ module Schematic
         field :plan_id, -> { String }, optional: true, nullable: false
         field :plan_ids, -> { String }, optional: true, nullable: false
         field :plan_version_id, -> { String }, optional: true, nullable: false
+        field :plan_version_ids, -> { String }, optional: true, nullable: false
         field :q, -> { String }, optional: true, nullable: false
         field :sort_order_column, -> { String }, optional: true, nullable: false
         field :sort_order_direction, -> { Schematic::Types::SortDirection }, optional: true, nullable: false

data/lib/schematic/companies/types/list_companies_params.rb

@@ -14,6 +14,7 @@ module Schematic
         field :plan_id, -> { String }, optional: true, nullable: false
         field :plan_ids, -> { Internal::Types::Array[String] }, optional: true, nullable: false
         field :plan_version_id, -> { String }, optional: true, nullable: false
+        field :plan_version_ids, -> { Internal::Types::Array[String] }, optional: true, nullable: false
         field :q, -> { String }, optional: true, nullable: false
         field :sort_order_column, -> { String }, optional: true, nullable: false
         field :sort_order_direction, -> { Schematic::Types::SortDirection }, optional: true, nullable: false

data/lib/schematic/companies/types/list_companies_request.rb

@@ -11,6 +11,7 @@ module Schematic
         field :plan_id, -> { String }, optional: true, nullable: false
         field :plan_ids, -> { String }, optional: true, nullable: false
         field :plan_version_id, -> { String }, optional: true, nullable: false
+        field :plan_version_ids, -> { String }, optional: true, nullable: false
         field :q, -> { String }, optional: true, nullable: false
         field :sort_order_column, -> { String }, optional: true, nullable: false
         field :sort_order_direction, -> { Schematic::Types::SortDirection }, optional: true, nullable: false

data/lib/schematic/credits/client.rb

@@ -747,6 +747,108 @@ module Schematic
         end
       end
 
+      # @param request_options [Hash]
+      # @param params [Schematic::Credits::Types::AcquireCreditLeaseRequestBody]
+      # @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
+      #
+      # @return [Schematic::Credits::Types::AcquireCreditLeaseResponse]
+      def acquire_credit_lease(request_options: {}, **params)
+        params = Schematic::Internal::Types::Utils.normalize_keys(params)
+        request = Schematic::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "billing/credits/lease",
+          body: Schematic::Credits::Types::AcquireCreditLeaseRequestBody.new(params).to_h,
+          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)
+          Schematic::Credits::Types::AcquireCreditLeaseResponse.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 [Schematic::Credits::Types::ExtendCreditLeaseRequestBody]
+      # @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] :lease_id
+      #
+      # @return [Schematic::Credits::Types::ExtendCreditLeaseResponse]
+      def extend_credit_lease(request_options: {}, **params)
+        params = Schematic::Internal::Types::Utils.normalize_keys(params)
+        request_data = Schematic::Credits::Types::ExtendCreditLeaseRequestBody.new(params).to_h
+        non_body_param_names = ["lease_id"]
+        body = request_data.except(*non_body_param_names)
+
+        request = Schematic::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "PUT",
+          path: "billing/credits/lease/#{URI.encode_uri_component(params[:lease_id].to_s)}/extend",
+          body: body,
+          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)
+          Schematic::Credits::Types::ExtendCreditLeaseResponse.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 [Schematic::Types::ReleaseCreditLeaseRequestBody]
+      # @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] :lease_id
+      #
+      # @return [Schematic::Credits::Types::ReleaseCreditLeaseResponse]
+      def release_credit_lease(request_options: {}, **params)
+        params = Schematic::Internal::Types::Utils.normalize_keys(params)
+        request = Schematic::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "PUT",
+          path: "billing/credits/lease/#{URI.encode_uri_component(params[:lease_id].to_s)}/release",
+          body: 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)
+          Schematic::Credits::Types::ReleaseCreditLeaseResponse.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/credits/types/acquire_credit_lease_request_body.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Credits
+    module Types
+      class AcquireCreditLeaseRequestBody < Internal::Types::Model
+        field :company_id, -> { String }, optional: false, nullable: false
+        field :credit_type_id, -> { String }, optional: false, nullable: false
+        field :expires_at, -> { String }, optional: true, nullable: false
+        field :requested_amount, -> { Integer }, optional: false, nullable: false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Credits
+    module Types
+      class AcquireCreditLeaseResponse < Internal::Types::Model
+        field :data, -> { Schematic::Types::CreditLeaseResponseData }, optional: false, nullable: false
+        field :params, -> { Internal::Types::Hash[String, Object] }, optional: false, nullable: false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Credits
+    module Types
+      class ExtendCreditLeaseRequestBody < Internal::Types::Model
+        field :lease_id, -> { String }, optional: false, nullable: false
+        field :additional_amount, -> { Integer }, optional: false, nullable: false
+        field :expires_at, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Credits
+    module Types
+      class ExtendCreditLeaseResponse < Internal::Types::Model
+        field :data, -> { Schematic::Types::CreditLeaseResponseData }, optional: false, nullable: false
+        field :params, -> { Internal::Types::Hash[String, Object] }, optional: false, nullable: false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Schematic
+  module Credits
+    module Types
+      class ReleaseCreditLeaseResponse < Internal::Types::Model
+        field :data, -> { Schematic::Types::CreditLeaseResponseData }, optional: false, nullable: false
+        field :params, -> { Internal::Types::Hash[String, Object] }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/schematic/datastream/merge.rb

@@ -16,25 +16,42 @@ module Schematic
       COMPANY_MAP_FIELDS = %i[credit_balances keys traits].freeze
       COMPANY_ARRAY_FIELDS = %i[billing_product_ids entitlements plan_ids plan_version_ids rules].freeze
 
+      # Partials don't carry refreshed entitlements, so when their derived
+      # fields change in another part of the company we sync them here to match
+      # server behavior (see schematic-python merge.partial_company):
+      #   - credit_remaining <- credit_balances[credit_id]
+      #   - usage            <- metric value matching (event_name, metric_period, month_reset)
+      # Both are skipped when the partial also sends entitlements wholesale.
       def partial_company(existing, partial_data)
         return existing unless partial_data.is_a?(Hash)
 
         result = deep_copy(existing)
+        entitlements_in_partial = partial_data.key?(:entitlements) || partial_data.key?("entitlements")
+        updated_balances = nil
+        metrics_updated = false
 
         partial_data.each do |key, value|
           sym_key = key.to_sym
           if COMPANY_MAP_FIELDS.include?(sym_key)
             result[sym_key] ||= {}
             result[sym_key] = result[sym_key].merge(value) if value.is_a?(Hash)
+            updated_balances = (value.is_a?(Hash) ? value : {}) if sym_key == :credit_balances
           elsif COMPANY_ARRAY_FIELDS.include?(sym_key)
             result[sym_key] = value if value.is_a?(Array)
           elsif sym_key == :metrics
             result[sym_key] = upsert_metrics(result[sym_key] || [], value || [])
+            metrics_updated = true
           else
             result[sym_key] = value
           end
         end
 
+        if (updated_balances&.any? || metrics_updated) && !entitlements_in_partial
+          result[:entitlements] = sync_entitlements(
+            result[:entitlements], result[:metrics], updated_balances, metrics_updated
+          )
+        end
+
         result
       end
 
@@ -90,6 +107,60 @@ module Schematic
       def get_metric_field(metric, field)
         metric[field] || metric[field.to_s]
       end
+
+      # Re-derive entitlement usage / credit_remaining from the merged metrics
+      # and the just-updated credit balances. Mirrors schematic-python so that
+      # entitlement usage reflects DataStream track events immediately.
+      def sync_entitlements(entitlements, metrics, updated_balances, metrics_updated)
+        return entitlements unless entitlements.is_a?(Array) && !entitlements.empty?
+
+        metrics_lookup = {}
+        if metrics_updated && metrics.is_a?(Array)
+          metrics.each do |metric|
+            next unless metric.is_a?(Hash)
+
+            key = [
+              get_metric_field(metric, :event_subtype) || "",
+              get_metric_field(metric, :period) || "",
+              get_metric_field(metric, :month_reset) || ""
+            ]
+            value = get_metric_field(metric, :value)
+            metrics_lookup[key] = value.nil? ? 0 : value
+          end
+        end
+
+        entitlements.map do |ent|
+          next ent unless ent.is_a?(Hash)
+
+          new_ent = deep_copy(ent)
+
+          credit_id = get_metric_field(ent, :credit_id)
+          if updated_balances && credit_id
+            present, balance = fetch_balance(updated_balances, credit_id)
+            new_ent[:credit_remaining] = balance if present
+          end
+
+          event_name = get_metric_field(ent, :event_name)
+          unless metrics_lookup.empty? || event_name.nil?
+            period = get_metric_field(ent, :metric_period) || "all_time"
+            month_reset = get_metric_field(ent, :month_reset) || "first_of_month"
+            matched = metrics_lookup[[event_name, period, month_reset]]
+            new_ent[:usage] = matched unless matched.nil?
+          end
+
+          new_ent
+        end
+      end
+
+      # The partial's credit_balances may be keyed by string or symbol depending
+      # on how the message was parsed, while an entitlement's credit_id is a
+      # string value, so check both key forms.
+      def fetch_balance(balances, credit_id)
+        return [true, balances[credit_id]] if balances.key?(credit_id)
+        return [true, balances[credit_id.to_sym]] if balances.key?(credit_id.to_sym)
+
+        [false, nil]
+      end
     end
   end
 end

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

@@ -29,6 +29,7 @@ module Schematic
         field :quarterly_unit_price_decimal, -> { String }, optional: true, nullable: false
         field :soft_limit, -> { Integer }, optional: true, nullable: false
         field :tier_mode, -> { Schematic::Types::BillingTiersMode }, optional: true, nullable: false
+        field :usage_quantity, -> { Integer }, optional: true, nullable: false
         field :value_bool, -> { Internal::Types::Boolean }, optional: true, nullable: false
         field :value_credit_id, -> { String }, optional: true, nullable: false
         field :value_numeric, -> { Integer }, optional: true, nullable: false

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

@@ -27,6 +27,7 @@ module Schematic
         field :quarterly_unit_price_decimal, -> { String }, optional: true, nullable: false
         field :soft_limit, -> { Integer }, optional: true, nullable: false
         field :tier_mode, -> { Schematic::Types::BillingTiersMode }, optional: true, nullable: false
+        field :usage_quantity, -> { Integer }, optional: true, nullable: false
         field :value_bool, -> { Internal::Types::Boolean }, optional: true, nullable: false
         field :value_credit_id, -> { String }, optional: true, nullable: false
         field :value_numeric, -> { Integer }, optional: true, nullable: false

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

@@ -25,6 +25,7 @@ module Schematic
         field :quarterly_unit_price_decimal, -> { String }, optional: true, nullable: false
         field :soft_limit, -> { Integer }, optional: true, nullable: false
         field :tier_mode, -> { Schematic::Types::BillingTiersMode }, optional: true, nullable: false
+        field :usage_quantity, -> { Integer }, optional: true, nullable: false
         field :value_bool, -> { Internal::Types::Boolean }, optional: true, nullable: false
         field :value_credit_id, -> { String }, optional: true, nullable: false
         field :value_numeric, -> { Integer }, optional: true, nullable: false