melaya 0.1.4 → 0.2.0

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.2.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,86 @@ 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/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
+  # - +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 +104,114 @@ 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
+    # 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.
+    #
+    # @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")
+    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 +219,92 @@ 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)
+      @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
+      )
+
+      # 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

data/melaya.gemspec

@@ -8,15 +8,20 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Melaya"]
   spec.email         = ["sdk@melaya.org"]
 
-  spec.summary       = "Official Ruby SDK for the Melaya unified market-data & trading API"
-  spec.description   = "Access 70+ exchanges via Melaya's normalized REST and WebSocket API. " \
-                       "Market data, strategies, backtesting, sim trading, and streaming."
+  spec.summary       = "Official Ruby SDK for Melaya Agent Builder and Mobile Device Control"
+  spec.description   = "Official Ruby SDK for Melaya Agent Builder and Mobile Device Control. Includes preview Melaya Trading namespaces that are not yet generally available."
   spec.homepage      = "https://melaya.org"
-  spec.license       = "MIT"
+  spec.license       = "Apache-2.0"
+
+  spec.metadata = {
+    "homepage_uri"    => "https://melaya.org",
+    "source_code_uri" => "https://github.com/melaya-labs/melaya",
+    "changelog_uri"   => "https://github.com/melaya-labs/melaya/blob/main/CHANGELOG.md"
+  }
 
   spec.required_ruby_version = ">= 3.0.0"
 
-  spec.files         = Dir["lib/**/*.rb", "README.md", "melaya.gemspec"]
+  spec.files         = Dir["lib/**/*.rb", "README.md", "LICENSE", "melaya.gemspec"]
   spec.require_paths = ["lib"]
 
   # stdlib only — no runtime gem dependencies

metadata

@@ -1,40 +1,61 @@
 --- !ruby/object:Gem::Specification
 name: melaya
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Melaya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-19 00:00:00.000000000 Z
+date: 2026-07-24 00:00:00.000000000 Z
 dependencies: []
-description: Access 70+ exchanges via Melaya's normalized REST and WebSocket API.
-  Market data, strategies, backtesting, sim trading, and streaming.
+description: Official Ruby SDK for Melaya Agent Builder and Mobile Device Control.
+  Includes preview Melaya Trading namespaces that are not yet generally available.
 email:
 - sdk@melaya.org
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
 - README.md
 - lib/melaya.rb
 - lib/melaya/account.rb
+- lib/melaya/accounts.rb
+- lib/melaya/assistant.rb
+- lib/melaya/auth.rb
 - lib/melaya/backtest.rb
+- lib/melaya/billing.rb
+- lib/melaya/bugs.rb
+- lib/melaya/connectors.rb
+- lib/melaya/credentials.rb
 - lib/melaya/errors.rb
+- lib/melaya/evals.rb
+- lib/melaya/events.rb
+- lib/melaya/hitl.rb
 - lib/melaya/http_client.rb
 - lib/melaya/market.rb
+- lib/melaya/namespaces.rb
+- lib/melaya/phone.rb
+- lib/melaya/pipelines.rb
+- lib/melaya/projects.rb
+- lib/melaya/runner.rb
 - lib/melaya/sim.rb
 - lib/melaya/strategies.rb
 - lib/melaya/stream.rb
+- lib/melaya/team.rb
+- lib/melaya/templates.rb
 - lib/melaya/trade.rb
 - lib/melaya/version.rb
 - melaya.gemspec
 homepage: https://melaya.org
 licenses:
-- MIT
-metadata: {}
+- Apache-2.0
+metadata:
+  homepage_uri: https://melaya.org
+  source_code_uri: https://github.com/melaya-labs/melaya
+  changelog_uri: https://github.com/melaya-labs/melaya/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -53,5 +74,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Official Ruby SDK for the Melaya unified market-data & trading API
+summary: Official Ruby SDK for Melaya Agent Builder and Mobile Device Control
 test_files: []