mixin_bot 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d03bd8cb9d6710487b3ef3c5ed57e88136a0bcb99c841d366fe7e24b3e8a43c
-  data.tar.gz: 5e0c70f36c6ca291a0e65e11137434474ad804829e67c553a7b8fbee651b5ea9
+  metadata.gz: 2bbc251caedc50e5324a90713c291cf019b2bf0fa003a7ad4df3401af5b175fa
+  data.tar.gz: cb7e858d5073bb2fc8bd5e487027fc10a684b8ff05dbc2949aa48270808e1f0a
 SHA512:
-  metadata.gz: a717d7b6103c5e1df8b1cb044303114c159cbc31cb47e6f0a33e9c7e7906a204c0fd3ab92507b9eb903979c603c5031e192a2f6bf392ee4d2636eea5f3f3c88c
-  data.tar.gz: 75a350a5053a490aff9cfac0b556e70dad2d2e20bf4cafb4408640b6d5c5dd932ec2264bf2cf952a3dec511b4e71855d4c5996e7acb32ccf6ea201b17943c80f
+  metadata.gz: 758781312e8be1e922eee338ed4ddfd3154c44ea25fb1d7e2b67d9e3ea8298381e4cc4d6df33904c35b831545d136da14c4af1630fdabe7789d3761a1617d6d9
+  data.tar.gz: a5350e9812115ef75e39a906e6fb48aa55189692887ee037c0dc3f29cf67b00e70b912575fbe5b9d1f44d93be29c520c2a3142804671c1bcfd3bc96dcfee6b9a

data/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — MixinBot
 
-Ruby gem (v2.0.0): Mixin Network REST SDK + `mixinbot` CLI. Parity target: [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client).
+Ruby gem (v2.2.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).
 
 ## Commands
 
@@ -35,7 +35,7 @@ docs/agent/             # LLM-oriented CLI and cookbook docs
 ## CI and release
 
 - **CI** (`.github/workflows/ci.yml`): `pull_request` and `push` to `main` — `rake test` on Ruby 3.2/3.3/4.0, `rake rubocop` (3.3), `rake mixin_bot:api_coverage`.
