melaya 0.1.4 → 0.2.0

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/connectors.rb

@@ -0,0 +1,71 @@
+# 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
+
+    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/credentials.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Melaya
+  # Credentials API — store, retrieve, test, and delete secrets and
+  # third-party service connections at user scope.
+  #
+  # Credentials are envelope-encrypted at rest. Use +Melaya::ConnectorsAPI+
+  # for project-scoped connector credentials.
+  #
+  # Maps to /api/v1/private/credentials/*.
+  #
+  # @example
+  #   melaya.credentials.set("openai", value: "sk-...")
+  #   melaya.credentials.test("openai")
+  #   melaya.credentials.delete("openai")
+  class CredentialsAPI
+    def initialize(http)
+      @http = http
+    end
+
+    # GET /api/v1/private/credentials
+    # List all stored credentials (services, OAuth connections, env handles).
+    def list
+      @http.get("/api/v1/private/credentials")
+    end
+
+    # GET /api/v1/private/credentials/services
+    # List connected third-party services for the caller.
+    def connected_services
+      @http.get("/api/v1/private/credentials/services")
+    end
+
+    # GET /api/v1/private/credentials/:service
+    # Get a stored credential value by service name.
+    # @param service [String]
+    # @param key [String, nil] optional named key within the service
+    def get(service, key: nil)
+      params = key ? { "key" => key } : {}
+      @http.get("/api/v1/private/credentials/#{enc(service)}", params)
+    end
+
+    # PUT /api/v1/private/credentials/:service
+    # Store or update a credential (envelope-encrypted at rest).
+    # @param service [String]
+    # @param value [String] the secret value
+    # @param key [String, nil]
+    # @param label [String, nil]
+    def set(service, value:, key: nil, label: nil)
+      body = compact("value" => value, "key" => key, "label" => label)
+      @http.put("/api/v1/private/credentials/#{enc(service)}", body)
+    end
+
+    # DELETE /api/v1/private/credentials/:service
+    # Delete a stored credential by service name.
+    # @param service [String]
+    def delete(service)
+      @http.delete("/api/v1/private/credentials/#{enc(service)}")
+    end
+
+    # POST /api/v1/private/credentials/:service/test
+    # Test a stored credential (e.g. validate API key against its service).
+    # @param service [String]
+    def test(service)
+      @http.post("/api/v1/private/credentials/#{enc(service)}/test")
+    end
+
+    # ── Operator profile ───────────────────────────────────────────────────────
+
+    # GET /api/v1/private/credentials/operator-profile
+    # Get operator profile (persona config for agent context).
+    def get_operator_profile
+      @http.get("/api/v1/private/credentials/operator-profile")
+    end
+
+    # PUT /api/v1/private/credentials/operator-profile
+    # Save operator profile.
+    # @param profile [Hash]
+    def set_operator_profile(profile)
+      @http.put("/api/v1/private/credentials/operator-profile", profile)
+    end
+
+    # ── AI models ──────────────────────────────────────────────────────────────
+
+    # GET /api/v1/private/credentials/models
+    # List available AI models across all configured providers.
+    # Collapses 19+ provider fan-out into a parameterized query.
+    # @param provider [String, nil]
+    # @param capability [String, nil]
+    def list_models(provider: nil, capability: nil)
+      @http.get("/api/v1/private/credentials/models",
+        compact("provider" => provider, "capability" => capability))
+    end
+
+    # ── Melaya sub-accounts ────────────────────────────────────────────────────
+
+    # GET /api/v1/private/credentials/melaya-accounts
+    # List Melaya sub-accounts available to the caller.
+    def melaya_accounts
+      @http.get("/api/v1/private/credentials/melaya-accounts")
+    end
+
+    # ── RAG ────────────────────────────────────────────────────────────────────
+
+    # POST /api/v1/private/rag/ingest
+    # Start a RAG document ingestion job.
+    # @param body [Hash]
+    def rag_ingest_start(body = {})
+      @http.post("/api/v1/private/rag/ingest", body)
+    end
+
+    # GET /api/v1/private/rag/ingest/:sessionId
+    # Poll RAG ingestion job status.
+    # @param session_id [String]
+    def rag_ingest_status(session_id)
+      @http.get("/api/v1/private/rag/ingest/#{enc(session_id)}")
+    end
+
+    # POST /api/v1/private/rag/retrieve
+    # Start a RAG retrieval query.
+    # @param body [Hash]
+    def rag_retrieve_start(body = {})
+      @http.post("/api/v1/private/rag/retrieve", body)
+    end
+
+    # GET /api/v1/private/rag/retrieve/:sessionId
+    # Poll RAG retrieval result.
+    # @param session_id [String]
+    def rag_retrieve_status(session_id)
+      @http.get("/api/v1/private/rag/retrieve/#{enc(session_id)}")
+    end
+
+    # ── Folder picker ──────────────────────────────────────────────────────────
+
+    # POST /api/v1/private/rag/pick-folder
+    # Initiate native folder picker for file ingestion.
+    # @param body [Hash]
+    def pick_folder_start(body = {})
+      @http.post("/api/v1/private/rag/pick-folder", body)
+    end
+
+    # GET /api/v1/private/rag/pick-folder/:sessionId
+    # Poll folder picker result.
+    # @param session_id [String]
+    def pick_folder_status(session_id)
+      @http.get("/api/v1/private/rag/pick-folder/#{enc(session_id)}")
+    end
+
+    # ── LinkedIn OAuth ─────────────────────────────────────────────────────────
+
+    # POST /api/v1/private/credentials/linkedin/connect
+    # Start LinkedIn OAuth flow.
+    def linkedin_connect_start(body = {})
+      @http.post("/api/v1/private/credentials/linkedin/connect", body)
+    end
+
+    # DELETE /api/v1/private/credentials/linkedin/connect
+    # Cancel an in-progress LinkedIn OAuth flow.
+    def linkedin_connect_cancel
+      @http.delete("/api/v1/private/credentials/linkedin/connect")
+    end
+
+    # GET /api/v1/private/credentials/linkedin/connect/status
+    # Poll LinkedIn OAuth connection status.
+    def linkedin_connect_status
+      @http.get("/api/v1/private/credentials/linkedin/connect/status")
+    end
+
+    # ── Luma OAuth ────────────────────────────────────────────────────────────
+
+    # POST /api/v1/private/credentials/luma/connect
+    # Start Luma OAuth flow.
+    def luma_connect_start(body = {})
+      @http.post("/api/v1/private/credentials/luma/connect", body)
+    end
+
+    # GET /api/v1/private/credentials/luma/connect/status
+    # Poll Luma OAuth connection status.
+    def luma_connect_status
+      @http.get("/api/v1/private/credentials/luma/connect/status")
+    end
+
+    # DELETE /api/v1/private/credentials/luma/connect
+    # Cancel an in-progress Luma OAuth flow.
+    def luma_connect_cancel
+      @http.delete("/api/v1/private/credentials/luma/connect")
+    end
+
+    # GET /api/v1/private/credentials/luma/schema
+    # Get the Luma event registration form schema.
+    # @param params [Hash]
+    def luma_schema(params = {})
+      @http.get("/api/v1/private/credentials/luma/schema", params)
+    end
+
+    # ── Google OAuth ───────────────────────────────────────────────────────────
+
+    # POST /api/v1/private/credentials/google/oauth
+    # Start Google OAuth flow for credential storage.
+    def google_oauth_start(body = {})
+      @http.post("/api/v1/private/credentials/google/oauth", body)
+    end
+
+    # ── CLI auth ───────────────────────────────────────────────────────────────
+
+    # POST /api/v1/private/credentials/cli-auth
+    # Start CLI authentication flow (device-code style).
+    def cli_auth_start(body = {})
+      @http.post("/api/v1/private/credentials/cli-auth", body)
+    end
+
+    # ── NotebookLM ─────────────────────────────────────────────────────────────
+
+    # POST /api/v1/private/credentials/notebooklm/login
+    # Store NotebookLM credentials.
+    def notebooklm_login(body = {})
+      @http.post("/api/v1/private/credentials/notebooklm/login", body)
+    end
+
+    # GET /api/v1/private/credentials/notebooklm/status
+    # Check NotebookLM connection status.
+    def notebooklm_status
+      @http.get("/api/v1/private/credentials/notebooklm/status")
+    end
+
+    # ── Telegram auth ──────────────────────────────────────────────────────────
+
+    # POST /api/v1/private/credentials/telegram/auth
+    # Start Telegram user auth (phone number step).
+    def telegram_auth_start(body = {})
+      @http.post("/api/v1/private/credentials/telegram/auth", body)
+    end
+
+    # POST /api/v1/private/credentials/telegram/auth/code
+    # Submit Telegram SMS verification code.
+    def telegram_auth_code(body = {})
+      @http.post("/api/v1/private/credentials/telegram/auth/code", body)
+    end
+
+    # POST /api/v1/private/credentials/telegram/auth/2fa
+    # Submit Telegram 2FA password.
+    def telegram_auth_2fa(body = {})
+      @http.post("/api/v1/private/credentials/telegram/auth/2fa", 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

data/lib/melaya/errors.rb

@@ -1,9 +1,19 @@
 # frozen_string_literal: true
 
 module Melaya
-  # Raised for non-2xx REST responses or ok:false envelopes.
+  # Raised for non-2xx REST responses or ok:false response envelopes.
+  #
+  # Two server error shapes are normalised here:
+  #   1. { error: 'tier_insufficient', tier: '...' }  → HTTP 403
+  #   2. { error: '...', message: '...', code: '...' } → other 4xx/5xx
   class MelayaError < StandardError
-    attr_reader :status, :code, :body
+    # HTTP status code (Integer), or 0 for transport/WS errors.
+    attr_reader :status
+    # Short machine-readable error code from the server (String or nil).
+    attr_reader :code
+    # Raw response body (Hash, String, or nil). Not included in #message so
+    # secrets embedded in error payloads do not leak to log lines.
+    attr_reader :body
 
     def initialize(message, status: 0, code: nil, body: nil)
       super(message)
@@ -12,4 +22,28 @@ module Melaya
       @body   = body
     end
   end
+
+  # Raised when the server returns { error: 'tier_insufficient' } (HTTP 403).
+  # Check +#tier+ for the minimum required tier string.
+  class TierInsufficientError < MelayaError
+    attr_reader :tier
+
+    def initialize(tier: nil, body: nil)
+      @tier = tier
+      super("Melaya: feature requires a higher tier (#{tier})", status: 403, code: "tier_insufficient", body: body)
+    end
+  end
+
+  # Raised when the server returns HTTP 429 (rate-limited) after all retries
+  # are exhausted.
+  class RateLimitError < MelayaError
+    # Retry-After header value in seconds, if present.
+    attr_reader :retry_after
+
+    def initialize(retry_after: nil, body: nil)
+      @retry_after = retry_after
+      super("Melaya: rate limit exceeded#{retry_after ? " (retry after #{retry_after}s)" : ""}",
+            status: 429, code: "rate_limited", body: body)
+    end
+  end
 end

data/lib/melaya/evals.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Melaya
+  # Evals API — list and inspect agent evaluation run results.
+  #
+  # Maps to /api/v1/private/evals/*.
+  #
+  # @example
+  #   runs    = melaya.evals.list_runs
+  #   summary = melaya.evals.summary
+  #   detail  = melaya.evals.run_detail(runs.first["id"])
+  class EvalsAPI
+    def initialize(http)
+      @http = http
+    end
+
+    # GET /api/v1/private/evals/runs
+    # List eval run results for the caller's tenant.
+    def list_runs(params = {})
+      @http.get("/api/v1/private/evals/runs", params)
+    end
+
+    # GET /api/v1/private/evals/summary
+    # Get aggregate summary of eval results.
+    def summary
+      @http.get("/api/v1/private/evals/summary")
+    end
+
+    # GET /api/v1/private/evals/runs/:runId
+    # Get detailed results for a specific eval run.
+    # @param run_id [String]
+    def run_detail(run_id)
+      @http.get("/api/v1/private/evals/runs/#{enc(run_id)}")
+    end
+
+    # GET /api/v1/private/evals/compare
+    # Compare results across multiple eval runs.
+    # @param params [Hash] e.g. { "runIds" => "id1,id2" }
+    def compare(params = {})
+      @http.get("/api/v1/private/evals/compare", params)
+    end
+
+    # GET /api/v1/private/evals/memory-graph
+    # Get memory graph visualization data for eval runs.
+    def memory_graph(params = {})
+      @http.get("/api/v1/private/evals/memory-graph", params)
+    end
+
+    # GET /api/v1/private/evals/runs/:runId/memory
+    # Get memory usage for a specific eval run.
+    # @param run_id [String]
+    def run_memory(run_id)
+      @http.get("/api/v1/private/evals/runs/#{enc(run_id)}/memory")
+    end
+
+    # GET /api/v1/private/evals/crew-memory
+    # Get agent crew memory for a pipeline.
+    # @param pipeline [String]
+    # @param project [String]
+    def crew_memory(pipeline:, project:)
+      @http.get("/api/v1/private/evals/crew-memory",
+        "pipeline" => pipeline,
+        "project"  => project)
+    end
+
+    # GET /api/v1/private/evals/benchmarks
+    # Get benchmark scores across eval runs.
+    def benchmarks(params = {})
+      @http.get("/api/v1/private/evals/benchmarks", params)
+    end
+
+    private
+
+    def enc(s)
+      URI.encode_www_form_component(s.to_s)
+    end
+  end
+end