mixin_bot 2.1.0 → 2.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b32c36a1629b320052d174d39a6330439f726c44dd78ff98b7fdb20d517fe1a
-  data.tar.gz: 0bc0cade506ab4db2aada6776bcf860f4a01ae3db8b83e530fa79b5d91755a12
+  metadata.gz: ee9a02bff6da3b4331ff084e75d4f94d10d0a98b50e7b2c899679ec78340c659
+  data.tar.gz: 699c595d8f4acfd94041be582b0eda32db2ea4ba4da34359d1fc231d7e6bcbc2
 SHA512:
-  metadata.gz: 1cb159a3d41d2b09bd2880023df2beeb2af8c3fd82d702f6abb8e1cdcfe77833a7ac52e067e04f913ff304d3c6f0ab302810534ab98da67f396ccae4af1845cb
-  data.tar.gz: f917dbae1725dd89b83ddc8e8139e104660509e3bc978870b483441c824912b244ec474895b8b1a05edc95c726c1631ee4b1d4b01455bff410bc5f07c6d4b6cb
+  metadata.gz: ad0a66de09acfda9b1a4da94568ec4d704eab3be8f4eb92de145262bd0e74fc4b0efaee1243b16d5876199d270160c2fbd48aced6580af3308ab55117e156205
+  data.tar.gz: de638caf39c1af94cb169887f424d48127971f8bcd74c60a3f1b9e338b974c867001931e649244f16523e7d8efa501c6d81f0604c25f04a891cc7412550a45ed

data/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — MixinBot
 
-Ruby gem (v2.1.0): Mixin Network REST SDK + `mixinbot` CLI. Parity targets: [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client), [bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client).
+Ruby gem (v2.2.1): Mixin Network REST SDK + `mixinbot` CLI. Parity targets: [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client), [bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client).
 
 ## Commands
 

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.1] - 2026-05-24
+
+### Changed
+
+- **Billing preflight `increment`** — `ensure_app_billing_credit!` accepts an `increment` parameter (default `0`) instead of reading `app_properties.price`. `create_user` / `create_safe_user` default to `0.5` per billed user; pass `increment: 0` for free-tier headroom.
+
+## [2.2.0] - 2026-05-24
+
+### Added
+
+- **`MixinBot::API#create_user` billing preflight** — verifies app billing headroom (`credit > cost + next user fee`) via `app_billing` and `app_properties` before `POST /users`. Raises `InsufficientAppBillingError` by default; pass `force: true` to skip. `create_safe_user` forwards `force:` to `create_user`.
+- **`MixinBot::InsufficientAppBillingError`** — structured fields: `app_id`, `credit`, `cost`, `increment`.
+- **CLI** — `mixinbot call create_user ... --force` skips billing preflight; billing failures map to structured error kind `billing`.
+
 ## [2.1.0] - 2026-05-24
 
 ### Added

data/README.md

@@ -6,7 +6,7 @@ Ruby SDK and CLI for [Mixin Network](https://developers.mixin.one/docs): authent
 
 The gem aims for **parity with the official [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client)** Go SDK and **[bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client)** Node SDK. See [API_COVERAGE.md](API_COVERAGE.md) for the full mapping; run `rake mixin_bot:api_coverage` to confirm no gaps are marked missing.
 
-Current gem version: **2.1.0** (see [CHANGELOG.md](CHANGELOG.md) for breaking changes and deprecations).
+Current gem version: **2.2.1** (see [CHANGELOG.md](CHANGELOG.md) for breaking changes and deprecations).
 
 ## Requirements
 

data/docs/agent/cli.md

@@ -72,7 +72,7 @@ Error (stderr, exit 1):
 }
 ```
 
-Error kinds: `invalid_args`, `auth`, `not_found`, `api_error`, `unsupported`, `conflict`, `internal`.
+Error kinds: `invalid_args`, `auth`, `not_found`, `api_error`, `billing`, `unsupported`, `conflict`, `internal`.
 
 ## Commands
 
@@ -106,8 +106,12 @@ List JSON shape:
 mixinbot call me -k keystore.json -o json
 mixinbot call safe_outputs -k keystore.json -d '{"asset":"965e5c6e-434c-3fa9-b780-c50f43cd955c","state":"unspent","limit":10}' -o json
 mixinbot call user USER_UUID -k keystore.json --data-only -o json
+mixinbot call create_user "Bot User" -k keystore.json -o json
+mixinbot call create_user "Bot User" -k keystore.json --force -o json
 ```
 
