melaya 0.1.4 → 0.3.0

data/lib/melaya/strategies.rb

@@ -151,5 +151,20 @@ module Melaya
     def ai_opt_runs(strategy_id)
       @http.get("/api/v1/strategies/#{strategy_id}/ai-opt/runs")
     end
+
+    # ── restRoutes.ts strategies endpoints ────────────────────────────────────
+
+    # GET /api/v1/private/strategies/team
+    # List strategies visible to the caller's team project.
+    def list_team
+      @http.get("/api/v1/private/strategies/team")
+    end
+
+    # POST /api/v1/private/strategies/summaries/bulk
+    # Bulk-fetch lightweight summaries for a list of strategy IDs.
+    # @param strategy_ids [Array<String>]
+    def summaries_bulk(strategy_ids)
+      @http.post("/api/v1/private/strategies/summaries/bulk", "strategyIds" => strategy_ids)
+    end
   end
 end

data/lib/melaya/stream.rb

@@ -42,8 +42,9 @@ module Melaya
     end
 
     def initialize(url, verify_ssl: true)
+      raise ArgumentError, "Melaya: TLS certificate verification cannot be disabled." unless verify_ssl
       @uri        = URI.parse(url)
-      @verify_ssl = verify_ssl
+      @verify_ssl = true
       @socket     = nil
       @closed     = false
       @buf        = String.new("", encoding: "BINARY")
@@ -54,7 +55,7 @@ module Melaya
 
       @socket = if @uri.scheme == "wss"
         ctx = OpenSSL::SSL::SSLContext.new
-        ctx.verify_mode = @verify_ssl ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+        ctx.verify_mode = OpenSSL::SSL::VERIFY_PEER
         ssl = OpenSSL::SSL::SSLSocket.new(tcp, ctx)
         ssl.hostname = @uri.host
         ssl.connect
@@ -259,10 +260,11 @@ module Melaya
     DEFAULT_WS_URL = "wss://wss.melaya.org"
 
     def initialize(api_key, ws_url, http, verify_ssl: true)
+      raise ArgumentError, "Melaya: TLS certificate verification cannot be disabled." unless verify_ssl
       @api_key    = api_key
       @ws_url     = ws_url.to_s.chomp("/")
       @http       = http
-      @verify_ssl = verify_ssl
+      @verify_ssl = true
     end
 
     # Live ticker frames.

