melaya 0.1.4 → 0.3.0

data/lib/melaya/http_client.rb

@@ -4,69 +4,253 @@ require "net/http"
 require "uri"
 require "json"
 require "openssl"
+require "securerandom"
 
 require_relative "errors"
 
 module Melaya
-  # Internal HTTP client. Injects the API key on every call as both
-  # a query-param (?apiKey=) and Authorization: Bearer header.
+  # Internal HTTP client. Supports Bearer JWT *and* mk_* platform API key.
+  # The credential is sent ONLY via the Authorization header — never in the URL
+  # query string, so it cannot leak into access logs or proxies. TLS is
+  # enforced by default; never log secrets.
+  #
+  # Retry policy: bounded exponential back-off with jitter on network errors,
+  # 429, and 5xx — but ONLY for idempotent GET requests (max 2 retries).
+  # POST/PUT/PATCH/DELETE are never retried. Retry-After header is honoured
+  # on 429. Per-request timeout default: 30 seconds (configurable).
   class HttpClient
-    DEFAULT_BASE_URL = "https://api.melaya.org"
+    DEFAULT_BASE_URL    = "https://api.melaya.org"
+    DEFAULT_TIMEOUT_MS  = 30_000  # milliseconds
 
-    def initialize(api_key:, base_url: DEFAULT_BASE_URL, verify_ssl: true)
-      @api_key    = api_key
+    # Maximum additional retries after the first attempt (2 retries = 3 total
+    # attempts) for idempotent GET requests only.
+    MAX_GET_RETRIES = 2
+    RETRY_STATUSES  = [429, 500, 502, 503, 504].freeze
+
+    # @param api_key [String] mk_* platform key or Bearer JWT
+    # @param base_url [String]
+    # @param verify_ssl [Boolean]
+    # @param timeout_ms [Integer] per-request timeout in milliseconds (default 30 000)
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, verify_ssl: true,
+                   timeout_ms: DEFAULT_TIMEOUT_MS)
+      raise ArgumentError, "Melaya: TLS certificate verification cannot be disabled." unless verify_ssl
+      # Never store in a way that could leak to logs accidentally — keep as
+      # an opaque token string only accessible through the private accessor.
+      @_tok       = api_key.freeze
       @base_uri   = URI.parse(base_url.chomp("/"))
-      @verify_ssl = verify_ssl
+      @verify_ssl = true
+      @timeout_s  = (timeout_ms / 1000.0).ceil
+    end
+
+    # ── Public verb helpers ────────────────────────────────────────────────────
+    #
+    # Every verb accepts an optional trailing +timeout_s+ override for that
+    # single call (e.g. a slow RAG ingest job); it defaults to the client's own
+    # timeout. NOTE: it is a plain positional parameter, not a keyword — many
+    # call sites pass a bare `"key" => value` Hash literal as +body+/+params+,
+    # and Ruby 3's keyword/Hash separation would otherwise raise
+    # "unknown keyword" on every one of them if this were `timeout_s:`.
+
+    def get(path, params = {}, timeout_s = nil)
+      request(:get, path, params: params, timeout_s: timeout_s)
+    end
+
+    def post(path, body = nil, timeout_s = nil)
+      request(:post, path, body: body, timeout_s: timeout_s)
+    end
+
+    def put(path, body = nil, timeout_s = nil)
+      request(:put, path, body: body, timeout_s: timeout_s)
     end
 
-    def get(path, params = {})
-      request(:get, path, params: params)
+    def patch(path, body = nil, timeout_s = nil)
+      request(:patch, path, body: body, timeout_s: timeout_s)
     end
 
-    def post(path, body = nil)
-      request(:post, path, body: body)
+    # +body+ is optional: some bridged DELETE routes take structured input
+    # (e.g. googleDisconnect's { accountId, capability? }) that should not be
+    # exposed in a URL, so it travels as a JSON body instead of query params.
+    def delete(path, params = {}, body = nil, timeout_s = nil)
+      request(:delete, path, params: params, body: body, timeout_s: timeout_s)
     end
 
