melaya 0.1.4 → 0.3.0

data/lib/melaya/backtest.rb

@@ -97,5 +97,43 @@ module Melaya
     def delete_all
       @http.delete("/api/v1/private/backtest")
     end
+
+    # ── Parameter sweep optimizer (restRoutes.ts /api/v1/private/backtest/optimize) ──
+
+    # POST /api/v1/private/backtest/optimize
+    # Start a parameter sweep optimization (genetic/grid) over a strategy config.
+    # @param body [Hash] strategy config + param ranges + objective
+    def optimize_start(body)
+      @http.post("/api/v1/private/backtest/optimize", body)
+    end
+
+    # GET /api/v1/private/backtest/optimize
+    # List optimization sweep runs.
+    # @param params [Hash]
+    def optimize_list(params = {})
+      @http.get("/api/v1/private/backtest/optimize", params)
+    end
+
+    # GET /api/v1/private/backtest/optimize/:optRunId/status
+    # Get the status/progress of an optimization sweep run.
+    # @param opt_run_id [String]
+    def optimize_status(opt_run_id)
+      @http.get("/api/v1/private/backtest/optimize/#{URI.encode_www_form_component(opt_run_id.to_s)}/status")
+    end
+
+    # POST /api/v1/private/backtest/optimize/:optRunId/cancel
+    # Cancel an in-progress optimization sweep.
+    # @param opt_run_id [String]
+    def optimize_cancel(opt_run_id)
+      @http.post("/api/v1/private/backtest/optimize/#{URI.encode_www_form_component(opt_run_id.to_s)}/cancel")
+    end
+
+    # POST /api/v1/private/backtest/optimize/:optRunId/apply
+    # Apply best params from a completed optimization sweep to a strategy.
+    # @param opt_run_id [String]
+    # @param body [Hash]
+    def optimize_apply(opt_run_id, body = {})
+      @http.post("/api/v1/private/backtest/optimize/#{URI.encode_www_form_component(opt_run_id.to_s)}/apply", body)
+    end
   end
 end

data/lib/melaya/billing.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Melaya
+  # Billing API — subscription status, Stripe checkout/portal sessions,
+  # public pricing plans, and credit balances.
+  #
+  # Maps to /api/v1/private/billing/* (authenticated) and
+  # /api/v1/billing/plans (public), and /api/v1/private/accounts/* for credits.
+  class BillingAPI
+    def initialize(http)
+      @http = http
+    end
+
+    # GET /api/v1/private/billing/subscription
+    # Get caller's current Stripe subscription status and tier.
+    def subscription
+      @http.get("/api/v1/private/billing/subscription")
+    end
+
+    # POST /api/v1/private/billing/checkout
+    # Create Stripe Checkout session for tier upgrade.
+    # Returns a URL to redirect the user to.
+    # @param price_id [String, nil] Stripe price ID
+    # @param tier [String, nil]
+    def create_checkout(price_id: nil, tier: nil)
+      body = compact("priceId" => price_id, "tier" => tier)
+      @http.post("/api/v1/private/billing/checkout", body)
+    end
+
+    # POST /api/v1/private/billing/portal
+    # Create Stripe Customer Portal session for subscription management.
+    # Returns a URL to redirect the user to.
+    def create_portal
+      @http.post("/api/v1/private/billing/portal")
+    end
+
+    # GET /api/v1/billing/plans (public)
+    # Return public pricing plan details (price IDs for forge/bastion/citadel tiers).
+    def plans
+      @http.get("/api/v1/billing/plans")
+    end
+
+    # ── Promos ────────────────────────────────────────────────────────────────
+
+    # GET /api/v1/private/billing/ambassador-perk
+    # The ambassador discount the caller is entitled to, or nil.
+    def ambassador_perk
+      @http.get("/api/v1/private/billing/ambassador-perk")
+    end
+
+    # POST /api/v1/private/billing/redeem-code
+    # Redeem a single-use promo code to the caller's account; the discount
+    # applies on the next checkout.
+    # @param code [String]
+    def redeem_code(code)
+      @http.post("/api/v1/private/billing/redeem-code", "code" => code)
+    end
+
+    # GET /api/v1/private/billing/reserved-promo
+    # The caller's active reserved promo (for the subscription modal to
+    # reflect), or nil.
+    def reserved_promo
+      @http.get("/api/v1/private/billing/reserved-promo")
+    end
+
+    # ── Credits ───────────────────────────────────────────────────────────────
+
+    # GET /api/v1/private/accounts/credits
+    # Return current credit balance and transaction history.
+    def credits
+      @http.get("/api/v1/private/accounts/credits")
+    end
+
+    # GET /api/v1/private/accounts/credits/ai
+    # Return AI/LLM credit balance.
+    def ai_credits
+      @http.get("/api/v1/private/accounts/credits/ai")
+    end
+
+    # GET /api/v1/private/accounts/credits/portfolio-ideas
+    # Return portfolio-ideas feature credit balance.
+    def portfolio_ideas_credits
+      @http.get("/api/v1/private/accounts/credits/portfolio-ideas")
+    end
+
+    # GET /api/v1/private/accounts/credits/risk-monitoring
+    # Return risk-monitoring feature credit balance.
+    def risk_monitoring_credits
+      @http.get("/api/v1/private/accounts/credits/risk-monitoring")
+    end
+
+    private
+
+    def compact(hash)
+      hash.reject { |_, v| v.nil? }
+    end
+  end
+end