data/lib/melaya/team.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Melaya
+  # Team API — manage project team membership, roles, and invitations.
+  #
+  # Maps to:
+  #   /api/v1/private/projects/:project/members/*
+  #   /api/v1/private/team/*
+  #   /api/v1/private/projects/:project/pipelines/:pipeline/visibility
+  #
+  # @example
+  #   members = melaya.team.list_members("my-project")
+  #   melaya.team.invite("my-project", username: "alice")
+  #   link = melaya.team.create_invite_link("my-project")
+  class TeamAPI
+    def initialize(http)
+      @http = http
+    end
+
+    # GET /api/v1/private/projects/:project/members
+    # List members of a project team.
+    # @param project [String] project name
+    def list_members(project)
+      @http.get("/api/v1/private/projects/#{enc(project)}/members")
+    end
+
+    # POST /api/v1/private/projects/:project/members/invite
+    # Invite a user to a project team by username.
+    # @param project [String]
+    # @param username [String]
+    def invite(project, username:)
+      @http.post("/api/v1/private/projects/#{enc(project)}/members/invite",
+        "username" => username)
+    end
+
+    # POST /api/v1/private/projects/:project/invite-link
+    # Create a shareable invite link for a project.
+    # Returns the URL to send to new team members.
+    # @param project [String]
+    def create_invite_link(project)
+      @http.post("/api/v1/private/projects/#{enc(project)}/invite-link")
+    end
+
+    # POST /api/v1/private/team/invite/accept
+    # Accept a project invite using the token from an invite link.
+    # @param token [String]
+    def accept_invite(token)
+      @http.post("/api/v1/private/team/invite/accept", "token" => token)
+    end
+
+    # PATCH /api/v1/private/projects/:project/members/:userId
+    # Update a team member's role in a project.
+    # @param project [String]
+    # @param user_id [String]
+    # @param role [String] one of "owner", "editor", "viewer"
+    def update_member_role(project, user_id, role:)
+      @http.patch(
+        "/api/v1/private/projects/#{enc(project)}/members/#{enc(user_id)}",
+        "role" => role
+      )
+    end
+
+    # DELETE /api/v1/private/projects/:project/members/:userId
+    # Remove a member from a project team.
+    # @param project [String]
+    # @param user_id [String]
+    def remove_member(project, user_id)
+      @http.delete("/api/v1/private/projects/#{enc(project)}/members/#{enc(user_id)}")
+    end
+
+    # POST /api/v1/private/projects/:project/transfer-ownership
+    # Transfer project ownership (creator) to another active member. Only the
+    # current project owner may call this.
+    # @param project [String]
+    # @param new_owner_user_id [String] uuid of an existing active member
+    def transfer_ownership(project, new_owner_user_id)
+      @http.post("/api/v1/private/projects/#{enc(project)}/transfer-ownership",
+        "newOwnerUserId" => new_owner_user_id)
+    end
+
+    # ── Pipeline visibility ────────────────────────────────────────────────────
+
+    # GET /api/v1/private/projects/:project/pipelines/:pipeline/visibility
+    # Get visibility settings for a pipeline within a project.
+    # @param project [String]
+    # @param pipeline [String]
+    def get_pipeline_visibility(project, pipeline)
+      @http.get(
+        "/api/v1/private/projects/#{enc(project)}/pipelines/#{enc(pipeline)}/visibility"
+      )
+    end
+
+    # PUT /api/v1/private/projects/:project/pipelines/:pipeline/visibility
+    # Set pipeline visibility within a project.
+    # @param project [String]
+    # @param pipeline [String]
+    # @param body [Hash]
+    def set_pipeline_visibility(project, pipeline, body = {})
+      @http.put(
+        "/api/v1/private/projects/#{enc(project)}/pipelines/#{enc(pipeline)}/visibility",
+        body
+      )
+    end
+
+    private
+
+    def enc(s)
+      URI.encode_www_form_component(s.to_s)
+    end
+  end
+end
+