-    def delete(path, params = {})
-      request(:delete, path, params: params)
+    # GET that returns the RAW response body (String, binary encoding) instead
+    # of JSON-parsing it — for binary downloads like +runInputFile+. Errors are
+    # still parsed and raised exactly like the JSON verb helpers. Retried like
+    # any other GET (idempotent).
+    def get_bytes(path, params = {}, timeout_s = nil)
+      request(:get, path, params: params, timeout_s: timeout_s, raw: true)
+    end
+
+    # Upload a single file as `multipart/form-data` with one file part named
+    # +field_name+. Never retried (a partial multipart re-send could double an
+    # upload with side effects), and the response is parsed exactly like the
+    # JSON POST helper (same error type).
+    #
+    # @param path [String]
+    # @param query [Hash] query-string params (e.g. { "key" => ..., "project" => ... })
+    # @param field_name [String] the multipart field name the server expects (e.g. "file")
+    # @param bytes [String] raw file content
+    # @param filename [String] filename reported in the part's Content-Disposition
+    # @param content_type [String, nil] defaults to "application/octet-stream"
+    def post_multipart(path, query, field_name, bytes, filename, content_type = nil)
+      uri = build_uri(path, query || {})
+      boundary = "MelayaFormBoundary#{SecureRandom.hex(16)}"
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl      = uri.scheme == "https"
+      http.verify_mode  = OpenSSL::SSL::VERIFY_PEER
+      http.open_timeout = @timeout_s
+      http.read_timeout = @timeout_s
+
+      req = Net::HTTP::Post.new(uri)
+      req["Authorization"] = "Bearer #{@_tok}"
+      req["Accept"]        = "application/json"
+      req["User-Agent"]    = "melaya-ruby/#{Melaya::VERSION}"
+      req["Content-Type"]  = "multipart/form-data; boundary=#{boundary}"
+      req.body = multipart_body(boundary, field_name, bytes, filename, content_type)
+
+      resp = http.request(req)
+      parse(resp)
     end
 
     private
 
+    # Builds a single-file multipart/form-data body by hand (no dependency on
+    # any multipart-encoding gem).
+    def multipart_body(boundary, field_name, bytes, filename, content_type)
+      ct = content_type || "application/octet-stream"
+      head =
+        "--#{boundary}\r\n" \
+        "Content-Disposition: form-data; name=\"#{field_name}\"; filename=\"#{escape_multipart_value(filename)}\"\r\n" \
+        "Content-Type: #{ct}\r\n\r\n"
+      tail = "\r\n--#{boundary}--\r\n"
+      (head.b + bytes.to_s.b + tail.b)
+    end
+
+    # Escapes double quotes / newlines out of a Content-Disposition value.
+    def escape_multipart_value(value)
+      value.to_s.gsub("\\", "\\\\\\\\").gsub('"', '\\"').tr("\r\n", "  ")
+    end
+
     def build_uri(path, params = {})
       uri = URI.parse("#{@base_uri}#{path}")
-      query = { "apiKey" => @api_key }
+      # SECURITY: the credential is never placed in the query string; it is
+      # sent only via the Authorization header (see make_request).
+      query = {}
       params.each { |k, v| query[k.to_s] = v.to_s unless v.nil? }
-      uri.query = URI.encode_www_form(query)
+      uri.query = URI.encode_www_form(query) unless query.empty?
       uri
     end
 
-    def request(method, path, params: {}, body: nil)
-      uri = build_uri(path, params)
-
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == "https"
-      http.verify_mode = @verify_ssl ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
-      http.open_timeout = 15
-      http.read_timeout = 60
-
+    def make_request(method, uri, body)
       req = case method
             when :get    then Net::HTTP::Get.new(uri)
             when :post   then Net::HTTP::Post.new(uri)
+            when :put    then Net::HTTP::Put.new(uri)
+            when :patch  then Net::HTTP::Patch.new(uri)
             when :delete then Net::HTTP::Delete.new(uri)
             else raise ArgumentError, "Unknown HTTP method: #{method}"
             end
 
-      req["Authorization"] = "Bearer #{@api_key}"
+      # Authorization: never expose token in error output below
+      req["Authorization"] = "Bearer #{@_tok}"
       req["Accept"]        = "application/json"
+      req["User-Agent"]    = "melaya-ruby/#{Melaya::VERSION}"
 
       if body
         req["Content-Type"] = "application/json"
         req.body = JSON.generate(body)
       end
 