-- **Release** (`.github/workflows/release.yml`): push tag `v*` (must match `MixinBot::VERSION`, e.g. tag `v2.0.0` for `VERSION = '2.0.0'`) → `rake build` → RubyGems via [trusted publishing](https://guides.rubygems.org/trusted-publishing/) (OIDC; workflow `release.yml`, no repo secret).
+- **Release** (`.github/workflows/release.yml`): push tag `v*` (must match `MixinBot::VERSION`, e.g. tag `v2.1.0` for `VERSION = '2.1.0'`) → `rake build` → RubyGems via [trusted publishing](https://guides.rubygems.org/trusted-publishing/) (OIDC; workflow `release.yml`, no repo secret) → GitHub Release (notes from `CHANGELOG.md`, `.gem` attached).
 - **Dependabot** (`.github/dependabot.yml`): weekly Bundler and GitHub Actions updates; Dependabot PRs use the same CI workflow.
 
 ## Conventions

data/API_COVERAGE.md

@@ -1,8 +1,10 @@
-# Mixin Go SDK API Coverage
+# Mixin SDK API Coverage
 
-Reference: [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client) (`package bot`).
+Go reference: [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client) (`package bot`).
 
-Status values: `done` | `alias` | `n/a` (CLI-only / config)
+Node reference: [bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client) (`@mixin.dev/mixin-node-sdk`).
+
+Status values: `done` | `alias` | `n/a` (CLI-only / config / platform-specific)
 
 | Go symbol | Ruby method | HTTP / notes | Status |
 |-----------|-------------|--------------|--------|
@@ -140,4 +142,79 @@ Status values: `done` | `alias` | `n/a` (CLI-only / config)
 | NewSafeUser | `MixinBot::Configuration` | config | n/a |
 | cli/*, examples/*, mixin/rpc main | `mixinbot call` / `mixinbot list` | CLI dispatch to `MixinBot::API` | done |
 
+## Node SDK
+
+TS-only or Node-first REST surfaces. Ruby methods follow snake_case; aliases mirror TS names where helpful.
+
+| TS symbol | Ruby method | HTTP / notes | Status |
+|-----------|-------------|--------------|--------|
+| **Circle** |
+| circle.fetch | `API#circle` | GET `/circles/:id` | done |
+| circle.fetchList | `API#circles` | GET `/circles` | done |
+| circle.conversations | `API#circle_conversations` | GET `/circles/:id/conversations` | done |
+| circle.create | `API#create_circle` | POST `/circles` | done |
+| circle.update | `API#update_circle` | POST `/circles/:id` | done |
+| circle.delete | `API#delete_circle` | POST `/circles/:id/delete` | done |
+| circle.addUser | `API#add_user_to_circle` | POST `/users/:id/circles` | done |
+| circle.removeUser | `API#remove_user_from_circle` | POST `/users/:id/circles` | done |
+| circle.addConversation | `API#add_conversation_to_circle` | POST `/conversations/:id/circles` | done |
+| circle.removeConversation | `API#remove_conversation_from_circle` | POST `/conversations/:id/circles` | done |
+| **App** |
+| app.fetch | `API#app` | GET `/apps/:id` | done |
+| app.fetchList | `API#apps` | GET `/apps` | done |
+| app.properties | `API#app_properties` | GET `/apps/property` | done |
+| app.billing | `API#app_billing` | GET `/safe/apps/:id/billing` | done |
+| app.create | `API#create_app` | POST `/apps` | done |
+| app.update | `API#update_app` | POST `/apps/:id` | done |
+| app.updateSecret | `API#rotate_app_secret` | POST `/apps/:id/secret` | done |
+| app.updateSafeSession | `API#update_app_safe_session` | POST `/safe/apps/:id/session` | done |
+| app.registerSafe | `API#register_app_safe` | POST `/safe/apps/:id/register` | done |
+| app.favorite / unfavorite | `API#add_favorite_app` / `#remove_favorite_app` | POST `/apps/:id/favorite` | done |
+| app.favorites | `API#favorite_apps` | GET `/users/:id/apps/favorite` | done |
+| app.migrate | `API#transfer_app_ownership` | POST `/apps/:id/transfer` | done |
+| **OAuth** |
+| oauth.getToken | `API#oauth_token` | POST `/oauth/token` | done |
+| oauth.authorize | `API#authorize_code` | POST `/oauth/authorize` | done |
+| oauth.authorizations | `API#authorizations` | GET `/authorizations` | done |
+| oauth.revokeAuthorize | `API#revoke_authorization` | POST `/oauth/cancel` | done |
+| **User** |
+| user.profile | `API#me` | GET `/me` | done |
+| user.friends | `API#friends` | GET `/friends` | done |
+| user.blockings | `API#blocking_users` | GET `/blocking_users` | done |
+| user.rotateCode | `API#rotate_user_code` | GET `/me/code` | done |
+| user.search | `API#search_user` | GET `/search/:q` | done |
+| user.fetch | `API#user` | GET `/users/:id` | done |
+| user.fetchList | `API#fetch_users` | POST `/users/fetch` | done |
+| user.createBareUser | `API#create_user` | POST `/users` | done |
+| user.update | `API#update_me` | POST `/me` | done |
+| user.updatePreferences | `API#update_preferences` | POST `/me/preferences` | done |
+| user.updateRelationships | `API#relationship` | POST `/relationships` | done |
+| user.logs | `API#user_logs` | GET `/logs` | done |
+| **Conversation** |
+| conversation.mute / unmute | `API#mute_conversation` / `#unmute_conversation` | POST `/conversations/:id/mute` | done |
+| conversation.disappearDuration | `API#set_conversation_disappear_duration` | POST `/conversations/:id/disappear` | done |
+| conversation.updateGroupInfo | `API#update_conversation` | POST `/conversations/:id` | done |
+| conversation.* (CRUD/participants) | `API#conversation`, `#create_*`, `#join_*`, etc. | various | done |
+| **Message** |
+| message.sendAcknowledgement(s) | `API#acknowledge_message` / `#acknowledge_messages` | POST `/acknowledgements` | done |
+| message.sendSticker/Audio/Video/Live/Location/Transfer | `API#send_*_message` | POST `/messages` | done |
+| message.sendText/Image/File/Post/Contact/AppCard/AppButton/Recall | `API#send_*_message` | POST `/messages` | done |
+| **Code** |
+| code.fetch | `API#read_code` | GET `/codes/:id` | done |
+| code.schemes | `API#create_scheme` | POST `/schemes` | done |
+| **Address** |
+| address.fetchListOfChain | `API#safe_withdraw_addresses` | GET `/safe/addresses?chain=` | done |
+| address.fetch/create/delete | `API#get_withdraw_address`, `#create_withdraw_address`, `#delete_withdraw_address` | `/addresses` | done |
+| **External** |
+| external.proxy | `API#external_proxy` | POST `/external/proxy` | done |
+| external.deposits | `API#transactions` (legacy) | GET `/external/transactions` | done |
+| external.checkAddress | `API#check_address` | GET `/external/addresses/check` | done |
+| external.exchangeRates | `API#fiats` | GET `/external/fiats` | done |
+| **Safe / UTXO / Transfer / Network / etc.** |
+| safe.* / utxo.* / transfer.* / network.* | spread across existing `API` modules | same HTTP paths as TS | done |
+| **Blaze** |
+| blaze.loop | `API#blaze` | WebSocket | done |
+| **WebView** |
+| WebViewApi | — | browser bridge | n/a |
+
 Update this file when adding or changing API surfaces. Run `rake mixin_bot:api_coverage` to ensure no `missing` rows remain.

data/CHANGELOG.md

@@ -7,26 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-05-24
+
 ### Added
 
-- **`mixinbot call METHOD`** and **`mixinbot list`** — invoke any public `MixinBot::API` method from the CLI with JSON keyword arguments (`-d`).
-- **`mixinbot utils call`** / **`mixinbot utils list`** — same for `MixinBot.utils` helpers.
+- **`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`.
 
-### Changed
+## [2.1.0] - 2026-05-24
 
-- **`mixinbot transfer`** — uses Safe API (`create_safe_transfer`) instead of legacy `POST /transfers`.
-- **`mixinbot api`** — routes through `MixinBot::Client` (supports JSON array POST bodies); keystore loading includes `spend_key` and `client_secret`.
-- **`mixinbot updatetip`** — uses `update_tip_pin` instead of misusing `update_pin`.
-- **`mixinbot safetransfer`** — delegates to `transfer` (no duplicated signing pipeline).
+### Added
 
-### Deprecated
+- **Node SDK REST parity** with [bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client): Circle API (`API::Circle`), `external_proxy`, extended App CRUD/Safe registration, OAuth `authorizations` / `revoke_authorization`, user `blocking_users` / `rotate_user_code` / `user_logs`, conversation mute/disappear, HTTP message acknowledgements and additional send helpers, `create_scheme`, `safe_withdraw_addresses`, and query params on `pending_safe_deposits`.
+- **API_COVERAGE.md** Node SDK section mapping TS symbols to Ruby methods.
 
-- **`mixinbot legacy-transfer`** — explicit legacy transfer command (replaces old default `transfer` behavior).
-- **`mixinbot safetransfer`** — use `transfer` instead.
+## [2.0.1] - 2026-05-24
 
 ### Fixed
 
-- **`mixinbot nftmemo`** — calls `MixinBot.utils.nft_memo` (was a broken `nft` alias).
+- **`StringIO.new`** — use keyword `contents:` for Ruby 4 compatibility (`lib/mixin_bot/api/message.rb`).
+
+### Changed
+
+- Release workflow creates a GitHub Release with notes from `CHANGELOG.md` when publishing version tags.
 
 ## [2.0.0] - 2026-05-16
 

data/README.md

@@ -4,9 +4,9 @@
 
 Ruby SDK and CLI for [Mixin Network](https://developers.mixin.one/docs): authenticated REST calls, **Safe** UTXO transfers, Blaze messaging, network asset catalog, inscriptions, invoices and mix addresses, transaction encoding, and optional **MVM** (Mixin Virtual Machine) helpers.
 
-The gem aims for **parity with the official [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client)** Go 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.
+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.0.0** (see [CHANGELOG.md](CHANGELOG.md) for breaking changes and deprecations).
+Current gem version: **2.2.0** (see [CHANGELOG.md](CHANGELOG.md) for breaking changes and deprecations).
 
 ## Requirements
 
@@ -353,14 +353,14 @@ Publishing to [RubyGems.org](https://rubygems.org/gems/mixin_bot) is automated w
 
 1. Bump `MixinBot::VERSION` in `lib/mixin_bot/version.rb` and update `CHANGELOG.md`.
 2. Commit and push to `main`.
-3. Create and push a tag matching the gem version (e.g. `v2.0.1` for version `2.0.1`):
+3. Create and push a tag matching the gem version (e.g. `v2.1.0` for version `2.1.0`):
 
    ```bash
-   git tag v2.0.1
-   git push origin v2.0.1
+   git tag v2.1.0
+   git push origin v2.1.0
    ```
 
-The [Release workflow](.github/workflows/release.yml) builds the gem and publishes to RubyGems.org via [trusted publishing](https://guides.rubygems.org/trusted-publishing/) (GitHub OIDC; trusted publisher for workflow `release.yml` on `an-lee/mixin_bot`). To build without publishing, run the Release workflow manually with **dry run** enabled.
+The [Release workflow](.github/workflows/release.yml) builds the gem, publishes to RubyGems.org via [trusted publishing](https://guides.rubygems.org/trusted-publishing/) (GitHub OIDC; trusted publisher for workflow `release.yml` on `an-lee/mixin_bot`), and creates a GitHub Release with notes from `CHANGELOG.md` and the `.gem` attached. To build without publishing, run the Release workflow manually with **dry run** enabled.
 
 ## References
 

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

@@ -3,17 +3,116 @@
 module MixinBot
   class API
     module App
+      def app(app_id, access_token: nil)
+        path = format('/apps/%<id>s', id: app_id)
+        client.get path, access_token:
+      end
+      alias fetch_app app
+
+      def apps(access_token: nil)
+        client.get '/apps', access_token:
+      end
+      alias fetch_apps apps
+
+      def app_properties(access_token: nil)
+        client.get '/apps/property', access_token:
+      end
+      alias app_property app_properties
+
+      def app_billing(app_id, access_token: nil)
+        path = format('/safe/apps/%<id>s/billing', id: app_id)
+        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
+      # @raise [InsufficientAppBillingError] when +credit+ is not greater than
+      #   total cost plus the next user fee from {app_properties}
+      #
+      def ensure_app_billing_credit!(force: false, access_token: nil)
+        return if force
+
+        app_id = config.app_id
+        billing = app_billing(app_id, access_token:)['data']
+        properties = app_properties(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 properties['price']
+
+        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],
+          home_uri: kwargs[:home_uri],
+          name: kwargs[:name],
+          description: kwargs[:description],
+          icon_base64: kwargs[:icon_base64],
+          category: kwargs[:category],
+          capabilities: kwargs[:capabilities],
+          resource_patterns: kwargs[:resource_patterns]
+        }.compact
+        client.post '/apps', **payload, access_token: kwargs[:access_token]
+      end
+
+      def update_app(app_id, **kwargs)
+        path = format('/apps/%<id>s', id: app_id)
+        payload = {
+          redirect_uri: kwargs[:redirect_uri],
+          home_uri: kwargs[:home_uri],
+          name: kwargs[:name],
+          description: kwargs[:description],
+          icon_base64: kwargs[:icon_base64],
+          category: kwargs[:category],
+          capabilities: kwargs[:capabilities],
+          resource_patterns: kwargs[:resource_patterns]
+        }.compact
+        client.post path, **payload, access_token: kwargs[:access_token]
+      end
+
+      def rotate_app_secret(app_id, access_token: nil)
+        path = format('/apps/%<id>s/secret', id: app_id)
+        client.post path, access_token:
+      end
+      alias update_app_secret rotate_app_secret
+
+      def update_app_safe_session(app_id, session_public_key:, access_token: nil)
+        path = format('/safe/apps/%<id>s/session', id: app_id)
+        client.post path, session_public_key:, access_token:
+      end
+
+      def register_app_safe(app_id, spend_public_key:, signature_base64:, access_token: nil)
+        path = format('/safe/apps/%<id>s/register', id: app_id)
+        client.post path, spend_public_key:, signature_base64:, access_token:
+      end
+
       def add_favorite_app(app_id, access_token: nil)
         path = format('/apps/%<id>s/favorite', id: app_id)
 
         client.post path, access_token:
       end
+      alias favorite_app add_favorite_app
 
       def remove_favorite_app(app_id, access_token: nil)
         path = format('/apps/%<id>s/unfavorite', id: app_id)
 
         client.post path, access_token:
       end
+      alias unfavorite_app remove_favorite_app
 
       def favorite_apps(user_id = nil, access_token: nil)
         path = format('/users/%<id>s/apps/favorite', id: user_id || config.app_id)
@@ -27,6 +126,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/auth.rb

@@ -56,6 +56,17 @@ module MixinBot
         client.post path, **payload, access_token: kwargs[:access_token]
       end
 
+      def authorizations(app_id: nil, access_token: nil)
+        params = {}
+        params[:app] = app_id if app_id
+        client.get '/authorizations', **params, access_token:
+      end
+
+      def revoke_authorization(client_id, access_token: nil)
+        client.post '/oauth/cancel', client_id:, access_token:
+      end
+      alias revoke_authorize revoke_authorization
+
       def authorization_data(app_id, scope = ['PROFILE:READ'])
         @_app_id = app_id
         @_scope = scope.join(' ')

data/lib/mixin_bot/api/circle.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module MixinBot
+  class API
+    module Circle
+      def circle(circle_id, access_token: nil)
+        path = format('/circles/%<circle_id>s', circle_id:)
+        client.get path, access_token:
+      end
+      alias fetch_circle circle
+
+      def circles(access_token: nil)
+        client.get '/circles', access_token:
+      end
+      alias fetch_circles circles
+
+      def circle_conversations(circle_id, **params)
+        path = format('/circles/%<circle_id>s/conversations', circle_id:)
+        client.get path, **params.compact, access_token: params[:access_token]
+      end
+
+      def create_circle(name:, access_token: nil)
+        client.post '/circles', name:, access_token:
+      end
+
+      def update_circle(circle_id, name:, access_token: nil)
+        path = format('/circles/%<circle_id>s', circle_id:)
+        client.post path, name:, access_token:
+      end
+
+      def delete_circle(circle_id, access_token: nil)
+        path = format('/circles/%<circle_id>s/delete', circle_id:)
+        client.post path, access_token:
+      end
+
+      def add_user_to_circle(user_id:, circle_id:, access_token: nil)
+        path = format('/users/%<user_id>s/circles', user_id:)
+        client.post path, circle_id:, action: 'ADD', access_token:
+      end
+
+      def remove_user_from_circle(user_id:, circle_id:, access_token: nil)
+        path = format('/users/%<user_id>s/circles', user_id:)
+        client.post path, circle_id:, action: 'REMOVE', access_token:
+      end
+
+      def add_conversation_to_circle(conversation_id:, circle_id:, access_token: nil)
+        path = format('/conversations/%<conversation_id>s/circles', conversation_id:)
+        client.post path, circle_id:, action: 'ADD', access_token:
+      end
+
+      def remove_conversation_from_circle(conversation_id:, circle_id:, access_token: nil)
+        path = format('/conversations/%<conversation_id>s/circles', conversation_id:)
+        client.post path, circle_id:, action: 'REMOVE', access_token:
+      end
+    end
+  end
+end

data/lib/mixin_bot/api/code.rb

@@ -11,6 +11,11 @@ module MixinBot
       def read_multisig_by_code(code_id, access_token: nil)
         read_code(code_id, access_token:)
       end
+
+      def create_scheme(target, access_token: nil)
+        client.post '/schemes', target:, access_token:
+      end
+      alias schemes create_scheme
     end
   end
 end

data/lib/mixin_bot/api/conversation.rb

@@ -55,23 +55,40 @@ module MixinBot
         )
       end
 
-      def update_group_conversation_name(name:, conversation_id:, access_token: nil)
+      def update_conversation(conversation_id:, **kwargs)
         path = format('/conversations/%<id>s', id: conversation_id)
         payload = {
-          name:
-        }
+          name: kwargs[:name],
+          announcement: kwargs[:announcement]
+        }.compact
+        client.post path, **payload, access_token: kwargs[:access_token]
+      end
+      alias update_group_info update_conversation
 
-        client.post path, **payload, access_token:
+      def update_group_conversation_name(name:, conversation_id:, access_token: nil)
+        update_conversation(conversation_id:, name:, access_token:)
       end
 
       def update_group_conversation_announcement(announcement:, conversation_id:, access_token: nil)
-        path = format('/conversations/%<id>s', id: conversation_id)
-        payload = {
-          announcement:
-        }
+        update_conversation(conversation_id:, announcement:, access_token:)
+      end
+
+      def mute_conversation(conversation_id, duration:, access_token: nil)
+        path = format('/conversations/%<id>s/mute', id: conversation_id)
+        client.post path, duration:, access_token:
+      end
+      alias mute mute_conversation
+
+      def unmute_conversation(conversation_id, access_token: nil)
+        mute_conversation conversation_id, duration: 0, access_token:
+      end
+      alias unmute unmute_conversation
 
-        client.post path, **payload, access_token:
+      def set_conversation_disappear_duration(conversation_id, duration:, access_token: nil)
+        path = format('/conversations/%<id>s/disappear', id: conversation_id)
+        client.post path, duration:, access_token:
       end
+      alias disappear_duration set_conversation_disappear_duration
 
       # participants = [{ user_id: "" }]
       def add_conversation_participants(conversation_id:, user_ids:, access_token: nil)

data/lib/mixin_bot/api/deposit.rb

@@ -3,8 +3,15 @@
 module MixinBot
   class API
     module Deposit
-      def pending_safe_deposits
-        client.get '/safe/deposits', access_token: ''
+      def pending_safe_deposits(**params)
+        query = {
+          limit: params[:limit],
+          offset: params[:offset],
+          asset: params[:asset],
+          destination: params[:destination],
+          tag: params[:tag]
+        }.compact
+        client.get '/safe/deposits', **query, access_token: params[:access_token] || ''
       end
       alias fetch_pending_safe_deposits pending_safe_deposits
     end

data/lib/mixin_bot/api/external.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module MixinBot
+  class API
+    module External
+      def external_proxy(method:, params: [], access_token: nil)
+        client.post '/external/proxy', method:, params:, access_token:
+      end
+      alias proxy external_proxy
+    end
+  end
+end

data/lib/mixin_bot/api/me.rb

@@ -126,6 +126,27 @@ module MixinBot
         path = '/relationships'
         client.post path, user_id:, action:, access_token:
       end
+      alias update_relationship relationship
+
+      def blocking_users(access_token: nil)
+        client.get '/blocking_users', access_token:
+      end
+      alias blockings blocking_users
+
+      def rotate_user_code(access_token: nil)
+        client.get '/me/code', access_token:
+      end
+      alias rotate_code rotate_user_code
+
+      def user_logs(**params)
+        query = {
+          limit: params[:limit],
+          offset: params[:offset],
+          category: params[:category]
+        }.compact
+        client.get '/logs', **query, access_token: params[:access_token]
+      end
+      alias logs user_logs
     end
   end
 end

data/lib/mixin_bot/api/message.rb

@@ -48,6 +48,18 @@ module MixinBot
         base_message_params(options.merge(category: 'PLAIN_VIDEO'))
       end
 
+      def plain_live(options)
+        base_message_params(options.merge(category: 'PLAIN_LIVE'))
+      end
+
+      def plain_location(options)
+        base_message_params(options.merge(category: 'PLAIN_LOCATION'))
+      end
+
+      def transfer_message(options)
+        base_message_params(options.merge(category: 'SYSTEM_ACCOUNT_SNAPSHOT'))
+      end
+
       def app_card(options)
         base_message_params(options.merge(category: 'APP_CARD'))
       end
@@ -105,7 +117,7 @@ module MixinBot
           params:
         }.to_json
 
-        io = StringIO.new 'wb'
+        io = StringIO.new
         gzip = Zlib::GzipWriter.new io
         gzip.write msg
         gzip.close
@@ -141,6 +153,30 @@ module MixinBot
         send_message app_button_group(options)
       end
 
+      def send_sticker_message(options)
+        send_message plain_sticker(options)
+      end
+
+      def send_audio_message(options)
+        send_message plain_audio(options)
+      end
+
+      def send_video_message(options)
+        send_message plain_video(options)
+      end
+
+      def send_live_message(options)
+        send_message plain_live(options)
+      end
+
+      def send_location_message(options)
+        send_message plain_location(options)
+      end
+
+      def send_transfer_message(options)
+        send_message transfer_message(options)
+      end
+
       def recall_message(message_id, options)
         send_message [recall_message_params(message_id, options)]
       end
@@ -149,6 +185,17 @@ module MixinBot
         send_message messages
       end
 
+      def acknowledge_message(message_id, status: 'READ', access_token: nil)
+        payload = { message_id:, status: }
+        client.post '/acknowledgements', payload, access_token:
+      end
+      alias send_acknowledgement acknowledge_message
+
+      def acknowledge_messages(messages, access_token: nil)
+        client.post '/acknowledgements', *messages, access_token:
+      end
+      alias send_acknowledgements acknowledge_messages
+
       # http post request
       def send_message(payload)
         path = '/messages'

data/lib/mixin_bot/api/user.rb

@@ -37,9 +37,14 @@ 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
       # @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)
+        ensure_app_billing_credit!(force:)
+
         keypair = JOSE::JWA::Ed25519.keypair key
         session_secret = Base64.urlsafe_encode64 keypair[0], padding: false
         private_key = keypair[1].unpack1('H*')
@@ -85,19 +90,23 @@ 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
       # @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)
         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
         data = user.fetch('data')
 
         keystore = {

data/lib/mixin_bot/api/withdraw.rb

@@ -70,6 +70,11 @@ module MixinBot
       end
       alias get_addresses_by_asset_id withdraw_addresses
 
+      def safe_withdraw_addresses(chain_id, access_token: nil)
+        client.get '/safe/addresses', chain: chain_id, access_token:
+      end
+      alias fetch_list_of_chain safe_withdraw_addresses
+
       def check_address(asset:, destination:, tag: nil)
         client.get '/external/addresses/check', asset:, destination:, tag:, access_token: ''
       end

data/lib/mixin_bot/api.rb

@@ -10,10 +10,12 @@ require_relative 'api/auth'
 require_relative 'api/blaze'
 require_relative 'api/chain'
 require_relative 'api/code'
+require_relative 'api/circle'
 require_relative 'api/computer_api'
 require_relative 'api/conversation'
 require_relative 'api/deposit'
 require_relative 'api/encrypted_message'
+require_relative 'api/external'
 require_relative 'api/fiat'
 require_relative 'api/inscription'
 require_relative 'api/legacy_collectible'
@@ -338,10 +340,12 @@ module MixinBot
     include MixinBot::API::Blaze
     include MixinBot::API::Chain
     include MixinBot::API::Code
+    include MixinBot::API::Circle
     include MixinBot::API::ComputerApi
     include MixinBot::API::Conversation
     include MixinBot::API::Deposit
     include MixinBot::API::EncryptedMessage
+    include MixinBot::API::External
     include MixinBot::API::Fiat
     include MixinBot::API::Inscription
     include MixinBot::API::LegacyCollectible

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.0.0'
+  VERSION = '2.2.0'
 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.0.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.0.
 
 Important notes:
 
@@ -11,7 +11,7 @@ Important notes:
 ## Docs
 
 - [README](README.md): Install, config, API overview, CLI summary
-- [API coverage vs Go SDK](API_COVERAGE.md): Method parity matrix
+- [API coverage vs Go/Node SDKs](API_COVERAGE.md): Method parity matrix
 - [CLI for agents](docs/agent/cli.md): Structured output, schema, examples
 - [Agent cookbook](docs/agent/cookbook.md): Common tasks (auth, transfer, messaging)
 - [Changelog](CHANGELOG.md): Breaking changes
@@ -25,5 +25,6 @@ Important notes:
 ## Optional
 
 - [Mixin official docs](https://developers.mixin.one/docs): External API reference
-- [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client): Parity reference
+- [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client): Go parity reference
+- [bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client): Node parity reference
 - [Generated RDoc](doc/index.html): Full API reference (local)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mixin_bot
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - an-lee
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-20 00:00:00.000000000 Z
+date: 2026-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -282,11 +282,13 @@ files:
 - lib/mixin_bot/api/auth.rb
 - lib/mixin_bot/api/blaze.rb
 - lib/mixin_bot/api/chain.rb
+- lib/mixin_bot/api/circle.rb
 - lib/mixin_bot/api/code.rb
 - lib/mixin_bot/api/computer_api.rb
 - lib/mixin_bot/api/conversation.rb
 - lib/mixin_bot/api/deposit.rb
 - lib/mixin_bot/api/encrypted_message.rb
+- lib/mixin_bot/api/external.rb
 - lib/mixin_bot/api/fiat.rb
 - lib/mixin_bot/api/inscription.rb
 - lib/mixin_bot/api/legacy_collectible.rb