data/lib/melaya/templates.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Melaya
+  # Templates API — create, manage, share, and assign pipeline templates.
+  #
+  # Templates bundle a pipeline definition into a reusable, shareable artifact.
+  # Visibility levels: private → team → community → assigned.
+  #
+  # Maps to:
+  #   /api/v1/private/user-templates/*    — CRUD + share + assignments
+  #   /api/v1/private/templates/*         — global/validated lists
+  #
+  # @example
+  #   templates = melaya.templates.list
+  #   t = melaya.templates.save(name: "My report", payload: { steps: [] })
+  #   melaya.templates.share(t["id"], "team")
+  #   melaya.templates.delete(t["id"])
+  class TemplatesAPI
+    def initialize(http)
+      @http = http
+    end
+
+    # GET /api/v1/private/user-templates
+    # List all templates visible to the caller (own + team + community + assigned).
+    def list
+      @http.get("/api/v1/private/user-templates")
+    end
+
+    # GET /api/v1/private/templates/global
+    # List all community-visibility (global) templates.
+    def list_global
+      @http.get("/api/v1/private/templates/global")
+    end
+
+    # GET /api/v1/private/templates/validated
+    # List IDs of all validated (platform-approved) templates.
+    def list_validated
+      @http.get("/api/v1/private/templates/validated")
+    end
+
+    # POST /api/v1/private/user-templates
+    # Create a new private user template.
+    # @param name [String]
+    # @param payload [Hash]
+    # @param description [String, nil]
+    # @param category [String, nil]
+    def save(name:, payload:, description: nil, category: nil)
+      body = compact(
+        "name"        => name,
+        "payload"     => payload,
+        "description" => description,
+        "category"    => category
+      )
+      @http.post("/api/v1/private/user-templates", body)
+    end
+
+    # PATCH /api/v1/private/user-templates/:id
+    # Update name/description/category/payload of a private user template.
+    # @param template_id [String]
+    # @param body [Hash]
+    def update(template_id, body = {})
+      @http.patch("/api/v1/private/user-templates/#{enc(template_id)}", body)
+    end
+
+    # POST /api/v1/private/user-templates/:sourceId/duplicate
+    # Duplicate a readable template into the caller's private library.
+    # @param template_id [String] the source template to copy
+    # @param new_name [String, nil]
+    def duplicate(template_id, new_name: nil)
+      body = new_name ? { "newName" => new_name } : nil
+      @http.post("/api/v1/private/user-templates/#{enc(template_id)}/duplicate", body)
+    end
+
+    # DELETE /api/v1/private/user-templates/:id
+    # Delete (or soft-demote if shared) a template.
+    # @param template_id [String]
+    def delete(template_id)
+      @http.delete("/api/v1/private/user-templates/#{enc(template_id)}")
+    end
+
+    # PUT /api/v1/private/user-templates/:id/visibility
+    # Change the visibility of a template.
+    # @param template_id [String]
+    # @param visibility [String] "private", "team", "community", or "assigned"
+    def share(template_id, visibility)
+      @http.put("/api/v1/private/user-templates/#{enc(template_id)}/visibility",
+        "visibility" => visibility)
+    end
+
+    # GET /api/v1/private/user-templates/share-targets
+    # List projects the caller is a member of (for the share target picker UI).
+    def share_targets
+      @http.get("/api/v1/private/user-templates/share-targets")
+    end
+
+    # ── Assignments ────────────────────────────────────────────────────────────
+
+    # GET /api/v1/private/user-templates/:templateId/assignments
+    # List all assignments (users / projects) for a template.
+    # @param template_id [String]
+    def list_assignments(template_id)
+      @http.get("/api/v1/private/user-templates/#{enc(template_id)}/assignments")
+    end
+
+    # POST /api/v1/private/user-templates/:templateId/assignments
+    # Assign a template to a user or project.
+    # Provide exactly one of +user_id:+ or +project_id:+ (both UUIDs);
+    # the server rejects requests carrying both or neither.
+    # @param template_id [String]
+    # @param user_id [String, nil] target user UUID
+    # @param project_id [String, nil] target project UUID
+    def assign(template_id, user_id: nil, project_id: nil)
+      @http.post("/api/v1/private/user-templates/#{enc(template_id)}/assignments",
+        assignment_target(user_id, project_id))
+    end
+
+    # DELETE /api/v1/private/user-templates/:templateId/assignments
+    # Remove an assignment from a template.
+    # Provide exactly one of +user_id:+ or +project_id:+ (both UUIDs).
+    # The target is sent as query params — the server ignores DELETE
+    # request bodies.
+    # @param template_id [String]
+    # @param user_id [String, nil] target user UUID
+    # @param project_id [String, nil] target project UUID
+    def unassign(template_id, user_id: nil, project_id: nil)
+      @http.delete("/api/v1/private/user-templates/#{enc(template_id)}/assignments",
+        assignment_target(user_id, project_id))
+    end
+
+    private
+
+    # Exactly one of user_id / project_id must be given.
+    def assignment_target(user_id, project_id)
+      if user_id.nil? == project_id.nil?
+        raise ArgumentError, "Melaya: provide exactly one of user_id: or project_id:"
+      end
+      user_id ? { "userId" => user_id } : { "projectId" => project_id }
+    end
+
+    def enc(s)
+      URI.encode_www_form_component(s.to_s)
+    end
+
+    def compact(hash)
+      hash.reject { |_, v| v.nil? }
+    end
+  end
+end