-      resp = http.request(req)
-      parse(resp)
+      req
+    end
+
+    def request(method, path, params: {}, body: nil, timeout_s: nil, raw: false)
+      uri = build_uri(path, params)
+
+      eff_timeout = timeout_s ? [timeout_s.to_f, 0.001].max.ceil : @timeout_s
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl      = uri.scheme == "https"
+      http.verify_mode  = OpenSSL::SSL::VERIFY_PEER
+      http.open_timeout = eff_timeout
+      http.read_timeout = eff_timeout
+
+      # Only GET requests are retried (idempotent); all mutating verbs fail fast.
+      retryable = (method == :get)
+      attempt   = 0
+
+      retry_after_hdr = nil
+      begin
+        attempt += 1
+        retry_after_hdr = nil  # reset on each attempt
+        req  = make_request(method, uri, body)
+        resp = http.request(req)
+        # Snapshot Retry-After before parse() consumes the response object,
+        # so we can honour the header even after the MelayaError is raised.
+        retry_after_hdr = resp["retry-after"] || resp["Retry-After"]
+        raw ? parse_raw(resp) : parse(resp)
+      rescue MelayaError => e
+        if retryable && RETRY_STATUSES.include?(e.status) && attempt <= MAX_GET_RETRIES
+          # Build a minimal resp-like object carrying only the header we need,
+          # so _backoff_delay can honour Retry-After without holding the socket.
+          hdr_carrier = { "retry-after" => retry_after_hdr }
+          delay = _backoff_delay(attempt, e, hdr_carrier)
+          sleep(delay)
+          retry
+        end
+        raise
+      rescue Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout
+        raise unless retryable && attempt <= MAX_GET_RETRIES
+        sleep(_backoff_delay(attempt, nil))
+        retry
+      end
+    end
+
+    # Exponential backoff with ±25 % jitter; honours Retry-After on 429.
+    # Base: 2^(attempt-1) seconds, capped at 16 s before jitter.
+    #
+    # Retry-After resolution order (first match wins):
+    #   1. HTTP `Retry-After` response header — seconds integer or HTTP-date
+    #   2. JSON body `retryAfter` / `retry_after` field (legacy fallback)
+    #   3. Exponential back-off
+    def _backoff_delay(attempt, err, resp = nil)
+      if err.is_a?(MelayaError) && err.status == 429
+        # 1. HTTP Retry-After header (preferred, RFC 7231)
+        if resp.respond_to?(:[]) && (ra_hdr = resp["retry-after"] || resp["Retry-After"])
+          secs = _parse_retry_after_header(ra_hdr)
+          return [secs, 0.5].max if secs
+        end
+
+        # 2. JSON body fallback ("retryAfter" or "retry_after")
+        if err.respond_to?(:body) && err.body.is_a?(Hash)
+          ra = err.body["retryAfter"] || err.body["retry_after"]
+          return [ra.to_f, 0.5].max if ra
+        end
+      end
+      base  = [2**(attempt - 1), 16].min.to_f
+      jitter = base * 0.25 * (rand - 0.5) * 2  # ±25 %
+      [base + jitter, 0.1].max
+    end
+
+    # Parse an RFC 7231 Retry-After value: either a delay-seconds integer
+    # or an HTTP-date string. Returns seconds as Float, or nil if unparseable.
+    def _parse_retry_after_header(value)
+      str = value.to_s.strip
+      # Delay-seconds: plain non-negative integer
+      if str =~ /\A\d+\z/
+        return str.to_f
+      end
+      # HTTP-date (e.g. "Wed, 21 Oct 2099 07:28:00 GMT")
+      begin
+        require "time"
+        target = Time.httpdate(str)
+        delay  = target - Time.now
+        return [delay, 0.0].max
+      rescue ArgumentError, TypeError
+        nil
+      end
     end
 
     def parse(resp)
@@ -77,21 +261,56 @@ module Melaya
         text
       end
 
-      if resp.code.to_i >= 400
-        code = data.is_a?(Hash) ? data["error"] : nil
-        msg  = "Melaya API #{resp.code}" + (code ? " (#{code})" : "")
-        raise MelayaError.new(msg, status: resp.code.to_i, code: code, body: data)
-      end
+      status = resp.code.to_i
+      raise_for_status!(resp, data, status) if status >= 400
 