data/lib/melaya/bugs.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Melaya
+  # Bugs API — submit and track bug reports.
+  #
+  # Maps to /api/v1/private/bugs/*.
+  #
+  # @example
+  #   melaya.bugs.create(title: "UI crash", description: "...")
+  #   reports = melaya.bugs.list_mine
+  class BugsAPI
+    def initialize(http)
+      @http = http
+    end
+
+    # POST /api/v1/private/bugs
+    # Submit a bug report (user-facing feedback form).
+    # @param title [String]
+    # @param description [String]
+    # @param extra [Hash] any additional fields
+    def create(title:, description: nil, **extra)
+      body = extra.transform_keys(&:to_s)
+      body["title"]       = title
+      body["description"] = description unless description.nil?
+      @http.post("/api/v1/private/bugs", body)
+    end
+
+    # GET /api/v1/private/bugs/mine
+    # List bug reports submitted by the caller.
+    def list_mine
+      @http.get("/api/v1/private/bugs/mine")
+    end
+
+    # GET /api/v1/private/bugs/:bugId
+    # Get a single bug report by ID.
+    # @param bug_id [String]
+    def get(bug_id)
+      @http.get("/api/v1/private/bugs/#{enc(bug_id)}")
+    end
+
+    # POST /api/v1/private/bugs/:bugId/comments
+    # Add a comment to a bug report.
+    # @param bug_id [String]
+    # @param comment [String]
+    def add_comment(bug_id, comment:)
+      @http.post("/api/v1/private/bugs/#{enc(bug_id)}/comments", "comment" => comment)
+    end
+
+    # GET /api/v1/private/bugs/notifications
+    # List unread bug-related notifications for the caller.
+    def list_notifications
+      @http.get("/api/v1/private/bugs/notifications")
+    end
+
+    # POST /api/v1/private/bugs/notifications/read
+    # Mark bug notifications as read.
+    def mark_notifications_read(body = {})
+      @http.post("/api/v1/private/bugs/notifications/read", body)
+    end
+
+    private
+
+    def enc(s)
+      URI.encode_www_form_component(s.to_s)
+    end
+  end
+end

