melaya 0.1.4 → 0.2.0

data/lib/melaya/http_client.rb

@@ -8,17 +8,41 @@ require "openssl"
 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"
-
-    def initialize(api_key:, base_url: DEFAULT_BASE_URL, verify_ssl: true)
-      @api_key    = api_key
+    DEFAULT_BASE_URL    = "https://api.melaya.org"
+    DEFAULT_TIMEOUT_MS  = 30_000  # milliseconds
+
+    # 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 ────────────────────────────────────────────────────
+
     def get(path, params = {})
       request(:get, path, params: params)
     end
@@ -27,6 +51,14 @@ module Melaya
       request(:post, path, body: body)
     end
 
+    def put(path, body = nil)
+      request(:put, path, body: body)
+    end
+
+    def patch(path, body = nil)
+      request(:patch, path, body: body)
+    end
+
     def delete(path, params = {})
       request(:delete, path, params: params)
     end
@@ -35,38 +67,120 @@ module Melaya
 
     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)
+      uri = build_uri(path, params)
+
+      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
+
+      # 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"]
+        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,18 +191,33 @@ 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)
+      status = resp.code.to_i
+      if status >= 400
+        # Two error envelope shapes:
+        #   1. { error: 'tier_insufficient', tier: '...' }  -> 403
+        #   2. { error: '...', message: '...', code: '...' }
+        # Extract error code safely — never echo raw body in message
+        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
 
-      # 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

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,115 @@
+# 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
+  #   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.)
+  AgentsNamespace = Struct.new(
+    :pipelines,
+    :hitl,
+    :assistant,
+    :phone,
+    :evals,
+    :models,
+    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,75 @@
+# 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
+
+    private
+
+    def enc(s)
+      URI.encode_www_form_component(s.to_s)
+    end
+  end
+end