-      # The API wraps every payload in { "ok": true/false, ... }.
-      # ok:false is a request-level failure — raise instead of returning silently.
+      # The API may wrap payload in { "ok": false, ... } for request-level failures.
       if data.is_a?(Hash) && data["ok"] == false
-        code = data["error"]
-        msg  = "Melaya API request failed" + (code ? ": #{code}" : "")
-        raise MelayaError.new(msg, status: resp.code.to_i, code: code, body: data)
+        err_code = data["error"]
+        msg = "Melaya API request failed" + (err_code ? ": #{err_code}" : "")
+        raise MelayaError.new(msg, status: resp.code.to_i, code: err_code, body: data)
       end
 
       data
     end
+
+    # Like +parse+, but for a raw binary body (a file download): on success
+    # the response body is returned unparsed; on error the same JSON error
+    # envelopes and exception types apply.
+    def parse_raw(resp)
+      status = resp.code.to_i
+      if status >= 400
+        text = resp.body.to_s.strip
+        data = begin
+          text.empty? ? nil : JSON.parse(text)
+        rescue JSON::ParserError
+          text
+        end
+        raise_for_status!(resp, data, status)
+      end
+      resp.body.to_s
+    end
+
+    # Shared 4xx/5xx handling for both +parse+ and +parse_raw+. Two error
+    # envelope shapes:
+    #   1. { error: 'tier_insufficient', tier: '...' }  -> 403
+    #   2. { error: '...', message: '...', code: '...' }
+    # Extract error code safely — never echo raw body in message.
+    def raise_for_status!(resp, data, status)
+      err_code = data.is_a?(Hash) ? data["error"] : nil
+
+      if status == 403 && err_code == "tier_insufficient"
+        raise TierInsufficientError.new(tier: data.is_a?(Hash) ? data["tier"] : nil, body: data)
+      end
+      if status == 429
+        # Raised here; the GET retry loop above may swallow-and-retry it —
+        # callers only see it once retries are exhausted.
+        ra = _parse_retry_after_header(resp["retry-after"] || resp["Retry-After"])
+        raise RateLimitError.new(retry_after: ra, body: data)
+      end
+
+      msg = "Melaya API #{resp.code}" + (err_code ? " (#{err_code})" : "")
+      raise MelayaError.new(msg, status: status, code: err_code, body: data)
+    end
   end
 end

data/lib/melaya/market.rb

@@ -147,6 +147,48 @@ module Melaya
       @http.get("/api/v1/public/catalog-counts")
     end
 
+    # ── restRoutes.ts market endpoints ──────────────────────────────────────────
+
+    # POST /api/v1/private/market/liquidations
+    # Get aggregated CEX liquidation data. (requireAuth)
+    # @param params [Hash] e.g. exchange, symbol, since_ms
+    def cex_liquidations(params = {})
+      @http.post("/api/v1/private/market/liquidations", params)
+    end
+
+    # GET /api/v1/market/mdd-pairs (public)
+    # Get max-drawdown pairs list (public screener data).
+    def mdd_pairs
+      @http.get("/api/v1/market/mdd-pairs")
+    end
+
+    # GET /api/v1/private/market/onchain-yields (Forge+ tier)
+    # Get on-chain yield data.
+    # @param params [Hash]
+    def onchain_yields(params = {})
+      @http.get("/api/v1/private/market/onchain-yields", params)
+    end
+
+    # GET /api/v1/private/market/onchain-liquidity (Forge+ tier)
+    # Get on-chain liquidity data.
+    # @param params [Hash]
+    def onchain_liquidity(params = {})
+      @http.get("/api/v1/private/market/onchain-liquidity", params)
+    end
+
+    # GET /api/v1/market/banner (public)
+    # Get marketing/notification banner content.
+    def banner
+      @http.get("/api/v1/market/banner")
+    end
+
+    # GET /api/v1/market/price-history (public)
+    # Get price history for chart display.
+    # @param params [Hash] e.g. exchange, symbol, timeframe
+    def price_history(params = {})
+      @http.get("/api/v1/market/price-history", params)
+    end
+
     private
 
     def compact(hash)