data/lib/melaya/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Melaya
-  VERSION = "0.1.4"
+  VERSION = "0.3.0"
 end

data/lib/melaya.rb

@@ -3,6 +3,8 @@
 require_relative "melaya/version"
 require_relative "melaya/errors"
 require_relative "melaya/http_client"
+
+# ── Trading plane ──────────────────────────────────────────────────────────────
 require_relative "melaya/market"
 require_relative "melaya/account"
 require_relative "melaya/sim"
@@ -11,28 +13,88 @@ require_relative "melaya/backtest"
 require_relative "melaya/stream"
 require_relative "melaya/trade"
 
+# ── Platform / agents plane ────────────────────────────────────────────────────
+require_relative "melaya/auth"
+require_relative "melaya/accounts"
+require_relative "melaya/billing"
+require_relative "melaya/runner"
+require_relative "melaya/projects"
+require_relative "melaya/pipelines"
+require_relative "melaya/hitl"
+require_relative "melaya/credentials"
+require_relative "melaya/connectors"
+require_relative "melaya/connector_tools"
+require_relative "melaya/phone"
+require_relative "melaya/team"
+require_relative "melaya/templates"
+require_relative "melaya/assistant"
+require_relative "melaya/evals"
+require_relative "melaya/bugs"
+require_relative "melaya/events"
+
+# ── Domain namespace groupings ─────────────────────────────────────────────────
+require_relative "melaya/namespaces"
+
 module Melaya
-  # The Melaya client.
+  # The unified Melaya client.
+  #
+  # Exposes every public endpoint in the Melaya REST API surface through three
+  # domain namespaces **and** flat module accessors (for backward compatibility).
+  #
+  # **Primary API — namespaced** (recommended):
+  #
+  #   melaya.trading.market.ticker(...)         # market data
+  #   melaya.trading.strategies.create(...)     # trading strategies
+  #   melaya.agents.pipelines.list(...)         # agent pipeline runs
+  #   melaya.agents.hitl.pending                # HITL approval queue
+  #   melaya.platform.projects.list             # platform projects
+  #   melaya.platform.billing.subscription      # billing
+  #
+  # **Flat accessors** (backward-compatible aliases):
+  #
+  #   melaya.market.ticker(...)    # same object as melaya.trading.market
+  #   melaya.pipelines.list(...)   # same object as melaya.agents.pipelines
+  #   melaya.projects.list         # same object as melaya.platform.projects
+  #
+  # **Namespace groupings**:
+  # - +trading+  — market, account, sim, strategies, backtest, stream, trade
+  # - +agents+   — pipelines (also +.runs+), hitl, assistant, phone, evals, models,
+  #                connector_tools
+  # - +platform+ — projects, credentials, connectors, billing, team, templates,
+  #                overview, runner, auth (also +.mfa+), accounts, bugs, events
+  #
+  # Authentication: pass your +mk_*+ platform API key via +api_key:+. Every REST call
+  # sends it as an Authorization: Bearer header. For session JWT workflows
+  # (login/refresh) construct the client with the JWT instead.
+  # Never log or expose the key — it is stored opaquely in the HTTP client.
   #
   # @example
   #   require "melaya"
-  #   melaya = Melaya::Client.new(api_key: ENV["MK"])
   #
-  #   # Market data
-  #   t = melaya.market.ticker(exchange: "binance", symbol: "BTC/USDT", market: "spot")
+  #   melaya = Melaya::Client.new(api_key: ENV["MELAYA_API_KEY"])
+  #
+  #   # Namespaced — primary API
+  #   t = melaya.trading.market.ticker(exchange: "binance", symbol: "BTC/USDT", market: "spot")
   #   puts t["last"]
   #