data/lib/melaya/connector_tools.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Melaya
+  # Connector Tools API — call any of the user's connected-service tools
+  # (Gmail, Slack, Stripe, ...) directly. Same surface the MCP server and the
+  # Melaya Assistant use: list connected services, discover tools by keyword,
+  # describe one, test a stored connector, start connecting a service, and
+  # call a tool.
+  #
+  # Do not confuse this with +melaya.connectors+ (project-scoped credential
+  # storage) — this module only calls already-connected tools.
+  #
+  # Maps to /api/v1/private/connector-tools/*.
+  #
+  # Read tools run immediately. A write tool defaults to +approval: "required"+
+  # and is staged as the same approval card the Assistant raises in the
+  # Melaya app: +call+ returns HTTP 202 (a success, not an error) with a
+  # +requestId+; poll +call_status+ — or use +call_and_wait+ — until the user
+  # has decided, and the write runs exactly once, on the first poll after
+  # approval. Pass +approval: "none"+ to run a write immediately instead; it
+  # is still audit-logged. Tools that move money or trade are always
+  # refused, under BOTH approval modes. No method here ever accepts or
+  # returns a credential value.
+  #
+  # @example
+  #   services = melaya.agents.connector_tools.services
+  #   found    = melaya.agents.connector_tools.search("unread email")
+  #   info     = melaya.agents.connector_tools.describe("gmail_list_messages")
+  #
+  #   # Read — runs immediately
+  #   read = melaya.agents.connector_tools.call("gmail_list_messages", args: { max_results: 5 })
+  #   puts read["result"]
+  #
+  #   # Write — staged for approval by default
+  #   staged = melaya.agents.connector_tools.call("gmail_send", args: { to: "a@b.com" })
+  #   outcome = melaya.agents.connector_tools.call_status(staged["requestId"])
+  #
+  #   # Or block until the approval is decided (or times out)
+  #   outcome = melaya.agents.connector_tools.call_and_wait("gmail_send", args: { to: "a@b.com" })
+  #
+  #   # Also reachable via the flat alias:
+  #   melaya.connector_tools.services
+  class ConnectorToolsAPI
+    BASE = "/api/v1/private/connector-tools"
+
+    # Statuses that end a +call_and_wait+ poll loop.
+    TERMINAL_STATUSES = %w[done rejected expired].freeze
+
+    # Defaults mirrored from the spec: poll every 3s, give up after 10 minutes.
+    DEFAULT_POLL_INTERVAL_S = 3
+    DEFAULT_WAIT_TIMEOUT_S  = 600
+
+    def initialize(http)
+      @http = http
+    end
+
+    # GET /connector-tools/services
+    # Connected services and built-in tool counts. Names only.
+    # @return [Hash] { "services" => [String], "builtIn" => "melaya_core",
+    #   "toolCounts" => { service => { "readTools" => Integer, "writeTools" => Integer } } }
+    def services
+      @http.get("#{BASE}/services")
+    end
+
+    # GET /connector-tools/search?q=&limit=
+    # Discover tools by plain business keywords (e.g. "unread email").
+    # @param q [String] required — plain business keywords
+    # @param limit [Integer, nil] 1-50, default 15
+    # @return [Hash] { "query" => String, "services" => [String], "tools" => [Hash] }
+    def search(q, limit: nil)
+      @http.get("#{BASE}/search", compact("q" => q, "limit" => limit))
+    end
+
+    # GET /connector-tools/tools/:tool
+    # Full description and parameters for one tool.
+    # @param tool [String]
+    # @return [Hash] ToolInfo — raises MelayaError (404) when unknown, or not
+    #   unlocked by any of your connected services.
+    def describe(tool)
+      @http.get("#{BASE}/tools/#{enc(tool)}")
+    end
+
+    # POST /connector-tools/test { service }
+    # Test the STORED credential for a connected service.
+    # Raises MelayaError (504, code "timeout") if the service does not
+    # answer within 30 seconds server-side.
+    # @param service [String]
+    # @return [Hash] { "service" => String, "success" => Boolean, "message" => String }
+    def test(service)
+      @http.post("#{BASE}/test", "service" => service)
+    end
+
+    # POST /connector-tools/connect { service }
+    # Start connecting a service. Never accepts a secret — OAuth services
+    # return an authorization URL to open; other kinds return where to store
+    # the credential in the Melaya app.
+    # @param service [String]
+    # @return [Hash] { "service", "kind" => "oauth"|"oauth_unavailable"|"interactive_login"|"api_key",
+    #   "authorizationUrl" => String (oauth only), "connectUrl" => String, "message" => String }
+    def connect(service)
+      @http.post("#{BASE}/connect", "service" => service)
+    end
+
+    # POST /connector-tools/call { tool, args, approval }
+    #
+    # A read tool (or a write with approval: "none") runs immediately and
+    # returns 200 with the result. A write with approval: "required"
+    # (default) is staged and returns 202 — a success, not an error — with a
+    # +requestId+ to poll via +call_status+ (or +call_and_wait+).
+    #
+    # Money-moving/trading tools are refused under both approval modes, and
+    # any other error response (400/403/404/502/503) is raised as a
+    # MelayaError by the underlying HTTP client, same as every other call in
+    # this SDK.
+    #
+    # @param tool [String]
+    # @param args [Hash] tool arguments
+    # @param approval [String] "required" (default, stage for approval) or "none" (run immediately)
+    # @return [Hash] { "status" => "done", "tool", "readOnly", "result" => String } or
+    #   { "status" => "pending_approval", "tool", "requestId", "message" }
+    def call(tool, args: {}, approval: "required")
+      @http.post("#{BASE}/call", "tool" => tool, "args" => args || {}, "approval" => approval)
+    end
+
+    # GET /connector-tools/calls/:requestId
+    # Outcome of a staged write. Raises MelayaError (404) when the request is
+    # unknown or has expired.
+    # @param request_id [String]
+    # @return [Hash] one of:
+    #   { "requestId", "tool", "status" => "pending" | "running" | "expired" }
+    #   { "requestId", "tool", "status" => "done", "ok" => Boolean, "result"/"error" => String }
+    #   { "requestId", "tool", "status" => "rejected", "reason" => String }
+    def call_status(request_id)
+      @http.get("#{BASE}/calls/#{enc(request_id)}")
+    end
+
+    # Helper: call a tool and, if it is staged for approval, block polling
+    # +call_status+ until the user has decided (done/rejected) or the
+    # request expires, then return that outcome. If the tool ran immediately
+    # (a read, or approval: "none"), returns that response as-is with no
+    # polling. Synchronous/blocking, like the rest of this SDK.
+    #
+    # @param tool [String]
+    # @param args [Hash]
+    # @param approval [String] "required" (default) or "none"
+    # @param poll_interval_s [Numeric] seconds between polls, default 3
+    # @param timeout_s [Numeric] give up polling after this many seconds and
+    #   return the last-seen (non-terminal) status, default 600 (10 minutes)
+    # @return [Hash] the immediate +call+ response, or the final +call_status+ outcome
+    def call_and_wait(tool, args: {}, approval: "required",
+                       poll_interval_s: DEFAULT_POLL_INTERVAL_S,
+                       timeout_s: DEFAULT_WAIT_TIMEOUT_S)
+      resp = call(tool, args: args, approval: approval)
+      return resp unless resp.is_a?(Hash) && resp["status"] == "pending_approval"
+
+      request_id = resp["requestId"]
+      deadline   = Time.now + timeout_s
+      loop do
+        outcome = call_status(request_id)
+        return outcome if outcome.is_a?(Hash) && TERMINAL_STATUSES.include?(outcome["status"])
+        return outcome if Time.now >= deadline
+
+        sleep(poll_interval_s)
+      end
+    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