data/lib/melaya/namespaces.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Melaya
+  # ── Domain namespace objects ─────────────────────────────────────────────────
+  #
+  # Three read-only namespace objects hang off every +Melaya::Client+ instance,
+  # grouping the flat module accessors into logical planes:
+  #
+  #   melaya.trading  — market data, account, sim, strategies, backtest, stream, trade
+  #   melaya.agents   — pipelines/runs, hitl, assistant, phone, evals, models, connector_tools
+  #   melaya.platform — projects, credentials, connectors, billing, team, templates,
+  #                     overview (via pipelines), runner, auth, mfa (via auth),
+  #                     accounts, bugs, events
+  #
+  # Every attribute on these objects is the *same* instance that is also reachable
+  # via the flat accessor on the client, so there is no duplication of state and
+  # no double HTTP calls.
+  #
+  # @example
+  #   melaya = Melaya::Client.new(api_key: ENV["MELAYA_API_KEY"])
+  #
+  #   # Namespaced (primary API)
+  #   melaya.trading.market.ticker(exchange: "binance", symbol: "BTC/USDT", market: "spot")
+  #   melaya.agents.pipelines.list(project: "my-project")
+  #   melaya.platform.projects.list
+  #
+  #   # Flat aliases still work (backward-compatible)
+  #   melaya.market.ticker(exchange: "binance", symbol: "BTC/USDT", market: "spot")
+
+  # Namespace grouping all trading-plane modules.
+  #
+  # Modules:
+  # - +market+     — REST market-data + reference endpoints (public + authenticated).
+  # - +account+    — Authenticated account reads: connected keys, tier limits, usage.
+  # - +sim+        — Paper trading (sim broker): virtual balance, positions, and orders.
+  # - +strategies+ — Launch, control, and inspect trading strategies (paper + live).
+  # - +backtest+   — Historical backtests + parameter sweeps on the Rust engine.
+  # - +stream+     — WebSocket streaming endpoints (public market data + private feeds).
+  # - +trade+      — Live trading — credentialed order placement on a connected exchange.
+  TradingNamespace = Struct.new(
+    :market,
+    :account,
+    :sim,
+    :strategies,
+    :backtest,
+    :stream,
+    :trade,
+    keyword_init: true
+  )
+
+  # Namespace grouping all agent-plane modules.
+  #
+  # Modules:
+  # - +pipelines+  — Pipeline runs, traces, schedules, and overview dashboard.
+  #                  (also aliased as +runs+ for ergonomics)
+  # - +hitl+       — Human-in-the-loop approval queue: list pending, approve, reject.
+  # - +assistant+  — Assistant onboarding profile (get + set).
+  # - +phone+      — Phone device control: pair, list, screen-tree, apps.
+  # - +evals+      — Agent evaluation runs and benchmarks.
+  # - +models+     — AI model list (reached via credentials#list_models; this is
+  #                  the CredentialsAPI instance filtered by convention — call
+  #                  +models.list_models(provider: "anthropic")+ etc.)
+  # - +connector_tools+ — Call already-connected connector tools directly
+  #                  (Gmail, Slack, Stripe, ...): list, search, describe, test,
+  #                  connect, call, call_status, call_and_wait.
+  AgentsNamespace = Struct.new(
+    :pipelines,
+    :hitl,
+    :assistant,
+    :phone,
+    :evals,
+    :models,
+    :connector_tools,
+    keyword_init: true
+  ) do
+    # +runs+ is an ergonomic alias for +pipelines+ (agents call them "runs").
+    def runs
+      pipelines
+    end
+  end
+
+  # Namespace grouping all platform-plane modules.
+  #
+  # Modules:
+  # - +projects+     — Create and list agent projects.
+  # - +credentials+  — User-scoped credential storage (services, OAuth, env handles, models).
+  # - +connectors+   — Project-scoped connector credentials.
+  # - +billing+      — Subscription, Stripe checkout/portal, pricing plans, credit balances.
+  # - +team+         — Project team management: members, roles, invite links.
+  # - +templates+    — Pipeline templates: create, share, assign, and manage visibility.
+  # - +overview+     — Pipeline overview dashboard (same object as +agents.pipelines+,
+  #                    exposed here for discoverability on the platform plane).
+  # - +runner+       — Runner tokens: mint, list, revoke +mel_run_+ tokens.
+  # - +auth+         — Login, MFA, registration, password management, session tokens.
+  # - +mfa+          — Alias for +auth+ (MFA operations live on the same AuthAPI object).
+  # - +accounts+     — Account management: GDPR export, CEX key removal, profile updates.
+  # - +bugs+         — Bug reports: submit, track, and comment.
+  # - +events+       — Platform real-time events over Socket.IO.
+  PlatformNamespace = Struct.new(
+    :projects,
+    :credentials,
+    :connectors,
+    :billing,
+    :team,
+    :templates,
+    :overview,
+    :runner,
+    :auth,
+    :accounts,
+    :bugs,
+    :events,
+    keyword_init: true
+  ) do
+    # +mfa+ is an ergonomic alias for +auth+ (MFA methods live on AuthAPI).
+    def mfa
+      auth
+    end
+  end
+end