-  #   # Paper strategy
-  #   result = melaya.strategies.create(
-  #     name: "my-bot", strategy_type: "custom", exchange: "binanceusdm",
-  #     symbol: "BTC/USDT:USDT", market: "FUTURES", dry_run: true,
-  #     params: { language: "rhai", definition: 'fn evaluate() { emit_long(param("qty")); }', qty: 0.001 }
-  #   )
-  #   sid = result["strategyId"]
-  #   melaya.strategies.stop(sid)
-  #   melaya.strategies.delete(sid)
+  #   # Agent pipelines
+  #   runs = melaya.agents.pipelines.list(project: "my-project", limit: 10)
+  #   # or via the alias:
+  #   runs = melaya.agents.runs.list(project: "my-project", limit: 10)
+  #
+  #   # HITL approvals
+  #   pending = melaya.agents.hitl.pending
+  #   pending.each { |r| melaya.agents.hitl.approve(r["requestId"]) }
+  #
+  #   # Platform
+  #   projects = melaya.platform.projects.list
+  #   melaya.platform.auth.login(username: "you@example.com", password: "s3cr3t")
+  #
+  #   # Real-time events (Socket.IO) — also on platform namespace
+  #   melaya.platform.events.on_run_update("run-123") { |e| puts e["event_type"] }
   class Client
-    # REST market-data + reference endpoints (public plane).
+    # ── Trading plane ──────────────────────────────────────────────────────────
+    # REST market-data + reference endpoints (public + authenticated).
     attr_reader :market
     # Authenticated account reads: connected keys, tier limits, usage.
     attr_reader :account
@@ -44,29 +106,120 @@ module Melaya
     attr_reader :backtest
     # WebSocket streaming endpoints (public market data + private feeds).
     attr_reader :stream
-    # Live trading — credentialed order placement and account state on a connected exchange. WARNING: real funds.
+    # Live trading — credentialed order placement on a connected exchange. WARNING: real funds.
     attr_reader :trade
 