data/lib/melaya/connectors.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Melaya
+  # Project Connectors API — manage credentials at project scope.
+  #
+  # Project-scoped connectors are isolated per project, letting separate
+  # projects use different API keys for the same service.
+  #
+  # Maps to /api/v1/private/projects/:project/connectors/*.
+  #
+  # @example
+  #   melaya.connectors.set("my-project", "openai", value: "sk-...")
+  #   services = melaya.connectors.connected_services("my-project")
+  class ConnectorsAPI
+    def initialize(http)
+      @http = http
+    end
+
+    # GET /api/v1/private/projects/:project/connectors/services
+    # List connected services for a project.
+    # @param project [String] project name
+    def connected_services(project)
+      @http.get("/api/v1/private/projects/#{enc(project)}/connectors/services")
+    end
+
+    # PUT /api/v1/private/projects/:project/connectors/:service
+    # Store a connector credential at project scope.
+    # @param project [String]
+    # @param service [String]
+    # @param value [String]
+    # @param key [String, nil]
+    # @param label [String, nil]
+    def set(project, service, value:, key: nil, label: nil)
+      body = compact("value" => value, "key" => key, "label" => label)
+      @http.put("/api/v1/private/projects/#{enc(project)}/connectors/#{enc(service)}", body)
+    end
+
+    # DELETE /api/v1/private/projects/:project/connectors/:service
+    # Delete a project-scoped connector credential.
+    # @param project [String]
+    # @param service [String]
+    def delete(project, service)
+      @http.delete("/api/v1/private/projects/#{enc(project)}/connectors/#{enc(service)}")
+    end
+
+    # POST /api/v1/private/projects/:project/connectors/env-handle
+    # Get a short-lived env-handle token for project-scoped credentials.
+    # @param project [String]
+    def env_handle(project)
+      @http.post("/api/v1/private/projects/#{enc(project)}/connectors/env-handle")
+    end
+
+    # POST /api/v1/private/projects/:project/connectors/google/oauth
+    # Start Google OAuth flow for project-scoped connector.
+    # @param project [String]
+    # @param body [Hash]
+    def google_oauth_start(project, body = {})
+      @http.post("/api/v1/private/projects/#{enc(project)}/connectors/google/oauth", body)
+    end
+
+    # POST /api/v1/private/projects/:project/connectors/:service/apply-personal
+    # Share the caller's OWN personal connector credential into the project
+    # pool (editor or owner only). Values stay server-side.
+    # @param project [String]
+    # @param service [String]
+    # @param google_capabilities [Array<String>, nil] restrict a Google
+    #   connector to these capabilities only, e.g. "gmail", "calendar",
+    #   "drive", "sheets", "docs", "search_console", "youtube", "google_ads",
+    #   "analytics", "meet", "slides"
+    def apply_personal(project, service, google_capabilities: nil)
+      body = compact("googleCapabilities" => google_capabilities)
+      @http.post("/api/v1/private/projects/#{enc(project)}/connectors/#{enc(service)}/apply-personal", body)
+    end
+
+    # GET /api/v1/private/projects/:project/connectors/shared-by
+    # Which member shared each connected project connector (usernames only —
+    # values are never returned).
+    # @param project [String]
+    def shared_by(project)
+      @http.get("/api/v1/private/projects/#{enc(project)}/connectors/shared-by")
+    end
+
+    # ── Google OAuth (status / defaults / disconnect) ─────────────────────────
+
+    # GET /api/v1/private/projects/:project/connectors/google/status
+    # List the Google OAuth capabilities actually granted to a project.
+    # @param project [String]
+    def google_status(project)
+      @http.get("/api/v1/private/projects/#{enc(project)}/connectors/google/status")
+    end
+
+    # PUT /api/v1/private/projects/:project/connectors/google/default
+    # Select the project's connected Google account used by one capability.
+    # @param project [String]
+    # @param capability [String] e.g. "gmail", "calendar", "drive", "sheets", ...
+    # @param account_id [String] 24-hex-char connected-account id
+    def google_set_default(project, capability, account_id)
+      @http.put("/api/v1/private/projects/#{enc(project)}/connectors/google/default",
+        "capability" => capability, "accountId" => account_id)
+    end
+
+    # DELETE /api/v1/private/projects/:project/connectors/google/access
+    # Disconnect one Google product, or an entire Google account, from a project.
+    # @param project [String]
+    # @param account_id [String] 24-hex-char connected-account id
+    # @param capability [String, nil] omit to disconnect the whole account
+    def google_disconnect(project, account_id, capability: nil)
+      body = compact("accountId" => account_id, "capability" => capability)
+      @http.delete("/api/v1/private/projects/#{enc(project)}/connectors/google/access", {}, body)
+    end
+
+    # ── Database connector test (runner-probed) ───────────────────────────────
+
+    # POST /api/v1/private/projects/:project/connectors/db-test
+    # Test a project database connector from the user's own runner (reaches
+    # IP-allow-listed / VPC hosts a cloud probe never could).
+    # @param project [String]
+    # @param service [String] one of "postgres", "mysql", "snowflake", "databricks", "sqlite"
+    # @param credentials [Hash, nil] freshly-typed credentials to test instead of the stored ones
+    # @return [Hash] { "sessionId" => String, ... }
+    def db_test_start(project, service, credentials: nil)
+      body = compact("service" => service, "credentials" => credentials)
+      @http.post("/api/v1/private/projects/#{enc(project)}/connectors/db-test", body)
+    end
+
+    # GET /api/v1/private/projects/:project/connectors/db-test/:sessionId
+    # Poll a project DB connector runner-test result.
+    # @param project [String]
+    # @param session_id [String]
+    def db_test_status(project, session_id)
+      @http.get("/api/v1/private/projects/#{enc(project)}/connectors/db-test/#{enc(session_id)}")
+    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