+`create_user` performs a client-side app billing preflight by default. When credit lacks headroom for the next billed user, the CLI returns `"kind": "billing"`. Use `--force` to skip the preflight (or pass `"force": true` in `-d`; `-d` wins when both are set).
+
 ### Raw HTTP
 
 ```bash

data/lib/mixin_bot/api/app.rb

@@ -24,6 +24,38 @@ module MixinBot
         client.get path, access_token:
       end
 
+      ##
+      # Verifies the app has billing headroom before a billed operation (e.g.
+      # creating a network user). Skipped when +force+ is true.
+      #
+      # @param force [Boolean] skip the preflight and call the API anyway
+      # @param increment [Numeric, String] estimated cost added to total billing
+      #   cost for headroom (default +0+)
+      # @raise [InsufficientAppBillingError] when +credit+ is not greater than
+      #   total cost plus +increment+
+      #
+      def ensure_app_billing_credit!(force: false, access_token: nil, increment: 0)
+        return if force
+
+        app_id = config.app_id
+        billing = app_billing(app_id, access_token:)['data']
+
+        credit = billing_decimal billing['credit']
+        cost_users = billing_decimal billing.dig('cost', 'users')
+        cost_resources = billing_decimal billing.dig('cost', 'resources')
+        cost = cost_users + cost_resources
+        increment = billing_decimal increment
+
+        return if credit > cost + increment
+
+        raise InsufficientAppBillingError.new(
+          app_id:,
+          credit: credit.to_s('F'),
+          cost: cost.to_s('F'),
+          increment: increment.to_s('F')
+        )
+      end
+
       def create_app(**kwargs)
         payload = {
           redirect_uri: kwargs[:redirect_uri],
@@ -95,6 +127,12 @@ module MixinBot
         client.post path, user_id: receiver_user_id, pin_base64: tip[:pin_base64] || tip[:pin], access_token:
       end
       alias migrate transfer_app_ownership
+
+      private
+
+      def billing_decimal(value)
+        BigDecimal(value.to_s)
+      end
     end
   end
 end

data/lib/mixin_bot/api/user.rb

@@ -23,6 +23,10 @@ module MixinBot
       # the new TIP PIN has time to propagate on the server side.
       TIP_PIN_PROPAGATION_DELAY = 1
 
+      # Billed cost per network user created via {#create_user} (USD), after
+      # the free tier. Pass +increment: 0+ to skip headroom for the new user.
+      CREATE_USER_BILLING_INCREMENT = '0.5'
+
       def user(user_id, access_token: nil)
         path = format('/users/%<user_id>s', user_id:)
         client.get path, access_token:
@@ -37,9 +41,16 @@ module MixinBot
       #
       # @param full_name [String] display name for the new user
       # @param key [String, nil] optional 32-byte Ed25519 seed
+      # @param force [Boolean] when false (default), verify app billing credit
+      #   headroom before calling the API; when true, skip the preflight
+      # @param increment [Numeric, String] billing headroom for the new user
+      #   (defaults to {CREATE_USER_BILLING_INCREMENT}; use +0+ on free tier)
       # @return [Hash] Mixin response merged with the hex-encoded private key
+      # @raise [InsufficientAppBillingError] when billing credit lacks headroom
       #
-      def create_user(full_name, key: nil)
+      def create_user(full_name, key: nil, force: false, increment: CREATE_USER_BILLING_INCREMENT)
+        ensure_app_billing_credit!(force:, increment:)
+
         keypair = JOSE::JWA::Ed25519.keypair key
         session_secret = Base64.urlsafe_encode64 keypair[0], padding: false
         private_key = keypair[1].unpack1('H*')
@@ -85,19 +96,24 @@ module MixinBot
       # @param name [String] display name for the new user
       # @param private_key [String, nil] optional 32-byte session Ed25519 seed
       # @param spend_key [String, nil] optional 32-byte spend Ed25519 seed
+      # @param force [Boolean] forwarded to {#create_user}; see billing preflight
+      #   there
+      # @param increment [Numeric, String] forwarded to {#create_user}
       # @return [Hash] keystore with +:app_id+, +:session_id+,
       #   +:session_private_key+, +:server_public_key+ and +:spend_key+
       # @raise [MixinBot::Error] when registration ultimately fails. Transient
       #   PIN/response errors are retried up to {SAFE_REGISTER_MAX_RETRIES}
       #   times; other errors bubble up immediately.
+      # @raise [InsufficientAppBillingError] when {#create_user} billing
+      #   preflight fails
       #
-      def create_safe_user(name, private_key: nil, spend_key: nil)
+      def create_safe_user(name, private_key: nil, spend_key: nil, force: false, increment: CREATE_USER_BILLING_INCREMENT)
         session_keypair = JOSE::JWA::Ed25519.keypair private_key
         spend_keypair = JOSE::JWA::Ed25519.keypair spend_key
 
         spend_key_hex = spend_keypair[1].unpack1('H*')
 
-        user = create_user name, key: session_keypair[1][...32]
+        user = create_user name, key: session_keypair[1][...32], force: force, increment: increment
         data = user.fetch('data')
 
         keystore = {

data/lib/mixin_bot/cli/call.rb

@@ -15,11 +15,13 @@ module MixinBot
     LONGDESC
     option :keystore, type: :string, aliases: '-k', desc: 'keystore JSON file path or inline JSON'
     option :data, type: :string, aliases: '-d', default: '{}', desc: 'JSON object of keyword arguments'
+    option :force, type: :boolean, default: false, desc: 'Skip billing preflight for create_user (see -d force to override)'
     option :data_only, type: :boolean, default: false, desc: 'Print only the data field of API responses'
     def call(method_name, *positional)
       with_command_name('call') do
         setup_api_instance!
         kwargs = parse_json_data(options[:data])
+        kwargs = merge_call_force_kwargs(method_name, kwargs)
         result = invoke_api(method_name, kwargs:, positional:)
         print_result(result, data_only: options[:data_only], command: 'call')
       end
@@ -55,6 +57,14 @@ module MixinBot
 
     private
 
+    def merge_call_force_kwargs(method_name, kwargs)
+      return kwargs unless method_name.to_sym == :create_user
+      return kwargs if kwargs.key?(:force)
+      return kwargs unless options[:force]
+
+      kwargs.merge(force: true)
+    end
+
     def print_pretty_list(items, total, limit, offset)
       grouped = items.group_by { |item| item['owner'] }
       grouped.sort_by { |owner, _| owner }.each do |owner, names|

data/lib/mixin_bot/cli/errors.rb

@@ -12,6 +12,7 @@ module MixinBot
       api_error: { retryable: false, description: 'Mixin API returned an error' },
       unsupported: { retryable: false, description: 'Operation is not supported in this context' },
       conflict: { retryable: false, description: 'Resource exists with incompatible configuration' },
+      billing: { retryable: false, description: 'App billing credit insufficient for the operation' },
       internal: { retryable: false, description: 'Unexpected internal error' }
     }.freeze
 
@@ -35,6 +36,8 @@ module MixinBot
         :auth
       when NotFoundError, UserNotFoundError
         :not_found
+      when InsufficientAppBillingError
+        :billing
       when ResponseError, RequestError, HttpError,
            InsufficientBalanceError, UtxoInsufficientError, InsufficientPoolError
         :api_error

data/lib/mixin_bot/errors.rb

@@ -51,6 +51,26 @@ module MixinBot
   #
   class InsufficientBalanceError < Error; end
 
+  ##
+  # Raised when app prepaid billing credit lacks headroom for a billed operation.
+  #
+  class InsufficientAppBillingError < Error
+    attr_reader :app_id, :credit, :cost, :increment
+
+    def initialize(app_id:, credit:, cost:, increment:)
+      @app_id = app_id
+      @credit = credit
+      @cost = cost
+      @increment = increment
+      super(
+        format(
+          'app billing insufficient: credit %<credit>s <= cost %<cost>s + increment %<increment>s (app_id=%<app_id>s)',
+          credit:, cost:, increment:, app_id:
+        )
+      )
+    end
+  end
+
   ##
   # Raised when selected UTXOs cannot cover the requested amount (mirrors Go +UtxoInsufficientError+).
   #

data/lib/mixin_bot/version.rb

@@ -11,5 +11,5 @@ module MixinBot
   #
   # @see https://semver.org/
   #
-  VERSION = '2.1.0'
+  VERSION = '2.2.1'
 end

data/llms.txt

@@ -1,6 +1,6 @@
 # MixinBot
 
-> Ruby SDK and CLI for Mixin Network: Safe UTXO transfers, REST API, Blaze messaging, transaction crypto, optional MVM helpers. Ruby >= 3.2. Gem version 2.1.0.
+> Ruby SDK and CLI for Mixin Network: Safe UTXO transfers, REST API, Blaze messaging, transaction crypto, optional MVM helpers. Ruby >= 3.2. Gem version 2.2.1.
 
 Important notes:
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mixin_bot
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.1
 platform: ruby
 authors:
 - an-lee