-    # @param api_key [String] your Melaya API key, prefixed +mk_+
-    # @param base_url [String] override the REST base URL
-    # @param ws_url [String] override the WebSocket base URL
-    # @param verify_ssl [Boolean] set false to skip TLS verification (dev-box only).
-    #   Prefer using ENV["MELAYA_INSECURE_TLS"]="1" rather than passing this directly.
+    # ── Platform / agents plane ────────────────────────────────────────────────
+    # Auth: login, MFA, registration, password management, session tokens.
+    attr_reader :auth
+    # Account management: GDPR export, CEX key removal, profile updates.
+    attr_reader :accounts
+    # Billing: subscription, Stripe checkout/portal, pricing plans, credit balances.
+    attr_reader :billing
+    # Runner tokens: mint, list, revoke mel_run_ tokens.
+    attr_reader :runner
+    # Agent projects: create and list.
+    attr_reader :projects
+    # Pipeline runs, traces, schedules, and overview dashboard.
+    attr_reader :pipelines
+    # Human-in-the-loop approval queue: list pending, approve, reject.
+    attr_reader :hitl
+    # User-scoped credential storage (services, OAuth, env handles, models).
+    attr_reader :credentials
+    # Project-scoped connector credentials.
+    attr_reader :connectors
+    # Call already-connected connector tools directly (Gmail, Slack, Stripe, ...)
+    # — the same surface the MCP server and Assistant use. Not to be confused
+    # with +connectors+ (credential storage).
+    attr_reader :connector_tools
+    # Phone device control: pair, list, screen-tree, apps.
+    attr_reader :phone
+    # Project team management: members, roles, invite links.
+    attr_reader :team
+    # Pipeline templates: create, share, assign, and manage visibility.
+    attr_reader :templates
+    # Assistant onboarding profile (get + set).
+    attr_reader :assistant
+    # Agent evaluation runs and benchmarks.
+    attr_reader :evals
+    # Bug reports: submit, track, and comment.
+    attr_reader :bugs
+    # Platform real-time events over Socket.IO at /api/v1/events.
+    # Subscribe to run updates, init-phase progress, HITL notifications,
+    # and pipeline CRUD events. Opens a background polling thread.
+    attr_reader :events
+
+    # ── Domain namespace accessors (primary API) ───────────────────────────────
+
+    # Trading-plane namespace.
+    # Groups: market, account, sim, strategies, backtest, stream, trade.
+    #
+    # @return [TradingNamespace]
+    # @example
+    #   melaya.trading.market.ticker(exchange: "binance", symbol: "BTC/USDT", market: "spot")
+    #   melaya.trading.strategies.create(name: "bot", strategy_type: "custom", ...)
+    #   melaya.trading.stream.ticker(exchange: "binance", symbol: "BTC/USDT", market: "spot") { |f| ... }
+    attr_reader :trading
+
+    # Agent-plane namespace.
+    # Groups: pipelines (alias: runs), hitl, assistant, phone, evals, models,
+    # connector_tools.
+    #
+    # @return [AgentsNamespace]
+    # @example
+    #   melaya.agents.pipelines.list(project: "my-project")
+    #   melaya.agents.runs.list(project: "my-project")  # alias for pipelines
+    #   melaya.agents.hitl.pending
+    #   melaya.agents.assistant.get_profile
+    #   melaya.agents.evals.list_runs
+    #   melaya.agents.models.list_models(provider: "anthropic")
+    #   melaya.agents.connector_tools.services
+    attr_reader :agents
+
+    # Platform-plane namespace.
+    # Groups: projects, credentials, connectors, billing, team, templates,
+    # overview, runner, auth (alias: mfa), accounts, bugs, events.
+    #
+    # @return [PlatformNamespace]
+    # @example
+    #   melaya.platform.projects.list
+    #   melaya.platform.billing.subscription
+    #   melaya.platform.auth.login(username: "u", password: "p")
+    #   melaya.platform.mfa.mfa_setup           # alias for auth
+    #   melaya.platform.credentials.set("openai", value: "sk-...")
+    #   melaya.platform.events.on_run_update("run-123") { |e| puts e["event_type"] }
+    attr_reader :platform
+
+    # @param api_key [String] Melaya platform API key, prefixed +mk_+.
+    #   Create one at melaya.org → Settings → API Keys. May also be a session
+    #   JWT for auth-plane operations (login/refresh return a JWT).
+    # @param base_url [String] Override the REST base URL.
+    # @param ws_url [String] Override the WebSocket base URL.
+    # @param verify_ssl [Boolean] Retained for compatibility; false is rejected.
+    # @param connect_events [Boolean] If false, do not open a Socket.IO connection
+    #   on construction. Call +events+ to connect lazily. Default: false (lazy).
     def initialize(api_key:, base_url: HttpClient::DEFAULT_BASE_URL,
-                   ws_url: StreamAPI::DEFAULT_WS_URL, verify_ssl: nil)
-      raise ArgumentError, "Melaya: api_key is required (create one at melaya.org -> Settings -> API Keys)." \
-        if api_key.nil? || api_key.empty?
-      raise ArgumentError, "Melaya: API keys must be prefixed 'mk_'." \
-        unless api_key.start_with?("mk_")
-
-      ssl = if verify_ssl.nil?
-        ENV["MELAYA_INSECURE_TLS"] != "1"
-      else
-        verify_ssl
+                   ws_url: StreamAPI::DEFAULT_WS_URL,
+                   verify_ssl: nil,
+                   connect_events: false)
+      raise ArgumentError,
+        "Melaya: api_key is required (create one at melaya.org → Settings → API Keys)." \
+        if api_key.nil? || api_key.to_s.empty?
+      # Allow JWTs (which don't start with mk_) for auth-plane use cases
+      # while still guiding developers who forget the prefix.
+      if !api_key.to_s.start_with?("mk_") && !api_key.to_s.start_with?("ey")
+        raise ArgumentError,
+          "Melaya: API keys must be prefixed 'mk_' (or a Bearer JWT starting with 'ey')."
+      end
+
+      if verify_ssl == false
+        raise ArgumentError, "Melaya: TLS certificate verification cannot be disabled."
       end