data/lib/melaya/phone.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Melaya
+  # Phone API — pair and control Android devices connected to the Melaya runner.
+  #
+  # Agents use these endpoints to drive a paired phone (tap, type, read
+  # screen state, launch apps) via the Melaya APK.
+  #
+  # Maps to /api/v1/private/phone/*.
+  #
+  # @example
+  #   result = melaya.phone.pair
+  #   puts "Pairing code: #{result["code"]}"
+  #   # User enters code in the Melaya APK on the phone
+  #
+  #   devices = melaya.phone.list_devices
+  #   tree = melaya.phone.screen_tree
+  class PhoneAPI
+    def initialize(http)
+      @http = http
+    end
+
+    # POST /api/v1/private/phone/pair
+    # Start phone device pairing — generates a pairing code for the Melaya APK.
+    def pair
+      @http.post("/api/v1/private/phone/pair")
+    end
+
+    # GET /api/v1/private/phone/devices
+    # List all paired phone devices for the authenticated user.
+    def list_devices
+      @http.get("/api/v1/private/phone/devices").fetch("devices", [])
+    end
+
+    # DELETE /api/v1/private/phone/devices/:deviceId
+    # Revoke a paired phone device by ID.
+    # @param device_id [String]
+    def revoke_device(device_id)
+      @http.delete("/api/v1/private/phone/devices/#{enc(device_id)}")
+    end
+
+    # GET /api/v1/private/phone/screen-tree
+    # Get the current accessibility tree from the paired phone's screen.
+    def screen_tree
+      @http.get("/api/v1/private/phone/screen-tree")
+    end
+
+    # GET /api/v1/private/phone/apps
+    # List installed apps on the paired phone.
+    def list_apps
+      @http.get("/api/v1/private/phone/apps").dig("result", "apps") || []
+    end
+
+    # PUT /api/v1/private/phone/apps/allowed
+    # Set the allowlist of apps that agents are permitted to interact with.
+    # @param package_names [Array<String>]
+    def set_allowed_apps(package_names)
+      apps = package_names.map { |package| { "package" => package } }
+      @http.put("/api/v1/private/phone/apps/allowed", "apps" => apps)
+    end
+
+    # POST /api/v1/private/phone/active-run
+    # Register the currently active pipeline run on the phone (used by agents).
+    # @param run_id [String]
+    def register_active_run(run_id)
+      @http.post("/api/v1/private/phone/active-run", "runId" => run_id)
+    end
+
+    # POST /api/v1/private/phone/apps/grant
+    # Grant ONE app into the agent allowlist (atomic append) — e.g. from an
+    # in-chat "allow this app" approval card, without replacing the whole list.
+    # @param package [String] Android package name
+    # @param label [String, nil]
+    def grant_app(package, label: nil)
+      body = compact("package" => package, "label" => label)
+      @http.post("/api/v1/private/phone/apps/grant", body)
+    end
+
+    # POST /api/v1/private/phone/request-cast
+    # Re-cast the phone screen (re-triggers the MediaProjection consent
+    # prompt) from the desktop mirror.
+    # @param device_id [String, nil]
+    def request_cast(device_id: nil)
+      body = compact("deviceId" => device_id)
+      @http.post("/api/v1/private/phone/request-cast", body.empty? ? nil : body)
+    end
+
+    private
+
+    def enc(s)
+      URI.encode_www_form_component(s.to_s)
+    end
+
+    def compact(hash)
+      hash.reject { |_, v| v.nil? }
+    end
+  end
+end