+      ssl = true
 
       http = HttpClient.new(api_key: api_key, base_url: base_url, verify_ssl: ssl)
 
+      # Trading plane
       @market     = MarketAPI.new(http)
       @account    = AccountAPI.new(http)
       @sim        = SimAPI.new(http)
@@ -74,6 +227,94 @@ module Melaya
       @backtest   = BacktestAPI.new(http)
       @stream     = StreamAPI.new(api_key, ws_url, http, verify_ssl: ssl)
       @trade      = TradeAPI.new(http)
+
+      # Platform / agents plane
+      @auth        = AuthAPI.new(http)
+      @accounts    = AccountsAPI.new(http)
+      @billing     = BillingAPI.new(http)
+      @runner      = RunnerAPI.new(http)
+      @projects    = ProjectsAPI.new(http)
+      @pipelines   = PipelinesAPI.new(http)
+      @hitl        = HitlAPI.new(http)
+      @credentials = CredentialsAPI.new(http)
+      @connectors  = ConnectorsAPI.new(http)
+      @connector_tools = ConnectorToolsAPI.new(http)
+      @phone       = PhoneAPI.new(http)
+      @team        = TeamAPI.new(http)
+      @templates   = TemplatesAPI.new(http)
+      @assistant   = AssistantAPI.new(http)
+      @evals       = EvalsAPI.new(http)
+      @bugs        = BugsAPI.new(http)
+
+      if connect_events
+        @events = Events.new(api_key: api_key, base_url: base_url, verify_ssl: ssl)
+      else
+        @_events_api_key   = api_key
+        @_events_base_url  = base_url
+        @_events_verify_ssl = ssl
+        @events = nil
+      end
+
+      # ── Domain namespaces ────────────────────────────────────────────────────
+      # Each attribute is the SAME instance as the flat accessor — no copies,
+      # no extra HTTP clients.
+
+      @trading = TradingNamespace.new(
+        market:     @market,
+        account:    @account,
+        sim:        @sim,
+        strategies: @strategies,
+        backtest:   @backtest,
+        stream:     @stream,
+        trade:      @trade
+      )
+
+      @agents = AgentsNamespace.new(
+        pipelines: @pipelines,
+        hitl:      @hitl,
+        assistant: @assistant,
+        phone:     @phone,
+        evals:     @evals,
+        # credentials#list_models is the canonical "models" surface; expose the
+        # full CredentialsAPI object here so callers can do agents.models.list_models(...)
+        models:    @credentials,
+        connector_tools: @connector_tools
+      )
+
+      # Platform namespace: events slot uses a lazy proxy so the Socket.IO
+      # thread is still only started on first access (same as the flat #events).
+      platform_self = self
+      @platform = PlatformNamespace.new(
+        projects:    @projects,
+        credentials: @credentials,
+        connectors:  @connectors,
+        billing:     @billing,
+        team:        @team,
+        templates:   @templates,
+        overview:    @pipelines,  # overview dashboard lives on PipelinesAPI
+        runner:      @runner,
+        auth:        @auth,
+        accounts:    @accounts,
+        bugs:        @bugs,
+        events:      nil          # filled lazily below
+      )
+
+      # Patch platform#events to delegate to the lazy flat accessor.
+      # We do this with a singleton method so PlatformNamespace remains a plain
+      # Struct (no subclassing required).
+      @platform.define_singleton_method(:events) { platform_self.events }
+    end
+
+    # Lazily initialize and return the events client.
+    # If +connect_events: true+ was passed to the constructor, returns the
+    # already-connected client. Otherwise creates and connects on first access.
+    # Also accessible as +melaya.platform.events+.
+    def events
+      @events ||= Events.new(
+        api_key:    @_events_api_key,
+        base_url:   @_events_base_url,
+        verify_ssl: @_events_verify_ssl
+      )
     end
   end
 end